@thurstonsand/pi-librarian 0.1.0

package/extensions/librarian/settings.ts

@@ -0,0 +1,119 @@
+import os from "node:os";
+import path from "node:path";
+import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
+import { SettingsManager } from "@earendil-works/pi-coding-agent";
+import { type Static, Type } from "typebox";
+import { parseTypeBoxValue } from "../shared/typebox.ts";
+
+const THINKING_LEVEL_SCHEMA = Type.Union([
+  Type.Literal("off"),
+  Type.Literal("minimal"),
+  Type.Literal("low"),
+  Type.Literal("medium"),
+  Type.Literal("high"),
+  Type.Literal("xhigh"),
+]);
+
+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())),
+  cacheDir: Type.Optional(Type.String()),
+});
+
+const ROOT_SETTINGS_SCHEMA = Type.Object({
+  librarian: Type.Optional(LIBRARIAN_FILE_SETTINGS_SCHEMA),
+});
+
+type LibrarianFileSettings = Static<typeof LIBRARIAN_FILE_SETTINGS_SCHEMA>;
+
+export class ModelReference {
+  constructor(
+    readonly provider: string,
+    readonly modelId: string,
+  ) {}
+
+  toString(): string {
+    return `${this.provider}/${this.modelId}`;
+  }
+}
+
+export interface LibrarianSettings {
+  model: ModelReference | undefined;
+  thinkingLevel: ThinkingLevel | undefined;
+  extensions: string[];
+  disabledTools: string[];
+  cacheDir: string;
+}
+
+export function getDefaultCacheDir(): string {
+  return path.join(os.tmpdir(), "pi-librarian");
+}
+
+function expandHome(rawPath: string): string {
+  if (rawPath === "~") {
+    return os.homedir();
+  }
+
+  if (rawPath.startsWith(`~${path.sep}`) || rawPath.startsWith("~/")) {
+    return path.join(os.homedir(), rawPath.slice(2));
+  }
+
+  return rawPath;
+}
+
+function normalizeCacheDir(value: string | undefined): string {
+  const trimmed = value?.trim();
+  if (!trimmed) {
+    return getDefaultCacheDir();
+  }
+
+  const expanded = expandHome(trimmed);
+  if (!path.isAbsolute(expanded)) {
+    throw new Error('librarian.cacheDir must be an absolute path or start with "~/".');
+  }
+
+  return path.normalize(expanded);
+}
+
+function parseModelReference(value: string | undefined): ModelReference | undefined {
+  const trimmed = value?.trim();
+  if (!trimmed) {
+    return undefined;
+  }
+
+  const slashIndex = trimmed.indexOf("/");
+  if (slashIndex <= 0 || slashIndex === trimmed.length - 1) {
+    return undefined;
+  }
+
+  return new ModelReference(trimmed.slice(0, slashIndex), trimmed.slice(slashIndex + 1));
+}
+
+function normalizeExtensionPaths(values: string[] | undefined): string[] {
+  if (!values) {
+    return [];
+  }
+
+  return values
+    .map((value) => value.trim())
+    .filter((value) => value.length > 0)
+    .map(expandHome);
+}
+
+export function resolveLibrarianSettings(fileSettings: LibrarianFileSettings): LibrarianSettings {
+  return {
+    model: parseModelReference(fileSettings.model),
+    thinkingLevel: fileSettings.thinkingLevel,
+    extensions: normalizeExtensionPaths(fileSettings.extensions),
+    disabledTools: fileSettings.disabledTools ?? [],
+    cacheDir: normalizeCacheDir(fileSettings.cacheDir),
+  };
+}
+
+export function loadSettings(): LibrarianSettings {
+  const globalSettings = SettingsManager.create(process.cwd()).getGlobalSettings();
+  const parsed = parseTypeBoxValue(ROOT_SETTINGS_SCHEMA, globalSettings, "Invalid settings");
+  return resolveLibrarianSettings(parsed.librarian ?? {});
+}

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

@@ -0,0 +1,88 @@
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { CheckoutError, checkoutRepo } from "../checkout.ts";
+import { LIBRARIAN_TOOL_NAMES } from "./names.ts";
+
+export interface CheckoutRepoDetails {
+  kind: "checkout_repo";
+  repo: string;
+  path: string;
+  headSha: string;
+  ref: string;
+  fileCount: number;
+  reusedClone: boolean;
+}
+
+const CheckoutRepoParams = Type.Object({
+  repo: Type.String({
+    description: "Repository as owner/repo (for Github) or an HTTPS/SSH repository URL.",
+  }),
+  ref: Type.Optional(
+    Type.String({
+      description: "Branch, tag, or commit sha. Default: the default branch.",
+    }),
+  ),
+});
+
+export function createCheckoutRepoTool(cacheDir: string) {
+  return defineTool<typeof CheckoutRepoParams, CheckoutRepoDetails>({
+    name: LIBRARIAN_TOOL_NAMES.checkoutRepo,
+    label: "Checkout repo",
+    description: "Clone a repo (blob-less partial clone, cached locally).",
+    promptSnippet: "Clone a repo",
+    promptGuidelines: [
+      "Use when you want to deep dive on a specific repo. Follow up using grep/read/find/ls on the returned path, and `git -C <path> log/blame/diff` for history.",
+      "Do not checkout repos directly using `git`. Always use this tool instead.",
+    ],
+    parameters: CheckoutRepoParams,
+
+    async execute(_toolCallId, params, signal) {
+      try {
+        const result = await checkoutRepo(params.repo, params.ref, cacheDir, signal);
+        const text = [
+          `Checked out ${result.repo}@${result.ref} (${result.headSha.slice(0, 12)})`,
+          `Local path: ${result.path}`,
+          `${result.fileCount} files.`,
+        ].join("\n");
+
+        return {
+          content: [{ type: "text", text }],
+          details: {
+            kind: "checkout_repo",
+            repo: result.repo,
+            path: result.path,
+            headSha: result.headSha,
+            ref: result.ref,
+            fileCount: result.fileCount,
+            reusedClone: result.reusedClone,
+          },
+        };
+      } catch (error) {
+        const message =
+          error instanceof CheckoutError
+            ? error.message
+            : 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,
+        };
+      }
+    },
+  });
+}

package/extensions/librarian/tools/names.ts

@@ -0,0 +1,21 @@
+export const LIBRARIAN_TOOL_NAMES = {
+  searchRepos: "search_repos",
+  searchCode: "search_code",
+  searchGitHubCode: "search_github_code",
+  checkoutRepo: "checkout_repo",
+  readGitHubFile: "read_github_file",
+  provideResults: "provide_results",
+} as const;
+
+export const ATTACHABLE_TOOL_NAMES = [
+  LIBRARIAN_TOOL_NAMES.searchRepos,
+  LIBRARIAN_TOOL_NAMES.searchCode,
+  LIBRARIAN_TOOL_NAMES.searchGitHubCode,
+  LIBRARIAN_TOOL_NAMES.checkoutRepo,
+  LIBRARIAN_TOOL_NAMES.readGitHubFile,
+] as const;
+
+export const LIBRARIAN_RUN_TOOL_NAMES = [
+  ...ATTACHABLE_TOOL_NAMES,
+  LIBRARIAN_TOOL_NAMES.provideResults,
+] as const;

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

@@ -0,0 +1,60 @@
+import { defineTool } from "@earendil-works/pi-coding-agent";
+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." }),
+  lines: Type.Optional(
+    Type.String({ description: 'Line range like "80-140" or a single line like "42".' }),
+  ),
+  note: Type.String({ description: "Relevance of the file." }),
+});
+
+export const FindingsSchema = Type.Object({
+  summary: Type.String({
+    description: "1-3 sentence direct answer to the query. No preamble.",
+  }),
+  locations: Type.Array(LocationSchema, {
+    description: "Evidence locations.",
+  }),
+  description: Type.Optional(
+    Type.String({
+      description:
+        "Optional extended findings in markdown (e.g. step-by-step flow tracing, comparisons).",
+    }),
+  ),
+});
+
+export type Findings = Static<typeof FindingsSchema>;
+export type FindingsLocation = Static<typeof LocationSchema>;
+
+export interface ProvideResultsDetails {
+  kind: "provide_results";
+  locationCount: number;
+}
+
+export function createProvideResultsTool(onFindings: (findings: Findings) => void) {
+  return defineTool<typeof FindingsSchema, ProvideResultsDetails>({
+    name: LIBRARIAN_TOOL_NAMES.provideResults,
+    label: "Provide results",
+    description: "Report your findings in structured form.",
+    promptSnippet: "Provide results",
+    promptGuidelines: [
+      "Tool must be called before the turn ends.",
+      "After calling this tool, the turn will end.",
+    ],
+    parameters: FindingsSchema,
+
+    async execute(_toolCallId, params) {
+      onFindings(params);
+      return {
+        content: [
+          { type: "text", text: "Findings recorded. You are done; do not call more tools." },
+        ],
+        details: { kind: "provide_results", locationCount: params.locations.length },
+        terminate: true,
+      };
+    },
+  });
+}

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

@@ -0,0 +1,122 @@
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { GitHubApiError, type GitHubClientProvider } from "../github.ts";
+import { LIBRARIAN_TOOL_NAMES } from "./names.ts";
+
+const MAX_LINES_WITHOUT_RANGE = 1200;
+
+export interface ReadGitHubFileDetails {
+  kind: "read_github_file";
+  owner: string;
+  repo: string;
+  path: string;
+  lineCount: number;
+  isDirectory: boolean;
+}
+
+const ReadGitHubFileParams = Type.Object({
+  owner: Type.String({ description: "Repository owner or organization." }),
+  repo: Type.String({ description: "Repository name." }),
+  path: Type.String({ description: "File or directory path within the repository." }),
+  ref: Type.Optional(
+    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 })], {
+      description: "[startLine, endLine] (1-based, inclusive) for large files.",
+    }),
+  ),
+});
+
+export function createReadGitHubFileTool(githubClient: GitHubClientProvider) {
+  return defineTool<typeof ReadGitHubFileParams, ReadGitHubFileDetails>({
+    name: LIBRARIAN_TOOL_NAMES.readGitHubFile,
+    label: "Read GitHub file",
+    description:
+      "Read a single file (or list a directory) from a GitHub repo via the API, without cloning.",
+    promptSnippet: "Read Github file",
+    promptGuidelines: [
+      "For quick peeks — package.json, a README, one source file.",
+      "For multi-file exploration prefer checkout_repo.",
+    ],
+    parameters: ReadGitHubFileParams,
+
+    async execute(_toolCallId, params) {
+      try {
+        const github = await githubClient();
+        const contents = await github.readContents({
+          repo: { owner: params.owner, repo: params.repo },
+          path: params.path,
+          ref: params.ref,
+        });
+
+        if (contents.kind === "directory") {
+          const listing = contents.entries
+            .map((entry) => `${entry.path}${entry.type === "dir" ? "/" : ""}`)
+            .join("\n");
+          return {
+            content: [{ type: "text", text: listing || "(empty directory)" }],
+            details: {
+              kind: "read_github_file",
+              owner: params.owner,
+              repo: params.repo,
+              path: params.path,
+              lineCount: contents.entries.length,
+              isDirectory: true,
+            },
+          };
+        }
+
+        const allLines = contents.text.split("\n");
+        let start = 1;
+        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);
+        } 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.`;
+        }
+
+        const width = String(end).length;
+        const numbered = allLines
+          .slice(start - 1, end)
+          .map((line, index) => `${String(start + index).padStart(width)}\t${line}`)
+          .join("\n");
+
+        return {
+          content: [{ type: "text", text: `${numbered}${clipNote}` }],
+          details: {
+            kind: "read_github_file",
+            owner: params.owner,
+            repo: params.repo,
+            path: params.path,
+            lineCount: end - start + 1,
+            isDirectory: false,
+          },
+        };
+      } catch (error) {
+        const message =
+          error instanceof GitHubApiError && error.status === 404
+            ? `${params.owner}/${params.repo}:${params.path} not found (check the path and ref; private repos need gh auth).`
+            : 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,
+        };
+      }
+    },
+  });
+}

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

@@ -0,0 +1,99 @@
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { type GrepCodeMatch, searchCodeGrep } from "../grep-app.ts";
+import { LIBRARIAN_TOOL_NAMES } from "./names.ts";
+
+export interface SearchCodeDetails {
+  kind: "search_code";
+  pattern: string;
+  backend: "grep.app";
+  matchCount: number;
+  repoCount: number;
+}
+
+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.",
+  }),
+  regex: Type.Optional(
+    Type.Boolean({
+      description:
+        "Treat pattern as a regular expression. Grep supports multi-line regex with (?s).",
+    }),
+  ),
+  repo: Type.Optional(
+    Type.String({
+      description:
+        "Restrict to a repository or repository prefix, e.g. drizzle-team/drizzle-orm or vercel.",
+    }),
+  ),
+  language: Type.Optional(Type.String({ description: "Restrict to a language, e.g. TypeScript." })),
+  path: Type.Optional(
+    Type.String({
+      description: "Restrict to file paths matching this pattern.",
+    }),
+  ),
+});
+
+function formatGrepMatches(matches: GrepCodeMatch[]): string {
+  return matches
+    .map((match) => {
+      const snippets = match.snippets
+        .slice(0, 2)
+        .map((snippet) => {
+          const lines = snippet.content
+            .split("\n")
+            .slice(0, 8)
+            .map((line, offset) => `    ${snippet.lineNumber + offset}: ${line.trimEnd()}`)
+            .join("\n");
+          return lines;
+        })
+        .join("\n");
+      const url = match.url ? `\n    ${match.url}` : "";
+      return `  ${match.repo}:${match.path}${url}${snippets ? `\n${snippets}` : ""}`;
+    })
+    .join("\n");
+}
+
+export const searchCodeTool = defineTool<typeof SearchCodeParams, SearchCodeDetails>({
+  name: LIBRARIAN_TOOL_NAMES.searchCode,
+  label: "Search code across repos",
+  description: "Cross-repo code search over public source code.",
+  promptSnippet: "Search code across repos",
+  promptGuidelines: [
+    "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.",
+  ],
+  parameters: SearchCodeParams,
+
+  async execute(_toolCallId, params, signal) {
+    const result = await searchCodeGrep(
+      {
+        query: params.pattern,
+        ...(params.regex ? { useRegexp: true } : {}),
+        ...(params.repo ? { repo: params.repo } : {}),
+        ...(params.language ? { language: [params.language] } : {}),
+        ...(params.path ? { path: params.path } : {}),
+      },
+      signal,
+    );
+    const repoCount = new Set(result.matches.map((match) => match.repo)).size;
+    const body =
+      result.matches.length === 0
+        ? "No matches. Note: private repositories need search_github_code or checkout_repo + grep."
+        : formatGrepMatches(result.matches);
+    const header = `${result.matches.length} matches across ${repoCount} repos (grep.app).`;
+
+    return {
+      content: [{ type: "text", text: `${header}\n\n${body}` }],
+      details: {
+        kind: "search_code",
+        pattern: params.pattern,
+        backend: "grep.app",
+        matchCount: result.matches.length,
+        repoCount,
+      },
+    };
+  },
+});

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

@@ -0,0 +1,125 @@
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import type { GitHubClientProvider, GitHubCodeSearchResult, GitHubRepoSlug } from "../github.ts";
+import { LIBRARIAN_TOOL_NAMES } from "./names.ts";
+
+export interface SearchGitHubCodeDetails {
+  kind: "search_github_code";
+  pattern: string;
+  matchCount: number;
+  repoCount: number;
+}
+
+const GitHubRepoScopeParams = Type.Object({
+  owner: Type.String({ description: "Repository owner or organization." }),
+  repo: Type.String({ description: "Repository name." }),
+});
+
+const SearchGitHubCodeParams = Type.Object({
+  pattern: Type.String({
+    description: "GitHub REST code search pattern.",
+  }),
+  repos: Type.Optional(
+    Type.Array(GitHubRepoScopeParams, {
+      description: "Restrict to these repositories.",
+      maxItems: 20,
+    }),
+  ),
+  owners: Type.Optional(
+    Type.Array(Type.String(), {
+      description: "Restrict to these owners/orgs.",
+      maxItems: 20,
+    }),
+  ),
+  language: Type.Optional(Type.String({ description: "Restrict to a language, e.g. typescript." })),
+  path: Type.Optional(
+    Type.String({
+      description: "Restrict to file paths matching this pattern.",
+    }),
+  ),
+  limit: Type.Optional(
+    Type.Number({
+      minimum: 1,
+      maximum: 100,
+      description: "Max results. Default: 30.",
+    }),
+  ),
+});
+
+export function buildGitHubCodeQuery(params: {
+  pattern: string;
+  repos?: GitHubRepoSlug[];
+  owners?: string[];
+  language?: string;
+  path?: string;
+}): string {
+  const parts: string[] = [params.pattern.replace(/^\/|\/$/g, "")];
+
+  for (const repo of params.repos ?? []) {
+    parts.push(`repo:${repo.owner}/${repo.repo}`);
+  }
+  for (const owner of params.owners ?? []) {
+    parts.push(`user:${owner}`);
+  }
+  if (params.language) {
+    parts.push(`language:${params.language}`);
+  }
+  if (params.path) {
+    parts.push(`path:${params.path}`);
+  }
+
+  return parts.join(" ");
+}
+
+function formatGitHubMatches(result: GitHubCodeSearchResult): string {
+  return result.hits
+    .map((hit) => {
+      const fragments = hit.fragments
+        .slice(0, 2)
+        .map((fragment) => `    ${fragment.split("\n").slice(0, 3).join("\n    ")}`)
+        .join("\n");
+      return `  ${hit.repo}:${hit.path}${fragments ? `\n${fragments}` : ""}`;
+    })
+    .join("\n");
+}
+
+export function createSearchGitHubCodeTool(githubClient: GitHubClientProvider) {
+  return defineTool<typeof SearchGitHubCodeParams, SearchGitHubCodeDetails>({
+    name: LIBRARIAN_TOOL_NAMES.searchGitHubCode,
+    label: "Search GitHub code",
+    description:
+      "GitHub REST code search over public code and private repositories your configured GitHub auth can access.",
+    promptSnippet: "Search GitHub code",
+    promptGuidelines: [
+      "Results are CANDIDATES to verify via checkout_repo/read_github_file — never cite them directly.",
+      "GitHub REST code search is literal/tokenized and does not support regex; use search_code for public regex/global code search.",
+    ],
+    parameters: SearchGitHubCodeParams,
+
+    async execute(_toolCallId, params) {
+      const limit = params.limit ?? 30;
+      const github = await githubClient();
+      const result = await github.searchCode({
+        pattern: params.pattern,
+        ...(params.repos ? { repos: params.repos } : {}),
+        ...(params.owners ? { owners: params.owners } : {}),
+        ...(params.language ? { language: params.language } : {}),
+        ...(params.path ? { path: params.path } : {}),
+        limit,
+      });
+      const repoCount = new Set(result.hits.map((hit) => hit.repo)).size;
+      const body = result.hits.length === 0 ? "No matches." : formatGitHubMatches(result);
+      const header = `${result.hits.length} of ${result.totalCount} matches across ${repoCount} repos (github).`;
+
+      return {
+        content: [{ type: "text", text: `${header}\n\n${body}` }],
+        details: {
+          kind: "search_github_code",
+          pattern: params.pattern,
+          matchCount: result.hits.length,
+          repoCount,
+        },
+      };
+    },
+  });
+}