@thurstonsand/pi-librarian 0.1.1 → 0.2.1

package/extensions/librarian/grep-app.ts

@@ -2,7 +2,10 @@ import { Type } from "typebox";
 import { safeParseTypeBoxValue } from "../shared/typebox.ts";
 
 const GREP_MCP_URL = "https://mcp.grep.app";
-const GREP_SEARCH_TIMEOUT_MS = 30_000;
+// Escalating per-attempt budgets: the upstream gateway kills stalled requests at ~15s, so
+// early attempts abort fast (p90 success is ~500ms) instead of waiting out the full timeout.
+const GREP_ATTEMPT_TIMEOUTS_MS = [3_000, 5_000, 7_000];
+const GREP_RETRY_DELAY_MS = 300;
 
 export class GrepError extends Error {
   constructor(message: string) {
@@ -159,7 +162,12 @@ export function parseGrepMcpEvents(body: string): GrepCodeSearchResult {
       continue;
     }
     if (result.isError) {
-      throw new GrepError("Grep MCP returned an error result.");
+      const message = (result.content ?? [])
+        .map((rawContent) => safeParseTypeBoxValue(MCP_TEXT_CONTENT_SCHEMA, rawContent)?.text)
+        .filter((text): text is string => text !== undefined)
+        .join("\n")
+        .trim();
+      throw new GrepError(message || "Grep MCP returned an error result.");
     }
 
     for (const rawContent of result.content ?? []) {
@@ -203,11 +211,45 @@ function buildGrepArguments(params: GrepCodeSearchParams): Record<string, unknow
   return args;
 }
 
-export async function searchCodeGrep(
+function extractHtmlTitle(body: string): string | undefined {
+  const match = /<title[^>]*>(.*?)<\/title>/is.exec(body);
+  return match?.[1]?.replace(/\s+/g, " ").trim();
+}
+
+function formatHttpError(status: number, body: string): string {
+  return `Grep MCP returned ${status}: ${extractHtmlTitle(body) ?? body.slice(0, 200)}`;
+}
+
+function formatTransientError(error: unknown): string {
+  const cause =
+    error instanceof GrepTransientHttpError ? `returned ${error.status}` : "request failed";
+  return `Grep MCP ${cause} after retry (transient backend error). Retry, or simplify the query.`;
+}
+
+function delay(milliseconds: number, signal: AbortSignal | undefined): Promise<void> {
+  if (signal?.aborted) {
+    return Promise.reject(signal.reason);
+  }
+
+  return new Promise((resolve, reject) => {
+    const timeout = setTimeout(resolve, milliseconds);
+    signal?.addEventListener(
+      "abort",
+      () => {
+        clearTimeout(timeout);
+        reject(signal.reason);
+      },
+      { once: true },
+    );
+  });
+}
+
+async function searchCodeGrepAttempt(
   params: GrepCodeSearchParams,
   signal: AbortSignal | undefined,
+  timeoutMs: number,
 ): Promise<GrepCodeSearchResult> {
-  const timeoutSignal = AbortSignal.timeout(GREP_SEARCH_TIMEOUT_MS);
+  const timeoutSignal = AbortSignal.timeout(timeoutMs);
   const requestSignal = signal ? AbortSignal.any([signal, timeoutSignal]) : timeoutSignal;
   const response = await fetch(GREP_MCP_URL, {
     method: "POST",
@@ -230,8 +272,49 @@ export async function searchCodeGrep(
 
   const body = await response.text();
   if (!response.ok) {
-    throw new GrepError(`Grep MCP returned ${response.status}: ${body.slice(0, 200)}`);
+    if (response.status >= 500) {
+      throw new GrepTransientHttpError(response.status, body);
+    }
+    throw new GrepError(formatHttpError(response.status, body));
   }
 
   return parseGrepMcpEvents(body);
 }
+
+// Do not extend GrepError: GrepError is the deterministic no-retry signal.
+class GrepTransientHttpError extends Error {
+  readonly status: number;
+
+  constructor(status: number, body: string) {
+    super(formatHttpError(status, body));
+    this.name = "GrepTransientHttpError";
+    this.status = status;
+  }
+}
+
+export async function searchCodeGrep(
+  params: GrepCodeSearchParams,
+  signal: AbortSignal | undefined,
+): Promise<GrepCodeSearchResult> {
+  if (signal?.aborted) {
+    throw signal.reason;
+  }
+
+  let transientError: unknown;
+  for (const [attempt, timeoutMs] of GREP_ATTEMPT_TIMEOUTS_MS.entries()) {
+    if (attempt > 0) {
+      await delay(GREP_RETRY_DELAY_MS, signal);
+    }
+
+    try {
+      return await searchCodeGrepAttempt(params, signal, timeoutMs);
+    } catch (error) {
+      if (error instanceof GrepError || signal?.aborted) {
+        throw error;
+      }
+      transientError = error;
+    }
+  }
+
+  throw new GrepError(formatTransientError(transientError));
+}

package/extensions/librarian/prompt.ts

@@ -21,7 +21,7 @@ Clones live under ${cacheDir}/repos/<owner>/<repo>. They are read-only research
 
 ## Citations
 
-- Only cite files you actually read in this run.
+- Only cite files you actually read within context.
 - Cite as repo + file path + line range when you have one.
 - If evidence is partial, say what is confirmed and what remains uncertain.
 - If access fails (404/403, private repo), report that constraint plainly.

package/extensions/librarian/resource-loader.ts

@@ -0,0 +1,40 @@
+import {
+  DefaultResourceLoader,
+  getAgentDir,
+  type LoadExtensionsResult,
+} from "@earendil-works/pi-coding-agent";
+
+export function stripExtensionHooks(result: LoadExtensionsResult): LoadExtensionsResult {
+  return {
+    ...result,
+    extensions: result.extensions.map((extension) => ({
+      ...extension,
+      handlers: new Map(),
+    })),
+  };
+}
+
+export interface LibrarianResourceLoaderOptions {
+  cacheDir: string;
+  extensionPaths: string[];
+  systemPromptOverride: (base: string | undefined) => string | undefined;
+}
+
+export function createLibrarianResourceLoader(
+  options: LibrarianResourceLoaderOptions,
+): DefaultResourceLoader {
+  return new DefaultResourceLoader({
+    cwd: options.cacheDir,
+    agentDir: getAgentDir(),
+    noExtensions: true,
+    ...(options.extensionPaths.length > 0
+      ? { additionalExtensionPaths: options.extensionPaths }
+      : {}),
+    noSkills: true,
+    noPromptTemplates: true,
+    noThemes: true,
+    extensionsOverride: stripExtensionHooks,
+    skillsOverride: () => ({ skills: [], diagnostics: [] }),
+    systemPromptOverride: options.systemPromptOverride,
+  });
+}

package/extensions/librarian/run.ts

@@ -1,22 +1,21 @@
 import fs from "node:fs/promises";
+import path from "node:path";
 import type { AgentToolResult, ThinkingLevel } from "@earendil-works/pi-agent-core";
 import type { Api, Model } from "@earendil-works/pi-ai";
 import type { AgentSession, AgentSessionEvent } from "@earendil-works/pi-coding-agent";
-import {
-  createAgentSession,
-  DefaultResourceLoader,
-  getAgentDir,
-  SessionManager,
-} from "@earendil-works/pi-coding-agent";
+import { createAgentSession, SessionManager } from "@earendil-works/pi-coding-agent";
+import { type ExtraToolsResolution, LIBRARIAN_BASELINE_TOOL_NAMES } from "./extra-tools.ts";
 import type { GitHubClientProvider } from "./github.ts";
 import {
   buildLibrarianSystemPrompt,
   buildLibrarianUserPrompt,
   buildProvideResultsReminder,
 } from "./prompt.ts";
+import { createLibrarianResourceLoader } from "./resource-loader.ts";
 import { renderFindingsMarkdown } from "./results.ts";
 import type { LibrarianSettings } from "./settings.ts";
 import { createCheckoutRepoTool } from "./tools/checkout-repo.ts";
+import { LIBRARIAN_RUN_TOOL_NAMES } from "./tools/names.ts";
 import type { Findings } from "./tools/provide-results.ts";
 import { createProvideResultsTool } from "./tools/provide-results.ts";
 import { createReadGitHubFileTool } from "./tools/read-github-file.ts";
@@ -26,9 +25,12 @@ import { createSearchReposTool } from "./tools/search-repos.ts";
 import { asRepoToolDetails, summarizeToolResult } from "./trace.ts";
 
 const MAX_PROVIDE_RESULTS_REMINDERS = 3;
-const HARDCODED_EXCLUDED_TOOLS = ["write", "edit"];
+const DEFAULT_EXCLUDED_TOOLS = ["write", "edit"];
+
+class LibrarianRunError extends Error {}
 
 export type LibrarianRunStatus = "running" | "done" | "error" | "aborted";
+type FailedLibrarianRunStatus = "error" | "aborted";
 
 export interface TraceCall {
   id: string;
@@ -49,6 +51,8 @@ export interface LibrarianRunDetails {
   findings?: Findings;
   checkouts: Record<string, string>;
   error?: string;
+  runId?: string;
+  debugSessionPath?: string;
   startedAt: number;
   endedAt?: number;
 }
@@ -57,14 +61,30 @@ export interface LibrarianRunOptions {
   query: string;
   repos: string[];
   owners: string[];
+  continueFrom: string | undefined;
   model: Model<Api>;
   thinkingLevel: ThinkingLevel;
   settings: LibrarianSettings;
+  extraTools: ExtraToolsResolution;
   githubClient: GitHubClientProvider;
   signal: AbortSignal | undefined;
   onUpdate: ((details: LibrarianRunDetails) => void) | undefined;
 }
 
+async function openContinuedSession(
+  runId: string,
+  sessionsDir: string,
+  cacheDir: string,
+  fail: (status: FailedLibrarianRunStatus, content: string) => never,
+): Promise<SessionManager> {
+  const sessions = await SessionManager.listAll(sessionsDir);
+  const sessionFile = sessions.find((candidate) => candidate.id === runId)?.path;
+  if (!sessionFile) {
+    fail("error", `Librarian run not found: ${runId}`);
+  }
+  return SessionManager.open(sessionFile, sessionsDir, cacheDir);
+}
+
 export async function runLibrarian(
   options: LibrarianRunOptions,
 ): Promise<AgentToolResult<LibrarianRunDetails>> {
@@ -88,26 +108,45 @@ export async function runLibrarian(
     options.onUpdate?.({ ...details, trace: [...details.trace] });
   };
 
-  const finish = (
-    status: LibrarianRunStatus,
-    content: string,
-    isError: boolean,
-  ): AgentToolResult<LibrarianRunDetails> => {
+  const finalizeDetails = (status: LibrarianRunStatus, content: string): string => {
+    const suffixes = [
+      ...(details.runId ? [`run: ${details.runId}`] : []),
+      ...(details.debugSessionPath ? [`debug_session: ${details.debugSessionPath}`] : []),
+    ];
+    const resultContent = suffixes.length > 0 ? `${content}\n\n${suffixes.join("\n")}` : content;
     details.status = status;
     details.endedAt = Date.now();
-    if (isError) {
+    if (status !== "done") {
       details.error = content.split("\n")[0] ?? content;
     }
     emit(true);
-    return {
-      content: [{ type: "text", text: content }],
-      details: { ...details, trace: [...details.trace] },
-      ...(isError ? { isError: true } : {}),
-    };
+    return resultContent;
+  };
+
+  const finish = (
+    status: LibrarianRunStatus,
+    content: string,
+  ): AgentToolResult<LibrarianRunDetails> => ({
+    content: [{ type: "text", text: finalizeDetails(status, content) }],
+    details: { ...details, trace: [...details.trace] },
+  });
+
+  const fail = (status: FailedLibrarianRunStatus, content: string): never => {
+    throw new LibrarianRunError(finalizeDetails(status, content));
   };
 
   await fs.mkdir(options.settings.cacheDir, { recursive: true });
 
+  const sessionsDir = path.join(options.settings.cacheDir, "sessions");
+  const sessionManager = options.continueFrom
+    ? await openContinuedSession(options.continueFrom, sessionsDir, options.settings.cacheDir, fail)
+    : SessionManager.create(options.settings.cacheDir, sessionsDir);
+  details.runId = sessionManager.getSessionId();
+  const debugSessionPath = sessionManager.getSessionFile();
+  if (options.settings.debug.persistRuns && debugSessionPath) {
+    details.debugSessionPath = debugSessionPath;
+  }
+
   let findings: Findings | undefined;
   const repoTools = [
     createSearchReposTool(options.githubClient),
@@ -120,21 +159,27 @@ export async function runLibrarian(
     }),
   ];
 
-  const resourceLoader = new DefaultResourceLoader({
-    cwd: options.settings.cacheDir,
-    agentDir: getAgentDir(),
-    noExtensions: true,
-    ...(options.settings.extensions.length > 0
-      ? { additionalExtensionPaths: options.settings.extensions }
-      : {}),
-    noSkills: true,
-    noPromptTemplates: true,
-    noThemes: true,
+  const resourceLoader = createLibrarianResourceLoader({
+    cacheDir: options.settings.cacheDir,
+    extensionPaths: options.extraTools.extensionPaths,
     systemPromptOverride: () => buildLibrarianSystemPrompt(options.settings.cacheDir),
-    skillsOverride: () => ({ skills: [], diagnostics: [] }),
   });
   await resourceLoader.reload();
 
+  const extensionLoadErrors = resourceLoader.getExtensions().errors;
+  for (const [index, error] of extensionLoadErrors.entries()) {
+    const now = Date.now();
+    details.trace.push({
+      id: `extension-load-${index}`,
+      name: "load_extension",
+      args: { path: error.path },
+      startedAt: now,
+      endedAt: now,
+      isError: true,
+      resultSummary: error.error,
+    });
+  }
+
   emit(true);
 
   let session: AgentSession | undefined;
@@ -145,20 +190,21 @@ export async function runLibrarian(
     const created = await createAgentSession({
       cwd: options.settings.cacheDir,
       resourceLoader,
-      sessionManager: SessionManager.inMemory(options.settings.cacheDir),
+      sessionManager,
       model: options.model,
       thinkingLevel: options.thinkingLevel,
       customTools: repoTools,
-      excludeTools: [...HARDCODED_EXCLUDED_TOOLS, ...options.settings.disabledTools],
+      excludeTools: DEFAULT_EXCLUDED_TOOLS.filter(
+        (toolName) => !options.extraTools.toolNames.includes(toolName),
+      ),
     });
     session = created.session;
 
-    const excluded = new Set([...HARDCODED_EXCLUDED_TOOLS, ...options.settings.disabledTools]);
-    const allToolNames = session
-      .getAllTools()
-      .map((tool) => tool.name)
-      .filter((name) => !excluded.has(name));
-    session.setActiveToolsByName(allToolNames);
+    session.setActiveToolsByName([
+      ...LIBRARIAN_BASELINE_TOOL_NAMES,
+      ...LIBRARIAN_RUN_TOOL_NAMES,
+      ...options.extraTools.toolNames,
+    ]);
 
     unsubscribe = session.subscribe((event: AgentSessionEvent) => {
       switch (event.type) {
@@ -198,7 +244,7 @@ export async function runLibrarian(
     });
 
     if (options.signal?.aborted) {
-      return finish("aborted", "Librarian run aborted before it started.", true);
+      fail("aborted", "Librarian run aborted before it started.");
     }
 
     const activeSession = session;
@@ -214,30 +260,34 @@ export async function runLibrarian(
     let reminders = 0;
     while (!findings && !options.signal?.aborted && reminders < MAX_PROVIDE_RESULTS_REMINDERS) {
       reminders += 1;
-      await session.prompt(buildProvideResultsReminder(), { expandPromptTemplates: false });
+      await session.prompt(buildProvideResultsReminder(), {
+        expandPromptTemplates: false,
+      });
     }
 
     if (options.signal?.aborted) {
-      return finish("aborted", "Librarian run aborted.", true);
+      fail("aborted", "Librarian run aborted.");
     }
 
     if (findings) {
       details.findings = findings;
-      return finish("done", renderFindingsMarkdown(findings, details.checkouts), false);
+      return finish("done", renderFindingsMarkdown(findings, details.checkouts));
     }
 
     const lastText = session.getLastAssistantText() ?? "";
-    return finish(
+    fail(
       "error",
       `Librarian did not report structured findings after ${MAX_PROVIDE_RESULTS_REMINDERS} reminders.${lastText ? `\n\nRaw final message:\n${lastText}` : ""}`,
-      true,
     );
   } catch (error) {
+    if (error instanceof LibrarianRunError) {
+      throw error;
+    }
     if (options.signal?.aborted) {
-      return finish("aborted", "Librarian run aborted.", true);
+      fail("aborted", "Librarian run aborted.");
     }
     const message = error instanceof Error ? error.message : String(error);
-    return finish("error", `Librarian run failed: ${message}`, true);
+    fail("error", `Librarian run failed: ${message}`);
   } finally {
     if (onAbort) {
       options.signal?.removeEventListener("abort", onAbort);
@@ -245,4 +295,6 @@ export async function runLibrarian(
     unsubscribe?.();
     session?.dispose();
   }
+
+  throw new Error("Unreachable librarian run state.");
 }

package/extensions/librarian/settings.ts

@@ -18,8 +18,13 @@ const LIBRARIAN_FILE_SETTINGS_SCHEMA = Type.Object({
   model: Type.Optional(Type.String()),
   thinkingLevel: Type.Optional(THINKING_LEVEL_SCHEMA),
   extensions: Type.Optional(Type.Array(Type.String())),
-  disabledTools: Type.Optional(Type.Array(Type.String())),
+  tools: Type.Optional(Type.Array(Type.String())),
   cacheDir: Type.Optional(Type.String()),
+  debug: Type.Optional(
+    Type.Object({
+      persistRuns: Type.Optional(Type.Boolean()),
+    }),
+  ),
 });
 
 const ROOT_SETTINGS_SCHEMA = Type.Object({
@@ -43,8 +48,11 @@ export interface LibrarianSettings {
   model: ModelReference | undefined;
   thinkingLevel: ThinkingLevel | undefined;
   extensions: string[];
-  disabledTools: string[];
+  tools: string[];
   cacheDir: string;
+  debug: {
+    persistRuns: boolean;
+  };
 }
 
 export function getDefaultCacheDir(): string {
@@ -102,13 +110,24 @@ function normalizeExtensionPaths(values: string[] | undefined): string[] {
     .map(expandHome);
 }
 
+function normalizeToolNames(values: string[] | undefined): string[] {
+  if (!values) {
+    return [];
+  }
+
+  return [...new Set(values.map((value) => value.trim()).filter((value) => value.length > 0))];
+}
+
 export function resolveLibrarianSettings(fileSettings: LibrarianFileSettings): LibrarianSettings {
   return {
     model: parseModelReference(fileSettings.model),
     thinkingLevel: fileSettings.thinkingLevel,
     extensions: normalizeExtensionPaths(fileSettings.extensions),
-    disabledTools: fileSettings.disabledTools ?? [],
+    tools: normalizeToolNames(fileSettings.tools),
     cacheDir: normalizeCacheDir(fileSettings.cacheDir),
+    debug: {
+      persistRuns: fileSettings.debug?.persistRuns ?? false,
+    },
   };
 }
 

package/extensions/librarian/tools/checkout-repo.ts

@@ -64,24 +64,9 @@ export function createCheckoutRepoTool(cacheDir: string) {
             : error instanceof Error
               ? error.message
               : String(error);
-        return {
-          content: [
-            {
-              type: "text",
-              text: `${message}\nIf the repo name is uncertain, resolve it with search_repos first.`,
-            },
-          ],
-          details: {
-            kind: "checkout_repo",
-            repo: params.repo,
-            path: "",
-            headSha: "",
-            ref: params.ref ?? "",
-            fileCount: 0,
-            reusedClone: false,
-          },
-          isError: true,
-        };
+        throw new Error(
+          `${message}\nIf the repo name is uncertain, resolve it with search_repos first.`,
+        );
       }
     },
   });

package/extensions/librarian/tools/provide-results.ts

@@ -3,10 +3,16 @@ import { type Static, Type } from "typebox";
 import { LIBRARIAN_TOOL_NAMES } from "./names.ts";
 
 export const LocationSchema = Type.Object({
-  repo: Type.String({ description: "Repository as owner/repo or a repository URL." }),
-  file: Type.String({ description: "File path within the repository." }),
+  repo: Type.String({
+    description: "Repository as owner/repo or a repository URL.",
+  }),
+  file: Type.String({
+    description: "Validated file path within the repository.",
+  }),
   lines: Type.Optional(
-    Type.String({ description: 'Line range like "80-140" or a single line like "42".' }),
+    Type.String({
+      description: 'Line range like "80-140" or a single line like "42".',
+    }),
   ),
   note: Type.String({ description: "Relevance of the file." }),
 });
@@ -16,7 +22,8 @@ export const FindingsSchema = Type.Object({
     description: "1-3 sentence direct answer to the query. No preamble.",
   }),
   locations: Type.Array(LocationSchema, {
-    description: "Evidence locations.",
+    description:
+      "Evidence source-file locations. Include only repository files you validated by reading.",
   }),
   description: Type.Optional(
     Type.String({
@@ -50,9 +57,15 @@ export function createProvideResultsTool(onFindings: (findings: Findings) => voi
       onFindings(params);
       return {
         content: [
-          { type: "text", text: "Findings recorded. You are done; do not call more tools." },
+          {
+            type: "text",
+            text: "Findings recorded. You are done; do not call more tools.",
+          },
         ],
-        details: { kind: "provide_results", locationCount: params.locations.length },
+        details: {
+          kind: "provide_results",
+          locationCount: params.locations.length,
+        },
         terminate: true,
       };
     },

package/extensions/librarian/tools/read-github-file.ts

@@ -22,8 +22,10 @@ const ReadGitHubFileParams = Type.Object({
     Type.String({ description: "Branch, tag, or commit sha. Default: the default branch." }),
   ),
   range: Type.Optional(
-    Type.Tuple([Type.Number({ minimum: 1 }), Type.Number({ minimum: 1 })], {
+    Type.Array(Type.Number({ minimum: 1 }), {
       description: "[startLine, endLine] (1-based, inclusive) for large files.",
+      minItems: 2,
+      maxItems: 2,
     }),
   ),
 });
@@ -42,6 +44,11 @@ export function createReadGitHubFileTool(githubClient: GitHubClientProvider) {
     parameters: ReadGitHubFileParams,
 
     async execute(_toolCallId, params) {
+      const range = params.range ? (params.range as [number, number]) : undefined;
+      if (range && range[1] < range[0]) {
+        throw new Error("range end must be greater than or equal to range start.");
+      }
+
       try {
         const github = await githubClient();
         const contents = await github.readContents({
@@ -72,9 +79,9 @@ export function createReadGitHubFileTool(githubClient: GitHubClientProvider) {
         let end = allLines.length;
         let clipNote = "";
 
-        if (params.range) {
-          start = Math.min(params.range[0], allLines.length);
-          end = Math.min(params.range[1], allLines.length);
+        if (range) {
+          start = Math.min(range[0], allLines.length);
+          end = Math.min(range[1], allLines.length);
         } else if (allLines.length > MAX_LINES_WITHOUT_RANGE) {
           end = MAX_LINES_WITHOUT_RANGE;
           clipNote = `\n... clipped at line ${MAX_LINES_WITHOUT_RANGE} of ${allLines.length}; pass range to read further.`;
@@ -104,18 +111,7 @@ export function createReadGitHubFileTool(githubClient: GitHubClientProvider) {
             : error instanceof Error
               ? error.message
               : String(error);
-        return {
-          content: [{ type: "text", text: message }],
-          details: {
-            kind: "read_github_file",
-            owner: params.owner,
-            repo: params.repo,
-            path: params.path,
-            lineCount: 0,
-            isDirectory: false,
-          },
-          isError: true,
-        };
+        throw new Error(message);
       }
     },
   });

package/extensions/librarian/tools/search-code.ts

@@ -14,12 +14,11 @@ export interface SearchCodeDetails {
 const SearchCodeParams = Type.Object({
   pattern: Type.String({
     description:
-      "Public code search pattern. Literal by default; set regex: true to treat it as a regular expression.",
+      "Public code search pattern. Use literal code patterns as they appear in files, not keywords: e.g. `useState(` rather than `react hook state`.",
   }),
   regex: Type.Optional(
     Type.Boolean({
-      description:
-        "Treat pattern as a regular expression. Grep supports multi-line regex with (?s).",
+      description: "Treat `pattern` as a regular expression instead of literals.",
     }),
   ),
   repo: Type.Optional(
@@ -62,6 +61,7 @@ export const searchCodeTool = defineTool<typeof SearchCodeParams, SearchCodeDeta
   description: "Cross-repo code search over public source code.",
   promptSnippet: "Search code across repos",
   promptGuidelines: [
+    "When `regex` is true, `pattern` can also use `(?s)` for multi-line patterns.",
     "Results are CANDIDATES to verify via checkout_repo/read_github_file — never cite them directly.",
     "This searches public GitHub code only. Use search_github_code when private repository access matters.",
   ],

package/extensions/librarian/tools/search-repos.ts

@@ -85,16 +85,7 @@ export function createSearchReposTool(githubClient: GitHubClientProvider) {
             : error instanceof Error
               ? error.message
               : String(error);
-        return {
-          content: [{ type: "text", text: message }],
-          details: {
-            kind: "search_repos",
-            query: params.query,
-            resultCount: 0,
-            totalCount: 0,
-          },
-          isError: true,
-        };
+        throw new Error(message);
       }
     },
   });