package protocol // Operator shell commands: commands the operator runs themselves inside one // chat's working directory (the chat's `!cmd`). They are owned by Pipelines, // not by the chat harness: the model never sees a command or its output unless // the operator explicitly shares it (chat_shell_share), which queues an // ordinary prompt. const ( // ChatShellRun starts one command. The body is ChatShellRunRequest // (session_id, command); the reply carries the new run in ChatShellRun. ChatShellRun = "chat_shell_run" // ChatShellStop interrupts one running command (SIGINT to its process // group, then SIGKILL after a grace period). The body is // ChatShellRunRequest (session_id, run_id); the reply echoes the run. ChatShellStop = "chat_shell_stop" // ChatShellRuns lists the session's recorded runs, oldest first, each with // at most ChatShellRunListOutput bytes of its retained output tail. The // body is ChatQuery. ChatShellRuns = "chat_shell_runs" // ChatShellRunOutput reads one run with its whole retained output (at most // ChatShellRunRetained bytes) and its plain-text rendering. The body is // ChatShellRunRequest; a nonzero After asks only for the output from that // absolute byte on (a reconnecting client resuming its copy). ChatShellRunOutput = "chat_shell_run_output" // ChatShellShare queues an ordinary prompt carrying the run's command, exit // status and bounded output tail. The body is ChatShellRunRequest; the // reply is the chat_prompt acknowledgement. ChatShellShare = "chat_shell_share" // ChatShellRunEvent is pushed to every client watching the session: a // lifecycle change (Run set) or an output chunk (Output set). Output // chunks of one run are pushed in order; their byte offsets are the // stream's sequence numbers. ChatShellRunEvent = "chat_shell_run_event" ) // ChatShellRunRecord status values. Running is the only non-final status. const ( ChatShellRunRunning = "running" ChatShellRunExited = "exited" ChatShellRunStopped = "stopped" ChatShellRunFailed = "failed" ChatShellRunInterrupted = "interrupted" ) // Bounds of operator shell commands. const ( // ChatShellRunCommandLimit bounds one command line. ChatShellRunCommandLimit = 16 << 10 // ChatShellRunRetained is the retained (and persisted) output tail of one // run: older output is dropped and the record says so. ChatShellRunRetained = 1 << 20 // ChatShellRunListOutput bounds the output tail each run carries in a // chat_shell_runs list, so a long history stays one small frame. ChatShellRunListOutput = 64 << 10 // ChatShellRunChunkLimit bounds one live output frame. ChatShellRunChunkLimit = 64 << 10 // ChatShellRunShareOutput bounds the output tail shared with the agent. ChatShellRunShareOutput = 16 << 10 // ChatShellRunConcurrent bounds the commands one session runs at once. ChatShellRunConcurrent = 4 // ChatShellRunHistory bounds the finished runs kept per session. ChatShellRunHistory = 50 ) // ChatShellRunRequest names one session and either a new command or a run. // OperationID is the optional retry identity of chat_shell_share's prompt. // Cols and Rows size a new run's terminal (chat_shell_run) or resize a running // one (chat_shell_resize); Data is chat_shell_input's typed text; After is // chat_shell_run_output's resume offset. type ChatShellRunRequest struct { SessionID string `json:"session_id"` Command string `json:"command,omitempty"` RunID string `json:"run_id,omitempty"` OperationID string `json:"operation_id,omitempty"` Cols int `json:"cols,omitempty"` Rows int `json:"rows,omitempty"` Data string `json:"data,omitempty"` After int64 `json:"after,omitempty"` } // ChatShellRunRecord is one operator command and what it produced. Output is // the retained text starting at absolute byte OutputStart of everything the // command wrote (stdout and stderr merged); OutputBytes is that total. A record // with OutputStart > 0 dropped its beginning. Times are epoch milliseconds. // ExitCode is set once the process exited with a code; a signal-terminated // or never-started command has none. type ChatShellRunRecord struct { ID string `json:"id"` SessionID string `json:"session_id"` Command string `json:"command"` Directory string `json:"directory"` Status string `json:"status"` ExitCode *int `json:"exit_code,omitempty"` Signal string `json:"signal,omitempty"` Error string `json:"error,omitempty"` StartedAt int64 `json:"started_at"` EndedAt int64 `json:"ended_at,omitempty"` DurationMS int64 `json:"duration_ms,omitempty"` Output string `json:"output,omitempty"` OutputStart int64 `json:"output_start,omitempty"` OutputBytes int64 `json:"output_bytes,omitempty"` // Truncated is true when Output does not hold everything the command // wrote (OutputStart > 0). Truncated bool `json:"truncated,omitempty"` // Terminal is true when the command runs in a pseudo-terminal of Cols x // Rows: Output is then the raw terminal stream, and input is accepted // while it runs. Terminal bool `json:"terminal,omitempty"` Cols int `json:"cols,omitempty"` Rows int `json:"rows,omitempty"` // Text is the plain-text rendering of Output (escape sequences removed, // carriage-return redraws applied): what Copy output copies and Send to // agent shares. Only chat_shell_run_output carries it. Text string `json:"text,omitempty"` } // ChatShellRunEventFrame is one live change to a run. A lifecycle frame sets // Run (without output); an output frame sets Output covering absolute bytes // [Offset, End). A client whose own copy ends before Offset missed output and // shows that gap rather than joining unrelated text. type ChatShellRunEventFrame struct { SessionID string `json:"session_id"` RunID string `json:"run_id"` Run *ChatShellRunRecord `json:"run,omitempty"` Output string `json:"output,omitempty"` Offset int64 `json:"offset,omitempty"` End int64 `json:"end,omitempty"` }