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). The body is ChatShellRunRequest. 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). 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. 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"` } // 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"` } // 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"` }