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:
@@ -35,6 +35,7 @@ type App struct {
|
||||
type options struct {
|
||||
harness string
|
||||
url, name, prompt, title, template, workspace, paths, key, opencode, model string
|
||||
option, feedback string
|
||||
output string
|
||||
conflict string
|
||||
all bool
|
||||
@@ -107,6 +108,9 @@ func (a App) flags(command string) (*flag.FlagSet, *options) {
|
||||
f.DurationVar(&o.waitTimeout, "wait-timeout", 0, "Client limit for --wait (0 waits until the run ends); independent of --timeout")
|
||||
case "cancel", "draft-delete":
|
||||
f.BoolVar(&o.yes, "yes", false, "Confirm this action without an interactive prompt")
|
||||
case "decide":
|
||||
f.StringVar(&o.option, "option", "", "Option key to choose among the waiting stage's edges (required)")
|
||||
f.StringVar(&o.feedback, "feedback", "", "Optional free-text feedback recorded with the decision")
|
||||
case "debug":
|
||||
f.StringVar(&o.harness, "harness", "", "Debugging harness: configured opencode/pi, or nvim")
|
||||
f.BoolVar(&o.yes, "yes", false, "Approve opening a debugging session without prompting")
|
||||
@@ -778,6 +782,38 @@ func (a App) Run(ctx context.Context, args []string) error {
|
||||
return a.finishRun(ctx, r, o, call)
|
||||
}
|
||||
return a.output(r.RunDetail)
|
||||
case "decide":
|
||||
if len(pos) < 1 || len(pos) > 2 {
|
||||
return fmt.Errorf("decide requires a run ID and an optional stage key")
|
||||
}
|
||||
id, err := strconv.ParseInt(pos[0], 10, 64)
|
||||
if err != nil || id <= 0 {
|
||||
return fmt.Errorf("run ID must be positive")
|
||||
}
|
||||
option := strings.TrimSpace(o.option)
|
||||
if option == "" {
|
||||
return fmt.Errorf("decide requires --option KEY")
|
||||
}
|
||||
stageKey := ""
|
||||
if len(pos) == 2 {
|
||||
stageKey = pos[1]
|
||||
}
|
||||
r, err := call(protocol.Message{Type: protocol.DecideRun, RunID: id, Stage: stageKey, Option: option, Feedback: o.feedback})
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
if r.RunDetail == nil {
|
||||
return fmt.Errorf("server did not return run detail")
|
||||
}
|
||||
if o.json {
|
||||
return a.output(r.RunDetail)
|
||||
}
|
||||
line := fmt.Sprintf("Decided run #%d: %s · %s", r.RunDetail.ID, option, r.RunDetail.Status)
|
||||
if feedback := strings.TrimSpace(o.feedback); feedback != "" {
|
||||
line += " · feedback: " + feedback
|
||||
}
|
||||
_, err = fmt.Fprintln(a.Out, line)
|
||||
return err
|
||||
case "title":
|
||||
if len(pos) != 2 {
|
||||
return fmt.Errorf("title requires a run ID and a title")
|
||||
|
||||
@@ -20,6 +20,7 @@ var usage = map[string]string{
|
||||
"runs": "runs [--pipeline NAME] [--json]",
|
||||
"inspect": "inspect <run-id> [--json]",
|
||||
"cancel": "cancel <run-id> [--json]",
|
||||
"decide": "decide <run-id> [stage] --option KEY [--feedback TEXT] [--json]",
|
||||
"retry": "retry <run-id> [--json [--wait [--wait-timeout DURATION]]]",
|
||||
"title": "title <run-id> \"<title>\" [--json]",
|
||||
"debug": "debug <run-id> [--json | --no-open]",
|
||||
@@ -44,6 +45,7 @@ var notes = map[string]string{
|
||||
"run": "Runs in your current directory after action confirmation (--yes skips it). Select a pipeline and compose a multiline task with Ctrl+S. Stage tools are enabled automatically; no file list or typed RUN confirmation. Cancellation does not undo edits. --title sets an explicit run title; without it the title is derived from the prompt. In JSON mode --wait polls until terminal; --wait-timeout bounds only the client wait after admission and is independent of per-request --timeout. A reached wait limit leaves the run active: inspect read-only with `inspect <run-id> --json`, or reattach with --wait reusing the original --request-key (never an automatic replay or cancel).",
|
||||
"retry": "Start a new attempt of a failed run with the same initial input, directory, pipeline version, and edit scope. Original history is retained. Already-completed side effects are not undone. --wait/--wait-timeout behave as for run: a reached wait limit leaves the new run active; inspect read-only with `inspect <run-id> --json`, or reattach with --wait and the original --request-key instead of starting a duplicate retry.",
|
||||
"title": "Rename a run's operator-facing title after the fact without touching its input, steps or execution. The title is collapsed to a single bounded line and recorded as explicitly set. `pipelines runs` and `pipelines inspect` then show it.",
|
||||
"decide": "Choose an option for a run waiting on a human stage. The run must be `waiting`; the option must be one of that stage's non-error edges. The stage is inferred from the run's current stage unless named. The choice and optional --feedback are recorded as the step's evidence (visible in inspect and the TUI) and the run resumes along the chosen edge. An unknown option is refused with the valid list; a repeated decision for an already-decided visit does not double-apply. Works across a server restart because the wait is persisted.",
|
||||
"debug": "Open a fresh configured harness conversation to investigate a run using inspect/show/runs CLI queries. --harness opencode|pi|nvim chooses another configured harness or read-only nvim packet. Does not resume implementation or retry. --json returns the prompt without launching anything.",
|
||||
"rpc": "Accepts a JSON protocol envelope; '-' reads stdin. Every TUI server operation is available here too. Mutating commands are not dry runs.",
|
||||
}
|
||||
|
||||
@@ -0,0 +1,85 @@
|
||||
package cli_test
|
||||
|
||||
import (
|
||||
"context"
|
||||
"encoding/json"
|
||||
"strconv"
|
||||
"strings"
|
||||
"testing"
|
||||
|
||||
"git.a-wan.net/alan/pipelines/internal/protocol"
|
||||
)
|
||||
|
||||
const cliHumanSource = "# stage gate\n\n```output\nDecision evidence.\n```\n\n```prompt\nApprove the release.\n```\n\n```edges\ngo -> #success\nhalt -> #failure\nerror -> #failure\n```\n\n```configs\ntype=human\n```\n\n"
|
||||
|
||||
func TestCLIDecideWaitingHumanRun(t *testing.T) {
|
||||
run, store, _ := setup(t)
|
||||
ctx := context.Background()
|
||||
if _, err := store.Submit(ctx, "human-ws", cliHumanSource); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
|
||||
output, err := run("run", "human-ws", "ship it", "--json", "--yes")
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
var started protocol.Message
|
||||
if err := json.Unmarshal([]byte(output), &started); err != nil || started.RunDetail == nil {
|
||||
t.Fatalf("run did not return detail: %v %s", err, output)
|
||||
}
|
||||
runID := started.RunDetail.ID
|
||||
|
||||
waitFor := func(status string) protocol.RunDetail {
|
||||
t.Helper()
|
||||
for i := 0; i < 100; i++ {
|
||||
text, err := run("inspect", strconv.FormatInt(runID, 10), "--json")
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
var detail protocol.RunDetail
|
||||
if err := json.Unmarshal([]byte(text), &detail); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if detail.Status == status {
|
||||
return detail
|
||||
}
|
||||
}
|
||||
t.Fatalf("run never reached %s", status)
|
||||
return protocol.RunDetail{}
|
||||
}
|
||||
waiting := waitFor(protocol.RunStatusWaiting)
|
||||
if len(waiting.Steps) != 1 || waiting.Steps[0].Status != protocol.StepStatusWaiting {
|
||||
t.Fatalf("waiting step not visible: %+v", waiting.Steps)
|
||||
}
|
||||
if prompt := protocol.WaitingPrompt(waiting.Steps[0].Output); !strings.Contains(prompt, "Approve the release") {
|
||||
t.Fatalf("waiting prompt not visible: %+v", waiting.Steps[0].Output)
|
||||
}
|
||||
|
||||
if _, err := run("decide", strconv.FormatInt(runID, 10)); err == nil || !strings.Contains(err.Error(), "--option") {
|
||||
t.Fatalf("missing --option was accepted: %v", err)
|
||||
}
|
||||
if _, err := run("decide", strconv.FormatInt(runID, 10), "--option", "launch"); err == nil || !strings.Contains(err.Error(), "valid options") {
|
||||
t.Fatalf("unknown option was accepted: %v", err)
|
||||
}
|
||||
|
||||
output, err = run("decide", strconv.FormatInt(runID, 10), "gate", "--option", "go", "--feedback", "approved", "--json")
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
var decided protocol.RunDetail
|
||||
if err := json.Unmarshal([]byte(output), &decided); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
final := waitFor("succeeded")
|
||||
gate := final.Steps[0]
|
||||
if gate.Outcome != "go" || gate.Target != protocol.SuccessEnd || gate.Output["feedback"] != "approved" || gate.Diagnostic != "" {
|
||||
t.Fatalf("decision evidence not recorded: %+v", gate)
|
||||
}
|
||||
if gate.Verdict == nil || gate.Verdict.Option != "go → success" || gate.Verdict.Reason != "approved" {
|
||||
t.Fatalf("derived verdict missing the decision: %+v", gate.Verdict)
|
||||
}
|
||||
|
||||
if _, err := run("help", "decide"); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
}
|
||||
@@ -26,6 +26,7 @@ EXECUTE
|
||||
runs List audited runs; --pipeline filters results
|
||||
inspect <run-id> Inspect stages, outputs, errors and status
|
||||
cancel <run-id> Cancel a run; changes are NOT rolled back
|
||||
decide <run-id> [stage] Choose an option for a run waiting on a person
|
||||
retry <run-id> Restart a failed run with its original input and directory
|
||||
title <run-id> "<title>" Rename a run after the fact; input/steps unchanged
|
||||
debug <run-id> Investigate a run with a configured harness or nvim
|
||||
|
||||
Reference in New Issue
Block a user