pi-vault-mind 0.7.0

package/dist/src/tools.js

@@ -0,0 +1,772 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { Type } from "typebox";
+import { graphUpsert, queryGraph } from "./graph.js";
+import { getStatus, searchFts, searchHybrid, upsertEntry, } from "./lance.js";
+import { collectionNames, ensureDir, findConfig, loadConfig } from "./utils.js";
+import { VaultWriter } from "./vault-writer.js";
+export const registerTools = (pi) => {
+    /* ── promote_wiki ── */
+    pi.registerTool({
+        name: "promote_wiki",
+        label: "Promote Wiki Entries",
+        description: "Promote entries from one collection to another via the pending queue for human approval.",
+        promptSnippet: 'promote_wiki(sourceCollection="research", targetCollection="main", entryIds=["id1"], reason="...")',
+        promptGuidelines: [
+            "Use when you find an insight in one collection that should be promoted to a more permanent one.",
+            'Stages entries in "pending" for human review. Does NOT append directly to target.',
+            "Provide a clear reason why these entries are worth promoting.",
+        ],
+        parameters: Type.Object({
+            sourceCollection: Type.String({ description: "Collection where entries currently reside" }),
+            targetCollection: Type.String({ description: "Collection where entries should be moved" }),
+            entryIds: Type.Array(Type.String(), { description: "List of entry IDs to promote" }),
+            reason: Type.String({ description: "Reason for promoting these entries" }),
+        }),
+        async execute(_id, params, _signal, _onUpdate, ctx) {
+            const cfg = loadConfig(ctx.cwd);
+            const sourceDef = cfg.collections[params.sourceCollection];
+            const targetDef = cfg.collections[params.targetCollection];
+            const pendingDef = cfg.collections.pending;
+            if (!sourceDef)
+                return {
+                    content: [
+                        { type: "text", text: `Unknown source collection "${params.sourceCollection}".` },
+                    ],
+                    details: {},
+                };
+            if (!targetDef)
+                return {
+                    content: [
+                        { type: "text", text: `Unknown target collection "${params.targetCollection}".` },
+                    ],
+                    details: {},
+                };
+            if (!pendingDef)
+                return {
+                    content: [{ type: "text", text: "Pending collection not configured. Run /wiki init." }],
+                    details: {},
+                };
+            if (!fs.existsSync(sourceDef.path))
+                return {
+                    content: [{ type: "text", text: `Source collection file missing at ${sourceDef.path}.` }],
+                    details: {},
+                };
+            const lines = fs.readFileSync(sourceDef.path, "utf-8").split("\n").filter(Boolean);
+            const entries = lines
+                .map((l) => {
+                try {
+                    return JSON.parse(l);
+                }
+                catch {
+                    return null;
+                }
+            })
+                .filter(Boolean);
+            const promotedIds = [];
+            for (const id of params.entryIds) {
+                const entry = entries.find((e) => e.id === id);
+                if (!entry)
+                    continue;
+                const promotionEntry = {
+                    ...entry,
+                    _promotion_target: params.targetCollection,
+                    _promotion_source: params.sourceCollection,
+                    _promotion_reason: params.reason,
+                    _promoted_at: new Date().toISOString(),
+                };
+                ensureDir(pendingDef.path);
+                fs.appendFileSync(pendingDef.path, `${JSON.stringify(promotionEntry)}\n`);
+                promotedIds.push(id);
+            }
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: promotedIds.length > 0
+                            ? `Staged ${promotedIds.length} entry(ies) for promotion from "${params.sourceCollection}" to "${params.targetCollection}". Use /wiki approve to finalize.`
+                            : `No matching entries found for IDs: ${params.entryIds.join(", ")}`,
+                    },
+                ],
+                details: {},
+            };
+        },
+    });
+    /* ── wiki_search ── */
+    pi.registerTool({
+        name: "wiki_search",
+        label: "Wiki Semantic Search",
+        description: "Semantic vector search across indexed wiki collections using LanceDB.",
+        promptSnippet: 'wiki_search(collection="main", query="...", limit=5)',
+        promptGuidelines: [
+            "Use wiki_search for natural-language semantic queries.",
+            "For exact keyword/phrase matching, use wiki_fts_search instead.",
+        ],
+        parameters: Type.Object({
+            collection: Type.String({ description: "Collection name (e.g. main)", default: "main" }),
+            query: Type.String({ description: "Natural-language search query" }),
+            limit: Type.Optional(Type.Number({ description: "Max results (default 5)" })),
+        }),
+        async execute(_id, params, _signal, _onUpdate, ctx) {
+            const cfg = loadConfig(ctx.cwd);
+            try {
+                const results = await searchHybrid(cfg.wiki.dataDir, params.collection, params.query, params.limit ?? 5, cfg.wiki);
+                return { content: [{ type: "text", text: JSON.stringify(results, null, 2) }], details: {} };
+            }
+            catch (error) {
+                return { content: [{ type: "text", text: `Error: ${error.message}` }], details: {} };
+            }
+        },
+    });
+    /* ── wiki_fts_search ── */
+    pi.registerTool({
+        name: "wiki_fts_search",
+        label: "Wiki Full-Text Search",
+        description: "Full-text keyword search (Tantivy BM25) across indexed wiki collections.",
+        promptSnippet: 'wiki_fts_search(collection="main", query="login", limit=5)',
+        promptGuidelines: [
+            "Use for exact keyword/phrase matching. For natural-language queries, use wiki_search instead.",
+        ],
+        parameters: Type.Object({
+            collection: Type.String({ description: "Collection name (e.g. main)", default: "main" }),
+            query: Type.String({ description: "Keyword or phrase for full-text search" }),
+            limit: Type.Optional(Type.Number({ description: "Max results (default 5)" })),
+        }),
+        async execute(_id, params, _signal, _onUpdate, ctx) {
+            const cfg = loadConfig(ctx.cwd);
+            try {
+                const results = await searchFts(cfg.wiki.dataDir, params.collection, params.query, params.limit ?? 5, cfg.wiki);
+                return { content: [{ type: "text", text: JSON.stringify(results, null, 2) }], details: {} };
+            }
+            catch (error) {
+                return { content: [{ type: "text", text: `Error: ${error.message}` }], details: {} };
+            }
+        },
+    });
+    /* ── wiki_graph_query ── */
+    pi.registerTool({
+        name: "wiki_graph_query",
+        label: "Wiki Graph Query",
+        description: "Traverse entity connections in the LanceDB graph tables.",
+        promptSnippet: 'wiki_graph_query(entity="Auth", depth=1)',
+        promptGuidelines: ["Use to find relations to a specific entity or concept."],
+        parameters: Type.Object({
+            entity: Type.String({ description: "Entity to search for relations" }),
+            depth: Type.Optional(Type.Number({ description: "Depth of traversal (default 1)" })),
+        }),
+        async execute(_id, params, _signal, _onUpdate, ctx) {
+            const cfg = loadConfig(ctx.cwd);
+            try {
+                const results = await queryGraph(cfg.wiki.dataDir, cfg.wiki, params.entity, params.depth ?? 1);
+                return { content: [{ type: "text", text: JSON.stringify(results, null, 2) }], details: {} };
+            }
+            catch (error) {
+                return { content: [{ type: "text", text: `Error: ${error.message}` }], details: {} };
+            }
+        },
+    });
+    /* ── wiki_sync ── */
+    pi.registerTool({
+        name: "wiki_sync",
+        label: "Wiki Sync to Vault",
+        description: "Push matching wiki entries to an Obsidian vault as markdown pages or canvas graph files.",
+        promptSnippet: 'wiki_sync(vault="default", query="tag:decision", collection="main")',
+        promptGuidelines: [
+            "Use to push agent knowledge to a human-readable Obsidian vault.",
+            'Omit vault to use the configured default vault. Use vault="*" for all configured vaults.',
+            'format="markdown" writes individual .md files. format="canvas" generates a .canvas graph file from entity relations.',
+        ],
+        parameters: Type.Object({
+            vault: Type.Optional(Type.String({
+                description: 'Vault name (defaults to "default"). Use "*" for all configured vaults.',
+            })),
+            query: Type.Optional(Type.String({ description: "Free-text search to select entries to sync" })),
+            tag: Type.Optional(Type.String({ description: "Sync entries matching this tag" })),
+            collection: Type.Optional(Type.String({ description: "Collection to sync from (default: main)" })),
+            format: Type.Optional(Type.Union([Type.Literal("markdown"), Type.Literal("canvas")], {
+                description: "Output format (default: markdown)",
+            })),
+            limit: Type.Optional(Type.Number({ description: "Max entries (default 20)" })),
+        }),
+        async execute(_id, params, _signal, _onUpdate, ctx) {
+            const cfg = loadConfig(ctx.cwd);
+            if (!cfg.wiki.vaults || Object.keys(cfg.wiki.vaults).length === 0) {
+                return {
+                    content: [
+                        { type: "text", text: "No vaults configured. Add vaults to wiki.vaults in config." },
+                    ],
+                    details: {},
+                };
+            }
+            const vaultNames = params.vault === "*" ? Object.keys(cfg.wiki.vaults) : [params.vault || "default"];
+            const results = [];
+            for (const vaultName of vaultNames) {
+                const vaultCfg = cfg.wiki.vaults[vaultName];
+                if (!vaultCfg) {
+                    results.push(`⚠️  Vault "${vaultName}" not configured.`);
+                    continue;
+                }
+                try {
+                    const writer = new VaultWriter(vaultCfg.path, cfg.wiki);
+                    if (params.format === "canvas") {
+                        const count = await writer.syncGraphToCanvas();
+                        results.push(`✅ Vault "${vaultName}": canvas graph synced (${count} edges)`);
+                    }
+                    else {
+                        const collection = params.collection || "main";
+                        const query = params.query || (params.tag ? `tag:${params.tag}` : "");
+                        const count = await writer.syncEntries(collection, query, params.limit ?? 20);
+                        results.push(`✅ Vault "${vaultName}": ${count} entries synced to Agent/Inbox/`);
+                    }
+                }
+                catch (err) {
+                    results.push(`❌ Vault "${vaultName}": ${err.message}`);
+                }
+            }
+            return { content: [{ type: "text", text: results.join("\n") }], details: {} };
+        },
+    });
+    /* ── query_wiki ── */
+    pi.registerTool({
+        name: "query_wiki",
+        label: "Query Wiki",
+        description: "Deterministic JSONL search by collection name. Use for exact lookups and filtered retrieval.",
+        promptSnippet: 'query_wiki(collection="main", query="...", filters={key: "value"})',
+        promptGuidelines: [
+            "Use when you know the collection name and need exact matches.",
+            "query does substring search across all text fields; filters does exact key-value matching.",
+            "If the collection is missing, run /wiki init first.",
+        ],
+        parameters: Type.Object({
+            collection: Type.String({ description: "Collection name (e.g. main, pending)" }),
+            query: Type.Optional(Type.String({ description: "Free-text substring search across all text fields" })),
+            filters: Type.Optional(Type.Record(Type.String(), Type.String(), { description: "Exact {field: value} matches" })),
+        }),
+        async execute(_id, params, _signal, _onUpdate, ctx) {
+            const cfg = loadConfig(ctx.cwd);
+            const def = cfg.collections[params.collection];
+            if (!def)
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Unknown collection "${params.collection}". Available: ${collectionNames(cfg).join(", ")}`,
+                        },
+                    ],
+                    details: {},
+                };
+            if (!fs.existsSync(def.path))
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Collection "${params.collection}" not found at ${def.path}. Run /wiki init.`,
+                        },
+                    ],
+                    details: {},
+                };
+            const lines = fs.readFileSync(def.path, "utf-8").split("\n").filter(Boolean);
+            const results = [];
+            for (const line of lines) {
+                try {
+                    const entry = JSON.parse(line);
+                    let match = true;
+                    if (params.query) {
+                        const text = def.schema
+                            .map((f) => entry[f] ?? "")
+                            .join(" ")
+                            .toLowerCase();
+                        match = text.includes(params.query.toLowerCase());
+                    }
+                    if (match && params.filters) {
+                        for (const [k, v] of Object.entries(params.filters)) {
+                            if (String(entry[k] ?? "") !== String(v)) {
+                                match = false;
+                                break;
+                            }
+                        }
+                    }
+                    if (match)
+                        results.push(entry);
+                }
+                catch {
+                    /* ignore malformed */
+                }
+            }
+            return { content: [{ type: "text", text: JSON.stringify(results, null, 2) }], details: {} };
+        },
+    });
+    /* ── append_wiki ── */
+    pi.registerTool({
+        name: "append_wiki",
+        label: "Append Wiki Entry",
+        description: "Append to a wiki collection. Autopilot dual-writes to JSONL + LanceDB with optional auto-sync to vault.",
+        promptSnippet: 'append_wiki(collection="main", mode="autopilot", entry={...})',
+        promptGuidelines: [
+            "Use autopilot for everyday notes — deduplicates automatically.",
+            "Use gated mode when the fact needs human review (queues in pending).",
+            "Use strict mode only for the most sensitive facts requiring explicit user confirmation.",
+            "Entry keys must match the collection schema. Call describe_wiki first if unsure.",
+            'When the user says "Remember: [fact]", automatically use append_wiki to store it.',
+            'Set sync="auto" to push substantial entries to configured vault(s).',
+        ],
+        parameters: Type.Object({
+            collection: Type.String({
+                description: "Target collection name (call describe_wiki if unsure)",
+            }),
+            mode: Type.Union([Type.Literal("strict"), Type.Literal("gated"), Type.Literal("autopilot")]),
+            entry: Type.Record(Type.String(), Type.String(), {
+                description: "Field-key → value map matching the collection schema",
+            }),
+            sync: Type.Optional(Type.Union([Type.Literal("auto"), Type.Literal("manual"), Type.Literal("none")], {
+                description: "Vault sync mode (default: auto)",
+            })),
+            vault: Type.Optional(Type.String({ description: "Specific vault to sync to (default: all configured)" })),
+        }),
+        async execute(_id, params, _signal, _onUpdate, ctx) {
+            const cfg = loadConfig(ctx.cwd);
+            const def = cfg.collections[params.collection];
+            if (!def)
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Unknown collection "${params.collection}". Available: ${collectionNames(cfg).join(", ")}`,
+                        },
+                    ],
+                    details: {},
+                };
+            const line = `${JSON.stringify(params.entry)}\n`;
+            if (params.mode === "strict") {
+                const ok = await ctx.ui.confirm("Strict Mode", `Approve entry for "${params.collection}"?\n\n${JSON.stringify(params.entry, null, 2)}`);
+                if (ok) {
+                    ensureDir(def.path);
+                    fs.appendFileSync(def.path, line);
+                    return {
+                        content: [{ type: "text", text: `Appended to "${params.collection}".` }],
+                        details: {},
+                    };
+                }
+                return { content: [{ type: "text", text: "Entry rejected." }], details: {} };
+            }
+            if (params.mode === "gated") {
+                const pending = cfg.collections.pending || def;
+                ensureDir(pending.path);
+                fs.appendFileSync(pending.path, line);
+                return { content: [{ type: "text", text: `Queued for "${pending.path}".` }], details: {} };
+            }
+            // autopilot
+            if (def.dedupField && fs.existsSync(def.path)) {
+                try {
+                    const results = await searchHybrid(cfg.wiki.dataDir, params.collection, params.entry[def.dedupField] || "", 1, cfg.wiki);
+                    if (results.length > 0 &&
+                        results[0][def.dedupField] === params.entry[def.dedupField]) {
+                        return {
+                            content: [
+                                { type: "text", text: `Duplicate detected via "${def.dedupField}". Skipped.` },
+                            ],
+                            details: {},
+                        };
+                    }
+                }
+                catch {
+                    /* ignore */
+                }
+            }
+            ensureDir(def.path);
+            fs.appendFileSync(def.path, line);
+            try {
+                await upsertEntry(cfg.wiki.dataDir, params.collection, params.entry, cfg.wiki);
+                if (cfg.wiki.graph?.enabled) {
+                    await graphUpsert(cfg.wiki.dataDir, cfg.wiki, params.entry);
+                }
+                // Auto-sync to vault if enabled
+                const syncMode = params.sync ?? "auto";
+                if (syncMode !== "none" && cfg.wiki.vaults && Object.keys(cfg.wiki.vaults).length > 0) {
+                    const entry = params.entry;
+                    const shouldSync = syncMode === "auto" || syncMode === "manual";
+                    const isSubstantial = (entry.fact || "").length > 200;
+                    const forceTag = entry.tag && ["decision", "insight", "requirement"].includes(entry.tag);
+                    if (shouldSync && (isSubstantial || forceTag)) {
+                        const vaultNames = params.vault ? [params.vault] : Object.keys(cfg.wiki.vaults);
+                        for (const vn of vaultNames) {
+                            const vc = cfg.wiki.vaults[vn];
+                            if (!vc)
+                                continue;
+                            try {
+                                const writer = new VaultWriter(vc.path, cfg.wiki);
+                                await writer.writeEntry(params.collection, entry);
+                            }
+                            catch {
+                                /* vault write is best-effort */
+                            }
+                        }
+                    }
+                    // Auto-sync canvas graph if enabled
+                    if (cfg.wiki.graph?.canvasSync &&
+                        cfg.wiki.graph?.enabled &&
+                        cfg.wiki.vaults &&
+                        Object.keys(cfg.wiki.vaults).length > 0) {
+                        for (const vn of params.vault ? [params.vault] : Object.keys(cfg.wiki.vaults)) {
+                            const vc = cfg.wiki.vaults[vn];
+                            if (!vc)
+                                continue;
+                            try {
+                                const writer = new VaultWriter(vc.path, cfg.wiki);
+                                await writer.syncGraphToCanvas();
+                            }
+                            catch {
+                                /* canvas sync is best-effort */
+                            }
+                        }
+                    }
+                }
+            }
+            catch (error) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Appended to "${params.collection}" (autopilot) but index failed: ${error.message}`,
+                        },
+                    ],
+                    details: {},
+                };
+            }
+            return {
+                content: [{ type: "text", text: `Appended to "${params.collection}" (autopilot).` }],
+                details: {},
+            };
+        },
+    });
+    /* ── configure_wiki ── */
+    pi.registerTool({
+        name: "configure_wiki",
+        label: "Configure Wiki",
+        description: "Read or update the pi-vault-mind config at runtime.",
+        promptSnippet: 'configure_wiki(action="read")',
+        promptGuidelines: [
+            'Use configure_wiki(action="read") to inspect current config.',
+            'Use configure_wiki(action="update", config={...}) to change schema, add collections, or modify vaults.',
+        ],
+        parameters: Type.Object({
+            action: Type.Union([Type.Literal("read"), Type.Literal("update")]),
+            config: Type.Optional(Type.Record(Type.String(), Type.Any(), { description: "Partial config object to merge" })),
+        }),
+        async execute(_id, params, _signal, _onUpdate, ctx) {
+            const cfgPath = findConfig(ctx.cwd).project || path.join(ctx.cwd, "pi-vault-mind.config.json");
+            if (params.action === "read" || !params.config) {
+                const cfg = loadConfig(ctx.cwd);
+                return { content: [{ type: "text", text: JSON.stringify(cfg, null, 2) }], details: {} };
+            }
+            let existing = {};
+            if (fs.existsSync(cfgPath)) {
+                try {
+                    existing = JSON.parse(fs.readFileSync(cfgPath, "utf-8"));
+                }
+                catch {
+                    /* fresh */
+                }
+            }
+            const merged = { ...existing, ...params.config };
+            ensureDir(cfgPath);
+            fs.writeFileSync(cfgPath, `${JSON.stringify(merged, null, 2)}\n`, "utf-8");
+            ctx.ui.notify?.(`Config updated: ${cfgPath}`, "info");
+            return { content: [{ type: "text", text: JSON.stringify(merged, null, 2) }], details: {} };
+        },
+    });
+    /* ── describe_wiki ── */
+    pi.registerTool({
+        name: "describe_wiki",
+        label: "Describe Wiki",
+        description: "Introspect a named collection: schema, entry count, and sample entries.",
+        promptSnippet: 'describe_wiki(collection="main")',
+        promptGuidelines: [
+            "Call before append_wiki if you are unsure what fields the collection expects.",
+        ],
+        parameters: Type.Object({
+            collection: Type.String({ description: "Collection name to inspect" }),
+        }),
+        async execute(_id, params, _signal, _onUpdate, ctx) {
+            const cfg = loadConfig(ctx.cwd);
+            const def = cfg.collections[params.collection];
+            if (!def)
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Unknown collection "${params.collection}". Available: ${collectionNames(cfg).join(", ")}`,
+                        },
+                    ],
+                    details: {},
+                };
+            if (!fs.existsSync(def.path))
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Collection "${params.collection}" not found at ${def.path}. Run /wiki init.`,
+                        },
+                    ],
+                    details: {},
+                };
+            const lines = fs.readFileSync(def.path, "utf-8").split("\n").filter(Boolean);
+            const total = lines.length;
+            let first = null;
+            let last = null;
+            let malformed = 0;
+            for (const line of lines) {
+                try {
+                    const e = JSON.parse(line);
+                    if (!first)
+                        first = e;
+                    last = e;
+                }
+                catch {
+                    malformed++;
+                }
+            }
+            const report = [
+                `Collection: "${params.collection}"`,
+                `Path: ${def.path}`,
+                `Schema: [${def.schema.join(", ")}]`,
+                `Total entries: ${total}`,
+                malformed ? `Malformed lines: ${malformed}` : "",
+                `DedupField: ${def.dedupField ?? "(none)"}`,
+                "",
+                "First entry:",
+                JSON.stringify(first, null, 2),
+                "",
+                "Most recent entry:",
+                JSON.stringify(last, null, 2),
+            ]
+                .filter(Boolean)
+                .join("\n");
+            return { content: [{ type: "text", text: report }], details: {} };
+        },
+    });
+    /* ── wiki_stats ── */
+    pi.registerTool({
+        name: "wiki_stats",
+        label: "Wiki Stats",
+        description: "Dashboard of all collections: counts, sizes, pending queue size, and LanceDB health.",
+        promptSnippet: "wiki_stats()",
+        promptGuidelines: ["Call for a quick overview before writing or after a batch of appends."],
+        parameters: Type.Object({}),
+        async execute(_id, _params, _signal, _onUpdate, ctx) {
+            const cfg = loadConfig(ctx.cwd);
+            const lines = [
+                "pi-vault-mind Stats",
+                `Config path: project=${findConfig(ctx.cwd).project || "(none)"}, global=${findConfig(ctx.cwd).global || "(none)"}`,
+                "",
+                `LanceDB DataDir: ${cfg.wiki.dataDir}`,
+                `Injectors: ${cfg.injectors.length}`,
+                "",
+            ];
+            for (const [name, def] of Object.entries(cfg.collections)) {
+                let count = 0;
+                let malformed = 0;
+                if (fs.existsSync(def.path)) {
+                    const data = fs.readFileSync(def.path, "utf-8").split("\n").filter(Boolean);
+                    for (const line of data) {
+                        try {
+                            JSON.parse(line);
+                            count++;
+                        }
+                        catch {
+                            malformed++;
+                        }
+                    }
+                }
+                const size = fs.existsSync(def.path) ? `${fs.statSync(def.path).size} bytes` : "missing";
+                lines.push(`  "${name}"`, `    → ${def.path}`, `    Schema: [${def.schema.join(", ")}]`, `    Entries: ${count} entries, ${size}${malformed ? `, ${malformed} malformed` : ""}`);
+                if (def.dedupField)
+                    lines.push(`    DedupField: ${def.dedupField}`);
+            }
+            return { content: [{ type: "text", text: lines.join("\n") }], details: {} };
+        },
+    });
+    /* ── wiki_export ── */
+    pi.registerTool({
+        name: "wiki_export",
+        label: "Wiki Export",
+        description: "Export a collection to JSON, CSV, or Markdown.",
+        promptSnippet: 'wiki_export(collection="main", format="json")',
+        promptGuidelines: [
+            "Use to share, archive, or import wiki data elsewhere. Schema keys become column headers for CSV/Markdown.",
+        ],
+        parameters: Type.Object({
+            collection: Type.String({ description: "Collection name to export" }),
+            format: Type.Union([Type.Literal("json"), Type.Literal("csv"), Type.Literal("markdown")], {
+                description: "Export format (default json)",
+            }),
+        }),
+        async execute(_id, params, _signal, _onUpdate, ctx) {
+            const cfg = loadConfig(ctx.cwd);
+            const def = cfg.collections[params.collection];
+            if (!def)
+                return {
+                    content: [{ type: "text", text: `Unknown collection "${params.collection}".` }],
+                    details: {},
+                };
+            if (!fs.existsSync(def.path))
+                return {
+                    content: [{ type: "text", text: `Collection "${params.collection}" not found.` }],
+                    details: {},
+                };
+            const lines = fs.readFileSync(def.path, "utf-8").split("\n").filter(Boolean);
+            const entries = [];
+            for (const line of lines) {
+                try {
+                    entries.push(JSON.parse(line));
+                }
+                catch {
+                    /* skip malformed */
+                }
+            }
+            let text = "";
+            const format = params.format || "json";
+            if (format === "json") {
+                text = JSON.stringify(entries, null, 2);
+            }
+            else {
+                const schemaKeys = def.schema.length
+                    ? def.schema
+                    : entries[0]
+                        ? Object.keys(entries[0])
+                        : [];
+                const escCsv = (s) => `"${String(s ?? "").replace(/"/g, '""')}"`;
+                if (format === "csv") {
+                    text = [
+                        schemaKeys.map(escCsv).join(","),
+                        ...entries.map((e) => schemaKeys.map((k) => escCsv(e[k])).join(",")),
+                    ].join("\n");
+                }
+                else {
+                    const esc = (s) => String(s ?? "")
+                        .replace(/\|/g, "\\|")
+                        .replace(/\n/g, " ");
+                    text = [
+                        `| ${schemaKeys.join(" | ")} |`,
+                        `| ${schemaKeys.map(() => "---").join(" | ")} |`,
+                        ...entries.map((e) => `| ${schemaKeys.map((k) => esc(e[k])).join(" | ")} |`),
+                    ].join("\n");
+                }
+            }
+            return { content: [{ type: "text", text }], details: {} };
+        },
+    });
+    /* ── wiki_ingest ── */
+    pi.registerTool({
+        name: "wiki_ingest",
+        label: "Wiki Ingest",
+        description: "Ingest documents (URLs, HTML, PDFs) into the wiki. Converts to clean markdown via any2md, then returns the text for entity extraction and append_wiki.",
+        promptSnippet: 'wiki_ingest(source="https://arxiv.org/abs/...", collection="main")',
+        promptGuidelines: [
+            "Use to convert external documents into wiki-ready markdown.",
+            "Accepts URLs (https://...), local file paths, or raw text blobs.",
+            "When source is a URL, calls any2md to fetch and convert to markdown.",
+            "When source is a file path, reads the file directly (use any2md via bash for PDFs/DOCX).",
+            "Returns the converted markdown — you then call append_wiki for extracted facts.",
+        ],
+        parameters: Type.Object({
+            source: Type.String({ description: "URL, file path, or raw text to ingest" }),
+            sourceType: Type.Optional(Type.Union([Type.Literal("url"), Type.Literal("file"), Type.Literal("text")], {
+                description: "Source type (auto-detected if omitted)",
+            })),
+        }),
+        async execute(_id, params, _signal, _onUpdate, ctx) {
+            const source = params.source;
+            let sourceType = params.sourceType;
+            // Auto-detect source type
+            if (!sourceType) {
+                if (source.startsWith("http://") || source.startsWith("https://")) {
+                    sourceType = "url";
+                }
+                else if (fs.existsSync(source)) {
+                    sourceType = "file";
+                }
+                else {
+                    sourceType = "text";
+                }
+            }
+            let markdown = "";
+            try {
+                if (sourceType === "url") {
+                    // Use any2md via npx to fetch and convert
+                    const cwd = path.dirname(source) === "." ? ctx.cwd : ctx.cwd;
+                    try {
+                        const result = await pi.exec("npx", ["-y", "any2md", source], { cwd, timeout: 60000 });
+                        markdown = result.stdout || result.stderr || "";
+                        if (!markdown.trim()) {
+                            return {
+                                content: [{ type: "text", text: `any2md returned empty output for ${source}` }],
+                                details: {},
+                            };
+                        }
+                    }
+                    catch (err) {
+                        return {
+                            content: [
+                                {
+                                    type: "text",
+                                    text: `any2md failed: ${err.message || err}. Try installing: npm install -g any2md`,
+                                },
+                            ],
+                            details: {},
+                        };
+                    }
+                }
+                else if (sourceType === "file") {
+                    // Read the file directly
+                    try {
+                        markdown = fs.readFileSync(source, "utf-8");
+                    }
+                    catch (err) {
+                        return {
+                            content: [{ type: "text", text: `Cannot read file: ${err.message}` }],
+                            details: {},
+                        };
+                    }
+                }
+                else {
+                    // Raw text — passthrough
+                    markdown = source;
+                }
+                const lines = markdown.split("\n");
+                const preview = lines.slice(0, 20).join("\n");
+                const truncated = lines.length > 20 ? markdown : markdown;
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Ingested from ${sourceType}: ${source}\nLines: ${lines.length}\n\n--- PREVIEW (first 20 lines) ---\n${preview}${lines.length > 20 ? "\n... (truncated, full text available via read)" : ""}\n\n--- FULL TEXT ---\n${truncated}`,
+                        },
+                    ],
+                    details: { sourceType, source, lineCount: lines.length },
+                };
+            }
+            catch (error) {
+                return { content: [{ type: "text", text: `Ingest error: ${error.message}` }], details: {} };
+            }
+        },
+    });
+    /* ── wiki_status ── */
+    pi.registerTool({
+        name: "wiki_status",
+        label: "Wiki Status",
+        description: "Show LanceDB status: data directory and tables.",
+        promptSnippet: "wiki_status()",
+        parameters: Type.Object({}),
+        async execute(_id, _params, _signal, _onUpdate, ctx) {
+            const cfg = loadConfig(ctx.cwd);
+            try {
+                const status = await getStatus(cfg.wiki.dataDir);
+                return { content: [{ type: "text", text: JSON.stringify(status, null, 2) }], details: {} };
+            }
+            catch (error) {
+                return { content: [{ type: "text", text: `Error: ${error.message}` }], details: {} };
+            }
+        },
+    });
+};