pi-doc-injector 0.1.3 → 0.2.0

package/README.md

@@ -54,7 +54,10 @@ keywords:
 ```
 
 3. Start Pi. The extension scans `docs/` on session start.
-4. When the LLM mentions keywords from your docs, the relevant document is injected into the next turn's system prompt.
+4. When the user mentions a keyword, the matching doc is injected into the
+   system prompt **before the assistant responds** — no one-turn delay.
+5. If the assistant mentions a NEW keyword mid-response, generation is
+   automatically aborted and restarted with the doc injected immediately.
 
 ## Configuration
 
@@ -63,7 +66,7 @@ Create `.pi/doc-injector.json` in your project root to customize behavior:
 ```json
 {
   "docsPath": "./docs",
-  "matchThreshold": 2,
+  "matchThreshold": 1,
   "contextThreshold": 80,
   "recursive": true
 }
@@ -72,7 +75,7 @@ Create `.pi/doc-injector.json` in your project root to customize behavior:
 | Option             | Default    | Description                                              |
 | ------------------ | ---------- | -------------------------------------------------------- |
 | `docsPath`         | `"./docs"` | Path to docs folder (relative to project root)           |
-| `matchThreshold`   | `2`        | Minimum keyword matches required to inject a doc         |
+| `matchThreshold`   | `1`        | Minimum keyword matches required to inject a doc         |
 | `contextThreshold` | `80`       | Skip injection when context usage exceeds this % (0–100) |
 | `recursive`        | `true`     | Scan docs subdirectories recursively                     |
 
@@ -103,14 +106,28 @@ The extension uses a per-session injection model:
 - Use `/doc-inject reset` to manually reset all flags and allow docs to be injected again.
 - Use `/doc-inject list` to see which docs have been injected (✅) and which are pending (⬜).
 
+### System Prompt Lifecycle
+
+Pi **reconstructs the system prompt from source files each turn** (verified against pi v0.70.6).
+
+When `before_agent_start` fires, the `systemPrompt` passed to the extension is a freshly rebuilt prompt from `AGENTS.md`, `SYSTEM.md`, skills, and tool snippets. It is **not** accumulated from previous turns.
+
+This means:
+
+- Injections apply to the **current turn only** and do not persist in subsequent turns.
+- There is no risk of duplicate injection sections stacking up over time.
+- The `injected` flag alone is sufficient to prevent re-injection — no additional deduplication or marker-based stripping is needed.
+
+For the full source-level verification, see the JSDoc block in `index.ts`.
+
 ## Development
 
 ```bash
 # Run tests
-bun test
+npm test
 
 # Run tests in watch mode
-bun test --watch
+npm run test:watch
 ```
 
 ## License

package/docs/bun.md

@@ -1,32 +1,32 @@
 ---
 title: "JavaScript Runtime & Package Manager"
-keywords: [bun, package manager, runtime, install, test, build]
+keywords: [npm, node, package manager, runtime, install, test, build]
 ---
 
 # JavaScript Runtime & Package Manager
 
-This project uses **Bun** as its JavaScript runtime and package manager.
+This project uses **Node.js** as its JavaScript runtime and **npm** as its package manager.
 
-## Why Bun?
+## Why npm?
 
-- Fast native TypeScript support (no separate tsc step needed)
-- All-in-one runtime, bundler, and test runner
-- Drop-in replacement for Node.js and npm/yarn/pnpm
-- Significantly faster installs and test executions
+- The default package manager that ships with Node.js
+- Widely supported across all CI/CD platforms
+- Deterministic installs via `package-lock.json`
+- No additional runtime or tooling required
 
 ## Common Commands
 
 ```bash
 # Install dependencies
-bun install
+npm install
 
 # Run tests
-bun test
+npm test
 
-# Run tests in watch mode (recommended for development)
-bun test --watch
+# Run tests in watch mode
+npm run test:watch
 ```
 
 ## Version
 
-This project requires Bun >= 1.3.0. The lockfile (`bun.lock`) ensures reproducible installs.
+This project requires Node.js >= 18.0.0. The lockfile (`package-lock.json`) ensures reproducible installs.

package/docs/publish.md

@@ -1,6 +1,6 @@
 ---
 title: "Publishing Workflow"
-keywords: [publish, release, npm, version, tag, bun, oidc, trusted publisher]
+keywords: [publish, release, npm, version, tag, node, oidc, trusted publisher]
 ---
 
 # Publishing Workflow
@@ -54,9 +54,9 @@ git push origin master --follow-tags
 ## CI/CD
 
 The `Publish` workflow triggers on `v*` tags and:
-- Runs `bun install --frozen-lockfile`
+- Runs `npm ci`
 - Verifies tag matches `package.json` version
-- Runs `bun test`
+- Runs `npm test`
 - Publishes to npm with provenance via OIDC
 
 Monitor: https://github.com/lmn451/pi-docs/actions

package/index.ts

@@ -22,6 +22,29 @@
  * session, once a doc is injected, it won't be re-injected unless the user
  * manually runs `/doc-inject reset`.
  *
+ * ## System Prompt Lifecycle (verified against pi v0.70.6)
+ *
+ * Pi **reconstructs the system prompt from source files each turn**. Here is
+ * the exact flow, verified via source-code review of dist/core/agent-session.js
+ * and dist/core/extensions/runner.js (v0.70.6):
+ *
+ * 1. Before each agent turn, pi calls `this._rebuildSystemPrompt(toolNames)`.
+ *    This builds the prompt from `AGENTS.md`, `SYSTEM.md`, skills, enabled
+ *    tool snippets — never from a previously modified (injected) prompt.
+ * 2. The rebuilt prompt is stored in `this._baseSystemPrompt`.
+ * 3. `emitBeforeAgentStart(..., this._baseSystemPrompt, ...)` passes this
+ *    *fresh* base prompt to every extension handler.
+ * 4. Extension handlers can return a modified `systemPrompt` for the current
+ *    turn. Pi uses the modified prompt **only for this turn**.
+ * 5. When no extension modifies the prompt, pi explicitly resets to
+ *    `this._baseSystemPrompt` (comment in source: "Ensure we're using the
+ *    base prompt (in case previous turn had modifications)").
+ *
+ * **Therefore**: Previous injections from `before_agent_start` do NOT persist
+ * across turns. Duplicate sections cannot accumulate in the system prompt.
+ * The `injected` flag alone is sufficient to prevent re-injection — no
+ * marker-based stripping or deduplication is needed.
+ *
  * ## Race Condition Note
  *
  * If `resources_discover` (rebuild) fires while `before_agent_start` is running,
@@ -46,6 +69,7 @@ export default async function docInjectorExtension(pi: ExtensionAPI) {
   let enabled = true;
   let textBuffer = "";
   let pendingMatches = new Map<string, string[]>(); // filePath → matchedKeywords
+  let abortingForInjection = false; // guard against cascading aborts
 
   // ---- Helpers ----
   const getRegistry = () => registry;
@@ -74,8 +98,16 @@ export default async function docInjectorExtension(pi: ExtensionAPI) {
     );
   };
 
+  let lastInitTime = 0;
+
   // ---- Event: session_start ----
+  // Pi fires session_start twice on startup (both with reason "startup").
+  // Use a 2-second dedup window to skip the duplicate. Real session changes
+  // (/new, /resume, /fork) happen well outside this window.
   pi.on("session_start", async (_event, ctx) => {
+    const now = Date.now();
+    if (now - lastInitTime < 100) return;
+    lastInitTime = now;
     await initRegistry(ctx.cwd);
   });
 
@@ -92,54 +124,65 @@ export default async function docInjectorExtension(pi: ExtensionAPI) {
     await reloadRegistry();
   });
 
-  // ---- Event: message_update (streaming detection) ----
-  // NOTE: Pi's message_update event sends the full accumulated content of the
-  // assistant message on each update, not just the delta. We therefore REPLACE
-  // (not append to) the text buffer on each event, ensuring we always match
-  // against the complete message text.
-  pi.on("message_update", async (event, _ctx) => {
+  // ---- Event: input (user message matching) ----
+  // message_update only fires for assistant streaming messages, not user
+  // messages. We use the input event instead to populate pendingMatches
+  // BEFORE before_agent_start fires, so docs are injected in time for
+  // the assistant's immediate response.
+  pi.on("input", async (event, _ctx) => {
+    if (!enabled || !registry) return;
+    if (!event.text) return;
+
+    const matcher = buildMatcher();
+    if (!matcher) return;
+
+    const results = matcher.match(event.text);
+    for (const result of results) {
+      pendingMatches.set(result.entry.filePath, result.matchedKeywords);
+    }
+  });
+
+  // ---- Event: message_update (assistant streaming) ----
+  // For assistant streaming messages: if we detect NEW keyword matches for
+  // non-injected docs, abort the current generation and restart with the
+  // injected context — no waiting for the next turn.
+  pi.on("message_update", async (event, ctx) => {
     if (!enabled || !registry) return;
 
-    // Only process assistant messages
     const msg = event.message;
     if (msg.role !== "assistant") return;
 
-    // Replace buffer with full message text (message_update contains full content)
     const content = (msg as unknown as { content: unknown }).content;
     textBuffer = extractText(content);
     if (!textBuffer) return;
 
-    // Run matcher
     const matcher = buildMatcher();
     if (!matcher) return;
 
     const results = matcher.match(textBuffer);
 
-    // Store matches (dedup by filePath)
+    let hasNew = false;
     for (const result of results) {
+      if (!pendingMatches.has(result.entry.filePath)) {
+        hasNew = true;
+      }
       pendingMatches.set(result.entry.filePath, result.matchedKeywords);
     }
+
+    if (hasNew && !ctx.isIdle() && !abortingForInjection) {
+      abortingForInjection = true;
+      ctx.abort();
+    }
   });
 
   // ---- Event: message_end (finalize matches) ----
-  pi.on("message_end", async (event, ctx) => {
+  // Notification moved to before_agent_start so it fires for both user-triggered
+  // and auto-abort-triggered injections. message_end now just resets state.
+  pi.on("message_end", async (event, _ctx) => {
     if (!enabled || !registry) return;
-
     const msg = event.message;
     if (msg.role !== "assistant") return;
-
-    // Clear buffer
     textBuffer = "";
-
-    // Notify user about pending injections
-    if (pendingMatches.size > 0) {
-      const matchedEntries: DocEntry[] = [];
-      for (const [filePath] of pendingMatches) {
-        const entry = registry.getEntries().find((e) => e.filePath === filePath);
-        if (entry) matchedEntries.push(entry);
-      }
-      notifyInjection(ctx.ui, matchedEntries, pendingMatches);
-    }
   });
 
   // ---- Event: before_agent_start (inject into system prompt) ----
@@ -171,6 +214,12 @@ export default async function docInjectorExtension(pi: ExtensionAPI) {
 
     // Mark as injected only after confirming injection will happen
     registry.markInjected(matchedEntries.map((e) => e.filePath));
+
+    // Notify user about injection (moved here from message_end so it fires
+    // even when matches come from user messages, which get cleared before
+    // the assistant's message_end)
+    notifyInjection(ctx.ui, matchedEntries, pendingMatches);
+
     pendingMatches.clear();
 
     return {
@@ -178,6 +227,16 @@ export default async function docInjectorExtension(pi: ExtensionAPI) {
     };
   });
 
+  // ---- Event: agent_end (restart after auto-abort) ----
+  pi.on("agent_end", async () => {
+    if (abortingForInjection) {
+      abortingForInjection = false;
+      // Send a follow-up message to restart the turn.
+      // before_agent_start will inject the matched docs into context.
+      pi.sendUserMessage("continue", { deliverAs: "followUp" });
+    }
+  });
+
   // ---- Commands ----
   registerCommands(pi, {
     getRegistry,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-doc-injector",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "description": "Auto-inject relevant project documentation into Pi's LLM context based on keyword matching",
   "type": "module",
   "main": "./index.ts",
@@ -13,8 +13,8 @@
     "README.md"
   ],
   "scripts": {
-    "test": "bun test",
-    "test:watch": "bun test --watch"
+    "test": "vitest run",
+    "test:watch": "vitest"
   },
   "keywords": [
     "pi-package",
@@ -37,10 +37,12 @@
     "@mariozechner/pi-coding-agent": "*"
   },
   "devDependencies": {
-    "@types/bun": "^1.3.13"
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
   },
   "publishConfig": {
     "access": "public"
   },
-  "packageManager": "bun@1.3.11"
+  "packageManager": "npm@11.5.2"
 }

package/registry.ts

@@ -144,16 +144,28 @@ export class DocRegistry {
     for (const dirent of dirents) {
       if (!dirent.isFile() || !dirent.name.endsWith(".md")) continue;
 
-      // Build relative path from the directory tree
-      const parentPath = (dirent as Dirent & { path?: string }).path ?? "";
-      const relPath = parentPath
-        ? relative(dir, join(parentPath, dirent.name))
-        : dirent.name;
+      const fileName = basename(dirent.name);
+
+      // Cross-runtime: when dirent.name is just the filename, resolve the
+      // relative path from the parent directory. Use parentPath (Node 18+)
+      // with fallback to .path (Bun) for older runtimes.
+      let relPath: string;
+      if (dirent.name === fileName) {
+        const parentPath = (dirent as Dirent & { parentPath?: string; path?: string }).parentPath
+          ?? (dirent as Dirent & { path?: string }).path
+          ?? "";
+        relPath = parentPath
+          ? relative(dir, join(parentPath, dirent.name))
+          : dirent.name;
+      } else {
+        // Node-style: dirent.name already contains the relative path from dir
+        relPath = dirent.name;
+      }
 
       results.push({
         filePath: join(dir, relPath),
         relativePath: relPath,
-        fileName: dirent.name,
+        fileName,
       });
     }
 

package/types.ts

@@ -38,7 +38,7 @@ export interface DocInjectorConfig {
 /** Default configuration values. */
 export const DEFAULT_CONFIG: DocInjectorConfig = {
   docsPath: "./docs",
-  matchThreshold: 2,
+  matchThreshold: 1,
   contextThreshold: 80,
   recursive: true,
 };