@gajae-code/coding-agent 0.11.2 → 0.11.4

package/src/tools/browser/tab-supervisor.ts

@@ -19,7 +19,6 @@ import type {
 	RunResultOk,
 	SessionSnapshot,
 	Transferable,
-	Transport,
 	WorkerInbound,
 	WorkerInitPayload,
 	WorkerOutbound,
@@ -38,8 +37,8 @@ interface WorkerHandle {
 	send(msg: WorkerInbound, transferList?: Transferable[]): void;
 	onMessage(handler: (msg: WorkerOutbound) => void): () => void;
 	onError(handler: (error: Error) => void): () => void;
+	onClose(handler: () => void): () => void;
 	terminate(): Promise<void>;
-	readonly mode: "worker" | "inline";
 }
 
 export type DialogPolicy = "accept" | "dismiss";
@@ -118,6 +117,13 @@ let workerInitializerForTest:
 	| ((worker: WorkerHandle, payload: WorkerInitPayload, timeoutMs: number) => Promise<ReadyInfo>)
 	| undefined;
 const GRACE_MS = 750;
+const TAB_WORKER_MODE = "native-free";
+
+function startupError(stage: string): ToolError {
+	return new ToolError(
+		`Tab worker startup failed (stage=${stage}, mode=${TAB_WORKER_MODE}, platform=${process.platform}).`,
+	);
+}
 
 interface DeadTabDescriptor {
 	tab: TabSession;
@@ -152,7 +158,7 @@ async function awaitWithinBudget(op: Promise<unknown>, remainingMs: number, labe
 		logger.debug("close teardown budget already spent; detaching step", { label });
 		return false;
 	}
-	let timer: ReturnType<typeof setTimeout> | undefined;
+	let timer: NodeJS.Timeout | undefined;
 	const timedOut = new Promise<boolean>(resolve => {
 		timer = setTimeout(() => resolve(false), remainingMs);
 	});
@@ -358,64 +364,69 @@ export async function acquireTab(
 		if (replacementHold) await releaseBrowser(browser, { kill: false });
 		throw error;
 	}
-	let worker = await spawnAcquireWorker();
-	let info: ReadyInfo;
+	let worker: WorkerHandle;
 	try {
-		info = await initializeAcquireWorker(worker, initPayload, opts.timeoutMs + GRACE_MS);
-	} catch (error) {
-		// `BuildMessage`-class failures arrive asynchronously via the worker's `error` event,
-		// after `spawnTabWorker`'s synchronous try/catch has already returned. Fall back to
-		// the inline worker here so module-resolution failures don't poison every tab open.
-		await worker.terminate().catch(() => undefined);
-		if (worker.mode === "inline") {
-			if (replacementHold) await releaseBrowser(browser, { kill: false });
-			else if (browser.refCount === 0) await releaseBrowser(browser, { kill: false });
-			throw error;
-		}
-		logger.warn("Tab worker init failed; retrying with inline tab worker (no sync-loop guard)", {
-			error: error instanceof Error ? error.message : String(error),
-		});
-		worker = await (workerFactoryForTest?.() ?? spawnInlineWorker());
-		try {
-			info = await initializeAcquireWorker(worker, initPayload, opts.timeoutMs + GRACE_MS);
-		} catch (inlineError) {
-			await worker.terminate().catch(() => undefined);
-			if (replacementHold) await releaseBrowser(browser, { kill: false });
-			else if (browser.refCount === 0) await releaseBrowser(browser, { kill: false });
-			const finalError = new ToolError(
-				`Failed to start browser tab worker (inline fallback also failed): ${inlineError instanceof Error ? inlineError.message : String(inlineError)}`,
-			);
-			(finalError as { cause?: unknown }).cause = error;
-			throw finalError;
+		worker = await spawnAcquireWorker();
+	} catch {
+		if (replacementHold) await releaseBrowser(browser, { kill: false });
+		else if (browser.refCount === 0) await releaseBrowser(browser, { kill: false });
+		throw startupError("spawn");
+	}
+	let registeredTab: TabSession | undefined;
+	let startupFailure: Error | undefined;
+	let browserHeld = false;
+	const observeFailure = (error: Error): void => {
+		if (registeredTab) markTabDead(registeredTab, error);
+		else startupFailure ??= error;
+	};
+	const unlistenLifetimeMessages = worker.onMessage(msg => {
+		if (msg.type === "closed") observeFailure(startupError("protocol-closed"));
+	});
+	const unlistenLifetimeErrors = worker.onError(() => observeFailure(startupError("error")));
+	const unlistenLifetimeClose = worker.onClose(() => observeFailure(startupError("physical-close")));
+	try {
+		const info = await initializeAcquireWorker(worker, initPayload, opts.timeoutMs + GRACE_MS);
+		afterWorkerInitializationForTest?.(name);
+		if (startupFailure) throw startupFailure;
+		if (opts.requireVacantName && tabs.has(name))
+			throw new ToolError(`Tab ${JSON.stringify(name)} was replaced during recovery.`);
+
+		holdBrowser(browser);
+		browserHeld = true;
+		if (replacementHold) {
+			await releaseBrowser(browser, { kill: false });
+			replacementHold = false;
 		}
-	}
-
-	afterWorkerInitializationForTest?.(name);
-	if (opts.requireVacantName && tabs.has(name)) {
+		if (startupFailure) throw startupFailure;
+
+		const tab: TabSession = {
+			name,
+			browser,
+			targetId: info.targetId,
+			worker,
+			state: "alive",
+			info,
+			pending: new Map(),
+			dialogPolicy: opts.dialogs,
+			kindTag: browser.kind.kind,
+			ownerId: opts.ownerId,
+			lastUsedAt: Date.now(),
+			recoveryOpts: freezeRecoveryOptions(opts),
+		};
+		registeredTab = tab;
+		worker.onMessage(msg => handleTabMessage(tab, msg));
+		tabs.set(name, tab);
+		return { tab, created: true };
+	} catch (error) {
+		unlistenLifetimeMessages();
+		unlistenLifetimeErrors();
+		unlistenLifetimeClose();
 		await worker.terminate().catch(() => undefined);
+		if (browserHeld) await releaseBrowser(browser, { kill: false });
 		if (replacementHold) await releaseBrowser(browser, { kill: false });
-		throw new ToolError(`Tab ${JSON.stringify(name)} was replaced during recovery.`);
+		else if (!browserHeld && browser.refCount === 0) await releaseBrowser(browser, { kill: false });
+		throw error;
 	}
-	holdBrowser(browser);
-	if (replacementHold) await releaseBrowser(browser, { kill: false });
-	const tab: TabSession = {
-		name,
-		browser,
-		targetId: info.targetId,
-		worker,
-		state: "alive",
-		info,
-		pending: new Map(),
-		dialogPolicy: opts.dialogs,
-		kindTag: browser.kind.kind,
-		ownerId: opts.ownerId,
-		lastUsedAt: Date.now(),
-		recoveryOpts: freezeRecoveryOptions(opts),
-	};
-	worker.onMessage(msg => handleTabMessage(tab, msg));
-	worker.onError(error => markTabDead(tab, error));
-	tabs.set(name, tab);
-	return { tab, created: true };
 }
 
 export async function runInTab(name: string, opts: RunInTabOptions): Promise<RunResultOk> {
@@ -871,22 +882,14 @@ async function raceWithTimeout<T>(
 }
 
 async function spawnTabWorker(): Promise<WorkerHandle> {
-	try {
-		const worker = isCompiledBinary()
-			? new Worker("./packages/coding-agent/src/tools/browser/tab-worker-entry.ts", { type: "module" })
-			: new Worker(new URL("./tab-worker-entry.ts", import.meta.url).href, { type: "module" });
-		return wrapBunWorker(worker);
-	} catch (err) {
-		logger.warn("Bun Worker spawn failed; using inline tab worker (no sync-loop guard)", {
-			error: err instanceof Error ? err.message : String(err),
-		});
-		return spawnInlineWorker();
-	}
+	const worker = isCompiledBinary()
+		? new Worker("./packages/coding-agent/src/tools/browser/tab-worker-entry.ts", { type: "module" })
+		: new Worker(new URL("./tab-worker-entry.ts", import.meta.url).href, { type: "module" });
+	return wrapBunWorker(worker);
 }
 
 function wrapBunWorker(worker: Worker): WorkerHandle {
 	return {
-		mode: "worker",
 		send(msg, transferList) {
 			worker.postMessage(msg, { transfer: transferList ?? [] });
 		},
@@ -896,9 +899,8 @@ function wrapBunWorker(worker: Worker): WorkerHandle {
 			return () => worker.removeEventListener("message", wrap);
 		},
 		onError(handler) {
-			const onError = (event: ErrorEvent): void => handler(errorFromWorkerEvent(event));
-			const onMessageError = (event: MessageEvent): void =>
-				handler(new ToolError(`Tab worker message error: ${String(event.data)}`));
+			const onError = (): void => handler(startupError("error"));
+			const onMessageError = (): void => handler(startupError("messageerror"));
 			worker.addEventListener("error", onError);
 			worker.addEventListener("messageerror", onMessageError);
 			return () => {
@@ -906,69 +908,76 @@ function wrapBunWorker(worker: Worker): WorkerHandle {
 				worker.removeEventListener("messageerror", onMessageError);
 			};
 		},
+		onClose(handler) {
+			const onClose = (): void => handler();
+			worker.addEventListener("close", onClose);
+			return () => worker.removeEventListener("close", onClose);
+		},
 		async terminate() {
 			worker.terminate();
 		},
 	};
 }
 
-/**
- * Inline fallback for environments where Bun cannot compile or spawn the worker
- * entry. This preserves normal browser behavior but cannot interrupt synchronous
- * infinite loops because user code runs on the main thread.
- */
-async function spawnInlineWorker(): Promise<WorkerHandle> {
-	const hostListeners = new Set<(message: WorkerOutbound) => void>();
-	const workerListeners = new Set<(message: WorkerInbound) => void>();
-	const workerTransport: Transport = {
-		send: msg =>
-			queueMicrotask(() => {
-				for (const listener of hostListeners) listener(msg as WorkerOutbound);
-			}),
-		onMessage: handler => {
-			const typed = handler as (message: WorkerInbound) => void;
-			workerListeners.add(typed);
-			return () => workerListeners.delete(typed);
-		},
-		close: () => {},
-	};
-	const { WorkerCore } = await import("./tab-worker");
-	new WorkerCore(workerTransport);
-	return {
-		mode: "inline",
-		send: msg =>
-			queueMicrotask(() => {
-				for (const listener of workerListeners) listener(msg);
-			}),
-		onMessage: handler => {
-			hostListeners.add(handler);
-			return () => hostListeners.delete(handler);
-		},
-		onError: () => () => {},
-		async terminate() {},
-	};
-}
-
 async function initializeTabWorker(
 	worker: WorkerHandle,
 	payload: WorkerInitPayload,
 	timeoutMs: number,
 ): Promise<ReadyInfo> {
-	const { promise, resolve, reject } = Promise.withResolvers<ReadyInfo>();
+	type StartupPhase = "await-bootstrap" | "bootstrap-confirmed" | "await-init";
+	let phase: StartupPhase = "await-bootstrap";
+	const { promise: bootstrap, resolve: bootstrapReady, reject: rejectBootstrap } = Promise.withResolvers<void>();
+	const { promise: initialized, resolve: ready, reject: rejectInitialized } = Promise.withResolvers<ReadyInfo>();
+	void initialized.catch(() => undefined);
+	const fail = (stage: string): void => {
+		const error = startupError(stage);
+		rejectBootstrap(error);
+		rejectInitialized(error);
+	};
 	const unlisten = worker.onMessage(msg => {
-		if (msg.type === "ready") resolve(msg.info);
-		else if (msg.type === "init-failed") reject(errorFromPayload(msg.error));
-		else if (msg.type === "log") logWorkerMessage(msg);
-	});
-	const unlistenError = worker.onError(error => {
-		reject(new ToolError(`Tab worker failed during startup: ${error.message}`));
+		if (msg.type === "log") {
+			logWorkerMessage(msg);
+			return;
+		}
+		if (phase === "await-bootstrap") {
+			if (msg.type === "bootstrap-ready" && msg.version === 1 && msg.mode === TAB_WORKER_MODE) {
+				phase = "bootstrap-confirmed";
+				bootstrapReady();
+			} else if (msg.type === "bootstrap-failed") {
+				fail("bootstrap");
+			} else if (msg.type === "closed") {
+				fail("protocol-closed");
+			} else {
+				fail("protocol-phase");
+			}
+			return;
+		}
+		if (phase !== "await-init") {
+			fail("protocol-phase");
+			return;
+		}
+		if (msg.type === "ready") {
+			ready(msg.info);
+		} else if (msg.type === "init-failed") {
+			fail("init");
+		} else if (msg.type === "closed") {
+			fail("protocol-closed");
+		} else {
+			fail("protocol-phase");
+		}
 	});
+	const unlistenError = worker.onError(() => fail("error"));
+	const unlistenClose = worker.onClose(() => fail("physical-close"));
 	try {
+		worker.send({ type: "bootstrap", version: 1, mode: TAB_WORKER_MODE });
+		await raceWithTimeout(bootstrap, timeoutMs, startupError("bootstrap-timeout").message);
+		phase = "await-init";
 		worker.send({ type: "init", payload });
-		return await raceWithTimeout(promise, timeoutMs, "Timed out initializing browser tab worker");
+		return await raceWithTimeout(initialized, timeoutMs, startupError("init-timeout").message);
 	} finally {
 		unlisten();
 		unlistenError();
+		unlistenClose();
 	}
 }
 
@@ -979,9 +988,3 @@ export function initializeTabWorkerForTest(
 ): Promise<ReadyInfo> {
 	return initializeTabWorker(worker, payload, timeoutMs);
 }
-
-function errorFromWorkerEvent(event: ErrorEvent): Error {
-	if (event.error instanceof Error) return event.error;
-	if (event.message) return new Error(event.message);
-	return new Error("Unknown tab worker error");
-}

package/src/tools/browser/tab-worker-entry.ts

@@ -3,19 +3,38 @@ import type { Transport, WorkerInbound, WorkerOutbound } from "./tab-protocol";
 import { WorkerCore } from "./tab-worker";
 
 if (!parentPort) throw new Error("tab-worker-entry: missing parentPort");
+const port = parentPort;
+port.once("message", bootstrap => {
+	if (!isBootstrap(bootstrap)) {
+		port.postMessage({ type: "bootstrap-failed", error: "Invalid tab worker bootstrap." });
+		port.close();
+		return;
+	}
 
-const transport: Transport = {
-	send(msg, transferList) {
-		parentPort!.postMessage(msg, transferList ?? []);
-	},
-	onMessage(handler) {
-		const wrap = (message: unknown): void => handler(message as WorkerOutbound | WorkerInbound);
-		parentPort!.on("message", wrap);
-		return () => parentPort!.off("message", wrap);
-	},
-	close() {
-		parentPort!.close();
-	},
-};
+	const transport: Transport = {
+		send(msg, transferList) {
+			port.postMessage(msg, transferList ?? []);
+		},
+		onMessage(handler) {
+			const wrap = (message: unknown): void => handler(message as WorkerOutbound | WorkerInbound);
+			port.on("message", wrap);
+			return () => port.off("message", wrap);
+		},
+		close() {
+			port.close();
+		},
+	};
 
-new WorkerCore(transport);
+	new WorkerCore(transport);
+	port.postMessage({ type: "bootstrap-ready", version: 1, mode: "native-free" });
+});
+
+function isBootstrap(message: unknown): message is Extract<WorkerInbound, { type: "bootstrap" }> {
+	return (
+		typeof message === "object" &&
+		message !== null &&
+		(message as { type?: unknown }).type === "bootstrap" &&
+		(message as { version?: unknown }).version === 1 &&
+		(message as { mode?: unknown }).mode === "native-free"
+	);
+}

package/src/tools/browser/tab-worker-path-resolver.ts

@@ -0,0 +1,67 @@
+import * as os from "node:os";
+import * as path from "node:path";
+import * as url from "node:url";
+
+const UNICODE_SPACES = /[\u00A0\u2000-\u200A\u202F\u205F\u3000]/g;
+const TOP_LEVEL_INTERNAL_URL_PREFIXES = ["agent://", "artifact://", "rule://", "local://"] as const;
+
+function normalizeAtPrefix(filePath: string): string {
+	if (!filePath.startsWith("@")) return filePath;
+
+	const withoutAt = filePath.slice(1);
+	if (
+		withoutAt.startsWith("/") ||
+		withoutAt === "~" ||
+		withoutAt.startsWith("~/") ||
+		path.win32.isAbsolute(withoutAt) ||
+		withoutAt.startsWith("agent://") ||
+		withoutAt.startsWith("artifact://") ||
+		withoutAt.startsWith("rule://") ||
+		withoutAt.startsWith("local:")
+	) {
+		return withoutAt;
+	}
+
+	return filePath;
+}
+
+function expandPath(filePath: string): string {
+	const normalized = normalizeAtPrefix(filePath).replace(UNICODE_SPACES, " ");
+	if (normalized.toLowerCase().startsWith("file://")) {
+		try {
+			return expandTilde(url.fileURLToPath(normalized));
+		} catch {
+			return normalized;
+		}
+	}
+	return expandTilde(normalized);
+}
+
+function expandTilde(filePath: string): string {
+	const home = os.homedir();
+	if (filePath === "~") return home;
+	if (filePath.startsWith("~/") || filePath.startsWith("~\\")) return home + filePath.slice(1);
+	if (filePath.startsWith("~")) return path.join(home, filePath.slice(1));
+	return filePath;
+}
+
+function normalizeLocalScheme(filePath: string): string {
+	return filePath.replace(/^(local:)\/(?!\/)/, "$1//");
+}
+
+/** Resolve filesystem-only worker inputs without evaluating the broad path utility module. */
+export function resolveTabWorkerPath(filePath: string, cwd: string): string {
+	const normalized = normalizeLocalScheme(filePath);
+	const expanded = expandPath(normalized);
+	const expandedAndNormalized = normalizeLocalScheme(expanded);
+	for (const prefix of TOP_LEVEL_INTERNAL_URL_PREFIXES) {
+		if (expandedAndNormalized.startsWith(prefix)) {
+			throw new Error(
+				`Path "${normalized}" uses internal scheme "${prefix}" and must be resolved through the proper protocol handler, not as a filesystem path.`,
+			);
+		}
+	}
+
+	if (/^\/+$/u.test(expanded)) return cwd;
+	return path.isAbsolute(expanded) ? expanded : path.resolve(cwd, expanded);
+}

package/src/tools/browser/tab-worker-smoke.ts

@@ -0,0 +1,87 @@
+import { isCompiledBinary } from "@gajae-code/utils/env";
+import type { WorkerInbound, WorkerOutbound } from "./tab-protocol";
+
+interface SmokeWorkerHandle {
+	postMessage(message: WorkerInbound): void;
+	addEventListener(type: string, listener: EventListener): void;
+	removeEventListener(type: string, listener: EventListener): void;
+	terminate(): void;
+}
+
+const SMOKE_TIMEOUT_MS = 5_000;
+const TAB_WORKER_MODE = "native-free";
+
+function smokeStartupError(stage: string): Error {
+	return new Error(
+		`Tab worker startup failed (stage=${stage}, mode=${TAB_WORKER_MODE}, platform=${process.platform}).`,
+	);
+}
+
+/**
+ * Starts the real tab worker entry without connecting to a browser, then proves
+ * its bootstrap and shutdown protocol. The compiled branch deliberately keeps
+ * a static literal for Bun's --compile worker discovery.
+ */
+export async function smokeTestTabWorker(timeoutMs = SMOKE_TIMEOUT_MS): Promise<void> {
+	const worker = isCompiledBinary()
+		? new Worker("./packages/coding-agent/src/tools/browser/tab-worker-entry.ts", { type: "module" })
+		: new Worker(new URL("./tab-worker-entry.ts", import.meta.url).href, { type: "module" });
+	await smokeTestTabWorkerWithWorkerForTest(worker, timeoutMs);
+}
+
+/** Test-only: verify the smoke handshake against a controlled worker transport. */
+export async function smokeTestTabWorkerWithWorkerForTest(worker: SmokeWorkerHandle, timeoutMs: number): Promise<void> {
+	type SmokePhase = "await-bootstrap" | "await-closed";
+	let phase: SmokePhase = "await-bootstrap";
+	const { promise, resolve, reject } = Promise.withResolvers<void>();
+	let settled = false;
+	let timeout: NodeJS.Timeout | undefined;
+
+	const cleanup = (): void => {
+		if (timeout) clearTimeout(timeout);
+		worker.removeEventListener("message", onMessage);
+		worker.removeEventListener("error", onError);
+		worker.removeEventListener("messageerror", onMessageError);
+	};
+	const succeed = (): void => {
+		if (settled) return;
+		settled = true;
+		resolve();
+	};
+	const fail = (stage: string): void => {
+		if (settled) return;
+		settled = true;
+		reject(smokeStartupError(stage));
+	};
+	const onMessage: EventListener = event => {
+		const message = (event as MessageEvent<WorkerOutbound>).data;
+		if (message.type === "log") return;
+		if (phase === "await-bootstrap") {
+			if (message.type === "bootstrap-ready" && message.version === 1 && message.mode === TAB_WORKER_MODE) {
+				phase = "await-closed";
+				worker.postMessage({ type: "close" } satisfies WorkerInbound);
+			} else if (message.type === "bootstrap-failed") {
+				fail("bootstrap");
+			} else {
+				fail("protocol-phase");
+			}
+			return;
+		}
+		if (message.type === "closed") succeed();
+		else fail("protocol-phase");
+	};
+	const onError: EventListener = () => fail("error");
+	const onMessageError: EventListener = () => fail("messageerror");
+
+	worker.addEventListener("message", onMessage);
+	worker.addEventListener("error", onError);
+	worker.addEventListener("messageerror", onMessageError);
+	timeout = setTimeout(() => fail("smoke-timeout"), timeoutMs);
+	try {
+		worker.postMessage({ type: "bootstrap", version: 1, mode: TAB_WORKER_MODE } satisfies WorkerInbound);
+		await promise;
+	} finally {
+		cleanup();
+		worker.terminate();
+	}
+}

package/src/tools/browser/tab-worker.ts

@@ -2,7 +2,8 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 
-import { Snowflake, untilAborted } from "@gajae-code/utils";
+import { untilAborted } from "@gajae-code/utils/abortable";
+import { Snowflake } from "@gajae-code/utils/snowflake";
 import type { HTMLElement } from "linkedom";
 import type {
 	Browser,
@@ -17,8 +18,6 @@ import type {
 import { JsRuntime, type RuntimeHooks } from "../../eval/js/shared/runtime";
 import type { JsDisplayOutput } from "../../eval/js/shared/types";
 import { resizeImage } from "../../utils/image-resize";
-import { resolveToCwd } from "../path-utils";
-import { formatScreenshot } from "../render-utils";
 import { ToolAbortError, ToolError, throwIfAborted } from "../tool-errors";
 import {
 	applyStealthPatches,
@@ -28,6 +27,7 @@ import {
 	loadPuppeteerInWorker,
 } from "./launch";
 import { extractReadableFromHtml, type ReadableFormat, type ReadableResult } from "./readable";
+import { formatScreenshot } from "./screenshot-format";
 import type {
 	Observation,
 	ObservationEntry,
@@ -41,6 +41,7 @@ import type {
 	WorkerInbound,
 	WorkerInitPayload,
 } from "./tab-protocol";
+import { resolveTabWorkerPath } from "./tab-worker-path-resolver";
 
 declare global {
 	interface Element extends HTMLElement {}
@@ -813,7 +814,8 @@ export class WorkerCore {
 			{ type: "image", data: buffer.toBase64(), mimeType: "image/png" },
 			{ maxWidth: 1024, maxHeight: 1024, maxBytes: 150 * 1024, jpegQuality: 70 },
 		);
-		const explicitPath = opts.save ? resolveToCwd(opts.save, session.cwd) : undefined;
+		const explicitPath = opts.save ? resolveTabWorkerPath(opts.save, session.cwd) : undefined;
+
 		const dest =
 			explicitPath ??
 			(session.browserScreenshotDir
@@ -950,7 +952,7 @@ export class WorkerCore {
 			page.locator(normalizeSelector(selector)).setTimeout(timeoutMs).waitHandle(),
 		)) as ElementHandle;
 		try {
-			const absolute = filePaths.map(filePath => resolveToCwd(filePath, session.cwd));
+			const absolute = filePaths.map(filePath => resolveTabWorkerPath(filePath, session.cwd));
 			const upload = handle as unknown as { uploadFile: (...paths: string[]) => Promise<void> };
 			const tagName = (await untilAborted(signal, () =>
 				handle.evaluate(el => (el as unknown as { tagName: string }).tagName),

package/src/tools/output-meta.ts

@@ -605,6 +605,10 @@ async function spillLargeResultToArtifact(
 	toolName: string,
 	context: AgentToolContext | undefined,
 ): Promise<AgentToolResult> {
+	if (toolName === "read" && (result.details as { spillEligible?: boolean } | undefined)?.spillEligible !== true) {
+		return result;
+	}
+
 	const artifactCapability = artifactCapabilityForContext(context);
 	if (!artifactCapability) return result;
 	const { threshold, readThreshold, tailBytes, tailLines, headBytes } = getSpillConfig(context?.settings);
@@ -709,8 +713,8 @@ async function spillLargeResultToArtifact(
 /**
  * Absolute inline-size backstop enforced after {@link spillLargeResultToArtifact}.
  *
- * The threshold-based spill above has escape hatches: it early-returns for the
- * `read` tool and for results that already carry an `artifactId` (a tool may set
+ * The threshold-based spill above has escape hatches: it skips ineligible `read`
+ * results and results that already carry an `artifactId` (a tool may set
  * partial truncation meta yet still emit oversized inline text). This backstop
  * closes those gaps: when `tools.maxInlineResultBytes` is configured (> 0), any
  * final result whose inline text exceeds the cap is force-saved to an artifact