@the-librarian/pi-extension 1.0.0-rc.2

package/README.md

@@ -0,0 +1,85 @@
+# The Librarian — Pi extension
+
+A [Pi](https://pi.dev) package that gives the Pi coding agent durable memory and
+cross-harness handoffs, backed by a remote
+[Librarian](https://github.com/JimJafar/the-librarian) MCP server.
+
+Pi's core has **no MCP support**, so this extension does the wiring itself: it
+registers the Librarian's 7 agent verbs as native Pi tools (each one a thin,
+fail-soft proxy over the server's stateless `/mcp` endpoint) and injects the
+Librarian primer into the system prompt. One install, zero config files.
+
+## What you get
+
+- **7 tools, identical to every other harness** — `recall`, `remember`,
+  `flag_memory`, `store_handoff`, `list_handoffs`, `claim_handoff`,
+  `search_references`. Descriptions and schemas mirror the server's
+  (a drift-guard test pins them), so the model is taught the same protocol in
+  Pi as in Claude Code, Codex, OpenCode, and Hermes.
+- **Primer injection** — the operator-editable `vault/primer.md` (≤2KB) is
+  fetched once per process from `GET <server>/primer.md` and appended to the
+  system prompt via `before_agent_start`.
+- **Four slash commands** (optional sugar): `/handoff`, `/takeover`, `/learn`,
+  `/toggle-private` — thin prompt templates that drive the corresponding tool
+  flows. See [`docs/slash-commands.md`](../../docs/slash-commands.md).
+- **Fail-soft everywhere** — if the Librarian is down, tools return a short
+  error string (never a thrown harness error), the primer is skipped, and the
+  user's turn is never blocked.
+
+## Install
+
+From npm (once published — see "Publishing" below):
+
+```sh
+pi install npm:@the-librarian/pi-extension
+```
+
+From source (works today):
+
+```sh
+git clone https://github.com/JimJafar/the-librarian
+pi install /path/to/the-librarian/integrations/pi
+```
+
+(`pi install git:…` of the monorepo root won't work — the package lives in the
+`integrations/pi` subdirectory, so install from a local clone path.)
+
+## Configure
+
+Set two environment variables in the shell that launches `pi`:
+
+| Variable | Meaning |
+| --- | --- |
+| `LIBRARIAN_MCP_URL` | The server's MCP endpoint, e.g. `https://your-librarian/mcp` |
+| `LIBRARIAN_AGENT_TOKEN` | A per-agent bearer token issued by your Librarian |
+| `LIBRARIAN_TIMEOUT_MS` | *(optional)* per-call timeout, default `15000` |
+
+Without both required variables the extension stays **dormant**: no tools, no
+network calls — only the four slash commands register, and they explain what's
+missing.
+
+Security posture (inherited from the security-reviewed clients in this family):
+the bearer token travels only in the `Authorization` header, redirects are
+refused so a 3xx can't carry the token cross-origin, the endpoint scheme is
+allowlisted to http(s), and response bodies are size-capped.
+
+## Develop
+
+This package is part of the `the-librarian` pnpm workspace:
+
+```sh
+pnpm install
+pnpm --filter @the-librarian/pi-extension test        # vitest
+pnpm --filter @the-librarian/pi-extension typecheck   # tsc --noEmit
+```
+
+The schema-parity suite imports the compiled `@librarian/mcp-server`, which is
+built automatically on `pnpm install` (its `prepare` script).
+
+## Publishing
+
+The package is publishable (`"private": false`) and carries the `pi-package`
+keyword, so `npm publish` from `integrations/pi/` both releases it and lists it
+in Pi's gallery at `pi.dev/packages`. **Publishing is a repo-owner action** —
+it is deliberately not part of any automated flow here. Until it's published,
+use the "from source" install above.

package/extensions/librarian/commands.ts

@@ -0,0 +1,77 @@
+// Native Pi slash commands for The Librarian — optional sugar (rethink D9).
+//
+// Four thin prompt templates aligned with docs/slash-commands.md and the
+// 7-verb surface. Each handler injects a user message that drives the LLM
+// through the corresponding tool flow; the tools (and the primer) carry the
+// actual protocol, so these stay deliberately skeletal. Pi's `registerCommand`
+// is one call per verb — cheap enough to keep.
+
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+
+const HANDOFF_PROMPT =
+  "Author a five-section handoff document with these exact headings: " +
+  "`## Start & intent`, `## Journey`, `## Current state`, `## What's left`, " +
+  "`## Open questions`. Then call `store_handoff` with the document (plus " +
+  "project_key / cwd / harness when known) and report the returned handoff_id.";
+
+const TAKEOVER_PROMPT =
+  "Call `list_handoffs` scoped to the current project_key + cwd (drop filters " +
+  "to broaden when nothing matches), present the candidates to the user — " +
+  "never auto-select — then `claim_handoff` the chosen id and continue the " +
+  "work its document describes. If the user supplied a handoff id, claim it directly.";
+
+const LEARN_PROMPT =
+  "Extract durable lessons from this conversation and feed user-approved ones " +
+  "to `remember`, one call per lesson — fire-and-forget: the user picking a " +
+  "lesson is the review, so submit and move on; the curator dedupes, merges, " +
+  "and files each one asynchronously.";
+
+const TOGGLE_ON =
+  "Private mode is ON. `[librarian:private=on]` — do not call `remember`, " +
+  "`store_handoff`, or `flag_memory` until told otherwise. `recall` and " +
+  "`search_references` stay allowed; note that read queries still reach the " +
+  "Librarian server's logs. Remain in this state until explicitly toggled off.";
+
+const TOGGLE_OFF = "Private mode is OFF. `[librarian:private=off]` — normal operation resumed.";
+
+const TOGGLE_PROMPT =
+  "Toggle in-conversation private mode. Inject the inverse of the most recent " +
+  `\`[librarian:private=on|off]\` marker. If ON: emit \`${TOGGLE_OFF}\`. If ` +
+  `OFF or no marker: emit \`${TOGGLE_ON}\`.`;
+
+export const COMMAND_SPECS = [
+  {
+    name: "handoff",
+    description: "Author and persist a cross-harness handoff document",
+    prompt: HANDOFF_PROMPT,
+  },
+  {
+    name: "takeover",
+    description: "Pick up a handoff from another agent / harness",
+    prompt: TAKEOVER_PROMPT,
+  },
+  {
+    name: "learn",
+    description: "Extract durable lessons from this conversation into durable memory",
+    prompt: LEARN_PROMPT,
+  },
+  {
+    name: "toggle-private",
+    description: "Toggle in-conversation private mode (no server state, no hook)",
+    prompt: TOGGLE_PROMPT,
+  },
+] as const;
+
+export function registerCommands(pi: ExtensionAPI): void {
+  for (const spec of COMMAND_SPECS) {
+    pi.registerCommand(spec.name, {
+      description: spec.description,
+      handler: async (args: string, _ctx: ExtensionCommandContext) => {
+        // `sendUserMessage` always triggers a turn, so the template actually
+        // drives the flow (a UI notify would only reach the human).
+        const input = args.trim();
+        pi.sendUserMessage(input ? `${spec.prompt}\n\nUser input: ${input}` : spec.prompt);
+      },
+    });
+  }
+}

package/extensions/librarian/config.ts

@@ -0,0 +1,38 @@
+// Environment-driven configuration for the Pi ↔ Librarian integration.
+//
+// The extension stays DORMANT unless a remote Librarian is configured
+// (LIBRARIAN_MCP_URL + LIBRARIAN_AGENT_TOKEN). This mirrors the other harness
+// integrations: no endpoint/token → no automatic calls, no surprises.
+//
+// 2026-06-12 rethink (spec §7, D14) — the session-era `projectKey` /
+// `deviceId` fields are retired with the session subsystem; the surviving
+// config is exactly what the 7 tool proxies + primer fetch need.
+
+export const HARNESS = "pi" as const;
+
+export interface LibrarianConfig {
+  endpoint: string;
+  token: string;
+  timeoutMs?: number | undefined;
+}
+
+function parsePositiveInt(value: string | undefined): number | undefined {
+  if (value === undefined) return undefined;
+  const n = Number(value);
+  return Number.isFinite(n) && n > 0 ? n : undefined;
+}
+
+/**
+ * Read config from the environment. Returns null when the remote Librarian is
+ * not configured — the caller treats that as "extension dormant".
+ */
+export function readConfig(env: NodeJS.ProcessEnv = process.env): LibrarianConfig | null {
+  const endpoint = env.LIBRARIAN_MCP_URL?.trim();
+  const token = env.LIBRARIAN_AGENT_TOKEN?.trim();
+  if (!endpoint || !token) return null;
+
+  const config: LibrarianConfig = { endpoint, token };
+  const timeoutMs = parsePositiveInt(env.LIBRARIAN_TIMEOUT_MS);
+  if (timeoutMs !== undefined) config.timeoutMs = timeoutMs;
+  return config;
+}

package/extensions/librarian/index.ts

@@ -0,0 +1,64 @@
+// The Librarian — Pi coding-agent extension (rethink spec §7, D14).
+//
+// Ported from the standalone the-librarian-pi-extension repo. The 2026-06-12
+// rethink retires the conv-state injection, the per-turn conv_state fetch, and
+// the 3-tool limitation; what survives is exactly:
+//
+//   - the 7 agent verbs (recall / remember / flag_memory / store_handoff /
+//     list_handoffs / claim_handoff / search_references) as native Pi tool
+//     proxies over the Librarian's stateless /mcp endpoint — see `tools.ts`;
+//   - the ≤2KB primer, fetched from `GET /primer.md` once per process and
+//     appended to the system prompt via `before_agent_start` — see `primer.ts`;
+//   - four user-facing slash commands (`/handoff`, `/takeover`, `/learn`,
+//     `/toggle-private`) as thin prompt templates — see `commands.ts`.
+//
+// Private mode is purely in-conversation: an `[librarian:private=on|off]`
+// marker the LLM owns. There is no server flag, no on-disk state, and no
+// privacy hook here.
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { registerCommands } from "./commands.js";
+import { readConfig } from "./config.js";
+import { createMcpClient } from "./mcp-client.js";
+import { createPrimerSource, registerPrimerHook } from "./primer.js";
+import { registerLibrarianTools } from "./tools.js";
+
+const CONFIG_HINT =
+  "The Librarian is not configured. Set LIBRARIAN_MCP_URL and LIBRARIAN_AGENT_TOKEN.";
+
+const COMMAND_VERBS = ["handoff", "takeover", "learn", "toggle-private"] as const;
+
+export default function librarian(pi: ExtensionAPI): void {
+  const config = readConfig();
+
+  if (!config) {
+    // Dormant: no endpoint/token → no tools, no hook, no automatic calls.
+    // Still register the commands so they explain the missing configuration
+    // instead of being "unknown command".
+    for (const verb of COMMAND_VERBS) {
+      pi.registerCommand(verb, {
+        description: `${verb} (Librarian not configured)`,
+        handler: async (_args, ctx) => {
+          ctx.ui.notify(CONFIG_HINT, "warning");
+        },
+      });
+    }
+    return;
+  }
+
+  // One shared MCP client for all 7 tool proxies.
+  const mcp = createMcpClient({
+    endpoint: config.endpoint,
+    token: config.token,
+    ...(config.timeoutMs !== undefined ? { timeoutMs: config.timeoutMs } : {}),
+  });
+
+  // Expose the Librarian's 7 verbs to the model directly (no mcp.json needed).
+  registerLibrarianTools(pi, mcp);
+
+  // Primer → system prompt, once per turn, cached per process, fail-soft.
+  registerPrimerHook(pi, createPrimerSource({ endpoint: config.endpoint }));
+
+  // The four user-facing slash commands (optional sugar, D9).
+  registerCommands(pi);
+}

package/extensions/librarian/mcp-client.ts

@@ -0,0 +1,228 @@
+// Minimal MCP client for the Librarian HTTP server.
+//
+// The Librarian's `/mcp` is a STATELESS JSON-RPC 2.0 endpoint: no `initialize`
+// handshake and no session id — a `tools/call` is POSTed directly with a Bearer
+// token. So this is a single-request client: build the envelope, POST it, map
+// every failure onto a typed `McpClientError`, and return the tool's text.
+//
+// Ported from the standalone the-librarian-pi-extension repo (2026-06-12
+// rethink, D14) minus the retired session-prose parsers. Mirrors the security
+// posture of the Hermes integration's `client.py` (which a security review
+// hardened): the bearer token lives ONLY in the Authorization header and is
+// never put into an error message; 3xx redirects are refused so a redirect
+// can't carry the token cross-origin; the endpoint scheme is allowlisted to
+// http(s); and the response body is capped so a runaway endpoint cannot
+// exhaust memory. The transport is injectable so tests never touch the
+// network.
+
+const DEFAULT_TIMEOUT_MS = 15_000;
+const DEFAULT_MAX_RESPONSE_BYTES = 8 * 1024 * 1024;
+const MAX_RPC_MESSAGE_CHARS = 200;
+
+export type McpClientErrorKind = "config" | "network" | "timeout" | "http" | "rpc" | "malformed";
+
+export class McpClientError extends Error {
+  override readonly name = "McpClientError";
+  readonly kind: McpClientErrorKind;
+  readonly status?: number | undefined;
+
+  constructor(kind: McpClientErrorKind, message: string, extra: { status?: number } = {}) {
+    super(message);
+    this.kind = kind;
+    this.status = extra.status;
+  }
+}
+
+export interface McpRequest {
+  url: string;
+  body: string;
+  headers: Record<string, string>;
+  timeoutMs: number;
+}
+
+export interface McpResponse {
+  status: number;
+  body: string;
+}
+
+/** POST and return `(status, body)`. Throw a TimeoutError-named error on timeout. */
+export type McpTransport = (req: McpRequest) => Promise<McpResponse>;
+
+export interface McpClientConfig {
+  endpoint: string;
+  token: string;
+  timeoutMs?: number;
+  /** Cap on the buffered response body (default 8 MiB). */
+  maxResponseBytes?: number;
+}
+
+export interface McpClient {
+  callTool(name: string, args: Record<string, unknown>): Promise<string>;
+}
+
+export function createMcpClient(config: McpClientConfig, transport?: McpTransport): McpClient {
+  let url: URL;
+  try {
+    url = new URL(config.endpoint);
+  } catch {
+    throw new McpClientError("config", "Librarian endpoint is not a valid URL");
+  }
+  // Allowlist the scheme so a mistemplated endpoint can't reach a file:/data:
+  // handler (config-driven SSRF / local file read).
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    throw new McpClientError(
+      "config",
+      `Librarian endpoint must be http(s), got ${url.protocol.replace(/:$/, "") || "(none)"}`,
+    );
+  }
+  // Reject HTTP basic-auth userinfo in the URL: the token is the auth mechanism,
+  // and an embedded password is a second secret that would otherwise leak into
+  // the network error message below (same leak class as the bearer token).
+  if (url.username || url.password) {
+    throw new McpClientError(
+      "config",
+      "Librarian endpoint must not embed credentials; authenticate with the token instead",
+    );
+  }
+  const endpoint = config.endpoint;
+  // A credential-free, query-free rendering used in error messages so nothing
+  // secret-bearing in the endpoint can leak into logs.
+  const safeEndpoint = `${url.protocol}//${url.host}${url.pathname}`;
+  const token = config.token;
+  const timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const maxResponseBytes = config.maxResponseBytes ?? DEFAULT_MAX_RESPONSE_BYTES;
+  const send = transport ?? defaultTransport(maxResponseBytes);
+
+  return {
+    async callTool(name, args) {
+      const body = JSON.stringify({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "tools/call",
+        params: { name, arguments: args },
+      });
+      // The token lives ONLY here — never in args, the URL, or any error text.
+      const headers = {
+        "Content-Type": "application/json",
+        Accept: "application/json",
+        Authorization: `Bearer ${token}`,
+      };
+
+      let response: McpResponse;
+      try {
+        response = await send({ url: endpoint, body, headers, timeoutMs });
+      } catch (err) {
+        if (err instanceof McpClientError) throw err;
+        if (isTimeoutError(err)) {
+          throw new McpClientError("timeout", `${name} timed out after ${timeoutMs}ms`);
+        }
+        // Don't interpolate the underlying error (it may echo the request) —
+        // keep the token-bearing call strictly out of anything we render.
+        throw new McpClientError(
+          "network",
+          `${name} could not reach the Librarian at ${safeEndpoint}`,
+        );
+      }
+
+      if (response.status !== 200) {
+        throw new McpClientError("http", `${name} returned HTTP ${response.status}`, {
+          status: response.status,
+        });
+      }
+
+      let payload: unknown;
+      try {
+        payload = JSON.parse(response.body);
+      } catch {
+        throw new McpClientError("malformed", `${name} returned non-JSON`);
+      }
+
+      // `!= null` (not `"error" in payload`) so a spec-tolerant `error: null`
+      // alongside a result is treated as success, not a phantom rpc failure.
+      if (isRecord(payload) && payload.error != null) {
+        const rpc = payload.error;
+        const code = isRecord(rpc) ? rpc.code : undefined;
+        // Truncate the server-controlled message so it can't bloat logs.
+        const msg = isRecord(rpc) ? String(rpc.message ?? "").slice(0, MAX_RPC_MESSAGE_CHARS) : "";
+        throw new McpClientError("rpc", `${name} failed: ${msg} (code ${String(code)})`);
+      }
+
+      const text = extractText(payload);
+      if (text === null) {
+        throw new McpClientError("malformed", `${name} response had no text content`);
+      }
+      return text;
+    },
+  };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+function isTimeoutError(err: unknown): boolean {
+  const name = (err as { name?: string } | null)?.name;
+  const code = (err as { code?: string } | null)?.code;
+  return name === "AbortError" || name === "TimeoutError" || code === "ETIMEDOUT";
+}
+
+/** Pull `result.content[0].text` from an MCP tool response, or null. */
+function extractText(payload: unknown): string | null {
+  if (!isRecord(payload)) return null;
+  const result = payload.result;
+  if (!isRecord(result)) return null;
+  const content = result.content;
+  if (!Array.isArray(content) || content.length === 0) return null;
+  const first: unknown = content[0];
+  if (!isRecord(first)) return null;
+  return typeof first.text === "string" ? first.text : null;
+}
+
+function defaultTransport(maxResponseBytes: number): McpTransport {
+  return async ({ url, body, headers, timeoutMs }) => {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+      const response = await fetch(url, {
+        method: "POST",
+        body,
+        headers,
+        // A 3xx must NEVER be followed: fetch would carry the Authorization
+        // header to the redirect target and leak the bearer token cross-origin.
+        // The Librarian /mcp is a single stateless POST with no legitimate 3xx.
+        redirect: "error",
+        signal: controller.signal,
+      });
+      return { status: response.status, body: await readCapped(response, maxResponseBytes) };
+    } finally {
+      clearTimeout(timer);
+    }
+  };
+}
+
+async function readCapped(response: Response, cap: number): Promise<string> {
+  const reader = response.body?.getReader();
+  if (!reader) {
+    // No readable stream (e.g. an empty body). arrayBuffer buffers fully, but
+    // we still enforce the BYTE cap before decoding so the protection holds.
+    const buffer = Buffer.from(await response.arrayBuffer());
+    if (buffer.byteLength > cap) {
+      throw new McpClientError("malformed", "Librarian response exceeded the size cap");
+    }
+    return buffer.toString("utf8");
+  }
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    if (!value) continue;
+    total += value.byteLength;
+    if (total > cap) {
+      await reader.cancel();
+      throw new McpClientError("malformed", "Librarian response exceeded the size cap");
+    }
+    chunks.push(value);
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}

package/extensions/librarian/primer.ts

@@ -0,0 +1,100 @@
+// Primer injection via `before_agent_start` (rethink spec §5.2, D9).
+//
+// The Librarian teaches agents through one ≤2KB primer served unauthenticated
+// at `GET /primer.md` on the server root (the same document every other
+// harness sees). This module fetches it once per process, caches it, and
+// appends it to Pi's system prompt — the thinnest native channel Pi offers.
+//
+// Fail-soft contract (AGENTS.md §2): every failure path yields an empty primer
+// and an unchanged system prompt. The user's turn is never blocked; a fetch
+// failure is retried on the next turn rather than cached.
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+const DEFAULT_TIMEOUT_MS = 5_000;
+// The server enforces ≤2KB on save; 64KB of headroom keeps the cap a pure
+// runaway-endpoint guard rather than a contract we could trip on first.
+const DEFAULT_MAX_BYTES = 64 * 1024;
+
+export interface PrimerSourceConfig {
+  /** The configured LIBRARIAN_MCP_URL (usually `https://host/mcp`). */
+  endpoint: string;
+  timeoutMs?: number;
+  maxBytes?: number;
+  /** Injectable for tests. */
+  fetchImpl?: typeof fetch;
+}
+
+/**
+ * Resolve the primer URL from the MCP endpoint. The primer is served at the
+ * SERVER ROOT (`/primer.md`), not under `/mcp` — root-relative resolution
+ * strips the endpoint's path. Returns null for an unparseable endpoint.
+ */
+export function primerUrl(endpoint: string): string | null {
+  try {
+    return new URL("/primer.md", endpoint).toString();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Build a per-process primer source: the first successful fetch is cached for
+ * the lifetime of the process; failures return "" WITHOUT caching so a later
+ * turn can retry once the server is back.
+ */
+export function createPrimerSource(config: PrimerSourceConfig): () => Promise<string> {
+  const url = primerUrl(config.endpoint);
+  const timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const maxBytes = config.maxBytes ?? DEFAULT_MAX_BYTES;
+  const fetchImpl = config.fetchImpl ?? fetch;
+  let cached: string | null = null;
+
+  return async function getPrimer(): Promise<string> {
+    if (cached !== null) return cached;
+    if (!url) return "";
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+      // No Authorization header: /primer.md is unauthenticated by design, so
+      // the bearer token has no business on this request. Redirects are
+      // refused to match the MCP client's posture (and a primer has no
+      // legitimate 3xx).
+      const response = await fetchImpl(url, {
+        method: "GET",
+        redirect: "error",
+        signal: controller.signal,
+      });
+      if (response.status !== 200) return "";
+      const text = await response.text();
+      if (Buffer.byteLength(text, "utf8") > maxBytes) return "";
+      cached = text;
+      return cached;
+    } catch {
+      return "";
+    } finally {
+      clearTimeout(timer);
+    }
+  };
+}
+
+/**
+ * Wire the primer into Pi's system prompt. `before_agent_start` fires once per
+ * turn after Pi assembles the system prompt; the SDK chains multiple
+ * extensions' `systemPrompt` returns, so this append cooperates with any other
+ * extension that also augments the prompt. Empty primer → no return value →
+ * Pi leaves the prompt untouched.
+ */
+export function registerPrimerHook(pi: ExtensionAPI, getPrimer: () => Promise<string>): void {
+  pi.on("before_agent_start", async (event) => {
+    try {
+      const primer = await getPrimer();
+      if (!primer.trim()) return;
+      return { systemPrompt: `${event.systemPrompt}\n\n${primer}` };
+    } catch {
+      // Defensive net — getPrimer already swallows its own errors, but a
+      // top-level throw must never break the user's turn.
+      return;
+    }
+  });
+}

package/extensions/librarian/tools.ts

@@ -0,0 +1,223 @@
+// The Librarian's 7 agent verbs, registered natively in the extension.
+//
+// Pi's CORE has no MCP support (the `mcp.json` / mcpServers feature lives in
+// third-party adapter extensions, not the runtime). So rather than ask every
+// user to install an MCP adapter and hand-place a config file, the extension
+// exposes the Librarian's tools to the model itself via `pi.registerTool`,
+// proxying each call as a `tools/call` over HTTP. One `pi install`, zero config.
+//
+// Tool descriptions are the teaching surface (rethink spec §5.1): each one is
+// copied VERBATIM from `@librarian/mcp-server/src/mcp/tools/<verb>.ts` so Pi
+// users see exactly what every other harness sees. Schemas mirror the server's
+// `inputSchema`s minus `agent_id` (the server resolves the caller from the
+// bearer token) and the retired `conv_id`. Server fields typed
+// `["string","null"]` are exposed here as optional strings — omission and null
+// are equivalent for those filters, and a plain `string` type survives every
+// provider's schema translation (Google's rejects type arrays). The
+// schema-parity drift guard in `tests/schema-parity.test.ts` pins all of this
+// against the server package mechanically.
+//
+// Fail-soft (AGENTS.md §2): a proxy NEVER throws into the harness. A network /
+// server failure comes back as a short error string the model can read and
+// route around — the user's turn is never broken by a Librarian outage.
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type, type TSchema } from "typebox";
+import { McpClientError, type McpClient } from "./mcp-client.js";
+
+// Drop undefined values so optional args aren't sent as JSON nulls.
+function compact(obj: Record<string, unknown>): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(obj)) {
+    if (value !== undefined) out[key] = value;
+  }
+  return out;
+}
+
+export interface LibrarianToolSpec {
+  name: string;
+  label: string;
+  description: string;
+  parameters: TSchema;
+}
+
+/**
+ * The 7-verb agent surface (rethink spec §5.1), one spec per server tool.
+ * Exposed as a function (fresh schema objects per call) so tests can inspect
+ * the specs without registering anything.
+ */
+export function librarianToolSpecs(): LibrarianToolSpec[] {
+  return [
+    {
+      name: "recall",
+      label: "Recall",
+      description:
+        "Search the owner's durable memories. Call this before answering anything " +
+        "that may have prior context — at task start, and whenever a stored fact, " +
+        "preference, or past decision could change your answer. Memories only: " +
+        "long-form reference docs are NOT here — search those with " +
+        "`search_references`. Query by free text; `tags` narrows to memories " +
+        "carrying any of the supplied tags. Pass `include_ids: true` to prefix " +
+        "each result with its memory id, so a memory that turns out to be wrong " +
+        "can be passed straight to `flag_memory`.",
+      parameters: Type.Object({
+        query: Type.Optional(Type.String()),
+        tags: Type.Optional(Type.Array(Type.String())),
+        project_key: Type.Optional(Type.String()),
+        include_ids: Type.Optional(Type.Boolean()),
+        limit: Type.Optional(Type.Number()),
+      }),
+    },
+    {
+      name: "remember",
+      label: "Remember",
+      description:
+        "Save a durable fact, preference, or decision the moment you learn it — " +
+        "not transient chatter. Fire-and-forget: submit and move on; the curator " +
+        "files it asynchronously (dedupe, merge, link — no need to check first). " +
+        "Give it a short `title` and a self-contained `body`; add `tags` and a " +
+        "`project_key` so it surfaces in the right context. Caller-supplied " +
+        "`is_global` / `requires_approval` are ignored.",
+      parameters: Type.Object({
+        title: Type.String(),
+        body: Type.String(),
+        project_key: Type.Optional(Type.String()),
+        applies_to: Type.Optional(Type.Array(Type.String())),
+        priority: Type.Optional(Type.String()),
+        confidence: Type.Optional(Type.String()),
+        tags: Type.Optional(Type.Array(Type.String())),
+      }),
+    },
+    {
+      name: "flag_memory",
+      label: "Flag memory",
+      description:
+        "A recalled memory is wrong, misleading, or outdated — flag it with a short " +
+        "free-text `reason` (required: say why). The flag routes the memory to human " +
+        "review and demotes it below unflagged matches in recall; it never edits, " +
+        "archives, or deletes, and there is no 'this was useful' counterpart. Use it " +
+        "sparingly, only when a memory actively led you astray.",
+      parameters: Type.Object({
+        memory_id: Type.String(),
+        reason: Type.String({ minLength: 1, maxLength: 2000 }),
+      }),
+    },
+    {
+      name: "store_handoff",
+      label: "Store handoff",
+      description:
+        "Hand work off: persist a handoff document so another agent — on any " +
+        "harness — can resume your work later. Call it when pausing mid-task or " +
+        "ending a session that isn't finished. The document must carry exactly " +
+        "these five sections — Start & intent, Journey, Current state, What's " +
+        "left, Open questions — or it is rejected. The other side picks it up " +
+        "with `list_handoffs` then `claim_handoff`.",
+      parameters: Type.Object({
+        title: Type.String({ minLength: 5, maxLength: 120 }),
+        document_md: Type.String({ minLength: 100, maxLength: 50000 }),
+        project_key: Type.Optional(Type.String()),
+        source_ref: Type.Optional(Type.String()),
+        cwd: Type.Optional(Type.String()),
+        harness: Type.Optional(Type.String()),
+        tags: Type.Optional(Type.Array(Type.String(), { maxItems: 10 })),
+      }),
+    },
+    {
+      name: "list_handoffs",
+      label: "List handoffs",
+      description:
+        "Take over work, step 1: list the unclaimed handoffs waiting to be picked " +
+        "up, then `claim_handoff` the one you want. Default scope is the caller's " +
+        "current project_key + cwd when both are supplied; drop either filter to " +
+        "broaden when nothing matches.",
+      parameters: Type.Object({
+        project_key: Type.Optional(Type.String()),
+        cwd: Type.Optional(Type.String()),
+        harness: Type.Optional(Type.String()),
+        limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 100 })),
+      }),
+    },
+    {
+      name: "claim_handoff",
+      label: "Claim handoff",
+      description:
+        "Take over work, step 2 (after `list_handoffs`): atomically claim a " +
+        "handoff and receive its document to resume from. Claims race — 404 if " +
+        "the id is unknown; 409 if another agent claimed first (the existing " +
+        "claim is included so you can say who has it and since when).",
+      parameters: Type.Object({
+        handoff_id: Type.String({ minLength: 1 }),
+        claiming_agent_id: Type.Optional(Type.String()),
+        claiming_harness: Type.Optional(Type.String()),
+        claiming_source_ref: Type.Optional(Type.String()),
+        claiming_cwd: Type.Optional(Type.String()),
+      }),
+    },
+    {
+      name: "search_references",
+      label: "Search references",
+      description:
+        "Search the long-form reference documents (background material the " +
+        "operator filed under references/ — specs, manuals, design notes). " +
+        "References are deliberately NOT auto-recalled and never appear in " +
+        "`recall` results, so search here when the task needs that depth. " +
+        "Returns each match's vault path + the query-relevant section.",
+      parameters: Type.Object({
+        query: Type.String({ description: "What to look up in the references." }),
+        limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 100 })),
+      }),
+    },
+  ];
+}
+
+/** The 7 tool names this extension registers (for tests / smoke). */
+export const LIBRARIAN_TOOL_NAMES = [
+  "recall",
+  "remember",
+  "flag_memory",
+  "store_handoff",
+  "list_handoffs",
+  "claim_handoff",
+  "search_references",
+] as const;
+
+/**
+ * Register the 7 Librarian verbs as native Pi tools. Each is a thin proxy:
+ * forward to the remote MCP `tools/call`, return the server's prose. Failures
+ * come back as an error STRING (never a throw): the model reads it, tells the
+ * user, and keeps working — a Librarian outage must not break the turn.
+ */
+export function registerLibrarianTools(pi: ExtensionAPI, client: McpClient): void {
+  for (const spec of librarianToolSpecs()) {
+    pi.registerTool({
+      name: spec.name,
+      label: spec.label,
+      description: spec.description,
+      parameters: spec.parameters,
+      execute: async (_toolCallId: string, params: Record<string, unknown>) => {
+        try {
+          const text = await client.callTool(spec.name, compact(params));
+          return { content: [{ type: "text" as const, text }], details: {} };
+        } catch (err) {
+          // McpClientError messages are credential-free by construction; any
+          // other throw gets a generic line so nothing unexpected leaks.
+          const reason =
+            err instanceof McpClientError
+              ? err.message
+              : `${spec.name} failed before reaching the Librarian`;
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text:
+                  `Librarian unavailable — ${reason}. ` +
+                  "Continue the user's work without it; do not block on memory.",
+              },
+            ],
+            details: {},
+          };
+        }
+      },
+    });
+  }
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@the-librarian/pi-extension",
+  "version": "1.0.0-rc.2",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Pi coding-agent package for The Librarian: the 7 memory/handoff tools + primer injection, backed by a remote Librarian MCP server.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "author": {
+    "name": "Jim Sangwine",
+    "email": "jim@sangwine.net"
+  },
+  "homepage": "https://github.com/JimJafar/the-librarian/tree/main/integrations/pi",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/JimJafar/the-librarian",
+    "directory": "integrations/pi"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "memory",
+    "handoff",
+    "mcp",
+    "librarian",
+    "recall",
+    "cross-harness"
+  ],
+  "pi": {
+    "extensions": [
+      "extensions/librarian/index.ts"
+    ]
+  },
+  "files": [
+    "extensions",
+    "README.md"
+  ],
+  "scripts": {
+    "test:vitest": "vitest run",
+    "test": "pnpm run test:vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.75.5",
+    "@librarian/mcp-server": "workspace:*",
+    "@types/node": "^22.10.5",
+    "typebox": "^1.1.38",
+    "typescript": "catalog:",
+    "vitest": "catalog:"
+  }
+}