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

192 lines
6.6 KiB
Go

package protocol
import (
"encoding/json"
"path"
"strings"
)
// VerdictReasonKeys is the single ordered definition of the output keys a stage
// may use to state why it chose its outcome. The first key carrying usable text
// wins. Store, server and TUI all read this one list, so the order never drifts.
// "feedback" is last so it only states the reason when no model-authored key
// does: an operator's decision feedback is exactly the human stage's reason.
var VerdictReasonKeys = []string{"verdict", "reason", "decision", "summary", "implementation_summary", "feedback"}
// VerdictReasonCap bounds a verdict reason to this many runes, whether it was
// generated by the model or derived at read time. It is the same cap the
// summariser's OutputCap uses (summarise references this constant), so the two
// cannot drift.
const VerdictReasonCap = 200
// Verdict reason provenance. ReasonSource tells a diagnosis whether the stored
// one-liner came from the model, was derived at read time, or is honestly absent.
const (
VerdictReasonModel = "model"
VerdictReasonFallback = "fallback"
VerdictReasonAbsent = "absent"
)
// StageVerdict is the plain-language outcome of one completed stage visit: the
// chosen option (the step's outcome and the target it routed to), a one-line
// reason with its provenance, and the recorded artifacts the reason refers to. A
// nil RunStep.Verdict means there is no verdict (for example a running step); an
// empty struct is never serialised.
type StageVerdict struct {
Option string `json:"option"`
Reason string `json:"reason,omitempty"`
ReasonSource string `json:"reason_source,omitempty"`
Artifacts []string `json:"artifacts,omitempty"`
}
// DeriveVerdictReason reads the first usable reason line from a step's output in
// the shared key order. It accepts a string value, or JSON-encodes a non-string
// one (as OutputPreview does), normalises it to one safe line and bounds it to
// VerdictReasonCap runes. It returns "" when no key carries usable text and never
// synthesises a reason.
func DeriveVerdictReason(output map[string]any) string {
for _, key := range VerdictReasonKeys {
value, ok := output[key]
if !ok || value == nil {
continue
}
text, ok := value.(string)
if !ok {
encoded, err := json.Marshal(value)
if err != nil {
continue
}
text = string(encoded)
}
text = NormalizeText(text)
if text == "" || text == "[]" || text == "{}" {
continue
}
return capVerdictReason(text)
}
return ""
}
// VerdictOption states a step's chosen option plainly: its outcome and the target
// it routed to, with the terminal shorthands rendered as words.
func VerdictOption(outcome, target string) string {
target = ResolveTarget(outcome, target)
switch target {
case SuccessEnd:
target = "success"
case FailureEnd:
target = "failure"
}
return outcome + " → " + target
}
// ReferencedVerdictArtifacts returns the names of the artifacts actually recorded
// for a visit that the reason refers to, in their recorded order and deduplicated.
// A name is included when it (or its basename, for a slashed path) appears in the
// reason text, or when it is named in the output's screenshots list. Only recorded
// artifacts can be returned: a name the model invented that is not a real recorded
// file is never exposed.
func ReferencedVerdictArtifacts(reason string, output map[string]any, artifacts []StageArtifact) []string {
var names []string
seen := map[string]bool{}
for _, artifact := range artifacts {
name := artifact.Name
if name == "" || seen[name] {
continue
}
base := path.Base(name)
if !verdictMentionsArtifact(reason, name, base) && !screenshotsNameArtifact(output, name, base) {
continue
}
seen[name] = true
names = append(names, name)
}
return names
}
// verdictMentionsArtifact reports whether the reason text names an artifact by its
// full recorded name or by its basename.
func verdictMentionsArtifact(reason, name, base string) bool {
if reason == "" {
return false
}
if strings.Contains(reason, name) {
return true
}
return base != name && strings.Contains(reason, base)
}
// screenshotsNameArtifact reports whether the output's screenshots list names an
// artifact by its full recorded name or by its basename. The list may be a single
// string, a []string or a generic []any of strings.
func screenshotsNameArtifact(output map[string]any, name, base string) bool {
value, ok := output["screenshots"]
if !ok {
return false
}
for _, candidate := range screenshotNames(value) {
candidate = strings.TrimSpace(candidate)
if candidate != "" && (candidate == name || candidate == base) {
return true
}
}
return false
}
// screenshotNames flattens a screenshots value to its string entries, accepting
// the single-string, []string and generic []any forms stages emit.
func screenshotNames(value any) []string {
switch typed := value.(type) {
case string:
return []string{typed}
case []string:
return typed
case []any:
names := make([]string, 0, len(typed))
for _, item := range typed {
if name, ok := item.(string); ok {
names = append(names, name)
}
}
return names
}
return nil
}
// NewStageVerdict builds the verdict for one stage visit. It returns nil when the
// step carries neither an outcome nor a target (a running step has no verdict). A
// stored model reason is kept with its provenance; otherwise the read-time
// fallback derives the reason from the output, or marks it absent when no key
// carries usable text. Referenced artifacts are matched against the recorded
// artifacts only.
func NewStageVerdict(outcome, target string, output map[string]any, artifacts []StageArtifact, storedReason, storedSource string) *StageVerdict {
if outcome == "" && target == "" {
return nil
}
verdict := &StageVerdict{Option: VerdictOption(outcome, target)}
if reason := strings.TrimSpace(storedReason); reason != "" {
verdict.Reason = capVerdictReason(reason)
verdict.ReasonSource = storedSource
if verdict.ReasonSource == "" {
verdict.ReasonSource = VerdictReasonModel
}
} else if reason := DeriveVerdictReason(output); reason != "" {
verdict.Reason = reason
verdict.ReasonSource = VerdictReasonFallback
} else {
verdict.ReasonSource = VerdictReasonAbsent
}
verdict.Artifacts = ReferencedVerdictArtifacts(verdict.Reason, output, artifacts)
return verdict
}
// capVerdictReason bounds a reason to VerdictReasonCap runes without splitting a
// rune (rune slicing is inherently UTF-8-safe).
func capVerdictReason(text string) string {
runes := []rune(text)
if len(runes) <= VerdictReasonCap {
return text
}
return string(runes[:VerdictReasonCap])
}