pi-doc-injector 0.3.1 → 0.5.0

package/README.md

@@ -27,7 +27,23 @@ git clone https://github.com/yourname/pi-doc-injector.git .pi/extensions/doc-inj
 ## Quick Start
 
 1. Create a `docs/` folder in your project root.
-2. Add markdown files with YAML frontmatter:
+2. Add markdown files with frontmatter (`title` + `keywords`). See [Document Format](#document-format) for supported formats.
+3. Start Pi. The extension scans `docs/` on session start.
+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.
+
+## Document Format
+
+Documents are markdown files (`.md` or `.txt`) that the extension scans for injection.
+Each file can declare `title` and `keywords` via **frontmatter** — a metadata block at the top of the file.
+
+### Supported Frontmatter Formats
+
+The extension tries formats in this order and uses the first match it finds:
+
+**1. YAML (recommended)**
 
 ```md
 ---
@@ -36,28 +52,57 @@ keywords: [test, testing, jest, vitest]
 ---
 
 # Testing Workflow
+```
+
+**2. C-style block comment** — useful for `.ts`/`.js` doc files:
+
+```md
+/*---
+title: "Testing Workflow"
+keywords: [test, testing, jest, vitest]
+---*/
 
-Your documentation here...
+# Testing Workflow
 ```
 
-Keywords can also be specified in block format:
+**3. HTML comment** — useful for HTML-generated docs:
 
 ```md
----
+<!--
 title: "Testing Workflow"
-keywords:
+keywords: [test, testing, jest, vitest]
+-->
+
+# Testing Workflow
+```
+
+**4. Slash-slash comment** — useful for `.js`/`.ts` sidecar docs:
+
+```md
+//---
+title: "Testing Workflow"
+keywords: [test, testing, jest, vitest]
+
+# Testing Workflow
+```
+
+### Keyword Array Syntax
+
+Both **flow** and **block** keyword array syntaxes are supported:
+
+```md
+keywords: [test, testing, jest]          # flow: comma-separated in brackets
+keywords:                              # block: one per line
   - test
   - testing
   - jest
-  - vitest
----
 ```
 
-3. Start Pi. The extension scans `docs/` on session start.
-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.
+### Auto-Keywords Fallback
+
+If a file has **no frontmatter** and `autoKeywords` is enabled (default: `true`), the extension generates keywords heuristically from the filename and content — no metadata needed.
+
+If `autoKeywords` is `false`, files without valid frontmatter are **skipped** with a warning.
 
 ## Configuration
 
@@ -68,7 +113,10 @@ Create `.pi/doc-injector.json` in your project root to customize behavior:
   "docsPath": "./docs",
   "matchThreshold": 1,
   "contextThreshold": 80,
-  "recursive": true
+  "recursive": true,
+  "autoKeywords": true,
+  "llmKeywords": false,
+  "llmBatchSize": 20
 }
 ```
 
@@ -78,6 +126,9 @@ Create `.pi/doc-injector.json` in your project root to customize behavior:
 | `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                     |
+| `autoKeywords`     | `true`     | Generate keywords heuristically when frontmatter is missing |
+| `llmKeywords`      | `false`    | Enable LLM-based keyword generation (see below)          |
+| `llmBatchSize`     | `20`       | Max files per LLM keyword batch                          |
 
 ### Keyword Matching
 
@@ -96,6 +147,50 @@ Injection is also skipped if the current context usage exceeds 80% of the token
 | `/doc-inject reset`  | Reset all injected flags (docs become re-injectable) |
 | `/doc-inject status` | Show current injection status and config             |
 | `/doc-reload`        | Re-scan docs folder and rebuild registry             |
+| `/doc-keywords-gen`  | Generate LLM keywords for files without frontmatter (requires `llmKeywords: true` in config) |
+
+## Keyword Generation
+
+When a document has no frontmatter keywords, the extension handles it in two ways:
+
+### Heuristic (Automatic)
+
+If `autoKeywords` is `true` (default), keywords are generated automatically from:
+
+- **Filename parts**: `"api-authentication.md"` → `[api, authentication]`
+- **Markdown headings**: `"# Getting Started"` → `[getting, started]`
+- **Code symbols**: `"function foo()"` → `[foo]`
+
+All keywords are filtered through a stop-word list, lowercased, and capped at 20.
+
+### LLM Generation (Manual)
+
+For better keywords, enable LLM generation in config:
+
+```json
+{
+  "autoKeywords": true,
+  "llmKeywords": true,
+  "llmBatchSize": 20
+}
+```
+
+Then run `/doc-keywords-gen [path]` to generate keywords via LLM. Without a path argument, it processes all keyword-less files.
+
+The LLM reads each file's content and produces 3–10 relevant, searchable keywords per file. Results are saved to the cache and reused on subsequent scans.
+
+### Keyword Source Tracking
+
+The cache stores which method was used for each file's keywords:
+
+| Source       | How set                                          |
+| ------------ | ------------------------------------------------ |
+| `frontmatter` | Keywords declared in file frontmatter             |
+| `cache`      | Reused from previous scan (mtime match)          |
+| `heuristic`  | Auto-generated from filename/content             |
+| `llm`        | Generated via `/doc-keywords-gen`                |
+
+Use `/doc-inject list` to see each file's keyword source (shown as `[source]` tag).
 
 ## Injection Lifecycle
 

package/index.ts

@@ -4,6 +4,21 @@
  * Automatically injects relevant project documentation into the LLM context
  * by monitoring streaming output for keyword matches.
  *
+ * ## Injection Model: CustomMessage (NOT system prompt)
+ *
+ * On match, the extension returns a `message` field from `before_agent_start`
+ * (a `CustomMessage` with `customType: "doc-injector"`). Pi appends this to the
+ * session and sends it to the LLM as part of the conversation — the system
+ * prompt is NEVER mutated.
+ *
+ * Why a message and not the system prompt:
+ * - The system prompt is the highest-value Anthropic prompt-cache slot. Each
+ *   unique system prompt text breaks the cache (5-min TTL by default).
+ *   Appending per-turn doc content there would invalidate the cache on every
+ *   first injection.
+ * - A `message` only adds to the conversation prefix, leaving the system
+ *   prompt cache warm across turns.
+ *
  * ## Streaming Model
  *
  * This extension relies on Pi's streaming event contract:
@@ -13,7 +28,7 @@
  * - `message_end`: Fires once when the assistant's response is complete.
  *   The extension finalizes matches and notifies the user.
  * - `before_agent_start`: Fires before the next agent turn. The extension
- *   injects matched docs into the system prompt, then marks them as injected.
+ *   returns a `message` carrying the matched docs and marks them as injected.
  *
  * ## Injection Lifecycle
  *
@@ -22,28 +37,23 @@
  * 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)
+ * ## Double-Injection Prevention
+ *
+ * Two independent guards make duplicate injection impossible in a session:
  *
- * 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. **Matcher-level guard**: `buildMatcher()` calls `getNonInjectedEntries()`,
+ *    so already-injected docs are excluded from the candidate set. The
+ *    `pendingMatches` map is only populated from the matcher's output, so
+ *    once a doc is injected, the next `input` event cannot re-match it.
  *
- * 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)").
+ * 2. **Mark guard**: `markInjected()` is called inside `before_agent_start`
+ *    AFTER the build step but BEFORE the return value is processed. This
+ *    means the flag flips synchronously with the LLM call — even if the
+ *    session is reloaded mid-turn, the next `buildMatcher()` won't see the
+ *    doc as a candidate.
  *
- * **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.
+ * The two guards are redundant by design: if matcher exclusion ever fails
+ * (e.g. a race), the mark step still prevents the doc from being sent twice.
  *
  * ## Race Condition Note
  *
@@ -58,7 +68,7 @@ import { Type } from "@sinclair/typebox";
 import { resolve } from "node:path";
 import { loadCache, saveCache } from "./cache";
 import { loadConfig } from "./config";
-import { buildSystemPromptAppend, notifyInjection } from "./injector";
+import { buildInjectionContent, notifyInjection } from "./injector";
 import { buildKeywordGenPrompt } from "./keyword-llm";
 import { extractText, KeywordMatcher } from "./matcher";
 import { DocRegistry } from "./registry";
@@ -308,7 +318,11 @@ export default async function docInjectorExtension(pi: ExtensionAPI) {
     textBuffer = "";
   });
 
-  // ---- Event: before_agent_start (inject into system prompt) ----
+  // ---- Event: before_agent_start (inject as CustomMessage) ----
+  // Returns a `message` (CustomMessage with customType: "doc-injector") rather
+  // than mutating `systemPrompt`. The system prompt stays byte-identical across
+  // turns, preserving the prompt cache. The CustomMessage is appended to the
+  // session and sent to the LLM as part of the conversation.
   pi.on("before_agent_start", async (event, ctx) => {
     // P5.4b — Guard: skip injection during LLM keyword generation
     if (keywordGenInFlight) return;
@@ -335,9 +349,12 @@ export default async function docInjectorExtension(pi: ExtensionAPI) {
       return;
     }
 
-    const append = buildSystemPromptAppend(matchedEntries, pendingMatches);
+    const content = buildInjectionContent(matchedEntries, pendingMatches);
 
-    // Mark as injected only after confirming injection will happen
+    // Mark as injected only after confirming injection will happen.
+    // This is the second half of the double-injection guard: even if the
+    // matcher ever produced a duplicate match, markInjected prevents a
+    // second send.
     registry.markInjected(matchedEntries.map((e) => e.filePath));
 
     // Notify user about injection (moved here from message_end so it fires
@@ -348,7 +365,11 @@ export default async function docInjectorExtension(pi: ExtensionAPI) {
     pendingMatches.clear();
 
     return {
-      systemPrompt: (event.systemPrompt || "") + "\n\n" + append,
+      message: {
+        customType: "doc-injector",
+        content,
+        display: true,
+      },
     };
   });
 

package/injector.ts

@@ -1,8 +1,12 @@
 /**
- * Context Injector — formats matched docs into system prompt append
- * and sends TUI notifications.
+ * Context Injector — formats matched docs into a content string suitable for
+ * injection as a `CustomMessage` (returned from `before_agent_start`) and
+ * sends TUI notifications.
+ *
+ * The produced content is delivered to the LLM as a `CustomMessage` rather
+ * than appended to the system prompt. This keeps the system prompt
+ * byte-identical across turns so the provider's prompt cache stays warm.
  */
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import type { DocEntry } from "./types";
 
 /**
@@ -14,7 +18,7 @@ export interface NotifyCapability {
 }
 
 /**
- * Sanitize keywords for safe injection into the system prompt.
+ * Sanitize keywords for safe display in the injection content.
  *
  * - Strips \n and \r (replaces with space) to prevent prompt injection
  * - Caps each keyword at 100 characters
@@ -29,11 +33,13 @@ function sanitizeKeywords(keywords: string[]): string[] {
 }
 
 /**
- * Build a system prompt append string from matched documents.
+ * Build the content string for a `CustomMessage` injection from matched
+ * documents. This is the payload that gets returned in
+ * `before_agent_start`'s `message.content` and sent to the LLM.
  */
-export function buildSystemPromptAppend(
-  entries: DocEntry[],
-  matchedKeywords: Map<string, string[]>,
+export function buildInjectionContent(
+    entries: DocEntry[],
+    matchedKeywords: Map<string, string[]>,
 ): string {
   if (entries.length === 0) return "";
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-doc-injector",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "description": "Auto-inject relevant project documentation into Pi's LLM context based on keyword matching",
   "type": "module",
   "main": "./index.ts",