@tangle-network/agent-app 0.44.59 → 0.44.60

package/dist/sandbox/index.d.ts

@@ -261,20 +261,67 @@ 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 */
+/**
+ * Define identity details for a terminal proxy including user, workspace, and sandbox identifiers
+ *
+ * @deprecated Identity shape for the same-origin proxy terminal transport,
+ * superseded by the browser-direct scoped-token transport — build the route
+ * with `createSandboxTerminalConnectionRoute` (`src/sandbox/terminal-connection.ts`)
+ * instead. Three apps still import this seam; retirement is tracked in #350
+ * and removal is a major.
+ */
 interface TerminalProxyIdentity {
     userId: string;
     workspaceId: string;
     sandboxId: string;
 }
-/** Generate a signed token for TerminalProxyIdentity with an expiration based on TTL milliseconds */
+/**
+ * Generate a signed token for TerminalProxyIdentity with an expiration based on TTL milliseconds
+ *
+ * @deprecated Mints a token for the same-origin proxy terminal transport,
+ * superseded by the browser-direct scoped-token transport — build the route
+ * with `createSandboxTerminalConnectionRoute` (`src/sandbox/terminal-connection.ts`)
+ * instead. Three apps still import this seam; retirement is tracked in #350
+ * and removal is a major.
+ */
 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 */
+/**
+ * Verify the authenticity and validity of a terminal proxy token against expected identity and timestamp
+ *
+ * @deprecated Verifies a token for the same-origin proxy terminal transport,
+ * superseded by the browser-direct scoped-token transport — build the route
+ * with `createSandboxTerminalConnectionRoute` (`src/sandbox/terminal-connection.ts`)
+ * instead. Three apps still import this seam; retirement is tracked in #350
+ * and removal is a major.
+ */
 declare function verifyTerminalProxyToken(secret: string, token: string, expected: TerminalProxyIdentity, now?: () => number): Promise<boolean>;
 
+/**
+ * The same-origin PROXY terminal transport: connection handler -> HMAC proxy
+ * token -> runtime proxy -> WebSocket upgrade relay, with a worker in the
+ * data path for every terminal byte. Epic #343 / decision #341 moved the
+ * fleet default to the browser-direct scoped-token transport in
+ * `./terminal-connection.ts` — the product's server authenticates +
+ * provisions once, mints an SDK scoped token, and the browser connects
+ * `TerminalView` straight to the sidecar with no worker relay. Nothing here
+ * is removed (three apps still import this seam); retirement is tracked in
+ * #350 and removal is a major.
+ *
+ * KEPT / DEPRECATED split in this file:
+ *
+ * | export                                        | status                              |
+ * | ---------------------------------------------- | ----------------------------------- |
+ * | `createWorkspaceSandboxManager` + friends      | KEPT — generic box lifecycle, used by both transports |
+ * | `WorkspaceSandboxInstanceLike`                 | KEPT — same reason                  |
+ * | `createWorkspaceSandboxConnectionHandler`      | `@deprecated` — proxy connection route |
+ * | `createWorkspaceSandboxRuntimeProxyHandler`    | `@deprecated` — proxy runtime relay |
+ * | `createWorkspaceSandboxTerminalUpgradeHandler` | `@deprecated` — proxy WS upgrade relay |
+ * | `createSandboxTerminalToken` / `verifySandboxTerminalToken` | `@deprecated` — proxy HMAC token |
+ * | every other exported helper below              | `@deprecated` — exists only to serve the proxy relay |
+ */
 /** Define the shape of a workspace sandbox instance including its connection details and status */
 interface WorkspaceSandboxInstanceLike {
     id: string;
@@ -316,28 +363,84 @@ interface WorkspaceSandboxManager<TBox extends WorkspaceSandboxInstanceLike, TEn
 }
 /** Create a manager to handle workspace sandbox instances with client and options configuration */
 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 */
+/**
+ * Define options for generating a sandbox terminal token including secret and expiration settings
+ *
+ * @deprecated Options for the same-origin proxy terminal transport's HMAC
+ * token, superseded by the browser-direct scoped-token transport — build the
+ * route with `createSandboxTerminalConnectionRoute`
+ * (`src/sandbox/terminal-connection.ts`) instead. Three apps still import
+ * this seam; retirement is tracked in #350 and removal is a major.
+ */
 interface SandboxTerminalTokenOptions {
     secret?: string;
     expiresInMs?: number;
     now?: () => number;
 }
-/** Resolve the identity type used for sandbox terminal token subjects */
+/**
+ * Resolve the identity type used for sandbox terminal token subjects
+ *
+ * @deprecated Identity alias for the same-origin proxy terminal transport,
+ * superseded by the browser-direct scoped-token transport — build the route
+ * with `createSandboxTerminalConnectionRoute`
+ * (`src/sandbox/terminal-connection.ts`) instead. Three apps still import
+ * this seam; retirement is tracked in #350 and removal is a major.
+ */
 type SandboxTerminalTokenSubject = TerminalProxyIdentity;
-/** Provide token and expiration details for a sandbox terminal session */
+/**
+ * Provide token and expiration details for a sandbox terminal session
+ *
+ * @deprecated Result shape for the same-origin proxy terminal transport's
+ * HMAC token, superseded by the browser-direct scoped-token transport —
+ * build the route with `createSandboxTerminalConnectionRoute`
+ * (`src/sandbox/terminal-connection.ts`) instead. Three apps still import
+ * this seam; retirement is tracked in #350 and removal is a major.
+ */
 interface SandboxTerminalTokenResult {
     token: string;
     expiresAt: Date;
 }
-/** Generate a sandbox terminal token for a given subject with specified options */
+/**
+ * Generate a sandbox terminal token for a given subject with specified options
+ *
+ * @deprecated Mints a token for the same-origin proxy terminal transport,
+ * superseded by the browser-direct scoped-token transport — build the route
+ * with `createSandboxTerminalConnectionRoute`
+ * (`src/sandbox/terminal-connection.ts`) instead. Three apps still import
+ * this seam; retirement is tracked in #350 and removal is a major.
+ */
 declare function createSandboxTerminalToken(subject: SandboxTerminalTokenSubject, opts: SandboxTerminalTokenOptions): Promise<SandboxTerminalTokenResult>;
-/** Verify the validity of a sandbox terminal token against the expected identity and options */
+/**
+ * Verify the validity of a sandbox terminal token against the expected identity and options
+ *
+ * @deprecated Verifies a token for the same-origin proxy terminal transport,
+ * superseded by the browser-direct scoped-token transport — build the route
+ * with `createSandboxTerminalConnectionRoute`
+ * (`src/sandbox/terminal-connection.ts`) instead. Three apps still import
+ * this seam; retirement is tracked in #350 and removal is a major.
+ */
 declare function verifySandboxTerminalToken(token: string, expected: SandboxTerminalTokenSubject, opts: SandboxTerminalTokenOptions): Promise<boolean>;
-/** Represent an authenticated user within a sandbox environment with a unique identifier */
+/**
+ * Represent an authenticated user within a sandbox environment with a unique identifier
+ *
+ * @deprecated Exists only to serve the same-origin proxy terminal transport,
+ * superseded by the browser-direct scoped-token transport — build the route
+ * with `createSandboxTerminalConnectionRoute`
+ * (`src/sandbox/terminal-connection.ts`) instead. Three apps still import
+ * this seam; retirement is tracked in #350 and removal is a major.
+ */
 interface AuthenticatedSandboxUser {
     id: string;
 }
-/** Define options to handle workspace sandbox connections with user authentication and access control */
+/**
+ * Define options to handle workspace sandbox connections with user authentication and access control
+ *
+ * @deprecated Options for the same-origin proxy terminal connection handler,
+ * superseded by the browser-direct scoped-token transport — build the route
+ * with `createSandboxTerminalConnectionRoute`
+ * (`src/sandbox/terminal-connection.ts`) instead. Three apps still import
+ * this seam; retirement is tracked in #350 and removal is a major.
+ */
 interface WorkspaceSandboxConnectionHandlerOptions<TBox extends WorkspaceSandboxInstanceLike> {
     requireUser: (request: Request) => Promise<AuthenticatedSandboxUser>;
     requireWorkspaceAccess: (args: {
@@ -356,16 +459,40 @@ interface WorkspaceSandboxConnectionHandlerOptions<TBox extends WorkspaceSandbox
     }) => string;
     exposeDirectSidecar?: boolean;
 }
-/** Define arguments required to establish a workspace sandbox connection */
+/**
+ * Define arguments required to establish a workspace sandbox connection
+ *
+ * @deprecated Argument shape for the same-origin proxy terminal connection
+ * handler, superseded by the browser-direct scoped-token transport — build
+ * the route with `createSandboxTerminalConnectionRoute`
+ * (`src/sandbox/terminal-connection.ts`) instead. Three apps still import
+ * this seam; retirement is tracked in #350 and removal is a major.
+ */
 interface WorkspaceSandboxConnectionArgs {
     request: Request;
     params: {
         workspaceId?: string;
     };
 }
-/** Create a handler to resolve workspace sandbox connections with user and access validation */
+/**
+ * Create a handler to resolve workspace sandbox connections with user and access validation
+ *
+ * @deprecated The same-origin proxy terminal transport is superseded by the
+ * browser-direct scoped-token transport — build the route with
+ * `createSandboxTerminalConnectionRoute` (`src/sandbox/terminal-connection.ts`)
+ * instead. Three apps still import this seam; retirement is tracked in #350
+ * and removal is a major.
+ */
 declare function createWorkspaceSandboxConnectionHandler<TBox extends WorkspaceSandboxInstanceLike>(opts: WorkspaceSandboxConnectionHandlerOptions<TBox>): ({ request, params }: WorkspaceSandboxConnectionArgs) => Promise<Response>;
-/** Define credentials required to access the sandbox API environment */
+/**
+ * Define credentials required to access the sandbox API environment
+ *
+ * @deprecated Exists only to serve the same-origin proxy terminal transport,
+ * superseded by the browser-direct scoped-token transport — build the route
+ * with `createSandboxTerminalConnectionRoute`
+ * (`src/sandbox/terminal-connection.ts`) instead. Three apps still import
+ * this seam; retirement is tracked in #350 and removal is a major.
+ */
 interface SandboxApiCredentials {
     baseUrl: string;
     apiKey: string;
@@ -391,15 +518,37 @@ interface SandboxApiCredentials {
  * terminal against it and rendered a permanent spinner.
  *
  * Exported so no product writes the path literal a fourth time.
+ *
+ * @deprecated Exists only to serve the same-origin proxy terminal transport,
+ * superseded by the browser-direct scoped-token transport — build the route
+ * with `createSandboxTerminalConnectionRoute`
+ * (`src/sandbox/terminal-connection.ts`) instead. Three apps still import
+ * this seam; retirement is tracked in #350 and removal is a major.
  */
 declare function sandboxSidecarProxyUrl(baseUrl: string, sandboxId: string): string;
-/** Define a connection configuration for sandbox runtime including URL and optional server-side auth token */
+/**
+ * Define a connection configuration for sandbox runtime including URL and optional server-side auth token
+ *
+ * @deprecated Exists only to serve the same-origin proxy terminal transport,
+ * superseded by the browser-direct scoped-token transport — build the route
+ * with `createSandboxTerminalConnectionRoute`
+ * (`src/sandbox/terminal-connection.ts`) instead. Three apps still import
+ * this seam; retirement is tracked in #350 and removal is a major.
+ */
 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 */
+/**
+ * Define options for handling workspace sandbox runtime proxy including user, access, credentials, and connection retrieval
+ *
+ * @deprecated Options for the same-origin proxy terminal runtime relay,
+ * superseded by the browser-direct scoped-token transport — build the route
+ * with `createSandboxTerminalConnectionRoute`
+ * (`src/sandbox/terminal-connection.ts`) instead. Three apps still import
+ * this seam; retirement is tracked in #350 and removal is a major.
+ */
 interface WorkspaceSandboxRuntimeProxyHandlerOptions {
     requireUser: (request: Request) => Promise<AuthenticatedSandboxUser>;
     requireWorkspaceAccess: (args: {
@@ -424,7 +573,15 @@ interface WorkspaceSandboxRuntimeProxyHandlerOptions {
     fetch?: typeof fetch;
     forwardHeaders?: string[];
 }
-/** Define arguments for proxying runtime requests within a workspace sandbox environment */
+/**
+ * Define arguments for proxying runtime requests within a workspace sandbox environment
+ *
+ * @deprecated Argument shape for the same-origin proxy terminal runtime
+ * relay, superseded by the browser-direct scoped-token transport — build the
+ * route with `createSandboxTerminalConnectionRoute`
+ * (`src/sandbox/terminal-connection.ts`) instead. Three apps still import
+ * this seam; retirement is tracked in #350 and removal is a major.
+ */
 interface WorkspaceSandboxRuntimeProxyArgs {
     request: Request;
     params: {
@@ -433,9 +590,25 @@ interface WorkspaceSandboxRuntimeProxyArgs {
         '*'?: string;
     };
 }
-/** Create a proxy handler to resolve sandbox runtime requests with user and workspace access validation */
+/**
+ * Create a proxy handler to resolve sandbox runtime requests with user and workspace access validation
+ *
+ * @deprecated The same-origin proxy terminal transport is superseded by the
+ * browser-direct scoped-token transport — build the route with
+ * `createSandboxTerminalConnectionRoute` (`src/sandbox/terminal-connection.ts`)
+ * instead. Three apps still import this seam; retirement is tracked in #350
+ * and removal is a major.
+ */
 declare function createWorkspaceSandboxRuntimeProxyHandler(opts: WorkspaceSandboxRuntimeProxyHandlerOptions): ({ request, params }: WorkspaceSandboxRuntimeProxyArgs) => Promise<Response>;
-/** Define the structure for matching a sandbox terminal WebSocket with workspace and path details */
+/**
+ * Define the structure for matching a sandbox terminal WebSocket with workspace and path details
+ *
+ * @deprecated Exists only to serve the same-origin proxy terminal transport,
+ * superseded by the browser-direct scoped-token transport — build the route
+ * with `createSandboxTerminalConnectionRoute`
+ * (`src/sandbox/terminal-connection.ts`) instead. Three apps still import
+ * this seam; retirement is tracked in #350 and removal is a major.
+ */
 interface SandboxTerminalWsMatch {
     workspaceId: string;
     sandboxId: string;
@@ -448,11 +621,33 @@ interface SandboxTerminalWsMatch {
  * (`/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.
+ *
+ * @deprecated Parses a path for the same-origin proxy terminal transport,
+ * superseded by the browser-direct scoped-token transport — build the route
+ * with `createSandboxTerminalConnectionRoute`
+ * (`src/sandbox/terminal-connection.ts`) instead. Three apps still import
+ * this seam; retirement is tracked in #350 and removal is a major.
  */
 declare function matchSandboxTerminalWsPath(pathname: string): SandboxTerminalWsMatch | null;
-/** True when `request` is a WebSocket upgrade for a sandbox terminal path. */
+/**
+ * True when `request` is a WebSocket upgrade for a sandbox terminal path.
+ *
+ * @deprecated Exists only to serve the same-origin proxy terminal transport,
+ * superseded by the browser-direct scoped-token transport — build the route
+ * with `createSandboxTerminalConnectionRoute`
+ * (`src/sandbox/terminal-connection.ts`) instead. Three apps still import
+ * this seam; retirement is tracked in #350 and removal is a major.
+ */
 declare function isSandboxTerminalWsUpgrade(request: Request): boolean;
-/** Define options to handle user authentication, workspace access, and sandbox API credential retrieval */
+/**
+ * Define options to handle user authentication, workspace access, and sandbox API credential retrieval
+ *
+ * @deprecated Options for the same-origin proxy terminal WS upgrade relay,
+ * superseded by the browser-direct scoped-token transport — build the route
+ * with `createSandboxTerminalConnectionRoute`
+ * (`src/sandbox/terminal-connection.ts`) instead. Three apps still import
+ * this seam; retirement is tracked in #350 and removal is a major.
+ */
 interface WorkspaceSandboxTerminalUpgradeHandlerOptions {
     requireUser: (request: Request) => Promise<AuthenticatedSandboxUser>;
     requireWorkspaceAccess: (args: {
@@ -486,9 +681,23 @@ interface WorkspaceSandboxTerminalUpgradeHandlerOptions {
  * const handled = await handleSandboxTerminalUpgrade(request)
  * if (handled) return handled
  * ```
+ *
+ * @deprecated The same-origin proxy terminal transport is superseded by the
+ * browser-direct scoped-token transport — build the route with
+ * `createSandboxTerminalConnectionRoute` (`src/sandbox/terminal-connection.ts`)
+ * instead. Three apps still import this seam; retirement is tracked in #350
+ * and removal is a major.
  */
 declare function createWorkspaceSandboxTerminalUpgradeHandler(opts: WorkspaceSandboxTerminalUpgradeHandlerOptions): (request: Request) => Promise<Response | null>;
-/** A response-like shape carrying just what the subprotocol echo decision reads. */
+/**
+ * A response-like shape carrying just what the subprotocol echo decision reads.
+ *
+ * @deprecated Exists only to serve the same-origin proxy terminal transport,
+ * superseded by the browser-direct scoped-token transport — build the route
+ * with `createSandboxTerminalConnectionRoute`
+ * (`src/sandbox/terminal-connection.ts`) instead. Three apps still import
+ * this seam; retirement is tracked in #350 and removal is a major.
+ */
 interface TerminalUpgradeResponseLike {
     status: number;
     statusText?: string;
@@ -509,6 +718,12 @@ interface TerminalUpgradeResponseLike {
  *
  * 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.
+ *
+ * @deprecated Exists only to serve the same-origin proxy terminal transport,
+ * superseded by the browser-direct scoped-token transport — build the route
+ * with `createSandboxTerminalConnectionRoute`
+ * (`src/sandbox/terminal-connection.ts`) instead. Three apps still import
+ * this seam; retirement is tracked in #350 and removal is a major.
  */
 declare function terminalUpgradeSubprotocolEcho(upstream: TerminalUpgradeResponseLike, browserProtocol: string | null): {
     status: number;
@@ -522,19 +737,212 @@ declare function terminalUpgradeSubprotocolEcho(upstream: TerminalUpgradeRespons
  * 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.
+ *
+ * @deprecated Exists only to serve the same-origin proxy terminal transport,
+ * superseded by the browser-direct scoped-token transport — build the route
+ * with `createSandboxTerminalConnectionRoute`
+ * (`src/sandbox/terminal-connection.ts`) instead. Three apps still import
+ * this seam; retirement is tracked in #350 and removal is a major.
  */
 declare function selectedBearerSubprotocol(value: string | null): string | null;
-/** Build proxy headers for sandbox runtime including authorization and forwarded headers */
+/**
+ * Build proxy headers for sandbox runtime including authorization and forwarded headers
+ *
+ * @deprecated Exists only to serve the same-origin proxy terminal transport,
+ * superseded by the browser-direct scoped-token transport — build the route
+ * with `createSandboxTerminalConnectionRoute`
+ * (`src/sandbox/terminal-connection.ts`) instead. Three apps still import
+ * this seam; retirement is tracked in #350 and removal is a major.
+ */
 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 */
+/**
+ * Encode a runtime path by URI-encoding each valid segment and returning null for invalid segments
+ *
+ * @deprecated Exists only to serve the same-origin proxy terminal transport,
+ * superseded by the browser-direct scoped-token transport — build the route
+ * with `createSandboxTerminalConnectionRoute`
+ * (`src/sandbox/terminal-connection.ts`) instead. Three apps still import
+ * this seam; retirement is tracked in #350 and removal is a major.
+ */
 declare function encodeSandboxRuntimePath(runtimePath: string): string | null;
-/** Extract the token from a bearer authorization string or return null if invalid or missing */
+/**
+ * Extract the token from a bearer authorization string or return null if invalid or missing
+ *
+ * @deprecated Exists only to serve the same-origin proxy terminal transport,
+ * superseded by the browser-direct scoped-token transport — build the route
+ * with `createSandboxTerminalConnectionRoute`
+ * (`src/sandbox/terminal-connection.ts`) instead. Three apps still import
+ * this seam; retirement is tracked in #350 and removal is a major.
+ */
 declare function bearerToken(value: string | null): string | null;
-/** Resolve and decode a bearer token from a comma-separated subprotocol string or return null */
+/**
+ * Resolve and decode a bearer token from a comma-separated subprotocol string or return null
+ *
+ * @deprecated Exists only to serve the same-origin proxy terminal transport,
+ * superseded by the browser-direct scoped-token transport — build the route
+ * with `createSandboxTerminalConnectionRoute`
+ * (`src/sandbox/terminal-connection.ts`) instead. Three apps still import
+ * this seam; retirement is tracked in #350 and removal is a major.
+ */
 declare function bearerSubprotocolToken(value: string | null): string | null;
-/** Resolve the terminal token from request headers using Authorization or Sec-WebSocket-Protocol fields */
+/**
+ * Resolve the terminal token from request headers using Authorization or Sec-WebSocket-Protocol fields
+ *
+ * @deprecated Exists only to serve the same-origin proxy terminal transport,
+ * superseded by the browser-direct scoped-token transport — build the route
+ * with `createSandboxTerminalConnectionRoute`
+ * (`src/sandbox/terminal-connection.ts`) instead. Three apps still import
+ * this seam; retirement is tracked in #350 and removal is a major.
+ */
 declare function terminalTokenFromRequest(headers: Headers): string | null;
 
+/**
+ * Browser-direct scoped-token terminal connection route (#341/#349).
+ *
+ * Epic #343 / decision #341: the fleet's terminal transport is browser-direct
+ * — the product's server authenticates the request and provisions/resolves
+ * the sandbox exactly once, mints a short-lived SDK scoped token
+ * (`box.mintScopedToken`), and hands the browser just enough to connect
+ * `TerminalView` straight to the sidecar. No worker relays terminal bytes for
+ * this shape — that is the proxy transport in `./workspace-terminal` +
+ * `./terminal-proxy-token`, now `@deprecated` in favor of this one
+ * (retirement tracked in #350; nothing removed, three apps still import it).
+ *
+ * VERIFIED PLATFORM CONTRACT (`@tangle-network/sandbox` 0.15.2 + the
+ * orchestrator/sidecar enforcement source, verified 2026-07-30):
+ *
+ * 1. Only a `scope: 'session-runtime'` token carries the `terminal`
+ *    capability (`cap: ["read", "workspace", "terminal"]`). `'project'` and
+ *    `'session'` mint SessionGateway READ tokens (HS256, `typ: "read"`, no
+ *    `cap` claim at all — a different token family the sidecar rejects
+ *    outright); `'read-only'` carries `cap: ["read"]` only. **No scope other
+ *    than `'session-runtime'` can ever open a terminal**, which is why this
+ *    route no longer takes `scope` as a parameter — it is pinned.
+ * 2. The orchestrator's terminal WS gate fails closed unless the token's
+ *    `sid` claim EQUALS the `<connectionId>` path segment of
+ *    `/terminals/<connectionId>/ws`
+ *    (`verifyScopedSidecarCapability(sidecar, token, "terminal", connectionId)`).
+ *    So `mintScopedToken({ scope: 'session-runtime', sessionId })` MUST be
+ *    called with `sessionId === connectionId` — the exact id `TerminalView`
+ *    will dial. That is why this route threads a `connectionId` end to end
+ *    instead of deriving its own session id.
+ * 3. The browser-safe terminal base is the mint result's `sidecarProxyUrl`
+ *    (`/v1/sidecar-proxy/{id}` on the Sandbox API) — **not**
+ *    `box.connection.runtimeUrl`. The SDK's own `_attachTerminal` is the
+ *    reference implementation:
+ *    `mintScopedToken({ scope: 'session-runtime', sessionId: connectionId })`
+ *    then dial `${scoped.sidecarProxyUrl}/terminals/${connectionId}/ws`.
+ *    Pointing `TerminalView` at `runtimeUrl` fails auth regardless of scope —
+ *    only the sidecar-proxy hop decodes the browser's
+ *    `bearer.<base64url>` WS subprotocol.
+ *
+ * HISTORICAL NOTE: an earlier shape of this route (and legal-agent's
+ * production route it was modeled on, `scope: 'project'` +
+ * `connection.runtimeUrl`) predates the platform's terminal-auth hardening —
+ * the terminal capability gate (2026-06-19), the scoped-token terminal WS
+ * path (2026-07-15), and the `sid`-binding fail-closed check
+ * (2026-07-17/18). That shape does not authenticate on the current platform
+ * and is not a valid spec for the token path anymore.
+ *
+ * SECURITY POSTURE: unlike the read-only session-gateway streaming token
+ * (`box.mintScopedToken({scope:'session'})` paired with
+ * `SessionGatewayClient`), the token this route mints grants **command
+ * execution** in the sandbox once handed to `TerminalView`. Its safety rests
+ * on a **short TTL** (default 15 minutes, the SDK's own max — still a caller
+ * parameter) and, structurally, the narrowest scope the platform offers: one
+ * box (`ensureSandbox` resolved it for THIS user), one terminal connection
+ * (`session-runtime` bound to a single `sid`). Widening the TTL default
+ * without an explicit reason is a security regression, not a convenience.
+ *
+ * Wire contract: the browser passes the response's `sidecarUrl` as
+ * `TerminalView`'s `apiUrl` prop, `token` as its token prop, and the
+ * response's echoed `connectionId` as `TerminalView`'s `connectionId` prop —
+ * the token's `sid` is bound to exactly that id, so any other value fails the
+ * WS upgrade. sandbox-ui sends the token as a `bearer.<base64url>` WebSocket
+ * subprotocol (browsers cannot set `Authorization` on a WS handshake).
+ * `useSandboxTerminalConnection` (`../web-react/sandbox-terminal`) carries
+ * `connectionId` through automatically.
+ */
+/** The structural surface this route needs from an SDK sandbox box — no `@tangle-network/sandbox` class import (invariant 3). */
+interface TerminalConnectionBoxLike {
+    id: string;
+    status?: string;
+    connection?: {
+        runtimeUrl?: string;
+    };
+    mintScopedToken(opts: {
+        scope: string;
+        sessionId?: string;
+        ttlMinutes?: number;
+    }): Promise<{
+        token: string;
+        expiresAt: Date;
+        sidecarProxyUrl: string;
+    }>;
+}
+/** Configuration for {@link createSandboxTerminalConnectionRoute}. */
+interface SandboxTerminalConnectionRouteOptions<TBox extends TerminalConnectionBoxLike, TUser> {
+    /**
+     * Authenticate the incoming request. Return the authenticated user, or a
+     * `Response` to short-circuit the route (e.g. a 401) — that Response is
+     * returned to the caller verbatim.
+     */
+    requireUser(request: Request): Promise<TUser | Response>;
+    /**
+     * Resolve (provisioning if needed) the sandbox this user's terminal should
+     * connect to. Domain-specific provisioning (workspace- vs user-scoped,
+     * naming, reuse) stays entirely in the product's implementation of this
+     * seam — the route only reacts to success/failure.
+     */
+    ensureSandbox(user: TUser, request: Request): Promise<TBox>;
+    /** `box.mintScopedToken` TTL in minutes. Default `15` (the SDK's own max). */
+    ttlMinutes?: number;
+    /**
+     * Resolve the terminal connection id the minted token's `sid` is bound to
+     * — this MUST be the same id `TerminalView` dials
+     * (`tabTerminalConnectionId()`), because the orchestrator's terminal WS
+     * gate fails closed unless `sid === <connectionId>` in
+     * `/terminals/<connectionId>/ws`.
+     *
+     * `requested` is `new URL(request.url).searchParams.get('connectionId')`.
+     * The default resolver returns `requested` unchanged. A product may
+     * validate/namespace the id here (e.g. a per-user prefix in a shared box)
+     * — if it rewrites the id, the client MUST use the response's echoed
+     * `connectionId`, since the sid binding makes any other id fail the WS
+     * upgrade.
+     *
+     * A resolved falsy/empty value fails the request with a 400 before any
+     * sandbox work happens.
+     */
+    resolveConnectionId?: (ctx: {
+        request: Request;
+        user: TUser;
+        box: TBox;
+        requested: string | null;
+    }) => string | null | undefined | Promise<string | null | undefined>;
+}
+/**
+ * Build the browser-direct terminal connection route: `GET` handler that
+ * authenticates, resolves the sandbox, mints a scoped token pinned to
+ * `scope: 'session-runtime'` (the ONLY scope the platform grants the
+ * `terminal` capability to), and returns exactly what the browser needs to
+ * connect `TerminalView` directly to the sidecar — no worker in the data
+ * path once the terminal is open.
+ *
+ * Response shapes:
+ * - `requireUser` returns a `Response` → that `Response`, verbatim.
+ * - `ensureSandbox` throws → `500 {error}` (the thrown message surfaced).
+ * - `box.connection?.runtimeUrl` missing → `503 {error, status: box.status}`
+ *   — this is a READINESS gate only; the URL returned to the client on
+ *   success is always the mint's `sidecarProxyUrl`, never `runtimeUrl`.
+ * - resolved connection id is falsy/empty → `400 {error}`.
+ * - `box.mintScopedToken` rejects → `503 {error}`.
+ * - success → `200 {sidecarUrl, token, expiresAt, status, sandboxId, connectionId}`.
+ *   `connectionId` is the id the token's `sid` is bound to — the client MUST
+ *   hand this (not its own) to `TerminalView`.
+ */
+declare function createSandboxTerminalConnectionRoute<TBox extends TerminalConnectionBoxLike, TUser>(opts: SandboxTerminalConnectionRouteOptions<TBox, TUser>): (request: Request) => Promise<Response>;
+
 /**
  * `createSandboxPrewarmer` — "this user just opened this project; start warming
  * their box" as a shell primitive, so every agent-app product gets the same
@@ -1339,4 +1747,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 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 SandboxTerminalConnectionRouteOptions, type SandboxTerminalTokenOptions, type SandboxTerminalTokenResult, type SandboxTerminalTokenSubject, type SandboxTerminalWsMatch, type SandboxToolPathOptions, type SandboxToolSpec, type ScopedTokenResult, type SecretStore, type StoppedSandboxResumeFailure, type StoppedSandboxResumeRecovery, type StreamSandboxPromptOptions, type TerminalConnectionBoxLike, 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, createSandboxTerminalConnectionRoute, 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

@@ -23,6 +23,7 @@ import {
   collectSandboxPromptText,
   createD1PrewarmClaimStore,
   createSandboxPrewarmer,
+  createSandboxTerminalConnectionRoute,
   createSandboxTerminalToken,
   createWorkspaceSandboxConnectionHandler,
   createWorkspaceSandboxManager,
@@ -72,7 +73,7 @@ import {
   verifySandboxTerminalToken,
   verifyTerminalProxyToken,
   writeProfileFilesToBox
-} from "../chunk-2UDJH6QR.js";
+} from "../chunk-APFJITYT.js";
 import "../chunk-LWSJK546.js";
 import "../chunk-CQZSAR77.js";
 import "../chunk-ICOHEZK6.js";
@@ -105,6 +106,7 @@ export {
   collectSandboxPromptText,
   createD1PrewarmClaimStore,
   createSandboxPrewarmer,
+  createSandboxTerminalConnectionRoute,
   createSandboxTerminalToken,
   createWorkspaceSandboxConnectionHandler,
   createWorkspaceSandboxManager,

package/dist/web-react/index.js

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