@tangle-network/agent-app 0.44.28 → 0.44.30

package/dist/{parts-fyPPdDdK.d.ts → parts-7fbe2rj8.d.ts}

@@ -1,278 +1,8 @@
 import { Part } from '@tangle-network/agent-interface';
-import { a as ChatInteractionField, C as ChatInteractionStatus, I as InteractionAnswers, N as NoticeKind } from './contract-CEewO6DI.js';
-import { c as WorkProductPersistedPart } from './types-DB82fktc.js';
+import { C as ChatInteractionField, a as ChatInteractionStatus, I as InteractionAnswers, N as NoticeKind } from './contract-CQNvv5th.js';
+import { W as WorkProductPersistedPart } from './types-CCeYywdS.js';
 import { ChatPlanPersistedPart } from './plans/index.js';
-
-/**
- * Wire contract between the chat client (composer + `streamChatTurn`) and the
- * assembled server vertical (`createChatTurnRoutes`). Import-free on purpose:
- * `/web-react` re-exports these types into browser bundles, so nothing here may
- * reach a Node builtin or an engine package.
- *
- * The client part shape permits an absolute file path until the server converts
- * it to the URL required by the sandbox SDK. It is derived here, not imported,
- * so the client bundle never touches the SDK.
- */
-interface ChatTurnTextPartInput {
-    type: 'text';
-    text: string;
-}
-/** A non-text prompt part the upload route hands back and the client echoes
- *  on send. `url` carries an inline `data:` URI for small files; `path` is a
- *  sandbox workspace reference for large ones (the >1 MiB gateway body cap
- *  makes the two-step upload mandatory). */
-interface ChatTurnFilePartInput {
-    type: 'image' | 'file';
-    filename?: string;
-    mediaType?: string;
-    url?: string;
-    path?: string;
-}
-/** Resolve input as either a text part or a file part of a chat turn */
-type ChatTurnPartInput = ChatTurnTextPartInput | ChatTurnFilePartInput;
-/** Represent a text event produced by a source with a fixed type and associated text content */
-interface ProducerTextEvent {
-    type: 'text';
-    text: string;
-}
-/** Define an event representing reasoning output with a fixed type and associated text */
-interface ProducerReasoningEvent {
-    type: 'reasoning';
-    text: string;
-}
-/** Represent an event triggered by a producer tool call with its identifier, name, and arguments */
-interface ProducerToolCallEvent {
-    type: 'tool_call';
-    call: {
-        toolCallId: string;
-        toolName: string;
-        args: Record<string, unknown>;
-    };
-}
-/** Describe the structure of an event representing the result of a producer tool call */
-interface ProducerToolResultEvent {
-    type: 'tool_result';
-    toolCallId: string;
-    toolName: string;
-    outcome: {
-        ok: boolean;
-        result?: unknown;
-        message?: string;
-    };
-}
-/** Describe usage event with prompt and completion token counts for a producer */
-interface ProducerUsageEvent {
-    type: 'usage';
-    usage: {
-        promptTokens: number;
-        completionTokens: number;
-    };
-}
-/** Define the structure for a producer notice event with type, id, kind, and text fields */
-interface ProducerNoticeEvent {
-    type: 'notice';
-    id: string;
-    /** Kept inline with `/interactions`' `NoticeKind` so this file stays import-free. */
-    noticeKind: 'warning' | 'auto-declined';
-    text: string;
-}
-/** Represent an error event emitted by a producer containing message, code, and optional details */
-interface ProducerErrorEvent {
-    type: 'error';
-    data: {
-        message: string;
-        code?: string;
-        details?: Record<string, unknown>;
-    };
-}
-/** Stable raw lifecycle/interaction/plan/route events forwarded unchanged. */
-type ProducerPassthroughEventType = 'turn' | 'metadata' | 'interaction' | 'interaction.cancel' | 'plan.submitted' | 'done' | 'warning' | 'session.run.started' | 'session.run.completed' | 'session.run.failed' | 'turn_status';
-/** Define an event carrying passthrough data with flexible properties for producer communication */
-interface ProducerPassthroughEvent {
-    type: ProducerPassthroughEventType;
-    data?: Record<string, unknown>;
-    /** Route markers and raw passthroughs may carry `turnId`, `status`, `seq`, etc. */
-    [key: string]: unknown;
-}
-/** Represent events emitted by a producer during its operation for processing and handling */
-type ProducerWireEvent = ProducerTextEvent | ProducerReasoningEvent | ProducerToolCallEvent | ProducerToolResultEvent | ProducerUsageEvent | ProducerNoticeEvent | ProducerErrorEvent | ProducerPassthroughEvent;
-/** The image/file split an attachment is rendered and persisted under — the
- *  same discriminant as {@link ChatMentionKind}, but a distinct name because an
- *  attachment carries content the product uploaded (`ChatAttachmentInput`)
- *  while a mention points at a file the box already has. Defined HERE (the
- *  import-free layer) so `ChatAttachmentInput` can reference it and the client
- *  composer imports it without pulling the persisted-part vocabulary;
- *  `/chat-store`'s parts module re-exports it alongside the attachment helpers. */
-type ChatAttachmentKind = 'image' | 'file';
-/** `POST` turn-body entry describing a file already uploaded to the product's
- *  store (vault/object-store) — distinct from an inline {@link
- *  ChatTurnFilePartInput} (which carries bytes) and from a {@link FileMention}
- *  (a sandbox path the box already holds). The route resolves this field with
- *  {@link resolveChatAttachments}: every path is re-validated and every size is
- *  re-derived from the stored body, so nothing here is trusted as sent. */
-interface ChatAttachmentInput {
-    path: string;
-    name: string;
-    size: number;
-    mediaType: string;
-    kind: ChatAttachmentKind;
-}
-/** POST body for the turn route. `content` may be empty when `parts` carry the
- *  message (an image-only send). Product routing fields (workspaceId etc.) ride
- *  alongside and are read by the product's `authorize` seam. */
-interface ChatTurnRequestPayload {
-    threadId: string;
-    content?: string;
-    /** Non-text parts from the upload route, echoed back verbatim. */
-    parts?: ChatTurnFilePartInput[];
-    /** `@`-picked file mentions for this turn — path references into the
-     *  workspace sandbox, NOT uploads, so they travel in their own field rather
-     *  than as `parts` entries. A product whose `parts` field is already spoken
-     *  for (an attachment sentinel) can still send mentions, and mentions
-     *  persist as their own `ChatMentionPart`s so a retry rebuilds them. The
-     *  route validates this field with {@link parseFileMentions} and replaces it
-     *  on the payload with the validated, deduped list. */
-    mentions?: FileMention[];
-    /** Files uploaded to the product's store ahead of the turn — path
-     *  references, NOT inline bytes (those ride `parts`). Validated and
-     *  size-re-derived by {@link resolveChatAttachments} into persistable
-     *  attachment parts; a product whose `parts` field is spoken for by inline
-     *  uploads still sends store-backed files here. */
-    attachments?: ChatAttachmentInput[];
-    model?: string;
-    effort?: 'auto' | 'low' | 'medium' | 'high';
-    harness?: string;
-    /** Client-generated idempotency key for the logical turn (retry-safe). */
-    turnId?: string;
-    [key: string]: unknown;
-}
-/** `fetch` init for the turn route — the one place the client wire shape is
- *  serialized, so composer glue and products never drift from the server's
- *  parser. */
-declare function chatTurnRequestInit(payload: ChatTurnRequestPayload): RequestInit;
-/** Define the maximum byte size allowed for inline parts in data processing */
-declare const INLINE_PARTS_MAX_BYTES = 950000;
-/** Hard cap on the whole `/prompt` request body as it crosses the sandbox
- *  proxy — smaller in practice than a raw-file write cap because a dispatch
- *  carries several inline parts plus the flattened history in one request. */
-declare const DISPATCH_REQUEST_MAX_BYTES: number;
-/** Bytes reserved off the top of {@link DISPATCH_REQUEST_MAX_BYTES} for the
- *  JSON structure around the parts array (keys, delimiters, per-part
- *  `type`/`filename`/`mediaType` fields) that {@link base64WireLen} does not
- *  account for — keeps the inline budget off the exact proxy cap where one
- *  stray byte trips the 413. */
-declare const DISPATCH_STRUCTURAL_RESERVE_BYTES: number;
-/** Sidecar's hard cap on the `parts` array of one prompt request — a dispatch
- *  must never assemble more parts than this or the whole turn 400s. */
-declare const DISPATCH_MAX_PARTS = 64;
-/** Product-side cap on media parts per dispatch (current turn + carried
- *  history), well under {@link DISPATCH_MAX_PARTS}. History trimming that keeps
- *  a transcript's native media under this is a PRODUCT concern (the pointer
- *  block keeps trimmed media reachable); `buildDispatchParts` enforces only the
- *  total {@link DISPATCH_MAX_PARTS} cap. */
-declare const DISPATCH_MAX_MEDIA_PARTS = 24;
-/** Size a base64-encoded string occupies on the wire given the raw
- *  (pre-encoding) byte length: base64 packs 3 raw bytes into 4 output
- *  characters, rounded up to the next multiple of 4. */
-declare function base64WireLen(byteLen: number): number;
-/**
- * Render a raw byte count as a human-readable size (`512B`, `3KB`, `12MB
- * 500KB`). Ported EXACTLY from gtm-agent's `attachment-limits.ts` — byte-
- * identical implementation, not a reinterpretation — so `resolve-attachments`'s
- * and `promote-file-part`'s error strings match gtm's wording verbatim. Lives
- * in the import-free wire layer (not `resolve-attachments.ts` alone) because
- * BOTH the aggregate-cap message here and the per-file oversize message in
- * `promote-file-part.ts` need it; a browser composer wanting the same
- * formatting for a client-side pre-check can also import it with no engine
- * pulled in.
- */
-declare function formatBytes(bytes: number): string;
-/** Represent errors for invalid chat turn inputs with status and code properties */
-declare class ChatTurnInputError extends Error {
-    readonly status: number;
-    readonly code: string;
-    constructor(message: string, status?: number, code?: string);
-}
-/** Calculate the total byte size of an array of chat turn parts */
-declare function promptPartsByteSize(parts: ChatTurnPartInput[]): number;
-/** Throws `ChatTurnInputError` (413) when the parts' inline payload would blow
- *  the gateway cap. Path-ref parts are tiny by construction and always pass. */
-declare function assertPromptPartsWithinCap(parts: ChatTurnPartInput[], maxBytes?: number): void;
-/** A file mention resolved from the composer's `@`-picker: the
- *  workspace-relative path plus enough metadata to build a prompt part and
- *  pointer text. `path` is the canonical identity — the mention pill's
- *  `MentionItem.id` for the file kind (`/web-react`'s `useFileMentions`). */
-interface FileMention {
-    path: string;
-    name: string;
-    size?: number;
-}
-/** The `image/*` mime for a mention path by extension, or `undefined` for
- *  anything not in the known image set (dispatched as `type: 'file'`). */
-declare function mediaTypeForMentionPath(path: string): string | undefined;
-/** The image/file split a mention is rendered and persisted under — the
- *  composer pill's icon, the dispatched part's `type`, and
- *  `ChatMentionPart.mentionKind` are all this one value. */
-type ChatMentionKind = 'image' | 'file';
-/** `image` when the path's extension is in the known image set (the same table
- *  {@link mediaTypeForMentionPath} reads), `file` otherwise. Exported so a
- *  client that needs only the discriminant — a pill icon, a persisted part's
- *  `mentionKind` — never re-declares the extension table; two frozen copies of
- *  one mime table is how one gains a format and the other doesn't. */
-declare function mentionKindForPath(path: string): ChatMentionKind;
-/** Define options to resolve mention paths when converting file mentions to parts */
-interface FileMentionsToPartsOptions {
-    /** Resolve a mention's workspace-relative path to the absolute path the
-     *  dispatched part should carry (e.g. a host prefixing the in-box vault
-     *  root). Default: identity — the path travels unchanged. */
-    resolvePath?: (path: string) => string;
-}
-/** Maps resolved file mentions to path-only `ChatTurnFilePartInput`s —
- *  `image` vs `file` by extension, and always a `path`, never a `url` (the
- *  url/path XOR invariant: a mention is a sandbox path reference, never
- *  inline bytes). */
-declare function fileMentionsToParts(mentions: readonly FileMention[], opts?: FileMentionsToPartsOptions): ChatTurnFilePartInput[];
-/** The agent-facing pointer block appended to the dispatched prompt — never
- *  persisted in message `content`. Empty array → `''` so callers can append
- *  unconditionally. This is the sole producer of that text: the current
- *  turn's dispatch and any history projection built from the same mention
- *  list both route through here, so the two can't drift apart. */
-declare function buildMentionPromptBlock(mentions: readonly Pick<FileMention, 'name' | 'path'>[]): string;
-/** Hard cap on mentions per turn. Bounds the prompt pointer block, the
- *  persisted parts, and whatever media budget a dispatch draws from them. */
-declare const MENTION_MAX_COUNT = 16;
-/** Represent the result of a sandbox mention path check indicating success or failure with an error message */
-type SandboxMentionPathCheck = {
-    succeeded: true;
-} | {
-    succeeded: false;
-    error: string;
-};
-/**
- * Validate a workspace-relative sandbox mention path. Rejects traversal (a
- * `..` path segment), absolute paths (leading `/`), backslashes, and null
- * bytes — the four ways a path picked in a client can escape the root the
- * index route scanned.
- *
- * Spaces and unicode are deliberately ALLOWED: in-box filenames are arbitrary,
- * and an ASCII-only charset would silently drop real files from a feature
- * whose whole job is naming them.
- */
-declare function validateSandboxMentionPath(path: unknown): SandboxMentionPathCheck;
-/**
- * Validates the untyped `mentions` array off the wire, mirroring
- * {@link parseChatTurnParts}: the typed list, or `ChatTurnInputError` (400)
- * naming the offending entry. Never sanitizes-and-continues — a traversal path
- * is a rejected request, not a trimmed one.
- *
- * A path repeated within one turn is deduped to its first occurrence rather
- * than rejected: mentioning the same file twice is plausible user input, not
- * an attack.
- */
-declare function parseFileMentions(raw: unknown): FileMention[];
-/** Validates the untyped `parts` array off the wire. Returns the typed parts
- *  or throws `ChatTurnInputError` (400) naming the offending entry. */
-declare function parseChatTurnParts(raw: unknown): ChatTurnFilePartInput[];
+import { C as ChatMentionKind, a as ChatAttachmentKind, b as ChatAttachmentInput, F as FileMention } from './wire-DSp4LzEE.js';
 
 /**
  * The stored shape of `message.parts` — one typed vocabulary for every part a
@@ -606,4 +336,4 @@ declare function historyContentWithAttachments(message: {
     parts?: ReadonlyArray<Record<string, unknown>> | null;
 }, header?: string): string;
 
-export { type ProducerErrorEvent as $, isChatInteractionPart as A, isChatMentionPart as B, type ChatMessagePart as C, DEFAULT_ATTACHMENT_PROMPT_HEADER as D, isChatPlanPart as E, isChatStepFinishPart as F, isChatTextPart as G, isChatToolPart as H, isChatWorkProductPart as I, mentionInputToPart as J, mentionPartsFromMessageParts as K, toChatMessageParts as L, type FileMention as M, type ChatTurnRequestPayload as N, type ChatTurnPartInput as O, type ChatTurnFilePartInput as P, type ChatAttachmentInput as Q, ChatTurnInputError as R, type StorableHarnessPartKind as S, type ChatTurnTextPartInput as T, DISPATCH_MAX_MEDIA_PARTS as U, DISPATCH_MAX_PARTS as V, DISPATCH_REQUEST_MAX_BYTES as W, DISPATCH_STRUCTURAL_RESERVE_BYTES as X, type FileMentionsToPartsOptions as Y, INLINE_PARTS_MAX_BYTES as Z, MENTION_MAX_COUNT as _, type ChatAttachmentKind as a, type ProducerNoticeEvent as a0, type ProducerPassthroughEvent as a1, type ProducerPassthroughEventType as a2, type ProducerReasoningEvent as a3, type ProducerTextEvent as a4, type ProducerToolCallEvent as a5, type ProducerToolResultEvent as a6, type ProducerUsageEvent as a7, type ProducerWireEvent as a8, type SandboxMentionPathCheck as a9, assertPromptPartsWithinCap as aa, base64WireLen as ab, buildMentionPromptBlock as ac, chatTurnRequestInit as ad, fileMentionsToParts as ae, formatBytes as af, mediaTypeForMentionPath as ag, mentionKindForPath as ah, parseChatTurnParts as ai, parseFileMentions as aj, promptPartsByteSize as ak, validateSandboxMentionPath as al, type ChatAttachmentPart as b, type ChatFilePart as c, type ChatImagePart as d, type ChatInteractionPart as e, type ChatMentionKind as f, type ChatMentionPart as g, type ChatNoticePart as h, type ChatPartTime as i, type ChatPlanPart as j, type ChatReasoningPart as k, type ChatStepFinishPart as l, type ChatStepStartPart as m, type ChatSubtaskPart as n, type ChatTextPart as o, type ChatToolPart as p, type ChatToolState as q, type ChatToolStatus as r, type ChatUsageTokens as s, type ChatWorkProductPart as t, attachmentInputToPart as u, attachmentKindForMime as v, attachmentPartsFromMessageParts as w, buildAttachmentPromptBlock as x, historyContentWithAttachments as y, isChatAttachmentPart as z };
+export { isChatPlanPart as A, isChatStepFinishPart as B, type ChatMessagePart as C, DEFAULT_ATTACHMENT_PROMPT_HEADER as D, isChatTextPart as E, isChatToolPart as F, isChatWorkProductPart as G, mentionInputToPart as H, mentionPartsFromMessageParts as I, toChatMessageParts as J, type StorableHarnessPartKind as S, type ChatAttachmentPart as a, type ChatFilePart as b, type ChatImagePart as c, type ChatInteractionPart as d, type ChatMentionPart as e, type ChatNoticePart as f, type ChatPartTime as g, type ChatPlanPart as h, type ChatReasoningPart as i, type ChatStepFinishPart as j, type ChatStepStartPart as k, type ChatSubtaskPart as l, type ChatTextPart as m, type ChatToolPart as n, type ChatToolState as o, type ChatToolStatus as p, type ChatUsageTokens as q, type ChatWorkProductPart as r, attachmentInputToPart as s, attachmentKindForMime as t, attachmentPartsFromMessageParts as u, buildAttachmentPromptBlock as v, historyContentWithAttachments as w, isChatAttachmentPart as x, isChatInteractionPart as y, isChatMentionPart as z };

package/dist/{queue-vRI0Qx3X.d.ts → queue-VTBA5ONX.d.ts}

@@ -1,4 +1,4 @@
-import { W as WorkProductRef, a as WorkProductProvenance, b as WorkProductRecord } from './types-DB82fktc.js';
+import { a as WorkProductRef, b as WorkProductProvenance, c as WorkProductRecord } from './types-CCeYywdS.js';
 
 /**
  * The review queue is a PROJECTION, not a store — a client-safe pure fold of

package/dist/sandbox/index.d.ts

@@ -369,6 +369,29 @@ interface SandboxApiCredentials {
     baseUrl: string;
     apiKey: string;
 }
+/**
+ * Build the sandbox API's sidecar-proxy base for a box:
+ * `{baseUrl}/v1/sidecar-proxy/{sandboxId}`.
+ *
+ * This is the ONLY upstream that serves the interactive terminal. Measured on
+ * production (`sandbox.tangle.tools`, one box, `ws` client, same credential in
+ * every arm):
+ *
+ * | upstream base                          | result                          |
+ * |----------------------------------------|---------------------------------|
+ * | `/v1/sidecar-proxy/{id}`               | 101 -> `ready` 2551ms -> shell  |
+ * | `/v1/sandboxes/{id}/runtime/`          | HTTP 500                        |
+ * | `connection.runtimeUrl` (the box host) | 101 then close 1000, 0 bytes    |
+ *
+ * The box's own `connection.runtimeUrl` (`https://sandbox-*.tangle.sh`) accepts
+ * the upgrade — its Caddy front end upgrades every path, including ones that do
+ * not exist — and then hangs up without a PTY. A 101 from that host therefore
+ * proves nothing; only a `ready` control frame does. Two products shipped a
+ * terminal against it and rendered a permanent spinner.
+ *
+ * Exported so no product writes the path literal a fourth time.
+ */
+declare function sandboxSidecarProxyUrl(baseUrl: string, sandboxId: string): string;
 /** Define a connection configuration for sandbox runtime including URL and optional server-side auth token */
 interface SandboxRuntimeConnection {
     runtimeUrl: string;
@@ -464,6 +487,42 @@ interface WorkspaceSandboxTerminalUpgradeHandlerOptions {
  * ```
  */
 declare function createWorkspaceSandboxTerminalUpgradeHandler(opts: WorkspaceSandboxTerminalUpgradeHandlerOptions): (request: Request) => Promise<Response | null>;
+/** A response-like shape carrying just what the subprotocol echo decision reads. */
+interface TerminalUpgradeResponseLike {
+    status: number;
+    statusText?: string;
+    headers: Headers;
+}
+/**
+ * Decide whether a terminal upgrade's 101 needs the browser's own subprotocol
+ * echoed back onto it, and return the headers to answer with. `null` means
+ * "pass the upstream response through untouched".
+ *
+ * Why this exists: the browser's terminal credential rides in a
+ * `bearer.<base64url>` WebSocket subprotocol, because a browser cannot set
+ * `Authorization` on a WS handshake. That subprotocol is a browser-to-Worker
+ * credential, so it is stripped before the upstream hop — and the upstream then
+ * answers the 101 selecting nothing. A browser MUST fail the connection when a
+ * 101 selects no subprotocol after it offered one (RFC 6455 s4.1), so the socket
+ * dies on open and the terminal renders a spinner forever.
+ *
+ * Kept as a pure function because a 101 `Response` cannot be constructed off
+ * Workers, so this is the only part of the decision a test can drive directly.
+ */
+declare function terminalUpgradeSubprotocolEcho(upstream: TerminalUpgradeResponseLike, browserProtocol: string | null): {
+    status: number;
+    statusText: string;
+    headers: Headers;
+} | null;
+/**
+ * The exact `bearer.*` subprotocol string the browser offered, so it can be
+ * echoed verbatim on the 101. Returns null when the browser offered none.
+ *
+ * Takes the raw `Sec-WebSocket-Protocol` value rather than the `Headers`, to
+ * match its siblings `bearerSubprotocolToken` and `stripBearerSubprotocol` —
+ * one shape for the whole family, and the caller reads the header once.
+ */
+declare function selectedBearerSubprotocol(value: string | null): string | null;
 /** Build proxy headers for sandbox runtime including authorization and forwarded headers */
 declare function buildSandboxRuntimeProxyHeaders(source: Headers, sandboxApiKey: string, forwardHeaders?: string[]): Headers;
 /** Encode a runtime path by URI-encoding each valid segment and returning null for invalid segments */
@@ -475,6 +534,199 @@ declare function bearerSubprotocolToken(value: string | null): string | null;
 /** Resolve the terminal token from request headers using Authorization or Sec-WebSocket-Protocol fields */
 declare function terminalTokenFromRequest(headers: Headers): string | null;
 
+/**
+ * `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;
+
 /** Define client credentials for accessing the sandbox environment with API key and base URL */
 interface SandboxClientCredentials {
     apiKey: string;
@@ -976,4 +1228,4 @@ 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 AuthenticatedSandboxUser, type BuildAppToolMcpServersOptions, type BuildSandboxToolFileMountsOptions, DEFAULT_SANDBOX_RESOURCES, type DriveSandboxTurnOptions, ENV_TOTAL_MAX_BYTES, ENV_VALUE_MAX_BYTES, type EnsureWorkspaceSandboxOptions, type LivenessProbeConfig, type MemberSyncSeam, type ModelSelection, type ModelSelectionError, type ModelSelectionFailure, type ModelSelectionSource, type Outcome, PROVISION_PAYLOAD_MAX_BYTES, type PeekWorkspaceSandboxOutcome, type ProfileComposeOptions, type PromptInputPart, type ProviderResolutionConfig, type ProvisionPayloadSections, type ProvisionProfileSection, type ResolveSandboxClientCredentialsOptions, type ResolvedModel, type SandboxApiCredentials, type SandboxBuildContext, type SandboxClientCredentials, type SandboxCredentialEnvironment, type SandboxExecChannel, type SandboxExecOptions, type SandboxFileBytesOutcome, type SandboxFileSizeOutcome, SandboxModelResolutionError, type SandboxPermissionLevel, SandboxRecoveryFailedError, type SandboxRecoveryPhase, type SandboxResourceConfig, type SandboxRestoreSpec, SandboxRuntimeAuthRefreshError, type SandboxRuntimeConfig, type SandboxRuntimeConnection, type SandboxScope, type SandboxStepTransition, type SandboxTerminalTokenOptions, type SandboxTerminalTokenResult, type SandboxTerminalTokenSubject, type SandboxTerminalWsMatch, type SandboxToolPathOptions, type SandboxToolSpec, type ScopedTokenResult, type SecretStore, type StoppedSandboxResumeFailure, type StoppedSandboxResumeRecovery, type StreamSandboxPromptOptions, type TerminalProxyIdentity, type WorkspaceSandboxConnectionArgs, type WorkspaceSandboxConnectionHandlerOptions, type WorkspaceSandboxEnsureContext, type WorkspaceSandboxInstanceLike, type WorkspaceSandboxManager, type WorkspaceSandboxManagerOptions, type WorkspaceSandboxRuntimeProxyArgs, type WorkspaceSandboxRuntimeProxyHandlerOptions, type WorkspaceSandboxTerminalUpgradeHandlerOptions, type WriteProfileFilesOptions, assertEnvWithinLimits, assertProvisionPayloadWithinCap, attachReasoningEffort, bearerSubprotocolToken, bearerToken, buildAppToolMcpServers, buildSandboxRuntimeProxyHeaders, buildSandboxToolFileMounts, buildSandboxToolPathSetupScript, classifySeveredStream, collectSandboxPromptText, createSandboxTerminalToken, createWorkspaceSandboxConnectionHandler, createWorkspaceSandboxManager, createWorkspaceSandboxRuntimeProxyHandler, createWorkspaceSandboxTerminalUpgradeHandler, deferredCorpusHash, deleteSecret, detectInteractiveQuestion, driveSandboxTurn, encodeSandboxRuntimePath, ensureWorkspaceSandbox, flattenHistory, getClient, isSandboxTerminalWsUpgrade, isTerminalPromptEvent, matchSandboxTerminalWsPath, mergeExtraMcp, mergeHistoryIntoParts, mintSandboxScopedToken, mintTerminalProxyToken, peekWorkspaceSandbox, readSandboxBinaryBytes, readSecret, requireTransportableModel, resetClientCache, resolveModel, resolveModelSelection, resolveSandboxClientCredentials, runSandboxPrompt, runSandboxToolPathSetup, sandboxToolBinDir, sandboxToolPath, sandboxToolRootDir, secretStoreFromClient, shellQuote, splitDeferredProfileFiles, statSandboxFileSize, storeSecret, streamSandboxPrompt, syncSandboxMemberAdd, syncSandboxMemberRemove, syncSandboxMemberRole, terminalTokenFromRequest, verifySandboxTerminalToken, verifyTerminalProxyToken, writeProfileFilesToBox };
+export { type AppToolDescriptor, type AuthenticatedSandboxUser, type BuildAppToolMcpServersOptions, type BuildSandboxToolFileMountsOptions, DEFAULT_SANDBOX_RESOURCES, type DriveSandboxTurnOptions, ENV_TOTAL_MAX_BYTES, ENV_VALUE_MAX_BYTES, type EnsureWorkspaceSandboxOptions, type LivenessProbeConfig, type MemberSyncSeam, type ModelSelection, type ModelSelectionError, type ModelSelectionFailure, type ModelSelectionSource, type Outcome, PROVISION_PAYLOAD_MAX_BYTES, type PeekWorkspaceSandboxOutcome, 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 SandboxApiCredentials, type SandboxBuildContext, type SandboxClientCredentials, type SandboxCredentialEnvironment, type SandboxExecChannel, type SandboxExecOptions, type SandboxFileBytesOutcome, type SandboxFileSizeOutcome, SandboxModelResolutionError, type SandboxPermissionLevel, type SandboxPrewarmScope, type SandboxPrewarmer, type SandboxPrewarmerOptions, type SandboxReadiness, SandboxRecoveryFailedError, type SandboxRecoveryPhase, type SandboxResourceConfig, type SandboxRestoreSpec, SandboxRuntimeAuthRefreshError, type SandboxRuntimeConfig, type SandboxRuntimeConnection, type SandboxScope, type SandboxStepTransition, type SandboxTerminalTokenOptions, type SandboxTerminalTokenResult, type SandboxTerminalTokenSubject, type SandboxTerminalWsMatch, type SandboxToolPathOptions, type SandboxToolSpec, type ScopedTokenResult, type SecretStore, type StoppedSandboxResumeFailure, type StoppedSandboxResumeRecovery, type StreamSandboxPromptOptions, type TerminalProxyIdentity, type TerminalUpgradeResponseLike, type WorkspaceSandboxConnectionArgs, type WorkspaceSandboxConnectionHandlerOptions, type WorkspaceSandboxEnsureContext, type WorkspaceSandboxInstanceLike, type WorkspaceSandboxManager, type WorkspaceSandboxManagerOptions, type WorkspaceSandboxRuntimeProxyArgs, type WorkspaceSandboxRuntimeProxyHandlerOptions, type WorkspaceSandboxTerminalUpgradeHandlerOptions, type WriteProfileFilesOptions, assertEnvWithinLimits, assertProvisionPayloadWithinCap, attachReasoningEffort, bearerSubprotocolToken, bearerToken, buildAppToolMcpServers, buildSandboxRuntimeProxyHeaders, buildSandboxToolFileMounts, buildSandboxToolPathSetupScript, classifySeveredStream, collectSandboxPromptText, createSandboxPrewarmer, createSandboxTerminalToken, createWorkspaceSandboxConnectionHandler, createWorkspaceSandboxManager, createWorkspaceSandboxRuntimeProxyHandler, createWorkspaceSandboxTerminalUpgradeHandler, deferredCorpusHash, deleteSecret, detectInteractiveQuestion, driveSandboxTurn, encodeSandboxRuntimePath, ensureWorkspaceSandbox, flattenHistory, getClient, isSandboxTerminalWsUpgrade, isTerminalPromptEvent, matchSandboxTerminalWsPath, mergeExtraMcp, mergeHistoryIntoParts, mintSandboxScopedToken, mintTerminalProxyToken, peekWorkspaceSandbox, readSandboxBinaryBytes, readSecret, requireTransportableModel, resetClientCache, resolveModel, resolveModelSelection, resolveSandboxClientCredentials, runSandboxPrompt, runSandboxToolPathSetup, sandboxSidecarProxyUrl, sandboxToolBinDir, sandboxToolPath, sandboxToolRootDir, secretStoreFromClient, selectedBearerSubprotocol, shellQuote, splitDeferredProfileFiles, statSandboxFileSize, storeSecret, streamSandboxPrompt, syncSandboxMemberAdd, syncSandboxMemberRemove, syncSandboxMemberRole, terminalTokenFromRequest, terminalUpgradeSubprotocolEcho, verifySandboxTerminalToken, verifyTerminalProxyToken, writeProfileFilesToBox };

package/dist/sandbox/index.js

@@ -17,6 +17,7 @@ import {
   buildSandboxToolPathSetupScript,
   classifySeveredStream,
   collectSandboxPromptText,
+  createSandboxPrewarmer,
   createSandboxTerminalToken,
   createWorkspaceSandboxConnectionHandler,
   createWorkspaceSandboxManager,
@@ -47,10 +48,12 @@ import {
   resolveSandboxClientCredentials,
   runSandboxPrompt,
   runSandboxToolPathSetup,
+  sandboxSidecarProxyUrl,
   sandboxToolBinDir,
   sandboxToolPath,
   sandboxToolRootDir,
   secretStoreFromClient,
+  selectedBearerSubprotocol,
   shellQuote,
   splitDeferredProfileFiles,
   statSandboxFileSize,
@@ -60,10 +63,11 @@ import {
   syncSandboxMemberRemove,
   syncSandboxMemberRole,
   terminalTokenFromRequest,
+  terminalUpgradeSubprotocolEcho,
   verifySandboxTerminalToken,
   verifyTerminalProxyToken,
   writeProfileFilesToBox
-} from "../chunk-7775L5NN.js";
+} from "../chunk-BAC2B2KI.js";
 import "../chunk-LWSJK546.js";
 import "../chunk-CQZSAR77.js";
 import "../chunk-ICOHEZK6.js";
@@ -90,6 +94,7 @@ export {
   buildSandboxToolPathSetupScript,
   classifySeveredStream,
   collectSandboxPromptText,
+  createSandboxPrewarmer,
   createSandboxTerminalToken,
   createWorkspaceSandboxConnectionHandler,
   createWorkspaceSandboxManager,
@@ -120,10 +125,12 @@ export {
   resolveSandboxClientCredentials,
   runSandboxPrompt,
   runSandboxToolPathSetup,
+  sandboxSidecarProxyUrl,
   sandboxToolBinDir,
   sandboxToolPath,
   sandboxToolRootDir,
   secretStoreFromClient,
+  selectedBearerSubprotocol,
   shellQuote,
   splitDeferredProfileFiles,
   statSandboxFileSize,
@@ -133,6 +140,7 @@ export {
   syncSandboxMemberRemove,
   syncSandboxMemberRole,
   terminalTokenFromRequest,
+  terminalUpgradeSubprotocolEcho,
   verifySandboxTerminalToken,
   verifyTerminalProxyToken,
   writeProfileFilesToBox