sandbox-agent 0.2.1 → 0.3.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { NewSessionRequest, AnyMessage, AcpEnvelopeDirection, NewSessionResponse, PromptRequest, PromptResponse } from 'acp-http-client';
+import { NewSessionRequest, SessionConfigOption, SessionModeState, AnyMessage, AcpEnvelopeDirection, NewSessionResponse, PromptRequest, PromptResponse, SetSessionModeResponse, SetSessionConfigOptionResponse } from 'acp-http-client';
 export { AcpRpcError } from 'acp-http-client';
 
 type SandboxAgentSpawnLogMode = "inherit" | "pipe" | "silent";
@@ -85,7 +85,7 @@ interface components {
             agents: components["schemas"]["AgentInfo"][];
         };
         /** @enum {string} */
-        ErrorType: "invalid_request" | "conflict" | "unsupported_agent" | "agent_not_installed" | "install_failed" | "agent_process_exited" | "token_invalid" | "permission_denied" | "not_acceptable" | "unsupported_media_type" | "session_not_found" | "session_already_exists" | "mode_not_supported" | "stream_error" | "timeout";
+        ErrorType: "invalid_request" | "conflict" | "unsupported_agent" | "agent_not_installed" | "install_failed" | "agent_process_exited" | "token_invalid" | "permission_denied" | "not_acceptable" | "unsupported_media_type" | "not_found" | "session_not_found" | "session_already_exists" | "mode_not_supported" | "stream_error" | "timeout";
         FsActionResponse: {
             path: string;
         };
@@ -182,6 +182,116 @@ interface components {
             type: string;
             [key: string]: unknown;
         };
+        ProcessConfig: {
+            /** Format: int64 */
+            defaultRunTimeoutMs: number;
+            maxConcurrentProcesses: number;
+            maxInputBytesPerRequest: number;
+            maxLogBytesPerProcess: number;
+            maxOutputBytes: number;
+            /** Format: int64 */
+            maxRunTimeoutMs: number;
+        };
+        ProcessCreateRequest: {
+            args?: string[];
+            command: string;
+            cwd?: string | null;
+            env?: {
+                [key: string]: string;
+            };
+            interactive?: boolean;
+            tty?: boolean;
+        };
+        ProcessInfo: {
+            args: string[];
+            command: string;
+            /** Format: int64 */
+            createdAtMs: number;
+            cwd?: string | null;
+            /** Format: int32 */
+            exitCode?: number | null;
+            /** Format: int64 */
+            exitedAtMs?: number | null;
+            id: string;
+            interactive: boolean;
+            /** Format: int32 */
+            pid?: number | null;
+            status: components["schemas"]["ProcessState"];
+            tty: boolean;
+        };
+        ProcessInputRequest: {
+            data: string;
+            encoding?: string | null;
+        };
+        ProcessInputResponse: {
+            bytesWritten: number;
+        };
+        ProcessListResponse: {
+            processes: components["schemas"]["ProcessInfo"][];
+        };
+        ProcessLogEntry: {
+            data: string;
+            encoding: string;
+            /** Format: int64 */
+            sequence: number;
+            stream: components["schemas"]["ProcessLogsStream"];
+            /** Format: int64 */
+            timestampMs: number;
+        };
+        ProcessLogsQuery: {
+            follow?: boolean | null;
+            /** Format: int64 */
+            since?: number | null;
+            stream?: components["schemas"]["ProcessLogsStream"] | null;
+            tail?: number | null;
+        };
+        ProcessLogsResponse: {
+            entries: components["schemas"]["ProcessLogEntry"][];
+            processId: string;
+            stream: components["schemas"]["ProcessLogsStream"];
+        };
+        /** @enum {string} */
+        ProcessLogsStream: "stdout" | "stderr" | "combined" | "pty";
+        ProcessRunRequest: {
+            args?: string[];
+            command: string;
+            cwd?: string | null;
+            env?: {
+                [key: string]: string;
+            };
+            maxOutputBytes?: number | null;
+            /** Format: int64 */
+            timeoutMs?: number | null;
+        };
+        ProcessRunResponse: {
+            /** Format: int64 */
+            durationMs: number;
+            /** Format: int32 */
+            exitCode?: number | null;
+            stderr: string;
+            stderrTruncated: boolean;
+            stdout: string;
+            stdoutTruncated: boolean;
+            timedOut: boolean;
+        };
+        ProcessSignalQuery: {
+            /** Format: int64 */
+            waitMs?: number | null;
+        };
+        /** @enum {string} */
+        ProcessState: "running" | "exited";
+        ProcessTerminalResizeRequest: {
+            /** Format: int32 */
+            cols: number;
+            /** Format: int32 */
+            rows: number;
+        };
+        ProcessTerminalResizeResponse: {
+            /** Format: int32 */
+            cols: number;
+            /** Format: int32 */
+            rows: number;
+        };
         /** @enum {string} */
         ServerStatus: "running" | "stopped";
         ServerStatusInfo: {
@@ -694,12 +804,495 @@ interface operations {
             };
         };
     };
+    /**
+     * List all managed processes.
+     * @description Returns a list of all processes (running and exited) currently tracked
+     * by the runtime, sorted by process ID.
+     */
+    get_v1_processes: {
+        responses: {
+            /** @description List processes */
+            200: {
+                content: {
+                    "application/json": components["schemas"]["ProcessListResponse"];
+                };
+            };
+            /** @description Process API unsupported on this platform */
+            501: {
+                content: {
+                    "application/json": components["schemas"]["ProblemDetails"];
+                };
+            };
+        };
+    };
+    /**
+     * Create a long-lived managed process.
+     * @description Spawns a new process with the given command and arguments. Supports both
+     * pipe-based and PTY (tty) modes. Returns the process descriptor on success.
+     */
+    post_v1_processes: {
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["ProcessCreateRequest"];
+            };
+        };
+        responses: {
+            /** @description Started process */
+            200: {
+                content: {
+                    "application/json": components["schemas"]["ProcessInfo"];
+                };
+            };
+            /** @description Invalid request */
+            400: {
+                content: {
+                    "application/json": components["schemas"]["ProblemDetails"];
+                };
+            };
+            /** @description Process limit or state conflict */
+            409: {
+                content: {
+                    "application/json": components["schemas"]["ProblemDetails"];
+                };
+            };
+            /** @description Process API unsupported on this platform */
+            501: {
+                content: {
+                    "application/json": components["schemas"]["ProblemDetails"];
+                };
+            };
+        };
+    };
+    /**
+     * Get process runtime configuration.
+     * @description Returns the current runtime configuration for the process management API,
+     * including limits for concurrency, timeouts, and buffer sizes.
+     */
+    get_v1_processes_config: {
+        responses: {
+            /** @description Current runtime process config */
+            200: {
+                content: {
+                    "application/json": components["schemas"]["ProcessConfig"];
+                };
+            };
+            /** @description Process API unsupported on this platform */
+            501: {
+                content: {
+                    "application/json": components["schemas"]["ProblemDetails"];
+                };
+            };
+        };
+    };
+    /**
+     * Update process runtime configuration.
+     * @description Replaces the runtime configuration for the process management API.
+     * Validates that all values are non-zero and clamps default timeout to max.
+     */
+    post_v1_processes_config: {
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["ProcessConfig"];
+            };
+        };
+        responses: {
+            /** @description Updated runtime process config */
+            200: {
+                content: {
+                    "application/json": components["schemas"]["ProcessConfig"];
+                };
+            };
+            /** @description Invalid config */
+            400: {
+                content: {
+                    "application/json": components["schemas"]["ProblemDetails"];
+                };
+            };
+            /** @description Process API unsupported on this platform */
+            501: {
+                content: {
+                    "application/json": components["schemas"]["ProblemDetails"];
+                };
+            };
+        };
+    };
+    /**
+     * Run a one-shot command.
+     * @description Executes a command to completion and returns its stdout, stderr, exit code,
+     * and duration. Supports configurable timeout and output size limits.
+     */
+    post_v1_processes_run: {
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["ProcessRunRequest"];
+            };
+        };
+        responses: {
+            /** @description One-off command result */
+            200: {
+                content: {
+                    "application/json": components["schemas"]["ProcessRunResponse"];
+                };
+            };
+            /** @description Invalid request */
+            400: {
+                content: {
+                    "application/json": components["schemas"]["ProblemDetails"];
+                };
+            };
+            /** @description Process API unsupported on this platform */
+            501: {
+                content: {
+                    "application/json": components["schemas"]["ProblemDetails"];
+                };
+            };
+        };
+    };
+    /**
+     * Get a single process by ID.
+     * @description Returns the current state of a managed process including its status,
+     * PID, exit code, and creation/exit timestamps.
+     */
+    get_v1_process: {
+        parameters: {
+            path: {
+                /** @description Process ID */
+                id: string;
+            };
+        };
+        responses: {
+            /** @description Process details */
+            200: {
+                content: {
+                    "application/json": components["schemas"]["ProcessInfo"];
+                };
+            };
+            /** @description Unknown process */
+            404: {
+                content: {
+                    "application/json": components["schemas"]["ProblemDetails"];
+                };
+            };
+            /** @description Process API unsupported on this platform */
+            501: {
+                content: {
+                    "application/json": components["schemas"]["ProblemDetails"];
+                };
+            };
+        };
+    };
+    /**
+     * Delete a process record.
+     * @description Removes a stopped process from the runtime. Returns 409 if the process
+     * is still running; stop or kill it first.
+     */
+    delete_v1_process: {
+        parameters: {
+            path: {
+                /** @description Process ID */
+                id: string;
+            };
+        };
+        responses: {
+            /** @description Process deleted */
+            204: {
+                content: never;
+            };
+            /** @description Unknown process */
+            404: {
+                content: {
+                    "application/json": components["schemas"]["ProblemDetails"];
+                };
+            };
+            /** @description Process is still running */
+            409: {
+                content: {
+                    "application/json": components["schemas"]["ProblemDetails"];
+                };
+            };
+            /** @description Process API unsupported on this platform */
+            501: {
+                content: {
+                    "application/json": components["schemas"]["ProblemDetails"];
+                };
+            };
+        };
+    };
+    /**
+     * Write input to a process.
+     * @description Sends data to a process's stdin (pipe mode) or PTY writer (tty mode).
+     * Data can be encoded as base64, utf8, or text. Returns 413 if the decoded
+     * payload exceeds the configured `maxInputBytesPerRequest` limit.
+     */
+    post_v1_process_input: {
+        parameters: {
+            path: {
+                /** @description Process ID */
+                id: string;
+            };
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["ProcessInputRequest"];
+            };
+        };
+        responses: {
+            /** @description Input accepted */
+            200: {
+                content: {
+                    "application/json": components["schemas"]["ProcessInputResponse"];
+                };
+            };
+            /** @description Invalid request */
+            400: {
+                content: {
+                    "application/json": components["schemas"]["ProblemDetails"];
+                };
+            };
+            /** @description Process not writable */
+            409: {
+                content: {
+                    "application/json": components["schemas"]["ProblemDetails"];
+                };
+            };
+            /** @description Input exceeds configured limit */
+            413: {
+                content: {
+                    "application/json": components["schemas"]["ProblemDetails"];
+                };
+            };
+            /** @description Process API unsupported on this platform */
+            501: {
+                content: {
+                    "application/json": components["schemas"]["ProblemDetails"];
+                };
+            };
+        };
+    };
+    /**
+     * Send SIGKILL to a process.
+     * @description Sends SIGKILL to the process and optionally waits up to `waitMs`
+     * milliseconds for the process to exit before returning.
+     */
+    post_v1_process_kill: {
+        parameters: {
+            query?: {
+                /** @description Wait up to N ms for process to exit */
+                waitMs?: number | null;
+            };
+            path: {
+                /** @description Process ID */
+                id: string;
+            };
+        };
+        responses: {
+            /** @description Kill signal sent */
+            200: {
+                content: {
+                    "application/json": components["schemas"]["ProcessInfo"];
+                };
+            };
+            /** @description Unknown process */
+            404: {
+                content: {
+                    "application/json": components["schemas"]["ProblemDetails"];
+                };
+            };
+            /** @description Process API unsupported on this platform */
+            501: {
+                content: {
+                    "application/json": components["schemas"]["ProblemDetails"];
+                };
+            };
+        };
+    };
+    /**
+     * Fetch process logs.
+     * @description Returns buffered log entries for a process. Supports filtering by stream
+     * type, tail count, and sequence-based resumption. When `follow=true`,
+     * returns an SSE stream that replays buffered entries then streams live output.
+     */
+    get_v1_process_logs: {
+        parameters: {
+            query?: {
+                /** @description stdout|stderr|combined|pty */
+                stream?: components["schemas"]["ProcessLogsStream"] | null;
+                /** @description Tail N entries */
+                tail?: number | null;
+                /** @description Follow via SSE */
+                follow?: boolean | null;
+                /** @description Only entries with sequence greater than this */
+                since?: number | null;
+            };
+            path: {
+                /** @description Process ID */
+                id: string;
+            };
+        };
+        responses: {
+            /** @description Process logs */
+            200: {
+                content: {
+                    "application/json": components["schemas"]["ProcessLogsResponse"];
+                };
+            };
+            /** @description Unknown process */
+            404: {
+                content: {
+                    "application/json": components["schemas"]["ProblemDetails"];
+                };
+            };
+            /** @description Process API unsupported on this platform */
+            501: {
+                content: {
+                    "application/json": components["schemas"]["ProblemDetails"];
+                };
+            };
+        };
+    };
+    /**
+     * Send SIGTERM to a process.
+     * @description Sends SIGTERM to the process and optionally waits up to `waitMs`
+     * milliseconds for the process to exit before returning.
+     */
+    post_v1_process_stop: {
+        parameters: {
+            query?: {
+                /** @description Wait up to N ms for process to exit */
+                waitMs?: number | null;
+            };
+            path: {
+                /** @description Process ID */
+                id: string;
+            };
+        };
+        responses: {
+            /** @description Stop signal sent */
+            200: {
+                content: {
+                    "application/json": components["schemas"]["ProcessInfo"];
+                };
+            };
+            /** @description Unknown process */
+            404: {
+                content: {
+                    "application/json": components["schemas"]["ProblemDetails"];
+                };
+            };
+            /** @description Process API unsupported on this platform */
+            501: {
+                content: {
+                    "application/json": components["schemas"]["ProblemDetails"];
+                };
+            };
+        };
+    };
+    /**
+     * Resize a process terminal.
+     * @description Sets the PTY window size (columns and rows) for a tty-mode process and
+     * sends SIGWINCH so the child process can adapt.
+     */
+    post_v1_process_terminal_resize: {
+        parameters: {
+            path: {
+                /** @description Process ID */
+                id: string;
+            };
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["ProcessTerminalResizeRequest"];
+            };
+        };
+        responses: {
+            /** @description Resize accepted */
+            200: {
+                content: {
+                    "application/json": components["schemas"]["ProcessTerminalResizeResponse"];
+                };
+            };
+            /** @description Invalid request */
+            400: {
+                content: {
+                    "application/json": components["schemas"]["ProblemDetails"];
+                };
+            };
+            /** @description Unknown process */
+            404: {
+                content: {
+                    "application/json": components["schemas"]["ProblemDetails"];
+                };
+            };
+            /** @description Not a terminal process */
+            409: {
+                content: {
+                    "application/json": components["schemas"]["ProblemDetails"];
+                };
+            };
+            /** @description Process API unsupported on this platform */
+            501: {
+                content: {
+                    "application/json": components["schemas"]["ProblemDetails"];
+                };
+            };
+        };
+    };
+    /**
+     * Open an interactive WebSocket terminal session.
+     * @description Upgrades the connection to a WebSocket for bidirectional PTY I/O. Accepts
+     * `access_token` query param for browser-based auth (WebSocket API cannot
+     * send custom headers). Streams raw PTY output as binary frames and accepts
+     * JSON control frames for input, resize, and close.
+     */
+    get_v1_process_terminal_ws: {
+        parameters: {
+            query?: {
+                /** @description Bearer token alternative for WS auth */
+                access_token?: string | null;
+            };
+            path: {
+                /** @description Process ID */
+                id: string;
+            };
+        };
+        responses: {
+            /** @description WebSocket upgraded */
+            101: {
+                content: never;
+            };
+            /** @description Invalid websocket frame or upgrade request */
+            400: {
+                content: {
+                    "application/json": components["schemas"]["ProblemDetails"];
+                };
+            };
+            /** @description Unknown process */
+            404: {
+                content: {
+                    "application/json": components["schemas"]["ProblemDetails"];
+                };
+            };
+            /** @description Not a terminal process */
+            409: {
+                content: {
+                    "application/json": components["schemas"]["ProblemDetails"];
+                };
+            };
+            /** @description Process API unsupported on this platform */
+            501: {
+                content: {
+                    "application/json": components["schemas"]["ProblemDetails"];
+                };
+            };
+        };
+    };
 }
 
 type ProblemDetails = components["schemas"]["ProblemDetails"];
 type HealthResponse = JsonResponse<operations["get_v1_health"], 200>;
 type AgentListResponse = JsonResponse<operations["get_v1_agents"], 200>;
 type AgentInfo = components["schemas"]["AgentInfo"];
+type AgentQuery = QueryParams<operations["get_v1_agents"]>;
 type AgentInstallRequest = JsonRequestBody<operations["post_v1_agent_install"]>;
 type AgentInstallResponse = JsonResponse<operations["post_v1_agent_install"], 200>;
 type AcpEnvelope = components["schemas"]["AcpEnvelope"];
@@ -720,6 +1313,54 @@ type McpConfigQuery = QueryParams<operations["get_v1_config_mcp"]>;
 type McpServerConfig = components["schemas"]["McpServerConfig"];
 type SkillsConfigQuery = QueryParams<operations["get_v1_config_skills"]>;
 type SkillsConfig = components["schemas"]["SkillsConfig"];
+type ProcessConfig = JsonResponse<operations["get_v1_processes_config"], 200>;
+type ProcessCreateRequest = JsonRequestBody<operations["post_v1_processes"]>;
+type ProcessInfo = components["schemas"]["ProcessInfo"];
+type ProcessInputRequest = JsonRequestBody<operations["post_v1_process_input"]>;
+type ProcessInputResponse = JsonResponse<operations["post_v1_process_input"], 200>;
+type ProcessListResponse = JsonResponse<operations["get_v1_processes"], 200>;
+type ProcessLogEntry = components["schemas"]["ProcessLogEntry"];
+type ProcessLogsQuery = QueryParams<operations["get_v1_process_logs"]>;
+type ProcessLogsResponse = JsonResponse<operations["get_v1_process_logs"], 200>;
+type ProcessLogsStream = components["schemas"]["ProcessLogsStream"];
+type ProcessRunRequest = JsonRequestBody<operations["post_v1_processes_run"]>;
+type ProcessRunResponse = JsonResponse<operations["post_v1_processes_run"], 200>;
+type ProcessSignalQuery = QueryParams<operations["post_v1_process_stop"]>;
+type ProcessState = components["schemas"]["ProcessState"];
+type ProcessTerminalResizeRequest = JsonRequestBody<operations["post_v1_process_terminal_resize"]>;
+type ProcessTerminalResizeResponse = JsonResponse<operations["post_v1_process_terminal_resize"], 200>;
+type ProcessTerminalClientFrame = {
+    type: "input";
+    data: string;
+    encoding?: string;
+} | {
+    type: "resize";
+    cols: number;
+    rows: number;
+} | {
+    type: "close";
+};
+interface ProcessTerminalReadyFrame {
+    type: "ready";
+    processId: string;
+}
+interface ProcessTerminalExitFrame {
+    type: "exit";
+    exitCode?: number | null;
+}
+interface ProcessTerminalErrorFrame {
+    type: "error";
+    message: string;
+}
+type ProcessTerminalServerFrame = ProcessTerminalReadyFrame | ProcessTerminalExitFrame | ProcessTerminalErrorFrame;
+type TerminalReadyStatus = ProcessTerminalReadyFrame;
+type TerminalExitStatus = ProcessTerminalExitFrame;
+type TerminalErrorStatus = ProcessTerminalErrorFrame;
+type TerminalStatusMessage = ProcessTerminalServerFrame;
+interface TerminalResizePayload {
+    cols: number;
+    rows: number;
+}
 interface SessionRecord {
     id: string;
     agent: string;
@@ -728,6 +1369,8 @@ interface SessionRecord {
     createdAt: number;
     destroyedAt?: number;
     sessionInit?: Omit<NewSessionRequest, "_meta">;
+    configOptions?: SessionConfigOption[];
+    modes?: SessionModeState | null;
 }
 type SessionEventSender = "client" | "agent";
 interface SessionEvent {
@@ -798,12 +1441,17 @@ type QueryParams<T> = T extends {
     };
 } ? Q : never;
 
+interface SandboxAgentHealthWaitOptions {
+    timeoutMs?: number;
+}
 interface SandboxAgentConnectCommonOptions {
     headers?: HeadersInit;
     persist?: SessionPersistDriver;
     replayMaxEvents?: number;
     replayMaxChars?: number;
+    signal?: AbortSignal;
     token?: string;
+    waitForHealth?: boolean | SandboxAgentHealthWaitOptions;
 }
 type SandboxAgentConnectOptions = (SandboxAgentConnectCommonOptions & {
     baseUrl: string;
@@ -824,22 +1472,66 @@ interface SessionCreateRequest {
     id?: string;
     agent: string;
     sessionInit?: Omit<NewSessionRequest, "_meta">;
+    model?: string;
+    mode?: string;
+    thoughtLevel?: string;
 }
 interface SessionResumeOrCreateRequest {
     id: string;
     agent: string;
     sessionInit?: Omit<NewSessionRequest, "_meta">;
+    model?: string;
+    mode?: string;
+    thoughtLevel?: string;
 }
 interface SessionSendOptions {
     notification?: boolean;
 }
 type SessionEventListener = (event: SessionEvent) => void;
+type ProcessLogListener = (entry: ProcessLogEntry) => void;
+type ProcessLogFollowQuery = Omit<ProcessLogsQuery, "follow">;
+interface AgentQueryOptions {
+    config?: boolean;
+    noCache?: boolean;
+}
+interface ProcessLogSubscription {
+    close(): void;
+    closed: Promise<void>;
+}
+interface ProcessTerminalWebSocketUrlOptions {
+    accessToken?: string;
+}
+interface ProcessTerminalConnectOptions extends ProcessTerminalWebSocketUrlOptions {
+    protocols?: string | string[];
+    WebSocket?: typeof WebSocket;
+}
+type ProcessTerminalSessionOptions = ProcessTerminalConnectOptions;
 declare class SandboxAgentError extends Error {
     readonly status: number;
     readonly problem?: ProblemDetails;
     readonly response: Response;
     constructor(status: number, problem: ProblemDetails | undefined, response: Response);
 }
+declare class UnsupportedSessionCategoryError extends Error {
+    readonly sessionId: string;
+    readonly category: string;
+    readonly availableCategories: string[];
+    constructor(sessionId: string, category: string, availableCategories: string[]);
+}
+declare class UnsupportedSessionValueError extends Error {
+    readonly sessionId: string;
+    readonly category: string;
+    readonly configId: string;
+    readonly requestedValue: string;
+    readonly allowedValues: string[];
+    constructor(sessionId: string, category: string, configId: string, requestedValue: string, allowedValues: string[]);
+}
+declare class UnsupportedSessionConfigOptionError extends Error {
+    readonly sessionId: string;
+    readonly configId: string;
+    readonly availableConfigIds: string[];
+    constructor(sessionId: string, configId: string, availableConfigIds: string[]);
+}
 declare class Session {
     private record;
     private readonly sandbox;
@@ -853,6 +1545,12 @@ declare class Session {
     refresh(): Promise<Session>;
     send(method: string, params?: Record<string, unknown>, options?: SessionSendOptions): Promise<unknown>;
     prompt(prompt: PromptRequest["prompt"]): Promise<PromptResponse>;
+    setMode(modeId: string): Promise<SetSessionModeResponse | void>;
+    setConfigOption(configId: string, value: string): Promise<SetSessionConfigOptionResponse>;
+    setModel(model: string): Promise<SetSessionConfigOptionResponse>;
+    setThoughtLevel(thoughtLevel: string): Promise<SetSessionConfigOptionResponse>;
+    getConfigOptions(): Promise<SessionConfigOption[]>;
+    getModes(): Promise<SessionModeState | null>;
     onEvent(listener: SessionEventListener): () => void;
     toRecord(): SessionRecord;
     apply(record: SessionRecord): void;
@@ -890,15 +1588,43 @@ declare class LiveAcpConnection {
     private resolveSessionId;
     private localFromEnvelopeParams;
 }
+declare class ProcessTerminalSession {
+    readonly socket: WebSocket;
+    readonly closed: Promise<void>;
+    private readonly readyListeners;
+    private readonly dataListeners;
+    private readonly exitListeners;
+    private readonly errorListeners;
+    private readonly closeListeners;
+    private closeSignalSent;
+    private closedResolve;
+    constructor(socket: WebSocket);
+    onReady(listener: (status: TerminalReadyStatus) => void): () => void;
+    onData(listener: (data: Uint8Array) => void): () => void;
+    onExit(listener: (status: TerminalExitStatus) => void): () => void;
+    onError(listener: (error: TerminalErrorStatus | Error) => void): () => void;
+    onClose(listener: () => void): () => void;
+    sendInput(data: string | ArrayBuffer | ArrayBufferView): void;
+    resize(payload: TerminalResizePayload): void;
+    close(): void;
+    private handleMessage;
+    private sendFrame;
+    private emitError;
+}
 declare class SandboxAgent {
     private readonly baseUrl;
     private readonly token?;
     private readonly fetcher;
     private readonly defaultHeaders?;
+    private readonly healthWait;
+    private readonly healthWaitAbortController;
     private readonly persist;
     private readonly replayMaxEvents;
     private readonly replayMaxChars;
     private spawnHandle?;
+    private healthPromise?;
+    private healthError?;
+    private disposed;
     private readonly liveConnections;
     private readonly pendingLiveConnections;
     private readonly sessionHandles;
@@ -916,18 +1642,36 @@ declare class SandboxAgent {
     resumeSession(id: string): Promise<Session>;
     resumeOrCreateSession(request: SessionResumeOrCreateRequest): Promise<Session>;
     destroySession(id: string): Promise<Session>;
+    setSessionMode(sessionId: string, modeId: string): Promise<{
+        session: Session;
+        response: SetSessionModeResponse | void;
+    }>;
+    setSessionConfigOption(sessionId: string, configId: string, value: string): Promise<{
+        session: Session;
+        response: SetSessionConfigOptionResponse;
+    }>;
+    setSessionModel(sessionId: string, model: string): Promise<{
+        session: Session;
+        response: SetSessionConfigOptionResponse;
+    }>;
+    setSessionThoughtLevel(sessionId: string, thoughtLevel: string): Promise<{
+        session: Session;
+        response: SetSessionConfigOptionResponse;
+    }>;
+    getSessionConfigOptions(sessionId: string): Promise<SessionConfigOption[]>;
+    getSessionModes(sessionId: string): Promise<SessionModeState | null>;
+    private setSessionCategoryValue;
+    private hydrateSessionConfigOptions;
     sendSessionMethod(sessionId: string, method: string, params: Record<string, unknown>, options?: SessionSendOptions): Promise<{
         session: Session;
         response: unknown;
     }>;
+    private sendSessionMethodInternal;
+    private persistSessionStateFromMethod;
     onSessionEvent(sessionId: string, listener: SessionEventListener): () => void;
     getHealth(): Promise<HealthResponse>;
-    listAgents(options?: {
-        config?: boolean;
-    }): Promise<AgentListResponse>;
-    getAgent(agent: string, options?: {
-        config?: boolean;
-    }): Promise<AgentInfo>;
+    listAgents(options?: AgentQueryOptions): Promise<AgentListResponse>;
+    getAgent(agent: string, options?: AgentQueryOptions): Promise<AgentInfo>;
     installAgent(agent: string, request?: AgentInstallRequest): Promise<AgentInstallResponse>;
     listAcpServers(): Promise<AcpServerListResponse>;
     listFsEntries(query?: FsEntriesQuery): Promise<FsEntry[]>;
@@ -944,8 +1688,25 @@ declare class SandboxAgent {
     getSkillsConfig(query: SkillsConfigQuery): Promise<SkillsConfig>;
     setSkillsConfig(query: SkillsConfigQuery, config: SkillsConfig): Promise<void>;
     deleteSkillsConfig(query: SkillsConfigQuery): Promise<void>;
+    getProcessConfig(): Promise<ProcessConfig>;
+    setProcessConfig(config: ProcessConfig): Promise<ProcessConfig>;
+    createProcess(request: ProcessCreateRequest): Promise<ProcessInfo>;
+    runProcess(request: ProcessRunRequest): Promise<ProcessRunResponse>;
+    listProcesses(): Promise<ProcessListResponse>;
+    getProcess(id: string): Promise<ProcessInfo>;
+    stopProcess(id: string, query?: ProcessSignalQuery): Promise<ProcessInfo>;
+    killProcess(id: string, query?: ProcessSignalQuery): Promise<ProcessInfo>;
+    deleteProcess(id: string): Promise<void>;
+    getProcessLogs(id: string, query?: ProcessLogFollowQuery): Promise<ProcessLogsResponse>;
+    followProcessLogs(id: string, listener: ProcessLogListener, query?: ProcessLogFollowQuery): Promise<ProcessLogSubscription>;
+    sendProcessInput(id: string, request: ProcessInputRequest): Promise<ProcessInputResponse>;
+    resizeProcessTerminal(id: string, request: ProcessTerminalResizeRequest): Promise<ProcessTerminalResizeResponse>;
+    buildProcessTerminalWebSocketUrl(id: string, options?: ProcessTerminalWebSocketUrlOptions): string;
+    connectProcessTerminalWebSocket(id: string, options?: ProcessTerminalConnectOptions): WebSocket;
+    connectProcessTerminal(id: string, options?: ProcessTerminalSessionOptions): ProcessTerminalSession;
     private getLiveConnection;
     private persistObservedEnvelope;
+    private persistSessionStateFromEvent;
     private allocateSessionEventIndex;
     private ensureSessionEventIndexSeeded;
     private findMaxPersistedSessionEventIndex;
@@ -954,8 +1715,12 @@ declare class SandboxAgent {
     private requireSessionRecord;
     private requestJson;
     private requestRaw;
+    private startHealthWait;
+    private awaitHealthy;
+    private runHealthWait;
     private buildHeaders;
     private buildUrl;
+    private requestHealth;
 }
 
 interface InspectorUrlOptions {
@@ -979,4 +1744,4 @@ interface InspectorUrlOptions {
  */
 declare function buildInspectorUrl(options: InspectorUrlOptions): string;
 
-export { type AcpEnvelope, type AcpServerInfo, type AcpServerListResponse, type AgentInfo, type AgentInstallRequest, type AgentInstallResponse, type AgentListResponse, type FsActionResponse, type FsDeleteQuery, type FsEntriesQuery, type FsEntry, type FsMoveRequest, type FsMoveResponse, type FsPathQuery, type FsStat, type FsUploadBatchQuery, type FsUploadBatchResponse, type FsWriteResponse, type HealthResponse, InMemorySessionPersistDriver, type InMemorySessionPersistDriverOptions, type InspectorUrlOptions, type ListEventsRequest, type ListPage, type ListPageRequest, LiveAcpConnection, type McpConfigQuery, type McpServerConfig, type ProblemDetails, SandboxAgent, type SandboxAgentConnectOptions, SandboxAgentError, type SandboxAgentSpawnLogMode, type SandboxAgentSpawnOptions, type SandboxAgentStartOptions, Session, type SessionCreateRequest, type SessionEvent, type SessionEventListener, type SessionPersistDriver, type SessionRecord, type SessionResumeOrCreateRequest, type SessionSendOptions, type SkillsConfig, type SkillsConfigQuery, buildInspectorUrl };
+export { type AcpEnvelope, type AcpServerInfo, type AcpServerListResponse, type AgentInfo, type AgentInstallRequest, type AgentInstallResponse, type AgentListResponse, type AgentQuery, type AgentQueryOptions, type FsActionResponse, type FsDeleteQuery, type FsEntriesQuery, type FsEntry, type FsMoveRequest, type FsMoveResponse, type FsPathQuery, type FsStat, type FsUploadBatchQuery, type FsUploadBatchResponse, type FsWriteResponse, type HealthResponse, InMemorySessionPersistDriver, type InMemorySessionPersistDriverOptions, type InspectorUrlOptions, type ListEventsRequest, type ListPage, type ListPageRequest, LiveAcpConnection, type McpConfigQuery, type McpServerConfig, type ProblemDetails, type ProcessConfig, type ProcessCreateRequest, type ProcessInfo, type ProcessInputRequest, type ProcessInputResponse, type ProcessListResponse, type ProcessLogEntry, type ProcessLogFollowQuery, type ProcessLogListener, type ProcessLogSubscription, type ProcessLogsQuery, type ProcessLogsResponse, type ProcessLogsStream, type ProcessRunRequest, type ProcessRunResponse, type ProcessSignalQuery, type ProcessState, type ProcessTerminalClientFrame, type ProcessTerminalConnectOptions, type ProcessTerminalErrorFrame, type ProcessTerminalExitFrame, type ProcessTerminalReadyFrame, type ProcessTerminalResizeRequest, type ProcessTerminalResizeResponse, type ProcessTerminalServerFrame, ProcessTerminalSession, type ProcessTerminalSessionOptions, type ProcessTerminalWebSocketUrlOptions, SandboxAgent, type SandboxAgentConnectOptions, SandboxAgentError, type SandboxAgentHealthWaitOptions, type SandboxAgentSpawnLogMode, type SandboxAgentSpawnOptions, type SandboxAgentStartOptions, Session, type SessionCreateRequest, type SessionEvent, type SessionEventListener, type SessionPersistDriver, type SessionRecord, type SessionResumeOrCreateRequest, type SessionSendOptions, type SkillsConfig, type SkillsConfigQuery, type TerminalErrorStatus, type TerminalExitStatus, type TerminalReadyStatus, type TerminalResizePayload, type TerminalStatusMessage, UnsupportedSessionCategoryError, UnsupportedSessionConfigOptionError, UnsupportedSessionValueError, buildInspectorUrl };