@tangle-network/sandbox 0.9.4-develop.20260710231333.22d131b → 0.9.4-develop.20260711192548.3c9ec78

package/dist/{sandbox-BEkgXuYK.d.ts → types-Cmpv-ox_.d.ts}

@@ -794,6 +794,110 @@ interface SandboxInfo {
   /** Source of the egress policy */
   egressPolicySource?: "sandbox" | "team" | "platform";
 }
+/** Basic health reported by the runtime inside a sandbox. */
+interface SandboxRuntimeHealth {
+  status: string;
+  docker: {
+    enabled: boolean;
+    status: string;
+    dockerHost?: string;
+    error?: string;
+  };
+  backends: {
+    total: number;
+    byType: Record<string, number>;
+    pending: number;
+  };
+  timestamp: string;
+}
+/** Public preview link associated with a listening runtime port. */
+interface SandboxPortPreviewLink {
+  previewId: string;
+  url: string;
+  status: string;
+}
+/** One process listening on a port inside a sandbox. */
+interface SandboxPortBinding {
+  pid: number;
+  processName: string;
+  commandPath: string;
+  port: number;
+  protocol: "tcp" | "udp";
+  localAddress: string;
+  family: "tcp4" | "tcp6" | "udp4" | "udp6";
+  allowlisted: boolean;
+  firstSeenAt: string;
+  lastSeenAt: string;
+  previewLink?: SandboxPortPreviewLink;
+}
+/** Options for creating an interactive terminal. */
+interface SandboxTerminalCreateOptions {
+  name?: string;
+  description?: string;
+  shell?: string;
+  cwd?: string;
+  cols?: number;
+  rows?: number;
+}
+/** Runtime request context used to attribute terminal events to an agent session. */
+interface SandboxTerminalRequestOptions {
+  sessionId?: string;
+}
+/** Interactive terminal metadata returned by the runtime. */
+interface SandboxTerminalInfo {
+  sessionId: string;
+  connectionId?: string;
+  name?: string;
+  description?: string;
+  shell?: string;
+  command?: string;
+  cwd?: string;
+  cols?: number;
+  rows?: number;
+  createdAt?: string;
+  lastActivityAt?: string;
+  isRunning?: boolean;
+  exitCode?: number;
+  exitSignal?: string;
+  /** WebSocket path for terminal input/output. */
+  streamUrl?: string;
+  history?: unknown[];
+}
+/** Interactive terminal operations. Input/output flows over `streamUrl`. */
+interface SandboxTerminalManager {
+  create(options?: SandboxTerminalCreateOptions, request?: SandboxTerminalRequestOptions): Promise<SandboxTerminalInfo>;
+  /** Send input through the runtime's HTTP fallback for an existing terminal. */
+  input(terminalId: string, data: string, request?: SandboxTerminalRequestOptions): Promise<void>;
+  list(): Promise<SandboxTerminalInfo[]>;
+  get(sessionId: string): Promise<SandboxTerminalInfo | null>;
+}
+/** Runtime-local agent profile. */
+interface SandboxRuntimeProfile {
+  name: string;
+  description?: string;
+  systemPrompt?: string;
+  tools?: string[];
+  mcpServers?: string[];
+  env?: Record<string, string>;
+  model?: {
+    provider?: string;
+    model?: string;
+  };
+}
+/** Runtime-local profile listing and selected default. */
+interface SandboxRuntimeProfileList {
+  profiles: SandboxRuntimeProfile[];
+  defaultProfile?: string;
+}
+/** Profile summary returned before a sandbox runtime exists. */
+interface SandboxProfileSummary {
+  id: string;
+  name: string;
+  description?: string;
+  model?: string;
+  tags?: string[];
+  extends?: string;
+}
 /**
  * Raw TEE attestation evidence returned by the sandbox runtime.
  *
@@ -1618,6 +1722,136 @@ interface SessionListOptions {
   /** Filter by backend identifier. */
   backend?: string;
 }
+/** Options for creating a runtime agent session. */
+interface CreateSessionOptions {
+  title?: string;
+  parentId?: string;
+  backend: BackendConfig;
+}
+/** Backend credentials forwarded to the platform if a sandbox must restart. */
+interface SessionBackendCredentials {
+  apiKey: string;
+  baseUrl?: string;
+}
+/** One content part accepted by the runtime session message endpoint. */
+type SessionMessageInputPart = PromptInputPart | {
+  type: "reasoning";
+  text: string;
+} | {
+  type: "tool";
+  tool: string;
+  state: {
+    status: "pending" | "running" | "completed" | "failed";
+    input?: unknown;
+    output?: unknown;
+  };
+} | {
+  type: "step-start";
+} | {
+  type: "step-finish";
+  reason?: string;
+  tokens?: {
+    total?: number;
+    input?: number;
+    output?: number;
+    reasoning?: number;
+    cache?: {
+      write?: number;
+      read?: number;
+    };
+  };
+  cost?: number;
+};
+/** Message body accepted by `SandboxSession.sendMessage`. */
+interface SendSessionMessageRequest {
+  messageId?: string;
+  parts: SessionMessageInputPart[];
+  system?: string;
+  agent?: string;
+  model?: {
+    providerId: string;
+    modelId: string;
+  };
+  reasoningEffort?: "low" | "medium" | "high";
+  turnId?: string;
+  interactions?: BackendConfig["interactions"];
+}
+/** Per-call controls for `SandboxSession.sendMessage`. */
+interface SendSessionMessageOptions {
+  credentials?: SessionBackendCredentials;
+  timeoutMs?: number;
+  signal?: AbortSignal;
+}
+/** Response returned after a session message finishes processing. */
+interface SentSessionMessage {
+  info: {
+    id: string;
+    role: "user" | "assistant" | "system";
+    timestamp?: string;
+  };
+  parts: unknown[];
+}
+/** Canonical portable profile attached to a task session. */
+type TaskSessionProfile = AgentProfile & {
+  name: string;
+};
+/** Options for creating an isolated background task session. */
+interface CreateTaskSessionOptions {
+  sessionId: string;
+  backend: BackendConfig;
+  title: string;
+  profile?: TaskSessionProfile;
+  parentSessionId?: string;
+  isolateFileWrites?: boolean;
+}
+/** Task-session metadata returned at creation time. */
+interface TaskSessionInfo {
+  id: string;
+  title?: string;
+  parentSessionId?: string;
+  worktreeInfo?: {
+    worktreePath: string;
+    branchName: string;
+    baseCommitSha: string;
+  };
+  profile?: TaskSessionProfile;
+}
+/** One changed file in an isolated task session. */
+interface TaskSessionFileChange {
+  file: string;
+  operation: "added" | "modified" | "deleted";
+  additions: number;
+  deletions: number;
+}
+/** Current diff and commit history for an isolated task session. */
+interface TaskSessionChanges {
+  sessionId: string;
+  files: TaskSessionFileChange[];
+  diff: string;
+  commits: Array<{
+    sha: string;
+    message: string;
+    date: string;
+  }>;
+  worktreeInfo: {
+    worktreePath: string;
+    branchName: string;
+    baseCommitSha: string;
+    headCommitSha?: string;
+  };
+}
+/** Options for merging task-session changes into the main workspace. */
+interface CommitTaskSessionOptions {
+  message?: string;
+  files?: string[];
+}
+/** Result of merging task-session changes into the main workspace. */
+interface TaskSessionCommitResult {
+  success: true;
+  commitSha?: string;
+  conflicts?: string[];
+  appliedFiles: number;
+}
 /**
  * Options for `SandboxSession.events()` streaming.
  */
@@ -1784,10 +2018,11 @@ type TurnDriveResult = {
   error: string;
 };
 /**
- * Scope of a `box.mintScopedToken()` request. Each value narrows the
- * token's authority compared to the full sandbox bearer.
+ * Scope of a `box.mintScopedToken()` request. Each value narrows the token's
+ * authority compared to the full sandbox bearer. `session-runtime` permits
+ * only typed message, workspace-file, and terminal operations for one session.
  */
-type ScopedTokenScope = "session" | "project" | "read-only";
+type ScopedTokenScope = "session" | "session-runtime" | "project" | "read-only";
 /**
  * Options for `box.mintScopedToken()`.
  */
@@ -1796,7 +2031,7 @@ interface MintScopedTokenOptions {
    * grants read access to the whole sandbox; `read-only` is a project
    * scope without prompt-dispatch capabilities. */
   scope: ScopedTokenScope;
-  /** Required when `scope === "session"`. */
+  /** Required when `scope` is `session` or `session-runtime`. */
   sessionId?: string;
   /** TTL in minutes. Default 5; clamped to [1, 15]. Browser-side
    * bearers must be short-lived; pair with `client.onTokenRefresh()`
@@ -1887,6 +2122,10 @@ interface BatchTask {
   /** Per-task timeout in milliseconds */
   timeoutMs?: number;
 }
+/** Backend configuration accepted by batch execution, including named profiles. */
+type BatchBackend = Omit<Partial<BackendConfig>, "type"> & {
+  type?: BackendType | `${BackendType}:${string}`;
+};
 /**
  * Options for batch execution.
  */
@@ -1901,11 +2140,38 @@ interface BatchOptions {
    * Use `backend.profile` with a string for a named profile or a provider-neutral
    * `AgentProfile` object for inline profile configuration.
    */
-  backend?: Partial<BackendConfig>;
+  backend?: BatchBackend;
+  /** Run every task against each backend for comparison. */
+  backends?: BatchBackend[];
+  /** User identifier attached to the batch for platform attribution. */
+  userId?: string;
+  /** Partner identifier attached to the batch for credit attribution. */
+  partnerId?: string;
+  /** Request identifier used in events and metrics. */
+  identifier?: string;
+  /** Workload class used by capacity and lifecycle policy. */
+  executionClass?: "project" | "simulation" | "background";
+  /** Capacity to provision before execution starts. */
+  desiredCapacity?: number;
+  /** Maximum time to wait for requested capacity. */
+  provisionTimeoutMs?: number;
   /** Keep sandboxes alive after completion (default: false) */
   persistent?: boolean;
+  /** Lifecycle policy for persistent batch sandboxes. */
+  lifecycle?: {
+    idleTimeoutMs?: number;
+    coldTimeoutMs?: number;
+  };
+  /** Use deterministic mock model responses. Intended for tests. */
+  mock?: boolean;
   /** Milliseconds to keep non-persistent batch sandboxes alive after completion. */
   graceMs?: number;
+  /** Repository cloned into persistent batch workspaces. */
+  git?: GitConfig;
+  /** Full replacement for the default agent system prompt. */
+  systemPrompt?: string;
+  /** Instructions appended to the default agent system prompt. */
+  instructions?: string;
   /**
    * AbortSignal to cancel the batch mid-stream. When aborted, the HTTP
    * request to `/batch/run` is torn down; the SSE generator stops
@@ -1917,6 +2183,14 @@ interface BatchOptions {
    */
   signal?: AbortSignal;
 }
+/** Complete request accepted by `runBatch` and `streamBatch`. */
+interface BatchRunRequest extends Omit<BatchOptions, "signal"> {
+  tasks: BatchTask[];
+}
+/** Per-call controls that are not serialized into a batch request. */
+interface BatchRunOptions {
+  signal?: AbortSignal;
+}
 /**
  * Result of a single task in a batch.
  */
@@ -1935,6 +2209,16 @@ interface BatchTaskResult {
   retries: number;
   /** Token usage if available */
   tokensUsed?: number;
+  /** Backend identifier for multi-backend batches. */
+  backend?: string;
+  /** Human-readable backend label emitted by the server. */
+  backendLabel?: string;
+  /** Model identifier emitted by the server. */
+  backendModel?: string;
+  /** Runtime session created for this task execution. */
+  sessionId?: string;
+  /** Sandbox used for this task execution. */
+  sandboxId?: string;
 }
 /**
  * Summary of batch execution.
@@ -1953,23 +2237,145 @@ interface BatchResult {
   /** Individual task results */
   results: BatchTaskResult[];
 }
-/**
- * SSE event from batch streaming.
- */
-interface BatchEvent {
-  /** Event type (batch.started, task.completed, etc.) */
-  type: string;
-  /** Event data */
-  data: Record<string, unknown>;
-  /**
-   * Optional `id:` from the SSE frame. Present at runtime whenever
-   * the server emits an `id:` line (used by EventSource-style
-   * reconnection). Declared optional because the batch protocol
-   * doesn't currently emit it — downstream consumers that want to
-   * implement resume should feature-detect.
-   */
-  id?: string;
+/** Token and tool usage emitted when one batch task completes. */
+interface BatchTaskUsage {
+  inputTokens: number;
+  outputTokens: number;
+  cacheReadTokens?: number;
+  cacheWriteTokens?: number;
+  toolCallCount?: number;
+}
+/** Per-backend aggregate emitted by `batch.completed`. */
+interface BatchBackendStats {
+  backend: string;
+  backendLabel?: string;
+  backendModel?: string;
+  success: number;
+  failure: number;
+  retries: number;
+  successRate: number;
+}
+/** Sidecars allocated to one backend configuration. */
+interface BatchSidecarGroup {
+  backend: string;
+  sidecarIds: string[];
+}
+interface BatchTaskEventIdentity {
+  taskId: string;
+  backend: string;
+  backendLabel?: string;
+  backendModel?: string;
+}
+/** Data payloads keyed by the SSE event name emitted by `/batch/run`. */
+interface BatchEventDataMap {
+  "batch.provisioning": {
+    desiredCapacity: number;
+    currentCapacity: number;
+    provisionTimeoutMs: number;
+  };
+  "batch.provisioned": {
+    capacity: number;
+  };
+  "batch.started": {
+    taskCount: number;
+    backendCount: number;
+    totalExecutions: number;
+    maxConcurrent: number;
+    scalingMode: string;
+    backends: string[];
+  };
+  "sidecars.allocated": {
+    count: number;
+    groups: BatchSidecarGroup[];
+  };
+  "batch.completed": {
+    taskCount: number;
+    backendCount: number;
+    totalExecutions: number;
+    totalSuccess: number;
+    totalFailure: number;
+    totalRetries: number;
+    successRate: number;
+    byBackend: BatchBackendStats[];
+  };
+  "batch.failed": {
+    error: string;
+    backends?: string[];
+  };
+  "batch.persistent": {
+    message: string;
+    sidecarCount: number;
+  };
+  "batch.grace_period": {
+    message: string;
+    sidecarCount: number;
+    graceMs: number;
+    sidecarIds: string[];
+  };
+  "task.started": BatchTaskEventIdentity & {
+    sidecarId: string;
+    projectRef?: string;
+    attempt: number;
+  };
+  "task.message.delta": BatchTaskEventIdentity & {
+    sidecarId: string;
+    projectRef?: string;
+    value: string;
+    part: Record<string, unknown>;
+  };
+  "task.reasoning": BatchTaskEventIdentity & {
+    sidecarId: string;
+    projectRef?: string;
+    value: string;
+    part: Record<string, unknown>;
+  };
+  "task.tool.updated": BatchTaskEventIdentity & {
+    sidecarId: string;
+    projectRef?: string;
+    part: Record<string, unknown>;
+  };
+  "task.completed": BatchTaskEventIdentity & {
+    durationMs: number;
+    attempt: number;
+    retries: number;
+    sidecarId: string;
+    projectRef?: string;
+    resultSummary?: string;
+    sessionId?: string;
+    usage: BatchTaskUsage;
+  };
+  "task.failed": BatchTaskEventIdentity & {
+    durationMs: number;
+    attempt: number;
+    retries: number;
+    error: string;
+    sidecarId?: string;
+  };
+  "task.retry": BatchTaskEventIdentity & {
+    attempt: number;
+    maxRetries: number;
+    error: string;
+    delayMs: number;
+  };
+  "backend.completed": {
+    backend: string;
+    backendLabel?: string;
+    backendModel?: string;
+    success: number;
+    failure: number;
+    retries: number;
+    successRate: number;
+  };
+  "sidecar.releasing": {
+    sidecarId: string;
+  };
 }
+/** Discriminated SSE event from a batch execution. */
+type BatchEvent = { [K in keyof BatchEventDataMap]: {
+  type: K;
+  data: BatchEventDataMap[K]; /** Optional SSE id used by reconnecting consumers. */
+  id?: string;
+} }[keyof BatchEventDataMap];
 /**
  * Stable worker identifier inside a sandbox fleet.
  *
@@ -2869,6 +3275,18 @@ interface BackendConfig {
     question?: boolean;
     plan?: boolean;
   };
+  /** Runtime session metadata used for attribution and workspace selection. */
+  metadata?: {
+    containerType?: string;
+    telemetry?: {
+      otlp: {
+        endpoint: string;
+        headers: string;
+      };
+      resourceAttributes: Record<string, string>;
+    };
+    [key: string]: unknown;
+  };
 }
 /**
  * Backend capabilities.
@@ -3842,6 +4260,71 @@ interface FileInfo {
   /** Last access time */
   accessTime: Date;
 }
+/** File metadata returned by the recursive workspace tree endpoint. */
+interface FileTreeFile {
+  path: string;
+  size: number;
+  /** File modification time as Unix milliseconds. */
+  mtime: number;
+}
+/** Options for recursively scanning a workspace tree. */
+interface FileTreeOptions {
+  sessionId?: string;
+  maxDepth?: number;
+}
+/** Recursive workspace tree with scan statistics. */
+interface FileTreeResult {
+  root: string;
+  directories: string[];
+  files: FileTreeFile[];
+  stats: {
+    totalDirectories: number;
+    totalFiles: number;
+    scanDurationMs: number;
+    truncated: boolean;
+  };
+}
+/** File content and metadata returned by a batch read. */
+interface FileReadResult {
+  path: string;
+  content: string;
+  encoding: "utf8" | "base64";
+  hash: string;
+  size: number;
+  /** File modification time as Unix milliseconds. */
+  mtime: number;
+}
+/** One file that could not be read during a partial-success batch. */
+interface FileReadError {
+  path: string;
+  error: string;
+  code?: string;
+}
+/** Options for reading files in a batch. */
+interface FileReadBatchOptions {
+  encoding?: "utf8" | "base64";
+  sessionId?: string;
+}
+/** Partial-success result from a batch file read. */
+interface FileReadBatchResult {
+  files: FileReadResult[];
+  errors: FileReadError[];
+  stats: {
+    requested: number;
+    succeeded: number;
+    failed: number;
+  };
+}
+/** Metadata returned after a successful file write. */
+interface FileWriteResult {
+  path: string;
+  hash: string;
+  size: number;
+  /** File modification time as Unix milliseconds. */
+  mtime: number;
+  /** Encoding echoed by runtimes that include it in write responses. */
+  encoding?: "utf8" | "base64";
+}
 /**
  * Options for uploading files.
  */
@@ -3910,6 +4393,8 @@ interface MkdirOptions {
 interface DeleteOptions {
   /** Recursively delete directories (like rm -rf) */
   recursive?: boolean;
+  /** Agent session whose workspace and change history receive the deletion. */
+  sessionId?: string;
 }
 /**
  * File system operations for sandboxes. Access via `sandbox.fs`.
@@ -3974,6 +4459,10 @@ interface WriteManyFile {
 interface WriteFileOptions {
   /** Unix mode bits applied after write, e.g. 0o755. */
   mode?: number;
+  /** Encoding of `content` on the wire. */
+  encoding?: "utf8" | "base64";
+  /** Agent session whose workspace and change history receive the write. */
+  sessionId?: string;
 }
 /** Options for {@link FileSystem.writeMany}. */
 interface WriteManyOptions {
@@ -3995,6 +4484,10 @@ interface FileSystem {
    * @throws NotFoundError if file doesn't exist
    */
   read(path: string): Promise<string>;
+  /** Read up to any number of files with content metadata and per-file errors. */
+  readBatch(paths: string[], options?: FileReadBatchOptions): Promise<FileReadBatchResult>;
+  /** Recursively scan the workspace and return file metadata. */
+  tree(path: string, options?: FileTreeOptions): Promise<FileTreeResult>;
   /**
    * Write string content to a file.
    * For binary files, use upload() instead.
@@ -4003,7 +4496,7 @@ interface FileSystem {
    * @param path - Path to file (relative to workspace)
    * @param content - Content to write
    */
-  write(path: string, content: string, options?: WriteFileOptions): Promise<void>;
+  write(path: string, content: string, options?: WriteFileOptions): Promise<FileWriteResult>;
   /**
    * Write many files in one paced, retry-aware batch.
    *
@@ -4256,1431 +4749,4 @@ interface CodeExecutionOptions {
   idempotencyKey?: string;
 }
 //#endregion
-//#region src/mcp.d.ts
-/**
- * MCP (Model Context Protocol) helpers for sandbox capabilities.
- *
- * The sandbox exposes capabilities (currently `computer_use`, more
- * later) as MCP tools over Streamable HTTP. Any MCP-capable client —
- * Claude Desktop, Cursor, claude-code, codex, opencode, raw
- * `@modelcontextprotocol/sdk` apps — can consume this surface by
- * pasting the JSON returned from `Sandbox#getMcpEndpoint()` (or
- * `buildSandboxMcpConfig` if you already have the URL + token) into
- * the client's MCP config.
- *
- * Security model:
- *   - Tokens are capability-scoped JWTs (claim `cap: ["computer_use"]`).
- *   - Full sandbox runtime tokens are rejected on `/mcp`; only
- *     capability-scoped tokens work there.
- *   - A scoped token cannot pivot to admin endpoints (`/exec`, `/files`,
- *     etc.) — those routes reject scoped tokens.
- *   - Tokens are short-lived. Rotate via `Sandbox#getMcpEndpoint()`,
- *     which mints a fresh token each call.
- */
-/** Default name of the MCP server entry — surfaces in the host UI. */
-declare const SANDBOX_MCP_SERVER_NAME = "tangle-sandbox";
-/**
- * MCP HTTP server entry — matches the Anthropic MCP HTTP transport
- * schema (`type: "http"`, `url`, optional `headers`). Compatible with
- * every MCP host that implements the spec.
- */
-interface SandboxMcpServerEntry {
-  type: "http";
-  url: string;
-  headers: Record<string, string>;
-}
-/**
- * `.mcp.json`-shaped config any MCP host accepts. Drop the contents of
- * `mcpServers` into your host's `mcpServers` block (Claude Desktop,
- * Cursor, claude-code's `--mcp-config`, etc.) — no host-specific
- * fields, no provider lock-in.
- */
-interface SandboxMcpConfig {
-  mcpServers: Record<string, SandboxMcpServerEntry>;
-}
-/**
- * Endpoint payload returned by `GET /v1/sandboxes/:id/mcp`. Includes
- * the canonical config plus token expiry so callers can plan
- * refreshes.
- */
-interface SandboxMcpEndpoint {
-  /** MCP host config — paste this into Cursor/Claude Desktop/etc. */
-  config: SandboxMcpConfig;
-  /** Server entry name used inside `config.mcpServers`. */
-  serverName: string;
-  /** Reachable URL for the MCP HTTP transport. */
-  url: string;
-  /** Bearer token sent by the MCP host on every request. */
-  authToken: string;
-  /** ISO-8601 expiry — the host should refresh before this. */
-  expiresAt: string;
-  /** Capabilities the token is scoped to. */
-  capabilities: ReadonlyArray<"computer_use">;
-}
-interface BuildSandboxMcpConfigOptions {
-  /** Public sandbox URL where `/mcp` is reachable. No trailing slash. */
-  sandboxUrl: string;
-  /** Capability-scoped JWT minted by the Sandbox API. */
-  authToken: string;
-  /** Override the entry name. Defaults to SANDBOX_MCP_SERVER_NAME. */
-  serverName?: string;
-}
-/**
- * Build the canonical `mcpServers` config for a sandbox MCP endpoint.
- * Pure function — no I/O, no crypto. Use this when you already have a
- * `{ url, authToken }` pair from the API and just want the JSON shape
- * to paste into a host. Most callers should use
- * `Sandbox#getMcpEndpoint()` instead, which fetches a freshly-minted
- * token from the API.
- */
-declare function buildSandboxMcpConfig(options: BuildSandboxMcpConfigOptions): {
-  serverName: string;
-  config: SandboxMcpConfig;
-};
-/**
- * Default name of the control-plane MCP server entry. Distinct from the per-
- * sandbox runtime server (`SANDBOX_MCP_SERVER_NAME`): the sandbox surface
- * operates INSIDE one sandbox (`run_code`/`exec`/`read`/`write`), while this one
- * operates ACROSS the account (sandboxes, workflows, integrations, usage).
- */
-declare const CONTROL_PLANE_MCP_SERVER_NAME = "tangle-control-plane";
-interface BuildControlPlaneMcpConfigOptions {
-  /** Public platform URL where `/mcp` is reachable. No trailing slash. */
-  platformUrl: string;
-  /**
-   * A Tangle account API key scoped to the control-plane operations you need
-   * (e.g. `read`, `workflows:write`). Sent on every request as a Bearer token.
-   */
-  apiKey: string;
-  /** Override the entry name. Defaults to CONTROL_PLANE_MCP_SERVER_NAME. */
-  serverName?: string;
-}
-/**
- * Build the canonical `mcpServers` config for the public control-plane MCP
- * endpoint — the JSON a user pastes into Claude Desktop / Cursor / claude-code
- * to drive their Tangle account from their own agent. Pure function; mirrors
- * `buildSandboxMcpConfig` but carries an account API key instead of a per-
- * sandbox capability token.
- */
-declare function buildControlPlaneMcpConfig(options: BuildControlPlaneMcpConfigOptions): {
-  serverName: string;
-  config: SandboxMcpConfig;
-};
-//#endregion
-//#region src/interactive.d.ts
-/**
- * Interactive harness sessions on the public SDK.
- *
- * `box.session(id).interactive()` returns a handle that spawns a coding
- * harness's native interactive TUI in the sandbox (start), drives it with
- * prompts (sendPrompt), and tears it down (stop). The live framebuffer is
- * streamed over the WebSocket at the returned `streamUrl` (the secured
- * `/terminals/:id/ws` pixel lane) — open it with your terminal/xterm client.
- *
- * This is the public SDK surface of the Session Protocol Gateway; it rides the
- * same secured runtime routes as the rest of the SDK.
- */
-/** CLI auth file materialized into the harness's auth home before launch. */
-interface InteractiveAuthFile {
-  path: string;
-  content: string;
-  mode?: number;
-}
-interface StartInteractiveOptions {
-  /** Harness with a native interactive TUI: "claude-code" | "codex" | "kimi-code". */
-  harness: string;
-  model?: string;
-  apiKey?: string;
-  authMode?: string;
-  baseUrl?: string;
-  /** Working directory; defaults to the sandbox workspace root. */
-  cwd?: string;
-  cols?: number;
-  rows?: number;
-  authFiles?: InteractiveAuthFile[];
-}
-interface InteractiveSessionInfo {
-  sessionId: string;
-  harness: string;
-  /** ISO timestamp of when the harness process was spawned. */
-  startedAt: string;
-  /**
-   * Sandbox-relative WebSocket path that streams the live framebuffer and
-   * accepts keystrokes (the mTLS- + capability-gated terminal socket).
-   */
-  streamUrl: string;
-}
-/** Decision passed to `respondToPermission`. */
-interface RespondToPermissionOptions {
-  /** The human's decision for the awaiting permission interaction. */
-  response: "allow" | "deny";
-}
-/** Result of `interrupt`. */
-interface InterruptResult {
-  /**
-   * True iff an execution was actively running and the abort signal reached
-   * it. `false` means there was nothing in flight to cancel — surfaced
-   * explicitly rather than as a silent success so callers can distinguish a
-   * real interruption from a no-op.
-   */
-  cancelled: boolean;
-}
-/**
- * Host hooks the SDK box implements to drive interactive sessions. Kept
- * separate from the prompt/session-event host so the interactive surface is an
- * explicit, independently-mockable contract.
- */
-interface InteractiveSessionHost {
-  _startInteractive(id: string, options: StartInteractiveOptions): Promise<InteractiveSessionInfo>;
-  _sendInteractivePrompt(id: string, prompt: string): Promise<void>;
-  _stopInteractive(id: string): Promise<void>;
-}
-/**
- * Handle for one session's interactive harness. Obtained via
- * `box.session(id).interactive()`; does not hit the network until a method is
- * called.
- */
-declare class InteractiveSessionHandle {
-  private readonly host;
-  private readonly sessionId;
-  constructor(host: InteractiveSessionHost, sessionId: string);
-  /**
-   * Spawn the harness's interactive TUI for this session. Returns the
-   * `streamUrl` to attach a terminal client to. Throws if the harness has no
-   * interactive entrypoint (e.g. opencode), the binary is not installed, or a
-   * session is already running for this id.
-   */
-  start(options: StartInteractiveOptions): Promise<InteractiveSessionInfo>;
-  /** Inject a prompt as keystrokes into the live harness (submitted on send). */
-  sendPrompt(prompt: string): Promise<void>;
-  /** Stop the interactive harness and reap its PTY. */
-  stop(): Promise<void>;
-}
-//#endregion
-//#region src/session.d.ts
-/**
- * The subset of `SandboxInstance` a `SandboxSession` drives. Declared here
- * (rather than importing the concrete class) so `session.ts` stays a leaf
- * of `sandbox.ts` — `sandbox.ts` constructs `SandboxSession`, so the reverse
- * import would form a cycle. `SandboxInstance` satisfies this structurally.
- */
-interface SandboxSessionHost extends InteractiveSessionHost {
-  prompt(message: string | PromptInputPart[], options?: PromptOptions): Promise<PromptResult>;
-  _sessionStatus(id: string): Promise<SessionInfo | null>;
-  _sessionEvents(id: string, opts?: SessionEventStreamOptions): AsyncGenerator<SandboxEvent>;
-  _sessionResult(id: string): Promise<PromptResult>;
-  _sessionCancel(id: string): Promise<void>;
-  messages(opts: ListMessagesOptions): Promise<SessionMessage[]>;
-  _sessionFork(id: string, opts?: SessionForkOptions): Promise<SessionInfo>;
-  _respondToPermission(id: string, permissionID: string, options: RespondToPermissionOptions): Promise<void>;
-  _interrupt(id: string): Promise<InterruptResult>;
-  _answerQuestion(id: string, answers: Record<string, string[]>): Promise<void>;
-}
-/**
- * A single agent session inside a sandbox. Created via
- * `box.session(id)` — does not hit the network until a method is called.
- */
-declare class SandboxSession {
-  private readonly box;
-  /** Stable session id assigned by the sandbox runtime. */
-  readonly id: string;
-  /**
-   * @internal SDK-internal constructor — apps should call `box.session(id)`.
-   */
-  constructor(box: SandboxSessionHost, /** Stable session id assigned by the sandbox runtime. */
-
-  id: string);
-  /**
-   * Fetch the current session state from the sandbox. Includes status,
-   * model, prompt count, token usage if known, and timing metadata.
-   *
-   * Throws on transport error; returns `null` if the session id is not
-   * known to the sandbox (e.g. it ended and was reaped, or the id is
-   * invalid).
-   */
-  status(): Promise<SessionInfo | null>;
-  /**
-   * Stream events from this session as they arrive. With no `since`,
-   * starts at the live tail; with `since`, replays from that event id
-   * forward — useful for reconnect-after-disconnect flows.
-   *
-   * The async iterator terminates when the session reaches a terminal
-   * state (`completed`, `failed`, `cancelled`) and the corresponding
-   * terminal event has been yielded, OR when the caller's signal aborts.
-   */
-  events(opts?: SessionEventStreamOptions): AsyncGenerator<SandboxEvent>;
-  /**
-   * Await the session's terminal result. Polls status + drains events
-   * until the session reaches a terminal state, then returns the
-   * aggregated `PromptResult`.
-   *
-   * Use this to wait for a session that was started by another caller
-   * (e.g. `dispatchPrompt`).
-   */
-  result(): Promise<PromptResult>;
-  /**
-   * List persisted messages for this session, including in-flight assistant
-   * content when the runtime has flushed partial output.
-   */
-  messages(opts?: Omit<ListMessagesOptions, "sessionId">): Promise<SessionMessage[]>;
-  /**
-   * Continue this session with an additional prompt. Equivalent to
-   * `box.prompt(message, { ...opts, sessionId: this.id })` but reads
-   * naturally on a Session reference.
-   */
-  prompt(message: string | PromptInputPart[], opts?: PromptOptions): Promise<PromptResult>;
-  /**
-   * Abort the session's in-flight execution; the session and its messages
-   * are preserved (this does not delete the session). Void-returning alias
-   * of `interrupt()` — use `interrupt()` when you need to know whether an
-   * execution was actually running. Best-effort: an in-flight LLM call may
-   * still complete one more token before the abort takes effect. Idempotent —
-   * aborting a session with nothing in flight is a no-op.
-   */
-  cancel(): Promise<void>;
-  /**
-   * Fork this session into a new queued session. The fork shares the
-   * parent workspace and copies conversation history up to `messageId`
-   * when supplied.
-   */
-  fork(opts?: SessionForkOptions): Promise<{
-    session: SandboxSession;
-    info: SessionInfo;
-  }>;
-  /**
-   * Drive this session's harness in INTERACTIVE mode: spawn its native TUI,
-   * stream the live framebuffer, and inject prompts as keystrokes. Distinct
-   * from the headless `prompt()`/`events()` surface above. Lazy — does not hit
-   * the network until a handle method is called.
-   */
-  interactive(): InteractiveSessionHandle;
-  /**
-   * Resolve a pending permission interaction the agent raised mid-turn,
-   * forwarding `allow`/`deny` to the blocked agent through the unified
-   * interaction channel. Throws if no matching permission is outstanding.
-   */
-  respondToPermission(permissionID: string, options: RespondToPermissionOptions): Promise<void>;
-  /**
-   * Interrupt the session's current execution without deleting it. Returns
-   * `{ cancelled: false }` when nothing was running — the no-op is reported
-   * explicitly rather than masked as success.
-   */
-  interrupt(): Promise<InterruptResult>;
-  /**
-   * Answer a question the agent asked via a question tool invocation. `answers`
-   * maps each question id to the selected option(s). Backend-agnostic: works
-   * with any backend that raises kind:"question" interactions — OpenCode
-   * natively, or CLI backends with `BackendConfig.interactions.question`
-   * enabled. Backends with no question support reject loudly.
-   */
-  answer(answers: Record<string, string[]>): Promise<void>;
-}
-//#endregion
-//#region src/trace-exporter.d.ts
-type JsonObject = {
-  [key: string]: JsonValue;
-};
-type TraceExportFormat = "tangle" | "otel-json";
-type TraceExportBundle = SandboxTraceBundle | SandboxFleetTraceBundle;
-interface TraceExportSink {
-  url: string;
-  headers?: Record<string, string>;
-  format?: TraceExportFormat;
-  serviceName?: string;
-  timeoutMs?: number;
-  fetch?: typeof fetch;
-}
-interface TraceExportResult {
-  status: number;
-  ok: boolean;
-  body: string;
-}
-declare function buildTraceExportPayload(bundle: TraceExportBundle, format?: TraceExportFormat, serviceName?: string): TraceExportBundle | JsonObject;
-declare function exportTraceBundle(bundle: TraceExportBundle, sink: TraceExportSink): Promise<TraceExportResult>;
-declare function toOtelJson(bundle: TraceExportBundle, serviceName?: string): JsonObject;
-declare function otelTraceIdForTangleTrace(traceId: string): string;
-//#endregion
-//#region src/sandbox.d.ts
-/**
- * Result of registering a sidecar session mapping. `reprovisionRequired` is
- * true when the server reports the mapped sidecar is stale (HTTP 410) and the
- * caller must reprovision the sandbox before retrying.
- */
-interface SessionMappingResult {
-  success: boolean;
-  sessionId: string;
-  sidecarSessionId?: string;
-  reprovisionRequired: boolean;
-  code?: string;
-}
-/**
- * HTTP client interface for making requests.
- */
-interface HttpClient {
-  fetch(path: string, options?: RequestInit, fetchOptions?: {
-    timeoutMs?: number;
-  }): Promise<Response>;
-  getApiKey?(): string | undefined;
-}
-/**
- * Git capability for repository operations.
- */
-interface GitCapability {
-  /** Get repository status */
-  status(): Promise<GitStatus>;
-  /** Get commit log */
-  log(limit?: number): Promise<GitCommit[]>;
-  /** Get diff (optionally against a ref) */
-  diff(ref?: string): Promise<GitDiff>;
-  /** Stage files */
-  add(paths: string[]): Promise<void>;
-  /** Create a commit */
-  commit(message: string, options?: {
-    amend?: boolean;
-  }): Promise<GitCommit>;
-  /** Push to remote */
-  push(options?: {
-    force?: boolean;
-  }): Promise<void>;
-  /** Pull from remote */
-  pull(options?: {
-    rebase?: boolean;
-  }): Promise<void>;
-  /** List branches */
-  branches(): Promise<GitBranch[]>;
-  /** Checkout a branch or ref */
-  checkout(ref: string, options?: {
-    create?: boolean;
-  }): Promise<void>;
-}
-/**
- * Tools capability for managing language runtimes via mise.
- */
-interface ToolsCapability {
-  /** Install a tool version */
-  install(tool: string, version: string): Promise<void>;
-  /** Activate a tool version for the session */
-  use(tool: string, version: string): Promise<void>;
-  /** List installed tools */
-  list(): Promise<InstalledTool[]>;
-  /** Run a command with a specific tool */
-  run(tool: string, args: string[]): Promise<ExecResult>;
-}
-/**
- * A sandbox instance with methods for interaction.
- */
-declare class SandboxInstance {
-  private readonly client;
-  private info;
-  private readonly defaultRuntimeBackend?;
-  constructor(client: HttpClient, info: SandboxInfo, defaultRuntimeBackend?: BackendConfig);
-  /** Unique sandbox identifier */
-  get id(): string;
-  /** Human-readable name */
-  get name(): string | undefined;
-  /** Current status */
-  get status(): SandboxStatus;
-  /** Connection information */
-  get connection(): SandboxConnection | undefined;
-  /** Custom metadata */
-  get metadata(): Record<string, unknown> | undefined;
-  /** When the sandbox was created */
-  get createdAt(): Date;
-  /** When the sandbox started running */
-  get startedAt(): Date | undefined;
-  /** Last activity timestamp */
-  get lastActivityAt(): Date | undefined;
-  /** When the sandbox will expire */
-  get expiresAt(): Date | undefined;
-  /** Error message if status is 'failed' */
-  get error(): string | undefined;
-  /** GPU lease attached during sandbox creation, when requested. */
-  get gpuLease(): GpuLease | undefined;
-  /** Web terminal URL for browser-based access */
-  get url(): string | undefined;
-  /**
-   * The 12-phase startup breakdown (storage_provision, host_select, edge_bind,
-   * edge_ready, egress_proxy, docker_pull/create/start, sidecar_boot,
-   * health_check, …) the platform emitted when this sandbox was provisioned.
-   *
-   * Present only on a freshly-created box; `null` for a box resolved by id or
-   * when the runtime did not report diagnostics. Use `.phases` for the
-   * operation-name → durationMs map.
-   *
-   * @example
-   * ```typescript
-   * const d = box.startupDiagnostics();
-   * if (d) console.log(`provision phases: ${JSON.stringify(d.phases)}`);
-   * ```
-   */
-  startupDiagnostics(): StartupDiagnostics | null;
-  /**
-   * Serialize to the public sandbox shape for logs and structured
-   * output. Secrets in `connection` (currently `authToken`) are
-   * redacted so that `JSON.stringify(box)` is safe to ship to log
-   * sinks. Use {@link toDebugJSON} when the bearer is required (e.g.
-   * one-off CLI commands that print credentials to the user).
-   */
-  toJSON(): SandboxInfo;
-  /**
-   * Serialize the sandbox **including secrets** when `includeSecrets`
-   * is true. The default behavior matches {@link toJSON} and redacts
-   * `connection.authToken`.
-   *
-   * Use only when the caller has an explicit need for the bearer
-   * (e.g. presenting it once to the human operator). Never wire the
-   * result of `toDebugJSON({ includeSecrets: true })` into a structured
-   * logger — the bearer will land in any log sink consuming that output.
-   */
-  toDebugJSON(options?: {
-    includeSecrets?: boolean;
-  }): SandboxInfo;
-  /**
-   * Create an advanced direct-runtime view of this sandbox.
-   *
-   * Runtime methods on the returned instance talk to the sandbox runtime
-   * directly using `connection.runtimeUrl` and `connection.authToken`.
-   * Lifecycle methods still go through the parent SDK client.
-   */
-  direct(): SandboxInstance;
-  /**
-   * Get an MCP endpoint for this sandbox. Returns a paste-able config
-   * for any MCP-capable host (Claude Desktop, Cursor, claude-code,
-   * codex, opencode, …) plus a freshly-minted, capability-scoped JWT.
-   *
-   * The token is short-lived and limited to the requested capabilities
-   * — it cannot be used against admin endpoints (`/exec`, `/files`,
-   * etc.) on the sandbox. Call `getMcpEndpoint()` again to rotate.
-   *
-   * Requires the sandbox to have been created with `capabilities`
-   * including the requested capability (default: `computer_use`).
-   *
-   * @example
-   * ```typescript
-   * const ep = await box.getMcpEndpoint();
-   * // Save ep.config to your IDE's mcp.json — that's it.
-   * fs.writeFileSync("mcp.json", JSON.stringify(ep.config, null, 2));
-   * ```
-   */
-  getMcpEndpoint(options?: {
-    capabilities?: ReadonlyArray<"computer_use">; /** Override server entry name (default: "tangle-sandbox"). */
-    serverName?: string; /** Token TTL in minutes (server clamps to its policy). */
-    ttlMinutes?: number;
-  }): Promise<SandboxMcpEndpoint>;
-  /**
-   * Refresh sandbox information from the server.
-   */
-  refresh(): Promise<void>;
-  /**
-   * Fetch fresh TEE attestation evidence for this sandbox.
-   *
-   * When `attestationNonce` is supplied, the runtime must return evidence bound
-   * to that challenge or fail closed if the selected TEE backend cannot support
-   * nonce-bound report data.
-   */
-  getTeeAttestation(options?: TeeAttestationOptions): Promise<TeeAttestationResponse>;
-  /**
-   * Fetch the TEE-bound public key used for sealed-secret encryption.
-   *
-   * The returned key includes an attestation report. Verify that report before
-   * encrypting secrets to the key.
-   */
-  getTeePublicKey(): Promise<TeePublicKeyResponse>;
-  /**
-   * Bootstrap a real-time collaboration session for a file.
-   * Returns the WebSocket URL and auth token needed to connect a
-   * Hocuspocus/Yjs provider for live multi-user editing.
-   *
-   * @example
-   * ```typescript
-   * const collab = await box.collaborate("src/index.ts")
-   * // Use collab.transport.websocketUrl + collab.transport.token
-   * // with @hocuspocus/provider to connect
-   * ```
-   */
-  collaborate(path: string, options?: {
-    access?: "read" | "write";
-  }): Promise<{
-    documentId: string;
-    transport: {
-      websocketUrl: string;
-      token: string;
-      expiresAt: number;
-    };
-    permissions: {
-      access: "read" | "write";
-      canSnapshot: boolean;
-    };
-  }>;
-  /**
-   * Refresh a collaboration token for an existing document session.
-   */
-  /**
-   * Refresh a collaboration token. Access level is preserved from the original
-   * token — cannot be escalated (read stays read, write stays write).
-   */
-  refreshCollaborationToken(documentId: string, currentToken: string): Promise<{
-    token: string;
-    expiresAt: number;
-    access: "read" | "write";
-  }>;
-  /**
-   * Get SSH credentials for connecting to the sandbox.
-   * Throws if SSH is not enabled or sandbox is not running.
-   */
-  ssh(): Promise<SSHCredentials>;
-  sshCommand(): Promise<SSHCommandDescriptor>;
-  /**
-   * Execute a command in the sandbox.
-   */
-  exec(command: string, options?: ExecOptions): Promise<ExecResult>;
-  /**
-   * Run code in a persistent language kernel.
-   *
-   * Each `(sessionId, language)` pair gets its own long-lived kernel that
-   * keeps variable state across calls — like Jupyter cells. Without a
-   * `sessionId`, calls share a process-wide kernel per language.
-   *
-   * Returns typed results: stdout/stderr text plus a `results` array of
-   * structured outputs (matplotlib images as base64 PNG, pandas DataFrames,
-   * explicit `display(value)` calls as JSON/HTML, errors with traceback).
-   *
-   * @example Persistent Python session
-   * ```ts
-   * await box.runCode("python", "import pandas as pd; df = pd.DataFrame({'x': range(5)})", { sessionId: "s1" });
-   * const r = await box.runCode("python", "df.describe()", { sessionId: "s1" });
-   * // r.results[0] is a `dataframe` part with columns + rows from the describe()
-   * ```
-   *
-   * @example Matplotlib chart
-   * ```ts
-   * const r = await box.runCode("python",
-   *   "import matplotlib.pyplot as plt; plt.plot([1,2,3,4]); plt.show()",
-   *   { sessionId: "s1" });
-   * const png = r.results.find(p => p.type === "image");
-   * // png.data is a base64 PNG ready to render or hand back to an LLM
-   * ```
-   */
-  runCode(language: CodeLanguage, source: string, options?: CodeExecutionOptions): Promise<CodeExecutionResult>;
-  /**
-   * Read a file from the sandbox.
-   *
-   * @param path - Path to the file. Relative paths resolve from the workspace root.
-   *   Absolute paths (e.g., `/tmp/output.json`) access the container filesystem directly.
-   * @returns File content as string
-   *
-   * @example
-   * ```typescript
-   * const content = await box.read("src/index.ts");
-   * const report = await box.read("/output/report.json");
-   * ```
-   */
-  read(path: string, options?: {
-    sessionId?: string;
-  }): Promise<string>;
-  /**
-   * Write content to a file in the sandbox.
-   *
-   * @param path - Path to the file. Relative paths resolve from the workspace root.
-   *   Absolute paths (e.g., `/tmp/cases.json`) write to the container filesystem directly.
-   * @param content - Content to write
-   *
-   * @example
-   * ```typescript
-   * await box.write("src/fix.ts", "export const fix = () => {}");
-   * await box.write("/tmp/config.json", JSON.stringify(config));
-   * ```
-   */
-  write(path: string, content: string, options?: WriteFileOptions): Promise<void>;
-  /**
-   * Write many files in one paced, retry-aware batch — see
-   * {@link FileSystem.writeMany}. Each file goes through {@link write}; a small
-   * pace between writes keeps a large corpus under the file-write rate limit,
-   * and transient failures (quota / server / network / timeout) retry with
-   * exponential backoff (honoring a server `retryAfterMs`). Fail-loud on the
-   * first file that cannot be written after its retries.
-   */
-  writeMany(files: WriteManyFile[], options?: WriteManyOptions): Promise<void>;
-  /**
-   * Send a prompt to the agent running in the sandbox.
-   * Returns the complete response after the agent finishes.
-   */
-  prompt(message: string | PromptInputPart[], options?: PromptOptions): Promise<PromptResult>;
-  private logStreamCheckpoint;
-  /**
-   * Stream events from an agent prompt.
-   * Use this for real-time updates during agent execution.
-   *
-   * Guarantees a terminal event on every non-cancelled path: a clean run
-   * ends with the runtime's `result`/`done`; a failure (pre-stream HTTP
-   * error, mid-stream network drop, timeout, or reconnect exhaustion) is
-   * surfaced as an in-band `error` event followed by a synthetic `done`,
-   * never a thrown generator. Caller-initiated cancellation (aborting
-   * `options.signal`) ends the stream silently with no synthetic terminal.
-   *
-   * Automatically reconnects via the runtime event replay endpoint if the
-   * SSE stream drops before a terminal event (`result` or `done`) is
-   * received. Reconnection is transparent — replayed events that were
-   * already yielded (based on event ID tracking) are deduplicated.
-   */
-  streamPrompt(message: string | PromptInputPart[], options?: PromptOptions): AsyncGenerator<SandboxEvent>;
-  /**
-   * Inner prompt stream: opens the SSE connection and reconnects on silent
-   * drops. May throw (pre-stream HTTP error, timeout, reconnect exhausted);
-   * the public `streamPrompt` wrapper converts those throws into a terminal
-   * `error` + `done` so callers never see a thrown generator.
-   */
-  private streamPromptInner;
-  /**
-   * Stream sandbox lifecycle and activity events.
-   */
-  events(options?: EventStreamOptions): AsyncGenerator<SandboxEvent>;
-  trace(options?: SandboxTraceOptions): Promise<SandboxTraceBundle>;
-  intelligence(): Promise<NonNullable<SandboxTraceBundle["intelligence"]>>;
-  createIntelligenceReport(options?: {
-    mode?: "deterministic" | "agentic";
-    acknowledgeCost?: boolean;
-    budget?: IntelligenceReportBudget;
-    metadata?: Record<string, unknown>; /** Bound the analysis to a time window. */
-    window?: IntelligenceReportWindow; /** Compare this sandbox against a same-type baseline sandbox. */
-    compareTo?: IntelligenceReportCompareTo;
-  }): Promise<IntelligenceReport>;
-  createAgenticIntelligenceReport(options: {
-    maxUsd: number;
-    metadata?: Record<string, unknown>;
-  }): Promise<IntelligenceReport>;
-  exportTrace(sink: TraceExportSink): Promise<TraceExportResult>;
-  /**
-   * Stream real-time provisioning progress events.
-   *
-   * Connects to the SSE events stream and yields typed `ProvisionEvent` objects
-   * for each provisioning step. The generator completes when provisioning
-   * finishes (success or failure) and returns the terminal result.
-   *
-   * @returns AsyncGenerator of ProvisionEvent, with a ProvisionResult return value
-   *
-   * @example
-   * ```typescript
-   * const box = await client.create({ image: "ethereum" });
-   *
-   * const stream = box.watchProvisioning();
-   * for await (const event of stream) {
-   *   console.log(`[${event.step}] ${event.status} — ${event.message}`);
-   * }
-   * // stream.return value contains the terminal result
-   * ```
-   */
-  watchProvisioning(options?: {
-    signal?: AbortSignal;
-  }): AsyncGenerator<ProvisionEvent, ProvisionResult | undefined>;
-  /**
-   * Run an agentic task until completion.
-   *
-   * Unlike prompt(), task() is designed for autonomous agent work:
-   * - The agent works until it completes the task or hits an error
-   * - Session state is maintained for context continuity
-   * - Token usage is aggregated across the execution
-   *
-   * Note: The agent (OpenCode/Claude) handles multi-turn execution internally.
-   * Most tasks complete in a single call. The maxTurns option is for edge cases
-   * where the agent explicitly signals it needs additional input.
-   *
-   * @param prompt - Task description for the agent
-   * @param options - Task options
-   * @returns Task result with response and execution metadata
-   */
-  task(prompt: string, options?: TaskOptions): Promise<TaskResult>;
-  /**
-   * Stream events from a task execution.
-   *
-   * Use this for real-time updates as the agent works:
-   * - Tool calls and results
-   * - Thinking/reasoning steps
-   * - File operations
-   * - Final response
-   *
-   * @param prompt - Task description for the agent
-   * @param options - Task options
-   */
-  streamTask(prompt: string, options?: TaskOptions): AsyncGenerator<SandboxEvent>;
-  /**
-   * Search for text patterns in files using ripgrep.
-   *
-   * This is a first-class code search capability, not a shell wrapper.
-   * Ripgrep is pre-installed in all managed sandboxes.
-   *
-   * @param pattern - Regular expression pattern to search for
-   * @param options - Search options
-   * @returns Async iterator of search matches
-   *
-   * @example Search for task-marker comments
-   * ```typescript
-   * for await (const match of box.search("TASK:", { glob: "**\/*.ts" })) {
-   *   console.log(`${match.path}:${match.line}: ${match.text}`);
-   * }
-   * ```
-   *
-   * @example Collect all matches
-   * ```typescript
-   * const matches = [];
-   * for await (const match of box.search("function.*async")) {
-   *   matches.push(match);
-   * }
-   * ```
-   */
-  search(pattern: string, options?: SearchOptions): AsyncGenerator<SearchMatch>;
-  /**
-   * Live whole-sandbox resource usage (memory + CPU) from the container cgroup.
-   *
-   * Returns `null` when cgroup stats are unavailable (non-Linux host). Memory is
-   * in MB; `memoryPeakMb` is the high-water mark since the sandbox started. CPU
-   * is a cumulative microsecond counter — sample twice and compute
-   * `cpu% = ΔcpuUsageUsec / (ΔsampledAtMs * 10)` for utilization.
-   *
-   * @example
-   * ```typescript
-   * const r = await box.resourceUsage();
-   * if (r) console.log(`peak ${r.memoryPeakMb} MB`);
-   * ```
-   */
-  resourceUsage(): Promise<SandboxResourceUsage | null>;
-  /**
-   * Git capability object for repository operations.
-   *
-   * All git operations are executed in the sandbox workspace.
-   *
-   * @example Check status and commit
-   * ```typescript
-   * const status = await box.git.status();
-   * if (status.isDirty) {
-   *   await box.git.add(["."]);
-   *   await box.git.commit("Update files");
-   *   await box.git.push();
-   * }
-   * ```
-   */
-  get git(): GitCapability;
-  private gitStatus;
-  private gitLog;
-  private gitDiff;
-  private gitAdd;
-  private gitCommit;
-  private gitPush;
-  private gitPull;
-  private gitBranches;
-  private gitCheckout;
-  /**
-   * Tools capability object for managing language runtimes.
-   *
-   * Uses mise (polyglot version manager) to install and manage tools.
-   *
-   * @example Install and use Node.js
-   * ```typescript
-   * await box.tools.install("node", "22");
-   * await box.tools.use("node", "22");
-   * const list = await box.tools.list();
-   * ```
-   */
-  get tools(): ToolsCapability;
-  /**
-   * File system operations beyond basic read/write:
-   * - Binary upload/download
-   * - Directory ops (uploadDir, downloadDir, list, mkdir)
-   * - Metadata (stat, exists)
-   * - Progress reporting for large files
-   *
-   * @example Upload and download
-   * ```typescript
-   * await box.fs.upload("./model.bin", "/workspace/models/model.bin");
-   * await box.fs.download("/workspace/results.zip", "./results.zip");
-   * ```
-   *
-   * @example Directory operations
-   * ```typescript
-   * await box.fs.uploadDir("./project", "/workspace/project");
-   * const files = await box.fs.list("/workspace");
-   * ```
-   *
-   * @example File management
-   * ```typescript
-   * if (await box.fs.exists("/workspace/config.json")) {
-   *   const info = await box.fs.stat("/workspace/config.json");
-   *   console.log(`Size: ${info.size}`);
-   * }
-   * await box.fs.mkdir("/workspace/output", { recursive: true });
-   * await box.fs.delete("/workspace/temp", { recursive: true });
-   * ```
-   */
-  get fs(): FileSystem;
-  private fsUpload;
-  private fsDownload;
-  private fsUploadDir;
-  private fsDownloadDir;
-  private fsList;
-  private fsStat;
-  private fsDelete;
-  private fsMkdir;
-  private fsExists;
-  /**
-   * Permissions manager for multi-user access control.
-   *
-   * @example List users
-   * ```typescript
-   * const users = await box.permissions.list();
-   * for (const user of users) {
-   *   console.log(`${user.username}: ${user.role}`);
-   * }
-   * ```
-   *
-   * @example Add a developer
-   * ```typescript
-   * await box.permissions.add({
-   *   userId: "user_abc",
-   *   role: "developer",
-   *   sshKeys: ["ssh-ed25519 AAAA..."],
-   * });
-   * ```
-   */
-  get permissions(): PermissionsManager;
-  private permissionsList;
-  private permissionsGet;
-  private permissionsAdd;
-  private permissionsUpdate;
-  private permissionsRemove;
-  private permissionsSetAccessPolicies;
-  private permissionsGetAccessPolicies;
-  private permissionsCheckAccess;
-  /**
-   * Backend manager for runtime agent configuration.
-   *
-   * @example Check backend status
-   * ```typescript
-   * const status = await box.backend.status();
-   * console.log(`Backend: ${status.type}, Status: ${status.status}`);
-   * ```
-   *
-   * @example Add MCP server at runtime
-   * ```typescript
-   * await box.backend.addMcp("web-search", {
-   *   command: "npx",
-   *   args: ["-y", "@anthropic/web-search"],
-   * });
-   * ```
-   *
-   * @example Read provider-native Cursor metadata
-   * ```typescript
-   * const models = await box.backend.models();
-   * const agents = await box.backend.agents({ limit: 20 });
-   * const runs = await box.backend.runs(agents.items[0].agentId);
-   * ```
-   */
-  get backend(): BackendManager;
-  private backendStatus;
-  private backendCapabilities;
-  private backendAddMcp;
-  private backendGetMcpStatus;
-  private backendUpdateConfig;
-  private backendControlData;
-  private backendControlAction;
-  private backendListSearch;
-  private backendAccount;
-  private backendModels;
-  private backendRepositories;
-  private backendAgents;
-  private backendAgent;
-  private backendArchiveAgent;
-  private backendUnarchiveAgent;
-  private backendDeleteAgent;
-  private backendRuns;
-  private backendRun;
-  private backendAgentMessages;
-  private backendArtifacts;
-  private backendDownloadArtifact;
-  private backendRestart;
-  /**
-   * Process manager for spawning and controlling processes.
-   *
-   * Provides non-blocking process execution with real-time log streaming,
-   * ideal for long-running tasks like ML training or dev servers.
-   *
-   * @example Non-blocking process
-   * ```typescript
-   * const proc = await box.process.spawn("python train.py", {
-   *   cwd: "/workspace",
-   *   env: { "CUDA_VISIBLE_DEVICES": "0" }
-   * });
-   *
-   * // Stream logs
-   * for await (const entry of proc.logs()) {
-   *   console.log(`[${entry.type}] ${entry.data}`);
-   * }
-   *
-   * // Check status
-   * const status = await proc.status();
-   * console.log(`Running: ${status.running}`);
-   *
-   * // Kill if needed
-   * await proc.kill();
-   * ```
-   *
-   * @example Run Python code directly
-   * ```typescript
-   * const result = await box.process.runCode(`
-   *   import numpy as np
-   *   print(np.random.rand(10).mean())
-   * `);
-   * console.log(result.stdout);
-   * ```
-   */
-  get process(): ProcessManager;
-  private processSpawn;
-  private processRunCode;
-  private processList;
-  private processGet;
-  private createProcessHandle;
-  private parseProcessLogStream;
-  /**
-   * Network manager for runtime network configuration.
-   *
-   * @example Update network restrictions
-   * ```typescript
-   * // Block all outbound traffic
-   * await box.network.update({ blockOutbound: true });
-   *
-   * // Or switch to allowlist mode
-   * await box.network.update({
-   *   allowList: ["192.168.1.0/24", "8.8.8.8/32"]
-   * });
-   * ```
-   *
-   * @example Expose ports dynamically
-   * ```typescript
-   * const url = await box.network.exposePort(8000);
-   * console.log(`Service available at: ${url}`);
-   * ```
-   */
-  get network(): NetworkManager;
-  /**
-   * Egress policy manager for controlling outbound internet access.
-   *
-   * @example Read current egress policy
-   * ```typescript
-   * const { policy, source } = await box.egress.get();
-   * console.log(policy.mode, source);
-   * ```
-   *
-   * @example Update egress policy at runtime
-   * ```typescript
-   * await box.egress.update({ mode: "strict", allowDomains: ["api.github.com"] });
-   * ```
-   */
-  get egress(): EgressManager;
-  /**
-   * On-demand GPU leases attached to this sandbox.
-   *
-   * The base sandbox stays cheap; `attach` starts a temporary external GPU
-   * worker with an explicit spend cap, and `detach` destroys it.
-   */
-  get gpu(): GpuLeaseManager;
-  private networkUpdate;
-  private networkExposePort;
-  private networkListUrls;
-  private networkGetConfig;
-  private egressGet;
-  private egressUpdate;
-  private gpuAttach;
-  private gpuList;
-  private gpuExec;
-  private gpuDetach;
-  /**
-   * Validate CIDR notation (IPv4 and IPv6)
-   */
-  private isValidCidr;
-  /**
-   * Preview link management.
-   *
-   * Create publicly accessible HTTPS URLs for TCP ports inside the sandbox.
-   *
-   * @example
-   * ```typescript
-   * const link = await box.previewLinks.create(3000);
-   * console.log(link.url);
-   *
-   * const links = await box.previewLinks.list();
-   * await box.previewLinks.remove(link.previewId);
-   * ```
-   */
-  get previewLinks(): PreviewLinkManager;
-  private previewLinkCreate;
-  private previewLinkList;
-  private previewLinkRemove;
-  /**
-   * Get information about the infrastructure driver for this sandbox.
-   *
-   * @example
-   * ```typescript
-   * const info = await box.getDriverInfo();
-   * console.log(`Driver: ${info.type}, CRIU: ${info.capabilities.criu}`);
-   * ```
-   */
-  getDriverInfo(): Promise<DriverInfo>;
-  private toolsInstall;
-  private toolsUse;
-  private toolsList;
-  private toolsRun;
-  /**
-   * Create a snapshot of the sandbox state.
-   * Snapshots can be used to save workspace state for later restoration.
-   *
-   * If `storage` is provided (BYOS3), the snapshot is created directly
-   * directly on the sandbox and uploaded to customer-provided S3 storage.
-   *
-   * @param options - Snapshot options (tags, paths, storage)
-   * @returns Snapshot result with ID and metadata
-   *
-   * @example Standard snapshot (our storage)
-   * ```typescript
-   * const snap = await box.snapshot({
-   *   tags: ["v1.0", "stable"],
-   * });
-   * console.log(`Snapshot: ${snap.snapshotId}`);
-   * ```
-   *
-   * @example BYOS3 snapshot (customer storage)
-   * ```typescript
-   * const snap = await box.snapshot({
-   *   tags: ["production"],
-   *   storage: {
-   *     type: "s3",
-   *     bucket: "my-snapshots",
-   *     credentials: { accessKeyId: "...", secretAccessKey: "..." },
-   *   },
-   * });
-   * ```
-   */
-  snapshot(options?: SnapshotOptions): Promise<SnapshotResult>;
-  /**
-   * List all snapshots for this sandbox.
-   *
-   * If `storage` is provided (BYOS3), lists snapshots from customer-provided
-   * S3 storage.
-   *
-   * @param storage - Optional customer storage config for BYOS3
-   * @returns Array of snapshot metadata
-   *
-   * @example List from our storage
-   * ```typescript
-   * const snapshots = await box.listSnapshots();
-   * for (const snap of snapshots) {
-   *   console.log(`${snap.snapshotId}: ${snap.createdAt}`);
-   * }
-   * ```
-   *
-   * @example List from customer S3 (BYOS3)
-   * ```typescript
-   * const snapshots = await box.listSnapshots({
-   *   type: "s3",
-   *   bucket: "my-snapshots",
-   *   credentials: { accessKeyId: "...", secretAccessKey: "..." },
-   * });
-   * ```
-   */
-  listSnapshots(storage?: SnapshotOptions["storage"]): Promise<SnapshotInfo[]>;
-  revertToSnapshot(snapshotId: string): Promise<SnapshotResult>;
-  private waitForSnapshotRestore;
-  private waitForSnapshotVisible;
-  deleteSnapshot(snapshotId: string): Promise<void>;
-  /**
-   * Restore from the latest snapshot in customer-provided storage.
-   * Only available when using BYOS3 (calls the runtime directly).
-   *
-   * @param storage - Customer storage config (required)
-   * @param destinationPath - Optional path to restore to
-   * @returns Snapshot info if restored, null if no snapshot found
-   *
-   * @example Restore from customer S3
-   * ```typescript
-   * const result = await box.restoreFromStorage({
-   *   type: "s3",
-   *   bucket: "my-snapshots",
-   *   credentials: { accessKeyId: "...", secretAccessKey: "..." },
-   * });
-   *
-   * if (result) {
-   *   console.log(`Restored from ${result.snapshotId}`);
-   * } else {
-   *   console.log("No snapshot found");
-   * }
-   * ```
-   */
-  restoreFromStorage(storage: SnapshotOptions["storage"], options?: RestoreSnapshotOptions): Promise<SnapshotResult | null>;
-  /**
-   * @deprecated CRIU checkpoints were removed. To branch live memory into
-   * copy-on-write children of a running sandbox use {@link branch}; for durable
-   * filesystem state use {@link snapshot}. This method now throws.
-   */
-  checkpoint(): never;
-  /**
-   * @deprecated CRIU checkpoints were removed. List durable filesystem state
-   * with {@link listSnapshots}. This method now throws.
-   */
-  listCheckpoints(): never;
-  /**
-   * @deprecated CRIU checkpoints were removed. This method now throws.
-   */
-  deleteCheckpoint(): never;
-  /**
-   * @deprecated Forking from a CRIU checkpoint was removed. Use {@link branch}
-   * to fork a running sandbox's live memory into copy-on-write children, or
-   * `client.create({ fromSnapshot })` to provision from durable disk state.
-   * This method now throws.
-   */
-  fork(): never;
-  /**
-   * Branch this RUNNING sandbox into `count` copy-on-write children
-   * (Morph Infinibranch parity). Unlike {@link fork} — which rehydrates one
-   * sandbox from a CRIU checkpoint — branch forks the live VM's memory into
-   * many children at once via Firecracker UFFD copy-on-write: the children
-   * share the parent's clean pages instead of each copying full guest
-   * memory. The parent stays running.
-   *
-   * @param count - Number of children to create (must be >= 1).
-   * @param options - Per-child overrides.
-   * @returns Exactly `count` new sandbox instances.
-   *
-   * @example
-   * ```typescript
-   * const [a, b, c] = await box.branch(3);
-   * // a, b, c each share box's memory state at branch time
-   * ```
-   */
-  branch(count: number, options?: BranchOptions): Promise<SandboxInstance[]>;
-  /**
-   * Stop the sandbox (keeps state for resume).
-   */
-  stop(): Promise<void>;
-  /**
-   * Resume a stopped sandbox.
-   */
-  resume(options?: ResumeOptions): Promise<void>;
-  /**
-   * Delete the sandbox permanently.
-   */
-  delete(): Promise<void>;
-  /**
-   * keepAlive is intentionally unavailable until the API exposes timeout updates.
-   * @param seconds - Reserved for future support
-   */
-  keepAlive(_seconds?: number): Promise<void>;
-  /**
-   * Upload a local directory to the sandbox via tar.
-   * @param localPath - Local directory path to upload
-   * @param remotePath - Destination path in the sandbox (default: /home/user)
-   */
-  uploadDirectory(localPath: string, remotePath?: string): Promise<void>;
-  /**
-   * Wait for the sandbox to reach a specific status.
-   *
-   * When `onProgress` is provided and the sandbox is still provisioning,
-   * uses SSE events for real-time progress instead of polling. Falls back
-   * to polling if the SSE connection fails or is unavailable.
-   *
-   * @example Basic wait
-   * ```typescript
-   * await box.waitFor("running");
-   * ```
-   *
-   * @example Wait with progress tracking
-   * ```typescript
-   * await box.waitFor("running", {
-   *   onProgress: (event) => {
-   *     console.log(`[${event.step}] ${event.status} — ${event.message}`);
-   *     if (event.percent !== undefined) {
-   *       updateProgressBar(event.percent);
-   *     }
-   *   },
-   * });
-   * ```
-   */
-  waitFor(status: SandboxStatus | SandboxStatus[], options?: WaitForOptions): Promise<void>;
-  /**
-   * SSE-based wait implementation. Subscribes to provisioning events and
-   * delivers progress callbacks while waiting for a target status.
-   */
-  private waitForWithSSE;
-  private ensureRunning;
-  private runtimeFetch;
-  /**
-   * Delegates to the shared `parseSSEStream` in `lib/sse-parser.ts`
-   * — one canonical SSE implementation for the whole SDK. The
-   * shared parser throws `AbortError` on cancellation (so consumers
-   * can distinguish cancel from clean EOF), but agent/task streaming
-   * callers of this method historically relied on a silent-return
-   * abort: they check `options?.signal?.aborted` AFTER the loop and
-   * decide whether to reconnect. The try/catch below preserves that
-   * legacy contract by swallowing AbortError at the delegate layer.
-   */
-  private parseSSEStream;
-  /**
-   * Associate a session ID with a user ID so the Sandbox API can route
-   * subsequent WebSocket connections to this sandbox.
-   *
-   * @param opts - Session and user identifiers
-   *
-   * @example
-   * ```typescript
-   * await box.registerSessionMapping({
-   *   sessionId: "sess_abc",
-   *   userId: "user_123",
-   * });
-   * ```
-   */
-  registerSessionMapping(opts: {
-    sessionId: string;
-    userId: string; /** The runtime (sidecar) session id this agent session routes to. */
-    runtimeSessionId: string; /** Optional container id for direct routing. */
-    sidecarId?: string; /** Optional projectRef so the server can detect a stale sidecar. */
-    projectRef?: string;
-  }): Promise<SessionMappingResult>;
-  /**
-   * Remove the sidecar session mapping for an agent session. Sandbox deletion
-   * also cleans mappings, so this is only needed to release a mapping while the
-   * sandbox stays alive.
-   */
-  unregisterSessionMapping(opts: {
-    sessionId: string;
-    userId: string;
-  }): Promise<{
-    success: boolean;
-    sessionId: string;
-  }>;
-  private parseInfo;
-  private sleep;
-  /**
-   * Get a session reference bound to this sandbox. Lazy: does not hit the
-   * network until you call a method on the returned `SandboxSession`.
-   * Use {@link sessions} to discover existing session ids.
-   */
-  session(id: string): SandboxSession;
-  /**
-   * List sessions on this sandbox, optionally filtering by status. Returns
-   * `SandboxSession` instances paired with their last-known
-   * {@link SessionInfo} so callers can avoid an extra round-trip per
-   * session for status.
-   */
-  sessions(opts?: SessionListOptions): Promise<Array<{
-    session: SandboxSession;
-    info: SessionInfo;
-  }>>;
-  /**
-   * Dispatch a prompt and return immediately with the session id (Issue
-   * #913 Gap 2). The sandbox keeps running the prompt after this call
-   * returns; reconnect via `box.session(id).events()` or wait for
-   * completion with `box.session(id).result()`.
-   *
-   * Idempotent on `opts.sessionId`: re-dispatching with the same id when
-   * the session is already running is a lookup, not a re-create. This
-   * lets queue retries and reconnect-after-Worker-restart be safe by
-   * construction.
-   */
-  dispatchPrompt(message: string | PromptInputPart[], opts?: DispatchPromptOptions): Promise<DispatchedSession>;
-  /**
-   * List messages for a session, including in-flight assistant content
-   * the agent is still streaming. Each entry's `metadata` carries the
-   * durability marker — `status: "streaming" | "completed" | "interrupted"`,
-   * `completed/interrupted` booleans, and the caller-supplied `turnId`
-   * when one was set. See `SessionMessage` for the full contract.
-   *
-   * Polling this is the right way to detect "did the sidecar die mid-
-   * turn?" — a SIGKILL leaves the assistant message with `status:
-   * "streaming"` and no `completed`/`interrupted` marker; a graceful
-   * abort stamps `interrupted: true` explicitly.
-   */
-  messages(opts: ListMessagesOptions): Promise<SessionMessage[]>;
-  _sessionFork(id: string, opts?: SessionForkOptions): Promise<SessionInfo>;
-  /**
-   * Look up a cached turn result by idempotency key. Returns the cached
-   * payload if a turn with this `turnId` previously completed on the
-   * given session; returns `null` if no such turn has finished yet
-   * (either it never started, or it interrupted before completion).
-   *
-   * Call this before re-issuing a `streamPrompt` / `prompt` / `task`
-   * that you might be retrying — a non-null result means the original
-   * attempt finished and you can return that to your caller instead of
-   * running the agent a second time. Only turns that reach the
-   * `completed` terminal state are cached; interrupted turns are not.
-   */
-  findCompletedTurn(turnId: string, opts: {
-    sessionId: string;
-  }): Promise<CompletedTurnResult | null>;
-  /**
-   * Drive a detached turn forward by exactly one settle → poll → dispatch
-   * pass and report where it stands. Built for tick-based callers —
-   * Cloudflare Workflows steps, queue consumers, crons — that re-invoke
-   * on their own schedule instead of holding a stream open. One
-   * invocation never loops, never sleeps, and never keeps a connection
-   * alive past the pass.
-   *
-   * The pass resolves to the first of:
-   *   1. The completed-turn cache has `turnId` → `completed`, or `failed`
-   *      when the cached payload carries no text — that result is final,
-   *      so a retry cannot improve it.
-   *   2. The session is queued/running → `running`, after enforcing
-   *      `wallCapMs`: a session past the cap is cancelled and reported
-   *      `failed`.
-   *   3. The session is terminal without a cached turn → settle from the
-   *      session result; an unsuccessful result is `failed`.
-   *   4. No session exists → dispatch fire-and-detach (idempotent on
-   *      `sessionId`, exactly like `dispatchPrompt`) → `running`.
-   *
-   * `failed` is always deterministic: re-invoking with the same ids
-   * returns the same outcome rather than starting a second agent run, so
-   * callers can treat it as terminal without their own retry bookkeeping.
-   */
-  driveTurn(message: string | PromptInputPart[], opts: DriveTurnOptions): Promise<TurnDriveResult>;
-  /**
-   * Mint a scoped, time-bounded JWT for direct browser access to this
-   * sandbox (Issue #913 Gap 1). Authority is the caller's
-   * `TANGLE_API_KEY` (sk-tan-*) — the Sandbox API mints the token;
-   * signing secrets stay server-side.
-   *
-   * Use this to give a browser direct read access to the sandbox without
-   * leaking the full bearer (`box.connection.authToken`). The returned
-   * token verifies against the same sidecar middleware that already
-   * gates ProductTokenIssuer-issued JWTs — no new sidecar surface.
-   */
-  mintScopedToken(opts: MintScopedTokenOptions): Promise<ScopedToken>;
-  /** @internal — invoked by SandboxSession.status(). */
-  _sessionStatus(id: string): Promise<SessionInfo | null>;
-  /** @internal — invoked by SandboxSession.events(). */
-  _sessionEvents(id: string, opts?: SessionEventStreamOptions): AsyncGenerator<SandboxEvent>;
-  /** @internal — invoked by SandboxSession.result(). */
-  _sessionResult(id: string): Promise<PromptResult>;
-  /**
-   * @internal — invoked by SandboxSession.cancel(). Void-returning alias of
-   * `_interrupt`: both abort the in-flight execution via `POST /{id}/abort`
-   * (the session and its messages are preserved). `cancel()` discards the
-   * `cancelled` flag; callers that need to distinguish a real interruption
-   * from a no-op should use `interrupt()`.
-   */
-  _sessionCancel(id: string): Promise<void>;
-  /** @internal — invoked by InteractiveSessionHandle.start(). */
-  _startInteractive(id: string, options: StartInteractiveOptions): Promise<InteractiveSessionInfo>;
-  /** @internal — invoked by InteractiveSessionHandle.sendPrompt(). */
-  _sendInteractivePrompt(id: string, prompt: string): Promise<void>;
-  /** @internal — invoked by InteractiveSessionHandle.stop(). */
-  _stopInteractive(id: string): Promise<void>;
-  /** @internal — invoked by SandboxSession.respondToPermission(). */
-  _respondToPermission(id: string, permissionID: string, options: RespondToPermissionOptions): Promise<void>;
-  /** @internal — invoked by SandboxSession.interrupt(). */
-  _interrupt(id: string): Promise<InterruptResult>;
-  /**
-   * @internal — invoked by SandboxSession.answer(). Resolves the session's
-   * outstanding question interaction and posts the answer through the
-   * interaction response route. The positional answer arrays map onto the
-   * question's `answerSpec` fields in order.
-   */
-  _answerQuestion(id: string, answers: Record<string, string[]>): Promise<void>;
-}
-//#endregion
-export { CreateSandboxFleetOptions as $, SandboxFleetMachineRecord as $n, ToolsConfig as $r, ListMessagesOptions as $t, AttachGpuLeaseOptions as A, PublishPublicTemplateVersionOptions as An, SecretInfo as Ar, GitAuth as At, BatchResult as B, SandboxEnvironment as Bn, SshKeysManager as Br, GpuLeaseExecResult as Bt, SandboxMcpEndpoint as C, defineAgentProfile as Ci, ProvisionEvent as Cn, SandboxTraceExport as Cr, FleetDispatchStreamOptions as Ct, AcceleratorKind as D, PublicTemplateInfo as Dn, ScopedTokenScope as Dr, FleetPromptDispatchOptions as Dt, buildSandboxMcpConfig as E, mergeAgentProfiles as Ei, ProvisionStep as En, ScopedToken as Er, FleetMachineId as Et, BackendManager as F, RunCodeOptions as Fn, SessionMessage as Fr, GitStatus as Ft, CodeExecutionResult as G, SandboxFleetDispatchFailureClass as Gn, TaskOptions as Gr, HostAgentDriverConfig as Gt, BatchTaskResult as H, SandboxFleetArtifact as Hn, StartupOperation as Hr, GpuLeaseProviderName as Ht, BackendStatus as I, SSHCommandDescriptor as In, SessionStatus as Ir, GpuLease as It, CodeResultPart as J, SandboxFleetDriverTimings as Jn, TeeAttestationReport as Jr, IntelligenceReport as Jt, CodeLanguage as K, SandboxFleetDispatchResponse as Kn, TaskResult as Kr, HostAgentRuntimeBackend as Kt, BackendType as L, SSHCredentials as Ln, SnapshotInfo as Lr, GpuLeaseBilling as Lt, BackendCapabilities as M, ReapExpiredSandboxFleetsResult as Mn, SessionEventStreamOptions as Mr, GitCommit as Mt, BackendConfig as N, ReconcileSandboxFleetsOptions as Nn, SessionInfo as Nr, GitConfig as Nt, AccessPolicyRule as O, PublicTemplateVersionInfo as On, SearchMatch as Or, FleetPromptDispatchResult as Ot, BackendInfo as P, ReconcileSandboxFleetsResult as Pn, SessionListOptions as Pr, GitDiff as Pt, CreateRequestOptions as Q, SandboxFleetMachineMeteredUsage as Qn, TokenRefreshHandler as Qr, IntelligenceReportWindow as Qt, BatchEvent as R, SandboxClientConfig as Rn, SnapshotOptions as Rr, GpuLeaseCommandResult as Rt, SandboxMcpConfig as S, AgentSubagentProfile as Si, PromptResult as Sn, SandboxTraceEvent as Sr, FleetDispatchResultBufferOptions as St, buildControlPlaneMcpConfig as T, defineInlineResource as Ti, ProvisionStatus as Tn, SandboxUser as Tr, FleetExecDispatchResult as Tt, BranchOptions as U, SandboxFleetArtifactSpec as Un, StorageConfig as Ur, GpuLeaseStatus as Ut, BatchTask as V, SandboxEvent as Vn, StartupDiagnostics as Vr, GpuLeaseManager as Vt, CodeExecutionOptions as W, SandboxFleetCostEstimate as Wn, SubscriptionInfo as Wr, GpuType as Wt, CreateGpuLeaseOptions as X, SandboxFleetIntelligenceEnvelope as Xn, TeePublicKey as Xr, IntelligenceReportCompareTo as Xt, CompletedTurnResult as Y, SandboxFleetInfo as Yn, TeeAttestationResponse as Yr, IntelligenceReportBudget as Yt, CreateIntelligenceReportOptions as Z, SandboxFleetMachine as Zn, TeePublicKeyResponse as Zr, IntelligenceReportSubjectType as Zt, StartInteractiveOptions as _, AgentProfilePrompt as _i, ProcessSignal as _n, SandboxPermissionsConfig as _r, ExecResult as _t, TraceExportSink as a, WaitForOptions as ai, MkdirOptions as an, SandboxFleetToken as ar, DispatchPromptOptions as at, CONTROL_PLANE_MCP_SERVER_NAME as b, AgentProfileValidationIssue as bi, PromptInputPart as bn, SandboxStatus as br, FleetDispatchCancelResult as bt, otelTraceIdForTangleTrace as c, WriteManyOptions as ci, NonHostAgentDriverConfig as cn, SandboxFleetTraceExport as cr, DownloadProgress as ct, InteractiveAuthFile as d, AgentProfileConfidential as di, PreviewLinkInfo as dn, SandboxFleetWorkspace as dr, DriverInfo as dt, TurnDriveResult as ei, ListOptions as en, SandboxFleetMachineSpec as er, CreateSandboxFleetTokenOptions as et, InteractiveSessionHandle as f, AgentProfileConnection as fi, PreviewLinkManager as fn, SandboxFleetWorkspaceReconcileResult as fr, DriverType as ft, RespondToPermissionOptions as g, AgentProfilePermissionValue as gi, ProcessManager as gn, SandboxIntelligenceEnvelope as gr, ExecOptions as gt, InterruptResult as h, AgentProfileModelHints as hi, ProcessLogEntry as hn, SandboxInfo as hr, EventStreamOptions as ht, TraceExportResult as i, UsageInfo as ii, MintScopedTokenOptions as in, SandboxFleetPolicy as ir, DirectoryPermission as it, AttachSandboxFleetMachineOptions as j, ReapExpiredSandboxFleetsOptions as jn, SecretsManager as jr, GitBranch as jt, AddUserOptions as k, PublishPublicTemplateOptions as kn, SearchOptions as kr, GPU_LEASE_PROVIDER_NAMES as kt, toOtelJson as l, AgentProfile as li, PermissionLevel as ln, SandboxFleetTraceOptions as lr, DriveTurnOptions as lt, InteractiveSessionInfo as m, AgentProfileMcpServer as mi, ProcessInfo as mn, SandboxFleetWorkspaceSnapshotResult as mr, EgressPolicy as mt, SandboxInstance as n, UploadOptions as ni, ListSandboxOptions as nn, SandboxFleetManifestMachine as nr, CreateSandboxOptions as nt, buildTraceExportPayload as o, WriteFileOptions as oi, NetworkConfig as on, SandboxFleetTraceBundle as or, DispatchedSession as ot, InteractiveSessionHost as p, AgentProfileFileMount as pi, Process as pn, SandboxFleetWorkspaceRestoreResult as pr, EgressManager as pt, CodeResult as q, SandboxFleetDriverCapability as qn, TeeAttestationOptions as qr, InstalledTool as qt, TraceExportFormat as r, UploadProgress as ri, McpServerConfig as rn, SandboxFleetOperationsSummary as rr, DeleteOptions as rt, exportTraceBundle as s, WriteManyFile as si, NetworkManager as sn, SandboxFleetTraceEvent as sr, DownloadOptions as st, HttpClient as t, UpdateUserOptions as ti, ListSandboxFleetOptions as tn, SandboxFleetManifest as tr, CreateSandboxFleetWithCoordinatorOptions as tt, SandboxSession as u, AgentProfileCapabilities as ui, PermissionsManager as un, SandboxFleetUsage as ur, DriverConfig as ut, BuildControlPlaneMcpConfigOptions as v, AgentProfileResourceRef as vi, ProcessSpawnOptions as vn, SandboxResourceUsage as vr, FileInfo as vt, SandboxMcpServerEntry as w, defineGitHubResource as wi, ProvisionResult as wn, SandboxTraceOptions as wr, FleetExecDispatchOptions as wt, SANDBOX_MCP_SERVER_NAME as x, AgentProfileValidationResult as xi, PromptOptions as xn, SandboxTraceBundle as xr, FleetDispatchResultBuffer as xt, BuildSandboxMcpConfigOptions as y, AgentProfileResources as yi, ProcessStatus as yn, SandboxResources as yr, FileSystem as yt, BatchOptions as z, SandboxConnection as zn, SnapshotResult as zr, GpuLeaseExecOptions as zt };
+export { EventStreamOptions as $, SandboxFleetPolicy as $n, StartupOperation as $r, NetworkConfig as $t, CommitTaskSessionOptions as A, AgentProfileMcpServer as Ai, RunCodeOptions as An, SandboxUser as Ar, GpuLeaseCommandResult as At, CreateTaskSessionOptions as B, defineGitHubResource as Bi, SandboxFleetDispatchFailureClass as Bn, SessionBackendCredentials as Br, IntelligenceReport as Bt, BatchTaskUsage as C, WriteManyFile as Ci, PublishPublicTemplateVersionOptions as Cn, SandboxTerminalInfo as Cr, GitBranch as Ct, CodeLanguage as D, AgentProfileConfidential as Di, ReconcileSandboxFleetsResult as Dn, SandboxTraceEvent as Dr, GitStatus as Dt, CodeExecutionResult as E, AgentProfileCapabilities as Ei, ReconcileSandboxFleetsOptions as En, SandboxTraceBundle as Er, GitDiff as Et, CreateSandboxFleetOptions as F, AgentProfileResources as Fi, SandboxEnvironment as Fn, SecretInfo as Fr, GpuLeaseStatus as Ft, DownloadOptions as G, SandboxFleetIntelligenceEnvelope as Gn, SessionMessage as Gr, JsonValue as Gt, DirectoryPermission as H, mergeAgentProfiles as Hi, SandboxFleetDriverCapability as Hn, SessionForkOptions as Hr, IntelligenceReportCompareTo as Ht, CreateSandboxFleetTokenOptions as I, AgentProfileValidationIssue as Ii, SandboxEvent as In, SecretsManager as Ir, GpuType as It, DriverConfig as J, SandboxFleetMachineRecord as Jn, SnapshotInfo as Jr, ListSandboxFleetOptions as Jt, DownloadProgress as K, SandboxFleetMachine as Kn, SessionMessageInputPart as Kr, ListMessagesOptions as Kt, CreateSandboxFleetWithCoordinatorOptions as L, AgentProfileValidationResult as Li, SandboxFleetArtifact as Ln, SendSessionMessageOptions as Lr, HostAgentDriverConfig as Lt, CreateGpuLeaseOptions as M, AgentProfilePermissionValue as Mi, SSHCredentials as Mn, ScopedTokenScope as Mr, GpuLeaseExecResult as Mt, CreateIntelligenceReportOptions as N, AgentProfilePrompt as Ni, SandboxClientConfig as Nn, SearchMatch as Nr, GpuLeaseManager as Nt, CodeResult as O, AgentProfileConnection as Oi, RestoreSnapshotOptions as On, SandboxTraceExport as Or, GpuLease as Ot, CreateRequestOptions as P, AgentProfileResourceRef as Pi, SandboxConnection as Pn, SearchOptions as Pr, GpuLeaseProviderName as Pt, EgressPolicy as Q, SandboxFleetOperationsSummary as Qn, StartupDiagnostics as Qr, MkdirOptions as Qt, CreateSandboxOptions as R, AgentSubagentProfile as Ri, SandboxFleetArtifactSpec as Rn, SendSessionMessageRequest as Rr, HostAgentRuntimeBackend as Rt, BatchTaskResult as S, WriteFileOptions as Si, PublishPublicTemplateOptions as Sn, SandboxTerminalCreateOptions as Sr, GitAuth as St, CodeExecutionOptions as T, AgentProfile as Ti, ReapExpiredSandboxFleetsResult as Tn, SandboxTerminalRequestOptions as Tr, GitConfig as Tt, DispatchPromptOptions as U, SandboxFleetDriverTimings as Un, SessionInfo as Ur, IntelligenceReportSubjectType as Ut, DeleteOptions as V, defineInlineResource as Vi, SandboxFleetDispatchResponse as Vn, SessionEventStreamOptions as Vr, IntelligenceReportBudget as Vt, DispatchedSession as W, SandboxFleetInfo as Wn, SessionListOptions as Wr, IntelligenceReportWindow as Wt, DriverType as X, SandboxFleetManifest as Xn, SnapshotResult as Xr, McpServerConfig as Xt, DriverInfo as Y, SandboxFleetMachineSpec as Yn, SnapshotOptions as Yr, ListSandboxOptions as Yt, EgressManager as Z, SandboxFleetManifestMachine as Zn, SshKeysManager as Zr, MintScopedTokenOptions as Zt, BatchResult as _, UpdateUserOptions as _i, ProvisionResult as _n, SandboxResources as _r, FleetExecDispatchResult as _t, AttachSandboxFleetMachineOptions as a, TaskSessionCommitResult as ai, PreviewLinkManager as an, SandboxFleetUsage as ar, FileReadError as at, BatchSidecarGroup as b, UsageInfo as bi, PublicTemplateInfo as bn, SandboxRuntimeProfileList as br, FleetPromptDispatchResult as bt, BackendInfo as c, TaskSessionProfile as ci, ProcessLogEntry as cn, SandboxFleetWorkspaceRestoreResult as cr, FileTreeFile as ct, BackendType as d, TeeAttestationResponse as di, ProcessSpawnOptions as dn, SandboxIntelligenceEnvelope as dr, FileWriteResult as dt, StorageConfig as ei, NetworkManager as en, SandboxFleetToken as er, ExecOptions as et, BatchBackend as f, TeePublicKey as fi, ProcessStatus as fn, SandboxPermissionsConfig as fr, FleetDispatchCancelResult as ft, BatchOptions as g, TurnDriveResult as gi, ProvisionEvent as gn, SandboxResourceUsage as gr, FleetExecDispatchOptions as gt, BatchEventDataMap as h, ToolsConfig as hi, PromptResult as hn, SandboxProfileSummary as hr, FleetDispatchStreamOptions as ht, AttachGpuLeaseOptions as i, TaskSessionChanges as ii, PreviewLinkInfo as in, SandboxFleetTraceOptions as ir, FileReadBatchResult as it, CompletedTurnResult as j, AgentProfileModelHints as ji, SSHCommandDescriptor as jn, ScopedToken as jr, GpuLeaseExecOptions as jt, CodeResultPart as k, AgentProfileFileMount as ki, ResumeOptions as kn, SandboxTraceOptions as kr, GpuLeaseBilling as kt, BackendManager as l, TeeAttestationOptions as li, ProcessManager as ln, SandboxFleetWorkspaceSnapshotResult as lr, FileTreeOptions as lt, BatchEvent as m, TokenRefreshHandler as mi, PromptOptions as mn, SandboxPortPreviewLink as mr, FleetDispatchResultBufferOptions as mt, AccessPolicyRule as n, TaskOptions as ni, PermissionLevel as nn, SandboxFleetTraceEvent as nr, FileInfo as nt, BackendCapabilities as o, TaskSessionFileChange as oi, Process as on, SandboxFleetWorkspace as or, FileReadResult as ot, BatchBackendStats as p, TeePublicKeyResponse as pi, PromptInputPart as pn, SandboxPortBinding as pr, FleetDispatchResultBuffer as pt, DriveTurnOptions as q, SandboxFleetMachineMeteredUsage as qn, SessionStatus as qr, ListOptions as qt, AddUserOptions as r, TaskResult as ri, PermissionsManager as rn, SandboxFleetTraceExport as rr, FileReadBatchOptions as rt, BackendConfig as s, TaskSessionInfo as si, ProcessInfo as sn, SandboxFleetWorkspaceReconcileResult as sr, FileSystem as st, AcceleratorKind as t, SubscriptionInfo as ti, NonHostAgentDriverConfig as tn, SandboxFleetTraceBundle as tr, ExecResult as tt, BackendStatus as u, TeeAttestationReport as ui, ProcessSignal as un, SandboxInfo as ur, FileTreeResult as ut, BatchRunOptions as v, UploadOptions as vi, ProvisionStatus as vn, SandboxRuntimeHealth as vr, FleetMachineId as vt, BranchOptions as w, WriteManyOptions as wi, ReapExpiredSandboxFleetsOptions as wn, SandboxTerminalManager as wr, GitCommit as wt, BatchTask as x, WaitForOptions as xi, PublicTemplateVersionInfo as xn, SandboxStatus as xr, GPU_LEASE_PROVIDER_NAMES as xt, BatchRunRequest as y, UploadProgress as yi, ProvisionStep as yn, SandboxRuntimeProfile as yr, FleetPromptDispatchOptions as yt, CreateSessionOptions as z, defineAgentProfile as zi, SandboxFleetCostEstimate as zn, SentSessionMessage as zr, InstalledTool as zt };