@tangle-network/sandbox 0.0.3

package/dist/sandbox-D-1E98ow.d.ts

@@ -0,0 +1,3332 @@
+//#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";
+/**
+ * Generic resource reference that can be resolved into a file or instruction.
+ */
+type AgentProfileResourceRef = {
+  kind: "inline";
+  name: string;
+  content: string;
+} | {
+  kind: "github";
+  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?: {
+  ref?: string;
+  name?: string;
+}): AgentProfileResourceRef;
+/**
+ * Resource mounted into a backend workspace.
+ */
+interface AgentProfileFileMount {
+  path: string;
+  resource: AgentProfileResourceRef;
+  executable?: boolean;
+}
+/**
+ * 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[];
+  /**
+   * Additional instructions injected into the agent context.
+   */
+  instructions?: string | AgentProfileResourceRef;
+}
+/**
+ * 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, AgentProfilePermissionValue>;
+  maxSteps?: number;
+  metadata?: Record<string, unknown>;
+}
+/**
+ * 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, AgentProfilePermissionValue>;
+  tools?: Record<string, boolean>;
+  mcp?: Record<string, AgentProfileMcpServer>;
+  subagents?: Record<string, AgentSubagentProfile>;
+  resources?: AgentProfileResources;
+  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;
+  };
+  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
+/**
+ * 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;
+}
+/**
+ * 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;
+}
+/**
+ * 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;
+}
+/**
+ * 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;
+  /**
+   * 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>;
+  /**
+   * 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;
+  /**
+   * 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;
+}
+/**
+ * SSH connection credentials.
+ */
+interface SSHCredentials {
+  /** SSH server hostname */
+  host: string;
+  /** SSH server port */
+  port: number;
+  /** Username for SSH authentication */
+  username: 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;
+}
+/**
+ * Options for listing sandboxes.
+ */
+interface ListSandboxOptions {
+  /** Filter by status */
+  status?: SandboxStatus | SandboxStatus[];
+  /** 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 */
+  cwd?: string;
+  /** Environment variables */
+  env?: Record<string, string>;
+  /** Timeout in milliseconds */
+  timeoutMs?: number;
+}
+/**
+ * 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;
+}
+/**
+ * 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 cap at 0 at the charge path (`capAtZero: true`).
+   *
+   * 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;
+}
+/**
+ * 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;
+  /**
+   * 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;
+}
+/**
+ * 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-enabled sandboxes.
+ */
+type GpuType = "nvidia-a100" | "nvidia-h100" | "nvidia-l4" | "amd-mi250";
+/**
+ * Infrastructure driver configuration.
+ *
+ * @example Default
+ * ```typescript
+ * driver: { type: "docker" }
+ * ```
+ *
+ * @example With pause/resume support
+ * ```typescript
+ * driver: { type: "firecracker", enableCriu: true }
+ * ```
+ *
+ * @example GPU-enabled sandbox
+ * ```typescript
+ * driver: {
+ *   type: "host-agent",
+ *   gpuRequired: true,
+ *   gpuType: "nvidia-a100",
+ * }
+ * ```
+ */
+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;
+  /** 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;
+}
+/**
+ * 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;
+  };
+}
+/**
+ * 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.
+ * - `"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.
+ * - `"cli-base"` — Minimal CLI-only (no AI agent).
+ */
+type BackendType = "opencode" | "claude-code" | "codex" | "amp" | "factory-droids" | "pi" | "hermes" | "forge" | "openclaw" | "acp" | "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[];
+  }>;
+}
+/**
+ * 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>;
+  /**
+   * 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;
+}
+/**
+ * Enhanced 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.
+ *
+ * @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/sandbox.d.ts
+/**
+ * HTTP client interface for making requests.
+ */
+interface HttpClient {
+  fetch(path: string, options?: RequestInit): Promise<Response>;
+}
+/**
+ * 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;
+  constructor(client: HttpClient, info: SandboxInfo);
+  /** 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 CLI JSON output.
+   */
+  toJSON(): 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;
+  /**
+   * Refresh sandbox information from the server.
+   */
+  refresh(): Promise<void>;
+  /**
+   * 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>;
+  /**
+   * 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): 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>;
+  /**
+   * 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;
+  /**
+   * 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)
+   * - 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"],
+   * });
+   * ```
+   */
+  get backend(): BackendManager;
+  private backendStatus;
+  private backendCapabilities;
+  private backendAddMcp;
+  private backendGetMcpStatus;
+  private backendUpdateConfig;
+  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;
+  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;
+}
+//#endregion
+export { Process as $, defineGitHubResource as $t, ExecResult as A, StorageConfig as At, GitStatus as B, AgentProfile as Bt, DownloadOptions as C, SearchMatch as Ct, DriverType as D, SnapshotInfo as Dt, DriverInfo as E, SecretsManager as Et, GitAuth as F, UpdateUserOptions as Ft, McpServerConfig as G, AgentProfilePermissionValue as Gt, InstalledTool as H, AgentProfileFileMount as Ht, GitBranch as I, UploadOptions as It, NetworkManager as J, AgentProfileResources as Jt, MkdirOptions as K, AgentProfilePrompt as Kt, GitCommit as L, UploadProgress as Lt, FileSystem as M, TaskOptions as Mt, ForkOptions as N, TaskResult as Nt, EventStreamOptions as O, SnapshotOptions as Ot, ForkResult as P, ToolsConfig as Pt, PreviewLinkManager as Q, defineAgentProfile as Qt, GitConfig as R, UsageInfo as Rt, DirectoryPermission as S, SandboxUser as St, DriverConfig as T, SecretInfo as Tt, ListOptions as U, AgentProfileMcpServer as Ut, GpuType as V, AgentProfileCapabilities as Vt, ListSandboxOptions as W, AgentProfileModelHints as Wt, PermissionsManager as X, AgentProfileValidationResult as Xt, PermissionLevel as Y, AgentProfileValidationIssue as Yt, PreviewLinkInfo as Z, AgentSubagentProfile as Zt, CheckpointOptions as _, SandboxEvent as _t, BackendCapabilities as a, ProcessStatus as at, CreateSandboxOptions as b, SandboxResources as bt, BackendManager as c, ProvisionEvent as ct, BatchEvent as d, ProvisionStep as dt, defineInlineResource 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, 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, ProcessManager as nt, BackendConfig as o, PromptOptions as ot, BatchResult as p, SSHCredentials as pt, NetworkConfig as q, AgentProfileResourceRef as qt, AccessPolicyRule as r, ProcessSignal as rt, BackendInfo as s, PromptResult as st, HttpClient as t, mergeAgentProfiles 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, WaitForOptions as zt };