gsd-pi 2.33.1-dev.29a8268 → 2.33.1-dev.9bafd68

package/src/resources/extensions/search-the-web/index.ts

@@ -1,65 +1,48 @@
 /**
  * Web Search Extension v4
  *
- * Provides three tools for grounding the agent in real-world web content:
- *
- *   search-the-web   — Rich web search with extra snippets, freshness filtering,
- *                      domain scoping, AI summarizer, and compact output format.
- *                      Returns links and snippets for selective browsing.
- *
- *   fetch_page       — Extract clean markdown from any URL via Jina Reader.
- *                      Supports offset-based continuation, CSS selector targeting,
- *                      and content-type-aware extraction.
- *
- *   search_and_read  — Single-call search + content extraction via Brave LLM Context API.
- *                      Returns pre-extracted, relevance-scored page content.
- *                      Best when you need content, not just links.
- *
- * v4: Native Anthropic web search
- * - When using an Anthropic provider, injects the native `web_search_20250305`
- *   server-side tool via `before_provider_request`. This eliminates the need for
- *   a BRAVE_API_KEY when using Anthropic models — search is billed through the
- *   existing Anthropic API key ($0.01/search).
- * - Custom Brave-based tools (search-the-web, search_and_read) are disabled when
- *   Anthropic + no BRAVE_API_KEY to avoid confusing the LLM with broken tools.
- * - fetch_page (Jina) remains available — it works without a key at lower rate limits.
- *
- * v3 improvements over v2:
- * - search_and_read: New tool — Brave LLM Context API (search + read in one call)
- * - Structured error taxonomy: auth_error, rate_limited, network_error, etc.
- * - Spellcheck surfacing: query corrections from Brave shown to agent
- * - Latency tracking: API call timing in details for observability
- * - Rate limit info: remaining quota surfaced when available
- * - more_results_available: pagination hints from Brave
- * - Adaptive snippet budget: snippet count adapts to result count
- * - fetch_page offset: continuation reading for long pages
- * - fetch_page selector: CSS selector targeting via Jina X-Target-Selector
- * - fetch_page diagnostics: Jina failure reasons surfaced in details
- * - Content-type awareness: JSON passthrough, PDF detection
- * - Cache timer cleanup: purge timers use unref() to not block process exit
- *
- * Environment variables:
- *   BRAVE_API_KEY  — Optional with Anthropic models (built-in search available).
- *                    Required for non-Anthropic providers. Get one at brave.com/search/api
- *   JINA_API_KEY   — Optional. Higher rate limits for page extraction.
+ * Native Anthropic hooks stay eager. Heavy tool registration is deferred in
+ * interactive mode so startup is not blocked on the full search tool stack.
  */
 
-import type { ExtensionAPI } from "@gsd/pi-coding-agent";
-import { registerSearchTool } from "./tool-search.js";
-import { registerFetchPageTool } from "./tool-fetch-page.js";
-import { registerLLMContextTool } from "./tool-llm-context.js";
+import { importExtensionModule, type ExtensionAPI } from "@gsd/pi-coding-agent";
 import { registerSearchProviderCommand } from "./command-search-provider.js";
 import { registerNativeSearchHooks } from "./native-search.js";
 
-export default function (pi: ExtensionAPI) {
-  registerSearchTool(pi);
-  registerFetchPageTool(pi);
-  registerLLMContextTool(pi);
+let toolsPromise: Promise<void> | null = null;
 
+async function registerSearchTools(pi: ExtensionAPI): Promise<void> {
+  if (!toolsPromise) {
+    toolsPromise = (async () => {
+      const [{ registerSearchTool }, { registerFetchPageTool }, { registerLLMContextTool }] = await Promise.all([
+        importExtensionModule<typeof import("./tool-search.js")>(import.meta.url, "./tool-search.js"),
+        importExtensionModule<typeof import("./tool-fetch-page.js")>(import.meta.url, "./tool-fetch-page.js"),
+        importExtensionModule<typeof import("./tool-llm-context.js")>(import.meta.url, "./tool-llm-context.js"),
+      ]);
+      registerSearchTool(pi);
+      registerFetchPageTool(pi);
+      registerLLMContextTool(pi);
+    })().catch((error) => {
+      toolsPromise = null;
+      throw error;
+    });
+  }
 
-  // Register slash commands
-  registerSearchProviderCommand(pi);
+  return toolsPromise;
+}
 
-  // Register native Anthropic web search hooks
+export default function (pi: ExtensionAPI) {
+  registerSearchProviderCommand(pi);
   registerNativeSearchHooks(pi);
+
+  pi.on("session_start", async (_event, ctx) => {
+    if (ctx.hasUI) {
+      void registerSearchTools(pi).catch((error) => {
+        ctx.ui.notify(`search-the-web failed to load: ${error instanceof Error ? error.message : String(error)}`, "warning");
+      });
+      return;
+    }
+
+    await registerSearchTools(pi);
+  });
 }

package/src/resources/extensions/search-the-web/tavily.ts

@@ -6,7 +6,7 @@
  * All exports are pure functions with no side effects.
  */
 
-import type { SearchResultFormatted } from "./format.ts";
+import type { SearchResultFormatted } from "./format.js";
 
 // =============================================================================
 // Tavily API Types

package/dist/resources/extensions/ask-user-questions.ts

@@ -1,290 +0,0 @@
-/**
- * Request User Input — LLM tool for asking the user questions
- *
- * Thin wrapper around the shared interview-ui. The LLM presents 1-3
- * questions with 2-3 options each. Each question can be single-select (default)
- * or multi-select (allowMultiple: true). A free-form "None of the above" option
- * is added automatically to single-select questions.
- *
- * Based on: https://github.com/openai/codex (codex-rs/core/src/tools/handlers/ask_user_questions.rs)
- */
-
-import type { ExtensionAPI } from "@gsd/pi-coding-agent";
-import { sanitizeError } from "./shared/sanitize.js";
-import { Text } from "@gsd/pi-tui";
-import { Type } from "@sinclair/typebox";
-import {
-	showInterviewRound,
-	type Question,
-	type QuestionOption,
-	type RoundResult,
-} from "./shared/mod.js";
-
-// ─── Types ────────────────────────────────────────────────────────────────────
-
-interface LocalResultDetails {
-	remote?: false;
-	questions: Question[];
-	response: RoundResult | null;
-	cancelled: boolean;
-}
-
-interface RemoteResultDetails {
-	remote: true;
-	channel: string;
-	timed_out: boolean;
-	promptId?: string;
-	threadUrl?: string;
-	status?: string;
-	questions?: Question[];
-	response?: import("./remote-questions/types.js").RemoteAnswer;
-	error?: boolean;
-}
-
-type AskUserQuestionsDetails = LocalResultDetails | RemoteResultDetails;
-
-// ─── Schema ───────────────────────────────────────────────────────────────────
-
-const OptionSchema = Type.Object({
-	label: Type.String({ description: "User-facing label (1-5 words)" }),
-	description: Type.String({ description: "One short sentence explaining impact/tradeoff if selected" }),
-});
-
-const QuestionSchema = Type.Object({
-	id: Type.String({ description: "Stable identifier for mapping answers (snake_case)" }),
-	header: Type.String({ description: "Short header label shown in the UI (12 or fewer chars)" }),
-	question: Type.String({ description: "Single-sentence prompt shown to the user" }),
-	options: Type.Array(OptionSchema, {
-		description:
-			'Provide 2-3 mutually exclusive choices for single-select, or any number for multi-select. Put the recommended option first and suffix its label with "(Recommended)". Do not include an "Other" option for single-select; the client adds a free-form "None of the above" option automatically.',
-	}),
-	allowMultiple: Type.Optional(
-		Type.Boolean({
-			description:
-				"If true, the user can select multiple options using SPACE to toggle and ENTER to confirm. No 'None of the above' option is added. Default: false.",
-		}),
-	),
-});
-
-const AskUserQuestionsParams = Type.Object({
-	questions: Type.Array(QuestionSchema, {
-		description: "Questions to show the user. Prefer 1 and do not exceed 3.",
-	}),
-});
-
-// ─── Helpers ──────────────────────────────────────────────────────────────────
-
-const OTHER_OPTION_LABEL = "None of the above";
-
-function errorResult(
-	message: string,
-	questions: Question[] = [],
-): { content: { type: "text"; text: string }[]; details: AskUserQuestionsDetails } {
-	return {
-		content: [{ type: "text", text: sanitizeError(message) }],
-		details: { questions, response: null, cancelled: true },
-	};
-}
-
-/** Convert the shared RoundResult into the JSON the LLM expects. */
-function formatForLLM(result: RoundResult): string {
-	const answers: Record<string, { answers: string[] }> = {};
-	for (const [id, answer] of Object.entries(result.answers)) {
-		const list: string[] = [];
-		if (Array.isArray(answer.selected)) {
-			list.push(...answer.selected);
-		} else {
-			list.push(answer.selected);
-		}
-		if (answer.notes) {
-			list.push(`user_note: ${answer.notes}`);
-		}
-		answers[id] = { answers: list };
-	}
-	return JSON.stringify({ answers });
-}
-
-// ─── Extension ────────────────────────────────────────────────────────────────
-
-export default function AskUserQuestions(pi: ExtensionAPI) {
-	pi.registerTool({
-		name: "ask_user_questions",
-		label: "Request User Input",
-		description:
-			"Request user input for one to three short questions and wait for the response. Single-select questions have 2-3 mutually exclusive options with a free-form 'None of the above' added automatically. Multi-select questions (allowMultiple: true) let the user toggle multiple options with SPACE and confirm with ENTER.",
-		promptGuidelines: [
-			"Use ask_user_questions when you need the user to choose between concrete alternatives before proceeding.",
-			"Keep questions to 1 when possible; never exceed 3.",
-			"For single-select: each question must have 2-3 options. Put the recommended option first with '(Recommended)' suffix. Do not include an 'Other' or 'None of the above' option - the client adds one automatically.",
-			"For multi-select: set allowMultiple: true. The user can pick any number of options. No 'None of the above' is added.",
-		],
-		parameters: AskUserQuestionsParams,
-
-		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
-			// Validation
-			if (params.questions.length === 0 || params.questions.length > 3) {
-				return errorResult("Error: questions must contain 1-3 items", params.questions);
-			}
-
-			for (const q of params.questions) {
-				if (!q.options || q.options.length === 0) {
-					return errorResult(
-						`Error: ask_user_questions requires non-empty options for every question (question "${q.id}" has none)`,
-						params.questions,
-					);
-				}
-			}
-
-			if (!ctx.hasUI) {
-				const { tryRemoteQuestions } = await import("./remote-questions/manager.js");
-				const remoteResult = await tryRemoteQuestions(params.questions, signal);
-				if (remoteResult) return { ...remoteResult, details: remoteResult.details as unknown };
-				return errorResult("Error: UI not available (non-interactive mode)", params.questions);
-			}
-
-			// Delegate to shared interview UI
-			const result = await showInterviewRound(params.questions, {}, ctx as any);
-
-			// RPC mode fallback: custom() returns undefined, so showInterviewRound
-			// may return undefined. Fall back to sequential ctx.ui.select() calls.
-			if (!result) {
-				const answers: Record<string, { answers: string[] }> = {};
-				for (const q of params.questions) {
-					const options = q.options.map((o) => o.label);
-					if (!q.allowMultiple) {
-						options.push(OTHER_OPTION_LABEL);
-					}
-					const selected = await ctx.ui.select(
-						`${q.header}: ${q.question}`,
-						options,
-						{ signal, ...(q.allowMultiple ? { allowMultiple: true } : {}) },
-					);
-					if (selected === undefined) {
-						return errorResult("ask_user_questions was cancelled", params.questions);
-					}
-					answers[q.id] = {
-						answers: Array.isArray(selected) ? selected : [selected],
-					};
-				}
-				const roundResult: RoundResult = {
-					endInterview: false,
-					answers: Object.fromEntries(
-						Object.entries(answers).map(([id, a]) => [
-							id,
-							{ selected: a.answers.length === 1 ? a.answers[0] : a.answers, notes: "" },
-						]),
-					),
-				};
-				return {
-					content: [{ type: "text" as const, text: JSON.stringify({ answers }) }],
-					details: {
-						questions: params.questions,
-						response: roundResult,
-						cancelled: false,
-					} satisfies LocalResultDetails,
-				};
-			}
-
-			// Check if cancelled (empty answers = user exited)
-			const hasAnswers = Object.keys(result.answers).length > 0;
-			if (!hasAnswers) {
-				return {
-					content: [{ type: "text", text: "ask_user_questions was cancelled before receiving a response" }],
-					details: { questions: params.questions, response: null, cancelled: true } satisfies LocalResultDetails,
-				};
-			}
-
-			return {
-				content: [{ type: "text", text: formatForLLM(result) }],
-				details: { questions: params.questions, response: result, cancelled: false } satisfies LocalResultDetails,
-			};
-		},
-
-		// ─── Rendering ────────────────────────────────────────────────────────
-
-		renderCall(args, theme) {
-			const qs = (args.questions as Question[]) || [];
-			let text = theme.fg("toolTitle", theme.bold("ask_user_questions "));
-			text += theme.fg("muted", `${qs.length} question${qs.length !== 1 ? "s" : ""}`);
-			if (qs.length > 0) {
-				const headers = qs.map((q) => q.header).join(", ");
-				text += theme.fg("dim", ` (${headers})`);
-			}
-			for (const q of qs) {
-				const multiSel = !!q.allowMultiple;
-				text += `\n  ${theme.fg("text", q.question)}`;
-				const optLabels = multiSel
-					? (q.options || []).map((o: QuestionOption) => o.label)
-					: [...(q.options || []).map((o: QuestionOption) => o.label), OTHER_OPTION_LABEL];
-				const prefix = multiSel ? "☐" : "";
-				const numbered = optLabels.map((l, i) => `${prefix}${i + 1}. ${l}`).join(", ");
-				text += `\n  ${theme.fg("dim", numbered)}`;
-			}
-			return new Text(text, 0, 0);
-		},
-
-		renderResult(result, _options, theme) {
-			const details = result.details as AskUserQuestionsDetails | undefined;
-			if (!details) {
-				const text = result.content[0];
-				return new Text(text?.type === "text" ? text.text : "", 0, 0);
-			}
-
-			// Remote channel result (discriminated on details.remote === true)
-			if (details.remote) {
-				if (details.timed_out) {
-					return new Text(
-						`${theme.fg("warning", `${details.channel} — timed out`)}${details.threadUrl ? theme.fg("dim", ` ${details.threadUrl}`) : ""}`,
-						0,
-						0,
-					);
-				}
-
-				const questions = (details.questions ?? []) as Question[];
-				const lines: string[] = [];
-				lines.push(theme.fg("dim", details.channel));
-				if (details.response) {
-					for (const q of questions) {
-						const answer = details.response.answers[q.id];
-						if (!answer) {
-							lines.push(`${theme.fg("accent", q.header)}: ${theme.fg("dim", "(no answer)")}`);
-							continue;
-						}
-						const answerText = answer.answers.length > 0 ? answer.answers.join(", ") : "(custom)";
-						let line = `${theme.fg("success", "✓ ")}${theme.fg("accent", q.header)}: ${answerText}`;
-						if (answer.user_note) {
-							line += ` ${theme.fg("muted", `[note: ${answer.user_note}]`)}`;
-						}
-						lines.push(line);
-					}
-				}
-				return new Text(lines.join("\n"), 0, 0);
-			}
-
-			if (details.cancelled || !details.response) {
-				return new Text(theme.fg("warning", "Cancelled"), 0, 0);
-			}
-
-			const lines: string[] = [];
-			for (const q of details.questions) {
-				const answer = (details.response as RoundResult).answers[q.id];
-				if (!answer) {
-					lines.push(`${theme.fg("accent", q.header)}: ${theme.fg("dim", "(no answer)")}`);
-					continue;
-				}
-				const selected = answer.selected;
-				const notes = answer.notes;
-				const multiSel = !!q.allowMultiple;
-				const answerText = multiSel && Array.isArray(selected)
-					? selected.join(", ")
-					: (Array.isArray(selected) ? selected[0] : selected) ?? "(no answer)";
-				let line = `${theme.fg("success", "✓ ")}${theme.fg("accent", q.header)}: ${answerText}`;
-				if (notes) {
-					line += ` ${theme.fg("muted", `[note: ${notes}]`)}`;
-				}
-				lines.push(line);
-			}
-			return new Text(lines.join("\n"), 0, 0);
-		},
-	});
-}

package/dist/resources/extensions/async-jobs/async-bash-tool.ts

@@ -1,212 +0,0 @@
-/**
- * async_bash tool — run a bash command in the background.
- *
- * Registers the command with the AsyncJobManager and returns a job ID
- * immediately. The LLM can continue working and check results later
- * with await_job.
- */
-
-import type { ToolDefinition } from "@gsd/pi-coding-agent";
-import {
-	getShellConfig,
-	sanitizeCommand,
-	DEFAULT_MAX_BYTES,
-	DEFAULT_MAX_LINES,
-} from "@gsd/pi-coding-agent";
-import { Type } from "@sinclair/typebox";
-import { spawn } from "node:child_process";
-import { createWriteStream } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { randomBytes } from "node:crypto";
-import type { AsyncJobManager } from "./job-manager.js";
-
-const schema = Type.Object({
-	command: Type.String({ description: "Bash command to execute in the background" }),
-	timeout: Type.Optional(
-		Type.Number({ description: "Timeout in seconds (optional)" }),
-	),
-	label: Type.Optional(
-		Type.String({ description: "Short label for the job (shown in /jobs). Defaults to a truncated version of the command." }),
-	),
-});
-
-function getTempFilePath(): string {
-	const id = randomBytes(8).toString("hex");
-	return join(tmpdir(), `pi-async-bash-${id}.log`);
-}
-
-/**
- * Kill a process and its children. Uses process group kill on Unix.
- */
-function killTree(pid: number): void {
-	try {
-		// Kill the process group (negative PID)
-		process.kill(-pid, "SIGTERM");
-	} catch {
-		try {
-			process.kill(pid, "SIGTERM");
-		} catch {
-			// Already exited
-		}
-	}
-}
-
-export function createAsyncBashTool(
-	getManager: () => AsyncJobManager,
-	getCwd: () => string,
-): ToolDefinition<typeof schema> {
-	return {
-		name: "async_bash",
-		label: "Background Bash",
-		description:
-			`Run a bash command in the background. Returns a job ID immediately so you can continue working. ` +
-			`Use await_job to get results or cancel_job to stop. Ideal for long-running builds, tests, or installs. ` +
-			`Output is truncated to the last ${DEFAULT_MAX_LINES} lines or ${DEFAULT_MAX_BYTES / 1024}KB.`,
-		promptSnippet: "Run a bash command in the background, returning a job ID immediately.",
-		promptGuidelines: [
-			"Use async_bash for commands that take more than a few seconds (builds, tests, installs, large git operations).",
-			"After starting async jobs, continue with other work and use await_job when you need the results.",
-			"Use cancel_job to stop a running background job.",
-			"Check /jobs to see all running and recent background jobs.",
-		],
-		parameters: schema,
-		async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
-			const manager = getManager();
-			const cwd = getCwd();
-			const { command, timeout, label } = params;
-			const shortCmd = label ?? (command.length > 60 ? command.slice(0, 57) + "..." : command);
-
-			const jobId = manager.register("bash", shortCmd, (signal) => {
-				return executeBashInBackground(command, cwd, signal, timeout);
-			});
-
-			return {
-				content: [{
-					type: "text",
-					text: [
-						`Background job started: **${jobId}**`,
-						`Command: \`${shortCmd}\``,
-						"",
-						"Use `await_job` to get results when ready, or `cancel_job` to stop.",
-					].join("\n"),
-				}],
-				details: undefined,
-			};
-		},
-	};
-}
-
-/**
- * Execute a bash command, collecting output. Returns the text result.
- */
-function executeBashInBackground(
-	command: string,
-	cwd: string,
-	signal: AbortSignal,
-	timeout?: number,
-): Promise<string> {
-	return new Promise<string>((resolve, reject) => {
-		const { shell, args } = getShellConfig();
-		const resolvedCommand = sanitizeCommand(command);
-
-		const child = spawn(shell, [...args, resolvedCommand], {
-			cwd,
-			detached: true,
-			env: { ...process.env },
-			stdio: ["ignore", "pipe", "pipe"],
-		});
-
-		let timedOut = false;
-		let timeoutHandle: ReturnType<typeof setTimeout> | undefined;
-
-		if (timeout !== undefined && timeout > 0) {
-			timeoutHandle = setTimeout(() => {
-				timedOut = true;
-				if (child.pid) killTree(child.pid);
-			}, timeout * 1000);
-		}
-
-		const chunks: Buffer[] = [];
-		let totalBytes = 0;
-		let spillFilePath: string | undefined;
-		let spillStream: ReturnType<typeof createWriteStream> | undefined;
-		const MAX_BUFFER = DEFAULT_MAX_BYTES * 2;
-
-		const onData = (data: Buffer) => {
-			totalBytes += data.length;
-
-			if (totalBytes > DEFAULT_MAX_BYTES && !spillFilePath) {
-				spillFilePath = getTempFilePath();
-				spillStream = createWriteStream(spillFilePath);
-				for (const chunk of chunks) spillStream.write(chunk);
-			}
-			if (spillStream) spillStream.write(data);
-
-			chunks.push(data);
-			let chunksBytes = chunks.reduce((s, c) => s + c.length, 0);
-			while (chunksBytes > MAX_BUFFER && chunks.length > 1) {
-				const removed = chunks.shift()!;
-				chunksBytes -= removed.length;
-			}
-		};
-
-		if (child.stdout) child.stdout.on("data", onData);
-		if (child.stderr) child.stderr.on("data", onData);
-
-		const onAbort = () => {
-			if (child.pid) killTree(child.pid);
-		};
-
-		if (signal.aborted) {
-			onAbort();
-		} else {
-			signal.addEventListener("abort", onAbort, { once: true });
-		}
-
-		child.on("error", (err) => {
-			if (timeoutHandle) clearTimeout(timeoutHandle);
-			signal.removeEventListener("abort", onAbort);
-			reject(err);
-		});
-
-		child.on("close", (code) => {
-			if (timeoutHandle) clearTimeout(timeoutHandle);
-			signal.removeEventListener("abort", onAbort);
-			if (spillStream) spillStream.end();
-
-			if (signal.aborted) {
-				const output = Buffer.concat(chunks).toString("utf-8");
-				resolve(output ? `${output}\n\nCommand aborted` : "Command aborted");
-				return;
-			}
-
-			if (timedOut) {
-				const output = Buffer.concat(chunks).toString("utf-8");
-				resolve(output ? `${output}\n\nCommand timed out after ${timeout} seconds` : `Command timed out after ${timeout} seconds`);
-				return;
-			}
-
-			const fullOutput = Buffer.concat(chunks).toString("utf-8");
-
-			const lines = fullOutput.split("\n");
-			let text: string;
-			if (lines.length > DEFAULT_MAX_LINES) {
-				text = lines.slice(-DEFAULT_MAX_LINES).join("\n");
-				if (spillFilePath) {
-					text += `\n\n[Showing last ${DEFAULT_MAX_LINES} of ${lines.length} lines. Full output: ${spillFilePath}]`;
-				} else {
-					text += `\n\n[Showing last ${DEFAULT_MAX_LINES} of ${lines.length} lines]`;
-				}
-			} else {
-				text = fullOutput || "(no output)";
-			}
-
-			if (code !== 0 && code !== null) {
-				text += `\n\nCommand exited with code ${code}`;
-			}
-
-			resolve(text);
-		});
-	});
-}