@tangle-network/agent-app 0.44.59 → 0.45.1

package/dist/sandbox/index.d.ts

@@ -261,21 +261,7 @@ declare function statSandboxFileSize(box: SandboxExecChannel, absolutePath: stri
  *  mismatch is reported, never returned as a short buffer. */
 declare function readSandboxBinaryBytes(box: SandboxExecChannel, absolutePath: string, expectedSize: number, options?: SandboxExecOptions): Promise<SandboxFileBytesOutcome>;
 
-/** Define identity details for a terminal proxy including user, workspace, and sandbox identifiers */
-interface TerminalProxyIdentity {
-    userId: string;
-    workspaceId: string;
-    sandboxId: string;
-}
-/** Generate a signed token for TerminalProxyIdentity with an expiration based on TTL milliseconds */
-declare function mintTerminalProxyToken(secret: string, identity: TerminalProxyIdentity, ttlMs?: number, now?: () => number): Promise<Outcome<{
-    token: string;
-    expiresAt: Date;
-}>>;
-/** Verify the authenticity and validity of a terminal proxy token against expected identity and timestamp */
-declare function verifyTerminalProxyToken(secret: string, token: string, expected: TerminalProxyIdentity, now?: () => number): Promise<boolean>;
-
-/** Define the shape of a workspace sandbox instance including its connection details and status */
+/** Define the shape of a workspace sandbox instance including its connection details and status. */
 interface WorkspaceSandboxInstanceLike {
     id: string;
     name?: string;
@@ -288,12 +274,12 @@ interface WorkspaceSandboxInstanceLike {
         authTokenExpiresAt?: string;
     } | null;
 }
-/** Define the context containing workspace and user identifiers for sandbox environment operations */
+/** Define the context containing workspace and user identifiers for sandbox environment operations. */
 interface WorkspaceSandboxEnsureContext {
     workspaceId: string;
     userId: string;
 }
-/** Define configuration options for managing and interacting with workspace sandboxes */
+/** 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;
@@ -310,230 +296,161 @@ interface WorkspaceSandboxManagerOptions<TClient, TBox extends WorkspaceSandboxI
     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 */
+/** 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 manager to handle workspace sandbox instances with client and options configuration */
+/**
+ * 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>;
-/** Define options for generating a sandbox terminal token including secret and expiration settings */
-interface SandboxTerminalTokenOptions {
-    secret?: string;
-    expiresInMs?: number;
-    now?: () => number;
-}
-/** Resolve the identity type used for sandbox terminal token subjects */
-type SandboxTerminalTokenSubject = TerminalProxyIdentity;
-/** Provide token and expiration details for a sandbox terminal session */
-interface SandboxTerminalTokenResult {
-    token: string;
-    expiresAt: Date;
-}
-/** Generate a sandbox terminal token for a given subject with specified options */
-declare function createSandboxTerminalToken(subject: SandboxTerminalTokenSubject, opts: SandboxTerminalTokenOptions): Promise<SandboxTerminalTokenResult>;
-/** Verify the validity of a sandbox terminal token against the expected identity and options */
-declare function verifySandboxTerminalToken(token: string, expected: SandboxTerminalTokenSubject, opts: SandboxTerminalTokenOptions): Promise<boolean>;
-/** Represent an authenticated user within a sandbox environment with a unique identifier */
-interface AuthenticatedSandboxUser {
-    id: string;
-}
-/** Define options to handle workspace sandbox connections with user authentication and access control */
-interface WorkspaceSandboxConnectionHandlerOptions<TBox extends WorkspaceSandboxInstanceLike> {
-    requireUser: (request: Request) => Promise<AuthenticatedSandboxUser>;
-    requireWorkspaceAccess: (args: {
-        request: Request;
-        userId: string;
-        workspaceId: string;
-    }) => Promise<void>;
-    ensureWorkspaceSandbox: (workspaceId: string, userId: string) => Promise<TBox>;
-    tokenSecret: string | (() => string | undefined);
-    tokenExpiresInMs?: number;
-    proxyRuntimeUrl?: (args: {
-        request: Request;
-        workspaceId: string;
-        sandboxId: string;
-        box: TBox;
-    }) => string;
-    exposeDirectSidecar?: boolean;
-}
-/** Define arguments required to establish a workspace sandbox connection */
-interface WorkspaceSandboxConnectionArgs {
-    request: Request;
-    params: {
-        workspaceId?: string;
-    };
-}
-/** Create a handler to resolve workspace sandbox connections with user and access validation */
-declare function createWorkspaceSandboxConnectionHandler<TBox extends WorkspaceSandboxInstanceLike>(opts: WorkspaceSandboxConnectionHandlerOptions<TBox>): ({ request, params }: WorkspaceSandboxConnectionArgs) => Promise<Response>;
-/** Define credentials required to access the sandbox API environment */
-interface SandboxApiCredentials {
-    baseUrl: string;
-    apiKey: string;
-}
+
 /**
- * Build the sandbox API's sidecar-proxy base for a box:
- * `{baseUrl}/v1/sidecar-proxy/{sandboxId}`.
+ * Browser-direct scoped-token terminal connection route (#341/#349).
  *
- * 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):
+ * 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.
  *
- * | 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    |
+ * VERIFIED PLATFORM CONTRACT (`@tangle-network/sandbox` 0.15.2 + the
+ * orchestrator/sidecar enforcement source, verified 2026-07-30):
  *
- * 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.
+ * 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.
  *
- * Exported so no product writes the path literal a fourth time.
+ * 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.
  */
-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;
-    /** Server-side sidecar bearer. Must authorize terminal routes; never expose it to browser code. */
-    authToken?: string;
-}
-/** Define options for handling workspace sandbox runtime proxy including user, access, credentials, and connection retrieval */
-interface WorkspaceSandboxRuntimeProxyHandlerOptions {
-    requireUser: (request: Request) => Promise<AuthenticatedSandboxUser>;
-    requireWorkspaceAccess: (args: {
-        request: Request;
-        userId: string;
-        workspaceId: string;
-        sandboxId: string;
-    }) => Promise<void>;
-    getSandboxApiCredentials: (args: {
-        request: Request;
-        userId: string;
-        workspaceId: string;
-        sandboxId: string;
-    }) => Promise<SandboxApiCredentials>;
-    getSandboxRuntimeConnection?: (args: {
-        request: Request;
-        userId: string;
-        workspaceId: string;
-        sandboxId: string;
-    }) => Promise<SandboxRuntimeConnection | null | undefined>;
-    tokenSecret: string | (() => string | undefined);
-    fetch?: typeof fetch;
-    forwardHeaders?: string[];
-}
-/** Define arguments for proxying runtime requests within a workspace sandbox environment */
-interface WorkspaceSandboxRuntimeProxyArgs {
-    request: Request;
-    params: {
-        workspaceId?: string;
-        sandboxId?: string;
-        '*'?: string;
+/** 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;
+    }>;
 }
-/** Create a proxy handler to resolve sandbox runtime requests with user and workspace access validation */
-declare function createWorkspaceSandboxRuntimeProxyHandler(opts: WorkspaceSandboxRuntimeProxyHandlerOptions): ({ request, params }: WorkspaceSandboxRuntimeProxyArgs) => Promise<Response>;
-/** Define the structure for matching a sandbox terminal WebSocket with workspace and path details */
-interface SandboxTerminalWsMatch {
-    workspaceId: string;
-    sandboxId: string;
-    subPath: string;
-}
-/**
- * Parse a same-origin terminal-WS pathname into its parts, or `null` when the
- * path is not a sandbox terminal WebSocket. Matches the default `runtimeUrl`
- * convention emitted by {@link createWorkspaceSandboxConnectionHandler}
- * (`/api/workspaces/:workspaceId/sandbox/runtime/:sandboxId`) with a canonical
- * `terminals/:id/ws` sub-path. `subPath` is left URL-encoded for re-use in the
- * upstream URL; the ids are decoded for auth checks.
- */
-declare function matchSandboxTerminalWsPath(pathname: string): SandboxTerminalWsMatch | null;
-/** True when `request` is a WebSocket upgrade for a sandbox terminal path. */
-declare function isSandboxTerminalWsUpgrade(request: Request): boolean;
-/** Define options to handle user authentication, workspace access, and sandbox API credential retrieval */
-interface WorkspaceSandboxTerminalUpgradeHandlerOptions {
-    requireUser: (request: Request) => Promise<AuthenticatedSandboxUser>;
-    requireWorkspaceAccess: (args: {
-        request: Request;
-        userId: string;
-        workspaceId: string;
-        sandboxId: string;
-    }) => Promise<void>;
-    getSandboxApiCredentials: (args: {
-        request: Request;
-        userId: string;
-        workspaceId: string;
-        sandboxId: string;
-    }) => Promise<SandboxApiCredentials>;
-    getSandboxRuntimeConnection?: (args: {
+/** 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;
-        userId: string;
-        workspaceId: string;
-        sandboxId: string;
-    }) => Promise<SandboxRuntimeConnection | null | undefined>;
-    tokenSecret: string | (() => string | undefined);
-    fetch?: typeof fetch;
-}
-/**
- * Build a Worker-entry handler that proxies a sandbox terminal WebSocket
- * upgrade to the sandbox API runtime proxy. Returns `null` when the request is
- * not a terminal WS upgrade, so the caller can fall through to its normal
- * request handler:
- *
- * ```ts
- * const handled = await handleSandboxTerminalUpgrade(request)
- * if (handled) return handled
- * ```
- */
-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;
+        user: TUser;
+        box: TBox;
+        requested: string | null;
+    }) => string | null | undefined | Promise<string | null | undefined>;
 }
 /**
- * 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.
+ * 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.
  *
- * 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.
+ * 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 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 */
-declare function encodeSandboxRuntimePath(runtimePath: string): string | null;
-/** Extract the token from a bearer authorization string or return null if invalid or missing */
-declare function bearerToken(value: string | null): string | null;
-/** Resolve and decode a bearer token from a comma-separated subprotocol string or return null */
-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;
+declare function createSandboxTerminalConnectionRoute<TBox extends TerminalConnectionBoxLike, TUser>(opts: SandboxTerminalConnectionRouteOptions<TBox, TUser>): (request: Request) => Promise<Response>;
 
 /**
  * `createSandboxPrewarmer` — "this user just opened this project; start warming
@@ -1339,4 +1256,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, type D1PrewarmClaimStoreOptions, DEFAULT_PREWARM_CLAIM_TABLE, DEFAULT_SANDBOX_RESOURCES, DEFAULT_SIDECAR_PROCESS_PATTERN, 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, PREWARM_CLAIM_TABLE_DDL, PROVISION_PAYLOAD_MAX_BYTES, 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 SandboxApiCredentials, 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 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, createD1PrewarmClaimStore, 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 };
+export { type AppToolDescriptor, type BuildAppToolMcpServersOptions, type BuildSandboxToolFileMountsOptions, type D1PrewarmClaimStoreOptions, DEFAULT_PREWARM_CLAIM_TABLE, DEFAULT_SANDBOX_RESOURCES, DEFAULT_SIDECAR_PROCESS_PATTERN, 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, PREWARM_CLAIM_TABLE_DDL, PROVISION_PAYLOAD_MAX_BYTES, 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 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 SandboxReadiness, SandboxRecoveryFailedError, type SandboxRecoveryPhase, type SandboxResourceConfig, type SandboxRestoreSpec, SandboxRuntimeAuthRefreshError, type SandboxRuntimeConfig, type SandboxScope, type SandboxStepTransition, type SandboxTerminalConnectionRouteOptions, type SandboxToolPathOptions, type SandboxToolSpec, type ScopedTokenResult, type SecretStore, type StoppedSandboxResumeFailure, type StoppedSandboxResumeRecovery, type StreamSandboxPromptOptions, type TerminalConnectionBoxLike, type WorkspaceSandboxEnsureContext, type WorkspaceSandboxInstanceLike, type WorkspaceSandboxManager, type WorkspaceSandboxManagerOptions, type WriteProfileFilesOptions, assertEnvWithinLimits, assertProvisionPayloadWithinCap, attachReasoningEffort, buildAppToolMcpServers, buildSandboxToolFileMounts, buildSandboxToolPathSetupScript, classifySeveredStream, collectSandboxPromptText, createD1PrewarmClaimStore, createSandboxPrewarmer, createSandboxTerminalConnectionRoute, createWorkspaceSandboxManager, deferredCorpusHash, deleteSecret, detectInteractiveQuestion, driveSandboxTurn, ensureWorkspaceSandbox, flattenHistory, getClient, isTerminalPromptEvent, mergeExtraMcp, mergeHistoryIntoParts, mintSandboxScopedToken, peekWorkspaceSandbox, readSandboxBinaryBytes, readSecret, requireTransportableModel, resetClientCache, resolveModel, resolveModelSelection, resolveSandboxClientCredentials, runSandboxPrompt, runSandboxToolPathSetup, sandboxToolBinDir, sandboxToolPath, sandboxToolRootDir, secretStoreFromClient, shellQuote, splitDeferredProfileFiles, statSandboxFileSize, storeSecret, streamSandboxPrompt, syncSandboxMemberAdd, syncSandboxMemberRemove, syncSandboxMemberRole, writeProfileFilesToBox };

package/dist/sandbox/index.js

@@ -13,36 +13,26 @@ import {
   assertEnvWithinLimits,
   assertProvisionPayloadWithinCap,
   attachReasoningEffort,
-  bearerSubprotocolToken,
-  bearerToken,
   buildAppToolMcpServers,
-  buildSandboxRuntimeProxyHeaders,
   buildSandboxToolFileMounts,
   buildSandboxToolPathSetupScript,
   classifySeveredStream,
   collectSandboxPromptText,
   createD1PrewarmClaimStore,
   createSandboxPrewarmer,
-  createSandboxTerminalToken,
-  createWorkspaceSandboxConnectionHandler,
+  createSandboxTerminalConnectionRoute,
   createWorkspaceSandboxManager,
-  createWorkspaceSandboxRuntimeProxyHandler,
-  createWorkspaceSandboxTerminalUpgradeHandler,
   deferredCorpusHash,
   deleteSecret,
   detectInteractiveQuestion,
   driveSandboxTurn,
-  encodeSandboxRuntimePath,
   ensureWorkspaceSandbox,
   flattenHistory,
   getClient,
-  isSandboxTerminalWsUpgrade,
   isTerminalPromptEvent,
-  matchSandboxTerminalWsPath,
   mergeExtraMcp,
   mergeHistoryIntoParts,
   mintSandboxScopedToken,
-  mintTerminalProxyToken,
   peekWorkspaceSandbox,
   readSandboxBinaryBytes,
   readSecret,
@@ -53,12 +43,10 @@ import {
   resolveSandboxClientCredentials,
   runSandboxPrompt,
   runSandboxToolPathSetup,
-  sandboxSidecarProxyUrl,
   sandboxToolBinDir,
   sandboxToolPath,
   sandboxToolRootDir,
   secretStoreFromClient,
-  selectedBearerSubprotocol,
   shellQuote,
   splitDeferredProfileFiles,
   statSandboxFileSize,
@@ -67,12 +55,8 @@ import {
   syncSandboxMemberAdd,
   syncSandboxMemberRemove,
   syncSandboxMemberRole,
-  terminalTokenFromRequest,
-  terminalUpgradeSubprotocolEcho,
-  verifySandboxTerminalToken,
-  verifyTerminalProxyToken,
   writeProfileFilesToBox
-} from "../chunk-2UDJH6QR.js";
+} from "../chunk-EC7CUA4L.js";
 import "../chunk-LWSJK546.js";
 import "../chunk-CQZSAR77.js";
 import "../chunk-ICOHEZK6.js";
@@ -95,36 +79,26 @@ export {
   assertEnvWithinLimits,
   assertProvisionPayloadWithinCap,
   attachReasoningEffort,
-  bearerSubprotocolToken,
-  bearerToken,
   buildAppToolMcpServers,
-  buildSandboxRuntimeProxyHeaders,
   buildSandboxToolFileMounts,
   buildSandboxToolPathSetupScript,
   classifySeveredStream,
   collectSandboxPromptText,
   createD1PrewarmClaimStore,
   createSandboxPrewarmer,
-  createSandboxTerminalToken,
-  createWorkspaceSandboxConnectionHandler,
+  createSandboxTerminalConnectionRoute,
   createWorkspaceSandboxManager,
-  createWorkspaceSandboxRuntimeProxyHandler,
-  createWorkspaceSandboxTerminalUpgradeHandler,
   deferredCorpusHash,
   deleteSecret,
   detectInteractiveQuestion,
   driveSandboxTurn,
-  encodeSandboxRuntimePath,
   ensureWorkspaceSandbox,
   flattenHistory,
   getClient,
-  isSandboxTerminalWsUpgrade,
   isTerminalPromptEvent,
-  matchSandboxTerminalWsPath,
   mergeExtraMcp,
   mergeHistoryIntoParts,
   mintSandboxScopedToken,
-  mintTerminalProxyToken,
   peekWorkspaceSandbox,
   readSandboxBinaryBytes,
   readSecret,
@@ -135,12 +109,10 @@ export {
   resolveSandboxClientCredentials,
   runSandboxPrompt,
   runSandboxToolPathSetup,
-  sandboxSidecarProxyUrl,
   sandboxToolBinDir,
   sandboxToolPath,
   sandboxToolRootDir,
   secretStoreFromClient,
-  selectedBearerSubprotocol,
   shellQuote,
   splitDeferredProfileFiles,
   statSandboxFileSize,
@@ -149,10 +121,6 @@ export {
   syncSandboxMemberAdd,
   syncSandboxMemberRemove,
   syncSandboxMemberRole,
-  terminalTokenFromRequest,
-  terminalUpgradeSubprotocolEcho,
-  verifySandboxTerminalToken,
-  verifyTerminalProxyToken,
   writeProfileFilesToBox
 };
 //# sourceMappingURL=index.js.map

package/dist/web-react/index.js

@@ -102,7 +102,7 @@ import {
 import {
   tabTerminalConnectionId,
   useSandboxTerminalConnection
-} from "../chunk-HCOROIRT.js";
+} from "../chunk-BATKJP3P.js";
 import "../chunk-QY4BRKRJ.js";
 import {
   ATTACHMENT_ACCEPT

package/dist/web-react/terminal.d.ts

@@ -8,8 +8,21 @@ interface SandboxTerminalConnection {
     error: string | null;
     loading: boolean;
     sandboxId?: string;
+    connectionId?: string;
 }
-/** Define the response structure for a sandbox terminal connection including URLs, token, status, and errors */
+/**
+ * Define the response structure for a sandbox terminal connection including URLs, token, status, and errors
+ *
+ * The browser-direct scoped-token route (`createSandboxTerminalConnectionRoute`,
+ * `src/sandbox/terminal-connection.ts`) returns `sidecarUrl`. The hook also
+ * exposes that URL through the historical `runtimeUrl` state field so existing
+ * terminal panels do not need transport-specific branching.
+ *
+ * `connectionId` is the id the route's minted token's `sid` is bound to
+ * (echoed back from the `connectionId` the hook sent) — pass it straight
+ * through as `TerminalView`'s `connectionId` prop, since any other value
+ * fails the WS upgrade on the current platform.
+ */
 interface SandboxTerminalConnectionResponse {
     runtimeUrl?: string;
     sidecarUrl?: string;
@@ -18,11 +31,23 @@ interface SandboxTerminalConnectionResponse {
     status?: string;
     error?: string;
     sandboxId?: string;
+    connectionId?: string;
 }
-/** Define options for configuring a sandbox terminal connection including workspace ID and connection parameters */
+/**
+ * Define options for configuring a sandbox terminal connection including workspace ID and connection parameters
+ *
+ * `connectionId`, when set, is passed to
+ * `createSandboxTerminalConnectionRoute` as the `connectionId` query
+ * parameter — pass `tabTerminalConnectionId()` here so the route mints a
+ * token whose `sid` is bound to the same id `TerminalView` will dial. Give
+ * `TerminalView` the response's echoed `connectionId` (not this input
+ * value) alongside `sidecarUrl` as `apiUrl` and `token`, since a product's
+ * `resolveConnectionId` seam may rewrite it server-side.
+ */
 interface UseSandboxTerminalConnectionOptions {
     workspaceId: string;
     connectionUrl?: string | ((workspaceId: string) => string);
+    connectionId?: string;
     fetcher?: typeof fetch;
     provisionPollIntervalMs?: number;
     provisionPollTimeoutMs?: number;
@@ -32,7 +57,23 @@ interface UseSandboxTerminalConnectionOptions {
 interface UseSandboxTerminalConnectionResult extends SandboxTerminalConnection {
     connect: () => Promise<void>;
 }
-/** Manage and maintain a sandbox terminal connection with automatic polling and token refresh handling */
+/**
+ * Manage and maintain a sandbox terminal connection with automatic polling and token refresh handling
+ *
+ * `connectionUrl` is backed by the browser-direct scoped-token route
+ * (`createSandboxTerminalConnectionRoute`,
+ * `src/sandbox/terminal-connection.ts`). The route returns `sidecarUrl`; the
+ * hook normalizes it into both URL fields for compatibility with existing
+ * terminal panels.
+ *
+ * Pass `tabTerminalConnectionId()` as `opts.connectionId` — the hook forwards
+ * it as the `connectionId` query parameter the browser-direct route requires
+ * to mint a token whose `sid` is bound to that exact id (the orchestrator's
+ * terminal WS gate fails closed on any other value). Give `TerminalView` the
+ * RESULT's echoed `connectionId` (not the input value — a product's
+ * `resolveConnectionId` seam may rewrite it), the resolved `sidecarUrl`/
+ * `runtimeUrl` as `apiUrl`, and `token` as its token prop.
+ */
 declare function useSandboxTerminalConnection(opts: UseSandboxTerminalConnectionOptions): UseSandboxTerminalConnectionResult;
 /**
  * Stable-per-tab, unique-per-client terminal connection id.

package/dist/web-react/terminal.js

@@ -1,7 +1,7 @@
 import {
   tabTerminalConnectionId,
   useSandboxTerminalConnection
-} from "../chunk-HCOROIRT.js";
+} from "../chunk-BATKJP3P.js";
 export {
   tabTerminalConnectionId,
   useSandboxTerminalConnection