@the-librarian/pi-extension 1.37.0 → 1.38.0

package/README.md

@@ -22,6 +22,12 @@ Librarian primer into the system prompt. One install, zero config files.
 - **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`.
+- **The journal at session start** — the recent window of the
+  [journal](https://librarian-docs.codeministry.net/guides/journal/)
+  (`GET <server>/journal.md?max_chars=9500`) follows the primer in the system
+  prompt, fetched once per Pi session and then reused so the prompt stays the same
+  every turn. Captured turns are labelled with their project (the git repository
+  name, else the folder name) once `/healthz` shows the server accepts it.
 - **Automatic per-turn capture** — after every completed turn Pi fires
   `agent_end` with the turn's messages in-payload, and the adapter ships the
   non-private prose as a delta to the server's `POST /transcript` door for the
@@ -84,6 +90,7 @@ Set two environment variables in the shell that launches `pi`:
 | `LIBRARIAN_AGENT_TOKEN` | A per-agent bearer token issued by your Librarian |
 | `LIBRARIAN_TIMEOUT_MS` | *(optional)* per-call timeout for the tool proxies, default `15000` |
 | `LIBRARIAN_AUTO_SAVE` | *(optional)* set to `false` to disable automatic capture on this machine (default-on). Anything else (unset, `true`, …) leaves capture on. |
+| `LIBRARIAN_JOURNAL` | *(optional)* set to `off` (or `false` / `0` / `no`) to stop loading the journal at session start on this machine. The `journal` tool stays available. |
 | `LIBRARIAN_PI_DATA` | *(optional)* where the per-session capture state lives, default `$HOME/.librarian/pi-extension-data` |
 
 Without both required variables the extension stays **dormant**: no tools, no

package/extensions/librarian/capture.ts

@@ -69,6 +69,8 @@ export interface CaptureInput {
   env: Record<string, string | undefined>;
   /** Explicit-end hint (the session is ending) — the settle-sweep accelerator. */
   ended?: boolean;
+  /** Spec 078: the journal's project label, or null when the server can't take it. */
+  project?: string | null;
 }
 
 /** The orchestration outcome (mostly for tests / diagnostics). */
@@ -156,7 +158,13 @@ export async function runCapture(input: CaptureInput, deps: CaptureDeps): Promis
     }
 
     const seq = prior.seq + 1;
-    const payload = buildPayload({ convId, seq, turns: kept, ended });
+    const payload = buildPayload({
+      convId,
+      seq,
+      turns: kept,
+      ended,
+      project: input.project ?? null,
+    });
 
     // SHIP. A non-2xx (`ok:false`) or a thrown network error → DO NOT advance seq:
     // the delta re-ships next turn (idempotent; server/curator dedup). A 2xx →
@@ -195,7 +203,7 @@ function errMsg(error: unknown): string {
  * "conv_id = getSessionId()" maps to `ctx.sessionManager.getSessionId()`. Any
  * throw / non-string → "" so the orchestrator no-ops (NEVER cwd/$USER).
  */
-function readSessionId(ctx: unknown): string {
+export function readSessionId(ctx: unknown): string {
   try {
     const sm = (ctx as { sessionManager?: { getSessionId?: () => unknown } })?.sessionManager;
     const id = sm?.getSessionId?.();
@@ -205,6 +213,16 @@ function readSessionId(ctx: unknown): string {
   }
 }
 
+/** The session's working directory from the handler ctx (`ctx.cwd`), fail-soft. */
+export function readCwd(ctx: unknown): string | undefined {
+  try {
+    const cwd = (ctx as { cwd?: unknown })?.cwd;
+    return typeof cwd === "string" ? cwd : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 /**
  * Wire auto-capture into Pi's `agent_end` event — fired ONCE per completed user
  * prompt with the turn's messages in-payload (the §11.2 per-turn-end hook). The
@@ -213,8 +231,13 @@ function readSessionId(ctx: unknown): string {
  * getSessionId(); the delta re-ships next turn on any non-2xx.
  *
  * @param dataDir - the resolved plugin data dir (per-session state home).
+ * @param projectFor - the journal's project label for a cwd, or null (spec 078).
  */
-export function registerCaptureHook(pi: ExtensionAPI, dataDir: string): void {
+export function registerCaptureHook(
+  pi: ExtensionAPI,
+  dataDir: string,
+  projectFor: (cwd: string | undefined) => Promise<string | null> = async () => null,
+): void {
   // Opportunistic, fail-soft pruning of stale sibling state (never clear-all).
   try {
     pruneOldState(dataDir, PRUNE_MAX_AGE_MS);
@@ -228,7 +251,8 @@ export function registerCaptureHook(pi: ExtensionAPI, dataDir: string): void {
       const messages = Array.isArray((event as { messages?: unknown }).messages)
         ? (event as { messages: unknown[] }).messages
         : [];
-      await runCapture({ convId, messages, env: process.env }, { dataDir });
+      const project = await projectFor(readCwd(ctx));
+      await runCapture({ convId, messages, env: process.env, project }, { dataDir });
     } catch {
       // Defensive net — runCapture already swallows its own errors, but a
       // top-level throw must never break the user's turn or leak a stack trace.

package/extensions/librarian/index.ts

@@ -9,6 +9,8 @@
 //     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`;
+//   - the recent window of the conversation journal, fetched once per session and
+//     appended after the primer (spec 078) — see `journal.ts`;
 //   - four user-facing slash commands (`/handoff`, `/takeover`, `/learn`,
 //     `/toggle-private`) as thin prompt templates — see `commands.ts`.
 //
@@ -20,6 +22,7 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { registerCaptureHook, resolveDataDir } from "./capture.js";
 import { registerCommands } from "./commands.js";
 import { readConfig } from "./config.js";
+import { createJournalSource, registerJournalHook } from "./journal.js";
 import { createMcpClient } from "./mcp-client.js";
 import { createPrimerSource, registerPrimerHook } from "./primer.js";
 import { registerLibrarianTools } from "./tools.js";
@@ -60,6 +63,13 @@ export default function librarian(pi: ExtensionAPI): void {
   // Primer → system prompt, once per turn, cached per process, fail-soft.
   registerPrimerHook(pi, createPrimerSource({ endpoint: config.endpoint }));
 
+  // Spec 078: the recent journal window → system prompt, after the primer; fetched
+  // once per Pi session, fail-soft, `LIBRARIAN_JOURNAL=off` skips it. The same source
+  // labels captured conversations with their project once /healthz shows the server
+  // accepts the field.
+  const journal = createJournalSource({ endpoint: config.endpoint, token: config.token });
+  registerJournalHook(pi, journal);
+
   // Auto-capture (Phase 2B, spec 2026-06-16-harness-auto-capture): wire the
   // `agent_end` hook so each completed turn's NON-PRIVATE prose ships as a
   // per-turn delta to POST /transcript. Default-on; the LIBRARIAN_AUTO_SAVE=false
@@ -68,7 +78,7 @@ export default function librarian(pi: ExtensionAPI): void {
   // it stays inert when the server's curator.intake.enabled gate is off. The hook
   // is registered only when the extension is configured (the dormant branch above
   // returns before reaching here, so an unconfigured install captures nothing).
-  registerCaptureHook(pi, resolveDataDir(process.env));
+  registerCaptureHook(pi, resolveDataDir(process.env), (cwd) => journal.projectFor(cwd));
 
   // The four user-facing slash commands (optional sugar, D9).
   registerCommands(pi);

package/extensions/librarian/journal.ts

@@ -0,0 +1,212 @@
+// Journal injection + project label (spec 078) — the Pi port of
+// integrations/claude/scripts/lib/journal.mjs.
+//
+//   - The recent window of the conversation journal (`GET /journal.md`) is appended
+//     to the system prompt via `before_agent_start`, after the primer. It is fetched
+//     ONCE per Pi session and then served from memory: the prompt stays
+//     byte-identical every turn (prompt caching stays warm) and the server is asked
+//     once. Keyed by session id, not process — one Pi process can outlive several
+//     sessions, and each new session gets a fresh window.
+//   - The project label for /transcript (git repo name, else folder name), offered
+//     only after a `/healthz` probe shows the server accepts it — an older server
+//     rejects the unknown key and capture would stall. Probed once per process.
+//
+// Same rules as the Claude adapter: `max_chars=9500` (every harness gets the
+// Claude-sized window), `LIBRARIAN_JOURNAL=off` skips the fetch, the token rides the
+// Authorization header only, redirects are refused, and every failure resolves to
+// "" / null — never a throw into Pi's turn.
+
+import fs from "node:fs";
+import path from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { readSessionId } from "./capture.js";
+
+/** The window size every harness asks for — Claude Code's, under its 10,000-char cap. */
+export const JOURNAL_MAX_CHARS = 9_500;
+
+const TRIMMED_NOTE =
+  "Older entries were left out to fit — call the `journal` tool to read further back.";
+
+const DEFAULT_TIMEOUT_MS = 5_000;
+const PROBE_TIMEOUT_MS = 2_000;
+/** Sessions remembered at once; the oldest is forgotten first. */
+const MAX_SESSIONS = 200;
+
+type FetchLike = typeof fetch;
+
+/** `<origin>/journal.md?max_chars=N`, or null when the endpoint is unusable. */
+export function journalUrl(endpoint: string, maxChars = JOURNAL_MAX_CHARS): string | null {
+  try {
+    const parsed = new URL(endpoint);
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return null;
+    return `${parsed.origin}/journal.md?max_chars=${maxChars}`;
+  } catch {
+    return null;
+  }
+}
+
+/** Is the journal injection switched off locally (`LIBRARIAN_JOURNAL=off|false|0|no`)? */
+export function isJournalInjectionOff(env: Record<string, string | undefined>): boolean {
+  const raw = env.LIBRARIAN_JOURNAL ?? "";
+  return ["off", "false", "0", "no"].includes(raw.trim().toLowerCase());
+}
+
+/**
+ * Keep the window under `limit` characters by dropping the OLDEST `## ` blocks (the
+ * window is oldest-first). A server that honours `max_chars` never needs this.
+ */
+export function fitJournal(text: string, limit = JOURNAL_MAX_CHARS): string {
+  if (text.length <= limit) return text;
+  const parts = text.split(/\n(?=## )/);
+  const header = parts.shift() ?? "";
+  const blocks = parts.filter((b) => !b.startsWith(TRIMMED_NOTE)).map((b) => b.trimEnd());
+  const render = (kept: string[]): string =>
+    `${header.trimEnd()}\n\n${kept.join("\n\n")}\n\n${TRIMMED_NOTE}\n`;
+  let start = 0;
+  while (start < blocks.length - 1 && render(blocks.slice(start)).length > limit) start += 1;
+  const out = render(blocks.slice(start));
+  return out.length <= limit ? out : out.slice(0, limit);
+}
+
+/**
+ * The project label: the name of the git repository containing `cwd` (the nearest
+ * ancestor holding a `.git` entry), else the name of `cwd`. Null when unusable.
+ */
+export function deriveProject(cwd: string | undefined): string | null {
+  if (!cwd || !path.isAbsolute(cwd)) return null;
+  try {
+    let dir = path.resolve(cwd);
+    let name: string | null = null;
+    for (;;) {
+      if (fs.existsSync(path.join(dir, ".git"))) {
+        name = path.basename(dir);
+        break;
+      }
+      const parent = path.dirname(dir);
+      if (parent === dir) break;
+      dir = parent;
+    }
+    const label = (name ?? path.basename(path.resolve(cwd))).trim().slice(0, 200);
+    return label || null;
+  } catch {
+    return null;
+  }
+}
+
+export interface JournalSourceConfig {
+  endpoint: string;
+  token: string;
+  env?: Record<string, string | undefined>;
+  fetchImpl?: FetchLike;
+  timeoutMs?: number;
+}
+
+export interface JournalSource {
+  /** The window for this session ("" when there is none), fetched once per session. */
+  windowFor(sessionId: string): Promise<string>;
+  /** The project label for `cwd`, or null when the server can't take it. */
+  projectFor(cwd: string | undefined): Promise<string | null>;
+}
+
+export function createJournalSource(config: JournalSourceConfig): JournalSource {
+  const env = config.env ?? process.env;
+  const fetchImpl = config.fetchImpl ?? fetch;
+  const timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const windows = new Map<string, Promise<string>>();
+  let supported: Promise<boolean> | null = null;
+
+  async function fetchWindow(): Promise<string> {
+    if (isJournalInjectionOff(env)) return "";
+    const url = journalUrl(config.endpoint);
+    if (!url) return "";
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+      const response = await fetchImpl(url, {
+        method: "GET",
+        headers: { authorization: `Bearer ${config.token}` },
+        redirect: "error",
+        signal: controller.signal,
+      });
+      if (!response.ok) return "";
+      if (!(response.headers.get("content-type") ?? "").includes("text/markdown")) return "";
+      const text = await response.text();
+      return text.trim() ? fitJournal(text) : "";
+    } catch {
+      return "";
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  async function probe(): Promise<boolean> {
+    let url: string;
+    try {
+      const parsed = new URL(config.endpoint);
+      if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return false;
+      url = `${parsed.origin}/healthz`;
+    } catch {
+      return false;
+    }
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), PROBE_TIMEOUT_MS);
+    try {
+      // /healthz is unauthenticated, so no token is sent.
+      const response = await fetchImpl(url, { redirect: "error", signal: controller.signal });
+      if (!response.ok) return false;
+      const json: unknown = await response.json();
+      return (
+        typeof json === "object" &&
+        json !== null &&
+        !Array.isArray(json) &&
+        Object.prototype.hasOwnProperty.call(json, "journal")
+      );
+    } catch {
+      return false;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  return {
+    async windowFor(sessionId) {
+      if (!sessionId) return "";
+      let pending = windows.get(sessionId);
+      if (!pending) {
+        pending = fetchWindow().catch(() => "");
+        windows.set(sessionId, pending);
+        if (windows.size > MAX_SESSIONS) {
+          const oldest = windows.keys().next().value;
+          if (oldest !== undefined) windows.delete(oldest);
+        }
+      }
+      return pending;
+    },
+    async projectFor(cwd) {
+      try {
+        supported ??= probe().catch(() => false);
+        return (await supported) ? deriveProject(cwd) : null;
+      } catch {
+        return null;
+      }
+    },
+  };
+}
+
+/**
+ * Append the session's journal window to Pi's system prompt. Registered AFTER the
+ * primer hook, so the SDK's chained `systemPrompt` returns put it after the primer.
+ * Empty window → no return value → Pi leaves the prompt untouched.
+ */
+export function registerJournalHook(pi: ExtensionAPI, source: JournalSource): void {
+  pi.on("before_agent_start", async (event, ctx) => {
+    try {
+      const window = await source.windowFor(readSessionId(ctx));
+      if (!window.trim()) return;
+      return { systemPrompt: `${event.systemPrompt}\n\n${window}` };
+    } catch {
+      // Defensive net — a top-level throw must never break the user's turn.
+      return;
+    }
+  });
+}

package/extensions/librarian/transcript-capture.ts

@@ -53,6 +53,8 @@ export interface CapturePayload {
   seq: number;
   turns: CaptureTurn[];
   ended?: true;
+  /** Spec 078: the journal's project label — sent only to a server that accepts it. */
+  project?: string;
 }
 
 function isRecord(value: unknown): value is Record<string, unknown> {
@@ -184,21 +186,25 @@ export function filterPrivateSpans(
 
 /**
  * Build the uniform, harness-agnostic delta the server contract expects:
- * `{ conv_id, harness:"pi", seq, turns[], ended? }`. `ended` is omitted unless
- * true (the server treats its mere presence as the explicit-end accelerator).
+ * `{ conv_id, harness:"pi", seq, turns[], ended?, project? }`. `ended` is omitted
+ * unless true (the server treats its mere presence as the explicit-end accelerator).
+ * `project` is set only by a caller that knows the server accepts it (spec 078).
  */
 export function buildPayload({
   convId,
   seq,
   turns,
   ended = false,
+  project = null,
 }: {
   convId: string;
   seq: number;
   turns: CaptureTurn[];
   ended?: boolean;
+  project?: string | null;
 }): CapturePayload {
   const payload: CapturePayload = { conv_id: convId, harness: HARNESS, seq, turns };
   if (ended) payload.ended = true;
+  if (project) payload.project = project;
   return payload;
 }

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@the-librarian/pi-extension",
-  "version": "1.37.0",
+  "version": "1.38.0",
   "private": false,
   "publishConfig": {
     "access": "public"
   },
-  "description": "Pi coding-agent package for The Librarian: the 8 memory/handoff/journal tools + primer injection, backed by a remote Librarian MCP server.",
+  "description": "Pi coding-agent package for The Librarian: the 8 memory/handoff/journal tools + primer and journal injection, backed by a remote Librarian MCP server.",
   "license": "Apache-2.0",
   "type": "module",
   "author": {