@zosmaai/pi-llm-wiki 0.8.2 → 0.9.1

package/extensions/llm-wiki/lib/tools.ts

@@ -2,6 +2,9 @@ import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from
 import { join } from "node:path";
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import { Type } from "typebox";
+import { launchEmbedPages, reindexEmbeddings, resolveEmbedder } from "./embeddings.js";
+import { scheduleReindex } from "./indexing.js";
+import { runIngestSynthesis } from "./ingest-worker.js";
 import {
   type Registry,
   appendEvent,
@@ -10,7 +13,9 @@ import {
   rebuildMetadata,
   rebuildMetadataLight,
 } from "./metadata.js";
+import type { Runtime } from "./runtime.js";
 import { captureFile, captureText, captureUrl } from "./source-packet.js";
+import { parseModelRef } from "./task-config.js";
 import {
   type VaultPaths,
   detectVaultFormat,
@@ -39,6 +44,55 @@ function requireVault(paths: VaultPaths): { ok: true } | { ok: false; reason: st
   return { ok: true };
 }
 
+type WikiToolResult = {
+  content: { type: "text"; text: string }[];
+  details: Record<string, unknown>;
+  isError?: boolean;
+};
+
+type ToolCtx = {
+  cwd?: string;
+  hasUI: boolean;
+  ui?: { notify: (message: string, type?: string) => void };
+};
+
+/**
+ * Dispatch a heavy mutating action to the background runtime and report its
+ * result (issue #77). The agent turn is never blocked: `work` runs off-thread
+ * and the returned one-line summary is surfaced to the user via
+ * `runtime.report()`. Returns an immediate, non-blocking tool result.
+ *
+ * When no runtime is available (unit tests / degraded mode), `work` runs
+ * synchronously and its summary is returned inline, preserving prior behavior.
+ * Retrieval tools (search/read/recall/status) never use this — the model needs
+ * their output inline.
+ */
+async function dispatchReported(
+  runtime: Runtime | undefined,
+  ctx: ToolCtx,
+  opts: {
+    label: string;
+    /** Immediate, non-blocking acknowledgement shown while work runs. */
+    started: string;
+    /** Off-thread work; resolves to the human-readable completion summary. */
+    work: () => Promise<string>;
+    details?: Record<string, unknown>;
+  },
+): Promise<WikiToolResult> {
+  if (!runtime) {
+    const summary = await opts.work();
+    return {
+      content: [{ type: "text", text: summary }],
+      details: { background: false, ...opts.details },
+    };
+  }
+  runtime.launchReported({ hasUI: ctx.hasUI, ui: ctx.ui }, opts.label, opts.work);
+  return {
+    content: [{ type: "text", text: opts.started }],
+    details: { background: true, ...opts.details },
+  };
+}
+
 // ─── 1. wiki_bootstrap ──────────────────────────────────
 
 export function registerWikiBootstrap(pi: ExtensionAPI): void {
@@ -142,7 +196,7 @@ export function registerWikiBootstrap(pi: ExtensionAPI): void {
 
 // ─── 2. wiki_capture_source ─────────────────────────────
 
-export function registerWikiCaptureSource(pi: ExtensionAPI): void {
+export function registerWikiCaptureSource(pi: ExtensionAPI, runtime?: Runtime): void {
   pi.registerTool({
     name: "wiki_capture_source",
     label: "Wiki Capture Source",
@@ -191,7 +245,11 @@ export function registerWikiCaptureSource(pi: ExtensionAPI): void {
         };
       }
 
-      rebuildMetadataLight(paths);
+      if (runtime) {
+        scheduleReindex(runtime, { hasUI: ctx.hasUI, ui: ctx.ui }, paths);
+      } else {
+        rebuildMetadataLight(paths);
+      }
 
       return {
         content: [
@@ -220,16 +278,17 @@ export function registerWikiCaptureSource(pi: ExtensionAPI): void {
 
 // ─── 3. wiki_ingest ─────────────────────────────────────
 
-export function registerWikiIngest(pi: ExtensionAPI): void {
+export function registerWikiIngest(pi: ExtensionAPI, runtime?: Runtime): void {
   pi.registerTool({
     name: "wiki_ingest",
     label: "Wiki Ingest",
     description:
-      "Process uningested source packets. Returns a batch of source IDs with extracted content for the LLM to synthesize.",
-    promptSnippet: "Ingest source packets: get batch of sources needing synthesis",
+      "Process uningested source packets. By default synthesis runs in the background (non-blocking) on the configured task model; pass background=false to return extracted content for the main agent to synthesize itself.",
+    promptSnippet: "Ingest source packets (background synthesis by default)",
     promptGuidelines: [
       "Use wiki_ingest when the user wants to process captured sources.",
-      "After calling this tool, read each source's extracted.md, update its source page, create entity/concept pages, and cross-reference.",
+      "By default ingestion runs in the BACKGROUND — you'll get a notification, not extracted content. Do NOT synthesize those sources yourself.",
+      "If the tool returns extracted content (background unavailable, or background=false), then read each source's extracted.md, update its source page, create entity/concept pages, and cross-reference.",
       "The extension auto-updates metadata — you do NOT need to edit meta/ files.",
     ],
     parameters: Type.Object({
@@ -237,7 +296,20 @@ export function registerWikiIngest(pi: ExtensionAPI): void {
         Type.String({ description: "Specific source ID to ingest. Leave empty for all new." }),
       ),
       batch_size: Type.Optional(
-        Type.Number({ description: "Max sources to return (default: 3, max: 5)", default: 3 }),
+        Type.Number({ description: "Max sources to process (default: 3, max: 5)", default: 3 }),
+      ),
+      background: Type.Optional(
+        Type.Boolean({
+          description:
+            "Synthesize in the background without blocking (default: true). Set false to return extracted content for the main agent to synthesize.",
+          default: true,
+        }),
+      ),
+      model: Type.Optional(
+        Type.String({
+          description:
+            "Per-call model override as 'provider/id' (e.g. anthropic/claude-haiku). Overrides the configured wiki taskModel for this call; defaults to the configured/session model.",
+        }),
       ),
     }),
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
@@ -321,6 +393,76 @@ export function registerWikiIngest(pi: ExtensionAPI): void {
         return { id, extracted, manifest };
       });
 
+      // ── Background synthesis (issue #65) ──────────────────
+      // Default path: dispatch each source to a background sub-agent so the
+      // main agent is not blocked. Falls back to the synchronous return below
+      // when no runtime/model is available (resolveModel ok:false).
+      const wantBackground = params.background !== false;
+      if (wantBackground && runtime) {
+        runtime.ensureConfig(ctx.cwd);
+        // Per-call model override (issue #69): 'provider/id' beats the
+        // configured taskModel; a malformed/unknown ref degrades to the
+        // configured/session model inside resolveModel.
+        const override = params.model ? parseModelRef(params.model) : undefined;
+        const resolved = await runtime.resolveModel(ctx, override);
+        if (resolved.ok) {
+          const launchCtx = { hasUI: ctx.hasUI, ui: ctx.ui };
+          for (const s of sources) {
+            runtime.launchTask(launchCtx, `ingest:${s.id}`, async () => {
+              const committed = await runIngestSynthesis({
+                model: resolved.model as Parameters<typeof runIngestSynthesis>[0]["model"],
+                apiKey: resolved.apiKey,
+                headers: resolved.headers,
+                paths,
+                sourceId: s.id,
+                manifest: s.manifest,
+                extracted: s.extracted,
+              });
+              if (committed) {
+                // Background semantic embeddings (#66): embed the pages this
+                // ingest just wrote, off-thread. No-op when unconfigured.
+                const pageIds = [
+                  `sources/${committed.sourceId}`,
+                  ...committed.entitiesCreated.map((e) => `entities/${e}`),
+                  ...committed.entitiesLinked.map((e) => `entities/${e}`),
+                  ...committed.conceptsCreated.map((c) => `concepts/${c}`),
+                  ...committed.conceptsLinked.map((c) => `concepts/${c}`),
+                ];
+                launchEmbedPages(runtime, launchCtx, paths, pageIds, `embed:ingest:${s.id}`);
+              }
+              const summary = committed
+                ? `LLM Wiki: ingested ${s.id} → ${committed.entitiesCreated.length} entit${committed.entitiesCreated.length === 1 ? "y" : "ies"}, ${committed.conceptsCreated.length} concept${committed.conceptsCreated.length === 1 ? "" : "s"}`
+                : `LLM Wiki: ${s.id} produced no synthesis`;
+              if (ctx.hasUI) {
+                ctx.ui.notify(summary, committed ? "info" : "warning");
+              }
+              // Persistent, user-visible completion report (issue #77) in
+              // addition to the transient toast above. Notices-gated.
+              runtime.report(committed ? `✅ ${summary}` : `⚠️ ${summary}`);
+            });
+          }
+          return {
+            content: [
+              {
+                type: "text",
+                text: [
+                  `🔄 **Ingesting ${sources.length} source(s) in the background** (${toProcess.length - batch.length} remaining).`,
+                  "",
+                  ...sources.map((s) => `- **${s.id}**: ${s.manifest.title || s.id}`),
+                  "",
+                  "Synthesis runs on the configured task model without blocking. You'll be notified as each source completes — do NOT synthesize these yourself.",
+                ].join("\n"),
+              },
+            ],
+            details: {
+              background: true,
+              dispatched: sources.map((s) => s.id),
+              remaining: toProcess.length - batch.length,
+            } as Record<string, unknown>,
+          };
+        }
+      }
+
       return {
         content: [
           {
@@ -359,7 +501,7 @@ export function registerWikiIngest(pi: ExtensionAPI): void {
 
 // ─── 4. wiki_ensure_page ────────────────────────────────
 
-export function registerWikiEnsurePage(pi: ExtensionAPI): void {
+export function registerWikiEnsurePage(pi: ExtensionAPI, runtime?: Runtime): void {
   pi.registerTool({
     name: "wiki_ensure_page",
     label: "Wiki Ensure Page",
@@ -426,6 +568,15 @@ export function registerWikiEnsurePage(pi: ExtensionAPI): void {
         path: `${folder}/${slug}`,
       });
 
+      // Register the new page so retrieval + embeddings can see it. When a
+      // background runtime is available, the rebuild + embeddings run off the
+      // tool's critical path; otherwise fall back to a synchronous rebuild.
+      if (runtime) {
+        scheduleReindex(runtime, { hasUI: ctx.hasUI, ui: ctx.ui }, paths);
+      } else {
+        rebuildMetadataLight(paths);
+      }
+
       return {
         content: [{ type: "text", text: `✅ Created ${type} page: \`${pagePath}\`` }],
         details: { path: pagePath, created: true } as Record<string, unknown>,
@@ -571,7 +722,7 @@ export function registerWikiSearch(pi: ExtensionAPI): void {
 
 // ─── 6. wiki_lint ───────────────────────────────────────
 
-export function registerWikiLint(pi: ExtensionAPI): void {
+export function registerWikiLint(pi: ExtensionAPI, runtime?: Runtime): void {
   pi.registerTool({
     name: "wiki_lint",
     label: "Wiki Lint",
@@ -598,138 +749,143 @@ export function registerWikiLint(pi: ExtensionAPI): void {
         };
       }
 
-      const pages = findWikiPages(paths.wiki);
-      const registry = buildRegistry(paths);
-      buildBacklinks(paths, registry); // ensures backlinks.json is current
-
-      const findings: string[] = [];
-      let orphans = 0;
-      let missingPages = 0;
-      let contradictions = 0;
-      const gaps: Array<{ topic: string; mentionedBy: string[] }> = [];
-
-      const allPageIds = new Set(pages.map((p) => p.relative));
-      const linkCounts: Record<string, number> = {};
-
-      for (const page of pages) {
-        const links = extractWikilinks(page.content);
-        for (const link of links) {
-          if (!allPageIds.has(link)) {
-            missingPages++;
-            findings.push(`Missing page: [[${link}]] (in [[${page.relative}]])`);
-            const existing = gaps.find((g) => g.topic === link);
-            if (existing) {
-              if (!existing.mentionedBy.includes(page.relative))
-                existing.mentionedBy.push(page.relative);
-            } else {
-              gaps.push({ topic: link, mentionedBy: [page.relative] });
-            }
-          } else {
-            linkCounts[link] = (linkCounts[link] || 0) + 1;
-          }
-        }
-      }
+      // Full-vault scan (+ optional auto-fix writes + reindex) is O(pages):
+      // run it in the background and report the health summary (issue #77).
+      return dispatchReported(runtime, ctx as ToolCtx, {
+        label: `lint:${paths.root}`,
+        started:
+          "\u{1F9F9} LLM Wiki: lint started in the background — the health report will be posted when it completes.",
+        work: async () => runWikiLint(paths, params.auto_fix === true),
+      });
+    },
+  });
+}
 
-      for (const page of pages) {
-        if (!linkCounts[page.relative] || linkCounts[page.relative] === 0) {
-          orphans++;
-          findings.push(`Orphan: [[${page.relative}]] has no inbound links`);
+/**
+ * Run the wiki health scan (issue #77 extracted it from the tool body so it can
+ * run off-thread via `dispatchReported`). Returns the human-readable summary.
+ */
+function runWikiLint(paths: VaultPaths, autoFix: boolean): string {
+  const pages = findWikiPages(paths.wiki);
+  const registry = buildRegistry(paths);
+  buildBacklinks(paths, registry); // ensures backlinks.json is current
+
+  const findings: string[] = [];
+  let orphans = 0;
+  let missingPages = 0;
+  let contradictions = 0;
+  const gaps: Array<{ topic: string; mentionedBy: string[] }> = [];
+
+  const allPageIds = new Set(pages.map((p) => p.relative));
+  const linkCounts: Record<string, number> = {};
+
+  for (const page of pages) {
+    const links = extractWikilinks(page.content);
+    for (const link of links) {
+      if (!allPageIds.has(link)) {
+        missingPages++;
+        findings.push(`Missing page: [[${link}]] (in [[${page.relative}]])`);
+        const existing = gaps.find((g) => g.topic === link);
+        if (existing) {
+          if (!existing.mentionedBy.includes(page.relative))
+            existing.mentionedBy.push(page.relative);
+        } else {
+          gaps.push({ topic: link, mentionedBy: [page.relative] });
         }
+      } else {
+        linkCounts[link] = (linkCounts[link] || 0) + 1;
       }
+    }
+  }
 
-      for (const page of pages) {
-        if (page.content.includes("⚠️ **Contradiction")) {
-          contradictions++;
-          findings.push(`Contradiction flagged in [[${page.relative}]]`);
-        }
-      }
+  for (const page of pages) {
+    if (!linkCounts[page.relative] || linkCounts[page.relative] === 0) {
+      orphans++;
+      findings.push(`Orphan: [[${page.relative}]] has no inbound links`);
+    }
+  }
 
-      let fixesApplied = 0;
-      if (params.auto_fix) {
-        for (const gap of gaps) {
-          if (gap.mentionedBy.length >= 2) {
-            const folder = gap.topic.includes("/") ? gap.topic.split("/")[0] : "concepts";
-            const name = gap.topic.includes("/") ? gap.topic.split("/").pop()! : gap.topic;
-            const pagePath = join(paths.wiki, folder, `${name}.md`);
-            if (!existsSync(pagePath)) {
-              mkdirSync(join(paths.wiki, folder), { recursive: true });
-              writeFileSync(
-                pagePath,
-                `---\ntype: concept\ncreated: ${fmtDate()}\nupdated: ${fmtDate()}\nsources: []\nstatus: stub\n---\n\n# ${name.replace(/-/g, " ")}\n\n_Stub auto-created by lint. Expand with content from: ${gap.mentionedBy.map((r) => `[[${r}]]`).join(", ")}_\n`,
-                "utf-8",
-              );
-              fixesApplied++;
-            }
-          }
+  for (const page of pages) {
+    if (page.content.includes("⚠️ **Contradiction")) {
+      contradictions++;
+      findings.push(`Contradiction flagged in [[${page.relative}]]`);
+    }
+  }
+
+  let fixesApplied = 0;
+  if (autoFix) {
+    for (const gap of gaps) {
+      if (gap.mentionedBy.length >= 2) {
+        const folder = gap.topic.includes("/") ? gap.topic.split("/")[0] : "concepts";
+        const name = gap.topic.includes("/") ? gap.topic.split("/").pop()! : gap.topic;
+        const pagePath = join(paths.wiki, folder, `${name}.md`);
+        mkdirSync(join(paths.wiki, folder), { recursive: true });
+        try {
+          // Atomic create-if-absent: the `wx` flag fails with EEXIST instead of
+          // overwriting, avoiding the existsSync→write TOCTOU race (CodeQL).
+          writeFileSync(
+            pagePath,
+            `---\ntype: concept\ncreated: ${fmtDate()}\nupdated: ${fmtDate()}\nsources: []\nstatus: stub\n---\n\n# ${name.replace(/-/g, " ")}\n\n_Stub auto-created by lint. Expand with content from: ${gap.mentionedBy.map((r) => `[[${r}]]`).join(", ")}_\n`,
+            { encoding: "utf-8", flag: "wx" },
+          );
+          fixesApplied++;
+        } catch (err) {
+          // Page already exists — nothing to fix. Re-throw anything else.
+          if ((err as NodeJS.ErrnoException).code !== "EEXIST") throw err;
         }
       }
+    }
+  }
 
-      writeJson(join(paths.discoveries, "gaps.json"), {
-        gaps,
-        generated: new Date().toISOString(),
-      });
-
-      const reportLines = [
-        "# Wiki Lint Report",
-        `Generated: ${fmtDate()}`,
-        "",
-        "## Summary",
-        `- Total pages: ${pages.length}`,
-        `- Orphans: ${orphans}`,
-        `- Missing pages: ${missingPages}`,
-        `- Contradictions: ${contradictions}`,
-        params.auto_fix ? `- Fixes applied: ${fixesApplied}` : "",
-        "",
-        "## Findings",
-        findings.length > 0 ? findings.map((f) => `- ${f}`).join("\n") : "✅ No issues found!",
-        "",
-      ].filter(Boolean);
-
-      const reportPath = join(paths.outputs, `lint-${fmtDate()}.md`);
-      mkdirSync(paths.outputs, { recursive: true });
-      writeFileSync(reportPath, `${reportLines.join("\n")}\n`, "utf-8");
-
-      appendEvent(paths, {
-        kind: "lint",
-        orphans,
-        missing_pages: missingPages,
-        contradictions,
-        auto_fix: params.auto_fix ?? false,
-      });
-
-      rebuildMetadataLight(paths);
+  writeJson(join(paths.discoveries, "gaps.json"), {
+    gaps,
+    generated: new Date().toISOString(),
+  });
 
-      return {
-        content: [
-          {
-            type: "text",
-            text: [
-              "🧹 **Lint complete**",
-              "",
-              `- Pages: ${pages.length}`,
-              `- Orphans: ${orphans}`,
-              `- Missing: ${missingPages}`,
-              `- Contradictions: ${contradictions}`,
-              params.auto_fix ? `- Auto-fixes: ${fixesApplied}` : "",
-              "",
-              `📄 Report: \`${reportPath}\``,
-              gaps.length > 0 ? `💡 ${gaps.length} knowledge gap(s) tracked` : "",
-            ]
-              .filter(Boolean)
-              .join("\n"),
-          },
-        ],
-        details: {
-          pages: pages.length,
-          orphans,
-          missingPages,
-          contradictions,
-          reportPath,
-          gaps: gaps.length,
-        } as Record<string, unknown>,
-      };
-    },
+  const reportLines = [
+    "# Wiki Lint Report",
+    `Generated: ${fmtDate()}`,
+    "",
+    "## Summary",
+    `- Total pages: ${pages.length}`,
+    `- Orphans: ${orphans}`,
+    `- Missing pages: ${missingPages}`,
+    `- Contradictions: ${contradictions}`,
+    autoFix ? `- Fixes applied: ${fixesApplied}` : "",
+    "",
+    "## Findings",
+    findings.length > 0 ? findings.map((f) => `- ${f}`).join("\n") : "✅ No issues found!",
+    "",
+  ].filter(Boolean);
+
+  const reportPath = join(paths.outputs, `lint-${fmtDate()}.md`);
+  mkdirSync(paths.outputs, { recursive: true });
+  writeFileSync(reportPath, `${reportLines.join("\n")}\n`, "utf-8");
+
+  appendEvent(paths, {
+    kind: "lint",
+    orphans,
+    missing_pages: missingPages,
+    contradictions,
+    auto_fix: autoFix,
   });
+
+  rebuildMetadataLight(paths);
+
+  return [
+    "🧹 **LLM Wiki lint complete**",
+    "",
+    `- Pages: ${pages.length}`,
+    `- Orphans: ${orphans}`,
+    `- Missing: ${missingPages}`,
+    `- Contradictions: ${contradictions}`,
+    autoFix ? `- Auto-fixes: ${fixesApplied}` : "",
+    "",
+    `📄 Report: \`${reportPath}\``,
+    gaps.length > 0 ? `💡 ${gaps.length} knowledge gap(s) tracked` : "",
+  ]
+    .filter(Boolean)
+    .join("\n");
 }
 
 // ─── 7. wiki_status ─────────────────────────────────────
@@ -811,7 +967,7 @@ export function registerWikiStatus(pi: ExtensionAPI): void {
 
 // ─── 8. wiki_rebuild_meta ───────────────────────────────
 
-export function registerWikiRebuildMeta(pi: ExtensionAPI): void {
+export function registerWikiRebuildMeta(pi: ExtensionAPI, runtime?: Runtime): void {
   pi.registerTool({
     name: "wiki_rebuild_meta",
     label: "Wiki Rebuild Meta",
@@ -830,30 +986,94 @@ export function registerWikiRebuildMeta(pi: ExtensionAPI): void {
         };
       }
 
-      rebuildMetadata(paths);
-      appendEvent(paths, { kind: "rebuild_meta" });
-
-      const registry = readJson<Registry>(join(paths.meta, "registry.json"), {
-        version: "1.0",
-        last_updated: "",
-        pages: {},
+      // Heavy O(pages) rebuild — dispatch off the agent's critical path and
+      // report on completion (issue #77).
+      return dispatchReported(runtime, ctx as ToolCtx, {
+        label: `rebuild_meta:${paths.root}`,
+        started:
+          "\u{1F9E0} LLM Wiki: metadata rebuild started in the background — the result will be reported when it completes.",
+        work: async () => {
+          rebuildMetadata(paths);
+          appendEvent(paths, { kind: "rebuild_meta" });
+          const registry = readJson<Registry>(join(paths.meta, "registry.json"), {
+            version: "1.0",
+            last_updated: "",
+            pages: {},
+          });
+          return `✅ LLM Wiki: metadata rebuilt — ${Object.keys(registry.pages).length} pages indexed.`;
+        },
       });
-
-      return {
-        content: [
-          {
-            type: "text",
-            text: `✅ Metadata rebuilt. ${Object.keys(registry.pages).length} pages indexed.`,
-          },
-        ],
-        details: { pageCount: Object.keys(registry.pages).length } as Record<string, unknown>,
-      };
     },
   });
 }
 
 // ─── 9. wiki_log_event ──────────────────────────────────
 
+export function registerWikiReindexEmbeddings(pi: ExtensionAPI, runtime?: Runtime): void {
+  pi.registerTool({
+    name: "wiki_reindex_embeddings",
+    label: "Wiki Reindex Embeddings",
+    description:
+      "Backfill / refresh semantic embeddings for the vault. Embeds pages that " +
+      "are new or stale (content changed); pass force to re-embed everything. " +
+      "No-op when no embedding provider is configured.",
+    promptSnippet: "Backfill semantic embeddings for the wiki",
+    promptGuidelines: [
+      "Use wiki_reindex_embeddings to embed an existing vault or refresh stale embeddings.",
+      "Embeddings are optional: this no-ops cleanly when no embedding provider is configured.",
+    ],
+    parameters: Type.Object({
+      force: Type.Optional(
+        Type.Boolean({ description: "Re-embed every page, ignoring staleness (default: false)" }),
+      ),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const paths = getPaths(ctx.cwd);
+      const vaultCheck = requireVault(paths);
+      if (!vaultCheck.ok) {
+        return {
+          content: [{ type: "text", text: vaultCheck.reason }],
+          details: { error: vaultCheck.reason } as Record<string, unknown>,
+          isError: true,
+        };
+      }
+
+      if (runtime) runtime.ensureConfig(ctx.cwd ?? paths.root);
+      const embedder = runtime ? resolveEmbedder(runtime.config) : undefined;
+      if (!embedder) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: 'ℹ️ No embedding provider configured — semantic embeddings are disabled. Set `llm-wiki.embeddingProvider` (e.g. "openai") in settings to enable.',
+            },
+          ],
+          details: { enabled: false } as Record<string, unknown>,
+        };
+      }
+
+      // Embedding is network-bound and O(pages) — run it in the background and
+      // report the stats on completion (issue #77).
+      return dispatchReported(runtime, ctx as ToolCtx, {
+        label: `reindex_embeddings:${paths.root}`,
+        started: `\u{1F9E0} LLM Wiki: embedding reindex started in the background (${embedder.model}) — stats will be reported when it completes.`,
+        details: { enabled: true, model: embedder.model },
+        work: async () => {
+          const stats = await reindexEmbeddings(paths, embedder, { force: params.force === true });
+          appendEvent(paths, {
+            kind: "reindex_embeddings",
+            embedded: stats.embedded,
+            skipped: stats.skipped,
+            pruned: stats.pruned,
+            model: embedder.model,
+          });
+          return `✅ LLM Wiki: embeddings reindexed (${embedder.model}) — ${stats.embedded} embedded, ${stats.skipped} fresh, ${stats.pruned} pruned.`;
+        },
+      });
+    },
+  });
+}
+
 export function registerWikiLogEvent(pi: ExtensionAPI): void {
   pi.registerTool({
     name: "wiki_log_event",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zosmaai/pi-llm-wiki",
-  "version": "0.8.2",
+  "version": "0.9.1",
   "description": "Self-maintaining LLM Wiki for Pi — Karpathy-pattern knowledge base with immutable source capture, automated ingestion, search, linting, and Obsidian-compatible vault. auto-updating personal & company wiki.",
   "keywords": [
     "pi",

package/prompts/wiki-ingest.md

@@ -15,17 +15,20 @@ $ARGUMENTS
 
 ## Steps
 
-1. Call `wiki_ingest(source_id=<id if provided>, batch_size=3)` to get sources needing synthesis.
+1. Call `wiki_ingest(source_id=<id if provided>, batch_size=3)`.
 2. If the tool reports "All sources ingested", inform the user and stop.
-3. For each source in the returned batch:
+3. **If the tool reports it is ingesting in the background**, the synthesis sub-agent is handling those sources on the configured task model. Do NOT synthesize them yourself — just report which sources were dispatched and stop. (You'll be notified as each completes.)
+4. **Otherwise** (the tool returned extracted content — background unavailable or `background=false`), for each source in the returned batch:
    a. Read the extracted text from `raw/sources/<SOURCE_ID>/extracted.md`
    b. Update the skeleton source page in `wiki/sources/` with a proper summary, key entities, and concepts
    c. Use `wiki_ensure_page(type=entity, title=<name>)` for each new entity (people, orgs, tools, products)
    d. Use `wiki_ensure_page(type=concept, title=<name>)` for each new concept (ideas, patterns, frameworks)
    e. Add `[[wikilinks]]` cross-references between related pages
    f. Flag any contradictions with existing wiki content using `⚠️ **Contradiction**` markers
-4. After processing the batch, call `wiki_rebuild_meta` to update metadata.
-5. Report: "Ingested [N] sources → [M] pages created/updated. [X] contradictions flagged."
+5. After processing a synchronous batch, call `wiki_rebuild_meta` to update metadata.
+6. Report: "Ingested [N] sources → [M] pages created/updated. [X] contradictions flagged."
+
+> **Background vs synchronous:** ingestion runs in the background by default (non-blocking) when a task model is available, so the main agent is never stalled. It falls back to the synchronous main-agent flow above when no model/API key is configured, or when called with `background=false`.
 
 **Rules:**
 - Never modify files in `raw/` — source packets are immutable after capture.