@tangle-network/sandbox 0.30.2 → 0.31.0-develop.20260820224055.6e958e9

package/README.md

@@ -23,6 +23,7 @@ export SANDBOX_BASE_URL=https://sandbox.tangle.tools
 | Full client, sandboxes, fleets, images, sessions, and trace utilities | `@tangle-network/sandbox` |
 | Edge-safe client without `viem` | `@tangle-network/sandbox/core` |
 | Browser or Worker access with a short-lived scoped token | `@tangle-network/sandbox/runtime` |
+| Browser status, claim, and release control for an interactive session | `@tangle-network/sandbox/interactive-control` |
 | Direct Tangle chain operations | `@tangle-network/sandbox/tangle` |
 | Server-side token issuance and validation | `@tangle-network/sandbox/auth` |
 | Collaborative document clients and file bridging | `@tangle-network/sandbox/collaboration` |

package/dist/abort-signal-si1WMfJb.js

@@ -0,0 +1,31 @@
+//#region src/lib/abort-signal.ts
+function combineAbortSignals(signals) {
+	return AbortSignal.any(signals);
+}
+function awaitWithAbort(work, signal) {
+	if (!signal) return work;
+	signal.throwIfAborted();
+	return new Promise((resolve, reject) => {
+		let settled = false;
+		const onAbort = () => {
+			if (settled) return;
+			settled = true;
+			signal.removeEventListener("abort", onAbort);
+			reject(signal.reason ?? new DOMException("The request was aborted", "AbortError"));
+		};
+		signal.addEventListener("abort", onAbort, { once: true });
+		work.then((value) => {
+			if (settled) return;
+			settled = true;
+			signal.removeEventListener("abort", onAbort);
+			resolve(value);
+		}, (cause) => {
+			if (settled) return;
+			settled = true;
+			signal.removeEventListener("abort", onAbort);
+			reject(cause);
+		});
+	});
+}
+//#endregion
+export { combineAbortSignals as n, awaitWithAbort as t };

package/dist/agent/index.d.ts

@@ -1,6 +1,6 @@
-import { g as SandboxSession, h as SandboxTaskSession, r as SandboxInstance } from "../sandbox-Caev7isY.js";
-import { D as CodeResultPart, E as CodeLanguage, T as CodeExecutionResult, d as BackendConfig, w as CodeExecutionOptions, xi as SessionListOptions, yi as SessionInfo } from "../types-D_ykdqn6.js";
-import { i as Sandbox } from "../client-BkPr0m7Z.js";
+import { g as SandboxSession, h as SandboxTaskSession, r as SandboxInstance } from "../sandbox-Cr-4qzaA.js";
+import { D as CodeResultPart, E as CodeLanguage, T as CodeExecutionResult, d as BackendConfig, gi as SessionInfo, vi as SessionListOptions, w as CodeExecutionOptions } from "../types-BwYLVqxX.js";
+import { i as Sandbox } from "../client-Do_HS671.js";
 import * as _$_modelcontextprotocol_sdk_server_index_js0 from "@modelcontextprotocol/sdk/server/index.js";
 
 //#region src/agent/instances.d.ts

package/dist/agent/index.js

@@ -1,7 +1,7 @@
-import { f as assertCurrentBackendType } from "../runtime-api-TVLbV10b.js";
+import { d as assertCurrentBackendType } from "../runtime-api-B0tx7NJM.js";
 import { d as StateError, o as NotFoundError, p as ValidationError } from "../errors-C6kn-3zt.js";
-import { n as Sandbox } from "../client-CLuVW5gB.js";
-import { t as SandboxInstance } from "../sandbox-BKaSZNC7.js";
+import { n as Sandbox } from "../client-BfnJ44gF.js";
+import { t as SandboxInstance } from "../sandbox-AUHcCJe1.js";
 import { createRequire } from "node:module";
 //#region src/agent/instances.ts
 const managers = /* @__PURE__ */ new WeakMap();

package/dist/{agent-run-outcome-TwIC-Ccd.d.ts → agent-run-outcome-CM7xD7Mg.d.ts}

@@ -1,4 +1,4 @@
-import { Q as DurablePlanSnapshot, a as AgentQuestionRequest, dr as SandboxEvent, i as AgentApprovalRequirement, o as AgentRunStatus, s as AgentToolInvocation } from "./types-D_ykdqn6.js";
+import { Q as DurablePlanSnapshot, a as AgentQuestionRequest, i as AgentApprovalRequirement, o as AgentRunStatus, s as AgentToolInvocation, ur as SandboxEvent } from "./types-BwYLVqxX.js";
 import { InteractionRequest } from "@tangle-network/agent-interface";
 
 //#region src/agent-run-outcome.d.ts

package/dist/auth/index.d.ts

@@ -1,2 +1,2 @@
-import { _ as ReadTokenPayload, a as issueCollaborationToken, c as issueSessionScopedToken, d as AnyTokenPayload, f as BatchScopedTokenPayload, g as ProjectScopedTokenPayload, h as IssueCollaborationTokenOptions, i as issueBatchScopedToken, l as unsafeDecodeToken, m as CollaborationTokenPayload, n as getTokenTTL, o as issueProjectScopedToken, p as CollaborationAccess, r as isTokenExpiringSoon, s as issueReadToken, t as ProductTokenIssuer, u as verifyToken, v as SessionScopedTokenPayload, y as TokenScope } from "../index-DtRFVx5U.js";
+import { _ as ReadTokenPayload, a as issueCollaborationToken, c as issueSessionScopedToken, d as AnyTokenPayload, f as BatchScopedTokenPayload, g as ProjectScopedTokenPayload, h as IssueCollaborationTokenOptions, i as issueBatchScopedToken, l as unsafeDecodeToken, m as CollaborationTokenPayload, n as getTokenTTL, o as issueProjectScopedToken, p as CollaborationAccess, r as isTokenExpiringSoon, s as issueReadToken, t as ProductTokenIssuer, u as verifyToken, v as SessionScopedTokenPayload, y as TokenScope } from "../index-Bq_z_u6A.js";
 export { AnyTokenPayload, BatchScopedTokenPayload, CollaborationAccess, CollaborationTokenPayload, IssueCollaborationTokenOptions, ProductTokenIssuer, ProjectScopedTokenPayload, ReadTokenPayload, SessionScopedTokenPayload, TokenScope, getTokenTTL, isTokenExpiringSoon, issueBatchScopedToken, issueCollaborationToken, issueProjectScopedToken, issueReadToken, issueSessionScopedToken, unsafeDecodeToken, verifyToken };

package/dist/browser-interactive-control-controller-B476gcui.d.ts

@@ -0,0 +1,96 @@
+import { r as TerminalStreamHandlers } from "./terminal-stream-4KNJ6SmL.js";
+import { AgentInteractiveSessionAttach, AgentInteractiveSessionControlClaimAcknowledgement, AgentInteractiveSessionStatus } from "@tangle-network/agent-interface";
+import { AgentInteractiveSessionControlClaim as AgentInteractiveSessionControlClaim$1, AgentInteractiveSessionControlClaimRequest as AgentInteractiveSessionControlClaimRequest$1, AgentInteractiveSessionRef as AgentInteractiveSessionRef$1 } from "@tangle-network/agent-interface/environment-interactive-control";
+
+//#region src/interactive-types.d.ts
+/** Cancellation for an interactive SDK request. */
+interface InteractiveRequestOptions {
+  signal?: AbortSignal;
+}
+/** Cancellation for a control-claim request. */
+type InteractiveControlClaimOptions = InteractiveRequestOptions;
+/** Exact attach command after the controller has claimed control. */
+type InteractiveAttachOptions = AgentInteractiveSessionAttach & {
+  handlers?: TerminalStreamHandlers;
+};
+/** Published Interface control-claim acknowledgement. */
+type InteractiveControlClaimAcknowledgement = AgentInteractiveSessionControlClaimAcknowledgement;
+/** Provider-observed status without write authority. */
+type InteractiveSessionStatus = AgentInteractiveSessionStatus;
+//#endregion
+//#region src/interactive-control-controller.d.ts
+/** The exact identity needed to control one admitted interactive process. */
+interface InteractiveSessionIdentity {
+  ref: AgentInteractiveSessionRef$1;
+  control: AgentInteractiveSessionControlClaim$1;
+}
+/** Transport for the status, claim, and release control operations. */
+interface InteractiveSessionControlTransport {
+  status(sessionId: string, incarnationId: string, options?: InteractiveRequestOptions): Promise<InteractiveSessionStatus | null>;
+  claimControl(sessionId: string, request: AgentInteractiveSessionControlClaimRequest$1, options?: InteractiveRequestOptions): Promise<InteractiveControlClaimAcknowledgement>;
+  releaseControl(sessionId: string, ref: AgentInteractiveSessionRef$1, control: AgentInteractiveSessionControlClaim$1, options?: InteractiveRequestOptions): Promise<void>;
+}
+/** Maximum time spent on bounded claim recovery and release cleanup. */
+declare const INTERACTIVE_CONTROL_CLEANUP_TIMEOUT_MS = 5000;
+interface InteractiveSessionControlControllerOptions {
+  sessionId: string;
+  incarnationId: string;
+  holderId: string;
+  /** Check that the provider identity belongs to the expected environment. */
+  environmentId?: string;
+  /** Injectable only for deterministic callers and tests. */
+  operationIdFactory?: () => string;
+  /** Bound cleanup requests when a transport ignores AbortSignal. */
+  cleanupTimeoutMs?: number;
+}
+/** Create a holder id for one in-memory interactive controller. */
+declare function createInteractiveControlHolderId(prefix?: string): string;
+/**
+ * Own the one status → claim → release sequence shared by browser and SDK callers.
+ *
+ * This module deliberately has no terminal or WebSocket dependency. Attach-capable
+ * callers extend it with the stream operation after a claim has been resolved.
+ */
+declare class InteractiveSessionControlController {
+  protected readonly transport: InteractiveSessionControlTransport;
+  protected readonly options: InteractiveSessionControlControllerOptions;
+  private readonly operationIdFactory;
+  private readonly cleanupTimeoutMs;
+  private resolveInFlight?;
+  constructor(transport: InteractiveSessionControlTransport, options: InteractiveSessionControlControllerOptions);
+  protected safelyReleaseClaim(identity: InteractiveSessionIdentity): Promise<void>;
+  /**
+   * Recover a claim whose response or commit may have been lost or corrupted.
+   *
+   * The same operation id and digest make this replay idempotent. Recovery uses
+   * an independent bounded signal so caller abort cannot strand an invisible claim.
+   */
+  private recoverAmbiguousClaim;
+  /** Release one claim that this controller resolved. */
+  release(identity: InteractiveSessionIdentity, requestOptions?: InteractiveRequestOptions): Promise<void>;
+  /** Observe and claim the current exact process incarnation. */
+  resolve(requestOptions?: InteractiveRequestOptions): Promise<InteractiveSessionIdentity>;
+  private resolveInternal;
+  /** Expose the canonical ref digest used by persisted control identities. */
+  static identityDigest(identity: InteractiveSessionIdentity): string;
+}
+/** Expose the same digest used to bind persistence and control identities. */
+declare function interactiveSessionIdentityDigest(identity: InteractiveSessionIdentity): string;
+//#endregion
+//#region src/browser-interactive-control-controller.d.ts
+interface BrowserInteractiveSessionControlControllerOptions extends InteractiveSessionControlControllerOptions {
+  sessionApiUrl: string;
+  token: string;
+  fetchImpl?: typeof fetch;
+}
+/** Browser controller for status, claim, and release without terminal attach. */
+declare class BrowserInteractiveSessionControlController extends InteractiveSessionControlController {
+  constructor(options: BrowserInteractiveSessionControlControllerOptions);
+}
+/**
+ * Return one stable browser holder per exact sandbox process incarnation.
+ * Storage failures produce a new holder and never reuse persisted authority.
+ */
+declare function browserInteractiveControlHolderId(environmentId: string, sessionId: string, incarnationId: string): string;
+//#endregion
+export { InteractiveSessionControlController as a, InteractiveSessionIdentity as c, InteractiveAttachOptions as d, InteractiveControlClaimAcknowledgement as f, InteractiveSessionStatus as h, INTERACTIVE_CONTROL_CLEANUP_TIMEOUT_MS as i, createInteractiveControlHolderId as l, InteractiveRequestOptions as m, BrowserInteractiveSessionControlControllerOptions as n, InteractiveSessionControlControllerOptions as o, InteractiveControlClaimOptions as p, browserInteractiveControlHolderId as r, InteractiveSessionControlTransport as s, BrowserInteractiveSessionControlController as t, interactiveSessionIdentityDigest as u };

package/dist/browser-interactive-control-controller-wXQ7W5pT.js

@@ -0,0 +1,276 @@
+import { t as awaitWithAbort } from "./abort-signal-si1WMfJb.js";
+import { z } from "zod";
+import { AgentInteractiveSessionControlClaimAcknowledgementSchema, AgentInteractiveSessionControlClaimRequestSchema, AgentInteractiveSessionControlClaimSchema, AgentInteractiveSessionRefSchema, AgentInteractiveSessionStatusSchema, agentInteractiveSessionControlClaimAcknowledgementMatchesRequest, agentInteractiveSessionControlClaimMatchesRef, agentInteractiveSessionControlClaimRequestDigest } from "@tangle-network/agent-interface/environment-interactive-control";
+//#region ../../../packages/runtime-contracts/dist/interactive-session-control-http.js
+const interactiveSessionStatusResponseSchema = z.object({
+	success: z.literal(true),
+	data: z.object({ status: AgentInteractiveSessionStatusSchema }).strict()
+}).strict();
+const interactiveSessionControlClaimResponseSchema = z.object({
+	success: z.literal(true),
+	data: AgentInteractiveSessionControlClaimAcknowledgementSchema
+}).strict();
+const interactiveSessionControlReleaseBodySchema = z.object({
+	ref: AgentInteractiveSessionRefSchema,
+	control: AgentInteractiveSessionControlClaimSchema
+}).strict();
+const interactiveSessionControlReleaseResponseSchema = z.object({
+	success: z.literal(true),
+	data: z.object({ status: z.enum([
+		"released",
+		"already-released",
+		"absent"
+	]) }).strict()
+}).strict();
+//#endregion
+//#region src/interactive-control-controller.ts
+/** Maximum time spent on bounded claim recovery and release cleanup. */
+const INTERACTIVE_CONTROL_CLEANUP_TIMEOUT_MS = 5e3;
+function randomId(prefix) {
+	const cryptoApi = globalThis.crypto;
+	if (cryptoApi && typeof cryptoApi.randomUUID === "function") return `${prefix}-${cryptoApi.randomUUID()}`;
+	return `${prefix}-${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+}
+/** Create a holder id for one in-memory interactive controller. */
+function createInteractiveControlHolderId(prefix = "interactive") {
+	return randomId(prefix);
+}
+function assertInteractiveSessionRef(ref, options) {
+	if (ref.run.sessionId !== options.sessionId || ref.incarnationId !== options.incarnationId || options.environmentId !== void 0 && ref.run.environmentId !== options.environmentId) throw new Error("Interactive session identity does not match this sandbox");
+}
+function assertActiveControlClaim(control) {
+	const expiresAt = Date.parse(control.expiresAt);
+	if (!Number.isFinite(expiresAt) || expiresAt <= Date.now()) throw new Error("Interactive control claim is stale");
+}
+function createCleanupScope(timeoutMs) {
+	const controller = new AbortController();
+	const timer = setTimeout(() => {
+		controller.abort(new DOMException(`Interactive control cleanup timed out after ${timeoutMs}ms`, "TimeoutError"));
+	}, timeoutMs);
+	return {
+		signal: controller.signal,
+		dispose: () => clearTimeout(timer)
+	};
+}
+function claimAcknowledgementMatchesRequest(ref, request, acknowledgement) {
+	if (!agentInteractiveSessionControlClaimAcknowledgementMatchesRequest(request, acknowledgement)) return false;
+	if (acknowledgement.status !== "accepted" && acknowledgement.status !== "replayed") return true;
+	return acknowledgement.control !== void 0 && agentInteractiveSessionControlClaimMatchesRef(ref, acknowledgement.control) && acknowledgement.control.holderId === request.holderId;
+}
+/**
+* Own the one status → claim → release sequence shared by browser and SDK callers.
+*
+* This module deliberately has no terminal or WebSocket dependency. Attach-capable
+* callers extend it with the stream operation after a claim has been resolved.
+*/
+var InteractiveSessionControlController = class {
+	operationIdFactory;
+	cleanupTimeoutMs;
+	resolveInFlight;
+	constructor(transport, options) {
+		this.transport = transport;
+		this.options = options;
+		this.operationIdFactory = options.operationIdFactory ?? (() => randomId("interactive-claim"));
+		this.cleanupTimeoutMs = options.cleanupTimeoutMs ?? 5e3;
+		if (!Number.isFinite(this.cleanupTimeoutMs) || this.cleanupTimeoutMs <= 0) throw new RangeError("Interactive control cleanup timeout must be greater than zero");
+	}
+	async safelyReleaseClaim(identity) {
+		const cleanupScope = createCleanupScope(this.cleanupTimeoutMs);
+		try {
+			await awaitWithAbort(this.release(identity, { signal: cleanupScope.signal }), cleanupScope.signal);
+		} catch {} finally {
+			cleanupScope.dispose();
+		}
+	}
+	/**
+	* Recover a claim whose response or commit may have been lost or corrupted.
+	*
+	* The same operation id and digest make this replay idempotent. Recovery uses
+	* an independent bounded signal so caller abort cannot strand an invisible claim.
+	*/
+	async recoverAmbiguousClaim(ref, request) {
+		const cleanupScope = createCleanupScope(this.cleanupTimeoutMs);
+		try {
+			const acknowledgement = AgentInteractiveSessionControlClaimAcknowledgementSchema.parse(await awaitWithAbort(this.transport.claimControl(this.options.sessionId, request, { signal: cleanupScope.signal }), cleanupScope.signal));
+			if ((acknowledgement.status === "accepted" || acknowledgement.status === "replayed") && acknowledgement.control !== void 0 && claimAcknowledgementMatchesRequest(ref, request, acknowledgement) && agentInteractiveSessionControlClaimMatchesRef(ref, acknowledgement.control)) await this.safelyReleaseClaim({
+				ref,
+				control: acknowledgement.control
+			});
+		} catch {} finally {
+			cleanupScope.dispose();
+		}
+	}
+	/** Release one claim that this controller resolved. */
+	async release(identity, requestOptions) {
+		requestOptions?.signal?.throwIfAborted();
+		const exactRef = AgentInteractiveSessionRefSchema.parse(identity.ref);
+		assertInteractiveSessionRef(exactRef, this.options);
+		if (!agentInteractiveSessionControlClaimMatchesRef(exactRef, identity.control)) throw new Error("Interactive control claim is not bound to the session");
+		await this.transport.releaseControl(this.options.sessionId, exactRef, identity.control, requestOptions);
+	}
+	/** Observe and claim the current exact process incarnation. */
+	async resolve(requestOptions) {
+		requestOptions?.signal?.throwIfAborted();
+		if (this.resolveInFlight !== void 0) return await awaitWithAbort(this.resolveInFlight, requestOptions?.signal);
+		const operation = this.resolveInternal(requestOptions);
+		let tracked;
+		tracked = operation.finally(() => {
+			if (this.resolveInFlight === tracked) this.resolveInFlight = void 0;
+		});
+		this.resolveInFlight = tracked;
+		return await tracked;
+	}
+	async resolveInternal(requestOptions) {
+		let claimedIdentity;
+		try {
+			requestOptions?.signal?.throwIfAborted();
+			const status = await this.transport.status(this.options.sessionId, this.options.incarnationId, requestOptions);
+			requestOptions?.signal?.throwIfAborted();
+			if (!status || status.state !== "running") throw new Error("Interactive session is not running or has stale identity");
+			const ref = AgentInteractiveSessionRefSchema.parse(status.ref);
+			assertInteractiveSessionRef(ref, this.options);
+			let expectedGeneration = 1;
+			for (let attempt = 0; attempt < 2; attempt += 1) {
+				requestOptions?.signal?.throwIfAborted();
+				const material = {
+					operationId: this.operationIdFactory(),
+					ref,
+					holderId: this.options.holderId,
+					expectedGeneration
+				};
+				const request = AgentInteractiveSessionControlClaimRequestSchema.parse({
+					...material,
+					requestDigest: agentInteractiveSessionControlClaimRequestDigest(material)
+				});
+				let acknowledgement;
+				try {
+					acknowledgement = AgentInteractiveSessionControlClaimAcknowledgementSchema.parse(await this.transport.claimControl(this.options.sessionId, request, requestOptions));
+				} catch (error) {
+					await this.recoverAmbiguousClaim(ref, request);
+					throw error;
+				}
+				if (!claimAcknowledgementMatchesRequest(ref, request, acknowledgement)) {
+					await this.recoverAmbiguousClaim(ref, request);
+					throw new Error("Interactive control claim acknowledgement does not match the request");
+				}
+				if ((acknowledgement.status === "accepted" || acknowledgement.status === "replayed") && acknowledgement.control) {
+					if (!agentInteractiveSessionControlClaimMatchesRef(ref, acknowledgement.control)) throw new Error("Interactive control claim is not bound to the session");
+					claimedIdentity = {
+						ref,
+						control: acknowledgement.control
+					};
+					requestOptions?.signal?.throwIfAborted();
+					assertActiveControlClaim(acknowledgement.control);
+					return claimedIdentity;
+				}
+				requestOptions?.signal?.throwIfAborted();
+				if (acknowledgement.status === "conflict" && acknowledgement.conflictReason === "generation_mismatch" && acknowledgement.currentGeneration !== void 0 && acknowledgement.currentGeneration > expectedGeneration) {
+					expectedGeneration = acknowledgement.currentGeneration;
+					continue;
+				}
+				throw new Error(acknowledgement.message ?? "Interactive control is held by another client");
+			}
+			throw new Error("Interactive control claim became stale during attach");
+		} catch (error) {
+			if (claimedIdentity !== void 0) await this.safelyReleaseClaim(claimedIdentity);
+			throw error;
+		}
+	}
+	/** Expose the canonical ref digest used by persisted control identities. */
+	static identityDigest(identity) {
+		const ref = AgentInteractiveSessionRefSchema.parse(identity.ref);
+		const control = AgentInteractiveSessionControlClaimSchema.parse(identity.control);
+		if (!agentInteractiveSessionControlClaimMatchesRef(ref, control)) throw new Error("Interactive control claim is not bound to the session");
+		return control.refDigest;
+	}
+};
+/** Expose the same digest used to bind persistence and control identities. */
+function interactiveSessionIdentityDigest(identity) {
+	return InteractiveSessionControlController.identityDigest(identity);
+}
+//#endregion
+//#region src/browser-interactive-control-controller.ts
+function browserInteractiveSessionEndpoint(baseUrl, sessionId, suffix = "") {
+	return `${baseUrl.replace(/\/+$/, "")}/agents/sessions/${encodeURIComponent(sessionId)}/interactive${suffix}`;
+}
+function browserInteractiveTerminalEndpoint(baseUrl, sessionId) {
+	return `${baseUrl.replace(/\/+$/, "")}/terminals/${encodeURIComponent(sessionId)}/ws`;
+}
+function authHeaders(token, includeContentType = false) {
+	return {
+		Authorization: `Bearer ${token}`,
+		...includeContentType ? { "Content-Type": "application/json" } : {}
+	};
+}
+async function readError(response) {
+	if (response.status === 404) return /* @__PURE__ */ new Error("Interactive session identity is stale or no longer exists");
+	return /* @__PURE__ */ new Error(`Interactive session request failed (${response.status})`);
+}
+function createBrowserInteractiveSessionControlTransport(options) {
+	const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+	if (typeof fetchImpl !== "function") throw new Error("Interactive browser controller requires fetch");
+	return {
+		async status(sessionId, incarnationId, requestOptions) {
+			const response = await fetchImpl(`${browserInteractiveSessionEndpoint(options.sessionApiUrl, sessionId)}?incarnationId=${encodeURIComponent(incarnationId)}`, {
+				headers: authHeaders(options.token),
+				...requestOptions?.signal === void 0 ? {} : { signal: requestOptions.signal }
+			});
+			if (response.status === 404) return null;
+			if (!response.ok) throw await readError(response);
+			const parsed = interactiveSessionStatusResponseSchema.safeParse(await response.json());
+			if (!parsed.success) throw new Error("Interactive session is not running or has stale identity");
+			return parsed.data.data.status;
+		},
+		async claimControl(sessionId, request, requestOptions) {
+			const response = await fetchImpl(browserInteractiveSessionEndpoint(options.sessionApiUrl, sessionId, "/control"), {
+				method: "POST",
+				headers: authHeaders(options.token, true),
+				body: JSON.stringify(request),
+				...requestOptions?.signal === void 0 ? {} : { signal: requestOptions.signal }
+			});
+			if (!response.ok) throw await readError(response);
+			const parsed = interactiveSessionControlClaimResponseSchema.safeParse(await response.json());
+			if (!parsed.success) throw new Error("Interactive control claim response is invalid");
+			return parsed.data.data;
+		},
+		async releaseControl(sessionId, ref, control, requestOptions) {
+			const body = interactiveSessionControlReleaseBodySchema.parse({
+				ref,
+				control
+			});
+			const response = await fetchImpl(browserInteractiveSessionEndpoint(options.sessionApiUrl, sessionId, "/control/release"), {
+				method: "POST",
+				headers: authHeaders(options.token, true),
+				body: JSON.stringify(body),
+				...requestOptions?.signal === void 0 ? {} : { signal: requestOptions.signal }
+			});
+			if (!response.ok) throw await readError(response);
+			if (!interactiveSessionControlReleaseResponseSchema.safeParse(await response.json()).success) throw new Error("Interactive control release response is invalid");
+		}
+	};
+}
+/** Browser controller for status, claim, and release without terminal attach. */
+var BrowserInteractiveSessionControlController = class extends InteractiveSessionControlController {
+	constructor(options) {
+		super(createBrowserInteractiveSessionControlTransport(options), options);
+	}
+};
+/**
+* Return one stable browser holder per exact sandbox process incarnation.
+* Storage failures produce a new holder and never reuse persisted authority.
+*/
+function browserInteractiveControlHolderId(environmentId, sessionId, incarnationId) {
+	const key = `tangle.interactive.control-holder:${environmentId}:${sessionId}:${incarnationId}`;
+	try {
+		const storage = globalThis.sessionStorage;
+		const existing = storage.getItem(key);
+		if (existing) return existing;
+		const holderId = createInteractiveControlHolderId("browser");
+		storage.setItem(key, holderId);
+		return holderId;
+	} catch {
+		return createInteractiveControlHolderId("browser");
+	}
+}
+//#endregion
+export { INTERACTIVE_CONTROL_CLEANUP_TIMEOUT_MS as a, createInteractiveControlHolderId as c, interactiveSessionControlReleaseResponseSchema as d, interactiveSessionStatusResponseSchema as f, createBrowserInteractiveSessionControlTransport as i, interactiveSessionIdentityDigest as l, browserInteractiveControlHolderId as n, InteractiveSessionControlController as o, browserInteractiveTerminalEndpoint as r, assertInteractiveSessionRef as s, BrowserInteractiveSessionControlController as t, interactiveSessionControlClaimResponseSchema as u };

package/dist/{client-CLuVW5gB.js → client-BfnJ44gF.js}

@@ -1,6 +1,7 @@
-import { _ as backendTypeSchema, c as combineAbortSignals, d as applyRequestedModel, f as assertCurrentBackendType, l as encodePromptForWire, o as SANDBOX_PROXY_REQUEST_MAX_BYTES, p as normalizeRuntimeBackendConfig, u as encodeTextForWire } from "./runtime-api-TVLbV10b.js";
+import { c as encodePromptForWire, d as assertCurrentBackendType, f as normalizeRuntimeBackendConfig, g as backendTypeSchema, l as encodeTextForWire, o as SANDBOX_PROXY_REQUEST_MAX_BYTES, u as applyRequestedModel } from "./runtime-api-B0tx7NJM.js";
 import { a as NetworkError, f as TimeoutError, l as SandboxError, m as parseErrorResponse, o as NotFoundError, p as ValidationError, s as PartialFailureError, t as AuthError, u as ServerError } from "./errors-C6kn-3zt.js";
-import { i as normalizeStartupDiagnostics, n as createSandboxInstanceFromResponse, r as normalizeSandboxCreateReceipt, w as parseSSEStream, x as exportTraceBundle, y as normalizeConnection } from "./sandbox-BKaSZNC7.js";
+import { n as combineAbortSignals } from "./abort-signal-si1WMfJb.js";
+import { C as normalizeConnection, O as parseSSEStream, T as exportTraceBundle, _ as requestInteractiveSessionToken, i as normalizeStartupDiagnostics, n as createSandboxInstanceFromResponse, r as normalizeSandboxCreateReceipt } from "./sandbox-AUHcCJe1.js";
 import { agentProfileSchema } from "@tangle-network/agent-interface";
 import { z } from "zod";
 //#region src/backend-registry.ts
@@ -2444,11 +2445,11 @@ function withRequestContextHeaders(response, path, method) {
 	});
 }
 async function resolveLocalCliAuthFiles(backendType) {
-	const { discoverLocalCliAuthFiles } = await import("./local-cli-auth-D4u7fsnH.js");
+	const { discoverLocalCliAuthFiles } = await import("./local-cli-auth-CJmSpTjk.js");
 	return discoverLocalCliAuthFiles(backendType);
 }
 async function describeLocalCliAuthExpectation(backendType) {
-	const { describeLocalCliAuthExpectation: describe } = await import("./local-cli-auth-D4u7fsnH.js");
+	const { describeLocalCliAuthExpectation: describe } = await import("./local-cli-auth-CJmSpTjk.js");
 	return describe(backendType);
 }
 async function hydrateLocalCliBackendAuth(backend, baseUrl, trustLocalCliAuth) {
@@ -2822,6 +2823,16 @@ var Sandbox = class {
 		return parseBackendRegistryResponseBody(body);
 	}
 	/**
+	* Get one registered agent backend by its canonical type.
+	*
+	* An absent entry means the authenticated Sandbox deployment does not
+	* advertise that backend. The lookup uses the same typed catalog as
+	* {@link listBackends}; it does not maintain a second registry.
+	*/
+	async getBackend(type) {
+		return (await this.listBackends()).backends.find((backend) => backend.type === type);
+	}
+	/**
 	* List all sandboxes.
 	*
 	* @param options - Filtering and pagination options
@@ -2880,6 +2891,16 @@ var Sandbox = class {
 		return createSandboxInstanceFromResponse(this, this.parseInfo(data));
 	}
 	/**
+	* Mint the terminal-capable token for one exact interactive session.
+	*
+	* This is a server-side operation. It validates the complete session
+	* reference, derives the sandbox and runtime session IDs from that reference,
+	* and makes one scoped-token request without loading the sandbox first.
+	*/
+	async mintInteractiveSessionToken(ref, options = {}) {
+		return requestInteractiveSessionToken(this, ref, options);
+	}
+	/**
 	* Return the identity the public Sandbox API observed for this credential.
 	*
 	* This is useful for deployment checks that must confirm which account and
@@ -3116,6 +3137,7 @@ var Sandbox = class {
 		const requestTimeoutMs = typeof fetchOptions?.timeoutMs === "number" && fetchOptions.timeoutMs > 0 ? fetchOptions.timeoutMs : this.timeoutMs;
 		const controller = new AbortController();
 		const timeoutId = setTimeout(() => controller.abort(), requestTimeoutMs);
+		const requestSignal = options?.signal ? combineAbortSignals([options.signal, controller.signal]) : controller.signal;
 		try {
 			const headers = new Headers(options?.headers);
 			headers.set("Authorization", `Bearer ${this.apiKey}`);
@@ -3124,10 +3146,11 @@ var Sandbox = class {
 			return withRequestContextHeaders(await globalThis.fetch(url, {
 				...options,
 				headers,
-				signal: options?.signal ?? controller.signal
+				signal: requestSignal
 			}), path, options?.method);
 		} catch (err) {
-			if (err instanceof Error && err.name === "AbortError") throw new TimeoutError(requestTimeoutMs);
+			if (controller.signal.aborted && requestSignal.reason === controller.signal.reason) throw new TimeoutError(requestTimeoutMs);
+			if (options?.signal?.aborted) throw options.signal.reason ?? err;
 			throw new NetworkError(`Failed to connect to Sandbox API: ${err instanceof Error ? err.message : String(err)}`, err instanceof Error ? err : void 0, {
 				endpoint: path,
 				origin: "sandbox-api"

package/dist/{client-BkPr0m7Z.d.ts → client-Do_HS671.d.ts}

@@ -1,5 +1,7 @@
-import { l as TraceExportResult, n as HttpClient, r as SandboxInstance, u as TraceExportSink } from "./sandbox-Caev7isY.js";
-import { $i as UsageInfo, Ar as SandboxFleetTraceBundle, At as FleetExecDispatchResult, Bn as PublishPublicTemplateOptions, Br as SandboxInfo, Cr as SandboxFleetMachineRecord, Ct as FleetDispatchCancelResult, Dr as SandboxFleetOperationsSummary, Dt as FleetDriveTurnOutcome, Et as FleetDispatchStreamOptions, F as CreateSandboxFleetWithCoordinatorOptions, Gn as ReconcileSandboxFleetsResult, Hn as ReapExpiredSandboxFleetsOptions, I as CreateSandboxOptions, Ii as SubscriptionInfo, Ir as SandboxFleetWorkspaceReconcileResult, Lr as SandboxFleetWorkspaceRestoreResult, M as CreateRequestOptions, Mi as SshKeysManager, Mn as PromptOptions, Mt as FleetPromptDispatchOptions, N as CreateSandboxFleetOptions, Nn as PromptResult, Nr as SandboxFleetTraceOptions, Nt as FleetPromptDispatchResult, Ot as FleetDriveTurnRequest, P as CreateSandboxFleetTokenOptions, Pr as SandboxFleetUsage, Rn as PublicTemplateInfo, Rr as SandboxFleetWorkspaceSnapshotResult, Tr as SandboxFleetManifest, Tt as FleetDispatchResultBufferOptions, Un as ReapExpiredSandboxFleetsResult, Vn as PublishPublicTemplateVersionOptions, Wn as ReconcileSandboxFleetsOptions, _ as BatchRunOptions, _r as SandboxFleetDriverCapability, an as IntelligenceReportWindow, ct as ExecOptions, di as SecretsManager, fr as SandboxFleetArtifact, g as BatchResult, gr as SandboxFleetDispatchResponse, ir as SandboxConfig, j as CreateIntelligenceReportOptions, jn as PromptInputPart, jt as FleetMachineId, kr as SandboxFleetToken, kt as FleetExecDispatchOptions, l as AttachSandboxFleetMachineOptions, ln as ListSandboxFleetOptions, lt as ExecResult, mr as SandboxFleetCostEstimate, nn as IntelligenceReportBudget, pr as SandboxFleetArtifactSpec, qi as TokenRefreshHandler, rn as IntelligenceReportCompareTo, sa as BatchEvent, tn as IntelligenceReport, un as ListSandboxOptions, ur as SandboxEnvironment, v as BatchRunRequest, wt as FleetDispatchResultBuffer, yr as SandboxFleetInfo, zn as PublicTemplateVersionInfo, zr as SandboxIdentity } from "./types-D_ykdqn6.js";
+import { l as TraceExportResult, n as HttpClient, r as SandboxInstance, u as TraceExportSink } from "./sandbox-Cr-4qzaA.js";
+import { l as ScopedToken, s as MintInteractiveSessionTokenOptions } from "./terminal-stream-4KNJ6SmL.js";
+import { An as PromptInputPart, At as FleetExecDispatchResult, Bn as PublishPublicTemplateVersionOptions, Ct as FleetDispatchCancelResult, Dt as FleetDriveTurnOutcome, Er as SandboxFleetOperationsSummary, Et as FleetDispatchStreamOptions, F as CreateSandboxFleetWithCoordinatorOptions, Fr as SandboxFleetWorkspaceReconcileResult, Hn as ReapExpiredSandboxFleetsResult, I as CreateSandboxOptions, Ir as SandboxFleetWorkspaceRestoreResult, Ln as PublicTemplateInfo, Lr as SandboxFleetWorkspaceSnapshotResult, M as CreateRequestOptions, Mn as PromptResult, Mr as SandboxFleetTraceOptions, Mt as FleetPromptDispatchOptions, N as CreateSandboxFleetOptions, Ni as SubscriptionInfo, Nr as SandboxFleetUsage, Nt as FleetPromptDispatchResult, Or as SandboxFleetToken, Ot as FleetDriveTurnRequest, P as CreateSandboxFleetTokenOptions, Rn as PublicTemplateVersionInfo, Rr as SandboxIdentity, Sr as SandboxFleetMachineRecord, Tt as FleetDispatchResultBufferOptions, Un as ReconcileSandboxFleetsOptions, Vn as ReapExpiredSandboxFleetsOptions, Wi as TokenRefreshHandler, Wn as ReconcileSandboxFleetsResult, Xi as UsageInfo, _ as BatchRunOptions, an as IntelligenceReportWindow, ci as SecretsManager, ct as ExecOptions, dr as SandboxFleetArtifact, fr as SandboxFleetArtifactSpec, g as BatchResult, gr as SandboxFleetDriverCapability, hr as SandboxFleetDispatchResponse, ia as BatchEvent, j as CreateIntelligenceReportOptions, jn as PromptOptions, jt as FleetMachineId, ki as SshKeysManager, kr as SandboxFleetTraceBundle, kt as FleetExecDispatchOptions, l as AttachSandboxFleetMachineOptions, ln as ListSandboxFleetOptions, lr as SandboxEnvironment, lt as ExecResult, nn as IntelligenceReportBudget, pr as SandboxFleetCostEstimate, rn as IntelligenceReportCompareTo, rr as SandboxConfig, tn as IntelligenceReport, un as ListSandboxOptions, v as BatchRunRequest, vr as SandboxFleetInfo, wr as SandboxFleetManifest, wt as FleetDispatchResultBuffer, zn as PublishPublicTemplateOptions, zr as SandboxInfo } from "./types-BwYLVqxX.js";
+import { AgentInteractiveSessionRef } from "@tangle-network/agent-interface";
 import { z } from "zod";
 
 //#region src/backend-registry.d.ts
@@ -280,6 +282,13 @@ declare class SandboxFleetClient {
   private listBySandboxMetadata;
 }
 //#endregion
+//#region src/scoped-token.d.ts
+interface ScopedTokenHttpClient {
+  fetch(path: string, options?: RequestInit, fetchOptions?: {
+    timeoutMs?: number;
+  }): Promise<Response>;
+}
+//#endregion
 //#region src/session-events.d.ts
 /** Event delivered to a product session through the Sandbox session gateway. */
 interface SessionBroadcastEvent {
@@ -324,7 +333,7 @@ interface SessionBroadcastResult {
  * await box.delete();
  * ```
  */
-declare class Sandbox implements HttpClient {
+declare class Sandbox implements HttpClient, ScopedTokenHttpClient {
   private readonly baseUrl;
   private readonly apiKey;
   private readonly timeoutMs;
@@ -432,6 +441,14 @@ declare class Sandbox implements HttpClient {
    * fewer interaction kinds after its configuration is applied.
    */
   listBackends(): Promise<BackendRegistryResponse>;
+  /**
+   * Get one registered agent backend by its canonical type.
+   *
+   * An absent entry means the authenticated Sandbox deployment does not
+   * advertise that backend. The lookup uses the same typed catalog as
+   * {@link listBackends}; it does not maintain a second registry.
+   */
+  getBackend(type: string): Promise<BackendRegistryEntry | undefined>;
   /**
    * List all sandboxes.
    *
@@ -463,6 +480,14 @@ declare class Sandbox implements HttpClient {
    * ```
    */
   get(id: string): Promise<SandboxInstance | null>;
+  /**
+   * Mint the terminal-capable token for one exact interactive session.
+   *
+   * This is a server-side operation. It validates the complete session
+   * reference, derives the sandbox and runtime session IDs from that reference,
+   * and makes one scoped-token request without loading the sandbox first.
+   */
+  mintInteractiveSessionToken(ref: AgentInteractiveSessionRef, options?: MintInteractiveSessionTokenOptions): Promise<ScopedToken>;
   /**
    * Return the identity the public Sandbox API observed for this credential.
    *

package/dist/collaboration/index.d.ts

@@ -1,2 +1,2 @@
-import { _ as CollaborationTransportConfig, a as CollaborationClient, c as CollaborationClientConfig, d as CollaborationDocumentRef, f as CollaborationFileBridgeOptions, g as CollaborationTokenRefreshResponse, h as CollaborationTokenRefreshRequest, i as parseCollaborationDocumentId, l as CollaborationDocumentAdapter, m as CollaborationPermissions, n as buildCollaborationDocumentId, o as CollaborationBootstrapRequest, p as CollaborationFileEvent, r as normalizeCollaborationPath, s as CollaborationBootstrapResponse, t as CollaborationFileBridge, u as CollaborationDocumentChange, v as SaveCollaborationSnapshotRequest, y as SaveCollaborationSnapshotResponse } from "../index-Cp1KYanB.js";
+import { _ as CollaborationTransportConfig, a as CollaborationClient, c as CollaborationClientConfig, d as CollaborationDocumentRef, f as CollaborationFileBridgeOptions, g as CollaborationTokenRefreshResponse, h as CollaborationTokenRefreshRequest, i as parseCollaborationDocumentId, l as CollaborationDocumentAdapter, m as CollaborationPermissions, n as buildCollaborationDocumentId, o as CollaborationBootstrapRequest, p as CollaborationFileEvent, r as normalizeCollaborationPath, s as CollaborationBootstrapResponse, t as CollaborationFileBridge, u as CollaborationDocumentChange, v as SaveCollaborationSnapshotRequest, y as SaveCollaborationSnapshotResponse } from "../index-CMLW3u5K.js";
 export { CollaborationBootstrapRequest, CollaborationBootstrapResponse, CollaborationClient, CollaborationClientConfig, CollaborationDocumentAdapter, CollaborationDocumentChange, CollaborationDocumentRef, CollaborationFileBridge, CollaborationFileBridgeOptions, CollaborationFileEvent, CollaborationPermissions, CollaborationTokenRefreshRequest, CollaborationTokenRefreshResponse, CollaborationTransportConfig, SaveCollaborationSnapshotRequest, SaveCollaborationSnapshotResponse, buildCollaborationDocumentId, normalizeCollaborationPath, parseCollaborationDocumentId };

package/dist/collaboration/index.js

@@ -1,2 +1,2 @@
-import { a as CollaborationClient, i as parseCollaborationDocumentId, n as buildCollaborationDocumentId, r as normalizeCollaborationPath, t as CollaborationFileBridge } from "../collaboration-COCXdRrk.js";
+import { a as CollaborationClient, i as parseCollaborationDocumentId, n as buildCollaborationDocumentId, r as normalizeCollaborationPath, t as CollaborationFileBridge } from "../collaboration-DQD9kCdN.js";
 export { CollaborationClient, CollaborationFileBridge, buildCollaborationDocumentId, normalizeCollaborationPath, parseCollaborationDocumentId };

package/dist/core.d.ts

@@ -1,5 +1,5 @@
-import { a as WorkspaceImagePublishRequestOptions, i as WorkspaceImagePublishInput, o as WorkspaceImagePublishResult, r as SandboxInstance, s as WorkspaceImages } from "./sandbox-Caev7isY.js";
-import { Br as SandboxInfo, I as CreateSandboxOptions, Jr as SandboxStatus, Sn as PreviewLinkWaitOptions, bn as PreviewLinkInfo, ct as ExecOptions, hn as NetworkConfig, ir as SandboxConfig, jn as PromptInputPart, lt as ExecResult, xn as PreviewLinkManager } from "./types-D_ykdqn6.js";
-import { C as isBackendRegistryInteractionKind, S as backendRegistryResponseSchema, T as parseBackendRegistryResponseBody, _ as BackendRegistryInteractionKind, b as backendRegistryEntrySchema, g as BackendRegistryEntry, h as BackendRegistryCapabilities, i as Sandbox, v as BackendRegistryResponse, w as parseBackendRegistryResponse, x as backendRegistryInteractionKindSchema, y as backendRegistryCapabilitiesSchema } from "./client-BkPr0m7Z.js";
-import { a as NetworkError, c as QuotaError, d as SandboxFailureDetail, f as ServerError, h as ValidationError, i as FileWriteConflictError, l as SandboxError, m as TimeoutError, n as CapabilityError, o as NotFoundError, p as StateError, s as PartialFailureError, t as AuthError, u as SandboxErrorJson } from "./errors-Bdy5jXzc.js";
+import { a as WorkspaceImagePublishRequestOptions, i as WorkspaceImagePublishInput, o as WorkspaceImagePublishResult, r as SandboxInstance, s as WorkspaceImages } from "./sandbox-Cr-4qzaA.js";
+import { An as PromptInputPart, I as CreateSandboxOptions, bn as PreviewLinkManager, ct as ExecOptions, lt as ExecResult, mn as NetworkConfig, qr as SandboxStatus, rr as SandboxConfig, xn as PreviewLinkWaitOptions, yn as PreviewLinkInfo, zr as SandboxInfo } from "./types-BwYLVqxX.js";
+import { C as isBackendRegistryInteractionKind, S as backendRegistryResponseSchema, T as parseBackendRegistryResponseBody, _ as BackendRegistryInteractionKind, b as backendRegistryEntrySchema, g as BackendRegistryEntry, h as BackendRegistryCapabilities, i as Sandbox, v as BackendRegistryResponse, w as parseBackendRegistryResponse, x as backendRegistryInteractionKindSchema, y as backendRegistryCapabilitiesSchema } from "./client-Do_HS671.js";
+import { a as NetworkError, c as QuotaError, d as SandboxFailureDetail, f as ServerError, h as ValidationError, i as FileWriteConflictError, l as SandboxError, m as TimeoutError, n as CapabilityError, o as NotFoundError, p as StateError, s as PartialFailureError, t as AuthError, u as SandboxErrorJson } from "./errors-CQOvGddH.js";
 export { AuthError, type BackendRegistryCapabilities, type BackendRegistryEntry, type BackendRegistryInteractionKind, type BackendRegistryResponse, CapabilityError, type CreateSandboxOptions, type ExecOptions, type ExecResult, FileWriteConflictError, type NetworkConfig, NetworkError, NotFoundError, PartialFailureError, type PreviewLinkInfo, type PreviewLinkManager, type PreviewLinkWaitOptions, type PromptInputPart, QuotaError, Sandbox, type SandboxConfig, SandboxError, type SandboxErrorJson, type SandboxFailureDetail, type SandboxInfo, SandboxInstance, type SandboxStatus, ServerError, StateError, TimeoutError, ValidationError, type WorkspaceImagePublishInput, type WorkspaceImagePublishRequestOptions, type WorkspaceImagePublishResult, WorkspaceImages, backendRegistryCapabilitiesSchema, backendRegistryEntrySchema, backendRegistryInteractionKindSchema, backendRegistryResponseSchema, isBackendRegistryInteractionKind, parseBackendRegistryResponse, parseBackendRegistryResponseBody };

package/dist/core.js

@@ -1,4 +1,4 @@
 import { a as NetworkError, c as QuotaError, d as StateError, f as TimeoutError, i as FileWriteConflictError, l as SandboxError, n as CapabilityError, o as NotFoundError, p as ValidationError, s as PartialFailureError, t as AuthError, u as ServerError } from "./errors-C6kn-3zt.js";
-import { _ as parseBackendRegistryResponseBody, d as backendRegistryCapabilitiesSchema, f as backendRegistryEntrySchema, g as parseBackendRegistryResponse, h as isBackendRegistryInteractionKind, m as backendRegistryResponseSchema, n as Sandbox, p as backendRegistryInteractionKindSchema } from "./client-CLuVW5gB.js";
-import { a as WorkspaceImages, t as SandboxInstance } from "./sandbox-BKaSZNC7.js";
+import { _ as parseBackendRegistryResponseBody, d as backendRegistryCapabilitiesSchema, f as backendRegistryEntrySchema, g as parseBackendRegistryResponse, h as isBackendRegistryInteractionKind, m as backendRegistryResponseSchema, n as Sandbox, p as backendRegistryInteractionKindSchema } from "./client-BfnJ44gF.js";
+import { a as WorkspaceImages, t as SandboxInstance } from "./sandbox-AUHcCJe1.js";
 export { AuthError, CapabilityError, FileWriteConflictError, NetworkError, NotFoundError, PartialFailureError, QuotaError, Sandbox, SandboxError, SandboxInstance, ServerError, StateError, TimeoutError, ValidationError, WorkspaceImages, backendRegistryCapabilitiesSchema, backendRegistryEntrySchema, backendRegistryInteractionKindSchema, backendRegistryResponseSchema, isBackendRegistryInteractionKind, parseBackendRegistryResponse, parseBackendRegistryResponseBody };