@zosmaai/pi-llm-wiki 0.10.9 → 0.11.1

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

@@ -0,0 +1,128 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { readJson } from "./utils.js";
+import { compareCodePoint, discoverKnowledgeDocuments, inspectVaultFormat, } from "./vault-format.js";
+/**
+ * Search the registry for matching concepts.
+ *
+ * Matches ID, semantic title, type, category, domain, tags, aliases, and recall triggers.
+ * Preserves unknown types as strings.
+ */
+export function searchRegistry(paths, query, typeFilter) {
+    const diagnostics = [];
+    const vaultState = inspectVaultFormat(paths);
+    diagnostics.push(...vaultState.diagnostics);
+    const registryPath = join(paths.meta, "registry.json");
+    if (!existsSync(registryPath)) {
+        return { matches: [], diagnostics };
+    }
+    const registry = readJson(registryPath, {
+        version: "1.0",
+        last_updated: "",
+        pages: {},
+    });
+    const normalizedQuery = query.toLowerCase();
+    const matches = [];
+    for (const [id, entry] of Object.entries(registry.pages)) {
+        // Apply type filter
+        if (typeFilter && String(entry.type).toLowerCase() !== typeFilter.toLowerCase()) {
+            continue;
+        }
+        // Check if query matches any searchable field
+        if (matchesField(id, entry, normalizedQuery)) {
+            matches.push({
+                id,
+                title: String(entry.title || id),
+                type: String(entry.type || "unknown"),
+            });
+        }
+    }
+    // Sort by code point order for determinism
+    matches.sort((a, b) => compareCodePoint(a.id, b.id));
+    return { matches, diagnostics };
+}
+function matchesField(id, entry, query) {
+    // Match ID
+    if (id.toLowerCase().includes(query))
+        return true;
+    // Match title
+    if (String(entry.title || "")
+        .toLowerCase()
+        .includes(query))
+        return true;
+    // Match type
+    if (String(entry.type || "")
+        .toLowerCase()
+        .includes(query))
+        return true;
+    // Match category/domain
+    if (String(entry.category || "")
+        .toLowerCase()
+        .includes(query))
+        return true;
+    if (String(entry.domain || "")
+        .toLowerCase()
+        .includes(query))
+        return true;
+    // Match tags (array or string)
+    const tags = entry.tags;
+    if (Array.isArray(tags)) {
+        if (tags.some((t) => String(t).toLowerCase().includes(query)))
+            return true;
+    }
+    else if (typeof tags === "string" && tags.toLowerCase().includes(query)) {
+        return true;
+    }
+    // Match aliases (array or string)
+    const aliases = entry.aliases;
+    if (Array.isArray(aliases)) {
+        if (aliases.some((a) => String(a).toLowerCase().includes(query)))
+            return true;
+    }
+    else if (typeof aliases === "string" && aliases.toLowerCase().includes(query)) {
+        return true;
+    }
+    // Match recall_triggers (array or string)
+    const triggers = entry.recall_triggers;
+    if (Array.isArray(triggers)) {
+        if (triggers.some((t) => String(t).toLowerCase().includes(query)))
+            return true;
+    }
+    else if (typeof triggers === "string" && triggers.toLowerCase().includes(query)) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Get a status snapshot of the wiki.
+ *
+ * Reports resolved knowledge_format, page counts, and blocking diagnostics.
+ */
+export function getWikiStatus(paths) {
+    const vaultState = inspectVaultFormat(paths);
+    const diagnostics = [...vaultState.diagnostics];
+    // Also check discovery for current concept health
+    const discovery = discoverKnowledgeDocuments(paths);
+    diagnostics.push(...discovery.diagnostics);
+    const registryPath = join(paths.meta, "registry.json");
+    let registry;
+    if (existsSync(registryPath)) {
+        registry = readJson(registryPath, { version: "1.0", last_updated: "", pages: {} });
+    }
+    const byType = {};
+    let totalPages = 0;
+    if (registry) {
+        for (const entry of Object.values(registry.pages)) {
+            totalPages++;
+            const type = String(entry.type || "unknown");
+            byType[type] = (byType[type] || 0) + 1;
+        }
+    }
+    return {
+        knowledgeFormat: vaultState.knowledgeFormat,
+        totalPages,
+        byType,
+        blockingDiagnostics: diagnostics.filter((d) => d.severity === "error"),
+        lastUpdated: registry?.last_updated || "",
+    };
+}

package/dist/mcp/exec.js

@@ -0,0 +1,121 @@
+import { execFile, spawn } from "node:child_process";
+const MAX_OUTPUT_BYTES = 16 * 1024 * 1024;
+export function createExecApi() {
+    return {
+        exec(command, args, options = {}) {
+            return new Promise((resolve) => {
+                let killed = false;
+                let settled = false;
+                let stdoutLimited = false;
+                let stderrLimited = false;
+                let forceTimer;
+                let stdout = "";
+                let stderr = "";
+                const child = spawn(command, args, {
+                    cwd: options.cwd,
+                    stdio: ["ignore", "pipe", "pipe"],
+                    detached: process.platform !== "win32",
+                });
+                const sendSignal = (signal) => {
+                    if (process.platform === "win32" && child.pid) {
+                        execFile("taskkill", ["/pid", String(child.pid), "/T", "/F"], () => { });
+                        return;
+                    }
+                    if (child.pid) {
+                        try {
+                            process.kill(-child.pid, signal);
+                            return;
+                        }
+                        catch {
+                            // Fall back to the direct child when process-group signalling fails.
+                        }
+                    }
+                    child.kill(signal);
+                };
+                const forceStop = () => {
+                    if (forceTimer)
+                        clearTimeout(forceTimer);
+                    forceTimer = undefined;
+                    sendSignal("SIGKILL");
+                };
+                const stop = () => {
+                    if (killed)
+                        return;
+                    killed = true;
+                    sendSignal("SIGTERM");
+                    if (process.platform !== "win32")
+                        forceTimer = setTimeout(forceStop, 100);
+                };
+                const appendOutput = (current, chunk, limited) => {
+                    if (limited)
+                        return [current, true];
+                    const remaining = MAX_OUTPUT_BYTES - Buffer.byteLength(current);
+                    if (remaining <= 0) {
+                        stop();
+                        return [current, true];
+                    }
+                    const bytes = Buffer.from(chunk);
+                    if (bytes.byteLength <= remaining)
+                        return [current + chunk, false];
+                    stop();
+                    let prefix = "";
+                    let prefixBytes = 0;
+                    for (const char of chunk) {
+                        const charBytes = Buffer.byteLength(char);
+                        if (prefixBytes + charBytes > remaining)
+                            break;
+                        prefix += char;
+                        prefixBytes += charBytes;
+                    }
+                    return [current + prefix, true];
+                };
+                child.stdout?.setEncoding("utf8");
+                child.stderr?.setEncoding("utf8");
+                child.stdout?.on("data", (chunk) => {
+                    [stdout, stdoutLimited] = appendOutput(stdout, chunk, stdoutLimited);
+                });
+                child.stderr?.on("data", (chunk) => {
+                    [stderr, stderrLimited] = appendOutput(stderr, chunk, stderrLimited);
+                });
+                const timer = options.timeout ? setTimeout(stop, options.timeout) : undefined;
+                const abort = () => stop();
+                options.signal?.addEventListener("abort", abort, { once: true });
+                const finish = (code) => {
+                    if (settled)
+                        return;
+                    if (forceTimer) {
+                        clearTimeout(forceTimer);
+                        forceTimer = undefined;
+                        if (child.pid) {
+                            try {
+                                process.kill(-child.pid, "SIGKILL");
+                            }
+                            catch {
+                                // The process group already exited; do not signal the closed child's stale PID.
+                            }
+                        }
+                    }
+                    cleanup();
+                    resolve({
+                        stdout,
+                        stderr,
+                        code: stdoutLimited || stderrLimited ? 1 : killed && code === 0 ? 1 : code,
+                        killed,
+                    });
+                };
+                child.once("error", () => finish(1));
+                child.once("close", (code) => finish(typeof code === "number" ? code : 1));
+                function cleanup() {
+                    settled = true;
+                    if (timer)
+                        clearTimeout(timer);
+                    if (forceTimer)
+                        clearTimeout(forceTimer);
+                    options.signal?.removeEventListener("abort", abort);
+                }
+                if (options.signal?.aborted)
+                    stop();
+            });
+        },
+    };
+}

package/dist/mcp/index.js

@@ -0,0 +1,229 @@
+#!/usr/bin/env node
+/**
+ * LLM Wiki MCP Server
+ *
+ * Exposes wiki tools over the Model Context Protocol (MCP).
+ * Run: node dist/mcp/index.js
+ *
+ * Environment:
+ *   WIKI_ROOT — path to wiki vault (default: auto-detect from cwd)
+ */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { McpServer, StdioServerTransport } from "@modelcontextprotocol/server";
+import * as z from "zod/v4";
+import { resolveVaultPaths } from "../extensions/llm-wiki/lib/utils.js";
+import { createExecApi } from "./exec.js";
+import { captureSourceOperation, recallOperation, retroOperation, searchOperation, statusOperation, } from "./operations.js";
+const execApi = createExecApi();
+// ─── Vault Detection ────────────────────────────────────
+/** Resolve vault paths, same as Pi extension. */
+function getPaths() {
+    const root = process.env.WIKI_ROOT || process.cwd();
+    return resolveVaultPaths(root);
+}
+function hasVault() {
+    const paths = getPaths();
+    return existsSync(join(paths.dotWiki, "config.json"));
+}
+// ─── MCP Server ─────────────────────────────────────────
+const server = new McpServer({
+    name: "llm-wiki",
+    version: "1.0.0",
+});
+// ---- wiki_recall ----
+server.registerTool("wiki_recall", {
+    description: "Search the wiki for pages relevant to a query. Returns matching page IDs, titles, types, and content previews.",
+    inputSchema: z.object({
+        query: z.string().describe("Search query — use the user's full request or key terms"),
+        max_results: z.number().optional().default(5).describe("Max results (default: 5, max: 10)"),
+    }),
+}, async ({ query, max_results }) => {
+    if (!hasVault()) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "No wiki vault found. Set WIKI_ROOT or run wiki_bootstrap first.",
+                },
+            ],
+            isError: true,
+        };
+    }
+    const paths = getPaths();
+    const result = await recallOperation(paths, query, Math.min(max_results ?? 5, 10));
+    const detailLines = result.diagnostics.map((d) => `⚠️ ${d.code}: ${d.message}`);
+    const detailText = detailLines.length > 0 ? `\n\n${detailLines.join("\n")}` : "";
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(result.results, null, 2) + detailText,
+            },
+        ],
+    };
+});
+// ---- wiki_search ----
+server.registerTool("wiki_search", {
+    description: "Search the wiki registry for pages matching a query.",
+    inputSchema: z.object({
+        query: z.string().describe("Search term"),
+        type: z
+            .string()
+            .optional()
+            .describe("Filter by page type (source, entity, concept, synthesis, analysis)"),
+    }),
+}, async ({ query, type }) => {
+    if (!hasVault()) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "No wiki vault found. Set WIKI_ROOT or run wiki_bootstrap first.",
+                },
+            ],
+            isError: true,
+        };
+    }
+    const paths = getPaths();
+    const result = await searchOperation(paths, query, type);
+    if (result.matches.length === 0) {
+        return {
+            content: [{ type: "text", text: `No pages found for "${query}"` }],
+        };
+    }
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(result.matches, null, 2),
+            },
+        ],
+    };
+});
+// ---- wiki_status ----
+server.registerTool("wiki_status", {
+    description: "Show wiki health and stats: page counts, orphans, recent activity.",
+    inputSchema: z.object({}),
+}, async () => {
+    if (!hasVault()) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "No wiki vault found. Set WIKI_ROOT or run wiki_bootstrap first.",
+                },
+            ],
+            isError: true,
+        };
+    }
+    const paths = getPaths();
+    const status = await statusOperation(paths);
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(status, null, 2),
+            },
+        ],
+    };
+});
+// ---- wiki_retro ----
+server.registerTool("wiki_retro", {
+    description: "Save an atomic insight from a completed task into the wiki. Creates a source page.",
+    inputSchema: z.object({
+        slug: z.string().describe("Unique kebab-case identifier (e.g. 'jwt-revocation-pattern')"),
+        title: z.string().describe("Short descriptive title (60 chars max)"),
+        body: z.string().describe("Markdown body explaining what was learned."),
+        category: z
+            .string()
+            .optional()
+            .describe("Category (e.g. frontend, architecture, devops, bugfix)"),
+    }),
+}, async ({ slug, title, body, category }) => {
+    if (!hasVault()) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "No wiki vault found. Set WIKI_ROOT or run wiki_bootstrap first.",
+                },
+            ],
+            isError: true,
+        };
+    }
+    const paths = getPaths();
+    const result = await retroOperation(paths, slug, title, body, category);
+    if (!result.ok) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Vault error: ${result.diagnostics[0].message}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+    return {
+        content: [
+            {
+                type: "text",
+                text: `Insight saved: ${result.slug} — ${title}`,
+            },
+        ],
+    };
+});
+// ---- wiki_capture_source ----
+server.registerTool("wiki_capture_source", {
+    description: "Capture a URL, local file, or pasted text into an immutable source packet.",
+    inputSchema: z.object({
+        text: z.string().optional().describe("Text content to capture"),
+        url: z.string().optional().describe("URL to capture"),
+        file_path: z.string().optional().describe("Local file path to capture"),
+        title: z.string().optional().describe("Title for the captured source"),
+    }),
+}, async ({ text, url, file_path, title }) => {
+    if (!hasVault()) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "No wiki vault found. Set WIKI_ROOT or run wiki_bootstrap first.",
+                },
+            ],
+            isError: true,
+        };
+    }
+    const paths = getPaths();
+    const result = await captureSourceOperation(paths, { text, url, filePath: file_path, title }, execApi);
+    if (!result.ok) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: result.diagnostics[0].message,
+                },
+            ],
+            isError: true,
+        };
+    }
+    return {
+        content: [
+            {
+                type: "text",
+                text: `Source captured: ${result.sourceId}`,
+            },
+        ],
+    };
+});
+// ─── Main ───────────────────────────────────────────────
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("🧠 LLM Wiki MCP Server running on stdio");
+}
+main().catch((err) => {
+    console.error("MCP Server error:", err);
+    process.exit(1);
+});

package/dist/mcp/operations.js

@@ -0,0 +1,130 @@
+/**
+ * MCP operation adapters over shared wiki services.
+ *
+ * Each operation is a thin, testable wrapper around the same services
+ * used by Pi tools. No operation parses YAML, scans files, scores
+ * registry entries, or builds page strings itself.
+ */
+import { rebuildMetadata } from "../extensions/llm-wiki/lib/metadata.js";
+import { searchWiki } from "../extensions/llm-wiki/lib/recall.js";
+import { saveInsight } from "../extensions/llm-wiki/lib/retro.js";
+import { captureFile, captureText, captureUrl } from "../extensions/llm-wiki/lib/source-packet.js";
+import { VaultWriteError, inspectVaultFormat, inspectWritableVault, } from "../extensions/llm-wiki/lib/vault-format.js";
+import { getWikiStatus, searchRegistry } from "../extensions/llm-wiki/lib/wiki-service.js";
+function projectionOutcome(projection) {
+    return projection.ok
+        ? { ok: true }
+        : {
+            ok: false,
+            diagnostics: projection.diagnostics.map(({ code, message }) => ({ code, message })),
+        };
+}
+/** Shared recall operation: calls searchWiki and appends vault diagnostics. */
+export async function recallOperation(paths, query, maxResults = 5) {
+    const results = searchWiki(paths, query, maxResults);
+    const vaultState = inspectVaultFormat(paths);
+    return {
+        results,
+        diagnostics: vaultState.diagnostics.map((d) => ({ code: d.code, message: d.message })),
+    };
+}
+/** Shared search operation: delegates directly to wiki-service. */
+export async function searchOperation(paths, query, type) {
+    const result = searchRegistry(paths, query, type);
+    return {
+        matches: result.matches,
+        diagnostics: result.diagnostics.map((d) => ({ code: d.code, message: d.message })),
+    };
+}
+/** Shared status operation: delegates directly to wiki-service. */
+export async function statusOperation(paths) {
+    const status = getWikiStatus(paths);
+    return {
+        knowledgeFormat: status.knowledgeFormat,
+        totalPages: status.totalPages,
+        byType: status.byType,
+        blockingDiagnostics: status.blockingDiagnostics.map((d) => ({
+            code: d.code,
+            message: d.message,
+        })),
+        lastUpdated: status.lastUpdated,
+    };
+}
+/** Shared retro operation: validates vault then delegates to saveInsight. */
+export async function retroOperation(paths, slug, title, body, category) {
+    const vaultCheck = inspectWritableVault(paths);
+    if (!vaultCheck.ok) {
+        return {
+            ok: false,
+            diagnostics: vaultCheck.diagnostics.map((d) => ({ code: d.code, message: d.message })),
+        };
+    }
+    try {
+        const result = saveInsight(paths, slug, title, body, category, { rebuild: false });
+        const projection = projectionOutcome(rebuildMetadata(paths));
+        if (!projection.ok)
+            return projection;
+        return { ok: true, slug: result.slug, sourcePagePath: result.sourcePagePath };
+    }
+    catch (error) {
+        if (error instanceof VaultWriteError) {
+            return {
+                ok: false,
+                diagnostics: error.diagnostics.map((d) => ({ code: d.code, message: d.message })),
+            };
+        }
+        if (error.message.startsWith("Invalid insight slug:")) {
+            return {
+                ok: false,
+                diagnostics: [{ code: "invalid_insight_slug", message: error.message }],
+            };
+        }
+        throw error;
+    }
+}
+/** Shared capture operation: validates vault then delegates to capture functions. */
+export async function captureSourceOperation(paths, input, execApi) {
+    const vaultCheck = inspectWritableVault(paths);
+    if (!vaultCheck.ok) {
+        return {
+            ok: false,
+            diagnostics: vaultCheck.diagnostics.map((d) => ({ code: d.code, message: d.message })),
+        };
+    }
+    try {
+        let sourceId;
+        if (input.url) {
+            sourceId = (await captureUrl(execApi, paths, input.url)).sourceId;
+        }
+        else if (input.filePath) {
+            sourceId = (await captureFile(execApi, paths, input.filePath)).sourceId;
+        }
+        else if (input.text) {
+            sourceId = captureText(paths, input.text, input.title).sourceId;
+        }
+        else {
+            return {
+                ok: false,
+                diagnostics: [
+                    {
+                        code: "event_missing_kind",
+                        message: "Provide one of: text, url, or filePath",
+                    },
+                ],
+            };
+        }
+        const projection = projectionOutcome(rebuildMetadata(paths));
+        if (!projection.ok)
+            return projection;
+        return { ok: true, sourceId };
+    }
+    catch (error) {
+        if (error instanceof VaultWriteError) {
+            return {
+                ok: false,
+                diagnostics: error.diagnostics.map((d) => ({ code: d.code, message: d.message })),
+            };
+        }
+        throw error;
+    }
+}

package/dist/package.json

@@ -0,0 +1 @@
+{"type":"module"}

package/docs/api.md

@@ -280,6 +280,8 @@ Health is `"⚠️ Warning"` when orphan count exceeds 5, `"🔴 Empty"` when th
 Force a full synchronous rebuild of all generated metadata: `registry.json`, `backlinks.json`,
 `index.md`, `log.md`. Use when metadata appears out of sync with actual wiki files.
 
+If `meta/events.jsonl` is missing or unreadable, rebuild reports a warning and preserves existing log projections while continuing to rebuild registry, backlinks, and indexes. A present zero-byte event file is an intentional empty history.
+
 **Parameters**
 
 None.
@@ -294,8 +296,9 @@ details: { pageCount: number }
 
 ## wiki_log_event
 
-Append a structured event to `meta/events.jsonl` and regenerate `meta/log.md`. Every event is
-timestamped automatically.
+Append a structured event to the authoritative, append-only `meta/events.jsonl` stream and regenerate available log projections. Every event is timestamped automatically. The event stream must be preserved in full-vault backups; generated Markdown logs cannot reconstruct it.
+
+`details` is user-controlled and may appear in OKF-mode `wiki/log.md`. Do not include secrets, credentials, or private machine-local paths. Built-in local-file capture records its stable source ID and format in events, omitting the caller-supplied input path from the event stream and generated log projections. The exact path remains in the extension-owned raw manifest. Other wiki projections are not covered by this guarantee: extraction-failure text and source-page titles may still surface path-derived strings, so treat the source page area as potentially machine-local until a dedicated sanitization pass exists.
 
 **Parameters**
 

package/docs/architecture.md

@@ -55,7 +55,7 @@ WIKI_ROOT/
     │   ├── analyses/          # Durable query answers
     │   ├── cases/             # One specific past task per trajectory
     │   └── skills/            # Reusable patterns distilled from trajectories
-    ├── meta/                  # Auto-generated (extension-owned)
+    ├── meta/                  # Durable event source + generated internal projections
     │   ├── registry.json      # Master page catalog
     │   ├── backlinks.json     # Inbound link map
     │   ├── index.md           # Human-readable catalog
@@ -73,9 +73,12 @@ WIKI_ROOT/
 | --------------------- | ------------------------ | ------------------------ |
 | `.llm-wiki/raw/**`    | Extension                | Immutable after capture  |
 | `.llm-wiki/wiki/**`   | Model + user             | Editable knowledge pages |
-| `.llm-wiki/meta/**`   | Extension                | Auto-generated           |
+| `.llm-wiki/meta/events.jsonl` | Extension tools | Authoritative, append-only; preserve in full-vault backups |
+| `.llm-wiki/meta/**` except `events.jsonl` | Extension | Generated projections |
 | `.llm-wiki/` | Human + explicit request | Operating rules          |
 
+`events.jsonl` records selected extension operations, not every filesystem edit. `meta/log.md` and OKF-mode `wiki/log.md` are one-way projections; neither can recover the event stream.
+
 ## Source Packet Format
 
 Each captured source becomes a packet:

package/docs/configuration.md

@@ -32,6 +32,31 @@ The personal vault lives at `~/.llm-wiki/` (or `$WIKI_HOME`) and is always avail
 | `WIKI_HOME`                   | `~/.llm-wiki` | Override the personal wiki vault location     |
 | `WIKI_MARKITDOWN_TIMEOUT_MS` | 180000      | Timeout (ms) for MarkItDown PDF/text extraction |
 
+## Pi Agent Settings
+
+Runtime settings for the wiki's background tasks live in `.pi/settings.json` under the `llm-wiki` namespace. These can be set globally (`~/.pi/agent/settings.json`) or per-project (`<cwd>/.pi/settings.json`).
+
+| Setting               | Default | Description                                                  |
+| --------------------- | ------- | ------------------------------------------------------------ |
+| `taskModel`           | —       | Model for background tasks (`{ provider: "openai", id: "gpt-4o" }`) |
+| `synthesisLanguage`   | —       | BCP 47 language tag for ingest synthesis (e.g. `"ru"`, `"fr"`). When unset, synthesis defaults to English. |
+| `trajectories`        | false   | Enable agent-trajectory working-memory                       |
+| `notices`             | true    | Show wiki activity notices in chat                           |
+
+Example:
+
+```json
+{
+  "llm-wiki": {
+    "synthesisLanguage": "ru",
+    "taskModel": {
+      "provider": "openai",
+      "id": "gpt-4o"
+    }
+  }
+}
+```
+
 ## Vault Resolution
 
 The vault root is resolved in this priority order: