Files
alan a6aff47117 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).
2026-10-16 16:47:28 +01:00

61 lines
2.0 KiB
Go

package stage
import (
"context"
"fmt"
"sort"
"strings"
)
const HumanType = "human"
// HumanStage pauses its run until a person chooses one of the stage's outgoing
// options. It has no model, agent, tools or configs: its outcomes are exactly
// its non-error edges (the selectable options) and its required prompt block
// carries the operator instructions. It parses, validates, renders, exports and
// imports like every other registered type. The runner owns the wait and the
// decision path; Run is defensive only and never executes synchronously.
type HumanStage struct{}
func (HumanStage) Validate(def Definition) error {
if EffectiveType(def.Type) != HumanType {
return fmt.Errorf("expected human stage")
}
for name := range def.Blocks {
switch name {
case "configs", "edges", "output", "prompt":
default:
return fmt.Errorf("unexpected block %q for human stage", name)
}
}
for key := range def.Configs {
return fmt.Errorf("unknown human config %q", key)
}
if strings.TrimSpace(def.Blocks["prompt"]) == "" {
return fmt.Errorf("human stage requires a nonempty prompt block with the operator instructions")
}
if len(HumanOptions(def.Edges)) == 0 {
return fmt.Errorf("human stage requires at least one non-error option edge")
}
return nil
}
func (HumanStage) Run(context.Context, Definition, Values) (Result, error) {
return Result{}, fmt.Errorf("human stage is resolved by the runner's decision path, not executed")
}
// HumanOptions is the single definition of a human stage's selectable outcomes:
// its non-error edges in a deterministic order. The mandatory error edge is a
// failure route, not an operator choice, so it is never returned. Store, runner
// and TUI all read this one helper, so the option set cannot drift.
func HumanOptions(edges map[string]string) []string {
options := make([]string, 0, len(edges))
for outcome := range edges {
if outcome != "error" {
options = append(options, outcome)
}
}
sort.Strings(options)
return options
}