@tangle-network/sandbox 0.10.5 → 0.11.1-develop.20260717054349.4472dd9

package/dist/{sandbox-Vh7Aog8b.js → sandbox-Cf25Dgrc.js}

@@ -1,5 +1,5 @@
-import { n as normalizeSessionInfo, r as normalizeRuntimeBackendConfig, t as SandboxRuntimeApi } from "./runtime-api-CvAUrnHc.js";
-import { c as SandboxError, d as TimeoutError, f as ValidationError, i as NetworkError, l as ServerError, n as CapabilityError, p as parseErrorResponse, s as QuotaError, t as AuthError, u as StateError } from "./errors-DSz87Rkk.js";
+import { l as normalizeRuntimeBackendConfig, n as normalizeSessionInfo, o as combineAbortSignals, r as uploadChunked, s as encodePromptForWire, t as SandboxRuntimeApi, u as normalizeRuntimeModelOverride } from "./runtime-api-fqaQ3CN2.js";
+import { c as SandboxError, d as TimeoutError, f as ValidationError, i as NetworkError, l as ServerError, n as CapabilityError, p as parseErrorResponse, s as QuotaError, t as AuthError, u as StateError } from "./errors-Cbs78OlF.js";
 import { addTokenUsage, readTokenCostUsd, readTokenUsage } from "@tangle-network/agent-core";
 //#region src/lib/sse-parser.ts
 /**
@@ -18,6 +18,7 @@ async function* parseSSEStream(body, options) {
 	let currentEvent = "";
 	let dataLines = [];
 	let currentId = "";
+	let completed = false;
 	const flush = function* () {
 		if (dataLines.length === 0) {
 			currentEvent = "";
@@ -61,40 +62,13 @@ async function* parseSSEStream(body, options) {
 		buffer += decoder.decode();
 		if (buffer.length > 0) processLine(buffer);
 		yield* flush();
+		completed = true;
 	} finally {
+		if (!completed) await reader.cancel().catch(() => void 0);
 		reader.releaseLock();
 	}
 }
 //#endregion
-//#region src/lib/wire-encoding.ts
-/**
-* Encode a prompt text part for the wire. Server decodes at the route
-* boundary; the LLM only ever sees the original UTF-8. Done
-* unconditionally because readable bodies false-positive on ingress WAF
-* rules that pattern-match shell-injection-shaped substrings (which
-* legitimate prompts routinely contain — e.g. Step-0 dev-server
-* bootstrap).
-*/
-function encodeTextForWire(text) {
-	if (typeof Buffer !== "undefined") return Buffer.from(text, "utf8").toString("base64");
-	if (typeof btoa === "function") return btoa(encodeURIComponent(text).replace(/%([0-9A-F]{2})/g, (_, h) => String.fromCharCode(Number.parseInt(h, 16))));
-	throw new Error("encodeTextForWire: no base64 encoder available (Buffer and btoa both undefined)");
-}
-/**
-* Convert a caller-supplied prompt (string or parts array) into the
-* wire-format parts array. Every text part is base64-encoded; non-text
-* parts pass through. A bare string is wrapped in a single text part.
-*/
-function encodePromptForWire(message) {
-	return (typeof message === "string" ? [{
-		type: "text",
-		text: message
-	}] : message).map((part) => part.type === "text" ? {
-		type: "text",
-		text: encodeTextForWire(part.text)
-	} : part);
-}
-//#endregion
 //#region src/trace-exporter.ts
 function buildTraceExportPayload(bundle, format = "tangle", serviceName = "tangle-sandbox") {
 	if (format === "tangle") return bundle;
@@ -635,6 +609,29 @@ var SandboxSession = class SandboxSession {
 	async answer(answers) {
 		return this.box._answerQuestion(this.id, answers);
 	}
+	/** 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()
+		});
+	}
+	async requireCurrentPlan() {
+		const plan = await this.plan();
+		if (!plan) throw new Error("No durable plan is awaiting a decision");
+		return plan;
+	}
 };
 //#endregion
 //#region src/task-session.ts
@@ -738,6 +735,10 @@ const SNAPSHOT_RESTORE_POLL_INTERVAL_MS = 1e3;
 const SNAPSHOT_RESTORE_TIMEOUT_MS = 600 * 1e3;
 const SNAPSHOT_VISIBILITY_POLL_INTERVAL_MS = 1e3;
 const SNAPSHOT_VISIBILITY_TIMEOUT_MS = 120 * 1e3;
+const EXEC_DEFAULT_TIMEOUT_MS = 3e4;
+const EXEC_MIN_TIMEOUT_MS = 100;
+const EXEC_MAX_TIMEOUT_MS = 6e5;
+const EXEC_TRANSPORT_MARGIN_MS = 15e3;
 const SNAPSHOT_CREATE_REQUEST_TIMEOUT_MS = 600 * 1e3;
 function toSnapshotResult(data) {
 	return {
@@ -767,6 +768,11 @@ function runtimeFilesystemPath(endpoint, path) {
 * requirements; a turn whose tool failed (even if narrated around) fails.
 */
 function deriveOutcome(inputs) {
+	if (inputs.plan) return {
+		status: "awaiting_plan_decision",
+		success: false,
+		error: "Agent is awaiting a durable plan decision"
+	};
 	if (inputs.question) return {
 		status: "awaiting_question",
 		success: false,
@@ -799,6 +805,18 @@ function deriveOutcome(inputs) {
 		success: true
 	};
 }
+function readAwaitingPlan(data) {
+	const direct = data.plan;
+	const outcome = data.outcome;
+	const candidate = direct && typeof direct === "object" ? direct : outcome && typeof outcome === "object" && outcome.type === "awaiting_plan_decision" ? outcome.plan : void 0;
+	if (!candidate || typeof candidate !== "object") return void 0;
+	const plan = candidate;
+	if (typeof plan.id !== "string" || typeof plan.revision !== "number" || typeof plan.body !== "string" || typeof plan.submittedAt !== "string") return;
+	return plan;
+}
+function readPlanFromEvent(event) {
+	return event.type === "result" || event.type === "done" || event.type === "plan.submitted" ? readAwaitingPlan(event.data) : void 0;
+}
 /** Read tool invocations off a `result` event payload. */
 function readToolInvocations(data) {
 	const raw = data.toolInvocations;
@@ -920,6 +938,22 @@ const WRITE_MANY_DEFAULT_PACE_MS = 150;
 const WRITE_MANY_DEFAULT_MAX_RETRIES = 4;
 const WRITE_MANY_RETRY_BASE_MS = 250;
 const WRITE_MANY_RETRY_MAX_MS = 2e3;
+function parseTextFileReadResponse(body) {
+	let payload;
+	try {
+		payload = JSON.parse(body);
+	} catch {
+		throw new ServerError("Runtime returned invalid JSON for file read", 502, {
+			origin: "runtime",
+			endpoint: "/files/read"
+		});
+	}
+	if (typeof payload !== "object" || payload === null || !("success" in payload) || payload.success !== true || !("data" in payload) || typeof payload.data !== "object" || payload.data === null || !("content" in payload.data) || typeof payload.data.content !== "string" || !("encoding" in payload.data) || payload.data.encoding !== "utf8") throw new ServerError("Runtime returned a malformed text file response", 502, {
+		origin: "runtime",
+		endpoint: "/files/read"
+	});
+	return payload.data.content;
+}
 const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 /** Transient file-write failures worth retrying: rate-limit (quota), 5xx,
 *  transport (network), and request timeouts. A non-transient error (bad path,
@@ -1240,28 +1274,31 @@ var SandboxInstance = class SandboxInstance {
 	*/
 	async exec(command, options) {
 		await this.ensureRunning();
+		const timeoutMs = options?.timeoutMs ?? EXEC_DEFAULT_TIMEOUT_MS;
+		if (!Number.isInteger(timeoutMs) || timeoutMs < EXEC_MIN_TIMEOUT_MS || timeoutMs > EXEC_MAX_TIMEOUT_MS) throw new ValidationError(`exec timeoutMs must be an integer between ${EXEC_MIN_TIMEOUT_MS} and ${EXEC_MAX_TIMEOUT_MS}`);
 		const headers = {};
 		if (options?.sessionId) headers["X-Session-Id"] = options.sessionId;
-		const response = await this.runtimeFetch("/terminals/commands", {
+		const response = await this.runtimeFetch("/process/spawn", {
 			method: "POST",
 			headers,
 			body: JSON.stringify({
 				command,
 				cwd: options?.cwd,
 				env: options?.env,
-				timeout: options?.timeoutMs
+				timeoutMs,
+				blocking: true
 			})
-		});
+		}, { timeoutMs: timeoutMs + EXEC_TRANSPORT_MARGIN_MS });
 		if (!response.ok) {
 			const body = await response.text();
 			throw parseErrorResponse(response.status, body, void 0, response.headers);
 		}
-		const data = await response.json();
-		const result = data.result ?? data;
+		const result = (await response.json()).data;
+		if (!result || typeof result.exitCode !== "number" || typeof result.stdout !== "string" || typeof result.stderr !== "string") throw new ServerError("Sandbox process response was malformed", 502);
 		return {
-			exitCode: result.exitCode ?? 0,
-			stdout: result.stdout ?? "",
-			stderr: result.stderr ?? ""
+			exitCode: result.exitCode,
+			stdout: result.stdout,
+			stderr: result.stderr
 		};
 	}
 	/**
@@ -1331,18 +1368,20 @@ var SandboxInstance = class SandboxInstance {
 	*/
 	async read(path, options) {
 		await this.ensureRunning();
-		const headers = {};
-		if (options?.sessionId) headers["X-Session-Id"] = options.sessionId;
+		const headers = options?.sessionId ? { "X-Session-Id": options.sessionId } : void 0;
 		const response = await this.runtimeFetch("/files/read", {
 			method: "POST",
 			headers,
-			body: JSON.stringify({ path })
+			body: JSON.stringify({
+				path,
+				encoding: "utf8"
+			})
 		});
 		if (!response.ok) {
 			const body = await response.text();
 			throw parseErrorResponse(response.status, body, void 0, response.headers);
 		}
-		return (await response.json()).data?.content ?? "";
+		return parseTextFileReadResponse(await response.text());
 	}
 	/**
 	* Write content to a file in the sandbox.
@@ -1393,7 +1432,10 @@ var SandboxInstance = class SandboxInstance {
 			if (started && paceMs > 0) await delay(paceMs);
 			started = true;
 			try {
-				await this.write(file.path, file.content, { mode: file.mode });
+				await this.write(file.path, file.content, {
+					mode: file.mode,
+					encoding: file.encoding
+				});
 				break;
 			} catch (err) {
 				if (isTransientWriteError(err) && attempt < maxRetries) {
@@ -1420,10 +1462,11 @@ var SandboxInstance = class SandboxInstance {
 		let costUsd;
 		let toolInvocations;
 		let question;
+		let plan;
 		let terminalReached = false;
 		const controller = new AbortController();
 		try {
-			const signal = options?.signal ? AbortSignal.any([options.signal, controller.signal]) : controller.signal;
+			const signal = options?.signal ? combineAbortSignals([options.signal, controller.signal]) : controller.signal;
 			for await (const event of this.streamPrompt(message, {
 				...options,
 				signal
@@ -1433,6 +1476,7 @@ var SandboxInstance = class SandboxInstance {
 					usage = readTokenUsage(event.data) ?? usage;
 					costUsd = readTokenCostUsd(event.data) ?? costUsd;
 				}
+				plan = readPlanFromEvent(event) ?? plan;
 				if (event.type === "result") toolInvocations = readToolInvocations(event.data) ?? toolInvocations;
 				if (event.type === "result" || event.type === "done") terminalReached = true;
 				if (event.type === "interaction") question = readQuestionEvent(event.data) ?? question;
@@ -1449,7 +1493,8 @@ var SandboxInstance = class SandboxInstance {
 				runErrorCode,
 				toolInvocations,
 				approval,
-				question
+				question,
+				plan
 			});
 			return {
 				success: outcome.success,
@@ -1460,6 +1505,7 @@ var SandboxInstance = class SandboxInstance {
 				toolInvocations,
 				approval,
 				question,
+				plan,
 				traceId,
 				durationMs: Date.now() - startTime,
 				usage,
@@ -1544,11 +1590,11 @@ var SandboxInstance = class SandboxInstance {
 	* `error` + `done` so callers never see a thrown generator.
 	*/
 	async *streamPromptInner(message, options) {
+		if (options?.lastEventId && !options.executionId) throw new ValidationError("lastEventId requires executionId so the SDK can replay the correct execution", { executionId: "Required when lastEventId is set" });
 		await this.ensureRunning();
-		const parts = encodePromptForWire(message);
 		const timeoutMs = typeof options?.timeoutMs === "number" && options.timeoutMs > 0 ? options.timeoutMs : void 0;
 		const timeoutSignal = timeoutMs ? AbortSignal.timeout(timeoutMs) : void 0;
-		const streamSignal = timeoutSignal ? options?.signal ? AbortSignal.any([options.signal, timeoutSignal]) : timeoutSignal : options?.signal;
+		const streamSignal = timeoutSignal ? options?.signal ? combineAbortSignals([options.signal, timeoutSignal]) : timeoutSignal : options?.signal;
 		const throwIfTimedOut = () => {
 			if (!timeoutSignal?.aborted || !timeoutMs) return;
 			throw new TimeoutError(timeoutMs, `Prompt stream timed out after ${timeoutMs}ms`, {
@@ -1563,35 +1609,58 @@ var SandboxInstance = class SandboxInstance {
 				...data
 			});
 		};
+		const explicitReplay = Boolean(options?.executionId && options.lastEventId);
+		const requestEndpoint = explicitReplay ? `/agents/run/${encodeURIComponent(options?.executionId ?? "")}/events?lastEventId=${encodeURIComponent(options?.lastEventId ?? "")}&format=sse` : "/agents/run/stream";
+		let lastEventId = options?.lastEventId;
+		let executionId = options?.executionId;
+		let sessionId = options?.sessionId;
+		let receivedTerminal = false;
+		const RECONNECT_BACKOFF_MS = [
+			2e3,
+			4e3,
+			8e3,
+			16e3,
+			3e4,
+			3e4
+		];
+		const MAX_RECONNECT_ATTEMPTS = RECONNECT_BACKOFF_MS.length;
+		let lastReplayStatus;
+		let lastExecutionStatus;
+		let firstSseEventSeen = false;
 		let response;
 		try {
 			logStreamCheckpoint("runtime_post_start", {
-				endpoint: "/agents/run/stream",
+				endpoint: requestEndpoint,
 				sessionId: options?.sessionId,
 				executionId: options?.executionId,
 				hasLastEventId: Boolean(options?.lastEventId),
-				detach: options?.detach === true
+				detach: options?.detach === true,
+				replayOnly: explicitReplay
 			});
-			response = await this.runtimeFetch("/agents/run/stream", {
+			const request = explicitReplay ? {
+				method: "GET",
+				signal: streamSignal
+			} : {
 				method: "POST",
 				signal: streamSignal,
 				headers: {
 					...options?.executionId ? { "X-Execution-ID": options.executionId } : {},
-					...options?.lastEventId ? { "Last-Event-ID": options.lastEventId } : {},
 					...options?.detach ? { "x-agent-detach": "true" } : {}
 				},
 				body: JSON.stringify({
 					identifier: "default",
-					parts,
+					parts: encodePromptForWire(message),
 					sessionId: options?.sessionId,
 					turnId: options?.turnId,
 					metadata: options?.context,
 					requireVisibleAssistantOutput: options?.requireVisibleAssistantOutput,
 					...timeoutMs ? { timeoutMs } : {},
 					...options?.detach ? { detach: true } : {},
-					backend: normalizeRuntimeBackendConfig(options?.backend ?? this.defaultRuntimeBackend, { model: options?.model })
+					backend: normalizeRuntimeBackendConfig(options?.backend ?? this.defaultRuntimeBackend),
+					...options?.model ? { model: normalizeRuntimeModelOverride(options.model) } : {}
 				})
-			});
+			};
+			response = await this.runtimeFetch(requestEndpoint, request);
 			logStreamCheckpoint("runtime_response_headers", {
 				status: response.status,
 				ok: response.ok
@@ -1601,27 +1670,20 @@ var SandboxInstance = class SandboxInstance {
 			throwIfTimedOut();
 			throw err;
 		}
-		if (!response.ok) {
+		if (!response.ok && !explicitReplay) {
 			const body = await response.text();
 			throw parseErrorResponse(response.status, body, void 0, response.headers);
 		}
-		let lastEventId = options?.lastEventId;
-		let executionId = options?.executionId;
-		let sessionId = options?.sessionId;
-		let receivedTerminal = false;
-		const RECONNECT_BACKOFF_MS = [
-			2e3,
-			4e3,
-			8e3,
-			16e3,
-			3e4,
-			3e4
-		];
-		const MAX_RECONNECT_ATTEMPTS = RECONNECT_BACKOFF_MS.length;
-		let lastReplayStatus;
-		let lastExecutionStatus;
-		let firstSseEventSeen = false;
-		for await (const event of this.parseSSEStream(response, streamSignal)) {
+		if (!response.ok) {
+			lastReplayStatus = response.status;
+			await response.text();
+			logStreamCheckpoint("replay_response_status", {
+				attempt: 0,
+				status: response.status,
+				ok: false
+			});
+		} else for await (const event of this.parseSSEStream(response, streamSignal)) {
+			if (event.type === "history.replay.start" || event.type === "history.replay.end") continue;
 			if (!firstSseEventSeen) {
 				firstSseEventSeen = true;
 				logStreamCheckpoint("first_sse_event", {
@@ -1922,6 +1984,7 @@ var SandboxInstance = class SandboxInstance {
 		let costUsd;
 		let toolInvocations;
 		let question;
+		let plan;
 		let terminalReached = false;
 		try {
 			for await (const event of this.streamPrompt(prompt, {
@@ -1938,6 +2001,7 @@ var SandboxInstance = class SandboxInstance {
 				}
 				if (event.type === "done" && costUsd === void 0) costUsd = readTokenCostUsd(event.data);
 				if (event.type === "result" || event.type === "done") terminalReached = true;
+				plan = readPlanFromEvent(event) ?? plan;
 				if (event.type === "interaction") question = readQuestionEvent(event.data) ?? question;
 				if (event.type === "trace.id") traceId = event.data.traceId;
 				if (event.type === "error") {
@@ -1952,7 +2016,8 @@ var SandboxInstance = class SandboxInstance {
 				runErrorCode,
 				toolInvocations,
 				approval,
-				question
+				question,
+				plan
 			});
 			return {
 				success: outcome.success,
@@ -1963,6 +2028,7 @@ var SandboxInstance = class SandboxInstance {
 				toolInvocations,
 				approval,
 				question,
+				plan,
 				traceId,
 				durationMs: Date.now() - startTime,
 				usage,
@@ -2099,11 +2165,19 @@ var SandboxInstance = class SandboxInstance {
 	async resourceUsage() {
 		await this.ensureRunning();
 		const response = await this.runtimeFetch("/health/detailed", { method: "GET" });
-		if (!response.ok) {
-			const body = await response.text();
-			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		const body = await response.text();
+		let data;
+		try {
+			data = JSON.parse(body);
+		} catch (error) {
+			if (response.ok) throw new NetworkError("Detailed health returned a non-JSON response", error instanceof Error ? error : void 0, {
+				endpoint: "/health/detailed",
+				origin: "runtime"
+			});
 		}
-		return (await response.json()).resources ?? null;
+		if (data?.resources) return data.resources;
+		if (!response.ok) throw parseErrorResponse(response.status, body, void 0, response.headers);
+		return null;
 	}
 	/**
 	* Git capability object for repository operations.
@@ -2322,6 +2396,7 @@ var SandboxInstance = class SandboxInstance {
 			writeMany: (files, options) => this.writeMany(files, options),
 			search: (query, options) => this.search(query, options),
 			upload: (localPath, remotePath, options) => this.fsUpload(localPath, remotePath, options),
+			uploadData: (remotePath, data, options) => this.fsUploadData(remotePath, data, options),
 			download: (remotePath, localPath, options) => this.fsDownload(remotePath, localPath, options),
 			uploadDir: (localDir, remoteDir) => this.fsUploadDir(localDir, remoteDir),
 			downloadDir: (remoteDir, localDir) => this.fsDownloadDir(remoteDir, localDir),
@@ -2369,6 +2444,14 @@ var SandboxInstance = class SandboxInstance {
 			percentage: 100
 		});
 	}
+	/** See {@link FileSystem.uploadData}. Delegates to the shared, browser-safe
+	*  chunked-upload flow in `lib/chunked-upload.ts`, wired to this sandbox's
+	*  runtime endpoint (works over the gateway proxy or a direct connection —
+	*  both are transparent through `runtimeFetch`). */
+	async fsUploadData(remotePath, data, options) {
+		await this.ensureRunning();
+		return uploadChunked({ fetch: (path, init) => this.runtimeFetch(path, init) }, remotePath, data, options);
+	}
 	async fsDownload(remotePath, localPath, options) {
 		await this.ensureRunning();
 		const fs = await import("node:fs/promises");
@@ -2929,6 +3012,7 @@ var SandboxInstance = class SandboxInstance {
 	*/
 	get process() {
 		return {
+			ensureDevServer: (options) => this.processEnsureDevServer(options),
 			spawn: (command, options) => this.processSpawn(command, options),
 			spawnExact: (executable, args, options) => this.processSpawnExact(executable, args, options),
 			runCode: (code, options) => this.processRunCode(code, options),
@@ -2936,17 +3020,35 @@ var SandboxInstance = class SandboxInstance {
 			get: (pid) => this.processGet(pid)
 		};
 	}
-	async processSpawnExact(executable, args, options) {
+	async processEnsureDevServer(options) {
+		await this.ensureRunning();
+		if (options?.sessionId !== void 0) assertValidSessionId(options.sessionId);
+		const headers = options?.sessionId ? { "X-Session-Id": options.sessionId } : void 0;
+		const response = await this.runtimeFetch("/process/ensure-dev-server", {
+			method: "POST",
+			headers,
+			body: JSON.stringify({})
+		});
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+		const payload = await response.json();
+		return {
+			...payload.data,
+			startedAt: new Date(payload.data.startedAt)
+		};
+	}
+	async processSpawn(command, options) {
 		await this.ensureRunning();
-		const response = await this.runtimeFetch("/process/spawn-exact", {
+		const response = await this.runtimeFetch("/process/spawn", {
 			method: "POST",
 			body: JSON.stringify({
-				executable,
-				args,
+				command,
 				cwd: options?.cwd,
-				env: options?.env ?? {},
-				stdin: options?.stdin,
-				timeoutMs: options?.timeoutMs
+				env: options?.env,
+				timeoutMs: options?.timeoutMs,
+				blocking: false
 			})
 		});
 		if (!response.ok) {
@@ -2954,17 +3056,19 @@ var SandboxInstance = class SandboxInstance {
 			throw parseErrorResponse(response.status, body, void 0, response.headers);
 		}
 		const data = await response.json();
-		return this.createProcessHandle(data.data.pid, executable);
+		return this.createProcessHandle(data.data.pid, command);
 	}
-	async processSpawn(command, options) {
+	async processSpawnExact(executable, args, options) {
 		await this.ensureRunning();
 		const response = await this.runtimeFetch("/process/spawn", {
 			method: "POST",
 			body: JSON.stringify({
-				command,
+				executable,
+				args,
 				cwd: options?.cwd,
 				env: options?.env,
 				timeoutMs: options?.timeoutMs,
+				stdin: options?.stdin,
 				blocking: false
 			})
 		});
@@ -2973,7 +3077,7 @@ var SandboxInstance = class SandboxInstance {
 			throw parseErrorResponse(response.status, body, void 0, response.headers);
 		}
 		const data = await response.json();
-		return this.createProcessHandle(data.data.pid, command);
+		return this.createProcessHandle(data.data.pid, JSON.stringify([executable, ...args]));
 	}
 	async processRunCode(code, options) {
 		await this.ensureRunning();
@@ -3856,7 +3960,7 @@ var SandboxInstance = class SandboxInstance {
 	async resume(options = {}) {
 		if (options.timeoutMs !== void 0 && (!Number.isFinite(options.timeoutMs) || options.timeoutMs <= 0)) throw new ValidationError("resume timeoutMs must be a positive number");
 		const timeoutSignal = options.timeoutMs ? AbortSignal.timeout(options.timeoutMs) : void 0;
-		const signal = timeoutSignal ? options.signal ? AbortSignal.any([options.signal, timeoutSignal]) : timeoutSignal : options.signal;
+		const signal = timeoutSignal ? options.signal ? combineAbortSignals([options.signal, timeoutSignal]) : timeoutSignal : options.signal;
 		const response = await this.client.fetch(`/v1/sandboxes/${this.id}/resume`, {
 			method: "POST",
 			...signal ? { signal } : {}
@@ -4097,9 +4201,10 @@ var SandboxInstance = class SandboxInstance {
 		await this.refresh();
 		if (this.status !== "running") throw new StateError(`Sandbox is not running (status: ${this.status})`, this.status, "running");
 	}
-	async runtimeFetch(path, options) {
+	async runtimeFetch(path, options, fetchOptions) {
 		const url = `/v1/sandboxes/${encodeURIComponent(this.id)}/runtime${path}`;
 		try {
+			if (fetchOptions) return await this.client.fetch(url, options, fetchOptions);
 			return options ? await this.client.fetch(url, options) : await this.client.fetch(url);
 		} catch (err) {
 			throw new NetworkError(`Failed to connect to sandbox: ${err instanceof Error ? err.message : String(err)}`, err instanceof Error ? err : void 0, {
@@ -4329,24 +4434,8 @@ var SandboxInstance = class SandboxInstance {
 	* abort stamps `interrupted: true` explicitly.
 	*/
 	async messages(opts) {
-		await this.ensureRunning();
-		const params = new URLSearchParams();
-		if (opts.limit !== void 0) params.set("limit", String(opts.limit));
-		if (opts.offset !== void 0) params.set("offset", String(opts.offset));
-		if (opts.since !== void 0) params.set("since", String(opts.since));
-		const query = params.toString() ? `?${params.toString()}` : "";
-		const response = await this.client.fetch(`/v1/sessions/${encodeURIComponent(opts.sessionId)}/messages${query}`, { method: "GET" });
-		if (!response.ok) {
-			const body = await response.text();
-			throw parseErrorResponse(response.status, body, void 0, response.headers);
-		}
-		return (await response.json()).map((m) => ({
-			id: m.info.id,
-			role: m.info.role,
-			timestamp: m.info.timestamp,
-			parts: m.parts,
-			metadata: m.info.metadata
-		}));
+		const { sessionId, ...options } = opts;
+		return this.runtime.messages(sessionId, options);
 	}
 	/** @internal — invoked by SandboxSession.sendMessage(). */
 	async _sessionSendMessage(id, request, options = {}) {
@@ -4455,11 +4544,13 @@ var SandboxInstance = class SandboxInstance {
 		}
 		if (info) {
 			const result = await this._sessionResult(opts.sessionId);
+			const settled = settleTurnDrive({ ...result });
+			if (settled.state === "awaiting_plan_decision") return settled;
 			if (!result.success) return {
 				state: "failed",
 				error: `session ${opts.sessionId} ${info.status}: ${result.error ?? "no error detail"}`
 			};
-			return settleTurnDrive({ ...result });
+			return settled;
 		}
 		await this.dispatchPrompt(message, {
 			...opts,
@@ -4468,15 +4559,10 @@ var SandboxInstance = class SandboxInstance {
 		return { state: "running" };
 	}
 	/**
-	* Mint a scoped, time-bounded JWT for direct browser access to this
-	* sandbox (Issue #913 Gap 1). Authority is the caller's
-	* `TANGLE_API_KEY` (sk-tan-*) — the Sandbox API mints the token;
-	* signing secrets stay server-side.
-	*
-	* Use this to give a browser direct read access to the sandbox without
-	* leaking the full bearer (`box.connection.authToken`). The returned
-	* token verifies against the same sidecar middleware that already
-	* gates ProductTokenIssuer-issued JWTs — no new sidecar surface.
+	* Mint a scoped, time-bounded JWT for browser access (Issue #913 Gap 1).
+	* Authority is the caller's `TANGLE_API_KEY` (sk-tan-*); signing secrets
+	* stay server-side. Session/project scopes work with SessionGatewayClient,
+	* 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`);
@@ -4515,17 +4601,22 @@ var SandboxInstance = class SandboxInstance {
 		return normalizeSessionInfo(await response.json());
 	}
 	/** @internal — invoked by SandboxSession.events(). */
-	async *_sessionEvents(id, opts) {
+	async *_sessionEvents(id, opts, stopOnTurnTerminal = false) {
 		await this.ensureRunning();
 		const search = new URLSearchParams();
 		search.set("sessionId", id);
 		if (opts?.since) search.set("since", opts.since);
+		if (opts?.executionId) search.set("executionId", opts.executionId);
 		const response = await this.runtimeFetch(`/agents/events?${search.toString()}`, { signal: opts?.signal });
 		if (!response.ok) {
 			const body = await response.text();
 			throw parseErrorResponse(response.status, body, void 0, response.headers);
 		}
-		yield* this.parseSSEStream(response, opts?.signal);
+		for await (const event of this.parseSSEStream(response, opts?.signal)) {
+			yield event;
+			const turnTerminal = event.type === "result" || event.type === "done" || event.type === "error";
+			if ((stopOnTurnTerminal || opts?.executionId !== void 0) && turnTerminal) return;
+		}
 	}
 	/** @internal — invoked by SandboxSession.result(). */
 	async _sessionResult(id) {
@@ -4538,14 +4629,16 @@ var SandboxInstance = class SandboxInstance {
 		let costUsd;
 		let toolInvocations;
 		let question;
+		let plan;
 		let terminalReached = false;
-		for await (const event of this._sessionEvents(id)) {
+		for await (const event of this._sessionEvents(id, void 0, true)) {
 			response = applySandboxEventText(response, event);
 			if (event.type === "result" || event.type === "done") {
 				const data = event.data;
 				usage = readTokenUsage(data) ?? usage;
 				costUsd = readTokenCostUsd(data) ?? costUsd;
 			}
+			plan = readPlanFromEvent(event) ?? plan;
 			if (event.type === "result") {
 				const data = event.data;
 				toolInvocations = readToolInvocations(data) ?? toolInvocations;
@@ -4569,7 +4662,8 @@ var SandboxInstance = class SandboxInstance {
 			runErrorCode,
 			toolInvocations,
 			approval,
-			question
+			question,
+			plan
 		});
 		return {
 			success: outcome.success,
@@ -4580,6 +4674,7 @@ var SandboxInstance = class SandboxInstance {
 			toolInvocations,
 			approval,
 			question,
+			plan,
 			traceId,
 			durationMs: Date.now() - startTime,
 			usage,
@@ -4711,8 +4806,48 @@ var SandboxInstance = class SandboxInstance {
 			throw parseErrorResponse(response.status, body, void 0, response.headers);
 		}
 	}
+	/** @internal — invoked by SandboxSession.plan(). */
+	async _currentPlan(sessionId) {
+		const path = `/v1/sandboxes/${encodeURIComponent(this.id)}/agent-sessions/${encodeURIComponent(sessionId)}/plans/current`;
+		const response = await this.client.fetch(path);
+		if (response.status === 404) return null;
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+		const decoded = await response.json();
+		if (!decoded.plan) throw new ServerError("Durable plan response is missing plan", 502, {
+			endpoint: path,
+			origin: "control-plane"
+		});
+		return decoded.plan;
+	}
+	/** @internal — invoked by SandboxSession.approvePlan()/rejectPlan(). */
+	async _decidePlan(sessionId, planId, decision) {
+		const path = `/v1/sandboxes/${encodeURIComponent(this.id)}/agent-sessions/${encodeURIComponent(sessionId)}/plans/${encodeURIComponent(planId)}/decision`;
+		const response = await this.client.fetch(path, {
+			method: "POST",
+			body: JSON.stringify(decision)
+		});
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+		const decoded = await response.json();
+		if (!decoded.plan) throw new ServerError("Plan decision response is missing plan", 502, {
+			endpoint: path,
+			origin: "control-plane"
+		});
+		return decoded.plan;
+	}
 };
 function settleTurnDrive(result) {
+	const plan = readAwaitingPlan(result);
+	if (plan) return {
+		state: "awaiting_plan_decision",
+		plan,
+		result
+	};
 	const text = typeof result.text === "string" ? result.text : typeof result.response === "string" ? result.response : void 0;
 	const status = typeof result.status === "string" ? result.status : deriveOutcome({
 		terminalReached: true,
@@ -4795,4 +4930,4 @@ function quoteForShell(value) {
 	return `'${value.replace(/'/g, "'\\''")}'`;
 }
 //#endregion
-export { InteractiveSessionHandle as a, getSandboxEventText as c, exportTraceBundle as d, otelTraceIdForTangleTrace as f, parseSSEStream as g, encodeTextForWire as h, SandboxSession as i, normalizeConnection as l, encodePromptForWire as m, normalizeStartupDiagnostics as n, applySandboxEventText as o, toOtelJson as p, SandboxTaskSession as r, collectAgentResponseText as s, SandboxInstance as t, buildTraceExportPayload as u };
+export { InteractiveSessionHandle as a, getSandboxEventText as c, exportTraceBundle as d, otelTraceIdForTangleTrace as f, SandboxSession as i, normalizeConnection as l, parseSSEStream as m, normalizeStartupDiagnostics as n, applySandboxEventText as o, toOtelJson as p, SandboxTaskSession as r, collectAgentResponseText as s, SandboxInstance as t, buildTraceExportPayload as u };