Files
pipelines/internal/protocol/chat_shell_run.go
T
alan e6bc57c901 Run operator shell commands in a chat's directory on the server
chat_shell_run starts $SHELL -lc in the chat session's directory in its own
process group, streams merged output to every watcher of the session, keeps a
1 MiB tail and persists each run; chat_shell_stop interrupts the group and
kills it after a grace period. chat_shell_share queues an ordinary prompt
with the command and a bounded output tail.
2026-11-09 15:55:14 +00:00

108 lines
4.9 KiB
Go

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"`
}