@asterxsk/kiln 0.1.0

package/agent/extensions/pi-web-access/test/proxy-transport.test.mjs

@@ -0,0 +1,286 @@
+import assert from "node:assert/strict";
+import { mkdtemp, readFile, rm, writeFile, chmod } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { delimiter, join } from "node:path";
+import { test } from "node:test";
+
+import initializeExtension from "../index.ts";
+import { getActiveProxy, installGlobalProxyFetch, runWithProxy } from "../utils.ts";
+
+const originalFetch = globalThis.fetch;
+const originalPath = process.env.PATH;
+const originalAgentDir = process.env.PI_CODING_AGENT_DIR;
+const originalNoProxy = process.env.NO_PROXY;
+const originalNoProxyLower = process.env.no_proxy;
+
+// Fake shebang executables cannot run on Windows: extensionless scripts are not
+// resolvable/spawnable via CreateProcess, and `.cmd` shims are refused by
+// child_process without `shell: true` (post CVE-2024-27980 hardening). Tests
+// below that depend on the fake curl's canned responses skip there; they still
+// run on POSIX CI. Behavior-only proxy tests are unaffected and keep running.
+const SKIP_FAKE_CURL = process.platform === "win32"
+	? "requires a runnable fake curl executable (unavailable on Windows)"
+	: false;
+
+async function withFakeCurl(t, routes, fn) {
+	const dir = await mkdtemp(join(tmpdir(), "pi-proxy-test-"));
+	const logPath = join(dir, "curl-args.jsonl");
+	const curlPath = join(dir, "curl");
+	await writeFile(curlPath, `#!/usr/bin/env node
+const fs = require("node:fs");
+const routes = JSON.parse(process.env.PI_PROXY_TEST_ROUTES);
+const args = process.argv.slice(2);
+fs.appendFileSync(process.env.PI_PROXY_TEST_LOG, JSON.stringify(args) + "\\n");
+function valueAfter(flag) {
+  const index = args.indexOf(flag);
+  return index === -1 ? null : args[index + 1];
+}
+const url = args[args.length - 1];
+const route = routes[url];
+if (!route) throw new Error("unexpected url " + url);
+fs.writeFileSync(valueAfter("-D"), "HTTP/1.1 " + route.status + " " + route.statusText + "\\r\\n" + (route.location ? "Location: " + route.location + "\\r\\n" : "") + "\\r\\n");
+fs.writeFileSync(valueAfter("--output"), route.body || "");
+process.stdout.write(JSON.stringify({ url_effective: url, num_redirects: 0 }));
+`);
+	await chmod(curlPath, 0o755);
+	if (process.platform === "win32") {
+		// Windows CreateProcess resolves executables via PATHEXT, so the
+		// extensionless shebang script above is invisible to spawn("curl").
+		// A curl.cmd shim in the same directory makes the fake win resolution.
+		await writeFile(join(dir, "curl.cmd"), `@echo off\r\nnode "%~dp0curl" %*\r\n`);
+	}
+	process.env.PATH = `${dir}${delimiter}${originalPath ?? ""}`;
+	process.env.PI_PROXY_TEST_LOG = logPath;
+	process.env.PI_PROXY_TEST_ROUTES = JSON.stringify(routes);
+	process.env.NO_PROXY = "";
+	process.env.no_proxy = "";
+	globalThis.fetch = originalFetch;
+	installGlobalProxyFetch();
+	t.after(async () => {
+		globalThis.fetch = originalFetch;
+		if (originalPath === undefined) delete process.env.PATH;
+		else process.env.PATH = originalPath;
+		if (originalNoProxy === undefined) delete process.env.NO_PROXY;
+		else process.env.NO_PROXY = originalNoProxy;
+		if (originalNoProxyLower === undefined) delete process.env.no_proxy;
+		else process.env.no_proxy = originalNoProxyLower;
+		delete process.env.PI_PROXY_TEST_LOG;
+		delete process.env.PI_PROXY_TEST_ROUTES;
+		await rm(dir, { recursive: true, force: true });
+	});
+	const result = await fn(logPath);
+	return result;
+}
+
+async function readCurlCalls(logPath) {
+	return (await readFile(logPath, "utf8"))
+		.trim()
+		.split("\n")
+		.filter(Boolean)
+		.map((line) => JSON.parse(line));
+}
+
+function headerValues(args) {
+	const values = [];
+	for (let index = 0; index < args.length; index++) {
+		if (args[index] === "-H") values.push(args[index + 1]);
+	}
+	return values;
+}
+
+function registerSourceCheck() {
+	const tools = [];
+	initializeExtension({
+		registerTool(tool) { tools.push(tool); },
+		registerCommand() {},
+		registerShortcut() {},
+		on() {},
+		appendEntry() {},
+	});
+	return tools.find((tool) => tool.name === "source_check");
+}
+
+function registerFetchContent() {
+	const tools = [];
+	initializeExtension({
+		registerTool(tool) { tools.push(tool); },
+		registerCommand() {},
+		registerShortcut() {},
+		on() {},
+		appendEntry() {},
+	});
+	return tools.find((tool) => tool.name === "fetch_content");
+}
+
+function proxyArg(args) {
+	const index = args.indexOf("-x");
+	return index === -1 ? undefined : args[index + 1];
+}
+
+test("proxy curl redirects strip caller headers across origins", { skip: SKIP_FAKE_CURL }, async (t) => {
+	await withFakeCurl(t, {
+		"https://origin.example/start": { status: 302, statusText: "Found", location: "https://other.example/final" },
+		"https://other.example/final": { status: 200, statusText: "OK", body: "ok" },
+	}, async (logPath) => {
+		const response = await runWithProxy("http://proxy.example:8080", () => fetch("https://origin.example/start", {
+			headers: {
+				Authorization: "Bearer secret",
+				Cookie: "session=secret",
+				"X-Api-Key": "secret",
+				Accept: "text/html",
+			},
+		}));
+
+		assert.equal(await response.text(), "ok");
+		assert.equal(response.url, "https://other.example/final");
+		assert.equal(response.redirected, true);
+		const calls = await readCurlCalls(logPath);
+		assert.equal(calls.length, 2);
+		assert.ok(headerValues(calls[0]).some((header) => /^authorization:/i.test(header)));
+		assert.deepEqual(headerValues(calls[1]), []);
+		assert.ok(calls.every((args) => !args.includes("--location")));
+	});
+});
+
+test("omitted proxy uses global config while empty string forces direct access", async (t) => {
+	const dir = await mkdtemp(join(tmpdir(), "pi-proxy-config-test-"));
+	await writeFile(join(dir, "web-search.json"), JSON.stringify({ proxy: "http://global-proxy.example:8080" }));
+	process.env.PI_CODING_AGENT_DIR = dir;
+	t.after(async () => {
+		if (originalAgentDir === undefined) delete process.env.PI_CODING_AGENT_DIR;
+		else process.env.PI_CODING_AGENT_DIR = originalAgentDir;
+		await rm(dir, { recursive: true, force: true });
+	});
+
+	assert.equal(runWithProxy(undefined, () => getActiveProxy()), "http://global-proxy.example:8080/");
+	assert.equal(runWithProxy("", () => getActiveProxy()), null);
+	assert.equal(runWithProxy("http://call-proxy.example:8080", () => getActiveProxy()), "http://call-proxy.example:8080/");
+});
+
+test("invalid configured proxy fails closed instead of direct fetching", async (t) => {
+	const dir = await mkdtemp(join(tmpdir(), "pi-proxy-invalid-config-test-"));
+	await writeFile(join(dir, "web-search.json"), JSON.stringify({ proxy: "socks5://proxy.example:1080" }));
+	process.env.PI_CODING_AGENT_DIR = dir;
+	t.after(async () => {
+		if (originalAgentDir === undefined) delete process.env.PI_CODING_AGENT_DIR;
+		else process.env.PI_CODING_AGENT_DIR = originalAgentDir;
+		await rm(dir, { recursive: true, force: true });
+	});
+
+	assert.throws(() => getActiveProxy(), /proxy.*must use the http:\/\/ or https:\/\/ scheme/);
+});
+
+test("proxy transport does not spawn curl for pre-aborted requests", async (t) => {
+	await withFakeCurl(t, {
+		"https://origin.example/abort": { status: 200, statusText: "OK", body: "late" },
+	}, async (logPath) => {
+		const controller = new AbortController();
+		controller.abort();
+
+		await assert.rejects(
+			runWithProxy("http://proxy.example:8080", () => fetch("https://origin.example/abort", { signal: controller.signal })),
+			/error.*abort/i,
+		);
+		await assert.rejects(readFile(logPath, "utf8"), /ENOENT/);
+	});
+});
+
+test("proxy transport errors redact proxy credentials", async (t) => {
+	await withFakeCurl(t, {}, async () => {
+		await assert.rejects(
+			runWithProxy("http://user:secret@proxy.example:8080", () => fetch("https://origin.example/missing")),
+			(error) => {
+				assert.match(error.message, /http:\/\/redacted:redacted@proxy\.example:8080\//);
+				assert.doesNotMatch(error.message, /user:secret/);
+				return true;
+			},
+		);
+	});
+});
+
+test("proxy curl redirects keep caller headers on the same origin", { skip: SKIP_FAKE_CURL }, async (t) => {
+	await withFakeCurl(t, {
+		"https://origin.example/start": { status: 302, statusText: "Found", location: "/final" },
+		"https://origin.example/final": { status: 200, statusText: "OK", body: "ok" },
+	}, async (logPath) => {
+		await runWithProxy("http://proxy.example:8080", () => fetch("https://origin.example/start", {
+			headers: { Authorization: "Bearer secret" },
+		}));
+
+		const calls = await readCurlCalls(logPath);
+		assert.equal(calls.length, 2);
+		assert.ok(headerValues(calls[1]).some((header) => /^authorization:/i.test(header)));
+	});
+});
+
+test("proxy curl keeps manual redirects as redirect responses", { skip: SKIP_FAKE_CURL }, async (t) => {
+	await withFakeCurl(t, {
+		"https://origin.example/start": { status: 302, statusText: "Found", location: "https://other.example/final" },
+	}, async (logPath) => {
+		const response = await runWithProxy("http://proxy.example:8080", () => fetch("https://origin.example/start", { redirect: "manual" }));
+
+		assert.equal(response.status, 302);
+		assert.equal(response.headers.get("location"), "https://other.example/final");
+		assert.equal((await readCurlCalls(logPath)).length, 1);
+	});
+});
+
+test("source_check fetchContent uses the explicit proxy for result pages", { skip: SKIP_FAKE_CURL }, async (t) => {
+	const previousKey = process.env.EXA_API_KEY;
+	process.env.EXA_API_KEY = "source-check-proxy-test-key";
+	t.after(() => {
+		if (previousKey === undefined) delete process.env.EXA_API_KEY;
+		else process.env.EXA_API_KEY = previousKey;
+	});
+
+	await withFakeCurl(t, {
+		"https://api.exa.ai/answer": {
+			status: 200,
+			statusText: "OK",
+			body: JSON.stringify({
+				answer: "The API docs are available.",
+				citations: [{ title: "API docs", url: "https://example.com/api" }],
+			}),
+		},
+		"https://example.com/api": { status: 200, statusText: "OK", body: "<html><title>API docs</title><body>The API docs are available.</body></html>" },
+	}, async (logPath) => {
+		const tool = registerSourceCheck();
+		assert.ok(tool);
+		const response = await tool.execute("call", {
+			claim: "API docs",
+			fetchContent: true,
+			proxy: "http://call-proxy.example:8080",
+		}, undefined, undefined, { modelRegistry: {} });
+
+		assert.equal(response.details.sourceCount, 1);
+		const calls = await readCurlCalls(logPath);
+		const apiCall = calls.find((args) => args.at(-1) === "https://api.exa.ai/answer");
+		const pageCall = calls.find((args) => args.at(-1) === "https://example.com/api");
+		assert.ok(apiCall);
+		assert.ok(pageCall);
+		assert.ok(["http://call-proxy.example:8080", "http://call-proxy.example:8080/"].includes(proxyArg(apiCall)));
+		assert.ok(["http://call-proxy.example:8080", "http://call-proxy.example:8080/"].includes(proxyArg(pageCall)));
+	});
+});
+
+test("fetch_content passes the explicit proxy through queued extraction", { skip: SKIP_FAKE_CURL }, async (t) => {
+	await withFakeCurl(t, {
+		"https://example.com/page": {
+			status: 200,
+			statusText: "OK",
+			body: "<html><title>Proxy page</title><body>Fetched through the requested proxy.</body></html>",
+		},
+	}, async (logPath) => {
+		const tool = registerFetchContent();
+		assert.ok(tool);
+		const response = await tool.execute("call", {
+			url: "https://example.com/page",
+			proxy: "http://call-proxy.example:8080",
+		});
+
+		assert.equal(response.details.successful, 1);
+		const pageCall = (await readCurlCalls(logPath)).find((args) => args.at(-1) === "https://example.com/page");
+		assert.ok(pageCall);
+		assert.ok(["http://call-proxy.example:8080", "http://call-proxy.example:8080/"].includes(proxyArg(pageCall)));
+	});
+});

package/agent/extensions/pi-web-access/test/query-rewrite.test.mjs

@@ -0,0 +1,52 @@
+import assert from "node:assert/strict";
+import { after, test } from "node:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const previousAgentDir = process.env.PI_CODING_AGENT_DIR;
+const agentDir = await mkdtemp(join(tmpdir(), "pi-query-rewrite-"));
+process.env.PI_CODING_AGENT_DIR = agentDir;
+after(async () => {
+	if (previousAgentDir === undefined) delete process.env.PI_CODING_AGENT_DIR;
+	else process.env.PI_CODING_AGENT_DIR = previousAgentDir;
+	await rm(agentDir, { recursive: true, force: true });
+});
+
+const { rewriteSearchQuery } = await import("../query-rewrite.ts");
+
+test("rewriteSearchQuery uses the registered provider runtime", async () => {
+	const model = {
+		api: "custom-rewrite-api",
+		provider: "anthropic",
+		id: "claude-haiku-4-5",
+		input: ["text"],
+	};
+	let request;
+	const signal = new AbortController().signal;
+	const result = await rewriteSearchQuery(
+		"http status codes",
+		{
+			modelRegistry: {
+				find: () => model,
+				getAvailable: () => [model],
+				getApiKeyAndHeaders: async () => ({ ok: true, apiKey: "test-key" }),
+				complete: async (calledModel, context, options) => {
+					request = { model: calledModel, context, options };
+					return {
+						stopReason: "stop",
+						content: [{ type: "text", text: "HTTP status code semantics RFC 9110" }],
+					};
+				},
+			},
+			cwd: process.cwd(),
+			isProjectTrusted: () => false,
+		},
+		signal,
+	);
+
+	assert.equal(result, "HTTP status code semantics RFC 9110");
+	assert.equal(request.model, model);
+	assert.equal(request.options.signal, signal);
+	assert.match(request.context.messages[0].content[0].text, /Query: http status codes/);
+});

package/agent/extensions/pi-web-access/test/rsc-fallback.test.mjs

@@ -0,0 +1,102 @@
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { test } from "node:test";
+
+import { extractContent } from "../extract.ts";
+
+const indexSrc = readFileSync(new URL("../index.ts", import.meta.url), "utf8");
+const lookup = async () => [{ address: "93.184.216.34", family: 4 }];
+const originalFetch = globalThis.fetch;
+
+test("weak Readability output falls back to useful RSC content", async (t) => {
+	t.after(() => { globalThis.fetch = originalFetch; });
+	const article = "RSC article content survives the loading shell. ".repeat(20);
+	const payload = `23:${JSON.stringify(["$", "article", null, { children: ["$", "p", null, { children: article }] }])}\n`;
+	globalThis.fetch = async () => new Response(
+		`<!doctype html><html><head><title>RSC article</title></head><body><article>Loading...</article><script>self.__next_f.push([1,${JSON.stringify(payload)}])</script></body></html>`,
+		{
+			status: 200,
+			headers: {
+				"content-type": "text/html",
+				link: '</openapi.json>; rel="service-desc"',
+			},
+		},
+	);
+
+	const result = await extractContent("https://example.com/rsc", undefined, { lookup });
+	assert.equal(result.error, null);
+	assert.equal(result.title, "RSC article");
+	assert.match(result.content, /RSC article content survives the loading shell/);
+	assert.match(result.content, /https:\/\/example\.com\/openapi\.json/);
+});
+
+test("null Readability output falls back to local Defuddle extraction", async (t) => {
+	t.after(() => { globalThis.fetch = originalFetch; });
+	let fetchCalls = 0;
+	const article = "Useful local Defuddle fallback content with enough detail. ".repeat(20);
+	globalThis.fetch = async () => {
+		fetchCalls += 1;
+		if (fetchCalls > 1) throw new Error("Defuddle attempted a hidden network request");
+		return new Response(
+			`<!doctype html><html><head><title>Defuddle article</title></head><body><aside><main>${article}</main></aside></body></html>`,
+			{
+				status: 200,
+				headers: {
+					"content-type": "text/html",
+					link: '</openapi.json>; rel="service-desc"',
+				},
+			},
+		);
+	};
+
+	const result = await extractContent("https://example.com/defuddle-null", undefined, { lookup });
+	assert.equal(fetchCalls, 1);
+	assert.equal(result.error, null);
+	assert.equal(result.title, "Defuddle article");
+	assert.match(result.content, /Useful local Defuddle fallback content/);
+	assert.match(result.content, /https:\/\/example\.com\/openapi\.json/);
+});
+
+test("short Readability output falls back to useful Defuddle content", async (t) => {
+	t.after(() => { globalThis.fetch = originalFetch; });
+	const article = "Useful Defuddle content after the short Readability article. ".repeat(20);
+	globalThis.fetch = async () => new Response(
+		`<!doctype html><html><head><title>Short article fallback</title></head><body><article>Loading...</article><aside><main>${article}</main></aside></body></html>`,
+		{ status: 200, headers: { "content-type": "text/html" } },
+	);
+
+	const result = await extractContent("https://example.com/defuddle-short", undefined, { lookup });
+	assert.equal(result.error, null);
+	assert.equal(result.title, "Short article fallback");
+	assert.match(result.content, /Useful Defuddle content after the short Readability article/);
+});
+
+test("short non-RSC pages remain incomplete", async (t) => {
+	t.after(() => { globalThis.fetch = originalFetch; });
+	globalThis.fetch = async () => new Response(
+		"<!doctype html><html><head><title>Short</title></head><body><article>Loading...</article></body></html>",
+		{ status: 200, headers: { "content-type": "text/html" } },
+	);
+
+	const result = await extractContent("https://example.com/short", undefined, { lookup });
+	assert.notEqual(result.error, null);
+});
+
+test("short RSC payloads remain incomplete", async (t) => {
+	t.after(() => { globalThis.fetch = originalFetch; });
+	const payload = `23:${JSON.stringify(["$", "article", null, { children: "Short RSC content" }])}\n`;
+	globalThis.fetch = async () => new Response(
+		`<!doctype html><html><head><title>Short RSC</title></head><body><script>self.__next_f.push([1,${JSON.stringify(payload)}])</script></body></html>`,
+		{ status: 200, headers: { "content-type": "text/html" } },
+	);
+
+	const result = await extractContent("https://example.com/short-rsc", undefined, { lookup });
+	assert.notEqual(result.error, null);
+});
+
+test("background fetch notification distinguishes full, partial, and failed content", () => {
+	assert.match(indexSrc, /ok === fetched\.length\r?\n\s*\? "Full page content now available\."/);
+	assert.match(indexSrc, /ok > 0\r?\n\s*\? "Partial page content now available\."/);
+	assert.match(indexSrc, /"No page content was fetched\. Stored fetch diagnostics are available\."/);
+	assert.match(indexSrc, /Content fetched for \$\{ok\}\/\$\{fetched\.length\} URLs \[\$\{fetchId\}\]\. \$\{availability\}/);
+});

package/agent/extensions/pi-web-access/test/search-error-render.test.mjs

@@ -0,0 +1,152 @@
+// Repro + guard for the web_search Ctrl+O error-path dead-end (ronin fix).
+//
+// BEFORE the fix, web_search renderResult early-returned a SINGLE line on the
+// error/cancel path (before the collapsed/expanded branch), so Ctrl+O flipped
+// `expanded` with zero visible effect and discarded the partial results. This
+// test pins the new behavior: the error/cancel path produces a rich, EXPANDABLE
+// plan (>1 line, with diagnostics + a "ctrl+o to expand" hint), routed through
+// the dep-free buildSearchErrorPlan() that index.ts.renderResult delegates to.
+//
+// Runner: node --test (matches the package's existing .test.mjs convention).
+// Node >= 22.6 imports the .ts source directly (no build step).
+
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { test } from "node:test";
+
+import { buildSearchErrorPlan } from "../render-search-error.ts";
+
+// --- fixture: a stale cancel with partial results, mirroring the user's report
+// ("Search curation cancelled (stale)" with 2/3 queries done, one errored,
+//  browser never connected). ---
+const staleCancel = {
+	error: "Search curation cancelled (stale).",
+	cancelled: true,
+	cancelReason: "stale",
+	browserConnected: false,
+	lastHeartbeatAgeMs: 31200,
+	queryCount: 3,
+	cancelledQueries: [
+		{ query: "z.ai API usage endpoint coding plan credits", provider: "perplexity", error: null, resultCount: 5 },
+		{ query: "z.ai GLM coding plan API key usage limits", provider: "perplexity", error: "Connection error", resultCount: 0 },
+	],
+};
+
+test("cancel/error path is NOT a dead-end single line: expanded plan has >1 line", () => {
+	const plan = buildSearchErrorPlan(staleCancel);
+	assert.notEqual(plan, null, "a cancelled result must produce a plan, not null");
+	const expanded = plan.expanded.join("\n");
+	// The dead-end was exactly ONE line. Pin that the expanded view is rich.
+	assert.ok(plan.expanded.length > 1, `expanded must be >1 line, got ${plan.expanded.length}`);
+	assert.match(expanded, /Search curation cancelled \(stale\)/);
+});
+
+test("expanded plan surfaces the diagnostics that were previously discarded", () => {
+	const plan = buildSearchErrorPlan(staleCancel);
+	const expanded = plan.expanded.join("\n");
+	// cancel reason
+	assert.match(expanded, /cancel reason\s*:\s*stale/);
+	// browser state — the #1 stale cause, previously invisible
+	assert.match(expanded, /browser\s*:\s*never connected/);
+	// query progress (2 of 3 done)
+	assert.match(expanded, /queries started\s*:\s*3/);
+	assert.match(expanded, /queries done\s*:\s*2/);
+	// per-query results: the completed one (with source count) AND the errored one
+	assert.match(expanded, /z\.ai API usage endpoint/);
+	assert.match(expanded, /5 sources/);
+	assert.match(expanded, /\[err\]/);
+	assert.match(expanded, /Connection error/);
+});
+
+test("collapsed view is a short summary WITH a ctrl+o expand hint (Ctrl+O now does something)", () => {
+	const plan = buildSearchErrorPlan(staleCancel);
+	// collapsed preview summarizes progress + browser state
+	const collapsed = plan.collapsed.join("\n");
+	assert.match(collapsed, /2\/3 queries completed/);
+	assert.match(collapsed, /browser never connected/);
+	// THE fix signal: an expand hint exists (the old single-line return had none,
+	// so Ctrl+O did nothing). Mutation: dropping the hint fails here.
+	assert.equal(typeof plan.expandHint, "string");
+	assert.match(plan.expandHint, /ctrl\+o to expand/i, "expand hint must mention ctrl+o");
+	// and the hint correctly counts the hidden lines
+	assert.match(plan.expandHint, /\d+ more lines/);
+});
+
+test("plain (non-cancel) error stays a clean single line — no diagnostic noise", () => {
+	// A bare argument error has nothing to diagnose; it must NOT sprout fake
+	// "browser: unknown" diagnostics. Guards the gating logic in the module.
+	const plan = buildSearchErrorPlan({ error: "No query provided" });
+	assert.notEqual(plan, null);
+	assert.equal(plan.expanded.length, 1, "plain error must be a single line");
+	assert.equal(plan.collapsed.length, 0);
+	assert.equal(plan.expandHint, null, "plain error must have no expand hint");
+});
+
+// --- other tools (fetch_content / get_search_content): the same
+// dead-end exists in their renderResults; they now reuse buildSearchErrorPlan via
+// extraLines. These pin that non-cancel errors with detail become expandable
+// WITHOUT provider/browser diagnostics (which are web_search-only). ---
+
+test("fetch_content-style error (extras, no cancel) is expandable without browser diagnostics", () => {
+	const plan = buildSearchErrorPlan({
+		error: "Failed to fetch: https://example.com/x (404)",
+		extraLines: ["urls: 1/2 succeeded", "response id: resp_abc", "  \u25b8 https://example.com/x"],
+	});
+	assert.notEqual(plan, null);
+	const expanded = plan.expanded.join("\n");
+	assert.ok(plan.expanded.length > 1);
+	assert.match(expanded, /urls: 1\/2 succeeded/);
+	assert.match(expanded, /resp_abc/);
+	// MUST NOT show provider/browser diagnostics for a non-cancel error.
+	assert.doesNotMatch(expanded, /browser|cancel reason|queries started/);
+	assert.equal(typeof plan.expandHint, "string");
+	assert.match(plan.expandHint, /ctrl\+o to expand/i);
+});
+
+test("non-search error with extras shows detail without browser diagnostics", () => {
+	const plan = buildSearchErrorPlan({
+		error: "Exa search failed: connection reset",
+		extraLines: ["query: how to use p-limit concurrency"],
+	});
+	assert.notEqual(plan, null);
+	assert.match(plan.expanded.join("\n"), /query: how to use p-limit concurrency/);
+	assert.doesNotMatch(plan.expanded.join("\n"), /browser/);
+	assert.equal(typeof plan.expandHint, "string");
+});
+
+test("error with NO extras and NO cancel stays single-line", () => {
+	// e.g. fetch_content with no url — nothing to diagnose.
+	const plan = buildSearchErrorPlan({ error: "Some transient error" });
+	assert.notEqual(plan, null);
+	assert.equal(plan.expanded.length, 1);
+	assert.equal(plan.expandHint, null);
+});
+
+test("non-error result yields null so the caller falls through to the success renderer", () => {
+	assert.equal(buildSearchErrorPlan({ queryCount: 3, totalResults: 9 }), null);
+	assert.equal(buildSearchErrorPlan(undefined), null);
+	assert.equal(buildSearchErrorPlan(null), null);
+});
+
+// --- source-contract guard: index.ts web_search renderResult must DELEGATE to
+// buildSearchErrorPlan on the error path (mutation-proof against reverting the
+// integration back to the dead-end single-line return). ---
+const indexPath = fileURLToPath(new URL("../index.ts", import.meta.url));
+const indexSrc = readFileSync(indexPath, "utf8");
+
+test("index.ts imports buildSearchErrorPlan and wires it into the web_search error path", () => {
+	assert.match(indexSrc, /import \{ buildSearchErrorPlan, type SearchErrorDetails, type SearchErrorPlan \} from "\.\/render-search-error\.ts";/);
+	// The web_search renderResult error branch must call buildSearchErrorPlan.
+	// (Mutation: reverting renderResult to `return new Text(error...)` drops this.)
+	assert.match(indexSrc, /buildSearchErrorPlan\(details as SearchErrorDetails\)/);
+	assert.match(indexSrc, /cancelledQueries/);
+	// the 2 other tools must also delegate to buildSearchErrorPlan (mutation-proof:
+	// reverting any of them to the bare single-line drops its buildSearchErrorPlan call).
+	// Count call sites: web_search + fetch_content + get_search_content = 3.
+	const callSiteCount = (indexSrc.match(/const plan = buildSearchErrorPlan\(/g) || []).length;
+	assert.equal(callSiteCount, 3, `expected 3 buildSearchErrorPlan call sites, got ${callSiteCount}`);
+	// renderSearchErrorPlan shared renderer is used by all 3.
+	const renderCount = (indexSrc.match(/return renderSearchErrorPlan\(plan, expanded, theme\)/g) || []).length;
+	assert.equal(renderCount, 3, `expected 3 renderSearchErrorPlan returns, got ${renderCount}`);
+});