@gajae-code/coding-agent 0.16.3 → 0.16.6

package/src/tools/skill.ts

@@ -32,6 +32,10 @@ import { getSkillManifest } from "../gjc-runtime/workflow-manifest";
 import skillDescription from "../prompts/tools/skill.md" with { type: "text" };
 import { SKILL_PROMPT_MESSAGE_TYPE } from "../session/messages";
 import { isCanonicalGjcWorkflowSkill } from "../skill-state/active-state";
+import {
+	getSkillFilesystemIdentity,
+	isCanonicalGjcWorkflowSkillFilesystemAlias,
+} from "../skill-state/canonical-skills";
 import type { ToolSession } from ".";
 import { ToolError } from "./tool-errors";
 
@@ -66,6 +70,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>;
 
@@ -137,6 +161,12 @@ export class SkillTool implements AgentTool<typeof skillSchema, SkillToolDetails
 					`skill tool: "${requestedName}" is not a valid skill name. The name must be a single concrete skill (e.g. "ralplan"), not a glob or wildcard pattern. Pass one exact skill name as shown in /skill:<name>.`,
 				);
 			}
+			if (
+				isCanonicalGjcWorkflowSkillFilesystemAlias(requestedName) &&
+				getSkillFilesystemIdentity(requestedName) !== requestedName.toLowerCase()
+			) {
+				throw new ToolError(`skill tool: refusing filesystem alias for bundled workflow skill "${requestedName}"`);
+			}
 			const activeState = this.#session.getActiveSkillState?.();
 			const activeSkill = normalizeSkillName(activeState?.skill);
 			if (activeSkill && requestedName === activeSkill) {
@@ -145,6 +175,9 @@ export class SkillTool implements AgentTool<typeof skillSchema, SkillToolDetails
 				);
 			}
 
+			const agentDir =
+				this.#session.getSessionAgentDir?.() ??
+				(this.#session.home === undefined ? this.#session.settings.getAgentDir() : undefined);
 			const skill =
 				skills.find(s => s.name === requestedName) ??
 				(await findRuntimeSkillByName(
@@ -152,12 +185,14 @@ export class SkillTool implements AgentTool<typeof skillSchema, SkillToolDetails
 					requestedName,
 					this.#getRuntimeSkillPolicy(),
 					this.#session.home,
+					agentDir,
+					this.#session.profileAuthority,
 				));
 			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

@@ -12,6 +12,7 @@ import { ToolError } from "./tool-errors";
 
 const DEFAULT_AWAIT_TIMEOUT_MS = 30_000;
 const MAX_AWAIT_TIMEOUT_MS = 60 * 60 * 1000;
+const MAX_AWAIT_HEARTBEAT_MS = 60_000;
 /**
  * Bounded cadence for await liveness: even when the rendered-state signature is
  * stable (a running subagent emitting no new progress), the await panel re-emits
@@ -47,9 +48,9 @@ const subagentSchema = z.object({
 		.describe("terminal wait condition; defaults to all_terminal"),
 	heartbeat_ms: z
 		.number()
-		.refine(value => value === 0 || (Number.isInteger(value) && value >= 100 && value <= 5000))
+		.refine(value => value === 0 || (Number.isInteger(value) && value >= 100 && value <= MAX_AWAIT_HEARTBEAT_MS))
 		.optional()
-		.describe("heartbeat interval; 0 disables"),
+		.describe(`heartbeat interval in milliseconds (100-${MAX_AWAIT_HEARTBEAT_MS}); 0 disables`),
 	timeout_ms: z.number().min(0).max(MAX_AWAIT_TIMEOUT_MS).optional().describe("await timeout in milliseconds"),
 	limit: z.number().min(1).max(MAX_LIST_LIMIT).optional().describe("maximum subagents to return"),
 	verbosity: z
@@ -227,7 +228,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": [
@@ -2236,7 +2243,7 @@ export const TOOL_CATALOG: Readonly<Record<string, ToolCatalogEntry>> = {
 	"subagent": {
 		"name": "subagent",
 		"label": "Subagent",
-		"description": "Lists, inspects, awaits, pauses, resumes, steers, or cancels detached task subagents.\n\nTask launches return immediately. Use this tool when you need direct control over those running subagents. Prefer `subagent` for task subagents; generic `job` remains available for non-subagent jobs and compatibility fallback access.\n\n`verbosity` controls output size: `receipt` (default) returns status metadata plus a single ≤280-character result/error preview and an `agent://<id>` output ref when available; `preview` returns ≤2000 characters; `full` returns ≤12000 characters and requires explicit `ids`.\n\n# Operations\n\n## `action: \"list\"`\nSnapshot your visible detached subagents, including `running`, `paused`, `queued`, and terminal subagents when retained. Optional `limit` (1–50) caps how many subagents are returned. Output is receipt-only by default; use `verbosity: \"preview\"` for a bounded preview or inspect explicit `ids` with `verbosity: \"full\"` when fuller retained text is necessary.\n\n## `action: \"inspect\"`\nInspect selected subagents by `ids`; omit `ids` to inspect current running subagents. Terminal subagents return receipt-only output by default, with an `agent://<id>` ref when a verified output artifact is available. `verbosity: \"full\"` requires explicit `ids`.\n\n## `action: \"await\"`\nWait for selected subagents by `ids`; omit `ids` to wait for current running subagents.\n- Always set `timeout_ms` when the result is not immediately required forever.\n- Await timeout only bounds this tool call's wait; it does not stop the subagent and is not a failure reason.\n- On timeout, inspect progress and keep doing independent work. Never cancel just because an await timed out; cancel only if the subagent has actually failed, gone off-track, or become unrecoverably wrong.\n- Completed results are receipt-first by default: bounded preview plus `agent://<id>` output ref when available, not full retained output.\n\n## `action: \"pause\"`\nRequest a graceful safe-boundary pause for selected subagents by `ids`.\n- Non-running subagents are a no-op and return their current status snapshot.\n- A paused subagent keeps its session context and can be resumed later.\n\n## `action: \"resume\"`\nResume one subagent by `id` (preferred) or a single-item `ids` array.\n- Optional `message` is delivered into that one resumed run.\n- Running subagents are a no-op and return their current status snapshot.\n- Terminal subagents require `message` to start a follow-up resume run; without `message`, the tool returns the current snapshot with guidance.\n- `paused` subagents resume from saved context; `queued` subagents are already waiting for capacity.\n- Multiple targets are rejected because one global `message` must not broadcast to several subagents.\n\n## `action: \"steer\"`\nSend a non-empty `message` to one subagent by `id` (preferred) or a single-item `ids` array.\n- A running subagent receives the message through its live handle.\n- Optional `pause: true` requests a safe-boundary pause after steering a running subagent.\n- `pause` only matters while the target is running.\n- A non-active subagent (`paused`, `queued`, or terminal) automatically resumes with the message; `pause` is ignored for that target.\n- Multiple targets are rejected because one global `message` must not broadcast to several subagents.\n\n## `action: \"cancel\"`\nStop selected subagents by `ids`, including running, paused, or queued subagents.\n- Use only when the subagent has actually failed, gone off-track, or become unrecoverably wrong; an await timeout alone is never a cancellation reason.\n- Cancellation keeps the subagent session file for possible later context recovery.\n\n# Statuses\n\n- `running` — currently executing.\n- `paused` — stopped at a safe boundary with resumable context.\n- `queued` — resume requested and waiting for execution capacity.\n- `completed` — finished successfully.\n- `failed` — finished with an error.\n- `cancelled` — stopped by cancellation.\n- `not_found` — no visible subagent matches the requested id.",
+		"description": "Lists, inspects, awaits, pauses, resumes, steers, or cancels detached task subagents.\n\nTask launches return immediately. Use this tool when you need direct control over those running subagents. Prefer `subagent` for task subagents; generic `job` remains available for non-subagent jobs and compatibility fallback access.\n\n`verbosity` controls output size: `receipt` (default) returns status metadata plus a single ≤280-character result/error preview and an `agent://<id>` output ref when available; `preview` returns ≤2000 characters; `full` returns ≤12000 characters and requires explicit `ids`.\n\n# Operations\n\n## `action: \"list\"`\nSnapshot your visible detached subagents, including `running`, `paused`, `queued`, and terminal subagents when retained. Optional `limit` (1–50) caps how many subagents are returned. Output is receipt-only by default; use `verbosity: \"preview\"` for a bounded preview or inspect explicit `ids` with `verbosity: \"full\"` when fuller retained text is necessary.\n\n## `action: \"inspect\"`\nInspect selected subagents by `ids`; omit `ids` to inspect current running subagents. Terminal subagents return receipt-only output by default, with an `agent://<id>` ref when a verified output artifact is available. `verbosity: \"full\"` requires explicit `ids`.\n\n## `action: \"await\"`\nWait for selected subagents by `ids`; omit `ids` to wait for current running subagents.\n- Always set `timeout_ms` when the result is not immediately required forever.\n- `heartbeat_ms` accepts integer intervals from 100 to 60,000 milliseconds (for example, 10,000 for ten seconds); `0` disables heartbeat updates and omission retains the 500 ms default. Terminal completion is event-driven, not delayed until the next heartbeat.\n- Await timeout only bounds this tool call's wait; it does not stop the subagent and is not a failure reason.\n- On timeout, inspect progress and keep doing independent work. Never cancel just because an await timed out; cancel only if the subagent has actually failed, gone off-track, or become unrecoverably wrong.\n- Completed results are receipt-first by default: bounded preview plus `agent://<id>` output ref when available, not full retained output.\n\n## `action: \"pause\"`\nRequest a graceful safe-boundary pause for selected subagents by `ids`.\n- Non-running subagents are a no-op and return their current status snapshot.\n- A paused subagent keeps its session context and can be resumed later.\n\n## `action: \"resume\"`\nResume one subagent by `id` (preferred) or a single-item `ids` array.\n- Optional `message` is delivered into that one resumed run.\n- Running subagents are a no-op and return their current status snapshot.\n- Terminal subagents require `message` to start a follow-up resume run; without `message`, the tool returns the current snapshot with guidance.\n- `paused` subagents resume from saved context; `queued` subagents are already waiting for capacity.\n- Multiple targets are rejected because one global `message` must not broadcast to several subagents.\n\n## `action: \"steer\"`\nSend a non-empty `message` to one subagent by `id` (preferred) or a single-item `ids` array.\n- A running subagent receives the message through its live handle.\n- Optional `pause: true` requests a safe-boundary pause after steering a running subagent.\n- `pause` only matters while the target is running.\n- A non-active subagent (`paused`, `queued`, or terminal) automatically resumes with the message; `pause` is ignored for that target.\n- Multiple targets are rejected because one global `message` must not broadcast to several subagents.\n\n## `action: \"cancel\"`\nStop selected subagents by `ids`, including running, paused, or queued subagents.\n- Use only when the subagent has actually failed, gone off-track, or become unrecoverably wrong; an await timeout alone is never a cancellation reason.\n- Cancellation keeps the subagent session file for possible later context recovery.\n\n# Statuses\n\n- `running` — currently executing.\n- `paused` — stopped at a safe boundary with resumable context.\n- `queued` — resume requested and waiting for execution capacity.\n- `completed` — finished successfully.\n- `failed` — finished with an error.\n- `cancelled` — stopped by cancellation.\n- `not_found` — no visible subagent matches the requested id.",
 		"parameters": {
 			"type": "object",
 			"properties": {
@@ -2281,7 +2288,7 @@ export const TOOL_CATALOG: Readonly<Record<string, ToolCatalogEntry>> = {
 					]
 				},
 				"heartbeat_ms": {
-					"description": "heartbeat interval; 0 disables",
+					"description": "heartbeat interval in milliseconds (100-60000); 0 disables",
 					"type": "number"
 				},
 				"timeout_ms": {

package/src/tools/ultragoal-ask-guard.ts

@@ -70,9 +70,9 @@ export function guardToolForUltragoalAsk<T extends AgentTool>(
 	const candidate = tool as GuardedTool;
 	if (candidate[ULTRAGOAL_ASK_GUARD]) return tool;
 	const wrapped = new Proxy(tool, {
-		get(target, prop, receiver) {
+		get(target, prop) {
 			if (prop === ULTRAGOAL_ASK_GUARD) return true;
-			if (prop !== "execute") return Reflect.get(target, prop, receiver);
+			if (prop !== "execute") return Reflect.get(target, prop);
 			return async (...args: unknown[]): Promise<unknown> => {
 				// The wrapper runs BEFORE AskTool.execute(): resolve the nudge
 				// budget against the SESSION profile, never the process-global one.

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);
 }