@tangle-network/agent-app 0.45.53 → 0.45.55

package/dist/{model-CdCDfBA9.d.ts → runtime/model.d.ts}

@@ -7,7 +7,7 @@
  * shape feeds the sandbox SDK's `backend.model`. Lifted here so no product
  * hand-rolls the env parsing + the router default.
  */
-interface TangleModelConfig {
+export interface TangleModelConfig {
     /** The Tangle Router is OpenAI-compatible → driven via `openai-compat`.
      *  `anthropic` is the BYOK escape hatch. */
     provider: 'openai-compat' | 'anthropic';
@@ -16,20 +16,20 @@ interface TangleModelConfig {
     baseUrl: string;
 }
 /** Define the environment context for executing Tangle operations */
-type TangleExecutionEnvironment = 'development' | 'staging' | 'production' | 'test';
+export type TangleExecutionEnvironment = 'development' | 'staging' | 'production' | 'test';
 /** Resolve the source of the Tangle execution key as either local environment or user input */
-type TangleExecutionKeySource = 'local-env' | 'user';
+export type TangleExecutionKeySource = 'local-env' | 'user';
 /** Define error codes for Tangle execution key issues related to API key and account connection */
-type TangleExecutionKeyErrorCode = 'local_tangle_api_key_required' | 'tangle_account_not_connected';
+export type TangleExecutionKeyErrorCode = 'local_tangle_api_key_required' | 'tangle_account_not_connected';
 /** Resolve options for model configuration including environment variables and default router base URL */
-interface ResolveModelOptions {
+export interface ResolveModelOptions {
     /** Env to read (defaults to process.env). */
     env?: Record<string, string | undefined>;
     /** Router base URL default when `TANGLE_ROUTER_BASE_URL` is unset. */
     defaultRouterBaseUrl?: string;
 }
 /** Resolve options for retrieving user API keys within a specific Tangle execution environment */
-interface ResolveUserTangleExecutionKeyOptions {
+export interface ResolveUserTangleExecutionKeyOptions {
     /** Deployment context. Only local development may fall back to env keys. */
     environment?: TangleExecutionEnvironment;
     /** Env to read for the local-development fallback. */
@@ -38,19 +38,19 @@ interface ResolveUserTangleExecutionKeyOptions {
     getUserApiKey: () => string | null | undefined | Promise<string | null | undefined>;
 }
 /** Resolve options for retrieving a user's Tangle execution key with environment and API key access parameters */
-interface ResolveUserTangleExecutionKeyForUserOptions<UserId = string> {
+export interface ResolveUserTangleExecutionKeyForUserOptions<UserId = string> {
     userId: UserId;
     environment?: TangleExecutionEnvironment;
     env?: Record<string, string | undefined>;
     getUserApiKey: (userId: UserId) => string | null | undefined | Promise<string | null | undefined>;
 }
 /** Define a resolved key combining an API key with its Tangle execution source */
-interface ResolvedTangleExecutionKey {
+export interface ResolvedTangleExecutionKey {
     apiKey: string;
     source: TangleExecutionKeySource;
 }
 /** Resolve options for retrieving a Tangle developer or user API key based on environment and context */
-interface ResolveTangleDevOrUserKeyOptions {
+export interface ResolveTangleDevOrUserKeyOptions {
     /** Deployment context. Only local development may use the env key. */
     environment?: TangleExecutionEnvironment;
     /** Env to read for the local-development fallback. */
@@ -59,7 +59,7 @@ interface ResolveTangleDevOrUserKeyOptions {
     getUserApiKey: () => string | null | undefined | Promise<string | null | undefined>;
 }
 /** Represent HTTP error response containing status, error message, and specific error code */
-interface TangleExecutionKeyHttpError {
+export interface TangleExecutionKeyHttpError {
     status: number;
     body: {
         error: string;
@@ -67,13 +67,13 @@ interface TangleExecutionKeyHttpError {
     };
 }
 /** Define configuration options for creating a Tangle router model including API key and model details */
-interface CreateTangleRouterModelConfigOptions {
+export interface CreateTangleRouterModelConfigOptions {
     apiKey: string;
     model: string;
     baseUrl?: string;
 }
 /** Define options for configuring billing enforcement environment variables and overrides */
-interface TangleBillingEnforcementOptions {
+export interface TangleBillingEnforcementOptions {
     /** Env to read (defaults to process.env). */
     env?: Record<string, string | undefined>;
     /**
@@ -83,21 +83,21 @@ interface TangleBillingEnforcementOptions {
     enforcementEnvVar?: string;
 }
 /** Provide the default base URL for the Tangle router API endpoint */
-declare const DEFAULT_TANGLE_ROUTER_BASE_URL = "https://router.tangle.tools/v1";
+export declare const DEFAULT_TANGLE_ROUTER_BASE_URL = "https://router.tangle.tools/v1";
 /** Define the default environment variable name for Tangle billing enforcement */
-declare const DEFAULT_TANGLE_BILLING_ENFORCEMENT_ENV_VAR = "TANGLE_BILLING_ENFORCEMENT";
+export declare const DEFAULT_TANGLE_BILLING_ENFORCEMENT_ENV_VAR = "TANGLE_BILLING_ENFORCEMENT";
 /** Resolve a string by trimming whitespace or returning null if empty or undefined */
-declare function trimOrNull(value: string | null | undefined): string | null;
+export declare function trimOrNull(value: string | null | undefined): string | null;
 /** Represent execution key errors with specific codes and HTTP status information */
-declare class TangleExecutionKeyError extends Error {
+export declare class TangleExecutionKeyError extends Error {
     readonly code: TangleExecutionKeyErrorCode;
     readonly status: number;
     constructor(code: TangleExecutionKeyErrorCode, message: string, status: number);
 }
 /** Identify whether an error is a TangleExecutionKeyError based on its properties and type */
-declare function isTangleExecutionKeyError(error: unknown): error is TangleExecutionKeyError;
+export declare function isTangleExecutionKeyError(error: unknown): error is TangleExecutionKeyError;
 /** Resolve the current Tangle execution environment based on provided or process environment variables */
-declare function resolveTangleExecutionEnvironment(env?: Record<string, string | undefined>): TangleExecutionEnvironment;
+export declare function resolveTangleExecutionEnvironment(env?: Record<string, string | undefined>): TangleExecutionEnvironment;
 /**
  * Shared policy for agent products that bill through the Tangle Platform.
  *
@@ -107,16 +107,16 @@ declare function resolveTangleExecutionEnvironment(env?: Record<string, string |
  * override flag (`FOO_BILLING_ENFORCEMENT`) while new apps can use the shared
  * `TANGLE_BILLING_ENFORCEMENT`.
  */
-declare function isTangleBillingEnforcementDisabled(opts?: TangleBillingEnforcementOptions): boolean;
+export declare function isTangleBillingEnforcementDisabled(opts?: TangleBillingEnforcementOptions): boolean;
 /** Resolve and format TangleExecutionKey HTTP errors into a standardized error object or return null */
-declare function tangleExecutionKeyHttpError(error: unknown): TangleExecutionKeyHttpError | null;
+export declare function tangleExecutionKeyHttpError(error: unknown): TangleExecutionKeyHttpError | null;
 /**
  * Shared dev-aware Tangle key resolution. Local development may use a server
  * `TANGLE_API_KEY`; otherwise the caller's linked platform key is used. Returns
  * null when neither resolves, so each caller can throw its own domain error
  * (e.g. model-execution 503/401 vs hub `tangle_link_required` 412).
  */
-declare function resolveTangleDevOrUserKey(opts: ResolveTangleDevOrUserKeyOptions): Promise<ResolvedTangleExecutionKey | null>;
+export declare function resolveTangleDevOrUserKey(opts: ResolveTangleDevOrUserKeyOptions): Promise<ResolvedTangleExecutionKey | null>;
 /**
  * Resolve the user-facing Tangle API key for model execution.
  *
@@ -124,14 +124,14 @@ declare function resolveTangleDevOrUserKey(opts: ResolveTangleDevOrUserKeyOption
  * Deployed contexts must use the caller's linked platform key; this keeps
  * model execution, billing, and account ownership aligned across products.
  */
-declare function resolveUserTangleExecutionKey(opts: ResolveUserTangleExecutionKeyOptions): Promise<ResolvedTangleExecutionKey>;
+export declare function resolveUserTangleExecutionKey(opts: ResolveUserTangleExecutionKeyOptions): Promise<ResolvedTangleExecutionKey>;
 /** Resolve the Tangle execution key for a specified user using provided environment and API key options */
-declare function resolveUserTangleExecutionKeyForUser<UserId = string>(opts: ResolveUserTangleExecutionKeyForUserOptions<UserId>): Promise<ResolvedTangleExecutionKey>;
+export declare function resolveUserTangleExecutionKeyForUser<UserId = string>(opts: ResolveUserTangleExecutionKeyForUserOptions<UserId>): Promise<ResolvedTangleExecutionKey>;
 /**
  * Build an OpenAI-compatible Tangle Router model config from an already
  * resolved execution key. This intentionally does not read TANGLE_API_KEY.
  */
-declare function createTangleRouterModelConfig(opts: CreateTangleRouterModelConfigOptions): TangleModelConfig;
+export declare function createTangleRouterModelConfig(opts: CreateTangleRouterModelConfigOptions): TangleModelConfig;
 /**
  * Resolve the model config from env. DEFAULT path (`MODEL_PROVIDER` unset or
  * `openai-compat`/`tangle-router`/`tcloud`): the Tangle Router, authenticated
@@ -140,6 +140,4 @@ declare function createTangleRouterModelConfig(opts: CreateTangleRouterModelConf
  * `ANTHROPIC_BASE_URL`. Throws (fail-loud) on a missing required var so a
  * misconfigured deploy fails at boot, not mid-turn.
  */
-declare function resolveTangleModelConfig(opts?: ResolveModelOptions): TangleModelConfig;
-
-export { type CreateTangleRouterModelConfigOptions as C, DEFAULT_TANGLE_BILLING_ENFORCEMENT_ENV_VAR as D, type ResolveModelOptions as R, type TangleModelConfig as T, type TangleExecutionEnvironment as a, type TangleExecutionKeySource as b, DEFAULT_TANGLE_ROUTER_BASE_URL as c, type ResolveTangleDevOrUserKeyOptions as d, type ResolveUserTangleExecutionKeyForUserOptions as e, type ResolveUserTangleExecutionKeyOptions as f, type ResolvedTangleExecutionKey as g, type TangleBillingEnforcementOptions as h, TangleExecutionKeyError as i, type TangleExecutionKeyErrorCode as j, type TangleExecutionKeyHttpError as k, createTangleRouterModelConfig as l, isTangleBillingEnforcementDisabled as m, isTangleExecutionKeyError as n, resolveTangleExecutionEnvironment as o, resolveTangleModelConfig as p, resolveUserTangleExecutionKey as q, resolveTangleDevOrUserKey as r, resolveUserTangleExecutionKeyForUser as s, tangleExecutionKeyHttpError as t, trimOrNull as u };
+export declare function resolveTangleModelConfig(opts?: ResolveModelOptions): TangleModelConfig;

package/dist/runtime/openai-stream.d.ts

@@ -0,0 +1,126 @@
+/**
+ * OpenAI-compatible stream → `LoopEvent` adapter, for NON-sandbox copilots.
+ *
+ * `streamAppToolLoop` takes a `streamTurn` seam that yields `LoopEvent`s. A
+ * sandboxed agent produces those from its container; a browser/edge copilot
+ * instead calls a model directly. The Tangle Router, the tcloud SDK, and most
+ * providers all speak the OpenAI Chat Completions streaming shape — so the ONE
+ * reusable piece is assembling that stream (content deltas + FRAGMENTED
+ * tool-call deltas) into `LoopEvent`s. That assembly is the boilerplate every
+ * copilot would re-write (and get wrong — OpenAI streams tool-call arguments in
+ * pieces across chunks).
+ *
+ * This does NOT implement an HTTP client beyond a minimal `fetch` + SSE reader
+ * (browser/edge/Node-safe, zero deps). For richer transport use the tcloud SDK
+ * or the Vercel AI SDK and pipe their stream through {@link toLoopEvents}.
+ */
+import type { LoopEvent, LoopMessage } from './loop';
+/** Minimal OpenAI Chat Completions streaming chunk (structural — no `openai` dep). */
+export interface OpenAIStreamChunk {
+    /** The model that produced this chunk. The Tangle Router reports the DATED
+     *  upstream id here (`gpt-5-2025-08-07`) whether or not it substituted, so
+     *  this is a served-model source only after id folding — see
+     *  {@link OpenAICompatServedModel}. */
+    model?: string;
+    choices?: Array<{
+        delta?: {
+            content?: string | null;
+            /** Reasoning deltas — DeepSeek/router use `reasoning_content`; some proxies use `thinking`. */
+            reasoning_content?: string | null;
+            thinking?: string | null;
+            tool_calls?: Array<{
+                index: number;
+                id?: string;
+                function?: {
+                    name?: string;
+                    arguments?: string;
+                };
+            }>;
+        };
+        finish_reason?: string | null;
+    }>;
+    /** Final-chunk token accounting (requires `stream_options.include_usage`). */
+    usage?: {
+        prompt_tokens?: number;
+        completion_tokens?: number;
+    } | null;
+}
+/**
+ * Map an OpenAI-compat streaming chunk iterator to `LoopEvent`s: each content
+ * delta → a `text` event; tool-call deltas are accumulated by index across
+ * chunks and emitted as one complete `tool_call` event when the stream finishes
+ * (arguments JSON-parsed; an empty/garbled args string yields `{}` rather than
+ * throwing). Works for the Tangle Router, tcloud, or any OpenAI-compat source.
+ */
+export declare function toLoopEvents(chunks: AsyncIterable<OpenAIStreamChunk>): AsyncIterable<LoopEvent>;
+/**
+ * Which model actually served one direct-router turn.
+ *
+ * The router substitutes models on purpose — a quota-walled primary comes back
+ * `200` answered by a different model — and says so in response headers. This
+ * lane used to drop the whole `Response` after taking `.body`, so a turn
+ * requested as `claude-sonnet-4-6` and answered by `openai/gpt-5` was recorded
+ * by its caller as Claude: per-model quality scoring blamed the wrong model and
+ * cost used the wrong price basis.
+ *
+ * Map this onto the shell's existing attribution contract rather than inventing
+ * a second channel — `ChatTurnRouteProducer.modelAttribution()` (`/chat-routes`):
+ *
+ *     modelAttribution: () => ({ requestedModel, servedModel, echoReceived: true })
+ *
+ * Leave that contract's `servedSource` unset: its union is sandbox
+ * profile-resolution vocabulary with no router analogue.
+ */
+export interface OpenAICompatServedModel {
+    /** The model id this turn asked for (`OpenAICompatStreamTurnOptions.model`). */
+    requestedModel: string;
+    /** The model the router/provider reports having actually served. */
+    servedModel: string;
+    /** Where `servedModel` was read from. The header is the router's own
+     *  substitution signal; the body is the backstop that survives CORS. */
+    source: 'router_header' | 'response_body';
+    /** True when served differs from requested after id folding. Folded, not
+     *  compared raw: the body reports a dated id on EVERY turn, so `!==` would
+     *  claim a substitution every time. */
+    substituted: boolean;
+    /** `x-tangle-failover` `trigger=` — why the router swapped. Absent when the
+     *  router did not inject the substitute (a caller-supplied fallback chain
+     *  sets the served-model header without the failover one). */
+    trigger?: string;
+    /** `x-tangle-failover` `degraded=`. */
+    degraded?: boolean;
+}
+/** Define options for configuring an OpenAI-compatible streaming chat turn including API details and tools */
+export interface OpenAICompatStreamTurnOptions {
+    /** OpenAI-compat base URL (e.g. the Tangle Router `https://router.tangle.tools/v1`). */
+    baseUrl: string;
+    apiKey: string;
+    model: string;
+    /** OpenAI tool definitions — pass `buildAppToolOpenAITools(taxonomy)` so the
+     *  model can call the app tools. Omit for a tool-free copilot. */
+    tools?: unknown[];
+    temperature?: number;
+    fetchImpl?: typeof fetch;
+    /** Extra body fields (e.g. `max_tokens`). */
+    extraBody?: Record<string, unknown>;
+    /**
+     * Called at most ONCE per turn, as soon as the serving model is
+     * determinable, with what actually answered. Never called when neither the
+     * header nor the body names a model — silence means "learned nothing", not
+     * "nothing was substituted".
+     *
+     * `streamTurn` runs once per TOOL turn, so a multi-turn `runAppToolLoop`
+     * fires this once per turn; take the last for row attribution.
+     */
+    onServedModel?: (served: OpenAICompatServedModel) => void;
+}
+/**
+ * Build a `streamTurn` that calls an OpenAI-compatible `/chat/completions`
+ * endpoint (Tangle Router / tcloud / any compat provider) with `stream: true`
+ * and yields `LoopEvent`s via {@link toLoopEvents}. Browser/edge/Node-safe —
+ * just `fetch` + an SSE reader. Drop straight into `streamAppToolLoop`:
+ *
+ *   const cfg = resolveTangleModelConfig()                 // or { baseUrl, apiKey, model }
+ *   streamAppToolLoop({ streamTurn: createOpenAICompatStreamTurn({ ...cfg, tools }), executeToolCall, ... })
+ */
+export declare function createOpenAICompatStreamTurn(opts: OpenAICompatStreamTurnOptions): (messages: LoopMessage[]) => AsyncIterable<LoopEvent>;

package/dist/runtime/surface-profile.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Surface-scoped profile overlay — the seam letting any product page (a
+ * sequence editor, a brief composer, a dataset view) add MCP servers, a prompt
+ * addendum, and permission tightening to the workspace agent profile for turns
+ * initiated FROM that surface, without the chat orchestrator knowing any
+ * surface's specifics. The orchestrator resolves `(kind, ctx)` through a
+ * registry the REQUEST HANDLER constructs per request (construction is a Map
+ * build — cheap) and merges the result into the base profile it was about to
+ * send to the sandbox. Per-request construction is the trust mechanism, not an
+ * optimization target: each `build()` closes over server-trusted request state
+ * (env bindings, secrets, the AUTHENTICATED user/workspace), which on Workers
+ * exists only per request — a startup-built registry would force identity
+ * through the untrusted client `ctx`.
+ *
+ * SECURITY INVARIANT: the surface `kind` and the ids inside `ctx` arrive on
+ * the client request and are pure ROUTING data — never trusted content, never
+ * identity. Identity comes from the closure (see above). The registered
+ * `build()` runs server-side only: it validates the routing ids against the
+ * product's access control, then mints its own URLs from server configuration
+ * (`buildHttpMcpServer` in ../tools). A client can therefore never inject an
+ * arbitrary MCP url, header, or credential into the agent profile: the
+ * overlay's `mcp` values are typed as {@link SurfaceMcpServer} (= the
+ * server-built `AppToolMcpServer` entry shape), and only build() constructs
+ * them.
+ *
+ * The credential itself never appears in the overlay. Since the tagged-config
+ * contract (`agent-interface` 0.38.0) the `Authorization` header is a
+ * `secret-ref` naming a box-environment variable, which the sandbox resolves
+ * privately; `build()` supplies that key NAME from server configuration and the
+ * product writes the value into `SandboxRuntimeConfig.env` at box creation. The
+ * value must be deterministic for the box's lifetime (an HMAC over the
+ * workspace id, e.g. `createCapabilityToken` in ../tools), because a freshly
+ * random per-request mint would never match what the box already carries.
+ */
+import type { AppToolMcpServer } from '../tools/mcp';
+/** Sandbox permission posture values, ranked deny > ask > allow for merging. */
+export type SurfacePermissionValue = 'allow' | 'ask' | 'deny';
+/** The only MCP entry shape an overlay may carry: the server-built bridge
+ *  entry from ../tools/mcp (transport, url, headers, and capability token all
+ *  assembled server-side). The alias exists so overlay authors reach for the
+ *  builders in ../tools rather than hand-rolling `{ url: ctx.url }` shapes
+ *  that would let request data become a dialable endpoint. */
+export type SurfaceMcpServer = AppToolMcpServer;
+/** What one surface contributes to the agent profile for a single turn. */
+export interface SurfaceOverlay {
+    /** MCP servers to mount for this turn, keyed by tool-routing name. Names
+     *  must not collide with the base profile's — see {@link mergeSurfaceOverlay}. */
+    mcp?: Record<string, SurfaceMcpServer>;
+    /** Appended to the base system-prompt addendum with a blank-line separator. */
+    promptAddendum?: string;
+    /** Per-key posture the surface wants for its turns. Merging is monotone
+     *  fail-closed: the stricter of base/overlay wins, so a surface can tighten
+     *  the workspace posture but never relax it. */
+    permissions?: Record<string, SurfacePermissionValue>;
+}
+/**
+ * One registered surface kind. `TCtx` is the shape build() expects — a CLAIM
+ * about the client payload, not a guarantee: the registry hands build() the
+ * request's `ctx` unvalidated, so build() must treat every field as an
+ * untrusted id (resolve it through access control that throws on a bad or
+ * foreign id) before minting anything from it.
+ */
+export interface SurfaceKindDefinition<TCtx> {
+    kind: string;
+    build: (ctx: TCtx) => SurfaceOverlay | Promise<SurfaceOverlay>;
+}
+/** The variance-erased form a registry accepts (`build` is contravariant in
+ *  `TCtx`, so every concrete definition is assignable to this). */
+export type AnySurfaceKind = SurfaceKindDefinition<never>;
+/**
+ * Declare one surface kind. The `kind` string is the client-visible routing
+ * key (e.g. `'sequences'`); `build` is the server-side factory that turns a
+ * validated ctx into the overlay for one turn.
+ */
+export declare function defineSurfaceKind<TCtx>(opts: {
+    kind: string;
+    build: (ctx: TCtx) => SurfaceOverlay | Promise<SurfaceOverlay>;
+}): SurfaceKindDefinition<TCtx>;
+/** Resolve and build the overlay for a given surface kind within a turn context */
+export interface SurfaceRegistry {
+    /** Build the overlay for one turn. Throws on an unknown kind — an unknown
+     *  surface is a routing bug (client and server registries drifted), and
+     *  silently returning an empty overlay would strip the surface's tools from
+     *  the turn with no signal anywhere. Build errors propagate unwrapped. */
+    resolve(kind: string, ctx: unknown): Promise<SurfaceOverlay>;
+}
+/**
+ * Assemble the product's surface registry from its registered kinds. Duplicate
+ * kinds throw at construction: two builders behind one routing key would make
+ * the mounted toolset depend on registration order.
+ */
+export declare function createSurfaceRegistry(kinds: readonly AnySurfaceKind[]): SurfaceRegistry;
+/** Base-profile slice the merge reads/writes. Real callers pass their full
+ *  profile object; every field outside this slice passes through untouched. */
+export interface SurfaceMergeBase {
+    mcp?: Record<string, unknown>;
+    systemPromptAddendum?: string;
+    permissions?: Record<string, SurfacePermissionValue>;
+}
+/**
+ * Merge one surface overlay into a base profile, returning a new object
+ * (the base is never mutated; untouched nested records are shared by
+ * reference).
+ *
+ * - `mcp`: overlay servers are added under their own names. A name already
+ *   present on the base THROWS — a collision is two servers claiming one
+ *   routing name, and renaming either silently would corrupt tool routing for
+ *   whichever caller expected the original binding.
+ * - `systemPromptAddendum`: the overlay's `promptAddendum` appends after a
+ *   blank-line separator (no separator when the base has no addendum).
+ * - `permissions`: per key the STRICTER value wins (deny > ask > allow). A
+ *   surface can tighten the base posture for its turns; a base 'deny' survives
+ *   any overlay.
+ */
+export declare function mergeSurfaceOverlay<TBase extends SurfaceMergeBase>(base: TBase, overlay: SurfaceOverlay): TBase & SurfaceMergeBase;

package/dist/sandbox/binary-read.d.ts

@@ -0,0 +1,63 @@
+/**
+ * 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. */
+export 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 */
+export 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 */
+export 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 */
+export 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. */
+export 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. */
+export 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. */
+export declare function readSandboxBinaryBytes(box: SandboxExecChannel, absolutePath: string, expectedSize: number, options?: SandboxExecOptions): Promise<SandboxFileBytesOutcome>;

package/dist/sandbox/diagnostics.d.ts

@@ -0,0 +1,69 @@
+export interface SafeSandboxErrorCause {
+    name?: string;
+    message?: string;
+    code?: string | number;
+    status?: string | number;
+    phase?: string;
+    endpoint?: string;
+    origin?: string;
+    retryAfterMs?: number;
+    sidecarVersion?: string;
+    containerImage?: string;
+}
+export interface SafeSandboxErrorDiagnostics {
+    message: string;
+    causes: SafeSandboxErrorCause[];
+    truncated: boolean;
+    truncatedAtDepth?: number;
+    cycle: boolean;
+}
+export declare function serializeSandboxProvisioningError(error: unknown, options?: {
+    maxDepth?: number;
+}): SafeSandboxErrorDiagnostics;
+export declare function formatSandboxProvisioningSupportDetails(diagnostics: SafeSandboxErrorDiagnostics): string;
+export declare function isSandboxAuthFailure(diagnostics: SafeSandboxErrorDiagnostics): boolean;
+export 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.
+ */
+export 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.
+ */
+export declare function isSandboxHostCapacityFailure(diagnostics: SafeSandboxErrorDiagnostics): boolean;
+/**
+ * True when a resume failed on the box's own configuration rather than on
+ * anything a retry can change.
+ *
+ * These are permanent facts about one box: the platform cannot rebuild its
+ * proxy because the egress policy it was created with is no longer recorded, so
+ * the box can never start again where it is. The platform says as much in the
+ * message — "re-apply the sandbox egress policy and retry" is a description of
+ * creating a fresh box, since policy is applied at creation.
+ *
+ * Narrow on purpose. A bare 500 from the sandbox API is transient far more
+ * often than not, and treating one as unbringable would delete a healthy box.
+ * Matched on the specific unrecoverable phrasing, and only from `sandbox-api`.
+ */
+export declare function isSandboxBoxConfigFailure(diagnostics: SafeSandboxErrorDiagnostics): boolean;
+export declare function formatSandboxProvisioningUserMessage(diagnostics: SafeSandboxErrorDiagnostics): string;