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

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -19,6 +19,17 @@ 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`.
+- **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
+  curator to mine for durable memories. Default-on; opt out with
+  `LIBRARIAN_AUTO_SAVE=false`. Forward-only private mode is honoured (a
+  `[librarian:private=on]` turn and every turn until `[librarian:private=off]`
+  is never shipped, and never retroactively sent), the conversation is keyed by
+  Pi's own session id (`getSessionId()` — concurrent sessions never collide,
+  never `$USER`/cwd), the seq advances only on a server 2xx ack, the bearer
+  token travels in the header only (`redirect:"error"`), and it is fully
+  fail-soft — a Librarian outage never blocks a turn or leaks a stack trace.
 - **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).
@@ -28,6 +39,20 @@ Librarian primer into the system prompt. One install, zero config files.
 
 ## Install
 
+### The easy way — the Librarian CLI (recommended)
+
+```sh
+npx @the-librarian/cli install      # choose Pi; paste your MCP URL + token
+npx @the-librarian/cli update       # later: pull the latest extension
+```
+
+`install` runs Pi's native `pi install` for you and persists your server URL +
+token. Run it with `npx`, or `npm i -g @the-librarian/cli` once and call
+`librarian install` / `librarian update` directly. Prefer to wire it by hand?
+See below.
+
+### Manual setup
+
 From npm (once published — see "Publishing" below):
 
 ```sh
@@ -50,9 +75,11 @@ 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_MCP_URL` | The server's MCP endpoint, e.g. `https://your-librarian/mcp` (auto-capture posts to `/transcript` on the same origin) |
 | `LIBRARIAN_AGENT_TOKEN` | A per-agent bearer token issued by your Librarian |
-| `LIBRARIAN_TIMEOUT_MS` | *(optional)* per-call timeout, default `15000` |
+| `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_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
 network calls — only the four slash commands register, and they explain what's

package/extensions/librarian/capture-state.ts

@@ -0,0 +1,125 @@
+// Per-session auto-capture state — the adapter's only durable capture state.
+// Phase 2B / T-Pi. Records, PER SESSION (keyed by Pi's getSessionId()):
+//   - `seq`     : the adapter's monotonic delta counter for the /transcript
+//                 contract payload.
+//   - `private` : whether the previous delta ended inside an open `[private=on]`
+//                 span (carry-forward, so an unterminated span stays private into
+//                 the next delta — even across a process restart within a session).
+//
+// There is NO byte offset (unlike the Claude cursor): the `agent_end` hook hands
+// the adapter the completed turn IN-PAYLOAD, so there is nothing to re-read. The
+// state is NON-CRITICAL: if lost, the next delta restarts at seq 0 / public and
+// idempotency rests on the server/curator's fact-level dedup + advance-on-ack. So
+// every read is fail-soft (a missing/corrupt file reads as a fresh start).
+//
+// Concurrency (spec §4.11 / SC5): keyed by the SESSION ID ONLY (never `$USER`/
+// cwd), so N concurrent same-machine sessions get N distinct files. Pruning is
+// AGE-BASED — never "clear all" (that would clobber a live sibling session).
+//
+// RUNTIME-IMPORT NOTE: only `node:` builtins + relative paths here, so the module
+// loads in a git/local Pi install with no node_modules (tests/runtime-imports).
+
+import fs from "node:fs";
+import path from "node:path";
+
+/** A session's durable capture state. */
+export interface CaptureState {
+  seq: number;
+  private: boolean;
+}
+
+/** The capture-state directory under the plugin data dir. */
+export function captureDir(dataDir: string): string {
+  return path.join(dataDir, "capture");
+}
+
+/**
+ * Reduce a session id to a single safe path segment so a hostile/odd id can't
+ * traverse out of `capture/`. Mirrors the server's `sanitizeConvId`, the Claude
+ * cursor's `safeSegment`, and the Hermes `_safe_segment`.
+ */
+function safeSegment(sessionId: string): string {
+  const cleaned = String(sessionId ?? "")
+    .replace(/[^a-zA-Z0-9._-]/g, "_")
+    .replace(/\.\.+/g, "_") // collapse any `..` run — never a parent-dir reference
+    .replace(/^\.+/, "_") // never a leading dot (no `.` / dotfiles)
+    .slice(0, 200);
+  return cleaned || "unknown";
+}
+
+/** Absolute path of a session's capture-state file. */
+export function captureStatePath(dataDir: string, sessionId: string): string {
+  return path.join(captureDir(dataDir), `${safeSegment(sessionId)}.json`);
+}
+
+/**
+ * Read a session's capture state. Fail-soft: a missing or unparseable file reads
+ * as a fresh start (`{seq:0, private:false}`) — re-shipping is safe (the
+ * server/curator dedup), so this never throws.
+ */
+export function readCaptureState(dataDir: string, sessionId: string): CaptureState {
+  const fresh: CaptureState = { seq: 0, private: false };
+  try {
+    const raw = fs.readFileSync(captureStatePath(dataDir, sessionId), "utf8");
+    const parsed: unknown = JSON.parse(raw);
+    if (typeof parsed !== "object" || parsed === null) return fresh;
+    const obj = parsed as { seq?: unknown; private?: unknown };
+    return {
+      seq: Number.isInteger(obj.seq) && (obj.seq as number) >= 0 ? (obj.seq as number) : 0,
+      private: obj.private === true,
+    };
+  } catch {
+    return fresh;
+  }
+}
+
+/**
+ * Persist a session's capture state. Written atomically (tmp + rename) so a crash
+ * mid-write can never leave a torn file a concurrent run misreads. Fail-soft: a
+ * write failure is swallowed (the caller already shipped; a lost state file only
+ * costs an idempotent re-ship next delta).
+ */
+export function writeCaptureState(dataDir: string, sessionId: string, state: CaptureState): void {
+  try {
+    const dir = captureDir(dataDir);
+    fs.mkdirSync(dir, { recursive: true });
+    const target = captureStatePath(dataDir, sessionId);
+    const tmp = `${target}.tmp-${process.pid}`;
+    fs.writeFileSync(
+      tmp,
+      JSON.stringify({ seq: state.seq, private: Boolean(state.private) }),
+      "utf8",
+    );
+    fs.renameSync(tmp, target);
+  } catch {
+    // Non-critical state; a lost file self-heals via re-ship + dedup.
+  }
+}
+
+/**
+ * Age-based pruning (SC5-adjacent housekeeping): drop state files whose mtime is
+ * older than `maxAgeMs`. NEVER "clear all" — a fresh sibling file (a concurrently
+ * running session) must survive. Fail-soft: a missing dir or an un-stat-able file
+ * is skipped, never thrown.
+ */
+export function pruneOldState(dataDir: string, maxAgeMs = 7 * 24 * 60 * 60 * 1000): void {
+  const dir = captureDir(dataDir);
+  let names: string[];
+  try {
+    names = fs.readdirSync(dir);
+  } catch {
+    return; // no capture dir yet — nothing to prune
+  }
+  const cutoff = Date.now() - maxAgeMs;
+  for (const name of names) {
+    const file = path.join(dir, name);
+    try {
+      const stat = fs.statSync(file);
+      if (stat.isFile() && stat.mtimeMs < cutoff) {
+        fs.rmSync(file, { force: true });
+      }
+    } catch {
+      // Race with a concurrent session writing/rotating — skip it.
+    }
+  }
+}

package/extensions/librarian/capture.ts

@@ -0,0 +1,237 @@
+// Pi auto-capture adapter — the orchestrator + the `agent_end` hook wiring.
+// Spec 2026-06-16-harness-auto-capture, Phase 2B (Pi / T-Pi).
+//
+// Wires the pure transforms (transcript-capture.ts), the durable per-session
+// state (capture-state.ts), and the network ship (transcript-post.ts) into the
+// one decision the per-turn-end handler makes: ship this completed turn's
+// NON-PRIVATE prose to POST /transcript and advance seq ONLY on a server 2xx ack.
+// Everything is fail-soft (AGENTS.md: a Librarian/network/parse failure must
+// never throw out of a harness hook, never block the user's turn, never leak a
+// stack trace) — every path resolves; an error logs to the injected logger and
+// seq stays put so the delta re-ships next turn (idempotent; server/curator dedup).
+//
+// ─── The Pi event/session API: CONFIRMED vs ASSUMED ───────────────────────────
+// Confirmed against the pinned @earendil-works/pi-coding-agent@0.75.5 SDK types
+// (node_modules/.../dist/core/extensions/types.d.ts) and the bundled
+// docs/extensions.md, plus the build-pi-extension skill:
+//   - CONFIRMED `pi.on("agent_end", handler)` exists; AgentEndEvent =
+//     `{ type:"agent_end", messages: AgentMessage[] }`, fired ONCE per user
+//     prompt with the completed turn's messages IN-PAYLOAD. This is the §11.2
+//     "per-turn-end event handing the completed turn in-payload" — so the delta
+//     is O(1) (no cursor, no transcript re-read).
+//   - CONFIRMED `ctx.sessionManager.getSessionId(): string` is the stable session
+//     id. The spec's "conv_id = Pi's getSessionId()" maps to THIS. conv_id is the
+//     session id ONLY — NEVER $USER/cwd (concurrent same-machine sessions must
+//     not collide, spec §4.11 / SC5). No stable id → fail soft to a no-op.
+//   - ASSUMED (OPTIMISTIC — there is no `pi` CLI on this machine, so SC1 e2e is
+//     DEFERRED): that `agent_end` (the whole-prompt boundary) is the right hook
+//     vs `turn_end` (which fires per LLM-response loop within one prompt and
+//     carries a single `message`, not the full exchange). We pick `agent_end` per
+//     the §11.2 expectation and make a wrong shape fail SAFE: messagesToTurns
+//     skips any unexpected message/block shape → a wrong event or payload is a
+//     clean no-op, never a throw or garbage capture. The hook also guards its
+//     whole body so a thrown getSessionId()/handler error can never escape.
+//
+// The network `post` + the dataDir are INJECTED so the orchestration is
+// unit-testable without a running Pi or a socket; registerCaptureHook passes the
+// real postDelta + the resolved data dir.
+
+import path from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { pruneOldState, readCaptureState, writeCaptureState } from "./capture-state.js";
+import { buildPayload, filterPrivateSpans, messagesToTurns } from "./transcript-capture.js";
+import { type CaptureAck, deriveTranscriptUrl, postDelta } from "./transcript-post.js";
+
+// Age-based pruning of stale per-session capture state (~7 days), opportunistic
+// and fail-soft — NEVER clear-all (a fresh sibling is a live concurrent session).
+const PRUNE_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+
+/** A fail-soft logger; capture never logs turn text or the token. */
+export type CaptureLogger = (message: string) => void;
+
+/** The injected dependencies the orchestration needs (testable). */
+export interface CaptureDeps {
+  /** Plugin data dir (per-session state home). */
+  dataDir: string;
+  /** Injectable network ship (tests pass a fake; the hook passes postDelta). */
+  post?: typeof postDelta;
+  /** Fail-soft logger (defaults to a no-op). */
+  log?: CaptureLogger;
+}
+
+/** The fire context the handler hands the orchestrator. */
+export interface CaptureInput {
+  /** Pi's getSessionId() — the conv_id. Empty/missing → a clean no-op. */
+  convId: string;
+  /** The completed turn's AgentMessage[] (agent_end's in-payload turn). */
+  messages: unknown[];
+  /** Process env: the URL + token + the LIBRARIAN_AUTO_SAVE kill-switch. */
+  env: Record<string, string | undefined>;
+  /** Explicit-end hint (the session is ending) — the settle-sweep accelerator. */
+  ended?: boolean;
+}
+
+/** The orchestration outcome (mostly for tests / diagnostics). */
+export interface CaptureResult {
+  posted: boolean;
+  skipped?: string;
+  ack?: CaptureAck;
+}
+
+/**
+ * Is the local auto-save kill-switch OFF? True ONLY for the exact string "false"
+ * (case-insensitive); anything else (unset, "", "true", …) is default-ON
+ * (slash-commands.md "two gates"). Pure + total.
+ */
+export function isAutoSaveOff(env: Record<string, string | undefined>): boolean {
+  const v = env?.LIBRARIAN_AUTO_SAVE;
+  return typeof v === "string" && v.trim().toLowerCase() === "false";
+}
+
+/**
+ * Resolve the plugin data dir (per-session state home). Default:
+ * `${LIBRARIAN_PI_DATA:-$HOME/.librarian/pi-extension-data}` — mirrors the
+ * Claude adapter's `CLAUDE_PLUGIN_DATA → $HOME/.librarian/claude-plugin-data`.
+ */
+export function resolveDataDir(env: Record<string, string | undefined>): string {
+  const explicit = env.LIBRARIAN_PI_DATA;
+  if (explicit && explicit.trim()) return explicit;
+  const home = env.HOME || env.USERPROFILE || ".";
+  return path.join(home, ".librarian", "pi-extension-data");
+}
+
+/**
+ * Run one capture pass for a completed turn (`agent_end`). Ships the new
+ * NON-PRIVATE prose and advances seq ONLY on a 2xx ack. Never throws — every
+ * failure path resolves to a clean no-op and (best-effort) logs.
+ */
+export async function runCapture(input: CaptureInput, deps: CaptureDeps): Promise<CaptureResult> {
+  const post = deps.post ?? postDelta;
+  const log: CaptureLogger = typeof deps.log === "function" ? deps.log : () => {};
+  const dataDir = deps.dataDir;
+  const env = input.env ?? {};
+
+  // KILL-SWITCH (slash-commands.md, SC4): LIBRARIAN_AUTO_SAVE=false ships nothing
+  // and advances nothing on this machine. Hard gate, checked before any work.
+  if (isAutoSaveOff(env)) {
+    return { posted: false, skipped: "auto-save-off" };
+  }
+
+  try {
+    // conv_id keys the per-session state + the server buffer; a missing id is a
+    // clean no-op (NEVER cwd/$USER, so concurrent sessions never collide).
+    const convId = input.convId;
+    if (!convId) {
+      log("skip: no stable conv_id (getSessionId() empty)");
+      return { posted: false, skipped: "no-conv-id" };
+    }
+
+    // CONFIG (fail-soft): without a URL + token there is nowhere to ship — a clean
+    // no-op, state untouched, re-ships once configured.
+    const url = deriveTranscriptUrl(env.LIBRARIAN_MCP_URL);
+    const token = env.LIBRARIAN_AGENT_TOKEN;
+    if (!url || !token) {
+      log("skip: LIBRARIAN_MCP_URL / LIBRARIAN_AGENT_TOKEN not set");
+      return { posted: false, skipped: "not-configured" };
+    }
+
+    // Build this turn's prose turns and apply the forward-only private-span filter,
+    // carrying the open-span state forward across turns. A garbage payload yields
+    // [] (messagesToTurns is fail-soft) → a clean no-op below.
+    const prior = readCaptureState(dataDir, convId);
+    const allTurns = messagesToTurns(input.messages);
+    const { kept, endPrivate } = filterPrivateSpans(allTurns, { startPrivate: prior.private });
+
+    const ended = input.ended === true;
+
+    // Nothing public to ship. If the conversation ended we still send an
+    // ended-only delta (a private-only / empty tail shouldn't strand the server
+    // buffer). Otherwise persist any changed private state (so the next turn stays
+    // private) and no-op — a private turn is now behind us, NEVER retroactively shipped.
+    if (kept.length === 0 && !ended) {
+      if (endPrivate !== prior.private) {
+        writeCaptureState(dataDir, convId, { seq: prior.seq, private: endPrivate });
+      }
+      return { posted: false, skipped: "no-new-turns" };
+    }
+
+    const seq = prior.seq + 1;
+    const payload = buildPayload({ convId, seq, turns: kept, ended });
+
+    // 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 →
+    // advance seq + persist the carried private state.
+    let ack: CaptureAck;
+    try {
+      ack = await post(url, payload, token);
+    } catch (error) {
+      // Transient/infra: log + hold seq. Never leak the token (postDelta guarantees
+      // it stays in the header) or a stack trace into the model's context.
+      log(`ship failed (transient, will retry): ${errMsg(error)}`);
+      return { posted: false, skipped: "post-failed" };
+    }
+
+    if (!ack || !ack.ok) {
+      log(`ship not acked (status ${ack ? ack.status : "?"}); seq held, will retry`);
+      return { posted: false, skipped: "not-acked", ack };
+    }
+
+    writeCaptureState(dataDir, convId, { seq, private: endPrivate });
+    return { posted: true, ack };
+  } catch (error) {
+    // Last-resort fail-soft: any unexpected error logs + exits a no-op. State is
+    // untouched on this path (no write reached), so the delta re-ships next turn.
+    log(`unexpected error (no-op, fail-soft): ${errMsg(error)}`);
+    return { posted: false, skipped: "error" };
+  }
+}
+
+function errMsg(error: unknown): string {
+  return error instanceof Error ? error.message : "unknown error";
+}
+
+/**
+ * Read Pi's stable session id from the handler ctx, fail-soft. The spec's
+ * "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 {
+  try {
+    const sm = (ctx as { sessionManager?: { getSessionId?: () => unknown } })?.sessionManager;
+    const id = sm?.getSessionId?.();
+    return typeof id === "string" ? id : "";
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * 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
+ * whole body is guarded so a Librarian/network/parse failure can NEVER throw out
+ * of the handler or block the turn (AGENTS.md fail-soft). conv_id is the stable
+ * getSessionId(); the delta re-ships next turn on any non-2xx.
+ *
+ * @param dataDir - the resolved plugin data dir (per-session state home).
+ */
+export function registerCaptureHook(pi: ExtensionAPI, dataDir: string): void {
+  // Opportunistic, fail-soft pruning of stale sibling state (never clear-all).
+  try {
+    pruneOldState(dataDir, PRUNE_MAX_AGE_MS);
+  } catch {
+    // pruning is best-effort; a failure must not break extension load.
+  }
+
+  pi.on("agent_end", async (event, ctx) => {
+    try {
+      const convId = readSessionId(ctx);
+      const messages = Array.isArray((event as { messages?: unknown }).messages)
+        ? (event as { messages: unknown[] }).messages
+        : [];
+      await runCapture({ convId, messages, env: process.env }, { 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

@@ -17,6 +17,7 @@
 // privacy hook here.
 
 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 { createMcpClient } from "./mcp-client.js";
@@ -59,6 +60,16 @@ export default function librarian(pi: ExtensionAPI): void {
   // Primer → system prompt, once per turn, cached per process, fail-soft.
   registerPrimerHook(pi, createPrimerSource({ endpoint: config.endpoint }));
 
+  // 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
+  // kill-switch + forward-only private mode are enforced at fire time inside the
+  // handler (so a mid-session env change takes effect without a re-install), and
+  // 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));
+
   // The four user-facing slash commands (optional sugar, D9).
   registerCommands(pi);
 }

package/extensions/librarian/tools.ts

@@ -63,7 +63,6 @@ export function librarianToolSpecs(): LibrarianToolSpec[] {
       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()),
       }),
@@ -75,15 +74,13 @@ export function librarianToolSpecs(): LibrarianToolSpec[] {
         "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 " +
+        "Give it a short `title` and a self-contained `body`; add `tags` 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())),
       }),

package/extensions/librarian/transcript-capture.ts

@@ -0,0 +1,204 @@
+// Auto-capture pure transforms (no IO, no network) — Phase 2B / T-Pi.
+//
+// The Pi `agent_end` hook hands the adapter the completed turn's messages
+// IN-PAYLOAD (`event.messages: AgentMessage[]`) plus a stable session id from
+// `ctx.sessionManager.getSessionId()`. That is the §11.2 expectation: the delta
+// is built O(1) from the in-payload turn — there is NO cursor and NO transcript
+// re-read (unlike the Claude `Stop` adapter, which byte-slices a JSONL file).
+//
+// CONFIRMED vs ASSUMED (build-pi-extension + the pinned SDK @0.75.5 types in
+// node_modules/@earendil-works/pi-coding-agent/dist/core/extensions/types.d.ts):
+//   - CONFIRMED: `agent_end` fires once per user prompt with `messages:
+//     AgentMessage[]` (the completed turn in-payload). `AgentMessage = Message |
+//     custom`; `Message` (from @earendil-works/pi-ai) is UserMessage /
+//     AssistantMessage / ToolResultMessage. UserMessage.content is `string |
+//     (TextContent|ImageContent)[]`; AssistantMessage.content is
+//     `(TextContent|ThinkingContent|ToolCall)[]`; every message carries a numeric
+//     epoch-ms `timestamp`. We capture PROSE ONLY (text blocks), mirroring the
+//     Claude adapter — dropping thinking, toolCall, images, and toolResult.
+//   - ASSUMED (optimistic, no live `pi` to confirm e2e): that `agent_end` is the
+//     right per-turn-end boundary to capture a whole exchange (vs `turn_end`,
+//     which fires per LLM-response loop within one prompt and carries only one
+//     `message`). The extraction here is structurally defensive: any unexpected
+//     shape (a custom message, a non-text block, a missing field) yields a clean
+//     skip, NEVER a throw or garbage capture — so a wrong assumption fails SAFE.
+//
+// This module owns the three pure transforms the hook drives; the orchestrator
+// (capture.ts) wires the session state, the network ship, and the env gates
+// around them. Everything here is trivially unit-testable and fail-soft.
+//
+// RUNTIME-IMPORT NOTE: a git/local-installed Pi package is not `npm install`ed,
+// so `extensions/` may only value-import `typebox`, `node:` builtins, or relative
+// paths (tests/runtime-imports.test.ts pins this). The Pi/AI types below are
+// `import type` (erased at runtime); the rest is plain TS over globals.
+
+// The private-mode markers (AGENTS.md: never bypass private mode). Same literals
+// the harness toggles in-conversation and the server backstops on intake.
+export const PRIVATE_ON = "[librarian:private=on]";
+export const PRIVATE_OFF = "[librarian:private=off]";
+
+export const HARNESS = "pi" as const;
+
+/** A single already-non-private turn — the /transcript contract turn shape. */
+export interface CaptureTurn {
+  role: "user" | "assistant";
+  text: string;
+  ts?: string;
+}
+
+/** The uniform, harness-agnostic delta payload the server contract expects. */
+export interface CapturePayload {
+  conv_id: string;
+  harness: typeof HARNESS;
+  seq: number;
+  turns: CaptureTurn[];
+  ended?: true;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+/**
+ * Flatten an assistant content array to its prose, dropping `thinking`,
+ * `toolCall`, and any non-text block. Thinking is private reasoning and toolCall
+ * is machine plumbing — neither is durable conversational fact. A plain string
+ * (defensive: some message shapes carry a string) is returned as-is.
+ */
+function assistantText(content: unknown): string {
+  if (typeof content === "string") return content.trim();
+  if (!Array.isArray(content)) return "";
+  return content
+    .filter(
+      (b): b is { type: "text"; text: string } =>
+        isRecord(b) && b.type === "text" && typeof b.text === "string",
+    )
+    .map((b) => b.text)
+    .join("\n")
+    .trim();
+}
+
+/**
+ * Extract real user prose. A string is the prompt. An array is content blocks —
+ * we keep only `text` blocks (an `image` block is not prose, and a `toolResult`
+ * never appears as a user message here).
+ */
+function userText(content: unknown): string {
+  if (typeof content === "string") return content.trim();
+  if (!Array.isArray(content)) return "";
+  return content
+    .filter(
+      (b): b is { type: "text"; text: string } =>
+        isRecord(b) && b.type === "text" && typeof b.text === "string",
+    )
+    .map((b) => b.text)
+    .join("\n")
+    .trim();
+}
+
+/**
+ * Convert a numeric epoch-ms `timestamp` to an ISO-8601 string for the contract
+ * `ts` field (which is an optional string). Returns undefined for anything that
+ * is not a finite number (so a missing/garbage stamp simply omits `ts`).
+ */
+function toIsoTs(timestamp: unknown): string | undefined {
+  if (typeof timestamp !== "number" || !Number.isFinite(timestamp)) return undefined;
+  try {
+    return new Date(timestamp).toISOString();
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Map the `agent_end` payload's AgentMessage[] to ordered user/assistant turns.
+ * Forward-only and fail-soft: a non-array input, a null/garbage entry, a
+ * toolResult message, a custom (roleless) message, or a turn that is empty after
+ * prose extraction is silently skipped rather than thrown. We accept `unknown[]`
+ * so a wrong-shape payload (the optimistic assumption being off) is a clean
+ * no-op, never garbage capture.
+ *
+ * @param messages - `event.messages` from the `agent_end` hook (the completed turn).
+ */
+export function messagesToTurns(messages: unknown[]): CaptureTurn[] {
+  if (!Array.isArray(messages)) return [];
+  const turns: CaptureTurn[] = [];
+  for (const m of messages) {
+    if (!isRecord(m)) continue;
+    const role = m.role;
+    // Only top-level conversational messages. `toolResult` is plumbing; a custom
+    // AgentMessage has no LLM role at all — both skipped.
+    if (role !== "user" && role !== "assistant") continue;
+
+    const text = role === "user" ? userText(m.content) : assistantText(m.content);
+    if (!text) continue;
+
+    const turn: CaptureTurn = { role, text };
+    const ts = toIsoTs(m.timestamp);
+    if (ts) turn.ts = ts;
+    turns.push(turn);
+  }
+  return turns;
+}
+
+/**
+ * Per-turn private-span filter (mirrors the Claude/Hermes adapters). Tracks the
+ * `[private=on]/[private=off]` marker state across the turns in this delta AND
+ * across deltas via `startPrivate` (whether the previous delta left an open
+ * span). Any turn while the span is open is SKIPPED; the marker-toggle turns
+ * themselves are skipped too (they carry no durable fact). Forward-only: the
+ * orchestrator advances past skipped turns so a private turn is NEVER
+ * retroactively shipped.
+ *
+ * Within a single turn's text the LAST-occurring marker wins, so a turn that
+ * re-opens privacy stays private into the next turn.
+ *
+ * @returns the non-private turns + the span state to carry into the next delta.
+ */
+export function filterPrivateSpans(
+  turns: CaptureTurn[],
+  { startPrivate }: { startPrivate: boolean },
+): { kept: CaptureTurn[]; endPrivate: boolean } {
+  let priv = Boolean(startPrivate);
+  const kept: CaptureTurn[] = [];
+  for (const turn of turns) {
+    const text = turn.text;
+    const hasOn = text.includes(PRIVATE_ON);
+    const hasOff = text.includes(PRIVATE_OFF);
+    const isMarkerTurn = hasOn || hasOff;
+
+    // Resolve the new state from this turn's last-occurring marker.
+    if (isMarkerTurn) {
+      const onAt = hasOn ? text.lastIndexOf(PRIVATE_ON) : -1;
+      const offAt = hasOff ? text.lastIndexOf(PRIVATE_OFF) : -1;
+      priv = onAt > offAt;
+    }
+
+    // Skip if we're (or just entered) a private span, OR this is itself a
+    // boundary marker turn (it may carry private text alongside the marker).
+    if (priv || isMarkerTurn) continue;
+    kept.push(turn);
+  }
+  return { kept, endPrivate: priv };
+}
+
+/**
+ * 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).
+ */
+export function buildPayload({
+  convId,
+  seq,
+  turns,
+  ended = false,
+}: {
+  convId: string;
+  seq: number;
+  turns: CaptureTurn[];
+  ended?: boolean;
+}): CapturePayload {
+  const payload: CapturePayload = { conv_id: convId, harness: HARNESS, seq, turns };
+  if (ended) payload.ended = true;
+  return payload;
+}

package/extensions/librarian/transcript-post.ts

@@ -0,0 +1,88 @@
+// Auto-capture POST-URL derivation + the network ship (Phase 2B / T-Pi).
+//
+// The endpoint is derived from the SAME public listener the MCP config already
+// points at: `LIBRARIAN_MCP_URL` is `<origin>/mcp`, the transcript intake is
+// `<origin>/transcript`. We rewrite the path on the same origin so a deployment
+// configures one URL, not two (and a hostile redirect can't move it cross-origin
+// — `redirect:"error"` below).
+//
+// Auth is `Authorization: Bearer ${LIBRARIAN_AGENT_TOKEN}` — in the HEADER only,
+// never the URL or a log (AGENTS.md: privacy is the product, tokens never leak).
+// Mirrors the Claude adapter's post.mjs and the Pi mcp-client's security posture.
+//
+// RUNTIME-IMPORT NOTE: uses only the global `fetch` / `URL` / `AbortController`
+// (no imports at all), so it loads in a git/local Pi install with no node_modules.
+
+const SHIP_TIMEOUT_MS = 10_000;
+
+/** The small ack the orchestrator folds into its advance-on-2xx decision. */
+export interface CaptureAck {
+  ok: boolean;
+  status: number;
+  buffered?: number;
+}
+
+/**
+ * Derive the transcript-intake URL from `LIBRARIAN_MCP_URL`. Rewrites the path to
+ * `/transcript` on the same origin, dropping any `/mcp` suffix, query, or hash.
+ * Returns `null` for an unusable / non-http(s) URL so the caller can fail-soft
+ * (skip, no throw).
+ */
+export function deriveTranscriptUrl(mcpUrl: string | undefined): string | null {
+  if (!mcpUrl || typeof mcpUrl !== "string") return null;
+  let parsed: URL;
+  try {
+    parsed = new URL(mcpUrl);
+  } catch {
+    return null;
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return null;
+  return `${parsed.origin}/transcript`;
+}
+
+/**
+ * POST a delta payload to the transcript endpoint. Returns a small ack —
+ * `{ ok, status, buffered? }` — never throws on an HTTP error status (a non-2xx
+ * is `ok:false`, which the caller treats as "do not advance seq"). A
+ * network/transport failure (DNS, ECONNREFUSED, timeout, a refused redirect) DOES
+ * reject so the orchestrator's try/catch logs it and skips — both are "do not
+ * advance".
+ *
+ * `redirect:"error"` (AGENTS.md): a 3xx must never bounce the Bearer token to a
+ * different origin. A 10s timeout bounds a hung server so the hook can't hang.
+ */
+export async function postDelta(url: string, payload: unknown, token: string): Promise<CaptureAck> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), SHIP_TIMEOUT_MS);
+  try {
+    const response = await fetch(url, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        // The token lives ONLY here — never in the URL or any logged string.
+        authorization: `Bearer ${token}`,
+      },
+      body: JSON.stringify(payload),
+      redirect: "error",
+      signal: controller.signal,
+    });
+    let buffered: number | undefined;
+    try {
+      const json: unknown = await response.json();
+      if (
+        json &&
+        typeof json === "object" &&
+        typeof (json as { buffered?: unknown }).buffered === "number"
+      ) {
+        buffered = (json as { buffered: number }).buffered;
+      }
+    } catch {
+      // Non-JSON / empty body — the status alone decides ok/not-ok.
+    }
+    const ack: CaptureAck = { ok: response.ok, status: response.status };
+    if (buffered !== undefined) ack.buffered = buffered;
+    return ack;
+  } finally {
+    clearTimeout(timer);
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@the-librarian/pi-extension",
-  "version": "1.0.0-rc.2",
+  "version": "1.4.0",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -15,7 +15,7 @@
   "homepage": "https://github.com/JimJafar/the-librarian/tree/main/integrations/pi",
   "repository": {
     "type": "git",
-    "url": "https://github.com/JimJafar/the-librarian",
+    "url": "git+https://github.com/JimJafar/the-librarian.git",
     "directory": "integrations/pi"
   },
   "keywords": [
@@ -37,21 +37,21 @@
     "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:"
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8",
+    "@librarian/mcp-server": "0.0.0"
+  },
+  "scripts": {
+    "test:vitest": "vitest run",
+    "test": "pnpm run test:vitest",
+    "typecheck": "tsc --noEmit"
   }
-}
+}