@tangle-network/sandbox 0.1.2 → 0.3.0

package/dist/{sandbox-BvZ0-Iv7.d.ts → sandbox-CpK8etqP.d.ts}

@@ -1,3 +1,5 @@
+import { IntegrationActor, IntegrationManifest } from "@tangle-network/agent-integrations";
+
 //#region src/agent-profile.d.ts
 /**
  * Provider-neutral agent profile types for public SDK consumers.
@@ -10,6 +12,7 @@
  * 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.
  */
@@ -19,6 +22,11 @@ type AgentProfileResourceRef = {
   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;
@@ -31,6 +39,7 @@ declare function defineInlineResource(name: string, content: string): AgentProfi
  * Helper for creating typed GitHub-backed resource refs.
  */
 declare function defineGitHubResource(path: string, options?: {
+  repository?: string;
   ref?: string;
   name?: string;
 }): AgentProfileResourceRef;
@@ -44,19 +53,38 @@ interface AgentProfileFileMount {
 }
 /**
  * Provider-neutral resource bundle.
- *
- * Provider-specific concepts such as "skills" or "commands" should be modeled
- * under `extensions` unless they become portable across multiple backends.
  */
 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.
@@ -100,10 +128,25 @@ interface AgentSubagentProfile {
   prompt?: string;
   model?: string;
   tools?: Record<string, boolean>;
-  permissions?: Record<string, AgentProfilePermissionValue>;
+  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.
  *
@@ -153,11 +196,13 @@ interface AgentProfile {
   tags?: string[];
   prompt?: AgentProfilePrompt;
   model?: AgentProfileModelHints;
-  permissions?: Record<string, AgentProfilePermissionValue>;
+  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>;
   /**
@@ -186,7 +231,13 @@ interface AgentProfileCapabilities {
   resources: {
     files: boolean;
     instructions: boolean;
+    tools?: boolean;
+    skills?: boolean;
+    agents?: boolean;
+    commands?: boolean;
   };
+  hooks?: boolean;
+  modes?: boolean;
   runtimeUpdate: boolean;
   validation: boolean;
   /**
@@ -219,6 +270,9 @@ interface AgentProfileValidationResult {
 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.
  *
@@ -235,6 +289,61 @@ interface SandboxEnvironment {
   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.
@@ -357,6 +466,21 @@ interface SandboxClientConfig {
   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.
@@ -381,7 +505,11 @@ interface SandboxResources {
   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.
  *
@@ -566,6 +694,37 @@ interface CreateSandboxOptions {
   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.
@@ -586,6 +745,10 @@ interface CreateSandboxOptions {
   sshEnabled?: boolean;
   /** Custom SSH public key for access (optional) */
   sshPublicKey?: string;
+  /** Custom SSH public keys for access (optional) */
+  sshPublicKeys?: string[];
+  /** Stored SSH key IDs or names to authorize at creation time */
+  sshKeyIds?: string[];
   /**
    * Enable web terminal access.
    * Provides a browser-based terminal via websocket.
@@ -603,6 +766,35 @@ interface CreateSandboxOptions {
   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.
    *
@@ -634,17 +826,101 @@ interface CreateSandboxOptions {
    * (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 {
-  /** SSH server hostname */
-  host: string;
-  /** SSH server port */
-  port: number;
   /** 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.
@@ -799,7 +1075,7 @@ interface ExecOptions {
  *
  * @example Search TypeScript files
  * ```typescript
- * const matches = await box.search("TODO", {
+ * const matches = await box.search("export function", {
  *   glob: "**\/*.ts",
  *   maxResults: 100,
  * });
@@ -974,6 +1250,31 @@ interface PromptOptions {
   context?: Record<string, unknown>;
   /** AbortSignal for cancellation */
   signal?: AbortSignal;
+  /**
+   * Stable execution id for cross-process reconnect. When passed, the same
+   * id on a retry lands on the same substrate execution — the platform
+   * replays its buffered event stream instead of spawning a duplicate run.
+   * Forwarded as the `X-Execution-ID` header. Omit to let the SDK extract
+   * one from the response stream's `execution.started` event (in-call
+   * reconnect only).
+   */
+  executionId?: string;
+  /**
+   * Last event id the caller has already acknowledged. The substrate
+   * replays strictly after this id on reconnect. Forwarded as the
+   * `Last-Event-ID` header. Omit on first attempt.
+   */
+  lastEventId?: string;
+  /**
+   * Caller-supplied turn idempotency key. When set, a retry with the
+   * same `turnId` on the same `sessionId` short-circuits to the cached
+   * result instead of re-issuing the upstream LLM call. Generate a
+   * fresh `turnId` per logical attempt (a different user message gets
+   * a new id) and reuse it only for retries of the same intent
+   * (Stripe-style idempotency). Combine with `box.findCompletedTurn`
+   * to check completion before re-dispatching.
+   */
+  turnId?: string;
 }
 /**
  * SSE event from sandbox streaming.
@@ -986,6 +1287,142 @@ interface SandboxEvent {
   /** 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;
+}
+/**
+ * Subject types for an Intelligence Report.
+ *
+ * - `sandbox`: one container's run.
+ * - `fleet`: one managed grouping of sandboxes. Add `subject.dispatchId`
+ *   to narrow to a single coordinated command within the fleet
+ *   (previously a standalone `dispatch` subject type — now expressed
+ *   as a fleet refinement).
+ */
+type IntelligenceReportSubjectType = "sandbox" | "fleet";
+interface IntelligenceReport {
+  jobId: string;
+  subject: {
+    type: IntelligenceReportSubjectType;
+    id: string; /** Present when the report was narrowed to a single fleet dispatch. */
+    dispatchId?: 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";
+}
+/**
+ * Time window for an intelligence report. Both bounds are millisecond
+ * epochs. Omit `since` to mean "from the subject's first observation";
+ * omit `until` to mean "now". `since` must be <= `until` when both are
+ * set; the server enforces this at the schema layer.
+ */
+interface IntelligenceReportWindow {
+  since?: number;
+  until?: number;
+}
+/**
+ * Comparison baseline. When present, the report includes an explicit
+ * delta between the primary subject and this baseline. Must be the
+ * same `type` as the primary subject — the analyzer rejects mixed
+ * subject-type comparisons because the delta would be meaningless.
+ *
+ * `dispatchId` is only valid when `type === "fleet"`.
+ */
+interface IntelligenceReportCompareTo {
+  type: IntelligenceReportSubjectType;
+  id: string;
+  /** Narrow the baseline to a single dispatch within the fleet. */
+  dispatchId?: string;
+}
+interface CreateIntelligenceReportOptions {
+  subject: {
+    type: IntelligenceReportSubjectType;
+    id: string;
+    /**
+     * Narrow the analysis to a single coordinated command within a
+     * fleet. Only valid when `type === "fleet"`.
+     */
+    dispatchId?: string; /** Bound the analysis to a time window. */
+    window?: IntelligenceReportWindow; /** Compare the primary subject against a same-type baseline. */
+    compareTo?: IntelligenceReportCompareTo;
+  };
+  mode?: "deterministic" | "agentic";
+  acknowledgeCost?: boolean;
+  budget?: IntelligenceReportBudget;
+  metadata?: Record<string, unknown>;
+}
 /**
  * Options for event streaming.
  */
@@ -1089,7 +1526,9 @@ interface SubscriptionInfo {
    *
    * **May be negative** for overage-enabled plans (pro/enterprise):
    * overage charges can push the stored balance below zero. Free-tier
-   * plans cap at 0 at the charge path (`capAtZero: true`).
+   * 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
@@ -1193,6 +1632,181 @@ interface TaskResult extends PromptResult {
   /** 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;
+}
+/**
+ * Options for `box.messages()` — list messages on a session including
+ * mid-turn partial assistant content.
+ */
+interface ListMessagesOptions {
+  /** Session id whose messages to return (required). */
+  sessionId: string;
+  /** Max entries, default 100. Server caps at 1000. */
+  limit?: number;
+  /** Skip this many entries from the start. */
+  offset?: number;
+  /** Only return messages newer than this Unix-ms timestamp. */
+  since?: number;
+}
+/**
+ * One message on a session — user, assistant, or system. The metadata
+ * field carries the durability marker set by the sidecar:
+ *   - `status: "streaming"` and no `completed`/`interrupted` flag → turn
+ *      is in flight, OR the sidecar died before stamping a marker
+ *      (SIGKILL, OOM). The partial parts are the partial assistant
+ *      content the recorder flushed before death.
+ *   - `completed: true` + `completedAt` → turn finished normally. If a
+ *      `turnId` was supplied, its result is cached for idempotent retry.
+ *   - `interrupted: true` + `interruptedAt` + `interruptReason` → graceful
+ *      abort, timeout, or upstream error. Partial content is preserved
+ *      but not billable as a completion.
+ */
+interface SessionMessage {
+  id: string;
+  role: "user" | "assistant" | "system";
+  /** ISO timestamp string. */
+  timestamp: string;
+  /** Message parts (text, tool calls, reasoning, files). Same shape as
+   *  events emitted by `streamPrompt`. */
+  parts: unknown[];
+  /** Durability + idempotency metadata. See class doc above. */
+  metadata?: {
+    status?: "streaming" | "completed" | "interrupted";
+    completed?: boolean;
+    completedAt?: string;
+    interrupted?: boolean;
+    interruptedAt?: string;
+    interruptReason?: string;
+    turnId?: string;
+    startedAt?: string;
+    [extra: string]: unknown;
+  };
+}
+/**
+ * Returned by `box.findCompletedTurn()` — the cached result of a
+ * previously-completed turn, keyed on the caller's `turnId`.
+ */
+interface CompletedTurnResult {
+  turnId: string;
+  sessionId: string;
+  /** ISO timestamp when the turn finished. */
+  completedAt: string;
+  /** The cached AgentExecutionResult-shape payload (text, toolInvocations,
+   *  sessionId, tokenUsage, etc.). */
+  result: Record<string, unknown>;
+}
+/**
+ * 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.
  */
@@ -1268,6 +1882,8 @@ interface BatchOptions {
   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
@@ -1332,6 +1948,524 @@ interface BatchEvent {
    */
   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.
  */
@@ -1408,9 +2542,29 @@ interface ForkResult {
  */
 type DriverType = "docker" | "firecracker" | "host-agent" | "tangle";
 /**
- * Accelerator class for GPU-enabled sandboxes.
+ * 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 GpuType = "nvidia-a100" | "nvidia-h100" | "nvidia-l4" | "amd-mi250";
+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.
  *
@@ -1424,12 +2578,10 @@ type GpuType = "nvidia-a100" | "nvidia-h100" | "nvidia-l4" | "amd-mi250";
  * driver: { type: "firecracker", enableCriu: true }
  * ```
  *
- * @example GPU-enabled sandbox
+ * @example Accelerator-backed sandbox
  * ```typescript
- * driver: {
- *   type: "host-agent",
- *   gpuRequired: true,
- *   gpuType: "nvidia-a100",
+ * resources: {
+ *   accelerator: { kind: "nvidia-a100", count: 1 },
  * }
  * ```
  */
@@ -1444,20 +2596,23 @@ interface DriverConfig {
    * Support depends on the selected driver.
    */
   enableCriu?: boolean;
-  /** Require a GPU for this sandbox. */
-  gpuRequired?: boolean;
-  /** Accelerator class preference. */
-  gpuType?: GpuType;
-  /**
-   * Number of GPUs required.
-   * @default 1 (when gpuRequired is true)
-   */
-  gpuCount?: number;
   /**
    * 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.
@@ -1482,6 +2637,11 @@ interface DriverInfo {
     available: number;
     total: number;
   };
+  acceleratorCapacity?: {
+    available: number;
+    total: number;
+    kinds: AcceleratorKind[];
+  };
 }
 /**
  * Backend type identifier. Controls which AI agent runtime runs inside the sandbox.
@@ -1508,9 +2668,10 @@ interface DriverInfo {
  * - `"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" | "cli-base";
+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.
  */
@@ -1643,6 +2804,60 @@ interface BackendInfo {
     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.
  *
@@ -1981,6 +3196,34 @@ interface BackendManager {
   }>>;
   /** 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.
    *
@@ -2248,6 +3491,20 @@ interface SecretInfo {
   /** When the secret was last updated */
   updatedAt: Date;
 }
+interface SshKeyInfo {
+  id: string;
+  name: string;
+  publicKey: string;
+  fingerprint: string;
+  keyType: string;
+  createdAt: Date;
+  updatedAt: Date;
+}
+interface SshKeysManager {
+  create(name: string, publicKey: string): Promise<SshKeyInfo>;
+  list(): Promise<SshKeyInfo[]>;
+  delete(id: string): Promise<void>;
+}
 /**
  * Secrets manager for storing and retrieving encrypted secrets.
  * Access via `client.secrets`.
@@ -2452,12 +3709,10 @@ interface DeleteOptions {
   recursive?: boolean;
 }
 /**
- * Enhanced file system operations for sandboxes.
- * Access via `sandbox.fs`.
+ * File system operations for sandboxes. Access via `sandbox.fs`.
  *
- * Provides comprehensive file operations beyond basic read/write,
- * including binary file upload/download, directory operations,
- * and progress reporting for large files.
+ * Beyond basic read/write: binary upload/download, directory operations,
+ * progress reporting for large files.
  *
  * @example Upload and download files
  * ```typescript
@@ -2672,6 +3927,262 @@ interface FileSystem {
    */
   exists(path: string): Promise<boolean>;
 }
+/** Languages supported by the persistent code kernel. */
+type CodeLanguage = "python" | "node" | "typescript" | "bash";
+/**
+ * One structured result produced by a runCode() call. The kernel emits these
+ * alongside stdout — matplotlib figures arrive as `image`, pandas DataFrames
+ * as `dataframe`, explicit `display(value)` calls as `json` or `html`, and
+ * uncaught exceptions as `error` plus an `error` field on the result.
+ */
+type CodeResultPart = {
+  type: "text";
+  value: string;
+} | {
+  type: "json";
+  value: unknown;
+} | {
+  type: "image";
+  format: "png" | "jpeg" | "svg"; /** base64-encoded image bytes (no `data:` prefix). */
+  data: string;
+} | {
+  type: "html";
+  value: string;
+} | {
+  type: "dataframe";
+  columns: {
+    name: string;
+    dtype: string;
+  }[];
+  rows: unknown[][];
+  truncated: boolean;
+} | {
+  type: "error";
+  name: string;
+  message: string;
+  traceback?: string;
+};
+/**
+ * Outcome of a single runCode() call.
+ *
+ * `stdout`/`stderr` are the user-visible streams with frame markers stripped.
+ * `results` is the structured-result list. `error` is set when user code
+ * raised; the kernel itself stays alive and the next call reuses its state.
+ */
+interface CodeExecutionResult {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+  durationMs: number;
+  results: CodeResultPart[];
+  error?: {
+    name: string;
+    message: string;
+    traceback?: string;
+  };
+}
+/** Options for `box.runCode()`. */
+interface CodeExecutionOptions {
+  /** Session scope: kernels persist variables across calls with the same id. */
+  sessionId?: string;
+  /** Per-call timeout in ms. 0 disables. Default 60_000. */
+  timeoutMs?: number;
+  /** Extra env vars merged in for this call only. */
+  env?: Record<string, string>;
+  /** Working directory override (honored on kernel creation only). */
+  cwd?: string;
+  /**
+   * Caller-supplied dedup key. Two `runCode` calls with the same key and
+   * the same `sessionId` within a 15-minute window return the same result
+   * without re-executing — including the case where the second call arrives
+   * while the first is still running (it awaits the in-flight result).
+   *
+   * Scoped per `sessionId` so two sessions reusing the same key stay
+   * isolated. A failed execution is not cached; a retry with the same key
+   * gets a fresh attempt.
+   *
+   * For exactly-once across an outer agent loop (multi-turn tool use), pair
+   * with `box.dispatchPrompt({ sessionId, turnId })` — the agent layer
+   * dedups the whole loop, this one dedups a single code-exec call.
+   */
+  idempotencyKey?: string;
+}
+//#endregion
+//#region src/mcp.d.ts
+/**
+ * MCP (Model Context Protocol) helpers for sandbox capabilities.
+ *
+ * The sandbox exposes capabilities (currently `computer_use`, more
+ * later) as MCP tools over Streamable HTTP. Any MCP-capable client —
+ * Claude Desktop, Cursor, claude-code, codex, opencode, raw
+ * `@modelcontextprotocol/sdk` apps — can consume this surface by
+ * pasting the JSON returned from `Sandbox#getMcpEndpoint()` (or
+ * `buildSandboxMcpConfig` if you already have the URL + token) into
+ * the client's MCP config.
+ *
+ * Security model:
+ *   - Tokens are capability-scoped JWTs (claim `cap: ["computer_use"]`).
+ *   - Full sandbox runtime tokens are rejected on `/mcp`; only
+ *     capability-scoped tokens work there.
+ *   - A scoped token cannot pivot to admin endpoints (`/exec`, `/files`,
+ *     etc.) — those routes reject scoped tokens.
+ *   - Tokens are short-lived. Rotate via `Sandbox#getMcpEndpoint()`,
+ *     which mints a fresh token each call.
+ */
+/** Default name of the MCP server entry — surfaces in the host UI. */
+declare const SANDBOX_MCP_SERVER_NAME = "tangle-sandbox";
+/**
+ * MCP HTTP server entry — matches the Anthropic MCP HTTP transport
+ * schema (`type: "http"`, `url`, optional `headers`). Compatible with
+ * every MCP host that implements the spec.
+ */
+interface SandboxMcpServerEntry {
+  type: "http";
+  url: string;
+  headers: Record<string, string>;
+}
+/**
+ * `.mcp.json`-shaped config any MCP host accepts. Drop the contents of
+ * `mcpServers` into your host's `mcpServers` block (Claude Desktop,
+ * Cursor, claude-code's `--mcp-config`, etc.) — no host-specific
+ * fields, no provider lock-in.
+ */
+interface SandboxMcpConfig {
+  mcpServers: Record<string, SandboxMcpServerEntry>;
+}
+/**
+ * Endpoint payload returned by `GET /v1/sandboxes/:id/mcp`. Includes
+ * the canonical config plus token expiry so callers can plan
+ * refreshes.
+ */
+interface SandboxMcpEndpoint {
+  /** MCP host config — paste this into Cursor/Claude Desktop/etc. */
+  config: SandboxMcpConfig;
+  /** Server entry name used inside `config.mcpServers`. */
+  serverName: string;
+  /** Reachable URL for the MCP HTTP transport. */
+  url: string;
+  /** Bearer token sent by the MCP host on every request. */
+  authToken: string;
+  /** ISO-8601 expiry — the host should refresh before this. */
+  expiresAt: string;
+  /** Capabilities the token is scoped to. */
+  capabilities: ReadonlyArray<"computer_use">;
+}
+interface BuildSandboxMcpConfigOptions {
+  /** Public sandbox URL where `/mcp` is reachable. No trailing slash. */
+  sandboxUrl: string;
+  /** Capability-scoped JWT minted by the Sandbox API. */
+  authToken: string;
+  /** Override the entry name. Defaults to SANDBOX_MCP_SERVER_NAME. */
+  serverName?: string;
+}
+/**
+ * Build the canonical `mcpServers` config for a sandbox MCP endpoint.
+ * Pure function — no I/O, no crypto. Use this when you already have a
+ * `{ url, authToken }` pair from the API and just want the JSON shape
+ * to paste into a host. Most callers should use
+ * `Sandbox#getMcpEndpoint()` instead, which fetches a freshly-minted
+ * token from the API.
+ */
+declare function buildSandboxMcpConfig(options: BuildSandboxMcpConfigOptions): {
+  serverName: string;
+  config: SandboxMcpConfig;
+};
+//#endregion
+//#region src/session.d.ts
+/**
+ * The subset of `SandboxInstance` a `SandboxSession` drives. Declared here
+ * (rather than importing the concrete class) so `session.ts` stays a leaf
+ * of `sandbox.ts` — `sandbox.ts` constructs `SandboxSession`, so the reverse
+ * import would form a cycle. `SandboxInstance` satisfies this structurally.
+ */
+interface SandboxSessionHost {
+  prompt(message: string | PromptInputPart[], options?: PromptOptions): Promise<PromptResult>;
+  _sessionStatus(id: string): Promise<SessionInfo | null>;
+  _sessionEvents(id: string, opts?: SessionEventStreamOptions): AsyncGenerator<SandboxEvent>;
+  _sessionResult(id: string): Promise<PromptResult>;
+  _sessionCancel(id: string): Promise<void>;
+}
+/**
+ * A single agent session inside a sandbox. Created via
+ * `box.session(id)` — does not hit the network until a method is called.
+ */
+declare class SandboxSession {
+  private readonly box;
+  /** Stable session id assigned by the sandbox runtime. */
+  readonly id: string;
+  /**
+   * @internal SDK-internal constructor — apps should call `box.session(id)`.
+   */
+  constructor(box: SandboxSessionHost, /** Stable session id assigned by the sandbox runtime. */
+
+  id: string);
+  /**
+   * Fetch the current session state from the sandbox. Includes status,
+   * model, prompt count, token usage if known, and timing metadata.
+   *
+   * Throws on transport error; returns `null` if the session id is not
+   * known to the sandbox (e.g. it ended and was reaped, or the id is
+   * invalid).
+   */
+  status(): Promise<SessionInfo | null>;
+  /**
+   * Stream events from this session as they arrive. With no `since`,
+   * starts at the live tail; with `since`, replays from that event id
+   * forward — useful for reconnect-after-disconnect flows.
+   *
+   * The async iterator terminates when the session reaches a terminal
+   * state (`completed`, `failed`, `cancelled`) and the corresponding
+   * terminal event has been yielded, OR when the caller's signal aborts.
+   */
+  events(opts?: SessionEventStreamOptions): AsyncGenerator<SandboxEvent>;
+  /**
+   * Await the session's terminal result. Polls status + drains events
+   * until the session reaches a terminal state, then returns the
+   * aggregated `PromptResult`.
+   *
+   * Use this to wait for a session that was started by another caller
+   * (e.g. `dispatchPrompt`).
+   */
+  result(): Promise<PromptResult>;
+  /**
+   * 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
 /**
@@ -2679,6 +4190,7 @@ interface FileSystem {
  */
 interface HttpClient {
   fetch(path: string, options?: RequestInit): Promise<Response>;
+  getApiKey?(): string | undefined;
 }
 /**
  * Git capability for repository operations.
@@ -2755,9 +4267,26 @@ declare class SandboxInstance {
   /** Web terminal URL for browser-based access */
   get url(): string | undefined;
   /**
-   * Serialize to the public sandbox shape for CLI JSON output.
+   * 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.
    *
@@ -2766,6 +4295,30 @@ declare class SandboxInstance {
    * 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.
    */
@@ -2828,10 +4381,39 @@ declare class SandboxInstance {
    * Throws if SSH is not enabled or sandbox is not running.
    */
   ssh(): Promise<SSHCredentials>;
+  sshCommand(): Promise<SSHCommandDescriptor>;
   /**
    * Execute a command in the sandbox.
    */
   exec(command: string, options?: ExecOptions): Promise<ExecResult>;
+  /**
+   * Run code in a persistent language kernel.
+   *
+   * Each `(sessionId, language)` pair gets its own long-lived kernel that
+   * keeps variable state across calls — like Jupyter cells. Without a
+   * `sessionId`, calls share a process-wide kernel per language.
+   *
+   * Returns typed results: stdout/stderr text plus a `results` array of
+   * structured outputs (matplotlib images as base64 PNG, pandas DataFrames,
+   * explicit `display(value)` calls as JSON/HTML, errors with traceback).
+   *
+   * @example Persistent Python session
+   * ```ts
+   * await box.runCode("python", "import pandas as pd; df = pd.DataFrame({'x': range(5)})", { sessionId: "s1" });
+   * const r = await box.runCode("python", "df.describe()", { sessionId: "s1" });
+   * // r.results[0] is a `dataframe` part with columns + rows from the describe()
+   * ```
+   *
+   * @example Matplotlib chart
+   * ```ts
+   * const r = await box.runCode("python",
+   *   "import matplotlib.pyplot as plt; plt.plot([1,2,3,4]); plt.show()",
+   *   { sessionId: "s1" });
+   * const png = r.results.find(p => p.type === "image");
+   * // png.data is a base64 PNG ready to render or hand back to an LLM
+   * ```
+   */
+  runCode(language: CodeLanguage, source: string, options?: CodeExecutionOptions): Promise<CodeExecutionResult>;
   /**
    * Read a file from the sandbox.
    *
@@ -2881,6 +4463,21 @@ declare class SandboxInstance {
    * Stream sandbox lifecycle and activity events.
    */
   events(options?: EventStreamOptions): AsyncGenerator<SandboxEvent>;
+  trace(options?: SandboxTraceOptions): Promise<SandboxTraceBundle>;
+  intelligence(): Promise<NonNullable<SandboxTraceBundle["intelligence"]>>;
+  createIntelligenceReport(options?: {
+    mode?: "deterministic" | "agentic";
+    acknowledgeCost?: boolean;
+    budget?: IntelligenceReportBudget;
+    metadata?: Record<string, unknown>; /** Bound the analysis to a time window. */
+    window?: IntelligenceReportWindow; /** Compare this sandbox against a same-type baseline sandbox. */
+    compareTo?: IntelligenceReportCompareTo;
+  }): Promise<IntelligenceReport>;
+  createAgenticIntelligenceReport(options: {
+    maxUsd: number;
+    metadata?: Record<string, unknown>;
+  }): Promise<IntelligenceReport>;
+  exportTrace(sink: TraceExportSink): Promise<TraceExportResult>;
   /**
    * Stream real-time provisioning progress events.
    *
@@ -2999,12 +4596,10 @@ declare class SandboxInstance {
    */
   get tools(): ToolsCapability;
   /**
-   * Enhanced file system operations.
-   *
-   * Provides comprehensive file operations beyond basic read/write:
-   * - Binary file upload/download
-   * - Directory operations (uploadDir, downloadDir, list, mkdir)
-   * - File metadata (stat, exists)
+   * 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
@@ -3084,6 +4679,13 @@ declare class SandboxInstance {
    *   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;
@@ -3091,6 +4693,22 @@ declare class SandboxInstance {
   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.
@@ -3454,6 +5072,82 @@ declare class SandboxInstance {
   }): 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>;
+  /**
+   * List messages for a session, including in-flight assistant content
+   * the agent is still streaming. Each entry's `metadata` carries the
+   * durability marker — `status: "streaming" | "completed" | "interrupted"`,
+   * `completed/interrupted` booleans, and the caller-supplied `turnId`
+   * when one was set. See `SessionMessage` for the full contract.
+   *
+   * Polling this is the right way to detect "did the sidecar die mid-
+   * turn?" — a SIGKILL leaves the assistant message with `status:
+   * "streaming"` and no `completed`/`interrupted` marker; a graceful
+   * abort stamps `interrupted: true` explicitly.
+   */
+  messages(opts: ListMessagesOptions): Promise<SessionMessage[]>;
+  /**
+   * Look up a cached turn result by idempotency key. Returns the cached
+   * payload if a turn with this `turnId` previously completed on the
+   * given session; returns `null` if no such turn has finished yet
+   * (either it never started, or it interrupted before completion).
+   *
+   * Call this before re-issuing a `streamPrompt` / `prompt` / `task`
+   * that you might be retrying — a non-null result means the original
+   * attempt finished and you can return that to your caller instead of
+   * running the agent a second time. Only turns that reach the
+   * `completed` terminal state are cached; interrupted turns are not.
+   */
+  findCompletedTurn(turnId: string, opts: {
+    sessionId: string;
+  }): Promise<CompletedTurnResult | null>;
+  /**
+   * 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 { Process as $, AgentProfileResourceRef as $t, ExecResult as A, StorageConfig as At, GitStatus as B, UpdateUserOptions as Bt, DownloadOptions as C, SearchMatch as Ct, DriverType as D, SnapshotInfo as Dt, DriverInfo as E, SecretsManager as Et, GitAuth as F, TeeAttestationReport as Ft, McpServerConfig as G, AgentProfile as Gt, InstalledTool as H, UploadProgress as Ht, GitBranch as I, TeeAttestationResponse as It, NetworkManager as J, AgentProfileFileMount as Jt, MkdirOptions as K, AgentProfileCapabilities as Kt, GitCommit as L, TeePublicKey as Lt, FileSystem as M, TaskOptions as Mt, ForkOptions as N, TaskResult as Nt, EventStreamOptions as O, SnapshotOptions as Ot, ForkResult as P, TeeAttestationOptions as Pt, PreviewLinkManager as Q, AgentProfilePrompt as Qt, GitConfig as R, TeePublicKeyResponse as Rt, DirectoryPermission as S, SandboxUser as St, DriverConfig as T, SecretInfo as Tt, ListOptions as U, UsageInfo as Ut, GpuType as V, UploadOptions as Vt, ListSandboxOptions as W, WaitForOptions as Wt, PermissionsManager as X, AgentProfileModelHints as Xt, PermissionLevel as Y, AgentProfileMcpServer as Yt, PreviewLinkInfo as Z, AgentProfilePermissionValue as Zt, CheckpointOptions as _, SandboxEvent as _t, BackendCapabilities as a, defineGitHubResource as an, ProcessStatus as at, CreateSandboxOptions as b, SandboxResources as bt, BackendManager as c, ProvisionEvent as ct, BatchEvent as d, ProvisionStep as dt, AgentProfileResources as en, ProcessInfo as et, BatchOptions as f, RunCodeOptions as ft, CheckpointInfo as g, SandboxEnvironment as gt, BatchTaskResult as h, SandboxConnection as ht, AddUserOptions as i, defineAgentProfile as in, ProcessSpawnOptions as it, FileInfo as j, SubscriptionInfo as jt, ExecOptions as k, SnapshotResult as kt, BackendStatus as l, ProvisionResult as lt, BatchTask as m, SandboxClientConfig as mt, SandboxInstance as n, AgentProfileValidationResult as nn, ProcessManager as nt, BackendConfig as o, defineInlineResource as on, PromptOptions as ot, BatchResult as p, SSHCredentials as pt, NetworkConfig as q, AgentProfileConfidential as qt, AccessPolicyRule as r, AgentSubagentProfile as rn, ProcessSignal as rt, BackendInfo as s, mergeAgentProfiles as sn, PromptResult as st, HttpClient as t, AgentProfileValidationIssue as tn, ProcessLogEntry as tt, BackendType as u, ProvisionStatus as ut, CheckpointResult as v, SandboxInfo as vt, DownloadProgress as w, SearchOptions as wt, DeleteOptions as x, SandboxStatus as xt, CodeResult as y, SandboxPermissionsConfig as yt, GitDiff as z, ToolsConfig as zt };
+export { DriverInfo as $, SandboxTraceOptions as $n, ProvisionEvent as $t, BatchTask as A, SandboxFleetMachineSpec as An, UsageInfo as Ar, ListMessagesOptions as At, CompletedTurnResult as B, SandboxFleetUsage as Bn, AgentProfileResourceRef as Br, PermissionsManager as Bt, BackendInfo as C, SandboxFleetDriverCapability as Cn, TeePublicKey as Cr, GpuType as Ct, BatchEvent as D, SandboxFleetMachine as Dn, UpdateUserOptions as Dr, IntelligenceReportCompareTo as Dt, BackendType as E, SandboxFleetIntelligenceEnvelope as En, ToolsConfig as Er, IntelligenceReportBudget as Et, CodeExecutionOptions as F, SandboxFleetToken as Fn, AgentProfileFileMount as Fr, MintScopedTokenOptions as Ft, CreateSandboxOptions as G, SandboxInfo as Gn, defineAgentProfile as Gr, ProcessLogEntry as Gt, CreateSandboxFleetOptions as H, SandboxFleetWorkspaceReconcileResult as Hn, AgentProfileValidationIssue as Hr, PreviewLinkManager as Ht, CodeExecutionResult as I, SandboxFleetTraceBundle as In, AgentProfileMcpServer as Ir, MkdirOptions as It, DispatchPromptOptions as J, SandboxResources as Jn, mergeAgentProfiles as Jr, ProcessSpawnOptions as Jt, DeleteOptions as K, SandboxIntelligenceEnvelope as Kn, defineGitHubResource as Kr, ProcessManager as Kt, CodeLanguage as L, SandboxFleetTraceEvent as Ln, AgentProfileModelHints as Lr, NetworkConfig as Lt, CheckpointInfo as M, SandboxFleetManifestMachine as Mn, AgentProfile as Mr, ListSandboxFleetOptions as Mt, CheckpointOptions as N, SandboxFleetOperationsSummary as Nn, AgentProfileCapabilities as Nr, ListSandboxOptions as Nt, BatchOptions as O, SandboxFleetMachineMeteredUsage as On, UploadOptions as Or, IntelligenceReportSubjectType as Ot, CheckpointResult as P, SandboxFleetPolicy as Pn, AgentProfileConfidential as Pr, McpServerConfig as Pt, DriverConfig as Q, SandboxTraceExport as Qn, PromptResult as Qt, CodeResult as R, SandboxFleetTraceExport as Rn, AgentProfilePermissionValue as Rr, NetworkManager as Rt, BackendConfig as S, SandboxFleetDispatchResponse as Sn, TeeAttestationResponse as Sr, GitStatus as St, BackendStatus as T, SandboxFleetInfo as Tn, TokenRefreshHandler as Tr, IntelligenceReport as Tt, CreateSandboxFleetTokenOptions as U, SandboxFleetWorkspaceRestoreResult as Un, AgentProfileValidationResult as Ur, Process as Ut, CreateIntelligenceReportOptions as V, SandboxFleetWorkspace as Vn, AgentProfileResources as Vr, PreviewLinkInfo as Vt, CreateSandboxFleetWithCoordinatorOptions as W, SandboxFleetWorkspaceSnapshotResult as Wn, AgentSubagentProfile as Wr, ProcessInfo as Wt, DownloadOptions as X, SandboxTraceBundle as Xn, PromptInputPart as Xt, DispatchedSession as Y, SandboxStatus as Yn, ProcessStatus as Yt, DownloadProgress as Z, SandboxTraceEvent as Zn, PromptOptions as Zt, AcceleratorKind as _, SandboxEvent as _n, SubscriptionInfo as _r, GitAuth as _t, TraceExportSink as a, PublishPublicTemplateOptions as an, SecretInfo as ar, FileSystem as at, AttachSandboxFleetMachineOptions as b, SandboxFleetCostEstimate as bn, TeeAttestationOptions as br, GitConfig as bt, otelTraceIdForTangleTrace as c, ReapExpiredSandboxFleetsResult as cn, SessionInfo as cr, FleetDispatchResultBufferOptions as ct, BuildSandboxMcpConfigOptions as d, RunCodeOptions as dn, SessionStatus as dr, FleetExecDispatchResult as dt, ProvisionResult as en, SandboxUser as er, DriverType as et, SANDBOX_MCP_SERVER_NAME as f, SSHCommandDescriptor as fn, SnapshotInfo as fr, FleetMachineId as ft, buildSandboxMcpConfig as g, SandboxEnvironment as gn, StorageConfig as gr, ForkResult as gt, SandboxMcpServerEntry as h, SandboxConnection as hn, SshKeysManager as hr, ForkOptions as ht, TraceExportResult as i, PublicTemplateVersionInfo as in, SearchOptions as ir, FileInfo as it, BatchTaskResult as j, SandboxFleetManifest as jn, WaitForOptions as jr, ListOptions as jt, BatchResult as k, SandboxFleetMachineRecord as kn, UploadProgress as kr, IntelligenceReportWindow as kt, toOtelJson as l, ReconcileSandboxFleetsOptions as ln, SessionListOptions as lr, FleetDispatchStreamOptions as lt, SandboxMcpEndpoint as m, SandboxClientConfig as mn, SnapshotResult as mr, FleetPromptDispatchResult as mt, SandboxInstance as n, ProvisionStep as nn, ScopedTokenScope as nr, ExecOptions as nt, buildTraceExportPayload as o, PublishPublicTemplateVersionOptions as on, SecretsManager as or, FleetDispatchCancelResult as ot, SandboxMcpConfig as p, SSHCredentials as pn, SnapshotOptions as pr, FleetPromptDispatchOptions as pt, DirectoryPermission as q, SandboxPermissionsConfig as qn, defineInlineResource as qr, ProcessSignal as qt, TraceExportFormat as r, PublicTemplateInfo as rn, SearchMatch as rr, ExecResult as rt, exportTraceBundle as s, ReapExpiredSandboxFleetsOptions as sn, SessionEventStreamOptions as sr, FleetDispatchResultBuffer as st, HttpClient as t, ProvisionStatus as tn, ScopedToken as tr, EventStreamOptions as tt, SandboxSession as u, ReconcileSandboxFleetsResult as un, SessionMessage as ur, FleetExecDispatchOptions as ut, AccessPolicyRule as v, SandboxFleetArtifact as vn, TaskOptions as vr, GitBranch as vt, BackendManager as w, SandboxFleetDriverTimings as wn, TeePublicKeyResponse as wr, InstalledTool as wt, BackendCapabilities as x, SandboxFleetDispatchFailureClass as xn, TeeAttestationReport as xr, GitDiff as xt, AddUserOptions as y, SandboxFleetArtifactSpec as yn, TaskResult as yr, GitCommit as yt, CodeResultPart as z, SandboxFleetTraceOptions as zn, AgentProfilePrompt as zr, PermissionLevel as zt };