feat(runs): add typed results and model aliases (#2043)

Also fix repository-free message.send validation (#2046) and add a single-binary development smoke path (#1977).

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
samandCopilot committed 2026-11-18 23:47:35 +11:00
1 parent 6a3bf5a71a
commit 64dfad6d53
55 files changed
+1162 -517

No files matched your search

@@ -0,0 +1,76 @@
---
name: technical-prose-cleanup
description: Use when asked to clean up awkward or machine-generated technical writing in Archie's modules without changing behaviour. Reviews one module at a time.
---
# Technical prose cleanup
Follow `AGENTS.md`. Improve wording without changing behaviour, contracts or
technical meaning. Use Australian English.
## Set the scope
1. Check the working tree for existing changes. Inspect `modules/` without
editing and choose the smallest module with enough clear problems to justify
a pass, unless the maintainer has specified one.
2. Set the complete file scope before editing: exactly one module, at most
15 files. Do not expand into other modules or start another batch.
3. Use subagents only when independent work warrants it. Assign at most three
in parallel, each with a disjoint list of owned files, this writing standard
and relevant examples. Instruct them to inspect the implementation, leave
clear prose alone, report ambiguities and make no commits or pushes.
The coordinator owns integration and validation. In a shared worktree,
avoid broad staging, resets, checkouts and formatters that rewrite other work.
## Edit in context
Check comments, errors, logs, test names, schema descriptions, CLI help,
prompts, user-facing strings and module documentation. Look for unnatural word
order, awkward possessives, unusual verbs, needless synonyms and wording that
obscures the operation. Read the surrounding implementation and tests before
rewriting. Do not mechanically replace words or edit text that already reads well.
Use conventional terms, even when they repeat. Keep established idioms such as
“pin a dependency”, “drain a stream” and “acquire a lock”. Prefer precision over
brevity when conditions, timing, ownership or guarantees matter.
| Instead of | Write |
| --- | --- |
| “PrepareRequest names the release to stage and who hears the outcome.” | “PrepareRequest specifies the release to stage and notification recipients.” |
| “ReadOnly leaves the agent only the tools that change nothing.” | “ReadOnly restricts the agent to read-only tools.” |
| “a release another key signed” | “a release signed by a different key” |
| “it recalls earlier incidents and files what it found” | “it retrieves previous incidents and stores new findings” |
Comments explain why. Remove narration that adds nothing, but keep
non-obvious constraints, invariants and decisions. Retain required Go
documentation. Don't shorten a comment about replay into a generic retry
description: say what is recorded and what is rebuilt or resolved at runtime.
Likewise, distinguish a per-action reapproval limit from a run-wide limit,
and escalation within one request from a new request.
Do not refactor or rename identifiers, configuration keys or API fields.
Do not edit generated files by hand, add tooling or dependencies, or reformat
unrelated code. Check consumers and tests before changing errors, logs or other
output. Keep machine-readable values and exact text used as a contract. If a
safe edit needs changes outside the scope or the meaning is unclear, leave
the text alone and report why.
For prompts, preserve instructions, conditions, tool semantics and output
requirements. Check what the agent actually sees. For example, judgement runs
inside an action tool call; it is not a separate tool the agent calls directly.
The investigation prompt says: “If a tool call returns a judgement decision,
report the decision and any reasons it gives.” Keep matching fixtures in sync
when editing prompt text.
## Review and stop
Review the combined diff against both the implementation and the starting
working tree. Verify the module and file limits, check that unrelated edits
are intact, and confirm that no logic or contract changed. If implementation
work already shares a file, keep it out of the prose diff; separate by hunk
if asked to commit both.
Run the relevant checks on the final tree and follow `AGENTS.md` for the
commit gate. Report failed or unavailable checks; do not fix unrelated
failures in this batch. Summarise the module, file count, main edits,
deliberately unchanged ambiguities and validation. Stop after this batch.
+7 -2
View File
@@ -131,8 +131,13 @@ When sources disagree, the higher one wins:
- Log through the service's injected `*slog.Logger` with the `...Context` - Log through the service's injected `*slog.Logger` with the `...Context`
methods, so lines carry the OpenTelemetry trace id. Never the global `slog`. methods, so lines carry the OpenTelemetry trace id. Never the global `slog`.
- If a fix fails twice, throw the block away and rewrite it simply. - If a fix fails twice, throw the block away and rewrite it simply.
- Comments say why, briefly. No migration history, phase names or issue - Comments explain why, not what the code already says. No migration
narration in code. history, phase names or issue narration in code.
- Write natural, idiomatic technical English in comments, errors, logs,
test names, descriptions, prompts and user-facing text. Use conventional
terminology and normal word order. Avoid invented metaphors, awkward
possessives, inverted sentences and clever paraphrases. Prefer repeating
an established term over inventing a synonym.
- Generated files (protobuf, sqlc) are regenerated and committed - Generated files (protobuf, sqlc) are regenerated and committed
with the change that caused them, never hand-edited. with the change that caused them, never hand-edited.
+4
View File
@@ -150,6 +150,10 @@ another [deployment template](deployments/README.md).
<http://localhost:5173>, using [`deployments/dev.toml`](deployments/dev.toml). <http://localhost:5173>, using [`deployments/dev.toml`](deployments/dev.toml).
`task check` is the quality gate; [AGENTS.md](AGENTS.md) lists its tools. `task check` is the quality gate; [AGENTS.md](AGENTS.md) lists its tools.
| Project skill | Use |
| --- | --- |
| [`/technical-prose-cleanup`](.github/skills/technical-prose-cleanup/SKILL.md) | Review technical writing in one module without changing behaviour. |
## Documentation ## Documentation
- [Your first playbook](docs/guides/first-playbook.md) - [Your first playbook](docs/guides/first-playbook.md)
+24
View File
@@ -211,6 +211,30 @@ tasks:
- task: dev:wait-state - task: dev:wait-state
- go run ./cmd/archie-messaging -config-overlay deployments/dev.toml - go run ./cmd/archie-messaging -config-overlay deployments/dev.toml
dev:archie:
desc: Run the single archie binary against the development PostgreSQL (admin token "dev")
deps: [dev:postgres]
vars:
DIR: tmp/dev-archie
cmds:
- |
set -eu
mkdir -p {{.DIR}}
# Generated once: the age identity seals the dev credentials, so keep
# it across runs. Roles come from dev:postgres.
if [ ! -f {{.DIR}}/config.toml ]; then
umask 077
{
echo 'listen = "127.0.0.1:8080"'
echo "admin_token_sha256 = \"$(printf dev | sha256sum | cut -d' ' -f1)\""
echo "age_identity = \"$(go run ./cmd/archie -new-age-identity)\""
echo '[database]'
echo 'url = "postgres://archie_runtime:archie@127.0.0.1:5432/archie?sslmode=disable"'
echo 'owner_url = "postgres://archie_migrator:archie@127.0.0.1:5432/archie?sslmode=disable"'
} > {{.DIR}}/config.toml
fi
- go run ./cmd/archie -config {{.DIR}}/config.toml
dev:ui: dev:ui:
desc: Run Vite (requires the dashboard backend) desc: Run Vite (requires the dashboard backend)
dir: ui dir: ui
+1 -1
View File
@@ -133,7 +133,7 @@ _runs without a repository._
| `protect_tests` | bool | Write-block the repository test files. | | `protect_tests` | bool | Write-block the repository test files. |
| `read_only` | bool | Restrict the agent to read-only tools. | | `read_only` | bool | Restrict the agent to read-only tools. |
| `result` | mapping | A JSON Schema object the agent must return; later steps read it as steps.<id>.result. | | `result` | mapping | A JSON Schema object the agent must return; later steps read it as steps.<id>.result. |
| `model` | text | The model alias that runs the agent, e.g. default or fast. Empty means default. | | `model` | text | A model alias configured under Settings > Agent models, such as `fast`. Omit it or use `default` to select the organisation's default agent model. |
### `command.run` ### `command.run`
+38 -1
View File
@@ -2445,7 +2445,7 @@ paths:
schema: schema:
$ref: "#/components/schemas/ErrorModel" $ref: "#/components/schemas/ErrorModel"
description: Error description: Error
summary: Replay one of the group's events through the draft, changing nothing summary: Replay a stored event against the draft workflow and policy in a dry run
tags: tags:
- Drafts - Drafts
/api/drafts/{id}/publish: /api/drafts/{id}/publish:
@@ -3108,6 +3108,14 @@ paths:
/api/settings/agent-model: /api/settings/agent-model:
get: get:
operationId: get-agent-model operationId: get-agent-model
parameters:
- description: Agent model alias; omit for the default model
explode: false
in: query
name: alias
schema:
description: Agent model alias; omit for the default model
type: string
responses: responses:
"200": "200":
content: content:
@@ -3126,6 +3134,14 @@ paths:
- Governance - Governance
put: put:
operationId: put-agent-model operationId: put-agent-model
parameters:
- description: Agent model alias; omit for the default model
explode: false
in: query
name: alias
schema:
description: Agent model alias; omit for the default model
type: string
requestBody: requestBody:
content: content:
application/json: application/json:
@@ -3173,6 +3189,27 @@ paths:
summary: Ask a model one question before saving it summary: Ask a model one question before saving it
tags: tags:
- Governance - Governance
/api/settings/agent-models:
get:
operationId: list-agent-models
responses:
"200":
content:
application/json:
schema:
additionalProperties:
$ref: "#/components/schemas/GovernanceModel"
type: object
description: OK
default:
content:
application/problem+json:
schema:
$ref: "#/components/schemas/ErrorModel"
description: Error
summary: List agent models by alias
tags:
- Governance
/api/sources: /api/sources:
get: get:
operationId: list-sources operationId: list-sources
+21
View File
@@ -48,6 +48,27 @@ The first run needs `pnpm install --dir e2e` and `pnpm --dir e2e exec playwright
install chromium`. In the cloud environment, Chromium and Playwright are install chromium`. In the cloud environment, Chromium and Playwright are
preinstalled; run with `NODE_PATH=$(pnpm root -g)`. preinstalled; run with `NODE_PATH=$(pnpm root -g)`.
## Single-binary smoke check
Point this check at an already running, disposable `archie` instance with its
own PostgreSQL database and no external delivery connectors. Set
`ARCHIE_SMOKE_TOKEN` to that instance's bootstrap token and
`ARCHIE_SMOKE_URL` to its IPv4 loopback URL (for example
`http://127.0.0.1:8080`), then run:
```bash
node e2e/archie-smoke.cjs
```
The check saves a workflow and a one-minute schedule, then verifies that its
run links back to the schedule event and appears in the composer. It disables
the schedule after the check but leaves records for inspection. No model or
forge is needed. The legacy `task e2e:up` stack is not the target of this check.
If Archie is running in WSL and its loopback URL is not reachable from
Windows, run the check with Node in the same Linux environment as Archie.
If the schedule starts but the run does not finish, check the `events` and
`runs` logs; readiness alone does not verify that either worker can claim work.
## Release evidence ## Release evidence
```bash ```bash
+74
View File
@@ -0,0 +1,74 @@
const assert = require("node:assert/strict");
const { randomUUID } = require("node:crypto");
const { setTimeout: delay } = require("node:timers/promises");
async function main() {
assert.ok(process.env.ARCHIE_SMOKE_URL, "Set ARCHIE_SMOKE_URL to a disposable Archie stack");
const origin = new URL(process.env.ARCHIE_SMOKE_URL);
const token = process.env.ARCHIE_SMOKE_TOKEN;
assert.equal(origin.protocol, "http:");
assert.equal(origin.hostname, "127.0.0.1", "Use a disposable Archie stack on IPv4 loopback");
assert.ok(token, "Set ARCHIE_SMOKE_TOKEN to the disposable stack's admin token");
async function request(path, { method = "GET", body, authenticated = true, status = 200 } = {}) {
const response = await fetch(new URL(path, origin), {
method,
redirect: "error",
signal: AbortSignal.timeout(10_000),
headers: {
...(authenticated && { Authorization: `Bearer ${token}` }),
...(body !== undefined && { "Content-Type": "application/json" }),
},
body: body === undefined ? undefined : JSON.stringify(body),
}).catch((err) => {
throw new Error(`${method} ${path}: could not reach Archie at ${origin.origin}: ${err.cause?.message || err.message}`, { cause: err });
});
assert.equal(response.status, status, `${method} ${path}: expected HTTP ${status}, got ${response.status}`);
return response.json();
}
const ready = await request("/readyz", { authenticated: false });
assert.equal(ready.ready, true, "Archie is not ready");
await request("/api/workflows", { authenticated: false, status: 401 });
const name = `smoke-${randomUUID()}`;
const saved = await request(`/api/workflows/${name}`, {
method: "PUT",
body: { body: `repository: none\nsteps:\n - id: notify\n type: run.notify\n settings: {title: ${name}}\n` },
});
const trigger = { workflow: name, every: "1m" };
try {
await request(`/api/triggers/${name}`, { method: "PUT", body: trigger });
const deadline = Date.now() + 90_000;
let last = "no scheduled run";
while (Date.now() < deadline) {
const recent = await request("/api/runs");
const run = recent.find((row) => row.workflow === name);
if (run) {
last = `run ${run.id}: ${run.state}`;
assert.ok(!["failed", "cancelled"].includes(run.state), `${last}: ${run.error || "no error returned"}`);
if (run.state === "succeeded") {
const trail = await request(`/api/runs/${run.id}`);
assert.equal(trail.run.workflow_version, saved.version, "Run used the wrong workflow version");
assert.equal(trail.origin?.trigger, name, "Run trail is missing the schedule trigger");
assert.ok(trail.origin?.event_id, "Run trail is missing the originating event");
assert.equal(trail.origin.type, "schedule.tick");
const messages = await request("/api/composer/messages");
assert.equal(messages.filter((m) => m.run_id === run.id && m.title === name).length, 1,
"Expected one composer notification linked to the run");
console.log(`Schedule, run trail and composer notification verified for ${run.id}`);
return;
}
}
await delay(1_000);
}
throw new Error(`Timed out waiting for ${name}: ${last}`);
} finally {
await request(`/api/triggers/${name}`, { method: "PUT", body: { ...trigger, disabled: true } });
}
}
main().catch((err) => {
console.error(err.message);
process.exitCode = 1;
});
+1 -1
View File
@@ -13,7 +13,6 @@ require (
github.com/cespare/xxhash/v2 v2.3.0 // indirect github.com/cespare/xxhash/v2 v2.3.0 // indirect
github.com/cloudflare/circl v1.6.5 // indirect github.com/cloudflare/circl v1.6.5 // indirect
github.com/containerd/errdefs/pkg v0.3.0 // indirect github.com/containerd/errdefs/pkg v0.3.0 // indirect
github.com/danielgtaylor/huma/v2 v2.40.0 // indirect
github.com/distribution/reference v0.6.0 // indirect github.com/distribution/reference v0.6.0 // indirect
github.com/docker/go-connections v0.8.2 // indirect github.com/docker/go-connections v0.8.2 // indirect
github.com/docker/go-units v0.5.0 // indirect github.com/docker/go-units v0.5.0 // indirect
@@ -72,6 +71,7 @@ require (
github.com/cedar-policy/cedar-go v1.9.1 github.com/cedar-policy/cedar-go v1.9.1
github.com/containerd/errdefs v1.0.0 github.com/containerd/errdefs v1.0.0
github.com/coreos/go-oidc/v3 v3.21.0 github.com/coreos/go-oidc/v3 v3.21.0
github.com/danielgtaylor/huma/v2 v2.40.0
github.com/go-git/go-billy/v6 v6.0.0-beta.1 github.com/go-git/go-billy/v6 v6.0.0-beta.1
github.com/go-git/go-git/v6 v6.0.0-beta.1 github.com/go-git/go-git/v6 v6.0.0-beta.1
github.com/go-jose/go-jose/v4 v4.1.9 github.com/go-jose/go-jose/v4 v4.1.9
+2
View File
@@ -70,6 +70,8 @@ github.com/fxamacker/cbor/v2 v2.10.0 h1:HVF3T5vYwLqO81ebPirWEPNv2SMrUMD3HLnKgEr6
github.com/fxamacker/cbor/v2 v2.10.0/go.mod h1:uSwlToFuT9BZAKRxxVm3qQC8DR4tlWl7D6pf20iRYH4= github.com/fxamacker/cbor/v2 v2.10.0/go.mod h1:uSwlToFuT9BZAKRxxVm3qQC8DR4tlWl7D6pf20iRYH4=
github.com/gliderlabs/ssh v0.3.8 h1:a4YXD1V7xMF9g5nTkdfnja3Sxy1PVDCj1Zg4Wb8vY6c= github.com/gliderlabs/ssh v0.3.8 h1:a4YXD1V7xMF9g5nTkdfnja3Sxy1PVDCj1Zg4Wb8vY6c=
github.com/gliderlabs/ssh v0.3.8/go.mod h1:xYoytBv1sV0aL3CavoDuJIQNURXkkfPA/wxQ1pL1fAU= github.com/gliderlabs/ssh v0.3.8/go.mod h1:xYoytBv1sV0aL3CavoDuJIQNURXkkfPA/wxQ1pL1fAU=
github.com/go-chi/chi/v5 v5.5.0 h1:xdKQ1dJmVJsmgahrXSKhUx8NyVPzpwdlyrrQFpMPJgg=
github.com/go-chi/chi/v5 v5.5.0/go.mod h1:d1IG7GtKPSjPyBP365PH8sAGVHk3qfB/IhjFNRH1wWM=
github.com/go-git/gcfg/v2 v2.0.2 h1:MY5SIIfTGGEMhdA7d7JePuVVxtKL7Hp+ApGDJAJ7dpo= github.com/go-git/gcfg/v2 v2.0.2 h1:MY5SIIfTGGEMhdA7d7JePuVVxtKL7Hp+ApGDJAJ7dpo=
github.com/go-git/gcfg/v2 v2.0.2/go.mod h1:/lv2NsxvhepuMrldsFilrgct6pxzpGdSRC13ydTLSLs= github.com/go-git/gcfg/v2 v2.0.2/go.mod h1:/lv2NsxvhepuMrldsFilrgct6pxzpGdSRC13ydTLSLs=
github.com/go-git/go-billy/v6 v6.0.0-beta.1 h1:OJ4r207zcEbeq/DJNajQUOMd+pph3r9A7hRq1Sjl1bA= github.com/go-git/go-billy/v6 v6.0.0-beta.1 h1:OJ4r207zcEbeq/DJNajQUOMd+pph3r9A7hRq1Sjl1bA=
@@ -9,6 +9,23 @@ import (
"github.com/samcharles93/archie-core/internal/domain/workflow/task" "github.com/samcharles93/archie-core/internal/domain/workflow/task"
) )
// TestMessageSendWithoutRepository guards workflows that only send a message
// from being rejected by the worktree requirement.
func TestMessageSendWithoutRepository(t *testing.T) {
for _, mode := range []string{"none", "optional"} {
t.Run(mode, func(t *testing.T) {
_, err := ParseDefinition("id: notify\nrepository: "+mode+`
steps:
- type: message.send
settings: {channel: telegram, chat_id: "123", text: "Done"}
`, StepRegistry{MessageSendStepName: newMessageSendStage})
if err != nil {
t.Fatal(err)
}
})
}
}
func TestValidateControlTargets(t *testing.T) { func TestValidateControlTargets(t *testing.T) {
registry := StepRegistry{ registry := StepRegistry{
AgentRunStepName: newAgentRunStage, AgentRunStepName: newAgentRunStage,
+1
View File
@@ -37,6 +37,7 @@ type YAMLDefinition struct {
var repoFreeStepTypes = map[string]bool{ var repoFreeStepTypes = map[string]bool{
AgentRunStepName: true, WorkflowCallStepName: true, FinishStepName: true, AgentRunStepName: true, WorkflowCallStepName: true, FinishStepName: true,
HandoffStepName: true, ApproveStepName: true, CloseIssueStepName: true, CommentStepName: true, HandoffStepName: true, ApproveStepName: true, CloseIssueStepName: true, CommentStepName: true,
MessageSendStepName: true,
} }
// NeedsRepository reports whether a step type can run only with a worktree. // NeedsRepository reports whether a step type can run only with a worktree.
@@ -0,0 +1,8 @@
-- +goose Up
ALTER TABLE governance.model_roles DROP CONSTRAINT model_roles_role_check;
ALTER TABLE governance.model_roles ADD CONSTRAINT model_roles_role_check
CHECK (role = 'agent' OR (role <> 'agent:default' AND role ~ '^agent:[a-zA-Z0-9][a-zA-Z0-9_.-]{0,62}$'));
-- +goose Down
ALTER TABLE governance.model_roles DROP CONSTRAINT model_roles_role_check;
ALTER TABLE governance.model_roles ADD CONSTRAINT model_roles_role_check CHECK (role = 'agent');
+47 -90
View File
@@ -1,11 +1,7 @@
// Package approvals owns an approval request: one judged action waiting for a // Package approvals manages requests for human approval and records responses.
// person's answer, and the answer that settles it. A request is made when // A response to an action request resumes the waiting run. The request binds
// judgement holds an action at propose and wait, and an answer is an event in: // the approval to the decision ID and action digest so it cannot authorize a
// it wakes the run waiting on that key, which then runs the action only if the // different action.
// answer named the exact action that was judged.
//
// The request binds to the decision and its digest, so an approval covers the
// action that was shown and nothing else.
package approvals package approvals
import ( import (
@@ -33,8 +29,8 @@ import (
"github.com/samcharles93/archie-core/modules/judgement" "github.com/samcharles93/archie-core/modules/judgement"
) )
// The states a request can be in. A settled request never changes again, // A settled request cannot be answered again. An approved request may still
// except that an approval the action no longer matched is discarded. // be discarded before the approval is counted.
const ( const (
StatePending = "pending" StatePending = "pending"
StateApproved = "approved" StateApproved = "approved"
@@ -72,12 +68,12 @@ const (
KindRaise = "raise" KindRaise = "raise"
) )
// Request is one judged action waiting for a person's answer. // Request tracks approval of an action or a proposed increase in autonomy.
type Request struct { type Request struct {
ID uuid.UUID ID uuid.UUID
Kind string Kind string
RunID uuid.UUID RunID uuid.UUID
// Key is the run's wait key, stored so an answer knows what to wake. // Key identifies the run wait that receives the response.
Key string Key string
Decision judgement.Decision Decision judgement.Decision
DecisionID uuid.UUID DecisionID uuid.UUID
@@ -89,11 +85,9 @@ type Request struct {
Level string Level string
Summary string Summary string
State string State string
// Deadline is when the request runs out for good: the end of the last // Deadline applies to the whole request, not just the current escalation step.
// escalation step.
Deadline time.Time Deadline time.Time
// Step is the escalation step the request is at, and StepDeadline when it // Step and StepDeadline track the current escalation step and its deadline.
// moves on.
Step int Step int
StepDeadline time.Time StepDeadline time.Time
// ChangeRequest is whether the request went through a change request // ChangeRequest is whether the request went through a change request
@@ -104,7 +98,7 @@ type Request struct {
AnsweredVia string AnsweredVia string
} }
// Answer is what the run wakes with. // Answer records the decision and who made it.
type Answer struct { type Answer struct {
RequestID uuid.UUID `json:"request_id"` RequestID uuid.UUID `json:"request_id"`
Approved bool `json:"approved"` Approved bool `json:"approved"`
@@ -113,12 +107,13 @@ type Answer struct {
At time.Time `json:"at"` At time.Time `json:"at"`
} }
// Approval is the authority this answer gives judgement to run the action. // Approval binds the approver's identity and response time to the decision ID
// and action digest.
func (a Answer) Approval(d judgement.Decision) judgement.Approval { func (a Answer) Approval(d judgement.Decision) judgement.Approval {
return judgement.Approval{DecisionID: d.ID, Digest: d.Action.Digest, By: a.By, At: a.At} return judgement.Approval{DecisionID: d.ID, Digest: d.Action.Digest, By: a.By, At: a.At}
} }
// View is a request as the API shows it. // View is the API representation of an approval request.
type View struct { type View struct {
ID uuid.UUID `json:"id"` ID uuid.UUID `json:"id"`
Kind string `json:"kind"` Kind string `json:"kind"`
@@ -129,11 +124,10 @@ type View struct {
Summary string `json:"summary"` Summary string `json:"summary"`
State string `json:"state"` State string `json:"state"`
Deadline time.Time `json:"deadline"` Deadline time.Time `json:"deadline"`
// Step is the escalation step the request is at, and StepDeadline when it // Step and StepDeadline describe the current escalation step.
// moves to the next.
Step int `json:"step"` Step int `json:"step"`
StepDeadline time.Time `json:"step_deadline,omitzero"` StepDeadline time.Time `json:"step_deadline,omitzero"`
// DecisionID is the judged action the request is about. // DecisionID identifies the judgement decision or, for a raise request, the proposed raise.
DecisionID uuid.UUID `json:"decision_id"` DecisionID uuid.UUID `json:"decision_id"`
RequestedAt time.Time `json:"requested_at"` RequestedAt time.Time `json:"requested_at"`
AnsweredBy string `json:"answered_by,omitzero"` AnsweredBy string `json:"answered_by,omitzero"`
@@ -141,7 +135,7 @@ type View struct {
AnsweredAt time.Time `json:"answered_at,omitzero"` AnsweredAt time.Time `json:"answered_at,omitzero"`
} }
// View is r as the API shows it. // View converts a request to its API representation.
func (r Request) View() View { func (r Request) View() View {
return View{ return View{
ID: r.ID, Kind: r.Kind, RunID: r.RunID, Action: r.Connector + " " + r.Action, ID: r.ID, Kind: r.Kind, RunID: r.RunID, Action: r.Connector + " " + r.Action,
@@ -157,16 +151,15 @@ type Signaller interface {
Signal(ctx context.Context, id uuid.UUID, key string, payload jsontext.Value) error Signal(ctx context.Context, id uuid.UUID, key string, payload jsontext.Value) error
} }
// Delivery carries a request to every channel someone can answer on. // Delivery sends approval requests and publishes responses and notifications.
type Delivery interface { type Delivery interface {
Ask(ctx context.Context, a deliveries.ApprovalRequest) error Ask(ctx context.Context, a deliveries.ApprovalRequest) error
Told(ctx context.Context, a deliveries.ApprovalRequest, answer string) error Told(ctx context.Context, a deliveries.ApprovalRequest, answer string) error
Notify(ctx context.Context, n deliveries.Notification) error Notify(ctx context.Context, n deliveries.Notification) error
} }
// Classes is where answers become autonomy: an approval counts toward raising // Classes updates action-class autonomy. Denials reduce autonomy; approvals
// an action class, a denial tightens it, and a raise a person approves // count towards an increase that a person must approve separately.
// loosens it.
type Classes interface { type Classes interface {
Approved(ctx context.Context, decisionID uuid.UUID, by string, need int, deadline time.Time) (*judgement.Raise, error) Approved(ctx context.Context, decisionID uuid.UUID, by string, need int, deadline time.Time) (*judgement.Raise, error)
Denied(ctx context.Context, decisionID uuid.UUID) error Denied(ctx context.Context, decisionID uuid.UUID) error
@@ -174,14 +167,13 @@ type Classes interface {
CancelRaise(ctx context.Context, id uuid.UUID) error CancelRaise(ctx context.Context, id uuid.UUID) error
} }
// Policy is what the organisation decided about approvals. // Policy provides the organisation's deadline and approval threshold for raises.
type Policy interface { type Policy interface {
ApprovalDeadline(ctx context.Context) (time.Duration, error) ApprovalDeadline(ctx context.Context) (time.Duration, error)
RaiseAfter(ctx context.Context) (int, error) RaiseAfter(ctx context.Context) (int, error)
} }
// People says who an identity belongs to. An answer from an identity it // People resolves verified channel identities to people.
// doesn't verify is refused.
type People interface { type People interface {
Verify(ctx context.Context, identity string) (governance.Verified, bool, error) Verify(ctx context.Context, identity string) (governance.Verified, bool, error)
} }
@@ -200,10 +192,7 @@ type Module struct {
now func() time.Time now func() time.Time
} }
// NewModule returns the approvals module for orgID. Answers are delivered by // NewModule creates the approvals module for orgID.
// tell and wake the run through wake, and are counted into classes under
// policy. An answer a channel delivers is accepted only from an identity
// people verifies.
func NewModule(db *sqlx.DB, log *slog.Logger, orgID string, tell Delivery, wake Signaller, classes Classes, policy Policy, people People) *Module { func NewModule(db *sqlx.DB, log *slog.Logger, orgID string, tell Delivery, wake Signaller, classes Classes, policy Policy, people People) *Module {
return &Module{ return &Module{
orgID: orgID, store: store.New(db), tell: tell, wake: wake, classes: classes, policy: policy, people: people, orgID: orgID, store: store.New(db), tell: tell, wake: wake, classes: classes, policy: policy, people: people,
@@ -211,12 +200,10 @@ func NewModule(db *sqlx.DB, log *slog.Logger, orgID string, tell Delivery, wake
} }
} }
// Ask records a request for d and puts it to the first step of path. It runs // Ask reuses the request for the same run and key so retries do not create
// out for good when the last step does. Asking again for the same run and key // duplicate requests. It uses a change-request connector when judgement
// returns the request that stands, so a replayed step asks once. An action // requires a change request and a connector is configured. Otherwise, it
// judgement's change-request rules pick goes through a change request when a // sends the request to the approval channels with the first step's deadline.
// change-request connector is installed, and every other one through the
// approvers' channels.
func (m *Module) Ask(ctx context.Context, runID uuid.UUID, key string, d judgement.Decision, path []governance.PathStep) (Request, error) { func (m *Module) Ask(ctx context.Context, runID uuid.UUID, key string, d judgement.Decision, path []governance.PathStep) (Request, error) {
if len(path) == 0 { if len(path) == 0 {
return Request{}, ErrNoPath return Request{}, ErrNoPath
@@ -267,9 +254,6 @@ func (m *Module) Ask(ctx context.Context, runID uuid.UUID, key string, d judgeme
return r, nil return r, nil
} }
// answerAs settles request id with a verified person's decision and wakes the run
// waiting on it. Only a pending request settles: a second answer, or one that
// arrives after the deadline, is refused and wakes nobody.
func (m *Module) answerAs(ctx context.Context, id uuid.UUID, by, via string, approved bool) (Request, error) { func (m *Module) answerAs(ctx context.Context, id uuid.UUID, by, via string, approved bool) (Request, error) {
now := m.now().UTC() now := m.now().UTC()
if _, err := m.pending(ctx, id, now); err != nil { if _, err := m.pending(ctx, id, now); err != nil {
@@ -296,9 +280,8 @@ func (m *Module) answerAs(ctx context.Context, id uuid.UUID, by, via string, app
if err := m.wakeWith(ctx, row, answer); err != nil { if err := m.wakeWith(ctx, row, answer); err != nil {
return Request{}, err return Request{}, err
} }
// The run has what it waited for. A denial tightens the class now. An // Count denials immediately. Defer counting approvals until execution
// approval counts only once the action is about to run on it, so one that // is imminent so discarded approvals do not increase autonomy.
// is discarded first counts for nothing.
if !answer.Approved { if !answer.Approved {
if err := m.classes.Denied(ctx, row.DecisionID); err != nil { if err := m.classes.Denied(ctx, row.DecisionID); err != nil {
return Request{}, err return Request{}, err
@@ -307,8 +290,6 @@ func (m *Module) answerAs(ctx context.Context, id uuid.UUID, by, via string, app
return requestOf(row, judgement.Decision{}), nil return requestOf(row, judgement.Decision{}), nil
} }
// learn counts an approval of an action into its class. An approval that
// completes a run of them earns a raise, which is put to a person.
func (m *Module) learn(ctx context.Context, row store.Request, a Answer) error { func (m *Module) learn(ctx context.Context, row store.Request, a Answer) error {
need, err := m.policy.RaiseAfter(ctx) need, err := m.policy.RaiseAfter(ctx)
if err != nil { if err != nil {
@@ -325,8 +306,6 @@ func (m *Module) learn(ctx context.Context, row store.Request, a Answer) error {
return m.askRaise(ctx, raise) return m.askRaise(ctx, raise)
} }
// askRaise puts a raise to a person on every channel. If it can't be asked the
// raise is withdrawn, so the class proposes it again at its next approval.
func (m *Module) askRaise(ctx context.Context, r *judgement.Raise) error { func (m *Module) askRaise(ctx context.Context, r *judgement.Raise) error {
class := r.Class class := r.Class
row, err := m.store.Put(ctx, store.Request{ row, err := m.store.Put(ctx, store.Request{
@@ -343,6 +322,7 @@ func (m *Module) askRaise(ctx context.Context, r *judgement.Raise) error {
}) })
} }
if err != nil { if err != nil {
// Cancel the raise so a later approval can trigger another proposal.
if cerr := m.classes.CancelRaise(ctx, r.ID); cerr != nil { if cerr := m.classes.CancelRaise(ctx, r.ID); cerr != nil {
err = errors.Join(err, cerr) err = errors.Join(err, cerr)
} }
@@ -359,19 +339,17 @@ func (m *Module) answerRaise(ctx context.Context, row store.Request, a Answer) e
} }
text := answerText(a) text := answerText(a)
if a.Approved && !raised { if a.Approved && !raised {
text += " The class had changed since, so its level stays." text += " This approval did not increase the action class's autonomy level."
} }
return m.tell.Told(ctx, deliveries.ApprovalRequest{ return m.tell.Told(ctx, deliveries.ApprovalRequest{
RequestID: row.ID, Key: row.Key + ":ask", Title: "Raise answered", RequestID: row.ID, Key: row.Key + ":ask", Title: "Raise answered",
}, text) }, text)
} }
// raiseSummary is what a person is shown about a raise: the class, the change
// and the approvals that earned it.
func raiseSummary(r *judgement.Raise) string { func raiseSummary(r *judgement.Raise) string {
c := r.Class c := r.Class
var s strings.Builder var s strings.Builder
fmt.Fprintf(&s, "%s: %s on %s in %s. Raise from %s to %s.\nEarned by %d approvals in a row:", fmt.Fprintf(&s, "%s: %s on %s in %s. Proposed autonomy increase: %s to %s.\nConsecutive approvals (%d):",
c.Connector, c.Action, c.TargetKind, c.Environment, r.From, r.To, len(r.Evidence)) c.Connector, c.Action, c.TargetKind, c.Environment, r.From, r.To, len(r.Evidence))
for _, e := range r.Evidence { for _, e := range r.Evidence {
fmt.Fprintf(&s, "\n- %s, %s", e.By, e.At.UTC().Format("2006-01-02 15:04 UTC")) fmt.Fprintf(&s, "\n- %s, %s", e.By, e.At.UTC().Format("2006-01-02 15:04 UTC"))
@@ -379,13 +357,10 @@ func raiseSummary(r *judgement.Raise) string {
return s.String() return s.String()
} }
// Settle answers a request from an answer a channel delivered as an event, // Settle processes a response from a channel identity such as "telegram:1001".
// given by identity (such as "telegram:1001"). An answer from an identity no // It records why it rejected an unverified or unauthorized response. It returns
// person holds, or from a person who may not answer that kind of request, is // false without an error for recorded rejections and for requests that are
// refused and the refusal recorded with its reason. An answer that can't // missing, expired or already answered, since retrying won't help.
// settle the request, because it was already answered, has expired or names no
// request, also reports false rather than an error: retrying the event would
// never change that.
func (m *Module) Settle(ctx context.Context, id uuid.UUID, identity, via string, approved bool) (bool, error) { func (m *Module) Settle(ctx context.Context, id uuid.UUID, identity, via string, approved bool) (bool, error) {
row, err := m.store.ByID(ctx, m.orgID, id) row, err := m.store.ByID(ctx, m.orgID, id)
if errors.Is(err, ErrNotFound) { if errors.Is(err, ErrNotFound) {
@@ -414,11 +389,6 @@ func (m *Module) Settle(ctx context.Context, id uuid.UUID, identity, via string,
return false, err return false, err
} }
// verify says whether identity may answer request row. An action is answered
// by someone who answers for actions and whom the request has reached on its
// escalation path, or who holds authority, and an action at the escalate level
// needs authority. A raise changes policy, so only a person with authority
// answers it.
func (m *Module) verify(ctx context.Context, identity string, row store.Request) (governance.Verified, error) { func (m *Module) verify(ctx context.Context, identity string, row store.Request) (governance.Verified, error) {
who, ok, err := m.people.Verify(ctx, identity) who, ok, err := m.people.Verify(ctx, identity)
if err != nil { if err != nil {
@@ -446,7 +416,6 @@ func mayAnswer(who governance.Verified, row store.Request) error {
return nil return nil
} }
// askedOf is the ids of the people the request has reached.
func askedOf(row store.Request) []string { func askedOf(row store.Request) []string {
var ids []string var ids []string
if err := json.Unmarshal([]byte(row.Asked), &ids); err != nil { if err := json.Unmarshal([]byte(row.Asked), &ids); err != nil {
@@ -455,16 +424,14 @@ func askedOf(row store.Request) []string {
return ids return ids
} }
// refusal reports whether err is a refused answer rather than a failure. // refusal distinguishes a rejected response from an operational error.
func refusal(err error) bool { func refusal(err error) bool {
return errors.Is(err, ErrUnverified) || errors.Is(err, ErrNotApprover) || errors.Is(err, ErrNoAuthority) || return errors.Is(err, ErrUnverified) || errors.Is(err, ErrNotApprover) || errors.Is(err, ErrNoAuthority) ||
errors.Is(err, ErrNotAsked) || errors.Is(err, ErrNeedsAuthority) errors.Is(err, ErrNotAsked) || errors.Is(err, ErrNeedsAuthority)
} }
// Expire settles a request whose last escalation step ran out, so the trail // Expire records a timeout without reducing the action class's autonomy:
// shows why it never ran. Nothing is acted on, an open change request is // receiving no response is not a denial.
// withdrawn, and the report goes to every channel. Expiry says nothing about
// the action's class, so it is not tightened.
func (m *Module) Expire(ctx context.Context, id uuid.UUID) error { func (m *Module) Expire(ctx context.Context, id uuid.UUID) error {
row, err := m.store.Answer(ctx, m.orgID, id, StateExpired, "deadline", "clock", m.now().UTC()) row, err := m.store.Answer(ctx, m.orgID, id, StateExpired, "deadline", "clock", m.now().UTC())
if err != nil { if err != nil {
@@ -486,16 +453,15 @@ func (m *Module) Expire(ctx context.Context, id uuid.UUID) error {
} }
if err := m.tell.Told(ctx, deliveries.ApprovalRequest{ if err := m.tell.Told(ctx, deliveries.ApprovalRequest{
RunID: row.RunID, RequestID: row.ID, Key: row.Key + ":ask", RunID: row.RunID, RequestID: row.ID, Key: row.Key + ":ask",
Title: "Approval expired", Body: "The request ran out of time, so nothing was run." + withdrawn, Title: "Approval expired", Body: "The approval request expired without a response. The action did not run." + withdrawn,
}, "Expired without an answer."); err != nil { }, "Expired without an answer."); err != nil {
return err return err
} }
// The report goes to every channel. Its key is stable, so an Expire // Use a stable key so retrying the expiry does not duplicate the notification.
// retried after a failed delivery sends it once.
return m.tell.Notify(ctx, deliveries.Notification{ return m.tell.Notify(ctx, deliveries.Notification{
RunID: row.RunID, Key: row.Key + ":expired", RunID: row.RunID, Key: row.Key + ":expired",
Title: "Approval timed out: " + row.Connector + " " + row.Action, Title: "Approval timed out: " + row.Connector + " " + row.Action,
Body: "Nobody answered before the last escalation step ran out, so " + row.Connector + " " + row.Action + Body: "No one responded before the final escalation deadline, so " + row.Connector + " " + row.Action +
" did not run." + withdrawn + " " + row.Summary, " did not run." + withdrawn + " " + row.Summary,
}) })
} }
@@ -526,8 +492,7 @@ func (m *Module) ForRun(ctx context.Context, runID uuid.UUID) ([]Request, error)
return out, nil return out, nil
} }
// Outcomes says what became of the requests made for the decisions in ids, // Outcomes returns approval outcomes by decision ID for the action class history.
// for the history of the action class they belong to.
func (m *Module) Outcomes(ctx context.Context, ids []uuid.UUID) (map[uuid.UUID]judgement.Outcome, error) { func (m *Module) Outcomes(ctx context.Context, ids []uuid.UUID) (map[uuid.UUID]judgement.Outcome, error) {
rows, err := m.store.ByDecisions(ctx, m.orgID, ids) rows, err := m.store.ByDecisions(ctx, m.orgID, ids)
if err != nil { if err != nil {
@@ -560,9 +525,8 @@ func (m *Module) Register(api huma.API) {
}, m.answer) }, m.answer)
} }
// bootstrapAdmin names the identity the bootstrap admin token stands for. The // The token guard authenticates the bootstrap admin before the API handler,
// token guard has already authenticated it, so it counts as a person with // so the handler does not look up a channel identity.
// authority and skips the people check until real sign-in exists.
const bootstrapAdmin = "admin" const bootstrapAdmin = "admin"
type answerInput struct { type answerInput struct {
@@ -604,9 +568,6 @@ func (m *Module) answer(ctx context.Context, in *answerInput) (*httpapi.Reply[Vi
return httpapi.OK(out.View()), nil return httpapi.OK(out.View()), nil
} }
// pending reads a request that is still open and inside its deadline. The
// store settles only a pending row; this refuses the answer before that, with
// the reason.
func (m *Module) pending(ctx context.Context, id uuid.UUID, now time.Time) (store.Request, error) { func (m *Module) pending(ctx context.Context, id uuid.UUID, now time.Time) (store.Request, error) {
row, err := m.store.ByID(ctx, m.orgID, id) row, err := m.store.ByID(ctx, m.orgID, id)
if err != nil { if err != nil {
@@ -618,8 +579,6 @@ func (m *Module) pending(ctx context.Context, id uuid.UUID, now time.Time) (stor
return row, nil return row, nil
} }
// settleable says whether an answer now may settle r. A request settles once:
// a second answer, and one that arrives after the deadline, changes nothing.
func settleable(r store.Request, now time.Time) error { func settleable(r store.Request, now time.Time) error {
switch { switch {
case r.State != StatePending: case r.State != StatePending:
@@ -652,8 +611,7 @@ func answerText(a Answer) string {
return fmt.Sprintf("%s by %s via %s.", verb, a.By, a.Via) return fmt.Sprintf("%s by %s via %s.", verb, a.By, a.Via)
} }
// Summary is what a person is shown about the action they are asked to allow: // Summary shows the approver the action, its target and why it requires approval.
// what it does, to what, and what held it back.
func Summary(d judgement.Decision) string { func Summary(d judgement.Decision) string {
s := fmt.Sprintf("%s: %s on %s %q.", d.Action.Connector, d.Action.Name, d.Action.Target.Kind, d.Action.Target.ID) s := fmt.Sprintf("%s: %s on %s %q.", d.Action.Connector, d.Action.Name, d.Action.Target.Kind, d.Action.Target.ID)
if d.Action.Effect.Summary != "" { if d.Action.Effect.Summary != "" {
@@ -682,7 +640,7 @@ func Summary(d judgement.Decision) string {
} }
// inputLine renders an action's input as "key=value" pairs in key order, or // inputLine renders an action's input as "key=value" pairs in key order, or
// the raw JSON when it isn't a flat object. // the raw JSON when it is not a nonempty object.
func inputLine(input jsontext.Value) string { func inputLine(input jsontext.Value) string {
var fields map[string]jsontext.Value var fields map[string]jsontext.Value
if err := json.Unmarshal(input, &fields); err != nil || len(fields) == 0 { if err := json.Unmarshal(input, &fields); err != nil || len(fields) == 0 {
@@ -700,7 +658,6 @@ func inputLine(input jsontext.Value) string {
return strings.Join(parts, ", ") return strings.Join(parts, ", ")
} }
// requestOf is a stored row as the module's Request.
func requestOf(row store.Request, d judgement.Decision) Request { func requestOf(row store.Request, d judgement.Decision) Request {
r := Request{ r := Request{
ID: row.ID, Kind: row.Kind, RunID: row.RunID, Key: row.Key, Decision: d, DecisionID: row.DecisionID, RequestedAt: row.CreatedAt, ID: row.ID, Kind: row.Kind, RunID: row.RunID, Key: row.Key, Decision: d, DecisionID: row.DecisionID, RequestedAt: row.CreatedAt,
+17 -20
View File
@@ -19,11 +19,9 @@ func (f fakePeople) Verify(_ context.Context, identity string) (governance.Verif
return p, ok, nil return p, ok, nil
} }
// TestVerifyAcceptsAnAnswerOnlyFromAPersonWhoMayGiveIt guards the rule that an // TestVerifyAcceptsAnAnswerOnlyFromAPersonWhoMayGiveIt checks that a verified
// approval counts only from a verified identity, on every channel: an identity // identity alone is not enough: the request kind, escalation step and required
// no person holds, a person without the standing for that kind of request, a // authority also determine who can respond.
// person the request hasn't reached on its escalation path, or one without the
// authority the action's level needs, is refused rather than settling it.
func TestVerifyAcceptsAnAnswerOnlyFromAPersonWhoMayGiveIt(t *testing.T) { func TestVerifyAcceptsAnAnswerOnlyFromAPersonWhoMayGiveIt(t *testing.T) {
people := fakePeople{ people := fakePeople{
"telegram:1001": {ID: "owner", Name: "Owner", Approver: true}, "telegram:1001": {ID: "owner", Name: "Owner", Approver: true},
@@ -41,18 +39,18 @@ func TestVerifyAcceptsAnAnswerOnlyFromAPersonWhoMayGiveIt(t *testing.T) {
row store.Request row store.Request
wantErr error wantErr error
}{ }{
{name: "an approver the request has reached answers", identity: "telegram:1001", row: action(propose, "owner")}, {name: "an approver can respond once notified", identity: "telegram:1001", row: action(propose, "owner")},
{name: "an unmapped identity is refused", identity: "telegram:9999", row: action(propose, "owner"), wantErr: ErrUnverified}, {name: "an unmapped identity is refused", identity: "telegram:9999", row: action(propose, "owner"), wantErr: ErrUnverified},
{name: "an unmapped identity can't answer a raise", identity: "telegram:9999", row: store.Request{Kind: KindRaise}, wantErr: ErrUnverified}, {name: "an unmapped identity can't answer a raise", identity: "telegram:9999", row: store.Request{Kind: KindRaise}, wantErr: ErrUnverified},
{name: "a person who isn't an approver is refused an action", identity: "telegram:1003", row: action(propose, "owner"), wantErr: ErrNotApprover}, {name: "an unlisted person who isn't an approver cannot respond", identity: "telegram:1003", row: action(propose, "owner"), wantErr: ErrNotApprover},
{name: "the target's owner answers when the request was put to them", identity: "telegram:1003", row: action(propose, "bystander")}, {name: "the target owner can respond when explicitly asked", identity: "telegram:1003", row: action(propose, "bystander")},
{name: "an approver without authority is refused a raise", identity: "telegram:1001", row: store.Request{Kind: KindRaise}, wantErr: ErrNoAuthority}, {name: "an approver without authority cannot respond to a raise", identity: "telegram:1001", row: store.Request{Kind: KindRaise}, wantErr: ErrNoAuthority},
{name: "authority answers a raise", identity: "telegram:1002", row: store.Request{Kind: KindRaise}}, {name: "a person with authority can respond to a raise", identity: "telegram:1002", row: store.Request{Kind: KindRaise}},
{name: "a person on the path is refused until the request reaches them", identity: "telegram:1004", row: action(propose, "owner"), wantErr: ErrNotAsked}, {name: "a later approver cannot respond before escalation", identity: "telegram:1004", row: action(propose, "owner"), wantErr: ErrNotAsked},
{name: "a person on the path answers once the request reaches them", identity: "telegram:1004", row: action(propose, "owner", "second")}, {name: "a later approver can respond after escalation", identity: "telegram:1004", row: action(propose, "owner", "second")},
{name: "authority answers before it is asked", identity: "telegram:1002", row: action(propose, "owner")}, {name: "a person with authority can respond without being asked", identity: "telegram:1002", row: action(propose, "owner")},
{name: "an action at escalate needs authority even from someone asked", identity: "telegram:1001", row: action(escalate, "owner"), wantErr: ErrNeedsAuthority}, {name: "the escalate level requires authority even when the approver was asked", identity: "telegram:1001", row: action(escalate, "owner"), wantErr: ErrNeedsAuthority},
{name: "authority answers an action at escalate", identity: "telegram:1002", row: action(escalate, "owner")}, {name: "a person with authority can respond at the escalate level", identity: "telegram:1002", row: action(escalate, "owner")},
} }
m := &Module{people: people} m := &Module{people: people}
for _, tt := range tests { for _, tt := range tests {
@@ -68,9 +66,8 @@ func TestVerifyAcceptsAnAnswerOnlyFromAPersonWhoMayGiveIt(t *testing.T) {
} }
} }
// TestSettleableRefusesASecondAnswerOrALateOne guards the rule that makes an // TestSettleableRefusesASecondAnswerOrALateOne checks that a settled request or
// approval one decision: the first answer settles a request, so a replaying // one at its deadline cannot accept a response.
// answer or one that arrives after the deadline wakes no run and runs nothing.
func TestSettleableRefusesASecondAnswerOrALateOne(t *testing.T) { func TestSettleableRefusesASecondAnswerOrALateOne(t *testing.T) {
deadline := time.Date(2026, 11, 16, 12, 0, 0, 0, time.UTC) deadline := time.Date(2026, 11, 16, 12, 0, 0, 0, time.UTC)
request := func(state string) store.Request { request := func(state string) store.Request {
@@ -82,8 +79,8 @@ func TestSettleableRefusesASecondAnswerOrALateOne(t *testing.T) {
now time.Time now time.Time
wantErr error wantErr error
}{ }{
{name: "a pending request settles inside its deadline", row: request(StatePending), now: deadline.Add(-time.Minute)}, {name: "a pending request accepts a response before the deadline", row: request(StatePending), now: deadline.Add(-time.Minute)},
{name: "a pending request is too late after its deadline", row: request(StatePending), now: deadline, wantErr: ErrExpired}, {name: "a pending request rejects a response at the deadline", row: request(StatePending), now: deadline, wantErr: ErrExpired},
{name: "an approved request doesn't settle again", row: request(StateApproved), now: deadline.Add(-time.Minute), wantErr: ErrAnswered}, {name: "an approved request doesn't settle again", row: request(StateApproved), now: deadline.Add(-time.Minute), wantErr: ErrAnswered},
{name: "a denied request doesn't settle again", row: request(StateDenied), now: deadline.Add(-time.Minute), wantErr: ErrAnswered}, {name: "a denied request doesn't settle again", row: request(StateDenied), now: deadline.Add(-time.Minute), wantErr: ErrAnswered},
{name: "an expired request doesn't settle", row: request(StateExpired), now: deadline.Add(-time.Minute), wantErr: ErrAnswered}, {name: "an expired request doesn't settle", row: request(StateExpired), now: deadline.Add(-time.Minute), wantErr: ErrAnswered},
+14 -20
View File
@@ -12,24 +12,20 @@ import (
"github.com/samcharles93/archie-core/modules/governance" "github.com/samcharles93/archie-core/modules/governance"
) )
// ChangeRequests is a change-request connector. Judgement's change-request // ChangeRequests manages external change requests for actions that require them.
// rules decide which held actions need one; this opens and withdraws them.
type ChangeRequests interface { type ChangeRequests interface {
// Open raises the change request for r. It may be called again for the same // Open must be idempotent for the same approval request.
// request and must not open a second one.
Open(ctx context.Context, r Request) error Open(ctx context.Context, r Request) error
// Withdraw withdraws r's change request if it is still open. // Withdraw withdraws r's change request if it is still open.
Withdraw(ctx context.Context, r Request) error Withdraw(ctx context.Context, r Request) error
} }
// UseChangeRequests makes the module open the change requests judgement asks // UseChangeRequests configures the change-request connector. Without one,
// for through c. Without one, those approvals go to the approvers' channels, // approval requests still go to the approvers' channels.
// so a rule never strands a request where nobody can answer it.
func (m *Module) UseChangeRequests(c ChangeRequests) { m.changes = c } func (m *Module) UseChangeRequests(c ChangeRequests) { m.changes = c }
// Escalate passes a pending request to step n of its path, telling every // Escalate advances a pending request to step n. It sets the step's deadline
// channel who it has reached and until when. The step's deadline runs from // relative to the time of escalation.
// now. A request that has since been answered is left alone.
func (m *Module) Escalate(ctx context.Context, id uuid.UUID, n int, to governance.PathStep) error { func (m *Module) Escalate(ctx context.Context, id uuid.UUID, n int, to governance.PathStep) error {
row, err := m.store.ByID(ctx, m.orgID, id) row, err := m.store.ByID(ctx, m.orgID, id)
if err != nil { if err != nil {
@@ -43,12 +39,12 @@ func (m *Module) Escalate(ctx context.Context, id uuid.UUID, n int, to governanc
if to.Name != "" { if to.Name != "" {
who = to.Name who = to.Name
} }
// The notice goes first and is idempotent by key, so an escalation retried // Send the notice before updating the request. If the update fails,
// after the move failed still tells people once. // retrying with the same key won't duplicate the notice.
if err := m.tell.Notify(ctx, deliveries.Notification{ if err := m.tell.Notify(ctx, deliveries.Notification{
RunID: row.RunID, Key: row.Key + ":escalated:" + strconv.Itoa(n), RunID: row.RunID, Key: row.Key + ":escalated:" + strconv.Itoa(n),
Title: "Approval escalated: " + row.Connector + " " + row.Action, Title: "Approval escalated: " + row.Connector + " " + row.Action,
Body: "Nobody answered in time, so it now goes to " + who + " and waits until " + until.Format("2006-01-02 15:04 UTC") + ". " + row.Summary, Body: "No one responded before the previous deadline. Next approver: " + who + ". Response deadline: " + until.Format("2006-01-02 15:04 UTC") + ". " + row.Summary,
}); err != nil { }); err != nil {
return err return err
} }
@@ -59,9 +55,8 @@ func (m *Module) Escalate(ctx context.Context, id uuid.UUID, n int, to governanc
return nil return nil
} }
// Accept counts an approval toward raising its action class, once, when the // Accept counts an approval towards an increase in autonomy just before the
// action it covers is about to run. An approval that is discarded first never // action runs. Each approval counts at most once; discarded approvals do not count.
// counts.
func (m *Module) Accept(ctx context.Context, id uuid.UUID) error { func (m *Module) Accept(ctx context.Context, id uuid.UUID) error {
row, counted, err := m.store.Count(ctx, m.orgID, id) row, counted, err := m.store.Count(ctx, m.orgID, id)
if err != nil || !counted { if err != nil || !counted {
@@ -72,9 +67,8 @@ func (m *Module) Accept(ctx context.Context, id uuid.UUID) error {
}) })
} }
// Discard withdraws an approval whose action changed before it could run, and // Discard records why an approval is no longer valid and notifies the approval
// says why. A discarded approval doesn't count toward a raise, and a request // channels. A discarded approval cannot count towards a raise.
// for the changed action is a new one.
func (m *Module) Discard(ctx context.Context, id uuid.UUID, because string) error { func (m *Module) Discard(ctx context.Context, id uuid.UUID, because string) error {
row, discarded, err := m.store.Discard(ctx, m.orgID, id, because) row, discarded, err := m.store.Discard(ctx, m.orgID, id, because)
if err != nil || !discarded { if err != nil || !discarded {
@@ -90,5 +84,5 @@ func (m *Module) Discard(ctx context.Context, id uuid.UUID, because string) erro
return nil return nil
} }
// ErrNoPath means a request was asked without anyone to put it to. // ErrNoPath indicates that an approval request has no escalation path.
var ErrNoPath = errors.New("an approval request needs an escalation path") var ErrNoPath = errors.New("an approval request needs an escalation path")
+18 -23
View File
@@ -1,5 +1,4 @@
// Package store holds the approvals module's SQL: the requests waiting for an // Package store persists approval requests, responses and rejections.
// answer, and what was answered.
package store package store
import ( import (
@@ -13,19 +12,17 @@ import (
"github.com/jmoiron/sqlx" "github.com/jmoiron/sqlx"
) )
// Request is one judged action waiting for a person's answer. // Request is the stored record of an action or raise approval request.
type Request struct { type Request struct {
ID uuid.UUID `db:"id"` ID uuid.UUID `db:"id"`
OrgID string `db:"org_id"` OrgID string `db:"org_id"`
RunID uuid.UUID `db:"run_id"` RunID uuid.UUID `db:"run_id"`
Key string `db:"key"` Key string `db:"key"`
// DecisionID is the judged action the request is about, or for a raise // DecisionID identifies the judgement decision or the proposed raise.
// request the raise.
DecisionID uuid.UUID `db:"decision_id"` DecisionID uuid.UUID `db:"decision_id"`
Kind string `db:"kind"` Kind string `db:"kind"`
Digest string `db:"digest"` Digest string `db:"digest"`
// The action's own names, kept so a request reads back without its // Copy the action details so the request can be read without loading the decision.
// decision.
Connector string `db:"connector"` Connector string `db:"connector"`
Action string `db:"action"` Action string `db:"action"`
TargetKind string `db:"target_kind"` TargetKind string `db:"target_kind"`
@@ -38,9 +35,8 @@ type Request struct {
AnsweredAt sql.NullTime `db:"answered_at"` AnsweredAt sql.NullTime `db:"answered_at"`
AnsweredBy sql.NullString `db:"answered_by"` AnsweredBy sql.NullString `db:"answered_by"`
AnsweredVia sql.NullString `db:"answered_via"` AnsweredVia sql.NullString `db:"answered_via"`
// Step is the escalation step the request is at, StepDeadline when that // Asked is a JSON array of person IDs reached so far, not just the
// step runs out, and Asked a JSON array of the ids of the people it has // person assigned to the current step.
// reached so far.
Step int `db:"step"` Step int `db:"step"`
StepDeadline sql.NullTime `db:"step_deadline"` StepDeadline sql.NullTime `db:"step_deadline"`
Asked string `db:"asked"` Asked string `db:"asked"`
@@ -48,8 +44,7 @@ type Request struct {
// rather than the approvers' channels. // rather than the approvers' channels.
ChangeRequest bool `db:"change_request"` ChangeRequest bool `db:"change_request"`
// Counted is whether the approval was counted toward raising its class. // Counted is whether the approval was counted toward raising its class.
Counted bool `db:"counted"` Counted bool `db:"counted"`
// DiscardedBecause is why an approval no longer stood.
DiscardedBecause sql.NullString `db:"discarded_because"` DiscardedBecause sql.NullString `db:"discarded_because"`
} }
@@ -65,8 +60,8 @@ const requestColumns = `id, org_id, run_id, key, decision_id, kind, digest, conn
target_id, level, summary, state, deadline, created_at, answered_at, answered_by, answered_via, target_id, level, summary, state, deadline, created_at, answered_at, answered_by, answered_via,
step, step_deadline, asked::text AS asked, change_request, counted, discarded_because` step, step_deadline, asked::text AS asked, change_request, counted, discarded_because`
// Put records r unless a request already exists for its run and key, and // Put inserts r or returns the existing request for the same organisation,
// returns the request that stands either way. // run and key.
func (s *Store) Put(ctx context.Context, r Request) (Request, error) { func (s *Store) Put(ctx context.Context, r Request) (Request, error) {
var out Request var out Request
err := s.db.GetContext(ctx, &out, ` err := s.db.GetContext(ctx, &out, `
@@ -107,8 +102,8 @@ func (s *Store) Get(ctx context.Context, orgID string, runID uuid.UUID, key stri
return out, nil return out, nil
} }
// Answer settles one request, and only while it is still pending. It returns // Answer updates only pending requests. If another response already settled
// the request as it now stands, or the one that already settled it. // the request, it returns the stored record unchanged.
func (s *Store) Answer(ctx context.Context, orgID string, id uuid.UUID, state, by, via string, at time.Time) (Request, error) { func (s *Store) Answer(ctx context.Context, orgID string, id uuid.UUID, state, by, via string, at time.Time) (Request, error) {
var out Request var out Request
err := s.db.GetContext(ctx, &out, ` err := s.db.GetContext(ctx, &out, `
@@ -125,9 +120,9 @@ func (s *Store) Answer(ctx context.Context, orgID string, id uuid.UUID, state, b
return out, nil return out, nil
} }
// Escalate moves a pending request to step, which has reached person and runs // Escalate advances a pending request to step, sets the deadline to until and
// out at until. It returns false when the request is no longer pending, or has // records person if supplied. It returns false if the request has already
// already moved that far, so a replayed escalation changes nothing. // reached that step or is no longer pending.
func (s *Store) Escalate(ctx context.Context, orgID string, id uuid.UUID, step int, person string, until time.Time) (Request, bool, error) { func (s *Store) Escalate(ctx context.Context, orgID string, id uuid.UUID, step int, person string, until time.Time) (Request, bool, error) {
var out Request var out Request
err := s.db.GetContext(ctx, &out, ` err := s.db.GetContext(ctx, &out, `
@@ -145,8 +140,8 @@ func (s *Store) Escalate(ctx context.Context, orgID string, id uuid.UUID, step i
return out, true, nil return out, true, nil
} }
// Discard withdraws an approval that no longer stands, and only while it has // Discard invalidates an approval only if it has not yet been counted.
// not been counted. It returns false when there was nothing to discard. // It returns false if no record was updated.
func (s *Store) Discard(ctx context.Context, orgID string, id uuid.UUID, because string) (Request, bool, error) { func (s *Store) Discard(ctx context.Context, orgID string, id uuid.UUID, because string) (Request, bool, error) {
var out Request var out Request
err := s.db.GetContext(ctx, &out, ` err := s.db.GetContext(ctx, &out, `
@@ -162,8 +157,8 @@ func (s *Store) Discard(ctx context.Context, orgID string, id uuid.UUID, because
return out, true, nil return out, true, nil
} }
// Count marks an approval as counted, once. It returns false when the approval // Count marks a valid action approval as counted. It returns false if no
// was already counted or no longer stands. // eligible approval was updated.
func (s *Store) Count(ctx context.Context, orgID string, id uuid.UUID) (Request, bool, error) { func (s *Store) Count(ctx context.Context, orgID string, id uuid.UUID) (Request, bool, error) {
var out Request var out Request
err := s.db.GetContext(ctx, &out, ` err := s.db.GetContext(ctx, &out, `
+24 -29
View File
@@ -1,7 +1,6 @@
// Package drafts holds what an unmatched group of events could become: the // Package drafts manages proposed triggers, workflows and policies for groups
// trigger it proposes, the workflow that trigger would start and any policy // of unmatched events. Drafts can be tested by replaying a stored event in a
// that workflow needs, with a plain-language summary and a dry run. Nothing in // dry run before the trigger is enabled.
// a draft is in force until it is published.
package drafts package drafts
import ( import (
@@ -28,11 +27,10 @@ import (
"github.com/samcharles93/archie-core/modules/runs" "github.com/samcharles93/archie-core/modules/runs"
) )
// replayable is how many of a group's newest events a dry run can choose from. // replayable limits dry runs to the group's most recently received events.
const replayable = 50 const replayable = 50
// Groups is where a draft finds the unmatched events it is made from, and // Groups provides unmatched event groups, replay tracking and trigger storage.
// where its trigger is saved.
type Groups interface { type Groups interface {
Group(ctx context.Context, id uuid.UUID) (events.Group, bool, error) Group(ctx context.Context, id uuid.UUID) (events.Group, bool, error)
GroupEvents(ctx context.Context, id uuid.UUID, limit int) ([]events.Stored, error) GroupEvents(ctx context.Context, id uuid.UUID, limit int) ([]events.Stored, error)
@@ -40,7 +38,7 @@ type Groups interface {
SaveTrigger(ctx context.Context, t events.TriggerSpec) error SaveTrigger(ctx context.Context, t events.TriggerSpec) error
} }
// Workflows stores workflow documents and runs them dry. // Workflows installs workflow documents and manages dry runs.
type Workflows interface { type Workflows interface {
Install(ctx context.Context, orgID, name, body, by string) (int, error) Install(ctx context.Context, orgID, name, body, by string) (int, error)
Has(ctx context.Context, orgID, name string) (bool, error) Has(ctx context.Context, orgID, name string) (bool, error)
@@ -48,7 +46,8 @@ type Workflows interface {
DryReport(ctx context.Context, orgID string, id uuid.UUID) (runs.DryReport, bool, error) DryReport(ctx context.Context, orgID string, id uuid.UUID) (runs.DryReport, bool, error)
} }
// Policies checks a draft's policy against the set in force and adds it. // Policies validates a draft's policy against the current policy set and
// adds it when the draft is published.
type Policies interface { type Policies interface {
Check(ctx context.Context, kind, extra string) error Check(ctx context.Context, kind, extra string) error
Append(ctx context.Context, kind, extra, by string) (judgement.PolicySetView, error) Append(ctx context.Context, kind, extra, by string) (judgement.PolicySetView, error)
@@ -90,7 +89,7 @@ func (m *Module) Register(api huma.API) {
}, m.edit) }, m.edit)
huma.Register(api, huma.Operation{ huma.Register(api, huma.Operation{
OperationID: "dry-run-draft", Method: http.MethodPost, Path: "/api/drafts/{id}/dry-run", OperationID: "dry-run-draft", Method: http.MethodPost, Path: "/api/drafts/{id}/dry-run",
Summary: "Replay one of the group's events through the draft, changing nothing", Tags: tags, Summary: "Replay a stored event against the draft workflow and policy in a dry run", Tags: tags,
}, m.dryRun) }, m.dryRun)
huma.Register(api, huma.Operation{ huma.Register(api, huma.Operation{
OperationID: "publish-draft", Method: http.MethodPost, Path: "/api/drafts/{id}/publish", OperationID: "publish-draft", Method: http.MethodPost, Path: "/api/drafts/{id}/publish",
@@ -102,7 +101,7 @@ type idInput struct {
ID string `path:"id" format:"uuid"` ID string `path:"id" format:"uuid"`
} }
// View is a draft as the API returns it. // View is the API representation of a draft.
type View struct { type View struct {
ID uuid.UUID `json:"id"` ID uuid.UUID `json:"id"`
GroupID uuid.UUID `json:"group_id"` GroupID uuid.UUID `json:"group_id"`
@@ -114,7 +113,7 @@ type View struct {
// Policy is Cedar policy text added to the set in force when published. // Policy is Cedar policy text added to the set in force when published.
Policy string `json:"policy"` Policy string `json:"policy"`
Summary string `json:"summary"` Summary string `json:"summary"`
// DryRun is the last dry run of the draft as it stands. // DryRun reports the latest dry run since the draft was last edited.
DryRun *runs.DryReport `json:"dry_run,omitzero"` DryRun *runs.DryReport `json:"dry_run,omitzero"`
DryEventID *uuid.UUID `json:"dry_event_id,omitzero"` DryEventID *uuid.UUID `json:"dry_event_id,omitzero"`
PublishedAt *time.Time `json:"published_at,omitzero"` PublishedAt *time.Time `json:"published_at,omitzero"`
@@ -159,8 +158,6 @@ var (
policyKinds = map[string]string{judgement.KindHardRules: "hard rule", judgement.KindChangeRequest: "change request rule"} policyKinds = map[string]string{judgement.KindHardRules: "hard rule", judgement.KindChangeRequest: "change request rule"}
) )
// summarize says in plain language when a draft fires and what it does. It is
// built from the draft's own fields, so it can't disagree with them.
func summarize(d store.Draft) string { func summarize(d store.Draft) string {
var filter map[string]string var filter map[string]string
_ = json.Unmarshal(d.Filter, &filter) _ = json.Unmarshal(d.Filter, &filter)
@@ -197,7 +194,8 @@ func summarize(d store.Draft) string {
return b.String() return b.String()
} }
// defaultName is a trigger name that is valid and tells groups apart. // defaultName uses part of the group ID to distinguish groups with the same
// source and event type.
func defaultName(g events.Group) string { func defaultName(g events.Group) string {
slug := strings.Trim(nameChars.ReplaceAllString(strings.ToLower(g.Source+"-"+g.EventType), "-"), "-") slug := strings.Trim(nameChars.ReplaceAllString(strings.ToLower(g.Source+"-"+g.EventType), "-"), "-")
if len(slug) > 50 { if len(slug) > 50 {
@@ -222,12 +220,12 @@ func (m *Module) list(ctx context.Context, _ *struct{}) (*httpapi.Reply[[]View],
return httpapi.OK(out), nil return httpapi.OK(out), nil
} }
// create makes a group's draft, or returns the one it has. A new draft // create reuses an existing group draft rather than replacing any edits
// proposes the group's trigger and a copy of the investigate workflow. // with the default investigation workflow.
func (m *Module) create(ctx context.Context, in *idInput) (*httpapi.Reply[View], error) { func (m *Module) create(ctx context.Context, in *idInput) (*httpapi.Reply[View], error) {
id, err := uuid.Parse(in.ID) id, err := uuid.Parse(in.ID)
if err != nil { if err != nil {
return nil, huma.Error400BadRequest("an id is a UUID") return nil, huma.Error400BadRequest("ID must be a UUID")
} }
g, found, err := m.groups.Group(ctx, id) g, found, err := m.groups.Group(ctx, id)
switch { switch {
@@ -268,8 +266,6 @@ type editInput struct {
} }
} }
// edit replaces a draft's name, workflow and policy after checking them. What
// doesn't validate changes nothing.
func (m *Module) edit(ctx context.Context, in *editInput) (*httpapi.Reply[View], error) { func (m *Module) edit(ctx context.Context, in *editInput) (*httpapi.Reply[View], error) {
d, err := m.draft(ctx, in.ID) d, err := m.draft(ctx, in.ID)
if err != nil { if err != nil {
@@ -295,7 +291,6 @@ func (m *Module) edit(ctx context.Context, in *editInput) (*httpapi.Reply[View],
return m.respond(ctx, d) return m.respond(ctx, d)
} }
// check validates what a draft would put in force.
func (m *Module) check(ctx context.Context, name, document, policyKind, policy string) error { func (m *Module) check(ctx context.Context, name, document, policyKind, policy string) error {
if !validName.MatchString(name) { if !validName.MatchString(name) {
return &runs.InvalidError{Problems: []runs.Problem{{Path: "name", Message: "lowercase letters, digits and hyphens, starting with a letter"}}} return &runs.InvalidError{Problems: []runs.Problem{{Path: "name", Message: "lowercase letters, digits and hyphens, starting with a letter"}}}
@@ -331,8 +326,8 @@ type dryRunInput struct {
} }
} }
// dryRun replays one of the group's stored events through the draft's workflow // dryRun tests the draft workflow and policy against a stored event. If the
// in dry mode: the newest by default. // caller omits the event ID, it replays the most recently received event.
func (m *Module) dryRun(ctx context.Context, in *dryRunInput) (*httpapi.Reply[View], error) { func (m *Module) dryRun(ctx context.Context, in *dryRunInput) (*httpapi.Reply[View], error) {
d, err := m.draft(ctx, in.ID) d, err := m.draft(ctx, in.ID)
if err != nil { if err != nil {
@@ -372,7 +367,7 @@ func (m *Module) dryRun(ctx context.Context, in *dryRunInput) (*httpapi.Reply[Vi
return m.respond(ctx, d) return m.respond(ctx, d)
} }
// pick returns the event asked for, or the newest when none is. // pick expects events in newest-first order so a missing ID selects the newest.
func pick(stored []events.Stored, id uuid.UUID) (events.Stored, bool) { func pick(stored []events.Stored, id uuid.UUID) (events.Stored, bool) {
for _, e := range stored { for _, e := range stored {
if id == uuid.Nil || e.ID == id { if id == uuid.Nil || e.ID == id {
@@ -382,10 +377,10 @@ func pick(stored []events.Stored, id uuid.UUID) (events.Stored, bool) {
return events.Stored{}, false return events.Stored{}, false
} }
// publish puts a draft in force: its policy is added to the set, its workflow // publish installs the policy and workflow before saving the trigger so the
// is installed as the next version, and last its trigger is saved, so nothing // trigger cannot fire before both are available. A recorded workflow version
// fires before the rules that govern it exist. A retry after a failure carries // lets a retry skip the name-conflict check. The retry still calls the policy
// on from where it stopped. // and workflow installers, which avoid duplicating unchanged content.
func (m *Module) publish(ctx context.Context, in *idInput) (*httpapi.Reply[View], error) { func (m *Module) publish(ctx context.Context, in *idInput) (*httpapi.Reply[View], error) {
d, err := m.draft(ctx, in.ID) d, err := m.draft(ctx, in.ID)
if err != nil { if err != nil {
@@ -438,7 +433,7 @@ func (m *Module) publish(ctx context.Context, in *idInput) (*httpapi.Reply[View]
func (m *Module) draft(ctx context.Context, rawID string) (store.Draft, error) { func (m *Module) draft(ctx context.Context, rawID string) (store.Draft, error) {
id, err := uuid.Parse(rawID) id, err := uuid.Parse(rawID)
if err != nil { if err != nil {
return store.Draft{}, huma.Error400BadRequest("an id is a UUID") return store.Draft{}, huma.Error400BadRequest("ID must be a UUID")
} }
d, err := m.store.ByID(ctx, m.orgID, id) d, err := m.store.ByID(ctx, m.orgID, id)
switch { switch {
+9 -9
View File
@@ -17,7 +17,7 @@ import (
// ErrNotFound means no such draft. // ErrNotFound means no such draft.
var ErrNotFound = errors.New("no such draft") var ErrNotFound = errors.New("no such draft")
// ErrTaken means another draft already has that name or that group. // ErrTaken indicates that another draft already uses the name.
var ErrTaken = errors.New("name already used by another draft") var ErrTaken = errors.New("name already used by another draft")
// Draft is one stored draft. // Draft is one stored draft.
@@ -34,7 +34,8 @@ type Draft struct {
Policy string `db:"policy"` Policy string `db:"policy"`
DryRunID uuid.NullUUID `db:"dry_run_id"` DryRunID uuid.NullUUID `db:"dry_run_id"`
DryEventID uuid.NullUUID `db:"dry_event_id"` DryEventID uuid.NullUUID `db:"dry_event_id"`
// InstalledVersion is the workflow version a publish installed, once one did. // InstalledVersion is recorded before the trigger is saved so a retry
// can distinguish an earlier installation from a workflow name conflict.
InstalledVersion sql.NullInt32 `db:"installed_version"` InstalledVersion sql.NullInt32 `db:"installed_version"`
PublishedAt sql.NullTime `db:"published_at"` PublishedAt sql.NullTime `db:"published_at"`
CreatedAt time.Time `db:"created_at"` CreatedAt time.Time `db:"created_at"`
@@ -52,8 +53,7 @@ type Store struct {
// New returns a store on db. // New returns a store on db.
func New(db *sqlx.DB) *Store { return &Store{db: db} } func New(db *sqlx.DB) *Store { return &Store{db: db} }
// Create stores d unless its group already has a draft, and returns the draft // Create inserts a draft or returns the existing draft for the group.
// the group has.
func (s *Store) Create(ctx context.Context, d Draft) (Draft, error) { func (s *Store) Create(ctx context.Context, d Draft) (Draft, error) {
_, err := s.db.ExecContext(ctx, ` _, err := s.db.ExecContext(ctx, `
INSERT INTO drafts.drafts (id, org_id, group_id, name, source, event_type, filter, document, policy_kind, policy) INSERT INTO drafts.drafts (id, org_id, group_id, name, source, event_type, filter, document, policy_kind, policy)
@@ -98,8 +98,8 @@ func (s *Store) List(ctx context.Context, orgID string) ([]Draft, error) {
return out, nil return out, nil
} }
// Edit replaces what a person edits of an unpublished draft. A dry run made of // Edit updates an unpublished draft and clears its dry-run references because
// an earlier version no longer describes it, so it is cleared. // the previous run no longer represents the current draft.
func (s *Store) Edit(ctx context.Context, orgID string, id uuid.UUID, name, document, policyKind, policy string) error { func (s *Store) Edit(ctx context.Context, orgID string, id uuid.UUID, name, document, policyKind, policy string) error {
res, err := s.db.ExecContext(ctx, ` res, err := s.db.ExecContext(ctx, `
UPDATE drafts.drafts UPDATE drafts.drafts
@@ -118,7 +118,7 @@ func (s *Store) Edit(ctx context.Context, orgID string, id uuid.UUID, name, docu
return nil return nil
} }
// SetDryRun records the dry run last made of a draft and the event it replayed. // SetDryRun records the latest dry run and the event it replayed.
func (s *Store) SetDryRun(ctx context.Context, orgID string, id, runID, eventID uuid.UUID) error { func (s *Store) SetDryRun(ctx context.Context, orgID string, id, runID, eventID uuid.UUID) error {
if _, err := s.db.ExecContext(ctx, ` if _, err := s.db.ExecContext(ctx, `
UPDATE drafts.drafts SET dry_run_id = $3, dry_event_id = $4, updated_at = now() UPDATE drafts.drafts SET dry_run_id = $3, dry_event_id = $4, updated_at = now()
@@ -128,7 +128,7 @@ func (s *Store) SetDryRun(ctx context.Context, orgID string, id, runID, eventID
return nil return nil
} }
// MarkInstalled records the workflow version a publish installed. // MarkInstalled records the workflow version installed during publication.
func (s *Store) MarkInstalled(ctx context.Context, orgID string, id uuid.UUID, version int) error { func (s *Store) MarkInstalled(ctx context.Context, orgID string, id uuid.UUID, version int) error {
if _, err := s.db.ExecContext(ctx, ` if _, err := s.db.ExecContext(ctx, `
UPDATE drafts.drafts SET installed_version = $3, updated_at = now() WHERE org_id = $1 AND id = $2`, UPDATE drafts.drafts SET installed_version = $3, updated_at = now() WHERE org_id = $1 AND id = $2`,
@@ -138,7 +138,7 @@ func (s *Store) MarkInstalled(ctx context.Context, orgID string, id uuid.UUID, v
return nil return nil
} }
// MarkPublished records that a draft is in force. // MarkPublished records the publication time without overwriting it on retry.
func (s *Store) MarkPublished(ctx context.Context, orgID string, id uuid.UUID) error { func (s *Store) MarkPublished(ctx context.Context, orgID string, id uuid.UUID) error {
if _, err := s.db.ExecContext(ctx, ` if _, err := s.db.ExecContext(ctx, `
UPDATE drafts.drafts SET published_at = COALESCE(published_at, now()), updated_at = now() UPDATE drafts.drafts SET published_at = COALESCE(published_at, now()), updated_at = now()
+2 -1
View File
@@ -53,7 +53,8 @@ type Event struct {
Own bool `db:"own"` Own bool `db:"own"`
OriginRunID uuid.NullUUID `db:"origin_run_id"` OriginRunID uuid.NullUUID `db:"origin_run_id"`
GroupKey sql.NullString `db:"group_key"` GroupKey sql.NullString `db:"group_key"`
GroupFilter jsontext.Value `db:"group_filter"` // Scan into []byte to preserve SQL NULL for events with no group.
GroupFilter []byte `db:"group_filter"`
} }
// Trigger starts a workflow for events of one type from one source whose // Trigger starts a workflow for events of one type from one source whose
+77 -8
View File
@@ -13,7 +13,9 @@ import (
"log/slog" "log/slog"
"net/http" "net/http"
"net/url" "net/url"
"regexp"
"slices" "slices"
"strings"
"time" "time"
"github.com/danielgtaylor/huma/v2" "github.com/danielgtaylor/huma/v2"
@@ -29,7 +31,27 @@ import (
// is no built-in default. // is no built-in default.
var ErrNoAgentModel = errors.New("no agent model is set for the organisation") var ErrNoAgentModel = errors.New("no agent model is set for the organisation")
const roleAgent = "agent" const (
roleAgent = "agent"
agentAliasPrefix = "agent:"
)
var agentAliasPattern = regexp.MustCompile(`^[a-zA-Z0-9][a-zA-Z0-9_.-]{0,62}$`)
// ValidateAgentModelAlias accepts an empty alias for the default model.
func ValidateAgentModelAlias(alias string) error {
if alias != "" && !agentAliasPattern.MatchString(alias) {
return fmt.Errorf("invalid agent model alias %q: use 1-63 letters, digits, dots, underscores or hyphens, starting with a letter or digit", alias)
}
return nil
}
func agentModelRole(alias string) string {
if alias == "" || alias == "default" {
return roleAgent
}
return agentAliasPrefix + alias
}
// DefaultApprovalDeadline is how long an approval request waits for an answer // DefaultApprovalDeadline is how long an approval request waits for an answer
// when the organisation hasn't said. // when the organisation hasn't said.
@@ -247,11 +269,23 @@ func (m *Module) UseCredentials(c Credentials) { m.credentials = c }
// AgentModel returns the organisation's agent model. // AgentModel returns the organisation's agent model.
func (m *Module) AgentModel(ctx context.Context) (Model, error) { func (m *Module) AgentModel(ctx context.Context) (Model, error) {
role, ok, err := m.store.ModelRole(ctx, m.orgID, roleAgent) return m.AgentModelForAlias(ctx, "")
}
// AgentModelForAlias resolves a model without falling back for unknown aliases.
func (m *Module) AgentModelForAlias(ctx context.Context, alias string) (Model, error) {
if err := ValidateAgentModelAlias(alias); err != nil {
return Model{}, err
}
key := agentModelRole(alias)
role, ok, err := m.store.ModelRole(ctx, m.orgID, key)
if err != nil { if err != nil {
return Model{}, err return Model{}, err
} }
if !ok { if !ok {
if key != roleAgent {
return Model{}, fmt.Errorf("agent model alias %q: %w", alias, ErrNoAgentModel)
}
return Model{}, ErrNoAgentModel return Model{}, ErrNoAgentModel
} }
return Model{Class: role.Class, BaseURL: role.BaseURL, Model: role.Model, APIKeyCredential: role.APIKeyCredential}, nil return Model{Class: role.Class, BaseURL: role.BaseURL, Model: role.Model, APIKeyCredential: role.APIKeyCredential}, nil
@@ -355,6 +389,10 @@ func (m *Module) Register(api huma.API) {
OperationID: "put-settings", Method: http.MethodPut, Path: "/api/settings", OperationID: "put-settings", Method: http.MethodPut, Path: "/api/settings",
Summary: "Change the organisation settings", Tags: tags, Summary: "Change the organisation settings", Tags: tags,
}, m.putSettings) }, m.putSettings)
huma.Register(api, huma.Operation{
OperationID: "list-agent-models", Method: http.MethodGet, Path: "/api/settings/agent-models",
Summary: "List agent models by alias", Tags: tags,
}, m.listAgentModels)
huma.Register(api, huma.Operation{ huma.Register(api, huma.Operation{
OperationID: "get-agent-model", Method: http.MethodGet, Path: "/api/settings/agent-model", OperationID: "get-agent-model", Method: http.MethodGet, Path: "/api/settings/agent-model",
Summary: "Get the agent model", Tags: tags, Summary: "Get the agent model", Tags: tags,
@@ -495,8 +533,32 @@ func (s Settings) knows(people []store.Person) error {
return nil return nil
} }
func (m *Module) getAgentModel(ctx context.Context, _ *struct{}) (*httpapi.Reply[Model], error) { func (m *Module) listAgentModels(ctx context.Context, _ *struct{}) (*httpapi.Reply[map[string]Model], error) {
model, err := m.AgentModel(ctx) rows, err := m.store.AgentModelRoles(ctx, m.orgID)
if err != nil {
m.log.ErrorContext(ctx, "list agent models", "error", err)
return nil, huma.NewError(http.StatusInternalServerError, "couldn't list agent models")
}
out := make(map[string]Model, len(rows))
for _, row := range rows {
alias := strings.TrimPrefix(row.Role, agentAliasPrefix)
if row.Role == roleAgent {
alias = "default"
}
out[alias] = Model{Class: row.Class, BaseURL: row.BaseURL, Model: row.Model, APIKeyCredential: row.APIKeyCredential}
}
return httpapi.OK(out), nil
}
type agentModelAlias struct {
Alias string `query:"alias" doc:"Agent model alias; omit for the default model"`
}
func (m *Module) getAgentModel(ctx context.Context, in *agentModelAlias) (*httpapi.Reply[Model], error) {
if err := ValidateAgentModelAlias(in.Alias); err != nil {
return nil, huma.NewError(http.StatusBadRequest, err.Error())
}
model, err := m.AgentModelForAlias(ctx, in.Alias)
switch { switch {
case errors.Is(err, ErrNoAgentModel): case errors.Is(err, ErrNoAgentModel):
return nil, huma.NewError(http.StatusNotFound, err.Error()) return nil, huma.NewError(http.StatusNotFound, err.Error())
@@ -508,9 +570,16 @@ func (m *Module) getAgentModel(ctx context.Context, _ *struct{}) (*httpapi.Reply
} }
} }
// putAgentModel sets the agent model. An empty base URL takes the class's type agentModelInput struct {
// published default, and the stored value is always explicit. Alias string `query:"alias" doc:"Agent model alias; omit for the default model"`
func (m *Module) putAgentModel(ctx context.Context, in *struct{ Body Model }) (*httpapi.Reply[Model], error) { Body Model
}
// putAgentModel stores the resolved base URL so saved settings are explicit.
func (m *Module) putAgentModel(ctx context.Context, in *agentModelInput) (*httpapi.Reply[Model], error) {
if err := ValidateAgentModelAlias(in.Alias); err != nil {
return nil, huma.NewError(http.StatusBadRequest, err.Error())
}
req := in.Body req := in.Body
model, err := settle(req) model, err := settle(req)
if err != nil { if err != nil {
@@ -520,7 +589,7 @@ func (m *Module) putAgentModel(ctx context.Context, in *struct{ Body Model }) (*
return nil, huma.NewError(http.StatusBadRequest, err.Error()) return nil, huma.NewError(http.StatusBadRequest, err.Error())
} }
if err := m.store.PutModelRole(ctx, store.ModelRole{ if err := m.store.PutModelRole(ctx, store.ModelRole{
OrgID: m.orgID, Role: roleAgent, Class: model.Class, BaseURL: model.BaseURL, Model: model.Model, OrgID: m.orgID, Role: agentModelRole(in.Alias), Class: model.Class, BaseURL: model.BaseURL, Model: model.Model,
APIKeyCredential: model.APIKeyCredential, APIKeyCredential: model.APIKeyCredential,
}); err != nil { }); err != nil {
m.log.ErrorContext(ctx, "put agent model", "error", err) m.log.ErrorContext(ctx, "put agent model", "error", err)
@@ -47,6 +47,17 @@ func (s *Store) ModelRole(ctx context.Context, orgID, role string) (ModelRole, b
return out, true, nil return out, true, nil
} }
func (s *Store) AgentModelRoles(ctx context.Context, orgID string) ([]ModelRole, error) {
var out []ModelRole
if err := s.db.SelectContext(ctx, &out, `
SELECT org_id, role, class, base_url, model, api_key_credential
FROM governance.model_roles
WHERE org_id = $1 AND (role = 'agent' OR role LIKE 'agent:%')`, orgID); err != nil {
return nil, fmt.Errorf("list agent models: %w", err)
}
return out, nil
}
// PutModelRole records the organisation's model for a role. // PutModelRole records the organisation's model for a role.
func (s *Store) PutModelRole(ctx context.Context, m ModelRole) error { func (s *Store) PutModelRole(ctx context.Context, m ModelRole) error {
if _, err := s.db.NamedExecContext(ctx, ` if _, err := s.db.NamedExecContext(ctx, `
+8 -9
View File
@@ -1,5 +1,4 @@
// Package store holds the memory module's SQL: incidents and the proposals // Package store persists incident history and proposals for root-cause fixes.
// raised from them.
package store package store
import ( import (
@@ -11,7 +10,7 @@ import (
"github.com/jmoiron/sqlx" "github.com/jmoiron/sqlx"
) )
// Incident is one investigation of one target as stored. // Incident is the stored record of a run's investigation.
type Incident struct { type Incident struct {
ID uuid.UUID `db:"id"` ID uuid.UUID `db:"id"`
RunID uuid.UUID `db:"run_id"` RunID uuid.UUID `db:"run_id"`
@@ -24,7 +23,7 @@ type Incident struct {
At time.Time `db:"at"` At time.Time `db:"at"`
} }
// Proposal is a root-cause fix asked for on a target. // Proposal is a request to fix a recurring cause on a target.
type Proposal struct { type Proposal struct {
ID uuid.UUID `db:"id"` ID uuid.UUID `db:"id"`
TargetKind string `db:"target_kind"` TargetKind string `db:"target_kind"`
@@ -42,8 +41,8 @@ type Store struct {
// New returns a store on db. // New returns a store on db.
func New(db *sqlx.DB) *Store { return &Store{db: db} } func New(db *sqlx.DB) *Store { return &Store{db: db} }
// Upsert records the incident of a run, replacing what an earlier attempt of the // Upsert inserts an incident or updates the target, cause and summary for
// same run recorded. // the same organisation and run. It preserves the original event and timestamp.
func (s *Store) Upsert(ctx context.Context, orgID string, in Incident) error { func (s *Store) Upsert(ctx context.Context, orgID string, in Incident) error {
if _, err := s.db.ExecContext(ctx, ` if _, err := s.db.ExecContext(ctx, `
INSERT INTO memory.incidents (id, org_id, run_id, target_kind, target_id, cause, summary, event) INSERT INTO memory.incidents (id, org_id, run_id, target_kind, target_id, cause, summary, event)
@@ -57,7 +56,7 @@ func (s *Store) Upsert(ctx context.Context, orgID string, in Incident) error {
return nil return nil
} }
// SetActions records what was done in a run's incident. // SetActions replaces the recorded action outcomes for a run's incident.
func (s *Store) SetActions(ctx context.Context, orgID string, runID uuid.UUID, actions []byte) error { func (s *Store) SetActions(ctx context.Context, orgID string, runID uuid.UUID, actions []byte) error {
if _, err := s.db.ExecContext(ctx, ` if _, err := s.db.ExecContext(ctx, `
UPDATE memory.incidents SET actions = $3 WHERE org_id = $1 AND run_id = $2`, UPDATE memory.incidents SET actions = $3 WHERE org_id = $1 AND run_id = $2`,
@@ -93,8 +92,8 @@ func (s *Store) ByTarget(ctx context.Context, orgID, kind, id string, limit int)
return out, nil return out, nil
} }
// Propose records p unless the target and cause already have one, and returns // Propose stores one proposal per organisation, target and cause. If one
// the one that stands. // already exists, it updates the incident count and returns the original text.
func (s *Store) Propose(ctx context.Context, orgID string, p Proposal) (Proposal, error) { func (s *Store) Propose(ctx context.Context, orgID string, p Proposal) (Proposal, error) {
var out Proposal var out Proposal
if err := s.db.GetContext(ctx, &out, ` if err := s.db.GetContext(ctx, &out, `
+25 -28
View File
@@ -1,7 +1,6 @@
// Package memory is what Archie remembers about a target: each incident // Package memory records investigated incidents by target, including their
// investigated on it, the cause found, and what was done about it. A cause that // causes and action outcomes. When a cause reaches the recurrence threshold
// keeps coming back on a target, whatever became of each attempt to handle it, // for a target, the module proposes a root-cause fix regardless of action outcomes.
// raises a proposal for a root-cause fix.
package memory package memory
import ( import (
@@ -28,17 +27,17 @@ const maxHistory = 200
// MaxRecurrence is the largest recurrence threshold the history can confirm. // MaxRecurrence is the largest recurrence threshold the history can confirm.
const MaxRecurrence = 100 const MaxRecurrence = 100
// Target is what an incident happened to: a kind and an id, such as host web-1. // Target identifies the affected resource by kind and ID, such as host web-1.
type Target struct { type Target struct {
Kind string `json:"kind"` Kind string `json:"kind"`
ID string `json:"id"` ID string `json:"id"`
} }
// Action is something done during an incident and how it ended. // Action records an action considered during an incident and its outcome.
type Action struct { type Action struct {
Action string `json:"action"` Action string `json:"action"`
Target string `json:"target"` Target string `json:"target"`
// State is what became of it: ran, refused, or the approval's state. // State records whether the action ran, was refused or has an approval status.
State string `json:"state"` State string `json:"state"`
Detail string `json:"detail,omitzero"` Detail string `json:"detail,omitzero"`
} }
@@ -51,7 +50,7 @@ type Incident struct {
Actions []Action `json:"actions"` Actions []Action `json:"actions"`
} }
// Line is the incident as one entry of a list an agent reads. // Line formats the incident as one entry in the history shown to the agent.
func (i Incident) Line() string { func (i Incident) Line() string {
line := fmt.Sprintf("- %s, cause %q: %s", i.At.Format("2006-01-02"), i.Cause, i.Summary) line := fmt.Sprintf("- %s, cause %q: %s", i.At.Format("2006-01-02"), i.Cause, i.Summary)
if len(i.Actions) == 0 { if len(i.Actions) == 0 {
@@ -68,17 +67,16 @@ func (i Incident) Line() string {
return line + " Actions: " + strings.Join(parts, "; ") + "." return line + " Actions: " + strings.Join(parts, "; ") + "."
} }
// Review is what recording a run's actions found about its cause. // Review reports how often the cause occurred and any proposal for a fix.
type Review struct { type Review struct {
// Repeats is how many incidents on the target have this cause, this one // Repeats counts matching incidents in the target's recent history,
// included. // including the current incident if it is in that history.
Repeats int Repeats int
// Proposal is the root-cause fix asked for, empty until the cause has // Proposal is the text of the request for a root-cause fix. It is empty
// recurred enough. // below the recurrence threshold.
Proposal string Proposal string
} }
// ledger is where incidents and proposals are kept.
type ledger interface { type ledger interface {
Upsert(ctx context.Context, orgID string, in store.Incident) error Upsert(ctx context.Context, orgID string, in store.Incident) error
SetActions(ctx context.Context, orgID string, runID uuid.UUID, actions []byte) error SetActions(ctx context.Context, orgID string, runID uuid.UUID, actions []byte) error
@@ -87,7 +85,7 @@ type ledger interface {
Propose(ctx context.Context, orgID string, p store.Proposal) (store.Proposal, error) Propose(ctx context.Context, orgID string, p store.Proposal) (store.Proposal, error)
} }
// Module remembers one organisation's incidents. // Module manages incident history and proposals for one organisation.
type Module struct { type Module struct {
orgID string orgID string
ledger ledger ledger ledger
@@ -100,14 +98,14 @@ func NewModule(db *sqlx.DB, orgID string) *Module {
var unsafeCause = regexp.MustCompile(`[^a-z0-9]+`) var unsafeCause = regexp.MustCompile(`[^a-z0-9]+`)
// Cause is a cause as it is compared: lower case words joined by hyphens, so // Cause normalises labels for comparison: "Disk pressure" and "disk-pressure"
// "Disk pressure" and "disk-pressure" are one cause. // both produce "disk-pressure".
func Cause(s string) string { func Cause(s string) string {
return strings.Trim(unsafeCause.ReplaceAllString(strings.ToLower(s), "-"), "-") return strings.Trim(unsafeCause.ReplaceAllString(strings.ToLower(s), "-"), "-")
} }
// Record remembers what a run's investigation found: the event, the target it // Record saves the incident for a run. Recording it again updates the target,
// concerned and the cause. Recording again replaces the earlier attempt's. // cause and summary without replacing the original event.
func (m *Module) Record(ctx context.Context, runID uuid.UUID, event jsontext.Value, t Target, cause, summary string) error { func (m *Module) Record(ctx context.Context, runID uuid.UUID, event jsontext.Value, t Target, cause, summary string) error {
t = Target{Kind: strings.TrimSpace(t.Kind), ID: strings.TrimSpace(t.ID)} t = Target{Kind: strings.TrimSpace(t.Kind), ID: strings.TrimSpace(t.ID)}
cause = Cause(cause) cause = Cause(cause)
@@ -123,7 +121,7 @@ func (m *Module) Record(ctx context.Context, runID uuid.UUID, event jsontext.Val
}) })
} }
// Past returns the incidents recorded on t before the run's own, newest first. // Past returns recent incidents for t, newest first, excluding the current run.
func (m *Module) Past(ctx context.Context, runID uuid.UUID, t Target) ([]Incident, error) { func (m *Module) Past(ctx context.Context, runID uuid.UUID, t Target) ([]Incident, error) {
rows, err := m.ledger.ByTarget(ctx, m.orgID, strings.TrimSpace(t.Kind), strings.TrimSpace(t.ID), maxHistory) rows, err := m.ledger.ByTarget(ctx, m.orgID, strings.TrimSpace(t.Kind), strings.TrimSpace(t.ID), maxHistory)
if err != nil { if err != nil {
@@ -143,10 +141,9 @@ func (m *Module) Past(ctx context.Context, runID uuid.UUID, t Target) ([]Inciden
return out, nil return out, nil
} }
// Finish remembers what was done in a run's incident and checks whether its // Finish records action outcomes. It requests a root-cause fix if at least
// cause has come back enough to ask for a root-cause fix: that is when // threshold incidents in the target's recent history share the current cause,
// threshold incidents on the target share the cause, whatever their outcomes. // regardless of their action outcomes. A run with no recorded incident is ignored.
// A run that recorded no incident has nothing to finish.
func (m *Module) Finish(ctx context.Context, runID uuid.UUID, actions []Action, threshold int) (Review, error) { func (m *Module) Finish(ctx context.Context, runID uuid.UUID, actions []Action, threshold int) (Review, error) {
current, ok, err := m.ledger.Incident(ctx, m.orgID, runID) current, ok, err := m.ledger.Incident(ctx, m.orgID, runID)
if err != nil || !ok { if err != nil || !ok {
@@ -194,8 +191,8 @@ func incident(r store.Incident) (Incident, error) {
return out, nil return out, nil
} }
// proposalBody asks for the cause to be fixed rather than handled again. same // proposalBody expects matching incidents in newest-first order so it can
// is newest first. // report the date of the oldest match.
func proposalBody(current store.Incident, same []store.Incident) string { func proposalBody(current store.Incident, same []store.Incident) string {
var tried []string var tried []string
for _, r := range same { for _, r := range same {
@@ -209,10 +206,10 @@ func proposalBody(current store.Incident, same []store.Incident) string {
} }
} }
} }
body := fmt.Sprintf("%q has been the cause of %d incidents on %s %s since %s. Handling each one has not stopped it, so find what keeps producing it and fix that.", body := fmt.Sprintf("%q caused %d recorded incidents on %s %s since %s. Identify and fix the underlying problem.",
current.Cause, len(same), current.TargetKind, current.TargetID, same[len(same)-1].At.Format("2006-01-02")) current.Cause, len(same), current.TargetKind, current.TargetID, same[len(same)-1].At.Format("2006-01-02"))
if len(tried) > 0 { if len(tried) > 0 {
body += " Handled so far with: " + strings.Join(tried, "; ") + "." body += " Recorded actions: " + strings.Join(tried, "; ") + "."
} }
return body return body
} }
+4 -5
View File
@@ -38,9 +38,8 @@ func (f *fakeLedger) Propose(_ context.Context, _ string, p store.Proposal) (sto
return p, nil return p, nil
} }
// TestFinishProposesOnRecurrence guards the rule that a cause seen threshold // TestFinishProposesOnRecurrence checks that only incidents with the same
// times on a target raises a root-cause fix, whatever happened to the actions // cause count towards the configured threshold, even if an action was denied.
// taken in each incident, and that other causes don't count towards it.
func TestFinishProposesOnRecurrence(t *testing.T) { func TestFinishProposesOnRecurrence(t *testing.T) {
now := time.Date(2026, 11, 16, 0, 0, 0, 0, time.UTC) now := time.Date(2026, 11, 16, 0, 0, 0, 0, time.UTC)
run := uuid.New() run := uuid.New()
@@ -60,8 +59,8 @@ func TestFinishProposesOnRecurrence(t *testing.T) {
{"one short of the threshold", incidents("disk-pressure", "disk-pressure", "disk-pressure", "disk-pressure"), 5, false}, {"one short of the threshold", incidents("disk-pressure", "disk-pressure", "disk-pressure", "disk-pressure"), 5, false},
{"the threshold is met by this incident", incidents("disk-pressure", "disk-pressure", "disk-pressure", "disk-pressure", "disk-pressure"), 5, true}, {"the threshold is met by this incident", incidents("disk-pressure", "disk-pressure", "disk-pressure", "disk-pressure", "disk-pressure"), 5, true},
{"other causes are not counted", incidents("disk-pressure", "oom", "oom", "oom", "oom", "disk-pressure"), 5, false}, {"other causes are not counted", incidents("disk-pressure", "oom", "oom", "oom", "oom", "disk-pressure"), 5, false},
{"the threshold is the organisation's", incidents("disk-pressure", "disk-pressure", "disk-pressure"), 3, true}, {"uses the organisation's threshold", incidents("disk-pressure", "disk-pressure", "disk-pressure"), 3, true},
{"past the threshold still proposes", incidents("disk-pressure", "disk-pressure", "disk-pressure", "disk-pressure", "disk-pressure", "disk-pressure"), 5, true}, {"proposes above the threshold", incidents("disk-pressure", "disk-pressure", "disk-pressure", "disk-pressure", "disk-pressure", "disk-pressure"), 5, true},
} }
for _, tt := range tests { for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) { t.Run(tt.name, func(t *testing.T) {
+34 -1
View File
@@ -2,6 +2,7 @@ package runs
import ( import (
"context" "context"
"encoding/json/jsontext"
"errors" "errors"
"github.com/samcharles93/ai-sdk/agentloop" "github.com/samcharles93/ai-sdk/agentloop"
@@ -22,6 +23,11 @@ type AgentRequest struct {
Prompt string Prompt string
Tools core.ToolSet Tools core.ToolSet
Budget agentloop.Budget Budget agentloop.Budget
// Capture is the name of a tool whose input the loop should keep. The
// input of its last successful call comes back as AgentResult.Returned.
// It is read from the journal, so a resumed run that replays the call
// still has it.
Capture string
} }
// AgentResult is how an agent loop ended. // AgentResult is how an agent loop ended.
@@ -33,6 +39,9 @@ type AgentResult struct {
Steps int `json:"steps"` Steps int `json:"steps"`
ToolCalls int `json:"tool_calls"` ToolCalls int `json:"tool_calls"`
Usage chat.Usage `json:"usage"` Usage chat.Usage `json:"usage"`
// Returned is the input of the agent's last successful call to the tool
// that AgentRequest.Capture names.
Returned jsontext.Value `json:"returned,omitzero"`
} }
// Agent runs a tool-using agent loop whose every model call and tool call is // Agent runs a tool-using agent loop whose every model call and tool call is
@@ -76,6 +85,30 @@ func (rc *Context) Agent(req AgentRequest) (AgentResult, error) {
if err := rc.ctx.Err(); err != nil { if err := rc.ctx.Err(); err != nil {
return out, err return out, err
} }
if req.Capture != "" && out.Completed {
if out.Returned, err = returned(rc.ctx, journal, req.Capture); err != nil {
return out, err
}
}
return out, nil
}
// returned only scans entries consumed by the loop. On replay, the next
// position may already contain the workflow step that follows the loop.
func returned(ctx context.Context, j *Journal[agentloop.Entry], tool string) (jsontext.Value, error) {
var out jsontext.Value
end := int64(j.rc.next - j.base)
for pos := range end {
e, err := j.Lookup(ctx, pos)
switch {
case err != nil:
return nil, err
case e == nil:
return out, nil
case e.Kind == agentloop.EntryTool && e.ToolName == tool && e.Error == "" && !e.Unknown:
out = jsontext.Value(e.Input)
}
}
return out, nil return out, nil
} }
@@ -86,7 +119,7 @@ func retryModel(p chat.Provider) chat.Provider {
return middleware.RetryChat(middleware.RetryConfig{MaxAttempts: 4}, middleware.ExponentialBackoff{}, middleware.DefaultRetryableError)(p) return middleware.RetryChat(middleware.RetryConfig{MaxAttempts: 4}, middleware.ExponentialBackoff{}, middleware.DefaultRetryableError)(p)
} }
// loopJournal is the run journal in the shape the agent loop consults. // loopJournal adapts the run journal for the agent loop.
type loopJournal struct { type loopJournal struct {
*Journal[agentloop.Entry] *Journal[agentloop.Entry]
} }
+108
View File
@@ -0,0 +1,108 @@
package runs
import (
"context"
"encoding/json/jsontext"
json "encoding/json/v2"
"errors"
"fmt"
"strings"
"github.com/google/jsonschema-go/jsonschema"
"github.com/samcharles93/ai-sdk/core"
"github.com/samcharles93/archie-core/modules/connectors"
)
// resultTool is the name of the tool that accepts a structured result.
const resultTool = "return_result"
const resultRule = "Return your result by calling " + resultTool + " exactly once, when you have it."
// resultSchema compiles the step's result schema. Tool parameters must be
// a JSON object.
func (s agentSettings) resultSchema() ([]byte, *jsonschema.Resolved, error) {
// Tool schemas are part of the journaled model request digest.
raw, err := json.Marshal(s.Result, json.Deterministic(true))
if err != nil {
return nil, nil, fmt.Errorf("schema: %w", err)
}
var schema jsonschema.Schema
if err := json.Unmarshal(raw, &schema); err != nil {
return nil, nil, fmt.Errorf("schema: %w", err)
}
if schema.Type != "object" {
return nil, nil, errors.New("a JSON Schema with type object")
}
resolved, err := schema.Resolve(nil)
if err != nil {
return nil, nil, fmt.Errorf("schema: %w", err)
}
return raw, resolved, nil
}
// resultFields are the fields the result schema declares, or nil when it
// declares none, which accepts any field.
func (s agentSettings) resultFields() map[string]bool {
props, _ := s.Result["properties"].(map[string]any)
if len(props) == 0 {
return nil
}
fields := make(map[string]bool, len(props))
for name := range props {
fields[name] = true
}
return fields
}
// system is the part of the agent's system prompt the step adds: its mission,
// its extra rules and, with a result schema, how to return it.
func (s agentSettings) system() string {
parts := []string{s.Mission}
if strings.TrimSpace(s.ExtraRules) != "" {
parts = append(parts, s.ExtraRules)
}
if s.Result != nil {
parts = append(parts, resultRule)
}
return strings.Join(parts, "\n\n")
}
// newResultTool returns validation errors to the agent so it can correct
// its result.
func newResultTool(raw []byte, schema *jsonschema.Resolved) *core.Tool {
return &core.Tool{
Name: resultTool,
Description: "Return the result of this step.",
Parameters: raw,
Execute: func(_ context.Context, input string) (string, error) {
if _, err := decodeResult(jsontext.Value(input), schema); err != nil {
return "", err
}
return "recorded", nil
},
}
}
// decodeResult reads what the agent returned and checks it against the schema.
func decodeResult(raw jsontext.Value, schema *jsonschema.Resolved) (map[string]any, error) {
var out map[string]any
if err := json.Unmarshal(raw, &out); err != nil {
return nil, fmt.Errorf("the result is not a JSON object: %w", err)
}
if err := schema.Validate(out); err != nil {
return nil, fmt.Errorf("the result doesn't match its schema: %w", err)
}
return out, nil
}
// readOnly filters tool declarations to read-only tools.
func readOnly(decls []connectors.Declaration) []connectors.Declaration {
out := make([]connectors.Declaration, 0, len(decls))
for _, d := range decls {
if d.ReadOnly {
out = append(out, d)
}
}
return out
}
+91
View File
@@ -6,6 +6,8 @@ import (
json "encoding/json/v2" json "encoding/json/v2"
"errors" "errors"
"log/slog" "log/slog"
"os"
"slices"
"strings" "strings"
"sync" "sync"
"testing" "testing"
@@ -14,9 +16,98 @@ import (
"github.com/samcharles93/ai-sdk/chat" "github.com/samcharles93/ai-sdk/chat"
"github.com/samcharles93/ai-sdk/core" "github.com/samcharles93/ai-sdk/core"
"github.com/samcharles93/archie-core/modules/governance"
"github.com/samcharles93/archie-core/modules/runs/internal/store" "github.com/samcharles93/archie-core/modules/runs/internal/store"
) )
type triageModel struct {
scriptedModel
models []string
}
func (m *triageModel) Chat(_ context.Context, req chat.Request) (chat.Response, error) {
m.models = append(m.models, req.Model)
if req.Messages[len(req.Messages)-1].Role == chat.RoleTool {
return chat.Response{Role: chat.RoleAssistant, Content: "No change needed.", FinishReason: "stop"}, nil
}
return chat.Response{
Role: chat.RoleAssistant, FinishReason: "tool_calls",
ToolCalls: []chat.ToolCall{{ID: "classification", Name: "return_result", Arguments: `{"needs_code_change":false,"reasons":"Already resolved"}`}},
}, nil
}
type modelSettings struct {
onePersonPath
model *triageModel
name string
}
func (s modelSettings) AgentModelForAlias(_ context.Context, alias string) (governance.Model, error) {
if alias != "fast" {
return governance.Model{}, governance.ErrNoAgentModel
}
return governance.Model{Model: s.name}, nil
}
func (s modelSettings) AgentProvider(context.Context, governance.Model) (chat.Provider, chat.ModelInfo, error) {
return s.model, chat.ModelInfo{}, nil
}
func (modelSettings) AttemptsPerRun(context.Context) (int, error) { return 6, nil }
// TestTriageClassificationUsesPinnedModel checks that a resumed step returns
// the same typed classification even if its model alias now resolves differently.
func TestTriageClassificationUsesPinnedModel(t *testing.T) {
raw, err := os.ReadFile("testdata/corpus/triage.yaml")
if err != nil {
t.Fatal(err)
}
body, _, ok := strings.Cut(string(raw), " - type: forge.comment")
if !ok {
t.Fatal("triage fixture has no forge comment step")
}
body = strings.Replace(body, " read_only: true", " read_only: true\n model: fast", 1)
doc, err := ParseDocument(body)
if err != nil {
t.Fatal(err)
}
engine := newEngine(nil, &fakeWork{}, slog.New(slog.DiscardHandler), Options{})
engine.Use(Deps{Settings: modelSettings{}})
_, err = engine.Install(t.Context(), "org", "triage", strings.Replace(body, "model: fast", "model: missing", 1), "operator")
var invalid *InvalidError
if !errors.As(err, &invalid) || len(invalid.Problems) != 1 || invalid.Problems[0].Path != "steps[0].settings.model" {
t.Fatalf("saving an unknown alias returned %v, want a model setting error", err)
}
run := store.Run{ID: uuid.New()}
work := &fakeWork{}
aliases, withMemory := agentUse(doc)
for _, tt := range []struct {
name string
want []string
}{
{name: "fast-v1", want: []string{"fast-v1", "fast-v1"}},
{name: "fast-v2"},
} {
model := &triageModel{}
deps := Deps{Settings: modelSettings{model: model, name: tt.name}, Toolbox: anyBox{}, Judge: &actionJudge{}}
rc := newContext(t.Context(), work, run, uuid.New(), work.steps)
p := &progress{results: make(map[string]StepResult)}
if err := deps.pin(rc, p, aliases, withMemory); err != nil {
t.Fatal(err)
}
if err := deps.runStep(rc, p, doc.Steps[0], 0); err != nil {
t.Fatal(err)
}
got := p.results["classify"].Result
if got["needs_code_change"] != false || got["reasons"] != "Already resolved" {
t.Fatalf("classification = %#v", got)
}
if !slices.Equal(model.models, tt.want) {
t.Fatalf("model calls = %v, want %v", model.models, tt.want)
}
}
}
// scriptedModel answers by turn: a tool call first, then findings once the // scriptedModel answers by turn: a tool call first, then findings once the
// tool's result is in the history. // tool's result is in the history.
type scriptedModel struct { type scriptedModel struct {
+15 -3
View File
@@ -42,12 +42,24 @@ func (c *checker) step(at string, s Step, mode RepositoryMode, earlier *refScope
c.typed(at, s, mode, earlier) c.typed(at, s, mode, earlier)
} }
if s.ID != "" { if s.ID != "" {
earlier.steps[s.ID] = nil earlier.steps[s.ID] = resultFields(s)
} }
} }
// controls validates the settings every step carries: when, on_failure and // resultFields are the result fields a step's type declares, or nil when it
// retry. // declares none.
func resultFields(s Step) map[string]bool {
if s.Type != typeAgent {
return nil
}
var settings agentSettings
if decodeSettings(s.Settings, &settings) != nil {
return nil
}
return settings.resultFields()
}
// controls validates the common step settings: when, on_failure and retry.
func (c *checker) controls(at string, s Step, earlier *refScope) { func (c *checker) controls(at string, s Step, earlier *refScope) {
if s.OnFailure != "" && s.OnFailure != onFailurePark && s.OnFailure != onFailureContinue { if s.OnFailure != "" && s.OnFailure != onFailurePark && s.OnFailure != onFailureContinue {
c.add(at+".on_failure", "park or continue, not %q", s.OnFailure) c.add(at+".on_failure", "park or continue, not %q", s.OnFailure)
+28 -7
View File
@@ -38,14 +38,14 @@ func TestCorpusChecksAsItsStepTypesLand(t *testing.T) {
}{ }{
{name: "investigate checks", file: "investigate"}, {name: "investigate checks", file: "investigate"},
{ {
name: "feasibility waits for repositories, switch, approve and agent results", file: "feasibility", name: "feasibility waits for repositories, switch and approve", file: "feasibility",
want: slices.Concat(notYet("repo.prepare", "workflow.approve"), agentLater("read_only", "result", "read_only", "result"), want: slices.Concat(notYet("repo.prepare", "workflow.approve"),
[]string{"switch steps are not supported yet"}), []string{"switch steps are not supported yet"}),
}, },
{ {
name: "implement waits for repositories, gates and agent settings", file: "implement", name: "implement waits for repositories and gates", file: "implement",
want: slices.Concat(notYet("repo.prepare", "repo.tooling", "gate.repository", "repo.commit", "repo.open-pr"), want: slices.Concat(notYet("repo.prepare", "repo.tooling", "gate.repository", "repo.commit", "repo.open-pr"),
agentLater("read_only", "gate", "extra_rules")), agentLater("gate")),
}, },
{name: "pr-review waits for review steps", file: "pr-review", want: notYet("review.pr")}, {name: "pr-review waits for review steps", file: "pr-review", want: notYet("review.pr")},
{ {
@@ -53,13 +53,34 @@ func TestCorpusChecksAsItsStepTypesLand(t *testing.T) {
want: slices.Concat(notYet("review.start-round", "repo.prepare", "repo.commit", "review.reply"), agentLater("gate")), want: slices.Concat(notYet("review.start-round", "repo.prepare", "repo.commit", "review.reply"), agentLater("gate")),
}, },
{ {
name: "tdd waits for repositories, gates and agent settings", file: "tdd", name: "tdd waits for repositories, gates and protected tests", file: "tdd",
want: slices.Concat(notYet("repo.prepare", "repo.tooling", "gate.repository", "gate.repository", "repo.commit", "repo.commit", "repo.open-pr"), want: slices.Concat(notYet("repo.prepare", "repo.tooling", "gate.repository", "gate.repository", "repo.commit", "repo.commit", "repo.open-pr"),
agentLater("read_only", "gate", "gate", "protect_tests", "extra_rules")), agentLater("gate", "gate", "protect_tests")),
}, },
{ {
name: "triage's references and conditions check; it waits for forge and outcome steps", file: "triage", name: "triage's references and conditions check; it waits for forge and outcome steps", file: "triage",
want: slices.Concat(notYet("forge.comment", "forge.close-issue", "workflow.finish", "workflow.handoff"), agentLater("read_only", "result")), want: notYet("forge.comment", "forge.close-issue", "workflow.finish", "workflow.handoff"),
},
{
name: "a result field the agent's schema doesn't declare is refused",
yaml: `steps:
- id: assess
type: agent.run
settings:
mission: m
result: {type: object, properties: {fit: {type: boolean}}}
- type: agent.run
settings: {mission: "{{ steps.assess.result.fit }} {{ steps.assess.result.verdict }}"}
`,
want: []string{`step "assess"'s result has no field "verdict"`},
},
{
name: "a result schema must describe an object",
yaml: `steps:
- type: agent.run
settings: {mission: m, result: {type: string}}
`,
want: []string{"result: a JSON Schema with type object"},
}, },
{ {
name: "an earlier step's summary and result fields resolve", name: "an earlier step's summary and result fields resolve",
+11 -11
View File
@@ -15,13 +15,12 @@ import (
//go:embed workflows/investigate.yaml //go:embed workflows/investigate.yaml
var investigateDocument string var investigateDocument string
// InvestigateDocument is the workflow document that has an agent look into the // InvestigateDocument defines the default workflow for investigating an event,
// event that started the run, put what it proposes to people, and report. // requesting approval for proposed actions and reporting the findings.
func InvestigateDocument() string { return investigateDocument } func InvestigateDocument() string { return investigateDocument }
// Document is a workflow as data: what it declares to whatever starts it, and // Document defines a workflow's interface and ordered steps. The engine
// the ordered steps the engine executes. It is stored, diffed and validated as // stores, compares and validates workflow definitions as text.
// text.
type Document struct { type Document struct {
Interface `yaml:",inline"` Interface `yaml:",inline"`
Steps []Step `yaml:"steps"` Steps []Step `yaml:"steps"`
@@ -68,8 +67,8 @@ const (
onFailureContinue = "continue" onFailureContinue = "continue"
) )
// name is what a step's work is recorded under: its id, else its type and // name returns the journal name. Steps without an ID use their type and
// position, which a pinned document keeps stable. // position, which stay stable because the run pins its workflow version.
func (s Step) name(index int) string { func (s Step) name(index int) string {
if s.ID != "" { if s.ID != "" {
return s.ID return s.ID
@@ -77,7 +76,7 @@ func (s Step) name(index int) string {
return fmt.Sprintf("%s@%d", s.Type, index) return fmt.Sprintf("%s@%d", s.Type, index)
} }
// Problem is one thing wrong with a document, at the path of the field. // Problem describes a validation issue at a field path.
type Problem struct { type Problem struct {
Path string `json:"path"` Path string `json:"path"`
Message string `json:"message"` Message string `json:"message"`
@@ -85,7 +84,7 @@ type Problem struct {
func (p Problem) String() string { return p.Path + ": " + p.Message } func (p Problem) String() string { return p.Path + ": " + p.Message }
// InvalidError is the problems found in a document. // InvalidError contains the problems found during workflow validation.
type InvalidError struct { type InvalidError struct {
Problems []Problem `json:"problems"` Problems []Problem `json:"problems"`
} }
@@ -174,7 +173,7 @@ func decodeSettings(settings yaml.Node, target any) error {
var unknownSetting = regexp.MustCompile(`field (\S+) not found`) var unknownSetting = regexp.MustCompile(`field (\S+) not found`)
// Describe says in plain language what each step does. // Describe returns a plain-language summary of each step.
func (d Document) Describe() []string { func (d Document) Describe() []string {
out := make([]string, 0, len(d.Steps)) out := make([]string, 0, len(d.Steps))
for _, s := range d.Steps { for _, s := range d.Steps {
@@ -191,7 +190,8 @@ func (d Document) Describe() []string {
return out return out
} }
// normalise is the form two documents are compared in. // normalise ignores line-ending differences and surrounding whitespace when
// comparing workflow documents.
func normalise(body string) string { func normalise(body string) string {
return string(bytes.TrimSpace([]byte(strings.ReplaceAll(body, "\r\n", "\n")))) return string(bytes.TrimSpace([]byte(strings.ReplaceAll(body, "\r\n", "\n"))))
} }
+9 -12
View File
@@ -17,8 +17,8 @@ import (
"github.com/samcharles93/archie-core/modules/runs/internal/store" "github.com/samcharles93/archie-core/modules/runs/internal/store"
) )
// dryOverlay is what a dry run carries instead of a stored workflow version: // dryOverlay contains the workflow document and policy a dry run tests as
// the document it runs, and the policy it is judged under as if published. // if they were published.
type dryOverlay struct { type dryOverlay struct {
Document string `json:"document"` Document string `json:"document"`
PolicyKind string `json:"policy_kind,omitzero"` PolicyKind string `json:"policy_kind,omitzero"`
@@ -32,7 +32,6 @@ func (o *dryOverlay) policy() *judgement.PolicyOverlay {
return &judgement.PolicyOverlay{Kind: o.PolicyKind, Body: o.Policy} return &judgement.PolicyOverlay{Kind: o.PolicyKind, Body: o.Policy}
} }
// readOverlay decodes the overlay a dry run carries.
func readOverlay(raw jsontext.Value) (*dryOverlay, error) { func readOverlay(raw jsontext.Value) (*dryOverlay, error) {
var o dryOverlay var o dryOverlay
if err := json.Unmarshal(raw, &o); err != nil { if err := json.Unmarshal(raw, &o); err != nil {
@@ -41,12 +40,10 @@ func readOverlay(raw jsontext.Value) (*dryOverlay, error) {
return &o, nil return &o, nil
} }
// Dry reports whether the run is a dry run: every action is judged and none // Dry reports whether the run is a dry run. Dry runs evaluate actions but
// that changes something is executed, nobody is asked and nothing is sent. // execute only read-only actions, and send no approval requests or notifications.
func (rc *Context) Dry() bool { return rc.run.Dry } func (rc *Context) Dry() bool { return rc.run.Dry }
// mayExecute reports whether judgement's decision may be carried out in this
// run. A dry run carries out only what reads.
func (rc *Context) mayExecute(d judgement.Decision) bool { func (rc *Context) mayExecute(d judgement.Decision) bool {
return !rc.run.Dry || d.Action.Effect.ReadOnly return !rc.run.Dry || d.Action.Effect.ReadOnly
} }
@@ -76,7 +73,7 @@ type DryRequest struct {
// StartDry queues a dry run of a document and returns its run's id. A document // StartDry queues a dry run of a document and returns its run's id. A document
// that doesn't validate starts nothing. // that doesn't validate starts nothing.
func (e *Engine) StartDry(ctx context.Context, req DryRequest) (uuid.UUID, error) { func (e *Engine) StartDry(ctx context.Context, req DryRequest) (uuid.UUID, error) {
if _, err := ParseDocument(req.Document); err != nil { if err := e.validateDocument(ctx, req.Document); err != nil {
return uuid.Nil, err return uuid.Nil, err
} }
overlay, err := json.Marshal(dryOverlay{Document: req.Document, PolicyKind: req.PolicyKind, Policy: req.Policy}) overlay, err := json.Marshal(dryOverlay{Document: req.Document, PolicyKind: req.PolicyKind, Policy: req.Policy})
@@ -124,7 +121,7 @@ type DryNotice struct {
Body string `json:"body"` Body string `json:"body"`
} }
// DryReport is what a dry run did: every action it judged and what came of it. // DryReport records evaluated actions, their outcomes and unsent notifications.
type DryReport struct { type DryReport struct {
RunID uuid.UUID `json:"run_id"` RunID uuid.UUID `json:"run_id"`
State string `json:"state"` State string `json:"state"`
@@ -135,8 +132,8 @@ type DryReport struct {
At time.Time `json:"at"` At time.Time `json:"at"`
} }
// DryReport reads what dry run id did so far. ok is false when there is no // DryReport returns the results recorded so far. It reports ok=false if the
// such dry run. // ID does not identify a dry run.
func (e *Engine) DryReport(ctx context.Context, orgID string, id uuid.UUID) (rep DryReport, ok bool, err error) { func (e *Engine) DryReport(ctx context.Context, orgID string, id uuid.UUID) (rep DryReport, ok bool, err error) {
run, found, err := e.db.Detail(ctx, orgID, id) run, found, err := e.db.Detail(ctx, orgID, id)
if err != nil || !found || !run.Dry { if err != nil || !found || !run.Dry {
@@ -205,7 +202,7 @@ func pathNames(path []governance.PathStep) []string {
return names return names
} }
// settleDry records who each held action would be put to, and asks nobody. // settleDry records the intended approvers without sending requests.
func settleDry(rc *Context, judge Judge, settings Settings, settled map[string]bool) ([]approvalOutcome, error) { func settleDry(rc *Context, judge Judge, settings Settings, settled map[string]bool) ([]approvalOutcome, error) {
held, err := heldSince(rc, judge, settled) held, err := heldSince(rc, judge, settled)
if err != nil { if err != nil {
+8 -10
View File
@@ -15,10 +15,8 @@ import (
"github.com/samcharles93/archie-core/modules/runs/internal/store" "github.com/samcharles93/archie-core/modules/runs/internal/store"
) )
// TestAfterApprovalDiscardsAnApprovalThatNoLongerMatchesTheAction guards the // TestAfterApprovalDiscardsAnApprovalThatNoLongerMatchesTheAction checks that
// rule that an approval covers the action as it was shown: when something else // a changed target or effect, or a stricter verdict, invalidates the approval.
// changed the target or effect, or judgement got worse, the approval is
// discarded and the action is put to people again, never run on the old one.
func TestAfterApprovalDiscardsAnApprovalThatNoLongerMatchesTheAction(t *testing.T) { func TestAfterApprovalDiscardsAnApprovalThatNoLongerMatchesTheAction(t *testing.T) {
decided := func(level judgement.Level, mutate func(*judgement.Decision)) judgement.Decision { decided := func(level judgement.Level, mutate func(*judgement.Decision)) judgement.Decision {
d := judgement.Decision{Level: level, Action: judgement.Action{ d := judgement.Decision{Level: level, Action: judgement.Action{
@@ -36,15 +34,15 @@ func TestAfterApprovalDiscardsAnApprovalThatNoLongerMatchesTheAction(t *testing.
fresh judgement.Decision fresh judgement.Decision
want afterwards want afterwards
}{ }{
{name: "an unchanged action runs on its approval", fresh: decided(judgement.ProposeAndWait, nil), want: runApproval}, {name: "an unchanged action uses the existing approval", fresh: decided(judgement.ProposeAndWait, nil), want: runApproval},
{name: "a worse verdict is put to people again", fresh: decided(judgement.Escalate, nil), want: reaskPerson}, {name: "a stricter verdict requires new approval", fresh: decided(judgement.Escalate, nil), want: reaskPerson},
{name: "a changed target is put to people again", fresh: decided(judgement.ProposeAndWait, func(d *judgement.Decision) { {name: "a changed target requires new approval", fresh: decided(judgement.ProposeAndWait, func(d *judgement.Decision) {
d.Action.Target.ID = "db" d.Action.Target.ID = "db"
}), want: reaskPerson}, }), want: reaskPerson},
{name: "a changed environment is put to people again", fresh: decided(judgement.ProposeAndWait, func(d *judgement.Decision) { {name: "a changed environment requires new approval", fresh: decided(judgement.ProposeAndWait, func(d *judgement.Decision) {
d.Action.Target.Environment = "staging" d.Action.Target.Environment = "staging"
}), want: reaskPerson}, }), want: reaskPerson},
{name: "a changed effect is put to people again", fresh: decided(judgement.ProposeAndWait, func(d *judgement.Decision) { {name: "a changed effect requires new approval", fresh: decided(judgement.ProposeAndWait, func(d *judgement.Decision) {
d.Action.Effect.Summary = "delete" d.Action.Effect.Summary = "delete"
}), want: reaskPerson}, }), want: reaskPerson},
{name: "a refusal discards the approval", fresh: decided(judgement.Never, nil), want: refuseAction}, {name: "a refusal discards the approval", fresh: decided(judgement.Never, nil), want: refuseAction},
@@ -118,7 +116,7 @@ func TestWaitThroughPathMovesOnAtEachDeadlineAndExpiresAtTheEnd(t *testing.T) {
{name: "one step with no answer expires without escalating", path: []governance.PathStep{step("a")}, wantExpired: 1}, {name: "one step with no answer expires without escalating", path: []governance.PathStep{step("a")}, wantExpired: 1},
{name: "every step runs out and then the request expires", path: []governance.PathStep{step("a"), step("b"), step("c")}, wantSteps: []int{1, 2}, wantExpired: 1}, {name: "every step runs out and then the request expires", path: []governance.PathStep{step("a"), step("b"), step("c")}, wantSteps: []int{1, 2}, wantExpired: 1},
{name: "an answer at the second step stops the escalation", path: []governance.PathStep{step("a"), step("b"), step("c")}, arrives: 2, wantSteps: []int{1}, wantAnswered: true}, {name: "an answer at the second step stops the escalation", path: []governance.PathStep{step("a"), step("b"), step("c")}, arrives: 2, wantSteps: []int{1}, wantAnswered: true},
{name: "an answer at the first step escalates nowhere", path: []governance.PathStep{step("a"), step("b")}, arrives: 1, wantAnswered: true}, {name: "an answer at the first step prevents escalation", path: []governance.PathStep{step("a"), step("b")}, arrives: 1, wantAnswered: true},
} }
for _, tt := range tests { for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) { t.Run(tt.name, func(t *testing.T) {
+3 -2
View File
@@ -50,8 +50,9 @@ type Run struct {
Attempts int `db:"attempts"` Attempts int `db:"attempts"`
// Dry marks a dry run, and Overlay is the document and policy it runs // Dry marks a dry run, and Overlay is the document and policy it runs
// under; a dry run pins no stored version. // under; a dry run pins no stored version.
Dry bool `db:"dry"` Dry bool `db:"dry"`
Overlay jsontext.Value `db:"overlay"` // Scan into []byte because live runs have a SQL NULL overlay.
Overlay []byte `db:"overlay"`
} }
// Step is one recorded step of a run. // Step is one recorded step of a run.
+117 -58
View File
@@ -12,6 +12,7 @@ import (
"strings" "strings"
"time" "time"
"github.com/google/jsonschema-go/jsonschema"
"github.com/google/uuid" "github.com/google/uuid"
"github.com/samcharles93/ai-sdk/agentloop" "github.com/samcharles93/ai-sdk/agentloop"
"github.com/samcharles93/ai-sdk/chat" "github.com/samcharles93/ai-sdk/chat"
@@ -27,10 +28,9 @@ import (
"github.com/samcharles93/archie-core/modules/runs/internal/store" "github.com/samcharles93/archie-core/modules/runs/internal/store"
) )
// Settings is where a workflow finds what the organisation decided: the agent // Settings provides the organisation's model configuration and escalation policy.
// model it runs, and the escalation path an approval request takes.
type Settings interface { type Settings interface {
AgentModel(ctx context.Context) (governance.Model, error) AgentModelForAlias(ctx context.Context, alias string) (governance.Model, error)
// AgentProvider builds the chat client for a model, resolving the // AgentProvider builds the chat client for a model, resolving the
// credential it names. The model is journaled; the client is rebuilt. // credential it names. The model is journaled; the client is rebuilt.
AgentProvider(ctx context.Context, model governance.Model) (chat.Provider, chat.ModelInfo, error) AgentProvider(ctx context.Context, model governance.Model) (chat.Provider, chat.ModelInfo, error)
@@ -55,10 +55,10 @@ type Judge interface {
ForRun(ctx context.Context, runID uuid.UUID) ([]judgement.Decision, error) ForRun(ctx context.Context, runID uuid.UUID) ([]judgement.Decision, error)
} }
// Approver asks people to allow an action judgement held, moves a request // Approver requests approval for actions held by judgement, escalates
// that nobody answered to the next step of its path, and settles one whose last // unanswered requests and expires them after the final deadline. An approval
// step ran out. An approval is counted when the action is about to run on it, // counts towards an increase in autonomy only when the action is about to run
// and discarded when the action no longer matches it. // using it. If reassessment invalidates the approval, it is discarded instead.
type Approver interface { type Approver interface {
Ask(ctx context.Context, runID uuid.UUID, key string, d judgement.Decision, path []governance.PathStep) (approvals.Request, error) Ask(ctx context.Context, runID uuid.UUID, key string, d judgement.Decision, path []governance.PathStep) (approvals.Request, error)
Escalate(ctx context.Context, id uuid.UUID, step int, to governance.PathStep) error Escalate(ctx context.Context, id uuid.UUID, step int, to governance.PathStep) error
@@ -106,14 +106,18 @@ type Deps struct {
// and the results of earlier steps. // and the results of earlier steps.
type Workflow func(rc *Context, input jsontext.Value) (jsontext.Value, error) type Workflow func(rc *Context, input jsontext.Value) (jsontext.Value, error)
// pinned is what a run's first steps fix, so a resumed run asks the same model type pinnedModel struct {
// with the same tools even if settings or connectors changed meanwhile. model governance.Model
provider chat.Provider
info chat.ModelInfo
}
// A resumed run reuses the recorded configuration but rebuilds model
// clients and resolves tool calls against the connectors currently running.
type pinned struct { type pinned struct {
model governance.Model models map[string]pinnedModel
threshold int threshold int
decls []connectors.Declaration decls []connectors.Declaration
provider chat.Provider
info chat.ModelInfo
} }
// progress is what the steps of one execution have produced so far. // progress is what the steps of one execution have produced so far.
@@ -141,15 +145,15 @@ type progress struct {
// Compile returns the code that runs doc. The same steps run live and dry; a // Compile returns the code that runs doc. The same steps run live and dry; a
// dry run (rc.Dry) judges every action and executes only those that read. // dry run (rc.Dry) judges every action and executes only those that read.
func (d Deps) Compile(doc Document) Workflow { func (d Deps) Compile(doc Document) Workflow {
agent, withMemory := agentUse(doc) aliases, withMemory := agentUse(doc)
settleAtEnd := heldAfterLastApproval(doc) settleAtEnd := heldAfterLastApproval(doc)
return func(rc *Context, input jsontext.Value) (jsontext.Value, error) { return func(rc *Context, input jsontext.Value) (jsontext.Value, error) {
p := &progress{ p := &progress{
input: input, inputs: decodeInputs(input), instructions: doc.Instructions, input: input, inputs: decodeInputs(input), instructions: doc.Instructions,
results: map[string]StepResult{}, outcomes: []approvalOutcome{}, settled: map[string]bool{}, results: map[string]StepResult{}, outcomes: []approvalOutcome{}, settled: map[string]bool{},
} }
if agent { if len(aliases) > 0 {
if err := d.pin(rc, p, withMemory); err != nil { if err := d.pin(rc, p, aliases, withMemory); err != nil {
return nil, err return nil, err
} }
} }
@@ -173,9 +177,8 @@ func (d Deps) Compile(doc Document) Workflow {
} }
} }
// runStep runs one step if its condition holds, with its settings rendered // runStep resolves settings from the run's inputs and earlier results, and
// from the run's inputs and earlier results, and keeps what it leaves under its // saves the result under the step ID if the step runs.
// id.
func (d Deps) runStep(rc *Context, p *progress, s Step, index int) error { func (d Deps) runStep(rc *Context, p *progress, s Step, index int) error {
name := s.name(index) name := s.name(index)
values := scope(p.inputs, p.results) values := scope(p.inputs, p.results)
@@ -214,19 +217,28 @@ func stepFailed(err error) bool {
return true return true
} }
// agentUse reports whether any step runs an agent, and whether one uses memory. func agentUse(doc Document) (aliases []string, withMemory bool) {
func agentUse(doc Document) (agent, withMemory bool) {
for _, s := range doc.Steps { for _, s := range doc.Steps {
if s.Type != typeAgent { if s.Type != typeAgent {
continue continue
} }
agent = true
var settings agentSettings var settings agentSettings
if decodeSettings(s.Settings, &settings) == nil && settings.Memory { if decodeSettings(s.Settings, &settings) == nil {
withMemory = true alias := modelAlias(settings.Model)
if !slices.Contains(aliases, alias) {
aliases = append(aliases, alias)
}
withMemory = withMemory || settings.Memory
} }
} }
return agent, withMemory return aliases, withMemory
}
func modelAlias(alias string) string {
if alias == "default" {
return ""
}
return alias
} }
// heldAfterLastApproval reports whether a step that can propose an action comes // heldAfterLastApproval reports whether a step that can propose an action comes
@@ -254,19 +266,29 @@ func decodeInputs(input jsontext.Value) map[string]any {
return out return out
} }
func (d Deps) pin(rc *Context, p *progress, withMemory bool) error { func (d Deps) pin(rc *Context, p *progress, aliases []string, withMemory bool) error {
model, err := rc.Step("agent-model", func(ctx context.Context, _ string) (governance.Model, error) { models := make(map[string]pinnedModel, len(aliases))
return d.Settings.AgentModel(ctx) for _, alias := range aliases {
}) step := "agent-model"
if err != nil { if alias != "" {
return err step += ":" + alias
} }
if withMemory { model, err := rc.Step(step, func(ctx context.Context, _ string) (governance.Model, error) {
if p.pin.threshold, err = rc.Step("recurrence-threshold", func(ctx context.Context, _ string) (int, error) { return d.Settings.AgentModelForAlias(ctx, alias)
return d.Settings.RecurrenceThreshold(ctx) })
}); err != nil { if err != nil {
return err return err
} }
models[alias] = pinnedModel{model: model}
}
if withMemory {
threshold, err := rc.Step("recurrence-threshold", func(ctx context.Context, _ string) (int, error) {
return d.Settings.RecurrenceThreshold(ctx)
})
if err != nil {
return err
}
p.pin.threshold = threshold
} }
decls, err := rc.Step("agent-tools", func(context.Context, string) ([]connectors.Declaration, error) { decls, err := rc.Step("agent-tools", func(context.Context, string) ([]connectors.Declaration, error) {
return d.Toolbox.Declarations(), nil return d.Toolbox.Declarations(), nil
@@ -274,11 +296,14 @@ func (d Deps) pin(rc *Context, p *progress, withMemory bool) error {
if err != nil { if err != nil {
return err return err
} }
provider, info, err := d.Settings.AgentProvider(rc.Context(), model) for _, alias := range aliases {
if err != nil { m := models[alias]
return err if m.provider, m.info, err = d.Settings.AgentProvider(rc.Context(), m.model); err != nil {
return err
}
models[alias] = m
} }
p.pin.model, p.pin.decls, p.pin.provider, p.pin.info = model, decls, provider, info p.pin.models, p.pin.decls = models, decls
return nil return nil
} }
@@ -292,34 +317,54 @@ func agentSystem(instructions, mission string) string {
return strings.Join(append(parts, mission), "\n\n") return strings.Join(append(parts, mission), "\n\n")
} }
// runAgent has an agent work on its mission with the run's inputs. An action // runAgent evaluates each action when the agent calls it. Actions that
// it proposes is judged as it calls it; the ones judgement holds wait for an // require human approval are deferred to an approval step.
// approval step.
func runAgent(d Deps, rc *Context, p *progress, name string, s agentSettings) (StepResult, error) { func runAgent(d Deps, rc *Context, p *progress, name string, s agentSettings) (StepResult, error) {
budget, err := stepBudget(rc.Context(), d.Settings) budget, err := stepBudget(rc.Context(), d.Settings)
if err != nil { if err != nil {
return StepResult{}, err return StepResult{}, err
} }
decls := p.pin.decls
if s.ReadOnly {
decls = readOnly(decls)
}
var (
resultRaw []byte
resultSchema *jsonschema.Resolved
)
if s.Result != nil {
if resultRaw, resultSchema, err = s.resultSchema(); err != nil {
return StepResult{}, fmt.Errorf("step %q result: %w", name, err)
}
}
tools := func() core.ToolSet { tools := func() core.ToolSet {
set := toolSet(d.Toolbox, d.Judge, rc, p.pin.decls) set := toolSet(d.Toolbox, d.Judge, rc, decls)
if s.Memory { if s.Memory {
set = withMemory(set, d.Memory, rc.RunID()) set = withMemory(set, d.Memory, rc.RunID())
} }
if resultSchema != nil {
set[resultTool] = newResultTool(resultRaw, resultSchema)
}
return set return set
} }
model := p.pin.models[modelAlias(s.Model)]
base := AgentRequest{ base := AgentRequest{
Provider: p.pin.provider, Model: p.pin.model.Model, ModelInfo: p.pin.info, Provider: model.provider, Model: model.model.Model, ModelInfo: model.info,
System: agentSystem(p.instructions, s.Mission), Tools: tools(), System: agentSystem(p.instructions, s.system()), Tools: tools(),
} }
first := base first := base
first.Name, first.Prompt, first.Budget = name, string(p.input), budget first.Name, first.Prompt, first.Budget = name, string(p.input), budget
if resultSchema != nil {
first.Capture = resultTool
}
res, err := rc.Agent(first) res, err := rc.Agent(first)
if err != nil { if err != nil {
return StepResult{}, err return StepResult{}, err
} }
returnedResult := res.Returned
followUp := base followUp := base
followUp.Tools = tools() followUp.Tools = tools()
if res, err = followThrough(rc, d.Judge, p.pin.decls, p.input, res, followUp); err != nil { if res, err = followThrough(rc, d.Judge, decls, p.input, res, followUp); err != nil {
return StepResult{}, err return StepResult{}, err
} }
p.agent = &res p.agent = &res
@@ -335,7 +380,23 @@ func runAgent(d Deps, rc *Context, p *progress, name string, s agentSettings) (S
} }
} }
} }
return StepResult{Summary: res.Answer}, nil return agentResult(name, res, returnedResult, resultSchema)
}
func agentResult(name string, res AgentResult, returned jsontext.Value, schema *jsonschema.Resolved) (StepResult, error) {
out := StepResult{Summary: res.Answer}
if schema == nil || !res.Completed {
return out, nil
}
if len(returned) == 0 {
return StepResult{}, fmt.Errorf("step %q: the agent finished without returning its result", name)
}
result, err := decodeResult(returned, schema)
if err != nil {
return StepResult{}, fmt.Errorf("step %q: %w", name, err)
}
out.Result = result
return out, nil
} }
// result is the run's output: the last agent's findings, or what became of the // result is the run's output: the last agent's findings, or what became of the
@@ -464,9 +525,8 @@ func settleProposals(rc *Context, judge Judge, ask Approver, settings Settings,
return out, nil return out, nil
} }
// heldSince is what judgement held in the run that no earlier approval step // heldSince journals all actions held for approval before filtering out
// settled. The whole list is recorded and the settled ones dropped after, so a // settled ones so that replay uses the same list.
// replay filters the recorded list the same way.
func heldSince(rc *Context, judge Judge, settled map[string]bool) ([]judgement.Decision, error) { func heldSince(rc *Context, judge Judge, settled map[string]bool) ([]judgement.Decision, error) {
held, err := rc.Step("proposals", func(ctx context.Context, _ string) ([]judgement.Decision, error) { held, err := rc.Step("proposals", func(ctx context.Context, _ string) ([]judgement.Decision, error) {
decisions, err := judge.ForRun(ctx, rc.RunID()) decisions, err := judge.ForRun(ctx, rc.RunID())
@@ -481,8 +541,9 @@ func heldSince(rc *Context, judge Judge, settled map[string]bool) ([]judgement.D
return slices.DeleteFunc(held, func(d judgement.Decision) bool { return settled[d.Action.Digest] }), nil return slices.DeleteFunc(held, func(d judgement.Decision) bool { return settled[d.Action.Digest] }), nil
} }
// maxReapprovals bounds how many times an action that keeps changing under its // maxReapprovals limits the number of new requests for one action after
// approval is put to people again. // reassessment invalidates an approval and the action still requires approval.
// The initial request and escalation within a request do not count.
const maxReapprovals = 2 const maxReapprovals = 2
// settleOne gets one action approved and runs it. Before it runs it is judged // settleOne gets one action approved and runs it. Before it runs it is judged
@@ -656,11 +717,9 @@ const (
refuseAction refuseAction
) )
// afterApproval says what an approval of approved means now that the action was // afterApproval checks whether an approval is still valid after reassessment.
// judged again as fresh. An approval covers the action as it was shown, so one // If the action still requires approval, a stricter verdict or a change to the
// whose verdict got worse, or whose target or effect changed, no longer // resolved target or effect requires a new request.
// stands. The target and effect are what the connector resolves the action to
// now, which is what judgement has to tell that something else changed them.
func afterApproval(approved, fresh judgement.Decision) (afterwards, string) { func afterApproval(approved, fresh judgement.Decision) (afterwards, string) {
switch { switch {
case fresh.Level == judgement.Never: case fresh.Level == judgement.Never:
@@ -672,7 +731,7 @@ func afterApproval(approved, fresh judgement.Decision) (afterwards, string) {
case fresh.Action.Effect != approved.Action.Effect: case fresh.Action.Effect != approved.Action.Effect:
return reaskPerson, "the effect changed since it was approved" return reaskPerson, "the effect changed since it was approved"
case fresh.Level > approved.Level: case fresh.Level > approved.Level:
return reaskPerson, "judgement got worse since it was approved: now " + fresh.Level.String() return reaskPerson, "judgement is stricter than when the action was approved: now " + fresh.Level.String()
} }
return runApproval, "" return runApproval, ""
} }
+13 -18
View File
@@ -17,28 +17,26 @@ import (
"github.com/samcharles93/archie-core/modules/memory" "github.com/samcharles93/archie-core/modules/memory"
) )
// Memory is what an investigation remembers and recalls about its target. // Memory stores and retrieves incident history for an investigation target.
type Memory interface { type Memory interface {
Past(ctx context.Context, runID uuid.UUID, t memory.Target) ([]memory.Incident, error) Past(ctx context.Context, runID uuid.UUID, t memory.Target) ([]memory.Incident, error)
Record(ctx context.Context, runID uuid.UUID, event jsontext.Value, t memory.Target, cause, summary string) error Record(ctx context.Context, runID uuid.UUID, event jsontext.Value, t memory.Target, cause, summary string) error
Finish(ctx context.Context, runID uuid.UUID, actions []memory.Action, threshold int) (memory.Review, error) Finish(ctx context.Context, runID uuid.UUID, actions []memory.Action, threshold int) (memory.Review, error)
} }
// recordCauseBudget bounds the turn that files the cause: one tool call and a
// reply.
var recordCauseBudget = agentloop.Budget{MaxSteps: 4, MaxTokens: 30_000, WallClock: 3 * time.Minute} var recordCauseBudget = agentloop.Budget{MaxSteps: 4, MaxTokens: 30_000, WallClock: 3 * time.Minute}
// maxRecalled is how many earlier incidents the agent is shown. // maxRecalled is how many earlier incidents the agent is shown.
const maxRecalled = 10 const maxRecalled = 10
const targetSchema = `{"type":"object","properties":{ const targetSchema = `{"type":"object","properties":{
"target_kind":{"type":"string","description":"what the incident is about, such as host"}, "target_kind":{"type":"string","description":"the resource type, such as host"},
"target_id":{"type":"string","description":"which one, such as web-1"}}, "target_id":{"type":"string","description":"the resource ID, such as web-1"}},
"required":["target_kind","target_id"]}` "required":["target_kind","target_id"]}`
const causeSchema = `{"type":"object","properties":{ const causeSchema = `{"type":"object","properties":{
"target_kind":{"type":"string","description":"what the incident happened to, such as host"}, "target_kind":{"type":"string","description":"the resource type, such as host"},
"target_id":{"type":"string","description":"which one, such as web-1"}, "target_id":{"type":"string","description":"the resource ID, such as web-1"},
"cause":{"type":"string","description":"two to four lowercase words joined by hyphens, such as disk-pressure"}, "cause":{"type":"string","description":"two to four lowercase words joined by hyphens, such as disk-pressure"},
"summary":{"type":"string","description":"one sentence: what happened and why"}}, "summary":{"type":"string","description":"one sentence: what happened and why"}},
"required":["target_kind","target_id","cause","summary"]}` "required":["target_kind","target_id","cause","summary"]}`
@@ -54,11 +52,10 @@ type causeInput struct {
Summary string `json:"summary"` Summary string `json:"summary"`
} }
// pastIncidentsTool lets the agent ask what happened to a target before.
func pastIncidentsTool(mem Memory, runID uuid.UUID) *core.Tool { func pastIncidentsTool(mem Memory, runID uuid.UUID) *core.Tool {
return &core.Tool{ return &core.Tool{
Name: "memory_past_incidents", Name: "memory_past_incidents",
Description: "Lists earlier incidents on a target: when, the cause found, what was done and how it ended.", Description: "Lists previous incidents for a target, including dates, causes, actions and outcomes.",
Parameters: []byte(targetSchema), Parameters: []byte(targetSchema),
Execute: func(ctx context.Context, input string) (string, error) { Execute: func(ctx context.Context, input string) (string, error) {
var in targetInput var in targetInput
@@ -82,10 +79,9 @@ func pastIncidentsTool(mem Memory, runID uuid.UUID) *core.Tool {
} }
} }
// recordCause has the agent name the target and cause of the investigation it // recordCause uses a separate turn because small models are more reliable
// just finished, in a turn of its own: a small model that is asked for four // when asked for four fields after reporting than when asked to remember
// plain fields right after writing its findings fills them reliably, where one // a tool call throughout the investigation.
// asked to remember a tool call at the end of a long investigation does not.
func recordCause(rc *Context, mem Memory, input jsontext.Value, res AgentResult, req AgentRequest) error { func recordCause(rc *Context, mem Memory, input jsontext.Value, res AgentResult, req AgentRequest) error {
if !res.Completed { if !res.Completed {
return nil return nil
@@ -97,7 +93,7 @@ func recordCause(rc *Context, mem Memory, input jsontext.Value, res AgentResult,
req.Name, req.System, req.Prompt, req.Budget = "record-cause", prompts.RecordCause(), string(prompt), recordCauseBudget req.Name, req.System, req.Prompt, req.Budget = "record-cause", prompts.RecordCause(), string(prompt), recordCauseBudget
req.Tools = core.ToolSet{"record_cause": { req.Tools = core.ToolSet{"record_cause": {
Name: "record_cause", Name: "record_cause",
Description: "Files the target and cause of this incident in memory.", Description: "Records the incident target, cause and summary.",
Parameters: []byte(causeSchema), Parameters: []byte(causeSchema),
Execute: func(ctx context.Context, raw string) (string, error) { Execute: func(ctx context.Context, raw string) (string, error) {
var in causeInput var in causeInput
@@ -110,8 +106,7 @@ func recordCause(rc *Context, mem Memory, input jsontext.Value, res AgentResult,
return "recorded", nil return "recorded", nil
}, },
}} }}
// A turn that doesn't file anything leaves the run without an incident; the // If the agent records no incident, keep the investigation findings.
// investigation's findings stand.
_, err = rc.Agent(req) _, err = rc.Agent(req)
return err return err
} }
@@ -158,8 +153,8 @@ func firstText(parts ...string) string {
return "" return ""
} }
// remember files what the run did and checks whether its cause has recurred // remember records the incident and checks whether it meets the recurrence
// enough to ask for a root-cause fix. // threshold for proposing a root-cause fix.
func remember(rc *Context, mem Memory, judge Judge, outcomes []approvalOutcome, threshold int) (memory.Review, error) { func remember(rc *Context, mem Memory, judge Judge, outcomes []approvalOutcome, threshold int) (memory.Review, error) {
return rc.Step("remember", func(ctx context.Context, _ string) (memory.Review, error) { return rc.Step("remember", func(ctx context.Context, _ string) (memory.Review, error) {
decisions, err := judge.ForRun(ctx, rc.RunID()) decisions, err := judge.ForRun(ctx, rc.RunID())
+7 -10
View File
@@ -11,7 +11,7 @@ import (
"github.com/samcharles93/archie-core/internal/platform/stableid" "github.com/samcharles93/archie-core/internal/platform/stableid"
) )
// StepResult is what a finished step leaves for later steps to reference as // StepResult is the output later steps can reference as
// steps.<id>.summary and steps.<id>.result.<field>. // steps.<id>.summary and steps.<id>.result.<field>.
type StepResult struct { type StepResult struct {
Summary string `json:"summary"` Summary string `json:"summary"`
@@ -21,8 +21,8 @@ type StepResult struct {
// referencePattern matches {{ path }} in a step's string settings. // referencePattern matches {{ path }} in a step's string settings.
var referencePattern = regexp.MustCompile(`\{\{\s*([^{}\s]+)\s*\}\}`) var referencePattern = regexp.MustCompile(`\{\{\s*([^{}\s]+)\s*\}\}`)
// soleReferencePattern matches a value that is exactly one reference, which is // soleReferencePattern matches a standalone reference, which preserves the
// what lets it carry the referenced value's own type instead of its text. // referenced value's type.
var soleReferencePattern = regexp.MustCompile(`^\s*\{\{\s*([^{}\s]+)\s*\}\}\s*$`) var soleReferencePattern = regexp.MustCompile(`^\s*\{\{\s*([^{}\s]+)\s*\}\}\s*$`)
// taskFields are the fields a task run fills in. They are accepted in any // taskFields are the fields a task run fills in. They are accepted in any
@@ -135,11 +135,9 @@ func scope(inputs map[string]any, results map[string]StepResult) map[string]any
// renderSettings returns a copy of settings with every reference replaced by // renderSettings returns a copy of settings with every reference replaced by
// its value in this run. // its value in this run.
// //
// A value that is exactly one reference takes that reference's own type, so a // A standalone reference preserves the value's type. References embedded in
// boolean, number, array or object crosses from one step to the next intact; a // strings are interpolated as text. Missing values render empty because a
// reference embedded in prose is interpolated as text, the only thing a string // skipped step produces no output.
// can hold. A reference to an absent value renders empty, which is not an
// error: a skipped earlier step leaves nothing behind.
func renderSettings(settings yaml.Node, values map[string]any) yaml.Node { func renderSettings(settings yaml.Node, values map[string]any) yaml.Node {
rendered := deepCopyNode(&settings) rendered := deepCopyNode(&settings)
renderNode(rendered, values) renderNode(rendered, values)
@@ -147,8 +145,7 @@ func renderSettings(settings yaml.Node, values map[string]any) yaml.Node {
} }
// renderNode replaces references in a settings node's string values, in place. // renderNode replaces references in a settings node's string values, in place.
// Mapping keys are interpolated as text: a key names a field, so it has no // Mapping keys are interpolated as text even for standalone references.
// typed value to carry.
func renderNode(node *yaml.Node, values map[string]any) { func renderNode(node *yaml.Node, values map[string]any) {
switch node.Kind { switch node.Kind {
case yaml.DocumentNode, yaml.SequenceNode: case yaml.DocumentNode, yaml.SequenceNode:
+37 -2
View File
@@ -17,10 +17,11 @@ import (
"github.com/google/uuid" "github.com/google/uuid"
"github.com/jmoiron/sqlx" "github.com/jmoiron/sqlx"
"github.com/samcharles93/archie-core/modules/governance"
"github.com/samcharles93/archie-core/modules/runs/internal/store" "github.com/samcharles93/archie-core/modules/runs/internal/store"
) )
// StartRequest names the workflow to run and the organisation it runs for. // StartRequest specifies the workflow and organisation for a new run.
// A non-empty Key makes the start idempotent within the organisation. // A non-empty Key makes the start idempotent within the organisation.
type StartRequest struct { type StartRequest struct {
OrgID string OrgID string
@@ -107,7 +108,7 @@ func (e *Engine) steps() (Deps, error) {
// what the latest version already is, and returns the version in force. A body // what the latest version already is, and returns the version in force. A body
// that doesn't validate is stored as nothing. // that doesn't validate is stored as nothing.
func (e *Engine) Install(ctx context.Context, orgID, name, body, by string) (int, error) { func (e *Engine) Install(ctx context.Context, orgID, name, body, by string) (int, error) {
if _, err := ParseDocument(body); err != nil { if err := e.validateDocument(ctx, body); err != nil {
return 0, err return 0, err
} }
latest, err := e.db.Workflow(ctx, orgID, name, 0) latest, err := e.db.Workflow(ctx, orgID, name, 0)
@@ -124,6 +125,40 @@ func (e *Engine) Install(ctx context.Context, orgID, name, body, by string) (int
return w.Version, nil return w.Version, nil
} }
func (e *Engine) validateDocument(ctx context.Context, body string) error {
doc, err := ParseDocument(body)
if err != nil {
return err
}
var problems []Problem
for i, step := range doc.Steps {
if step.Type != typeAgent {
continue
}
var s agentSettings
if err := decodeSettings(step.Settings, &s); err != nil {
return err
}
if modelAlias(s.Model) == "" {
continue
}
deps, err := e.steps()
if err != nil {
return err
}
if _, err := deps.Settings.AgentModelForAlias(ctx, s.Model); err != nil {
if !errors.Is(err, governance.ErrNoAgentModel) {
return err
}
problems = append(problems, Problem{Path: fmt.Sprintf("steps[%d].settings.model", i), Message: fmt.Sprintf("unknown agent model alias %q", s.Model)})
}
}
if len(problems) > 0 {
return &InvalidError{Problems: problems}
}
return nil
}
// Has reports whether a workflow is stored under name. // Has reports whether a workflow is stored under name.
func (e *Engine) Has(ctx context.Context, orgID, name string) (bool, error) { func (e *Engine) Has(ctx context.Context, orgID, name string) (bool, error) {
_, err := e.db.Workflow(ctx, orgID, name, 0) _, err := e.db.Workflow(ctx, orgID, name, 0)
+1 -1
View File
@@ -72,7 +72,7 @@ func (a *askCounter) Discard(context.Context, uuid.UUID, string) error { return
// onePersonPath sends every request to one person. // onePersonPath sends every request to one person.
type onePersonPath struct{} type onePersonPath struct{}
func (onePersonPath) AgentModel(context.Context) (governance.Model, error) { func (onePersonPath) AgentModelForAlias(context.Context, string) (governance.Model, error) {
return governance.Model{}, errors.New("no agent in these workflows") return governance.Model{}, errors.New("no agent in these workflows")
} }
+8 -8
View File
@@ -13,12 +13,11 @@ steps:
infrastructure. An investigation ends when the cause is found, not when infrastructure. An investigation ends when the cause is found, not when
the first figure is. the first figure is.
Archie remembers earlier incidents. Once you know which target the event Once you identify the target (a kind and ID, such as host web-1), pass
is about (a kind and an id, such as host web-1), call it to memory_past_incidents before continuing. In your findings, list any
memory_past_incidents with it before you dig further. If it lists previous incidents with the same cause, along with their dates,
earlier incidents with the same cause, say so in your findings: cite actions and outcomes. Consider those outcomes before recommending
each by its date, what was done then and how it ended, and weigh that the same action again.
before recommending the same action again.
The event is a claim, not a fact. Check it against what you measure, and The event is a claim, not a fact. Check it against what you measure, and
if they disagree (an alert says a disk is full and it is at 40%), say so if they disagree (an alert says a disk is full and it is at 40%), say so
@@ -45,8 +44,9 @@ steps:
- The likely cause, and how sure you are. - The likely cause, and how sure you are.
- The evidence: what you looked at and what it showed. - The evidence: what you looked at and what it showed.
- What should happen next, naming the action and its target precisely. - What should happen next, naming the action and its target precisely.
Say what judgement answered if you called it. Don't claim a call you If a tool call returns a judgement decision, report the decision and
didn't make: only a tool call counts, and a failed one says so. any reasons it gives. Report failed tool calls as failures, and don't
claim to have called a tool you didn't use.
If you couldn't find out, say what you tried and what is missing. If you couldn't find out, say what you tried and what is missing.
- id: approve - id: approve
+39 -29
View File
@@ -12,6 +12,7 @@ import (
"gopkg.in/yaml.v3" "gopkg.in/yaml.v3"
"github.com/samcharles93/archie-core/modules/deliveries" "github.com/samcharles93/archie-core/modules/deliveries"
"github.com/samcharles93/archie-core/modules/governance"
"github.com/samcharles93/archie-core/modules/judgement" "github.com/samcharles93/archie-core/modules/judgement"
) )
@@ -24,14 +25,12 @@ const (
typeSleep = "workflow.sleep" typeSleep = "workflow.sleep"
) )
// StepType is one word of the workflow vocabulary: the type a step names, the // StepType defines a workflow step's settings and implementation.
// settings it takes, and the code that runs it.
type StepType struct { type StepType struct {
Name string `json:"name"` Name string `json:"name"`
// Title is the human name editors show for the step type. // Title is the label shown in workflow editors.
Title string `json:"title"` Title string `json:"title"`
// NeedsRepository is a type that runs only with a worktree, so a workflow // NeedsRepository restricts the step type to workflows that require a repository.
// whose repository isn't required can't use it.
NeedsRepository bool `json:"needs_repository"` NeedsRepository bool `json:"needs_repository"`
// Settings is the JSON Schema of the type's settings. // Settings is the JSON Schema of the type's settings.
Settings *jsonschema.Schema `json:"settings"` Settings *jsonschema.Schema `json:"settings"`
@@ -84,7 +83,7 @@ var stepTypes = vocabulary(
define(typeAgent, "Run an agent", agentSettings.valid, agentSettings.describe, runAgent), define(typeAgent, "Run an agent", agentSettings.valid, agentSettings.describe, runAgent),
define(typeAction, "Run a connector action", actionSettings.valid, actionSettings.describe, runAction), define(typeAction, "Run a connector action", actionSettings.valid, actionSettings.describe, runAction),
define(typeApproval, "Wait for approval", noSettings.valid, func(noSettings) string { define(typeApproval, "Wait for approval", noSettings.valid, func(noSettings) string {
return "Waits for approval before anything judgement holds runs" return "Requests approval for actions held by judgement and runs approved actions"
}, runApprovalWait), }, runApprovalWait),
define(typeNotify, "Report the findings", notifySettings.valid, notifySettings.describe, runNotify), define(typeNotify, "Report the findings", notifySettings.valid, notifySettings.describe, runNotify),
define(typeSleep, "Wait", sleepSettings.valid, sleepSettings.describe, runSleep), define(typeSleep, "Wait", sleepSettings.valid, sleepSettings.describe, runSleep),
@@ -107,31 +106,46 @@ func StepTypes() []StepType {
return out return out
} }
// agentSettings run a tool-using agent. Mission is what it is asked to do;
// Memory gives it the lookup of a target's earlier incidents and files what
// the run found and did once it ends.
type agentSettings struct { type agentSettings struct {
Mission string `yaml:"mission" json:"mission" jsonschema:"what the agent is asked to do"` Mission string `yaml:"mission" json:"mission" jsonschema:"the task the agent should perform"`
Memory bool `yaml:"memory,omitempty" json:"memory,omitempty" jsonschema:"recall a target's earlier incidents and file what this run found"` Memory bool `yaml:"memory,omitempty" json:"memory,omitempty" jsonschema:"retrieve previous incidents for the target and store new findings"`
ReadOnly bool `yaml:"read_only,omitempty" json:"read_only,omitempty" jsonschema:"restrict the agent to read-only tools"`
ExtraRules string `yaml:"extra_rules,omitempty" json:"extra_rules,omitempty" jsonschema:"appended to the agent's system prompt"`
Model string `yaml:"model,omitempty" json:"model,omitempty" jsonschema:"organisation model alias; omit to use the default"`
// Result defines the output schema. Later steps can read the validated
// output at steps.<id>.result.
Result map[string]any `yaml:"result,omitempty" json:"result,omitempty" jsonschema:"JSON Schema for the object the agent must return; later steps read the result at steps.<id>.result"`
} }
func (s agentSettings) valid() error { func (s agentSettings) valid() error {
if s.Mission == "" { if s.Mission == "" {
return errors.New("an agent needs a mission") return errors.New("an agent needs a mission")
} }
if err := governance.ValidateAgentModelAlias(s.Model); err != nil {
return err
}
if s.Result != nil {
if _, _, err := s.resultSchema(); err != nil {
return fmt.Errorf("result: %w", err)
}
}
return nil return nil
} }
func (s agentSettings) describe() string { func (s agentSettings) describe() string {
line := "An agent works on its mission, looking things up and proposing actions, each judged before it runs" line := "The agent looks up information and proposes actions for judgement before execution"
if s.ReadOnly {
line = "The agent can only use read-only tools"
}
if s.Result != nil {
line += "; it returns a structured result"
}
if s.Memory { if s.Memory {
line += "; it recalls earlier incidents and files what it found" line += "; it retrieves previous incidents and stores new findings"
} }
return line return line
} }
// actionSettings judge one connector action and run it if judgement lets it
// run unattended.
type actionSettings struct { type actionSettings struct {
Connector string `yaml:"connector" json:"connector"` Connector string `yaml:"connector" json:"connector"`
Name string `yaml:"name" json:"name"` Name string `yaml:"name" json:"name"`
@@ -146,21 +160,19 @@ func (s actionSettings) valid() error {
} }
func (s actionSettings) describe() string { func (s actionSettings) describe() string {
return fmt.Sprintf("Runs %s %s once judged", s.Connector, s.Name) return fmt.Sprintf("Submits %s %s for judgement and runs it if allowed to run unattended", s.Connector, s.Name)
} }
// noSettings is a type that takes none.
type noSettings struct{} type noSettings struct{}
func (noSettings) valid() error { return nil } func (noSettings) valid() error { return nil }
// notifySettings tell people what the run found. Title replaces the default.
type notifySettings struct { type notifySettings struct {
Title string `yaml:"title,omitempty" json:"title,omitempty"` Title string `yaml:"title,omitempty" json:"title,omitempty"`
} }
func (notifySettings) valid() error { return nil } func (notifySettings) valid() error { return nil }
func (notifySettings) describe() string { return "Reports what it found and did" } func (notifySettings) describe() string { return "Reports the run's findings and actions" }
// maxSleep bounds a sleep step. // maxSleep bounds a sleep step.
const maxSleep = 24 * time.Hour const maxSleep = 24 * time.Hour
@@ -184,9 +196,8 @@ func (s sleepSettings) duration() time.Duration {
return d return d
} }
// runAction judges the action and runs it if judgement lets it run // runAction executes only actions allowed to run unattended. A later
// unattended. One judgement holds waits for an approval step; one it refuses // approval step handles actions held for approval.
// is reported.
func runAction(d Deps, rc *Context, p *progress, name string, s actionSettings) (StepResult, error) { func runAction(d Deps, rc *Context, p *progress, name string, s actionSettings) (StepResult, error) {
input := s.Input input := s.Input
if input == nil { if input == nil {
@@ -220,7 +231,6 @@ func runAction(d Deps, rc *Context, p *progress, name string, s actionSettings)
}, nil }, nil
} }
// runApprovalWait puts what judgement held to people and runs what they allow.
func runApprovalWait(d Deps, rc *Context, p *progress, _ string, _ noSettings) (StepResult, error) { func runApprovalWait(d Deps, rc *Context, p *progress, _ string, _ noSettings) (StepResult, error) {
out, err := d.settle(rc, p) out, err := d.settle(rc, p)
if err != nil { if err != nil {
@@ -229,9 +239,8 @@ func runApprovalWait(d Deps, rc *Context, p *progress, _ string, _ noSettings) (
return StepResult{Summary: outcomeLines(out)}, nil return StepResult{Summary: outcomeLines(out)}, nil
} }
// settle puts every action judgement held and nobody has settled yet to // settle requests approval for pending actions and runs those approved.
// people, and runs what they allow. In a dry run nobody is asked: it records // A dry run records the intended recipients without contacting them.
// who would be.
func (d Deps) settle(rc *Context, p *progress) ([]approvalOutcome, error) { func (d Deps) settle(rc *Context, p *progress) ([]approvalOutcome, error) {
var ( var (
out []approvalOutcome out []approvalOutcome
@@ -252,8 +261,9 @@ func (d Deps) settle(rc *Context, p *progress) ([]approvalOutcome, error) {
return out, nil return out, nil
} }
// runNotify tells people what the run found, after filing it in memory. In a // runNotify records incident history before notifying when memory is enabled
// dry run it records what would be sent and sends nothing. // and the investigation can finish. A dry run records the notification without
// sending it.
func runNotify(d Deps, rc *Context, p *progress, _ string, s notifySettings) (StepResult, error) { func runNotify(d Deps, rc *Context, p *progress, _ string, s notifySettings) (StepResult, error) {
if p.memory && !p.remembered && !p.stopped && !rc.Dry() { if p.memory && !p.remembered && !p.stopped && !rc.Dry() {
review, err := remember(rc, d.Memory, d.Judge, p.outcomes, p.pin.threshold) review, err := remember(rc, d.Memory, d.Judge, p.outcomes, p.pin.threshold)
@@ -274,7 +284,7 @@ func runNotify(d Deps, rc *Context, p *progress, _ string, s notifySettings) (St
_, err := rc.Step("notify", func(ctx context.Context, key string) (bool, error) { _, err := rc.Step("notify", func(ctx context.Context, key string) (bool, error) {
return true, d.Notifier.Notify(ctx, n(key)) return true, d.Notifier.Notify(ctx, n(key))
}) })
// The title doesn't depend on the key, so a replay summarises it alike. // The title doesn't depend on the key, so it stays the same on replay.
return StepResult{Summary: n("").Title}, err return StepResult{Summary: n("").Title}, err
} }
+8 -8
View File
@@ -13,12 +13,11 @@ steps:
infrastructure. An investigation ends when the cause is found, not when infrastructure. An investigation ends when the cause is found, not when
the first figure is. the first figure is.
Archie remembers earlier incidents. Once you know which target the event Once you identify the target (a kind and ID, such as host web-1), pass
is about (a kind and an id, such as host web-1), call it to memory_past_incidents before continuing. In your findings, list any
memory_past_incidents with it before you dig further. If it lists previous incidents with the same cause, along with their dates,
earlier incidents with the same cause, say so in your findings: cite actions and outcomes. Consider those outcomes before recommending
each by its date, what was done then and how it ended, and weigh that the same action again.
before recommending the same action again.
The event is a claim, not a fact. Check it against what you measure, and The event is a claim, not a fact. Check it against what you measure, and
if they disagree (an alert says a disk is full and it is at 40%), say so if they disagree (an alert says a disk is full and it is at 40%), say so
@@ -45,8 +44,9 @@ steps:
- The likely cause, and how sure you are. - The likely cause, and how sure you are.
- The evidence: what you looked at and what it showed. - The evidence: what you looked at and what it showed.
- What should happen next, naming the action and its target precisely. - What should happen next, naming the action and its target precisely.
Say what judgement answered if you called it. Don't claim a call you If a tool call returns a judgement decision, report the decision and
didn't make: only a tool call counts, and a failed one says so. any reasons it gives. Report failed tool calls as failures, and don't
claim to have called a tool you didn't use.
If you couldn't find out, say what you tried and what is missing. If you couldn't find out, say what you tried and what is missing.
- id: approve - id: approve
+2 -1
View File
@@ -79,7 +79,8 @@ state; the UI presents them and submits operator choices.
- Name things after what you are working with. The page sets context, so use - Name things after what you are working with. The page sets context, so use
"Restore default" not "Restore shipped workflows". "Restore default" not "Restore shipped workflows".
- No filler or guidance text. Delete empty-state essays, hints that repeat the - No filler or guidance text. Delete empty-state essays, hints that repeat the
label, and sentences explaining how the UI works. label, and sentences explaining how the UI works. Don't say that secret
values are hidden when the control only displays credential names.
- Product names are our own. The editor helper is "Build with Archie" or - Product names are our own. The editor helper is "Build with Archie" or
"Iterate with Archie", never generic terms like "Ask bar". "Iterate with Archie", never generic terms like "Ask bar".
- Actions live where their scope lives. Bulk or instance-wide actions (e.g., - Actions live where their scope lives. Bulk or instance-wide actions (e.g.,
-1
View File
@@ -7,7 +7,6 @@ import { MetadataList } from "@/components/ui/metadata-list";
import { Timestamp } from "@/components/ui/timestamp"; import { Timestamp } from "@/components/ui/timestamp";
import type { ActionTrail, ApprovalRequest, Effect, Verdict } from "./api"; import type { ActionTrail, ApprovalRequest, Effect, Verdict } from "./api";
/** One action from judgement to effect: verdicts, the approval it was put to, and what it did. */
const props = defineProps<{ action: ActionTrail }>(); const props = defineProps<{ action: ActionTrail }>();
type Tone = "ok" | "warn" | "danger" | "info" | "secondary"; type Tone = "ok" | "warn" | "danger" | "info" | "secondary";
+51 -33
View File
@@ -1,5 +1,5 @@
<script setup lang="ts"> <script setup lang="ts">
import { onBeforeUnmount, onMounted, reactive, ref } from "vue"; import { computed, onBeforeUnmount, onMounted, reactive, ref } from "vue";
import { Button } from "@/components/ui/button"; import { Button } from "@/components/ui/button";
import { Input } from "@/components/ui/input"; import { Input } from "@/components/ui/input";
@@ -9,8 +9,7 @@ import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "@
import { SettingRow } from "@/components/ui/setting-row"; import { SettingRow } from "@/components/ui/setting-row";
import { Spinner } from "@/components/ui/spinner"; import { Spinner } from "@/components/ui/spinner";
import { import {
ApiError, listAgentModels,
getAgentModel,
listCredentials, listCredentials,
saveAgentModel, saveAgentModel,
testAgentModel, testAgentModel,
@@ -19,47 +18,54 @@ import {
type CredentialView, type CredentialView,
} from "./api"; } from "./api";
/**
* The model every agent loop asks. The key is a credential named here; the
* value stays sealed, and Test asks the model one question.
*/
const emit = defineEmits<{ unauthorized: [] }>(); const emit = defineEmits<{ unauthorized: [] }>();
const none = "none"; const none = "none";
const model = reactive<AgentModel>({ class: "openai", base_url: "", model: "", api_key_credential: "" }); const blankModel = (): AgentModel => ({ class: "openai", base_url: "", model: "", api_key_credential: "" });
const models = reactive(new Map<string, AgentModel>([["default", blankModel()]]));
const alias = ref("default");
const newAlias = ref("");
const model = computed(() => models.get(alias.value)!);
const credentials = ref<CredentialView[]>([]); const credentials = ref<CredentialView[]>([]);
const loading = ref(true); const loading = ref(true);
const loadError = ref("");
const error = ref(""); const error = ref("");
const answer = ref(""); const answer = ref("");
const saved = ref(""); const saved = ref("");
const testing = ref(false); const testing = ref(false);
const saving = ref(false); const saving = ref(false);
const unset = ref(false);
const controller = new AbortController(); const controller = new AbortController();
async function load() { async function load() {
loading.value = true; loading.value = true;
error.value = ""; loadError.value = "";
try { try {
const [current, creds] = await Promise.all([ const [current, creds] = await Promise.all([
getAgentModel(controller.signal).catch((err: unknown) => { listAgentModels(controller.signal),
if (err instanceof ApiError && err.status === 404) {
unset.value = true;
return null;
}
throw err;
}),
listCredentials(controller.signal), listCredentials(controller.signal),
]); ]);
credentials.value = creds; credentials.value = creds;
if (current) Object.assign(model, current); for (const [name, configured] of Object.entries(current)) models.set(name, configured);
} catch (err) { } catch (err) {
fail(err); fail(err, loadError);
} finally { } finally {
loading.value = false; loading.value = false;
} }
} }
function selectAlias(name: string) {
alias.value = name;
error.value = answer.value = saved.value = "";
}
function addAlias() {
const name = newAlias.value.trim();
if (!name) return;
if (!models.has(name)) models.set(name, blankModel());
selectAlias(name);
newAlias.value = "";
}
async function test() { async function test() {
testing.value = true; testing.value = true;
error.value = ""; error.value = "";
@@ -80,8 +86,7 @@ async function save() {
error.value = ""; error.value = "";
saved.value = ""; saved.value = "";
try { try {
Object.assign(model, await saveAgentModel(payload())); models.set(alias.value, await saveAgentModel(alias.value, payload()));
unset.value = false;
saved.value = "Saved."; saved.value = "Saved.";
} catch (err) { } catch (err) {
fail(err); fail(err);
@@ -92,17 +97,17 @@ async function save() {
function payload(): AgentModel { function payload(): AgentModel {
return { return {
class: model.class.trim(), class: model.value.class.trim(),
base_url: model.base_url.trim(), base_url: model.value.base_url.trim(),
model: model.model.trim(), model: model.value.model.trim(),
api_key_credential: model.api_key_credential === none ? "" : model.api_key_credential, api_key_credential: model.value.api_key_credential === none ? "" : model.value.api_key_credential,
}; };
} }
function fail(err: unknown) { function fail(err: unknown, target = error) {
if (controller.signal.aborted) return; if (controller.signal.aborted) return;
if (err instanceof Unauthorized) emit("unauthorized"); if (err instanceof Unauthorized) emit("unauthorized");
error.value = err instanceof Error ? err.message : String(err); target.value = err instanceof Error ? err.message : String(err);
} }
onMounted(load); onMounted(load);
@@ -110,21 +115,34 @@ onBeforeUnmount(() => controller.abort());
</script> </script>
<template> <template>
<Section title="Agent model"> <Section title="Agent models">
<Spinner v-if="loading" /> <Spinner v-if="loading" />
<ReadError v-else-if="error && !model.model" :message="error" retry-label="Retry" @retry="load" /> <ReadError v-else-if="loadError" :message="loadError" retry-label="Retry" @retry="load" />
<template v-else> <template v-else>
<p v-if="unset" class="mb-2 text-caption text-warn">No agent model is set, so runs that ask a model fail.</p> <SettingRow label="Model alias" for="model-alias">
<Select :model-value="alias" :disabled="saving || testing" @update:model-value="(name) => selectAlias(String(name))">
<SelectTrigger id="model-alias" class="w-full sm:w-64"><SelectValue /></SelectTrigger>
<SelectContent>
<SelectItem v-for="name in [...models.keys()].sort()" :key="name" :value="name">{{ name }}</SelectItem>
</SelectContent>
</Select>
</SettingRow>
<SettingRow label="New alias" for="new-model-alias">
<div class="flex flex-wrap gap-2">
<Input id="new-model-alias" v-model="newAlias" placeholder="fast" class="w-48" />
<Button size="sm" variant="outline" :disabled="saving || testing || !newAlias.trim()" @click="addAlias">Add alias</Button>
</div>
</SettingRow>
<SettingRow label="Provider class" for="agent-class" hint="The provider family, such as openai, anthropic or ollama."> <SettingRow label="Provider class" for="agent-class" hint="The provider family, such as openai, anthropic or ollama.">
<Input id="agent-class" v-model="model.class" placeholder="openai" /> <Input id="agent-class" v-model="model.class" placeholder="openai" />
</SettingRow> </SettingRow>
<SettingRow label="Base URL" for="agent-base-url" hint="Empty takes the provider class's published default."> <SettingRow label="Base URL" for="agent-base-url" hint="Leave blank to use the provider's default URL, if available.">
<Input id="agent-base-url" v-model="model.base_url" placeholder="https://…" /> <Input id="agent-base-url" v-model="model.base_url" placeholder="https://…" />
</SettingRow> </SettingRow>
<SettingRow label="Model" for="agent-model"> <SettingRow label="Model" for="agent-model">
<Input id="agent-model" v-model="model.model" /> <Input id="agent-model" v-model="model.model" />
</SettingRow> </SettingRow>
<SettingRow label="API key" for="agent-credential" hint="A bearer credential. Its token is never shown."> <SettingRow label="API key" for="agent-credential">
<Select :model-value="model.api_key_credential || none" @update:model-value="(v) => (model.api_key_credential = String(v))"> <Select :model-value="model.api_key_credential || none" @update:model-value="(v) => (model.api_key_credential = String(v))">
<SelectTrigger id="agent-credential" class="w-full sm:w-64"><SelectValue /></SelectTrigger> <SelectTrigger id="agent-credential" class="w-full sm:w-64"><SelectValue /></SelectTrigger>
<SelectContent> <SelectContent>
@@ -138,7 +156,7 @@ onBeforeUnmount(() => controller.abort());
<Button variant="outline" size="sm" :disabled="testing || !model.class.trim() || !model.model.trim()" @click="test">Test</Button> <Button variant="outline" size="sm" :disabled="testing || !model.class.trim() || !model.model.trim()" @click="test">Test</Button>
<span v-if="saved" class="text-caption text-muted-foreground">{{ saved }}</span> <span v-if="saved" class="text-caption text-muted-foreground">{{ saved }}</span>
</div> </div>
<p v-if="answer" class="mt-2 text-label">The model answered: <span class="font-mono">{{ answer }}</span></p> <p v-if="answer" class="mt-2 text-label">Test response: <span class="font-mono">{{ answer }}</span></p>
<p v-if="error" class="mt-2 text-caption text-danger">{{ error }}</p> <p v-if="error" class="mt-2 text-caption text-danger">{{ error }}</p>
</template> </template>
</Section> </Section>
+3 -3
View File
@@ -12,8 +12,8 @@ import { Timestamp } from "@/components/ui/timestamp";
import { answerApproval, composerStream, latestMessages, messagesAfter, type Message, Unauthorized } from "./api"; import { answerApproval, composerStream, latestMessages, messagesAfter, type Message, Unauthorized } from "./api";
/** /**
* The composer: what Archie tells you, newest last. Messages are read from a * The stream sends sequence numbers, not message bodies. Fetch messages
* cursor; the stream only says when there is more to read. * after the last loaded sequence number to catch up after reconnecting.
*/ */
const emit = defineEmits<{ unauthorized: [] }>(); const emit = defineEmits<{ unauthorized: [] }>();
@@ -100,7 +100,7 @@ onBeforeUnmount(() => controller.abort());
<Spinner v-if="loading" /> <Spinner v-if="loading" />
<ReadError v-else-if="error" :message="error" retry-label="Retry" @retry="load" /> <ReadError v-else-if="error" :message="error" retry-label="Retry" @retry="load" />
<Empty v-else-if="messages.length === 0"> <Empty v-else-if="messages.length === 0">
<EmptyHeader><EmptyTitle>Nothing yet</EmptyTitle></EmptyHeader> <EmptyHeader><EmptyTitle>No messages yet</EmptyTitle></EmptyHeader>
</Empty> </Empty>
<Section v-for="m in messages" v-else :key="m.id" :title="m.title"> <Section v-for="m in messages" v-else :key="m.id" :title="m.title">
<template #action> <template #action>
+2 -3
View File
@@ -14,9 +14,8 @@ import { Spinner } from "@/components/ui/spinner";
import { listCredentials, saveCredential, Unauthorized, type CredentialField, type CredentialView } from "./api"; import { listCredentials, saveCredential, Unauthorized, type CredentialField, type CredentialView } from "./api";
/** /**
* Credentials are the values connectors are configured with. They are write * The API returns field sources, not saved secret values. Enter those values
* only: a saved field says where it comes from, never what it holds, and * again when replacing a credential.
* replacing a credential means entering its values again.
*/ */
const emit = defineEmits<{ unauthorized: [] }>(); const emit = defineEmits<{ unauthorized: [] }>();
+3 -8
View File
@@ -17,11 +17,6 @@ import { Textarea } from "@/components/ui/textarea";
import { Timestamp } from "@/components/ui/timestamp"; import { Timestamp } from "@/components/ui/timestamp";
import { getEvent, listEvents, listSources, Unauthorized, type EventDetail, type EventRow } from "./api"; import { getEvent, listEvents, listSources, Unauthorized, type EventDetail, type EventRow } from "./api";
/**
* Events are what Archie heard, with the payload it arrived in and the runs
* triggers started. Filters narrow by source, type and whether a trigger
* matched.
*/
const emit = defineEmits<{ unauthorized: [] }>(); const emit = defineEmits<{ unauthorized: [] }>();
const rows = ref<EventRow[]>([]); const rows = ref<EventRow[]>([]);
@@ -97,15 +92,15 @@ onBeforeUnmount(() => controller.abort());
<Section title="Filters"> <Section title="Filters">
<SettingRow label="Source" for="event-source"> <SettingRow label="Source" for="event-source">
<Select v-model="source" @update:model-value="load"> <Select v-model="source" @update:model-value="load">
<SelectTrigger id="event-source" class="w-full sm:w-64"><SelectValue placeholder="Every source" /></SelectTrigger> <SelectTrigger id="event-source" class="w-full sm:w-64"><SelectValue placeholder="All sources" /></SelectTrigger>
<SelectContent> <SelectContent>
<SelectItem value="all">Every source</SelectItem> <SelectItem value="all">All sources</SelectItem>
<SelectItem v-for="s in sources" :key="s" :value="s">{{ s }}</SelectItem> <SelectItem v-for="s in sources" :key="s" :value="s">{{ s }}</SelectItem>
</SelectContent> </SelectContent>
</Select> </Select>
</SettingRow> </SettingRow>
<SettingRow label="Type" for="event-type"> <SettingRow label="Type" for="event-type">
<Input id="event-type" v-model="type" placeholder="Every type" @change="load" /> <Input id="event-type" v-model="type" placeholder="All event types" @change="load" />
</SettingRow> </SettingRow>
<SettingRow label="Trigger" for="event-matched"> <SettingRow label="Trigger" for="event-matched">
<Select v-model="matched" @update:model-value="load"> <Select v-model="matched" @update:model-value="load">
+6 -8
View File
@@ -27,9 +27,7 @@ import {
} from "./api"; } from "./api";
/** /**
* Accepted packages grouped by the contract they serve. Each one shows its * The UI configures credential slots by name without reading secret values.
* state, version and digest, and expands into the settings it declares and the
* credential slots it was given. A credential is named, never read.
*/ */
const emit = defineEmits<{ unauthorized: [] }>(); const emit = defineEmits<{ unauthorized: [] }>();
@@ -261,7 +259,7 @@ onBeforeUnmount(() => controller.abort());
<div v-for="items in [rows[c.id]]" :key="`${c.id}-list`"> <div v-for="items in [rows[c.id]]" :key="`${c.id}-list`">
<Empty v-if="items.length === 0"> <Empty v-if="items.length === 0">
<EmptyHeader><EmptyTitle>None accepted</EmptyTitle></EmptyHeader> <EmptyHeader><EmptyTitle>No extensions accepted</EmptyTitle></EmptyHeader>
</Empty> </Empty>
<DataTable v-if="items.length" :columns="columns" :rows="items" :row-key="(x) => x.name" :storage-key="`extensions-${c.id}`"> <DataTable v-if="items.length" :columns="columns" :rows="items" :row-key="(x) => x.name" :storage-key="`extensions-${c.id}`">
<template #cell-name="{ row }"><span class="font-medium">{{ row.name }}</span></template> <template #cell-name="{ row }"><span class="font-medium">{{ row.name }}</span></template>
@@ -316,7 +314,7 @@ onBeforeUnmount(() => controller.abort());
@update:model-value="(v) => setSetting(s.key, String(v))" @update:model-value="(v) => setSetting(s.key, String(v))"
/> />
</SettingRow> </SettingRow>
<SettingRow label="Credential slots" hint="The credential that fills each slot the package reads. Its value is sealed and never shown."> <SettingRow label="Credential slots" hint="Assign a credential to each slot.">
<div class="flex flex-col gap-2"> <div class="flex flex-col gap-2">
<div v-for="(slot, index) in edit.slots" :key="index" class="flex flex-wrap items-center gap-2"> <div v-for="(slot, index) in edit.slots" :key="index" class="flex flex-wrap items-center gap-2">
<Input v-model="slot.slot" placeholder="slot" class="w-40" aria-label="Credential slot" /> <Input v-model="slot.slot" placeholder="slot" class="w-40" aria-label="Credential slot" />
@@ -366,7 +364,7 @@ onBeforeUnmount(() => controller.abort());
<SettingRow label="Egress" :for="`${c.id}-egress`" hint="Comma-separated hosts it may reach. Empty runs it on the host network."> <SettingRow label="Egress" :for="`${c.id}-egress`" hint="Comma-separated hosts it may reach. Empty runs it on the host network.">
<Input :id="`${c.id}-egress`" v-model="forms[c.id].egress" /> <Input :id="`${c.id}-egress`" v-model="forms[c.id].egress" />
</SettingRow> </SettingRow>
<SettingRow label="Environment" :for="`${c.id}-env`" hint="Comma-separated host variables it may read."> <SettingRow label="Environment" :for="`${c.id}-env`" hint="Comma-separated names of host environment variables the extension may read.">
<Input :id="`${c.id}-env`" v-model="forms[c.id].env" /> <Input :id="`${c.id}-env`" v-model="forms[c.id].env" />
</SettingRow> </SettingRow>
<SettingRow v-if="c.id === 'mcp'" label="Arguments" :for="`${c.id}-args`"> <SettingRow v-if="c.id === 'mcp'" label="Arguments" :for="`${c.id}-args`">
@@ -375,7 +373,7 @@ onBeforeUnmount(() => controller.abort());
<SettingRow v-if="c.id === 'mcp'" label="Tools" :for="`${c.id}-tools`" hint="The tools the server may offer, as JSON."> <SettingRow v-if="c.id === 'mcp'" label="Tools" :for="`${c.id}-tools`" hint="The tools the server may offer, as JSON.">
<Textarea :id="`${c.id}-tools`" v-model="forms[c.id].tools" rows="5" class="font-mono" spellcheck="false" /> <Textarea :id="`${c.id}-tools`" v-model="forms[c.id].tools" rows="5" class="font-mono" spellcheck="false" />
</SettingRow> </SettingRow>
<SettingRow label="Credential slots" hint="A slot the extension reads, and the credential that fills it."> <SettingRow label="Credential slots">
<div class="flex flex-col gap-2"> <div class="flex flex-col gap-2">
<div v-for="(slot, index) in forms[c.id].slots" :key="index" class="flex flex-wrap items-center gap-2"> <div v-for="(slot, index) in forms[c.id].slots" :key="index" class="flex flex-wrap items-center gap-2">
<Input v-model="slot.slot" placeholder="slot" class="w-40" aria-label="Credential slot" /> <Input v-model="slot.slot" placeholder="slot" class="w-40" aria-label="Credential slot" />
@@ -390,7 +388,7 @@ onBeforeUnmount(() => controller.abort());
<Button variant="outline" size="xs" class="self-start" @click="forms[c.id].slots.push({ slot: '', credential: '' })">Add slot</Button> <Button variant="outline" size="xs" class="self-start" @click="forms[c.id].slots.push({ slot: '', credential: '' })">Add slot</Button>
</div> </div>
</SettingRow> </SettingRow>
<SettingRow label="Settings" hint="The package's declared settings. A value it doesn't declare is refused."> <SettingRow label="Settings" hint="Use only setting keys declared by the extension.">
<div class="flex flex-col gap-2"> <div class="flex flex-col gap-2">
<div v-for="(pair, index) in forms[c.id].settingPairs" :key="index" class="flex flex-wrap items-center gap-2"> <div v-for="(pair, index) in forms[c.id].settingPairs" :key="index" class="flex flex-wrap items-center gap-2">
<Input v-model="pair.key" placeholder="key" class="w-40" aria-label="Setting key" /> <Input v-model="pair.key" placeholder="key" class="w-40" aria-label="Setting key" />
+3 -3
View File
@@ -14,8 +14,8 @@ import { TagsInput, TagsInputInput, TagsInputItem, TagsInputItemDelete, TagsInpu
import { getPeople, savePeople, Unauthorized, type Person } from "./api"; import { getPeople, savePeople, Unauthorized, type Person } from "./api";
/** /**
* The people who answer for the organisation. An approval from a channel * A response from a channel must be linked to a person before the server
* counts only when its identity is listed here. * checks whether that person can respond to the request.
*/ */
const emit = defineEmits<{ unauthorized: [] }>(); const emit = defineEmits<{ unauthorized: [] }>();
@@ -79,7 +79,7 @@ onBeforeUnmount(() => controller.abort());
<template v-else> <template v-else>
<Empty v-if="!people.length"> <Empty v-if="!people.length">
<EmptyHeader> <EmptyHeader>
<EmptyTitle>No one can answer approvals from a channel yet</EmptyTitle> <EmptyTitle>No people configured</EmptyTitle>
</EmptyHeader> </EmptyHeader>
</Empty> </Empty>
<Section v-for="(person, index) in people" :key="person.id || `new-${index}`"> <Section v-for="(person, index) in people" :key="person.id || `new-${index}`">
+3 -5
View File
@@ -15,9 +15,7 @@ import { TagsInput, TagsInputInput, TagsInputItem, TagsInputItemDelete, TagsInpu
import { listExtensions, listSources, putKeyFields, putSource, Unauthorized, type Extension, type SourceView } from "./api"; import { listExtensions, listSources, putKeyFields, putSource, Unauthorized, type Extension, type SourceView } from "./api";
/** /**
* Sources are the places events come from. A source names the connector that * The API returns a source token only when it is issued or rotated.
* parses its payloads; its token is the verification, and it is shown only
* when it is created or rotated.
*/ */
const emit = defineEmits<{ unauthorized: [] }>(); const emit = defineEmits<{ unauthorized: [] }>();
@@ -142,7 +140,7 @@ onBeforeUnmount(() => controller.abort());
</form> </form>
</Section> </Section>
<Section v-if="issued" title="Token" description="This is the only time it is shown."> <Section v-if="issued" title="Token" description="Copy the token now. You won't be able to retrieve it later.">
<div class="flex flex-col gap-2 sm:flex-row sm:items-center"> <div class="flex flex-col gap-2 sm:flex-row sm:items-center">
<Input :model-value="issued.token" readonly class="font-mono" aria-label="Source token" /> <Input :model-value="issued.token" readonly class="font-mono" aria-label="Source token" />
<div class="flex items-center gap-2"> <div class="flex items-center gap-2">
@@ -166,7 +164,7 @@ onBeforeUnmount(() => controller.abort());
<SettingRow label="Connector"> <SettingRow label="Connector">
<span class="text-label">{{ src.connector }}</span> <span class="text-label">{{ src.connector }}</span>
</SettingRow> </SettingRow>
<SettingRow label="Key fields" hint="Events sharing these field values group as one incident. Leave empty for the connector's default."> <SettingRow label="Key fields" hint="Events with matching values for these fields are grouped together. Leave blank to use the connector's defaults.">
<TagsInput v-model="keyFields[src.name]" class="font-mono"> <TagsInput v-model="keyFields[src.name]" class="font-mono">
<TagsInputItem v-for="path in keyFields[src.name]" :key="path" :value="path"> <TagsInputItem v-for="path in keyFields[src.name]" :key="path" :value="path">
<TagsInputItemText /> <TagsInputItemText />
+4 -5
View File
@@ -10,9 +10,8 @@ import { Spinner } from "@/components/ui/spinner";
import { getBootstrap, rotateAdminToken, Unauthorized, type BootstrapView } from "./api"; import { getBootstrap, rotateAdminToken, Unauthorized, type BootstrapView } from "./api";
/** /**
* The bootstrap values the binary reads before the database is reachable. They * Bootstrap settings are loaded before the database is available. The only
* are shown read-only because they come first; the admin token is the one that * bootstrap setting this page can change is the admin token.
* can be rotated here.
*/ */
const emit = defineEmits<{ unauthorized: [] }>(); const emit = defineEmits<{ unauthorized: [] }>();
@@ -72,7 +71,7 @@ onBeforeUnmount(() => controller.abort());
</script> </script>
<template> <template>
<Section title="System" description="Bootstrap values, read-only. Changing one means editing the config file and restarting."> <Section title="System" description="To change the settings below, edit the configuration file and restart Archie.">
<Spinner v-if="loading" /> <Spinner v-if="loading" />
<ReadError v-else-if="error && !bootstrap" :message="error" retry-label="Retry" @retry="load" /> <ReadError v-else-if="error && !bootstrap" :message="error" retry-label="Retry" @retry="load" />
<template v-else-if="bootstrap"> <template v-else-if="bootstrap">
@@ -97,7 +96,7 @@ onBeforeUnmount(() => controller.abort());
<Button variant="ghost" @click="issued = ''">Done</Button> <Button variant="ghost" @click="issued = ''">Done</Button>
</div> </div>
</div> </div>
<p v-if="issued" class="text-caption text-fg-subtle">This is the only time the token is shown.</p> <p v-if="issued" class="text-caption text-fg-subtle">Copy the token now. You won't be able to retrieve it later.</p>
</div> </div>
</template> </template>
</Section> </Section>
+4 -5
View File
@@ -14,8 +14,7 @@ import { Switch } from "@/components/ui/switch";
import { listSources, listTriggers, saveTrigger, Unauthorized, type SourceView, type TriggerView } from "./api"; import { listSources, listTriggers, saveTrigger, Unauthorized, type SourceView, type TriggerView } from "./api";
/** /**
* Triggers match an event, or an interval, to a workflow. A disabled trigger * Disabling a trigger keeps its configuration but stops it from starting runs.
* is kept and starts nothing.
*/ */
const emit = defineEmits<{ unauthorized: [] }>(); const emit = defineEmits<{ unauthorized: [] }>();
@@ -164,13 +163,13 @@ onBeforeUnmount(() => controller.abort());
<SettingRow label="Event type" for="trigger-event" hint="The event type the source's connector emits, such as alert.firing."> <SettingRow label="Event type" for="trigger-event" hint="The event type the source's connector emits, such as alert.firing.">
<Input id="trigger-event" v-model="draft.eventType" /> <Input id="trigger-event" v-model="draft.eventType" />
</SettingRow> </SettingRow>
<SettingRow label="Every" for="trigger-every" hint="An interval such as 1h fires on a schedule instead of on events. Source and type are then the schedule's own."> <SettingRow label="Every" for="trigger-every" hint="Set an interval to run on a schedule. Archie sets the source, event type and filter for scheduled triggers.">
<Input id="trigger-every" v-model="draft.every" placeholder="1h" /> <Input id="trigger-every" v-model="draft.every" placeholder="1h" />
</SettingRow> </SettingRow>
<SettingRow label="Workflow" for="trigger-workflow"> <SettingRow label="Workflow" for="trigger-workflow">
<Input id="trigger-workflow" v-model="draft.workflow" placeholder="investigate" /> <Input id="trigger-workflow" v-model="draft.workflow" placeholder="investigate" />
</SettingRow> </SettingRow>
<SettingRow label="Filter" hint="Every field must hold its value for the trigger to match."> <SettingRow label="Filter" hint="An event must match every field and value listed here.">
<div class="flex flex-col gap-2"> <div class="flex flex-col gap-2">
<div v-for="(pair, index) in draft.filter" :key="index" class="flex flex-wrap items-center gap-2"> <div v-for="(pair, index) in draft.filter" :key="index" class="flex flex-wrap items-center gap-2">
<Input v-model="pair.key" placeholder="field" class="w-40" aria-label="Filter field" /> <Input v-model="pair.key" placeholder="field" class="w-40" aria-label="Filter field" />
@@ -207,7 +206,7 @@ onBeforeUnmount(() => controller.abort());
<SettingRow label="Event type" :for="`${t.name}-type`"> <SettingRow label="Event type" :for="`${t.name}-type`">
<Input :id="`${t.name}-type`" v-model="drafts[t.name].eventType" /> <Input :id="`${t.name}-type`" v-model="drafts[t.name].eventType" />
</SettingRow> </SettingRow>
<SettingRow label="Every" :for="`${t.name}-every`" hint="Empty fires on events; an interval such as 1h fires on a schedule."> <SettingRow label="Every" :for="`${t.name}-every`" hint="Leave blank to match events, or set an interval to run on a schedule.">
<Input :id="`${t.name}-every`" v-model="drafts[t.name].every" placeholder="1h" /> <Input :id="`${t.name}-every`" v-model="drafts[t.name].every" placeholder="1h" />
</SettingRow> </SettingRow>
<SettingRow label="Workflow" :for="`${t.name}-workflow`"> <SettingRow label="Workflow" :for="`${t.name}-workflow`">
+1 -2
View File
@@ -28,7 +28,6 @@ import {
} from "./api"; } from "./api";
import { levelLabel } from "./state"; import { levelLabel } from "./state";
/** Unmatched events, each group with the draft it could become: summary, dry run and publish. */
const emit = defineEmits<{ unauthorized: [] }>(); const emit = defineEmits<{ unauthorized: [] }>();
const groups = ref<EventGroup[]>([]); const groups = ref<EventGroup[]>([]);
@@ -120,7 +119,7 @@ const filterText = (filter: Record<string, string>) =>
.join(" "); .join(" ");
const outcomeLabel = (a: DryAction) => const outcomeLabel = (a: DryAction) =>
({ ran: "Ran, read only", would_run: "Would run", would_ask: "Would ask", refused: "Refused" })[a.outcome]; ({ ran: "Read-only action ran", would_run: "Would run", would_ask: "Would request approval", refused: "Refused" })[a.outcome];
const outcomeTone = (a: DryAction) => const outcomeTone = (a: DryAction) =>
({ ran: "ok", would_run: "info", would_ask: "warn", refused: "danger" })[a.outcome] as "ok" | "info" | "warn" | "danger"; ({ ran: "ok", would_run: "info", would_ask: "warn", refused: "danger" })[a.outcome] as "ok" | "info" | "warn" | "danger";
const policyKinds = [ const policyKinds = [
+13 -13
View File
@@ -1,10 +1,9 @@
// The single binary's HTTP API. Until identities exist, every route sits // The dashboard keeps the bootstrap admin token in browser session storage.
// behind the bootstrap admin token, held for this browser session only.
const TOKEN_KEY = "archie.adminToken"; const TOKEN_KEY = "archie.adminToken";
export class Unauthorized extends Error {} export class Unauthorized extends Error {}
/** A failed request, with the status the server answered. */ /** A failed HTTP request with its response status. */
export class ApiError extends Error { export class ApiError extends Error {
readonly status: number; readonly status: number;
@@ -20,7 +19,7 @@ export const clearToken = () => sessionStorage.removeItem(TOKEN_KEY);
async function request(path: string, signal?: AbortSignal): Promise<Response> { async function request(path: string, signal?: AbortSignal): Promise<Response> {
const res = await fetch(path, { headers: { Authorization: `Bearer ${token()}` }, signal }); const res = await fetch(path, { headers: { Authorization: `Bearer ${token()}` }, signal });
if (res.status === 401) throw new Unauthorized("The admin token was refused."); if (res.status === 401) throw new Unauthorized("Sign in with a valid admin token.");
if (!res.ok) { if (!res.ok) {
const body = (await res.json().catch(() => ({}))) as { error?: string; detail?: string }; const body = (await res.json().catch(() => ({}))) as { error?: string; detail?: string };
throw new ApiError(body.detail ?? body.error ?? `${res.status} ${res.statusText}`, res.status); throw new ApiError(body.detail ?? body.error ?? `${res.status} ${res.statusText}`, res.status);
@@ -274,7 +273,7 @@ async function send<T>(method: string, path: string, payload?: unknown): Promise
headers: { Authorization: `Bearer ${token()}`, "Content-Type": "application/json" }, headers: { Authorization: `Bearer ${token()}`, "Content-Type": "application/json" },
body: payload === undefined ? undefined : JSON.stringify(payload), body: payload === undefined ? undefined : JSON.stringify(payload),
}); });
if (res.status === 401) throw new Unauthorized("The admin token was refused."); if (res.status === 401) throw new Unauthorized("Sign in with a valid admin token.");
if (!res.ok) { if (!res.ok) {
const body = (await res.json().catch(() => ({}))) as { error?: string; detail?: string }; const body = (await res.json().catch(() => ({}))) as { error?: string; detail?: string };
throw new ApiError(body.detail ?? body.error ?? `${res.status} ${res.statusText}`, res.status); throw new ApiError(body.detail ?? body.error ?? `${res.status} ${res.statusText}`, res.status);
@@ -307,7 +306,7 @@ export async function answerApproval(id: string, approved: boolean): Promise<voi
headers: { Authorization: `Bearer ${token()}`, "Content-Type": "application/json" }, headers: { Authorization: `Bearer ${token()}`, "Content-Type": "application/json" },
body: JSON.stringify({ approved }), body: JSON.stringify({ approved }),
}); });
if (res.status === 401) throw new Unauthorized("The admin token was refused."); if (res.status === 401) throw new Unauthorized("Sign in with a valid admin token.");
if (!res.ok) { if (!res.ok) {
const body = (await res.json().catch(() => ({}))) as { error?: string; detail?: string }; const body = (await res.json().catch(() => ({}))) as { error?: string; detail?: string };
throw new Error(body.detail ?? body.error ?? `${res.status} ${res.statusText}`); throw new Error(body.detail ?? body.error ?? `${res.status} ${res.statusText}`);
@@ -371,7 +370,7 @@ export async function resetClass(id: string): Promise<void> {
method: "POST", method: "POST",
headers: { Authorization: `Bearer ${token()}` }, headers: { Authorization: `Bearer ${token()}` },
}); });
if (res.status === 401) throw new Unauthorized("The admin token was refused."); if (res.status === 401) throw new Unauthorized("Sign in with a valid admin token.");
if (!res.ok) { if (!res.ok) {
const body = (await res.json().catch(() => ({}))) as { error?: string; detail?: string }; const body = (await res.json().catch(() => ({}))) as { error?: string; detail?: string };
throw new Error(body.detail ?? body.error ?? `${res.status} ${res.statusText}`); throw new Error(body.detail ?? body.error ?? `${res.status} ${res.statusText}`);
@@ -389,7 +388,7 @@ export interface EventGroup {
export const listGroups = (signal?: AbortSignal) => get<EventGroup[]>("/api/groups", signal); export const listGroups = (signal?: AbortSignal) => get<EventGroup[]>("/api/groups", signal);
/** What a dry run did with one action: only reads ran; everything else was judged and left alone. */ /** A dry-run decision and its outcome. Only read-only actions can run. */
export interface DryAction { export interface DryAction {
action: string; action: string;
target: string; target: string;
@@ -410,7 +409,7 @@ export interface DryReport {
at: string; at: string;
} }
/** The trigger, workflow and policy an unmatched group could become, with its latest dry run. */ /** A proposed trigger, workflow and policy, with the latest dry-run report. */
export interface Draft { export interface Draft {
id: string; id: string;
group_id: string; group_id: string;
@@ -460,7 +459,7 @@ const extensionPath: Record<ExtensionContract, string> = {
mcp: "mcp-servers", mcp: "mcp-servers",
}; };
/** An accepted package: what it is, whether it runs, and what it was given. */ /** An accepted extension's metadata, runtime status and configuration. */
export interface Extension { export interface Extension {
name: string; name: string;
contract: ExtensionContract; contract: ExtensionContract;
@@ -587,9 +586,10 @@ export const getCredential = (name: string, signal?: AbortSignal) =>
export const saveCredential = (name: string, kind: CredentialView["kind"], fields: Record<string, CredentialField>) => export const saveCredential = (name: string, kind: CredentialView["kind"], fields: Record<string, CredentialField>) =>
send<{ name: string; kind: string; restarted: string[] }>("PUT", `/api/credentials/${encodeURIComponent(name)}`, { kind, fields }); send<{ name: string; kind: string; restarted: string[] }>("PUT", `/api/credentials/${encodeURIComponent(name)}`, { kind, fields });
export const getAgentModel = (signal?: AbortSignal) => get<AgentModel>("/api/settings/agent-model", signal); export const listAgentModels = (signal?: AbortSignal) =>
export const saveAgentModel = (model: AgentModel) => get<Record<string, AgentModel>>("/api/settings/agent-models", signal);
send<AgentModel>("PUT", "/api/settings/agent-model", model); export const saveAgentModel = (alias: string, model: AgentModel) =>
send<AgentModel>("PUT", `/api/settings/agent-model?${new URLSearchParams({ alias })}`, model);
export const testAgentModel = (model: AgentModel) => export const testAgentModel = (model: AgentModel) =>
send<{ model: string; answer: string }>("POST", "/api/settings/agent-model/test", model); send<{ model: string; answer: string }>("POST", "/api/settings/agent-model/test", model);