@zosmaai/pi-llm-wiki 0.10.7 → 0.11.0

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

@@ -0,0 +1,158 @@
+import { dirname, resolve } from "node:path";
+import { Type } from "typebox";
+import { scheduleReindex } from "./indexing.js";
+import { createKnowledgeDocument, writeKnowledgeDocumentFile } from "./knowledge-document.js";
+import { appendEvent, rebuildMetadataLight } from "./metadata.js";
+import { fmtDate, resolveVaultPaths } from "./utils.js";
+import { assertWritableVault, inspectWritableVault } from "./vault-format.js";
+/**
+ * Save an atomic insight into the wiki as a single markdown file.
+ *
+ * Unlike wiki_capture_source (which creates a full source packet with
+ * manifest.json, extracted.md, and attachments), this is a lightweight
+ * path for quick knowledge capture — one file, one call.
+ *
+ * The 4-layer pipeline (raw → source pages → canonical pages → metadata)
+ * is still available via wiki_capture_source → wiki_ingest for deep research.
+ */
+function insightPath(paths, slug) {
+    if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(slug) || slug === "index" || slug === "log") {
+        throw new Error(`Invalid insight slug: ${slug}`);
+    }
+    const directory = resolve(paths.wiki, "sources");
+    const target = resolve(directory, `${slug}.md`);
+    if (dirname(target) !== directory)
+        throw new Error(`Invalid insight slug: ${slug}`);
+    return target;
+}
+export function saveInsight(paths, slug, title, body, category, opts) {
+    assertWritableVault(paths);
+    const today = fmtDate();
+    const sourcePagePath = insightPath(paths, slug);
+    const pageBody = `# ${title}
+
+${body}
+
+${category ? `*Category: ${category}*` : ""}
+
+---
+*Captured: ${today}*
+
+## Related
+
+_Add links to related pages._`;
+    const doc = createKnowledgeDocument(`sources/${slug}.md`, {
+        type: "source",
+        title,
+        slug,
+        status: "insight",
+        created: today,
+        updated: today,
+        ...(category ? { category } : {}),
+    }, pageBody);
+    writeKnowledgeDocumentFile(sourcePagePath, doc);
+    // Log event
+    appendEvent(paths, {
+        kind: "retro",
+        slug,
+        title,
+        category: category || "uncategorized",
+    });
+    // Rebuild metadata so the insight is immediately searchable. The wiki_retro
+    // tool passes { rebuild: false } and schedules a non-blocking reindex instead.
+    if (opts?.rebuild !== false)
+        rebuildMetadataLight(paths);
+    return { slug, sourcePagePath };
+}
+// ─── Tool Registration ──────────────────────────────────
+/**
+ * Register the `wiki_retro` tool.
+ * The model calls this to save an atomic insight from a completed task.
+ * Inspired by the memex_retro pattern.
+ */
+export function registerWikiRetro(pi, runtime) {
+    pi.registerTool({
+        name: "wiki_retro",
+        label: "Wiki Retro",
+        description: "Save an atomic insight from a completed task into the wiki. " +
+            "Creates a source packet and source page. The insight will be " +
+            "surfaced automatically by wiki_recall in future sessions.",
+        promptSnippet: "Save atomic insights from completed tasks into the wiki",
+        promptGuidelines: [
+            "Use wiki_retro at the END of every meaningful task to save what you learned.",
+            "Write atomic insights — one insight per call. Use multiple calls for multiple insights.",
+            "The insight will be auto-surfaced by wiki_recall in future sessions.",
+        ],
+        parameters: Type.Object({
+            slug: Type.String({
+                description: "Unique kebab-case identifier (e.g. 'jwt-revocation-pattern'). Used for lookups.",
+            }),
+            title: Type.String({
+                description: "Short descriptive title (60 chars max). Noun phrase, not a sentence.",
+            }),
+            body: Type.String({
+                description: "Markdown body with [[wikilinks]] to related wiki pages. Explain what was learned.",
+            }),
+            category: Type.Optional(Type.String({
+                description: "Optional category (e.g. frontend, architecture, devops, bugfix, design)",
+            })),
+        }),
+        async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+            const paths = resolveVaultPaths(ctx.cwd ?? process.cwd());
+            const vaultCheck = inspectWritableVault(paths);
+            if (!vaultCheck.ok) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Wiki vault error: ${vaultCheck.diagnostics[0].message}`,
+                        },
+                    ],
+                    details: {
+                        error: vaultCheck.diagnostics[0].code,
+                        diagnostics: vaultCheck.diagnostics,
+                    },
+                    isError: true,
+                };
+            }
+            let result;
+            try {
+                result = saveInsight(paths, params.slug, params.title, params.body, params.category, {
+                    rebuild: !runtime,
+                });
+            }
+            catch (error) {
+                if (error.message.startsWith("Invalid insight slug:")) {
+                    return {
+                        content: [{ type: "text", text: error.message }],
+                        details: { error: "invalid_insight_slug" },
+                        isError: true,
+                    };
+                }
+                throw error;
+            }
+            if (runtime) {
+                scheduleReindex(runtime, { hasUI: ctx.hasUI, ui: ctx.ui }, paths);
+            }
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: [
+                            `🧠 **Insight saved**: ${params.title}`,
+                            "",
+                            `- Page: \`${result.sourcePagePath}\``,
+                            "",
+                            "This insight will be auto-surfaced by wiki_recall in future sessions.",
+                        ].join("\n"),
+                    },
+                ],
+                details: {
+                    slug: params.slug,
+                    title: params.title,
+                    category: params.category || null,
+                },
+            };
+        },
+    });
+}

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

@@ -0,0 +1,191 @@
+import { TASK_DEFAULTS, loadTaskConfig, noticesEnabled } from "./task-config.js";
+export class Runtime {
+    config = { ...TASK_DEFAULTS };
+    configLoaded = false;
+    /**
+     * Extension API handle, attached at registration. Used by `report()` to emit
+     * visible completion messages for background actions (issue #77). Optional so
+     * the Runtime stays unit-testable without a live `pi`.
+     */
+    pi;
+    /** Labels of tasks currently in flight (single-flight guard per label). */
+    inFlightLabels = new Set();
+    /** All in-flight task promises, keyed for await-at-exit and dedupe. */
+    inFlight = new Map();
+    /** Whether we've already surfaced a model-resolution failure (avoid spam). */
+    resolveFailureNotified = false;
+    ensureConfig(cwd) {
+        if (this.configLoaded)
+            return;
+        this.config = loadTaskConfig(cwd);
+        this.configLoaded = true;
+    }
+    /** True if a task with this label is currently running. */
+    isInFlight(label) {
+        return this.inFlightLabels.has(label);
+    }
+    /** Number of background tasks currently running. */
+    get pendingCount() {
+        return this.inFlight.size;
+    }
+    /**
+     * Resolve the model + auth for background work.
+     *
+     * Precedence (issue #69): per-call `override` → configured `taskModel` →
+     * session model. Each configured layer is applied only when the model is
+     * found in the registry; a missing layer warns (when UI is available) and
+     * falls through to the next. Returns { ok: false } when nothing resolves or
+     * no API key exists, so callers can fall back to the synchronous
+     * main-agent path.
+     */
+    async resolveModel(ctx, override) {
+        let model = ctx.model;
+        // Configured taskModel layer (beats the session model).
+        const configured = this.config.taskModel;
+        if (configured) {
+            const found = ctx.modelRegistry.find(configured.provider, configured.id);
+            if (found) {
+                model = found;
+            }
+            else if (ctx.hasUI && ctx.ui) {
+                ctx.ui.notify(`LLM Wiki: configured task model ${configured.provider}/${configured.id} not found, using session model`, "warning");
+            }
+        }
+        // Per-call override layer (beats both config and session).
+        if (override) {
+            const found = ctx.modelRegistry.find(override.provider, override.id);
+            if (found) {
+                model = found;
+            }
+            else if (ctx.hasUI && ctx.ui) {
+                ctx.ui.notify(`LLM Wiki: model override ${override.provider}/${override.id} not found, using ${configured ? "configured/session" : "session"} model`, "warning");
+            }
+        }
+        if (!model) {
+            return {
+                ok: false,
+                reason: "no model available (session has no model and no taskModel configured)",
+            };
+        }
+        const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
+        if (!auth.ok || !auth.apiKey) {
+            const provider = model.provider ?? "unknown";
+            return { ok: false, reason: `no API key for provider "${provider}"` };
+        }
+        return { ok: true, model, apiKey: auth.apiKey, headers: auth.headers };
+    }
+    /**
+     * Fire-and-forget a background task.
+     *
+     * The work runs in a detached promise so the caller (an agent hook/tool)
+     * is never blocked. Errors are caught and surfaced via the UI (when
+     * available) instead of crashing the agent. Single-flight per label: if a
+     * task with the same label is already running, the new request is dropped
+     * and the existing promise is returned.
+     *
+     * The returned promise resolves when the work completes; hold onto it (or
+     * call awaitAll) to drain background work before compaction/exit.
+     */
+    launchTask(ctx, label, work) {
+        const existing = this.inFlight.get(label);
+        if (existing)
+            return existing;
+        // Capture ctx properties synchronously — after `await work()` the extension
+        // ctx may be stale (e.g. after newSession/fork/switchSession/reload), and
+        // accessing ctx.hasUI or ctx.ui on a stale proxy throws.
+        const hasUI = ctx.hasUI;
+        const ui = ctx.ui;
+        this.inFlightLabels.add(label);
+        // biome-ignore lint/style/useConst: referenced inside its own initializer (finally block)
+        let promise;
+        promise = (async () => {
+            try {
+                await work();
+            }
+            catch (error) {
+                const msg = error instanceof Error ? error.message : String(error);
+                if (hasUI && ui)
+                    ui.notify(`LLM Wiki: ${label} failed: ${msg}`, "warning");
+            }
+            finally {
+                this.inFlightLabels.delete(label);
+                if (this.inFlight.get(label) === promise)
+                    this.inFlight.delete(label);
+            }
+        })();
+        this.inFlight.set(label, promise);
+        return promise;
+    }
+    /**
+     * Report a completed background action to the user (issue #77).
+     *
+     * Every mutating wiki action runs off the agent's critical path; this is how
+     * the work becomes visible. Emits a `wiki-action-report` custom message,
+     * shown in the UI when notices are enabled (the `notices` config, default
+     * on) and otherwise injected silently. Delivered as `nextTurn` so it never
+     * interrupts or triggers a turn. Never throws — reporting must not crash the
+     * background task that called it.
+     */
+    report(summary, opts) {
+        if (!this.pi || !summary)
+            return;
+        const display = opts?.display ?? noticesEnabled(this.config);
+        try {
+            this.pi.sendMessage({ customType: "wiki-action-report", content: summary, display }, { deliverAs: "nextTurn" });
+        }
+        catch {
+            // Reporting is best-effort; a stale/torn-down session must not propagate.
+        }
+    }
+    /**
+     * Run a mutating action in the background and report its result (issue #77).
+     *
+     * Thin wrapper over `launchTask`: `work` performs the off-thread mutation and
+     * returns a one-line human summary (or null to stay silent). On success the
+     * summary is surfaced via `report()`. Single-flight, error-isolated, and
+     * awaited-at-exit exactly like `launchTask`.
+     */
+    launchReported(ctx, label, work) {
+        return this.launchTask(ctx, label, async () => {
+            const summary = await work();
+            if (summary)
+                this.report(summary);
+        });
+    }
+    /**
+     * Await all in-flight background tasks. Call at compaction / session exit so
+     * background work is not lost. Never rejects — task errors are already
+     * isolated inside launchTask.
+     */
+    async awaitAll() {
+        while (this.inFlight.size > 0) {
+            await Promise.allSettled([...this.inFlight.values()]);
+        }
+    }
+}
+/**
+ * Register the shared background runtime and wire it into the extension
+ * lifecycle: config is loaded lazily per turn, and in-flight tasks are drained
+ * before compaction and on shutdown so background work is never lost.
+ *
+ * Returns the Runtime instance so concrete background workers (issues #65,
+ * #66) can launch tasks on it.
+ */
+export function registerBackgroundRuntime(pi) {
+    const runtime = new Runtime();
+    // Attach the API so background tasks can emit visible completion reports
+    // (issue #77). Done here (not in the constructor) to keep Runtime testable.
+    runtime.pi = pi;
+    pi.on("turn_start", (_event, ctx) => {
+        runtime.ensureConfig(ctx.cwd);
+    });
+    // Drain in-flight background work before the session is compacted or shut
+    // down, so nothing is lost mid-flight.
+    pi.on("session_before_compact", async () => {
+        await runtime.awaitAll();
+    });
+    pi.on("session_shutdown", async () => {
+        await runtime.awaitAll();
+    });
+    return runtime;
+}