@tangle-network/agent-app 0.44.60 → 0.45.2

package/dist/sandbox/index.d.ts

@@ -261,68 +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
- *
- * @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
- *
- * @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
- *
- * @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 */
+/** Define the shape of a workspace sandbox instance including its connection details and status. */
 interface WorkspaceSandboxInstanceLike {
     id: string;
     name?: string;
@@ -335,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;
@@ -357,444 +296,15 @@ 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 */
-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
- *
- * @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
- *
- * @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
- *
- * @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
- *
- * @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
- *
- * @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
- *
- * @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
- *
- * @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: {
-        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
- *
- * @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
- *
- * @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
- *
- * @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;
-}
 /**
- * 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.
- *
- * @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.
+ * Create a generic name-keyed sandbox lifecycle manager for products that
+ * drive their own SDK or box types.
  */
-declare function sandboxSidecarProxyUrl(baseUrl: string, sandboxId: string): string;
-/**
- * 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
- *
- * @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: {
-        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
- *
- * @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: {
-        workspaceId?: string;
-        sandboxId?: string;
-        '*'?: string;
-    };
-}
-/**
- * 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
- *
- * @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;
-    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.
- *
- * @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.
- *
- * @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
- *
- * @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: {
-        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;
-}
-/**
- * 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
- * ```
- *
- * @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.
- *
- * @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;
-    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.
- *
- * @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;
-    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.
- *
- * @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
- *
- * @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
- *
- * @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
- *
- * @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
- *
- * @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
- *
- * @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;
+declare function createWorkspaceSandboxManager<TClient, TBox extends WorkspaceSandboxInstanceLike, TEnsureOptions = void>(opts: WorkspaceSandboxManagerOptions<TClient, TBox, TEnsureOptions>): WorkspaceSandboxManager<TBox, TEnsureOptions>;
 
 /**
  * Browser-direct scoped-token terminal connection route (#341/#349).
@@ -803,10 +313,9 @@ declare function terminalTokenFromRequest(headers: Headers): string | null;
  * — 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).
+ * `TerminalView` straight to the sidecar. No worker relays terminal bytes.
+ * The deprecated same-origin relay was removed in #350 after the fleet
+ * migrated, leaving this as the package's only terminal transport.
  *
  * VERIFIED PLATFORM CONTRACT (`@tangle-network/sandbox` 0.15.2 + the
  * orchestrator/sidecar enforcement source, verified 2026-07-30):
@@ -1349,6 +858,26 @@ interface SandboxRuntimeConfig {
     name: (workspaceId: string) => string;
     metadata: (harness: Harness) => Record<string, unknown>;
     connectedIntegrationIds: (workspaceId: string) => Promise<string[]>;
+    /**
+     * Raw box environment written once at sandbox CREATION — deliberately plain
+     * strings, and the one place a credential value legitimately lives.
+     *
+     * This is the private side of the tagged-config contract, not profile
+     * material: an `AgentProfileMcpServer` may only carry a `secret-ref` naming a
+     * key, and the sandbox resolves that key against THIS map (or against the
+     * platform secret store fed by {@link SandboxRuntimeConfig.secrets}). So a
+     * `tokenEnvKey` passed to `buildAppToolMcpServers` must name a variable this
+     * seam places, or the reference resolves to nothing.
+     *
+     * It is NOT widened to tagged values: the sandbox SDK's create payload types
+     * `env` as `Record<string, string>`, and {@link assertEnvWithinLimits}
+     * measures those bytes against the kernel's per-entry `MAX_ARG_STRLEN`.
+     * Tagging it would make the box env reference itself.
+     *
+     * Values are workspace-wide and fixed for the box's lifetime, so a per-user
+     * or per-resource credential cannot be placed here — see
+     * `unresolvableSurfaceCredential` in `../tools/mcp`.
+     */
     env: (ctx: SandboxBuildContext) => Promise<Record<string, string>>;
     files: (ctx: SandboxBuildContext) => Promise<AgentProfileFileMount[]>;
     secrets: (workspaceId: string) => Promise<string[]>;
@@ -1392,7 +921,17 @@ interface AppToolDescriptor {
 interface BuildAppToolMcpServersOptions {
     tools: AppToolDescriptor[];
     baseUrl: string;
-    token: string;
+    /**
+     * NAME of the box-environment variable holding the capability token — never
+     * the token itself. Every emitted `Authorization` header is a `secret-ref` to
+     * this key, which the sandbox resolves privately; see
+     * `BuildHttpMcpServerOptions.tokenEnvKey` in `../tools/mcp`.
+     *
+     * The key must name a variable the box carries — placed by
+     * {@link SandboxRuntimeConfig.env} at creation, or injected from the platform
+     * secret store via {@link SandboxRuntimeConfig.secrets}.
+     */
+    tokenEnvKey: string;
     ctx: AppToolContext;
     headerNames?: ToolHeaderNames;
 }
@@ -1747,4 +1286,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 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 };
+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 };