@tangle-network/sandbox 0.33.1 → 0.34.0

package/dist/{sandbox-sU-uwrYh.js → sandbox-Dg4nXKd9.js}

@@ -2,7 +2,7 @@ import { a as uploadChunked, c as encodePromptForWire, d as applyRequestedModel,
 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 { 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 { AgentExactRunControlRefSchema, AgentInteractiveSessionAttachSchema, AgentInteractiveSessionControlClaimAcknowledgementSchema, AgentInteractiveSessionControlClaimRequestSchema, AgentInteractiveSessionControlClaimSchema, AgentInteractiveSessionPromptAcknowledgementSchema, AgentInteractiveSessionPromptCommandSchema, AgentInteractiveSessionRefSchema, AgentInteractiveSessionStartSchema, AgentInteractiveSessionStopAcknowledgementSchema, AgentInteractiveSessionStopCommandSchema, AgentRunCancellationAcknowledgementSchema, AgentRunCancellationRequestSchema, InteractionAcknowledgementSchema, InteractionBindingSchema, InteractionRequestSchema, InteractionResponseCommandSchema, InteractionResponseSchema, TerminalInputSchema, TerminalOutputEventSchema, TerminalReplayWindowSchema, TerminalResizeSchema, TerminalSessionRefSchema, agentInteractiveSessionControlClaimAcknowledgementMatchesRequest, agentInteractiveSessionControlClaimIsNewer, agentInteractiveSessionControlClaimMatchesRef, agentInteractiveSessionPromptAcknowledgementMatchesCommand, agentInteractiveSessionPromptRequestDigest, agentInteractiveSessionRefMatchesStart, agentInteractiveSessionStatusMatchesRef, agentInteractiveSessionStopAcknowledgementMatchesCommand, agentRunCancellationAcknowledgementMatchesRequest, canonicalCandidateDigest, exactAgentInteractiveSessionStart, sha256DigestSchema, terminalSessionUsable } 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";
@@ -1369,7 +1369,21 @@ const terminalReadyMessageSchema = z.object({
 	connectionId: z.string(),
 	sessionId: z.string(),
 	restored: z.boolean(),
-	detachTimeoutMs: z.number().int().positive()
+	detachTimeoutMs: z.number().int().positive(),
+	/** Exact viewer count held by the runtime for this connection. */
+	attachCount: z.number().int().positive().optional(),
+	/** Server-issued output cursor window for exact interactive terminals. */
+	cursors: z.object({
+		earliest: z.number().int().nonnegative(),
+		latest: z.number().int().nonnegative()
+	}).optional()
+});
+/** One sequenced output frame for an exact interactive terminal. */
+const terminalOutputMessageSchema = z.object({
+	type: z.literal("output"),
+	seq: z.number().int().positive(),
+	/** Base64-encoded UTF-8 bytes from the retained terminal event. */
+	data: z.string().min(1)
 });
 const terminalExitMessageSchema = z.object({
 	type: z.literal("exit"),
@@ -1387,6 +1401,7 @@ const terminalErrorMessageSchema = z.object({
 });
 const terminalServerMessageSchema = z.union([
 	terminalReadyMessageSchema,
+	terminalOutputMessageSchema,
 	terminalExitMessageSchema,
 	terminalRenewedMessageSchema,
 	terminalErrorMessageSchema
@@ -1412,7 +1427,9 @@ const terminalServerMessageSchema = z.union([
 *   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}
+*     ready  {connectionId, sessionId, restored, detachTimeoutMs,
+*             attachCount?, cursors?}
+*     output {seq, data} — exact interactive output as base64 UTF-8 bytes
 *     exit   {exitCode?, exitSignal?}
 *     error  {code, message}
 *     rec / rec.done — recording tee frames for the platform's session
@@ -1528,6 +1545,19 @@ function toWebSocketUrl(url) {
 function assertDimension(name, value) {
 	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");
 }
+/** Decode the sidecar's base64 output frame without a Node-only dependency. */
+function decodeBase64(value) {
+	if (!/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(value)) throw new TerminalStreamError("Terminal output frame is not valid base64", "INVALID_FRAME");
+	let binary;
+	try {
+		binary = atob(value);
+	} catch {
+		throw new TerminalStreamError("Terminal output frame is not valid base64", "INVALID_FRAME");
+	}
+	const bytes = new Uint8Array(binary.length);
+	for (let index = 0; index < binary.length; index += 1) bytes[index] = binary.charCodeAt(index);
+	return bytes;
+}
 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");
@@ -1729,7 +1759,7 @@ var TerminalStream = class TerminalStream {
 		}
 		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;
+		if (message.type !== "ready" && message.type !== "output" && message.type !== "exit" && message.type !== "renewed" && message.type !== "error") return;
 		const parsed = terminalServerMessageSchema.safeParse(message);
 		if (!parsed.success) {
 			failProtocolFrame();
@@ -1741,13 +1771,27 @@ var TerminalStream = class TerminalStream {
 					connectionId: parsed.data.connectionId,
 					sessionId: parsed.data.sessionId,
 					restored: parsed.data.restored,
-					detachTimeoutMs: parsed.data.detachTimeoutMs
+					detachTimeoutMs: parsed.data.detachTimeoutMs,
+					...parsed.data.attachCount === void 0 ? {} : { attachCount: parsed.data.attachCount },
+					...parsed.data.cursors === void 0 ? {} : { cursors: parsed.data.cursors }
 				};
 				this.readyInfo = info;
 				connectPhase.succeed();
 				this.handlers.onReady?.(info);
 				return;
 			}
+			case "output":
+				try {
+					const bytes = decodeBase64(parsed.data.data);
+					this.handlers.onOutput?.(parsed.data.seq, bytes);
+					if (this.handlers.onOutput === void 0) this.handlers.onData?.(bytes);
+				} catch (error) {
+					const protocolError = error instanceof TerminalStreamError ? error : new TerminalStreamError("Terminal output frame is not valid base64", "INVALID_FRAME");
+					if (!connectPhase.settled()) connectPhase.fail(protocolError);
+					else this.handlers.onError?.(protocolError);
+					if (this.ws.readyState === WebSocket.OPEN) this.ws.close(1e3, "invalid terminal output");
+				}
+				return;
 			case "exit":
 				this.handlers.onExit?.({
 					exitCode: parsed.data.exitCode,
@@ -2014,6 +2058,397 @@ var BrowserInteractiveSessionController = class extends InteractiveSessionContro
 	}
 };
 //#endregion
+//#region src/interactive-terminal-session.ts
+const MAX_RETAINED_TERMINAL_FRAMES = 4096;
+const MAX_RETAINED_TERMINAL_BYTES = 8 * 1024 * 1024;
+const terminalTextEncoder = new TextEncoder();
+/**
+* Bounded ordered terminal frames backed by server-issued output sequences.
+*
+* The server cursor is never replaced with a client counter.  A reconnecting
+* handle therefore exposes the same output identity after process restart.
+*/
+var InteractiveTerminalFrameLog = class {
+	entries = [];
+	entryStartIndex = 0;
+	retainedStartOrdinal = 1;
+	outputEntries = [];
+	outputEntryStartIndex = 0;
+	lastOrdinal = 0;
+	retainedBytes = 0;
+	latestOutputSeq = 0;
+	lastSeenOutputSeq = 0;
+	earliestOutputSeq = 0;
+	evictedOutputOrdinal = 0;
+	ended = false;
+	waiters = /* @__PURE__ */ new Set();
+	configure(window) {
+		const exactWindow = TerminalReplayWindowSchema.parse(window);
+		if (exactWindow.latest < exactWindow.earliest) throw new Error("Terminal replay cursor window is reversed");
+		this.earliestOutputSeq = exactWindow.earliest;
+		this.latestOutputSeq = exactWindow.latest;
+		this.lastSeenOutputSeq = exactWindow.earliest;
+	}
+	append(event) {
+		const exactEvent = this.validateEvent(event);
+		if (exactEvent.type === "output") {
+			if (exactEvent.seq <= this.lastSeenOutputSeq) throw new Error("Terminal output sequence is not strictly increasing");
+			this.lastSeenOutputSeq = exactEvent.seq;
+			this.latestOutputSeq = Math.max(this.latestOutputSeq, exactEvent.seq);
+		}
+		const ordinal = ++this.lastOrdinal;
+		if (this.activeEntryCount() === 0) this.retainedStartOrdinal = ordinal;
+		const entry = {
+			ordinal,
+			event: exactEvent
+		};
+		this.entries.push(entry);
+		if (exactEvent.type === "output") this.outputEntries.push({
+			ordinal,
+			seq: exactEvent.seq
+		});
+		this.retainedBytes += this.eventBytes(exactEvent);
+		this.trim();
+		this.wake();
+	}
+	end() {
+		this.ended = true;
+		this.wake();
+	}
+	get cursors() {
+		return {
+			earliest: this.earliestOutputSeq,
+			latest: this.latestOutputSeq
+		};
+	}
+	async *read(since, signal) {
+		signal?.throwIfAborted();
+		const cursor = since ?? this.earliestOutputSeq;
+		this.assertCursor(cursor);
+		let ordinal = this.ordinalForCursor(cursor);
+		let outputCursor = cursor;
+		while (true) {
+			signal?.throwIfAborted();
+			if (this.evictedOutputOrdinal > ordinal) throw new Error("Terminal output was evicted before this consumer could read it");
+			const entryIndex = this.indexAfterOrdinal(ordinal);
+			const entry = this.entries[this.entryStartIndex + entryIndex];
+			if (entry !== void 0) {
+				ordinal = entry.ordinal;
+				if (entry.event.type === "output" && entry.event.seq <= outputCursor) continue;
+				if (entry.event.type === "output") outputCursor = entry.event.seq;
+				yield entry.event;
+				signal?.throwIfAborted();
+				continue;
+			}
+			if (this.ended) return;
+			await this.waitForFrames(signal);
+		}
+	}
+	validateEvent(event) {
+		return TerminalOutputEventSchema.parse(event);
+	}
+	eventBytes(event) {
+		return event.type === "output" ? terminalTextEncoder.encode(event.data).byteLength : 64;
+	}
+	trim() {
+		while (this.activeEntryCount() > MAX_RETAINED_TERMINAL_FRAMES || this.retainedBytes > MAX_RETAINED_TERMINAL_BYTES && this.activeEntryCount() > 1) {
+			const dropped = this.entries[this.entryStartIndex];
+			if (dropped === void 0) return;
+			this.entryStartIndex += 1;
+			this.retainedBytes -= this.eventBytes(dropped.event);
+			if (dropped.event.type === "output") {
+				this.earliestOutputSeq = Math.max(this.earliestOutputSeq, dropped.event.seq);
+				this.evictedOutputOrdinal = dropped.ordinal;
+			}
+		}
+		this.retainedStartOrdinal = this.entries[this.entryStartIndex]?.ordinal ?? this.lastOrdinal + 1;
+		while (this.outputEntries[this.outputEntryStartIndex] !== void 0 && this.outputEntries[this.outputEntryStartIndex].ordinal < this.retainedStartOrdinal) this.outputEntryStartIndex += 1;
+		this.compactRetainedEntries();
+	}
+	assertCursor(cursor) {
+		if (!Number.isSafeInteger(cursor) || cursor < 0) throw new Error("Terminal replay cursor must be a non-negative integer");
+		const { earliest, latest } = this.cursors;
+		if (cursor < earliest) throw new Error(`Terminal replay cursor ${cursor} is older than ${earliest}`);
+		if (cursor > latest) throw new Error(`Terminal replay cursor ${cursor} is ahead of ${latest}`);
+	}
+	ordinalForCursor(cursor) {
+		let low = this.outputEntryStartIndex;
+		let high = this.outputEntries.length - 1;
+		let matchingOrdinal;
+		while (low <= high) {
+			const middle = low + Math.floor((high - low) / 2);
+			const candidate = this.outputEntries[middle];
+			if (candidate === void 0) break;
+			if (candidate.seq <= cursor) {
+				matchingOrdinal = candidate.ordinal;
+				low = middle + 1;
+			} else high = middle - 1;
+		}
+		if (matchingOrdinal !== void 0) return matchingOrdinal;
+		if (cursor === this.earliestOutputSeq) return this.evictedOutputOrdinal;
+		if (cursor <= this.latestOutputSeq) return this.lastOrdinal;
+		throw new Error("Terminal replay cursor is not retained");
+	}
+	activeEntryCount() {
+		return this.entries.length - this.entryStartIndex;
+	}
+	indexAfterOrdinal(ordinal) {
+		const first = this.entries[this.entryStartIndex];
+		if (first === void 0 || ordinal < first.ordinal) return 0;
+		const last = this.entries[this.entries.length - 1];
+		if (last === void 0 || ordinal >= last.ordinal) return this.activeEntryCount();
+		return ordinal - first.ordinal + 1;
+	}
+	compactRetainedEntries() {
+		if (this.entryStartIndex > 1024 && this.entryStartIndex * 2 >= this.entries.length) {
+			this.entries = this.entries.slice(this.entryStartIndex);
+			this.entryStartIndex = 0;
+		}
+		if (this.outputEntryStartIndex > 1024 && this.outputEntryStartIndex * 2 >= this.outputEntries.length) {
+			this.outputEntries = this.outputEntries.slice(this.outputEntryStartIndex);
+			this.outputEntryStartIndex = 0;
+		}
+	}
+	waitForFrames(signal) {
+		return new Promise((resolve, reject) => {
+			let settled = false;
+			const wake = () => {
+				if (settled) return;
+				settled = true;
+				signal?.removeEventListener("abort", onAbort);
+				this.waiters.delete(wake);
+				resolve();
+			};
+			const onAbort = () => {
+				if (settled) return;
+				settled = true;
+				this.waiters.delete(wake);
+				reject(signal?.reason instanceof Error ? signal.reason : new DOMException("Terminal event read was aborted", "AbortError"));
+			};
+			this.waiters.add(wake);
+			signal?.addEventListener("abort", onAbort, { once: true });
+			if (signal?.aborted) onAbort();
+		});
+	}
+	wake() {
+		for (const waiter of [...this.waiters]) waiter();
+	}
+};
+/** Create a capture that preserves output sequence and UTF-8 boundaries. */
+function createInteractiveTerminalCapture() {
+	const log = new InteractiveTerminalFrameLog();
+	const decoder = new TextDecoder();
+	let ready;
+	let failure;
+	const exit = { seen: false };
+	let explicitClose = false;
+	const fail = (error) => {
+		failure ??= error;
+		log.append({
+			type: "error",
+			message: error.message
+		});
+		log.end();
+	};
+	return {
+		handlers: {
+			onReady: (info) => {
+				ready = info;
+				if (info.cursors === void 0) {
+					fail(/* @__PURE__ */ new Error("Exact terminal ready message has no replay cursors"));
+					return;
+				}
+				try {
+					log.configure(info.cursors);
+					log.append({ type: "ready" });
+				} catch (error) {
+					fail(error instanceof Error ? error : new Error(String(error)));
+				}
+			},
+			onOutput: (seq, bytes) => {
+				try {
+					log.append({
+						type: "output",
+						seq,
+						data: decoder.decode(bytes)
+					});
+				} catch (error) {
+					fail(error instanceof Error ? error : new Error(String(error)));
+				}
+			},
+			onData: () => {
+				fail(/* @__PURE__ */ new Error("Exact terminal transport returned unsequenced binary output"));
+			},
+			onExit: (info) => {
+				try {
+					exit.seen = true;
+					exit.exitCode = info.exitCode;
+					exit.exitSignal = info.exitSignal;
+					log.append({
+						type: "exit",
+						...info.exitCode === void 0 ? {} : { exitCode: info.exitCode },
+						...info.exitSignal === void 0 ? {} : { exitSignal: info.exitSignal }
+					});
+					log.end();
+				} catch (error) {
+					fail(error instanceof Error ? error : new Error(String(error)));
+				}
+			},
+			onError: (error) => fail(error),
+			onClose: (code, reason) => {
+				try {
+					if (exit.seen || explicitClose || failure !== void 0) {
+						log.end();
+						return;
+					}
+					fail(/* @__PURE__ */ new Error(`Terminal connection closed before the process exited (code ${code}${reason ? `: ${reason}` : ""})`));
+				} catch (error) {
+					fail(error instanceof Error ? error : new Error(String(error)));
+				}
+			}
+		},
+		log,
+		markExplicitClose: () => {
+			explicitClose = true;
+		},
+		flushOutput: () => {},
+		get ready() {
+			return ready;
+		},
+		get failure() {
+			return failure;
+		},
+		exit
+	};
+}
+/** Build the provider-neutral ref from server metadata and exact authority. */
+function createInteractiveTerminalSession(options) {
+	const { stream, capture, metadata, ref, parentExecutionId, control } = options;
+	const ready = capture.ready ?? stream.ready;
+	const cursors = ready.cursors;
+	if (cursors === void 0) throw new Error("Exact terminal ready message has no replay cursors");
+	if (capture.failure !== void 0) throw capture.failure;
+	if (!agentInteractiveSessionControlClaimMatchesRef(ref, control)) throw new Error("Exact terminal control claim is not bound");
+	if (ready.attachCount === void 0) throw new Error("Exact terminal ready message has no attach count");
+	if (metadata.sessionId !== ready.sessionId) throw new Error("Terminal metadata does not match the attached session");
+	if (metadata.connectionId !== void 0 && metadata.connectionId !== ready.connectionId) throw new Error("Terminal metadata does not match the attached connection");
+	const required = {
+		name: metadata.name,
+		shell: metadata.shell,
+		cwd: metadata.cwd,
+		cols: metadata.cols,
+		rows: metadata.rows,
+		createdAt: metadata.createdAt,
+		lastActivityAt: metadata.lastActivityAt,
+		isRunning: metadata.isRunning
+	};
+	if (typeof required.name !== "string" || typeof required.shell !== "string" || typeof required.cwd !== "string" || !Number.isSafeInteger(required.cols) || !Number.isSafeInteger(required.rows) || typeof required.createdAt !== "string" || typeof required.lastActivityAt !== "string" || typeof required.isRunning !== "boolean") throw new Error("Terminal metadata omits required provider facts");
+	const terminalRef = TerminalSessionRefSchema.parse({
+		terminalSessionId: ready.sessionId,
+		parentExecutionId,
+		name: required.name,
+		shell: required.shell,
+		...metadata.command === void 0 ? {} : { command: metadata.command },
+		cwd: required.cwd,
+		cols: required.cols,
+		rows: required.rows,
+		connectionId: ready.connectionId,
+		createdAt: required.createdAt,
+		lastActivityAt: required.lastActivityAt,
+		expiresAt: control.expiresAt,
+		isRunning: required.isRunning,
+		...metadata.exitCode === void 0 ? {} : { exitCode: metadata.exitCode },
+		...metadata.exitSignal === void 0 ? {} : { exitSignal: metadata.exitSignal },
+		attachCount: ready.attachCount
+	});
+	if (ref.run.executionId !== parentExecutionId || ref.run.sessionId !== metadata.sessionId) throw new Error("Interactive terminal ref does not match its parent execution");
+	return new InteractiveTerminalSessionImpl(terminalRef, cursors, control, stream, capture.log, capture, capture.exit);
+}
+var InteractiveTerminalSessionImpl = class {
+	detached = false;
+	constructor(initialRef, initialCursors, control, stream, log, capture, exit = void 0) {
+		this.initialRef = initialRef;
+		this.initialCursors = initialCursors;
+		this.control = control;
+		this.stream = stream;
+		this.log = log;
+		this.capture = capture;
+		this.exit = exit;
+	}
+	get ref() {
+		return TerminalSessionRefSchema.parse({
+			...this.initialRef,
+			isRunning: this.initialRef.isRunning && !(this.exit?.seen ?? false),
+			...this.exit?.exitCode === void 0 ? {} : { exitCode: this.exit.exitCode },
+			...this.exit?.exitSignal === void 0 ? {} : { exitSignal: this.exit.exitSignal }
+		});
+	}
+	get cursors() {
+		return this.log.cursors.latest === 0 && this.initialCursors.latest > 0 ? this.initialCursors : this.log.cursors;
+	}
+	async input(input, options) {
+		const exactInput = TerminalInputSchema.parse(input);
+		this.assertWritable(options);
+		this.stream.write(exactInput.data);
+	}
+	async resize(resize, options) {
+		const exactResize = TerminalResizeSchema.parse(resize);
+		this.assertWritable(options);
+		this.capture.flushOutput();
+		this.stream.resize(exactResize.cols, exactResize.rows);
+		this.log.append({
+			type: "resize",
+			cols: exactResize.cols,
+			rows: exactResize.rows
+		});
+	}
+	async detach(options) {
+		options?.signal?.throwIfAborted();
+		if (!this.detached) {
+			this.capture.markExplicitClose();
+			this.capture.flushOutput();
+			await this.stream.close();
+			this.detached = true;
+			this.log.end();
+		}
+		return {
+			status: "detached",
+			terminalSessionId: this.initialRef.terminalSessionId,
+			connectionId: this.initialRef.connectionId
+		};
+	}
+	async close(options) {
+		options?.signal?.throwIfAborted();
+		if (!this.detached) {
+			this.capture.markExplicitClose();
+			this.capture.flushOutput();
+			await this.stream.close();
+			this.detached = true;
+			this.log.end();
+		}
+		if (this.exit?.seen) return {
+			status: "closed",
+			terminalSessionId: this.initialRef.terminalSessionId,
+			...this.exit.exitCode === void 0 ? {} : { exitCode: this.exit.exitCode },
+			...this.exit.exitSignal === void 0 ? {} : { exitSignal: this.exit.exitSignal }
+		};
+		return {
+			status: "unknown",
+			terminalSessionId: this.initialRef.terminalSessionId,
+			message: "The terminal connection closed, but only the interactive stop operation can prove process termination.",
+			retryable: false
+		};
+	}
+	events(options) {
+		return this.log.read(options?.since, options?.signal);
+	}
+	assertWritable(options) {
+		options?.signal?.throwIfAborted();
+		if (this.detached) throw new Error("Terminal connection is detached");
+		if (!terminalSessionUsable(this.ref, (/* @__PURE__ */ new Date()).toISOString()) || this.exit?.seen) throw new Error("Terminal connection is no longer writable");
+	}
+};
+//#endregion
 //#region src/interactive.ts
 /**
 * Exact native coding-agent sessions on the public SDK.
@@ -2042,7 +2477,7 @@ function createInteractiveSessionController(host, sessionId, ref, 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.
+* Attach claims fresh control unless the caller supplies an exact active claim.
 */
 var InteractiveSessionHandle = class {
 	ref;
@@ -2050,6 +2485,8 @@ var InteractiveSessionHandle = class {
 	attachHolderId = createInteractiveControlHolderId("sdk");
 	attachController;
 	attachInFlight;
+	agentTerminalAttachInFlight;
+	agentTerminalAttachDigest;
 	constructor(host, sessionId, options = {}) {
 		this.host = host;
 		this.sessionId = sessionId;
@@ -2104,19 +2541,44 @@ var InteractiveSessionHandle = class {
 	}
 	attach(request = {}, options) {
 		options?.signal?.throwIfAborted();
-		if (this.attachInFlight !== void 0) return awaitWithAbort(this.attachInFlight, options?.signal);
+		const suppliedRequest = request;
+		const explicitControl = suppliedRequest.control !== void 0;
+		if (this.attachInFlight !== void 0) {
+			if (explicitControl) throw new Error(`Interactive session ${this.sessionId} cannot attach with an exact control while another attach is in flight`);
+			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);
+		let exactIdentity;
+		let attachRequest = suppliedRequest;
+		if (explicitControl) {
+			const { control, handlers, ...wireRequest } = suppliedRequest;
+			const exactAttach = AgentInteractiveSessionAttachSchema.parse({
+				...wireRequest,
+				control
+			});
+			if (!agentInteractiveSessionControlClaimMatchesRef(ref, exactAttach.control)) throw new Error(`Interactive session ${this.sessionId} attach is bound to a different exact control claim`);
+			assertActiveInteractiveControlClaim(exactAttach.control);
+			exactIdentity = {
+				ref,
+				control: exactAttach.control
+			};
+			attachRequest = {
+				...wireRequest,
+				...handlers === void 0 ? {} : { handlers }
+			};
+		}
+		const operation = (async () => {
+			const identity = exactIdentity === void 0 ? await controller.resolve(options) : exactIdentity;
+			const stream = await controller.attachWithIdentity(identity, attachRequest, options);
 			this.ref = identity.ref;
 			this.control = identity.control;
 			return stream;
-		});
+		})();
 		let tracked;
 		tracked = operation.finally(() => {
 			if (this.attachInFlight === tracked) this.attachInFlight = void 0;
@@ -2124,6 +2586,54 @@ var InteractiveSessionHandle = class {
 		this.attachInFlight = tracked;
 		return tracked;
 	}
+	/** Attach the native terminal with server-issued replay identity. */
+	attachAgentTerminal(request, options) {
+		options?.signal?.throwIfAborted();
+		const binding = this.requireBinding();
+		const exactRequest = AgentInteractiveSessionAttachSchema.parse(request);
+		if (!agentInteractiveSessionControlClaimMatchesRef(binding.ref, exactRequest.control) || canonicalCandidateDigest(exactRequest.control) !== canonicalCandidateDigest(binding.control)) throw new Error(`Interactive session ${this.sessionId} terminal attach is bound to a different active control claim`);
+		const requestDigest = canonicalCandidateDigest(exactRequest);
+		if (this.agentTerminalAttachInFlight !== void 0) {
+			if (this.agentTerminalAttachDigest !== requestDigest) throw new Error(`Interactive session ${this.sessionId} cannot attach with a different terminal request while another attach is in flight`);
+			return awaitWithAbort(this.agentTerminalAttachInFlight, options?.signal);
+		}
+		const capture = createInteractiveTerminalCapture();
+		const operation = (async () => {
+			const stream = await this.attach({
+				...exactRequest,
+				handlers: capture.handlers
+			}, options);
+			try {
+				if (capture.failure !== void 0) throw capture.failure;
+				const ready = capture.ready ?? stream.ready;
+				const metadataReader = this.host._interactiveTerminalInfo;
+				if (metadataReader === void 0) throw new Error("Sandbox runtime exposes no exact interactive terminal metadata");
+				const metadata = options === void 0 ? await metadataReader(this.sessionId, ready.sessionId) : await metadataReader(this.sessionId, ready.sessionId, options);
+				if (metadata === null) throw new Error(`Interactive terminal ${ready.sessionId} metadata is unavailable`);
+				return createInteractiveTerminalSession({
+					stream,
+					capture,
+					metadata,
+					ref: binding.ref,
+					parentExecutionId: binding.ref.run.executionId,
+					control: binding.control
+				});
+			} catch (error) {
+				await stream.close().catch(() => {});
+				throw error;
+			}
+		})();
+		let tracked;
+		tracked = operation.finally(() => {
+			if (this.agentTerminalAttachInFlight === tracked) {
+				this.agentTerminalAttachInFlight = void 0;
+				this.agentTerminalAttachDigest = void 0;
+			}
+		});
+		this.agentTerminalAttachInFlight = tracked;
+		this.agentTerminalAttachDigest = requestDigest;
+		return awaitWithAbort(tracked, options?.signal);
+	}
 	status(options) {
 		options?.signal?.throwIfAborted();
 		const ref = this.requireRef();
@@ -2170,6 +2680,10 @@ var InteractiveSessionHandle = class {
 		});
 	}
 };
+function assertActiveInteractiveControlClaim(control) {
+	const expiresAt = Date.parse(control.expiresAt);
+	if (!Number.isFinite(expiresAt) || expiresAt <= Date.now()) throw new Error("Interactive control claim is stale");
+}
 //#endregion
 //#region src/session.ts
 /**
@@ -2691,9 +3205,12 @@ function normalizeSandboxCreateReceipt(raw) {
 	const record = raw;
 	const idempotencyKeyApplied = record.idempotencyKeyApplied;
 	if (typeof idempotencyKeyApplied !== "boolean") return null;
+	const outcome = SANDBOX_CREATE_OUTCOMES.includes(record.outcome) ? record.outcome : "unknown";
+	const injectedSecrets = Array.isArray(record.injectedSecrets) ? record.injectedSecrets.filter((name) => typeof name === "string") : void 0;
 	return {
-		outcome: SANDBOX_CREATE_OUTCOMES.includes(record.outcome) ? record.outcome : "unknown",
-		idempotencyKeyApplied
+		outcome,
+		idempotencyKeyApplied,
+		...injectedSecrets ? { injectedSecrets } : {}
 	};
 }
 /**
@@ -7163,6 +7680,14 @@ var SandboxInstance = class SandboxInstance {
 	async _attachInteractive(id, ref, request, options, reconnectAuthority) {
 		return this.interactiveTerminalOperations._attachInteractive(id, ref, request, options, reconnectAuthority);
 	}
+	/** @internal — read exact terminal facts from the runtime-owned manager. */
+	async _interactiveTerminalInfo(id, terminalId, options) {
+		options?.signal?.throwIfAborted();
+		if (id !== this.id) throw new ValidationError("Interactive terminal metadata request does not belong to this sandbox");
+		const metadata = await this.runtime.terminals.get(terminalId);
+		options?.signal?.throwIfAborted();
+		return metadata;
+	}
 	/** @internal — delegated to the native interactive operations module. */
 	async _attachTerminal(connectionId, options = {}) {
 		return this.interactiveTerminalOperations._attachTerminal(connectionId, options);
@@ -7411,4 +7936,4 @@ function quoteForShell(value) {
 	return `'${value.replace(/'/g, "'\\''")}'`;
 }
 //#endregion
-export { normalizeConnection as C, toOtelJson as D, otelTraceIdForTangleTrace as E, 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 };
+export { toOtelJson as A, collectAgentResponseText as C, buildTraceExportPayload as D, normalizeConnection as E, exportTraceBundle as O, collectAgentFinalMessageText as S, isToolBearingEvent as T, TerminalStream as _, WorkspaceImages as a, requestInteractiveSessionToken as b, SandboxTaskSession as c, agentInteractiveSessionPromptRequestDigest as d, InteractiveTerminalFrameLog as f, InteractiveSessionController as g, BrowserInteractiveSessionController as h, normalizeStartupDiagnostics as i, otelTraceIdForTangleTrace as k, SandboxSession as l, createInteractiveTerminalSession as m, createSandboxInstanceFromResponse as n, GPU_LEASE_PROVIDER_NAMES as o, createInteractiveTerminalCapture as p, normalizeSandboxCreateReceipt as r, MAX_EGRESS_DENIALS_LIMIT as s, SandboxInstance as t, InteractiveSessionHandle as u, TerminalStreamError as v, getSandboxEventText as w, applySandboxEventText as x, TERMINAL_WS_ECHO_SUBPROTOCOL as y };

package/dist/tangle/index.d.ts

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