fix(eda): clear completed tasks; document the tool allowlist's reach and unchecked profile names

ClearTerminalTasks now deletes completed tasks, with a test that holds its
SQL list to taskstate.Terminal. The AllowTools comment says agentloop's
built-in file tools are outside the allowlist and why. The PRD model
diagram lists only what a profile holds (image, tools), and the profile
field and AgentProfile say a workflow's profile name is resolved at
dispatch, not when the workflow is saved.
This commit is contained in:
sam committed 2026-09-24 20:53:51 +10:00
1 parent d320a1a01a
commit d8bec1ae06
8 files changed
+51 -10

No files matched your search

+1 -1
View File
@@ -244,7 +244,7 @@
"url": "/dev/prds/event-automation/",
"title": "Event automation: identified events, typed parameters, purpose-built agents",
"section": "PRDs",
"body": "# Event automation: identified events, typed parameters, purpose-built agents\n\n**Status:** Approved\n**Date:** 2026-09-23\n**Parent:** epic `archie-core-t2db`\n\n## Why this exists\n\nArchie is an event-driven automation system. Any system that can send a\nwebhook (a forge, an error tracker, a firewall, a monitoring stack) should be\nable to start an agent built for that job. The shape this replaces cannot:\n\n- A binding matches only the URL segment an event was posted to, and a source\n may have one binding. Two kinds of event from one sender cannot go to\n different workflows.\n- A mapping is a list of JSON paths written against one example payload.\n Nothing recognises what kind of event arrived.\n- Mapped values reach the task only as `key=value` lines in its body text.\n- Every task needs a repository and runs in a git worktree.\n- Every agent runs the same image with the same forwarded keys.\n\n## The model\n\n```\nsource ─▶ event type ─▶ mapping ─▶ binding ─▶ workflow ─▶ agent profile\n (identified) (params) (+ filter, (inputs, (image, tools,\n repo) profile) secrets, access)\n```\n\n### Sources\n\nA source is the endpoint one sender posts to. Its path is a generated UUIDv7\n(`/webhooks/capture/0199…`), so an endpoint cannot be guessed or collide. The\noperator may replace it with a custom path for a sender that cannot use that\nformat; a custom path must be unique and URL-safe, and is refused otherwise.\nA source owns the signing setting:\n\n- **Signed** (default). Archie generates the secret. Only events with a valid\n `X-Hub-Signature-256` or `X-Signature-256` HMAC are dispatched.\n- **Unsigned.** The operator turns signing off for a sender that cannot sign.\n The source and every event from it are marked unsigned in the inspector,\n the binding list and the task timeline. Turning signing off needs the same\n approval as arming a binding.\n\nUnauthenticated events on a signed source are captured and never\ndispatched.\n\n### Event types\n\nAn event type is a named kind of event from one source, such as\n`github / pull_request.opened` or `firewall / blocked_connection`. It is\ndefined by a match rule:\n\n- header equality (`X-GitHub-Event = pull_request`), and\n- payload conditions (`action = \"opened\"`, or a path being present).\n\nAn event type can be created two ways:\n\n- **From an example payload.** The operator pastes a payload (and optionally\n its headers), and archie converts it to the type's schema. No event needs to\n have arrived.\n- **From captures.** Archie proposes types from what has arrived, as below.\n\nEither way, archie infers the schema, not the operator:\n\n- Each capture gets a structural signature: the set of JSON paths with their\n value types, plus the headers that look like discriminators (`*-Event`,\n `*-Type`, `Content-Type`).\n- Captures from one source that share a signature are grouped. The inspector\n shows each group as a proposed event type, with its inferred schema, its\n number of events and a sample, until the operator names it or dismisses it.\n- The proposed match rule is the set of discriminators that separates the\n group from its siblings. The operator can edit it before saving.\n- A capture that matches no named type is shown as unidentified. It is never\n dispatched.\n\nTwo event types on one source whose rules can match the same event are\nrefused when the second one is saved.\n\n### Mappings\n\nA mapping belongs to an event type. It maps payload paths to named, typed\nparameters, and it is checked against the type's inferred schema, so a path\nthe type does not have is refused when the mapping is saved. Any number of\nbindings may reuse one mapping.\n\nEach mapping shows how many events it has matched, with the time of the most\nrecent, so an operator can see which mappings are live and which have never\nfired.\n\n### Workflows declare inputs\n\nA workflow definition declares its inputs:\n\n```yaml\nid: firewall-investigate\ninputs:\n src_ip: { type: string, required: true }\n severity: { type: string }\nrepository: none # none | optional | required\nprofile: network-investigator\nsteps: ...\n```\n\n- `repository: none` runs the agent in a scratch workspace with no clone.\n `required`, the default, gives the agent a worktree of the task's\n repository. `optional` gives it a worktree when the binding names a\n repository and a scratch workspace when it does not.\n- A workflow whose `repository` is not `required` may use only steps that need\n no repository. `agent.run` is one: it runs one agent mission and finishes\n the task as done, with no pull request.\n- The declared inputs reach the agent as structured data in the task brief\n and in the agent's context. They are not body text.\n- A workflow may declare `outputs`, the structured result it returns when it\n finishes.\n\n### Workflows call workflows\n\nA workflow steLine truncated
"body": "# Event automation: identified events, typed parameters, purpose-built agents\n\n**Status:** Approved\n**Date:** 2026-09-23\n**Parent:** epic `archie-core-t2db`\n\n## Why this exists\n\nArchie is an event-driven automation system. Any system that can send a\nwebhook (a forge, an error tracker, a firewall, a monitoring stack) should be\nable to start an agent built for that job. The shape this replaces cannot:\n\n- A binding matches only the URL segment an event was posted to, and a source\n may have one binding. Two kinds of event from one sender cannot go to\n different workflows.\n- A mapping is a list of JSON paths written against one example payload.\n Nothing recognises what kind of event arrived.\n- Mapped values reach the task only as `key=value` lines in its body text.\n- Every task needs a repository and runs in a git worktree.\n- Every agent runs the same image with the same forwarded keys.\n\n## The model\n\n```\nsource ─▶ event type ─▶ mapping ─▶ binding ─▶ workflow ─▶ agent profile\n (identified) (params) (+ filter, (inputs, (image, tools)\n repo) profile)\n```\n\n### Sources\n\nA source is the endpoint one sender posts to. Its path is a generated UUIDv7\n(`/webhooks/capture/0199…`), so an endpoint cannot be guessed or collide. The\noperator may replace it with a custom path for a sender that cannot use that\nformat; a custom path must be unique and URL-safe, and is refused otherwise.\nA source owns the signing setting:\n\n- **Signed** (default). Archie generates the secret. Only events with a valid\n `X-Hub-Signature-256` or `X-Signature-256` HMAC are dispatched.\n- **Unsigned.** The operator turns signing off for a sender that cannot sign.\n The source and every event from it are marked unsigned in the inspector,\n the binding list and the task timeline. Turning signing off needs the same\n approval as arming a binding.\n\nUnauthenticated events on a signed source are captured and never\ndispatched.\n\n### Event types\n\nAn event type is a named kind of event from one source, such as\n`github / pull_request.opened` or `firewall / blocked_connection`. It is\ndefined by a match rule:\n\n- header equality (`X-GitHub-Event = pull_request`), and\n- payload conditions (`action = \"opened\"`, or a path being present).\n\nAn event type can be created two ways:\n\n- **From an example payload.** The operator pastes a payload (and optionally\n its headers), and archie converts it to the type's schema. No event needs to\n have arrived.\n- **From captures.** Archie proposes types from what has arrived, as below.\n\nEither way, archie infers the schema, not the operator:\n\n- Each capture gets a structural signature: the set of JSON paths with their\n value types, plus the headers that look like discriminators (`*-Event`,\n `*-Type`, `Content-Type`).\n- Captures from one source that share a signature are grouped. The inspector\n shows each group as a proposed event type, with its inferred schema, its\n number of events and a sample, until the operator names it or dismisses it.\n- The proposed match rule is the set of discriminators that separates the\n group from its siblings. The operator can edit it before saving.\n- A capture that matches no named type is shown as unidentified. It is never\n dispatched.\n\nTwo event types on one source whose rules can match the same event are\nrefused when the second one is saved.\n\n### Mappings\n\nA mapping belongs to an event type. It maps payload paths to named, typed\nparameters, and it is checked against the type's inferred schema, so a path\nthe type does not have is refused when the mapping is saved. Any number of\nbindings may reuse one mapping.\n\nEach mapping shows how many events it has matched, with the time of the most\nrecent, so an operator can see which mappings are live and which have never\nfired.\n\n### Workflows declare inputs\n\nA workflow definition declares its inputs:\n\n```yaml\nid: firewall-investigate\ninputs:\n src_ip: { type: string, required: true }\n severity: { type: string }\nrepository: none # none | optional | required\nprofile: network-investigator\nsteps: ...\n```\n\n- `repository: none` runs the agent in a scratch workspace with no clone.\n `required`, the default, gives the agent a worktree of the task's\n repository. `optional` gives it a worktree when the binding names a\n repository and a scratch workspace when it does not.\n- A workflow whose `repository` is not `required` may use only steps that need\n no repository. `agent.run` is one: it runs one agent mission and finishes\n the task as done, with no pull request.\n- The declared inputs reach the agent as structured data in the task brief\n and in the agent's context. They are not body text.\n- A workflow may declare `outputs`, the structured result it returns when it\n finishes.\n\n### Workflows call workflows\n\nA workflow step can call another woLine truncated
},
{
"url": "/dev/prds/event-capture-storage/",
+2 -2
View File
@@ -23,8 +23,8 @@ able to start an agent built for that job. The shape this replaces cannot:
```
source ─▶ event type ─▶ mapping ─▶ binding ─▶ workflow ─▶ agent profile
(identified) (params) (+ filter, (inputs, (image, tools,
repo) profile) secrets, access)
(identified) (params) (+ filter, (inputs, (image, tools)
repo) profile)
```
### Sources
+6 -3
View File
@@ -43,7 +43,10 @@ type LoopRunner struct {
// AllowTools is the agent profile's allowlist over the tools archie adds
// (central/MCP, repository scripts and skill plugins). Empty allows them
// all. A stage's capture tools are how it returns structured results, so
// they are never filtered.
// they are never filtered. The agent loop's built-in file tools are not
// covered either: ai-sdk agentloop registers them itself with no filter
// hook, so they are always present (read-only when the stage asks), and
// restricting them needs an ai-sdk change.
AllowTools []string
}
@@ -393,8 +396,6 @@ func scriptToolSet(workspace string) core.ToolSet {
}
}
// mergeToolSets combines tool sets into one; later sets win on name
// collisions.
// allowedTools keeps the tools allow names; an empty allow keeps them all.
func allowedTools(set core.ToolSet, allow []string) core.ToolSet {
if len(allow) == 0 {
@@ -409,6 +410,8 @@ func allowedTools(set core.ToolSet, allow []string) core.ToolSet {
return kept
}
// mergeToolSets combines tool sets into one; later sets win on name
// collisions.
func mergeToolSets(sets ...core.ToolSet) core.ToolSet {
merged := core.ToolSet{}
for _, set := range sets {
+3 -1
View File
@@ -914,7 +914,9 @@ type ContainerConfig struct {
// AgentProfile is a named execution environment for an agent. Secrets and
// forge or network access are granted to identities, not profiles
// (docs/prds/orgs-and-access.md).
// (docs/prds/orgs-and-access.md). A workflow's profile name is not checked
// when the workflow is saved: a name with no profile here parks the task for
// an operator when it is dispatched (daemon pinTaskProfile).
type AgentProfile struct {
// Image is the container image; empty means [containers].image.
Image string `toml:"image" yaml:"image" json:"image,omitempty"`
+3 -1
View File
@@ -39,7 +39,9 @@ type InputSpec struct {
type WorkflowInterface struct {
Inputs map[string]InputSpec `yaml:"inputs,omitempty" json:"inputs,omitempty"`
Repository RepositoryMode `yaml:"repository,omitempty" json:"repository,omitempty"`
Profile string `yaml:"profile,omitempty" json:"profile,omitempty"`
// Profile names a [containers.profiles] entry. It is resolved when a task
// is dispatched, not when the workflow is saved.
Profile string `yaml:"profile,omitempty" json:"profile,omitempty"`
}
var (
@@ -0,0 +1,34 @@
package postgres
import (
"testing"
"github.com/samcharles93/archie-core/internal/taskstate"
)
// ClearTerminalTasks deletes exactly the statuses taskstate.Terminal names, so
// the SQL list cannot fall behind a new terminal status.
func TestClearTerminalTasksMatchesTaskstate(t *testing.T) {
s := storeFor(t)
statuses := taskstate.Statuses()
for i, meta := range statuses {
if _, err := s.EnqueueIssue(t.Context(), "acme", "widgets", i+1, "t", "b", "", ""); err != nil {
t.Fatal(err)
}
if _, err := s.pool.Exec(t.Context(), "UPDATE tasks SET status = $1 WHERE issue_number = $2", meta.ID, i+1); err != nil {
t.Fatal(err)
}
}
if _, err := s.ClearTerminalTasks(t.Context()); err != nil {
t.Fatal(err)
}
for i, meta := range statuses {
task, err := s.TaskByIssue(t.Context(), "acme", "widgets", i+1)
if err != nil {
t.Fatal(err)
}
if kept := task != nil; kept == taskstate.Terminal(meta.ID) {
t.Errorf("status %q: kept = %v, want kept only when not terminal", meta.ID, kept)
}
}
}
@@ -159,7 +159,7 @@ func (q *Queries) ClaimNextTask(ctx context.Context) (Task, error) {
const clearTerminalTasks = `-- name: ClearTerminalTasks :execrows
DELETE FROM tasks
WHERE status IN ('merged', 'rejected', 'dead', 'closed_wont_do')
WHERE status IN ('merged', 'rejected', 'dead', 'closed_wont_do', 'completed')
`
func (q *Queries) ClearTerminalTasks(ctx context.Context) (int64, error) {
@@ -88,7 +88,7 @@ WHERE id = $1 AND status = $4;
-- name: ClearTerminalTasks :execrows
DELETE FROM tasks
WHERE status IN ('merged', 'rejected', 'dead', 'closed_wont_do');
WHERE status IN ('merged', 'rejected', 'dead', 'closed_wont_do', 'completed');
-- name: RecoverStaleTasks :execrows
UPDATE tasks SET status = 'queued', updated_at = now() WHERE status = 'running';