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"` } type RunSummary struct { 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"` } // 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 } type RunStep struct { Control *ControlEvidence `json:"control,omitempty"` FileChanges *StageFileChanges `json:"file_changes,omitempty"` Verdict *StageVerdict `json:"verdict,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"` } 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"` } // 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"` 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"` // 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"` }