@asterxsk/kiln 0.1.0 → 0.3.0

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

@@ -1,52 +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/);
-});
+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

@@ -1,102 +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\}/);
-});
+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

@@ -1,152 +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}`);
-});
+// 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}`);
+});