@namzu/sandbox 1.1.0

package/dist/index.d.ts

@@ -0,0 +1,611 @@
+/**
+ * @namzu/sandbox — pluggable sandbox provider for @namzu/sdk.
+ *
+ * The SDK already declares a `SandboxProvider` shape in
+ * `@namzu/sdk` (`packages/sdk/src/types/sandbox/index.ts`). This
+ * package implements that shape with concrete BACKENDS picked at
+ * construction time. The set is aligned with the 2026 industrial
+ * standard for AI-agent code-execution sandboxes:
+ *
+ *  • `docker` — plain OCI container per task, seccomp default
+ *    profile, tmpfs workdir, no-network-by-default. The universal
+ *    fallback every namzu host gets locally with `docker compose`
+ *    and on every Linux replica in any cloud. What Northflank /
+ *    Railway / Render / Compass-platform / GitHub Actions runners
+ *    actually ship for code execution. Trust boundary: namespaces.
+ *
+ *  • `e2b` — adapter for E2B's managed Firecracker microVM service
+ *    (`e2b.dev`). Sub-second cold-start via snapshot/restore, full
+ *    kernel-level trust boundary. The SaaS-friendly path to real
+ *    Firecracker isolation without running our own scheduler.
+ *
+ *  • `fly-machines` — adapter for Fly Machines (`fly.io/docs/machines`).
+ *    Also Firecracker microVMs; closer to bare-metal control than
+ *    E2B, useful when the workload is more "arbitrary tool calls"
+ *    than "Python REPL".
+ *
+ *  • `firecracker` — self-hosted `firecracker-containerd` on bare
+ *    metal (or KVM-enabled cloud instance). For hosts that need
+ *    Firecracker isolation AND insist on running the scheduler
+ *    themselves. Tier 3 isolation, highest operational cost.
+ *
+ *  • `gvisor` — adapter for `runsc` runtime (Google's userspace
+ *    kernel). What OpenAI Code Interpreter and Modal Labs ship.
+ *    Trusted-tenant tier with near-zero cold-start; runs on
+ *    commodity Linux without nested virt. Locally via Linux Docker
+ *    runtime; not available on macOS Docker Desktop.
+ *
+ *  • `passthrough` — no isolation, runs commands directly. For
+ *    tests and trusted environments only. Off by default; opt-in.
+ *
+ * **What we deliberately do NOT build** is yet-another Firecracker
+ * scheduler — that is E2B's and Fly's entire product, and writing
+ * our own is a years-long detour. We adapt to theirs.
+ *
+ * **Cloud portability:** the backend interface is cloud-agnostic.
+ * `docker` works on every cloud; `e2b` and `fly-machines` are
+ * managed services not tied to any cloud; `firecracker` and
+ * `gvisor` need infrastructure the host chooses (GKE Sandbox, AWS
+ * Fargate, self-hosted KVM, etc.). Picking a stronger backend may
+ * imply moving cloud — that's the host's call, not the SDK's.
+ *
+ * **Local dev story:** Phase 1 (`docker`) runs everywhere. Phase 2
+ * (`e2b` / `fly-machines`) hits the managed service from a dev
+ * laptop with no infra setup. Phase 3 (`firecracker` / `gvisor`)
+ * needs Lima/Colima on macOS or native KVM on Linux — only the
+ * adversarial-multi-tenant prod path needs that and it's clearly
+ * documented as such.
+ *
+ * This file is the public surface. Concrete backend implementations
+ * land under `./backends/<kind>/` in subsequent commits — the
+ * `SandboxBackend` interface here is the contract they implement.
+ *
+ * Refs: `e2b.dev/docs/sandbox`, `fly.io/docs/machines`,
+ * `firecracker-microvm.github.io`, `gvisor.dev/docs`,
+ * `cloud.google.com/kubernetes-engine/docs/concepts/sandbox-pods`,
+ * `aws.amazon.com/blogs/aws/firecracker-lightweight-virtualization-for-serverless-computing`.
+ */
+import type { ContainerSandboxLayout, Sandbox, SandboxProvider } from '@namzu/sdk';
+export type { ContainerSandboxLayout, ContainerSandboxLayoutMount, ContainerSandboxMountSource, ContainerSandboxSkillMount, ResolvedContainerSandboxLayout, } from '@namzu/sdk';
+export { SANDBOX_DEFAULT_OUTPUTS_PATH, SANDBOX_DEFAULT_SKILLS_PARENT, SANDBOX_DEFAULT_TOOL_RESULTS_PATH, SANDBOX_DEFAULT_TRANSCRIPTS_PATH, SANDBOX_DEFAULT_UPLOADS_PATH, } from '@namzu/sdk';
+export type { FirecrackerBackendInternalConfig, OrchestratorTokenProvider, } from './backends/firecracker/index.js';
+export { type SandboxAgentHandle, type VsockTransportOptions, VsockAgentTransport, } from './backends/firecracker/transport.js';
+/**
+ * Top-level sandbox tier. Each tier is a use-case bucket:
+ *
+ *   - `process` — the agent runs on the developer's own host;
+ *     the sandbox keeps it from reading `~/.ssh` or running
+ *     `rm -rf ~`. Single-user; no multi-tenancy. What Anthropic
+ *     ships with Claude Code via `@anthropic-ai/sandbox-runtime`.
+ *
+ *   - `container` — the agent runs inside an OCI container per
+ *     task. Same code path locally (`docker compose`) and on
+ *     Linux replicas in any cloud. The default for "trusted
+ *     prompts, contained workloads" — Northflank, Railway,
+ *     Render, Compass-platform, GitHub Actions runners all
+ *     ship this tier.
+ *
+ *   - `microvm` — the agent runs inside a Firecracker microVM
+ *     per task. Hardware-virtualization trust boundary; the
+ *     industry standard for adversarial multi-tenancy
+ *     (AWS Lambda/Fargate, Fly Machines, Replit, E2B, Daytona
+ *     all converged here). Sub-second cold-start via
+ *     snapshot/restore.
+ *
+ *   - `passthrough` — no isolation; for tests and explicitly
+ *     trusted environments.
+ *
+ * The concrete implementation inside a tier is picked via the
+ * tier-specific config (see {@link ProcessBackendConfig},
+ * {@link ContainerBackendConfig}, {@link MicroVMBackendConfig}).
+ */
+export type SandboxTier = 'process' | 'container' | 'microvm' | 'passthrough';
+/**
+ * Discriminated union of sandbox backend configurations. Each
+ * tier has its own configuration shape — picking a tier picks the
+ * shape automatically via TS narrowing.
+ */
+export type SandboxBackendConfig = ProcessBackendConfig | ContainerBackendConfig | ACIStandbyPoolBackendConfig | MicroVMBackendConfig | PassthroughBackendConfig;
+/**
+ * Azure Container Instances Standby Pool backend. Container tier,
+ * managed-microvm-ish: every claim is a fresh ACI container group
+ * pre-warmed in an Azure-managed standby pool (`Microsoft.StandbyPool`).
+ * ~1.5 s claim latency vs ~10-30 s for cold ACI spawn. Trust boundary
+ * = Microsoft's ACI isolation host (gVisor-equivalent depending on
+ * SKU; AMD SEV-SNP TEE when the pool is created with sku=Confidential).
+ *
+ * No host filesystem — workspace mounts ride `azureFileShare` sources
+ * (the host provisions a per-task Azure Files share upstream and
+ * threads it into the layout). Auth via a caller-supplied
+ * `getArmToken()` callback so the sandbox package stays free of
+ * Azure SDK dependencies; the host runtime owns Managed Identity /
+ * AzureCLI / federated credential picking.
+ *
+ * Use this when (a) running on Azure Container Apps and you cannot
+ * mount the docker socket, (b) you want per-task container
+ * isolation without operating a Firecracker host yourself, and
+ * (c) sub-2-second claim latency is acceptable.
+ */
+export interface ACIStandbyPoolBackendConfig {
+    readonly tier: 'container';
+    readonly runtime: 'aci-standby-pool';
+    readonly subscriptionId: string;
+    readonly resourceGroup: string;
+    readonly location: string;
+    readonly standbyPoolResourceId: string;
+    readonly containerGroupProfileResourceId: string;
+    readonly containerGroupProfileRevision?: number;
+    /**
+     * Async callback returning a fresh ARM bearer token (audience
+     * `https://management.azure.com/`). Invoked on every ARM call.
+     */
+    readonly getArmToken: () => Promise<string>;
+    readonly subnetId?: string;
+    readonly readyPollIntervalMs?: number;
+    readonly readyTimeoutMs?: number;
+    readonly workerPort?: number;
+    readonly armApiVersion?: string;
+    /**
+     * Prefix for the ACI container group name and the inner worker
+     * container. Combined with a generated sandbox id and
+     * sanitised to ARM's allowed character set. Default
+     * `namzu-task`; consumers (e.g. Vandal) override to brand
+     * their own deployments.
+     */
+    readonly containerNamePrefix?: string;
+}
+/**
+ * `process` tier. Auto-detects the platform's native primitive
+ * unless overridden:
+ *
+ *   - `bubblewrap` on Linux / WSL2 (`bwrap`)
+ *   - `seatbelt` on macOS (`sandbox-exec`)
+ *
+ * Both are what `@anthropic-ai/sandbox-runtime` ships. Cold-start
+ * is process spawn (~ms). Use this when the agent runs on the
+ * end-user's developer machine — Claude Code's deployment model.
+ */
+export interface ProcessBackendConfig {
+    readonly tier: 'process';
+    readonly engine?: 'auto' | 'bubblewrap' | 'seatbelt';
+}
+/**
+ * `container` tier. Two runtime options:
+ *
+ *   - `docker` (default) — plain OCI container on the host's
+ *     Docker daemon. No special runtime required.
+ *   - `runsc` — Google's gVisor userspace-kernel runtime. Stronger
+ *     isolation (syscall-table separation), runs on commodity
+ *     Linux without nested virt. Trusted-tenant tier; what OpenAI
+ *     Code Interpreter and Modal Labs ship. Requires the
+ *     `runsc` runtime installed on the Docker daemon (Linux only;
+ *     Docker Desktop on macOS does not support it). See
+ *     `gvisor.dev/docs/user_guide/quick_start/docker`.
+ *
+ * `image` is the container image to spawn per task. The package
+ * ships a reference Dockerfile (compass-platform pattern) with
+ * Python doc-gen libraries, LibreOffice, pandoc, Chromium, and
+ * `tesseract` pre-installed; hosts that want a leaner image
+ * supply their own.
+ */
+export interface ContainerBackendConfig {
+    readonly tier: 'container';
+    readonly runtime?: 'docker' | 'runsc';
+    readonly image: string;
+    /**
+     * How the SDK consumer reaches the in-container worker. Default
+     * `'host-port'` — the original loopback host-port flow, works
+     * when the consumer runs ON the docker host. Set
+     * `'container-network'` when the consumer is itself a container
+     * spawning siblings via the host's Docker daemon: the worker is
+     * reachable at `http://<containerName>:2024` over the docker
+     * bridge named in `network`.
+     */
+    readonly hostReachability?: 'host-port' | 'container-network';
+    /**
+     * Docker network the spawned container attaches to. Default
+     * `'none'` (no inbound or outbound network). Set to a docker
+     * bridge name when `hostReachability='container-network'` so the
+     * SDK consumer (also on that bridge) can reach the worker by
+     * container DNS name. Egress from the sandbox is governed
+     * separately by `EgressPolicy`.
+     */
+    readonly network?: 'none' | 'bridge' | string;
+    /**
+     * Optional `--label key=value` pairs applied to the spawned
+     * container. Hosts use this to make the container findable from
+     * out-of-band cleanup paths (reaper jobs, monitoring filters)
+     * via `docker ps --filter label=...`. Keys with `=` or empty
+     * names are rejected at construction; values are passed verbatim
+     * to the docker CLI argv (no shell interpolation — `spawn` argv
+     * not a shell pipeline). Default unset (no extra labels).
+     *
+     * Convention for namzu hosts: namespace your keys
+     * (`vandal.sandbox=true`, `vandal.task-id=<id>`, …) to avoid
+     * collisions with Docker / orchestrator labels.
+     */
+    readonly labels?: Readonly<Record<string, string>>;
+}
+/**
+ * `microvm` tier. Three concrete services, all Firecracker under
+ * the hood:
+ *
+ *   - `e2b` — adapter for E2B's managed sandbox service
+ *     (`e2b.dev`). TS SDK does the scheduler work; namzu wraps it.
+ *     ~150ms cold-start (snapshot/restore). Apache-2.0 server side,
+ *     so the same code path can run against self-hosted E2B if
+ *     the host eventually wants to leave the managed service.
+ *   - `fly-machines` — adapter for Fly Machines
+ *     (`fly.io/docs/machines`). Closer to bare-metal control than
+ *     E2B; the right tier when the workload is "arbitrary tool
+ *     calls" rather than "Python REPL".
+ *   - `self-hosted` — direct `firecracker-containerd` against a
+ *     KVM-enabled host. For deployments where E2B and Fly are
+ *     both off the table for policy reasons. Operationally the
+ *     heaviest path; everything below ships first.
+ *
+ * Local dev: `e2b` and `fly-machines` work from any laptop with
+ * an API key (no infra setup). `self-hosted` requires Linux + KVM
+ * (Lima/Colima on macOS).
+ */
+export type MicroVMBackendConfig = {
+    readonly tier: 'microvm';
+    readonly service: 'e2b';
+    readonly apiKey: string;
+    readonly template?: string;
+} | {
+    readonly tier: 'microvm';
+    readonly service: 'fly-machines';
+    readonly apiToken: string;
+    readonly app: string;
+    readonly image: string;
+    readonly region?: string;
+} | {
+    readonly tier: 'microvm';
+    readonly service: 'self-hosted';
+    readonly firecrackerBinary: string;
+    readonly kernelImage: string;
+    readonly rootfsImage: string;
+    /**
+     * The owned-platform seam (ses_051). When these are present the
+     * `self-hosted` arm targets the OWNED Azure Firecracker
+     * orchestrator (`backends/firecracker/`), not a local
+     * `firecracker-containerd`: `orchestratorEndpoint` is the
+     * control-plane base URL, `getToken` mints a bearer for it
+     * (the ACI `getArmToken` closure pattern, so this package keeps
+     * zero Azure-SDK deps), and `template` selects the golden
+     * snapshot revision to CoW-resume.
+     *
+     * The legacy local-`firecracker-containerd` shape
+     * (`firecrackerBinary`/`kernelImage`/`rootfsImage` only) is
+     * still NOT implemented and throws
+     * {@link SandboxBackendNotImplementedError}; supplying
+     * `orchestratorEndpoint` is what routes to the owned backend.
+     */
+    readonly orchestratorEndpoint?: string;
+    readonly getToken?: () => Promise<string>;
+    readonly template?: string;
+    /**
+     * Resume this per-agent captured snapshot (layered on its base
+     * golden) INSTEAD of a fresh golden boot. Tier-agnostic, additive,
+     * optional: the backend that supports it (the owned firecracker
+     * backend) honors it; others ignore it. Absent ⇒ the create body is
+     * byte-identical and the generic golden-resume hot path is unchanged
+     * (the field is only ever set by the host's per-agent trigger path).
+     * Sibling to `template` (base-golden selector) — see
+     * {@link AgentSnapshotRef}.
+     */
+    readonly agentSnapshot?: AgentSnapshotRef;
+    /** Fixed guest AF_VSOCK port the in-VM agent listens on. */
+    readonly agentVsockPort?: number;
+    readonly readyTimeoutMs?: number;
+    readonly readyPollIntervalMs?: number;
+    /**
+     * NETWORK-mode mTLS client material (ses_051 P4 client-proxy
+     * bridge). When present, the orchestrator returns an `mtls` agent
+     * handle (host/port/sandboxId, NO cert material) and this CA/cert/key
+     * is MERGED onto that handle before the transport dials the per-host
+     * relay over mTLS. Injected by the consumer's runtime (the Vandal
+     * host layer reads it from `VANDAL_SANDBOX_FC_TLS_*`), NEVER fetched
+     * inside this package — same dependency boundary as `getToken`, so
+     * `@namzu/sandbox` stays Azure-SDK-free. Absent for the single-host
+     * VSOCK default (the live proofs).
+     */
+    readonly mtls?: {
+        readonly ca: string | Buffer;
+        readonly cert: string | Buffer;
+        readonly key: string | Buffer;
+        readonly servername?: string;
+    };
+    /**
+     * CONTROL-plane mTLS client material. When present, the orchestrator
+     * control-plane calls (create/destroy POSTs to `orchestratorEndpoint`)
+     * dial over mTLS — presenting this client cert and pinning this CA —
+     * instead of plain `fetch`. Secures the control plane when
+     * `orchestratorEndpoint` is an `https://` URL reached over the PUBLIC
+     * internet (the non-VNet-integrated caller→FC-host hop), where the
+     * shared-secret bearer alone would be exposed. The bearer is STILL sent
+     * (defense in depth). Same `{ca,cert,key,servername}` shape + the same
+     * consumer-injected dependency boundary as `mtls` (the one fleet CA
+     * secures both planes). Absent → plain `fetch` control plane (the
+     * single-host VSOCK default, unchanged).
+     */
+    readonly controlPlaneMtls?: {
+        readonly ca: string | Buffer;
+        readonly cert: string | Buffer;
+        readonly key: string | Buffer;
+        readonly servername?: string;
+    };
+};
+/**
+ * A reference to a per-agent captured snapshot, layered on top of a base
+ * golden revision. Provider-AGNOSTIC: this is a sandbox-spec concept, a
+ * sibling to {@link MicroVMBackendConfig}'s `template` (which selects a
+ * base golden), not a provider-specific shape — hence no provider prefix
+ * in the name. A microVM backend that supports per-agent resume (the owned
+ * Firecracker backend) honors it by resuming this agent's captured diff
+ * INSTEAD of a fresh golden boot; backends that do not support it ignore it.
+ *
+ * The triple identifies exactly one captured snapshot: the owning tenant
+ * (`orgId`), the agent registry row (`agentId`), and the registry version
+ * (`version`, a decimal string so the whole triple is a set of path
+ * segments). The host constructs this server-side from its own registry;
+ * `@namzu/sandbox` only forwards it.
+ */
+export interface AgentSnapshotRef {
+    readonly orgId: string;
+    readonly agentId: string;
+    readonly version: string;
+}
+/**
+ * `passthrough` tier. No isolation — runs commands directly in
+ * the host process. Tests and trusted environments only.
+ */
+export interface PassthroughBackendConfig {
+    readonly tier: 'passthrough';
+}
+/**
+ * Egress allowlist resolution. Host-supplied policy decides whether
+ * an outbound request is allowed before the proxy opens a socket.
+ *
+ * Four shapes:
+ *
+ *   - `deny-all` — default. Reject every outbound request.
+ *   - `allow-all` — accept every outbound request. Tests only.
+ *   - `static` — fixed allowlist of hostnames at construction.
+ *   - `resolver` — async closure returning the allowlist.
+ *     Parameterless **on purpose**: the resolver is a closure that
+ *     captures whatever context the host has (tenantId, runId,
+ *     auth token, etc.) at provider-construction time. Compass-
+ *     platform's JWT-minting flow already works this way: the
+ *     server knows the tenant when it issues the JWT, and the
+ *     allowlist claim is baked in there. This avoids the
+ *     "where does the resolver get its context from" plumbing
+ *     problem — the host owns the closure, the SDK runtime
+ *     doesn't have to forward identity through `provider.create`.
+ */
+export type EgressPolicy = {
+    readonly kind: 'deny-all';
+} | {
+    readonly kind: 'allow-all';
+} | {
+    readonly kind: 'static';
+    readonly allowedHosts: readonly string[];
+} | {
+    readonly kind: 'resolver';
+    readonly resolve: () => Promise<readonly string[]>;
+};
+/**
+ * Backend strategy. Each tier × concrete-service combination ships
+ * an implementation of this interface in its own subfolder under
+ * `src/backends/`.
+ *
+ * Backends are responsible for:
+ *  - turning {@link SandboxBackendOptions} into a concrete
+ *    {@link Sandbox} instance the SDK can use,
+ *  - wiring {@link EgressPolicy} into whatever proxy / network
+ *    primitive the backend has,
+ *  - cleaning up host resources on `destroy()` (process-level
+ *    cleanup, container teardown, microVM stop+delete, etc.).
+ *
+ * Tier-specific concepts (bind-mount layout for container, microVM
+ * volume id, process-tier seccomp profile) are NOT carried on
+ * `SandboxBackendOptions`. They are baked into the backend at
+ * construction time via the tier-specific config (see
+ * {@link SandboxProviderConfig.layout} for the container tier). This
+ * keeps `provider.create()` symmetric across tiers and prevents the
+ * SDK runtime from accidentally calling a container backend without
+ * a layout — the binding is at construction, not per-call.
+ *
+ * The backend does NOT see the agent or its tools — the SDK
+ * composes them at the runtime layer. Backends are pure isolation
+ * primitives.
+ */
+export interface SandboxBackend {
+    readonly tier: SandboxTier;
+    readonly name: string;
+    create(options: SandboxBackendOptions): Promise<Sandbox>;
+}
+/**
+ * Per-call options handed to a backend's `create()`. Tier-agnostic
+ * host knobs only:
+ *
+ *  - `workingDirectory` — the per-task root where the sandbox is
+ *    rooted (e.g. `/tmp/<tenant>/<run>/`). Backends bind-mount or
+ *    chroot this depending on platform.
+ *  - `egress` — the allowlist policy applied to outbound network
+ *    inside the sandbox. Backends translate this into proxy /
+ *    iptables / domain-allowlist plumbing.
+ *  - `timeoutMs`, `memoryLimitMb`, `maxProcesses` — resource caps
+ *    applied per spawned process inside the sandbox.
+ *  - `env` — environment variables added to the inside of the
+ *    sandbox (NOT host process env). Used to forward
+ *    `HTTP_PROXY` / `HTTPS_PROXY` to the egress proxy when one
+ *    is in play.
+ *
+ * `layout` is **not** here — see the type-level note on
+ * {@link SandboxBackend}. Identity-aware fields (tenantId / runId /
+ * agentId) are deliberately NOT in this shape either; hosts that
+ * need per-tenant sandbox config bake the tenant into the closure
+ * that constructs the provider — see the `EgressPolicy` resolver
+ * shape.
+ */
+export interface SandboxBackendOptions {
+    readonly workingDirectory: string;
+    readonly egress?: EgressPolicy;
+    readonly timeoutMs?: number;
+    readonly memoryLimitMb?: number;
+    readonly maxProcesses?: number;
+    readonly env?: Record<string, string>;
+}
+/**
+ * Configuration for {@link createSandboxProvider}. The host picks
+ * a tier-specific backend config (process / container / microvm /
+ * passthrough) and supplies cross-tier defaults that
+ * `provider.create()` calls can override.
+ *
+ * Container-tier backends require a per-task
+ * {@link ContainerSandboxLayout} captured at construction time (see
+ * the discriminated union). The layout is per-task — different
+ * `hostPath`s for different runs — so hosts call
+ * `createSandboxProvider` once per task with the task-specific
+ * layout baked in. The `Sandbox` instance returned by
+ * `provider.create()` then inherits that layout. This is the only
+ * path: there is no per-call layout argument that could be silently
+ * omitted by the SDK runtime.
+ */
+export type SandboxProviderConfig = (SandboxProviderConfigBase & {
+    readonly backend: ContainerBackendConfig;
+    readonly layout: ContainerSandboxLayout;
+}) | (SandboxProviderConfigBase & {
+    readonly backend: ProcessBackendConfig | MicroVMBackendConfig | PassthroughBackendConfig;
+});
+interface SandboxProviderConfigBase {
+    readonly defaultEgress?: EgressPolicy;
+    readonly defaultTimeoutMs?: number;
+    readonly defaultMemoryLimitMb?: number;
+    readonly defaultMaxProcesses?: number;
+}
+/**
+ * Build a {@link SandboxProvider} the SDK can wire into
+ * `drainQuery`'s `sandboxProvider` field. Selects the backend at
+ * construction time; subsequent `provider.create()` calls all use
+ * the chosen backend.
+ *
+ * Backends are loaded lazily — the package only imports the
+ * platform-specific modules (Anthropic's sandbox-runtime, the
+ * Docker SDK, the E2B SDK, …) when the corresponding backend is
+ * requested. That keeps `@namzu/sandbox` reasonable to install in
+ * environments where one backend is genuinely impossible.
+ *
+ * **Not implemented in this commit** — this file declares the
+ * surface; backends arrive in subsequent commits per the ses_004
+ * phase plan:
+ *
+ *   - **P3.1** — `container` (docker runtime). Phase 1: ship now.
+ *   - **P3.2** — `EgressPolicy` plumbing + reference egress proxy.
+ *   - **P3.3** — `microvm` (E2B + Fly Machines adapters). Phase 2.
+ *   - **P3.4** — `process` (Anthropic sandbox-runtime adapter).
+ *   - **P3.5** — `microvm` (self-hosted firecracker-containerd) +
+ *     `container` (gVisor runtime). Phase 3 adversarial-multi-tenant.
+ *
+ * Calling this function now throws
+ * {@link SandboxBackendNotImplementedError} so consumers get a
+ * clear signal during the staged rollout.
+ */
+export declare function createSandboxProvider(config: SandboxProviderConfig): SandboxProvider;
+/**
+ * Thrown by the factory when a backend is requested before its
+ * implementation has landed. Makes the staged rollout legible —
+ * consumers see exactly which backend is missing rather than a
+ * generic `TypeError: foo is not a function`.
+ *
+ * Subclasses Error so existing host error handling (instanceof
+ * checks, JSON.stringify, etc.) keeps working.
+ */
+export declare class SandboxBackendNotImplementedError extends Error {
+    readonly backend: string;
+    readonly name = "SandboxBackendNotImplementedError";
+    constructor(backend: string);
+}
+/**
+ * Thrown when a {@link ContainerSandboxLayout} fails validation:
+ * missing required `outputs` mount, malformed skill id, duplicate
+ * skill id, duplicate `containerPath` across mounts. The `reasons`
+ * array carries one entry per violation so consumers can surface
+ * every problem in one round-trip rather than fix-then-rerun.
+ *
+ * **Transport caveat.** `JSON.stringify(err)` works because
+ * `toJSON()` returns a plain object with `reasons` preserved. But
+ * `structuredClone(err)` on the Error object itself drops the
+ * subclass name and any non-enumerable fields. For transport
+ * boundaries (postMessage, worker IPC, log shippers) call
+ * {@link serializeSandboxError} which returns a plain object that
+ * is `structuredClone`-safe and `JSON.stringify`-safe in one shape.
+ */
+export declare class ContainerSandboxLayoutValidationError extends Error {
+    readonly reasons: readonly string[];
+    readonly name = "ContainerSandboxLayoutValidationError";
+    constructor(reasons: readonly string[], options?: {
+        cause?: unknown;
+    });
+    toJSON(): {
+        name: string;
+        message: string;
+        reasons: readonly string[];
+        cause?: unknown;
+    };
+}
+/**
+ * Transport-safe serialisation for any error this package raises
+ * (and any nested `cause` chain). Returns a plain object with
+ * `name`, `message`, optional `stack`, optional `cause`
+ * (recursively serialised into the same envelope shape), and — for
+ * {@link ContainerSandboxLayoutValidationError} — the `reasons`
+ * array. The result is **uniformly safe** through
+ * `structuredClone`, `postMessage`, and `JSON.stringify`:
+ *
+ *  - No function / Symbol / BigInt / non-finite-number values
+ *    leak into the envelope; non-Error causes (and non-Error
+ *    inputs) are converted to a typed envelope by
+ *    {@link serializeNonErrorCause}.
+ *  - Cycles (`a.cause = a`, `a.cause = b; b.cause = a`) are
+ *    detected via a `WeakSet` and replaced with a
+ *    `{ name: 'CircularReference', message: '[circular]' }`
+ *    sentinel — no stack overflow, no `JSON.stringify` throw.
+ *  - Deep chains are walked in full (no arbitrary depth cap); the
+ *    cycle guard, not depth, is what bounds the recursion.
+ *
+ * Why this helper exists: `Error` subclasses don't survive any
+ * structured-clone-like channel — `structuredClone(err)` drops the
+ * subclass name and non-enumerable fields, `postMessage` follows
+ * the same rules, and most log shippers serialise via JSON which
+ * calls the unhelpful default `toJSON`. Vandal's supervisor
+ * architecture crosses every one of those boundaries; explicit
+ * serialisation keeps the `reasons[]` discoverable downstream.
+ *
+ * Use:
+ * ```ts
+ * try { ... }
+ * catch (err) {
+ *   logger.error(serializeSandboxError(err))
+ *   parent.postMessage(serializeSandboxError(err))
+ * }
+ * ```
+ */
+export interface SerializedSandboxError {
+    readonly name: string;
+    readonly message: string;
+    readonly stack?: string;
+    readonly reasons?: readonly string[];
+    /**
+     * Recursively serialised cause envelope. Always the same shape;
+     * non-Error causes go through {@link serializeNonErrorCause}
+     * before they reach this slot, so values that `JSON.stringify`
+     * or `structuredClone` would choke on (Function, Symbol,
+     * BigInt, NaN, ±Infinity, undefined) never appear here.
+     */
+    readonly cause?: SerializedSandboxError;
+}
+export declare function serializeSandboxError(err: unknown): SerializedSandboxError;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkEG;AAEH,OAAO,KAAK,EACX,sBAAsB,EACtB,OAAO,EAEP,eAAe,EACf,MAAM,YAAY,CAAA;AASnB,YAAY,EACX,sBAAsB,EACtB,2BAA2B,EAC3B,2BAA2B,EAC3B,0BAA0B,EAC1B,8BAA8B,GAC9B,MAAM,YAAY,CAAA;AAOnB,OAAO,EACN,4BAA4B,EAC5B,6BAA6B,EAC7B,iCAAiC,EACjC,gCAAgC,EAChC,4BAA4B,GAC5B,MAAM,YAAY,CAAA;AAMnB,YAAY,EACX,gCAAgC,EAChC,yBAAyB,GACzB,MAAM,iCAAiC,CAAA;AACxC,OAAO,EACN,KAAK,kBAAkB,EACvB,KAAK,qBAAqB,EAC1B,mBAAmB,GACnB,MAAM,qCAAqC,CAAA;AAM5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,WAAW,GAAG,SAAS,GAAG,aAAa,CAAA;AAE7E;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,GAC7B,oBAAoB,GACpB,sBAAsB,GACtB,2BAA2B,GAC3B,oBAAoB,GACpB,wBAAwB,CAAA;AAE3B;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,2BAA2B;IAC3C,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;IAC1B,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAA;IACpC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;IAC/B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;IAC9B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAA;IACtC,QAAQ,CAAC,+BAA+B,EAAE,MAAM,CAAA;IAChD,QAAQ,CAAC,6BAA6B,CAAC,EAAE,MAAM,CAAA;IAC/C;;;OAGG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAA;IAC3C,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAA;IACrC,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAA;IAChC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAA;IAC/B;;;;;;OAMG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAA;CACrC;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,oBAAoB;IACpC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,YAAY,GAAG,UAAU,CAAA;CACpD;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,sBAAsB;IACtC,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;IAC1B,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAA;IACrC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB;;;;;;;;OAQG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,WAAW,GAAG,mBAAmB,CAAA;IAC7D;;;;;;;OAOG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,MAAM,CAAA;IAC7C;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;CAClD;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,MAAM,oBAAoB,GAC7B;IACA,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;IACxB,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAA;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CACzB,GACD;IACA,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;IACxB,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAA;IAChC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CACvB,GACD;IACA,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;IACxB,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAA;IAC/B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAA;IAClC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAA;IACtC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAA;IACzC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B;;;;;;;;;OASG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,gBAAgB,CAAA;IACzC,4DAA4D;IAC5D,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAA;IAChC,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAA;IAChC,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAA;IACrC;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE;QACf,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAAA;QAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAA;QAC9B,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAA;QAC7B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAC5B,CAAA;IACD;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE;QAC3B,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAAA;QAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAA;QAC9B,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAA;QAC7B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAC5B,CAAA;CACA,CAAA;AAEJ;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACxB;AAED;;;GAGG;AACH,MAAM,WAAW,wBAAwB;IACxC,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAA;CAC5B;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,YAAY,GACrB;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;CAAE,GAC7B;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;CAAE,GAC9B;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GACrE;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC,CAAA;CAAE,CAAA;AAEpF;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,WAAW,cAAc;IAC9B,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IAErB,MAAM,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;CACxD;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,qBAAqB;IACrC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAA;IACjC,QAAQ,CAAC,MAAM,CAAC,EAAE,YAAY,CAAA;IAC9B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAA;IAC/B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;IAC9B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CACrC;AAMD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,qBAAqB,GAC9B,CAAC,yBAAyB,GAAG;IAC7B,QAAQ,CAAC,OAAO,EAAE,sBAAsB,CAAA;IACxC,QAAQ,CAAC,MAAM,EAAE,sBAAsB,CAAA;CACtC,CAAC,GACF,CAAC,yBAAyB,GAAG;IAC7B,QAAQ,CAAC,OAAO,EAAE,oBAAoB,GAAG,oBAAoB,GAAG,wBAAwB,CAAA;CACvF,CAAC,CAAA;AAEL,UAAU,yBAAyB;IAClC,QAAQ,CAAC,aAAa,CAAC,EAAE,YAAY,CAAA;IACrC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;IAClC,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAA;IACtC,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAA;CACrC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,qBAAqB,GAAG,eAAe,CA+BpF;AAyHD;;;;;;;;GAQG;AACH,qBAAa,iCAAkC,SAAQ,KAAK;aAG/B,OAAO,EAAE,MAAM;IAF3C,SAAkB,IAAI,uCAAsC;gBAEhC,OAAO,EAAE,MAAM;CAK3C;AAED;;;;;;;;;;;;;;GAcG;AACH,qBAAa,qCAAsC,SAAQ,KAAK;aAI9C,OAAO,EAAE,SAAS,MAAM,EAAE;IAH3C,SAAkB,IAAI,2CAA0C;gBAG/C,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1C,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;IAQ9B,MAAM,IAAI;QACT,IAAI,EAAE,MAAM,CAAA;QACZ,OAAO,EAAE,MAAM,CAAA;QACf,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;QAC1B,KAAK,CAAC,EAAE,OAAO,CAAA;KACf;CAQD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,MAAM,WAAW,sBAAsB;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACpC;;;;;;OAMG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,sBAAsB,CAAA;CACvC;AA4BD,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,OAAO,GAAG,sBAAsB,CAE1E"}