8f3036bd3b
Add a server-pushed run_event frame so a client no longer has to poll once a second to notice run changes. - protocol: RunEventFrame/RunStepDelta compact delta (run id, workspace, status, outcome, current stage, completed-step count, timestamps and an optional single step delta), plus subscribe/unsubscribe/run_event types and the optional RunEvent/RunIDs message fields. All fields optional so older peers ignore them. - server: runEventHub with per-connection subscriptions scoped to a workspace (and optional explicit run ids), one bounded writer goroutine per subscription, slow-subscriber drop, per-client subscription cap and a ~220ms per-run coalescer that flushes pending deltas before a terminal frame. - runner: emit deltas on created/queued, queued->running and step start, human waiting, step finish (outcome, target, diagnostic, artifacts and completed count), terminal finish, cancel of a waiting run and decide/resume; emitRun is a no-op without a hub. - websocket: subscribe seeds current state before the ack, unsubscribe and connection teardown drop subscriptions, and pushed frames reuse the connection write closure. - tests: protocol golden-JSON wire shape plus websocket coverage for the started-run frame sequence, subscribe current-state snapshot, silent unsubscribed/never-subscribed clients, workspace isolation and a bounded coalescing frame count. - docs: note subscribe/unsubscribe/run_event in docs/cli.md; TUI and Android still poll in this release.
241 lines
9.3 KiB
Go
241 lines
9.3 KiB
Go
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"`
|
|
}
|