@thurstonsand/pi-librarian 0.1.0

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

@@ -0,0 +1,101 @@
+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";
+
+export interface SearchReposDetails {
+  kind: "search_repos";
+  query: string;
+  resultCount: number;
+  totalCount: number;
+}
+
+const SearchReposParams = Type.Object({
+  query: Type.String({
+    description:
+      "GitHub repository search query. Plain terms plus qualifiers like language:typescript, topic:orm, stars:>1000, org:vercel.",
+  }),
+  sort: Type.Optional(
+    Type.Union([Type.Literal("stars"), Type.Literal("updated"), Type.Literal("best-match")], {
+      description: "Result ordering. Default: stars.",
+    }),
+  ),
+  limit: Type.Optional(
+    Type.Number({
+      minimum: 1,
+      maximum: 50,
+      description: "Max results. Default: 10.",
+    }),
+  ),
+});
+
+export function createSearchReposTool(githubClient: GitHubClientProvider) {
+  return defineTool<typeof SearchReposParams, SearchReposDetails>({
+    name: LIBRARIAN_TOOL_NAMES.searchRepos,
+    label: "Search repos metadata",
+    description: "Discover GitHub repositories.",
+    promptSnippet: "Search repos metadata",
+    promptGuidelines: ["Use for questions like 'what are the popular X libraries'."],
+    parameters: SearchReposParams,
+
+    async execute(_toolCallId, params) {
+      const limit = params.limit ?? 10;
+      try {
+        const github = await githubClient();
+        const result = await github.searchRepositories({
+          query: params.query,
+          sort: params.sort ?? "stars",
+          limit,
+        });
+
+        const lines = result.hits.map((hit) => {
+          const meta: string[] = [`★${hit.stars}`];
+          if (hit.language) {
+            meta.push(hit.language);
+          }
+          if (hit.pushedAt) {
+            meta.push(`pushed ${hit.pushedAt.slice(0, 10)}`);
+          }
+          if (hit.archived) {
+            meta.push("ARCHIVED");
+          }
+          if (hit.fork) {
+            meta.push("fork");
+          }
+
+          const topics = hit.topics.length > 0 ? `\n  topics: ${hit.topics.join(", ")}` : "";
+          const description = hit.description ? `\n  ${hit.description}` : "";
+          return `${hit.repo} (${meta.join(" · ")})${description}${topics}`;
+        });
+
+        const header = `${result.totalCount} repositories match; showing ${result.hits.length}.`;
+        return {
+          content: [{ type: "text", text: [header, ...lines].join("\n\n") }],
+          details: {
+            kind: "search_repos",
+            query: params.query,
+            resultCount: result.hits.length,
+            totalCount: result.totalCount,
+          },
+        };
+      } catch (error) {
+        const message =
+          error instanceof GitHubApiError && error.retryAfterSeconds !== undefined
+            ? `${error.message} (retry after ~${error.retryAfterSeconds}s)`
+            : 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,
+        };
+      }
+    },
+  });
+}

package/extensions/librarian/trace.ts

@@ -0,0 +1,76 @@
+import type { AgentToolResult } from "@earendil-works/pi-agent-core";
+import type { CheckoutRepoDetails } from "./tools/checkout-repo.ts";
+import { LIBRARIAN_RUN_TOOL_NAMES } from "./tools/names.ts";
+import type { ProvideResultsDetails } from "./tools/provide-results.ts";
+import type { ReadGitHubFileDetails } from "./tools/read-github-file.ts";
+import type { SearchCodeDetails } from "./tools/search-code.ts";
+import type { SearchGitHubCodeDetails } from "./tools/search-github-code.ts";
+import type { SearchReposDetails } from "./tools/search-repos.ts";
+
+type RepoToolDetails =
+  | SearchReposDetails
+  | SearchCodeDetails
+  | SearchGitHubCodeDetails
+  | CheckoutRepoDetails
+  | ReadGitHubFileDetails
+  | ProvideResultsDetails;
+
+interface ToolResultShape {
+  content?: { type: string; text?: string }[];
+  details?: unknown;
+}
+
+export function asRepoToolDetails(details: unknown): RepoToolDetails | undefined {
+  if (
+    details &&
+    typeof details === "object" &&
+    "kind" in details &&
+    typeof details.kind === "string" &&
+    LIBRARIAN_RUN_TOOL_NAMES.includes(details.kind as (typeof LIBRARIAN_RUN_TOOL_NAMES)[number])
+  ) {
+    return details as RepoToolDetails;
+  }
+  return undefined;
+}
+
+export function summarizeToolResult(
+  result: AgentToolResult<unknown> | ToolResultShape | undefined,
+  isError: boolean,
+): string | undefined {
+  if (!result || typeof result !== "object") {
+    return undefined;
+  }
+
+  const firstText = result.content?.find(
+    (part): part is { type: "text"; text: string } =>
+      part.type === "text" && "text" in part && typeof part.text === "string",
+  )?.text;
+  if (isError) {
+    return firstText?.split("\n")[0]?.slice(0, 120);
+  }
+
+  const details = asRepoToolDetails(result.details);
+  if (details) {
+    switch (details.kind) {
+      case "search_repos":
+        return `${details.resultCount} of ${details.totalCount} repos`;
+      case "search_code":
+        return `${details.matchCount} hits · ${details.repoCount} repos · ${details.backend}`;
+      case "search_github_code":
+        return `${details.matchCount} hits · ${details.repoCount} repos · github`;
+      case "checkout_repo":
+        return `${details.reusedClone ? "cached" : "cloned"} · ${details.fileCount} files @ ${details.headSha.slice(0, 7)}`;
+      case "read_github_file":
+        return details.isDirectory ? `${details.lineCount} entries` : `${details.lineCount} lines`;
+      case "provide_results":
+        return `${details.locationCount} location${details.locationCount === 1 ? "" : "s"}`;
+    }
+  }
+
+  if (firstText !== undefined) {
+    const lineCount = firstText.length === 0 ? 0 : firstText.split("\n").length;
+    return `${lineCount} lines`;
+  }
+
+  return undefined;
+}

package/extensions/librarian/view.ts

@@ -0,0 +1,307 @@
+import path from "node:path";
+import type { AgentToolResult } from "@earendil-works/pi-agent-core";
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { getMarkdownTheme } from "@earendil-works/pi-coding-agent";
+import { Container, Markdown, Spacer, Text } from "@earendil-works/pi-tui";
+import type { LibrarianRunDetails, TraceCall } from "./run.ts";
+import { LIBRARIAN_TOOL_NAMES } from "./tools/names.ts";
+
+const COLLAPSED_TRACE_CALLS = 3;
+const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+const SPINNER_INTERVAL_MS = 80;
+
+interface LiveRenderContext {
+  invalidate(): void;
+  state: {
+    librarianSpinnerFrame?: number;
+    librarianSpinnerInterval?: ReturnType<typeof setInterval>;
+  };
+}
+
+export function formatDuration(milliseconds: number): string {
+  if (milliseconds < 0) {
+    return "0.0s";
+  }
+  const seconds = milliseconds / 1000;
+  if (seconds >= 60) {
+    const minutes = Math.floor(seconds / 60);
+    return `${minutes}m ${Math.round(seconds - minutes * 60)}s`;
+  }
+  return `${seconds.toFixed(1)}s`;
+}
+
+export function shorten(text: string, max: number): string {
+  const normalized = text.replace(/\s+/g, " ").trim();
+  return normalized.length <= max ? normalized : `${normalized.slice(0, max)}…`;
+}
+
+export function relativizeCachePath(rawPath: string, cacheDir: string): string {
+  const reposRoot = path.join(cacheDir, "repos") + path.sep;
+  if (!rawPath.startsWith(reposRoot)) {
+    return rawPath;
+  }
+
+  const underRepos = rawPath.slice(reposRoot.length);
+  const segments = underRepos.split(path.sep);
+  // repos/<owner>/<repo>/<file...> — drop the owner so the trace reads repo/file.
+  return segments.length > 1 ? segments.slice(1).join(path.sep) : underRepos;
+}
+
+function firstString(record: Record<string, unknown>, keys: string[]): string | undefined {
+  for (const key of keys) {
+    const value = record[key];
+    if (typeof value === "string" && value.trim().length > 0) {
+      return value;
+    }
+  }
+
+  for (const value of Object.values(record)) {
+    if (typeof value === "string" && value.trim().length > 0) {
+      return value;
+    }
+  }
+
+  return undefined;
+}
+
+export interface TraceLine {
+  verb: string;
+  subject: string;
+}
+
+export function formatTraceLine(call: TraceCall, cacheDir: string): TraceLine {
+  const args = (call.args && typeof call.args === "object" ? call.args : {}) as Record<
+    string,
+    unknown
+  >;
+
+  switch (call.name) {
+    case "read": {
+      const rawPath = typeof args.path === "string" ? args.path : "";
+      const offset = typeof args.offset === "number" ? args.offset : undefined;
+      const limit = typeof args.limit === "number" ? args.limit : undefined;
+      const range =
+        offset !== undefined || limit !== undefined
+          ? `:${offset ?? 1}${limit !== undefined ? `-${(offset ?? 1) + limit - 1}` : ""}`
+          : "";
+      return { verb: "read", subject: `${relativizeCachePath(rawPath, cacheDir)}${range}` };
+    }
+    case "bash": {
+      const command = typeof args.command === "string" ? args.command : "";
+      return { verb: "bash", subject: shorten(command, 120) };
+    }
+    case "grep": {
+      const pattern = typeof args.pattern === "string" ? args.pattern : "";
+      const searchPath = typeof args.path === "string" ? args.path : "";
+      const scope = searchPath ? ` ${relativizeCachePath(searchPath, cacheDir)}` : "";
+      return { verb: "grep", subject: `"${shorten(pattern, 60)}"${scope}` };
+    }
+    case "find": {
+      const pattern = typeof args.pattern === "string" ? args.pattern : "";
+      return { verb: "find", subject: shorten(pattern, 80) };
+    }
+    case "ls": {
+      const rawPath = typeof args.path === "string" ? args.path : ".";
+      return { verb: "ls", subject: relativizeCachePath(rawPath, cacheDir) };
+    }
+    case LIBRARIAN_TOOL_NAMES.searchRepos: {
+      const query = typeof args.query === "string" ? args.query : "";
+      return { verb: "search", subject: `repos ${shorten(query, 80)}` };
+    }
+    case LIBRARIAN_TOOL_NAMES.searchCode: {
+      const pattern = typeof args.pattern === "string" ? args.pattern : "";
+      const repo = typeof args.repo === "string" ? ` in ${shorten(args.repo, 40)}` : "";
+      return { verb: "search", subject: `code ${shorten(pattern, 60)}${repo}` };
+    }
+    case LIBRARIAN_TOOL_NAMES.searchGitHubCode: {
+      const pattern = typeof args.pattern === "string" ? args.pattern : "";
+      const repos = Array.isArray(args.repos)
+        ? args.repos
+            .map((repo) => {
+              if (!repo || typeof repo !== "object") {
+                return undefined;
+              }
+              const record = repo as Record<string, unknown>;
+              return typeof record.owner === "string" && typeof record.repo === "string"
+                ? `${record.owner}/${record.repo}`
+                : undefined;
+            })
+            .filter((repo): repo is string => repo !== undefined)
+        : [];
+      const owners = Array.isArray(args.owners) ? (args.owners as string[]) : [];
+      const scopeParts = [...repos, ...owners.map((owner) => `${owner}/*`)];
+      const scope = scopeParts.length > 0 ? ` in ${shorten(scopeParts.join(","), 40)}` : "";
+      return { verb: "search.gh", subject: `code ${shorten(pattern, 60)}${scope}` };
+    }
+    case LIBRARIAN_TOOL_NAMES.checkoutRepo: {
+      const repo = typeof args.repo === "string" ? args.repo : "";
+      const ref = typeof args.ref === "string" ? `@${args.ref}` : "";
+      return { verb: "checkout", subject: `${repo}${ref}` };
+    }
+    case LIBRARIAN_TOOL_NAMES.readGitHubFile: {
+      const owner = typeof args.owner === "string" ? args.owner : "";
+      const repo = typeof args.repo === "string" ? args.repo : "";
+      const filePath = typeof args.path === "string" ? args.path : "";
+      return { verb: "read.gh", subject: `${owner}/${repo}/${filePath}` };
+    }
+    case LIBRARIAN_TOOL_NAMES.provideResults:
+      return { verb: "results", subject: "" };
+    default: {
+      const subject = firstString(args, ["query", "url", "prompt", "objective"]);
+      return { verb: call.name, subject: subject ? shorten(subject, 80) : "" };
+    }
+  }
+}
+
+function renderTraceCallText(
+  call: TraceCall,
+  cacheDir: string,
+  theme: Theme,
+  spinnerFrame: string,
+): string {
+  const { verb, subject } = formatTraceLine(call, cacheDir);
+  const running = call.endedAt === undefined;
+  const icon = call.isError
+    ? theme.fg("error", "✗")
+    : running
+      ? theme.fg("warning", spinnerFrame)
+      : theme.fg("success", "✓");
+  const duration = formatDuration((call.endedAt ?? Date.now()) - call.startedAt);
+  const summary = call.resultSummary
+    ? theme.fg(call.isError ? "error" : "muted", ` (${shorten(call.resultSummary, 60)})`)
+    : "";
+
+  const subjectText = subject ? ` ${theme.fg("toolOutput", subject)}` : "";
+  return `  ${icon} ${theme.fg("dim", verb)}${subjectText}${summary} ${theme.fg("dim", `· ${duration}`)}`;
+}
+
+function renderQuestion(details: LibrarianRunDetails, expanded: boolean, theme: Theme): string {
+  return theme.fg("dim", expanded ? details.query : shorten(details.query, 120));
+}
+
+function renderFooter(details: LibrarianRunDetails, theme: Theme): string {
+  const callCount = details.trace.length;
+  const elapsed = formatDuration((details.endedAt ?? Date.now()) - details.startedAt);
+  const model = theme.fg("dim", `${details.modelLabel} (${details.thinkingLevel})`);
+  return theme.fg(
+    "muted",
+    `${callCount} tool call${callCount === 1 ? "" : "s"} · ${elapsed} · ${model}`,
+  );
+}
+
+function renderTrace(
+  details: LibrarianRunDetails,
+  expanded: boolean,
+  cacheDir: string,
+  theme: Theme,
+  spinnerFrame: string,
+): string[] {
+  const lines: string[] = [];
+  const calls = expanded ? details.trace : details.trace.slice(-COLLAPSED_TRACE_CALLS);
+  const hiddenCount = details.trace.length - calls.length;
+  if (hiddenCount > 0) {
+    lines.push(
+      theme.fg(
+        "muted",
+        `  … ${hiddenCount} earlier call${hiddenCount === 1 ? "" : "s"} (Ctrl+O to expand)`,
+      ),
+    );
+  }
+  for (const call of calls) {
+    lines.push(renderTraceCallText(call, cacheDir, theme, spinnerFrame));
+  }
+  return lines;
+}
+
+function updateLiveRender(context: LiveRenderContext | undefined, running: boolean): string {
+  if (!context) {
+    return (
+      SPINNER_FRAMES[Math.floor(Date.now() / SPINNER_INTERVAL_MS) % SPINNER_FRAMES.length] ?? ""
+    );
+  }
+
+  context.state.librarianSpinnerFrame ??= 0;
+  if (running && !context.state.librarianSpinnerInterval) {
+    context.state.librarianSpinnerInterval = setInterval(() => {
+      context.state.librarianSpinnerFrame =
+        ((context.state.librarianSpinnerFrame ?? 0) + 1) % SPINNER_FRAMES.length;
+      context.invalidate();
+    }, SPINNER_INTERVAL_MS);
+  } else if (!running && context.state.librarianSpinnerInterval) {
+    clearInterval(context.state.librarianSpinnerInterval);
+    delete context.state.librarianSpinnerInterval;
+  }
+
+  return SPINNER_FRAMES[context.state.librarianSpinnerFrame] ?? "";
+}
+
+export function renderLibrarianResult(
+  result: AgentToolResult<LibrarianRunDetails>,
+  options: { expanded: boolean; isPartial: boolean },
+  theme: Theme,
+  cacheDir: string,
+  context?: LiveRenderContext,
+): Container {
+  const container = new Container();
+  const details = result.details;
+
+  if (!details) {
+    const firstText = result.content.find((part) => part.type === "text");
+    container.addChild(
+      new Text(firstText && "text" in firstText ? firstText.text : "(no output)", 0, 0),
+    );
+    return container;
+  }
+
+  const running = options.isPartial || details.status === "running";
+  const spinnerFrame = updateLiveRender(context, running);
+  container.addChild(new Text(renderQuestion(details, options.expanded, theme), 0, 0));
+  container.addChild(new Spacer(1));
+
+  if (running || !details.findings) {
+    for (const line of renderTrace(details, options.expanded, cacheDir, theme, spinnerFrame)) {
+      container.addChild(new Text(line, 0, 0));
+    }
+  }
+
+  if (!running) {
+    if (details.findings) {
+      const markdown = buildFindingsMarkdown(details, options.expanded);
+      container.addChild(new Markdown(markdown, 0, 0, getMarkdownTheme()));
+    } else if (details.error) {
+      container.addChild(new Spacer(1));
+      container.addChild(new Text(theme.fg("error", `  ${details.error}`), 0, 0));
+    }
+  }
+
+  container.addChild(new Spacer(1));
+  container.addChild(new Text(renderFooter(details, theme), 0, 0));
+  return container;
+}
+
+function buildFindingsMarkdown(details: LibrarianRunDetails, expanded: boolean): string {
+  const findings = details.findings;
+  if (!findings) {
+    return "";
+  }
+
+  const sections = [findings.summary];
+
+  if (findings.locations.length > 0) {
+    const bullets = findings.locations.map((location) => {
+      const lineSuffix = location.lines ? `:${location.lines}` : "";
+      return `- \`${location.repo}/${location.file}${lineSuffix}\` — ${location.note}`;
+    });
+    sections.push(bullets.join("\n"));
+  }
+
+  if (findings.description) {
+    sections.push(findings.description);
+  }
+
+  return expanded ? sections.join("\n\n") : findings.summary;
+}
+
+export function renderLibrarianCall(theme: Theme): Text {
+  return new Text(theme.fg("toolTitle", theme.bold("Librarian")), 0, 0);
+}

package/extensions/librarian.ts

@@ -0,0 +1,181 @@
+import type { ExtensionAPI, SessionStartEvent } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+import { applyAttachState, readAttachState, setAttachState } from "./librarian/attach.ts";
+import { createGitHubClientProvider } from "./librarian/github.ts";
+import { resolveLibrarianModel } from "./librarian/model.ts";
+import { type LibrarianRunDetails, runLibrarian, type TraceCall } from "./librarian/run.ts";
+import { loadSettings } from "./librarian/settings.ts";
+import { createCheckoutRepoTool } from "./librarian/tools/checkout-repo.ts";
+import { ATTACHABLE_TOOL_NAMES } from "./librarian/tools/names.ts";
+import { createReadGitHubFileTool } from "./librarian/tools/read-github-file.ts";
+import { searchCodeTool } from "./librarian/tools/search-code.ts";
+import { createSearchGitHubCodeTool } from "./librarian/tools/search-github-code.ts";
+import { createSearchReposTool } from "./librarian/tools/search-repos.ts";
+import {
+  formatTraceLine,
+  renderLibrarianCall,
+  renderLibrarianResult,
+  shorten,
+} from "./librarian/view.ts";
+
+const LibrarianParams = Type.Object({
+  query: Type.String({
+    description:
+      "The research question. Include everything you already know: symbols, error messages, desired output shape. Do not guess unknown details — say what is uncertain and let the librarian discover it.",
+  }),
+  repos: Type.Optional(
+    Type.Array(Type.String(), {
+      description: "Optional owner/repo scope for the research.",
+      maxItems: 20,
+    }),
+  ),
+  owners: Type.Optional(
+    Type.Array(Type.String(), {
+      description: "Optional owner/org scope for the research.",
+      maxItems: 20,
+    }),
+  ),
+});
+
+export default function librarianExtension(pi: ExtensionAPI): void {
+  const settings = loadSettings();
+  const githubClient = createGitHubClientProvider();
+
+  const attachableTools = [
+    createSearchReposTool(githubClient),
+    searchCodeTool,
+    createSearchGitHubCodeTool(githubClient),
+    createCheckoutRepoTool(settings.cacheDir),
+    createReadGitHubFileTool(githubClient),
+  ];
+
+  for (const tool of attachableTools) {
+    pi.registerTool({
+      ...tool,
+      description: `${tool.description} (Librarian tool, attached via /librarian: use for quick single lookups; delegate multi-step research to the librarian tool.)`,
+      renderCall(args, theme) {
+        const { verb, subject } = formatTraceLine(
+          { name: tool.name, args, id: "", startedAt: 0 } satisfies TraceCall,
+          settings.cacheDir,
+        );
+        return new Text(
+          `${theme.fg("toolTitle", theme.bold(verb))} ${theme.fg("toolOutput", subject)}`,
+          0,
+          0,
+        );
+      },
+    });
+  }
+
+  pi.registerTool<typeof LibrarianParams, LibrarianRunDetails>({
+    name: "librarian",
+    label: "Librarian",
+    description:
+      "Understand complex, multi-repo codebases, exploring cross-repo relationships, analyzing architectural patterns, finding implementations across codebases, understanding code evolution/commit history, diving deep on specific code bases, getting comprehensive feature explanations, and exploring end-to-end system design across within or across repositories.",
+    promptSnippet:
+      "librarian: research GitHub repos (implementation questions, ecosystem comparisons, usage examples) and return cited findings",
+    promptGuidelines: [
+      "If a single file or reference must be located, you may use other means (search for downloaded dependencies, web search, etc), but for deeper queries that will take multiple steps to resolve, prefer the librarian.",
+    ],
+    parameters: LibrarianParams,
+
+    async execute(_toolCallId, params, signal, onUpdate, ctx) {
+      const thinkingLevel = settings.thinkingLevel ?? pi.getThinkingLevel();
+      const resolution = resolveLibrarianModel(ctx, settings.model, thinkingLevel);
+      if (!resolution) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: "No model available for the librarian. Configure librarian.model or select a session model.",
+            },
+          ],
+          details: {
+            status: "error",
+            query: params.query,
+            modelLabel: "(none)",
+            thinkingLevel,
+            trace: [],
+            checkouts: {},
+            startedAt: Date.now(),
+            endedAt: Date.now(),
+            error: "No model available.",
+          } satisfies LibrarianRunDetails,
+          isError: true,
+        };
+      }
+
+      return runLibrarian({
+        query: params.query,
+        repos: params.repos ?? [],
+        owners: params.owners ?? [],
+        model: resolution.model,
+        thinkingLevel: resolution.thinkingLevel,
+        settings,
+        githubClient,
+        signal,
+        onUpdate: onUpdate
+          ? (details) => {
+              onUpdate({
+                content: [{ type: "text", text: `Researching: ${shorten(params.query, 80)}` }],
+                details,
+              });
+            }
+          : undefined,
+      });
+    },
+
+    renderCall(_args, theme) {
+      return renderLibrarianCall(theme);
+    },
+
+    renderResult(result, options, theme, context) {
+      return renderLibrarianResult(result, options, theme, settings.cacheDir, context);
+    },
+  });
+
+  pi.registerCommand("librarian", {
+    description: "Attach/detach the librarian's GitHub tools in this session (on|off|status)",
+    getArgumentCompletions: (prefix) =>
+      ["on", "off", "status"]
+        .filter((option) => option.startsWith(prefix.trim()))
+        .map((option) => ({ value: option, label: option })),
+    async handler(args, ctx) {
+      const argument = args.trim().toLowerCase();
+      const currentlyAttached = readAttachState(ctx);
+
+      if (argument === "status") {
+        ctx.ui.notify(
+          currentlyAttached
+            ? `Librarian tools attached: ${ATTACHABLE_TOOL_NAMES.join(", ")}`
+            : "Librarian tools not attached. Run /librarian to attach.",
+          "info",
+        );
+        return;
+      }
+
+      const nextAttached =
+        argument === "on" ? true : argument === "off" ? false : !currentlyAttached;
+      if (nextAttached === currentlyAttached) {
+        ctx.ui.notify(
+          nextAttached ? "Librarian tools already attached." : "Librarian tools not attached.",
+          "info",
+        );
+        return;
+      }
+
+      setAttachState(pi, nextAttached);
+      ctx.ui.notify(
+        nextAttached
+          ? `Attached librarian tools: ${ATTACHABLE_TOOL_NAMES.join(", ")}`
+          : "Detached librarian tools.",
+        "info",
+      );
+    },
+  });
+
+  pi.on("session_start", async (_event: SessionStartEvent, ctx) => {
+    applyAttachState(pi, readAttachState(ctx));
+  });
+}

package/extensions/shared/typebox.ts

@@ -0,0 +1,31 @@
+import type { Static, TSchema } from "typebox";
+import { Value } from "typebox/value";
+
+export function parseTypeBoxValue<T extends TSchema>(
+  schema: T,
+  value: unknown,
+  context: string,
+): Static<T> {
+  if (Value.Check(schema, value)) {
+    return value as Static<T>;
+  }
+
+  throw new Error(formatTypeBoxError(schema, value, context));
+}
+
+export function safeParseTypeBoxValue<T extends TSchema>(
+  schema: T,
+  value: unknown,
+): Static<T> | undefined {
+  return Value.Check(schema, value) ? (value as Static<T>) : undefined;
+}
+
+function formatTypeBoxError(schema: TSchema, value: unknown, context: string): string {
+  const firstError = Value.Errors(schema, value)[0];
+  if (!firstError) {
+    return `${context}: invalid value.`;
+  }
+
+  const path = firstError.instancePath.length > 0 ? firstError.instancePath : "/";
+  return `${context}: ${path} ${firstError.message}`;
+}