One page per area: frontend UI, agent, workflows, daemon (task lifecycle and event automation together), State Store, control plane and settings, and processes and wiring, with merging work kept separate.
91 lines
3.9 KiB
Markdown
91 lines
3.9 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 catalog in `ui/src/lib/task-meta.ts`. The server
|
|
catalog 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 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.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.
|