a6aff47117
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).
192 lines
6.6 KiB
Go
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])
|
|
}
|