03123c23fd
chat_shell_dismiss hides finished runs from every readback and pushes a dismissal frame to every watcher; chat_shell_restore undoes it within a 30 s window, after which the command, output and error are purged and only a tombstone remains, reported by chat_shell_runs for clients that missed the event.
132 lines
6.2 KiB
Go
132 lines
6.2 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) 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"`
|
|
// RunIDs names the runs of chat_shell_dismiss and chat_shell_restore.
|
|
RunIDs []string `json:"run_ids,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 dismissal frame sets Dismissed (the card goes away). 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"`
|
|
Dismissed bool `json:"dismissed,omitempty"`
|
|
}
|