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]) }