@tangle-network/sandbox 0.30.2-develop.20260820100122.dc85046 → 0.30.2-develop.20260820200640.75917

package/dist/{sandbox-DM-VD8ja.js → sandbox-AUHcCJe1.js}

@@ -1,7 +1,10 @@
-import { a as uploadChunked, c as combineAbortSignals, d as applyRequestedModel, f as assertCurrentBackendType, h as deriveAgentResultOutcome, i as sessionHeaders, l as encodePromptForWire, m as createAgentRunOutcomeTracker, n as normalizeSessionInfo, o as SANDBOX_PROXY_REQUEST_MAX_BYTES, p as normalizeRuntimeBackendConfig, r as appendSessionIdQuery, t as SandboxRuntimeApi } from "./runtime-api-TVLbV10b.js";
+import { a as uploadChunked, c as encodePromptForWire, d as assertCurrentBackendType, f as normalizeRuntimeBackendConfig, i as sessionHeaders, m as deriveAgentResultOutcome, n as normalizeSessionInfo, o as SANDBOX_PROXY_REQUEST_MAX_BYTES, p as createAgentRunOutcomeTracker, r as appendSessionIdQuery, t as SandboxRuntimeApi, u as applyRequestedModel } from "./runtime-api-B0tx7NJM.js";
 import { a as NetworkError, c as QuotaError, d as StateError, f as TimeoutError, l as SandboxError, m as parseErrorResponse, n as CapabilityError, o as NotFoundError, p as ValidationError, t as AuthError, u as ServerError } from "./errors-C6kn-3zt.js";
-import { AgentExactRunControlRefSchema, AgentRunCancellationAcknowledgementSchema, AgentRunCancellationRequestSchema, InteractionAcknowledgementSchema, InteractionBindingSchema, InteractionRequestSchema, InteractionResponseCommandSchema, InteractionResponseSchema, agentRunCancellationAcknowledgementMatchesRequest, canonicalCandidateDigest, sha256DigestSchema } from "@tangle-network/agent-interface";
+import { c as createInteractiveControlHolderId, d as interactiveSessionControlReleaseResponseSchema, f as interactiveSessionStatusResponseSchema, i as createBrowserInteractiveSessionControlTransport, o as InteractiveSessionControlController, r as browserInteractiveTerminalEndpoint, s as assertInteractiveSessionRef, u as interactiveSessionControlClaimResponseSchema } from "./browser-interactive-control-controller-wXQ7W5pT.js";
+import { n as combineAbortSignals, t as awaitWithAbort } from "./abort-signal-si1WMfJb.js";
+import { AgentExactRunControlRefSchema, AgentInteractiveSessionAttachSchema, AgentInteractiveSessionControlClaimAcknowledgementSchema, AgentInteractiveSessionControlClaimRequestSchema, AgentInteractiveSessionControlClaimSchema, AgentInteractiveSessionPromptAcknowledgementSchema, AgentInteractiveSessionPromptCommandSchema, AgentInteractiveSessionRefSchema, AgentInteractiveSessionStartSchema, AgentInteractiveSessionStopAcknowledgementSchema, AgentInteractiveSessionStopCommandSchema, AgentRunCancellationAcknowledgementSchema, AgentRunCancellationRequestSchema, InteractionAcknowledgementSchema, InteractionBindingSchema, InteractionRequestSchema, InteractionResponseCommandSchema, InteractionResponseSchema, agentInteractiveSessionControlClaimAcknowledgementMatchesRequest, agentInteractiveSessionControlClaimIsNewer, agentInteractiveSessionControlClaimMatchesRef, agentInteractiveSessionPromptAcknowledgementMatchesCommand, agentInteractiveSessionPromptRequestDigest, agentInteractiveSessionRefMatchesStart, agentInteractiveSessionStatusMatchesRef, agentInteractiveSessionStopAcknowledgementMatchesCommand, agentRunCancellationAcknowledgementMatchesRequest, canonicalCandidateDigest, exactAgentInteractiveSessionStart, sha256DigestSchema } from "@tangle-network/agent-interface";
 import { z } from "zod";
+import { AgentInteractiveSessionControlClaimSchema as AgentInteractiveSessionControlClaimSchema$1, AgentInteractiveSessionPromptAcknowledgementSchema as AgentInteractiveSessionPromptAcknowledgementSchema$1, AgentInteractiveSessionRefSchema as AgentInteractiveSessionRefSchema$1, AgentInteractiveSessionStatusSchema, AgentInteractiveSessionStopAcknowledgementSchema as AgentInteractiveSessionStopAcknowledgementSchema$1 } from "@tangle-network/agent-interface/environment-interactive-control";
 import { readTokenCostUsd, readTokenUsage } from "@tangle-network/agent-core";
 //#region ../../../packages/sse-core/dist/index.js
 /**
@@ -475,9 +478,9 @@ function readFlagGroup(record, group, keys) {
 *  - Anything else (non-object, missing or non-numeric `schema`) throws:
 *    that is not a capability document at all.
 */
-function parseSandboxRuntimeCapabilities(value) {
-	if (value === null || typeof value !== "object" || Array.isArray(value)) invalidCapabilities("a non-object document");
-	const record = value;
+function parseSandboxRuntimeCapabilities(raw) {
+	if (raw === null || typeof raw !== "object" || Array.isArray(raw)) invalidCapabilities("a non-object document");
+	const record = raw;
 	if (typeof record.schema === "number" && Number.isInteger(record.schema) && record.schema > 1) return null;
 	if (record.schema !== 1) invalidCapabilities(`schema version ${JSON.stringify(record.schema)} — this SDK understands 1`);
 	if (typeof record.agentInterface !== "string" || typeof record.sidecarVersion !== "string" || typeof record.image !== "string") invalidCapabilities("a document missing its identity fields");
@@ -485,6 +488,19 @@ function parseSandboxRuntimeCapabilities(value) {
 	if (interactionsValue === null || typeof interactionsValue !== "object" || Array.isArray(interactionsValue)) invalidCapabilities("a malformed 'interactions' group");
 	const interactionsRecord = interactionsValue;
 	if ("responseDedupe" in interactionsRecord && typeof interactionsRecord.responseDedupe !== "boolean") invalidCapabilities("a non-boolean 'interactions.responseDedupe' flag");
+	const interactiveAgentValue = record.interactiveAgent;
+	let interactiveAgent;
+	if (interactiveAgentValue !== void 0) interactiveAgent = readFlagGroup(record, "interactiveAgent", [
+		"start",
+		"status",
+		"attach",
+		"control",
+		"reattach",
+		"sendPrompt",
+		"input",
+		"resize",
+		"stop"
+	]);
 	return {
 		schema: 1,
 		agentInterface: record.agentInterface,
@@ -497,7 +513,8 @@ function parseSandboxRuntimeCapabilities(value) {
 			"idempotent"
 		]),
 		runs: readFlagGroup(record, "runs", ["executionScopedStatus", "eventReplay"]),
-		interactions: typeof interactionsRecord.responseDedupe === "boolean" ? { responseDedupe: interactionsRecord.responseDedupe } : {}
+		interactions: typeof interactionsRecord.responseDedupe === "boolean" ? { responseDedupe: interactionsRecord.responseDedupe } : {},
+		...interactiveAgent === void 0 ? {} : { interactiveAgent }
 	};
 }
 /**
@@ -603,11 +620,19 @@ function validateAcceptedDispatchRunRef(raw, expected, sandboxId, sessionId, exe
 	return accepted;
 }
 //#endregion
-//#region src/interaction-response.ts
-const APPLIED_INTERACTION_STATUS = z.enum(["accepted", "already_resolved_same"]);
-const REFUSED_INTERACTION_STATUS = z.enum(["already_resolved_different", "binding_mismatch"]);
-const InteractionResolutionSchema = z.strictObject({
-	status: APPLIED_INTERACTION_STATUS,
+//#region ../../../packages/runtime-contracts/dist/interaction-response.js
+/** Durable states reported for a recorded interaction response. */
+const interactionResolutionDeliveryStateSchema = z.enum([
+	"pending",
+	"delivering",
+	"delivered",
+	"delivery_failed",
+	"backend_lost",
+	"effect_unknown"
+]);
+/** Canonical result returned after a response is recorded by Sidecar. */
+const interactionResolutionAcknowledgementSchema = z.strictObject({
+	status: z.enum(["accepted", "already_resolved_same"]),
 	operationId: z.string().min(1),
 	responseDigest: sha256DigestSchema,
 	interactionId: z.string().min(1),
@@ -617,14 +642,19 @@ const InteractionResolutionSchema = z.strictObject({
 		"declined",
 		"cancelled"
 	]),
+	deliveryState: interactionResolutionDeliveryStateSchema,
 	delivered: z.boolean(),
 	resolvedAt: z.string().min(1),
 	binding: InteractionBindingSchema.optional()
 });
-const InteractionResolutionEnvelopeSchema = z.object({
+/** Canonical success envelope for the public session interaction endpoint. */
+const interactionResolutionResponseSchema = z.strictObject({
 	success: z.literal(true),
-	resolution: InteractionResolutionSchema
+	resolution: interactionResolutionAcknowledgementSchema
 });
+//#endregion
+//#region src/interaction-response.ts
+const REFUSED_INTERACTION_STATUS = z.enum(["already_resolved_different", "binding_mismatch"]);
 const InteractionConflictEnvelopeSchema = z.object({
 	success: z.literal(false),
 	currentState: REFUSED_INTERACTION_STATUS,
@@ -667,7 +697,7 @@ function assertResolutionMatches(resolution, sessionId, submitted, response, end
 async function readInteractionResult(response, endpoint, sessionId, submitted) {
 	const body = await response.text();
 	if (response.ok) {
-		const parsed = InteractionResolutionEnvelopeSchema.safeParse(parseJson(body, response, endpoint));
+		const parsed = interactionResolutionResponseSchema.safeParse(parseJson(body, response, endpoint));
 		if (!parsed.success) throw invalidRuntimeResponse("Sidecar returned an invalid interaction resolution", response, endpoint);
 		assertResolutionMatches(parsed.data.resolution, sessionId, submitted, response, endpoint);
 		return parsed.data.resolution;
@@ -1037,277 +1067,558 @@ function collectAgentFinalMessageText(events) {
 	return composed.trim().length > 0 ? composed : void 0;
 }
 //#endregion
-//#region src/interactive.ts
-/**
-* Handle for one session's interactive harness. Obtained via
-* `box.session(id).interactive()`; does not hit the network until a method is
-* called.
-*/
-var InteractiveSessionHandle = class {
-	constructor(host, sessionId) {
+//#region ../../../packages/runtime-contracts/dist/interactive-session-http.js
+const runningStatusSchema = AgentInteractiveSessionStatusSchema.options[0];
+const exitedStatusSchema = AgentInteractiveSessionStatusSchema.options[1];
+/** Start result for one exact interactive process. */
+const interactiveSessionStartDataSchema = z.discriminatedUnion("state", [runningStatusSchema.extend({
+	control: AgentInteractiveSessionControlClaimSchema$1,
+	streamUrl: z.string().min(1)
+}).strict(), exitedStatusSchema.extend({ control: AgentInteractiveSessionControlClaimSchema$1 }).strict()]);
+const interactiveSessionStartResponseSchema = z.object({
+	success: z.literal(true),
+	data: interactiveSessionStartDataSchema
+}).strict();
+z.object({
+	success: z.literal(false),
+	error: z.object({
+		code: z.string().min(1),
+		message: z.string().min(1)
+	}).strict()
+}).strict();
+const interactiveSessionPromptResponseSchema = z.object({
+	success: z.literal(true),
+	data: AgentInteractiveSessionPromptAcknowledgementSchema$1
+}).strict();
+const interactiveSessionStopResponseSchema = z.object({
+	success: z.literal(true),
+	data: AgentInteractiveSessionStopAcknowledgementSchema$1
+}).strict();
+z.object({ ref: AgentInteractiveSessionRefSchema$1 }).strict();
+z.object({ incarnationId: AgentInteractiveSessionRefSchema$1.shape.incarnationId }).strict();
+//#endregion
+//#region src/sandbox-interactive-operations.ts
+function assertInteractiveRefBelongsToSandbox(ref, sandboxId) {
+	if (ref.run.environmentId !== sandboxId) throw new ValidationError("Interactive session reference does not belong to this sandbox", { "ref.run.environmentId": `Expected ${sandboxId}` });
+}
+var SandboxInteractiveOperations = class {
+	constructor(host) {
 		this.host = host;
-		this.sessionId = sessionId;
 	}
-	/**
-	* 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) {
-		return this.host._startInteractive(this.sessionId, options);
+	/** @internal — invoked by InteractiveSessionHandle.start(). */
+	async _startInteractive(id, options, requestOptions) {
+		requestOptions?.signal?.throwIfAborted();
+		const exactStart = exactAgentInteractiveSessionStart(options);
+		if (!exactStart.profile.harness) throw new ValidationError("Interactive profile harness is required");
+		assertCurrentBackendType(exactStart.profile.harness, "profile.harness");
+		if (exactStart.run.sessionId !== id) throw new ValidationError("Interactive start request does not belong to the session");
+		if (exactStart.run.environmentId !== this.host.id) throw new ValidationError("Interactive start request does not belong to this sandbox");
+		await this.host.ensureRunning(requestOptions?.signal);
+		const response = await this.host.runtimeFetch(`/agents/sessions/${encodeURIComponent(id)}/interactive`, {
+			method: "POST",
+			body: JSON.stringify(exactStart),
+			...requestOptions?.signal === void 0 ? {} : { signal: requestOptions.signal }
+		});
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+		const endpoint = `/agents/sessions/${encodeURIComponent(id)}/interactive`;
+		const parsed = interactiveSessionStartResponseSchema.safeParse(await response.json());
+		if (!parsed.success) throw new ServerError("Interactive session response has an invalid exact identity", 502, {
+			endpoint,
+			origin: "runtime"
+		});
+		const result = parsed.data.data;
+		if (!agentInteractiveSessionRefMatchesStart(exactStart, result.ref) || !agentInteractiveSessionControlClaimMatchesRef(result.ref, result.control)) throw new ServerError("Interactive session response has an invalid exact identity", 502, {
+			endpoint,
+			origin: "runtime"
+		});
+		return result;
 	}
-	/** Inject a prompt as keystrokes into the live harness (submitted on send). */
-	sendPrompt(prompt) {
-		return this.host._sendInteractivePrompt(this.sessionId, prompt);
+	/** @internal — invoked by InteractiveSessionHandle.sendPrompt(). */
+	async _sendInteractivePrompt(id, command, options) {
+		options?.signal?.throwIfAborted();
+		const exactCommand = AgentInteractiveSessionPromptCommandSchema.parse(command);
+		if (exactCommand.ref.run.sessionId !== id) throw new ValidationError("Interactive prompt command does not belong to the session");
+		await this.host.ensureRunning(options?.signal);
+		const status = await this._interactiveStatus(id, exactCommand.ref.incarnationId, options);
+		if (!status) throw new NotFoundError("Interactive session", id, {
+			origin: "runtime",
+			endpoint: `/agents/sessions/${encodeURIComponent(id)}/interactive`
+		});
+		if (canonicalCandidateDigest(status.ref) !== canonicalCandidateDigest(exactCommand.ref)) throw new ValidationError("Interactive prompt ref or control does not match the session");
+		const endpoint = `/agents/sessions/${encodeURIComponent(id)}/interactive/prompt`;
+		const response = await this.host.runtimeFetch(endpoint, {
+			method: "POST",
+			body: JSON.stringify(exactCommand),
+			...options?.signal === void 0 ? {} : { signal: options.signal }
+		});
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+		const parsed = interactiveSessionPromptResponseSchema.safeParse(await response.json());
+		if (!parsed.success) throw new ServerError("Interactive prompt acknowledgement is invalid", 502, {
+			endpoint,
+			origin: "runtime"
+		});
+		const acknowledgement = parsed.data.data;
+		if (!agentInteractiveSessionPromptAcknowledgementMatchesCommand(exactCommand, acknowledgement)) throw new ServerError("Interactive prompt acknowledgement does not match the command", 502, {
+			endpoint,
+			origin: "runtime"
+		});
+		return acknowledgement;
 	}
-	/**
-	* 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) {
-		if (!this.host._attachInteractive) return Promise.reject(/* @__PURE__ */ new Error("Interactive session attach is not supported by this host"));
-		return this.host._attachInteractive(this.sessionId, options);
+	/** @internal — invoked by InteractiveSessionHandle.claimControl(). */
+	async _claimInteractiveControl(id, request, options) {
+		options?.signal?.throwIfAborted();
+		const exactRequest = AgentInteractiveSessionControlClaimRequestSchema.parse(request);
+		if (exactRequest.ref.run.sessionId !== id) throw new ValidationError("Interactive control claim does not belong to the session");
+		assertInteractiveRefBelongsToSandbox(exactRequest.ref, this.host.id);
+		await this.host.ensureRunning(options?.signal);
+		options?.signal?.throwIfAborted();
+		const endpoint = `/agents/sessions/${encodeURIComponent(id)}/interactive/control`;
+		const response = await this.host.runtimeFetch(endpoint, {
+			method: "POST",
+			body: JSON.stringify(exactRequest),
+			...options?.signal === void 0 ? {} : { signal: options.signal }
+		});
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+		const parsed = interactiveSessionControlClaimResponseSchema.safeParse(await response.json());
+		if (!parsed.success) throw new ServerError("Interactive control claim acknowledgement is invalid", 502, {
+			endpoint,
+			origin: "runtime"
+		});
+		const acknowledgement = parsed.data.data;
+		if (!agentInteractiveSessionControlClaimAcknowledgementMatchesRequest(exactRequest, acknowledgement)) throw new ServerError("Interactive control claim acknowledgement does not match the request", 502, {
+			endpoint,
+			origin: "runtime"
+		});
+		return acknowledgement;
 	}
-	/**
-	* 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() {
-		if (!this.host._interactiveStatus) return Promise.reject(/* @__PURE__ */ new Error("Interactive session status is not supported by this host"));
-		return this.host._interactiveStatus(this.sessionId);
+	/** @internal — invoked by the interactive attach controller on cleanup. */
+	async _releaseInteractiveControl(id, ref, control, options) {
+		options?.signal?.throwIfAborted();
+		const exactRef = AgentInteractiveSessionRefSchema.parse(ref);
+		const exactControl = AgentInteractiveSessionControlClaimSchema.parse(control);
+		if (exactRef.run.sessionId !== id) throw new ValidationError("Interactive control release does not belong to the session");
+		assertInteractiveRefBelongsToSandbox(exactRef, this.host.id);
+		if (!agentInteractiveSessionControlClaimMatchesRef(exactRef, exactControl)) throw new ValidationError("Interactive control release does not match the session ref");
+		const endpoint = `/agents/sessions/${encodeURIComponent(id)}/interactive/control/release`;
+		const response = await this.host.runtimeFetch(endpoint, {
+			method: "POST",
+			body: JSON.stringify({
+				ref: exactRef,
+				control: exactControl
+			}),
+			...options?.signal === void 0 ? {} : { signal: options.signal }
+		});
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+		if (!interactiveSessionControlReleaseResponseSchema.safeParse(await response.json()).success) throw new ServerError("Interactive control release response is invalid", 502, {
+			endpoint,
+			origin: "runtime"
+		});
+	}
+	/** @internal — invoked by InteractiveSessionHandle.status(). */
+	async _interactiveStatus(id, incarnationId, options) {
+		options?.signal?.throwIfAborted();
+		await this.host.ensureRunning(options?.signal);
+		const endpoint = `/agents/sessions/${encodeURIComponent(id)}/interactive`;
+		const response = await this.host.runtimeFetch(`${endpoint}?incarnationId=${encodeURIComponent(incarnationId)}`, {
+			method: "GET",
+			...options?.signal === void 0 ? {} : { signal: options.signal }
+		});
+		if (response.status === 404) return null;
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+		const parsed = interactiveSessionStatusResponseSchema.safeParse(await response.json());
+		if (!parsed.success) throw new ServerError("Interactive status response has an invalid exact identity", 502, {
+			endpoint,
+			origin: "runtime"
+		});
+		const status = parsed.data.data.status;
+		if (status.ref.run.sessionId !== id || status.ref.incarnationId !== incarnationId) throw new ServerError("Interactive status response has an invalid exact identity", 502, {
+			endpoint,
+			origin: "runtime"
+		});
+		assertInteractiveRefBelongsToSandbox(status.ref, this.host.id);
+		return status;
+	}
+	/** @internal — invoked by InteractiveSessionHandle.stop(). */
+	async _stopInteractive(id, command, options) {
+		options?.signal?.throwIfAborted();
+		const exactCommand = AgentInteractiveSessionStopCommandSchema.parse(command);
+		if (exactCommand.ref.run.sessionId !== id) throw new ValidationError("Interactive stop command does not belong to the session");
+		assertInteractiveRefBelongsToSandbox(exactCommand.ref, this.host.id);
+		await this.host.ensureRunning(options?.signal);
+		const endpoint = `/agents/sessions/${encodeURIComponent(id)}/interactive`;
+		const response = await this.host.runtimeFetch(endpoint, {
+			method: "DELETE",
+			body: JSON.stringify(exactCommand),
+			...options?.signal === void 0 ? {} : { signal: options.signal }
+		});
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+		const parsed = interactiveSessionStopResponseSchema.safeParse(await response.json());
+		if (!parsed.success) throw new ServerError("Interactive stop acknowledgement is invalid", 502, {
+			endpoint,
+			origin: "runtime"
+		});
+		const acknowledgement = parsed.data.data;
+		if (!agentInteractiveSessionStopAcknowledgementMatchesCommand(exactCommand, acknowledgement)) throw new ServerError("Interactive stop acknowledgement does not match the command", 502, {
+			endpoint,
+			origin: "runtime"
+		});
+		return acknowledgement;
 	}
-	/** Stop the interactive harness and reap its PTY. */
-	stop() {
-		return this.host._stopInteractive(this.sessionId);
+	/** @internal — lifecycle authority for exact provider teardown. */
+	async _stopInteractiveLifecycle(id, ref, options) {
+		options?.signal?.throwIfAborted();
+		const exactRef = AgentInteractiveSessionRefSchema.parse(ref);
+		if (exactRef.run.sessionId !== id) throw new ValidationError("Interactive lifecycle stop reference does not belong to the session");
+		assertInteractiveRefBelongsToSandbox(exactRef, this.host.id);
+		await this.host.ensureRunning(options?.signal);
+		const endpoint = `/agents/sessions/${encodeURIComponent(id)}/interactive/lifecycle`;
+		const response = await this.host.runtimeFetch(endpoint, {
+			method: "DELETE",
+			body: JSON.stringify({ ref: exactRef }),
+			...options?.signal === void 0 ? {} : { signal: options.signal }
+		});
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+		const parsed = interactiveSessionStopResponseSchema.safeParse(await response.json());
+		if (!parsed.success) throw new ServerError("Interactive lifecycle stop acknowledgement is invalid", 502, {
+			endpoint,
+			origin: "runtime"
+		});
+		const acknowledgement = parsed.data.data;
+		if (canonicalCandidateDigest(acknowledgement.ref) !== canonicalCandidateDigest(exactRef)) throw new ServerError("Interactive lifecycle stop acknowledgement does not match the exact ref", 502, {
+			endpoint,
+			origin: "runtime"
+		});
+		return acknowledgement;
 	}
 };
 //#endregion
-//#region src/session.ts
-/**
-* A single agent session inside a sandbox. Created via
-* `box.session(id)` — does not hit the network until a method is called.
-*/
-var SandboxSession = class SandboxSession {
-	/**
-	* @internal SDK-internal constructor — apps should call `box.session(id)`.
-	*/
-	constructor(box, id) {
-		this.box = box;
-		this.id = id;
+//#region src/scoped-token.ts
+/** Maximum time for the exact interactive terminal-token request. */
+const SCOPED_TOKEN_REQUEST_TIMEOUT_MS = 5e3;
+const scopedTokenResponseSchema = z.object({
+	token: z.string().min(1),
+	expiresAt: z.number().finite().nonnegative(),
+	runtimeUrl: z.string().min(1),
+	sidecarProxyUrl: z.string().min(1),
+	scope: z.enum([
+		"session",
+		"session-runtime",
+		"project",
+		"read-only"
+	])
+});
+/** Reject a scoped credential that the SDK must not send to a consumer. */
+function assertScopedTokenActive(token, expectedScope) {
+	if (expectedScope !== void 0 && token.scope !== expectedScope) throw new ValidationError(`Scoped token must use the ${expectedScope} scope`);
+	if (typeof token.token !== "string" || !token.token.trim() || !(token.expiresAt instanceof Date) || !Number.isFinite(token.expiresAt.getTime()) || token.expiresAt.getTime() <= Date.now()) throw new ValidationError("Scoped token is expired or invalid");
+}
+function parseScopedTokenResponse(raw, expectedScope) {
+	const parsed = scopedTokenResponseSchema.safeParse(raw);
+	if (!parsed.success) throw new ServerError("Sandbox API returned an invalid scoped token response.", 502, { origin: "sandbox-api" });
+	if (parsed.data.scope !== expectedScope) throw new ServerError(`Sandbox API returned a ${parsed.data.scope} token for a ${expectedScope} request.`, 502, { origin: "sandbox-api" });
+	const token = {
+		token: parsed.data.token,
+		expiresAt: /* @__PURE__ */ new Date(parsed.data.expiresAt * 1e3),
+		runtimeUrl: parsed.data.runtimeUrl,
+		sidecarProxyUrl: parsed.data.sidecarProxyUrl,
+		scope: parsed.data.scope
+	};
+	try {
+		assertScopedTokenActive(token, expectedScope);
+	} catch {
+		throw new ServerError("Sandbox API returned an expired or invalid scoped token.", 502, { origin: "sandbox-api" });
 	}
-	/**
-	* Fetch the current session state from the sandbox. Includes status,
-	* model, prompt count, token usage if known, and timing metadata.
-	*
-	* Throws on transport error; returns `null` if the session id is not
-	* known to the sandbox (e.g. it ended and was reaped, or the id is
-	* invalid).
-	*/
-	async status() {
-		return this.box._sessionStatus(this.id);
+	return token;
+}
+async function requestScopedToken(client, sandboxId, options, requestOptions) {
+	if ((options.scope === "session" || options.scope === "session-runtime") && !options.sessionId) throw new ValidationError(`${options.scope} scope requires a sessionId`);
+	if (options.scope === "session" && !options.runtimeSessionId) throw new ValidationError("session scope requires the actual runtimeSessionId");
+	const response = await client.fetch(`/v1/sandboxes/${encodeURIComponent(sandboxId)}/scoped-token`, {
+		method: "POST",
+		headers: { "Content-Type": "application/json" },
+		body: JSON.stringify({
+			scope: options.scope,
+			...options.sessionId ? { sessionId: options.sessionId } : {},
+			...options.scope === "session" ? { runtimeSessionId: options.runtimeSessionId } : {},
+			...options.ttlMinutes ? { ttlMinutes: options.ttlMinutes } : {}
+		}),
+		...options.signal === void 0 ? {} : { signal: options.signal }
+	}, requestOptions);
+	if (!response.ok) {
+		const body = await response.text();
+		throw parseErrorResponse(response.status, body, void 0, response.headers);
 	}
-	/**
-	* Stream events from this session as they arrive. With no `since`,
-	* starts at the live tail; with `since`, replays strictly after that
-	* event id — useful for reconnect-after-disconnect flows.
-	*
-	* The async iterator terminates when the session reaches a terminal
-	* state (`completed`, `failed`, `cancelled`) and the corresponding
-	* terminal event has been yielded, OR when the caller's signal aborts.
-	*/
-	events(opts) {
-		return this.box._sessionEvents(this.id, opts);
+	let raw;
+	try {
+		raw = await response.json();
+	} catch {
+		throw new ServerError("Sandbox API returned invalid scoped token JSON.", 502, { origin: "sandbox-api" });
 	}
-	/**
-	* Await a terminal result. With `executionId`, drains only that execution;
-	* without it, reads status and selects the latest execution. Event replay
-	* makes either form safe after the execution has already finished.
-	*
-	* Use this to wait for a session that was started by another caller
-	* (e.g. `dispatchPrompt`).
-	*/
-	async result(options) {
-		return options ? this.box._sessionResult(this.id, options) : this.box._sessionResult(this.id);
+	return parseScopedTokenResponse(raw, options.scope);
+}
+function parseInteractiveSessionTokenRef(ref) {
+	const parsed = AgentInteractiveSessionRefSchema.safeParse(ref);
+	if (!parsed.success) throw new ValidationError("Interactive session ref is invalid.", { ref: parsed.error.issues[0]?.message ?? "invalid ref" });
+	return parsed.data;
+}
+function interactiveSessionTokenOptions(ref, options = {}) {
+	const exactRef = parseInteractiveSessionTokenRef(ref);
+	return {
+		sandboxId: exactRef.run.environmentId,
+		request: {
+			scope: "session-runtime",
+			sessionId: exactRef.run.sessionId,
+			...options.ttlMinutes === void 0 ? {} : { ttlMinutes: options.ttlMinutes },
+			...options.signal === void 0 ? {} : { signal: options.signal }
+		}
+	};
+}
+function requestInteractiveSessionToken(client, ref, options) {
+	const exact = interactiveSessionTokenOptions(ref, options);
+	return requestScopedToken(client, exact.sandboxId, exact.request, { timeoutMs: SCOPED_TOKEN_REQUEST_TIMEOUT_MS });
+}
+//#endregion
+//#region src/sandbox-interactive-terminal.ts
+var SandboxInteractiveTerminalOperations = class {
+	constructor(host) {
+		this.host = host;
 	}
 	/**
-	* List persisted messages for this session, including in-flight assistant
-	* content when the runtime has flushed partial output.
+	* 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.
 	*/
-	async messages(opts = {}) {
-		return this.box.messages({
-			...opts,
-			sessionId: this.id
-		});
+	resolveTerminalStreamUrl(sidecarProxyUrl, streamPath) {
+		if (!streamPath.startsWith("/")) throw new ServerError(`Terminal stream path must be sandbox-relative (got "${streamPath}")`, 502, { origin: "runtime" });
+		return `${sidecarProxyUrl.replace(/\/+$/, "")}${streamPath}`;
 	}
-	/**
-	* Continue this session with an additional prompt. Equivalent to
-	* `box.prompt(message, { ...opts, sessionId: this.id })` but reads
-	* naturally on a Session reference.
-	*/
-	async prompt(message, opts) {
-		return this.box.prompt(message, {
-			...opts,
-			sessionId: this.id
+	/** @internal — invoked by InteractiveSessionHandle.attach(). */
+	async _attachInteractive(id, ref, request, options, reconnectAuthority) {
+		options?.signal?.throwIfAborted();
+		const exactRef = AgentInteractiveSessionRefSchema.parse(ref);
+		if (exactRef.run.sessionId !== id) throw new ValidationError("Interactive attach ref does not belong to the session");
+		assertInteractiveRefBelongsToSandbox(exactRef, this.host.id);
+		const { handlers, ...attachRequest } = request;
+		const exactRequest = AgentInteractiveSessionAttachSchema.parse(attachRequest);
+		if (!agentInteractiveSessionControlClaimMatchesRef(exactRef, exactRequest.control)) throw new ValidationError("Interactive attach control does not match the session ref");
+		const status = await this.host.interactiveStatus(id, exactRef.incarnationId, options);
+		if (!status) throw new NotFoundError("Interactive session", id, {
+			origin: "runtime",
+			endpoint: `/agents/sessions/${encodeURIComponent(id)}/interactive`
+		});
+		if (status.state !== "running") throw new StateError(`Interactive session ${id} has exited; there is no live PTY to attach`, status.state, "running", {
+			origin: "runtime",
+			endpoint: `/agents/sessions/${encodeURIComponent(id)}/interactive`
+		}, "INTERACTIVE_SESSION_EXITED");
+		if (canonicalCandidateDigest(status.ref) !== canonicalCandidateDigest(exactRef)) throw new ValidationError("Interactive attach ref does not match the current session");
+		const scoped = await this.host.mintScopedToken({
+			scope: "session-runtime",
+			sessionId: id,
+			...options?.signal === void 0 ? {} : { signal: options.signal }
+		});
+		const stream = await this.host.terminalStreamConnect({
+			url: this.resolveTerminalStreamUrl(scoped.sidecarProxyUrl, `/terminals/${encodeURIComponent(id)}/ws`),
+			token: this.terminalTokenProvider(scoped, id),
+			connectionId: id,
+			cols: exactRequest.cols,
+			rows: exactRequest.rows,
+			incarnationId: exactRef.incarnationId,
+			control: exactRequest.control,
+			handlers,
+			signal: options?.signal,
+			...reconnectAuthority === void 0 ? {} : { reconnectAuthority }
 		});
+		if (options?.signal?.aborted) {
+			await stream.close();
+			options.signal.throwIfAborted();
+		}
+		return stream;
 	}
 	/**
-	* Submit a structured message through the session message endpoint. The
-	* returned receipt confirms admission; follow progress with `events()` or
-	* await the terminal response with `result()`. Model and message identifiers
-	* are translated to the runtime's wire names by the SDK.
+	* 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.
 	*/
-	async sendMessage(request, options) {
-		return this.box._sessionSendMessage(this.id, request, options);
-	}
-	/** Delete this session and its persisted runtime state. */
-	async delete() {
-		return this.box._sessionDelete(this.id);
+	terminalTokenProvider(initialToken, sessionId) {
+		let unused = initialToken;
+		return async (signal) => {
+			signal?.throwIfAborted();
+			if (unused !== null) {
+				const token = unused;
+				unused = null;
+				assertScopedTokenActive(token, "session-runtime");
+				return token;
+			}
+			const scoped = await this.host.mintScopedToken({
+				scope: "session-runtime",
+				sessionId,
+				signal
+			});
+			assertScopedTokenActive(scoped, "session-runtime");
+			return scoped;
+		};
 	}
-	/**
-	* Fork this session into a new queued session. The fork shares the
-	* parent workspace and copies conversation history up to `messageId`
-	* when supplied.
-	*/
-	async fork(opts) {
-		const info = await this.box._sessionFork(this.id, opts);
-		return {
-			session: new SandboxSession(this.box, info.id),
-			info
-		};
-	}
-	/**
-	* Drive this session's harness in INTERACTIVE mode: spawn its native TUI,
-	* stream the live framebuffer, and inject prompts as keystrokes. Distinct
-	* from the headless `prompt()`/`events()` surface above. Lazy — does not hit
-	* the network until a handle method is called.
-	*/
-	interactive() {
-		return new InteractiveSessionHandle(this.box, this.id);
-	}
-	/**
-	* Resolve a pending permission interaction the agent raised mid-turn,
-	* forwarding `allow`/`deny` to the blocked agent through the unified
-	* interaction channel. Throws if no matching permission is outstanding.
-	*/
-	async respondToPermission(permissionID, options) {
-		return this.box._respondToPermission(this.id, permissionID, options);
-	}
-	/** Return every interaction that still awaits a response on this session. */
-	async interactions(options) {
-		return this.box._listInteractions(this.id, options);
-	}
-	/** Respond to one exact interaction with a retry-safe command. */
-	async respondToInteraction(command, options) {
-		return this.box._respondToInteraction(this.id, command, options);
-	}
-	/**
-	* Interrupt an execution without deleting the session. Pass `executionId`
-	* to make the cancellation exact: a newer run on the same session is never
-	* touched. Without it, the current execution is selected. Returns
-	* `{ cancelled: false }` when the selected execution is not running.
-	*/
-	async interrupt(options) {
-		return options ? this.box._interrupt(this.id, options) : this.box._interrupt(this.id);
-	}
-	/**
-	* Cancel one exact run through the durable operation contract. Reusing the
-	* same request after a lost response returns the sidecar's replayed
-	* acknowledgement instead of issuing a second cancellation.
-	*/
-	async cancelRun(request, options) {
-		return this.box._cancelRun(this.id, request, options);
-	}
-	/** Answer one exact question without selecting another outstanding ask. */
-	async answer(interactionId, answers, options) {
-		return this.box._answerQuestion(this.id, interactionId, answers, options);
-	}
-	/** Return the newest plan awaiting a decision for this session. */
-	async plan() {
-		return this.box._currentPlan(this.id);
-	}
-	/** Approve a durable plan and enqueue its separate execution turn. */
-	async approvePlan(planId) {
-		const id = planId ?? (await this.requireCurrentPlan()).id;
-		return this.box._decidePlan(this.id, id, { outcome: "approved" });
-	}
-	/** Reject a durable plan with required feedback and enqueue a revision turn. */
-	async rejectPlan(feedback, planId) {
-		if (!feedback.trim()) throw new Error("Plan rejection feedback is required");
-		const id = planId ?? (await this.requireCurrentPlan()).id;
-		return this.box._decidePlan(this.id, id, {
-			outcome: "rejected",
-			feedback: feedback.trim()
+	/** @internal — invoked by `box.terminals.attach()`. */
+	async _attachTerminal(connectionId, options = {}) {
+		if (!connectionId.trim()) throw new ValidationError("Terminal connectionId is required");
+		const scoped = await this.host.mintScopedToken({
+			scope: "session-runtime",
+			sessionId: connectionId
+		});
+		return this.host.terminalStreamConnect({
+			url: this.resolveTerminalStreamUrl(scoped.sidecarProxyUrl, `/terminals/${encodeURIComponent(connectionId)}/ws`),
+			token: this.terminalTokenProvider(scoped, connectionId),
+			connectionId,
+			cols: options.cols,
+			rows: options.rows,
+			command: options.command,
+			cwd: options.cwd,
+			env: options.env,
+			handlers: options.handlers
 		});
 	}
-	async requireCurrentPlan() {
-		const plan = await this.plan();
-		if (!plan) throw new Error("No durable plan is awaiting a decision");
-		return plan;
-	}
 };
+const TERMINAL_WS_MAX_DIMENSION = 4096;
+/** Input chunk size that leaves room for JSON escaping inside one frame. */
+const TERMINAL_WS_INPUT_FRAME_CHUNK_CHARS = 128 * 1024;
+/** WebSocket authentication envelope prefixes. */
+const TERMINAL_WS_EDGE_BEARER_SUBPROTOCOL_PREFIX = "bearer.";
+const TERMINAL_WS_SIDECAR_BEARER_SUBPROTOCOL_PREFIX = "tangle.bearer.";
+/** Non-credential protocol selected during a successful terminal handshake. */
+const TERMINAL_WS_ECHO_SUBPROTOCOL = "tangle.terminal.v1";
+const terminalGeometry = {
+	cols: z.number().int().min(1).max(TERMINAL_WS_MAX_DIMENSION),
+	rows: z.number().int().min(1).max(TERMINAL_WS_MAX_DIMENSION)
+};
+const terminalInitMessageSchema = z.object({
+	type: z.literal("init"),
+	connectionId: z.string().optional(),
+	/** Required for an interactive-agent PTY; absent for generic terminals. */
+	incarnationId: z.string().uuid().optional(),
+	...terminalGeometry,
+	command: z.string().min(1).optional(),
+	cwd: z.string().min(1).optional(),
+	env: z.record(z.string(), z.string()).optional(),
+	sessionId: z.string().min(1).optional(),
+	/** Canonical control claim for an interactive-agent PTY. */
+	control: AgentInteractiveSessionControlClaimSchema.optional()
+}).superRefine((message, refinement) => {
+	if (message.incarnationId !== void 0 && message.control === void 0) refinement.addIssue({
+		code: "custom",
+		path: ["control"],
+		message: "Interactive session attach requires a control claim"
+	});
+	if (message.incarnationId === void 0 && message.control !== void 0) refinement.addIssue({
+		code: "custom",
+		path: ["control"],
+		message: "Generic terminal attach cannot carry an interactive control claim"
+	});
+});
+const terminalInputMessageSchema = z.object({
+	type: z.literal("input"),
+	data: z.string()
+});
+const terminalResizeMessageSchema = z.object({
+	type: z.literal("resize"),
+	...terminalGeometry
+});
+const terminalRenewMessageSchema = z.object({ type: z.literal("renew") });
+const terminalCloseMessageSchema = z.object({ type: z.literal("close") });
+z.union([
+	terminalInitMessageSchema,
+	terminalInputMessageSchema,
+	terminalResizeMessageSchema,
+	terminalRenewMessageSchema,
+	terminalCloseMessageSchema
+]);
+const terminalReadyMessageSchema = z.object({
+	type: z.literal("ready"),
+	connectionId: z.string(),
+	sessionId: z.string(),
+	restored: z.boolean(),
+	detachTimeoutMs: z.number().int().positive()
+});
+const terminalExitMessageSchema = z.object({
+	type: z.literal("exit"),
+	exitCode: z.number().optional(),
+	exitSignal: z.string().optional()
+});
+const terminalRenewedMessageSchema = z.object({
+	type: z.literal("renewed"),
+	sessionId: z.string()
+});
+const terminalErrorMessageSchema = z.object({
+	type: z.literal("error"),
+	code: z.string(),
+	message: z.string()
+});
+const terminalServerMessageSchema = z.union([
+	terminalReadyMessageSchema,
+	terminalExitMessageSchema,
+	terminalRenewedMessageSchema,
+	terminalErrorMessageSchema
+]);
 //#endregion
-//#region src/tangle/tee-intercept.ts
-/** hono's default unmatched-route body. */
-const HONO_NOT_FOUND_BODY = "404 Not Found";
+//#region src/terminal-stream.ts
 /**
-* A 404 carrying hono's own unmatched-route body came from the router.
+* TerminalStream — typed client for the sandbox terminal WebSocket protocol.
 *
-* hono answers an unmatched route with exactly "404 Not Found", so that body
-* is the deployment saying it has no such route — which for `/tee` means the
-* operator intercept is absent, not that the sandbox is missing.
-* `ensureRunning()` has already confirmed the sandbox at this point, which is
-* what makes the distinction safe to draw.
-*/
-function isRouterNotFound(body) {
-	return body === HONO_NOT_FOUND_BODY;
-}
-/**
-* Request a TEE surface, refusing by name when the deployment cannot serve it.
+* 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 browser-safe wire contract
+* is defined by the shared browser-safe runtime contract and shared with the
+* sidecar:
 *
-* Returns the successful response for the caller to parse. Throws
-* `CapabilityError` when the intercept is absent, and otherwise the same
-* parsed error every other SDK call throws.
+*   client → server (TEXT JSON):
+*     init   {connectionId?, cols, rows, command?, cwd?, env?}  — MUST be first
+*     input  {data}
+*     resize {cols, rows}
+*
+*   Interactive-agent init frames add the exact process authority:
+*     {incarnationId, control: {refDigest, generation, leaseId, holderId, expiresAt}}
+*   Subsequent input and resize frames carry only their operation fields; the
+*   server binds authority to the init for the socket lifetime.
+*   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`.
 */
-async function fetchTeeSurface(client, sandboxId, surface, init) {
-	const path = `/v1/sandboxes/${encodeURIComponent(sandboxId)}/tee/${surface}`;
-	const response = await client.fetch(path, init);
-	if (response.ok) return response;
-	const body = await response.text();
-	if (response.status === 404 && isRouterNotFound(body)) throw new CapabilityError(`TEE ${surface} is not served by this deployment. The /tee paths are answered by a Tangle confidential operator that intercepts them before the sandbox API; a sandbox reached through the public API has no such route. Point the client at the operator, or create the sandbox with driver.type "tangle" on a deployment that fronts it.`, "TEE_UNSUPPORTED", 404, void 0, "tee");
-	throw parseErrorResponse(response.status, body, void 0, response.headers);
-}
-//#endregion
-//#region src/task-session.ts
-/** A background task session with isolated changeset operations. */
-var SandboxTaskSession = class extends SandboxSession {
-	/** @internal Apps should call `box.taskSession(id)`. */
-	constructor(taskBox, id) {
-		super(taskBox, id);
-		this.taskBox = taskBox;
-	}
-	/** Read the task's isolated file changes. */
-	async changes() {
-		return this.taskBox._taskSessionChanges(this.id);
-	}
-	/** Apply all or a selected subset of the task's isolated file changes. */
-	async commit(options) {
-		return this.taskBox._taskSessionCommit(this.id, options);
-	}
-};
-//#endregion
-//#region src/terminal-stream.ts
 /** A protocol `error` control frame or a transport failure. */
 var TerminalStreamError = class extends Error {
 	/** Protocol error code (e.g. `INIT_FAILED`) or `TRANSPORT` for socket faults. */
@@ -1319,38 +1630,17 @@ var TerminalStreamError = class extends Error {
 	}
 };
 /**
-* The sidecar caps WebSocket frames at 1 MiB (`WS_MAX_PAYLOAD_BYTES` in
-* `apps/sidecar/src/routes/terminal-ws.ts`) and drops the connection on
+* The sidecar caps WebSocket frames at 1 MiB
+* (`TERMINAL_WS_MAX_PAYLOAD_BYTES` in the shared runtime contract) and drops
+* the connection on
 * larger frames. `write()` chunks input so every serialized `input` frame
 * stays under that cap: 128 Ki characters per chunk × a worst-case JSON
 * escape expansion of 6 bytes per character (`` etc.) ≈ 768 KiB,
 * comfortably below the limit including the frame's JSON envelope.
 */
-const INPUT_FRAME_CHUNK_CHARS = 128 * 1024;
 const DEFAULT_COLS = 80;
 const DEFAULT_ROWS = 24;
 const DEFAULT_CONNECT_TIMEOUT_MS = 15e3;
-/** Geometry bounds mirrored from the sidecar's init/resize schemas. */
-const MIN_DIMENSION = 1;
-const MAX_DIMENSION = 4096;
-const EDGE_BEARER_SUBPROTOCOL_PREFIX = "bearer.";
-const SIDECAR_BEARER_SUBPROTOCOL_PREFIX = "tangle.bearer.";
-/**
-* 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.
-*/
-const TERMINAL_WS_ECHO_SUBPROTOCOL = "tangle.terminal.v1";
 /**
 * base64url-encode a UTF-8 string without padding — the exact envelope the
 * edge's `parseTerminalWsSubprotocolToken` decodes (its strict round-trip
@@ -1364,19 +1654,56 @@ function base64UrlEncodeUtf8(value) {
 	return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
 }
 function buildAuthSubprotocols(format, token) {
-	if (format === "sidecar-direct") return [`${SIDECAR_BEARER_SUBPROTOCOL_PREFIX}${token}`, TERMINAL_WS_ECHO_SUBPROTOCOL];
-	return [`${EDGE_BEARER_SUBPROTOCOL_PREFIX}${base64UrlEncodeUtf8(token)}`, TERMINAL_WS_ECHO_SUBPROTOCOL];
+	if (format === "sidecar-direct") return [`${TERMINAL_WS_SIDECAR_BEARER_SUBPROTOCOL_PREFIX}${token}`, TERMINAL_WS_ECHO_SUBPROTOCOL];
+	return [`${TERMINAL_WS_EDGE_BEARER_SUBPROTOCOL_PREFIX}${base64UrlEncodeUtf8(token)}`, TERMINAL_WS_ECHO_SUBPROTOCOL];
 }
 /**
 * Resolve the dial credential: invoke a provider (fresh token per dial) or
 * pass a string through. Fails loud on an empty result — a blank credential
 * would dial and be rejected with an opaque 401 downstream.
 */
-async function resolveTerminalToken(token) {
-	const value = typeof token === "function" ? await token() : token;
+async function resolveTerminalToken(token, signal) {
+	const value = typeof token === "function" ? await token(signal) : token;
+	if (typeof value === "object" && value !== null) {
+		try {
+			assertScopedTokenActive(value, "session-runtime");
+		} catch {
+			throw new TerminalStreamError("Terminal stream scoped token is expired or invalid", "INVALID_TOKEN");
+		}
+		return value.token;
+	}
 	if (typeof value !== "string" || !value.trim()) throw new TerminalStreamError(typeof token === "function" ? "Terminal stream token provider returned an empty token" : "Terminal stream token must not be empty", "INVALID_TOKEN");
 	return value;
 }
+function terminalAbortReason(signal) {
+	return signal.reason instanceof Error ? signal.reason : new DOMException("Terminal attach was aborted", "AbortError");
+}
+function awaitTerminalOperation(promise, signal) {
+	if (!signal) return promise;
+	signal.throwIfAborted();
+	return new Promise((resolve, reject) => {
+		let settled = false;
+		const cleanup = () => signal.removeEventListener("abort", onAbort);
+		const onAbort = () => {
+			if (settled) return;
+			settled = true;
+			cleanup();
+			reject(terminalAbortReason(signal));
+		};
+		signal.addEventListener("abort", onAbort, { once: true });
+		promise.then((value) => {
+			if (settled) return;
+			settled = true;
+			cleanup();
+			resolve(value);
+		}, (cause) => {
+			if (settled) return;
+			settled = true;
+			cleanup();
+			reject(cause);
+		});
+	});
+}
 function toWebSocketUrl(url) {
 	let parsed;
 	try {
@@ -1390,7 +1717,48 @@ function toWebSocketUrl(url) {
 	return parsed.toString();
 }
 function assertDimension(name, value) {
-	if (!Number.isInteger(value) || value < MIN_DIMENSION || value > MAX_DIMENSION) throw new TerminalStreamError(`${name} must be an integer in [${MIN_DIMENSION}, ${MAX_DIMENSION}], got ${value}`, "INVALID_DIMENSION");
+	if (!Number.isInteger(value) || value < 1 || value > 4096) throw new TerminalStreamError(`${name} must be an integer in [1, ${TERMINAL_WS_MAX_DIMENSION}], got ${value}`, "INVALID_DIMENSION");
+}
+function normalizeInteractiveSessionIdentity(incarnationId, control) {
+	if (incarnationId === void 0 && control === void 0) return void 0;
+	if (typeof incarnationId !== "string" || incarnationId.length === 0 || incarnationId.trim() !== incarnationId) throw new TerminalStreamError("Interactive terminal attach requires an exact incarnationId", "INVALID_INTERACTIVE_IDENTITY");
+	if (control === void 0) throw new TerminalStreamError("Interactive terminal attach requires an exact control claim", "INVALID_INTERACTIVE_CONTROL");
+	const parsedControl = AgentInteractiveSessionControlClaimSchema.safeParse(control);
+	if (!parsedControl.success) throw new TerminalStreamError("Interactive terminal attach requires an exact control claim", "INVALID_INTERACTIVE_CONTROL");
+	const expiresAt = Date.parse(parsedControl.data.expiresAt);
+	if (!Number.isFinite(expiresAt) || expiresAt <= Date.now()) throw new TerminalStreamError("Interactive terminal control claim is expired", "INTERACTIVE_CONTROL_EXPIRED");
+	return {
+		incarnationId,
+		control: parsedControl.data
+	};
+}
+function interactiveInitFields(identity) {
+	if (identity === void 0) return {};
+	return {
+		incarnationId: identity.incarnationId,
+		control: identity.control
+	};
+}
+function buildTerminalInitMessage(options, identity) {
+	if (typeof options.connectionId !== "string" || !options.connectionId.trim()) throw new TerminalStreamError("Terminal stream connectionId must not be empty", "INVALID_CONNECTION_ID");
+	if (options.cols !== void 0) assertDimension("cols", options.cols);
+	if (options.rows !== void 0) assertDimension("rows", options.rows);
+	const parsed = terminalInitMessageSchema.safeParse({
+		type: "init",
+		connectionId: options.connectionId,
+		cols: options.cols ?? DEFAULT_COLS,
+		rows: options.rows ?? DEFAULT_ROWS,
+		...options.command !== void 0 ? { command: options.command } : {},
+		...options.cwd !== void 0 ? { cwd: options.cwd } : {},
+		...options.env !== void 0 ? { env: options.env } : {},
+		...interactiveInitFields(identity)
+	});
+	if (!parsed.success) throw new TerminalStreamError("Terminal stream init does not match the shared terminal protocol", "INVALID_INIT");
+	return parsed.data;
+}
+function assertInteractiveControlActive(identity) {
+	if (identity === void 0) return;
+	if (Date.parse(identity.control.expiresAt) <= Date.now()) throw new TerminalStreamError("Interactive terminal control claim is expired", "INTERACTIVE_CONTROL_EXPIRED");
 }
 /**
 * Split input so each serialized `input` frame stays under the server's
@@ -1398,13 +1766,13 @@ function assertDimension(name, value) {
 * pair would reach the PTY as two invalid UTF-8 writes).
 */
 function* chunkInput(text) {
-	if (text.length <= INPUT_FRAME_CHUNK_CHARS) {
+	if (text.length <= 131072) {
 		yield text;
 		return;
 	}
 	let index = 0;
 	while (index < text.length) {
-		let end = Math.min(index + INPUT_FRAME_CHUNK_CHARS, text.length);
+		let end = Math.min(index + TERMINAL_WS_INPUT_FRAME_CHUNK_CHARS, text.length);
 		if (end < text.length) {
 			const trailing = text.charCodeAt(end - 1);
 			if (trailing >= 55296 && trailing <= 56319) end -= 1;
@@ -1422,11 +1790,14 @@ function* chunkInput(text) {
 var TerminalStream = class TerminalStream {
 	ws;
 	options;
+	interactiveIdentity;
+	initMessage;
 	handlers;
 	readyInfo = null;
 	closed = false;
 	closeWaiters = [];
 	textDecoder = new TextDecoder();
+	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
@@ -1436,20 +1807,32 @@ var TerminalStream = class TerminalStream {
 	* fresh credential.
 	*/
 	static async connect(options) {
-		return new TerminalStream(options, await resolveTerminalToken(options.token)).establish();
-	}
-	constructor(options, resolvedToken) {
-		if (!options.connectionId.trim()) throw new TerminalStreamError("Terminal stream connectionId must not be empty", "INVALID_CONNECTION_ID");
-		if (options.cols !== void 0) assertDimension("cols", options.cols);
-		if (options.rows !== void 0) assertDimension("rows", options.rows);
+		const interactiveIdentity = normalizeInteractiveSessionIdentity(options.incarnationId, options.control);
+		options.signal?.throwIfAborted();
+		const initMessage = buildTerminalInitMessage(options, interactiveIdentity);
+		const token = await awaitTerminalOperation(resolveTerminalToken(options.token, options.signal), options.signal);
+		options.signal?.throwIfAborted();
+		return new TerminalStream(options, token, interactiveIdentity, initMessage).establish(options.signal);
+	}
+	constructor(options, resolvedToken, interactiveIdentity, initMessage) {
+		const exactOptions = interactiveIdentity === void 0 ? options : {
+			...options,
+			incarnationId: interactiveIdentity.incarnationId,
+			control: interactiveIdentity.control
+		};
 		const WebSocketCtor = globalThis.WebSocket;
 		if (typeof WebSocketCtor !== "function") throw new TerminalStreamError("global WebSocket is unavailable in this environment (Node >= 22 or a browser is required)", "ENVIRONMENT");
-		this.options = options;
-		this.handlers = options.handlers ?? {};
-		this.ws = new WebSocketCtor(toWebSocketUrl(options.url), buildAuthSubprotocols(options.authFormat ?? "edge", resolvedToken));
+		this.options = {
+			...exactOptions,
+			signal: void 0
+		};
+		this.interactiveIdentity = interactiveIdentity;
+		this.initMessage = initMessage;
+		this.handlers = exactOptions.handlers ?? {};
+		this.ws = new WebSocketCtor(toWebSocketUrl(exactOptions.url), buildAuthSubprotocols(exactOptions.authFormat ?? "edge", resolvedToken));
 		this.ws.binaryType = "arraybuffer";
 	}
-	establish() {
+	establish(signal) {
 		return new Promise((resolve, reject) => {
 			let settled = false;
 			const timeoutMs = this.options.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS;
@@ -1457,28 +1840,41 @@ var TerminalStream = class TerminalStream {
 				fail(new TerminalStreamError(`Terminal attach timed out after ${timeoutMs}ms waiting for ready`, "CONNECT_TIMEOUT"));
 				this.ws.close(1e3, "connect timeout");
 			}, timeoutMs);
+			const cleanup = () => {
+				clearTimeout(timer);
+				signal?.removeEventListener("abort", onAbort);
+			};
 			const succeed = () => {
 				if (settled) return;
 				settled = true;
-				clearTimeout(timer);
+				cleanup();
 				resolve(this);
 			};
 			const fail = (error) => {
 				if (settled) return;
 				settled = true;
-				clearTimeout(timer);
+				cleanup();
 				reject(error);
 			};
+			const onAbort = () => {
+				if (!signal) return;
+				fail(terminalAbortReason(signal));
+				this.ws.close(1e3, "connect aborted");
+			};
+			signal?.addEventListener("abort", onAbort, { once: true });
+			if (signal?.aborted) {
+				onAbort();
+				return;
+			}
 			this.ws.addEventListener("open", () => {
-				this.ws.send(JSON.stringify({
-					type: "init",
-					connectionId: this.options.connectionId,
-					cols: this.options.cols ?? DEFAULT_COLS,
-					rows: this.options.rows ?? DEFAULT_ROWS,
-					...this.options.command !== void 0 ? { command: this.options.command } : {},
-					...this.options.cwd !== void 0 ? { cwd: this.options.cwd } : {},
-					...this.options.env !== void 0 ? { env: this.options.env } : {}
-				}));
+				if (settled) return;
+				try {
+					assertInteractiveControlActive(this.interactiveIdentity);
+				} catch (error) {
+					fail(error instanceof TerminalStreamError ? error : new TerminalStreamError("Interactive terminal control claim is expired", "INTERACTIVE_CONTROL_EXPIRED"));
+					return;
+				}
+				this.ws.send(JSON.stringify(this.initMessage));
 			});
 			this.ws.addEventListener("message", (event) => {
 				this.handleMessage(event.data, {
@@ -1499,25 +1895,44 @@ var TerminalStream = class TerminalStream {
 			});
 		});
 	}
-	handleMessage(data, connectPhase) {
-		if (typeof data !== "string") {
-			if (data instanceof ArrayBuffer) this.handlers.onData?.(new Uint8Array(data));
+	handleMessage(raw, connectPhase) {
+		if (typeof raw !== "string") {
+			if (raw instanceof ArrayBuffer) this.handlers.onData?.(new Uint8Array(raw));
 			return;
 		}
-		let message;
+		const failProtocolFrame = () => {
+			const error = new TerminalStreamError("Terminal control frame does not match the shared terminal protocol", "INVALID_FRAME");
+			const beforeReady = !connectPhase.settled();
+			if (this.ws.readyState === WebSocket.OPEN) this.ws.close(1e3, "invalid terminal frame");
+			if (beforeReady) connectPhase.fail(error);
+			else this.handlers.onError?.(error);
+		};
+		let decoded;
 		try {
-			message = JSON.parse(data);
+			decoded = JSON.parse(raw);
 		} catch {
-			this.handlers.onError?.(new TerminalStreamError("Terminal control frame is not valid JSON", "INVALID_FRAME"));
+			failProtocolFrame();
+			return;
+		}
+		if (decoded === null || typeof decoded !== "object" || Array.isArray(decoded) || typeof decoded.type !== "string") {
+			failProtocolFrame();
 			return;
 		}
-		switch (message.type) {
+		const message = decoded;
+		if (message.type === "rec" || message.type === "rec.done") return;
+		if (message.type !== "ready" && message.type !== "exit" && message.type !== "renewed" && message.type !== "error") return;
+		const parsed = terminalServerMessageSchema.safeParse(message);
+		if (!parsed.success) {
+			failProtocolFrame();
+			return;
+		}
+		switch (parsed.data.type) {
 			case "ready": {
 				const info = {
-					connectionId: String(message.connectionId ?? ""),
-					sessionId: String(message.sessionId ?? ""),
-					restored: message.restored === true,
-					detachTimeoutMs: Number(message.detachTimeoutMs ?? 0)
+					connectionId: parsed.data.connectionId,
+					sessionId: parsed.data.sessionId,
+					restored: parsed.data.restored,
+					detachTimeoutMs: parsed.data.detachTimeoutMs
 				};
 				this.readyInfo = info;
 				connectPhase.succeed();
@@ -1526,12 +1941,13 @@ var TerminalStream = class TerminalStream {
 			}
 			case "exit":
 				this.handlers.onExit?.({
-					exitCode: typeof message.exitCode === "number" ? message.exitCode : void 0,
-					exitSignal: typeof message.exitSignal === "string" ? message.exitSignal : void 0
+					exitCode: parsed.data.exitCode,
+					exitSignal: parsed.data.exitSignal
 				});
 				return;
+			case "renewed": return;
 			case "error": {
-				const error = new TerminalStreamError(typeof message.message === "string" ? message.message : "terminal error", typeof message.code === "string" ? message.code : "UNKNOWN");
+				const error = new TerminalStreamError(parsed.data.message, parsed.data.code);
 				if (!connectPhase.settled()) {
 					connectPhase.fail(error);
 					return;
@@ -1539,9 +1955,6 @@ var TerminalStream = class TerminalStream {
 				this.handlers.onError?.(error);
 				return;
 			}
-			case "rec":
-			case "rec.done": return;
-			default: return;
 		}
 	}
 	/** PTY connection id this stream is attached to. */
@@ -1565,56 +1978,600 @@ var TerminalStream = class TerminalStream {
 	*/
 	write(data) {
 		this.assertOpen("write");
+		assertInteractiveControlActive(this.interactiveIdentity);
 		const text = typeof data === "string" ? data : this.textDecoder.decode(data);
 		for (const chunk of chunkInput(text)) this.ws.send(JSON.stringify({
 			type: "input",
 			data: chunk
 		}));
 	}
-	/** Resize the PTY. */
-	resize(cols, rows) {
-		assertDimension("cols", cols);
-		assertDimension("rows", rows);
-		this.assertOpen("resize");
-		this.ws.send(JSON.stringify({
-			type: "resize",
-			cols,
-			rows
-		}));
+	/** Resize the PTY. */
+	resize(cols, rows) {
+		assertDimension("cols", cols);
+		assertDimension("rows", rows);
+		this.assertOpen("resize");
+		assertInteractiveControlActive(this.interactiveIdentity);
+		this.ws.send(JSON.stringify({
+			type: "resize",
+			cols,
+			rows
+		}));
+	}
+	/**
+	* 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() {
+		if (this.closed) return Promise.resolve();
+		return new Promise((resolve) => {
+			this.closeWaiters.push(resolve);
+			this.ws.close(1e3, "client detach");
+		});
+	}
+	/**
+	* 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) {
+		const existing = this.reconnectInFlight;
+		if (existing !== void 0) return awaitTerminalOperation(existing, overrides?.signal);
+		const operation = this.reconnectOnce(overrides);
+		let tracked;
+		tracked = operation.finally(() => {
+			if (this.reconnectInFlight === tracked) this.reconnectInFlight = void 0;
+		});
+		this.reconnectInFlight = tracked;
+		return awaitTerminalOperation(tracked, overrides?.signal);
+	}
+	async reconnectOnce(overrides) {
+		const binding = await this.options.reconnectAuthority?.acquire(overrides?.signal);
+		try {
+			return await TerminalStream.connect({
+				...this.options,
+				...binding === void 0 ? {} : {
+					incarnationId: binding.incarnationId,
+					control: binding.control
+				},
+				token: overrides?.token ?? this.options.token,
+				handlers: this.handlersForReconnect(overrides?.handlers),
+				cols: overrides?.cols ?? this.options.cols,
+				rows: overrides?.rows ?? this.options.rows,
+				signal: overrides?.signal
+			});
+		} catch (error) {
+			try {
+				await binding?.onFailure?.();
+			} catch {}
+			throw error;
+		}
+	}
+	handlersForReconnect(overrides) {
+		const lifecycleHandlers = this.options.handlers;
+		if (overrides === void 0 || lifecycleHandlers?.onClose === void 0) return overrides ?? lifecycleHandlers;
+		return {
+			...overrides,
+			onClose: (code, reason) => {
+				lifecycleHandlers.onClose?.(code, reason);
+				overrides.onClose?.(code, reason);
+			}
+		};
+	}
+	assertOpen(action) {
+		if (!this.isOpen) throw new TerminalStreamError(`Cannot ${action}: terminal stream is not open`, "NOT_OPEN");
+	}
+};
+//#endregion
+//#region src/interactive-controller.ts
+/**
+* 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.
+*/
+var InteractiveSessionController = class extends InteractiveSessionControlController {
+	attachInFlight;
+	constructor(attachTransport, options) {
+		super(attachTransport, options);
+		this.attachTransport = attachTransport;
+	}
+	async attach(request, requestOptions) {
+		requestOptions?.signal?.throwIfAborted();
+		if (this.attachInFlight !== void 0) return await awaitWithAbort(this.attachInFlight, requestOptions?.signal);
+		const operation = (async () => {
+			const identity = await this.resolve(requestOptions);
+			return this.attachWithIdentity(identity, request, requestOptions);
+		})();
+		let tracked;
+		tracked = operation.finally(() => {
+			if (this.attachInFlight === tracked) this.attachInFlight = void 0;
+		});
+		this.attachInFlight = tracked;
+		return await tracked;
+	}
+	/**
+	* Open a stream for a claim returned by this controller's `resolve()`.
+	* The controller releases that claim when the stream cannot be opened.
+	*/
+	async attachWithIdentity(identity, request, requestOptions) {
+		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");
+		let activeIdentity = {
+			ref: exactRef,
+			control: identity.control
+		};
+		const releasePromises = /* @__PURE__ */ new WeakMap();
+		const releaseClaim = (target) => {
+			const existing = releasePromises.get(target);
+			if (existing !== void 0) return existing;
+			const release = this.safelyReleaseClaim(target);
+			releasePromises.set(target, release);
+			return release;
+		};
+		let reconnectInFlight;
+		const reconnectAuthority = { acquire: async (signal) => {
+			if (!releasePromises.has(activeIdentity)) throw new Error("Interactive terminal must be closed before reconnecting");
+			if (reconnectInFlight !== void 0) return await awaitWithAbort(reconnectInFlight, signal);
+			const operation = (async () => {
+				const next = await this.resolve({ signal });
+				const nextRef = AgentInteractiveSessionRefSchema.parse(next.ref);
+				assertInteractiveSessionRef(nextRef, this.options);
+				const nextIdentity = {
+					ref: nextRef,
+					control: next.control
+				};
+				activeIdentity = nextIdentity;
+				return {
+					incarnationId: nextRef.incarnationId,
+					control: next.control,
+					onFailure: () => releaseClaim(nextIdentity)
+				};
+			})();
+			let tracked;
+			tracked = operation.finally(() => {
+				if (reconnectInFlight === tracked) reconnectInFlight = void 0;
+			});
+			reconnectInFlight = tracked;
+			return await tracked;
+		} };
+		try {
+			requestOptions?.signal?.throwIfAborted();
+			const callerHandlers = request.handlers;
+			const exactRequest = {
+				...request,
+				control: identity.control,
+				handlers: {
+					...callerHandlers,
+					onClose: (code, reason) => {
+						releaseClaim(activeIdentity);
+						callerHandlers?.onClose?.(code, reason);
+					}
+				}
+			};
+			const stream = await this.attachTransport.attach(this.options.sessionId, exactRef, exactRequest, requestOptions, reconnectAuthority);
+			if (requestOptions?.signal?.aborted) {
+				await stream.close();
+				requestOptions.signal.throwIfAborted();
+			}
+			return stream;
+		} catch (error) {
+			await releaseClaim(activeIdentity);
+			throw error;
+		}
+	}
+};
+function browserTransport(options) {
+	return {
+		...createBrowserInteractiveSessionControlTransport(options),
+		async attach(sessionId, ref, request, requestOptions, reconnectAuthority) {
+			requestOptions?.signal?.throwIfAborted();
+			if (options.terminalTokenProvider === void 0) throw new Error("Browser interactive terminal attach requires terminalTokenProvider");
+			const exactRef = AgentInteractiveSessionRefSchema.parse(ref);
+			const { handlers, ...wireRequest } = request;
+			const { control, ...terminalRequest } = AgentInteractiveSessionAttachSchema.parse(wireRequest);
+			const terminalOptions = {
+				url: browserInteractiveTerminalEndpoint(options.sessionApiUrl, sessionId),
+				token: options.terminalTokenProvider,
+				connectionId: sessionId,
+				...terminalRequest,
+				incarnationId: exactRef.incarnationId,
+				control,
+				authFormat: "edge",
+				signal: requestOptions?.signal,
+				...reconnectAuthority === void 0 ? {} : { reconnectAuthority },
+				...handlers === void 0 ? {} : { handlers }
+			};
+			requestOptions?.signal?.throwIfAborted();
+			const stream = await TerminalStream.connect(terminalOptions);
+			if (requestOptions?.signal?.aborted) {
+				await stream.close();
+				requestOptions.signal.throwIfAborted();
+			}
+			return stream;
+		}
+	};
+}
+/** Concrete controller for browser deep links and terminal attachment. */
+var BrowserInteractiveSessionController = class extends InteractiveSessionController {
+	constructor(options) {
+		super(browserTransport(options), options);
+	}
+};
+//#endregion
+//#region src/interactive.ts
+/**
+* Exact native coding-agent sessions on the public SDK.
+*
+* Agent Interface owns the wire contracts. The SDK only adds local stream
+* handlers and binds the returned ref/control to a convenient session handle.
+*/
+function createInteractiveSessionController(host, sessionId, ref, holderId) {
+	const releaseInteractiveControl = host._releaseInteractiveControl;
+	return new InteractiveSessionController({
+		status: (id, incarnationId, requestOptions) => requestOptions === void 0 ? host._interactiveStatus(id, incarnationId) : host._interactiveStatus(id, incarnationId, requestOptions),
+		claimControl: (id, claimRequest, requestOptions) => host._claimInteractiveControl(id, claimRequest, requestOptions),
+		attach: (id, attachRef, attachRequest, requestOptions, reconnectAuthority) => {
+			if (reconnectAuthority === void 0) return requestOptions === void 0 ? host._attachInteractive(id, attachRef, attachRequest) : host._attachInteractive(id, attachRef, attachRequest, requestOptions);
+			return host._attachInteractive(id, attachRef, attachRequest, requestOptions, reconnectAuthority);
+		},
+		releaseControl: (id, releaseRef, control, requestOptions) => requestOptions === void 0 ? releaseInteractiveControl(id, releaseRef, control) : releaseInteractiveControl(id, releaseRef, control, requestOptions)
+	}, {
+		sessionId,
+		incarnationId: ref.incarnationId,
+		environmentId: ref.run.environmentId,
+		holderId
+	});
+}
+/**
+* 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.
+*/
+var InteractiveSessionHandle = class {
+	ref;
+	control;
+	attachHolderId = createInteractiveControlHolderId("sdk");
+	attachController;
+	attachInFlight;
+	constructor(host, sessionId, options = {}) {
+		this.host = host;
+		this.sessionId = sessionId;
+		this.ref = options.ref;
+		this.control = options.control;
+	}
+	start(options, requestOptions) {
+		requestOptions?.signal?.throwIfAborted();
+		const exactStart = AgentInteractiveSessionStartSchema.parse(options);
+		if (exactStart.run.sessionId !== this.sessionId) throw new Error(`Interactive session ${this.sessionId} start is bound to session ${exactStart.run.sessionId}`);
+		return (requestOptions === void 0 ? this.host._startInteractive(this.sessionId, exactStart) : this.host._startInteractive(this.sessionId, exactStart, requestOptions)).then((info) => {
+			const ref = AgentInteractiveSessionRefSchema.parse(info.ref);
+			const control = AgentInteractiveSessionControlClaimSchema.parse(info.control);
+			if (!agentInteractiveSessionRefMatchesStart(exactStart, ref) || !agentInteractiveSessionControlClaimMatchesRef(ref, control)) throw new Error(`Interactive session ${this.sessionId} start returned an inexact ref or control claim`);
+			const exactInfo = {
+				...info,
+				ref,
+				control
+			};
+			this.ref = ref;
+			this.control = control;
+			this.attachController = void 0;
+			return exactInfo;
+		});
+	}
+	requireBinding() {
+		const ref = this.requireRef();
+		if (!this.control) throw new Error(`Interactive session ${this.sessionId} handle is not bound to an exact ref and control claim`);
+		const control = AgentInteractiveSessionControlClaimSchema.parse(this.control);
+		if (!agentInteractiveSessionControlClaimMatchesRef(ref, control)) throw new Error(`Interactive session ${this.sessionId} handle is not bound to a control claim for its exact ref`);
+		return {
+			ref,
+			control
+		};
+	}
+	requireRef() {
+		if (!this.ref) throw new Error(`Interactive session ${this.sessionId} handle is not bound to an exact ref`);
+		const ref = AgentInteractiveSessionRefSchema.parse(this.ref);
+		if (ref.run.sessionId !== this.sessionId) throw new Error(`Interactive session ${this.sessionId} handle is bound to session ${ref.run.sessionId}`);
+		return ref;
+	}
+	sendPrompt(command, options) {
+		options?.signal?.throwIfAborted();
+		const binding = this.requireBinding();
+		const exactCommand = AgentInteractiveSessionPromptCommandSchema.parse(command);
+		if (canonicalCandidateDigest(exactCommand.ref) !== canonicalCandidateDigest(binding.ref) || canonicalCandidateDigest(exactCommand.control) !== canonicalCandidateDigest(binding.control)) throw new Error(`Interactive session ${this.sessionId} prompt is bound to a different exact ref`);
+		return (options === void 0 ? this.host._sendInteractivePrompt(this.sessionId, exactCommand) : this.host._sendInteractivePrompt(this.sessionId, exactCommand, options)).then((acknowledgement) => {
+			const exactAcknowledgement = AgentInteractiveSessionPromptAcknowledgementSchema.parse(acknowledgement);
+			if (!agentInteractiveSessionPromptAcknowledgementMatchesCommand(exactCommand, exactAcknowledgement)) throw new Error(`Interactive session ${this.sessionId} prompt acknowledgement does not match the command`);
+			return exactAcknowledgement;
+		});
+	}
+	attach(request = {}, options) {
+		options?.signal?.throwIfAborted();
+		if (this.attachInFlight !== void 0) return awaitWithAbort(this.attachInFlight, options?.signal);
+		const ref = this.requireRef();
+		let controller = this.attachController;
+		if (controller === void 0) {
+			controller = createInteractiveSessionController(this.host, this.sessionId, ref, this.attachHolderId);
+			this.attachController = controller;
+		}
+		const operation = controller.resolve(options).then(async (identity) => {
+			const stream = await controller.attachWithIdentity(identity, request, options);
+			this.ref = identity.ref;
+			this.control = identity.control;
+			return stream;
+		});
+		let tracked;
+		tracked = operation.finally(() => {
+			if (this.attachInFlight === tracked) this.attachInFlight = void 0;
+		});
+		this.attachInFlight = tracked;
+		return tracked;
+	}
+	status(options) {
+		options?.signal?.throwIfAborted();
+		const ref = this.requireRef();
+		return (options === void 0 ? this.host._interactiveStatus(this.sessionId, ref.incarnationId) : this.host._interactiveStatus(this.sessionId, ref.incarnationId, options)).then((status) => {
+			if (status !== null && !agentInteractiveSessionStatusMatchesRef(ref, status)) throw new Error(`Interactive session ${this.sessionId} status returned an inexact ref`);
+			return status;
+		});
+	}
+	claimControl(request, options) {
+		options?.signal?.throwIfAborted();
+		const ref = this.requireRef();
+		const exactRequest = AgentInteractiveSessionControlClaimRequestSchema.parse(request);
+		if (canonicalCandidateDigest(exactRequest.ref) !== canonicalCandidateDigest(ref)) throw new Error(`Interactive session ${this.sessionId} control claim is bound to a different exact ref`);
+		return this.host._claimInteractiveControl(this.sessionId, exactRequest, options).then((acknowledgement) => {
+			const exactAcknowledgement = AgentInteractiveSessionControlClaimAcknowledgementSchema.parse(acknowledgement);
+			if (!agentInteractiveSessionControlClaimAcknowledgementMatchesRequest(exactRequest, exactAcknowledgement)) throw new Error(`Interactive session ${this.sessionId} control claim acknowledgement does not match the request`);
+			if ((exactAcknowledgement.status === "accepted" || exactAcknowledgement.status === "replayed") && exactAcknowledgement.control) {
+				const current = this.control ? AgentInteractiveSessionControlClaimSchema.parse(this.control) : void 0;
+				if (current === void 0 || agentInteractiveSessionControlClaimIsNewer(exactAcknowledgement.control, current)) this.control = exactAcknowledgement.control;
+			}
+			return exactAcknowledgement;
+		});
+	}
+	stop(command, options) {
+		options?.signal?.throwIfAborted();
+		const binding = this.requireBinding();
+		const exactCommand = AgentInteractiveSessionStopCommandSchema.parse(command);
+		if (canonicalCandidateDigest(exactCommand.ref) !== canonicalCandidateDigest(binding.ref) || canonicalCandidateDigest(exactCommand.control) !== canonicalCandidateDigest(binding.control)) throw new Error(`Interactive session ${this.sessionId} stop is bound to a different exact ref`);
+		return (options === void 0 ? this.host._stopInteractive(this.sessionId, exactCommand) : this.host._stopInteractive(this.sessionId, exactCommand, options)).then((acknowledgement) => {
+			const exactAcknowledgement = AgentInteractiveSessionStopAcknowledgementSchema.parse(acknowledgement);
+			if (!agentInteractiveSessionStopAcknowledgementMatchesCommand(exactCommand, exactAcknowledgement)) throw new Error(`Interactive session ${this.sessionId} stop acknowledgement does not match the command`);
+			return exactAcknowledgement;
+		});
+	}
+	stopLifecycle(options) {
+		options?.signal?.throwIfAborted();
+		const ref = this.requireRef();
+		return (options === void 0 ? this.host._stopInteractiveLifecycle(this.sessionId, ref) : this.host._stopInteractiveLifecycle(this.sessionId, ref, options)).then((acknowledgement) => {
+			const exactAcknowledgement = AgentInteractiveSessionStopAcknowledgementSchema.parse(acknowledgement);
+			if (canonicalCandidateDigest(exactAcknowledgement.ref) !== canonicalCandidateDigest(ref)) throw new Error(`Interactive session ${this.sessionId} lifecycle stop acknowledgement does not match the exact ref`);
+			if (exactAcknowledgement.status !== "accepted" && exactAcknowledgement.status !== "replayed") throw new Error(`Interactive session ${this.sessionId} lifecycle stop was not confirmed (${exactAcknowledgement.status})`);
+			if (exactAcknowledgement.effect === "unknown") throw new Error(`Interactive session ${this.sessionId} lifecycle stop returned an unknown outcome`);
+			return exactAcknowledgement;
+		});
+	}
+};
+//#endregion
+//#region src/session.ts
+/**
+* A single agent session inside a sandbox. Created via
+* `box.session(id)` — does not hit the network until a method is called.
+*/
+var SandboxSession = class SandboxSession {
+	/**
+	* @internal SDK-internal constructor — apps should call `box.session(id)`.
+	*/
+	constructor(box, id) {
+		this.box = box;
+		this.id = id;
+	}
+	/**
+	* Fetch the current session state from the sandbox. Includes status,
+	* model, prompt count, token usage if known, and timing metadata.
+	*
+	* Throws on transport error; returns `null` if the session id is not
+	* known to the sandbox (e.g. it ended and was reaped, or the id is
+	* invalid).
+	*/
+	async status() {
+		return this.box._sessionStatus(this.id);
+	}
+	/**
+	* Stream events from this session as they arrive. With no `since`,
+	* starts at the live tail; with `since`, replays strictly after that
+	* event id — useful for reconnect-after-disconnect flows.
+	*
+	* The async iterator terminates when the session reaches a terminal
+	* state (`completed`, `failed`, `cancelled`) and the corresponding
+	* terminal event has been yielded, OR when the caller's signal aborts.
+	*/
+	events(opts) {
+		return this.box._sessionEvents(this.id, opts);
+	}
+	/**
+	* Await a terminal result. With `executionId`, drains only that execution;
+	* without it, reads status and selects the latest execution. Event replay
+	* makes either form safe after the execution has already finished.
+	*
+	* Use this to wait for a session that was started by another caller
+	* (e.g. `dispatchPrompt`).
+	*/
+	async result(options) {
+		return options ? this.box._sessionResult(this.id, options) : this.box._sessionResult(this.id);
+	}
+	/**
+	* List persisted messages for this session, including in-flight assistant
+	* content when the runtime has flushed partial output.
+	*/
+	async messages(opts = {}) {
+		return this.box.messages({
+			...opts,
+			sessionId: this.id
+		});
+	}
+	/**
+	* Continue this session with an additional prompt. Equivalent to
+	* `box.prompt(message, { ...opts, sessionId: this.id })` but reads
+	* naturally on a Session reference.
+	*/
+	async prompt(message, opts) {
+		return this.box.prompt(message, {
+			...opts,
+			sessionId: this.id
+		});
+	}
+	/**
+	* Submit a structured message through the session message endpoint. The
+	* returned receipt confirms admission; follow progress with `events()` or
+	* await the terminal response with `result()`. Model and message identifiers
+	* are translated to the runtime's wire names by the SDK.
+	*/
+	async sendMessage(request, options) {
+		return this.box._sessionSendMessage(this.id, request, options);
+	}
+	/** Delete this session and its persisted runtime state. */
+	async delete() {
+		return this.box._sessionDelete(this.id);
+	}
+	/**
+	* Fork this session into a new queued session. The fork shares the
+	* parent workspace and copies conversation history up to `messageId`
+	* when supplied.
+	*/
+	async fork(opts) {
+		const info = await this.box._sessionFork(this.id, opts);
+		return {
+			session: new SandboxSession(this.box, info.id),
+			info
+		};
+	}
+	/**
+	* Drive this session's harness in INTERACTIVE mode: spawn its native TUI,
+	* stream the live framebuffer, and inject prompts as keystrokes. Distinct
+	* from the headless `prompt()`/`events()` surface above. Lazy — does not hit
+	* the network until a handle method is called.
+	*/
+	interactive(options = {}) {
+		return new InteractiveSessionHandle(this.box, this.id, options);
+	}
+	/**
+	* Resolve a pending permission interaction the agent raised mid-turn,
+	* forwarding `allow`/`deny` to the blocked agent through the unified
+	* interaction channel. Throws if no matching permission is outstanding.
+	*/
+	async respondToPermission(permissionID, options) {
+		return this.box._respondToPermission(this.id, permissionID, options);
+	}
+	/** Return every interaction that still awaits a response on this session. */
+	async interactions(options) {
+		return this.box._listInteractions(this.id, options);
+	}
+	/** Respond to one exact interaction with a retry-safe command. */
+	async respondToInteraction(command, options) {
+		return this.box._respondToInteraction(this.id, command, options);
 	}
 	/**
-	* 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.
+	* Interrupt an execution without deleting the session. Pass `executionId`
+	* to make the cancellation exact: a newer run on the same session is never
+	* touched. Without it, the current execution is selected. Returns
+	* `{ cancelled: false }` when the selected execution is not running.
 	*/
-	close() {
-		if (this.closed) return Promise.resolve();
-		return new Promise((resolve) => {
-			this.closeWaiters.push(resolve);
-			this.ws.close(1e3, "client detach");
-		});
+	async interrupt(options) {
+		return options ? this.box._interrupt(this.id, options) : this.box._interrupt(this.id);
 	}
 	/**
-	* 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.
+	* Cancel one exact run through the durable operation contract. Reusing the
+	* same request after a lost response returns the sidecar's replayed
+	* acknowledgement instead of issuing a second cancellation.
 	*/
-	reconnect(overrides) {
-		return TerminalStream.connect({
-			...this.options,
-			token: overrides?.token ?? this.options.token,
-			handlers: overrides?.handlers ?? this.options.handlers,
-			cols: overrides?.cols ?? this.options.cols,
-			rows: overrides?.rows ?? this.options.rows
+	async cancelRun(request, options) {
+		return this.box._cancelRun(this.id, request, options);
+	}
+	/** Answer one exact question without selecting another outstanding ask. */
+	async answer(interactionId, answers, options) {
+		return this.box._answerQuestion(this.id, interactionId, answers, options);
+	}
+	/** Return the newest plan awaiting a decision for this session. */
+	async plan() {
+		return this.box._currentPlan(this.id);
+	}
+	/** Approve a durable plan and enqueue its separate execution turn. */
+	async approvePlan(planId) {
+		const id = planId ?? (await this.requireCurrentPlan()).id;
+		return this.box._decidePlan(this.id, id, { outcome: "approved" });
+	}
+	/** Reject a durable plan with required feedback and enqueue a revision turn. */
+	async rejectPlan(feedback, planId) {
+		if (!feedback.trim()) throw new Error("Plan rejection feedback is required");
+		const id = planId ?? (await this.requireCurrentPlan()).id;
+		return this.box._decidePlan(this.id, id, {
+			outcome: "rejected",
+			feedback: feedback.trim()
 		});
 	}
-	assertOpen(action) {
-		if (!this.isOpen) throw new TerminalStreamError(`Cannot ${action}: terminal stream is not open`, "NOT_OPEN");
+	async requireCurrentPlan() {
+		const plan = await this.plan();
+		if (!plan) throw new Error("No durable plan is awaiting a decision");
+		return plan;
+	}
+};
+//#endregion
+//#region src/tangle/tee-intercept.ts
+/** hono's default unmatched-route body. */
+const HONO_NOT_FOUND_BODY = "404 Not Found";
+/**
+* A 404 carrying hono's own unmatched-route body came from the router.
+*
+* hono answers an unmatched route with exactly "404 Not Found", so that body
+* is the deployment saying it has no such route — which for `/tee` means the
+* operator intercept is absent, not that the sandbox is missing.
+* `ensureRunning()` has already confirmed the sandbox at this point, which is
+* what makes the distinction safe to draw.
+*/
+function isRouterNotFound(body) {
+	return body === HONO_NOT_FOUND_BODY;
+}
+/**
+* Request a TEE surface, refusing by name when the deployment cannot serve it.
+*
+* Returns the successful response for the caller to parse. Throws
+* `CapabilityError` when the intercept is absent, and otherwise the same
+* parsed error every other SDK call throws.
+*/
+async function fetchTeeSurface(client, sandboxId, surface, init) {
+	const path = `/v1/sandboxes/${encodeURIComponent(sandboxId)}/tee/${surface}`;
+	const response = await client.fetch(path, init);
+	if (response.ok) return response;
+	const body = await response.text();
+	if (response.status === 404 && isRouterNotFound(body)) throw new CapabilityError(`TEE ${surface} is not served by this deployment. The /tee paths are answered by a Tangle confidential operator that intercepts them before the sandbox API; a sandbox reached through the public API has no such route. Point the client at the operator, or create the sandbox with driver.type "tangle" on a deployment that fronts it.`, "TEE_UNSUPPORTED", 404, void 0, "tee");
+	throw parseErrorResponse(response.status, body, void 0, response.headers);
+}
+//#endregion
+//#region src/task-session.ts
+/** A background task session with isolated changeset operations. */
+var SandboxTaskSession = class extends SandboxSession {
+	/** @internal Apps should call `box.taskSession(id)`. */
+	constructor(taskBox, id) {
+		super(taskBox, id);
+		this.taskBox = taskBox;
+	}
+	/** Read the task's isolated file changes. */
+	async changes() {
+		return this.taskBox._taskSessionChanges(this.id);
+	}
+	/** Apply all or a selected subset of the task's isolated file changes. */
+	async commit(options) {
+		return this.taskBox._taskSessionCommit(this.id, options);
 	}
 };
 //#endregion
@@ -2167,6 +3124,10 @@ var SandboxInstance = class SandboxInstance {
 	defaultRuntimeBackend;
 	runtime;
 	workspaceImages;
+	interactiveOperations;
+	interactiveTerminalOperations;
+	/** @internal Test seam for terminal attach unit tests. */
+	_terminalStreamConnect = (options) => TerminalStream.connect(options);
 	/**
 	* A profile the runtime has cached (create-time priming), letting turns
 	* send `backend.profileSha256` instead of re-shipping the profile's static
@@ -2194,6 +3155,17 @@ var SandboxInstance = class SandboxInstance {
 			fetch: (path, init) => this.runtimeFetch(path, init)
 		});
 		this.workspaceImages = new WorkspaceImages(this.client, this.info.id, () => this.ensureRunning(), () => this.info.filesystemIncarnationId);
+		this.interactiveOperations = new SandboxInteractiveOperations({
+			id: this.info.id,
+			ensureRunning: (signal) => this.ensureRunning(signal),
+			runtimeFetch: (endpoint, request) => this.runtimeFetch(endpoint, request)
+		});
+		this.interactiveTerminalOperations = new SandboxInteractiveTerminalOperations({
+			id: this.info.id,
+			mintScopedToken: (options) => this.mintScopedToken(options),
+			terminalStreamConnect: (options) => this._terminalStreamConnect(options),
+			interactiveStatus: (id, incarnationId, options) => this._interactiveStatus(id, incarnationId, options)
+		});
 	}
 	/** Unique sandbox identifier */
 	get id() {
@@ -2394,15 +3366,16 @@ var SandboxInstance = class SandboxInstance {
 	/**
 	* Refresh sandbox information from the server.
 	*/
-	async refresh() {
+	async refresh(signal) {
+		signal?.throwIfAborted();
 		if (this.refreshInFlight) {
-			await this.refreshInFlight;
+			await awaitWithAbort(this.refreshInFlight, signal);
 			return;
 		}
 		const refresh = this.refreshInfo();
 		this.refreshInFlight = refresh;
 		try {
-			await refresh;
+			await awaitWithAbort(refresh, signal);
 		} finally {
 			if (this.refreshInFlight === refresh) this.refreshInFlight = void 0;
 		}
@@ -2441,7 +3414,7 @@ var SandboxInstance = class SandboxInstance {
 		this.info = {
 			...this.info,
 			metadata: {
-				...this.info.metadata ?? {},
+				...this.info.metadata,
 				teeAttestationJson: JSON.stringify(data.attestation),
 				...data.attestationNonce ? { attestationNonce: data.attestationNonce } : {}
 			}
@@ -2466,7 +3439,7 @@ var SandboxInstance = class SandboxInstance {
 		this.info = {
 			...this.info,
 			metadata: {
-				...this.info.metadata ?? {},
+				...this.info.metadata,
 				teePublicKeyJson: JSON.stringify(data.public_key)
 			}
 		};
@@ -4454,62 +5427,64 @@ var SandboxInstance = class SandboxInstance {
 		return this.createProcessHandle(pid, data.data.command);
 	}
 	createProcessHandle(pid, command) {
-		const self = this;
+		const status = async () => {
+			const response = await this.runtimeFetch(`/process/${pid}`, { method: "GET" });
+			if (!response.ok) {
+				const body = await response.text();
+				throw parseErrorResponse(response.status, body, void 0, response.headers);
+			}
+			const process = (await response.json()).data;
+			return {
+				pid: process.pid,
+				...process.idempotencyKey === void 0 ? {} : { idempotencyKey: process.idempotencyKey },
+				command: process.command,
+				cwd: process.cwd,
+				running: process.running,
+				exitCode: process.exitCode,
+				exitSignal: process.exitSignal,
+				startedAt: new Date(process.startedAt),
+				exitedAt: process.exitedAt ? new Date(process.exitedAt) : void 0
+			};
+		};
+		const kill = async (signal = "SIGTERM", options) => {
+			const response = await this.runtimeFetch(`/process/${pid}`, {
+				method: "DELETE",
+				body: JSON.stringify({
+					signal,
+					...options?.tree === true ? { tree: true } : {}
+				})
+			});
+			if (!response.ok && response.status !== 404) {
+				const body = await response.text();
+				throw parseErrorResponse(response.status, body, void 0, response.headers);
+			}
+		};
+		const logs = async function* (runtimeFetch, parseProcessLogStream) {
+			const response = await runtimeFetch(`/process/${pid}/logs`, { method: "GET" });
+			if (!response.ok) {
+				const body = await response.text();
+				throw parseErrorResponse(response.status, body, void 0, response.headers);
+			}
+			yield* parseProcessLogStream(response);
+		}.bind(void 0, this.runtimeFetch.bind(this), this.parseProcessLogStream.bind(this));
 		return {
 			pid,
 			command,
-			async status() {
-				const response = await self.runtimeFetch(`/process/${pid}`, { method: "GET" });
-				if (!response.ok) {
-					const body = await response.text();
-					throw parseErrorResponse(response.status, body, void 0, response.headers);
-				}
-				const p = (await response.json()).data;
-				return {
-					pid: p.pid,
-					...p.idempotencyKey === void 0 ? {} : { idempotencyKey: p.idempotencyKey },
-					command: p.command,
-					cwd: p.cwd,
-					running: p.running,
-					exitCode: p.exitCode,
-					exitSignal: p.exitSignal,
-					startedAt: new Date(p.startedAt),
-					exitedAt: p.exitedAt ? new Date(p.exitedAt) : void 0
-				};
-			},
+			status,
 			async wait() {
 				while (true) {
-					const s = await this.status();
+					const s = await status();
 					if (!s.running) return s.exitCode;
 					await new Promise((resolve) => setTimeout(resolve, 500));
 				}
 			},
-			async kill(signal = "SIGTERM", options) {
-				const response = await self.runtimeFetch(`/process/${pid}`, {
-					method: "DELETE",
-					body: JSON.stringify({
-						signal,
-						...options?.tree === true ? { tree: true } : {}
-					})
-				});
-				if (!response.ok && response.status !== 404) {
-					const body = await response.text();
-					throw parseErrorResponse(response.status, body, void 0, response.headers);
-				}
-			},
-			async *logs() {
-				const response = await self.runtimeFetch(`/process/${pid}/logs`, { method: "GET" });
-				if (!response.ok) {
-					const body = await response.text();
-					throw parseErrorResponse(response.status, body, void 0, response.headers);
-				}
-				yield* self.parseProcessLogStream(response);
-			},
+			kill,
+			logs,
 			async *stdout() {
-				for await (const entry of this.logs()) if (entry.type === "stdout") yield entry.data;
+				for await (const entry of logs()) if (entry.type === "stdout") yield entry.data;
 			},
 			async *stderr() {
-				for await (const entry of this.logs()) if (entry.type === "stderr") yield entry.data;
+				for await (const entry of logs()) if (entry.type === "stderr") yield entry.data;
 			}
 		};
 	}
@@ -5743,10 +6718,12 @@ var SandboxInstance = class SandboxInstance {
 		if (!statuses.includes(this.status)) return false;
 		return this.status !== "running" || this.filesystemIncarnationReadiness === "ready";
 	}
-	async ensureRunning() {
+	async ensureRunning(signal) {
+		signal?.throwIfAborted();
 		const statusObservedAt = sandboxStatusObservedAt.get(this) ?? 0;
 		const statusAgeMs = Date.now() - statusObservedAt;
-		if (directRuntimeInstances.has(this) || statusObservedAt <= 0 || statusAgeMs < 0 || statusAgeMs >= SANDBOX_STATUS_FRESHNESS_MS) await this.refresh();
+		if (directRuntimeInstances.has(this) || statusObservedAt <= 0 || statusAgeMs < 0 || statusAgeMs >= SANDBOX_STATUS_FRESHNESS_MS) await this.refresh(signal);
+		signal?.throwIfAborted();
 		if (this.status !== "running") throw new StateError(`Sandbox is not running (status: ${this.status})`, this.status, "running");
 		this.assertFilesystemIncarnationReady();
 	}
@@ -6231,31 +7208,7 @@ var SandboxInstance = class SandboxInstance {
 	* while session-runtime/read-only scopes work with SandboxRuntimeClient.
 	*/
 	async mintScopedToken(opts) {
-		if ((opts.scope === "session" || opts.scope === "session-runtime") && !opts.sessionId) throw new ValidationError(`${opts.scope} scope requires a sessionId`);
-		if (opts.scope === "session" && !opts.runtimeSessionId) throw new ValidationError("session scope requires the actual runtimeSessionId");
-		const response = await this.client.fetch(`/v1/sandboxes/${encodeURIComponent(this.id)}/scoped-token`, {
-			method: "POST",
-			headers: { "Content-Type": "application/json" },
-			body: JSON.stringify({
-				scope: opts.scope,
-				...opts.sessionId ? { sessionId: opts.sessionId } : {},
-				...opts.scope === "session" ? { runtimeSessionId: opts.runtimeSessionId } : {},
-				...opts.ttlMinutes ? { ttlMinutes: opts.ttlMinutes } : {}
-			})
-		});
-		if (!response.ok) {
-			const body = await response.text();
-			throw parseErrorResponse(response.status, body, void 0, response.headers);
-		}
-		const data = await response.json();
-		if (typeof data.runtimeUrl !== "string" || typeof data.sidecarProxyUrl !== "string") throw new Error("Scoped token response missing runtime URLs.");
-		return {
-			token: data.token,
-			expiresAt: /* @__PURE__ */ new Date(data.expiresAt * 1e3),
-			runtimeUrl: data.runtimeUrl,
-			sidecarProxyUrl: data.sidecarProxyUrl,
-			scope: data.scope
-		};
+		return requestScopedToken(this.client, this.id, opts);
 	}
 	/** @internal — invoked by SandboxSession.status(). */
 	async _sessionStatus(id) {
@@ -6359,141 +7312,41 @@ var SandboxInstance = class SandboxInstance {
 			costUsd
 		};
 	}
-	/** @internal — invoked by InteractiveSessionHandle.start(). */
-	async _startInteractive(id, options) {
-		assertCurrentBackendType(options.harness, "harness");
-		await this.ensureRunning();
-		const response = await this.runtimeFetch(`/agents/sessions/${encodeURIComponent(id)}/interactive`, {
-			method: "POST",
-			body: JSON.stringify(options)
-		});
-		if (!response.ok) {
-			const body = await response.text();
-			throw parseErrorResponse(response.status, body, void 0, response.headers);
-		}
-		const data = (await response.json())?.data;
-		if (!data || typeof data.sessionId !== "string" || typeof data.streamUrl !== "string") throw new ServerError("Interactive session response missing data", 502, {
-			endpoint: `/agents/sessions/${encodeURIComponent(id)}/interactive`,
-			origin: "runtime"
-		});
-		return data;
+	/** @internal — delegated to the native interactive operations module. */
+	async _startInteractive(id, options, requestOptions) {
+		return this.interactiveOperations._startInteractive(id, options, requestOptions);
 	}
-	/** @internal — invoked by InteractiveSessionHandle.sendPrompt(). */
-	async _sendInteractivePrompt(id, prompt) {
-		await this.ensureRunning();
-		const response = await this.runtimeFetch(`/agents/sessions/${encodeURIComponent(id)}/interactive/prompt`, {
-			method: "POST",
-			body: JSON.stringify({ prompt })
-		});
-		if (!response.ok) {
-			const body = await response.text();
-			throw parseErrorResponse(response.status, body, void 0, response.headers);
-		}
+	/** @internal — delegated to the native interactive operations module. */
+	async _sendInteractivePrompt(id, command, options) {
+		return this.interactiveOperations._sendInteractivePrompt(id, command, options);
 	}
-	/** @internal — invoked by InteractiveSessionHandle.status(). */
-	async _interactiveStatus(id) {
-		await this.ensureRunning();
-		const response = await this.runtimeFetch(`/agents/sessions/${encodeURIComponent(id)}/interactive`, { method: "GET" });
-		if (response.status === 404) return null;
-		if (!response.ok) {
-			const body = await response.text();
-			throw parseErrorResponse(response.status, body, void 0, response.headers);
-		}
-		const data = (await response.json())?.data;
-		if (!data || data.state !== "running" && data.state !== "exited") throw new ServerError("Interactive status response missing data", 502, {
-			endpoint: `/agents/sessions/${encodeURIComponent(id)}/interactive`,
-			origin: "runtime"
-		});
-		return data;
+	/** @internal — delegated to the native interactive operations module. */
+	async _claimInteractiveControl(id, request, options) {
+		return this.interactiveOperations._claimInteractiveControl(id, request, options);
 	}
-	/**
-	* @internal Test seam: unit tests replace this to intercept terminal
-	* WebSocket dials without opening a real socket. Production paths always
-	* go through `TerminalStream.connect`.
-	*/
-	_terminalStreamConnect = (options) => TerminalStream.connect(options);
-	/**
-	* 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.
-	*/
-	resolveTerminalStreamUrl(sidecarProxyUrl, streamPath) {
-		if (!streamPath.startsWith("/")) throw new ServerError(`Terminal stream path must be sandbox-relative (got "${streamPath}")`, 502, { origin: "runtime" });
-		return `${sidecarProxyUrl.replace(/\/+$/, "")}${streamPath}`;
+	/** @internal — delegated to the native interactive operations module. */
+	async _releaseInteractiveControl(id, ref, control, options) {
+		return this.interactiveOperations._releaseInteractiveControl(id, ref, control, options);
 	}
-	/** @internal — invoked by InteractiveSessionHandle.attach(). */
-	async _attachInteractive(id, options = {}) {
-		const status = await this._interactiveStatus(id);
-		if (!status) throw new NotFoundError("Interactive session", id, {
-			origin: "runtime",
-			endpoint: `/agents/sessions/${encodeURIComponent(id)}/interactive`
-		});
-		if (status.state !== "running") throw new StateError(`Interactive session ${id} has exited; there is no live PTY to attach`, status.state, "running", {
-			origin: "runtime",
-			endpoint: `/agents/sessions/${encodeURIComponent(id)}/interactive`
-		}, "INTERACTIVE_SESSION_EXITED");
-		const scoped = await this.mintScopedToken({
-			scope: "session-runtime",
-			sessionId: id
-		});
-		return this._terminalStreamConnect({
-			url: this.resolveTerminalStreamUrl(scoped.sidecarProxyUrl, status.streamUrl),
-			token: this.terminalTokenProvider(scoped.token, id),
-			connectionId: id,
-			cols: options.cols,
-			rows: options.rows,
-			handlers: options.handlers
-		});
+	/** @internal — delegated to the native interactive operations module. */
+	async _interactiveStatus(id, incarnationId, options) {
+		return this.interactiveOperations._interactiveStatus(id, incarnationId, options);
 	}
-	/**
-	* 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.
-	*/
-	terminalTokenProvider(initialToken, sessionId) {
-		let unused = initialToken;
-		return async () => {
-			if (unused !== null) {
-				const token = unused;
-				unused = null;
-				return token;
-			}
-			return (await this.mintScopedToken({
-				scope: "session-runtime",
-				sessionId
-			})).token;
-		};
+	/** @internal — delegated to the native interactive operations module. */
+	async _attachInteractive(id, ref, request, options, reconnectAuthority) {
+		return this.interactiveTerminalOperations._attachInteractive(id, ref, request, options, reconnectAuthority);
 	}
-	/** @internal — invoked by `box.terminals.attach()`. */
+	/** @internal — delegated to the native interactive operations module. */
 	async _attachTerminal(connectionId, options = {}) {
-		if (!connectionId.trim()) throw new ValidationError("Terminal connectionId is required");
-		const scoped = await this.mintScopedToken({
-			scope: "session-runtime",
-			sessionId: connectionId
-		});
-		return this._terminalStreamConnect({
-			url: this.resolveTerminalStreamUrl(scoped.sidecarProxyUrl, `/terminals/${encodeURIComponent(connectionId)}/ws`),
-			token: this.terminalTokenProvider(scoped.token, connectionId),
-			connectionId,
-			cols: options.cols,
-			rows: options.rows,
-			command: options.command,
-			cwd: options.cwd,
-			env: options.env,
-			handlers: options.handlers
-		});
+		return this.interactiveTerminalOperations._attachTerminal(connectionId, options);
 	}
-	/** @internal — invoked by InteractiveSessionHandle.stop(). */
-	async _stopInteractive(id) {
-		await this.ensureRunning();
-		const response = await this.runtimeFetch(`/agents/sessions/${encodeURIComponent(id)}/interactive`, { method: "DELETE" });
-		if (!response.ok && response.status !== 404) {
-			const body = await response.text();
-			throw parseErrorResponse(response.status, body, void 0, response.headers);
-		}
+	/** @internal — delegated to the native interactive operations module. */
+	async _stopInteractive(id, command, options) {
+		return this.interactiveOperations._stopInteractive(id, command, options);
+	}
+	/** @internal — delegated to the native interactive operations module. */
+	async _stopInteractiveLifecycle(id, ref, options) {
+		return this.interactiveOperations._stopInteractiveLifecycle(id, ref, options);
 	}
 	interactionTransport() {
 		return {
@@ -6731,4 +7584,4 @@ function quoteForShell(value) {
 	return `'${value.replace(/'/g, "'\\''")}'`;
 }
 //#endregion
-export { toOtelJson as C, otelTraceIdForTangleTrace as S, getSandboxEventText as _, WorkspaceImages as a, buildTraceExportPayload as b, TERMINAL_WS_ECHO_SUBPROTOCOL as c, SandboxTaskSession as d, SandboxSession as f, collectAgentResponseText as g, collectAgentFinalMessageText as h, normalizeStartupDiagnostics as i, TerminalStream as l, applySandboxEventText as m, createSandboxInstanceFromResponse as n, GPU_LEASE_PROVIDER_NAMES as o, InteractiveSessionHandle as p, normalizeSandboxCreateReceipt as r, MAX_EGRESS_DENIALS_LIMIT as s, SandboxInstance as t, TerminalStreamError as u, isToolBearingEvent as v, parseSSEStream as w, exportTraceBundle as x, normalizeConnection as y };
+export { normalizeConnection as C, toOtelJson as D, otelTraceIdForTangleTrace as E, parseSSEStream as O, isToolBearingEvent as S, exportTraceBundle as T, requestInteractiveSessionToken as _, WorkspaceImages as a, collectAgentResponseText as b, SandboxTaskSession as c, agentInteractiveSessionPromptRequestDigest as d, BrowserInteractiveSessionController as f, TERMINAL_WS_ECHO_SUBPROTOCOL as g, TerminalStreamError as h, normalizeStartupDiagnostics as i, SandboxSession as l, TerminalStream as m, createSandboxInstanceFromResponse as n, GPU_LEASE_PROVIDER_NAMES as o, InteractiveSessionController as p, normalizeSandboxCreateReceipt as r, MAX_EGRESS_DENIALS_LIMIT as s, SandboxInstance as t, InteractiveSessionHandle as u, applySandboxEventText as v, buildTraceExportPayload as w, getSandboxEventText as x, collectAgentFinalMessageText as y };