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`
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.
- Comments say why, briefly. No migration history, phase names or issue
narration in code.
- Comments explain why, not what the code already says. No migration
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
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).
`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
- [Your first playbook](docs/guides/first-playbook.md)
+24
View File
@@ -211,6 +211,30 @@ tasks:
- task: dev:wait-state
- 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:
desc: Run Vite (requires the dashboard backend)
dir: ui
+1 -1
View File
@@ -133,7 +133,7 @@ _runs without a repository._
| `protect_tests` | bool | Write-block the repository test files. |
| `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. |
| `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`
+38 -1
View File
@@ -2445,7 +2445,7 @@ paths:
schema:
$ref: "#/components/schemas/ErrorModel"
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:
- Drafts
/api/drafts/{id}/publish:
@@ -3108,6 +3108,14 @@ paths:
/api/settings/agent-model:
get:
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:
"200":
content:
@@ -3126,6 +3134,14 @@ paths:
- Governance
put:
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:
content:
application/json:
@@ -3173,6 +3189,27 @@ paths:
summary: Ask a model one question before saving it
tags:
- 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:
get:
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
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
```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/cloudflare/circl v1.6.5 // 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/docker/go-connections v0.8.2 // 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/containerd/errdefs v1.0.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-git/v6 v6.0.0-beta.1
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/gliderlabs/ssh v0.3.8 h1:a4YXD1V7xMF9g5nTkdfnja3Sxy1PVDCj1Zg4Wb8vY6c=
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/go.mod h1:/lv2NsxvhepuMrldsFilrgct6pxzpGdSRC13ydTLSLs=
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"
)
// 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) {
registry := StepRegistry{
AgentRunStepName: newAgentRunStage,
+1
View File
@@ -37,6 +37,7 @@ type YAMLDefinition struct {
var repoFreeStepTypes = map[string]bool{
AgentRunStepName: true, WorkflowCallStepName: true, FinishStepName: true,
HandoffStepName: true, ApproveStepName: true, CloseIssueStepName: true, CommentStepName: true,
MessageSendStepName: true,
}
// 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
// person's answer, and the answer that settles it. A request is made when
// judgement holds an action at propose and wait, and an answer is an event in:
// it wakes the run waiting on that key, which then runs the action only if the
// 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 manages requests for human approval and records responses.
// A response to an action request resumes the waiting run. The request binds
// the approval to the decision ID and action digest so it cannot authorize a
// different action.
package approvals
import (
@@ -33,8 +29,8 @@ import (
"github.com/samcharles93/archie-core/modules/judgement"
)
// The states a request can be in. A settled request never changes again,
// except that an approval the action no longer matched is discarded.
// A settled request cannot be answered again. An approved request may still
// be discarded before the approval is counted.
const (
StatePending = "pending"
StateApproved = "approved"
@@ -72,12 +68,12 @@ const (
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 {
ID uuid.UUID
Kind string
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
Decision judgement.Decision
DecisionID uuid.UUID
@@ -89,11 +85,9 @@ type Request struct {
Level string
Summary string
State string
// Deadline is when the request runs out for good: the end of the last
// escalation step.
// Deadline applies to the whole request, not just the current escalation step.
Deadline time.Time
// Step is the escalation step the request is at, and StepDeadline when it
// moves on.
// Step and StepDeadline track the current escalation step and its deadline.
Step int
StepDeadline time.Time
// ChangeRequest is whether the request went through a change request
@@ -104,7 +98,7 @@ type Request struct {
AnsweredVia string
}
// Answer is what the run wakes with.
// Answer records the decision and who made it.
type Answer struct {
RequestID uuid.UUID `json:"request_id"`
Approved bool `json:"approved"`
@@ -113,12 +107,13 @@ type Answer struct {
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 {
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 {
ID uuid.UUID `json:"id"`
Kind string `json:"kind"`
@@ -129,11 +124,10 @@ type View struct {
Summary string `json:"summary"`
State string `json:"state"`
Deadline time.Time `json:"deadline"`
// Step is the escalation step the request is at, and StepDeadline when it
// moves to the next.
// Step and StepDeadline describe the current escalation step.
Step int `json:"step"`
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"`
RequestedAt time.Time `json:"requested_at"`
AnsweredBy string `json:"answered_by,omitzero"`
@@ -141,7 +135,7 @@ type View struct {
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 {
return View{
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
}
// Delivery carries a request to every channel someone can answer on.
// Delivery sends approval requests and publishes responses and notifications.
type Delivery interface {
Ask(ctx context.Context, a deliveries.ApprovalRequest) error
Told(ctx context.Context, a deliveries.ApprovalRequest, answer string) error
Notify(ctx context.Context, n deliveries.Notification) error
}
// Classes is where answers become autonomy: an approval counts toward raising
// an action class, a denial tightens it, and a raise a person approves
// loosens it.
// Classes updates action-class autonomy. Denials reduce autonomy; approvals
// count towards an increase that a person must approve separately.
type Classes interface {
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
@@ -174,14 +167,13 @@ type Classes interface {
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 {
ApprovalDeadline(ctx context.Context) (time.Duration, error)
RaiseAfter(ctx context.Context) (int, error)
}
// People says who an identity belongs to. An answer from an identity it
// doesn't verify is refused.
// People resolves verified channel identities to people.
type People interface {
Verify(ctx context.Context, identity string) (governance.Verified, bool, error)
}
@@ -200,10 +192,7 @@ type Module struct {
now func() time.Time
}
// NewModule returns the approvals module for orgID. Answers are delivered by
// 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.
// NewModule creates the approvals module for orgID.
func NewModule(db *sqlx.DB, log *slog.Logger, orgID string, tell Delivery, wake Signaller, classes Classes, policy Policy, people People) *Module {
return &Module{
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
// out for good when the last step does. Asking again for the same run and key
// returns the request that stands, so a replayed step asks once. An action
// judgement's change-request rules pick goes through a change request when a
// change-request connector is installed, and every other one through the
// approvers' channels.
// Ask reuses the request for the same run and key so retries do not create
// duplicate requests. It uses a change-request connector when judgement
// requires a change request and a connector is configured. Otherwise, it
// sends the request to the approval channels with the first step's deadline.
func (m *Module) Ask(ctx context.Context, runID uuid.UUID, key string, d judgement.Decision, path []governance.PathStep) (Request, error) {
if len(path) == 0 {
return Request{}, ErrNoPath
@@ -267,9 +254,6 @@ func (m *Module) Ask(ctx context.Context, runID uuid.UUID, key string, d judgeme
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) {
now := m.now().UTC()
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 {
return Request{}, err
}
// The run has what it waited for. A denial tightens the class now. An
// approval counts only once the action is about to run on it, so one that
// is discarded first counts for nothing.
// Count denials immediately. Defer counting approvals until execution
// is imminent so discarded approvals do not increase autonomy.
if !answer.Approved {
if err := m.classes.Denied(ctx, row.DecisionID); err != nil {
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
}
// 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 {
need, err := m.policy.RaiseAfter(ctx)
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)
}
// 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 {
class := r.Class
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 {
// Cancel the raise so a later approval can trigger another proposal.
if cerr := m.classes.CancelRaise(ctx, r.ID); cerr != nil {
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)
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{
RequestID: row.ID, Key: row.Key + ":ask", Title: "Raise answered",
}, 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 {
c := r.Class
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))
for _, e := range r.Evidence {
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()
}
// Settle answers a request from an answer a channel delivered as an event,
// given by identity (such as "telegram:1001"). An answer from an identity no
// person holds, or from a person who may not answer that kind of request, is
// refused and the refusal recorded with its reason. An answer that can't
// 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.
// Settle processes a response from a channel identity such as "telegram:1001".
// It records why it rejected an unverified or unauthorized response. It returns
// false without an error for recorded rejections and for requests that are
// missing, expired or already answered, since retrying won't help.
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)
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
}
// 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) {
who, ok, err := m.people.Verify(ctx, identity)
if err != nil {
@@ -446,7 +416,6 @@ func mayAnswer(who governance.Verified, row store.Request) error {
return nil
}
// askedOf is the ids of the people the request has reached.
func askedOf(row store.Request) []string {
var ids []string
if err := json.Unmarshal([]byte(row.Asked), &ids); err != nil {
@@ -455,16 +424,14 @@ func askedOf(row store.Request) []string {
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 {
return errors.Is(err, ErrUnverified) || errors.Is(err, ErrNotApprover) || errors.Is(err, ErrNoAuthority) ||
errors.Is(err, ErrNotAsked) || errors.Is(err, ErrNeedsAuthority)
}
// Expire settles a request whose last escalation step ran out, so the trail
// shows why it never ran. Nothing is acted on, an open change request is
// withdrawn, and the report goes to every channel. Expiry says nothing about
// the action's class, so it is not tightened.
// Expire records a timeout without reducing the action class's autonomy:
// receiving no response is not a denial.
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())
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{
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 {
return err
}
// The report goes to every channel. Its key is stable, so an Expire
// retried after a failed delivery sends it once.
// Use a stable key so retrying the expiry does not duplicate the notification.
return m.tell.Notify(ctx, deliveries.Notification{
RunID: row.RunID, Key: row.Key + ":expired",
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,
})
}
@@ -526,8 +492,7 @@ func (m *Module) ForRun(ctx context.Context, runID uuid.UUID) ([]Request, error)
return out, nil
}
// Outcomes says what became of the requests made for the decisions in ids,
// for the history of the action class they belong to.
// Outcomes returns approval outcomes by decision ID for the action class history.
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)
if err != nil {
@@ -560,9 +525,8 @@ func (m *Module) Register(api huma.API) {
}, m.answer)
}
// bootstrapAdmin names the identity the bootstrap admin token stands for. The
// token guard has already authenticated it, so it counts as a person with
// authority and skips the people check until real sign-in exists.
// The token guard authenticates the bootstrap admin before the API handler,
// so the handler does not look up a channel identity.
const bootstrapAdmin = "admin"
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
}
// 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) {
row, err := m.store.ByID(ctx, m.orgID, id)
if err != nil {
@@ -618,8 +579,6 @@ func (m *Module) pending(ctx context.Context, id uuid.UUID, now time.Time) (stor
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 {
switch {
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)
}
// Summary is what a person is shown about the action they are asked to allow:
// what it does, to what, and what held it back.
// Summary shows the approver the action, its target and why it requires approval.
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)
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
// 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 {
var fields map[string]jsontext.Value
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, ", ")
}
// requestOf is a stored row as the module's Request.
func requestOf(row store.Request, d judgement.Decision) Request {
r := Request{
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
}
// TestVerifyAcceptsAnAnswerOnlyFromAPersonWhoMayGiveIt guards the rule that an
// approval counts only from a verified identity, on every channel: an identity
// no person holds, a person without the standing for that kind of request, a
// 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.
// TestVerifyAcceptsAnAnswerOnlyFromAPersonWhoMayGiveIt checks that a verified
// identity alone is not enough: the request kind, escalation step and required
// authority also determine who can respond.
func TestVerifyAcceptsAnAnswerOnlyFromAPersonWhoMayGiveIt(t *testing.T) {
people := fakePeople{
"telegram:1001": {ID: "owner", Name: "Owner", Approver: true},
@@ -41,18 +39,18 @@ func TestVerifyAcceptsAnAnswerOnlyFromAPersonWhoMayGiveIt(t *testing.T) {
row store.Request
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 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: "the target's owner answers when the request was put to them", 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: "authority answers 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 person on the path answers once the request reaches them", identity: "telegram:1004", row: action(propose, "owner", "second")},
{name: "authority answers before it is 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: "authority answers an action at escalate", identity: "telegram:1002", row: action(escalate, "owner")},
{name: "an unlisted person who isn't an approver cannot respond", identity: "telegram:1003", row: action(propose, "owner"), wantErr: ErrNotApprover},
{name: "the target owner can respond when explicitly asked", identity: "telegram:1003", row: action(propose, "bystander")},
{name: "an approver without authority cannot respond to a raise", identity: "telegram:1001", row: store.Request{Kind: KindRaise}, wantErr: ErrNoAuthority},
{name: "a person with authority can respond to a raise", identity: "telegram:1002", row: store.Request{Kind: KindRaise}},
{name: "a later approver cannot respond before escalation", identity: "telegram:1004", row: action(propose, "owner"), wantErr: ErrNotAsked},
{name: "a later approver can respond after escalation", identity: "telegram:1004", row: action(propose, "owner", "second")},
{name: "a person with authority can respond without being asked", identity: "telegram:1002", row: action(propose, "owner")},
{name: "the escalate level requires authority even when the approver was asked", identity: "telegram:1001", row: action(escalate, "owner"), wantErr: ErrNeedsAuthority},
{name: "a person with authority can respond at the escalate level", identity: "telegram:1002", row: action(escalate, "owner")},
}
m := &Module{people: people}
for _, tt := range tests {
@@ -68,9 +66,8 @@ func TestVerifyAcceptsAnAnswerOnlyFromAPersonWhoMayGiveIt(t *testing.T) {
}
}
// TestSettleableRefusesASecondAnswerOrALateOne guards the rule that makes an
// approval one decision: the first answer settles a request, so a replaying
// answer or one that arrives after the deadline wakes no run and runs nothing.
// TestSettleableRefusesASecondAnswerOrALateOne checks that a settled request or
// one at its deadline cannot accept a response.
func TestSettleableRefusesASecondAnswerOrALateOne(t *testing.T) {
deadline := time.Date(2026, 11, 16, 12, 0, 0, 0, time.UTC)
request := func(state string) store.Request {
@@ -82,8 +79,8 @@ func TestSettleableRefusesASecondAnswerOrALateOne(t *testing.T) {
now time.Time
wantErr error
}{
{name: "a pending request settles inside its 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 accepts a response before the deadline", row: request(StatePending), now: deadline.Add(-time.Minute)},
{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: "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},
+14 -20
View File
@@ -12,24 +12,20 @@ import (
"github.com/samcharles93/archie-core/modules/governance"
)
// ChangeRequests is a change-request connector. Judgement's change-request
// rules decide which held actions need one; this opens and withdraws them.
// ChangeRequests manages external change requests for actions that require them.
type ChangeRequests interface {
// Open raises the change request for r. It may be called again for the same
// request and must not open a second one.
// Open must be idempotent for the same approval request.
Open(ctx context.Context, r Request) error
// Withdraw withdraws r's change request if it is still open.
Withdraw(ctx context.Context, r Request) error
}
// UseChangeRequests makes the module open the change requests judgement asks
// for through c. Without one, those approvals go to the approvers' channels,
// so a rule never strands a request where nobody can answer it.
// UseChangeRequests configures the change-request connector. Without one,
// approval requests still go to the approvers' channels.
func (m *Module) UseChangeRequests(c ChangeRequests) { m.changes = c }
// Escalate passes a pending request to step n of its path, telling every
// channel who it has reached and until when. The step's deadline runs from
// now. A request that has since been answered is left alone.
// Escalate advances a pending request to step n. It sets the step's deadline
// relative to the time of escalation.
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)
if err != nil {
@@ -43,12 +39,12 @@ func (m *Module) Escalate(ctx context.Context, id uuid.UUID, n int, to governanc
if to.Name != "" {
who = to.Name
}
// The notice goes first and is idempotent by key, so an escalation retried
// after the move failed still tells people once.
// Send the notice before updating the request. If the update fails,
// retrying with the same key won't duplicate the notice.
if err := m.tell.Notify(ctx, deliveries.Notification{
RunID: row.RunID, Key: row.Key + ":escalated:" + strconv.Itoa(n),
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 {
return err
}
@@ -59,9 +55,8 @@ func (m *Module) Escalate(ctx context.Context, id uuid.UUID, n int, to governanc
return nil
}
// Accept counts an approval toward raising its action class, once, when the
// action it covers is about to run. An approval that is discarded first never
// counts.
// Accept counts an approval towards an increase in autonomy just before the
// action runs. Each approval counts at most once; discarded approvals do not count.
func (m *Module) Accept(ctx context.Context, id uuid.UUID) error {
row, counted, err := m.store.Count(ctx, m.orgID, id)
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
// says why. A discarded approval doesn't count toward a raise, and a request
// for the changed action is a new one.
// Discard records why an approval is no longer valid and notifies the approval
// channels. A discarded approval cannot count towards a raise.
func (m *Module) Discard(ctx context.Context, id uuid.UUID, because string) error {
row, discarded, err := m.store.Discard(ctx, m.orgID, id, because)
if err != nil || !discarded {
@@ -90,5 +84,5 @@ func (m *Module) Discard(ctx context.Context, id uuid.UUID, because string) erro
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")
+18 -23
View File
@@ -1,5 +1,4 @@
// Package store holds the approvals module's SQL: the requests waiting for an
// answer, and what was answered.
// Package store persists approval requests, responses and rejections.
package store
import (
@@ -13,19 +12,17 @@ import (
"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 {
ID uuid.UUID `db:"id"`
OrgID string `db:"org_id"`
RunID uuid.UUID `db:"run_id"`
Key string `db:"key"`
// DecisionID is the judged action the request is about, or for a raise
// request the raise.
// DecisionID identifies the judgement decision or the proposed raise.
DecisionID uuid.UUID `db:"decision_id"`
Kind string `db:"kind"`
Digest string `db:"digest"`
// The action's own names, kept so a request reads back without its
// decision.
// Copy the action details so the request can be read without loading the decision.
Connector string `db:"connector"`
Action string `db:"action"`
TargetKind string `db:"target_kind"`
@@ -38,9 +35,8 @@ type Request struct {
AnsweredAt sql.NullTime `db:"answered_at"`
AnsweredBy sql.NullString `db:"answered_by"`
AnsweredVia sql.NullString `db:"answered_via"`
// Step is the escalation step the request is at, StepDeadline when that
// step runs out, and Asked a JSON array of the ids of the people it has
// reached so far.
// Asked is a JSON array of person IDs reached so far, not just the
// person assigned to the current step.
Step int `db:"step"`
StepDeadline sql.NullTime `db:"step_deadline"`
Asked string `db:"asked"`
@@ -48,8 +44,7 @@ type Request struct {
// rather than the approvers' channels.
ChangeRequest bool `db:"change_request"`
// Counted is whether the approval was counted toward raising its class.
Counted bool `db:"counted"`
// DiscardedBecause is why an approval no longer stood.
Counted bool `db:"counted"`
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,
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
// returns the request that stands either way.
// Put inserts r or returns the existing request for the same organisation,
// run and key.
func (s *Store) Put(ctx context.Context, r Request) (Request, error) {
var out Request
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
}
// Answer settles one request, and only while it is still pending. It returns
// the request as it now stands, or the one that already settled it.
// Answer updates only pending requests. If another response already settled
// 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) {
var out Request
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
}
// Escalate moves a pending request to step, which has reached person and runs
// out at until. It returns false when the request is no longer pending, or has
// already moved that far, so a replayed escalation changes nothing.
// Escalate advances a pending request to step, sets the deadline to until and
// records person if supplied. It returns false if the request has already
// 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) {
var out Request
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
}
// Discard withdraws an approval that no longer stands, and only while it has
// not been counted. It returns false when there was nothing to discard.
// Discard invalidates an approval only if it has not yet been counted.
// 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) {
var out Request
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
}
// Count marks an approval as counted, once. It returns false when the approval
// was already counted or no longer stands.
// Count marks a valid action approval as counted. It returns false if no
// eligible approval was updated.
func (s *Store) Count(ctx context.Context, orgID string, id uuid.UUID) (Request, bool, error) {
var out Request
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
// trigger it proposes, the workflow that trigger would start and any policy
// that workflow needs, with a plain-language summary and a dry run. Nothing in
// a draft is in force until it is published.
// Package drafts manages proposed triggers, workflows and policies for groups
// of unmatched events. Drafts can be tested by replaying a stored event in a
// dry run before the trigger is enabled.
package drafts
import (
@@ -28,11 +27,10 @@ import (
"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
// Groups is where a draft finds the unmatched events it is made from, and
// where its trigger is saved.
// Groups provides unmatched event groups, replay tracking and trigger storage.
type Groups interface {
Group(ctx context.Context, id uuid.UUID) (events.Group, bool, 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
}
// Workflows stores workflow documents and runs them dry.
// Workflows installs workflow documents and manages dry runs.
type Workflows interface {
Install(ctx context.Context, orgID, name, body, by string) (int, 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)
}
// 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 {
Check(ctx context.Context, kind, extra string) 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)
huma.Register(api, huma.Operation{
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)
huma.Register(api, huma.Operation{
OperationID: "publish-draft", Method: http.MethodPost, Path: "/api/drafts/{id}/publish",
@@ -102,7 +101,7 @@ type idInput struct {
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 {
ID uuid.UUID `json:"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 string `json:"policy"`
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"`
DryEventID *uuid.UUID `json:"dry_event_id,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"}
)
// 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 {
var filter map[string]string
_ = json.Unmarshal(d.Filter, &filter)
@@ -197,7 +194,8 @@ func summarize(d store.Draft) 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 {
slug := strings.Trim(nameChars.ReplaceAllString(strings.ToLower(g.Source+"-"+g.EventType), "-"), "-")
if len(slug) > 50 {
@@ -222,12 +220,12 @@ func (m *Module) list(ctx context.Context, _ *struct{}) (*httpapi.Reply[[]View],
return httpapi.OK(out), nil
}
// create makes a group's draft, or returns the one it has. A new draft
// proposes the group's trigger and a copy of the investigate workflow.
// create reuses an existing group draft rather than replacing any edits
// with the default investigation workflow.
func (m *Module) create(ctx context.Context, in *idInput) (*httpapi.Reply[View], error) {
id, err := uuid.Parse(in.ID)
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)
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) {
d, err := m.draft(ctx, in.ID)
if err != nil {
@@ -295,7 +291,6 @@ func (m *Module) edit(ctx context.Context, in *editInput) (*httpapi.Reply[View],
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 {
if !validName.MatchString(name) {
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
// in dry mode: the newest by default.
// dryRun tests the draft workflow and policy against a stored event. If the
// 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) {
d, err := m.draft(ctx, in.ID)
if err != nil {
@@ -372,7 +367,7 @@ func (m *Module) dryRun(ctx context.Context, in *dryRunInput) (*httpapi.Reply[Vi
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) {
for _, e := range stored {
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
}
// publish puts a draft in force: its policy is added to the set, its workflow
// is installed as the next version, and last its trigger is saved, so nothing
// fires before the rules that govern it exist. A retry after a failure carries
// on from where it stopped.
// publish installs the policy and workflow before saving the trigger so the
// trigger cannot fire before both are available. A recorded workflow version
// lets a retry skip the name-conflict check. The retry still calls the policy
// and workflow installers, which avoid duplicating unchanged content.
func (m *Module) publish(ctx context.Context, in *idInput) (*httpapi.Reply[View], error) {
d, err := m.draft(ctx, in.ID)
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) {
id, err := uuid.Parse(rawID)
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)
switch {
+9 -9
View File
@@ -17,7 +17,7 @@ import (
// ErrNotFound means 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")
// Draft is one stored draft.
@@ -34,7 +34,8 @@ type Draft struct {
Policy string `db:"policy"`
DryRunID uuid.NullUUID `db:"dry_run_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"`
PublishedAt sql.NullTime `db:"published_at"`
CreatedAt time.Time `db:"created_at"`
@@ -52,8 +53,7 @@ type Store struct {
// New returns a store on 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
// the group has.
// Create inserts a draft or returns the existing draft for the group.
func (s *Store) Create(ctx context.Context, d Draft) (Draft, error) {
_, err := s.db.ExecContext(ctx, `
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
}
// Edit replaces what a person edits of an unpublished draft. A dry run made of
// an earlier version no longer describes it, so it is cleared.
// Edit updates an unpublished draft and clears its dry-run references because
// 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 {
res, err := s.db.ExecContext(ctx, `
UPDATE drafts.drafts
@@ -118,7 +118,7 @@ func (s *Store) Edit(ctx context.Context, orgID string, id uuid.UUID, name, docu
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 {
if _, err := s.db.ExecContext(ctx, `
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
}
// 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 {
if _, err := s.db.ExecContext(ctx, `
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
}
// 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 {
if _, err := s.db.ExecContext(ctx, `
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"`
OriginRunID uuid.NullUUID `db:"origin_run_id"`
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
+77 -8
View File
@@ -13,7 +13,9 @@ import (
"log/slog"
"net/http"
"net/url"
"regexp"
"slices"
"strings"
"time"
"github.com/danielgtaylor/huma/v2"
@@ -29,7 +31,27 @@ import (
// is no built-in default.
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
// 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.
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 {
return Model{}, err
}
if !ok {
if key != roleAgent {
return Model{}, fmt.Errorf("agent model alias %q: %w", alias, ErrNoAgentModel)
}
return Model{}, ErrNoAgentModel
}
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",
Summary: "Change the organisation settings", Tags: tags,
}, 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{
OperationID: "get-agent-model", Method: http.MethodGet, Path: "/api/settings/agent-model",
Summary: "Get the agent model", Tags: tags,
@@ -495,8 +533,32 @@ func (s Settings) knows(people []store.Person) error {
return nil
}
func (m *Module) getAgentModel(ctx context.Context, _ *struct{}) (*httpapi.Reply[Model], error) {
model, err := m.AgentModel(ctx)
func (m *Module) listAgentModels(ctx context.Context, _ *struct{}) (*httpapi.Reply[map[string]Model], error) {
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 {
case errors.Is(err, ErrNoAgentModel):
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
// published default, and the stored value is always explicit.
func (m *Module) putAgentModel(ctx context.Context, in *struct{ Body Model }) (*httpapi.Reply[Model], error) {
type agentModelInput struct {
Alias string `query:"alias" doc:"Agent model alias; omit for the default model"`
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
model, err := settle(req)
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())
}
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,
}); err != nil {
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
}
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.
func (s *Store) PutModelRole(ctx context.Context, m ModelRole) error {
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
// raised from them.
// Package store persists incident history and proposals for root-cause fixes.
package store
import (
@@ -11,7 +10,7 @@ import (
"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 {
ID uuid.UUID `db:"id"`
RunID uuid.UUID `db:"run_id"`
@@ -24,7 +23,7 @@ type Incident struct {
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 {
ID uuid.UUID `db:"id"`
TargetKind string `db:"target_kind"`
@@ -42,8 +41,8 @@ type Store struct {
// New returns a store on 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
// same run recorded.
// Upsert inserts an incident or updates the target, cause and summary for
// the same organisation and run. It preserves the original event and timestamp.
func (s *Store) Upsert(ctx context.Context, orgID string, in Incident) error {
if _, err := s.db.ExecContext(ctx, `
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
}
// 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 {
if _, err := s.db.ExecContext(ctx, `
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
}
// Propose records p unless the target and cause already have one, and returns
// the one that stands.
// Propose stores one proposal per organisation, target and cause. If one
// 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) {
var out Proposal
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
// investigated on it, the cause found, and what was done about it. A cause that
// keeps coming back on a target, whatever became of each attempt to handle it,
// raises a proposal for a root-cause fix.
// Package memory records investigated incidents by target, including their
// causes and action outcomes. When a cause reaches the recurrence threshold
// for a target, the module proposes a root-cause fix regardless of action outcomes.
package memory
import (
@@ -28,17 +27,17 @@ const maxHistory = 200
// MaxRecurrence is the largest recurrence threshold the history can confirm.
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 {
Kind string `json:"kind"`
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 {
Action string `json:"action"`
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"`
Detail string `json:"detail,omitzero"`
}
@@ -51,7 +50,7 @@ type Incident struct {
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 {
line := fmt.Sprintf("- %s, cause %q: %s", i.At.Format("2006-01-02"), i.Cause, i.Summary)
if len(i.Actions) == 0 {
@@ -68,17 +67,16 @@ func (i Incident) Line() string {
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 {
// Repeats is how many incidents on the target have this cause, this one
// included.
// Repeats counts matching incidents in the target's recent history,
// including the current incident if it is in that history.
Repeats int
// Proposal is the root-cause fix asked for, empty until the cause has
// recurred enough.
// Proposal is the text of the request for a root-cause fix. It is empty
// below the recurrence threshold.
Proposal string
}
// ledger is where incidents and proposals are kept.
type ledger interface {
Upsert(ctx context.Context, orgID string, in store.Incident) 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)
}
// Module remembers one organisation's incidents.
// Module manages incident history and proposals for one organisation.
type Module struct {
orgID string
ledger ledger
@@ -100,14 +98,14 @@ func NewModule(db *sqlx.DB, orgID string) *Module {
var unsafeCause = regexp.MustCompile(`[^a-z0-9]+`)
// Cause is a cause as it is compared: lower case words joined by hyphens, so
// "Disk pressure" and "disk-pressure" are one cause.
// Cause normalises labels for comparison: "Disk pressure" and "disk-pressure"
// both produce "disk-pressure".
func Cause(s string) string {
return strings.Trim(unsafeCause.ReplaceAllString(strings.ToLower(s), "-"), "-")
}
// Record remembers what a run's investigation found: the event, the target it
// concerned and the cause. Recording again replaces the earlier attempt's.
// Record saves the incident for a run. Recording it again updates the target,
// 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 {
t = Target{Kind: strings.TrimSpace(t.Kind), ID: strings.TrimSpace(t.ID)}
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) {
rows, err := m.ledger.ByTarget(ctx, m.orgID, strings.TrimSpace(t.Kind), strings.TrimSpace(t.ID), maxHistory)
if err != nil {
@@ -143,10 +141,9 @@ func (m *Module) Past(ctx context.Context, runID uuid.UUID, t Target) ([]Inciden
return out, nil
}
// Finish remembers what was done in a run's incident and checks whether its
// cause has come back enough to ask for a root-cause fix: that is when
// threshold incidents on the target share the cause, whatever their outcomes.
// A run that recorded no incident has nothing to finish.
// Finish records action outcomes. It requests a root-cause fix if at least
// threshold incidents in the target's recent history share the current cause,
// regardless of their action outcomes. A run with no recorded incident is ignored.
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)
if err != nil || !ok {
@@ -194,8 +191,8 @@ func incident(r store.Incident) (Incident, error) {
return out, nil
}
// proposalBody asks for the cause to be fixed rather than handled again. same
// is newest first.
// proposalBody expects matching incidents in newest-first order so it can
// report the date of the oldest match.
func proposalBody(current store.Incident, same []store.Incident) string {
var tried []string
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"))
if len(tried) > 0 {
body += " Handled so far with: " + strings.Join(tried, "; ") + "."
body += " Recorded actions: " + strings.Join(tried, "; ") + "."
}
return body
}
+4 -5
View File
@@ -38,9 +38,8 @@ func (f *fakeLedger) Propose(_ context.Context, _ string, p store.Proposal) (sto
return p, nil
}
// TestFinishProposesOnRecurrence guards the rule that a cause seen threshold
// times on a target raises a root-cause fix, whatever happened to the actions
// taken in each incident, and that other causes don't count towards it.
// TestFinishProposesOnRecurrence checks that only incidents with the same
// cause count towards the configured threshold, even if an action was denied.
func TestFinishProposesOnRecurrence(t *testing.T) {
now := time.Date(2026, 11, 16, 0, 0, 0, 0, time.UTC)
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},
{"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},
{"the threshold is the organisation's", 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},
{"uses the organisation's threshold", incidents("disk-pressure", "disk-pressure", "disk-pressure"), 3, true},
{"proposes above the threshold", incidents("disk-pressure", "disk-pressure", "disk-pressure", "disk-pressure", "disk-pressure", "disk-pressure"), 5, true},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
+34 -1
View File
@@ -2,6 +2,7 @@ package runs
import (
"context"
"encoding/json/jsontext"
"errors"
"github.com/samcharles93/ai-sdk/agentloop"
@@ -22,6 +23,11 @@ type AgentRequest struct {
Prompt string
Tools core.ToolSet
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.
@@ -33,6 +39,9 @@ type AgentResult struct {
Steps int `json:"steps"`
ToolCalls int `json:"tool_calls"`
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
@@ -76,6 +85,30 @@ func (rc *Context) Agent(req AgentRequest) (AgentResult, error) {
if err := rc.ctx.Err(); err != nil {
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
}
@@ -86,7 +119,7 @@ func retryModel(p chat.Provider) chat.Provider {
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 {
*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"
"errors"
"log/slog"
"os"
"slices"
"strings"
"sync"
"testing"
@@ -14,9 +16,98 @@ import (
"github.com/samcharles93/ai-sdk/chat"
"github.com/samcharles93/ai-sdk/core"
"github.com/samcharles93/archie-core/modules/governance"
"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
// tool's result is in the history.
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)
}
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
// retry.
// resultFields are the result fields a step's type declares, or nil when it
// 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) {
if s.OnFailure != "" && s.OnFailure != onFailurePark && s.OnFailure != onFailureContinue {
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: "feasibility waits for repositories, switch, approve and agent results", file: "feasibility",
want: slices.Concat(notYet("repo.prepare", "workflow.approve"), agentLater("read_only", "result", "read_only", "result"),
name: "feasibility waits for repositories, switch and approve", file: "feasibility",
want: slices.Concat(notYet("repo.prepare", "workflow.approve"),
[]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"),
agentLater("read_only", "gate", "extra_rules")),
agentLater("gate")),
},
{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")),
},
{
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"),
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",
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",
+11 -11
View File
@@ -15,13 +15,12 @@ import (
//go:embed workflows/investigate.yaml
var investigateDocument string
// InvestigateDocument is the workflow document that has an agent look into the
// event that started the run, put what it proposes to people, and report.
// InvestigateDocument defines the default workflow for investigating an event,
// requesting approval for proposed actions and reporting the findings.
func InvestigateDocument() string { return investigateDocument }
// Document is a workflow as data: what it declares to whatever starts it, and
// the ordered steps the engine executes. It is stored, diffed and validated as
// text.
// Document defines a workflow's interface and ordered steps. The engine
// stores, compares and validates workflow definitions as text.
type Document struct {
Interface `yaml:",inline"`
Steps []Step `yaml:"steps"`
@@ -68,8 +67,8 @@ const (
onFailureContinue = "continue"
)
// name is what a step's work is recorded under: its id, else its type and
// position, which a pinned document keeps stable.
// name returns the journal name. Steps without an ID use their type and
// position, which stay stable because the run pins its workflow version.
func (s Step) name(index int) string {
if s.ID != "" {
return s.ID
@@ -77,7 +76,7 @@ func (s Step) name(index int) string {
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 {
Path string `json:"path"`
Message string `json:"message"`
@@ -85,7 +84,7 @@ type Problem struct {
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 {
Problems []Problem `json:"problems"`
}
@@ -174,7 +173,7 @@ func decodeSettings(settings yaml.Node, target any) error {
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 {
out := make([]string, 0, len(d.Steps))
for _, s := range d.Steps {
@@ -191,7 +190,8 @@ func (d Document) Describe() []string {
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 {
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"
)
// dryOverlay is what a dry run carries instead of a stored workflow version:
// the document it runs, and the policy it is judged under as if published.
// dryOverlay contains the workflow document and policy a dry run tests as
// if they were published.
type dryOverlay struct {
Document string `json:"document"`
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}
}
// readOverlay decodes the overlay a dry run carries.
func readOverlay(raw jsontext.Value) (*dryOverlay, error) {
var o dryOverlay
if err := json.Unmarshal(raw, &o); err != nil {
@@ -41,12 +40,10 @@ func readOverlay(raw jsontext.Value) (*dryOverlay, error) {
return &o, nil
}
// Dry reports whether the run is a dry run: every action is judged and none
// that changes something is executed, nobody is asked and nothing is sent.
// Dry reports whether the run is a dry run. Dry runs evaluate actions but
// execute only read-only actions, and send no approval requests or notifications.
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 {
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
// that doesn't validate starts nothing.
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
}
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"`
}
// 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 {
RunID uuid.UUID `json:"run_id"`
State string `json:"state"`
@@ -135,8 +132,8 @@ type DryReport struct {
At time.Time `json:"at"`
}
// DryReport reads what dry run id did so far. ok is false when there is no
// such dry run.
// DryReport returns the results recorded so far. It reports ok=false if the
// 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) {
run, found, err := e.db.Detail(ctx, orgID, id)
if err != nil || !found || !run.Dry {
@@ -205,7 +202,7 @@ func pathNames(path []governance.PathStep) []string {
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) {
held, err := heldSince(rc, judge, settled)
if err != nil {
+8 -10
View File
@@ -15,10 +15,8 @@ import (
"github.com/samcharles93/archie-core/modules/runs/internal/store"
)
// TestAfterApprovalDiscardsAnApprovalThatNoLongerMatchesTheAction guards the
// rule that an approval covers the action as it was shown: when something else
// 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.
// TestAfterApprovalDiscardsAnApprovalThatNoLongerMatchesTheAction checks that
// a changed target or effect, or a stricter verdict, invalidates the approval.
func TestAfterApprovalDiscardsAnApprovalThatNoLongerMatchesTheAction(t *testing.T) {
decided := func(level judgement.Level, mutate func(*judgement.Decision)) judgement.Decision {
d := judgement.Decision{Level: level, Action: judgement.Action{
@@ -36,15 +34,15 @@ func TestAfterApprovalDiscardsAnApprovalThatNoLongerMatchesTheAction(t *testing.
fresh judgement.Decision
want afterwards
}{
{name: "an unchanged action runs on its 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 changed target is put to people again", fresh: decided(judgement.ProposeAndWait, func(d *judgement.Decision) {
{name: "an unchanged action uses the existing approval", fresh: decided(judgement.ProposeAndWait, nil), want: runApproval},
{name: "a stricter verdict requires new approval", fresh: decided(judgement.Escalate, nil), want: reaskPerson},
{name: "a changed target requires new approval", fresh: decided(judgement.ProposeAndWait, func(d *judgement.Decision) {
d.Action.Target.ID = "db"
}), 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"
}), 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"
}), want: reaskPerson},
{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: "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 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 {
t.Run(tt.name, func(t *testing.T) {
+3 -2
View File
@@ -50,8 +50,9 @@ type Run struct {
Attempts int `db:"attempts"`
// Dry marks a dry run, and Overlay is the document and policy it runs
// under; a dry run pins no stored version.
Dry bool `db:"dry"`
Overlay jsontext.Value `db:"overlay"`
Dry bool `db:"dry"`
// Scan into []byte because live runs have a SQL NULL overlay.
Overlay []byte `db:"overlay"`
}
// Step is one recorded step of a run.
+117 -58
View File
@@ -12,6 +12,7 @@ import (
"strings"
"time"
"github.com/google/jsonschema-go/jsonschema"
"github.com/google/uuid"
"github.com/samcharles93/ai-sdk/agentloop"
"github.com/samcharles93/ai-sdk/chat"
@@ -27,10 +28,9 @@ import (
"github.com/samcharles93/archie-core/modules/runs/internal/store"
)
// Settings is where a workflow finds what the organisation decided: the agent
// model it runs, and the escalation path an approval request takes.
// Settings provides the organisation's model configuration and escalation policy.
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
// credential it names. The model is journaled; the client is rebuilt.
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)
}
// Approver asks people to allow an action judgement held, moves a request
// that nobody answered to the next step of its path, and settles one whose last
// step ran out. An approval is counted when the action is about to run on it,
// and discarded when the action no longer matches it.
// Approver requests approval for actions held by judgement, escalates
// unanswered requests and expires them after the final deadline. An approval
// counts towards an increase in autonomy only when the action is about to run
// using it. If reassessment invalidates the approval, it is discarded instead.
type Approver interface {
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
@@ -106,14 +106,18 @@ type Deps struct {
// and the results of earlier steps.
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
// with the same tools even if settings or connectors changed meanwhile.
type pinnedModel struct {
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 {
model governance.Model
models map[string]pinnedModel
threshold int
decls []connectors.Declaration
provider chat.Provider
info chat.ModelInfo
}
// 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
// dry run (rc.Dry) judges every action and executes only those that read.
func (d Deps) Compile(doc Document) Workflow {
agent, withMemory := agentUse(doc)
aliases, withMemory := agentUse(doc)
settleAtEnd := heldAfterLastApproval(doc)
return func(rc *Context, input jsontext.Value) (jsontext.Value, error) {
p := &progress{
input: input, inputs: decodeInputs(input), instructions: doc.Instructions,
results: map[string]StepResult{}, outcomes: []approvalOutcome{}, settled: map[string]bool{},
}
if agent {
if err := d.pin(rc, p, withMemory); err != nil {
if len(aliases) > 0 {
if err := d.pin(rc, p, aliases, withMemory); err != nil {
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
// from the run's inputs and earlier results, and keeps what it leaves under its
// id.
// runStep resolves settings from the run's inputs and earlier results, and
// saves the result under the step ID if the step runs.
func (d Deps) runStep(rc *Context, p *progress, s Step, index int) error {
name := s.name(index)
values := scope(p.inputs, p.results)
@@ -214,19 +217,28 @@ func stepFailed(err error) bool {
return true
}
// agentUse reports whether any step runs an agent, and whether one uses memory.
func agentUse(doc Document) (agent, withMemory bool) {
func agentUse(doc Document) (aliases []string, withMemory bool) {
for _, s := range doc.Steps {
if s.Type != typeAgent {
continue
}
agent = true
var settings agentSettings
if decodeSettings(s.Settings, &settings) == nil && settings.Memory {
withMemory = true
if decodeSettings(s.Settings, &settings) == nil {
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
@@ -254,19 +266,29 @@ func decodeInputs(input jsontext.Value) map[string]any {
return out
}
func (d Deps) pin(rc *Context, p *progress, withMemory bool) error {
model, err := rc.Step("agent-model", func(ctx context.Context, _ string) (governance.Model, error) {
return d.Settings.AgentModel(ctx)
})
if err != nil {
return err
}
if withMemory {
if p.pin.threshold, err = rc.Step("recurrence-threshold", func(ctx context.Context, _ string) (int, error) {
return d.Settings.RecurrenceThreshold(ctx)
}); err != nil {
func (d Deps) pin(rc *Context, p *progress, aliases []string, withMemory bool) error {
models := make(map[string]pinnedModel, len(aliases))
for _, alias := range aliases {
step := "agent-model"
if alias != "" {
step += ":" + alias
}
model, err := rc.Step(step, func(ctx context.Context, _ string) (governance.Model, error) {
return d.Settings.AgentModelForAlias(ctx, alias)
})
if err != nil {
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) {
return d.Toolbox.Declarations(), nil
@@ -274,11 +296,14 @@ func (d Deps) pin(rc *Context, p *progress, withMemory bool) error {
if err != nil {
return err
}
provider, info, err := d.Settings.AgentProvider(rc.Context(), model)
if err != nil {
return err
for _, alias := range aliases {
m := models[alias]
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
}
@@ -292,34 +317,54 @@ func agentSystem(instructions, mission string) string {
return strings.Join(append(parts, mission), "\n\n")
}
// runAgent has an agent work on its mission with the run's inputs. An action
// it proposes is judged as it calls it; the ones judgement holds wait for an
// approval step.
// runAgent evaluates each action when the agent calls it. Actions that
// require human approval are deferred to an approval step.
func runAgent(d Deps, rc *Context, p *progress, name string, s agentSettings) (StepResult, error) {
budget, err := stepBudget(rc.Context(), d.Settings)
if err != nil {
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 {
set := toolSet(d.Toolbox, d.Judge, rc, p.pin.decls)
set := toolSet(d.Toolbox, d.Judge, rc, decls)
if s.Memory {
set = withMemory(set, d.Memory, rc.RunID())
}
if resultSchema != nil {
set[resultTool] = newResultTool(resultRaw, resultSchema)
}
return set
}
model := p.pin.models[modelAlias(s.Model)]
base := AgentRequest{
Provider: p.pin.provider, Model: p.pin.model.Model, ModelInfo: p.pin.info,
System: agentSystem(p.instructions, s.Mission), Tools: tools(),
Provider: model.provider, Model: model.model.Model, ModelInfo: model.info,
System: agentSystem(p.instructions, s.system()), Tools: tools(),
}
first := base
first.Name, first.Prompt, first.Budget = name, string(p.input), budget
if resultSchema != nil {
first.Capture = resultTool
}
res, err := rc.Agent(first)
if err != nil {
return StepResult{}, err
}
returnedResult := res.Returned
followUp := base
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
}
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
@@ -464,9 +525,8 @@ func settleProposals(rc *Context, judge Judge, ask Approver, settings Settings,
return out, nil
}
// heldSince is what judgement held in the run that no earlier approval step
// settled. The whole list is recorded and the settled ones dropped after, so a
// replay filters the recorded list the same way.
// heldSince journals all actions held for approval before filtering out
// settled ones so that replay uses the same list.
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) {
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
}
// maxReapprovals bounds how many times an action that keeps changing under its
// approval is put to people again.
// maxReapprovals limits the number of new requests for one action after
// reassessment invalidates an approval and the action still requires approval.
// The initial request and escalation within a request do not count.
const maxReapprovals = 2
// settleOne gets one action approved and runs it. Before it runs it is judged
@@ -656,11 +717,9 @@ const (
refuseAction
)
// afterApproval says what an approval of approved means now that the action was
// judged again as fresh. An approval covers the action as it was shown, so one
// whose verdict got worse, or whose target or effect changed, no longer
// 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.
// afterApproval checks whether an approval is still valid after reassessment.
// If the action still requires approval, a stricter verdict or a change to the
// resolved target or effect requires a new request.
func afterApproval(approved, fresh judgement.Decision) (afterwards, string) {
switch {
case fresh.Level == judgement.Never:
@@ -672,7 +731,7 @@ func afterApproval(approved, fresh judgement.Decision) (afterwards, string) {
case fresh.Action.Effect != approved.Action.Effect:
return reaskPerson, "the effect changed since it was approved"
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, ""
}
+13 -18
View File
@@ -17,28 +17,26 @@ import (
"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 {
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
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}
// maxRecalled is how many earlier incidents the agent is shown.
const maxRecalled = 10
const targetSchema = `{"type":"object","properties":{
"target_kind":{"type":"string","description":"what the incident is about, such as host"},
"target_id":{"type":"string","description":"which one, such as web-1"}},
"target_kind":{"type":"string","description":"the resource type, such as host"},
"target_id":{"type":"string","description":"the resource ID, such as web-1"}},
"required":["target_kind","target_id"]}`
const causeSchema = `{"type":"object","properties":{
"target_kind":{"type":"string","description":"what the incident happened to, such as host"},
"target_id":{"type":"string","description":"which one, such as web-1"},
"target_kind":{"type":"string","description":"the resource type, such as host"},
"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"},
"summary":{"type":"string","description":"one sentence: what happened and why"}},
"required":["target_kind","target_id","cause","summary"]}`
@@ -54,11 +52,10 @@ type causeInput struct {
Summary string `json:"summary"`
}
// pastIncidentsTool lets the agent ask what happened to a target before.
func pastIncidentsTool(mem Memory, runID uuid.UUID) *core.Tool {
return &core.Tool{
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),
Execute: func(ctx context.Context, input string) (string, error) {
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
// just finished, in a turn of its own: a small model that is asked for four
// plain fields right after writing its findings fills them reliably, where one
// asked to remember a tool call at the end of a long investigation does not.
// recordCause uses a separate turn because small models are more reliable
// when asked for four fields after reporting than when asked to remember
// a tool call throughout the investigation.
func recordCause(rc *Context, mem Memory, input jsontext.Value, res AgentResult, req AgentRequest) error {
if !res.Completed {
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.Tools = core.ToolSet{"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),
Execute: func(ctx context.Context, raw string) (string, error) {
var in causeInput
@@ -110,8 +106,7 @@ func recordCause(rc *Context, mem Memory, input jsontext.Value, res AgentResult,
return "recorded", nil
},
}}
// A turn that doesn't file anything leaves the run without an incident; the
// investigation's findings stand.
// If the agent records no incident, keep the investigation findings.
_, err = rc.Agent(req)
return err
}
@@ -158,8 +153,8 @@ func firstText(parts ...string) string {
return ""
}
// remember files what the run did and checks whether its cause has recurred
// enough to ask for a root-cause fix.
// remember records the incident and checks whether it meets the recurrence
// threshold for proposing a root-cause fix.
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) {
decisions, err := judge.ForRun(ctx, rc.RunID())
+7 -10
View File
@@ -11,7 +11,7 @@ import (
"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>.
type StepResult struct {
Summary string `json:"summary"`
@@ -21,8 +21,8 @@ type StepResult struct {
// referencePattern matches {{ path }} in a step's string settings.
var referencePattern = regexp.MustCompile(`\{\{\s*([^{}\s]+)\s*\}\}`)
// soleReferencePattern matches a value that is exactly one reference, which is
// what lets it carry the referenced value's own type instead of its text.
// soleReferencePattern matches a standalone reference, which preserves the
// referenced value's type.
var soleReferencePattern = regexp.MustCompile(`^\s*\{\{\s*([^{}\s]+)\s*\}\}\s*$`)
// 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
// its value in this run.
//
// A value that is exactly one reference takes that reference's own type, so a
// boolean, number, array or object crosses from one step to the next intact; a
// reference embedded in prose is interpolated as text, the only thing a string
// can hold. A reference to an absent value renders empty, which is not an
// error: a skipped earlier step leaves nothing behind.
// A standalone reference preserves the value's type. References embedded in
// strings are interpolated as text. Missing values render empty because a
// skipped step produces no output.
func renderSettings(settings yaml.Node, values map[string]any) yaml.Node {
rendered := deepCopyNode(&settings)
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.
// Mapping keys are interpolated as text: a key names a field, so it has no
// typed value to carry.
// Mapping keys are interpolated as text even for standalone references.
func renderNode(node *yaml.Node, values map[string]any) {
switch node.Kind {
case yaml.DocumentNode, yaml.SequenceNode:
+37 -2
View File
@@ -17,10 +17,11 @@ import (
"github.com/google/uuid"
"github.com/jmoiron/sqlx"
"github.com/samcharles93/archie-core/modules/governance"
"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.
type StartRequest struct {
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
// that doesn't validate is stored as nothing.
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
}
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
}
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.
func (e *Engine) Has(ctx context.Context, orgID, name string) (bool, error) {
_, 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.
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")
}
+8 -8
View File
@@ -13,12 +13,11 @@ steps:
infrastructure. An investigation ends when the cause is found, not when
the first figure is.
Archie remembers earlier incidents. Once you know which target the event
is about (a kind and an id, such as host web-1), call
memory_past_incidents with it before you dig further. If it lists
earlier incidents with the same cause, say so in your findings: cite
each by its date, what was done then and how it ended, and weigh that
before recommending the same action again.
Once you identify the target (a kind and ID, such as host web-1), pass
it to memory_past_incidents before continuing. In your findings, list any
previous incidents with the same cause, along with their dates,
actions and outcomes. Consider those outcomes before recommending
the same action again.
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
@@ -45,8 +44,9 @@ steps:
- The likely cause, and how sure you are.
- The evidence: what you looked at and what it showed.
- 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
didn't make: only a tool call counts, and a failed one says so.
If a tool call returns a judgement decision, report the decision and
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.
- id: approve
+39 -29
View File
@@ -12,6 +12,7 @@ import (
"gopkg.in/yaml.v3"
"github.com/samcharles93/archie-core/modules/deliveries"
"github.com/samcharles93/archie-core/modules/governance"
"github.com/samcharles93/archie-core/modules/judgement"
)
@@ -24,14 +25,12 @@ const (
typeSleep = "workflow.sleep"
)
// StepType is one word of the workflow vocabulary: the type a step names, the
// settings it takes, and the code that runs it.
// StepType defines a workflow step's settings and implementation.
type StepType struct {
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"`
// NeedsRepository is a type that runs only with a worktree, so a workflow
// whose repository isn't required can't use it.
// NeedsRepository restricts the step type to workflows that require a repository.
NeedsRepository bool `json:"needs_repository"`
// Settings is the JSON Schema of the type's settings.
Settings *jsonschema.Schema `json:"settings"`
@@ -84,7 +83,7 @@ var stepTypes = vocabulary(
define(typeAgent, "Run an agent", agentSettings.valid, agentSettings.describe, runAgent),
define(typeAction, "Run a connector action", actionSettings.valid, actionSettings.describe, runAction),
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),
define(typeNotify, "Report the findings", notifySettings.valid, notifySettings.describe, runNotify),
define(typeSleep, "Wait", sleepSettings.valid, sleepSettings.describe, runSleep),
@@ -107,31 +106,46 @@ func StepTypes() []StepType {
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 {
Mission string `yaml:"mission" json:"mission" jsonschema:"what the agent is asked to do"`
Memory bool `yaml:"memory,omitempty" json:"memory,omitempty" jsonschema:"recall a target's earlier incidents and file what this run found"`
Mission string `yaml:"mission" json:"mission" jsonschema:"the task the agent should perform"`
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 {
if s.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
}
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 {
line += "; it recalls earlier incidents and files what it found"
line += "; it retrieves previous incidents and stores new findings"
}
return line
}
// actionSettings judge one connector action and run it if judgement lets it
// run unattended.
type actionSettings struct {
Connector string `yaml:"connector" json:"connector"`
Name string `yaml:"name" json:"name"`
@@ -146,21 +160,19 @@ func (s actionSettings) valid() error {
}
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{}
func (noSettings) valid() error { return nil }
// notifySettings tell people what the run found. Title replaces the default.
type notifySettings struct {
Title string `yaml:"title,omitempty" json:"title,omitempty"`
}
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.
const maxSleep = 24 * time.Hour
@@ -184,9 +196,8 @@ func (s sleepSettings) duration() time.Duration {
return d
}
// runAction judges the action and runs it if judgement lets it run
// unattended. One judgement holds waits for an approval step; one it refuses
// is reported.
// runAction executes only actions allowed to run unattended. A later
// approval step handles actions held for approval.
func runAction(d Deps, rc *Context, p *progress, name string, s actionSettings) (StepResult, error) {
input := s.Input
if input == nil {
@@ -220,7 +231,6 @@ func runAction(d Deps, rc *Context, p *progress, name string, s actionSettings)
}, 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) {
out, err := d.settle(rc, p)
if err != nil {
@@ -229,9 +239,8 @@ func runApprovalWait(d Deps, rc *Context, p *progress, _ string, _ noSettings) (
return StepResult{Summary: outcomeLines(out)}, nil
}
// settle puts every action judgement held and nobody has settled yet to
// people, and runs what they allow. In a dry run nobody is asked: it records
// who would be.
// settle requests approval for pending actions and runs those approved.
// A dry run records the intended recipients without contacting them.
func (d Deps) settle(rc *Context, p *progress) ([]approvalOutcome, error) {
var (
out []approvalOutcome
@@ -252,8 +261,9 @@ func (d Deps) settle(rc *Context, p *progress) ([]approvalOutcome, error) {
return out, nil
}
// runNotify tells people what the run found, after filing it in memory. In a
// dry run it records what would be sent and sends nothing.
// runNotify records incident history before notifying when memory is enabled
// 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) {
if p.memory && !p.remembered && !p.stopped && !rc.Dry() {
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) {
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
}
+8 -8
View File
@@ -13,12 +13,11 @@ steps:
infrastructure. An investigation ends when the cause is found, not when
the first figure is.
Archie remembers earlier incidents. Once you know which target the event
is about (a kind and an id, such as host web-1), call
memory_past_incidents with it before you dig further. If it lists
earlier incidents with the same cause, say so in your findings: cite
each by its date, what was done then and how it ended, and weigh that
before recommending the same action again.
Once you identify the target (a kind and ID, such as host web-1), pass
it to memory_past_incidents before continuing. In your findings, list any
previous incidents with the same cause, along with their dates,
actions and outcomes. Consider those outcomes before recommending
the same action again.
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
@@ -45,8 +44,9 @@ steps:
- The likely cause, and how sure you are.
- The evidence: what you looked at and what it showed.
- 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
didn't make: only a tool call counts, and a failed one says so.
If a tool call returns a judgement decision, report the decision and
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.
- 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
"Restore default" not "Restore shipped workflows".
- 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
"Iterate with Archie", never generic terms like "Ask bar".
- 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 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 }>();
type Tone = "ok" | "warn" | "danger" | "info" | "secondary";
+51 -33
View File
@@ -1,5 +1,5 @@
<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 { Input } from "@/components/ui/input";
@@ -9,8 +9,7 @@ import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "@
import { SettingRow } from "@/components/ui/setting-row";
import { Spinner } from "@/components/ui/spinner";
import {
ApiError,
getAgentModel,
listAgentModels,
listCredentials,
saveAgentModel,
testAgentModel,
@@ -19,47 +18,54 @@ import {
type CredentialView,
} 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 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 loading = ref(true);
const loadError = ref("");
const error = ref("");
const answer = ref("");
const saved = ref("");
const testing = ref(false);
const saving = ref(false);
const unset = ref(false);
const controller = new AbortController();
async function load() {
loading.value = true;
error.value = "";
loadError.value = "";
try {
const [current, creds] = await Promise.all([
getAgentModel(controller.signal).catch((err: unknown) => {
if (err instanceof ApiError && err.status === 404) {
unset.value = true;
return null;
}
throw err;
}),
listAgentModels(controller.signal),
listCredentials(controller.signal),
]);
credentials.value = creds;
if (current) Object.assign(model, current);
for (const [name, configured] of Object.entries(current)) models.set(name, configured);
} catch (err) {
fail(err);
fail(err, loadError);
} finally {
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() {
testing.value = true;
error.value = "";
@@ -80,8 +86,7 @@ async function save() {
error.value = "";
saved.value = "";
try {
Object.assign(model, await saveAgentModel(payload()));
unset.value = false;
models.set(alias.value, await saveAgentModel(alias.value, payload()));
saved.value = "Saved.";
} catch (err) {
fail(err);
@@ -92,17 +97,17 @@ async function save() {
function payload(): AgentModel {
return {
class: model.class.trim(),
base_url: model.base_url.trim(),
model: model.model.trim(),
api_key_credential: model.api_key_credential === none ? "" : model.api_key_credential,
class: model.value.class.trim(),
base_url: model.value.base_url.trim(),
model: model.value.model.trim(),
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 (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);
@@ -110,21 +115,34 @@ onBeforeUnmount(() => controller.abort());
</script>
<template>
<Section title="Agent model">
<Section title="Agent models">
<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>
<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.">
<Input id="agent-class" v-model="model.class" placeholder="openai" />
</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://…" />
</SettingRow>
<SettingRow label="Model" for="agent-model">
<Input id="agent-model" v-model="model.model" />
</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))">
<SelectTrigger id="agent-credential" class="w-full sm:w-64"><SelectValue /></SelectTrigger>
<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>
<span v-if="saved" class="text-caption text-muted-foreground">{{ saved }}</span>
</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>
</template>
</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";
/**
* The composer: what Archie tells you, newest last. Messages are read from a
* cursor; the stream only says when there is more to read.
* The stream sends sequence numbers, not message bodies. Fetch messages
* after the last loaded sequence number to catch up after reconnecting.
*/
const emit = defineEmits<{ unauthorized: [] }>();
@@ -100,7 +100,7 @@ onBeforeUnmount(() => controller.abort());
<Spinner v-if="loading" />
<ReadError v-else-if="error" :message="error" retry-label="Retry" @retry="load" />
<Empty v-else-if="messages.length === 0">
<EmptyHeader><EmptyTitle>Nothing yet</EmptyTitle></EmptyHeader>
<EmptyHeader><EmptyTitle>No messages yet</EmptyTitle></EmptyHeader>
</Empty>
<Section v-for="m in messages" v-else :key="m.id" :title="m.title">
<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";
/**
* Credentials are the values connectors are configured with. They are write
* only: a saved field says where it comes from, never what it holds, and
* replacing a credential means entering its values again.
* The API returns field sources, not saved secret values. Enter those values
* again when replacing a credential.
*/
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 { 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 rows = ref<EventRow[]>([]);
@@ -97,15 +92,15 @@ onBeforeUnmount(() => controller.abort());
<Section title="Filters">
<SettingRow label="Source" for="event-source">
<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>
<SelectItem value="all">Every source</SelectItem>
<SelectItem value="all">All sources</SelectItem>
<SelectItem v-for="s in sources" :key="s" :value="s">{{ s }}</SelectItem>
</SelectContent>
</Select>
</SettingRow>
<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 label="Trigger" for="event-matched">
<Select v-model="matched" @update:model-value="load">
+6 -8
View File
@@ -27,9 +27,7 @@ import {
} from "./api";
/**
* Accepted packages grouped by the contract they serve. Each one shows its
* state, version and digest, and expands into the settings it declares and the
* credential slots it was given. A credential is named, never read.
* The UI configures credential slots by name without reading secret values.
*/
const emit = defineEmits<{ unauthorized: [] }>();
@@ -261,7 +259,7 @@ onBeforeUnmount(() => controller.abort());
<div v-for="items in [rows[c.id]]" :key="`${c.id}-list`">
<Empty v-if="items.length === 0">
<EmptyHeader><EmptyTitle>None accepted</EmptyTitle></EmptyHeader>
<EmptyHeader><EmptyTitle>No extensions accepted</EmptyTitle></EmptyHeader>
</Empty>
<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>
@@ -316,7 +314,7 @@ onBeforeUnmount(() => controller.abort());
@update:model-value="(v) => setSetting(s.key, String(v))"
/>
</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 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" />
@@ -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.">
<Input :id="`${c.id}-egress`" v-model="forms[c.id].egress" />
</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" />
</SettingRow>
<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.">
<Textarea :id="`${c.id}-tools`" v-model="forms[c.id].tools" rows="5" class="font-mono" spellcheck="false" />
</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 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" />
@@ -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>
</div>
</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 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" />
+3 -3
View File
@@ -14,8 +14,8 @@ import { TagsInput, TagsInputInput, TagsInputItem, TagsInputItemDelete, TagsInpu
import { getPeople, savePeople, Unauthorized, type Person } from "./api";
/**
* The people who answer for the organisation. An approval from a channel
* counts only when its identity is listed here.
* A response from a channel must be linked to a person before the server
* checks whether that person can respond to the request.
*/
const emit = defineEmits<{ unauthorized: [] }>();
@@ -79,7 +79,7 @@ onBeforeUnmount(() => controller.abort());
<template v-else>
<Empty v-if="!people.length">
<EmptyHeader>
<EmptyTitle>No one can answer approvals from a channel yet</EmptyTitle>
<EmptyTitle>No people configured</EmptyTitle>
</EmptyHeader>
</Empty>
<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";
/**
* Sources are the places events come from. A source names the connector that
* parses its payloads; its token is the verification, and it is shown only
* when it is created or rotated.
* The API returns a source token only when it is issued or rotated.
*/
const emit = defineEmits<{ unauthorized: [] }>();
@@ -142,7 +140,7 @@ onBeforeUnmount(() => controller.abort());
</form>
</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">
<Input :model-value="issued.token" readonly class="font-mono" aria-label="Source token" />
<div class="flex items-center gap-2">
@@ -166,7 +164,7 @@ onBeforeUnmount(() => controller.abort());
<SettingRow label="Connector">
<span class="text-label">{{ src.connector }}</span>
</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">
<TagsInputItem v-for="path in keyFields[src.name]" :key="path" :value="path">
<TagsInputItemText />
+4 -5
View File
@@ -10,9 +10,8 @@ import { Spinner } from "@/components/ui/spinner";
import { getBootstrap, rotateAdminToken, Unauthorized, type BootstrapView } from "./api";
/**
* The bootstrap values the binary reads before the database is reachable. They
* are shown read-only because they come first; the admin token is the one that
* can be rotated here.
* Bootstrap settings are loaded before the database is available. The only
* bootstrap setting this page can change is the admin token.
*/
const emit = defineEmits<{ unauthorized: [] }>();
@@ -72,7 +71,7 @@ onBeforeUnmount(() => controller.abort());
</script>
<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" />
<ReadError v-else-if="error && !bootstrap" :message="error" retry-label="Retry" @retry="load" />
<template v-else-if="bootstrap">
@@ -97,7 +96,7 @@ onBeforeUnmount(() => controller.abort());
<Button variant="ghost" @click="issued = ''">Done</Button>
</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>
</template>
</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";
/**
* Triggers match an event, or an interval, to a workflow. A disabled trigger
* is kept and starts nothing.
* Disabling a trigger keeps its configuration but stops it from starting runs.
*/
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.">
<Input id="trigger-event" v-model="draft.eventType" />
</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" />
</SettingRow>
<SettingRow label="Workflow" for="trigger-workflow">
<Input id="trigger-workflow" v-model="draft.workflow" placeholder="investigate" />
</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 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" />
@@ -207,7 +206,7 @@ onBeforeUnmount(() => controller.abort());
<SettingRow label="Event type" :for="`${t.name}-type`">
<Input :id="`${t.name}-type`" v-model="drafts[t.name].eventType" />
</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" />
</SettingRow>
<SettingRow label="Workflow" :for="`${t.name}-workflow`">
+1 -2
View File
@@ -28,7 +28,6 @@ import {
} from "./api";
import { levelLabel } from "./state";
/** Unmatched events, each group with the draft it could become: summary, dry run and publish. */
const emit = defineEmits<{ unauthorized: [] }>();
const groups = ref<EventGroup[]>([]);
@@ -120,7 +119,7 @@ const filterText = (filter: Record<string, string>) =>
.join(" ");
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) =>
({ ran: "ok", would_run: "info", would_ask: "warn", refused: "danger" })[a.outcome] as "ok" | "info" | "warn" | "danger";
const policyKinds = [
+13 -13
View File
@@ -1,10 +1,9 @@
// The single binary's HTTP API. Until identities exist, every route sits
// behind the bootstrap admin token, held for this browser session only.
// The dashboard keeps the bootstrap admin token in browser session storage.
const TOKEN_KEY = "archie.adminToken";
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 {
readonly status: number;
@@ -20,7 +19,7 @@ export const clearToken = () => sessionStorage.removeItem(TOKEN_KEY);
async function request(path: string, signal?: AbortSignal): Promise<Response> {
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) {
const body = (await res.json().catch(() => ({}))) as { error?: string; detail?: string };
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" },
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) {
const body = (await res.json().catch(() => ({}))) as { error?: string; detail?: string };
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" },
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) {
const body = (await res.json().catch(() => ({}))) as { error?: string; detail?: string };
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",
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) {
const body = (await res.json().catch(() => ({}))) as { error?: string; detail?: string };
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);
/** 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 {
action: string;
target: string;
@@ -410,7 +409,7 @@ export interface DryReport {
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 {
id: string;
group_id: string;
@@ -460,7 +459,7 @@ const extensionPath: Record<ExtensionContract, string> = {
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 {
name: string;
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>) =>
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 saveAgentModel = (model: AgentModel) =>
send<AgentModel>("PUT", "/api/settings/agent-model", model);
export const listAgentModels = (signal?: AbortSignal) =>
get<Record<string, AgentModel>>("/api/settings/agent-models", signal);
export const saveAgentModel = (alias: string, model: AgentModel) =>
send<AgentModel>("PUT", `/api/settings/agent-model?${new URLSearchParams({ alias })}`, model);
export const testAgentModel = (model: AgentModel) =>
send<{ model: string; answer: string }>("POST", "/api/settings/agent-model/test", model);