@tangle-network/sandbox 0.10.2 → 0.10.4

package/dist/sandbox-BtNWbfd3.d.ts

@@ -0,0 +1,1545 @@
+import { $ as EventStreamOptions, A as CommitTaskSessionOptions, Ai as WriteFileOptions, An as Rollout, B as CreateTaskSessionOptions, Br as SearchMatch, Bt as IntelligenceReport, Ci as TurnDriveResult, Cr as SandboxResourceUsage, Ct as GitBranch, D as CodeLanguage, Dr as SandboxRuntimeProfileList, Dt as GitStatus, E as CodeExecutionResult, Et as GitDiff, Gr as SendSessionMessageRequest, Gt as JsonValue, Ht as IntelligenceReportCompareTo, Ir as SandboxTraceOptions, Jr as SessionEventStreamOptions, Kr as SentSessionMessage, Kt as ListMessagesOptions, Mi as WriteManyOptions, Mn as RolloutOptions, Nr as SandboxTraceBundle, Nt as GpuLeaseManager, Oi as WaitForOptions, On as RestoreSnapshotOptions, Or as SandboxStatus, Ot as GpuLease, Pn as RolloutStartResult, Qr as SessionMessage, Rn as SSHCommandDescriptor, Rr as ScopedToken, T as CodeExecutionOptions, Tr as SandboxRuntimeHealth, U as DispatchPromptOptions, Un as SandboxEvent, Vn as SandboxConnection, Vr as SearchOptions, Vt as IntelligenceReportBudget, W as DispatchedSession, Wr as SendSessionMessageOptions, Wt as IntelligenceReportWindow, Xr as SessionInfo, Y as DriverInfo, Yr as SessionForkOptions, Z as EgressManager, Zr as SessionListOptions, Zt as MintScopedTokenOptions, _n as ProvisionResult, _r as SandboxInfo, ai as StartupDiagnostics, an as PreviewLinkManager, bi as TeePublicKeyResponse, br as SandboxPortBinding, cr as SandboxFleetTraceBundle, di as TaskSessionChanges, dt as FileWriteResult, en as NetworkManager, et as ExecOptions, fi as TaskSessionCommitResult, gi as TeeAttestationOptions, gn as ProvisionEvent, hn as PromptResult, j as CompletedTurnResult, ji as WriteManyFile, jr as SandboxTerminalManager, ki as WaitForRolloutOptions, kn as ResumeOptions, l as BackendManager, li as TaskOptions, ln as ProcessManager, mi as TaskSessionInfo, mn as PromptOptions, ni as SnapshotOptions, pn as PromptInputPart, q as DriveTurnOptions, ri as SnapshotResult, rn as PermissionsManager, s as BackendConfig, st as FileSystem, ti as SnapshotInfo, tt as ExecResult, ui as TaskResult, vi as TeeAttestationResponse, w as BranchOptions, wt as GitCommit, z as CreateSessionOptions, zn as SSHCredentials, zt as InstalledTool } from "./types-BvSoEHz8.js";
+
+//#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>;
+  _sessionDelete(id: string): Promise<void>;
+  _sessionSendMessage(id: string, request: SendSessionMessageRequest, options?: SendSessionMessageOptions): Promise<SentSessionMessage>;
+  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>;
+  /**
+   * Send a structured message through the session message endpoint. Model and
+   * message identifiers are translated to the runtime's wire names by the SDK.
+   */
+  sendMessage(request: SendSessionMessageRequest, options?: SendSessionMessageOptions): Promise<SentSessionMessage>;
+  /**
+   * 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>;
+  /** Delete this session and its persisted runtime state. */
+  delete(): 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/task-session.d.ts
+/** @internal Operations implemented by `SandboxInstance`. */
+interface SandboxTaskSessionHost extends SandboxSessionHost {
+  _taskSessionChanges(id: string): Promise<TaskSessionChanges>;
+  _taskSessionCommit(id: string, options?: CommitTaskSessionOptions): Promise<TaskSessionCommitResult>;
+}
+/** A background task session with isolated changeset operations. */
+declare class SandboxTaskSession extends SandboxSession {
+  private readonly taskBox;
+  /** @internal Apps should call `box.taskSession(id)`. */
+  constructor(taskBox: SandboxTaskSessionHost, id: string);
+  /** Read the task's isolated file changes. */
+  changes(): Promise<TaskSessionChanges>;
+  /** Apply all or a selected subset of the task's isolated file changes. */
+  commit(options?: CommitTaskSessionOptions): Promise<TaskSessionCommitResult>;
+}
+//#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?;
+  private readonly runtime;
+  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<FileWriteResult>;
+  /**
+   * 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>;
+  /** Basic health reported by the runtime inside this sandbox. */
+  runtimeHealth(): Promise<SandboxRuntimeHealth>;
+  /** Return the runtime's current listening-port snapshot. */
+  ports(): Promise<SandboxPortBinding[]>;
+  /** Interactive terminal operations for this runtime. */
+  get terminals(): SandboxTerminalManager;
+  /** List profiles installed in this sandbox runtime. */
+  listProfiles(): Promise<SandboxRuntimeProfileList>;
+  /**
+   * 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 fsReadBatch;
+  private fsTree;
+  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[]>;
+  /**
+   * Speculative rollouts: branch this RUNNING sandbox into `n` copy-on-write
+   * children, run the SAME agent turn in every child in parallel, and
+   * optionally score each child by running `scorer.command` inside it (exit 0
+   * passes; stdout is parsed as the numeric score — highest wins).
+   *
+   * Async-op shape: resolves as soon as the children exist (their turns are
+   * still running); poll {@link getRollout} or use {@link waitForRollout} for
+   * results. Children are first-class sandboxes the caller may promote or
+   * delete — each occupies a concurrent-session quota slot like a create.
+   *
+   * @example
+   * ```typescript
+   * const started = await box.rollout({
+   *   n: 4,
+   *   parts: [{ type: "text", text: "make the failing test pass" }],
+   *   scorer: { type: "command", command: "npm test --silent && echo 1" },
+   * });
+   * const settled = await box.waitForRollout(started.rolloutId);
+   * console.log(settled.winner, settled.results);
+   * ```
+   */
+  rollout(options: RolloutOptions): Promise<RolloutStartResult>;
+  /**
+   * Poll a rollout's status and per-child results.
+   *
+   * Failed or timed-out children appear as result entries with `error` set —
+   * partial results are never dropped. Rollout poll-state lives in
+   * orchestrator RAM: after an orchestrator restart this returns 404 while
+   * the children themselves survive as first-class sandboxes.
+   */
+  getRollout(rolloutId: string): Promise<Rollout>;
+  /**
+   * Poll {@link getRollout} until the rollout leaves `running`, then return
+   * the terminal record — including `partial`/`failed` outcomes, whose
+   * per-child `error` entries are results the caller inspects, not
+   * exceptions. Throws {@link TimeoutError} on deadline or abort.
+   */
+  waitForRollout(rolloutId: string, options?: WaitForRolloutOptions): Promise<Rollout>;
+  /**
+   * Stop the sandbox (keeps state for resume).
+   *
+   * The stop response carries the orchestrator's per-phase stop breakdown
+   * (`stop_metering` / `container_kill` / `stop_complete` /
+   * `stop_unaccounted`); after this resolves, {@link startupDiagnostics}
+   * returns it (replacing the create breakdown).
+   */
+  stop(): Promise<void>;
+  /**
+   * Resume a stopped sandbox.
+   */
+  resume(options?: ResumeOptions): Promise<void>;
+  /**
+   * Delete the sandbox permanently.
+   *
+   * The delete response carries the orchestrator's per-phase delete breakdown
+   * (`container_remove` / `storage_binding_wait` / `cleanup_parallel` /
+   * `delete_complete` / `delete_unaccounted`); after this resolves,
+   * {@link startupDiagnostics} returns it for post-mortem reads on the
+   * now-gone sandbox.
+   */
+  delete(): Promise<void>;
+  /**
+   * Read the per-phase lifecycle breakdown off a stop/resume/delete response
+   * body. Never throws: diagnostics are measurement data — a body that fails
+   * to parse (older API, empty body) must not fail the lifecycle call.
+   */
+  private readLifecycleDiagnostics;
+  /**
+   * 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;
+  /** Create an agent session and return both its handle and initial metadata. */
+  createSession(options: CreateSessionOptions): Promise<{
+    session: SandboxSession;
+    info: SessionInfo;
+  }>;
+  /** Delete an agent session by id. */
+  deleteSession(id: string): Promise<void>;
+  /** Get a lazy background-task session reference. */
+  taskSession(id: string): SandboxTaskSession;
+  /** Create a background task session. Dispatch work with `session.sendMessage()`. */
+  createTaskSession(options: CreateTaskSessionOptions): Promise<{
+    session: SandboxTaskSession;
+    info: TaskSessionInfo;
+  }>;
+  /**
+   * 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[]>;
+  /** @internal — invoked by SandboxSession.sendMessage(). */
+  _sessionSendMessage(id: string, request: SendSessionMessageRequest, options?: SendSessionMessageOptions): Promise<SentSessionMessage>;
+  /** @internal — invoked by SandboxSession.delete(). */
+  _sessionDelete(id: string): Promise<void>;
+  /** @internal — invoked by SandboxTaskSession.changes(). */
+  _taskSessionChanges(id: string): Promise<TaskSessionChanges>;
+  /** @internal — invoked by SandboxTaskSession.commit(). */
+  _taskSessionCommit(id: string, options?: CommitTaskSessionOptions): Promise<TaskSessionCommitResult>;
+  _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 { SandboxMcpConfig as C, buildSandboxMcpConfig as D, buildControlPlaneMcpConfig as E, SANDBOX_MCP_SERVER_NAME as S, SandboxMcpServerEntry as T, RespondToPermissionOptions as _, TraceExportSink as a, BuildSandboxMcpConfigOptions as b, otelTraceIdForTangleTrace as c, SandboxSession as d, InteractiveAuthFile as f, InterruptResult as g, InteractiveSessionInfo as h, TraceExportResult as i, toOtelJson as l, InteractiveSessionHost as m, SandboxInstance as n, buildTraceExportPayload as o, InteractiveSessionHandle as p, TraceExportFormat as r, exportTraceBundle as s, HttpClient as t, SandboxTaskSession as u, StartInteractiveOptions as v, SandboxMcpEndpoint as w, CONTROL_PLANE_MCP_SERVER_NAME as x, BuildControlPlaneMcpConfigOptions as y };