kimetsu-pi 0.1.2 → 0.1.3

package/README.md

@@ -24,7 +24,8 @@ Pi has no MCP layer, so this package brings Kimetsu to Pi through Pi's own
 extension points:
 
 - **Extension** (`extensions/kimetsu.ts`) — a TypeScript Pi extension that hooks
-  Pi lifecycle events (`session_start`, `agent_end`, `session_shutdown`) and shells
+  Pi lifecycle events (`session_start`, `before_agent_start`, `agent_end`,
+  `session_shutdown`) and shells
   out to the `kimetsu` binary to warm, load, and persist brain context around each
   session. Each call is capped by a timeout, so a slow or hung binary never stalls
   Pi. If the binary is not on `PATH`, every hook silently no-ops and Pi is
@@ -55,9 +56,15 @@ extension points:
 | **13×** | cheaper per solved task ($0.19 vs $2.47 on a Terminal-Bench slice) |
 | **~1M** | memories in ~3 GB RAM with sub-2s retrieval, one SQLite file |
 
-## Prerequisite
+## Prerequisites
 
-The `kimetsu` binary must be on `PATH`. Install it with:
+Install current Pi (Node.js 22.19 or newer):
+
+```sh
+npm install -g @earendil-works/pi-coding-agent
+```
+
+The `kimetsu` v2.7.0 or newer binary must be on `PATH`. Install it with:
 
 ```sh
 npm install -g kimetsu-ai
@@ -77,10 +84,16 @@ pi install npm:kimetsu-pi
 
 | Pi lifecycle event | Kimetsu command run |
 | --- | --- |
-| `session_start` | `kimetsu brain warm` then `kimetsu brain context-hook` |
+| `session_start` | `kimetsu brain warm` |
+| `before_agent_start` | `kimetsu brain context-hook --warm-on-first-prompt` |
 | `agent_end` | `kimetsu brain stop-hook` |
 | `session_shutdown` | `kimetsu brain session-end-hook` |
 
+The extension uses Pi's `SessionManager` identity, so `/new`, `/resume`, and
+`/fork` keep separate Kimetsu warm-start and deduplication state. It also passes
+Pi's persisted JSONL transcript to the stop and session-end hooks, enabling
+Kimetsu's configured distiller and automatic work-episode capture.
+
 ## Development
 
 ```sh

package/extensions/kimetsu.ts

@@ -1,57 +1,198 @@
 // Kimetsu brain extension for Pi (earendil-works/pi).
-// Published as the `kimetsu-pi` npm package. Shells out to the kimetsu binary
-// on Pi lifecycle events to load brain context at session start and record
-// audit markers on session end. If kimetsu is not on PATH the exec silently
-// fails; Pi startup is unaffected.
+//
+// CANONICAL SOURCE: kimetsu/crates/kimetsu-chat/assets/pi-extension.ts
+// `kimetsu plugin install pi` writes this file verbatim, and the published
+// `kimetsu-pi` npm package vendors a byte-identical copy (CI diffs the two).
+// Edit it here — never in the installed or published copy.
+//
+// Pi exposes no MCP surface, so Kimetsu integrates by shelling out to the
+// binary on lifecycle events. `before_agent_start` is the injection point:
+// the hook payload goes in on stdin, the `additionalContext` block comes back
+// on stdout, and Pi carries it into the turn as a context message.
+//
+// Every failure mode is a silent no-op: a missing binary, a hung binary, a
+// crash, unparseable output. Kimetsu is a sidecar — it must never break Pi.
 
 import { spawn } from "node:child_process";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
-function kimetsuExec(args: string[]): Promise<void> {
+/** Hard cap on any single kimetsu invocation. A hung binary must not stall a turn. */
+const EXEC_TIMEOUT_MS = 10000;
+
+/** Fallback session id when Pi's context does not expose one. Stable per process,
+ *  which is what the brain's per-session dedupe and refractory windows need. */
+const FALLBACK_SESSION_ID = `pi-${process.pid}`;
+
+/**
+ * Run `kimetsu <args>`, optionally writing `input` to its stdin, and resolve
+ * with whatever it printed to stdout ("" on any failure).
+ *
+ * stdout is PIPED, not ignored: the context hook communicates entirely through
+ * it. stderr stays ignored so diagnostics never mix into the parsed payload.
+ */
+function kimetsuRun(args: string[], input?: string): Promise<string> {
   return new Promise((resolve) => {
     let settled = false;
     let timer: ReturnType<typeof setTimeout> | undefined;
+    let stdout = "";
     const done = () => {
       if (settled) return;
       settled = true;
       if (timer !== undefined) clearTimeout(timer);
-      resolve();
+      resolve(stdout);
     };
     try {
       const child = spawn("kimetsu", args, {
-        stdio: "ignore",
+        stdio: ["pipe", "pipe", "ignore"],
         shell: false,
         windowsHide: true,
       });
-      // A hung binary must never stall the lifecycle hook: cap the wait and
-      // kill the child if it overruns. unref() so the timer alone can't keep
-      // the host process alive.
+      // Cap the wait and kill the child if it overruns. unref() so the timer
+      // alone can never keep the host process alive.
       timer = setTimeout(() => {
         child.kill();
         done();
-      }, 10000);
+      }, EXEC_TIMEOUT_MS);
       if (typeof timer.unref === "function") timer.unref();
+
+      child.stdout?.setEncoding("utf8");
+      child.stdout?.on("data", (chunk: string) => {
+        stdout += chunk;
+      });
+      child.stdout?.on("error", () => {}); // torn pipe — resolve with what we have
+      child.stdin?.on("error", () => {}); // EPIPE when the child exits early
+
       child.on("error", done); // binary not on PATH — silent no-op
-      child.on("close", done); // finished, or killed by the timeout above
+      child.on("close", done); // 'close' (not 'exit') so stdout is complete
+
+      child.stdin?.end(input ?? "");
     } catch {
       done(); // any unexpected error — silent no-op
     }
   });
 }
 
-export default function (pi: any) {
+/**
+ * Pull `hookSpecificOutput.additionalContext` out of a hook's stdout.
+ *
+ * The hook prints a single JSON line, but scanning from the end tolerates any
+ * stray output ahead of it. Anything unparseable yields `undefined`, which the
+ * callers treat as "nothing to inject".
+ */
+function parseAdditionalContext(stdout: string): string | undefined {
+  const lines = stdout
+    .split("\n")
+    .map((line) => line.trim())
+    .filter((line) => line !== "")
+    .reverse();
+  for (const line of lines) {
+    try {
+      const parsed = JSON.parse(line);
+      const context = parsed?.hookSpecificOutput?.additionalContext;
+      if (typeof context === "string" && context.trim() !== "") return context;
+    } catch {
+      // Not JSON — keep looking at earlier lines.
+    }
+  }
+  return undefined;
+}
+
+/** Best-effort session id from Pi's handler context, across naming variants. */
+function sessionIdOf(ctx: any): string {
+  // Current Pi exposes the durable id through SessionManager. Prefer it over
+  // historical context-field variants so /new, /resume, and /fork each get a
+  // distinct Kimetsu session even when they happen in the same Pi process.
+  const getSessionId = ctx?.sessionManager?.getSessionId;
+  if (typeof getSessionId === "function") {
+    try {
+      const id = getSessionId.call(ctx.sessionManager);
+      if (typeof id === "string" && id.trim() !== "") return id;
+    } catch {
+      // A third-party/legacy SessionManager must not break the host.
+    }
+  }
+  const candidates = [ctx?.sessionId, ctx?.sessionID, ctx?.session_id, ctx?.session?.id];
+  for (const candidate of candidates) {
+    if (typeof candidate === "string" && candidate.trim() !== "") return candidate;
+  }
+  return FALLBACK_SESSION_ID;
+}
+
+/** Current Pi's persisted JSONL transcript, when the session is not ephemeral. */
+function transcriptPathOf(ctx: any): string | undefined {
+  const getSessionFile = ctx?.sessionManager?.getSessionFile;
+  if (typeof getSessionFile !== "function") return undefined;
+  try {
+    const path = getSessionFile.call(ctx.sessionManager);
+    return typeof path === "string" && path.trim() !== "" ? path : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Host-neutral hook payload understood by Kimetsu v2.7. */
+function lifecyclePayload(ctx: any, transcript?: unknown[]): string {
+  const payload: Record<string, unknown> = { session_id: sessionIdOf(ctx) };
+  const transcriptPath = transcriptPathOf(ctx);
+  if (transcriptPath !== undefined) payload.transcript_path = transcriptPath;
+  else if (Array.isArray(transcript)) payload.transcript = transcript;
+  return JSON.stringify(payload);
+}
+
+/** `--workspace <cwd>` when Pi tells us the working directory, else nothing
+ *  (the CLI then defaults to its own cwd). */
+function workspaceArgs(ctx: any): string[] {
+  const cwd = ctx?.cwd;
+  return typeof cwd === "string" && cwd.trim() !== "" ? ["--workspace", cwd] : [];
+}
+
+export default function (pi: ExtensionAPI) {
   // session_start fires once when Pi starts up or a new session begins.
-  pi.on("session_start", async (_event: any, _ctx: any) => {
-    await kimetsuExec(["brain", "warm"]);
-    await kimetsuExec(["brain", "context-hook"]);
+  // Warming spawns the embedder daemon so the first real retrieval is semantic
+  // rather than falling back to lexical FTS.
+  // (`brain warm` takes no --workspace: it resolves the project from its cwd.)
+  pi.on("session_start", async (_event, _ctx) => {
+    await kimetsuRun(["brain", "warm"]);
+  });
+
+  // before_agent_start fires with the user's prompt, before the model is
+  // called, and can return a message that joins the turn. This is where brain
+  // context is injected. Pi has no session-start context surface, so
+  // --warm-on-first-prompt folds the repo digest and episodic resume into the
+  // first turn of each session.
+  pi.on("before_agent_start", async (event, ctx) => {
+    const payload = JSON.stringify({
+      session_id: sessionIdOf(ctx),
+      prompt: typeof event?.prompt === "string" ? event.prompt : "",
+    });
+    const stdout = await kimetsuRun(
+      ["brain", "context-hook", "--warm-on-first-prompt", ...workspaceArgs(ctx)],
+      payload,
+    );
+    const content = parseAdditionalContext(stdout);
+    if (content === undefined) return; // nothing relevant — zero tokens
+    return {
+      message: {
+        customType: "kimetsu-brain",
+        content,
+        display: false,
+      },
+    };
   });
 
   // agent_end fires after the LLM turn completes (maps to Kimetsu stop-hook).
-  pi.on("agent_end", async (_event: any, _ctx: any) => {
-    await kimetsuExec(["brain", "stop-hook"]);
+  pi.on("agent_end", async (event, ctx) => {
+    await kimetsuRun(
+      ["brain", "stop-hook", ...workspaceArgs(ctx)],
+      lifecyclePayload(ctx, event.messages),
+    );
   });
 
   // session_shutdown fires on clean session close (maps to session-end-hook).
-  pi.on("session_shutdown", async (_event: any, _ctx: any) => {
-    await kimetsuExec(["brain", "session-end-hook"]);
+  pi.on("session_shutdown", async (_event, ctx) => {
+    await kimetsuRun(
+      ["brain", "session-end-hook", ...workspaceArgs(ctx)],
+      lifecyclePayload(ctx),
+    );
   });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kimetsu-pi",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Kimetsu brain as a Pi.dev package — local-first, cross-session memory for the Pi coding agent that gets sharper every run.",
   "keywords": ["pi-package", "pi", "kimetsu", "memory", "brain", "rag", "mcp", "extension", "skill"],
   "homepage": "https://kimetsu.dev",
@@ -13,14 +13,18 @@
     "image": "https://raw.githubusercontent.com/RodCor/kimetsu/main/docs/assets/kimetsu-logo.png"
   },
   "files": ["extensions/", "skills/", "README.md", "LICENSE"],
-  "engines": { "node": ">=16" },
+  "engines": { "node": ">=22.19.0" },
   "scripts": {
     "typecheck": "tsc --noEmit",
     "test": "vitest run"
   },
   "devDependencies": {
-    "@types/node": "^20.0.0",
-    "typescript": "^5.5.0",
-    "vitest": "^2.0.0"
+    "@earendil-works/pi-coding-agent": "^0.84.2",
+    "@types/node": "^26.0.0",
+    "typescript": "^7.0.0",
+    "vitest": "^4.1.10"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
   }
 }

package/skills/kimetsu-brain/SKILL.md

@@ -10,8 +10,10 @@ Brain-first workflow:
 1. Before planning or editing broad coding, review, debugging, or setup tasks,
    run `kimetsu brain context <query>` and read the returned capsules as working
    context before deciding on a plan.
-2. After solving a non-obvious problem, run `kimetsu brain record` with a
-   concrete, actionable lesson and 2-5 domain tags so future sessions benefit.
+2. After solving a non-obvious problem, run
+   `kimetsu brain memory add --scope project --kind <kind> "<lesson>"` with a
+   concrete, actionable lesson. Choose `fact`, `preference`, `convention`,
+   `command`, or `failure_pattern` for `<kind>`.
 3. Run `kimetsu brain status` when you need to know whether the brain is
    initialized, has accepted memories, or has pending proposals.