@tangle-network/sandbox 0.30.1 → 0.30.2-develop.20260820122029.869ebfa

package/dist/terminal-stream-4KNJ6SmL.d.ts

@@ -0,0 +1,256 @@
+import { AgentInteractiveSessionControlClaim, AgentInteractiveSessionRef } from "@tangle-network/agent-interface";
+import { z } from "zod";
+
+//#region ../../../packages/runtime-contracts/dist/terminal-websocket.d.ts
+/** Non-credential protocol selected during a successful terminal handshake. */
+declare const TERMINAL_WS_ECHO_SUBPROTOCOL = "tangle.terminal.v1";
+declare const terminalReadyMessageSchema: z.ZodObject<{
+  type: z.ZodLiteral<"ready">;
+  connectionId: z.ZodString;
+  sessionId: z.ZodString;
+  restored: z.ZodBoolean;
+  detachTimeoutMs: z.ZodNumber;
+}, z.core.$strip>;
+type TerminalReadyMessage = z.infer<typeof terminalReadyMessageSchema>;
+type TerminalReadyInfo = Omit<TerminalReadyMessage, "type">;
+declare const terminalExitMessageSchema: z.ZodObject<{
+  type: z.ZodLiteral<"exit">;
+  exitCode: z.ZodOptional<z.ZodNumber>;
+  exitSignal: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type TerminalExitMessage = z.infer<typeof terminalExitMessageSchema>;
+type TerminalExitInfo = Omit<TerminalExitMessage, "type">;
+type TerminalStreamAuthFormat = "edge" | "sidecar-direct";
+interface TerminalInteractiveSessionIdentity {
+  incarnationId: AgentInteractiveSessionRef["incarnationId"];
+  control: AgentInteractiveSessionControlClaim;
+}
+//#endregion
+//#region src/scoped-token-types.d.ts
+/**
+ * Public types for scoped consumer-side tokens.
+ *
+ * This module intentionally has no SDK implementation imports. Terminal
+ * streams and token requests share these contracts without depending on the
+ * SDK's aggregate types module.
+ */
+/**
+ * Scope of a `box.mintScopedToken()` request. `session` and `project` mint
+ * SessionGateway read tokens. `session-runtime` and `read-only` mint sidecar
+ * capability tokens for browser-safe runtime access.
+ */
+type ScopedTokenScope = "session" | "session-runtime" | "project" | "read-only";
+interface MintScopedTokenBase {
+  /** TTL in minutes. Default 5; clamped to [1, 15]. */
+  ttlMinutes?: number;
+  /** Cancel the token request before it reaches the terminal dial. */
+  signal?: AbortSignal;
+}
+/** Options for `box.mintScopedToken()`, narrowed by consumer scope. */
+type MintScopedTokenOptions = (MintScopedTokenBase & {
+  scope: "session"; /** Client-facing browser session ID. */
+  sessionId: string; /** Actual runtime session ID used to filter the sandbox event stream. */
+  runtimeSessionId: string;
+}) | (MintScopedTokenBase & {
+  scope: "session-runtime";
+  sessionId: string;
+  runtimeSessionId?: never;
+}) | (MintScopedTokenBase & {
+  scope: "project" | "read-only";
+  sessionId?: never;
+  runtimeSessionId?: never;
+});
+/** Options for the server-side exact interactive-session token request. */
+type MintInteractiveSessionTokenOptions = Pick<MintScopedTokenBase, "ttlMinutes" | "signal">;
+/**
+ * Returned by `box.mintScopedToken()`. Use session/project tokens with
+ * `SessionGatewayClient`; use session-runtime/read-only tokens with
+ * `SandboxRuntimeClient`.
+ */
+interface ScopedToken {
+  /** Bearer token (JWT) for the consumer selected by `scope`. */
+  token: string;
+  /** When the token expires. */
+  expiresAt: Date;
+  /** The runtime's direct edge URL. Use with runtime scopes; session/project
+   * tokens instead connect to the Sandbox API's `/session` WebSocket. */
+  runtimeUrl: string;
+  /** Browser-safe Sandbox API proxy base for terminal and runtime requests. */
+  sidecarProxyUrl: string;
+  /** Echo of the requested scope. */
+  scope: ScopedTokenScope;
+}
+//#endregion
+//#region src/terminal-stream.d.ts
+/** A protocol `error` control frame or a transport failure. */
+declare class TerminalStreamError extends Error {
+  /** Protocol error code (e.g. `INIT_FAILED`) or `TRANSPORT` for socket faults. */
+  readonly code: string;
+  constructor(message: string, code: string);
+}
+/**
+ * Event callbacks, passed at construction (the same idiom as
+ * `SessionGatewayClient`'s `handlers` config). Registering them up front is
+ * load-bearing: the server replays PTY history immediately after `ready`, so
+ * a handler attached after connect would miss the replayed screen.
+ */
+interface TerminalStreamHandlers {
+  /** Raw PTY output bytes (both live output and reattach history replay). */
+  onData?: (data: Uint8Array) => void;
+  onReady?: (info: TerminalReadyInfo) => void;
+  onExit?: (info: TerminalExitInfo) => void;
+  /** Protocol `error` frames and post-connect transport failures. */
+  onError?: (error: TerminalStreamError) => void;
+  /** Socket closed — by the server, the network, or a local `close()`. */
+  onClose?: (code: number, reason: string) => void;
+}
+/**
+ * Which WebSocket-subprotocol auth envelope to offer. A WebSocket client
+ * cannot set an Authorization header, so the bearer rides the
+ * `Sec-WebSocket-Protocol` offer — and the two dialable endpoints expect
+ * DIFFERENT envelopes:
+ *
+ * - `"edge"` (default): the public API proxy
+ *   (`wss://<api>/v1/sidecar-proxy/{sidecarId}/terminals/{id}/ws`) expects
+ *   `bearer.<base64url(token)>` — see `parseTerminalWsSubprotocolToken` in
+ *   `products/sandbox/api/src/lib/terminal-websocket.ts`. The fixed
+ *   `tangle.terminal.v1` marker is offered alongside the credential (see
+ *   {@link TERMINAL_WS_ECHO_SUBPROTOCOL}).
+ * - `"sidecar-direct"`: the sidecar's own `/terminals/{id}/ws` route expects
+ *   `tangle.bearer.<token>` plus the same `tangle.terminal.v1` echo marker —
+ *   see `apps/sidecar/src/routes/ws-subprotocol-auth.ts`. Only
+ *   platform-internal callers (and the composed integration tests) dial the
+ *   sidecar directly.
+ */
+/**
+ * Bearer credential for the dial: a token string, or a provider invoked on
+ * EVERY dial (including {@link TerminalStream.reconnect}). The provider
+ * receives that dial's AbortSignal so token minting observes cancellation.
+ * Scoped terminal tokens are short-lived (the platform clamps them to <= 15
+ * minutes), so a provider lets the SDK re-mint a fresh token per dial.
+ */
+type TerminalStreamToken = string | ScopedToken | ((signal?: AbortSignal) => Promise<string | ScopedToken> | string | ScopedToken);
+/** Authority refreshed before an interactive stream reconnects. */
+interface TerminalStreamReconnectBinding {
+  incarnationId: TerminalInteractiveSessionIdentity["incarnationId"];
+  control: TerminalInteractiveSessionIdentity["control"];
+  /** Release a claim if the new socket cannot be opened. */
+  onFailure?: () => Promise<void> | void;
+}
+/** Internal SDK hook that reclaims interactive authority before reconnect. */
+interface TerminalStreamReconnectAuthority {
+  acquire(signal?: AbortSignal): Promise<TerminalStreamReconnectBinding>;
+}
+interface TerminalStreamOptions {
+  /**
+   * Absolute URL of the terminal WebSocket endpoint. `http(s)` URLs are
+   * converted to `ws(s)` automatically.
+   */
+  url: string;
+  /**
+   * Bearer token carried in the auth subprotocol (see `authFormat`) — a
+   * string, or a provider re-invoked on every dial so short-lived scoped
+   * tokens stay fresh across reconnects.
+   */
+  token: TerminalStreamToken;
+  /**
+   * PTY connection id — also sent in the `init` frame; the server rejects a
+   * mismatch with the URL's id. Reusing an id reattaches the existing PTY.
+   */
+  connectionId: string;
+  cols?: number;
+  rows?: number;
+  /** Command to run when the id has no live PTY (defaults to the shell). */
+  command?: string;
+  cwd?: string;
+  env?: Record<string, string>;
+  /**
+   * Exact interactive-agent incarnation. Ordinary terminal consumers omit
+   * both interactive fields and retain the existing wire contract.
+   */
+  incarnationId?: TerminalInteractiveSessionIdentity["incarnationId"];
+  /** Exact active control claim for the interactive-agent incarnation. */
+  control?: TerminalInteractiveSessionIdentity["control"];
+  /** Auth subprotocol envelope. Default `"edge"`. */
+  authFormat?: TerminalStreamAuthFormat;
+  handlers?: TerminalStreamHandlers;
+  /** Reject `connect()` if `ready` has not arrived within this window. */
+  connectTimeoutMs?: number;
+  /** Cancel token resolution or an in-progress WebSocket handshake. */
+  signal?: AbortSignal;
+  /** Reclaim interactive authority before a reconnecting dial. */
+  reconnectAuthority?: TerminalStreamReconnectAuthority;
+}
+/**
+ * Client for one terminal WebSocket connection. Construct via
+ * {@link TerminalStream.connect}, which resolves once the server
+ * acknowledges the attach with `ready` (history replay then streams through
+ * `handlers.onData`).
+ */
+declare class TerminalStream {
+  private readonly ws;
+  private readonly options;
+  private readonly interactiveIdentity;
+  private readonly initMessage;
+  private readonly handlers;
+  private readyInfo;
+  private closed;
+  private closeWaiters;
+  private readonly textDecoder;
+  private reconnectInFlight?;
+  /**
+   * Dial the endpoint, send `init` as the first frame, and resolve once the
+   * server responds `ready`. Rejects on a protocol `error` frame, a socket
+   * close/failure before `ready`, or the connect timeout — always with the
+   * reason the server gave. A token PROVIDER is awaited here, before the
+   * socket opens, so every dial (first connect and each reconnect) carries a
+   * fresh credential.
+   */
+  static connect(options: TerminalStreamOptions): Promise<TerminalStream>;
+  private constructor();
+  private establish;
+  private handleMessage;
+  /** PTY connection id this stream is attached to. */
+  get connectionId(): string;
+  /** The server's `ready` acknowledgement. Set once `connect()` resolves. */
+  get ready(): TerminalReadyInfo;
+  /** True while the socket is open. */
+  get isOpen(): boolean;
+  /**
+   * Send input keystrokes to the PTY. `Uint8Array` input is decoded as
+   * UTF-8 (the wire protocol carries input as JSON text). Input larger than
+   * the server's 1 MiB frame cap is split across multiple `input` frames in
+   * order on the same socket, so delivery order is preserved.
+   */
+  write(data: string | Uint8Array): void;
+  /** Resize the PTY. */
+  resize(cols: number, rows: number): void;
+  /**
+   * Detach cleanly: close the socket and resolve once the close completes.
+   * The PTY survives server-side for `ready.detachTimeoutMs` (5 minutes
+   * today) — reattach within that window via {@link reconnect} (or a fresh
+   * `connect()` with the same connectionId) to replay history and continue.
+   */
+  close(): Promise<void>;
+  /**
+   * Re-dial the same endpoint with the same connectionId on a fresh socket
+   * — the server reattaches the PTY and replays its buffered history. When
+   * the stream was constructed with a token PROVIDER, it is re-invoked for
+   * the new dial (scoped terminal tokens expire within minutes, so the
+   * original credential may be dead by reconnect time); with a plain string
+   * token, pass a fresh `token` override yourself when it may have expired.
+   * `handlers` rebinds callbacks for the new stream.
+   */
+  reconnect(overrides?: {
+    token?: TerminalStreamToken;
+    handlers?: TerminalStreamHandlers;
+    cols?: number;
+    rows?: number;
+    signal?: AbortSignal;
+  }): Promise<TerminalStream>;
+  private reconnectOnce;
+  private handlersForReconnect;
+  private assertOpen;
+}
+//#endregion
+export { TerminalStreamReconnectAuthority as a, MintScopedTokenOptions as c, TERMINAL_WS_ECHO_SUBPROTOCOL as d, TerminalExitInfo as f, TerminalStreamAuthFormat as h, TerminalStreamOptions as i, ScopedToken as l, TerminalReadyInfo as m, TerminalStreamError as n, TerminalStreamToken as o, TerminalInteractiveSessionIdentity as p, TerminalStreamHandlers as r, MintInteractiveSessionTokenOptions as s, TerminalStream as t, ScopedTokenScope as u };

package/dist/{types-Qn3x7R8O.d.ts → types-BwYLVqxX.d.ts}

@@ -1,213 +1,8 @@
+import { r as TerminalStreamHandlers, t as TerminalStream } from "./terminal-stream-4KNJ6SmL.js";
+import * as _$_tangle_network_agent_interface0 from "@tangle-network/agent-interface";
 import { AgentExactRunControlRef, AgentProfile, AgentProfileCapabilities, AgentProfileConfidential, AgentProfileValidationResult, HarnessType, ReasoningEffort } from "@tangle-network/agent-interface";
 import { z } from "zod";
 
-//#region src/terminal-stream.d.ts
-/**
- * TerminalStream — typed client for the sandbox terminal WebSocket protocol.
- *
- * Drives a live PTY session (an interactive harness TUI or a plain shell)
- * from the caller's own program: binary frames stream raw PTY output bytes,
- * TEXT JSON frames carry the control protocol. The wire contract is defined
- * by the sidecar in `apps/sidecar/src/terminal/websocket-protocol.ts` (the
- * source of truth for these message shapes — its zod schemas cannot be
- * imported here without pulling sidecar dependencies into the SDK bundle,
- * so the types are mirrored locally):
- *
- *   client → server (TEXT JSON):
- *     init   {connectionId?, cols, rows, command?, cwd?, env?}  — MUST be first
- *     input  {data}
- *     resize {cols, rows}
- *   server → client (TEXT JSON):
- *     ready  {connectionId, sessionId, restored, detachTimeoutMs}
- *     exit   {exitCode?, exitSignal?}
- *     error  {code, message}
- *     rec / rec.done — recording tee frames for the platform's session
- *                      capture consumer; not part of the client surface
- *   server → client (BINARY): raw PTY output bytes
- *
- * Detach/reconnect: the server keeps the PTY alive for `detachTimeoutMs`
- * (5 minutes today) after the socket closes; re-dialing with the SAME
- * connectionId reattaches and replays the buffered output history, so a
- * fresh client repaints the current screen.
- *
- * Browser-safe: uses the global `WebSocket` (browsers, Workers, Node >= 22)
- * and never imports `ws` — the same environment contract as
- * `session-gateway/client.ts`.
- */
-/** Ready acknowledgement — the PTY is attached and history replay follows. */
-interface TerminalReadyInfo {
-  connectionId: string;
-  sessionId: string;
-  /** True when an existing PTY was reattached (its history is replayed). */
-  restored: boolean;
-  /** How long (ms) the server keeps the PTY alive after this socket closes. */
-  detachTimeoutMs: number;
-}
-/** Terminal process exit notification. */
-interface TerminalExitInfo {
-  exitCode?: number;
-  exitSignal?: string;
-}
-/** A protocol `error` control frame or a transport failure. */
-declare class TerminalStreamError extends Error {
-  /** Protocol error code (e.g. `INIT_FAILED`) or `TRANSPORT` for socket faults. */
-  readonly code: string;
-  constructor(message: string, code: string);
-}
-/**
- * Event callbacks, passed at construction (the same idiom as
- * `SessionGatewayClient`'s `handlers` config). Registering them up front is
- * load-bearing: the server replays PTY history immediately after `ready`, so
- * a handler attached after connect would miss the replayed screen.
- */
-interface TerminalStreamHandlers {
-  /** Raw PTY output bytes (both live output and reattach history replay). */
-  onData?: (data: Uint8Array) => void;
-  onReady?: (info: TerminalReadyInfo) => void;
-  onExit?: (info: TerminalExitInfo) => void;
-  /** Protocol `error` frames and post-connect transport failures. */
-  onError?: (error: TerminalStreamError) => void;
-  /** Socket closed — by the server, the network, or a local `close()`. */
-  onClose?: (code: number, reason: string) => void;
-}
-/**
- * Which WebSocket-subprotocol auth envelope to offer. A WebSocket client
- * cannot set an Authorization header, so the bearer rides the
- * `Sec-WebSocket-Protocol` offer — and the two dialable endpoints expect
- * DIFFERENT envelopes:
- *
- * - `"edge"` (default): the public API proxy
- *   (`wss://<api>/v1/sidecar-proxy/{sidecarId}/terminals/{id}/ws`) expects
- *   `bearer.<base64url(token)>` — see `parseTerminalWsSubprotocolToken` in
- *   `products/sandbox/api/src/lib/terminal-websocket.ts`. The fixed
- *   `tangle.terminal.v1` marker is offered alongside the credential (see
- *   {@link TERMINAL_WS_ECHO_SUBPROTOCOL}).
- * - `"sidecar-direct"`: the sidecar's own `/terminals/{id}/ws` route expects
- *   `tangle.bearer.<token>` plus the same `tangle.terminal.v1` echo marker —
- *   see `apps/sidecar/src/routes/ws-subprotocol-auth.ts`. Only
- *   platform-internal callers (and the composed integration tests) dial the
- *   sidecar directly.
- */
-type TerminalStreamAuthFormat = "edge" | "sidecar-direct";
-/**
- * Bearer credential for the dial: a token string, or a provider invoked on
- * EVERY dial (including {@link TerminalStream.reconnect}). Scoped terminal
- * tokens are short-lived (the platform clamps them to <= 15 minutes), so a
- * reconnect after the detach window with the original string would be
- * rejected — a provider lets the SDK re-mint a fresh token per dial.
- */
-type TerminalStreamToken = string | (() => Promise<string> | string);
-interface TerminalStreamOptions {
-  /**
-   * Absolute URL of the terminal WebSocket endpoint. `http(s)` URLs are
-   * converted to `ws(s)` automatically.
-   */
-  url: string;
-  /**
-   * Bearer token carried in the auth subprotocol (see `authFormat`) — a
-   * string, or a provider re-invoked on every dial so short-lived scoped
-   * tokens stay fresh across reconnects.
-   */
-  token: TerminalStreamToken;
-  /**
-   * PTY connection id — also sent in the `init` frame; the server rejects a
-   * mismatch with the URL's id. Reusing an id reattaches the existing PTY.
-   */
-  connectionId: string;
-  cols?: number;
-  rows?: number;
-  /** Command to run when the id has no live PTY (defaults to the shell). */
-  command?: string;
-  cwd?: string;
-  env?: Record<string, string>;
-  /** Auth subprotocol envelope. Default `"edge"`. */
-  authFormat?: TerminalStreamAuthFormat;
-  handlers?: TerminalStreamHandlers;
-  /** Reject `connect()` if `ready` has not arrived within this window. */
-  connectTimeoutMs?: number;
-}
-/**
- * Fixed non-credential marker offered on EVERY dial (both auth formats),
- * giving a spec-compliant server something safe to select into the 101's
- * `Sec-WebSocket-Protocol`. Two reasons it exists:
- *
- * 1. RFC 6455 §4.1 says a client that offered subprotocols MUST fail the
- *    connection when the server selects none. Node's WebSocket (undici,
- *    per the WHATWG spec) enforces this strictly; browsers are lenient and
- *    tolerate a 101 with no selected subprotocol — which is why the
- *    browser-only reference client got away with offering just the
- *    credential.
- * 2. The server must never echo the token-bearing offer back (that would
- *    leak the live credential into a response header) — so it needs a
- *    non-credential protocol it CAN select.
- */
-declare const TERMINAL_WS_ECHO_SUBPROTOCOL = "tangle.terminal.v1";
-/**
- * Client for one terminal WebSocket connection. Construct via
- * {@link TerminalStream.connect}, which resolves once the server
- * acknowledges the attach with `ready` (history replay then streams through
- * `handlers.onData`).
- */
-declare class TerminalStream {
-  private readonly ws;
-  private readonly options;
-  private readonly handlers;
-  private readyInfo;
-  private closed;
-  private closeWaiters;
-  private readonly textDecoder;
-  /**
-   * Dial the endpoint, send `init` as the first frame, and resolve once the
-   * server responds `ready`. Rejects on a protocol `error` frame, a socket
-   * close/failure before `ready`, or the connect timeout — always with the
-   * reason the server gave. A token PROVIDER is awaited here, before the
-   * socket opens, so every dial (first connect and each reconnect) carries a
-   * fresh credential.
-   */
-  static connect(options: TerminalStreamOptions): Promise<TerminalStream>;
-  private constructor();
-  private establish;
-  private handleMessage;
-  /** PTY connection id this stream is attached to. */
-  get connectionId(): string;
-  /** The server's `ready` acknowledgement. Set once `connect()` resolves. */
-  get ready(): TerminalReadyInfo;
-  /** True while the socket is open. */
-  get isOpen(): boolean;
-  /**
-   * Send input keystrokes to the PTY. `Uint8Array` input is decoded as
-   * UTF-8 (the wire protocol carries input as JSON text). Input larger than
-   * the server's 1 MiB frame cap is split across multiple `input` frames in
-   * order on the same socket, so delivery order is preserved.
-   */
-  write(data: string | Uint8Array): void;
-  /** Resize the PTY. */
-  resize(cols: number, rows: number): void;
-  /**
-   * Detach cleanly: close the socket and resolve once the close completes.
-   * The PTY survives server-side for `ready.detachTimeoutMs` (5 minutes
-   * today) — reattach within that window via {@link reconnect} (or a fresh
-   * `connect()` with the same connectionId) to replay history and continue.
-   */
-  close(): Promise<void>;
-  /**
-   * Re-dial the same endpoint with the same connectionId on a fresh socket
-   * — the server reattaches the PTY and replays its buffered history. When
-   * the stream was constructed with a token PROVIDER, it is re-invoked for
-   * the new dial (scoped terminal tokens expire within minutes, so the
-   * original credential may be dead by reconnect time); with a plain string
-   * token, pass a fresh `token` override yourself when it may have expired.
-   * `handlers` rebinds callbacks for the new stream.
-   */
-  reconnect(overrides?: {
-    token?: TerminalStreamToken;
-    handlers?: TerminalStreamHandlers;
-    cols?: number;
-    rows?: number;
-  }): Promise<TerminalStream>;
-  private assertOpen;
-}
-//#endregion
 //#region ../../../packages/runtime-contracts/dist/backend-types.d.ts
 /**
  * Canonical harnesses this repo ships no provider adapter for.
@@ -2510,17 +2305,18 @@ interface InstalledTool {
  */
 /**
  * Granular outcome of an agent run.
- * - `success` — reached a terminal event with no run-level error and no failed
- *   tool. A tool-only turn succeeds unless the caller opts into visible-output
- *   enforcement.
- * - `failed` — a run-level error event, or any failed (`isError`) tool, or the
- *   stream ended with no terminal event.
+ * - `success` — reached a successful terminal event. Failed tool calls remain
+ *   available in `toolInvocations` because an agent can recover from them.
+ * - `failed` — a run-level error, a failed terminal, a malformed terminal, or
+ *   a stream that ended with no terminal event.
  * - `blocked_on_approval` — a tool hit a hub approval gate; resolve it, then
  *   re-run. See {@link AgentApprovalRequirement}.
  * - `awaiting_question` — the agent asked a question and the turn ended without
  *   an answer. See {@link AgentQuestionRequest}.
+ * - `awaiting_interaction` — the agent emitted another canonical interaction
+ *   request and the turn ended without a response.
  */
-type AgentRunStatus = "success" | "failed" | "blocked_on_approval" | "awaiting_question" | "awaiting_plan_decision";
+type AgentRunStatus = "success" | "failed" | "blocked_on_approval" | "awaiting_question" | "awaiting_interaction" | "awaiting_plan_decision";
 interface DurablePlanSnapshot {
   id: string;
   revision: number;
@@ -2650,6 +2446,8 @@ interface PromptResult {
   approval?: AgentApprovalRequirement;
   /** Set when `status === "awaiting_question"`. */
   question?: AgentQuestionRequest;
+  /** Canonical request for any interaction that still needs a response. */
+  interaction?: _$_tangle_network_agent_interface0.InteractionRequest;
   /** Set when `status === "awaiting_plan_decision"`. */
   plan?: DurablePlanSnapshot;
   /** Trace ID for debugging */
@@ -3194,6 +2992,18 @@ interface SandboxRuntimeCapabilities {
      *  record. Absent on an image that predates the flag. */
     responseDedupe?: boolean;
   };
+  /** Native TUI lifecycle and control operations exposed by the deployment. */
+  interactiveAgent?: {
+    /** Start one native TUI for the requested session. */start: boolean; /** Read durable TUI state. */
+    status: boolean; /** Attach to the existing native TUI. */
+    attach: boolean; /** Fence concurrent TUI writers with an exact control claim. */
+    control: boolean; /** Reattach after a client disconnect. */
+    reattach: boolean; /** Send a prompt to the existing TUI. */
+    sendPrompt: boolean; /** Send terminal input to the existing TUI. */
+    input: boolean; /** Resize the existing TUI. */
+    resize: boolean; /** Stop the exact TUI session. */
+    stop: boolean;
+  };
 }
 /**
  * Lifecycle state of an agent session inside a sandbox.
@@ -3650,48 +3460,6 @@ type FleetDriveTurnOutcome = {
   outcome: "error";
   error: string;
 };
-/**
- * Scope of a `box.mintScopedToken()` request. `session` and `project` mint
- * SessionGateway read tokens. `session-runtime` and `read-only` mint sidecar
- * capability tokens for browser-safe runtime access.
- */
-type ScopedTokenScope = "session" | "session-runtime" | "project" | "read-only";
-interface MintScopedTokenBase {
-  /** TTL in minutes. Default 5; clamped to [1, 15]. */
-  ttlMinutes?: number;
-}
-/** Options for `box.mintScopedToken()`, narrowed by consumer scope. */
-type MintScopedTokenOptions = (MintScopedTokenBase & {
-  scope: "session"; /** Client-facing browser session ID. */
-  sessionId: string; /** Actual runtime session ID used to filter the sandbox event stream. */
-  runtimeSessionId: string;
-}) | (MintScopedTokenBase & {
-  scope: "session-runtime";
-  sessionId: string;
-  runtimeSessionId?: never;
-}) | (MintScopedTokenBase & {
-  scope: "project" | "read-only";
-  sessionId?: never;
-  runtimeSessionId?: never;
-});
-/**
- * Returned by `box.mintScopedToken()`. Use session/project tokens with
- * `SessionGatewayClient`; use session-runtime/read-only tokens with
- * `SandboxRuntimeClient`.
- */
-interface ScopedToken {
-  /** Bearer token (JWT) for the consumer selected by `scope`. */
-  token: string;
-  /** When the token expires. */
-  expiresAt: Date;
-  /** The runtime's direct edge URL. Use with runtime scopes; session/project
-   * tokens instead connect to the Sandbox API's `/session` WebSocket. */
-  runtimeUrl: string;
-  /** Browser-safe Sandbox API proxy base for terminal and runtime requests. */
-  sidecarProxyUrl: string;
-  /** Echo of the requested scope. */
-  scope: ScopedTokenScope;
-}
 /**
  * Callback invoked when the SDK refreshes a sandbox bearer transparently
  * (e.g. after a 401 retry against the runtime endpoint). Lets long-
@@ -6478,4 +6246,4 @@ interface CodeExecutionOptions {
   idempotencyKey?: string;
 }
 //#endregion
-export { EgressPolicy as $, WriteManyFile as $i, SandboxConfig as $n, SandboxTraceOptions as $r, IntelligenceReportSubjectType as $t, CreateSandboxFleetTokenOptions as A, StorageConfig as Ai, ProvisionResult as An, SandboxFleetWorkspace as Ar, ForkIdempotency as At, DownloadOptions as B, TeePublicKey as Bi, ReconcileSandboxFleetsResult as Bn, SandboxResources as Br, GpuLeaseBilling as Bt, CodeResultPart as C, SnapshotIdempotency as Ci, ProcessSignal as Cn, SandboxFleetPolicy as Cr, FleetDriveTurnRequest as Ct, CreateIntelligenceReportOptions as D, SshKeysManager as Di, PromptOptions as Dn, SandboxFleetTraceExport as Dr, FleetPromptDispatchOptions as Dt, CreateGpuLeaseOptions as E, SnapshotResult as Ei, PromptInputPart as En, SandboxFleetTraceEvent as Er, FleetMachineId as Et, DeleteOptions as F, TaskSessionInfo as Fi, PublishPublicTemplateOptions as Fn, SandboxInfo as Fr, GitCommit as Ft, DriverType as G, UpdateUserOptions as Gi, RolloutChildResult as Gn, SandboxTerminalCreateOptions as Gr, GpuLeaseProviderName as Gt, DriveTurnOptions as H, TokenRefreshHandler as Hi, RestoreSnapshotOptions as Hn, SandboxRuntimeHealth as Hr, GpuLeaseExecOptions as Ht, DevServerInfo as I, TaskSessionProfile as Ii, PublishPublicTemplateVersionOptions as In, SandboxIntelligenceEnvelope as Ir, GitConfig as It, EffectiveBackend as J, UsageInfo as Ji, RolloutStartResult as Jn, SandboxTerminalRequestOptions as Jr, HostAgentRuntimeBackend as Jt, DurablePlan as K, UploadOptions as Ki, RolloutOptions as Kn, SandboxTerminalInfo as Kr, GpuLeaseStatus as Kt, DirectoryPermission as L, TeeAttestationOptions as Li, ReapExpiredSandboxFleetsOptions as Ln, SandboxPortBinding as Lr, GitDiff as Lt, CreateSandboxOptions as M, TaskSessionChanges as Mi, ProvisionStep as Mn, SandboxFleetWorkspaceRestoreResult as Mr, GPU_LEASE_PROVIDER_NAMES as Mt, CreateSessionOptions as N, TaskSessionCommitResult as Ni, PublicTemplateInfo as Nn, SandboxFleetWorkspaceSnapshotResult as Nr, GitAuth as Nt, CreateRequestOptions as O, StartupDiagnostics as Oi, PromptResult as On, SandboxFleetTraceOptions as Or, FleetPromptDispatchResult as Ot, CreateTaskSessionOptions as P, TaskSessionFileChange as Pi, PublicTemplateVersionInfo as Pn, SandboxIdentity as Pr, GitBranch as Pt, EgressManager as Q, WriteFileOptions as Qi, SSHCredentials as Qn, SandboxTraceExport as Qr, IntelligenceReportCompareTo as Qt, DispatchPromptOptions as R, TeeAttestationReport as Ri, ReapExpiredSandboxFleetsResult as Rn, SandboxPortPreviewLink as Rr, GitStatus as Rt, CodeLanguage as S, SnapshotDeleteOutcome as Si, ProcessManager as Sn, SandboxFleetOperationsSummary as Sr, FleetDriveTurnOutcome as St, CompletedTurnResult as T, SnapshotOptions as Ti, ProcessStatus as Tn, SandboxFleetTraceBundle as Tr, FleetExecDispatchResult as Tt, DriverConfig as U, TokenUsage as Ui, ResumeOptions as Un, SandboxStatus as Ur, GpuLeaseExecResult as Ut, DownloadProgress as V, TeePublicKeyResponse as Vi, RenameOptions as Vn, SandboxRuntimeCapabilities as Vr, GpuLeaseCommandResult as Vt, DriverInfo as W, TurnDriveResult as Wi, Rollout as Wn, SandboxTerminalAttachOptions as Wr, GpuLeaseManager as Wt, EffectiveBackendSource as X, WaitForRolloutOptions as Xi, RolloutTurnPart as Xn, SandboxTraceBundle as Xr, IntelligenceReport as Xt, EffectiveBackendProfile as Y, WaitForOptions as Yi, RolloutStatus as Yn, SandboxTerminals as Yr, InstalledTool as Yt, EgressDenial as Z, WorkspaceOperationLookup as Zi, SSHCommandDescriptor as Zn, SandboxTraceEvent as Zr, IntelligenceReportBudget as Zt, BranchOptions as _, TerminalStreamToken as _a, SessionMessage as _i, PreviewLinkWaitOptions as _n, SandboxFleetMachineMeteredUsage as _r, FileWriteResult as _t, AttachSandboxFleetMachineOptions as a, BatchTaskUsage as aa, SecretInfo as ai, ListSandboxOptions as an, SandboxEnvironment as ar, FileInfo as at, CodeExecutionOptions as b, SessionStatus as bi, ProcessListOptions as bn, SandboxFleetManifest as br, FleetDispatchResultBufferOptions as bt, BackendInfo as c, parseBackendType as ca, SendSessionMessageRequest as ci, MintScopedTokenOptions as cn, SandboxFleetArtifactSpec as cr, FileReadError as ct, BatchBackend as d, TerminalReadyInfo as da, SessionEventStreamOptions as di, NetworkManager as dn, SandboxFleetDispatchResponse as dr, FileSystem as dt, WriteManyOptions as ea, SandboxUser as ei, IntelligenceReportWindow as en, SandboxConnection as er, EnsureDevServerOptions as et, BatchResult as f, TerminalStream as fa, SessionFailureReason as fi, NonHostAgentDriverConfig as fn, SandboxFleetDriverCapability as fr, FileTreeFile as ft, BatchTaskResult as g, TerminalStreamOptions as ga, SessionListOptions as gi, PreviewLinkManager as gn, SandboxFleetMachine as gr, FileUsageResult as gt, BatchTask as h, TerminalStreamHandlers as ha, SessionInterruptOptions as hi, PreviewLinkInfo as hn, SandboxFleetIntelligenceEnvelope as hr, FileUsageOptions as ht, AttachGpuLeaseOptions as i, BatchSidecarGroup as ia, SearchOptions as ii, ListSandboxFleetOptions as in, SandboxDeleteOutcome as ir, ExecResult as it, CreateSandboxFleetWithCoordinatorOptions as j, SubscriptionInfo as ji, ProvisionStatus as jn, SandboxFleetWorkspaceReconcileResult as jr, ForkLookupOptions as jt, CreateSandboxFleetOptions as k, StartupOperation as ki, ProvisionEvent as kn, SandboxFleetUsage as kr, ForkCounts as kt, BackendManager as l, TERMINAL_WS_ECHO_SUBPROTOCOL as la, SentSessionMessage as li, MkdirOptions as ln, SandboxFleetCostEstimate as lr, FileReadResult as lt, BatchRunRequest as m, TerminalStreamError as ma, SessionInfo as mi, PermissionsManager as mn, SandboxFleetInfo as mr, FileTreeResult as mt, AccessPolicyRule as n, BatchEvent as na, ScopedTokenScope as ni, ListMessagesOptions as nn, SandboxCreateReceipt as nr, ExactProcessSpawnOptions as nt, BackendCapabilities as o, PublicBatchRunRequest as oa, SecretsManager as oi, MAX_EGRESS_DENIALS_LIMIT as on, SandboxEvent as or, FileReadBatchOptions as ot, BatchRunOptions as p, TerminalStreamAuthFormat as pa, SessionForkOptions as pi, PermissionLevel as pn, SandboxFleetDriverTimings as pr, FileTreeOptions as pt, DurablePlanDecisionResult as q, UploadProgress as qi, RolloutScorer as qn, SandboxTerminalManager as qr, HostAgentDriverConfig as qt, AddUserOptions as r, BatchEventDataMap as ra, SearchMatch as ri, ListOptions as rn, SandboxDeleteAcknowledgement as rr, ExecOptions as rt, BackendConfig as s, BackendType as sa, SendSessionMessageOptions as si, McpServerConfig as sn, SandboxFleetArtifact as sr, FileReadBatchResult as st, AcceleratorKind as t, BatchBackendStats as ta, ScopedToken as ti, JsonValue as tn, SandboxCreateOutcome as tr, EventStreamOptions as tt, BackendStatus as u, TerminalExitInfo as ua, SessionBackendCredentials as ui, NetworkConfig as un, SandboxFleetDispatchFailureClass as ur, FileRenameResult as ut, ChunkedUploadOptions as v, SessionMessageInputPart as vi, Process as vn, SandboxFleetMachineRecord as vr, FleetDispatchCancelResult as vt, CommitTaskSessionOptions as w, SnapshotInfo as wi, ProcessSpawnOptions as wn, SandboxFleetToken as wr, FleetExecDispatchOptions as wt, CodeExecutionResult as x, SnapshotDeleteAcknowledgement as xi, ProcessLogEntry as xn, SandboxFleetManifestMachine as xr, FleetDispatchStreamOptions as xt, ChunkedUploadResult as y, SessionResultOptions as yi, ProcessInfo as yn, SandboxFleetMachineSpec as yr, FleetDispatchResultBuffer as yt, DispatchedSession as z, TeeAttestationResponse as zi, ReconcileSandboxFleetsOptions as zn, SandboxResourceUsage as zr, GpuLease as zt };
+export { EffectiveBackend as $, WorkspaceOperationLookup as $i, RolloutStatus as $n, SandboxTerminals as $r, HostAgentRuntimeBackend as $t, CreateGpuLeaseOptions as A, StartupDiagnostics as Ai, PromptInputPart as An, SandboxFleetTraceEvent as Ar, FleetExecDispatchResult as At, DevServerInfo as B, TeeAttestationReport as Bi, PublishPublicTemplateVersionOptions as Bn, SandboxIntelligenceEnvelope as Br, GitCommit as Bt, ChunkedUploadResult as C, SnapshotDeleteAcknowledgement as Ci, ProcessInfo as Cn, SandboxFleetMachineSpec as Cr, FleetDispatchCancelResult as Ct, CodeResultPart as D, SnapshotOptions as Di, ProcessSignal as Dn, SandboxFleetPolicy as Dr, FleetDriveTurnOutcome as Dt, CodeLanguage as E, SnapshotInfo as Ei, ProcessManager as En, SandboxFleetOperationsSummary as Er, FleetDispatchStreamOptions as Et, CreateSandboxFleetWithCoordinatorOptions as F, TaskSessionCommitResult as Fi, ProvisionStatus as Fn, SandboxFleetWorkspaceReconcileResult as Fr, ForkIdempotency as Ft, DownloadProgress as G, TokenUsage as Gi, RenameOptions as Gn, SandboxRuntimeCapabilities as Gr, GpuLeaseBilling as Gt, DispatchPromptOptions as H, TeePublicKey as Hi, ReapExpiredSandboxFleetsResult as Hn, SandboxPortPreviewLink as Hr, GitDiff as Ht, CreateSandboxOptions as I, TaskSessionFileChange as Ii, ProvisionStep as In, SandboxFleetWorkspaceRestoreResult as Ir, ForkLookupOptions as It, DriverInfo as J, UploadOptions as Ji, Rollout as Jn, SandboxTerminalAttachOptions as Jr, GpuLeaseExecResult as Jt, DriveTurnOptions as K, TurnDriveResult as Ki, RestoreSnapshotOptions as Kn, SandboxRuntimeHealth as Kr, GpuLeaseCommandResult as Kt, CreateSessionOptions as L, TaskSessionInfo as Li, PublicTemplateInfo as Ln, SandboxFleetWorkspaceSnapshotResult as Lr, GPU_LEASE_PROVIDER_NAMES as Lt, CreateRequestOptions as M, StorageConfig as Mi, PromptResult as Mn, SandboxFleetTraceOptions as Mr, FleetPromptDispatchOptions as Mt, CreateSandboxFleetOptions as N, SubscriptionInfo as Ni, ProvisionEvent as Nn, SandboxFleetUsage as Nr, FleetPromptDispatchResult as Nt, CommitTaskSessionOptions as O, SnapshotResult as Oi, ProcessSpawnOptions as On, SandboxFleetToken as Or, FleetDriveTurnRequest as Ot, CreateSandboxFleetTokenOptions as P, TaskSessionChanges as Pi, ProvisionResult as Pn, SandboxFleetWorkspace as Pr, ForkCounts as Pt, DurablePlanSnapshot as Q, WaitForRolloutOptions as Qi, RolloutStartResult as Qn, SandboxTerminalRequestOptions as Qr, HostAgentDriverConfig as Qt, CreateTaskSessionOptions as R, TaskSessionProfile as Ri, PublicTemplateVersionInfo as Rn, SandboxIdentity as Rr, GitAuth as Rt, ChunkedUploadOptions as S, SessionStatus as Si, Process as Sn, SandboxFleetMachineRecord as Sr, FileWriteResult as St, CodeExecutionResult as T, SnapshotIdempotency as Ti, ProcessLogEntry as Tn, SandboxFleetManifestMachine as Tr, FleetDispatchResultBufferOptions as Tt, DispatchedSession as U, TeePublicKeyResponse as Ui, ReconcileSandboxFleetsOptions as Un, SandboxResourceUsage as Ur, GitStatus as Ut, DirectoryPermission as V, TeeAttestationResponse as Vi, ReapExpiredSandboxFleetsOptions as Vn, SandboxPortBinding as Vr, GitConfig as Vt, DownloadOptions as W, TokenRefreshHandler as Wi, ReconcileSandboxFleetsResult as Wn, SandboxResources as Wr, GpuLease as Wt, DurablePlan as X, UsageInfo as Xi, RolloutOptions as Xn, SandboxTerminalInfo as Xr, GpuLeaseProviderName as Xt, DriverType as Y, UploadProgress as Yi, RolloutChildResult as Yn, SandboxTerminalCreateOptions as Yr, GpuLeaseManager as Yt, DurablePlanDecisionResult as Z, WaitForOptions as Zi, RolloutScorer as Zn, SandboxTerminalManager as Zr, GpuLeaseStatus as Zt, BatchRunOptions as _, SessionInterruptOptions as _i, PermissionLevel as _n, SandboxFleetDriverTimings as _r, FileTreeFile as _t, AgentQuestionRequest as a, BatchEventDataMap as aa, SearchMatch as ai, IntelligenceReportWindow as an, SandboxCreateOutcome as ar, EnsureDevServerOptions as at, BatchTaskResult as b, SessionMessageInputPart as bi, PreviewLinkManager as bn, SandboxFleetMachine as br, FileUsageOptions as bt, AttachGpuLeaseOptions as c, PublicBatchRunRequest as ca, SecretsManager as ci, ListOptions as cn, SandboxDeleteOutcome as cr, ExecOptions as ct, BackendConfig as d, SentSessionMessage as di, MAX_EGRESS_DENIALS_LIMIT as dn, SandboxFleetArtifact as dr, FileReadBatchOptions as dt, WriteFileOptions as ea, SandboxTraceBundle as ei, InstalledTool as en, RolloutTurnPart as er, EffectiveBackendProfile as et, BackendInfo as f, SessionBackendCredentials as fi, McpServerConfig as fn, SandboxFleetArtifactSpec as fr, FileReadBatchResult as ft, BatchResult as g, SessionInfo as gi, NonHostAgentDriverConfig as gn, SandboxFleetDriverCapability as gr, FileSystem as gt, BatchBackend as h, SessionForkOptions as hi, NetworkManager as hn, SandboxFleetDispatchResponse as hr, FileRenameResult as ht, AgentApprovalRequirement as i, BatchEvent as ia, SandboxUser as ii, IntelligenceReportSubjectType as in, SandboxConnection as ir, EgressPolicy as it, CreateIntelligenceReportOptions as j, StartupOperation as ji, PromptOptions as jn, SandboxFleetTraceExport as jr, FleetMachineId as jt, CompletedTurnResult as k, SshKeysManager as ki, ProcessStatus as kn, SandboxFleetTraceBundle as kr, FleetExecDispatchOptions as kt, AttachSandboxFleetMachineOptions as l, BackendType as la, SendSessionMessageOptions as li, ListSandboxFleetOptions as ln, SandboxEnvironment as lr, ExecResult as lt, BackendStatus as m, SessionFailureReason as mi, NetworkConfig as mn, SandboxFleetDispatchFailureClass as mr, FileReadResult as mt, AccessPolicyRule as n, WriteManyOptions as na, SandboxTraceExport as ni, IntelligenceReportBudget as nn, SSHCredentials as nr, EgressDenial as nt, AgentRunStatus as o, BatchSidecarGroup as oa, SearchOptions as oi, JsonValue as on, SandboxCreateReceipt as or, EventStreamOptions as ot, BackendManager as p, SessionEventStreamOptions as pi, MkdirOptions as pn, SandboxFleetCostEstimate as pr, FileReadError as pt, DriverConfig as q, UpdateUserOptions as qi, ResumeOptions as qn, SandboxStatus as qr, GpuLeaseExecOptions as qt, AddUserOptions as r, BatchBackendStats as ra, SandboxTraceOptions as ri, IntelligenceReportCompareTo as rn, SandboxConfig as rr, EgressManager as rt, AgentToolInvocation as s, BatchTaskUsage as sa, SecretInfo as si, ListMessagesOptions as sn, SandboxDeleteAcknowledgement as sr, ExactProcessSpawnOptions as st, AcceleratorKind as t, WriteManyFile as ta, SandboxTraceEvent as ti, IntelligenceReport as tn, SSHCommandDescriptor as tr, EffectiveBackendSource as tt, BackendCapabilities as u, parseBackendType as ua, SendSessionMessageRequest as ui, ListSandboxOptions as un, SandboxEvent as ur, FileInfo as ut, BatchRunRequest as v, SessionListOptions as vi, PermissionsManager as vn, SandboxFleetInfo as vr, FileTreeOptions as vt, CodeExecutionOptions as w, SnapshotDeleteOutcome as wi, ProcessListOptions as wn, SandboxFleetManifest as wr, FleetDispatchResultBuffer as wt, BranchOptions as x, SessionResultOptions as xi, PreviewLinkWaitOptions as xn, SandboxFleetMachineMeteredUsage as xr, FileUsageResult as xt, BatchTask as y, SessionMessage as yi, PreviewLinkInfo as yn, SandboxFleetIntelligenceEnvelope as yr, FileTreeResult as yt, DeleteOptions as z, TeeAttestationOptions as zi, PublishPublicTemplateOptions as zn, SandboxInfo as zr, GitBranch as zt };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/sandbox",
-  "version": "0.30.1",
+  "version": "0.30.2-develop.20260820122029.869ebfa",
   "description": "Client SDK for the Tangle Sandbox platform - build AI agent applications with dev containers",
   "type": "module",
   "sideEffects": [
@@ -24,6 +24,11 @@
       "types": "./dist/runtime.d.ts",
       "default": "./dist/runtime.js"
     },
+    "./interactive-control": {
+      "import": "./dist/interactive-control.js",
+      "types": "./dist/interactive-control.d.ts",
+      "default": "./dist/interactive-control.js"
+    },
     "./tangle": {
       "import": "./dist/tangle/index.js",
       "types": "./dist/tangle/index.d.ts",
@@ -91,7 +96,7 @@
   },
   "dependencies": {
     "@tangle-network/agent-core": "0.9.4",
-    "@tangle-network/agent-interface": "^1.0.0",
+    "@tangle-network/agent-interface": "^1.3.0",
     "zod": "4.4.3"
   },
   "peerDependencies": {
@@ -132,8 +137,8 @@
     "yjs": "13.6.30",
     "@repo/shared": "0.0.0",
     "@tangle-network/cli-agent-registry": "0.3.10",
-    "@tangle-network/sse-core": "0.0.0",
-    "@tangle-network/runtime-contracts": "0.6.1"
+    "@tangle-network/runtime-contracts": "0.6.1",
+    "@tangle-network/sse-core": "0.0.0"
   },
   "scripts": {
     "build": "node scripts/build-dist.mjs",