Add a human decision stage that pauses a run for an operator's choice

A new registered stage type `human` (internal/stage/human.go) has no model,
agent, tools or configs: its required `prompt` block carries the operator
instructions and its non-error edges are the selectable options. It parses,
validates, renders, exports and imports like every other type (no parser
special-case, no config keys).

At runtime the runner parks the run instead of executing: the step and the run
persist `waiting` with self-contained {prompt, options} evidence, and the run
returns without starting later stages, capturing file diffs, scanning artifacts,
holding a goroutine/timer or applying a stage timeout. The wait is durable: a
restart leaves the waiting rows untouched (RecoverRuns excludes them) and a
rebuilt runtime over the same database still accepts the decision.

`pipelines decide <run-id> [stage] --option KEY [--feedback TEXT] [--json]` and
the TUI `c` picker resolve the decision from the pinned graph in one store
transaction, record the choice and feedback as the step's evidence and resume
along edges[KEY]. An unknown option is refused with the valid list, a stage that
is not waiting is refused, and a repeated decision for an already-decided visit
does not double-apply. Cancel and retry keep working while waiting and after a
decision; a human stage is never killed by a stage timeout or max_visits, and a
`notify` policy can fire an `on=waiting` event.

Docs: the authoring skill references (format.md, operations.md), docs/cli.md and
README describe the stage, the command and the TUI picker. Tests cover stage
validation, the parsing round-trip, the store transitions, a websocket wait/decide
integration, cancel/retry, waiting notifications and a persistence-layer rebuild
(second Open + newRunner over one database, no process restart).
This commit is contained in:
2026-10-16 16:47:28 +01:00
parent 1b4674d22c
commit a6aff47117
32 changed files with 1782 additions and 87 deletions
+17 -1
View File
@@ -201,6 +201,7 @@ Submitting activates included schedules, so review them before publishing.
| Start a run | `run NAME PROMPT [--title TITLE] --yes --json` |
| Run history/inspection | `runs --json`, `inspect ID --json` |
| Rename a run | `title ID "TITLE" --json` |
| Decide a waiting human stage | `decide ID [STAGE] --option KEY [--feedback TEXT] --json` |
| Cancel | `cancel ID --json` |
| Connection and phone settings | `connection --json`, `ping --json` |
| Server/ntfy status popup | `status --json` |
@@ -218,7 +219,7 @@ printf '%s' '{"type":"get_pipeline","pipeline_id":1,"version":1}' | pipelines rp
Existing protocol commands: `ping`, `list_pipelines`, `get_pipeline`,
`list_templates`, `validate`, `submit`, `run_pipeline`, `list_runs`, `get_run`,
`cancel_run`, `retry_run`, `get_status`. `list_runs` also returns all-history `usage`
`cancel_run`, `retry_run`, `decide_run`, `set_run_title`, `get_run_evidence`, `get_status`. `list_runs` also returns all-history `usage`
aggregates. See `internal/protocol/message.go` for JSON envelopes. Mutating RPCs
have real effects; they are not previews. TUI-only animation, scrolling, and
transient client logs are presentation, not separate server capabilities.
@@ -257,6 +258,21 @@ Retry is hidden and rejected while a run is executing or agent cleanup remains
active, even if a terminal status was already persisted. Run RPCs report
`executing` alongside status so clients can distinguish cleanup from completion.
A pipeline may contain a `type=human` decision stage (see the authoring skill's
`references/format.md`). Its step becomes `waiting`, the run reports that it is
waiting on a person, and no later stage runs. `runs`/`inspect --json` show the
`waiting` status, the stage and its recorded instructions and options. Answer it
with `pipelines decide <run-id> [stage] --option KEY [--feedback TEXT] [--json]`
or, in the run inspector, press `c` to open the option picker, choose with
`↑/↓`, type optional feedback with `Tab`, and confirm with Enter. The choice and
feedback are recorded as the step's evidence and the run resumes along
`edges[KEY]`. An unknown option is refused with the valid list, a decision to a
stage that is not waiting is refused, and a repeated decision for an
already-decided visit does not double-apply. The wait is persisted in the run
rows, so it survives a server restart and `decide` still works afterwards;
`cancel` and `retry` keep working while waiting and after a decision, and a
human stage is never killed by a stage timeout or `max_visits`.
The run inspector's upper half shows the entire graph from the run's immutable
pinned version using the shared renderer and viewport. Executed stages and taken
routes retain their colors; unexecuted stages, unchosen routes and unreached