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

package/dist/{sandbox-B49ZGQv7.d.ts → sandbox-Cr-4qzaA.d.ts}

@@ -1,5 +1,7 @@
-import { $i as WriteManyFile, $r as SandboxTraceOptions, An as ProvisionResult, At as ForkIdempotency, Dn as PromptOptions, Ei as SnapshotResult, En as PromptInputPart, Fi as TaskSessionInfo, Fr as SandboxInfo, Ft as GitCommit, H as DriveTurnOptions, Hn as RestoreSnapshotOptions, Hr as SandboxRuntimeHealth, Jn as RolloutStartResult, K as DurablePlan, Kn as RolloutOptions, Li as TeeAttestationOptions, Lr as SandboxPortBinding, Lt as GitDiff, Mi as TaskSessionChanges, N as CreateSessionOptions, Ni as TaskSessionCommitResult, Oi as StartupDiagnostics, On as PromptResult, P as CreateTaskSessionOptions, Pt as GitBranch, Q as EgressManager, Qi as WriteFileOptions, Qn as SSHCredentials, Qt as IntelligenceReportCompareTo, R as DispatchPromptOptions, Rt as GitStatus, S as CodeLanguage, Sn as ProcessManager, T as CompletedTurnResult, Ti as SnapshotOptions, Tr as SandboxFleetTraceBundle, Un as ResumeOptions, Ur as SandboxStatus, Vi as TeePublicKeyResponse, Vr as SandboxRuntimeCapabilities, W as DriverInfo, Wi as TurnDriveResult, Wn as Rollout, Wr as SandboxTerminalAttachOptions, Wt as GpuLeaseManager, Xi as WaitForRolloutOptions, Xr as SandboxTraceBundle, Xt as IntelligenceReport, Yi as WaitForOptions, Yr as SandboxTerminals, Yt as InstalledTool, Zi as WorkspaceOperationLookup, Zn as SSHCommandDescriptor, Zt as IntelligenceReportBudget, _ as BranchOptions, _i as SessionMessage, _t as FileWriteResult, b as CodeExecutionOptions, ci as SendSessionMessageRequest, cn as MintScopedTokenOptions, di as SessionEventStreamOptions, dn as NetworkManager, dt as FileSystem, ea as WriteManyOptions, en as IntelligenceReportWindow, er as SandboxConnection, fa as TerminalStream, gi as SessionListOptions, gn as PreviewLinkManager, ha as TerminalStreamHandlers, hi as SessionInterruptOptions, ii as SearchOptions, it as ExecResult, jt as ForkLookupOptions, kn as ProvisionEvent, kt as ForkCounts, l as BackendManager, li as SentSessionMessage, mi as SessionInfo, mn as PermissionsManager, nn as ListMessagesOptions, nr as SandboxCreateReceipt, or as SandboxEvent, pi as SessionForkOptions, q as DurablePlanDecisionResult, ri as SearchMatch, rr as SandboxDeleteAcknowledgement, rt as ExecOptions, s as BackendConfig, sa as BackendType, si as SendSessionMessageOptions, ti as ScopedToken, tn as JsonValue, tt as EventStreamOptions, w as CommitTaskSessionOptions, wi as SnapshotInfo, x as CodeExecutionResult, xi as SnapshotDeleteAcknowledgement, yi as SessionResultOptions, z as DispatchedSession, zi as TeeAttestationResponse, zr as SandboxResourceUsage, zt as GpuLease } from "./types-Qn3x7R8O.js";
-import { AgentProfile, AgentRunCancellationAcknowledgement, AgentRunCancellationRequest, InteractionAcknowledgement, InteractionData, InteractionRequest, InteractionResponseCommand } from "@tangle-network/agent-interface";
+import { a as TerminalStreamReconnectAuthority, c as MintScopedTokenOptions, l as ScopedToken, t as TerminalStream } from "./terminal-stream-4KNJ6SmL.js";
+import { a as InteractiveSessionControlController, c as InteractiveSessionIdentity, d as InteractiveAttachOptions, f as InteractiveControlClaimAcknowledgement, h as InteractiveSessionStatus, m as InteractiveRequestOptions, n as BrowserInteractiveSessionControlControllerOptions, o as InteractiveSessionControlControllerOptions, p as InteractiveControlClaimOptions, s as InteractiveSessionControlTransport } from "./browser-interactive-control-controller-B476gcui.js";
+import { $i as WorkspaceOperationLookup, $r as SandboxTerminals, Ai as StartupDiagnostics, An as PromptInputPart, Bt as GitCommit, Ci as SnapshotDeleteAcknowledgement, Di as SnapshotOptions, E as CodeLanguage, Ei as SnapshotInfo, En as ProcessManager, Fi as TaskSessionCommitResult, Ft as ForkIdempotency, Gr as SandboxRuntimeCapabilities, H as DispatchPromptOptions, Ht as GitDiff, It as ForkLookupOptions, J as DriverInfo, Jn as Rollout, Jr as SandboxTerminalAttachOptions, K as DriveTurnOptions, Ki as TurnDriveResult, Kn as RestoreSnapshotOptions, Kr as SandboxRuntimeHealth, L as CreateSessionOptions, Li as TaskSessionInfo, Mn as PromptResult, Nn as ProvisionEvent, O as CommitTaskSessionOptions, Oi as SnapshotResult, Pi as TaskSessionChanges, Pn as ProvisionResult, Pt as ForkCounts, Qi as WaitForRolloutOptions, Qn as RolloutStartResult, R as CreateTaskSessionOptions, St as FileWriteResult, T as CodeExecutionResult, U as DispatchedSession, Ui as TeePublicKeyResponse, Ur as SandboxResourceUsage, Ut as GitStatus, Vi as TeeAttestationResponse, Vr as SandboxPortBinding, Wt as GpuLease, X as DurablePlan, Xn as RolloutOptions, Yt as GpuLeaseManager, Z as DurablePlanDecisionResult, Zi as WaitForOptions, _i as SessionInterruptOptions, ai as SearchMatch, an as IntelligenceReportWindow, bn as PreviewLinkManager, ct as ExecOptions, d as BackendConfig, di as SentSessionMessage, ea as WriteFileOptions, ei as SandboxTraceBundle, en as InstalledTool, gi as SessionInfo, gt as FileSystem, hi as SessionForkOptions, hn as NetworkManager, ir as SandboxConnection, jn as PromptOptions, k as CompletedTurnResult, kr as SandboxFleetTraceBundle, li as SendSessionMessageOptions, lt as ExecResult, na as WriteManyOptions, nn as IntelligenceReportBudget, nr as SSHCredentials, oi as SearchOptions, on as JsonValue, or as SandboxCreateReceipt, ot as EventStreamOptions, p as BackendManager, pi as SessionEventStreamOptions, qn as ResumeOptions, qr as SandboxStatus, ri as SandboxTraceOptions, rn as IntelligenceReportCompareTo, rt as EgressManager, sn as ListMessagesOptions, sr as SandboxDeleteAcknowledgement, ta as WriteManyFile, tn as IntelligenceReport, tr as SSHCommandDescriptor, ui as SendSessionMessageRequest, ur as SandboxEvent, vi as SessionListOptions, vn as PermissionsManager, w as CodeExecutionOptions, x as BranchOptions, xi as SessionResultOptions, yi as SessionMessage, zi as TeeAttestationOptions, zr as SandboxInfo, zt as GitBranch } from "./types-BwYLVqxX.js";
+import { AgentInteractiveSessionControlClaim, AgentInteractiveSessionControlClaimAcknowledgement, AgentInteractiveSessionControlClaimRequest, AgentInteractiveSessionPromptAcknowledgement, AgentInteractiveSessionPromptCommand, AgentInteractiveSessionRef, AgentInteractiveSessionStart, AgentInteractiveSessionStopAcknowledgement, AgentInteractiveSessionStopCommand, AgentRunCancellationAcknowledgement, AgentRunCancellationRequest, InteractionAcknowledgement, InteractionData, InteractionRequest, InteractionResponseCommand, agentInteractiveSessionPromptRequestDigest } from "@tangle-network/agent-interface";
 import { z } from "zod";
 
 //#region src/mcp.d.ts
@@ -113,12 +115,9 @@ declare function buildControlPlaneMcpConfig(options: BuildControlPlaneMcpConfigO
   config: SandboxMcpConfig;
 };
 //#endregion
-//#region src/interaction-response.d.ts
-declare const REFUSED_INTERACTION_STATUS: z.ZodEnum<{
-  already_resolved_different: "already_resolved_different";
-  binding_mismatch: "binding_mismatch";
-}>;
-declare const InteractionResolutionSchema: z.ZodObject<{
+//#region ../../../packages/runtime-contracts/dist/interaction-response.d.ts
+/** Canonical result returned after a response is recorded by Sidecar. */
+declare const interactionResolutionAcknowledgementSchema: z.ZodObject<{
   status: z.ZodEnum<{
     accepted: "accepted";
     already_resolved_same: "already_resolved_same";
@@ -132,6 +131,14 @@ declare const InteractionResolutionSchema: z.ZodObject<{
     declined: "declined";
     cancelled: "cancelled";
   }>;
+  deliveryState: z.ZodEnum<{
+    pending: "pending";
+    delivering: "delivering";
+    delivered: "delivered";
+    delivery_failed: "delivery_failed";
+    backend_lost: "backend_lost";
+    effect_unknown: "effect_unknown";
+  }>;
   delivered: z.ZodBoolean;
   resolvedAt: z.ZodString;
   binding: z.ZodOptional<z.ZodObject<{
@@ -144,7 +151,14 @@ declare const InteractionResolutionSchema: z.ZodObject<{
     interactionId: z.ZodString;
   }, z.core.$strict>>;
 }, z.core.$strict>;
-type SandboxInteractionResolution = z.infer<typeof InteractionResolutionSchema>;
+type InteractionResolutionAcknowledgement = z.infer<typeof interactionResolutionAcknowledgementSchema>;
+//#endregion
+//#region src/interaction-response.d.ts
+declare const REFUSED_INTERACTION_STATUS: z.ZodEnum<{
+  already_resolved_different: "already_resolved_different";
+  binding_mismatch: "binding_mismatch";
+}>;
+type SandboxInteractionResolution = InteractionResolutionAcknowledgement;
 type SandboxInteractionConflict = {
   status: z.infer<typeof REFUSED_INTERACTION_STATUS>;
   message: string;
@@ -159,177 +173,121 @@ interface SandboxInteractionCommandResult {
   serverResult?: SandboxInteractionResult;
 }
 //#endregion
-//#region src/interactive.d.ts
-/** CLI auth file materialized into the harness's auth home before launch. */
-interface InteractiveAuthFile {
-  path: string;
-  content: string;
-  mode?: number;
+//#region src/interactive-controller.d.ts
+/** The request fields supplied by an attach caller before control is claimed. */
+type InteractiveAttachRequest = Omit<InteractiveAttachOptions, "control">;
+/** Transport used by the status → claim → WebSocket controller. */
+interface InteractiveSessionControllerTransport extends InteractiveSessionControlTransport {
+  attach(sessionId: string, ref: AgentInteractiveSessionRef, request: InteractiveAttachOptions, options?: InteractiveRequestOptions, reconnectAuthority?: TerminalStreamReconnectAuthority): Promise<TerminalStream>;
 }
-interface StartInteractiveOptions {
-  /**
-   * Harness with a native interactive TUI (bare binary launches it): e.g.
-   * "claude-code", "codex", "opencode", "kimi-code", "factory-droids",
-   * "pi", "amp", "hermes". The sidecar's runner registry is the authority
-   * and rejects values without a TUI entrypoint.
-   */
-  harness: BackendType;
-  model?: string;
-  apiKey?: string;
-  authMode?: string;
-  baseUrl?: string;
-  /** Working directory; defaults to the sandbox workspace root. */
-  cwd?: string;
-  cols?: number;
-  rows?: number;
-  authFiles?: InteractiveAuthFile[];
-  /**
-   * Canonical agent profile (persona, skills, tool policy, MCP). When set, the
-   * sidecar materializes it into `cwd` before spawning the TUI, so the
-   * interactive session runs AS the configured agent rather than a bare harness.
-   * Omit to launch the harness's default TUI.
-   */
-  profile?: AgentProfile;
-  /**
-   * Opening message the TUI submits on its own once ready (via the harness's
-   * prompt launch arg). Use this to start the agent working immediately instead
-   * of writing keystrokes after start — a TUI drops input sent before it is
-   * ready to read. Omit for a session that opens idle.
-   */
-  initialPrompt?: string;
-}
-interface InteractiveSessionInfo {
-  sessionId: string;
-  harness: BackendType;
-  /** ISO timestamp of when the harness process was spawned. */
-  startedAt: string;
+interface InteractiveSessionControllerOptions extends InteractiveSessionControlControllerOptions {}
+/**
+ * Attach-capable controller for one exact interactive process.
+ *
+ * Control ownership lives in the dependency-light base controller. This layer
+ * adds only the terminal attach operation after that ownership is resolved.
+ */
+declare class InteractiveSessionController extends InteractiveSessionControlController {
+  private readonly attachTransport;
+  private attachInFlight?;
+  constructor(attachTransport: InteractiveSessionControllerTransport, options: InteractiveSessionControllerOptions);
+  attach(request: InteractiveAttachRequest, requestOptions?: InteractiveRequestOptions): Promise<TerminalStream>;
   /**
-   * Sandbox-relative WebSocket path that streams the live framebuffer and
-   * accepts keystrokes (the mTLS- + capability-gated terminal socket).
+   * Open a stream for a claim returned by this controller's `resolve()`.
+   * The controller releases that claim when the stream cannot be opened.
    */
-  streamUrl: string;
+  attachWithIdentity(identity: InteractiveSessionIdentity, request: InteractiveAttachRequest, requestOptions?: InteractiveRequestOptions): Promise<TerminalStream>;
 }
-/**
- * Snapshot of an interactive session's lifecycle: still running, or exited
- * with its exit code (served from the sidecar's bounded exit tombstone).
- * `status()` returns `null` when the sidecar no longer knows the id — never
- * started, tombstone evicted, or superseded by a restart under the same id.
- */
-type InteractiveSessionStatus = {
+/** Browser transport options for the attach-capable controller. */
+interface BrowserInteractiveSessionControllerOptions extends InteractiveSessionControllerOptions, BrowserInteractiveSessionControlControllerOptions {
+  /** Mint a future session-runtime token for every browser terminal dial. */
+  terminalTokenProvider?: (signal?: AbortSignal) => Promise<ScopedToken>;
+}
+/** Concrete controller for browser deep links and terminal attachment. */
+declare class BrowserInteractiveSessionController extends InteractiveSessionController {
+  constructor(options: BrowserInteractiveSessionControllerOptions);
+}
+//#endregion
+//#region src/interactive.d.ts
+/** Exact start request sent to the Sandbox runtime. */
+type InteractiveSessionStartOptions = AgentInteractiveSessionStart;
+/** Exact identity of one admitted interactive process. */
+type InteractiveSessionRef = AgentInteractiveSessionRef;
+/** Incarnation identifier carried by an exact interactive reference. */
+type InteractiveSessionIncarnationId = AgentInteractiveSessionRef["incarnationId"];
+/** Write authority for one exact interactive process. */
+type InteractiveSessionControlClaim = AgentInteractiveSessionControlClaim;
+/** Published Interface prompt command. */
+type InteractivePromptCommand = AgentInteractiveSessionPromptCommand;
+/** Published Interface stop command. */
+type InteractiveStopCommand = AgentInteractiveSessionStopCommand;
+/** Published Interface control-claim request. */
+type InteractiveControlClaimRequest = AgentInteractiveSessionControlClaimRequest;
+interface InteractiveSessionInfo {
   state: "running";
-  sessionId: string;
-  harness: BackendType;
-  startedAt: string;
+  ref: AgentInteractiveSessionRef;
+  control: AgentInteractiveSessionControlClaim;
   streamUrl: string;
-} | {
+}
+interface InteractiveSessionExitInfo {
   state: "exited";
-  sessionId: string;
-  harness: BackendType;
-  startedAt: string;
+  ref: AgentInteractiveSessionRef;
+  control: AgentInteractiveSessionControlClaim;
   endedAt: string;
   exitCode?: number;
   exitSignal?: string;
-  /**
-   * "exited" = the process ended on its own; "stopped" = explicit stop();
-   * "lost" = the session was interrupted by a sidecar restart mid-run (its
-   * PTY died with the process) and re-hydrated as a durable tombstone rather
-   * than reported as a 404/null. A "lost" session is a failed run.
-   */
   reason: "exited" | "stopped" | "lost";
-};
-/** Options for `InteractiveSessionHandle.attach()`. */
-interface InteractiveAttachOptions {
-  /** Initial PTY geometry reported in the attach init frame. */
-  cols?: number;
-  rows?: number;
-  /**
-   * Stream callbacks, bound before the socket opens. Register `onData` here:
-   * the server replays the session's buffered screen immediately after the
-   * attach acknowledgement, so a handler added after `attach()` resolves
-   * would miss the replayed frames.
-   */
-  handlers?: TerminalStreamHandlers;
+}
+type InteractiveSessionStartResult = InteractiveSessionInfo | InteractiveSessionExitInfo;
+/** Identity required to reconstruct a handle after a process boundary. */
+interface InteractiveSessionHandleOptions {
+  ref?: AgentInteractiveSessionRef;
+  control?: AgentInteractiveSessionControlClaim;
 }
 /** Decision passed to `respondToPermission`. */
 interface RespondToPermissionOptions {
-  /** The human's decision for the awaiting permission interaction. */
   response: "allow" | "deny";
   signal?: AbortSignal;
 }
 /** Result of `interrupt`. */
 interface InterruptResult {
-  /**
-   * True iff an execution was actively running and the abort signal reached
-   * it. `false` means there was nothing in flight to cancel — surfaced
-   * explicitly rather than as a silent success so callers can distinguish a
-   * real interruption from a no-op.
-   */
   cancelled: boolean;
 }
-/**
- * Host hooks the SDK box implements to drive interactive sessions. Kept
- * separate from the prompt/session-event host so the interactive surface is an
- * explicit, independently-mockable contract.
- */
+/** Host hooks implemented by the Sandbox client. */
 interface InteractiveSessionHost {
-  _startInteractive(id: string, options: StartInteractiveOptions): Promise<InteractiveSessionInfo>;
-  _sendInteractivePrompt(id: string, prompt: string): Promise<void>;
-  _stopInteractive(id: string): Promise<void>;
-  /**
-   * Optional so adding it does not break existing implementers of this exported
-   * interface (a required addition is a breaking change; this is additive). A
-   * host that omits it makes `InteractiveSessionHandle.status()` reject with a
-   * clear "not supported" error instead of failing to compile downstream.
-   */
-  _interactiveStatus?(id: string): Promise<InteractiveSessionStatus | null>;
-  /**
-   * Optional for the same additive-change reason as `_interactiveStatus`. A
-   * host that omits it makes `InteractiveSessionHandle.attach()` reject with
-   * a clear "not supported" error.
-   */
-  _attachInteractive?(id: string, options?: InteractiveAttachOptions): Promise<TerminalStream>;
+  _startInteractive(id: string, options: InteractiveSessionStartOptions, requestOptions?: InteractiveRequestOptions): Promise<InteractiveSessionStartResult>;
+  _sendInteractivePrompt(id: string, command: InteractivePromptCommand, options?: InteractiveRequestOptions): Promise<AgentInteractiveSessionPromptAcknowledgement>;
+  _stopInteractive(id: string, command: InteractiveStopCommand, options?: InteractiveRequestOptions): Promise<AgentInteractiveSessionStopAcknowledgement>;
+  _stopInteractiveLifecycle(id: string, ref: AgentInteractiveSessionRef, options?: InteractiveRequestOptions): Promise<AgentInteractiveSessionStopAcknowledgement>;
+  _claimInteractiveControl(id: string, request: InteractiveControlClaimRequest, options?: InteractiveControlClaimOptions): Promise<InteractiveControlClaimAcknowledgement>;
+  _releaseInteractiveControl(id: string, ref: AgentInteractiveSessionRef, control: AgentInteractiveSessionControlClaim, options?: InteractiveRequestOptions): Promise<void>;
+  _interactiveStatus(id: string, incarnationId: string, options?: InteractiveRequestOptions): Promise<InteractiveSessionStatus | null>;
+  _attachInteractive(id: string, ref: AgentInteractiveSessionRef, request: InteractiveAttachOptions, options?: InteractiveRequestOptions, reconnectAuthority?: TerminalStreamReconnectAuthority): Promise<TerminalStream>;
 }
 /**
- * Handle for one session's interactive harness. Obtained via
- * `box.session(id).interactive()`; does not hit the network until a method is
- * called.
+ * Handle for one exact interactive harness session.
+ *
+ * `start()` binds the returned ref and control for prompt and stop commands.
+ * Attach always observes and claims a fresh control before opening its stream.
  */
 declare class InteractiveSessionHandle {
   private readonly host;
   private readonly sessionId;
-  constructor(host: InteractiveSessionHost, sessionId: string);
-  /**
-   * Spawn the harness's interactive TUI for this session. Returns the
-   * `streamUrl` of the live framebuffer — open it programmatically with
-   * `attach()`, or hand it to a terminal frontend. Throws if the harness has
-   * no interactive entrypoint (e.g. cursor, which is SDK-only), the binary is
-   * not installed, or a session is already running for this id.
-   */
-  start(options: StartInteractiveOptions): Promise<InteractiveSessionInfo>;
-  /** Inject a prompt as keystrokes into the live harness (submitted on send). */
-  sendPrompt(prompt: string): Promise<void>;
-  /**
-   * Attach to the live harness PTY as a {@link TerminalStream}: the same PTY
-   * the interactive TUI runs in (the sidecar keys it by this session id), so
-   * the stream sees the harness's screen and its keystrokes drive the
-   * harness — never a fresh shell. The host mints a short-lived scoped
-   * terminal token and dials the session's `streamUrl` through the secured
-   * sidecar proxy; resolves once the server acknowledges the attach (the
-   * buffered screen then replays through `handlers.onData`).
-   *
-   * Throws when no interactive session is running for this id — attach after
-   * `start()`, or to a session another caller started.
-   */
-  attach(options?: InteractiveAttachOptions): Promise<TerminalStream>;
-  /**
-   * Observe the session: running, exited (with its exit code), or `null`
-   * when the sidecar no longer knows the id. Poll this to detect completion —
-   * an interactive session has no structured result stream, so the exit
-   * tombstone is the completion signal.
-   */
-  status(): Promise<InteractiveSessionStatus | null>;
-  /** Stop the interactive harness and reap its PTY. */
-  stop(): Promise<void>;
+  private ref?;
+  private control?;
+  private readonly attachHolderId;
+  private attachController?;
+  private attachInFlight?;
+  constructor(host: InteractiveSessionHost, sessionId: string, options?: InteractiveSessionHandleOptions);
+  start(options: InteractiveSessionStartOptions, requestOptions?: InteractiveRequestOptions): Promise<InteractiveSessionStartResult>;
+  private requireBinding;
+  private requireRef;
+  sendPrompt(command: InteractivePromptCommand, options?: InteractiveRequestOptions): Promise<AgentInteractiveSessionPromptAcknowledgement>;
+  attach(request?: InteractiveAttachRequest, options?: InteractiveRequestOptions): Promise<TerminalStream>;
+  status(options?: InteractiveRequestOptions): Promise<InteractiveSessionStatus | null>;
+  claimControl(request: InteractiveControlClaimRequest, options?: InteractiveControlClaimOptions): Promise<InteractiveControlClaimAcknowledgement>;
+  stop(command: InteractiveStopCommand, options?: InteractiveRequestOptions): Promise<AgentInteractiveSessionStopAcknowledgement>;
+  stopLifecycle(options?: InteractiveRequestOptions): Promise<AgentInteractiveSessionStopAcknowledgement>;
 }
 //#endregion
 //#region src/session.d.ts
@@ -447,7 +405,7 @@ declare class SandboxSession {
    * from the headless `prompt()`/`events()` surface above. Lazy — does not hit
    * the network until a handle method is called.
    */
-  interactive(): InteractiveSessionHandle;
+  interactive(options?: InteractiveSessionHandleOptions): InteractiveSessionHandle;
   /**
    * Resolve a pending permission interaction the agent raised mid-turn,
    * forwarding `allow`/`deny` to the blocked agent through the unified
@@ -681,6 +639,10 @@ declare class SandboxInstance {
   private readonly defaultRuntimeBackend?;
   private readonly runtime;
   private readonly workspaceImages;
+  private readonly interactiveOperations;
+  private readonly interactiveTerminalOperations;
+  /** @internal Test seam for terminal attach unit tests. */
+  private _terminalStreamConnect;
   /**
    * A profile the runtime has cached (create-time priming), letting turns
    * send `backend.profileSha256` instead of re-shipping the profile's static
@@ -814,7 +776,7 @@ declare class SandboxInstance {
   /**
    * Refresh sandbox information from the server.
    */
-  refresh(): Promise<void>;
+  refresh(signal?: AbortSignal): Promise<void>;
   private refreshInfo;
   /**
    * Fetch fresh TEE attestation evidence for this sandbox.
@@ -969,15 +931,13 @@ declare class SandboxInstance {
    * Stream events from an agent prompt.
    * Use this for real-time updates during agent execution.
    *
-   * Guarantees a terminal event on every non-cancelled path: a clean run
-   * ends with the runtime's `result`/`done`; a failure (pre-stream HTTP
-   * error, mid-stream network drop, timeout, or reconnect exhaustion) is
-   * surfaced as an in-band `error` event followed by a synthetic `done`,
-   * never a thrown generator. Caller-initiated cancellation (aborting
-   * `options.signal`) ends the stream silently with no synthetic terminal.
+   * Guarantees terminal completion on every non-cancelled path. A clean run
+   * emits a `result` summary and ends with `done`. A failure is an in-band
+   * `error` followed by `done`, never a thrown generator. Caller cancellation
+   * ends the stream silently with no synthetic terminal.
    *
    * Automatically reconnects via the runtime event replay endpoint if the
-   * SSE stream drops before a terminal event (`result` or `done`) is
+   * SSE stream drops before a terminal event (`done` or `error`) is
    * received. Reconnection is transparent — replayed events that were
    * already yielded (based on event ID tracking) are deduplicated.
    */
@@ -1900,39 +1860,24 @@ declare class SandboxInstance {
   private _executionEvents;
   /** @internal — invoked by SandboxSession.result(). */
   _sessionResult(id: string, options?: SessionResultOptions, knownSession?: SessionInfo): Promise<PromptResult>;
-  /** @internal — invoked by InteractiveSessionHandle.start(). */
-  _startInteractive(id: string, options: StartInteractiveOptions): Promise<InteractiveSessionInfo>;
-  /** @internal — invoked by InteractiveSessionHandle.sendPrompt(). */
-  _sendInteractivePrompt(id: string, prompt: string): Promise<void>;
-  /** @internal — invoked by InteractiveSessionHandle.status(). */
-  _interactiveStatus(id: string): Promise<InteractiveSessionStatus | null>;
-  /**
-   * @internal Test seam: unit tests replace this to intercept terminal
-   * WebSocket dials without opening a real socket. Production paths always
-   * go through `TerminalStream.connect`.
-   */
-  private _terminalStreamConnect;
-  /**
-   * Resolve a sandbox-relative terminal stream path against the browser-safe
-   * sidecar proxy base returned by the scoped-token mint. Concatenation, not
-   * URL resolution: the proxy base carries a path prefix
-   * (`/v1/sidecar-proxy/{id}`) that `new URL(absolutePath, base)` would drop.
-   */
-  private resolveTerminalStreamUrl;
-  /** @internal — invoked by InteractiveSessionHandle.attach(). */
-  _attachInteractive(id: string, options?: InteractiveAttachOptions): Promise<TerminalStream>;
-  /**
-   * Per-dial credential for a terminal attach. The first dial consumes the
-   * token minted alongside the proxy URL (no second mint); every later dial
-   * (a `reconnect()` after the socket dropped or the detach window) re-mints,
-   * because scoped terminal tokens are clamped to a <= 15-minute TTL and the
-   * original is likely dead by then.
-   */
-  private terminalTokenProvider;
-  /** @internal — invoked by `box.terminals.attach()`. */
+  /** @internal — delegated to the native interactive operations module. */
+  _startInteractive(id: string, options: InteractiveSessionStartOptions, requestOptions?: InteractiveRequestOptions): Promise<InteractiveSessionStartResult>;
+  /** @internal — delegated to the native interactive operations module. */
+  _sendInteractivePrompt(id: string, command: InteractivePromptCommand, options?: InteractiveRequestOptions): Promise<AgentInteractiveSessionPromptAcknowledgement>;
+  /** @internal — delegated to the native interactive operations module. */
+  _claimInteractiveControl(id: string, request: AgentInteractiveSessionControlClaimRequest, options?: InteractiveControlClaimOptions): Promise<AgentInteractiveSessionControlClaimAcknowledgement>;
+  /** @internal — delegated to the native interactive operations module. */
+  _releaseInteractiveControl(id: string, ref: AgentInteractiveSessionRef, control: AgentInteractiveSessionControlClaim, options?: InteractiveRequestOptions): Promise<void>;
+  /** @internal — delegated to the native interactive operations module. */
+  _interactiveStatus(id: string, incarnationId: string, options?: InteractiveRequestOptions): Promise<InteractiveSessionStatus | null>;
+  /** @internal — delegated to the native interactive operations module. */
+  _attachInteractive(id: string, ref: AgentInteractiveSessionRef, request: InteractiveAttachOptions, options?: InteractiveRequestOptions, reconnectAuthority?: TerminalStreamReconnectAuthority): Promise<TerminalStream>;
+  /** @internal — delegated to the native interactive operations module. */
   _attachTerminal(connectionId: string, options?: SandboxTerminalAttachOptions): Promise<TerminalStream>;
-  /** @internal — invoked by InteractiveSessionHandle.stop(). */
-  _stopInteractive(id: string): Promise<void>;
+  /** @internal — delegated to the native interactive operations module. */
+  _stopInteractive(id: string, command: InteractiveStopCommand, options?: InteractiveRequestOptions): Promise<AgentInteractiveSessionStopAcknowledgement>;
+  /** @internal — delegated to the native interactive operations module. */
+  _stopInteractiveLifecycle(id: string, ref: AgentInteractiveSessionRef, options?: InteractiveRequestOptions): Promise<AgentInteractiveSessionStopAcknowledgement>;
   private interactionTransport;
   /** @internal — invoked by SandboxSession.interactions(). */
   _listInteractions(id: string, options?: {
@@ -1965,4 +1910,4 @@ declare class SandboxInstance {
   }): Promise<DurablePlanDecisionResult>;
 }
 //#endregion
-export { BuildControlPlaneMcpConfigOptions as A, InterruptResult as C, SandboxInteractionConflict as D, SandboxInteractionCommandResult as E, SandboxMcpEndpoint as F, SandboxMcpServerEntry as I, buildControlPlaneMcpConfig as L, CONTROL_PLANE_MCP_SERVER_NAME as M, SANDBOX_MCP_SERVER_NAME as N, SandboxInteractionResolution as O, SandboxMcpConfig as P, buildSandboxMcpConfig as R, InteractiveSessionStatus as S, StartInteractiveOptions as T, InteractiveAttachOptions as _, WorkspaceImagePublishRequestOptions as a, InteractiveSessionHost as b, TraceExportFormat as c, buildTraceExportPayload as d, exportTraceBundle as f, SandboxSession as g, SandboxTaskSession as h, WorkspaceImagePublishInput as i, BuildSandboxMcpConfigOptions as j, SandboxInteractionResult as k, TraceExportResult as l, toOtelJson as m, HttpClient as n, WorkspaceImagePublishResult as o, otelTraceIdForTangleTrace as p, SandboxInstance as r, WorkspaceImages as s, ForkAcknowledgement as t, TraceExportSink as u, InteractiveAuthFile as v, RespondToPermissionOptions as w, InteractiveSessionInfo as x, InteractiveSessionHandle as y };
+export { RespondToPermissionOptions as A, SandboxInteractionResolution as B, InteractiveSessionIncarnationId as C, InteractiveSessionStartResult as D, InteractiveSessionStartOptions as E, InteractiveSessionController as F, SANDBOX_MCP_SERVER_NAME as G, BuildControlPlaneMcpConfigOptions as H, InteractiveSessionControllerOptions as I, SandboxMcpServerEntry as J, SandboxMcpConfig as K, InteractiveSessionControllerTransport as L, BrowserInteractiveSessionController as M, BrowserInteractiveSessionControllerOptions as N, InteractiveStopCommand as O, InteractiveAttachRequest as P, SandboxInteractionCommandResult as R, InteractiveSessionHost as S, InteractiveSessionRef as T, BuildSandboxMcpConfigOptions as U, SandboxInteractionResult as V, CONTROL_PLANE_MCP_SERVER_NAME as W, buildSandboxMcpConfig as X, buildControlPlaneMcpConfig as Y, InteractiveControlClaimRequest as _, WorkspaceImagePublishRequestOptions as a, InteractiveSessionHandle as b, TraceExportFormat as c, buildTraceExportPayload as d, exportTraceBundle as f, SandboxSession as g, SandboxTaskSession as h, WorkspaceImagePublishInput as i, agentInteractiveSessionPromptRequestDigest as j, InterruptResult as k, TraceExportResult as l, toOtelJson as m, HttpClient as n, WorkspaceImagePublishResult as o, otelTraceIdForTangleTrace as p, SandboxMcpEndpoint as q, SandboxInstance as r, WorkspaceImages as s, ForkAcknowledgement as t, TraceExportSink as u, InteractivePromptCommand as v, InteractiveSessionInfo as w, InteractiveSessionHandleOptions as x, InteractiveSessionControlClaim as y, SandboxInteractionConflict as z };

package/dist/tangle/index.d.ts

@@ -1,2 +1,2 @@
-import { a as TANGLE_JOBS_CONTRACT, c as AgentSandboxBlueprintAbi, d as SandboxCreateParamTypes, f as SandboxCreateResponseParamTypes, i as TANGLE_CHAIN_ID, l as ITangleJobsAbi, n as JOB_SANDBOX_CREATE, o as TANGLE_MAINNET_RPC, p as SandboxIdParamTypes, r as JOB_SANDBOX_DELETE, s as TangleSandboxClientConfig, t as TangleSandboxClient, u as JsonResponseParamTypes } from "../index-ldDRk8Jh.js";
+import { a as TANGLE_JOBS_CONTRACT, c as AgentSandboxBlueprintAbi, d as SandboxCreateParamTypes, f as SandboxCreateResponseParamTypes, i as TANGLE_CHAIN_ID, l as ITangleJobsAbi, n as JOB_SANDBOX_CREATE, o as TANGLE_MAINNET_RPC, p as SandboxIdParamTypes, r as JOB_SANDBOX_DELETE, s as TangleSandboxClientConfig, t as TangleSandboxClient, u as JsonResponseParamTypes } from "../index-ebsVOlUc.js";
 export { AgentSandboxBlueprintAbi, ITangleJobsAbi, JOB_SANDBOX_CREATE, JOB_SANDBOX_DELETE, JsonResponseParamTypes, SandboxCreateParamTypes, SandboxCreateResponseParamTypes, SandboxIdParamTypes, TANGLE_CHAIN_ID, TANGLE_JOBS_CONTRACT, TANGLE_MAINNET_RPC, TangleSandboxClient, TangleSandboxClientConfig };

package/dist/tangle/index.js

@@ -1,2 +1,2 @@
-import { a as TANGLE_JOBS_CONTRACT, c as ITangleJobsAbi, d as SandboxCreateResponseParamTypes, f as SandboxIdParamTypes, i as TANGLE_CHAIN_ID, l as JsonResponseParamTypes, n as JOB_SANDBOX_CREATE, o as TANGLE_MAINNET_RPC, r as JOB_SANDBOX_DELETE, s as AgentSandboxBlueprintAbi, t as TangleSandboxClient, u as SandboxCreateParamTypes } from "../tangle-CHpXtqlI.js";
+import { a as TANGLE_JOBS_CONTRACT, c as ITangleJobsAbi, d as SandboxCreateResponseParamTypes, f as SandboxIdParamTypes, i as TANGLE_CHAIN_ID, l as JsonResponseParamTypes, n as JOB_SANDBOX_CREATE, o as TANGLE_MAINNET_RPC, r as JOB_SANDBOX_DELETE, s as AgentSandboxBlueprintAbi, t as TangleSandboxClient, u as SandboxCreateParamTypes } from "../tangle-iDk_s8vt.js";
 export { AgentSandboxBlueprintAbi, ITangleJobsAbi, JOB_SANDBOX_CREATE, JOB_SANDBOX_DELETE, JsonResponseParamTypes, SandboxCreateParamTypes, SandboxCreateResponseParamTypes, SandboxIdParamTypes, TANGLE_CHAIN_ID, TANGLE_JOBS_CONTRACT, TANGLE_MAINNET_RPC, TangleSandboxClient };

package/dist/{tangle-CHpXtqlI.js → tangle-iDk_s8vt.js}

@@ -1,5 +1,5 @@
 import { m as parseErrorResponse } from "./errors-C6kn-3zt.js";
-import { n as createSandboxInstanceFromResponse } from "./sandbox-4F9CNqdR.js";
+import { n as createSandboxInstanceFromResponse } from "./sandbox-AUHcCJe1.js";
 //#region src/tangle/abi.ts
 /**
 * Tangle Contract ABI Definitions