@gajae-code/coding-agent 0.16.1 → 0.16.4

package/src/tools/skill.ts

@@ -66,6 +66,26 @@ function normalizeSkillName(name: string | undefined): string {
 }
 
 const SKILL_NAME_GLOB_PATTERN = /[*?[\]{}]/;
+const MAX_AVAILABLE_SKILL_NAMES = 50;
+const MAX_AVAILABLE_SKILL_CHARS = 2048;
+
+function formatAvailableSkills(skills: readonly { name: string }[]): string {
+	const names = [...new Set(skills.map(skill => skill.name))].sort();
+	const visible: string[] = [];
+	let visibleChars = 0;
+	for (let index = 0; index < names.length && visible.length < MAX_AVAILABLE_SKILL_NAMES; index++) {
+		const name = names[index];
+		const separatorChars = visible.length > 0 ? 2 : 0;
+		const omittedAfterAdding = names.length - (visible.length + 1);
+		const markerChars = omittedAfterAdding > 0 ? `, … (+${omittedAfterAdding} more)`.length : 0;
+		if (visibleChars + separatorChars + name.length + markerChars > MAX_AVAILABLE_SKILL_CHARS) break;
+		visible.push(name);
+		visibleChars += separatorChars + name.length;
+	}
+	const omitted = names.length - visible.length;
+	const marker = omitted > 0 ? `… (+${omitted} more)` : "";
+	return visible.length > 0 && marker ? `${visible.join(", ")}, ${marker}` : visible.join(", ") || marker;
+}
 
 type SkillToolInput = z.infer<typeof skillSchema>;
 
@@ -154,10 +174,10 @@ export class SkillTool implements AgentTool<typeof skillSchema, SkillToolDetails
 					this.#session.home,
 				));
 			if (!skill) {
-				const available = skills.map(s => s.name).sort();
+				const available = formatAvailableSkills(skills);
 				const hint =
 					available.length > 0
-						? ` Available: ${available.join(", ")}. Use skill_discovery to find project/user runtime skills.`
+						? ` Available: ${available}. Use skill_discovery to find project/user runtime skills.`
 						: " Use skill_discovery to find project/user runtime skills.";
 				throw new ToolError(`skill tool: unknown skill "${requestedName}".${hint}`);
 			}

package/src/tools/subagent.ts

@@ -227,7 +227,9 @@ export class SubagentTool implements AgentTool<typeof subagentSchema, SubagentTo
 		// or belong to a same-id subagent of another session (review thread P1).
 		const manager =
 			this.session.getAsyncJobManager?.() ??
-			AsyncJobManager.forEndpoint(this.session.getSessionId?.() ?? undefined) ??
+			AsyncJobManager.forEndpoint(
+				this.session.getAsyncEndpointId?.() ?? this.session.getSessionId?.() ?? undefined,
+			) ??
 			AsyncJobManager.instance();
 		if (!manager) {
 			return {

package/src/tools/tool-catalog.generated.ts

@@ -988,7 +988,7 @@ export const TOOL_CATALOG: Readonly<Record<string, ToolCatalogEntry>> = {
 	"search": {
 		"name": "search",
 		"label": "Search",
-		"description": "Searches files using powerful regex matching.\n\n<instruction>\n- Supports Rust regex syntax (RE2-style — no lookaround or backreferences). Use line anchors or post-filters instead of (?!…)/(?<!…)\n- `paths` accepts an array of files, directories, globs, or internal URLs; when omitted, the whole working directory is searched\n- `paths` is an array; do not embed commas or spaces inside a single entry. Pass `[\"src\", \"tests\"]` not `[\"src,tests\"]`.\n- Cross-line patterns are detected from literal `\\n` or escaped `\\\\n` in `pattern`\n</instruction>\n\n<output>\n</output>\n\n<critical>\n- Search paths are an array; pass separate entries rather than comma-joined paths.\n- Use a cross-line pattern only when the match actually spans lines.\n</critical>",
+		"description": "Searches files using powerful regex matching.\n\n<instruction>\n- Supports Rust regex syntax (RE2-style — no lookaround or backreferences). Use line anchors or post-filters instead of (?!…)/(?<!…)\n- `paths` accepts an array of files, directories, globs, or internal URLs; when omitted, the whole working directory is searched\n- `paths` is an array; do not embed commas or spaces inside a single entry. Pass `[\"src\", \"tests\"]` not `[\"src,tests\"]`.\n- Cross-line patterns are detected from literal `\\n` or escaped `\\\\n` in `pattern`\n- `timeout` is in seconds (default 5, range 0.5–60). Increase it only for intentionally broad searches; narrow `paths` first\n</instruction>\n\n<output>\n</output>\n\n<critical>\n- Search paths are an array; pass separate entries rather than comma-joined paths.\n- Use a cross-line pattern only when the match actually spans lines.\n- Do not retry a timed-out search unchanged; narrow `paths`/`pattern` or explicitly increase `timeout`.\n</critical>",
 		"parameters": {
 			"type": "object",
 			"properties": {
@@ -1016,6 +1016,13 @@ export const TOOL_CATALOG: Readonly<Record<string, ToolCatalogEntry>> = {
 				"skip": {
 					"description": "files to skip before collecting results — use to paginate when the prior call hit the file limit",
 					"type": "number"
+				},
+				"timeout": {
+					"default": 5,
+					"description": "timeout in seconds (0.5–60)",
+					"type": "number",
+					"minimum": 0.5,
+					"maximum": 60
 				}
 			},
 			"required": [
@@ -2319,7 +2326,7 @@ export const TOOL_CATALOG: Readonly<Record<string, ToolCatalogEntry>> = {
 	"job": {
 		"name": "job",
 		"label": "Job",
-		"description": "Inspects, waits, or cancels async jobs.\n\nBackground job results are delivered automatically when complete. Jobs that back task subagents should be controlled via the `subagent` tool when it is available; use `job` for non-subagent jobs (async bash, monitors) and as a compatibility fallback. Running job output stays quiet by default to avoid flooding the conversation; use `tail` when you explicitly want to show/reopen retained output. Reach for this tool only when you need to inspect or intervene.\n\nIn the interactive TUI, a running foreground command can be folded into a background job by pressing the fold chord twice (default `Alt+Shift+B`, plus `Cmd+B` on macOS; remappable via `app.tool.backgroundFold`), or automatically when the user sends a steer after the command has run for at least 2 seconds (with `busyPromptMode=steer` and `toolInterruptPolicy=abort_tools`). This covers managed non-PTY bash, editor/ACP client-terminal commands, and PTY-mode commands. A folded job keeps its original deadline, is never killed or restarted by folding, and its result wakes a later turn automatically; a folded PTY continues output-only and no longer accepts input. Job listings expose `foldReason` (`steer`, `chord`, `timer`, or `sdk_control`) beside `backgrounded` so you can tell why a job left the foreground. `task`/`subagent` waits are not foldable. Raw shell `Ctrl+Z`/`bg` is not the supported path inside GJC because it bypasses job ownership and output-routing contracts.\n\n# Operations\n\n## `list: true`\nUse to inspect what's running.\n\n## `tail: [id, …]`\nShow the retained output buffer for one or more background jobs without waiting.\n- Use this to reopen/tail a backgrounded long-running bash/tool output after folding it away.\n- Output is bounded by the manager retention window; stale cursors may report that only the retained tail is available.\n- Prefer `tail` over polling when you only need to peek at progress, so the conversation can continue without flooding the TUI.\n\n## `poll: [id, …]`\nBlock until the specified jobs finish or the wait window (~30 s, not configurable) elapses.\n- Use when you are genuinely blocked on a result and have no other work to do.\n- Returns the current snapshot when the timer elapses; running jobs remain running.\n- Completed jobs include their final output in the returned snapshot.\n\n## `cancel: [id, …]`\nStop running jobs.\n- Use when a job is stalled, hung, or no longer needed.\n- Returns immediately after cancelling.",
+		"description": "Inspects, waits, or cancels async jobs.\n\nBackground job results are delivered automatically when complete. Jobs that back task subagents should be controlled via the `subagent` tool when it is available; use `job` for non-subagent jobs (async bash, monitors) and as a compatibility fallback. Running job output stays quiet by default to avoid flooding the conversation; use `tail` when you explicitly want to show/reopen retained output. Reach for this tool only when you need to inspect or intervene.\n\nIn the interactive TUI, a running foreground command can be folded into a background job by pressing the fold chord twice (default `Alt+Shift+B`, plus `Cmd+B` on macOS; remappable via `app.tool.backgroundFold`), or automatically when the user sends a steer after the command has run for at least 2 seconds (with `busyPromptMode=steer` (`toolInterruptPolicy` is not a gate)). This covers managed non-PTY bash, editor/ACP client-terminal commands, and PTY-mode commands. A folded job keeps its original deadline, is never killed or restarted by folding, and its result wakes a later turn automatically; a folded PTY continues output-only and no longer accepts input. Job listings expose `foldReason` (`steer`, `chord`, `timer`, or `sdk_control`) beside `backgrounded` so you can tell why a job left the foreground. `task`/`subagent` waits are not foldable. Raw shell `Ctrl+Z`/`bg` is not the supported path inside GJC because it bypasses job ownership and output-routing contracts.\n\n# Operations\n\n## `list: true`\nUse to inspect what's running.\n\n## `tail: [id, …]`\nShow the retained output buffer for one or more background jobs without waiting.\n- Use this to reopen/tail a backgrounded long-running bash/tool output after folding it away.\n- Output is bounded by the manager retention window; stale cursors may report that only the retained tail is available.\n- Prefer `tail` over polling when you only need to peek at progress, so the conversation can continue without flooding the TUI.\n\n## `poll: [id, …]`\nBlock until the specified jobs finish or the wait window (~30 s, not configurable) elapses.\n- Use when you are genuinely blocked on a result and have no other work to do.\n- Returns the current snapshot when the timer elapses; running jobs remain running.\n- Completed jobs include their final output in the returned snapshot.\n\n## `cancel: [id, …]`\nStop running jobs.\n- Use when a job is stalled, hung, or no longer needed.\n- Returns immediately after cancelling.",
 		"parameters": {
 			"type": "object",
 			"properties": {

package/src/utils/external-editor.ts

@@ -65,8 +65,22 @@ const ENABLE_ECHO_INPUT = 0x0004;
 const ENABLE_WINDOW_INPUT = 0x0008;
 const ENABLE_VIRTUAL_TERMINAL_INPUT = 0x0200;
 
-function prepareWindowsConsoleForExternalEditor(): void {
-	if (process.platform !== "win32") return;
+interface RawModeInput {
+	setRawMode?: (mode: boolean) => unknown;
+}
+
+export function prepareWindowsConsoleForExternalEditor(
+	platform: NodeJS.Platform = process.platform,
+	input: RawModeInput = process.stdin,
+): void {
+	if (platform !== "win32") return;
+	// Native Windows terminals can expose stdin through a ConPTY pipe rather than
+	// a console input handle. In that case GetConsoleMode/SetConsoleMode below
+	// cannot re-arm the input stream, but the runtime's TTY implementation can.
+	try {
+		input.setRawMode?.(true);
+	} catch {}
+
 	try {
 		const kernel32 = dlopen("kernel32.dll", {
 			GetStdHandle: { args: [FFIType.i32], returns: FFIType.ptr },

package/src/web/insane/bridge.ts

@@ -15,6 +15,8 @@ import { type ChildProcess, spawn as nodeSpawn } from "node:child_process";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import { $which } from "@gajae-code/utils";
+import { probeLinuxProcPidSync } from "../../gjc-runtime/linux-proc";
+import { groupLeaderIdentityMatches } from "../../runtime/process-lifecycle";
 
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 /** packages/coding-agent/vendor/insane-search */
@@ -119,22 +121,85 @@ function appendCapped(buffer: string, chunk: string, cap: number): string {
 	return buffer + (chunk.length > remaining ? chunk.slice(0, remaining) : chunk);
 }
 
-/** Kill a child and its group, escalating to SIGKILL after a grace period. */
-function killChild(child: ChildProcess): void {
+/**
+ * Signal the child's whole process group on POSIX (the engine is spawned as a
+ * group leader, so its node/playwright grandchildren — including headless
+ * Chromium — are covered), with an exact-child fallback on Windows.
+ */
+type TeardownStatus = "terminated" | "still_running" | "identity_unverified";
+
+function processGroupAlive(pgid: number): boolean {
 	try {
-		child.kill("SIGTERM");
-	} catch {
-		// already gone
+		process.kill(-pgid, 0);
+		return true;
+	} catch (error) {
+		return (error as NodeJS.ErrnoException).code === "EPERM";
+	}
+}
+
+async function pollUntil(predicate: () => boolean, timeoutMs: number): Promise<boolean> {
+	if (predicate()) return true;
+	const deadline = Date.now() + timeoutMs;
+	while (Date.now() < deadline) {
+		await Bun.sleep(Math.min(20, deadline - Date.now()));
+		if (predicate()) return true;
 	}
-	const timer = setTimeout(() => {
+	return predicate();
+}
+
+/** Idempotently terminate the exact child/process group and await bounded reaping. */
+function createChildTeardown(child: ChildProcess, childExited: Promise<void>): () => Promise<TeardownStatus> {
+	const pgid = process.platform !== "win32" ? child.pid : undefined;
+	const leader = pgid && process.platform === "linux" ? probeLinuxProcPidSync(pgid) : undefined;
+	const leaderStartTime = leader?.kind === "live" ? leader.startTime : undefined;
+	let teardownPromise: Promise<TeardownStatus> | undefined;
+
+	const identityMatches = (): boolean => {
+		if (!pgid || process.platform !== "linux") return true;
+		return groupLeaderIdentityMatches(leaderStartTime, probeLinuxProcPidSync(pgid));
+	};
+	const signalGroup = (signal: "SIGTERM" | "SIGKILL"): boolean => {
+		if (!pgid || !identityMatches()) return false;
 		try {
-			child.kill("SIGKILL");
+			process.kill(-pgid, signal);
+			return true;
 		} catch {
-			// already gone
+			return !processGroupAlive(pgid);
 		}
-	}, KILL_GRACE_MS);
-	timer.unref?.();
-	child.once("exit", () => clearTimeout(timer));
+	};
+	const signalChild = (signal: "SIGTERM" | "SIGKILL"): void => {
+		try {
+			child.kill(signal);
+		} catch {
+			// Exact child is already gone.
+		}
+	};
+
+	return () => {
+		if (teardownPromise) return teardownPromise;
+		teardownPromise = (async (): Promise<TeardownStatus> => {
+			if (pgid) {
+				if (!processGroupAlive(pgid)) return "terminated";
+				if (!identityMatches()) return "identity_unverified";
+				signalGroup("SIGTERM");
+				if (await pollUntil(() => !processGroupAlive(pgid), KILL_GRACE_MS)) return "terminated";
+				if (!identityMatches()) return "identity_unverified";
+				signalGroup("SIGKILL");
+				return (await pollUntil(() => !processGroupAlive(pgid), KILL_GRACE_MS)) ? "terminated" : "still_running";
+			}
+
+			if (child.exitCode !== null || child.signalCode !== null) return "terminated";
+			signalChild("SIGTERM");
+			if ((await Promise.race([childExited.then(() => true), Bun.sleep(KILL_GRACE_MS).then(() => false)])) === true)
+				return "terminated";
+			signalChild("SIGKILL");
+			return (await Promise.race([childExited.then(() => true), Bun.sleep(KILL_GRACE_MS).then(() => false)])) ===
+				true
+				? "terminated"
+				: "still_running";
+		})();
+		return teardownPromise;
+	};
 }
 
 /** Real engine runner: `python3 -m engine "<url>" --json`. */
@@ -149,31 +214,45 @@ export function runEngineSubprocess(
 		let settled = false;
 		let timedOut = false;
 		let aborted = false;
+		let closeObserved = false;
+		let closeCode: number | null = null;
+		let teardownDone = false;
+		let teardownPromise: Promise<TeardownStatus> | undefined;
+		const { promise: childExited, resolve: resolveChildExited } = Promise.withResolvers<void>();
 
 		const child = spawnImpl("python3", ["-m", "engine", inv.url, "--json"], {
 			cwd: INSANE_VENDOR_DIR,
 			env: { ...process.env, PYTHONPATH: INSANE_VENDOR_DIR },
 			stdio: ["ignore", "pipe", "pipe"],
+			// Own process group on POSIX so killChild can signal the engine's
+			// whole tree (python3 -> node -> headless Chromium) in one shot.
+			detached: process.platform !== "win32",
 		});
+		const teardown = createChildTeardown(child, childExited);
 
-		const finish = (code: number | null): void => {
+		const finish = (): void => {
 			if (settled) return;
+			if (teardownPromise ? !teardownDone : !closeObserved) return;
 			settled = true;
 			clearTimeout(timer);
 			inv.signal?.removeEventListener("abort", onAbort);
-			resolve({ code, stdout, stderr, timedOut, aborted });
+			resolve({ code: closeObserved ? closeCode : null, stdout, stderr, timedOut, aborted });
+		};
+		const requestStop = (reason: "timeout" | "abort"): void => {
+			if (teardownPromise) return;
+			if (reason === "timeout") timedOut = true;
+			else aborted = true;
+			teardownPromise = teardown();
+			void teardownPromise.finally(() => {
+				teardownDone = true;
+				finish();
+			});
 		};
 
-		const timer = setTimeout(() => {
-			timedOut = true;
-			killChild(child);
-		}, inv.timeoutMs);
+		const timer = setTimeout(() => requestStop("timeout"), inv.timeoutMs);
 		timer.unref?.();
 
-		const onAbort = (): void => {
-			aborted = true;
-			killChild(child);
-		};
+		const onAbort = (): void => requestStop("abort");
 		if (inv.signal) {
 			if (inv.signal.aborted) onAbort();
 			else inv.signal.addEventListener("abort", onAbort, { once: true });
@@ -185,8 +264,19 @@ export function runEngineSubprocess(
 		child.stderr?.on("data", (chunk: Buffer) => {
 			stderr = appendCapped(stderr, chunk.toString("utf8"), MAX_STDERR_BYTES);
 		});
-		child.on("error", () => finish(null));
-		child.on("close", code => finish(code));
+		child.once("exit", () => resolveChildExited());
+		child.on("error", () => {
+			resolveChildExited();
+			closeObserved = true;
+			closeCode = null;
+			finish();
+		});
+		child.on("close", code => {
+			resolveChildExited();
+			closeObserved = true;
+			closeCode = code;
+			finish();
+		});
 	});
 }
 

package/src/web/search/providers/perplexity.ts

@@ -9,16 +9,9 @@
 
 import { type AuthStorage, getEnvApiKey } from "@gajae-code/ai/core";
 import { $env, readSseJson } from "@gajae-code/utils";
-import type {
-	PerplexityMessageOutput,
-	PerplexityRequest,
-	PerplexityResponse,
-	SearchCitation,
-	SearchResponse,
-	SearchSource,
-} from "../../../web/search/types";
+import type { PerplexityRequest, SearchCitation, SearchResponse, SearchSource } from "../../../web/search/types";
 import { SearchProviderError } from "../../../web/search/types";
-import { dateToAgeSeconds } from "../utils";
+import { clampNumResults, dateToAgeSeconds } from "../utils";
 import type { SearchParams } from "./base";
 import { SearchProvider } from "./base";
 import { classifyProviderHttpError, withHardTimeout } from "./utils";
@@ -29,6 +22,8 @@ const PERPLEXITY_OAUTH_ASK_URL = "https://www.perplexity.ai/rest/sse/perplexity_
 const DEFAULT_MAX_TOKENS = 8192;
 const DEFAULT_TEMPERATURE = 0.2;
 const DEFAULT_NUM_SEARCH_RESULTS = 10;
+const MIN_NUM_SEARCH_RESULTS = 3;
+const MAX_NUM_SEARCH_RESULTS = 100;
 const OAUTH_EXPIRY_BUFFER_MS = 5 * 60 * 1000;
 const OAUTH_API_VERSION = "2.18";
 const OAUTH_USER_AGENT = "Perplexity/641 CFNetwork/1568 Darwin/25.2.0";
@@ -239,11 +234,7 @@ async function findPerplexityAuth(
 }
 
 /** Call Perplexity API-key endpoint. */
-async function callPerplexityApi(
-	apiKey: string,
-	request: PerplexityRequest,
-	signal?: AbortSignal,
-): Promise<PerplexityResponse> {
+async function callPerplexityApi(apiKey: string, request: PerplexityRequest, signal?: AbortSignal): Promise<unknown> {
 	const response = await fetch(PERPLEXITY_API_URL, {
 		method: "POST",
 		headers: {
@@ -258,14 +249,15 @@ async function callPerplexityApi(
 		const errorText = await response.text();
 		const classified = classifyProviderHttpError("perplexity", response.status, errorText);
 		if (classified) throw classified;
-		throw new SearchProviderError(
-			"perplexity",
-			`Perplexity API error (${response.status}): ${errorText}`,
-			response.status,
-		);
+		throw new SearchProviderError("perplexity", `Perplexity API error (${response.status})`, response.status);
 	}
 
-	return response.json() as Promise<PerplexityResponse>;
+	try {
+		return await response.json();
+	} catch (error) {
+		if (error instanceof Error && error.name === "AbortError") throw error;
+		throw new SearchProviderError("perplexity", "Perplexity API returned invalid JSON", 502);
+	}
 }
 
 function buildOAuthSources(event: PerplexityOAuthStreamEvent): SearchSource[] {
@@ -377,11 +369,7 @@ async function callPerplexityOAuth(
 		const errorText = await response.text();
 		const classified = classifyProviderHttpError("perplexity", response.status, errorText);
 		if (classified) throw classified;
-		throw new SearchProviderError(
-			"perplexity",
-			`Perplexity OAuth API error (${response.status}): ${errorText}`,
-			response.status,
-		);
+		throw new SearchProviderError("perplexity", `Perplexity OAuth API error (${response.status})`, response.status);
 	}
 
 	if (!response.body) {
@@ -426,22 +414,79 @@ async function callPerplexityOAuth(
 	};
 }
 
-function messageContentToText(content: PerplexityMessageOutput["content"]): string {
-	if (!content) return "";
+type JsonObject = Record<string, unknown>;
+
+function malformedResponse(detail: string): never {
+	throw new SearchProviderError("perplexity", `Perplexity API returned malformed response body (${detail})`, 502);
+}
+
+function isJsonObject(value: unknown): value is JsonObject {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function optionalArray(value: unknown, detail: string): unknown[] {
+	if (value === undefined || value === null) return [];
+	if (!Array.isArray(value)) malformedResponse(detail);
+	return value;
+}
+
+function messageContentToText(content: unknown): string {
+	if (content === undefined || content === null) return "";
 	if (typeof content === "string") return content;
-	return content.map(chunk => (chunk.type === "text" ? chunk.text : "")).join("");
+	if (!Array.isArray(content)) malformedResponse("message content must be a string or array");
+
+	return content
+		.map(chunk => {
+			if (!isJsonObject(chunk) || typeof chunk.type !== "string") {
+				malformedResponse("message content chunks must be objects with a type");
+			}
+			if (chunk.type !== "text") return "";
+			if (typeof chunk.text !== "string") malformedResponse("text content chunks must contain text");
+			return chunk.text;
+		})
+		.join("");
 }
 
 /** Parse API response into unified SearchResponse */
-function parseResponse(response: PerplexityResponse): SearchResponse {
-	const messageContent = response.choices[0]?.message?.content ?? null;
+function parseResponse(value: unknown): SearchResponse {
+	if (!isJsonObject(value)) malformedResponse("expected a JSON object");
+
+	const choices = optionalArray(value.choices, "choices must be an array");
+	const firstChoice = choices[0];
+	if (firstChoice !== undefined && !isJsonObject(firstChoice)) malformedResponse("choices must contain objects");
+	const message = firstChoice?.message;
+	if (message !== undefined && !isJsonObject(message)) malformedResponse("choice message must be an object");
+	const messageContent = message?.content;
 	const answer = messageContentToText(messageContent);
 
 	const sources: SearchSource[] = [];
 	const citations: SearchCitation[] = [];
 
-	const citationUrls = response.citations ?? [];
-	const searchResults = response.search_results ?? [];
+	const citationUrls = optionalArray(value.citations, "citations must be an array").map(url => {
+		if (typeof url !== "string" || url.length === 0) malformedResponse("citations must contain non-empty URLs");
+		return url;
+	});
+	const searchResults = optionalArray(value.search_results, "search_results must be an array").map(result => {
+		if (!isJsonObject(result)) malformedResponse("search_results must contain objects");
+		if (typeof result.url !== "string" || result.url.length === 0) {
+			malformedResponse("search_results entries must contain a non-empty URL");
+		}
+		if (result.title !== undefined && typeof result.title !== "string") {
+			malformedResponse("search_results titles must be strings");
+		}
+		if (result.snippet !== undefined && typeof result.snippet !== "string") {
+			malformedResponse("search_results snippets must be strings");
+		}
+		if (result.date !== undefined && result.date !== null && typeof result.date !== "string") {
+			malformedResponse("search_results dates must be strings");
+		}
+		return {
+			title: result.title ?? result.url,
+			url: result.url,
+			snippet: result.snippet,
+			date: result.date,
+		};
+	});
 
 	if (citationUrls.length > 0) {
 		for (const url of citationUrls) {
@@ -475,18 +520,23 @@ function parseResponse(response: PerplexityResponse): SearchResponse {
 		answer: answer || undefined,
 		sources,
 		citations: citations.length > 0 ? citations : undefined,
-		usage: response.usage
+		usage: isJsonObject(value.usage)
 			? {
-					inputTokens: response.usage.prompt_tokens,
-					outputTokens: response.usage.completion_tokens,
-					totalTokens: response.usage.total_tokens,
+					inputTokens: typeof value.usage.prompt_tokens === "number" ? value.usage.prompt_tokens : undefined,
+					outputTokens:
+						typeof value.usage.completion_tokens === "number" ? value.usage.completion_tokens : undefined,
+					totalTokens: typeof value.usage.total_tokens === "number" ? value.usage.total_tokens : undefined,
 				}
 			: undefined,
-		model: response.model,
-		requestId: response.id,
+		model: typeof value.model === "string" ? value.model : undefined,
+		requestId: typeof value.id === "string" ? value.id : undefined,
 	};
 }
 
+function normalizeNumSearchResults(value: number | undefined): number {
+	return Math.max(MIN_NUM_SEARCH_RESULTS, clampNumResults(value, DEFAULT_NUM_SEARCH_RESULTS, MAX_NUM_SEARCH_RESULTS));
+}
+
 function applySourceLimit(result: SearchResponse, limit?: number): SearchResponse {
 	if (limit && result.sources.length > limit) {
 		result.sources = result.sources.slice(0, limit);
@@ -503,6 +553,9 @@ export async function searchPerplexity(params: PerplexitySearchParams): Promise<
 
 	if (auth.type === "oauth" || auth.type === "cookies") {
 		const oauthResult = await callPerplexityOAuth(auth, params);
+		if (!oauthResult.answer.trim()) {
+			throw new SearchProviderError("perplexity", "Perplexity web search returned no answer", 424);
+		}
 		return applySourceLimit(
 			{
 				provider: "perplexity",
@@ -529,7 +582,7 @@ export async function searchPerplexity(params: PerplexitySearchParams): Promise<
 		max_tokens: params.max_tokens ?? DEFAULT_MAX_TOKENS,
 		temperature: params.temperature ?? DEFAULT_TEMPERATURE,
 		search_mode: "web",
-		num_search_results: params.num_search_results ?? DEFAULT_NUM_SEARCH_RESULTS,
+		num_search_results: normalizeNumSearchResults(params.num_search_results),
 		web_search_options: {
 			search_type: "pro",
 			search_context_size: "medium",
@@ -543,8 +596,16 @@ export async function searchPerplexity(params: PerplexitySearchParams): Promise<
 		request.search_recency_filter = params.search_recency_filter;
 	}
 
-	const response = await callPerplexityApi(auth.token, request, params.signal);
-	const result = parseResponse(response);
+	let result: SearchResponse | undefined;
+	for (let attempt = 0; attempt < 2; attempt++) {
+		const response = await callPerplexityApi(auth.token, request, params.signal);
+		result = parseResponse(response);
+		if (result.answer?.trim()) break;
+	}
+
+	if (!result?.answer?.trim()) {
+		throw new SearchProviderError("perplexity", "Perplexity web search returned no answer", 424);
+	}
 	result.authMode = "api_key";
 	return applySourceLimit(result, params.num_results);
 }