@tangle-network/sandbox 0.0.0-develop.20260514223840.b2abd84

package/dist/sandbox-CTe9fN5m.d.ts

@@ -0,0 +1,4857 @@
+import { IntegrationActor, IntegrationManifest } from "@tangle-network/agent-integrations";
+
+//#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;
+};
+//#endregion
+//#region src/agent-profile.d.ts
+/**
+ * Provider-neutral agent profile types for public SDK consumers.
+ *
+ * These model portable agent intent at the application boundary.
+ * Individual backends can translate this shape into their own native
+ * profile/configuration formats internally.
+ */
+/**
+ * Permission policy value for a capability.
+ */
+type AgentProfilePermissionValue = "allow" | "ask" | "deny";
+type AgentProfilePermission = AgentProfilePermissionValue | Record<string, AgentProfilePermissionValue>;
+/**
+ * Generic resource reference that can be resolved into a file or instruction.
+ */
+type AgentProfileResourceRef = {
+  kind: "inline";
+  name: string;
+  content: string;
+} | {
+  kind: "github";
+  /**
+   * Optional repository in "owner/repo" form. When omitted, providers may
+   * only resolve the path if they have an ambient repository context.
+   */
+  repository?: string;
+  path: string;
+  ref?: string;
+  name?: string;
+};
+/**
+ * Helper for creating typed inline resource refs.
+ */
+declare function defineInlineResource(name: string, content: string): AgentProfileResourceRef;
+/**
+ * Helper for creating typed GitHub-backed resource refs.
+ */
+declare function defineGitHubResource(path: string, options?: {
+  repository?: string;
+  ref?: string;
+  name?: string;
+}): AgentProfileResourceRef;
+/**
+ * Resource mounted into a backend workspace.
+ */
+interface AgentProfileFileMount {
+  path: string;
+  resource: AgentProfileResourceRef;
+  executable?: boolean;
+}
+/**
+ * Provider-neutral resource bundle.
+ */
+interface AgentProfileResources {
+  /**
+   * Generic files to materialize into the agent workspace before execution.
+   */
+  files?: AgentProfileFileMount[];
+  /**
+   * Provider-native tool files. Backends materialize these into their standard
+   * discovery location when they support file-based tools.
+   */
+  tools?: AgentProfileResourceRef[];
+  /**
+   * Agent Skills (`SKILL.md`) packages. Supported by Cursor, Claude Code,
+   * Codex-compatible layouts, OpenCode, and Hermes-style skill harnesses.
+   */
+  skills?: AgentProfileResourceRef[];
+  /**
+   * Provider-native subagent definition files.
+   */
+  agents?: AgentProfileResourceRef[];
+  /**
+   * Provider-native slash command files.
+   */
+  commands?: AgentProfileResourceRef[];
+  /**
+   * Additional instructions injected into the agent context.
+   */
+  instructions?: string | AgentProfileResourceRef;
+  /**
+   * Fail initialization when a provider cannot materialize a resource.
+   */
+  failOnError?: boolean;
+}
+/**
+ * Model selection hints for backends.
+ */
+interface AgentProfileModelHints {
+  /**
+   * Preferred default model (format depends on backend, commonly "provider/model").
+   */
+  default?: string;
+  /**
+   * Preferred small/cheap model for lightweight work.
+   */
+  small?: string;
+  /**
+   * Optional provider preference hint.
+   */
+  provider?: string;
+  /**
+   * Backend-agnostic model metadata/hints.
+   */
+  metadata?: Record<string, unknown>;
+}
+/**
+ * Prompt shaping for an agent.
+ */
+interface AgentProfilePrompt {
+  /**
+   * Full system prompt replacement, when supported.
+   */
+  systemPrompt?: string;
+  /**
+   * Additional instruction lines appended to the active prompt.
+   */
+  instructions?: string[];
+}
+/**
+ * Generic subagent definition.
+ */
+interface AgentSubagentProfile {
+  description?: string;
+  prompt?: string;
+  model?: string;
+  tools?: Record<string, boolean>;
+  permissions?: Record<string, AgentProfilePermission>;
+  maxSteps?: number;
+  metadata?: Record<string, unknown>;
+}
+interface AgentProfileHookCommand {
+  command: string;
+  timeoutMs?: number;
+  blocking?: boolean;
+  matcher?: string;
+  env?: Record<string, string>;
+}
+interface AgentProfileMode {
+  description?: string;
+  model?: string;
+  prompt?: string;
+  tools?: Record<string, boolean>;
+  permissions?: Record<string, AgentProfilePermission>;
+  metadata?: Record<string, unknown>;
+}
+/**
+ * Confidential-execution options for sandbox backends.
+ *
+ * The Tangle blueprint path translates this into TEE job parameters and fails
+ * closed when the requested TEE is unavailable. Callers should verify returned
+ * attestation evidence before treating a session as confidential.
+ */
+interface AgentProfileConfidential {
+  /**
+   * TEE variant requested from the operator.
+   */
+  tee?: "tdx" | "nitro" | "phala-dstack" | "sev-snp" | "any" | (string & {});
+  /**
+   * Optional hex-encoded 32-64 byte challenge for deploy-time report data.
+   */
+  attestationNonce?: string;
+  /**
+   * Require no persistence across session end when supported by the backend.
+   */
+  sealed?: boolean;
+  /**
+   * Ask the SDK/backend to create or require a fresh attestation challenge.
+   */
+  attestationRefresh?: boolean;
+}
+/**
+ * Generic MCP server configuration.
+ */
+interface AgentProfileMcpServer {
+  transport?: "stdio" | "sse" | "http";
+  command?: string;
+  args?: string[];
+  env?: Record<string, string>;
+  cwd?: string;
+  url?: string;
+  headers?: Record<string, string>;
+  enabled?: boolean;
+  metadata?: Record<string, unknown>;
+}
+/**
+ * Public provider-neutral agent profile contract.
+ */
+interface AgentProfile {
+  name?: string;
+  description?: string;
+  version?: string;
+  tags?: string[];
+  prompt?: AgentProfilePrompt;
+  model?: AgentProfileModelHints;
+  permissions?: Record<string, AgentProfilePermission>;
+  tools?: Record<string, boolean>;
+  mcp?: Record<string, AgentProfileMcpServer>;
+  subagents?: Record<string, AgentSubagentProfile>;
+  resources?: AgentProfileResources;
+  hooks?: Record<string, AgentProfileHookCommand[]>;
+  modes?: Record<string, AgentProfileMode>;
+  confidential?: AgentProfileConfidential;
+  metadata?: Record<string, unknown>;
+  /**
+   * Non-portable backend-specific extensions.
+   *
+   * Use this only for features that cannot be expressed generically.
+   * SDK consumers should treat extension keys as backend namespaces.
+   */
+  extensions?: Record<string, Record<string, unknown> | undefined>;
+}
+/**
+ * Helper for declaring typed profiles in application code.
+ */
+declare function defineAgentProfile<T extends AgentProfile>(profile: T): T;
+/**
+ * Capabilities describing how a backend interprets AgentProfile.
+ */
+interface AgentProfileCapabilities {
+  namedProfiles: boolean;
+  systemPrompt: boolean;
+  instructions: boolean;
+  tools: boolean;
+  permissions: boolean;
+  mcp: boolean;
+  subagents: boolean;
+  resources: {
+    files: boolean;
+    instructions: boolean;
+    tools?: boolean;
+    skills?: boolean;
+    agents?: boolean;
+    commands?: boolean;
+  };
+  hooks?: boolean;
+  modes?: boolean;
+  runtimeUpdate: boolean;
+  validation: boolean;
+  /**
+   * Backend extension namespaces understood by this backend.
+   */
+  extensions?: string[];
+}
+/**
+ * Validation issue for a profile/backend pairing.
+ */
+interface AgentProfileValidationIssue {
+  level: "error" | "warning" | "info";
+  code: string;
+  message: string;
+  path?: string;
+}
+/**
+ * Validation output for a provider adapter.
+ */
+interface AgentProfileValidationResult {
+  ok: boolean;
+  issues: AgentProfileValidationIssue[];
+  normalizedProfile?: AgentProfile;
+}
+/**
+ * Merge two public AgentProfile values.
+ *
+ * Overlay fields win on conflicts. Array-like instruction sets are appended.
+ */
+declare function mergeAgentProfiles(base: AgentProfile | undefined, overlay: AgentProfile | undefined): AgentProfile | undefined;
+//#endregion
+//#region src/types.d.ts
+type JsonValue = string | number | boolean | null | JsonValue[] | {
+  [key: string]: JsonValue;
+};
+/**
+ * A development environment.
+ *
+ * Environments provide toolchains provisioned via Nix profiles mounted into
+ * a shared base container. The default "universal" environment includes all
+ * common toolchains (Node.js, Python, Rust, Go, etc.).
+ */
+interface SandboxEnvironment {
+  /** Environment identifier (e.g., "universal") */
+  id: string;
+  /** Human-readable description */
+  description?: string;
+  /** Base template this environment extends */
+  base?: string;
+  /** Environment version tag */
+  version: string;
+  /** Public template identifier when this environment comes from a published template */
+  publicTemplateId?: string;
+  /** Snapshot identifier backing the environment when applicable */
+  snapshotId?: string;
+}
+interface PublicTemplateVersionInfo {
+  id: string;
+  templateId: string;
+  versionNumber: number;
+  snapshotId: string;
+  sourceSandboxId: string;
+  readmeMarkdown: string;
+  tags: string[];
+  releaseNotes: string;
+  createdByCustomerId: string;
+  createdAt: string;
+}
+interface PublicTemplateInfo {
+  id: string;
+  slug: string;
+  name: string;
+  description: string;
+  websiteUrl: string | null;
+  ownerCustomerId: string;
+  ownerTeamId: string | null;
+  forkedFromTemplateId: string | null;
+  latestVersionId: string | null;
+  isFeatured: boolean;
+  featuredRank: number | null;
+  forkCount: number;
+  sandboxCount: number;
+  createdAt: string;
+  updatedAt: string;
+  publishedAt: string;
+  latestVersion: PublicTemplateVersionInfo | null;
+}
+interface PublishPublicTemplateOptions {
+  name: string;
+  slug?: string;
+  description?: string;
+  websiteUrl?: string;
+  snapshotId: string;
+  sourceSandboxId: string;
+  teamId?: string;
+  readmeMarkdown?: string;
+  tags?: string[];
+  releaseNotes?: string;
+  forkedFromTemplateId?: string;
+}
+interface PublishPublicTemplateVersionOptions {
+  snapshotId: string;
+  sourceSandboxId: string;
+  readmeMarkdown?: string;
+  tags?: string[];
+  releaseNotes?: string;
+}
+/**
+ * Git authentication configuration.
+ *
+ * @example HTTPS token
+ * ```typescript
+ * const auth: GitAuth = {
+ *   token: process.env.GITHUB_TOKEN,
+ * };
+ * ```
+ */
+interface GitAuth {
+  /** HTTPS auth token (e.g., GitHub PAT) */
+  token?: string;
+}
+/**
+ * Git repository configuration for cloning at sandbox creation.
+ *
+ * When provided, the repository is cloned during sandbox provisioning,
+ * before the sandbox becomes ready. This is more efficient than cloning
+ * after the sandbox starts.
+ *
+ * @example Basic clone
+ * ```typescript
+ * const git: GitConfig = {
+ *   url: "https://github.com/user/repo.git",
+ * };
+ * ```
+ *
+ * @example Clone specific branch with auth
+ * ```typescript
+ * const git: GitConfig = {
+ *   url: "https://github.com/user/private-repo.git",
+ *   ref: "develop",
+ *   auth: { token: process.env.GITHUB_TOKEN },
+ * };
+ * ```
+ *
+ * @example Sparse checkout for monorepo
+ * ```typescript
+ * const git: GitConfig = {
+ *   url: "https://github.com/org/monorepo.git",
+ *   sparse: ["packages/my-package", "shared"],
+ *   depth: 1,
+ * };
+ * ```
+ */
+interface GitConfig {
+  /** Repository URL (HTTPS or SSH) */
+  url: string;
+  /** Branch, tag, or commit SHA to checkout (default: default branch) */
+  ref?: string;
+  /** Shallow clone depth (default: 1 for faster clones) */
+  depth?: number;
+  /** Sparse checkout paths - only clone these directories */
+  sparse?: string[];
+  /** Authentication for private repositories */
+  auth?: GitAuth;
+}
+/**
+ * Tool version specifications for mise (polyglot version manager).
+ *
+ * Mise is pre-installed in all managed sandboxes and can install any
+ * language runtime or tool on demand. Specify versions here to have
+ * them pre-installed when the sandbox starts.
+ *
+ * @see https://mise.jdx.dev for supported tools
+ *
+ * @example Common tools
+ * ```typescript
+ * const tools: ToolsConfig = {
+ *   node: "22",        // Node.js 22.x (latest minor/patch)
+ *   python: "3.12",    // Python 3.12.x
+ *   rust: "1.75",      // Rust 1.75.x
+ *   go: "1.22",        // Go 1.22.x
+ * };
+ * ```
+ *
+ * @example Exact versions
+ * ```typescript
+ * const tools: ToolsConfig = {
+ *   node: "20.11.0",   // Exact version
+ *   pnpm: "8.15.1",
+ *   deno: "1.40",
+ * };
+ * ```
+ */
+interface ToolsConfig {
+  /** Node.js version (e.g., "22", "20.11.0", "lts") */
+  node?: string;
+  /** Python version (e.g., "3.12", "3.11.7") */
+  python?: string;
+  /** Rust version (e.g., "1.75", "stable", "nightly") */
+  rust?: string;
+  /** Go version (e.g., "1.22", "1.21.6") */
+  go?: string;
+  /** Java version (e.g., "21", "17") */
+  java?: string;
+  /** Ruby version (e.g., "3.3", "3.2.2") */
+  ruby?: string;
+  /** Any other mise-supported tool and version */
+  [tool: string]: string | undefined;
+}
+/**
+ * Configuration for initializing the Sandbox client.
+ *
+ * @example
+ * ```typescript
+ * const client = new Sandbox({
+ *   apiKey: "sk_sandbox_abc123",
+ *   baseUrl: "https://your-sandbox-api.example.com",
+ *   timeoutMs: 60000,
+ * });
+ * ```
+ */
+interface SandboxClientConfig {
+  /** API key for authentication. Must start with `sk_sandbox_` */
+  apiKey: string;
+  /** Base URL for the Sandbox API */
+  baseUrl: string;
+  /** Request timeout in milliseconds. Defaults to 30000 (30 seconds) */
+  timeoutMs?: number;
+  /**
+   * Permit the SDK to read CLI auth files from the host home directory
+   * (`~/.codex/auth.json`, `~/.claude/.credentials.json`,
+   * `~/.claude/settings.json`) and ship them to a `localhost` /
+   * `127.0.0.1` / `::1` `baseUrl` when creating a `codex` or
+   * `claude-code` backend without explicit credentials.
+   *
+   * Default `false`. Without this flag, any process bound to a
+   * localhost port (your sandbox-api or anything else) can impersonate
+   * the API and silently harvest those credentials. Set this to `true`
+   * only when the localhost endpoint is one you control. For non-local
+   * `baseUrl`s the flag is ignored — the SDK never reads home-dir auth
+   * files for remote endpoints.
+   */
+  trustLocalCliAuth?: boolean;
+}
+/**
+ * Status of a sandbox instance.
+ *
+ * Lifecycle: `pending` -> `provisioning` -> `running` -> `stopped` -> (deleted)
+ *
+ * - `pending` - Sandbox created but not yet provisioning
+ * - `provisioning` - Container and resources being allocated
+ * - `running` - Sandbox is active and accepting commands
+ * - `stopped` - Sandbox is paused (can be resumed)
+ * - `failed` - Sandbox encountered an error
+ * - `expired` - Sandbox exceeded its lifetime limit
+ */
+type SandboxStatus = "pending" | "provisioning" | "running" | "stopped" | "failed" | "expired";
+/**
+ * Resource limits for a sandbox.
+ */
+interface SandboxResources {
+  /** Number of CPU cores */
+  cpuCores?: number;
+  /** Memory in megabytes */
+  memoryMB?: number;
+  /** Disk space in gigabytes */
+  diskGB?: number;
+  /** Accelerator request for GPU-class workloads. */
+  accelerator?: SandboxAccelerator;
+}
+/** @deprecated Use SandboxAccelerator.kind via SandboxResources.accelerator. */
+type GpuType = string;
+/**
+ * Configuration for creating a new sandbox.
+ *
+ * Sandboxes can run in two modes:
+ * - **Managed** (default): Full-featured with agent, files, terminal, git, tools
+ * - **Bare**: Minimal container with only exec() and lifecycle methods
+ *
+ * @example Minimal sandbox (managed mode with defaults)
+ * ```typescript
+ * const box = await client.create();
+ * // Uses 'universal' image, managed mode, sane defaults
+ * ```
+ *
+ * @example Sandbox with pre-built image and git
+ * ```typescript
+ * const box = await client.create({
+ *   image: "ethereum",  // Stack name — tools provisioned via Nix profile
+ *   git: {
+ *     url: "https://github.com/user/dapp.git",
+ *     ref: "main",
+ *   },
+ *   tools: { node: "22", python: "3.12" },
+ * });
+ * ```
+ *
+ * @example Sandbox with custom Docker image
+ * ```typescript
+ * const box = await client.create({
+ *   image: "python:3.12-slim",
+ *   git: { url: "https://github.com/user/ml-project.git" },
+ *   tools: { python: "3.12" },
+ * });
+ * ```
+ *
+ * @example Bare sandbox (no managed runtime, just exec)
+ * ```typescript
+ * const box = await client.create({
+ *   image: "ubuntu:24.04",
+ *   bare: true,
+ * });
+ * // Only box.exec(), box.stop(), box.resume(), box.delete() available
+ * ```
+ *
+ * @example With BYOS3 storage for snapshots
+ * ```typescript
+ * const box = await client.create({
+ *   image: "universal",
+ *   storage: {
+ *     type: "s3",
+ *     bucket: "my-snapshots",
+ *     credentials: { accessKeyId: "...", secretAccessKey: "..." },
+ *   },
+ *   fromSnapshot: "snap_abc123",
+ * });
+ * ```
+ */
+interface CreateSandboxOptions {
+  /**
+   * Development environment name.
+   *
+   * Environments provision toolchains via Nix profiles mounted into a
+   * shared base container. Use `client.environments.list()` to discover
+   * available environments.
+   *
+   * Takes precedence over `image` if both are specified.
+   *
+   * @example
+   * ```typescript
+   * environment: "universal"  // Multi-language (default)
+   * ```
+   */
+  environment?: string;
+  /**
+   * Container image to use for the sandbox.
+   *
+   * For most use cases the default "universal" environment is sufficient.
+   * Use this field for custom images; the SDK runtime integration is applied
+   * automatically.
+   *
+   * **Resolution rules:**
+   * - Full image paths → Used as-is
+   * - Simple names without `/` or `:` → Treated as environment name
+   *   (equivalent to setting `environment`)
+   *
+   * When neither `environment` nor `image` is set the SDK omits the
+   * field entirely and the server applies its own default.
+   */
+  image?: string;
+  /**
+   * Create a bare sandbox without the managed runtime.
+   *
+   * Bare sandboxes only have:
+   * - `exec()` - Execute commands
+   * - `stop()` / `resume()` - Lifecycle control
+   * - `delete()` - Cleanup
+   *
+   * Use bare mode when you need a clean container without the managed
+   * runtime integration.
+   *
+   * @default false
+   */
+  bare?: boolean;
+  /**
+   * Infrastructure driver selection.
+   * Controls how the sandbox is provisioned and isolated.
+   *
+   * @example Firecracker with CRIU
+   * ```typescript
+   * driver: { type: "firecracker", enableCriu: true }
+   * ```
+   */
+  driver?: DriverConfig;
+  /**
+   * AI coding agent backend configuration.
+   * Determines which agent runs inside the sandbox.
+   *
+   * @example OpenCode with profile
+   * ```typescript
+   * backend: { type: "opencode", profile: "with-web-search" }
+   * ```
+   */
+  backend?: BackendConfig;
+  /**
+   * Confidential execution requirements for this sandbox.
+   *
+   * This is equivalent to setting `backend.profile.confidential` on an inline
+   * AgentProfile. Tangle-backed creation translates it into blueprint TEE
+   * fields; operators that cannot satisfy the requested TEE fail closed.
+   */
+  confidential?: AgentProfileConfidential;
+  /**
+   * Initial permissions and access control settings.
+   *
+   * @example Multi-user sandbox
+   * ```typescript
+   * permissions: {
+   *   defaultRole: "developer",
+   *   initialUsers: [{ userId: "user_xyz", role: "developer" }],
+   * }
+   * ```
+   */
+  permissions?: SandboxPermissionsConfig;
+  /**
+   * Network security configuration.
+   * Controls outbound network access from the sandbox.
+   *
+   * @example Block all outbound traffic
+   * ```typescript
+   * network: { blockOutbound: true }
+   * ```
+   *
+   * @example Allow only specific destinations
+   * ```typescript
+   * network: {
+   *   allowList: ["8.8.8.8/32", "10.0.0.0/8"],
+   *   ports: [8000, 8080], // Pre-expose ports
+   * }
+   * ```
+   */
+  network?: NetworkConfig;
+  /**
+   * Git repository to clone at sandbox creation.
+   *
+   * The repository is cloned during provisioning, before the sandbox
+   * becomes ready. This is more efficient than cloning after start.
+   *
+   * @example { url: "https://github.com/user/repo.git", ref: "main" }
+   */
+  git?: GitConfig;
+  /**
+   * Tool versions to pre-install via mise.
+   *
+   * Mise (polyglot version manager) is pre-installed in managed sandboxes.
+   * Specify versions here to have them ready when the sandbox starts.
+   *
+   * @example { node: "22", python: "3.12", rust: "1.75" }
+   */
+  tools?: ToolsConfig;
+  /** Human-readable name for the sandbox */
+  name?: string;
+  /** Resource limits (CPU cores, memory, disk) */
+  resources?: SandboxResources;
+  /** Environment variables injected into the sandbox */
+  env?: Record<string, string>;
+  /**
+   * Integration requirements the sandbox app needs at launch.
+   *
+   * The sandbox API resolves this manifest through id.tangle.tools,
+   * creates owner-scoped grants, and injects only a short-lived
+   * `TANGLE_INTEGRATION_BUNDLE` capability payload. Raw provider OAuth
+   * tokens and API keys never enter the sandbox environment.
+   */
+  integrationManifest?: IntegrationManifest;
+  /**
+   * Existing platform grant ids to bind to this launch.
+   *
+   * Use this for installed templates or pre-consented apps where the
+   * installer owns the connection. The sandbox API still requires
+   * `integrationManifest` so platform can fail closed if a grant does not
+   * match the declared requirements.
+   */
+  integrationGrantIds?: string[];
+  /**
+   * Grant durability for `integrationManifest`.
+   *
+   * `preview` scopes consent to this sandbox preview/session,
+   * `durable-app` is for installed/generated app instances, and
+   * `one-shot` is for a single workflow run.
+   */
+  integrationGrantMode?: "preview" | "durable-app" | "one-shot";
+  /**
+   * Logical app/agent subject receiving the grant. When omitted, the
+   * sandbox itself is the grantee and runtime subject.
+   */
+  integrationSubject?: IntegrationActor;
+  /**
+   * Maximum lifetime in seconds.
+   * Sandbox is automatically deleted after this time.
+   * @default 3600 (1 hour)
+   */
+  maxLifetimeSeconds?: number;
+  /**
+   * Idle timeout in seconds.
+   * Sandbox is suspended after this period of inactivity.
+   * @default 900 (15 minutes)
+   */
+  idleTimeoutSeconds?: number;
+  /**
+   * Enable SSH access to the sandbox.
+   * Use `sandbox.ssh()` to get connection credentials.
+   * @default false
+   */
+  sshEnabled?: boolean;
+  /** Custom SSH public key for access (optional) */
+  sshPublicKey?: string;
+  /**
+   * Enable web terminal access.
+   * Provides a browser-based terminal via websocket.
+   * @default false
+   */
+  webTerminalEnabled?: boolean;
+  /**
+   * Customer-provided S3-compatible storage for snapshots (BYOS3).
+   *
+   * When configured, snapshots are stored in your own bucket
+   * instead of Tangle's managed storage.
+   */
+  storage?: StorageConfig;
+  /** Snapshot ID to restore from when creating the sandbox */
+  fromSnapshot?: string;
+  /** Source sandbox ID that owns the snapshot (required when fromSnapshot is set) */
+  fromSandboxId?: string;
+  /**
+   * Apply a saved template at create time. Templates seed the
+   * sandbox with a snapshot, default environment, and config defaults
+   * so a team can publish a golden-path starting point once and have
+   * every member spin up the same baseline.
+   *
+   * The template must either be personal (owned by the caller) or
+   * belong to a team the caller is an active member of. Explicit
+   * fields on this call win over template defaults — so you can layer
+   * a one-off override on top of the golden path without forking the
+   * template itself.
+   *
+   * @example
+   * ```typescript
+   * const box = await client.create({
+   *   templateId: "tpl_abc123",
+   *   teamId: "team_...", // optional; sandbox is shared with the team
+   * });
+   * ```
+   */
+  templateId?: string;
+  /**
+   * Create from a published public template by id or slug.
+   * The API resolves the latest published version unless
+   * `publicTemplateVersionId` is also provided.
+   */
+  publicTemplateId?: string;
+  /** Pin sandbox creation to a specific published public-template version. */
+  publicTemplateVersionId?: string;
+  /**
+   * Names of secrets to inject as environment variables.
+   *
+   * Secrets must be created via `client.secrets.create()` before use.
+   * They are injected as environment variables with the same name.
+   *
+   * @example
+   * ```typescript
+   * // First, create the secrets
+   * await client.secrets.create("HF_TOKEN", "hf_xxx");
+   * await client.secrets.create("AWS_ACCESS_KEY", "AKIA...");
+   *
+   * // Then use them in a sandbox
+   * const box = await client.create({
+   *   secrets: ["HF_TOKEN", "AWS_ACCESS_KEY"],
+   * });
+   *
+   * // Secrets are available as env vars
+   * const result = await box.exec("echo $HF_TOKEN");
+   * ```
+   */
+  secrets?: string[];
+  /** Custom metadata to store with the sandbox */
+  metadata?: Record<string, unknown>;
+  /**
+   * Share this sandbox with a team. The caller must be an active
+   * member of the team — the API rejects requests from non-members
+   * before provisioning. When omitted the sandbox is personal
+   * (accessible only to the creator).
+   */
+  teamId?: string;
+  /**
+   * Sidecar capabilities to enable at boot. Each capability boots an
+   * additional subsystem inside the sandbox; absent capabilities incur
+   * zero startup cost.
+   *
+   * Currently supported:
+   * - `"computer_use"` — boots Xvfb, dbus, AT-SPI, and an MCP server
+   *   exposing mouse/keyboard/screenshot via the Anthropic + OpenAI
+   *   Responses computer-use surface. Required if you plan to call
+   *   {@link SandboxInstance.getMcpAccessToken | `getMcpAccessToken`}
+   *   with `capabilities: ["computer_use"]`.
+   *
+   * The capability is enforced at two layers:
+   * 1. The sidecar refuses to start if a capability's binaries are
+   *    missing (computer_use needs the universal Nix profile, which
+   *    Docker / host-agent / Firecracker drivers ship via the host
+   *    bind-mount or the universal sidecar image variant; Firecracker
+   *    host profiles built without the universal flake do not).
+   * 2. The MCP token endpoint refuses to mint a `cap: ["computer_use"]`
+   *    JWT for a sandbox that wasn't created with that capability.
+   *
+   * **Sizing note:** `computer_use` boots an always-on Xvfb + dbus
+   * stack costing roughly **~100 MB resident memory** inside the
+   * container. Billing is by reserved capacity (not measured RSS), so
+   * this comes out of your sandbox's RAM envelope rather than adding
+   * a separate line item. On a 1 GB sandbox that is ~10% of your
+   * workload's headroom; bump `resources.memoryMb` to 1.5–2 GB if
+   * the agent will run anything memory-hungry alongside it.
+   *
+   * @example
+   * ```typescript
+   * const box = await client.create({
+   *   environment: "universal",
+   *   capabilities: ["computer_use"],
+   * });
+   * const { token } = await box.getMcpAccessToken({
+   *   capabilities: ["computer_use"],
+   * });
+   * ```
+   */
+  capabilities?: ReadonlyArray<"computer_use">;
+  /**
+   * Privacy controls for the sandbox. Two independent layers:
+   *
+   * - **`egress`** — what happens when the sandbox sends a request to a
+   *   model vendor (Anthropic, OpenAI, your own router, etc.):
+   *   - `"redact"` — PII spans are masked before the request leaves
+   *     the sandbox. Emails, JWTs, API keys, credit cards (Luhn-
+   *     validated), SSNs, phone numbers, IPv4 addresses are caught
+   *     today; names / postal addresses / DOBs land when the OPF
+   *     model service is enabled. The agent receives normal
+   *     responses; the vendor sees masked input.
+   *   - `"block"` — PII presence fails the egress request closed.
+   *     For high-compliance flows that prefer fail-closed to leak.
+   *   - `"off"` — no egress filtering. Default for free tier; opt-in
+   *     for tasks that genuinely need raw PII (form-filling,
+   *     customer-support agents reading customer details).
+   *
+   * - **`logs`** — whether infrastructure logs / telemetry / Sentry
+   *   redact PII before recording. This is OUR side, not the model
+   *   vendor's, and there's basically never a reason to leak PII into
+   *   our own logs. Default `"on"`.
+   *
+   * Note: privacy controls operate at the boundary between the
+   * sandbox and external systems. They do NOT redact contents inside
+   * the sandbox workspace itself — files / code / database fixtures
+   * the customer puts there are the customer's data and stay
+   * unmodified. Snapshots preserve those contents verbatim.
+   *
+   * @example
+   * ```typescript
+   * const box = await client.create({
+   *   privacy: { egress: "redact", logs: "on" },
+   * });
+   * ```
+   */
+  privacy?: {
+    egress?: "redact" | "block" | "off";
+    logs?: "on" | "off";
+  };
+}
+/**
+ * SSH connection credentials.
+ */
+interface SSHCredentials {
+  /** Username for SSH authentication */
+  username: string;
+  /** SSH server port */
+  port: number;
+  /** ProxyCommand for sandbox API tunnel-based SSH. */
+  proxyCommand: string;
+}
+interface SSHCommandDescriptor {
+  command: string;
+  env: Record<string, string>;
+}
+/**
+ * Connection information for a sandbox.
+ *
+ * Most code should use `SandboxInstance` methods (`exec`, `prompt`, etc.).
+ * The raw `runtimeUrl` and `authToken` are surfaced only for advanced
+ * lower-level use cases such as custom protocol clients.
+ */
+interface SandboxConnection {
+  /** Sandbox runtime API URL for programmatic access */
+  runtimeUrl?: string;
+  /** Access token for authenticating directly with the runtime (Bearer token) */
+  authToken?: string;
+  /** Token expiration timestamp (ISO 8601). Refresh before this time. */
+  authTokenExpiresAt?: string;
+  /** SSH connection info if `sshEnabled` was true during creation */
+  ssh?: SSHCredentials;
+  /** Web terminal URL if `webTerminalEnabled` was true during creation */
+  webTerminalUrl?: string;
+}
+/**
+ * Full sandbox information returned from the API.
+ */
+interface SandboxInfo {
+  /** Unique sandbox identifier */
+  id: string;
+  /** Human-readable name */
+  name?: string;
+  /** Current status */
+  status: SandboxStatus;
+  /** Connection information */
+  connection?: SandboxConnection;
+  /** Custom metadata */
+  metadata?: Record<string, unknown>;
+  /** When the sandbox was created */
+  createdAt: Date;
+  /** When the sandbox started running */
+  startedAt?: Date;
+  /** Last activity timestamp */
+  lastActivityAt?: Date;
+  /** When the sandbox will expire */
+  expiresAt?: Date;
+  /** Error message if status is 'failed' */
+  error?: string;
+}
+/**
+ * Raw TEE attestation evidence returned by the sandbox runtime.
+ *
+ * Pass this object to `@tangle-network/tcloud-attestation` for caller-side
+ * policy checks and hardware verification.
+ */
+interface TeeAttestationReport {
+  /** TEE backend that produced the report, e.g. `Tdx`, `Sev`, or `Nitro`. */
+  tee_type: string;
+  /** Raw vendor evidence bytes. */
+  evidence: number[];
+  /** Runtime measurement bytes. */
+  measurement: number[];
+  /** Unix timestamp when the report was generated. */
+  timestamp: number;
+}
+/**
+ * Response from a sandbox TEE attestation request.
+ */
+interface TeeAttestationResponse {
+  /** Sandbox identifier the attestation belongs to. */
+  sandbox_id: string;
+  /** Raw TEE attestation report. */
+  attestation: TeeAttestationReport;
+  /** Caller nonce used for this report, when supplied. */
+  attestationNonce?: string;
+}
+/**
+ * TEE-bound public key used for sealed-secret encryption.
+ */
+interface TeePublicKey {
+  /** Key agreement/encryption algorithm, e.g. `x25519-hkdf-sha256`. */
+  algorithm: string;
+  /** Raw public key bytes. */
+  public_key_bytes: number[];
+  /** Attestation report binding this key to the enclave. */
+  attestation: TeeAttestationReport;
+}
+/**
+ * Response from a sandbox TEE public-key request.
+ */
+interface TeePublicKeyResponse {
+  /** Sandbox identifier the public key belongs to. */
+  sandbox_id: string;
+  /** TEE-bound public key and its attestation proof. */
+  public_key: TeePublicKey;
+}
+/**
+ * Options for requesting fresh TEE attestation evidence.
+ */
+interface TeeAttestationOptions {
+  /**
+   * Hex-encoded 32-64 byte caller nonce. When supported by the selected TEE
+   * backend, the runtime binds this to report data so the caller can reject
+   * replayed quotes.
+   */
+  attestationNonce?: string;
+}
+/**
+ * Options for listing sandboxes.
+ */
+interface ListSandboxOptions {
+  /** Filter by status */
+  status?: SandboxStatus | SandboxStatus[];
+  /** Filter personal/team visibility scope */
+  scope?: "personal" | "team" | "all" | `team:${string}`;
+  /** Maximum number of results */
+  limit?: number;
+  /** Offset for pagination */
+  offset?: number;
+}
+/**
+ * Result of executing a command.
+ */
+interface ExecResult {
+  /** Exit code (0 = success) */
+  exitCode: number;
+  /** Standard output */
+  stdout: string;
+  /** Standard error */
+  stderr: string;
+}
+/**
+ * Options for executing a command.
+ */
+interface ExecOptions {
+  /** Working directory for the command. When `sessionId` is set the
+   *  runtime remaps well-known absolute sandbox paths to the task's
+   *  real workspace; without `sessionId`, absolute paths pass through
+   *  verbatim and may not resolve to the task's actual filesystem. */
+  cwd?: string;
+  /** Environment variables */
+  env?: Record<string, string>;
+  /** Timeout in milliseconds */
+  timeoutMs?: number;
+  /** Task session id (e.g. `task-abc123`). When set, the runtime
+   *  resolves `cwd` against the session's isolated workspace and
+   *  applies a virtual-root remap so a well-known absolute sandbox
+   *  path lands in the directory the task actually writes to rather
+   *  than the host's literal filesystem. Essential for drivers that
+   *  give each task its own workspace subdirectory; no-op for drivers
+   *  where the workspace is already the container root. */
+  sessionId?: string;
+}
+/**
+ * Options for code search.
+ *
+ * @example Search TypeScript files
+ * ```typescript
+ * const matches = await box.search("TODO", {
+ *   glob: "**\/*.ts",
+ *   maxResults: 100,
+ * });
+ * ```
+ */
+interface SearchOptions {
+  /** Glob pattern to filter files (e.g., "**\/*.ts") */
+  glob?: string;
+  /** Directory to search in (default: workspace root) */
+  cwd?: string;
+  /** Maximum number of results */
+  maxResults?: number;
+  /** Case-insensitive search */
+  ignoreCase?: boolean;
+  /** Include line context (lines before/after match) */
+  context?: number;
+}
+/**
+ * A single search match from ripgrep.
+ */
+interface SearchMatch {
+  /** File path relative to search root */
+  path: string;
+  /** Line number (1-indexed) */
+  line: number;
+  /** Column number (1-indexed) */
+  column: number;
+  /** The matching line text */
+  text: string;
+  /** Context lines before the match */
+  before?: string[];
+  /** Context lines after the match */
+  after?: string[];
+}
+/**
+ * Git repository status.
+ */
+interface GitStatus {
+  /** Current branch name */
+  branch: string;
+  /** Commit SHA of HEAD */
+  head: string;
+  /** Whether there are uncommitted changes */
+  isDirty: boolean;
+  /** Number of commits ahead of upstream */
+  ahead: number;
+  /** Number of commits behind upstream */
+  behind: number;
+  /** Staged files */
+  staged: string[];
+  /** Modified but unstaged files */
+  modified: string[];
+  /** Untracked files */
+  untracked: string[];
+}
+/**
+ * Git commit information.
+ */
+interface GitCommit {
+  /** Commit SHA */
+  sha: string;
+  /** Short SHA (7 chars) */
+  shortSha: string;
+  /** Commit message */
+  message: string;
+  /** Author name */
+  author: string;
+  /** Author email */
+  email: string;
+  /** Commit date */
+  date: Date;
+}
+/**
+ * Git branch information.
+ */
+interface GitBranch {
+  /** Branch name */
+  name: string;
+  /** Whether this is the current branch */
+  current: boolean;
+  /** Upstream branch (if tracking) */
+  upstream?: string;
+  /** Latest commit SHA */
+  commit: string;
+}
+/**
+ * Git diff information.
+ */
+interface GitDiff {
+  /** Files changed */
+  files: Array<{
+    path: string;
+    status: "added" | "modified" | "deleted" | "renamed";
+    additions: number;
+    deletions: number;
+  }>;
+  /** Total additions */
+  additions: number;
+  /** Total deletions */
+  deletions: number;
+  /** Raw diff output */
+  raw: string;
+}
+/**
+ * Information about an installed tool.
+ */
+interface InstalledTool {
+  /** Tool name (e.g., "node", "python") */
+  name: string;
+  /** Installed version */
+  version: string;
+  /** Path to the tool binary */
+  path: string;
+  /** Whether this is the active/default version */
+  active: boolean;
+}
+/**
+ * Result of an agent prompt.
+ */
+interface PromptResult {
+  /** Whether the prompt completed successfully */
+  success: boolean;
+  /** Agent's response text */
+  response?: string;
+  /** Error message if failed */
+  error?: string;
+  /** Trace ID for debugging */
+  traceId?: string;
+  /** Duration in milliseconds */
+  durationMs: number;
+  /** Token usage */
+  usage?: {
+    inputTokens: number;
+    outputTokens: number;
+  };
+}
+type PromptInputPart = {
+  type: "text";
+  text: string;
+} | {
+  type: "image";
+  filename?: string;
+  mediaType?: string;
+  url?: string;
+  path?: string;
+} | {
+  type: "file";
+  filename?: string;
+  mediaType?: string;
+  url?: string;
+  path?: string;
+  content?: string;
+};
+/**
+ * Options for sending a prompt.
+ */
+interface PromptOptions {
+  /** Session ID for conversation continuity */
+  sessionId?: string;
+  /** Model to use (format: provider/model, e.g., anthropic/claude-sonnet-4-20250514) */
+  model?: string;
+  /**
+   * Per-run backend override.
+   *
+   * Use `backend.profile` with a string for a named profile or a provider-neutral
+   * `AgentProfile` object for inline profile configuration.
+   */
+  backend?: Partial<BackendConfig>;
+  /** Timeout in milliseconds */
+  timeoutMs?: number;
+  /** Additional context */
+  context?: Record<string, unknown>;
+  /** AbortSignal for cancellation */
+  signal?: AbortSignal;
+}
+/**
+ * SSE event from sandbox streaming.
+ */
+interface SandboxEvent {
+  /** Event type */
+  type: string;
+  /** Event data */
+  data: Record<string, unknown>;
+  /** Event ID */
+  id?: string;
+}
+interface SandboxTraceEvent {
+  type: "sandbox.lifecycle.snapshot" | "sandbox.runtime.snapshot" | "sandbox.usage.snapshot" | "sandbox.insight.summary";
+  timestamp: string;
+  sandboxId: string;
+  durationMs?: number;
+  attributes: Record<string, unknown>;
+}
+interface SandboxTraceExport {
+  schemaVersion: "sandbox.trace.v1";
+  traceId: string;
+  sandboxId: string;
+  exportedAt: string;
+  timings: {
+    observedLifecycleMs: number;
+    observedRuntimeMs: number;
+    idleObservedMs: number;
+  };
+  criticalPath: {
+    durationMs: number;
+    phases: Array<{
+      name: string;
+      durationMs: number;
+    }>;
+  };
+  events: SandboxTraceEvent[];
+}
+interface SandboxIntelligenceEnvelope {
+  schemaVersion: "sandbox.intelligence.v1";
+  source: "sandbox-api";
+  subject: {
+    type: "sandbox";
+    sandboxId: string;
+  };
+  billing: {
+    billable: false;
+    billedTo: "platform";
+    costUsd: 0;
+    reason: "deterministic_platform_insight";
+  };
+  metrics: Record<string, number>;
+  signals: Array<{
+    name: string;
+    value: string | number | boolean;
+    severity: "info" | "warn" | "critical";
+    rationale: string;
+  }>;
+  recommendedActions: string[];
+}
+interface SandboxTraceBundle {
+  trace: SandboxTraceExport;
+  intelligence?: SandboxIntelligenceEnvelope;
+}
+interface SandboxTraceOptions {
+  /**
+   * Include the platform-generated intelligence envelope. Defaults to false.
+   * Set true when a customer wants generated insight with the raw trace export.
+   */
+  includeIntelligence?: boolean;
+}
+type IntelligenceReportSubjectType = "sandbox" | "fleet" | "dispatch" | "trace_set";
+interface IntelligenceReport {
+  jobId: string;
+  subject: {
+    type: IntelligenceReportSubjectType;
+    id: string;
+  };
+  mode: "deterministic" | "agentic";
+  status: "queued" | "running" | "completed" | "failed";
+  billing: {
+    billable: boolean;
+    billedTo: "platform" | "customer";
+    costUsd: number;
+    reason: string;
+    budgetMaxUsd?: number;
+  };
+  result: Record<string, unknown> | null;
+  error?: string;
+  createdAt: string;
+  updatedAt: string;
+  completedAt?: string;
+}
+interface IntelligenceReportBudget {
+  maxUsd?: number;
+  billTo?: "customer" | "platform";
+}
+interface CreateIntelligenceReportOptions {
+  subject: {
+    type: IntelligenceReportSubjectType;
+    id: string;
+  };
+  mode?: "deterministic" | "agentic";
+  acknowledgeCost?: boolean;
+  budget?: IntelligenceReportBudget;
+  metadata?: Record<string, unknown>;
+}
+/**
+ * Options for event streaming.
+ */
+interface EventStreamOptions {
+  /** AbortSignal for cancellation */
+  signal?: AbortSignal;
+  /** Filter to specific event types */
+  eventTypes?: string[];
+}
+/**
+ * Provisioning step identifier for progress reporting.
+ */
+type ProvisionStep = "match" | "networking" | "git" | "host-select" | "storage" | "image-check" | "image-pull" | "image-build" | "container-create" | "container-start" | "health-check" | "runtime-ready" | "workspace";
+/**
+ * Status of a provisioning step.
+ */
+type ProvisionStatus = "started" | "progress" | "completed" | "skipped" | "error";
+/**
+ * Provisioning progress event emitted during sandbox creation.
+ *
+ * Subscribe via `box.watchProvisioning()` or pass `onProgress` to `box.waitFor()`.
+ *
+ * @example
+ * ```typescript
+ * for await (const event of box.watchProvisioning()) {
+ *   console.log(`[${event.step}] ${event.status} — ${event.message}`);
+ *   if (event.percent !== undefined) {
+ *     updateProgressBar(event.percent);
+ *   }
+ * }
+ * ```
+ */
+interface ProvisionEvent {
+  /** The provisioning step (e.g., "image-pull", "container-start") */
+  step: ProvisionStep;
+  /** Status of this step */
+  status: ProvisionStatus;
+  /** Human-readable progress message */
+  message?: string;
+  /** Overall progress percentage (0-100) */
+  percent?: number;
+  /** Additional detail for the step */
+  detail?: Record<string, unknown>;
+  /** ISO timestamp */
+  timestamp: string;
+}
+/**
+ * Terminal provisioning event indicating success or failure.
+ */
+type ProvisionResult = {
+  type: "complete";
+  containerId: string;
+  timestamp: string;
+} | {
+  type: "failed";
+  error: string;
+  timestamp: string;
+};
+/**
+ * Options for `waitFor()`.
+ */
+interface WaitForOptions {
+  /** Timeout in milliseconds (default: 120000) */
+  timeoutMs?: number;
+  /** Poll interval in milliseconds when SSE is unavailable (default: 2000) */
+  pollIntervalMs?: number;
+  /** AbortSignal for cancellation */
+  signal?: AbortSignal;
+  /**
+   * Callback invoked with real-time provisioning progress events.
+   * When provided and the sandbox is provisioning, `waitFor()` uses SSE
+   * instead of polling for faster, more granular updates.
+   */
+  onProgress?: (event: ProvisionEvent) => void;
+}
+/**
+ * Usage information for the account.
+ */
+interface UsageInfo {
+  /** Total compute minutes used today */
+  computeMinutes: number;
+  /** Number of currently active sandboxes */
+  activeSandboxes: number;
+  /** Total sandboxes created (lifetime) */
+  totalSandboxes: number;
+  /** Period start date (current day UTC) */
+  periodStart: Date;
+  /** Period end date (next day UTC) */
+  periodEnd: Date;
+}
+/**
+ * Subscription and billing information for the account.
+ */
+interface SubscriptionInfo {
+  /** Current plan tier */
+  plan: "free" | "pro" | "enterprise";
+  /** Subscription status */
+  status: "active" | "canceled" | "past_due";
+  /**
+   * Available credit balance in USD.
+   *
+   * **May be negative** for overage-enabled plans (pro/enterprise):
+   * overage charges can push the stored balance below zero. Free-tier
+   * plans floor at 0 at the charge path — free users top up their
+   * prepaid balance via Stripe Checkout (`POST /v1/billing/topup`,
+   * issue #874) when they hit zero rather than going into the red.
+   *
+   * Freshness semantics differ by deployment backend: the
+   * Cloudflare/D1 backend includes real-time projected cost of
+   * currently-running sandboxes; the Node/Redis backend returns the
+   * last-deducted stored balance and reflects running sandboxes only
+   * once their usage is recorded. Consumers should not assume this
+   * value is non-negative — use `>= 0` checks rather than truthiness.
+   */
+  creditsAvailableUsd: number;
+  /** Credits used in USD */
+  creditsUsedUsd: number;
+  /** Monthly included balance in USD */
+  monthlyBalanceUsd: number;
+  /** Max concurrent sandboxes (0 = unlimited) */
+  maxConcurrentSandboxes: number;
+  /** Whether overage billing is allowed */
+  overageAllowed: boolean;
+  /** Resource limits */
+  limits: {
+    maxCpuCores: number;
+    maxRamGB: number;
+    maxStorageGB: number;
+  };
+  /** Current billing period end (epoch ms) */
+  currentPeriodEnd: number;
+}
+/**
+ * S3-compatible storage provider configuration (BYOS3 - Bring Your Own S3).
+ *
+ * Allows customers to store snapshots in their own S3-compatible storage.
+ * Supports AWS S3, Google Cloud Storage (GCS), and Cloudflare R2.
+ *
+ * @example AWS S3
+ * ```typescript
+ * const storage: StorageConfig = {
+ *   type: "s3",
+ *   bucket: "my-snapshots",
+ *   region: "us-east-1",
+ *   credentials: {
+ *     accessKeyId: "AKIA...",
+ *     secretAccessKey: "...",
+ *   },
+ * };
+ * ```
+ *
+ * @example Cloudflare R2
+ * ```typescript
+ * const storage: StorageConfig = {
+ *   type: "r2",
+ *   bucket: "my-snapshots",
+ *   endpoint: "https://<account>.r2.cloudflarestorage.com",
+ *   credentials: {
+ *     accessKeyId: "...",
+ *     secretAccessKey: "...",
+ *   },
+ * };
+ * ```
+ *
+ * @example Google Cloud Storage
+ * ```typescript
+ * const storage: StorageConfig = {
+ *   type: "gcs",
+ *   bucket: "my-snapshots",
+ *   credentials: {
+ *     accessKeyId: "...",  // HMAC key
+ *     secretAccessKey: "...",
+ *   },
+ * };
+ * ```
+ */
+interface StorageConfig {
+  /** Storage provider type */
+  type: "s3" | "gcs" | "r2";
+  /** Bucket name */
+  bucket: string;
+  /** Custom endpoint URL (required for R2, optional for S3/GCS) */
+  endpoint?: string;
+  /** Region (e.g., us-east-1) */
+  region?: string;
+  /** Access credentials */
+  credentials: {
+    accessKeyId: string;
+    secretAccessKey: string;
+  };
+  /** Path prefix within bucket (default: sandbox-snapshots/) */
+  prefix?: string;
+}
+/**
+ * Options for running a multi-turn task.
+ */
+interface TaskOptions extends PromptOptions {
+  /** Maximum number of agent turns (default: 10, 0 = unlimited) */
+  maxTurns?: number;
+}
+/**
+ * Result of a multi-turn task execution.
+ */
+interface TaskResult extends PromptResult {
+  /** Number of agent turns used */
+  turnsUsed: number;
+  /** Session ID for the task (can be used to continue) */
+  sessionId: string;
+}
+/**
+ * Lifecycle state of an agent session inside a sandbox.
+ */
+type SessionStatus = "queued" | "running" | "completed" | "failed" | "cancelled";
+/**
+ * Snapshot of a session's state at the moment it was queried. Returned
+ * by `box.session(id).status()` and `box.sessions()`.
+ */
+interface SessionInfo {
+  /** Stable session id assigned by the sandbox runtime. */
+  id: string;
+  /** Current lifecycle state. */
+  status: SessionStatus;
+  /** Backend identifier (e.g. provider name). */
+  backend?: string;
+  /** Model id the session was created with. */
+  model?: string;
+  /** Number of prompts the session has processed. */
+  promptCount?: number;
+  /** When the session was created in the sandbox. */
+  createdAt?: Date;
+  /** When the session began executing. */
+  startedAt?: Date;
+  /** When the session reached a terminal state. */
+  endedAt?: Date;
+  /** Raw payload from the sidecar — stable subset above; this carries
+   * everything else for forward-compatibility. */
+  raw?: Record<string, unknown>;
+}
+/**
+ * Options for `box.sessions()` listing.
+ */
+interface SessionListOptions {
+  /** Filter by status. */
+  status?: SessionStatus;
+  /** Filter by backend identifier. */
+  backend?: string;
+}
+/**
+ * Options for `SandboxSession.events()` streaming.
+ */
+interface SessionEventStreamOptions {
+  /** Replay starting from this event id (inclusive). Omit to start at
+   * the live tail. Useful for reconnect-after-disconnect flows. */
+  since?: string;
+  /** Cancel the stream by aborting this signal. */
+  signal?: AbortSignal;
+}
+/**
+ * Options for `box.dispatchPrompt()` — fire-and-detach prompt semantics.
+ */
+interface DispatchPromptOptions extends PromptOptions {
+  /** Client-supplied session id for idempotency. Re-dispatching with
+   * the same id while the session is running is a lookup, not a
+   * re-create. Lets queue retries and reconnect-after-restart be safe
+   * by construction. */
+  sessionId?: string;
+}
+/**
+ * Returned by `box.dispatchPrompt()` — minimum the caller needs to track
+ * the session afterward. The sandbox keeps running the prompt; use
+ * `box.session(sessionId)` to follow it.
+ */
+interface DispatchedSession {
+  /** Session id (either the one the caller supplied or one the sandbox
+   * minted). */
+  sessionId: string;
+  /** Lifecycle state at the moment dispatch returned. */
+  status: SessionStatus;
+  /** True when an existing session with the supplied id was found and
+   * dispatch was a no-op (idempotency). */
+  alreadyExisted: boolean;
+}
+/**
+ * Scope of a `box.mintScopedToken()` request. Each value narrows the
+ * token's authority compared to the full sandbox bearer.
+ */
+type ScopedTokenScope = "session" | "project" | "read-only";
+/**
+ * Options for `box.mintScopedToken()`.
+ */
+interface MintScopedTokenOptions {
+  /** Scope to mint. `session` narrows to a single session id; `project`
+   * grants read access to the whole sandbox; `read-only` is a project
+   * scope without prompt-dispatch capabilities. */
+  scope: ScopedTokenScope;
+  /** Required when `scope === "session"`. */
+  sessionId?: string;
+  /** TTL in minutes. Default 5; clamped to [1, 15]. Browser-side
+   * bearers must be short-lived; pair with `client.onTokenRefresh()`
+   * for long-running consumers. */
+  ttlMinutes?: number;
+}
+/**
+ * Returned by `box.mintScopedToken()`. The token verifies against the
+ * same sidecar middleware that already gates ProductTokenIssuer-issued
+ * JWTs — no new sidecar surface.
+ */
+interface ScopedToken {
+  /** Bearer token (JWT). Send as `Authorization: Bearer <token>` or
+   * via the `EventSource` URL with token query param. */
+  token: string;
+  /** When the token expires. */
+  expiresAt: Date;
+  /** Echo of the requested scope. */
+  scope: ScopedTokenScope;
+}
+/**
+ * Callback invoked when the SDK refreshes a sandbox bearer transparently
+ * (e.g. after a 401 retry against the runtime endpoint). Lets long-
+ * running consumers propagate the new token to dependents (live
+ * `EventSource` connections, browser-side caches, etc.).
+ */
+type TokenRefreshHandler = (sandboxId: string, newToken: string) => void;
+/**
+ * Options for creating a snapshot.
+ */
+interface SnapshotOptions {
+  /** Tags to apply to the snapshot */
+  tags?: string[];
+  /** Specific paths to include (default: entire workspace) */
+  paths?: string[];
+  /** Customer-provided storage for BYOS3 (calls the runtime directly) */
+  storage?: StorageConfig;
+}
+/**
+ * Result of a snapshot operation.
+ */
+interface SnapshotResult {
+  /** Unique snapshot identifier */
+  snapshotId: string;
+  /** When the snapshot was created */
+  createdAt: Date;
+  /** Size in bytes */
+  sizeBytes?: number;
+  /** Tags applied to the snapshot */
+  tags: string[];
+}
+interface RestoreSnapshotOptions {
+  destinationPath?: string;
+  snapshotId?: string;
+}
+/**
+ * Metadata about an existing snapshot.
+ */
+interface SnapshotInfo {
+  /** Unique snapshot identifier */
+  snapshotId: string;
+  /** Sandbox this snapshot belongs to */
+  sandboxId: string;
+  /** When the snapshot was created */
+  createdAt: Date;
+  /** Tags applied to the snapshot */
+  tags: string[];
+  /** Paths included in the snapshot */
+  paths: string[];
+  /** Size in bytes */
+  sizeBytes?: number;
+}
+/**
+ * A single task in a batch execution.
+ */
+interface BatchTask {
+  /** Unique task identifier */
+  id: string;
+  /** Task prompt/message */
+  message: string;
+  /** Additional context for this task */
+  context?: Record<string, unknown>;
+  /** Per-task timeout in milliseconds */
+  timeoutMs?: number;
+}
+/**
+ * Options for batch execution.
+ */
+interface BatchOptions {
+  /** Timeout for entire batch in milliseconds (default: 300000 = 5 min) */
+  timeoutMs?: number;
+  /** Scaling mode: fastest, balanced, or cheapest (default: balanced) */
+  scalingMode?: "fastest" | "balanced" | "cheapest";
+  /**
+   * Shared backend override for the batch.
+   *
+   * Use `backend.profile` with a string for a named profile or a provider-neutral
+   * `AgentProfile` object for inline profile configuration.
+   */
+  backend?: Partial<BackendConfig>;
+  /** Keep sandboxes alive after completion (default: false) */
+  persistent?: boolean;
+  /** Milliseconds to keep non-persistent batch sandboxes alive after completion. */
+  graceMs?: number;
+  /**
+   * AbortSignal to cancel the batch mid-stream. When aborted, the HTTP
+   * request to `/batch/run` is torn down; the SSE generator stops
+   * yielding and `runBatch`/`streamBatch` reject with an `AbortError`.
+   *
+   * Note: the server-side batch may continue running to completion —
+   * the signal is strictly for disconnecting the client from the
+   * stream, not for halting server work.
+   */
+  signal?: AbortSignal;
+}
+/**
+ * Result of a single task in a batch.
+ */
+interface BatchTaskResult {
+  /** Task identifier */
+  taskId: string;
+  /** Whether the task succeeded */
+  success: boolean;
+  /** Task response if successful */
+  response?: string;
+  /** Error message if failed */
+  error?: string;
+  /** Duration in milliseconds */
+  durationMs: number;
+  /** Number of retries */
+  retries: number;
+  /** Token usage if available */
+  tokensUsed?: number;
+}
+/**
+ * Summary of batch execution.
+ */
+interface BatchResult {
+  /** Total tasks executed */
+  totalTasks: number;
+  /** Number of successful tasks */
+  succeeded: number;
+  /** Number of failed tasks */
+  failed: number;
+  /** Total retries across all tasks */
+  totalRetries: number;
+  /** Success rate (0-100) */
+  successRate: number;
+  /** 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;
+}
+/**
+ * Stable worker identifier inside a sandbox fleet.
+ *
+ * Machine IDs are intentionally narrower than sandbox names so agents
+ * can route work without smuggling shell metacharacters or path-like
+ * values through tool calls.
+ */
+type FleetMachineId = string;
+type SandboxFleetMachineRole = "coordinator" | "worker";
+/**
+ * Resource policy for a single fleet create call.
+ *
+ * These caps are enforced client-side before any sandbox is created.
+ * Server-side plan quotas still apply and remain the source of truth.
+ */
+interface SandboxFleetPolicy {
+  /** Maximum number of machines in this create call. Defaults to machines.length. */
+  maxMachines?: number;
+  /** Maximum sandbox create fanout allowed for this fleet request. */
+  maxConcurrentCreates?: number;
+  /** Maximum total requested CPU cores across machines with explicit resources. */
+  maxTotalCpu?: number;
+  /** Maximum total requested memory across machines with explicit resources. */
+  maxTotalMemoryMb?: number;
+  /** Maximum total requested storage across machines with explicit resources. */
+  maxTotalStorageMb?: number;
+  /** Maximum total requested accelerator devices across machines. */
+  maxTotalAccelerators?: number;
+  /** Maximum lifetime in seconds for any machine in this fleet. */
+  maxLifetimeSeconds?: number;
+  /** Maximum estimated USD spend for the fleet's configured lifetime. */
+  maxSpendUsd?: number;
+  /** Allowed infrastructure drivers for fleet machines. */
+  allowedDrivers?: DriverType[];
+  /** Allowed images/environments for fleet machines. */
+  allowedImages?: string[];
+  /** Allowed personal or public template identifiers for fleet machines. */
+  allowedTemplateIds?: string[];
+  /** Whether machines may request accelerator devices. Defaults to allowed. */
+  allowAccelerators?: boolean;
+}
+interface SandboxFleetWorkspace {
+  mode: "isolated" | "shared";
+  id?: string;
+  quotaMb?: number;
+  mountPath?: string;
+  snapshotId?: string;
+}
+/**
+ * Per-machine create spec for a sandbox fleet.
+ */
+interface SandboxFleetMachineSpec extends Omit<CreateSandboxOptions, "metadata" | "name"> {
+  /** Stable agent-facing machine id, e.g. "coordinator" or "worker-1". */
+  machineId: FleetMachineId;
+  /** Optional display name. Defaults to `${fleetId}-${machineId}`. */
+  name?: string;
+  /** Machine-specific metadata. Fleet tags are added automatically. */
+  metadata?: Record<string, unknown>;
+  /** Optional orchestration role. Defaults to worker. */
+  role?: SandboxFleetMachineRole;
+}
+/**
+ * Create a named set of sandboxes for one workload.
+ */
+interface CreateSandboxFleetOptions {
+  /** Stable fleet id. Generated when omitted. */
+  fleetId?: string;
+  /** Shared defaults applied to every machine before per-machine overrides. */
+  defaults?: Omit<CreateSandboxOptions, "metadata" | "name">;
+  /** Machines to create. */
+  machines: SandboxFleetMachineSpec[];
+  /** Fleet-level metadata copied to each sandbox under stable tags. */
+  metadata?: Record<string, unknown>;
+  /** Workspace policy for isolated or driver-supported shared mounts. */
+  workspace?: SandboxFleetWorkspace;
+  /**
+   * Client-side safety caps for this create call. These do not replace
+   * server-side quota enforcement.
+   */
+  policy?: SandboxFleetPolicy;
+  /**
+   * Delete already-created machines if a later machine fails to create.
+   * Defaults to true so partial fleets do not silently burn quota.
+   */
+  cleanupOnFailure?: boolean;
+  /**
+   * Maximum concurrent sandbox creates for this fleet request.
+   * Defaults to 4 to avoid accidental control-plane stampedes while still
+   * provisioning worker fleets faster than serial creation.
+   */
+  maxConcurrentCreates?: number;
+  /**
+   * Idempotency key for the server-backed fleet record. Defaults to fleetId.
+   */
+  idempotencyKey?: string;
+}
+interface CreateSandboxFleetWithCoordinatorOptions extends Omit<CreateSandboxFleetOptions, "machines"> {
+  /** Coordinator machine. Defaults to machineId "coordinator". */
+  coordinator?: Omit<SandboxFleetMachineSpec, "machineId" | "role"> & {
+    machineId?: FleetMachineId;
+  };
+  /** Worker machines attached to the same fleet. */
+  workers: SandboxFleetMachineSpec[];
+}
+/**
+ * A sandbox with its fleet-local machine id.
+ */
+interface SandboxFleetMachine {
+  machineId: FleetMachineId;
+  sandbox: SandboxInfo;
+  role?: SandboxFleetMachineRole;
+}
+/**
+ * Fleet create/list result.
+ */
+interface SandboxFleetInfo {
+  fleetId: string;
+  machines: SandboxFleetMachine[];
+}
+interface FleetExecDispatchOptions extends Pick<ExecOptions, "cwd" | "env" | "timeoutMs"> {
+  machines?: FleetMachineId[];
+  maxConcurrent?: number;
+  retry?: {
+    attempts?: number;
+  };
+  /** Caller-supplied dispatch id for idempotency/result lookup when supported by the API. */
+  dispatchId?: string;
+  /** Ask the API to retain branch results for later `dispatchResults` calls. */
+  bufferResults?: boolean;
+}
+interface FleetExecDispatchResult {
+  machineId: FleetMachineId;
+  sandboxId: string;
+  ok: boolean;
+  durationMs: number;
+  attempts?: number;
+  result?: ExecResult;
+  error?: {
+    message: string;
+    status?: number;
+    failureClass?: SandboxFleetDispatchFailureClass;
+  };
+}
+interface FleetPromptDispatchOptions extends Pick<PromptOptions, "sessionId" | "model" | "backend" | "timeoutMs" | "context"> {
+  machines?: FleetMachineId[];
+  maxConcurrent?: number;
+  retry?: {
+    attempts?: number;
+  };
+  /** Caller-supplied dispatch id for idempotency/result lookup when supported by the API. */
+  dispatchId?: string;
+  /** Ask the API to retain branch results for later `dispatchResults` calls. */
+  bufferResults?: boolean;
+}
+interface FleetPromptDispatchResult {
+  machineId: FleetMachineId;
+  sandboxId: string;
+  ok: boolean;
+  durationMs: number;
+  attempts?: number;
+  prompt?: PromptResult & {
+    metadata?: Record<string, unknown>;
+  };
+  error?: {
+    message: string;
+    status?: number;
+    failureClass?: SandboxFleetDispatchFailureClass;
+  };
+}
+type SandboxFleetDispatchFailureClass = "oom" | "timeout" | "dependency" | "infra" | "model" | "user_code";
+interface FleetDispatchStreamOptions {
+  signal?: AbortSignal;
+}
+interface FleetDispatchResultBufferOptions {
+  cursor?: string;
+  limit?: number;
+  machines?: FleetMachineId[];
+}
+interface FleetDispatchResultBuffer<T = FleetExecDispatchResult | FleetPromptDispatchResult> {
+  fleetId: string;
+  dispatchId: string;
+  results: T[];
+  cursor?: string;
+  nextCursor?: string;
+  done?: boolean;
+  truncated?: boolean;
+  trace?: SandboxFleetTraceExport;
+  intelligence?: SandboxFleetIntelligenceEnvelope;
+}
+interface FleetDispatchCancelResult {
+  fleetId: string;
+  dispatchId: string;
+  cancelled: boolean;
+  status?: string;
+}
+interface SandboxFleetArtifactSpec {
+  machineId: FleetMachineId;
+  /**
+   * Absolute path under /workspace. Fleet artifact collection intentionally
+   * rejects host/system paths so caller-provided manifests cannot turn artifact
+   * collection into arbitrary sandbox file reads.
+   */
+  path: string;
+  label?: string;
+  /** Maximum allowed artifact content size in bytes. Defaults to 5 MiB. */
+  maxBytes?: number;
+}
+interface SandboxFleetArtifact extends SandboxFleetArtifactSpec {
+  sandboxId: string;
+  content: string;
+}
+interface SandboxFleetDriverTimings {
+  queueMs?: number;
+  placementMs?: number;
+  provisionMs?: number;
+  startupMs?: number;
+  cleanupMs?: number;
+}
+interface SandboxFleetMachineMeteredUsage {
+  runtimeMs: number;
+  updatedAt: string;
+}
+interface AttachSandboxFleetMachineOptions {
+  machineId: FleetMachineId;
+  sandboxId: string;
+  status?: string;
+  role?: SandboxFleetMachineRole;
+  driverType?: DriverType;
+  image?: string;
+  environment?: string;
+  templateId?: string;
+  publicTemplateId?: string;
+  acceleratorCount?: number;
+  driverTimings?: SandboxFleetDriverTimings;
+}
+interface SandboxFleetMachineRecord extends AttachSandboxFleetMachineOptions {
+  workspaceMountPath?: string;
+  meteredUsage?: SandboxFleetMachineMeteredUsage;
+  createdAt?: string;
+  updatedAt?: string;
+}
+interface SandboxFleetManifestMachine {
+  machineId: FleetMachineId;
+  sandboxId: string;
+  role?: SandboxFleetMachineRole;
+  status?: string;
+  driverType?: DriverType;
+  image?: string;
+  environment?: string;
+  templateId?: string;
+  publicTemplateId?: string;
+  acceleratorCount?: number;
+  workspaceMountPath?: string;
+  driverTimings?: SandboxFleetDriverTimings;
+  meteredUsage?: SandboxFleetMachineMeteredUsage;
+  createdAt?: string;
+  updatedAt?: string;
+}
+interface SandboxFleetManifest {
+  fleetId?: string;
+  id?: string;
+  metadata?: Record<string, unknown>;
+  policy?: SandboxFleetPolicy;
+  resources?: Record<string, unknown>;
+  workspace?: SandboxFleetWorkspace & {
+    status?: string;
+    createdAt?: string;
+    updatedAt?: string;
+    deletedAt?: string;
+  };
+  machines: SandboxFleetManifestMachine[];
+  createdAt?: string;
+  updatedAt?: string;
+}
+interface SandboxFleetDispatchResponse<T = FleetExecDispatchResult | FleetPromptDispatchResult> {
+  fleetId: string;
+  dispatchId: string;
+  type: "exec" | "prompt";
+  results: T[];
+  durationMs: number;
+  trace?: SandboxFleetTraceExport;
+  intelligence?: SandboxFleetIntelligenceEnvelope;
+}
+interface SandboxFleetWorkspaceSnapshotResult {
+  snapshotId?: string;
+  id?: string;
+  status?: string;
+  createdAt?: string;
+  [key: string]: JsonValue | undefined;
+}
+interface SandboxFleetWorkspaceRestoreResult {
+  restored?: boolean;
+  snapshotId?: string;
+  status?: string;
+  [key: string]: JsonValue | undefined;
+}
+interface SandboxFleetWorkspaceReconcileResult {
+  fleetId: string;
+  workspaceId?: string;
+  checked: number;
+  orphanedMounts: number;
+  machines: Array<{
+    machineId: string;
+    sandboxId: string;
+    mounted: boolean;
+  }>;
+}
+interface SandboxFleetDriverCapability {
+  driverType: DriverType;
+  sharedWorkspace: boolean;
+  accelerators: boolean;
+  queueTimings: boolean;
+}
+interface SandboxFleetOperationsSummary {
+  capacity: {
+    fleets: number;
+    machines: number;
+    runningMachines: number;
+    failedMachines: number;
+    requestedCpu: number;
+    requestedMemoryMb: number;
+    requestedStorageMb: number;
+    requestedAccelerators: number;
+  };
+  alerts: Array<{
+    name: string;
+    severity: "info" | "warn" | "critical";
+    fleetId?: string;
+    machineId?: string;
+    message: string;
+    runbook: string[];
+  }>;
+}
+interface ReconcileSandboxFleetsOptions {
+  dryRun?: boolean;
+}
+interface ReconcileSandboxFleetsResult {
+  dryRun: boolean;
+  checked: number;
+  orphaned: number;
+  removed: number;
+  machines: Array<{
+    fleetId: string;
+    machineId: string;
+    sandboxId: string;
+    removed: boolean;
+    status?: number;
+    error?: string;
+  }>;
+}
+interface SandboxFleetUsage {
+  usage: {
+    fleetId: string;
+    status: string;
+    machineCount: number;
+    coordinatorCount: number;
+    workerCount: number;
+    runningMachines: number;
+    failedMachines: number;
+    resources?: {
+      machines: number;
+      totalCpu: number;
+      totalMemoryMb: number;
+      totalStorageMb: number;
+      totalAccelerators: number;
+      maxLifetimeSeconds?: number;
+    };
+    meteredUsage?: {
+      runtimeMs: number;
+      machineRuntimeMs: Record<string, number>;
+      updatedAt: string;
+    };
+    createdAt: string;
+    updatedAt: string;
+  };
+  insights: {
+    reliabilityScore: number;
+    parallelismEfficiencyScore: number;
+    failureRate: number;
+    recommendedActions: string[];
+  };
+  trace: SandboxFleetTraceExport;
+  intelligence: SandboxFleetIntelligenceEnvelope;
+}
+interface SandboxFleetTraceEvent {
+  type: "fleet.lifecycle.snapshot" | "fleet.machine.lifecycle.snapshot" | "fleet.workspace.lifecycle.snapshot" | "fleet.usage.snapshot" | "fleet.dispatch.result" | "fleet.insight.summary";
+  timestamp: string;
+  fleetId: string;
+  machineId?: string;
+  durationMs?: number;
+  attributes: Record<string, unknown>;
+}
+interface SandboxFleetTraceExport {
+  schemaVersion: "fleet.trace.v1";
+  traceId: string;
+  fleetId: string;
+  exportedAt: string;
+  timings: {
+    observedLifecycleMs: number;
+    machineObservedLifecycleMs: number;
+    dispatchFanoutMs: number;
+    dispatchRuntimeMs: number;
+    cleanupObservedMs: number;
+    driverQueueMs: number;
+    driverPlacementMs: number;
+    driverProvisionMs: number;
+    driverStartupMs: number;
+    driverCleanupMs: number;
+  };
+  criticalPath: {
+    durationMs: number;
+    phases: Array<{
+      name: string;
+      durationMs: number;
+      machineId?: string;
+    }>;
+  };
+  events: SandboxFleetTraceEvent[];
+}
+interface SandboxFleetIntelligenceEnvelope {
+  schemaVersion: "fleet.intelligence.v1";
+  source: "sandbox-api";
+  subject: {
+    type: "sandbox_fleet";
+    fleetId: string;
+  };
+  billing: {
+    billable: false;
+    billedTo: "platform";
+    costUsd: 0;
+    reason: "deterministic_platform_insight";
+  };
+  metrics: Record<string, number>;
+  signals: Array<{
+    name: string;
+    value: string | number | boolean;
+    severity: "info" | "warn" | "critical";
+    rationale: string;
+  }>;
+  recommendedActions: string[];
+}
+interface SandboxFleetTraceBundle {
+  trace: SandboxFleetTraceExport;
+  intelligence?: SandboxFleetIntelligenceEnvelope;
+}
+interface SandboxFleetTraceOptions {
+  /**
+   * Include the platform-generated intelligence envelope. Defaults to false.
+   * Set true when a customer wants generated insight with the raw trace export.
+   */
+  includeIntelligence?: boolean;
+}
+interface SandboxFleetCostEstimate {
+  plan: "free" | "pro" | "enterprise";
+  currency: "USD";
+  hourlyUsd: number;
+  maxLifetimeSeconds: number;
+  estimatedMaxLifetimeUsd: number;
+  requestedResources: {
+    machines: number;
+    totalCpu: number;
+    totalMemoryMb: number;
+    totalStorageMb: number;
+    totalAccelerators: number;
+    maxLifetimeSeconds?: number;
+  };
+  rates: {
+    cpuPerHr: number;
+    ramPerGbHr: number;
+    diskPerGbHr: number;
+    acceleratorPerDeviceHr: number;
+    minChargePerHr: number;
+    entDiscount: number;
+  };
+}
+type SandboxFleetTokenAction = "list" | "create" | "delete" | "exec" | "prompt" | "read" | "write";
+interface CreateSandboxFleetTokenOptions {
+  /** Allowed fleet actions. Defaults to read/list/exec. */
+  actions?: SandboxFleetTokenAction[];
+  /** Optional token-side policy caps enforced by the Sandbox API. */
+  policy?: SandboxFleetPolicy;
+  /** Token lifetime in minutes. API clamps to its server-side maximum. */
+  ttlMinutes?: number;
+}
+interface SandboxFleetToken {
+  token: string;
+  expiresAt: number;
+  fleetId: string;
+  actions: SandboxFleetTokenAction[];
+  policy?: SandboxFleetPolicy;
+}
+interface ReapExpiredSandboxFleetsOptions {
+  dryRun?: boolean;
+}
+interface ReapExpiredSandboxFleetsResult {
+  dryRun: boolean;
+  expired: number;
+  deleted: number;
+  fleets: Array<{
+    fleetId: string;
+    expiredAt: string;
+    deleted: boolean;
+    machines: Array<{
+      machineId: string;
+      sandboxId: string;
+      ok: boolean;
+      status?: number;
+      error?: string;
+    }>;
+  }>;
+}
+/**
+ * Options for listing fleet machines.
+ */
+interface ListSandboxFleetOptions extends ListSandboxOptions {
+  /** Fleet id to filter by. */
+  fleetId: string;
+}
+/**
+ * Options for creating a checkpoint.
+ */
+interface CheckpointOptions {
+  /** Tags to apply to the checkpoint */
+  tags?: string[];
+  /** Keep sandbox running after checkpoint (default: false - sandbox stops) */
+  leaveRunning?: boolean;
+  /** Also create a filesystem snapshot for data consistency */
+  includeSnapshot?: boolean;
+}
+/**
+ * Result of a checkpoint operation.
+ */
+interface CheckpointResult {
+  /** Unique checkpoint identifier */
+  checkpointId: string;
+  /** When the checkpoint was created */
+  createdAt: Date;
+  /** Size of checkpoint in bytes (memory state) */
+  sizeBytes?: number;
+  /** Tags applied to the checkpoint */
+  tags: string[];
+}
+/**
+ * Information about an existing checkpoint.
+ */
+interface CheckpointInfo {
+  /** Unique checkpoint identifier */
+  checkpointId: string;
+  /** Sandbox this checkpoint belongs to */
+  sandboxId: string;
+  /** When the checkpoint was created */
+  createdAt: Date;
+  /** Tags applied to the checkpoint */
+  tags: string[];
+  /** Size of checkpoint in bytes */
+  sizeBytes?: number;
+  /** Whether checkpoint includes memory state */
+  hasMemoryState: boolean;
+  /** Whether checkpoint includes filesystem snapshot */
+  hasFilesystemSnapshot: boolean;
+}
+/**
+ * Options for forking a sandbox from a checkpoint.
+ */
+interface ForkOptions {
+  /** Name for the forked sandbox */
+  name?: string;
+  /** Override environment variables in the fork */
+  env?: Record<string, string>;
+  /** Override resource limits in the fork */
+  resources?: SandboxResources;
+  /** Custom metadata for the fork */
+  metadata?: Record<string, unknown>;
+}
+/**
+ * Result of a fork operation.
+ */
+interface ForkResult {
+  /** The newly created sandbox instance */
+  sandbox: SandboxInfo;
+  /** The checkpoint that was forked from */
+  sourceCheckpoint: CheckpointInfo;
+  /** ID of the source sandbox */
+  sourceId: string;
+  /** Time taken to fork in milliseconds */
+  forkTimeMs: number;
+}
+/**
+ * Infrastructure driver identifier.
+ *
+ * Most callers should omit `driver` and let the platform select automatically.
+ */
+type DriverType = "docker" | "firecracker" | "host-agent" | "tangle";
+/**
+ * Accelerator class for GPU-class workloads.
+ *
+ * Examples: `nvidia-h100`, `nvidia-l4`, `nvidia-rtx-4090`, `amd-mi300x`.
+ * Providers can introduce new SKU labels without requiring an SDK release.
+ */
+type AcceleratorKind = string;
+/**
+ * Compute accelerator request.
+ *
+ * Accelerators are requested as resources because they are part of workload
+ * shape and billing, not a driver option.
+ */
+interface SandboxAccelerator {
+  /** Accelerator class required by the workload. */
+  kind: AcceleratorKind;
+  /**
+   * Number of accelerator devices required.
+   * @default 1
+   */
+  count?: number;
+  /** Minimum device memory in megabytes when the exact GPU class is flexible. */
+  memoryMB?: number;
+}
+/**
+ * Infrastructure driver configuration.
+ *
+ * @example Default
+ * ```typescript
+ * driver: { type: "docker" }
+ * ```
+ *
+ * @example With pause/resume support
+ * ```typescript
+ * driver: { type: "firecracker", enableCriu: true }
+ * ```
+ *
+ * @example Accelerator-backed sandbox
+ * ```typescript
+ * resources: {
+ *   accelerator: { kind: "nvidia-a100", count: 1 },
+ * }
+ * ```
+ */
+interface DriverConfig {
+  /**
+   * Driver type identifier.
+   * @default "docker"
+   */
+  type: DriverType;
+  /**
+   * Enable checkpointing for pause/resume and fork operations.
+   * Support depends on the selected driver.
+   */
+  enableCriu?: boolean;
+  /**
+   * Preferred placement region.
+   * e.g., "us-east-1", "eu-west-1".
+   */
+  preferredRegion?: string;
+  /**
+   * @deprecated Use `resources.accelerator` on sandbox or fleet machine specs.
+   */
+  gpuRequired?: boolean;
+  /**
+   * @deprecated Use `resources.accelerator.kind`.
+   */
+  gpuType?: GpuType;
+  /**
+   * @deprecated Use `resources.accelerator.count`.
+   */
+  gpuCount?: number;
+}
+/**
+ * Driver capabilities and status.
+ */
+interface DriverInfo {
+  /** Driver type */
+  type: DriverType;
+  /** Whether driver is available */
+  available: boolean;
+  /** Driver version string */
+  version: string;
+  /** Driver capabilities */
+  capabilities: {
+    /** Checkpoint/restore support */criu: boolean; /** GPU support */
+    gpu: boolean; /** Filesystem snapshots */
+    snapshots: boolean; /** Multi-user management */
+    userManagement: boolean; /** Network isolation */
+    networkIsolation: boolean;
+  };
+  /** Current capacity */
+  capacity?: {
+    available: number;
+    total: number;
+  };
+  acceleratorCapacity?: {
+    available: number;
+    total: number;
+    kinds: AcceleratorKind[];
+  };
+}
+/**
+ * Backend type identifier. Controls which AI agent runtime runs inside the sandbox.
+ *
+ * The public-SDK source of truth. Kept in lock-step with the private
+ * `@tangle-network/cli-agent-registry` spec list via the parity check in
+ * `packages/cli-agent-registry/tests/specs.test.ts` (adding a new CLI spec
+ * without updating this union surfaces as a test failure at PR review
+ * time). Inlined here so the published SDK doesn't carry an unpublished
+ * internal package as a runtime dep.
+ *
+ * - `"opencode"` — Default. Multi-provider, profile system, MCP support.
+ * - `"claude-code"` — Anthropic Claude Code CLI. Requires an Anthropic API key.
+ * - `"kimi-code"` — Moonshot Kimi Code CLI. Uses the operator's Kimi Code
+ *   subscription OAuth (shipped via authFiles) by default; falls back to
+ *   `MOONSHOT_API_KEY` when an apiKey is supplied.
+ * - `"codex"` — OpenAI Codex CLI. Requires an OpenAI API key.
+ * - `"amp"` — Sourcegraph AMP agent.
+ * - `"factory-droids"` — Factory Droid agent.
+ * - `"pi"` — Pi coding-agent CLI.
+ * - `"hermes"` — Hermes inference-router agent.
+ * - `"forge"` — Forge (forgecode.dev, tailcallhq) multi-provider coding agent.
+ * - `"openclaw"` — OpenClaw dispatcher that routes to claude-cli/codex-cli/gemini-cli.
+ * - `"acp"` — Agent Client Protocol bridge — fronts any ACP-compliant
+ *   agent binary (claude-agent-acp, codex-acp, gemini, openclaw acp).
+ *   Pick the backing agent via config.subAgent.
+ * - `"cursor"` — Cursor Agent SDK local/cloud backend.
+ * - `"cli-base"` — Minimal CLI-only (no AI agent).
+ */
+type BackendType = "opencode" | "claude-code" | "kimi-code" | "codex" | "amp" | "factory-droids" | "pi" | "hermes" | "forge" | "openclaw" | "acp" | "cursor" | "cli-base";
+/**
+ * MCP (Model Context Protocol) server configuration.
+ */
+interface McpServerConfig {
+  /** Command to run (e.g., "npx", "node") */
+  command: string;
+  /** Command arguments */
+  args?: string[];
+  /** Environment variables */
+  env?: Record<string, string>;
+  /** Working directory */
+  cwd?: string;
+  /** Remote URL (for remote MCP servers via SSE) */
+  url?: string;
+  /** Headers for remote connections */
+  headers?: Record<string, string>;
+}
+/**
+ * AI coding agent backend configuration.
+ *
+ * @example OpenCode with default settings
+ * ```typescript
+ * backend: { type: "opencode" }
+ * ```
+ *
+ * @example OpenCode with named profile
+ * ```typescript
+ * backend: {
+ *   type: "opencode",
+ *   profile: "with-web-search",
+ * }
+ * ```
+ *
+ * @example Claude Code with BYOK
+ * ```typescript
+ * backend: {
+ *   type: "claude-code",
+ *   model: {
+ *     provider: "anthropic",
+ *     model: "claude-sonnet-4-20250514",
+ *     apiKey: process.env.ANTHROPIC_API_KEY,
+ *   }
+ * }
+ * ```
+ */
+interface BackendConfig {
+  /**
+   * Backend type identifier.
+   * @default "opencode"
+   */
+  type: BackendType;
+  /**
+   * Backend profile selection.
+   *
+   * Use a string for a named provider/backend profile, or an `AgentProfile`
+   * object for an inline provider-neutral profile definition.
+   */
+  profile?: string | AgentProfile;
+  /**
+   * Model configuration override.
+   */
+  model?: {
+    /** Provider name (e.g., "anthropic", "openai", "google") */provider?: string; /** Model identifier (e.g., "claude-sonnet-4-20250514") */
+    model?: string; /** BYOK (Bring Your Own Key) API key */
+    apiKey?: string; /** Custom API base URL (for proxies or on-prem) */
+    baseUrl?: string; /** Maximum thinking tokens for extended reasoning */
+    maxThinkingTokens?: number; /** API mode: "api" for direct calls, "cli" for CLI wrapper */
+    mode?: "api" | "cli"; /** Authentication mode for CLI-native backends */
+    authMode?: "api-key" | "oauth"; /** Auth files to write into the sandbox home directory before CLI startup */
+    authFiles?: Array<{
+      path: string;
+      content: string;
+      mode?: number;
+    }>;
+  };
+  /**
+   * Backend server configuration.
+   */
+  server?: {
+    /** Server port (auto-assigned if not specified) */port?: number; /** Server hostname */
+    hostname?: string;
+  };
+}
+/**
+ * Backend capabilities.
+ */
+interface BackendCapabilities {
+  /** Supports streaming responses */
+  streaming: boolean;
+  /** Supports tool/function use */
+  toolUse: boolean;
+  /** Supports extended thinking/reasoning */
+  reasoning: boolean;
+  /** Supports multimodal (images, etc) */
+  multimodal: boolean;
+  /** Context window size in tokens */
+  contextWindow: number;
+  /** Support details for provider-neutral `AgentProfile` values */
+  profile?: AgentProfileCapabilities;
+}
+/**
+ * Backend status information.
+ */
+interface BackendStatus {
+  /** Backend type */
+  type: BackendType;
+  /** Current status */
+  status: "running" | "stopped" | "starting" | "stopping" | "unknown";
+  /** Backend version */
+  version?: string;
+  /** Error message if failed */
+  error?: string;
+  /** Additional metadata */
+  metadata?: Record<string, unknown>;
+}
+/**
+ * Backend information.
+ */
+interface BackendInfo {
+  /** Backend type */
+  type: BackendType;
+  /** Whether backend is available */
+  available: boolean;
+  /** Backend capabilities */
+  capabilities: BackendCapabilities;
+  /** Available profiles (for opencode) */
+  profiles?: Array<{
+    name: string;
+    description?: string;
+    tags?: string[];
+  }>;
+}
+interface BackendListOptions {
+  limit?: number;
+  cursor?: string;
+}
+interface BackendListResult<TItem> {
+  items: TItem[];
+  nextCursor?: string;
+}
+interface BackendAccount {
+  apiKeyName?: string;
+  userId?: number;
+  userEmail?: string;
+  userFirstName?: string;
+  userLastName?: string;
+  createdAt?: string;
+  metadata?: Record<string, unknown>;
+}
+interface BackendModel {
+  id: string;
+  displayName?: string;
+  description?: string;
+  parameters?: Array<Record<string, unknown>>;
+  variants?: Array<Record<string, unknown>>;
+}
+interface BackendRepository {
+  url: string;
+}
+interface BackendAgent {
+  agentId: string;
+  name?: string;
+  summary?: string;
+  lastModified?: number;
+  status?: "running" | "finished" | "error";
+  createdAt?: number;
+  archived?: boolean;
+  runtime?: "local" | "cloud";
+  cwd?: string;
+  env?: Record<string, unknown>;
+  repos?: string[];
+}
+interface BackendRun {
+  id: string;
+  agentId?: string;
+  status?: "running" | "finished" | "cancelled" | "error";
+  result?: string;
+  durationMs?: number;
+  model?: Record<string, unknown>;
+  git?: Record<string, unknown>;
+}
+interface BackendArtifact {
+  path: string;
+  sizeBytes?: number;
+  updatedAt?: string;
+}
+/**
+ * Network configuration for sandbox network isolation.
+ *
+ * Supports two modes:
+ * - `blockOutbound: true` - Block all egress traffic (ports still work for inbound)
+ * - `allowList: ["cidr", ...]` - Allow only specific destinations
+ *
+ * These modes are mutually exclusive.
+ *
+ * @example Block all outbound traffic
+ * ```typescript
+ * const box = await client.create({
+ *   network: { blockOutbound: true }
+ * });
+ * ```
+ *
+ * @example Allow only specific destinations
+ * ```typescript
+ * const box = await client.create({
+ *   network: {
+ *     allowList: [
+ *       "8.8.8.8/32",      // Google DNS
+ *       "10.0.0.0/8",      // Private network
+ *     ]
+ *   }
+ * });
+ * ```
+ *
+ * @example Pre-expose ports at creation
+ * ```typescript
+ * const box = await client.create({
+ *   network: {
+ *     blockOutbound: true,
+ *     ports: [8000, 8080], // Pre-expose these ports
+ *   }
+ * });
+ * ```
+ */
+interface NetworkConfig {
+  /**
+   * Block all outbound network traffic.
+   * Exposed ports still work for inbound connections.
+   * Mutually exclusive with `allowList`.
+   */
+  blockOutbound?: boolean;
+  /**
+   * CIDR allowlist for outbound traffic.
+   * Only traffic to these destinations is allowed.
+   * Maximum 10 entries. Mutually exclusive with `blockOutbound`.
+   *
+   * Supports both IPv4 and IPv6 CIDR notation:
+   * - "8.8.8.8/32" - Single IPv4 address
+   * - "10.0.0.0/8" - IPv4 subnet
+   * - "2001:db8::/32" - IPv6 subnet
+   */
+  allowList?: string[];
+  /**
+   * Ports to expose at creation time.
+   * These ports will be accessible regardless of network restrictions.
+   */
+  ports?: number[];
+}
+/**
+ * Network manager for runtime network configuration.
+ * Access via `sandbox.network`.
+ *
+ * @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"]
+ * });
+ *
+ * // Remove restrictions
+ * await box.network.update({ blockOutbound: false });
+ * ```
+ *
+ * @example Expose ports dynamically
+ * ```typescript
+ * const url = await box.network.exposePort(8000);
+ * console.log(`Service available at: ${url}`);
+ *
+ * const allUrls = await box.network.listUrls();
+ * ```
+ */
+interface NetworkManager {
+  /**
+   * Update network permissions at runtime.
+   * Changes apply immediately without container restart.
+   *
+   * @param config - Partial network configuration to apply
+   * @throws Error if blockOutbound and allowList are both specified
+   * @throws Error if allowList exceeds 10 entries
+   * @throws Error if CIDR format is invalid
+   */
+  update(config: Partial<NetworkConfig>): Promise<void>;
+  /**
+   * Expose a port dynamically.
+   * Returns a publicly accessible URL for the port.
+   * Works regardless of network restrictions.
+   *
+   * @param port - Port number to expose (1-65535)
+   * @returns Public URL for accessing the exposed port
+   */
+  exposePort(port: number): Promise<string>;
+  /**
+   * List all exposed port URLs.
+   *
+   * @returns Map of port numbers to their public URLs
+   */
+  listUrls(): Promise<Record<number, string>>;
+  /**
+   * Get current network configuration.
+   *
+   * @returns Current network config including any runtime changes
+   */
+  getConfig(): Promise<NetworkConfig>;
+}
+interface PreviewLinkInfo {
+  previewId: string;
+  sandboxId: string;
+  port: number;
+  protocol: "tcp" | "udp";
+  hostname: string;
+  url: string;
+  status: "provisioning" | "ready" | "error" | "disabled";
+  lastSyncAt: string;
+  createdAt: string;
+  updatedAt: string;
+  metadata?: Record<string, unknown>;
+}
+/**
+ * Preview link management.
+ *
+ * Create publicly accessible HTTPS URLs for TCP ports inside the sandbox.
+ *
+ * @example
+ * ```typescript
+ * // Expose a dev server
+ * const link = await box.previewLinks.create(3000);
+ * console.log(link.url);
+ *
+ * // List all preview links
+ * const links = await box.previewLinks.list();
+ *
+ * // Remove a preview link
+ * await box.previewLinks.remove(link.previewId);
+ * ```
+ */
+interface PreviewLinkManager {
+  /**
+   * Create a preview link for a port.
+   * Returns the preview link with its public URL.
+   * If a link already exists for this port, returns the existing one.
+   *
+   * @param port - Port number to expose (1-65535)
+   * @param options - Optional protocol and metadata
+   */
+  create(port: number, options?: {
+    protocol?: "tcp" | "udp";
+    metadata?: Record<string, unknown>;
+  }): Promise<PreviewLinkInfo>;
+  /**
+   * List all preview links for this sandbox.
+   */
+  list(): Promise<PreviewLinkInfo[]>;
+  /**
+   * Remove a preview link by ID.
+   *
+   * @param previewId - The preview link ID to remove
+   */
+  remove(previewId: string): Promise<void>;
+}
+/**
+ * Permission level for sandbox users.
+ *
+ * - `owner` — Full access, can manage users.
+ * - `admin` — Read/write workspace, can manage users.
+ * - `developer` — Read/write workspace.
+ * - `viewer` — Read-only workspace.
+ */
+type PermissionLevel = "owner" | "admin" | "developer" | "viewer";
+/**
+ * Directory-level permission override.
+ */
+interface DirectoryPermission {
+  /** Directory path (absolute, e.g. "/workspace/shared") */
+  path: string;
+  /** Read access */
+  read: boolean;
+  /** Write access */
+  write: boolean;
+  /** Execute/traverse access */
+  execute: boolean;
+}
+/**
+ * Glob-based access policy rule.
+ *
+ * @example Block all .env files
+ * ```typescript
+ * { pattern: "*.env", permission: "none" }
+ * ```
+ *
+ * @example Read-only secrets directory
+ * ```typescript
+ * { pattern: "/secrets/**", permission: "read" }
+ * ```
+ */
+interface AccessPolicyRule {
+  /** Glob pattern for matching (e.g., "*.env", "/secrets/**") */
+  pattern: string;
+  /** Access level for matching paths */
+  permission: "read" | "write" | "none";
+  /** Priority when patterns overlap (higher wins) */
+  priority?: number;
+}
+/**
+ * User in a sandbox.
+ */
+interface SandboxUser {
+  /** Unique user ID (from auth system) */
+  userId: string;
+  /** Username inside sandbox (Unix username) */
+  username: string;
+  /** Home directory path */
+  homeDir: string;
+  /** Permission level */
+  role: PermissionLevel;
+  /** SSH public keys */
+  sshKeys: string[];
+  /** Directory permission overrides */
+  directoryPermissions?: DirectoryPermission[];
+  /** Access policy rules */
+  accessPolicies?: AccessPolicyRule[];
+  /** When user was added */
+  createdAt: Date;
+}
+/**
+ * Options for adding a user to a sandbox.
+ */
+interface AddUserOptions {
+  /** Unique user ID (from your auth system) */
+  userId: string;
+  /** Preferred username (will be sanitized for Unix) */
+  username?: string;
+  /** Permission level (default: developer) */
+  role?: PermissionLevel;
+  /** SSH public keys for remote access */
+  sshKeys?: string[];
+  /** Custom directory permissions */
+  directoryPermissions?: DirectoryPermission[];
+}
+/**
+ * Options for updating a user.
+ */
+interface UpdateUserOptions {
+  /** New permission level */
+  role?: PermissionLevel;
+  /** SSH keys to add */
+  addSshKeys?: string[];
+  /** SSH keys to remove */
+  removeSshKeys?: string[];
+  /** Directory permissions to add/update */
+  directoryPermissions?: DirectoryPermission[];
+}
+/**
+ * Initial permissions configuration for sandbox creation.
+ */
+interface SandboxPermissionsConfig {
+  /**
+   * Default role for invited users.
+   * @default "developer"
+   */
+  defaultRole?: PermissionLevel;
+  /**
+   * Users to invite at creation time.
+   * Owner is automatically added from the API key.
+   */
+  initialUsers?: Array<{
+    userId: string;
+    role?: PermissionLevel;
+    sshKeys?: string[];
+  }>;
+  /**
+   * Default access policies for all users.
+   */
+  defaultPolicies?: AccessPolicyRule[];
+  /**
+   * Enable multi-user mode.
+   * @default true when initialUsers is provided
+   */
+  multiUser?: boolean;
+}
+/**
+ * Permissions manager interface.
+ * Access via `sandbox.permissions`.
+ */
+interface PermissionsManager {
+  /** List all users in the sandbox */
+  list(): Promise<SandboxUser[]>;
+  /** Get a specific user */
+  get(userId: string): Promise<SandboxUser | null>;
+  /** Add a user to the sandbox */
+  add(options: AddUserOptions): Promise<SandboxUser>;
+  /** Update a user's permissions */
+  update(userId: string, options: UpdateUserOptions): Promise<SandboxUser>;
+  /** Remove a user from the sandbox */
+  remove(userId: string, options?: {
+    preserveHomeDir?: boolean;
+  }): Promise<void>;
+  /** Set access policies for a user */
+  setAccessPolicies(userId: string, rules: AccessPolicyRule[]): Promise<void>;
+  /** Get access policies for a user */
+  getAccessPolicies(userId: string): Promise<AccessPolicyRule[]>;
+  /** Check if a user can perform an action on a path */
+  checkAccess(userId: string, path: string, action: "read" | "write" | "execute"): Promise<boolean>;
+}
+/**
+ * Backend manager for runtime agent configuration.
+ * Access via `sandbox.backend`.
+ */
+interface BackendManager {
+  /** Get current backend status */
+  status(): Promise<BackendStatus>;
+  /** Get backend capabilities */
+  capabilities(): Promise<BackendCapabilities>;
+  /** Add MCP server at runtime (opencode only) */
+  addMcp(name: string, config: McpServerConfig): Promise<void>;
+  /** Get MCP server status */
+  getMcpStatus(): Promise<Record<string, {
+    status: "running" | "stopped" | "error";
+    error?: string;
+  }>>;
+  /** Update backend configuration */
+  updateConfig(config: Partial<BackendConfig>): Promise<void>;
+  /** Provider account metadata, when exposed by the backend SDK */
+  account(): Promise<BackendAccount>;
+  /** Provider model catalog, when exposed by the backend SDK */
+  models(): Promise<BackendModel[]>;
+  /** Provider repository catalog, when exposed by the backend SDK */
+  repositories(): Promise<BackendRepository[]>;
+  /** Provider-native agent list */
+  agents(options?: BackendListOptions): Promise<BackendListResult<BackendAgent>>;
+  /** Provider-native agent lookup */
+  agent(agentId: string): Promise<BackendAgent>;
+  /** Archive provider-native agent */
+  archiveAgent(agentId: string): Promise<void>;
+  /** Unarchive provider-native agent */
+  unarchiveAgent(agentId: string): Promise<void>;
+  /** Delete provider-native agent */
+  deleteAgent(agentId: string): Promise<void>;
+  /** Provider-native runs for an agent */
+  runs(agentId: string, options?: BackendListOptions): Promise<BackendListResult<BackendRun>>;
+  /** Provider-native run lookup */
+  run(runId: string, options?: {
+    agentId?: string;
+  }): Promise<BackendRun>;
+  /** Provider-native agent messages */
+  agentMessages(agentId: string, options?: BackendListOptions): Promise<unknown>;
+  /** Artifacts for an active backend session */
+  artifacts(sessionId: string): Promise<BackendArtifact[]>;
+  /** Download an artifact from an active backend session */
+  downloadArtifact(sessionId: string, path: string): Promise<Uint8Array>;
+  /**
+   * Validate a provider-neutral profile against the active backend.
+   *
+   * Optional while backends adopt the public `AgentProfile` contract.
+   */
+  validateProfile?(profile: AgentProfile): Promise<AgentProfileValidationResult>;
+  /** Restart the backend agent */
+  restart(): Promise<void>;
+}
+/**
+ * Options for spawning a process.
+ *
+ * @example Basic spawn
+ * ```typescript
+ * const proc = await box.process.spawn("python train.py");
+ * ```
+ *
+ * @example With options
+ * ```typescript
+ * const proc = await box.process.spawn("python train.py", {
+ *   cwd: "/workspace/ml",
+ *   env: { "CUDA_VISIBLE_DEVICES": "0" },
+ *   timeoutMs: 3600000, // 1 hour
+ * });
+ * ```
+ */
+interface ProcessSpawnOptions {
+  /** Working directory for the process */
+  cwd?: string;
+  /** Environment variables to set */
+  env?: Record<string, string>;
+  /** Timeout in milliseconds (0 = no timeout) */
+  timeoutMs?: number;
+}
+/**
+ * Options for running Python code.
+ *
+ * @example Simple code execution
+ * ```typescript
+ * const result = await box.process.runCode(`
+ *   import numpy as np
+ *   print(np.random.rand(10))
+ * `);
+ * ```
+ */
+interface RunCodeOptions {
+  /** Working directory */
+  cwd?: string;
+  /** Environment variables */
+  env?: Record<string, string>;
+  /** Timeout in milliseconds */
+  timeoutMs?: number;
+}
+/**
+ * Status of a spawned process.
+ */
+interface ProcessStatus {
+  /** Process ID */
+  pid: number;
+  /** Command that was executed */
+  command: string;
+  /** Working directory */
+  cwd?: string;
+  /** Whether the process is still running */
+  running: boolean;
+  /** Exit code (-1 if still running) */
+  exitCode: number;
+  /** Signal that killed the process (if any) */
+  exitSignal?: string;
+  /** When the process started */
+  startedAt: Date;
+  /** When the process exited (if exited) */
+  exitedAt?: Date;
+}
+/**
+ * Full process information including environment.
+ */
+interface ProcessInfo extends ProcessStatus {
+  /** Environment variables used */
+  env?: Record<string, string>;
+}
+/**
+ * A log entry from process stdout/stderr.
+ */
+interface ProcessLogEntry {
+  /** Log source: stdout or stderr */
+  type: "stdout" | "stderr";
+  /** Log content */
+  data: string;
+  /** Timestamp in milliseconds */
+  timestamp: number;
+}
+/**
+ * Result of running code or a blocking process.
+ */
+interface CodeResult {
+  /** Process ID */
+  pid: number;
+  /** Exit code */
+  exitCode: number;
+  /** Standard output */
+  stdout: string;
+  /** Standard error */
+  stderr: string;
+  /** Execution duration in milliseconds */
+  durationMs: number;
+}
+/**
+ * Signal types for killing processes.
+ */
+type ProcessSignal = "SIGTERM" | "SIGKILL" | "SIGINT" | "SIGHUP" | "SIGQUIT" | "SIGUSR1" | "SIGUSR2";
+/**
+ * A handle to a spawned process with control methods.
+ *
+ * @example Non-blocking process with log streaming
+ * ```typescript
+ * const proc = await box.process.spawn("python train.py", {
+ *   cwd: "/workspace",
+ *   env: { "CUDA_VISIBLE_DEVICES": "0" }
+ * });
+ *
+ * console.log(`Started PID: ${proc.pid}`);
+ *
+ * // Stream logs in real-time
+ * for await (const line of proc.logs()) {
+ *   console.log(line);
+ * }
+ *
+ * // Or wait for completion
+ * const exitCode = await proc.wait();
+ * ```
+ *
+ * @example Check status and kill
+ * ```typescript
+ * const status = await proc.status();
+ * if (status.running) {
+ *   await proc.kill("SIGKILL");
+ * }
+ * ```
+ */
+interface Process {
+  /** Process ID */
+  readonly pid: number;
+  /** Command that was executed */
+  readonly command: string;
+  /**
+   * Get current process status.
+   */
+  status(): Promise<ProcessStatus>;
+  /**
+   * Wait for the process to exit.
+   * @returns Exit code
+   */
+  wait(): Promise<number>;
+  /**
+   * Kill the process.
+   * @param signal - Signal to send (default: SIGTERM)
+   */
+  kill(signal?: ProcessSignal): Promise<void>;
+  /**
+   * Stream stdout/stderr logs in real-time.
+   * Includes buffered logs from process start.
+   */
+  logs(): AsyncIterable<ProcessLogEntry>;
+  /**
+   * Stream only stdout.
+   */
+  stdout(): AsyncIterable<string>;
+  /**
+   * Stream only stderr.
+   */
+  stderr(): AsyncIterable<string>;
+}
+/**
+ * Process manager for spawning and controlling processes.
+ * Access via `sandbox.process`.
+ *
+ * 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); // Prints the mean
+ * ```
+ *
+ * @example List and manage processes
+ * ```typescript
+ * const procs = await box.process.list();
+ * for (const p of procs) {
+ *   console.log(`PID ${p.pid}: ${p.command} (${p.running ? 'running' : 'exited'})`);
+ * }
+ *
+ * // Get specific process
+ * const proc = await box.process.get(1234);
+ * if (proc) {
+ *   await proc.kill();
+ * }
+ * ```
+ */
+interface ProcessManager {
+  /**
+   * Spawn a process without blocking.
+   * Returns immediately with a Process handle.
+   *
+   * @param command - Shell command to execute
+   * @param options - Spawn options (cwd, env, timeout)
+   * @returns Process handle for control and monitoring
+   */
+  spawn(command: string, options?: ProcessSpawnOptions): Promise<Process>;
+  /**
+   * Run Python code directly.
+   * Blocks until completion and returns result.
+   *
+   * @param code - Python code to execute
+   * @param options - Execution options
+   * @returns Execution result with stdout/stderr
+   */
+  runCode(code: string, options?: RunCodeOptions): Promise<CodeResult>;
+  /**
+   * List all tracked processes.
+   *
+   * @returns Array of process status objects
+   */
+  list(): Promise<ProcessStatus[]>;
+  /**
+   * Get a process by PID.
+   *
+   * @param pid - Process ID
+   * @returns Process handle or null if not found
+   */
+  get(pid: number): Promise<Process | null>;
+}
+/**
+ * Information about a stored secret (without the value).
+ */
+interface SecretInfo {
+  /** Secret name (e.g., HF_TOKEN, AWS_ACCESS_KEY) */
+  name: string;
+  /** When the secret was created */
+  createdAt: Date;
+  /** When the secret was last updated */
+  updatedAt: Date;
+}
+/**
+ * Secrets manager for storing and retrieving encrypted secrets.
+ * Access via `client.secrets`.
+ *
+ * Secrets are encrypted at rest and can be injected into sandboxes
+ * as environment variables.
+ *
+ * @example Create and manage secrets
+ * ```typescript
+ * // Create a secret
+ * await client.secrets.create("HF_TOKEN", "hf_xxx");
+ *
+ * // List all secrets (names only, not values)
+ * const secrets = await client.secrets.list();
+ * console.log(secrets.map(s => s.name)); // ["HF_TOKEN"]
+ *
+ * // Get a secret value (audited operation)
+ * const value = await client.secrets.get("HF_TOKEN");
+ *
+ * // Update a secret
+ * await client.secrets.update("HF_TOKEN", "hf_new_value");
+ *
+ * // Delete a secret
+ * await client.secrets.delete("HF_TOKEN");
+ * ```
+ *
+ * @example Use secrets in a sandbox
+ * ```typescript
+ * // Create sandbox with secrets injected as env vars
+ * const box = await client.create({
+ *   secrets: ["HF_TOKEN", "AWS_ACCESS_KEY"],
+ * });
+ *
+ * // Secrets are available as environment variables
+ * const result = await box.exec("echo $HF_TOKEN");
+ * ```
+ */
+interface SecretsManager {
+  /**
+   * Create a new secret.
+   *
+   * @param name - Secret name (uppercase, alphanumeric + underscore, max 63 chars)
+   * @param value - Secret value (max 64KB)
+   * @returns Created secret info
+   * @throws If secret already exists or name is invalid
+   *
+   * @example
+   * ```typescript
+   * await client.secrets.create("HF_TOKEN", "hf_xxx");
+   * await client.secrets.create("AWS_ACCESS_KEY", "AKIA...");
+   * ```
+   */
+  create(name: string, value: string): Promise<SecretInfo>;
+  /**
+   * List all secrets (names and metadata only, not values).
+   *
+   * @returns Array of secret info objects
+   *
+   * @example
+   * ```typescript
+   * const secrets = await client.secrets.list();
+   * for (const s of secrets) {
+   *   console.log(`${s.name} - created ${s.createdAt}`);
+   * }
+   * ```
+   */
+  list(): Promise<SecretInfo[]>;
+  /**
+   * Get a secret's decrypted value.
+   *
+   * This is an audited operation - access is logged.
+   *
+   * @param name - Secret name
+   * @returns Secret value
+   * @throws If secret not found
+   *
+   * @example
+   * ```typescript
+   * const token = await client.secrets.get("HF_TOKEN");
+   * ```
+   */
+  get(name: string): Promise<string>;
+  /**
+   * Update an existing secret's value.
+   *
+   * @param name - Secret name
+   * @param value - New secret value
+   * @returns Updated secret info
+   * @throws If secret not found
+   *
+   * @example
+   * ```typescript
+   * await client.secrets.update("HF_TOKEN", "hf_new_value");
+   * ```
+   */
+  update(name: string, value: string): Promise<SecretInfo>;
+  /**
+   * Delete a secret.
+   *
+   * @param name - Secret name
+   * @throws If secret not found
+   *
+   * @example
+   * ```typescript
+   * await client.secrets.delete("HF_TOKEN");
+   * ```
+   */
+  delete(name: string): Promise<void>;
+}
+/**
+ * Detailed file/directory information.
+ */
+interface FileInfo {
+  /** File/directory name */
+  name: string;
+  /** Full path relative to workspace */
+  path: string;
+  /** Size in bytes */
+  size: number;
+  /** Whether this is a directory */
+  isDir: boolean;
+  /** Whether this is a regular file */
+  isFile: boolean;
+  /** Whether this is a symbolic link */
+  isSymlink: boolean;
+  /** Unix permissions (e.g., 0o755) */
+  permissions: number;
+  /** Owner user ID/name */
+  owner: string;
+  /** Group ID/name */
+  group: string;
+  /** Last modification time */
+  modTime: Date;
+  /** Last access time */
+  accessTime: Date;
+}
+/**
+ * Options for uploading files.
+ */
+interface UploadOptions {
+  /** Overwrite if file exists (default: true) */
+  overwrite?: boolean;
+  /** Set file permissions (Unix mode, e.g., 0o644) */
+  permissions?: number;
+  /** Progress callback for large files */
+  onProgress?: (progress: UploadProgress) => void;
+}
+/**
+ * Upload progress information.
+ */
+interface UploadProgress {
+  /** Bytes uploaded so far */
+  bytesUploaded: number;
+  /** Total bytes to upload */
+  totalBytes: number;
+  /** Percentage complete (0-100) */
+  percentage: number;
+}
+/**
+ * Options for downloading files.
+ */
+interface DownloadOptions {
+  /** Overwrite local file if exists (default: true) */
+  overwrite?: boolean;
+  /** Progress callback for large files */
+  onProgress?: (progress: DownloadProgress) => void;
+}
+/**
+ * Download progress information.
+ */
+interface DownloadProgress {
+  /** Bytes downloaded so far */
+  bytesDownloaded: number;
+  /** Total bytes to download */
+  totalBytes: number;
+  /** Percentage complete (0-100) */
+  percentage: number;
+}
+/**
+ * Options for listing directories.
+ */
+interface ListOptions {
+  /** Include hidden files (starting with .) */
+  all?: boolean;
+  /** Include full metadata (like ls -l) */
+  long?: boolean;
+}
+/**
+ * Options for creating directories.
+ */
+interface MkdirOptions {
+  /** Create parent directories as needed (like mkdir -p) */
+  recursive?: boolean;
+  /** Set directory permissions (Unix mode, e.g., 0o755) */
+  mode?: number;
+}
+/**
+ * Options for deleting files/directories.
+ */
+interface DeleteOptions {
+  /** Recursively delete directories (like rm -rf) */
+  recursive?: boolean;
+}
+/**
+ * File system operations for sandboxes. Access via `sandbox.fs`.
+ *
+ * Beyond basic read/write: binary upload/download, directory operations,
+ * progress reporting for large files.
+ *
+ * @example Upload and download files
+ * ```typescript
+ * // Upload a local file
+ * await box.fs.upload("./model.bin", "/workspace/models/model.bin");
+ *
+ * // Download a file
+ * await box.fs.download("/workspace/results.zip", "./local/results.zip");
+ *
+ * // With progress reporting
+ * await box.fs.upload("./large-file.bin", "/workspace/data.bin", {
+ *   onProgress: (p) => console.log(`${p.percentage}%`),
+ * });
+ * ```
+ *
+ * @example Directory operations
+ * ```typescript
+ * // Upload entire directory
+ * await box.fs.uploadDir("./local/project", "/workspace/project");
+ *
+ * // Download entire directory
+ * await box.fs.downloadDir("/workspace/output", "./local/output");
+ *
+ * // List directory contents
+ * const files = await box.fs.list("/workspace");
+ * for (const f of files) {
+ *   console.log(`${f.name} - ${f.size} bytes`);
+ * }
+ * ```
+ *
+ * @example File management
+ * ```typescript
+ * // Check if file exists
+ * if (await box.fs.exists("/workspace/config.json")) {
+ *   const info = await box.fs.stat("/workspace/config.json");
+ *   console.log(`Size: ${info.size}, Modified: ${info.modTime}`);
+ * }
+ *
+ * // Create directory
+ * await box.fs.mkdir("/workspace/output/images", { recursive: true });
+ *
+ * // Delete file or directory
+ * await box.fs.delete("/workspace/temp", { recursive: true });
+ * ```
+ */
+interface FileSystem {
+  /**
+   * Read a file's contents as a string.
+   * For binary files, use download() instead.
+   *
+   * @param path - Path to file (relative to workspace)
+   * @returns File contents as UTF-8 string
+   * @throws NotFoundError if file doesn't exist
+   */
+  read(path: string): Promise<string>;
+  /**
+   * Write string content to a file.
+   * For binary files, use upload() instead.
+   * Creates parent directories as needed.
+   *
+   * @param path - Path to file (relative to workspace)
+   * @param content - Content to write
+   */
+  write(path: string, content: string): Promise<void>;
+  /**
+   * Search for text patterns in files using ripgrep.
+   * @see SearchOptions for available options
+   */
+  search(query: string, options?: SearchOptions): AsyncIterable<SearchMatch>;
+  /**
+   * Upload a local file to the sandbox.
+   * Handles binary files correctly using multipart upload.
+   * Creates parent directories as needed.
+   *
+   * @param localPath - Path to local file
+   * @param remotePath - Destination path in sandbox
+   * @param options - Upload options (overwrite, permissions, progress)
+   * @throws Error if local file doesn't exist
+   *
+   * @example
+   * ```typescript
+   * await box.fs.upload("./model.bin", "/workspace/models/model.bin");
+   *
+   * // With progress
+   * await box.fs.upload("./large-file.bin", "/data/file.bin", {
+   *   onProgress: (p) => console.log(`${p.percentage.toFixed(1)}%`),
+   * });
+   * ```
+   */
+  upload(localPath: string, remotePath: string, options?: UploadOptions): Promise<void>;
+  /**
+   * Download a file from the sandbox.
+   * Handles binary files correctly.
+   * Creates local parent directories as needed.
+   *
+   * @param remotePath - Path to file in sandbox
+   * @param localPath - Local destination path
+   * @param options - Download options (overwrite, progress)
+   * @throws NotFoundError if remote file doesn't exist
+   *
+   * @example
+   * ```typescript
+   * await box.fs.download("/workspace/output.zip", "./results.zip");
+   * ```
+   */
+  download(remotePath: string, localPath: string, options?: DownloadOptions): Promise<void>;
+  /**
+   * Upload a local directory to the sandbox.
+   * Uses tar for efficient transfer.
+   * Preserves directory structure and file permissions.
+   *
+   * @param localDir - Path to local directory
+   * @param remoteDir - Destination directory in sandbox
+   * @throws Error if local directory doesn't exist
+   *
+   * @example
+   * ```typescript
+   * await box.fs.uploadDir("./project", "/workspace/project");
+   * ```
+   */
+  uploadDir(localDir: string, remoteDir: string): Promise<void>;
+  /**
+   * Download a directory from the sandbox.
+   * Uses tar for efficient transfer.
+   * Preserves directory structure and file permissions.
+   *
+   * @param remoteDir - Directory path in sandbox
+   * @param localDir - Local destination directory
+   * @throws NotFoundError if remote directory doesn't exist
+   *
+   * @example
+   * ```typescript
+   * await box.fs.downloadDir("/workspace/output", "./local-output");
+   * ```
+   */
+  downloadDir(remoteDir: string, localDir: string): Promise<void>;
+  /**
+   * List directory contents with metadata.
+   *
+   * @param path - Directory path (relative to workspace)
+   * @param options - List options (all, long)
+   * @returns Array of file/directory info
+   * @throws NotFoundError if directory doesn't exist
+   *
+   * @example
+   * ```typescript
+   * const entries = await box.fs.list("/workspace", { all: true });
+   * for (const e of entries) {
+   *   const type = e.isDir ? "DIR" : "FILE";
+   *   console.log(`[${type}] ${e.name} (${e.size} bytes)`);
+   * }
+   * ```
+   */
+  list(path: string, options?: ListOptions): Promise<FileInfo[]>;
+  /**
+   * Get detailed information about a file or directory.
+   *
+   * @param path - Path to file/directory
+   * @returns File/directory metadata
+   * @throws NotFoundError if path doesn't exist
+   *
+   * @example
+   * ```typescript
+   * const info = await box.fs.stat("/workspace/model.bin");
+   * console.log(`Size: ${info.size}, Modified: ${info.modTime}`);
+   * ```
+   */
+  stat(path: string): Promise<FileInfo>;
+  /**
+   * Delete a file or directory.
+   *
+   * @param path - Path to delete
+   * @param options - Delete options (recursive for directories)
+   * @throws NotFoundError if path doesn't exist
+   * @throws Error if deleting non-empty directory without recursive
+   *
+   * @example
+   * ```typescript
+   * // Delete file
+   * await box.fs.delete("/workspace/temp.txt");
+   *
+   * // Delete directory recursively
+   * await box.fs.delete("/workspace/cache", { recursive: true });
+   * ```
+   */
+  delete(path: string, options?: DeleteOptions): Promise<void>;
+  /**
+   * Create a directory.
+   *
+   * @param path - Directory path to create
+   * @param options - Options (recursive to create parents)
+   *
+   * @example
+   * ```typescript
+   * // Create with parents
+   * await box.fs.mkdir("/workspace/output/images", { recursive: true });
+   * ```
+   */
+  mkdir(path: string, options?: MkdirOptions): Promise<void>;
+  /**
+   * Check if a path exists.
+   *
+   * @param path - Path to check
+   * @returns true if path exists, false otherwise
+   *
+   * @example
+   * ```typescript
+   * if (await box.fs.exists("/workspace/config.json")) {
+   *   // File exists
+   * }
+   * ```
+   */
+  exists(path: string): Promise<boolean>;
+}
+//#endregion
+//#region src/session.d.ts
+/**
+ * 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: SandboxInstance, /** 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>;
+  /**
+   * 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>;
+  /**
+   * Cancel the session. Best-effort: an in-flight LLM call may still
+   * complete one more token before the abort takes effect. Idempotent —
+   * cancelling a completed session is a no-op.
+   */
+  cancel(): 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
+/**
+ * HTTP client interface for making requests.
+ */
+interface HttpClient {
+  fetch(path: string, options?: RequestInit): 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;
+  /** Web terminal URL for browser-based access */
+  get url(): string | undefined;
+  /**
+   * 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>;
+  /**
+   * 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): 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>;
+  /**
+   * Stream events from an agent prompt.
+   * Use this for real-time updates during agent execution.
+   *
+   * 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>;
+  /**
+   * 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>;
+  }): 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>;
+  /**
+   * 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;
+  private networkUpdate;
+  private networkExposePort;
+  private networkListUrls;
+  private networkGetConfig;
+  /**
+   * 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>;
+  /**
+   * Create a CRIU checkpoint of the sandbox's memory state.
+   *
+   * Checkpoints capture the complete memory state of the running sandbox,
+   * enabling true pause/resume and fork operations. Unlike snapshots which
+   * only preserve filesystem state, checkpoints preserve process memory,
+   * open file descriptors, and execution state.
+   *
+   * **Requirements:** CRIU must be available on the host. Check availability
+   * with `client.criuStatus()` before calling.
+   *
+   * **Note:** By default, checkpoint stops the sandbox. Use `leaveRunning: true`
+   * to keep it running (creates a copy-on-write checkpoint).
+   *
+   * @param options - Checkpoint options
+   * @returns Checkpoint result with ID and metadata
+   *
+   * @example Basic checkpoint (stops sandbox)
+   * ```typescript
+   * const checkpoint = await box.checkpoint();
+   * console.log(`Checkpoint: ${checkpoint.checkpointId}`);
+   * // Sandbox is now stopped, resume with box.resume()
+   * ```
+   *
+   * @example Checkpoint without stopping
+   * ```typescript
+   * const checkpoint = await box.checkpoint({
+   *   tags: ["before-deploy"],
+   *   leaveRunning: true,
+   * });
+   * // Sandbox continues running
+   * ```
+   */
+  checkpoint(options?: CheckpointOptions): Promise<CheckpointResult>;
+  /**
+   * List all checkpoints for this sandbox.
+   *
+   * @returns Array of checkpoint metadata
+   *
+   * @example
+   * ```typescript
+   * const checkpoints = await box.listCheckpoints();
+   * for (const cp of checkpoints) {
+   *   console.log(`${cp.checkpointId}: ${cp.createdAt}`);
+   * }
+   * ```
+   */
+  listCheckpoints(): Promise<CheckpointInfo[]>;
+  /**
+   * Delete a checkpoint.
+   *
+   * @param checkpointId - ID of the checkpoint to delete
+   */
+  deleteCheckpoint(checkpointId: string): Promise<void>;
+  /**
+   * Fork a new sandbox from a checkpoint.
+   *
+   * Creates a new sandbox with the same memory state as this sandbox
+   * at the time of the checkpoint. The fork has a new identity but
+   * preserves the execution state.
+   *
+   * **Use cases:**
+   * - Branch workflows: Create parallel execution paths
+   * - A/B testing: Run same state with different configurations
+   * - Debugging: Fork at a specific point to investigate
+   *
+   * @param checkpointId - ID of the checkpoint to fork from
+   * @param options - Fork configuration
+   * @returns The new sandbox instance
+   *
+   * @example Basic fork
+   * ```typescript
+   * const checkpoint = await box.checkpoint({ leaveRunning: true });
+   * const forked = await box.fork(checkpoint.checkpointId);
+   * // forked has same memory state as box at checkpoint time
+   * ```
+   *
+   * @example Fork with custom config
+   * ```typescript
+   * const forked = await box.fork(checkpointId, {
+   *   name: "experiment-branch",
+   *   env: { EXPERIMENT: "true" },
+   * });
+   * ```
+   */
+  fork(checkpointId: string, options?: ForkOptions): Promise<SandboxInstance>;
+  /**
+   * Stop the sandbox (keeps state for resume).
+   */
+  stop(): Promise<void>;
+  /**
+   * Resume a stopped sandbox.
+   */
+  resume(): 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 parseCheckpointInfo;
+  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;
+  }): Promise<void>;
+  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>;
+  /**
+   * 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(). */
+  _sessionCancel(id: string): Promise<void>;
+}
+//#endregion
+export { FleetExecDispatchOptions as $, StorageConfig as $n, SandboxClientConfig as $t, CreateIntelligenceReportOptions as A, SandboxInfo as An, defineInlineResource as Ar, ProcessLogEntry as At, DownloadProgress as B, ScopedToken as Bn, ProvisionStatus as Bt, BatchResult as C, SandboxFleetTraceExport as Cn, AgentProfileResourceRef as Cr, NetworkManager as Ct, CheckpointOptions as D, SandboxFleetWorkspaceReconcileResult as Dn, AgentSubagentProfile as Dr, PreviewLinkManager as Dt, CheckpointInfo as E, SandboxFleetWorkspace as En, AgentProfileValidationResult as Er, PreviewLinkInfo as Et, DeleteOptions as F, SandboxTraceBundle as Fn, SandboxMcpEndpoint as Fr, PromptInputPart as Ft, ExecOptions as G, SecretsManager as Gn, PublishPublicTemplateVersionOptions as Gt, DriverInfo as H, SearchMatch as Hn, PublicTemplateInfo as Ht, DirectoryPermission as I, SandboxTraceEvent as In, SandboxMcpServerEntry as Ir, PromptOptions as It, FileSystem as J, SessionListOptions as Jn, ReconcileSandboxFleetsOptions as Jt, ExecResult as K, SessionEventStreamOptions as Kn, ReapExpiredSandboxFleetsOptions as Kt, DispatchPromptOptions as L, SandboxTraceExport as Ln, buildSandboxMcpConfig as Lr, PromptResult as Lt, CreateSandboxFleetTokenOptions as M, SandboxPermissionsConfig as Mn, BuildSandboxMcpConfigOptions as Mr, ProcessSignal as Mt, CreateSandboxFleetWithCoordinatorOptions as N, SandboxResources as Nn, SANDBOX_MCP_SERVER_NAME as Nr, ProcessSpawnOptions as Nt, CheckpointResult as O, SandboxFleetWorkspaceRestoreResult as On, defineAgentProfile as Or, Process as Ot, CreateSandboxOptions as P, SandboxStatus as Pn, SandboxMcpConfig as Pr, ProcessStatus as Pt, FleetDispatchStreamOptions as Q, SnapshotResult as Qn, SSHCredentials as Qt, DispatchedSession as R, SandboxTraceOptions as Rn, ProvisionEvent as Rt, BatchOptions as S, SandboxFleetTraceEvent as Sn, AgentProfilePrompt as Sr, NetworkConfig as St, BatchTaskResult as T, SandboxFleetUsage as Tn, AgentProfileValidationIssue as Tr, PermissionsManager as Tt, DriverType as U, SearchOptions as Un, PublicTemplateVersionInfo as Ut, DriverConfig as V, ScopedTokenScope as Vn, ProvisionStep as Vt, EventStreamOptions as W, SecretInfo as Wn, PublishPublicTemplateOptions as Wt, FleetDispatchResultBuffer as X, SnapshotInfo as Xn, RunCodeOptions as Xt, FleetDispatchCancelResult as Y, SessionStatus as Yn, ReconcileSandboxFleetsResult as Yt, FleetDispatchResultBufferOptions as Z, SnapshotOptions as Zn, SSHCommandDescriptor as Zt, BackendInfo as _, SandboxFleetManifestMachine as _n, AgentProfileConfidential as _r, ListSandboxFleetOptions as _t, TraceExportSink as a, SandboxFleetCostEstimate as an, TeeAttestationResponse as ar, ForkResult as at, BackendType as b, SandboxFleetToken as bn, AgentProfileModelHints as br, MintScopedTokenOptions as bt, otelTraceIdForTangleTrace as c, SandboxFleetDriverCapability as cn, TokenRefreshHandler as cr, GitCommit as ct, AcceleratorKind as d, SandboxFleetIntelligenceEnvelope as dn, UploadOptions as dr, GitStatus as dt, SandboxConnection as en, SubscriptionInfo as er, FleetExecDispatchResult as et, AccessPolicyRule as f, SandboxFleetMachine as fn, UploadProgress as fr, GpuType as ft, BackendConfig as g, SandboxFleetManifest as gn, AgentProfileCapabilities as gr, ListOptions as gt, BackendCapabilities as h, SandboxFleetMachineSpec as hn, AgentProfile as hr, IntelligenceReportBudget as ht, TraceExportResult as i, SandboxFleetArtifactSpec as in, TeeAttestationReport as ir, ForkOptions as it, CreateSandboxFleetOptions as j, SandboxIntelligenceEnvelope as jn, mergeAgentProfiles as jr, ProcessManager as jt, CodeResult as k, SandboxFleetWorkspaceSnapshotResult as kn, defineGitHubResource as kr, ProcessInfo as kt, toOtelJson as l, SandboxFleetDriverTimings as ln, ToolsConfig as lr, GitConfig as lt, AttachSandboxFleetMachineOptions as m, SandboxFleetMachineRecord as mn, WaitForOptions as mr, IntelligenceReport as mt, SandboxInstance as n, SandboxEvent as nn, TaskResult as nr, FleetPromptDispatchOptions as nt, buildTraceExportPayload as o, SandboxFleetDispatchFailureClass as on, TeePublicKey as or, GitAuth as ot, AddUserOptions as p, SandboxFleetMachineMeteredUsage as pn, UsageInfo as pr, InstalledTool as pt, FileInfo as q, SessionInfo as qn, ReapExpiredSandboxFleetsResult as qt, TraceExportFormat as r, SandboxFleetArtifact as rn, TeeAttestationOptions as rr, FleetPromptDispatchResult as rt, exportTraceBundle as s, SandboxFleetDispatchResponse as sn, TeePublicKeyResponse as sr, GitBranch as st, HttpClient as t, SandboxEnvironment as tn, TaskOptions as tr, FleetMachineId as tt, SandboxSession as u, SandboxFleetInfo as un, UpdateUserOptions as ur, GitDiff as ut, BackendManager as v, SandboxFleetOperationsSummary as vn, AgentProfileFileMount as vr, ListSandboxOptions as vt, BatchTask as w, SandboxFleetTraceOptions as wn, AgentProfileResources as wr, PermissionLevel as wt, BatchEvent as x, SandboxFleetTraceBundle as xn, AgentProfilePermissionValue as xr, MkdirOptions as xt, BackendStatus as y, SandboxFleetPolicy as yn, AgentProfileMcpServer as yr, McpServerConfig as yt, DownloadOptions as z, SandboxUser as zn, ProvisionResult as zt };