package protocol import "strings" const ( RunPipeline = "run_pipeline" RunStarted = "run_started" ListRuns = "list_runs" Runs = "runs" GetRun = "get_run" Run = "run" CancelRun = "cancel_run" RetryRun = "retry_run" DecideRun = "decide_run" SetRunTitle = "set_run_title" GetRunEvidence = "get_run_evidence" RunEvidence = "run_evidence" ) // Waiting statuses. A human stage pauses its run without a live goroutine, so // the run and its step persist these statuses and the decision path resumes // them. Store, server, CLI and TUI read the one pair below, never a literal. const ( RunStatusQueued = "queued" RunStatusWaiting = "waiting" RunStatusRunning = "running" StepStatusRunning = "running" StepStatusWaiting = "waiting" // NotifyWaiting is the notification event a human stage emits when it parks // the run. It is the same value the `on=` policy accepts. NotifyWaiting = "waiting" ) // Waiting evidence keys. A human stage records its operator instructions and // its ordered selectable options in the step output, so inspect and the TUI are // self-contained without re-reading the pinned graph. const ( WaitingPromptKey = "prompt" WaitingOptionsKey = "options" ) // Decision evidence keys. A decided human step records the operator's chosen // option and optional feedback in its output, so the choice stays visible in // inspect and the TUI. They are the one definition of those keys. const ( DecisionOptionKey = "option" DecisionFeedbackKey = "feedback" ) // NewWaitingEvidence builds the self-contained evidence a human stage persists // at wait time: the operator instructions and the ordered options to choose. func NewWaitingEvidence(prompt string, options []string) map[string]any { ordered := make([]any, len(options)) for i, option := range options { ordered[i] = option } return map[string]any{WaitingPromptKey: prompt, WaitingOptionsKey: ordered} } // WaitingPrompt reads the recorded operator instructions from a waiting step's // output, or "" when none were recorded. func WaitingPrompt(output map[string]any) string { prompt, _ := output[WaitingPromptKey].(string) return prompt } // WaitingOptions reads the recorded selectable options from a waiting step's // output, accepting the string and generic forms JSON decoding produces. func WaitingOptions(output map[string]any) []string { switch options := output[WaitingOptionsKey].(type) { case []string: return options case []any: result := make([]string, 0, len(options)) for _, option := range options { if text, ok := option.(string); ok { result = append(result, text) } } return result } return nil } // DecisionEvidence reads the recorded choice and feedback from a decided human // step's output, or empty strings when none were recorded. It is the read side // of DecisionOptionKey/DecisionFeedbackKey. func DecisionEvidence(output map[string]any) (option, feedback string) { option, _ = output[DecisionOptionKey].(string) feedback, _ = output[DecisionFeedbackKey].(string) return option, feedback } type SessionEvidence struct { Sequence int `json:"sequence"` SessionID string `json:"session_id"` Backend string `json:"backend"` Directory string `json:"directory"` Data string `json:"data,omitempty"` Diagnostic string `json:"diagnostic,omitempty"` } // SessionExport is the recorded evidence of one stage's session file export: // the html file name written under the step's artifacts directory, its byte // size, the decoded message count, the source, whether the export was truncated // and a sanitized diagnostic. It is observed server-side evidence, not a model // claim. A record written before the HTML-only change also carried markdown and // markdown_bytes; readers ignore those fields. type SessionExport struct { SessionID string `json:"session_id,omitempty"` Backend string `json:"backend,omitempty"` Source string `json:"source,omitempty"` HTML string `json:"html,omitempty"` HTMLBytes int64 `json:"html_bytes,omitempty"` Messages int `json:"messages"` Truncated bool `json:"truncated,omitempty"` Diagnostic string `json:"diagnostic,omitempty"` } type RunSummary struct { ResourceWait *ResourceWait `json:"resource_wait,omitempty"` ID int64 `json:"id"` PipelineID int64 `json:"pipeline_id"` Name string `json:"name"` // Title is the operator-facing, bounded single-line description of what the // run is for, generated from its prompt. It is never empty for a new run; // historical rows predating the title column may omit it. Title string `json:"title,omitempty"` Version int `json:"version"` ContentHash string `json:"content_hash"` Status string `json:"status"` Executing bool `json:"executing"` Outcome string `json:"outcome"` CurrentStage string `json:"current_stage"` Workspace string `json:"workspace,omitempty"` CreatedAt string `json:"created_at"` FinishedAt string `json:"finished_at"` Diagnostic string `json:"diagnostic"` ResultPreview string `json:"result_preview,omitempty"` CompletedSteps int `json:"completed_steps"` // Model and StageModels are the launch-time overrides this run records so it // stays reproducible: Model covers every model stage and StageModels overrides // individual stages by key. They are empty for a run that used the pinned // models and for historical rows. Model string `json:"model,omitempty"` StageModels map[string]string `json:"stage_models,omitempty"` } // ResourceWait is bounded public queue metadata. Ownership credentials stay private. type ResourceWait struct { Resource string `json:"resource"` Stage string `json:"stage"` Sequence int `json:"sequence"` QueuedSince string `json:"queued_since"` } // ResourceCleanupConfirmedKey lets a stage report failed restoration without // pretending that tool idleness also proves the resource is ready. An explicit // false (or malformed value) vetoes release; it never authorizes release alone. const ResourceCleanupConfirmedKey = "resource_cleanup_confirmed" // Label is the operator-facing name of a run: the generated Title when the // server stored one, otherwise the pipeline Name (historical rows predate // titles). It is the single definition shared by the CLI and TUI. func (r RunSummary) Label() string { if title := strings.TrimSpace(r.Title); title != "" { return title } return r.Name } // StatusLabel separates resource contention from a human decision everywhere. func (r RunSummary) StatusLabel() string { if r.ResourceWait != nil { return "Waiting for resource " + r.ResourceWait.Resource } return r.Status } type RunStep struct { Control *ControlEvidence `json:"control,omitempty"` FileChanges *StageFileChanges `json:"file_changes,omitempty"` Verdict *StageVerdict `json:"verdict,omitempty"` SessionExport *SessionExport `json:"session_export,omitempty"` Usage *StageUsage `json:"usage,omitempty"` Notifications []NotificationReceipt `json:"notifications,omitempty"` Artifacts []StageArtifact `json:"artifacts,omitempty"` Sequence int `json:"sequence"` Stage string `json:"stage"` Status string `json:"status"` Outcome string `json:"outcome"` Target string `json:"target"` Input map[string]any `json:"input"` Output map[string]any `json:"output"` Diagnostic string `json:"diagnostic"` SessionID string `json:"session_id"` AgentActive bool `json:"agent_active"` Transcript string `json:"transcript"` // Provider and Model are the effective provider/model this visit actually ran // with, recorded for every model stage (including failures). They are empty // for non-model stages and historical steps. Provider string `json:"provider,omitempty"` Model string `json:"model,omitempty"` // ArtifactsSkipped and ArtifactsTruncated count files excluded from the // bounded per-step scan (over the file/size cap) and by the total budget. ArtifactsSkipped int `json:"artifacts_skipped,omitempty"` ArtifactsTruncated int `json:"artifacts_truncated,omitempty"` StartedAt string `json:"started_at"` FinishedAt string `json:"finished_at"` } // StageArtifact is one file a stage left in its artifacts directory. It is // observed server-side evidence, not a model's claim. An empty Artifacts slice // means no files were recorded (including historical steps). type StageArtifact struct { Name string `json:"name"` SizeBytes int64 `json:"size_bytes"` ContentType string `json:"content_type"` URL string `json:"url"` } // LegacySessionMarkdownArtifact is the retired markdown session export file name. // Nothing writes it any more, but a run recorded before the HTML-only change // still lists session.md among its stored artifacts: it is dated evidence that is // never presented, so every listing hides it rather than showing it beside the // session html. This is the one definition of the retired name, shared by the // stage export and the clients. const LegacySessionMarkdownArtifact = "session.md" // PresentedArtifacts is one step's recorded artifacts as they are presented: the // files with the retired markdown session export filtered out. It is the single // rule every Go artifact listing derives from, so a stage's artifacts never show // a session markdown beside the session html and a recorded count can never // disagree with the tiles. It never mutates the step and returns nil when nothing // is presented; the stored record still carries the legacy file. Pure, // O(artifacts) per step. func (s RunStep) PresentedArtifacts() []StageArtifact { if len(s.Artifacts) == 0 { return nil } presented := make([]StageArtifact, 0, len(s.Artifacts)) for _, artifact := range s.Artifacts { if artifact.Name == LegacySessionMarkdownArtifact { continue } presented = append(presented, artifact) } if len(presented) == 0 { return nil } return presented } // StageUsage is the usage one model stage actually reported, carried from the // stage's already-measured budget accounting rather than a second measurement or // a transcript parse. TokensTotal/TokensKnown are the reported total; TokensIn // and TokensOut are set only when the harness reported the input/output split // (SplitKnown), so a harness that reports only a total (Pi) never has its total // presented as input tokens. CostUSD is present only when CostKnown: a stage // whose provider reported no cost carries CostKnown=false and no fabricated or // zero cost. type StageUsage struct { TokensIn int64 `json:"tokens_in,omitempty"` TokensOut int64 `json:"tokens_out,omitempty"` TokensTotal int64 `json:"tokens_total"` TokensKnown bool `json:"tokens_known"` SplitKnown bool `json:"split_known,omitempty"` CostUSD float64 `json:"cost_usd,omitempty"` CostKnown bool `json:"cost_known"` } // RunUsage is the totalled reported usage of a run's model stages. It is summed // in one pass over the run's already-loaded steps, so reading it adds no query. // A stage that reported no cost is counted in CostUnknownStages and contributes // no cost; a stage that reported only a total contributes to TokensTotal but not // to the in/out split, and SplitKnown is true only when every stage that // reported tokens also reported the split. type RunUsage struct { TokensTotal int64 `json:"tokens_total"` TokensIn int64 `json:"tokens_in,omitempty"` TokensOut int64 `json:"tokens_out,omitempty"` SplitKnown bool `json:"split_known"` CostUSD float64 `json:"cost_usd,omitempty"` Stages int `json:"stages"` TokensKnownStages int `json:"tokens_known_stages"` SplitUnknownStages int `json:"split_unknown_stages,omitempty"` CostKnownStages int `json:"cost_known_stages"` CostUnknownStages int `json:"cost_unknown_stages,omitempty"` } // TotalUsage sums the per-stage usage of a run's steps into one run total. It is // the one definition of the run total, so per-run inspection cannot drift from // the history-wide aggregate over the same rows. func TotalUsage(steps []RunStep) *RunUsage { total := &RunUsage{} splitComplete := true for i := range steps { usage := steps[i].Usage if usage == nil { continue } total.Stages++ if usage.TokensKnown { total.TokensKnownStages++ total.TokensTotal += usage.TokensTotal if usage.SplitKnown { total.TokensIn += usage.TokensIn total.TokensOut += usage.TokensOut } else { splitComplete = false total.SplitUnknownStages++ } } if usage.CostKnown { total.CostKnownStages++ total.CostUSD += usage.CostUSD } else { total.CostUnknownStages++ } } if total.Stages == 0 { return nil } total.SplitKnown = total.TokensKnownStages > 0 && splitComplete return total } type MemoryRead struct { Source string `json:"source"` Sequence int `json:"sequence"` // zero denotes original run input } type ControlEvidence struct { Visit int `json:"visit"` MaxVisits int `json:"max_visits"` LimitReached bool `json:"limit_reached,omitempty"` ModelTarget string `json:"model_target,omitempty"` Memory map[string]MemoryRead `json:"memory,omitempty"` ResourceTarget *ResourceTarget `json:"resource_target,omitempty"` } // StageFileChanges is observed workspace evidence, not a model's claim of authorship. // Nil means no capture was retained (including historical steps). type StageFileChanges struct { Omitted int `json:"omitted,omitempty"` Scope string `json:"scope,omitempty"` Status string `json:"status"` // complete, partial, unavailable Files []FileChange `json:"files"` Skipped int `json:"skipped"` Diagnostic string `json:"diagnostic,omitempty"` } type FileChange struct { Path string `json:"path"` Kind string `json:"kind"` // added, modified, deleted Patch string `json:"patch,omitempty"` Binary bool `json:"binary,omitempty"` Truncated bool `json:"truncated,omitempty"` BeforeMode string `json:"before_mode,omitempty"` AfterMode string `json:"after_mode,omitempty"` } type NotificationReceipt struct { Destination string `json:"destination"` Status string `json:"status"` Filename string `json:"filename,omitempty"` MessageID string `json:"message_id,omitempty"` AttachmentURL string `json:"attachment_url,omitempty"` Diagnostic string `json:"diagnostic,omitempty"` } type RunDetail struct { RunSummary Graph Graph `json:"graph"` RetryOf int64 `json:"retry_of,omitempty"` RetryMode string `json:"retry_mode,omitempty"` RetrySource int64 `json:"retry_source,omitempty"` RetrySourceVersion int `json:"retry_source_version,omitempty"` RetrySourceHash string `json:"retry_source_hash,omitempty"` Workspace string `json:"workspace"` AllowTools bool `json:"allow_tools"` WritePaths []string `json:"write_paths"` Input map[string]any `json:"input"` Output map[string]any `json:"output"` Steps []RunStep `json:"steps"` // Usage is the totalled reported usage of the run's model stages, summed in // one pass over Steps. It is absent for a run with no model usage recorded // (including historical runs). Usage *RunUsage `json:"usage,omitempty"` // TitleSource is "model" when Title came from the shared summariser or // "fallback" when it was derived from the prompt; TitleModel names the model // that produced a model title. They are retained so a diagnosis can tell the // two apart and see which model was used. TitleSource string `json:"title_source,omitempty"` TitleModel string `json:"title_model,omitempty"` }