3.9 KiB
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
- Add the constant to
internal/taskstate/taskstate.goand place it inTerminal,ActionsandStatuses. Its value is stored, so renaming it later is a migration. - Alias it in
internal/domain/workflow/task/task.goandinternal/domain/workflow/task_aliases.go. - 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. - Find every hand-written status list in SQL:
grep -rn "'merged'" internal/infrastructure/postgres/queries.ClearTerminalTasksmust matchtaskstate.Terminal, whichTestClearTerminalTasksMatchesTaskstateenforces. The stats queries count outcomes by name; decide whether the new status counts. - Extend the table in
taskstate_test.go.
Adding a task field
Follow State Store for the
column and the wire. Then decide who writes it: UpdateTask writes a fixed
column set, so a field set at enqueue needs its own statement (as
StampTaskBinding does for binding provenance and inputs).
Changing what the agent receives
- The task brief is
container.TaskPayload, written to<workspace>/.git/task.jsonbyWriteTaskJSON. Never write it to the workspace root: the commit stage stages everything there. - The run request is
taskrun.Request.Validaterejects 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 checksbinding.Validate,binding.CompileFilterandBinding.CheckWorkflow. - At dispatch, in
dispatchOneBindingandresolveBindingTarget(internal/daemon), because the workflow or mapping may have changed since the save. A refusal is recorded withrecordDispatchFailureand 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
- Domain type and
Validateininternal/domain/binding. - Column, queries, store mapping, wire field,
newColumns(State Store). - The request type and
checkedBindinginapi_binding.go. - The draft, payload and editor in
ui/src/bindings/(Frontend UI). - Its effect at dispatch, with a case in
internal/daemon/dispatch_inputs_test.goordispatch_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.