package protocol // Server-pushed run state. A client sends subscribe (scoped to the workspace and // optionally to explicit run ids) to ask for the runs it displays: the server // first returns the current state of those runs so a reconnecting client // re-syncs, then pushes a compact run_event delta on every meaningful // transition. It sends unsubscribe to stop. Like chat_event, run_event is a // server-pushed frame with no matching request, so both fields are optional and // older peers ignore them. const ( Subscribe = "subscribe" Unsubscribe = "unsubscribe" RunEvent = "run_event" ) // RunEventFrame is the server-pushed run_event delta. It carries only the values // that changed, never the whole run: the run's identity, status, outcome, current // stage, completed-step count and timestamps, plus the latest changed step and // compact routing facts for all changed visits preserved during coalescing. // Every field is optional so an older peer ignores what it does not know and a // client can fold the frame into its cached run. // // PipelineID, Name, Title and Version are the pipeline identity and stored title // a list row shows, so a client that has never held the run can insert its row // from the frame instead of re-reading the whole list. They repeat on every // frame (pipeline identity never changes mid-run). type RunEventFrame struct { Scheduled bool `json:"scheduled"` ScheduleID int64 `json:"schedule_id,omitempty"` ScheduleName string `json:"schedule_name,omitempty"` // SessionExportUpdated requests a detail refresh even when the stage/run // outcome is unchanged. It never fabricates a second stage completion. SessionExportUpdated bool `json:"session_export_updated,omitempty"` // GraphEvidence seeds a complete compact snapshot; GraphVisits preserves // changed visits even when Step is replaced during frame coalescing. GraphEvidence *RunGraphEvidence `json:"graph_evidence,omitempty"` GraphVisits []RunGraphVisit `json:"graph_visits,omitempty"` NotifyMode string `json:"notify_mode,omitempty"` RunID int64 `json:"run_id"` Workspace string `json:"workspace,omitempty"` // PipelineID, Name, Title and Version identify the run's pipeline and its // operator-facing title, so a new run's row can be built without a fetch. PipelineID int64 `json:"pipeline_id,omitempty"` Name string `json:"name,omitempty"` Title string `json:"title,omitempty"` Version int `json:"version,omitempty"` Status string `json:"status,omitempty"` // On a lifecycle frame, zero/absence clears a prior export wait. ExportPendingSequence int `json:"export_pending_sequence,omitempty"` CancelRequested bool `json:"cancel_requested,omitempty"` CleanupUnconfirmed bool `json:"cleanup_unconfirmed,omitempty"` Outcome string `json:"outcome,omitempty"` CurrentStage string `json:"current_stage,omitempty"` CompletedSteps int `json:"completed_steps,omitempty"` CreatedAt string `json:"created_at,omitempty"` FinishedAt string `json:"finished_at,omitempty"` // Artifacts is the number of files recorded for the referenced step, so a // client can surface artifact capture without reading the step. Artifacts int `json:"artifacts,omitempty"` // Step is present when a single step changed (started, finished or waiting). Step *RunStepDelta `json:"step,omitempty"` } // RunStepDelta is the compact change of one step within a RunEventFrame. It is a // delta, not a RunStep: it omits the input/output, transcript, file changes and // artifact bytes a full step carries. type RunStepDelta struct { Sequence int `json:"sequence"` Stage string `json:"stage,omitempty"` Status string `json:"status,omitempty"` Outcome string `json:"outcome,omitempty"` Target string `json:"target,omitempty"` Diagnostic string `json:"diagnostic,omitempty"` Artifacts int `json:"artifacts,omitempty"` }