@tangle-network/agent-app 0.45.53 → 0.45.55

package/dist/sandbox/index.d.ts

@@ -1,1004 +1,19 @@
 import { Sandbox } from '@tangle-network/sandbox/core';
-import { SandboxInstance, ProvisionEvent, EgressPolicy, StorageConfig, ScopedTokenScope, TurnDriveResult, MintScopedTokenOptions } from '@tangle-network/sandbox';
-export { StorageConfig } from '@tangle-network/sandbox';
-import { ReasoningEffort, AgentProfileMcpServer, AgentProfileFileMount, AgentProfile } from '@tangle-network/agent-interface';
-import { T as ToolHeaderNames } from '../auth-BYtiazA4.js';
-import { a as AppToolName, A as AppToolContext } from '../types-B25Mib1r.js';
-import { Harness } from '../harness/index.js';
-import { a as TangleExecutionEnvironment } from '../model-CdCDfBA9.js';
-import { b as ProfileFingerprint, C as ComposeProfileBudget } from '../budget-BOucfcb_.js';
-
-/** Represent success or failure of an operation with corresponding value or error information */
-type Outcome<T> = {
-    succeeded: true;
-    value: T;
-} | {
-    succeeded: false;
-    error: Error;
-};
-
-/** Define configuration options for resolving a provider and its model with optional API keys and routing details */
-interface ProviderResolutionConfig {
-    routerBaseUrl?: string;
-    apiKey?: string;
-    providerName?: string;
-    modelName?: string;
-    defaultModel?: string;
-    openaiApiKey?: string;
-    allowKeylessModel?: boolean;
-}
-/** Represent a fully configured model with optional API key and base URL for sandbox platform integration */
-interface ResolvedModel {
-    model: string;
-    provider: string;
-    apiKey?: string;
-    baseUrl?: string;
-}
-/**
- * Why a model failed to resolve into something transportable to the sandbox
- * platform. `no_provider` — a model id exists but no provider name could be
- * derived (no explicit `providerName`, and no key present to infer one from).
- * `no_api_key` — a provider AND model both resolved, but no credential is
- * configured and the caller did not opt into `allowKeylessModel`.
- */
-type ModelSelectionError = 'no_provider' | 'no_api_key';
-/**
- * Which precedence slot supplied the failed/succeeded model id:
- * `override` — the caller's per-turn `{ model }` argument.
- * `config` — `provider.modelName`.
- * `default` — `provider.defaultModel` (only ever consulted for an
- * openai/openai-compat provider shape).
- */
-type ModelSelectionSource = 'override' | 'config' | 'default';
-/**
- * A model id was named (by override, config, or default) but is not
- * transportable to the sandbox platform. Carries enough to explain WHY
- * without the caller re-deriving the override/config/default precedence
- * chain itself (that re-derivation is how gtm-agent#665 happened — a caller
- * guessed loudness from the wrong slot and dropped a user-selected model).
- */
-type ModelSelectionFailure = {
-    succeeded: false;
-    error: 'no_provider';
-    model: string;
-    source: ModelSelectionSource;
-} | {
-    succeeded: false;
-    error: 'no_api_key';
-    model: string;
-    provider: string;
-    source: ModelSelectionSource;
-};
-/**
- * The three-state outcome of resolving a model: `{ succeeded: true, value:
- * undefined }` means NOTHING was requested (the legitimate box-default
- * configuration — not an error); `{ succeeded: true, value: ResolvedModel }`
- * means a fully transportable model resolved; anything else is a
- * {@link ModelSelectionFailure} — a model WAS named but can't be sent.
- */
-type ModelSelection = {
-    succeeded: true;
-    value: ResolvedModel | undefined;
-} | ModelSelectionFailure;
-/**
- * Resolve a provider + model configuration into a typed three-state outcome
- * that separates "nothing requested" from "something requested but
- * untransportable" — the distinction {@link resolveModel} collapses and the
- * one that caused gtm-agent#665 (a validated user-selected model silently
- * dropped, box default substituted, durable row still recording the user's
- * choice).
- *
- * Precedence (identical to the legacy `resolveModel`, byte-for-byte):
- * provider is computed first (`providerName`, else inferred `openai-compat`
- * from a present key, else inferred `openai` from a present
- * `openaiApiKey`, else unresolved); the model id is `override.model` else
- * `config.modelName` else — ONLY when the provider is `openai` or
- * `openai-compat` — `config.defaultModel`; the api key is
- * `override.modelApiKey` else `config.apiKey` else — only for provider
- * `openai` — `config.openaiApiKey`.
- *
- * Two behavioral deltas from the legacy function:
- *  1. Every string field (`routerBaseUrl`, `apiKey`, `providerName`,
- *     `modelName`, `defaultModel`, `openaiApiKey`, `override.model`,
- *     `override.modelApiKey`) is normalized through {@link trimOrNull} first,
- *     so `''` (and whitespace-only strings) are treated as absent instead of
- *     poisoning the `??` precedence chain — the issue's second stated defect.
- *     This also means a value is trimmed (`' gpt-5 '` resolves to `'gpt-5'`).
- *  2. The outcome is three-state instead of collapsing to `undefined`: no
- *     model derivable from any slot → `{ succeeded: true, value: undefined }`
- *     (still the legitimate "let the box pick its own default" case, NOT an
- *     error); a model id resolved but no provider could be derived → a
- *     `no_provider` failure; a model + provider resolved but no api key (and
- *     `allowKeylessModel` was not set) → a `no_api_key` failure. Both failure
- *     arms carry `source` so a caller can apply a loudness policy without
- *     re-deriving which precedence slot supplied the model.
- */
-declare function resolveModelSelection(config: ProviderResolutionConfig | undefined, override?: {
-    model?: string;
-    modelApiKey?: string;
-}): ModelSelection;
-/**
- * Resolve and return the appropriate model configuration based on provider
- * settings and optional overrides.
- *
- * Migration note (intentionally NOT tagged `@deprecated`): this is a thin,
- * source-compatible wrapper over {@link resolveModelSelection} that collapses
- * its three-state outcome back down to `ResolvedModel | undefined`, exactly
- * as before. It stays correct for the common case (no explicit model requested, or a
- * fully-transportable one), but it CANNOT distinguish "nothing was
- * requested" from "a named model could not be transported" — the ambiguity
- * that caused gtm-agent#665. Prefer {@link resolveModelSelection} directly,
- * or {@link requireTransportableModel} for the fail-loud-on-explicit-model
- * policy the internal sandbox callers use. Not tagged `@deprecated`: it
- * remains the correct call for a caller that never sets an explicit
- * override and only wants "the box's default is fine" semantics; a hard
- * deprecation is a later-major decision, not this fix's.
- *
- * The only behavior change on this entry point versus before is the
- * empty-string bugfix that comes free through delegation (issue #302's
- * second defect) — every signature and the `undefined` return semantics are
- * unchanged.
- */
-declare function resolveModel(config: ProviderResolutionConfig | undefined, override?: {
-    model?: string;
-    modelApiKey?: string;
-}): ResolvedModel | undefined;
-/**
- * Thrown by {@link requireTransportableModel} when a model that was
- * EXPLICITLY requested via a per-turn `{ model }` override cannot be
- * transported to the sandbox platform. The message names the model, which
- * precedence slot supplied it, what's missing, and the fix, and states
- * plainly that the requested model was NOT sent to the box (the failure mode
- * this error exists to make impossible to miss — gtm-agent#665 silently
- * substituted the box default instead of a user-selected model).
- *
- * The error class itself carries no opinion about *when* it should be
- * thrown — it is constructed from any {@link ModelSelectionFailure},
- * regardless of `source`. A caller wanting a stricter policy (e.g. also
- * fail-loud on an untransportable configured `provider.modelName`) can call
- * {@link resolveModelSelection} directly and throw this itself.
- */
-declare class SandboxModelResolutionError extends Error {
-    readonly code: ModelSelectionError;
-    readonly model: string;
-    readonly provider?: string;
-    readonly source: ModelSelectionSource;
-    constructor(failure: ModelSelectionFailure, context: string);
-}
-/**
- * Shared fail-loud policy for the sandbox platform's three internal model
- * callers (`ensureWorkspaceSandbox`'s `backendModelAtCreate`,
- * `streamSandboxPrompt`, `driveSandboxTurn`): a `ModelSelection` in, a plain
- * `ResolvedModel | undefined` out, so downstream code is unchanged from
- * before this fix.
- *
- * The policy: success delegates straight through. A failure whose `source`
- * is `'override'` means a PER-TURN model was explicitly selected THIS turn
- * (a live, user-driven choice — passed as `{ model }`) and could not be
- * sent; substituting the box default there is exactly the gtm-agent#665
- * defect, so it throws {@link SandboxModelResolutionError} rather than
- * silently falling back.
- *
- * A failure whose `source` is `'config'` or `'default'` means a
- * *configured* `provider.modelName` / `provider.defaultModel` couldn't
- * resolve — nobody made a choice this turn; the value came from board
- * config that may simply describe "the platform supplies the credential."
- * Shipped consumers rely on exactly that: tax-agent ships a shell with
- * `provider: { providerName: 'openai-compat', modelName, routerBaseUrl }`
- * and no `apiKey`/`allowKeylessModel`, with a contract test asserting
- * `ensureWorkspaceSandbox` creation SUCCEEDS with the model silently
- * dropped so the sandbox platform mints its own in-container credential
- * (`apps/web/tests/sandbox-service-contract.test.ts`). A config-loud policy
- * here would break every fresh tax sandbox provisioning and every tax turn.
- * So both `'config'` and `'default'` keep the pre-#302 logged-skip
- * behavior: `console.error` and drop, letting the box use its own default.
- * A product wanting strict enforcement of a configured `provider.modelName`
- * can call {@link resolveModelSelection} directly and apply its own policy.
- */
-declare function requireTransportableModel(selection: ModelSelection, context: string): ResolvedModel | undefined;
-
-/**
- * Reading arbitrary bytes out of a sandbox over an exec channel that only
- * speaks text.
- *
- * `box.exec` returns stdout as a string, so a binary file has to be encoded to
- * survive the trip: `wc -c` gives the on-disk length, `base64` gives the
- * payload, and the decoded byte count is checked against the stat. That last
- * check is the point of the module — an exec channel that caps or clips its
- * output still reports `exitCode: 0` with a short buffer, which decodes into a
- * perfectly valid but TRUNCATED file. Verifying the length turns that silent
- * corruption into a loud failure at the boundary.
- *
- * Both helpers return typed outcomes; callers must inspect `succeeded` before
- * touching `value`.
- */
-/** The `box.exec` surface these helpers use — structural, so a caller can pass
- *  the sandbox SDK's `SandboxInstance` directly or a narrower test double. */
-interface SandboxExecChannel {
-    exec(command: string, options?: {
-        sessionId?: string;
-    }): Promise<{
-        stdout: string;
-        stderr: string;
-        exitCode: number;
-    }>;
-}
-/** Define options to execute code within a sandbox environment with optional session control */
-interface SandboxExecOptions {
-    /** Run inside a named session rather than the box's default one. */
-    sessionId?: string;
-}
-/** Resolve the outcome of a sandbox file size check with success status and value or error message */
-type SandboxFileSizeOutcome = {
-    succeeded: true;
-    value: number;
-} | {
-    succeeded: false;
-    error: string;
-};
-/** Represent the outcome of reading sandbox file bytes with success status and corresponding data or error */
-type SandboxFileBytesOutcome = {
-    succeeded: true;
-    value: {
-        bytes: Uint8Array;
-        size: number;
-    };
-} | {
-    succeeded: false;
-    error: string;
-};
-/** Wraps a value in single quotes for `sh`, closing and reopening the quote
- *  around each embedded quote (`'` → `'"'"'`). Every path these helpers
- *  interpolate into a command goes through this — in-box filenames are
- *  arbitrary, so spaces, quotes and `$` are ordinary content, not syntax. */
-declare function shellQuote(value: string): string;
-/** Stats a sandbox file's byte length via `wc -c`. A caller enforcing a size
- *  cap must check this BEFORE {@link readSandboxBinaryBytes}, so an oversize
- *  file is rejected without paying for a base64 round trip of it. */
-declare function statSandboxFileSize(box: SandboxExecChannel, absolutePath: string, options?: SandboxExecOptions): Promise<SandboxFileSizeOutcome>;
-/** Reads a sandbox file as base64 and decodes it, verifying the decoded byte
- *  length against `expectedSize` (from a prior {@link statSandboxFileSize}). A
- *  mismatch is reported, never returned as a short buffer. */
-declare function readSandboxBinaryBytes(box: SandboxExecChannel, absolutePath: string, expectedSize: number, options?: SandboxExecOptions): Promise<SandboxFileBytesOutcome>;
-
-/**
- * What an app does after the platform hands back a sandbox it cannot use.
- *
- * `replaceUnbringableBox` (see `./index`) decides whether to abandon a dead box.
- * This decides everything around that: which box key the next attempt uses,
- * whether the old box's snapshot is safe to restore from, whether an owner has
- * to confirm the loss first, and what the person waiting is told. It is
- * bookkeeping, not I/O — the app supplies storage through
- * {@link WorkspaceSandboxRecoveryStore}.
- *
- * ── Why the tables ──────────────────────────────────────────────────────────
- * Every fact about an action or a code lives in ACTIONS/CODES below, and the
- * types are DERIVED from those tables. That is deliberate, and it is the whole
- * reliability argument for this module.
- *
- * The hand-maintained alternative — a union type plus a separate `x === 'a' ||
- * x === 'b' || …` list per question — silently drops anything not on the list.
- * A recovery recorded under an unlisted action is written to storage, read
- * back, discarded as malformed, and the workspace re-provisions the box it just
- * abandoned. Nothing throws. The fix looks correct, ships, and does nothing.
- * That failure was hit twice inside one change before this module existed.
- *
- * With the tables, adding an action or code is a compile error until every
- * question about it is answered. There is no list to forget.
- */
-/** The box exists and still holds unsnapshotted state, so discarding it is an
- *  owner's decision, not the runtime's. */
-declare const EGRESS_PROXY_RECOVERY_REQUIRED = "EGRESS_PROXY_RECOVERY_REQUIRED";
-declare const EGRESS_PROXY_RECOVERY_PHASE = "egress_proxy_recovery";
-/** The platform no longer has the box. Nothing to confirm, delete, or restore. */
-declare const WORKSPACE_SANDBOX_MISSING = "WORKSPACE_SANDBOX_MISSING";
-/** The box exists but its host has no free slot, so it can never be resumed
- *  where it is. A replacement can be placed on a host with room. */
-declare const WORKSPACE_SANDBOX_HOST_EXHAUSTED = "WORKSPACE_SANDBOX_HOST_EXHAUSTED";
-/** The platform ran its own recovery, failed, and asked for a replacement.
- *  Covers every way a box ends up unbringable with no more specific cause. */
-declare const WORKSPACE_SANDBOX_UNRECOVERABLE = "WORKSPACE_SANDBOX_UNRECOVERABLE";
-declare const WORKSPACE_SANDBOX_SNAPSHOT_MAX_AGE_MS: number;
-/**
- * Every recovery cause, and the one thing the runtime must know about each:
- * whether the box it names can still be read from.
- *
- * `snapshotUsable: false` is not a preference. A snapshot is addressed by the
- * sandbox it was taken from, so when that sandbox cannot be started the restore
- * fails exactly the way the resume did — and an app that tried it would turn a
- * recoverable workspace into a stuck one.
- */
-declare const CODES: {
-    readonly EGRESS_PROXY_RECOVERY_REQUIRED: {
-        readonly snapshotUsable: true;
-    };
-    readonly WORKSPACE_SANDBOX_MISSING: {
-        readonly snapshotUsable: false;
-    };
-    readonly WORKSPACE_SANDBOX_HOST_EXHAUSTED: {
-        readonly snapshotUsable: false;
-    };
-    readonly WORKSPACE_SANDBOX_UNRECOVERABLE: {
-        readonly snapshotUsable: false;
-    };
-};
-type WorkspaceSandboxRecoveryCode = keyof typeof CODES;
-/**
- * Every recovery action, and whether it means a replacement box has been
- * CHOSEN — the single question that decides which box key the next provisioning
- * attempt uses.
- *
- * `replacementChosen: false` covers the states where a key may be recorded but
- * must not be used yet: an owner has been asked and has not answered, or has
- * answered no. Handing back a key in those states replaces a box the owner
- * declined to lose.
- */
-declare const ACTIONS: {
-    readonly confirmation_required: {
-        readonly replacementChosen: false;
-    };
-    readonly deletion_declined: {
-        readonly replacementChosen: false;
-    };
-    readonly replacement_authorized: {
-        readonly replacementChosen: false;
-    };
-    readonly snapshot_replacement_authorized: {
-        readonly replacementChosen: false;
-    };
-    readonly replacement_started: {
-        readonly replacementChosen: true;
-    };
-    readonly replacement_completed: {
-        readonly replacementChosen: true;
-    };
-    readonly snapshot_replacement_started: {
-        readonly replacementChosen: true;
-    };
-    readonly snapshot_restore_failed: {
-        readonly replacementChosen: true;
-    };
-    readonly snapshot_replacement_completed: {
-        readonly replacementChosen: true;
-    };
-    readonly missing_replacement_started: {
-        readonly replacementChosen: true;
-    };
-    readonly missing_replacement_completed: {
-        readonly replacementChosen: true;
-    };
-    readonly unrecoverable_replacement_started: {
-        readonly replacementChosen: true;
-    };
-    readonly unrecoverable_replacement_completed: {
-        readonly replacementChosen: true;
-    };
-};
-type WorkspaceSandboxRecoveryAction = keyof typeof ACTIONS;
-type WorkspaceSandboxSnapshotAvailability = 'available' | 'missing' | 'stale';
-type WorkspaceSandboxSnapshotFreshness = 'fresh' | 'stale' | 'unknown';
-/** A snapshot the app took of a box, addressed by the box it came from. */
-interface WorkspaceSandboxSnapshot {
-    fromSandboxId: string;
-    createdAt: string;
-    [key: string]: unknown;
-}
-interface WorkspaceSandboxSnapshotAssessment {
-    availability: WorkspaceSandboxSnapshotAvailability;
-    freshness: WorkspaceSandboxSnapshotFreshness;
-    snapshot?: WorkspaceSandboxSnapshot;
-}
-interface WorkspaceSandboxRecoveryState {
-    code: WorkspaceSandboxRecoveryCode;
-    sandboxId: string;
-    detectedAt: string;
-    snapshot: WorkspaceSandboxSnapshotAssessment;
-    action: WorkspaceSandboxRecoveryAction;
-    replacementBoxKey?: string;
-    replacementSandboxId?: string;
-    confirmedAt?: string;
-}
-type WorkspaceSandboxRecoveryDecision = 'replace' | 'decline';
-/** Raised when chat cannot continue until an owner decides about the box. */
-declare class WorkspaceSandboxRecoveryRequiredError extends Error {
-    readonly code = "EGRESS_PROXY_RECOVERY_REQUIRED";
-    readonly status = 409;
-    readonly phase = "egress_proxy_recovery";
-    readonly recovery: WorkspaceSandboxRecoveryState;
-    constructor(recovery: WorkspaceSandboxRecoveryState, cause: Error);
-}
-declare function isEgressProxyRecoveryRequiredError(error: unknown): boolean;
-declare function isWorkspaceSandboxSnapshotRestoreError(error: unknown): boolean;
-/**
- * Judge a snapshot against the box being replaced.
- *
- * Fresh means BOTH that it came from this exact sandbox and that it is inside
- * the age bound — a snapshot from a different box restores someone else's
- * filesystem, which is worse than starting empty.
- */
-declare function assessWorkspaceSandboxSnapshot(snapshot: WorkspaceSandboxSnapshot | undefined, sandboxId: string, now?: number): WorkspaceSandboxSnapshotAssessment;
-declare function isWorkspaceSandboxRecoveryAction(value: unknown): value is WorkspaceSandboxRecoveryAction;
-declare function isWorkspaceSandboxRecoveryCode(value: unknown): value is WorkspaceSandboxRecoveryCode;
-declare function isWorkspaceSandboxRecoveryState(value: unknown): value is WorkspaceSandboxRecoveryState;
-declare function workspaceSandboxRecoveryFromError(error: unknown): WorkspaceSandboxRecoveryState | undefined;
-/** What to tell the person waiting. Never names the product, so an app can
- *  surface it verbatim. */
-declare function workspaceSandboxRecoveryMessage(recovery: WorkspaceSandboxRecoveryState): string;
-declare function workspaceSandboxRecoveryRecommendedActions(recovery: WorkspaceSandboxRecoveryState): string[];
-/** Flat key/value shape for a log line — no nesting, no secrets. */
-declare function workspaceSandboxRecoveryDiagnostic(recovery: WorkspaceSandboxRecoveryState): Record<string, string | undefined>;
-/**
- * The box key the next provisioning attempt should use, or undefined to keep
- * using the workspace's own key.
- *
- * Reads {@link ACTIONS} rather than a hand-kept list, because the failure mode
- * of a hand-kept list here is invisible: the key is recorded, silently ignored,
- * and provisioning goes back to the box the app just decided to abandon.
- */
-declare function preferredWorkspaceSandboxRecoveryBoxKey(recovery: WorkspaceSandboxRecoveryState | undefined): string | undefined;
-/** Whether the replacement should be restored from the old box's snapshot. */
-declare function shouldRestoreWorkspaceSandboxRecovery(recovery: WorkspaceSandboxRecoveryState | undefined): boolean;
-/**
- * Where an app keeps recovery state. One row per workspace, last write wins —
- * a recovery is a current situation, not a history.
- */
-interface WorkspaceSandboxRecoveryStore {
-    read: (workspaceId: string) => Promise<WorkspaceSandboxRecoveryState | undefined>;
-    write: (workspaceId: string, recovery: WorkspaceSandboxRecoveryState) => Promise<void>;
-}
-interface WorkspaceSandboxRecoveryManager {
-    read: (workspaceId: string) => Promise<WorkspaceSandboxRecoveryState | undefined>;
-    record: (workspaceId: string, recovery: WorkspaceSandboxRecoveryState) => Promise<void>;
-    /** Record an owner's decision. Returns undefined when the stored recovery does
-     *  not name this sandbox — a decision about a box that has already been
-     *  replaced must not resurrect it. */
-    decide: (args: {
-        workspaceId: string;
-        sandboxId: string;
-        decision: WorkspaceSandboxRecoveryDecision;
-        replacementBoxKey?: string;
-    }) => Promise<WorkspaceSandboxRecoveryState | undefined>;
-    /** Mark a replacement finished and name the box that took over. */
-    complete: (args: {
-        workspaceId: string;
-        replacementSandboxId: string;
-    }) => Promise<WorkspaceSandboxRecoveryState | undefined>;
-}
-/**
- * Bind the recovery bookkeeping to an app's storage.
- *
- * The app owns persistence — a D1 column, a KV key, a Postgres row — and
- * nothing else. Every rule about which action means what stays here, so it
- * cannot drift between apps.
- */
-declare function createWorkspaceSandboxRecoveryManager(store: WorkspaceSandboxRecoveryStore): WorkspaceSandboxRecoveryManager;
-/** Every declared action, for exhaustiveness tests in apps and here. */
-declare const WORKSPACE_SANDBOX_RECOVERY_ACTIONS: readonly WorkspaceSandboxRecoveryAction[];
-/** Every declared cause. */
-declare const WORKSPACE_SANDBOX_RECOVERY_CODES: readonly WorkspaceSandboxRecoveryCode[];
-
-interface SafeSandboxErrorCause {
-    name?: string;
-    message?: string;
-    code?: string | number;
-    status?: string | number;
-    phase?: string;
-    endpoint?: string;
-    origin?: string;
-    retryAfterMs?: number;
-    sidecarVersion?: string;
-    containerImage?: string;
-}
-interface SafeSandboxErrorDiagnostics {
-    message: string;
-    causes: SafeSandboxErrorCause[];
-    truncated: boolean;
-    truncatedAtDepth?: number;
-    cycle: boolean;
-}
-declare function serializeSandboxProvisioningError(error: unknown, options?: {
-    maxDepth?: number;
-}): SafeSandboxErrorDiagnostics;
-declare function formatSandboxProvisioningSupportDetails(diagnostics: SafeSandboxErrorDiagnostics): string;
-declare function isSandboxAuthFailure(diagnostics: SafeSandboxErrorDiagnostics): boolean;
-declare function isSandboxApiBearerAuthFailure(diagnostics: SafeSandboxErrorDiagnostics): boolean;
-/**
- * True when the sandbox API answered 404 for a specific sandbox resource — the
- * box behind a persisted sandbox id no longer exists.
- *
- * A sandbox id is a cache of where a workspace's box lives, not the workspace's
- * identity: the platform reaps, suspends, and loses boxes as ordinary lifecycle
- * events. Callers use this to discard the dead id and provision a replacement,
- * so the match is deliberately narrow — a 404 from the runtime sidecar
- * (`/runtime/...`, a missing file or session inside a live box) is NOT this.
- */
-declare function isSandboxApiSandboxMissingFailure(diagnostics: SafeSandboxErrorDiagnostics): boolean;
-/**
- * True when a resume failed because the host the box is pinned to cannot seat
- * it — the host's slot budget is exhausted, not the box's fault and not
- * something waiting fixes.
- *
- * A box lives on one host. When that host fills, every future resume for every
- * box on it fails identically and permanently, so a workspace whose box landed
- * on a full host is bricked until it is placed somewhere else. Callers use this
- * the same way they use {@link isSandboxApiSandboxMissingFailure}: discard the
- * dead id and provision a replacement, which the orchestrator is free to place
- * on a host with room. The workspace itself is preserved — it lives in the
- * Vault, not in the box's filesystem.
- *
- * Matched on the message because the sandbox API returns a generic
- * `SERVER_ERROR` for it; a dedicated code upstream would replace this.
- */
-declare function isSandboxHostCapacityFailure(diagnostics: SafeSandboxErrorDiagnostics): boolean;
-declare function formatSandboxProvisioningUserMessage(diagnostics: SafeSandboxErrorDiagnostics): string;
-
-/** Define the shape of a workspace sandbox instance including its connection details and status. */
-interface WorkspaceSandboxInstanceLike {
-    id: string;
-    name?: string;
-    status?: string;
-    connection?: {
-        runtimeUrl?: string;
-        sidecarUrl?: string;
-        authToken?: string;
-        sidecarToken?: string;
-        authTokenExpiresAt?: string;
-    } | null;
-}
-/** Define the context containing workspace and user identifiers for sandbox environment operations. */
-interface WorkspaceSandboxEnsureContext {
-    workspaceId: string;
-    userId: string;
-}
-/** Define configuration options for managing workspace sandboxes. */
-interface WorkspaceSandboxManagerOptions<TClient, TBox extends WorkspaceSandboxInstanceLike, TEnsureOptions = void> {
-    getClient: (ctx: WorkspaceSandboxEnsureContext) => Promise<TClient> | TClient;
-    nameForWorkspace: (workspaceId: string, ctx: WorkspaceSandboxEnsureContext) => string;
-    listSandboxes: (client: TClient, ctx: WorkspaceSandboxEnsureContext) => Promise<TBox[]>;
-    createSandbox: (args: {
-        client: TClient;
-        ctx: WorkspaceSandboxEnsureContext;
-        name: string;
-        options: TEnsureOptions;
-        listError?: unknown;
-    }) => Promise<TBox>;
-    waitForRunning?: (box: TBox, ctx: WorkspaceSandboxEnsureContext) => Promise<void>;
-    prepareExisting?: (box: TBox, ctx: WorkspaceSandboxEnsureContext, options: TEnsureOptions) => Promise<TBox | void>;
-    prepareCreated?: (box: TBox, ctx: WorkspaceSandboxEnsureContext, options: TEnsureOptions) => Promise<TBox | void>;
-    onListError?: (error: unknown, ctx: WorkspaceSandboxEnsureContext) => void;
-}
-/** Manage workspace sandboxes by ensuring their creation and retrieval for specified users. */
-interface WorkspaceSandboxManager<TBox extends WorkspaceSandboxInstanceLike, TEnsureOptions = void> {
-    ensureWorkspaceSandbox: (workspaceId: string, userId: string, options?: TEnsureOptions) => Promise<TBox>;
-}
-/**
- * Create a generic name-keyed sandbox lifecycle manager for products that
- * drive their own SDK or box types.
- */
-declare function createWorkspaceSandboxManager<TClient, TBox extends WorkspaceSandboxInstanceLike, TEnsureOptions = void>(opts: WorkspaceSandboxManagerOptions<TClient, TBox, TEnsureOptions>): WorkspaceSandboxManager<TBox, TEnsureOptions>;
-
-/**
- * Browser-direct scoped-token terminal connection route (#341/#349).
- *
- * Epic #343 / decision #341: the fleet's terminal transport is browser-direct
- * — the product's server authenticates the request and provisions/resolves
- * the sandbox exactly once, mints a short-lived SDK scoped token
- * (`box.mintScopedToken`), and hands the browser just enough to connect
- * `TerminalView` straight to the sidecar. No worker relays terminal bytes.
- * The deprecated same-origin relay was removed in #350 after the fleet
- * migrated, leaving this as the package's only terminal transport.
- *
- * VERIFIED PLATFORM CONTRACT (`@tangle-network/sandbox` 0.15.2 + the
- * orchestrator/sidecar enforcement source, verified 2026-07-30):
- *
- * 1. Only a `scope: 'session-runtime'` token carries the `terminal`
- *    capability (`cap: ["read", "workspace", "terminal"]`). `'project'` and
- *    `'session'` mint SessionGateway READ tokens (HS256, `typ: "read"`, no
- *    `cap` claim at all — a different token family the sidecar rejects
- *    outright); `'read-only'` carries `cap: ["read"]` only. **No scope other
- *    than `'session-runtime'` can ever open a terminal**, which is why this
- *    route no longer takes `scope` as a parameter — it is pinned.
- * 2. The orchestrator's terminal WS gate fails closed unless the token's
- *    `sid` claim EQUALS the `<connectionId>` path segment of
- *    `/terminals/<connectionId>/ws`
- *    (`verifyScopedSidecarCapability(sidecar, token, "terminal", connectionId)`).
- *    So `mintScopedToken({ scope: 'session-runtime', sessionId })` MUST be
- *    called with `sessionId === connectionId` — the exact id `TerminalView`
- *    will dial. That is why this route threads a `connectionId` end to end
- *    instead of deriving its own session id.
- * 3. The browser-safe terminal base is the mint result's `sidecarProxyUrl`
- *    (`/v1/sidecar-proxy/{id}` on the Sandbox API) — **not**
- *    `box.connection.runtimeUrl`. The SDK's own `_attachTerminal` is the
- *    reference implementation:
- *    `mintScopedToken({ scope: 'session-runtime', sessionId: connectionId })`
- *    then dial `${scoped.sidecarProxyUrl}/terminals/${connectionId}/ws`.
- *    Pointing `TerminalView` at `runtimeUrl` fails auth regardless of scope —
- *    only the sidecar-proxy hop decodes the browser's
- *    `bearer.<base64url>` WS subprotocol.
- *
- * HISTORICAL NOTE: an earlier shape of this route (and legal-agent's
- * production route it was modeled on, `scope: 'project'` +
- * `connection.runtimeUrl`) predates the platform's terminal-auth hardening —
- * the terminal capability gate (2026-06-19), the scoped-token terminal WS
- * path (2026-07-15), and the `sid`-binding fail-closed check
- * (2026-07-17/18). That shape does not authenticate on the current platform
- * and is not a valid spec for the token path anymore.
- *
- * SECURITY POSTURE: unlike the read-only session-gateway streaming token
- * (`box.mintScopedToken({scope:'session'})` paired with
- * `SessionGatewayClient`), the token this route mints grants **command
- * execution** in the sandbox once handed to `TerminalView`. Its safety rests
- * on a **short TTL** (default 15 minutes, the SDK's own max — still a caller
- * parameter) and, structurally, the narrowest scope the platform offers: one
- * box (`ensureSandbox` resolved it for THIS user), one terminal connection
- * (`session-runtime` bound to a single `sid`). Widening the TTL default
- * without an explicit reason is a security regression, not a convenience.
- *
- * Wire contract: the browser passes the response's `sidecarUrl` as
- * `TerminalView`'s `apiUrl` prop, `token` as its token prop, and the
- * response's echoed `connectionId` as `TerminalView`'s `connectionId` prop —
- * the token's `sid` is bound to exactly that id, so any other value fails the
- * WS upgrade. sandbox-ui sends the token as a `bearer.<base64url>` WebSocket
- * subprotocol (browsers cannot set `Authorization` on a WS handshake).
- * `useSandboxTerminalConnection` (`../web-react/sandbox-terminal`) carries
- * `connectionId` through automatically.
- */
-/** The structural surface this route needs from an SDK sandbox box — no `@tangle-network/sandbox` class import (invariant 3). */
-interface TerminalConnectionBoxLike {
-    id: string;
-    status?: string;
-    connection?: {
-        runtimeUrl?: string;
-    };
-    mintScopedToken(opts: {
-        scope: string;
-        sessionId?: string;
-        ttlMinutes?: number;
-    }): Promise<{
-        token: string;
-        expiresAt: Date;
-        sidecarProxyUrl: string;
-    }>;
-}
-/** Configuration for {@link createSandboxTerminalConnectionRoute}. */
-interface SandboxTerminalConnectionRouteOptions<TBox extends TerminalConnectionBoxLike, TUser> {
-    /**
-     * Authenticate the incoming request. Return the authenticated user, or a
-     * `Response` to short-circuit the route (e.g. a 401) — that Response is
-     * returned to the caller verbatim.
-     */
-    requireUser(request: Request): Promise<TUser | Response>;
-    /**
-     * Resolve (provisioning if needed) the sandbox this user's terminal should
-     * connect to. Domain-specific provisioning (workspace- vs user-scoped,
-     * naming, reuse) stays entirely in the product's implementation of this
-     * seam — the route only reacts to success/failure.
-     */
-    ensureSandbox(user: TUser, request: Request): Promise<TBox>;
-    /** `box.mintScopedToken` TTL in minutes. Default `15` (the SDK's own max). */
-    ttlMinutes?: number;
-    /**
-     * Resolve the terminal connection id the minted token's `sid` is bound to
-     * — this MUST be the same id `TerminalView` dials
-     * (`tabTerminalConnectionId()`), because the orchestrator's terminal WS
-     * gate fails closed unless `sid === <connectionId>` in
-     * `/terminals/<connectionId>/ws`.
-     *
-     * `requested` is `new URL(request.url).searchParams.get('connectionId')`.
-     * The default resolver returns `requested` unchanged. A product may
-     * validate/namespace the id here (e.g. a per-user prefix in a shared box)
-     * — if it rewrites the id, the client MUST use the response's echoed
-     * `connectionId`, since the sid binding makes any other id fail the WS
-     * upgrade.
-     *
-     * A resolved falsy/empty value fails the request with a 400 before any
-     * sandbox work happens.
-     */
-    resolveConnectionId?: (ctx: {
-        request: Request;
-        user: TUser;
-        box: TBox;
-        requested: string | null;
-    }) => string | null | undefined | Promise<string | null | undefined>;
-}
-/**
- * Build the browser-direct terminal connection route: `GET` handler that
- * authenticates, resolves the sandbox, mints a scoped token pinned to
- * `scope: 'session-runtime'` (the ONLY scope the platform grants the
- * `terminal` capability to), and returns exactly what the browser needs to
- * connect `TerminalView` directly to the sidecar — no worker in the data
- * path once the terminal is open.
- *
- * Response shapes:
- * - `requireUser` returns a `Response` → that `Response`, verbatim.
- * - `ensureSandbox` throws → `500 {error}` (the thrown message surfaced).
- * - `box.connection?.runtimeUrl` missing → `503 {error, status: box.status}`
- *   — this is a READINESS gate only; the URL returned to the client on
- *   success is always the mint's `sidecarProxyUrl`, never `runtimeUrl`.
- * - resolved connection id is falsy/empty → `400 {error}`.
- * - `box.mintScopedToken` rejects → `503 {error}`.
- * - success → `200 {sidecarUrl, token, expiresAt, status, sandboxId, connectionId}`.
- *   `connectionId` is the id the token's `sid` is bound to — the client MUST
- *   hand this (not its own) to `TerminalView`.
- */
-declare function createSandboxTerminalConnectionRoute<TBox extends TerminalConnectionBoxLike, TUser>(opts: SandboxTerminalConnectionRouteOptions<TBox, TUser>): (request: Request) => Promise<Response>;
-
-/**
- * `createSandboxPrewarmer` — "this user just opened this project; start warming
- * their box" as a shell primitive, so every agent-app product gets the same
- * answer instead of forking one.
- *
- * WHY THIS IS SHELL, NOT ENGINE. The engine rule asks whether the capability
- * makes sense without a specific app's side channel. "Warm a box" does — but
- * `@tangle-network/sandbox` has no notion of a WORKSPACE. It keys boxes by an
- * opaque sandbox id; the workspace→box mapping, the harness match, and the
- * profile materialisation all live in `ensureWorkspaceSandbox` here. A
- * prewarmer is that mapping plus a scheduling policy, so it belongs beside it.
- * It is deliberately NOT a new subpath: it composes `peekWorkspaceSandbox` and
- * `ensureWorkspaceSandbox` directly and needs exactly the peers `/sandbox`
- * already needs, so a separate entry would add a second place to look for "how
- * do I get a box" and buy no peer isolation (the reason `/work-product-react`
- * is split out).
- *
- * WHAT IT IS NOT. It does not make cold starts fast — they already are.
- * Measured on the real platform (staging-sandbox, n=5, 2026-07-28): a box goes
- * from nothing to terminal-ready in 2.34–3.19 s (median 2.73 s), and an
- * already-running box answers in 1.16–2.29 s (median 1.35 s). Prewarming buys
- * ~1.4 s. The reason it matters is not latency: it is that a product which
- * only ever provisions lazily, on a path whose guard never passes, never
- * provisions AT ALL — and the UI then shows a spinner over a box that does not
- * exist and is not being created. That is the failure this primitive removes.
- *
- * ── COST POSTURE (read before adopting) ────────────────────────────────────
- * A warmed box is a REAL charge. It bills from creation until the platform's
- * idle timeout reclaims it — `SandboxRuntimeConfig`'s create-time
- * `idleTimeoutSeconds`, not anything this module sets. A product warming on
- * every project open pays that timeout for every user who opens and bounces.
- * With a 3600 s idle timeout against a ~131 s mean session life, a bounce
- * costs an hour of box time to save ~1.4 s. THAT TRADE IS USUALLY WRONG.
- *
- * So the levers are explicit and the defaults are the cheap ones:
- *   - `mode: 'resume-only'` (DEFAULT) never creates a box that does not exist.
- *     It only revives one the user already has, so the spend is bounded by
- *     boxes the user already caused. This is the safe fleet default.
- *   - `mode: 'create-or-resume'` is the owner-requested behaviour — warm on
- *     open even for a first-time user. Opt in per product, and lower the
- *     shell's `idleTimeoutSeconds` when you do.
- *   - `shouldPrewarm(scope)` is the product's own policy hook (paid tier only,
- *     returning user only, has-documents only …). Returning false costs nothing.
- *   - `failureCooldownMs` stops a hard-failing workspace from retry-storming;
- *     every retry is another create attempt, which is more spend.
- * Warm with the SAME harness the next turn will use. `ensureWorkspaceSandbox`
- * DELETES and recreates a name-matched box whose harness differs, so warming
- * `opencode` and then turning `claude-code` pays for two boxes and is slower
- * than not warming at all. The prewarm key includes the harness so the two are
- * never deduped into one.
- *
- * ── SINGLE-FLIGHT (measured, not assumed) ──────────────────────────────────
- * The sandbox platform does NOT dedupe by box name. Two concurrent
- * `POST /v1/sandboxes` with an identical name both returned HTTP 201 and left
- * two running boxes (verified against staging-sandbox, 2026-07-28). So two
- * tabs, or two isolates, racing a warm genuinely leak a box — a prewarm that
- * races is worse than no prewarm. Hence two layers:
- *   1. an in-process map, which is free and catches same-isolate races
- *      (double-mount, two requests on one isolate);
- *   2. a `claim` store the product supplies, which is the only thing that can
- *      make this correct ACROSS isolates — the usual deployment target here is
- *      Cloudflare Workers, where "same isolate" guarantees nothing.
- * `claim` is REQUIRED, with `'single-isolate-only'` as the explicit opt-out,
- * so nobody gets the unsafe behaviour by forgetting a field. Say it out loud
- * or supply a store.
- *
- * ── FAILURE IS LOUD, NEVER FATAL ───────────────────────────────────────────
- * A failed warm degrades to exactly today's lazy path: the next real request
- * calls `ensureWorkspaceSandbox` itself. It never throws into the caller's
- * render path — `completion` RESOLVES with `{ ok: false }` rather than
- * rejecting, because an unhandled rejection handed to `waitUntil` can fail the
- * request it rode in on. But it is never silent: every failure fires
- * `onEvent({ type: 'failed' })` and is readable afterwards through
- * `readiness()` as `{ status: 'failed' }`. The bug class this whole module
- * exists to kill is a soft failure that surfaces as an unusable panel ten
- * minutes later, so a warm that dies must leave a trace a product can render.
- */
-
-/** The workspace a warm targets. Mirrors `EnsureWorkspaceSandboxOptions`'
- *  identity fields — the prewarmer forwards them verbatim so a warmed box is
- *  byte-identical to the one the lazy path would have built. */
-interface SandboxPrewarmScope {
-    workspaceId: string;
-    userId?: string;
-    /** Must match the harness the next turn will use — see the cost note above. */
-    harness: Harness;
-    billingOwnerId?: string;
-}
-/**
- * Cross-isolate claim. `acquire` must be atomic (a D1 conditional insert, a DO,
- * a KV `put` with `onlyIf`) — a read-then-write is exactly the race this exists
- * to close. `ttlSeconds` bounds a claim leaked by an isolate that died
- * mid-warm; without expiry a single crash wedges a workspace forever.
- */
-interface PrewarmClaimStore {
-    /** True when THIS caller now owns the right to warm `key`. */
-    acquire(key: string, ttlSeconds: number): Promise<boolean>;
-    /** Best-effort release. A throw here is swallowed — the TTL is the backstop. */
-    release(key: string): Promise<void>;
-    /** Optional: lets `readiness()` report `warming` for a warm running in
-     *  ANOTHER isolate. Without it, `warming` is only visible in the isolate
-     *  that started it, and every other one reports `absent`. */
-    isHeld?(key: string): Promise<boolean>;
-}
-/** What `prewarm()` decided. Every value except `started` means no box was
- *  created and nothing was spent on this call. */
-type PrewarmOutcome = 'started' | 'already-running' | 'already-warming' | 'warming-elsewhere' | 'declined-by-policy' | 'cooling-down' | 'absent-and-resume-only';
-/** Terminal result of a warm this caller owns. Never a rejection. */
-interface PrewarmResult {
-    ok: boolean;
-    boxId?: string;
-    error?: string;
-    /** Wall time of the warm itself, for the product's own timing trace. */
-    ms: number;
-}
-interface PrewarmDecision {
-    outcome: PrewarmOutcome;
-    /** Present ONLY when `outcome === 'started'`. Hand it to `ctx.waitUntil` so a
-     *  client disconnect cannot kill the warm. Never rejects. */
-    completion?: Promise<PrewarmResult>;
-}
-/** Readiness for the UI. `ready`/`warming` reuse the vocabulary
- *  `createSandboxFileIndexRoute` (`/chat-routes`) and `useFileMentions`
- *  (`/web-react`) already speak, so a product renders ONE warming state rather
- *  than inventing a second spinner for boxes. */
-type SandboxReadiness = {
-    status: 'ready';
-    boxId: string;
-} | {
-    status: 'warming';
-} | {
-    status: 'absent';
-} | {
-    status: 'failed';
-    error: string;
-    retryAfterMs: number;
-};
-type PrewarmEvent = {
-    type: 'started';
-    key: string;
-    workspaceId: string;
-} | {
-    type: 'succeeded';
-    key: string;
-    workspaceId: string;
-    boxId: string;
-    ms: number;
-} | {
-    type: 'failed';
-    key: string;
-    workspaceId: string;
-    error: string;
-    ms: number;
-} | {
-    type: 'skipped';
-    key: string;
-    workspaceId: string;
-    outcome: PrewarmOutcome;
-};
-interface SandboxPrewarmerOptions {
-    /** Cross-isolate single-flight, or the explicit acknowledgement that you are
-     *  accepting per-isolate dedupe only. No default — see the header. */
-    claim: PrewarmClaimStore | 'single-isolate-only';
-    /** `'resume-only'` (default) never creates a box that does not exist.
-     *  `'create-or-resume'` warms from nothing — the expensive one. */
-    mode?: 'resume-only' | 'create-or-resume';
-    /** Product policy gate. Not called when a box is already running. */
-    shouldPrewarm?(scope: SandboxPrewarmScope): boolean | Promise<boolean>;
-    /** Observability seam. A failed warm MUST be visible somewhere. */
-    onEvent?(event: PrewarmEvent): void;
-    /** Claim lifetime. Default 180 s — comfortably over a cold create. */
-    claimTtlSeconds?: number;
-    /** Suppress re-warming a workspace that just failed. Default 60_000 ms. */
-    failureCooldownMs?: number;
-    /** Clock seam for tests. */
-    now?(): number;
-}
-interface SandboxPrewarmer {
-    /**
-     * Non-blocking warm. The returned promise settles as soon as the DECISION is
-     * known (at most one `list()` against the platform, plus a claim `acquire`);
-     * the provisioning itself rides on `completion`. On a render path either
-     * ignore the returned promise or run the whole call inside `waitUntil` — do
-     * not await `completion` before responding.
-     */
-    prewarm(scope: SandboxPrewarmScope): Promise<PrewarmDecision>;
-    /** Zero-provisioning status read for a UI. Never creates or resumes. */
-    readiness(scope: SandboxPrewarmScope): Promise<SandboxReadiness>;
-    /** Clear a recorded failure so the next `prewarm` retries immediately. */
-    clearFailure(scope: SandboxPrewarmScope): void;
-}
-declare function createSandboxPrewarmer(shell: SandboxRuntimeConfig, options: SandboxPrewarmerOptions): SandboxPrewarmer;
-
-/**
- * `createD1PrewarmClaimStore` — the cross-isolate half of
- * `createSandboxPrewarmer`'s single-flight, implemented once.
- *
- * WHY THIS SHIPS HERE. `SandboxPrewarmerOptions.claim` is REQUIRED and has no
- * default, which is correct — the unsafe behaviour must be said out loud. But
- * "required with no implementation" is how five products end up hand-rolling
- * five subtly different atomic leases, and a lease that is subtly wrong is
- * indistinguishable from one that works until two tabs leak a box. Every
- * agent-app product deploys to Cloudflare Workers with a D1 binding, so the
- * store is the same code in all of them: it is mechanism, not domain, and it
- * belongs beside the prewarmer.
- *
- * The measured stake (staging-sandbox, 2026-07-28): two concurrent
- * `POST /v1/sandboxes` with an identical name BOTH returned HTTP 201 and left
- * two running boxes. The platform does not dedupe by name, so nothing below
- * this line is defensive programming — an unclaimed race genuinely doubles
- * spend.
- *
- * ── ATOMICITY IS THE WHOLE POINT ───────────────────────────────────────────
- * `acquire` is ONE statement. A `SELECT` followed by an `INSERT` is exactly the
- * race this exists to close: both isolates read "free", both write, both warm.
- * The upsert's `DO UPDATE ... WHERE expires_at <= now` means an unexpired claim
- * makes the conflict path a no-op, and `RETURNING` then yields no row — so the
- * loser learns it lost from the same statement that would have made it the
- * winner. `RETURNING` is used rather than `meta.changes` because a no-op upsert
- * reporting `changes: 0` is a SQLite detail, whereas "no row came back" is the
- * statement telling you directly.
- *
- * ── STRUCTURAL, NOT A DEPENDENCY ───────────────────────────────────────────
- * The binding is taken as the narrow shape actually used (`prepare().bind()`,
- * `.first()`, `.run()`), per the package's structural-over-hard-dep rule. No
- * `@cloudflare/workers-types` import, so `/sandbox` stays importable in a plain
- * node test. A real `D1Database` satisfies it.
- *
- * ── THE TABLE IS THE PRODUCT'S MIGRATION, NOT A LAZY CREATE ────────────────
- * The store never runs DDL. A `CREATE TABLE IF NOT EXISTS` on every project
- * open costs a round trip on the exact path this feature exists to keep fast,
- * and it hides schema drift instead of failing on it. `PREWARM_CLAIM_TABLE_DDL`
- * is exported so a product pastes it into a real migration. If the table is
- * missing, `acquire` throws — and the prewarmer treats a throwing claim as a
- * failed warm: it records the failure, emits `onEvent({type:'failed'})`, and
- * degrades to the lazy path. Fail-closed and loud, never a silent double-warm.
- */
-/** The columns and statements this store uses, and nothing else. A real
- *  `D1Database` structurally satisfies it. */
-interface PrewarmClaimD1Like {
-    prepare(query: string): {
-        bind(...values: unknown[]): {
-            first<T = Record<string, unknown>>(): Promise<T | null>;
-            run(): Promise<unknown>;
-        };
-    };
-}
-interface D1PrewarmClaimStoreOptions {
-    /** Defaults to `sandbox_prewarm_claims`. Must be a bare SQL identifier — it
-     *  is interpolated, because a table name cannot be a bound parameter. */
-    table?: string;
-    /** Clock seam for tests. */
-    now?(): number;
-}
-declare const DEFAULT_PREWARM_CLAIM_TABLE = "sandbox_prewarm_claims";
-/** Paste into a migration. `expires_at` is epoch MILLISECONDS, matching
- *  `Date.now()`, so no unit conversion sits between the lease and its clock. */
-declare const PREWARM_CLAIM_TABLE_DDL = "CREATE TABLE IF NOT EXISTS sandbox_prewarm_claims (\n  key TEXT PRIMARY KEY,\n  expires_at INTEGER NOT NULL\n)";
-/**
- * A `PrewarmClaimStore` backed by one D1 table.
- *
- * ```ts
- * const prewarmer = createSandboxPrewarmer(shell, {
- *   claim: createD1PrewarmClaimStore(env.DB),
- *   mode: 'create-or-resume',
- * })
- * ```
- */
-declare function createD1PrewarmClaimStore(db: PrewarmClaimD1Like, options?: D1PrewarmClaimStoreOptions): {
-    acquire(key: string, ttlSeconds: number): Promise<boolean>;
-    release(key: string): Promise<void>;
-    isHeld(key: string): Promise<boolean>;
-};
-
+import type { EgressPolicy, MintScopedTokenOptions, SandboxInstance, ScopedTokenScope, StorageConfig, TurnDriveResult, ProvisionEvent } from '@tangle-network/sandbox';
+import type { AgentProfile, AgentProfileFileMount, AgentProfileMcpServer, ReasoningEffort } from '@tangle-network/agent-interface';
+import { type AppToolName, type AppToolContext, type ToolHeaderNames } from '../tools/index';
+import { type Harness } from '../harness/index';
+import { type TangleExecutionEnvironment } from '../runtime/model';
+import { type Outcome } from './outcome';
+import { type ProfileFingerprint } from '../profile/fingerprint';
+import { type ComposeProfileBudget } from '../profile/budget';
+import { resolveModel, resolveModelSelection, requireTransportableModel, SandboxModelResolutionError, type ProviderResolutionConfig, type ResolvedModel, type ModelSelection, type ModelSelectionFailure, type ModelSelectionError, type ModelSelectionSource } from './model';
+export type { Outcome } from './outcome';
+export * from './binary-read';
+export { resolveModel, resolveModelSelection, requireTransportableModel, SandboxModelResolutionError, };
+export type { ProviderResolutionConfig, ResolvedModel, ModelSelection, ModelSelectionFailure, ModelSelectionError, ModelSelectionSource, };
 /** Define client credentials for accessing the sandbox environment with API key and base URL */
-interface SandboxClientCredentials {
+export interface SandboxClientCredentials {
     apiKey: string;
     baseUrl: string;
 }
@@ -1007,9 +22,9 @@ interface SandboxClientCredentials {
  * (development/test/staging/production) so env classification stays in one place
  * (see resolveTangleExecutionEnvironment in runtime/model).
  */
-type SandboxCredentialEnvironment = TangleExecutionEnvironment;
+export type SandboxCredentialEnvironment = TangleExecutionEnvironment;
 /** Resolve options for obtaining sandbox client credentials from environment variables and classification */
-interface ResolveSandboxClientCredentialsOptions {
+export interface ResolveSandboxClientCredentialsOptions {
     /**
      * Environment object to read from. Defaults to process.env when available.
      */
@@ -1050,9 +65,9 @@ interface ResolveSandboxClientCredentialsOptions {
     }) => SandboxClientCredentials | null | undefined | Promise<SandboxClientCredentials | null | undefined>;
 }
 /** Resolve sandbox client credentials based on environment and provided options asynchronously */
-declare function resolveSandboxClientCredentials(options?: ResolveSandboxClientCredentialsOptions): Promise<SandboxClientCredentials>;
+export declare function resolveSandboxClientCredentials(options?: ResolveSandboxClientCredentialsOptions): Promise<SandboxClientCredentials>;
 /** Define configuration parameters for sandbox resource allocation and lifecycle management */
-interface SandboxResourceConfig {
+export interface SandboxResourceConfig {
     image: string;
     cpuCores: number;
     memoryMB: number;
@@ -1061,34 +76,34 @@ interface SandboxResourceConfig {
     idleTimeoutSeconds: number;
 }
 /** Define the context for building a sandbox including workspace, integrations, and optional user ID */
-interface SandboxBuildContext {
+export interface SandboxBuildContext {
     workspaceId: string;
     connectedIntegrationIds: string[];
     userId?: string;
 }
 /** Hosts required when a product installs its pinned Python tooling at boot. */
-declare const PYPI_EGRESS_DOMAINS: readonly ["pypi.org", "files.pythonhosted.org", "pypi.python.org"];
-declare function buildProductEgressPolicy(publicOrigin: string | URL, extraDomains?: readonly string[]): EgressPolicy;
-
+export declare const PYPI_EGRESS_DOMAINS: readonly ["pypi.org", "files.pythonhosted.org", "pypi.python.org"];
+export declare function buildProductEgressPolicy(publicOrigin: string | URL, extraDomains?: readonly string[]): EgressPolicy;
+export type { StorageConfig };
 /** Define a scope containing workspace and optional user identifiers for sandbox environments */
-interface SandboxScope {
+export interface SandboxScope {
     workspaceId: string;
     userId?: string;
 }
 /** Define the specification for restoring a sandbox from a snapshot or another sandbox ID */
-interface SandboxRestoreSpec {
+export interface SandboxRestoreSpec {
     fromSnapshot: string;
     fromSandboxId: string;
 }
 /** Describe the failure details when resuming a stopped sandbox instance */
-interface StoppedSandboxResumeFailure {
+export interface StoppedSandboxResumeFailure {
     box: SandboxInstance;
     error: Error;
     scope: SandboxScope;
     boxKey: string;
 }
 /** Define the structure for resuming a stopped sandbox with replacement key and optional restore options */
-interface StoppedSandboxResumeRecovery {
+export interface StoppedSandboxResumeRecovery {
     replacementBoxKey: string;
     restore?: SandboxRestoreSpec | null;
 }
@@ -1098,9 +113,9 @@ interface StoppedSandboxResumeRecovery {
  * fleet's shared OpenCode, Claude Code, and Codex terminal path; products with
  * another harness can override it.
  */
-declare const DEFAULT_SIDECAR_PROCESS_PATTERN = "opencode|claude|codex";
+export declare const DEFAULT_SIDECAR_PROCESS_PATTERN = "opencode|claude|codex";
 /** Define configuration for liveness probes including sidecar process pattern and optional timeouts */
-interface LivenessProbeConfig {
+export interface LivenessProbeConfig {
     sidecarProcessPattern?: (harness: Harness) => string;
     execTimeoutMs?: number;
     psTimeoutMs?: number;
@@ -1116,7 +131,7 @@ interface LivenessProbeConfig {
     cacheTtlMs?: number;
 }
 /** Define options for composing a user profile including prompts, files, servers, and name */
-interface ProfileComposeOptions {
+export interface ProfileComposeOptions {
     systemPrompt?: string;
     extraFiles?: AgentProfileFileMount[];
     extraMcp?: Record<string, AgentProfileMcpServer>;
@@ -1137,7 +152,7 @@ interface ProfileComposeOptions {
     harness: Harness;
 }
 /** Define runtime configuration methods for sandbox environments including credentials, metadata, and permissions */
-interface SandboxRuntimeConfig {
+export interface SandboxRuntimeConfig {
     credentials: (scope?: SandboxScope) => SandboxClientCredentials | null | Promise<SandboxClientCredentials | null>;
     name: (workspaceId: string) => string;
     metadata: (harness: Harness) => Record<string, unknown>;
@@ -1208,19 +223,19 @@ interface SandboxRuntimeConfig {
     promptBudget?: ComposeProfileBudget;
 }
 /** Define default resource limits and settings for sandbox environments */
-declare const DEFAULT_SANDBOX_RESOURCES: SandboxResourceConfig;
+export declare const DEFAULT_SANDBOX_RESOURCES: SandboxResourceConfig;
 /** Resolve a synchronous sandbox client from provided runtime configuration credentials */
-declare function getClient(shell: SandboxRuntimeConfig): Sandbox;
+export declare function getClient(shell: SandboxRuntimeConfig): Sandbox;
 /** Reset the process-local sandbox client and liveness-verification caches. */
-declare function resetClientCache(): void;
+export declare function resetClientCache(): void;
 /** Describe an application tool with its name, unique key, and description */
-interface AppToolDescriptor {
+export interface AppToolDescriptor {
     tool: AppToolName;
     key: string;
     description: string;
 }
 /** Define options for building MCP server configurations in the app tool environment */
-interface BuildAppToolMcpServersOptions {
+export interface BuildAppToolMcpServersOptions {
     tools: AppToolDescriptor[];
     baseUrl: string;
     /**
@@ -1238,9 +253,9 @@ interface BuildAppToolMcpServersOptions {
     headerNames?: ToolHeaderNames;
 }
 /** Build a mapping of MCP server profiles keyed by tool identifiers from provided options */
-declare function buildAppToolMcpServers(options: BuildAppToolMcpServersOptions): Record<string, AgentProfileMcpServer>;
+export declare function buildAppToolMcpServers(options: BuildAppToolMcpServersOptions): Record<string, AgentProfileMcpServer>;
 /** Define options for ensuring a workspace sandbox with provisioning and progress handling */
-interface EnsureWorkspaceSandboxOptions {
+export interface EnsureWorkspaceSandboxOptions {
     workspaceId: string;
     userId?: string;
     harness: Harness;
@@ -1250,7 +265,7 @@ interface EnsureWorkspaceSandboxOptions {
     spend?: SandboxSpendHooks;
 }
 /** What `/sandbox` reports once a box is provisioned, reused, or resumed. */
-interface SandboxProvisionedObservation {
+export interface SandboxProvisionedObservation {
     readonly workspaceId: string;
     readonly userId?: string;
     /** The platform's sandbox id — the join key to every settlement row. */
@@ -1272,7 +287,7 @@ interface SandboxProvisionedObservation {
  * `onProvisioned` is an OBSERVER: its failures are swallowed, because
  * bookkeeping must never take down the provisioning it is bookkeeping.
  */
-interface SandboxSpendHooks {
+export interface SandboxSpendHooks {
     /** Runs before any create, resume, or reuse. Throw to refuse provisioning. */
     beforeProvision?(input: {
         workspaceId: string;
@@ -1300,49 +315,49 @@ interface SandboxSpendHooks {
     }): void;
 }
 /** Define the specification for a sandbox tool including its name, content, and optional executability */
-interface SandboxToolSpec {
+export interface SandboxToolSpec {
     name: string;
     content: string;
     executable?: boolean;
 }
 /** Define options for resolving sandbox tool paths including appName, baseDir, and binDir */
-interface SandboxToolPathOptions {
+export interface SandboxToolPathOptions {
     appName: string;
     baseDir?: string;
     binDir?: string;
 }
 /** Define options for building sandbox tool file mounts including tool specifications and paths */
-interface BuildSandboxToolFileMountsOptions extends SandboxToolPathOptions {
+export interface BuildSandboxToolFileMountsOptions extends SandboxToolPathOptions {
     tools: readonly SandboxToolSpec[];
 }
 /** Resolve the root directory path for a sandbox tool based on provided options */
-declare function sandboxToolRootDir(options: SandboxToolPathOptions): string;
+export declare function sandboxToolRootDir(options: SandboxToolPathOptions): string;
 /** Resolve the binary directory path for a sandbox tool based on provided options */
-declare function sandboxToolBinDir(options: SandboxToolPathOptions): string;
+export declare function sandboxToolBinDir(options: SandboxToolPathOptions): string;
 /** Resolve the file system path to a specified sandbox tool based on given options */
-declare function sandboxToolPath(options: SandboxToolPathOptions & {
+export declare function sandboxToolPath(options: SandboxToolPathOptions & {
     toolName: string;
 }): string;
 /** Build file mounts for sandbox tools based on provided options and tool configurations */
-declare function buildSandboxToolFileMounts(options: BuildSandboxToolFileMountsOptions): AgentProfileFileMount[];
+export declare function buildSandboxToolFileMounts(options: BuildSandboxToolFileMountsOptions): AgentProfileFileMount[];
 /** Build a shell script that sets up and exports the sandbox tool binary directory in user profiles */
-declare function buildSandboxToolPathSetupScript(options: SandboxToolPathOptions): string;
+export declare function buildSandboxToolPathSetupScript(options: SandboxToolPathOptions): string;
 /** Resolve the sandbox environment PATH setup by executing the configuration script with given options */
-declare function runSandboxToolPathSetup(box: SandboxInstance, options: SandboxToolPathOptions): Promise<Outcome<void>>;
+export declare function runSandboxToolPathSetup(box: SandboxInstance, options: SandboxToolPathOptions): Promise<Outcome<void>>;
 /** Split profile files into inline deferred files and a lean profile without them */
-declare function splitDeferredProfileFiles(profile: AgentProfile): {
+export declare function splitDeferredProfileFiles(profile: AgentProfile): {
     leanProfile: AgentProfile;
     deferredFiles: AgentProfileFileMount[];
 };
-type SandboxExistingBoxStage = 'reused' | 'resumed';
-type SandboxEgressPolicySource = Awaited<ReturnType<SandboxInstance['egress']['get']>>['source'];
+export type SandboxExistingBoxStage = 'reused' | 'resumed';
+export type SandboxEgressPolicySource = Awaited<ReturnType<SandboxInstance['egress']['get']>>['source'];
 /**
  * Thrown when an existing sandbox cannot be proven to have the requested
  * outbound network policy. The sandbox is preserved and its policy is not
  * changed. The caller explicitly decides whether to preserve, migrate, or
  * replace the sandbox.
  */
-declare class SandboxEgressPolicyMismatchError extends Error {
+export declare class SandboxEgressPolicyMismatchError extends Error {
     readonly stage: SandboxExistingBoxStage;
     readonly boxName: string;
     readonly currentPolicy: EgressPolicy;
@@ -1350,67 +365,68 @@ declare class SandboxEgressPolicyMismatchError extends Error {
     readonly desiredPolicy: EgressPolicy;
     constructor(stage: SandboxExistingBoxStage, boxName: string, currentPolicy: EgressPolicy, currentSource: SandboxEgressPolicySource, desiredPolicy: EgressPolicy);
 }
-
+export * from './recovery';
+export { serializeSandboxProvisioningError, formatSandboxProvisioningSupportDetails, formatSandboxProvisioningUserMessage, isSandboxAuthFailure, isSandboxApiBearerAuthFailure, isSandboxApiSandboxMissingFailure, isSandboxHostCapacityFailure, type SafeSandboxErrorCause, type SafeSandboxErrorDiagnostics, } from './diagnostics';
 /** Represent an error thrown when sandbox runtime authentication refresh fails for a specific stage and name */
-declare class SandboxRuntimeAuthRefreshError extends Error {
+export declare class SandboxRuntimeAuthRefreshError extends Error {
     constructor(stage: SandboxExistingBoxStage, name: string, detail: string, cause?: unknown);
 }
 /** Which step of the state-preserving stop→resume recovery failed. `stop` with a
  *  driver-unsupported cause means the platform cannot restart this box (the
  *  `tangle` driver exposes create/delete only); `probe` means the box restarted
  *  but is still unresponsive. */
-type SandboxRecoveryPhase = 'stop' | 'resume' | 'probe';
+export type SandboxRecoveryPhase = 'stop' | 'resume' | 'probe';
 /**
  * Thrown when an unresponsive box could not be recovered by a state-preserving
  * restart. Contract: this error is only ever thrown with the workspace intact —
  * recovery never deletes. The caller decides what to do next (retry, surface to
  * the user, or explicitly replace via `forceNew`).
  */
-declare class SandboxRecoveryFailedError extends Error {
+export declare class SandboxRecoveryFailedError extends Error {
     readonly boxKey: string;
     readonly stage: SandboxExistingBoxStage;
     readonly phase: SandboxRecoveryPhase;
     constructor(stage: SandboxExistingBoxStage, boxKey: string, phase: SandboxRecoveryPhase, detail: string, cause?: unknown);
 }
 /** Define options to control execution timeout, pacing, and retry behavior when writing profile files */
-interface WriteProfileFilesOptions {
+export interface WriteProfileFilesOptions {
     execTimeoutMs?: number;
     paceMs?: number;
     maxRetries?: number;
 }
 /** Write profile files to a sandbox with pacing, retries, and optional execution timeout handling */
-declare function writeProfileFilesToBox(box: SandboxInstance, files: AgentProfileFileMount[], options?: WriteProfileFilesOptions): Promise<Outcome<void>>;
+export declare function writeProfileFilesToBox(box: SandboxInstance, files: AgentProfileFileMount[], options?: WriteProfileFilesOptions): Promise<Outcome<void>>;
 /** Stable content hash of the deferred file corpus (path + inline content).
  *  Unchanged corpus ⇒ same hash; a new/edited/removed skill ⇒ different hash.
  *  Exported for the reuse-skip test. */
-declare function deferredCorpusHash(files: AgentProfileFileMount[]): string;
+export declare function deferredCorpusHash(files: AgentProfileFileMount[]): string;
 /** Gate on the provision body: the platform orchestrator caps the create
  *  payload at 256 KiB; 240 KB leaves headroom for transport framing. An
  *  over-cap payload fails provisioning 100% of the time (a 282 KB payload
  *  shipped once and no sandbox could ever be created). */
-declare const PROVISION_PAYLOAD_MAX_BYTES = 240000;
+export declare const PROVISION_PAYLOAD_MAX_BYTES = 240000;
 /** Per-variable env gate: the kernel rejects any single `NAME=value` env entry
  *  over MAX_ARG_STRLEN (131072 bytes) with E2BIG, killing every exec inside
  *  the box. 120 KB leaves headroom for the name and framing. */
-declare const ENV_VALUE_MAX_BYTES = 120000;
+export declare const ENV_VALUE_MAX_BYTES = 120000;
 /** Default wait for a box to reach `running`. Overridable per shell via
  *  {@link SandboxRuntimeConfig.provisionTimeoutMs}. */
-declare const DEFAULT_PROVISION_TIMEOUT_MS = 120000;
+export declare const DEFAULT_PROVISION_TIMEOUT_MS = 120000;
 /** Total env gate: the whole environment block shares the payload budget with
  *  the profile; past 200 KB the provision body cannot stay under the cap. */
-declare const ENV_TOTAL_MAX_BYTES = 200000;
+export declare const ENV_TOTAL_MAX_BYTES = 200000;
 /** Structural slice of the profile the payload gate reads: it only measures
  *  the profile's serialized size and names `resources.files` in the breakdown,
  *  so callers composing a payload outside the SDK (products, tests) can pass a
  *  plain object without casting through `AgentProfile`. */
-interface ProvisionProfileSection {
+export interface ProvisionProfileSection {
     resources?: {
         files?: readonly unknown[];
     };
 }
 /** The provision-payload sections the size gates need to see. Structural so
  *  the gate is testable without the SDK's (unexported) create-payload type. */
-interface ProvisionPayloadSections {
+export interface ProvisionPayloadSections {
     env?: Record<string, string>;
     secrets?: readonly string[];
     /** `profile` may also be a named-profile string ref (the SDK's
@@ -1425,18 +441,18 @@ interface ProvisionPayloadSections {
  * breakdown (profile/files/env/secrets) so the offending channel is named, not
  * guessed.
  */
-declare function assertProvisionPayloadWithinCap(payload: ProvisionPayloadSections): void;
+export declare function assertProvisionPayloadWithinCap(payload: ProvisionPayloadSections): void;
 /**
  * Throw when any single env value exceeds {@link ENV_VALUE_MAX_BYTES} or the
  * whole env block exceeds {@link ENV_TOTAL_MAX_BYTES}, naming the offending
  * variable. This is the E2BIG incident class: the box may even provision, but
  * every exec inside it dies on the oversized entry.
  */
-declare function assertEnvWithinLimits(env: Record<string, string>): void;
+export declare function assertEnvWithinLimits(env: Record<string, string>): void;
 /** What a peek can find. `not-running` carries the platform's own state string
  *  (`stopped`, `starting`, `failed`, …) — narrowing it to a union here would
  *  drop states the platform adds later, and every caller wants it for a log. */
-type PeekWorkspaceSandboxOutcome = {
+export type PeekWorkspaceSandboxOutcome = {
     status: 'running';
     box: SandboxInstance;
 } | {
@@ -1477,16 +493,16 @@ type PeekWorkspaceSandboxOutcome = {
  * platform never reported. Callers that must tolerate it say so explicitly
  * (the stale-turn-lock policy documents "a throw is treated as unreachable").
  */
-declare function peekWorkspaceSandbox(shell: SandboxRuntimeConfig, options: {
+export declare function peekWorkspaceSandbox(shell: SandboxRuntimeConfig, options: {
     workspaceId: string;
     userId?: string;
 }): Promise<PeekWorkspaceSandboxOutcome>;
 /** Resolve or create a workspace sandbox instance with optional reuse and progress tracking */
-declare function ensureWorkspaceSandbox(shell: SandboxRuntimeConfig, options: EnsureWorkspaceSandboxOptions): Promise<SandboxInstance>;
+export declare function ensureWorkspaceSandbox(shell: SandboxRuntimeConfig, options: EnsureWorkspaceSandboxOptions): Promise<SandboxInstance>;
 /** Extract a single element type from the array parameter of SandboxInstance's streamPrompt method */
-type PromptInputPart = Extract<Parameters<SandboxInstance['streamPrompt']>[0], readonly unknown[]>[number];
+export type PromptInputPart = Extract<Parameters<SandboxInstance['streamPrompt']>[0], readonly unknown[]>[number];
 /** Build a single string combining conversation history and the current user message */
-declare function flattenHistory(message: string, history?: Array<{
+export declare function flattenHistory(message: string, history?: Array<{
     role: 'user' | 'assistant';
     content: string;
 }>): string;
@@ -1495,16 +511,16 @@ declare function flattenHistory(message: string, history?: Array<{
  * transcript is folded into the first text part (image/file parts carry no
  * text to prepend to) rather than replacing the message wholesale.
  */
-declare function mergeHistoryIntoParts(parts: PromptInputPart[], history?: Array<{
+export declare function mergeHistoryIntoParts(parts: PromptInputPart[], history?: Array<{
     role: 'user' | 'assistant';
     content: string;
 }>): PromptInputPart[];
 /** Resolve conflicts and merge extra MCP profiles into the app tool MCP without overwriting existing keys */
-declare function mergeExtraMcp(appToolMcp: Record<string, AgentProfileMcpServer>, baseProfileMcp: Record<string, AgentProfileMcpServer>, extra: Record<string, AgentProfileMcpServer> | undefined): Record<string, AgentProfileMcpServer>;
+export declare function mergeExtraMcp(appToolMcp: Record<string, AgentProfileMcpServer>, baseProfileMcp: Record<string, AgentProfileMcpServer>, extra: Record<string, AgentProfileMcpServer> | undefined): Record<string, AgentProfileMcpServer>;
 /** Attach a specified reasoning effort level to an agent profile for a given harness */
-declare function attachReasoningEffort(profile: AgentProfile, harness: Harness, effort: 'auto' | ReasoningEffort | undefined): AgentProfile;
+export declare function attachReasoningEffort(profile: AgentProfile, harness: Harness, effort: 'auto' | ReasoningEffort | undefined): AgentProfile;
 /** Define options for configuring and controlling a streaming sandbox prompt session */
-interface StreamSandboxPromptOptions {
+export interface StreamSandboxPromptOptions {
     sessionId?: string;
     executionId?: string;
     /** Stable idempotency key for one logical dispatch. Reuse it with the same
@@ -1543,7 +559,7 @@ interface StreamSandboxPromptOptions {
  * adapter deliberately copies only the fields the gateway understands so
  * consumers do not each have to maintain a provider-to-gateway cast.
  */
-interface SandboxStreamEvent {
+export interface SandboxStreamEvent {
     type?: string;
     data?: {
         part?: {
@@ -1558,9 +574,9 @@ interface SandboxStreamEvent {
     };
 }
 /** Normalize raw sandbox events for shared agent-gateway consumers. */
-declare function adaptSandboxStream(events: AsyncIterable<unknown>): AsyncGenerator<SandboxStreamEvent>;
+export declare function adaptSandboxStream(events: AsyncIterable<unknown>): AsyncGenerator<SandboxStreamEvent>;
 /** Resolve and stream AI-generated responses from a sandboxed environment based on input messages and options */
-declare function streamSandboxPrompt(shell: SandboxRuntimeConfig, box: SandboxInstance, message: string | PromptInputPart[], options?: StreamSandboxPromptOptions): AsyncGenerator<unknown>;
+export declare function streamSandboxPrompt(shell: SandboxRuntimeConfig, box: SandboxInstance, message: string | PromptInputPart[], options?: StreamSandboxPromptOptions): AsyncGenerator<unknown>;
 /**
  * Aggregate a sandbox prompt event stream down to the turn's one final answer.
  *
@@ -1591,7 +607,7 @@ declare function streamSandboxPrompt(shell: SandboxRuntimeConfig, box: SandboxIn
  * @param history folded into the dispatched prompt by `streamSandboxPrompt`;
  *        pass whatever was passed there, since the echo replays the FOLDED text
  */
-declare function collectSandboxPromptText(events: AsyncIterable<unknown>, message: string | PromptInputPart[], history?: StreamSandboxPromptOptions['history']): Promise<string>;
+export declare function collectSandboxPromptText(events: AsyncIterable<unknown>, message: string | PromptInputPart[], history?: StreamSandboxPromptOptions['history']): Promise<string>;
 /**
  * Resolve a sandbox prompt by streaming it and aggregating the turn down to one
  * final string. The shell's profile / model / MCP resolution and severed-stream
@@ -1599,19 +615,19 @@ declare function collectSandboxPromptText(events: AsyncIterable<unknown>, messag
  * `collectSandboxPromptText`, which products driving their own generator should
  * import directly.
  */
-declare function runSandboxPrompt(shell: SandboxRuntimeConfig, box: SandboxInstance, message: string | PromptInputPart[], options?: StreamSandboxPromptOptions): Promise<string>;
+export declare function runSandboxPrompt(shell: SandboxRuntimeConfig, box: SandboxInstance, message: string | PromptInputPart[], options?: StreamSandboxPromptOptions): Promise<string>;
 /** Define permission levels for sandbox access and control */
-type SandboxPermissionLevel = 'owner' | 'admin' | 'developer' | 'viewer';
+export type SandboxPermissionLevel = 'owner' | 'admin' | 'developer' | 'viewer';
 /** Map workspace roles to corresponding sandbox permission levels */
-interface MemberSyncSeam {
+export interface MemberSyncSeam {
     roleToSandboxRole: (workspaceRole: string) => SandboxPermissionLevel;
 }
 /** Resolve adding a user with a specific role to a sandbox and return the operation outcome */
-declare function syncSandboxMemberAdd(box: SandboxInstance, seam: MemberSyncSeam, userId: string, role: string): Promise<Outcome<void>>;
+export declare function syncSandboxMemberAdd(box: SandboxInstance, seam: MemberSyncSeam, userId: string, role: string): Promise<Outcome<void>>;
 /** Remove a member from the sandbox while preserving their home directory and handle the outcome */
-declare function syncSandboxMemberRemove(box: SandboxInstance, userId: string): Promise<Outcome<void>>;
+export declare function syncSandboxMemberRemove(box: SandboxInstance, userId: string): Promise<Outcome<void>>;
 /** Synchronize a sandbox member's role by updating permissions based on the provided role mapping */
-declare function syncSandboxMemberRole(box: SandboxInstance, seam: MemberSyncSeam, userId: string, role: string): Promise<Outcome<void>>;
+export declare function syncSandboxMemberRole(box: SandboxInstance, seam: MemberSyncSeam, userId: string, role: string): Promise<Outcome<void>>;
 /**
  * Write-only secret port: create, replace, and delete a secret by name.
  *
@@ -1620,19 +636,19 @@ declare function syncSandboxMemberRole(box: SandboxInstance, seam: MemberSyncSea
  * the sandbox as an environment variable. A `get` here could only ever return
  * a value this process already held, so the port does not offer one.
  */
-interface SecretStore {
+export interface SecretStore {
     create: (name: string, value: string) => Promise<void>;
     update: (name: string, value: string) => Promise<void>;
     delete: (name: string) => Promise<void>;
 }
 /** Resolve a SecretStore interface using the provided SandboxRuntimeConfig shell */
-declare function secretStoreFromClient(shell: SandboxRuntimeConfig): SecretStore;
+export declare function secretStoreFromClient(shell: SandboxRuntimeConfig): SecretStore;
 /** Resolve storing a secret by creating it, or replacing it when it exists */
-declare function storeSecret(store: SecretStore, name: string, value: string): Promise<Outcome<void>>;
+export declare function storeSecret(store: SecretStore, name: string, value: string): Promise<Outcome<void>>;
 /** Delete a secret by name from the given secret store and return the operation outcome */
-declare function deleteSecret(store: SecretStore, name: string): Promise<Outcome<void>>;
+export declare function deleteSecret(store: SecretStore, name: string): Promise<Outcome<void>>;
 /** Represent a token with its expiration date and associated scope */
-interface ScopedTokenResult {
+export interface ScopedTokenResult {
     token: string;
     expiresAt: Date;
     scope: ScopedTokenScope;
@@ -1642,9 +658,9 @@ interface ScopedTokenResult {
  * proxy a narrowed credential). Uses the SDK's native `box.mintScopedToken`,
  * which normalizes `expiresAt` to a Date — no hand-rolled wire call.
  */
-declare function mintSandboxScopedToken(box: SandboxInstance, options: MintScopedTokenOptions): Promise<Outcome<ScopedTokenResult>>;
+export declare function mintSandboxScopedToken(box: SandboxInstance, options: MintScopedTokenOptions): Promise<Outcome<ScopedTokenResult>>;
 /** Define options to manage deterministic session resumption and turn idempotency in sandboxed drive turns */
-interface DriveSandboxTurnOptions extends StreamSandboxPromptOptions {
+export interface DriveSandboxTurnOptions extends StreamSandboxPromptOptions {
     /** Deterministic resume key — required. Every tick for the same logical turn
      * MUST reuse it so a crash + re-drive finds the in-flight session instead of
      * starting a second agent run. */
@@ -1655,9 +671,9 @@ interface DriveSandboxTurnOptions extends StreamSandboxPromptOptions {
     wallCapMs?: number;
 }
 /** Resolve a sandbox turn by processing a message with given configuration and options */
-declare function driveSandboxTurn(shell: SandboxRuntimeConfig, box: SandboxInstance, message: string | PromptInputPart[], options: DriveSandboxTurnOptions): Promise<Outcome<TurnDriveResult>>;
+export declare function driveSandboxTurn(shell: SandboxRuntimeConfig, box: SandboxInstance, message: string | PromptInputPart[], options: DriveSandboxTurnOptions): Promise<Outcome<TurnDriveResult>>;
 /** Define transitions marking the start or finish of a sandbox step with associated details */
-type SandboxStepTransition = {
+export type SandboxStepTransition = {
     kind: 'step-start';
 } | {
     kind: 'step-finish';
@@ -1665,10 +681,12 @@ type SandboxStepTransition = {
     severed: boolean;
 };
 /** Resolve the severed stream event to a corresponding sandbox step transition or null */
-declare function classifySeveredStream(event: unknown): SandboxStepTransition | null;
+export declare function classifySeveredStream(event: unknown): SandboxStepTransition | null;
 /** Determine if an event is a terminal prompt event with type 'result' or 'done */
-declare function isTerminalPromptEvent(event: unknown): boolean;
+export declare function isTerminalPromptEvent(event: unknown): boolean;
 /** Resolve the interactive question text from a structured event or return null if none found */
-declare function detectInteractiveQuestion(event: unknown): string | null;
-
-export { type AppToolDescriptor, type BuildAppToolMcpServersOptions, type BuildSandboxToolFileMountsOptions, type D1PrewarmClaimStoreOptions, DEFAULT_PREWARM_CLAIM_TABLE, DEFAULT_PROVISION_TIMEOUT_MS, DEFAULT_SANDBOX_RESOURCES, DEFAULT_SIDECAR_PROCESS_PATTERN, type DriveSandboxTurnOptions, EGRESS_PROXY_RECOVERY_PHASE, EGRESS_PROXY_RECOVERY_REQUIRED, ENV_TOTAL_MAX_BYTES, ENV_VALUE_MAX_BYTES, type EnsureWorkspaceSandboxOptions, type LivenessProbeConfig, type MemberSyncSeam, type ModelSelection, type ModelSelectionError, type ModelSelectionFailure, type ModelSelectionSource, type Outcome, PREWARM_CLAIM_TABLE_DDL, PROVISION_PAYLOAD_MAX_BYTES, PYPI_EGRESS_DOMAINS, type PeekWorkspaceSandboxOutcome, type PrewarmClaimD1Like, type PrewarmClaimStore, type PrewarmDecision, type PrewarmEvent, type PrewarmOutcome, type PrewarmResult, type ProfileComposeOptions, type PromptInputPart, type ProviderResolutionConfig, type ProvisionPayloadSections, type ProvisionProfileSection, type ResolveSandboxClientCredentialsOptions, type ResolvedModel, type SafeSandboxErrorCause, type SafeSandboxErrorDiagnostics, type SandboxBuildContext, type SandboxClientCredentials, type SandboxCredentialEnvironment, SandboxEgressPolicyMismatchError, type SandboxEgressPolicySource, type SandboxExecChannel, type SandboxExecOptions, type SandboxExistingBoxStage, type SandboxFileBytesOutcome, type SandboxFileSizeOutcome, SandboxModelResolutionError, type SandboxPermissionLevel, type SandboxPrewarmScope, type SandboxPrewarmer, type SandboxPrewarmerOptions, type SandboxProvisionedObservation, type SandboxReadiness, SandboxRecoveryFailedError, type SandboxRecoveryPhase, type SandboxResourceConfig, type SandboxRestoreSpec, SandboxRuntimeAuthRefreshError, type SandboxRuntimeConfig, type SandboxScope, type SandboxSpendHooks, type SandboxStepTransition, type SandboxStreamEvent, type SandboxTerminalConnectionRouteOptions, type SandboxToolPathOptions, type SandboxToolSpec, type ScopedTokenResult, type SecretStore, type StoppedSandboxResumeFailure, type StoppedSandboxResumeRecovery, type StreamSandboxPromptOptions, type TerminalConnectionBoxLike, WORKSPACE_SANDBOX_HOST_EXHAUSTED, WORKSPACE_SANDBOX_MISSING, WORKSPACE_SANDBOX_RECOVERY_ACTIONS, WORKSPACE_SANDBOX_RECOVERY_CODES, WORKSPACE_SANDBOX_SNAPSHOT_MAX_AGE_MS, WORKSPACE_SANDBOX_UNRECOVERABLE, type WorkspaceSandboxEnsureContext, type WorkspaceSandboxInstanceLike, type WorkspaceSandboxManager, type WorkspaceSandboxManagerOptions, type WorkspaceSandboxRecoveryAction, type WorkspaceSandboxRecoveryCode, type WorkspaceSandboxRecoveryDecision, type WorkspaceSandboxRecoveryManager, WorkspaceSandboxRecoveryRequiredError, type WorkspaceSandboxRecoveryState, type WorkspaceSandboxRecoveryStore, type WorkspaceSandboxSnapshot, type WorkspaceSandboxSnapshotAssessment, type WorkspaceSandboxSnapshotAvailability, type WorkspaceSandboxSnapshotFreshness, type WriteProfileFilesOptions, adaptSandboxStream, assertEnvWithinLimits, assertProvisionPayloadWithinCap, assessWorkspaceSandboxSnapshot, attachReasoningEffort, buildAppToolMcpServers, buildProductEgressPolicy, buildSandboxToolFileMounts, buildSandboxToolPathSetupScript, classifySeveredStream, collectSandboxPromptText, createD1PrewarmClaimStore, createSandboxPrewarmer, createSandboxTerminalConnectionRoute, createWorkspaceSandboxManager, createWorkspaceSandboxRecoveryManager, deferredCorpusHash, deleteSecret, detectInteractiveQuestion, driveSandboxTurn, ensureWorkspaceSandbox, flattenHistory, formatSandboxProvisioningSupportDetails, formatSandboxProvisioningUserMessage, getClient, isEgressProxyRecoveryRequiredError, isSandboxApiBearerAuthFailure, isSandboxApiSandboxMissingFailure, isSandboxAuthFailure, isSandboxHostCapacityFailure, isTerminalPromptEvent, isWorkspaceSandboxRecoveryAction, isWorkspaceSandboxRecoveryCode, isWorkspaceSandboxRecoveryState, isWorkspaceSandboxSnapshotRestoreError, mergeExtraMcp, mergeHistoryIntoParts, mintSandboxScopedToken, peekWorkspaceSandbox, preferredWorkspaceSandboxRecoveryBoxKey, readSandboxBinaryBytes, requireTransportableModel, resetClientCache, resolveModel, resolveModelSelection, resolveSandboxClientCredentials, runSandboxPrompt, runSandboxToolPathSetup, sandboxToolBinDir, sandboxToolPath, sandboxToolRootDir, secretStoreFromClient, serializeSandboxProvisioningError, shellQuote, shouldRestoreWorkspaceSandboxRecovery, splitDeferredProfileFiles, statSandboxFileSize, storeSecret, streamSandboxPrompt, syncSandboxMemberAdd, syncSandboxMemberRemove, syncSandboxMemberRole, workspaceSandboxRecoveryDiagnostic, workspaceSandboxRecoveryFromError, workspaceSandboxRecoveryMessage, workspaceSandboxRecoveryRecommendedActions, writeProfileFilesToBox };
+export declare function detectInteractiveQuestion(event: unknown): string | null;
+export * from './workspace-sandbox-manager';
+export * from './terminal-connection';
+export * from './prewarm';
+export * from './prewarm-claim-d1';