Files
archie/docs/development/daemon.md
T

92 lines
4.0 KiB
Markdown

# Daemon
The daemon claims and runs tasks, and turns captured events into tasks through
bindings. This page covers both.
## Task lifecycle
Authority: `docs/architecture/agent-system.md`. The status vocabulary lives in
`internal/taskstate`, which imports no internal package.
### Adding a status
1. Add the constant to `internal/taskstate/taskstate.go` and place it in
`Terminal`, `Actions` and `Statuses`. Its value is stored, so renaming it
later is a migration.
2. Alias it in `internal/domain/workflow/task/task.go` and
`internal/domain/workflow/task_aliases.go`.
3. Add it to the default catalogue in `ui/src/lib/task-meta.ts`. The server
catalogue replaces the defaults when it loads, but the defaults render first.
4. Find every hand-written status list in SQL:
`grep -rn "'merged'" internal/infrastructure/postgres/queries`.
`ClearTerminalTasks` must match `taskstate.Terminal`, which
`TestClearTerminalTasksMatchesTaskstate` enforces. The stats queries count
outcomes by name; decide whether the new status counts.
5. Extend the table in `taskstate_test.go`.
### Adding a task field
Follow [State Store](state-store.md) for the
column and the wire. Then decide who writes it: `UpdateTask` writes a fixed
column set, so a field set at enqueue belongs in the insert that creates the
row (as `InsertChatTask` does for inputs), or in its own statement when only
some producers set it (as `StampTaskBinding` does for binding provenance).
### Changing what the agent receives
- The task brief is `container.TaskPayload`, written to
`<workspace>/.git/task.json` by `WriteTaskJSON`. Never write it to the
workspace root: the commit stage stages everything there.
- The run request is `taskrun.Request`. `Validate` rejects a request that
cannot run; a new requirement goes there.
- Parking always carries a class (`taskstate.ParkTransient`,
`ParkNeedsHuman`, `ParkTerminal`) chosen by the code that parks. Pick the one
that says what an operator must do.
- A task with no repository (`Task.HasRepository`) runs in a scratch workspace
with no worktree grant. Code that assumes an owner and repo must check first.
## Event automation
Authority: `docs/prds/event-automation.md` (the model: source, event type,
mapping, binding, workflow, profile) and `docs/architecture/bindings.md`
(threat model).
### Where each check lives
A binding is checked twice, and a new rule usually belongs in both places:
- **On save**, in `checkedBinding` (`internal/webui/api_binding.go`), so the
operator sees the problem while editing. It calls the domain checks
`binding.Validate`, `binding.CompileFilter` and `Binding.CheckWorkflow`.
- **At dispatch**, in `dispatchOneBinding` and `resolveBindingTarget`
(`internal/daemon`), because the workflow or mapping may have changed since
the save. A refusal is recorded with `recordDispatchFailure` and starts no
task.
Put the rule itself in `internal/domain/binding` or
`internal/domain/workflow/task` and call it from both, rather than writing it
twice.
### Adding a binding field
1. Domain type and `Validate` in `internal/domain/binding`.
2. Column, queries, store mapping, wire field, `newColumns`
([State Store](state-store.md)).
3. The request type and `checkedBinding` in `api_binding.go`.
4. The draft, payload and editor in `ui/src/bindings/`
([Frontend UI](frontend-ui.md)).
5. Its effect at dispatch, with a case in
`internal/daemon/dispatch_inputs_test.go` or `dispatch_bindings_test.go`.
### Rules that must hold
- Signing belongs to the source. Intake verifies the HMAC against the source's
secret before the payload is parsed.
- An event must be identified as an event type before anything dispatches it,
and a binding applies only to its mapping's event type. Dispatch test
fixtures therefore create an event type before inserting captures.
- The dispatch ledger is claimed before the task is enqueued (at most once).
- Anything an event supplies that selects what the agent acts on, such as a
repository, must be checked against configuration. An event never widens
what an agent can reach.