@zosmaai/pi-llm-wiki 0.10.7 → 0.11.0

package/dist/extensions/llm-wiki/lib/guardrails.js

@@ -0,0 +1,232 @@
+import { isToolCallEventType } from "@mariozechner/pi-coding-agent";
+import { scheduleReindex } from "./indexing.js";
+import { rebuildMetadataLight } from "./metadata.js";
+import { isPathWithin, isProtectedPath, resolveVaultPaths } from "./utils.js";
+import { inspectVaultFormat, isGeneratedOkfPath } from "./vault-format.js";
+/**
+ * Guardrails and auto-rebuild hooks for the LLM Wiki extension.
+ */
+let pendingRebuild = false;
+const APPLY_PATCH_PATH_NOISE = /^\*{0,3}\s*(?:(?:update|add|delete|move)[^A-Za-z0-9]*(?:file|to)?[^A-Za-z0-9]*:)?\s*\*{0,3}\s*/i;
+const PATCH_INPUT_KEYS = { input: true, _input: true, patch: true };
+const DESTINATION_KEYS = {
+    rename: true,
+    move: true,
+    dest: true,
+    destination: true,
+    newPath: true,
+};
+function normalizeMutationPath(target) {
+    const trimmed = target.trim();
+    if (!trimmed)
+        return undefined;
+    const first = trimmed[0];
+    const last = trimmed[trimmed.length - 1];
+    const quoted = first === '"' || first === "'";
+    if (quoted !== (last === '"' || last === "'") || (quoted && first !== last)) {
+        return undefined;
+    }
+    const unquoted = quoted ? trimmed.slice(1, -1) : trimmed;
+    return unquoted.replace(APPLY_PATCH_PATH_NOISE, "") || undefined;
+}
+function parsePatchHeader(line) {
+    const trimmed = line.replace(/\r$/, "").trimEnd();
+    if (!trimmed.startsWith("[") || !trimmed.endsWith("]"))
+        return undefined;
+    const body = trimmed.slice(1, -1).trim();
+    const tag = /#[0-9A-Fa-f]{4}\s*$/.exec(body);
+    const rawTarget = tag ? body.slice(0, tag.index) : body.replace(/\s+$/, "");
+    if (!rawTarget || rawTarget.includes("#"))
+        return undefined;
+    return normalizeMutationPath(rawTarget);
+}
+function parseMoveDestination(line) {
+    const rawDestination = line.trim().slice(2).trim();
+    if (!rawDestination)
+        return undefined;
+    const quote = rawDestination[0];
+    if (quote !== '"' && quote !== "'")
+        return normalizeMutationPath(rawDestination);
+    let cursor = 1;
+    while (cursor < rawDestination.length) {
+        if (rawDestination[cursor] === "\\" && cursor + 1 < rawDestination.length) {
+            cursor += 2;
+            continue;
+        }
+        if (rawDestination[cursor] === quote) {
+            return cursor === rawDestination.length - 1
+                ? normalizeMutationPath(rawDestination)
+                : undefined;
+        }
+        cursor++;
+    }
+    return undefined;
+}
+function scanPatchString(input) {
+    const paths = [];
+    let sawHeader = false;
+    let sectionHasMove = false;
+    let complete = true;
+    const stripped = input.startsWith("\uFEFF") ? input.slice(1) : input;
+    for (const line of stripped.split("\n")) {
+        const trimmed = line.replace(/\r$/, "").trim();
+        if (trimmed.startsWith("[")) {
+            sawHeader = true;
+            sectionHasMove = false;
+            const path = parsePatchHeader(line);
+            if (path)
+                paths.push(path);
+            else
+                complete = false;
+            continue;
+        }
+        if (!/^MV(?:\s|$)/.test(trimmed))
+            continue;
+        const destination = parseMoveDestination(trimmed);
+        if (!sawHeader || sectionHasMove || !destination)
+            complete = false;
+        else {
+            paths.push(destination);
+            sectionHasMove = true;
+        }
+    }
+    return { paths, complete: sawHeader && complete };
+}
+function mergeMutationScans(target, source) {
+    target.paths.push(...source.paths);
+    target.complete &&= source.complete;
+}
+function addMutationPath(scan, target) {
+    const path = normalizeMutationPath(target);
+    if (path)
+        scan.paths.push(path);
+    else
+        scan.complete = false;
+}
+function collectMutationPaths(input, seen, stringsArePatches = false) {
+    if (typeof input === "string") {
+        return stringsArePatches ? scanPatchString(input) : { paths: [], complete: true };
+    }
+    if (!input || typeof input !== "object" || seen.has(input)) {
+        return { paths: [], complete: true };
+    }
+    seen.add(input);
+    const scan = { paths: [], complete: true };
+    if (Array.isArray(input)) {
+        for (const value of input) {
+            mergeMutationScans(scan, collectMutationPaths(value, seen, stringsArePatches));
+        }
+        return scan;
+    }
+    const record = input;
+    if (typeof record.path === "string" && record.path.length > 0) {
+        addMutationPath(scan, record.path);
+    }
+    const eventPaths = Array.isArray(record.paths) ? record.paths : [record.paths];
+    for (const path of eventPaths) {
+        if (typeof path === "string" && path.length > 0)
+            addMutationPath(scan, path);
+    }
+    for (const [key, value] of Object.entries(record)) {
+        if (key === "path" || key === "paths")
+            continue;
+        if (DESTINATION_KEYS[key] === true) {
+            if (typeof value === "string" && value.length > 0)
+                addMutationPath(scan, value);
+            else
+                scan.complete = false;
+            continue;
+        }
+        const childStringsArePatches = stringsArePatches || PATCH_INPUT_KEYS[key] === true;
+        if (typeof value !== "string" && (!value || typeof value !== "object"))
+            continue;
+        mergeMutationScans(scan, collectMutationPaths(value, seen, childStringsArePatches));
+    }
+    return scan;
+}
+function inspectMutationPaths(input) {
+    const stringsArePatches = typeof input === "string" || Array.isArray(input);
+    const scan = collectMutationPaths(input, new WeakSet(), stringsArePatches);
+    return { paths: [...new Set(scan.paths)], complete: scan.complete };
+}
+/** Return every file path targeted by a write or patch-shaped edit input. */
+export function extractMutationPaths(input) {
+    return inspectMutationPaths(input).paths;
+}
+/** True when a write or patch-shaped edit targets a page in the wiki directory. */
+export function hasWikiMutation(input, wikiPath) {
+    return extractMutationPaths(input).some((path) => isPathWithin(wikiPath, path));
+}
+export function mutationBlockReason(path, paths) {
+    const protectedPath = isProtectedPath(path, paths);
+    if (protectedPath.protected)
+        return protectedPath.reason;
+    if (isPathWithin(paths.dotWiki, path)) {
+        const state = inspectVaultFormat(paths);
+        if (state.blocking) {
+            return `Wiki vault configuration is invalid: ${state.diagnostics[0].message}`;
+        }
+    }
+    if (isGeneratedOkfPath(path, paths)) {
+        return "Generated OKF indexes and log are read-only. Use wiki_rebuild_meta or the page-producing tool that owns the source mutation.";
+    }
+    return undefined;
+}
+/** Install guardrails on the extension API. */
+export function installGuardrails(pi, runtime) {
+    // Block direct edits to raw/ and meta/, plus OKF generated projections
+    pi.on("tool_call", async (event) => {
+        if (isToolCallEventType("write", event)) {
+            const path = event.input.path;
+            const paths = resolveVaultPaths(process.cwd());
+            const reason = mutationBlockReason(path, paths);
+            if (reason)
+                return { block: true, reason };
+        }
+        if (isToolCallEventType("edit", event)) {
+            const mutation = inspectMutationPaths(event.input);
+            const targetPaths = mutation.paths;
+            if (!mutation.complete || targetPaths.length === 0) {
+                return { block: true, reason: "Cannot determine the files targeted by this edit." };
+            }
+            const paths = resolveVaultPaths(process.cwd());
+            for (const path of targetPaths) {
+                const reason = mutationBlockReason(path, paths);
+                if (reason)
+                    return { block: true, reason };
+            }
+        }
+    });
+    // Track wiki edits for auto-rebuild
+    pi.on("tool_result", async (event) => {
+        if (event.toolName === "write" || event.toolName === "edit") {
+            const paths = resolveVaultPaths(process.cwd());
+            if (hasWikiMutation(event.input, paths.wiki)) {
+                pendingRebuild = true;
+            }
+        }
+    });
+    // Rebuild metadata at end of turn if wiki was modified, then refresh
+    // semantic embeddings in the background (#66) so manual page edits get
+    // re-embedded. Both are best-effort no-ops when nothing is configured.
+    pi.on("turn_end", async (_event, ctx) => {
+        if (pendingRebuild) {
+            pendingRebuild = false;
+            try {
+                const paths = resolveVaultPaths(process.cwd());
+                // Manual page edits also rebuild off the critical path. Without a
+                // runtime (shouldn't happen in normal wiring) fall back to inline.
+                if (runtime) {
+                    const launchCtx = ctx ? { hasUI: ctx.hasUI, ui: ctx.ui } : { hasUI: false };
+                    scheduleReindex(runtime, launchCtx, paths);
+                }
+                else {
+                    rebuildMetadataLight(paths);
+                }
+            }
+            catch {
+                // Silently fail — metadata rebuild is best-effort
+            }
+        }
+    });
+}

package/dist/extensions/llm-wiki/lib/indexing.js

@@ -0,0 +1,78 @@
+/**
+ * Non-blocking vault (re)indexing.
+ *
+ * Writing a wiki page (observe / retro / capture / ensure_page) and editing one
+ * by hand both require the derived metadata — `meta/registry.json`,
+ * `backlinks.json`, `index.md`, `log.md` — to be rebuilt, plus (optionally) the
+ * semantic embedding store to be refreshed. That rebuild is O(pages): it
+ * rescans every page in the vault. Doing it inline on the tool's / turn's
+ * critical path makes every write get slower as the vault grows.
+ *
+ * `scheduleReindex` moves that work off the caller's stack onto the shared
+ * background Runtime (#64) and coalesces a burst of writes into a single pass:
+ *
+ *   - A leading micro-yield guarantees the caller (a tool's `execute`, or the
+ *     turn_end handler) returns BEFORE the heavy rebuild runs.
+ *   - A per-vault `dirty` flag + drain loop means writes that land while a pass
+ *     is in flight are folded into a trailing rebuild instead of being lost —
+ *     this also covers the async window of the embeddings refresh.
+ *   - A per-vault `inflight` guard collapses concurrent schedule calls onto the
+ *     same promise (single-flight), so N writes in a turn cost one rebuild.
+ *
+ * Errors are isolated by `Runtime.launchTask`; the promise never rejects. The
+ * embeddings step is a no-op unless an embedder is configured (#66/#67).
+ */
+import { reindexEmbeddings, resolveEmbedder } from "./embeddings.js";
+import { rebuildMetadataLight } from "./metadata.js";
+/** Promise of the current background pass, keyed by vault root. */
+const inflight = new Map();
+/** Vault roots with writes awaiting a (re)build. */
+const dirty = new Set();
+/** Stable single-flight label for a vault's background index pass. */
+export function indexLabel(root) {
+    return `index:${root}`;
+}
+/**
+ * Schedule a non-blocking metadata rebuild (+ embeddings refresh) for a vault.
+ * Returns the promise of the in-flight pass so callers/tests can await drainage
+ * (the agent loop itself never awaits it). Safe to call on every write.
+ */
+export function scheduleReindex(runtime, ctx, paths) {
+    const root = paths.root;
+    dirty.add(root);
+    const active = inflight.get(root);
+    if (active)
+        return active;
+    const pass = runtime.launchTask(ctx, indexLabel(root), async () => {
+        // Yield once so the caller returns before the O(pages) rebuild runs. This
+        // is what makes the surrounding write non-blocking.
+        await Promise.resolve();
+        try {
+            // Drain: keep rebuilding until no new write arrived during the previous
+            // pass. The loop re-checks AFTER the awaited embeddings step, so writes
+            // that land during embedding are not lost.
+            while (dirty.has(root)) {
+                dirty.delete(root);
+                const projection = rebuildMetadataLight(paths);
+                if (!projection.ok)
+                    continue;
+                // Refresh embeddings only after metadata is consistent. Stale-aware and
+                // a no-op unless an embedder is configured.
+                runtime.ensureConfig(root);
+                const embedder = resolveEmbedder(runtime.config);
+                if (embedder)
+                    await reindexEmbeddings(paths, embedder);
+            }
+        }
+        finally {
+            inflight.delete(root);
+        }
+    });
+    inflight.set(root, pass);
+    return pass;
+}
+/** Test-only: clear coalescing state between cases. */
+export function __resetIndexingState() {
+    inflight.clear();
+    dirty.clear();
+}

package/dist/extensions/llm-wiki/lib/ingest-worker.js

@@ -0,0 +1,310 @@
+import { existsSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { Type } from "typebox";
+import { createKnowledgeDocument, patchKnowledgeDocument, readKnowledgeDocumentFile, serializeKnowledgeDocument, writeKnowledgeDocumentFile, } from "./knowledge-document.js";
+import { appendEvent, rebuildMetadataLight } from "./metadata.js";
+import { runSubAgent } from "./subagent.js";
+import { fmtDate, slugify } from "./utils.js";
+import { VaultWriteError, assertWritableVault } from "./vault-format.js";
+/**
+ * Background ingest synthesis (issue #65, part of epic #63).
+ *
+ * Moves the work the main agent used to do during `wiki_ingest` — reading a
+ * captured source's extracted text and writing the source page + entity /
+ * concept pages — onto a background sub-agent, so capturing/ingesting never
+ * stalls the user.
+ *
+ * Design: the sub-agent produces ONE structured `commit_synthesis` call; the
+ * persistence (`commitSynthesis`) is fully deterministic and unit-testable
+ * without an LLM. This mirrors pi-observational-memory's single-structured-tool
+ * pattern and keeps the file-writing logic verifiable in isolation.
+ */
+// ── structured synthesis schema ───────────────────────────
+export const CommitSynthesisSchema = Type.Object({
+    summary: Type.String({
+        minLength: 1,
+        description: "2-3 paragraph summary of the source's key content.",
+    }),
+    key_takeaways: Type.Array(Type.String({ minLength: 1 }), {
+        description: "The most important points, one per item.",
+    }),
+    entities: Type.Array(Type.Object({
+        title: Type.String({
+            minLength: 1,
+            description: "Entity name (person, org, tool, product).",
+        }),
+        description: Type.String({ description: "One-line description of the entity." }),
+    }), { description: "Named entities mentioned in the source." }),
+    concepts: Type.Array(Type.Object({
+        title: Type.String({ minLength: 1, description: "Concept name (idea, pattern, framework)." }),
+        definition: Type.String({ description: "One-line definition of the concept." }),
+    }), { description: "Concepts discussed in the source." }),
+    quotes: Type.Optional(Type.Array(Type.Object({
+        text: Type.String({ minLength: 1 }),
+        attribution: Type.Optional(Type.String()),
+    }), { description: "Notable verbatim quotes." })),
+    contradictions: Type.Optional(Type.Array(Type.String({ minLength: 1 }), {
+        description: "Tensions/contradictions with existing wiki content, if any.",
+    })),
+});
+// ── deterministic persistence (no LLM) ────────────────────
+function buildEntityPageBody(title, description, sourceId) {
+    const desc = description.trim() || "One-line description.";
+    return `# ${title}
+
+${desc}
+
+## Overview
+
+[Key facts]
+
+## Links
+
+- [${sourceId}](/sources/${sourceId}.md)`;
+}
+function buildConceptPageBody(title, definition, sourceId) {
+    const def = definition.trim() || "One-line definition.";
+    return `# ${title}
+
+${def}
+
+## Definition
+
+[Clear explanation]
+
+## Links
+
+- [${sourceId}](/sources/${sourceId}.md)`;
+}
+/** Rebuild the source page body from synthesis data, marking it ingested. */
+export function buildIngestedSourcePageBody(manifest, data, _date) {
+    const id = String(manifest.id);
+    const title = String(manifest.title || id);
+    const url = manifest.url ? `\n> _Original: [${manifest.url}](${manifest.url})_` : "";
+    const takeaways = data.key_takeaways.length > 0
+        ? data.key_takeaways.map((t) => `- ${t.trim()}`).join("\n")
+        : "- [None recorded]";
+    const entities = data.entities.length > 0
+        ? data.entities.map((e) => `- [${e.title}](/entities/${slugify(e.title)}.md)`).join("\n")
+        : "- [None]";
+    const concepts = data.concepts.length > 0
+        ? data.concepts.map((c) => `- [${c.title}](/concepts/${slugify(c.title)}.md)`).join("\n")
+        : "- [None]";
+    const quotes = data.quotes && data.quotes.length > 0
+        ? data.quotes
+            .map((q) => `> ${q.text.trim()}${q.attribution ? ` — ${q.attribution}` : ""}`)
+            .join("\n\n")
+        : "> [None recorded]";
+    const contradictions = data.contradictions && data.contradictions.length > 0
+        ? `\n## Contradictions\n\n${data.contradictions.map((c) => `⚠️ **Contradiction**: ${c.trim()}`).join("\n")}\n`
+        : "";
+    return `# ${title}${url}
+
+## Summary
+
+${data.summary.trim()}
+
+## Key Takeaways
+
+${takeaways}
+
+## Entities Mentioned
+
+${entities}
+
+## Concepts Mentioned
+
+${concepts}
+
+## Notable Quotes
+
+${quotes}
+${contradictions}## Source Packet
+
+- **ID:** \`sources/${id}\`
+- **Extracted:** \`raw/sources/${id}/extracted.md\`
+- **Manifest:** \`raw/sources/${id}/manifest.json\`
+`;
+}
+/** Rebuild the source page from synthesis data, marking it ingested. */
+export function buildIngestedSourcePage(manifest, data, date) {
+    const id = String(manifest.id);
+    const title = String(manifest.title || id);
+    const format = String(manifest.format || "unknown");
+    const captured = String(manifest.captured || date);
+    const body = buildIngestedSourcePageBody(manifest, data, date);
+    const doc = createKnowledgeDocument(`sources/${id}.md`, {
+        type: "source",
+        title,
+        format,
+        source_id: id,
+        raw_path: `raw/sources/${id}/extracted.md`,
+        captured,
+        status: "ingested",
+        updated: date,
+    }, body);
+    return serializeKnowledgeDocument(doc);
+}
+/**
+ * Persist a synthesis deterministically: rewrite the source page (status →
+ * ingested), create missing entity/concept pages (existing pages are linked,
+ * never overwritten), and log the event. Pure file I/O — no LLM, no network.
+ */
+export function commitSynthesis(paths, sourceId, manifest, data, date = fmtDate()) {
+    const result = {
+        sourceId,
+        sourcePage: join(paths.wiki, "sources", `${sourceId}.md`),
+        entitiesCreated: [],
+        conceptsCreated: [],
+        entitiesLinked: [],
+        conceptsLinked: [],
+        contradictions: data.contradictions?.length ?? 0,
+    };
+    try {
+        assertWritableVault(paths);
+    }
+    catch (error) {
+        if (error instanceof VaultWriteError) {
+            return { ok: false, sourceId, diagnostics: error.diagnostics };
+        }
+        throw error;
+    }
+    // Patch existing documents so unknown fields, legacy sources, and titles survive.
+    let sourceDocument;
+    if (existsSync(result.sourcePage)) {
+        const parsed = readKnowledgeDocumentFile(result.sourcePage, `sources/${sourceId}.md`);
+        if (!parsed.ok)
+            return { ok: false, sourceId, diagnostics: parsed.diagnostics };
+        sourceDocument = patchKnowledgeDocument(parsed.document, {
+            fields: { status: "ingested", updated: date },
+            body: buildIngestedSourcePageBody(manifest, data, date),
+        });
+    }
+    else {
+        sourceDocument = createKnowledgeDocument(`sources/${sourceId}.md`, {
+            type: "source",
+            title: String(manifest.title || sourceId),
+            format: String(manifest.format || "unknown"),
+            source_id: sourceId,
+            raw_path: `raw/sources/${sourceId}/extracted.md`,
+            captured: String(manifest.captured || date),
+            status: "ingested",
+            updated: date,
+        }, buildIngestedSourcePageBody(manifest, data, date));
+    }
+    mkdirSync(join(paths.wiki, "sources"), { recursive: true });
+    writeKnowledgeDocumentFile(result.sourcePage, sourceDocument);
+    // Entity pages — create if absent, link if present.
+    mkdirSync(join(paths.wiki, "entities"), { recursive: true });
+    for (const e of data.entities) {
+        const slug = slugify(e.title);
+        if (!slug)
+            continue;
+        const pagePath = join(paths.wiki, "entities", `${slug}.md`);
+        if (existsSync(pagePath)) {
+            result.entitiesLinked.push(slug);
+        }
+        else {
+            const entityDoc = createKnowledgeDocument(`entities/${slug}.md`, {
+                type: "entity",
+                title: e.title,
+                description: e.description.trim() || "One-line description.",
+                created: date,
+                updated: date,
+            }, buildEntityPageBody(e.title, e.description, sourceId), [{ id: sourceId, resource: `/sources/${sourceId}.md` }]);
+            writeKnowledgeDocumentFile(pagePath, entityDoc);
+            result.entitiesCreated.push(slug);
+        }
+    }
+    // Concept pages — create if absent, link if present.
+    mkdirSync(join(paths.wiki, "concepts"), { recursive: true });
+    for (const c of data.concepts) {
+        const slug = slugify(c.title);
+        if (!slug)
+            continue;
+        const pagePath = join(paths.wiki, "concepts", `${slug}.md`);
+        if (existsSync(pagePath)) {
+            result.conceptsLinked.push(slug);
+        }
+        else {
+            const conceptDoc = createKnowledgeDocument(`concepts/${slug}.md`, {
+                type: "concept",
+                title: c.title,
+                description: c.definition.trim() || "One-line definition.",
+                created: date,
+                updated: date,
+            }, buildConceptPageBody(c.title, c.definition, sourceId), [{ id: sourceId, resource: `/sources/${sourceId}.md` }]);
+            writeKnowledgeDocumentFile(pagePath, conceptDoc);
+            result.conceptsCreated.push(slug);
+        }
+    }
+    appendEvent(paths, {
+        kind: "ingest",
+        source_id: sourceId,
+        entities_created: result.entitiesCreated.length,
+        concepts_created: result.conceptsCreated.length,
+        contradictions: result.contradictions,
+        background: true,
+    });
+    return { ok: true, ...result };
+}
+// ── sub-agent synthesis (LLM) ─────────────────────────────
+export const INGEST_SYSTEM = `You are the LLM Wiki ingestion synthesizer. You turn a single captured source's extracted text into structured wiki knowledge.
+
+Read the source content, then call \`commit_synthesis\` EXACTLY ONCE with:
+- summary: a faithful 2-3 paragraph summary (no fabrication).
+- key_takeaways: the most important points.
+- entities: named people, organizations, tools, products actually mentioned.
+- concepts: ideas, patterns, frameworks actually discussed.
+- quotes: notable verbatim quotes (optional).
+- contradictions: tensions with general knowledge or noted in the text (optional).
+
+Rules:
+- Never fabricate. Only include entities/concepts present in the source.
+- Keep descriptions to one line.
+- After calling commit_synthesis once, reply with a one-line confirmation and stop.`;
+/**
+ * Run the synthesis sub-agent for a single source, then commit + rebuild
+ * metadata. Returns the commit result, or undefined if the model produced no
+ * synthesis.
+ */
+export async function runIngestSynthesis(args) {
+    const { model, apiKey, headers, paths, sourceId, manifest, extracted, maxChars, signal } = args;
+    const content = extracted.slice(0, maxChars ?? 24_000);
+    if (!content.trim())
+        return undefined;
+    let committed;
+    const commitTool = {
+        name: "commit_synthesis",
+        label: "Commit synthesis",
+        description: "Persist the structured synthesis of this source into wiki pages. Call exactly once.",
+        parameters: CommitSynthesisSchema,
+        execute: async (_id, params) => {
+            const outcome = commitSynthesis(paths, sourceId, manifest, params);
+            if (!outcome.ok) {
+                return {
+                    content: [{ type: "text", text: `Failed: ${outcome.diagnostics[0].message}` }],
+                    details: { sourceId },
+                    isError: true,
+                };
+            }
+            committed = outcome;
+            const ack = `Committed: source page + ${committed.entitiesCreated.length} new entit${committed.entitiesCreated.length === 1 ? "y" : "ies"}, ${committed.conceptsCreated.length} new concept${committed.conceptsCreated.length === 1 ? "" : "s"}. Reply with a one-line confirmation and stop.`;
+            return { content: [{ type: "text", text: ack }], details: { sourceId } };
+        },
+    };
+    const title = String(manifest.title || sourceId);
+    const userPrompt = `Synthesize this captured source into wiki knowledge by calling commit_synthesis once.\n\nSOURCE: ${title} (${sourceId})\n\nEXTRACTED CONTENT:\n${content}`;
+    await runSubAgent({
+        model,
+        apiKey,
+        headers,
+        systemPrompt: INGEST_SYSTEM,
+        userPrompt,
+        tools: [commitTool],
+        signal,
+    });
+    if (committed)
+        rebuildMetadataLight(paths);
+    return committed;
+}

package/dist/extensions/llm-wiki/lib/inject.js

@@ -0,0 +1,65 @@
+/**
+ * System-prompt context injection primitives (issues #87, #92).
+ *
+ * The `before_agent_start` hook augments the chained system prompt with a
+ * visible wiki-status footer. This module isolates that append so it can be
+ * unit-tested for idempotency — a turn that aborts (network error / ESC) and is
+ * retried can carry the prior injection forward, and a naive append stacks the
+ * footer 2x, 3x, ...
+ *
+ * It also owns the cache-safety split (issue #92): VOLATILE per-turn context
+ * (recall results, one-time topic-inference directive) must never enter the
+ * system prompt — that is the provider's primary cache prefix, so per-turn
+ * variation there forces a full cache miss every turn. Volatile content is
+ * routed into a tail conversation message instead. `buildAgentStartInjection`
+ * is the single, pure decision point for that split.
+ */
+/** The always-injected wiki-status footer (sans surrounding whitespace). */
+export const WIKI_STATUS_BLOCK = "<wiki_status>LLM Wiki active — use wiki_recall for deeper search, wiki_observe to record observations, wiki_retro to save insights.</wiki_status>";
+/**
+ * Append the wiki-status footer to a system prompt — idempotently (issue #87).
+ *
+ * Strips any already-present footer (with its leading blank line) before
+ * appending exactly one. This makes the injection safe across aborted/retried
+ * agent starts that carry the prior injection forward in the chained system
+ * prompt, so the footer never stacks (2x, 3x, ...).
+ * See test/inject-idempotent.test.ts.
+ */
+export function appendWikiStatus(systemPrompt) {
+    const base = systemPrompt.split(`\n\n${WIKI_STATUS_BLOCK}`).join("");
+    return `${base}\n\n${WIKI_STATUS_BLOCK}`;
+}
+/** Normalize upstream Pi and OMP system-prompt representations. */
+export function normalizeSystemPrompt(systemPrompt) {
+    if (Array.isArray(systemPrompt))
+        return systemPrompt.join("\n\n");
+    return typeof systemPrompt === "string" ? systemPrompt : "";
+}
+/** customType of the hidden tail message carrying volatile per-turn context. */
+export const WIKI_RECALL_MESSAGE_TYPE = "wiki-recall-context";
+/**
+ * Split a turn's injection into a cache-stable system prompt and a volatile
+ * tail message (issue #92).
+ *
+ * - `systemPrompt` is always `appendWikiStatus(baseSystemPrompt)` — the static
+ *   footer only. It carries NONE of `dynamicBlocks`, so it does not vary with
+ *   recall results and never breaks the provider cache prefix.
+ * - `dynamicBlocks` (recall context, topic-inference directive, ...) are
+ *   trimmed, emptied entries dropped, and joined with a blank line into the
+ *   message body. When nothing survives, no message is emitted.
+ *
+ * Pure and side-effect free — see test/agent-start-injection.test.ts.
+ */
+export function buildAgentStartInjection(baseSystemPrompt, dynamicBlocks) {
+    const systemPrompt = appendWikiStatus(normalizeSystemPrompt(baseSystemPrompt));
+    const content = dynamicBlocks
+        .map((b) => b?.trim())
+        .filter((b) => Boolean(b))
+        .join("\n\n");
+    if (!content)
+        return { systemPrompt };
+    return {
+        systemPrompt,
+        message: { customType: WIKI_RECALL_MESSAGE_TYPE, content, display: false },
+    };
+}