e79ff9585f
Each completed step now exposes a verdict: the chosen option (outcome -> target), a bounded one-line reason with model/fallback/absent provenance, and the recorded artifacts the reason refers to. The store persists only the model-generated line in a new step_verdicts table and derives the fallback at read time (no backfill); the server generates the line once at completion, best-effort; the TUI renders it in the stage progress summary. The packaged debugging reference documents it.
190 lines
6.4 KiB
Go
190 lines
6.4 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.
|
|
var VerdictReasonKeys = []string{"verdict", "reason", "decision", "summary", "implementation_summary"}
|
|
|
|
// 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])
|
|
}
|