@zosmaai/pi-llm-wiki 0.8.2 → 0.9.1

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

@@ -0,0 +1,264 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { TASK_DEFAULTS, type TaskConfig, loadTaskConfig, noticesEnabled } from "./task-config.js";
+
+/**
+ * Background-task runtime for the LLM Wiki (issue #64, part of #63).
+ *
+ * Provides two primitives, ported from pi-observational-memory's proven
+ * pattern, that let the extension perform LLM work WITHOUT blocking the main
+ * agent turn:
+ *
+ *   - launchTask(): fire-and-forget a detached promise that may outlive the
+ *     current turn. The in-flight promise is stored so callers can await it at
+ *     compaction / session exit (so background work is never silently lost),
+ *     but the agent loop itself never blocks on it. Single-flight per label
+ *     to avoid pile-ups.
+ *
+ *   - resolveModel(): pick the model for background work — configured
+ *     `taskModel` → session model fallback → API-key resolution. Returns a
+ *     discriminated result so callers degrade gracefully (keep the existing
+ *     synchronous main-agent flow) when no model / API key is available.
+ *
+ * This module introduces NO user-facing behavior on its own; it is the
+ * infrastructure that issues #65 (background ingest), #66 (background
+ * embeddings) and #69 (model selection) build upon.
+ */
+
+export type ResolveResult =
+  | { ok: true; model: unknown; apiKey: string; headers?: Record<string, string> }
+  | { ok: false; reason: string };
+
+type NotifyLevel = "info" | "warning" | "error";
+type Notify = (message: string, type?: NotifyLevel) => void;
+
+export interface ResolveCtx {
+  /** Current session model (may be undefined when the session has no model). */
+  model: unknown;
+  modelRegistry: {
+    find(provider: string, id: string): unknown;
+    getApiKeyAndHeaders(
+      model: unknown,
+    ): Promise<{ ok: boolean; apiKey?: string; headers?: Record<string, string> }>;
+  };
+  hasUI: boolean;
+  ui?: { notify: Notify };
+}
+
+export interface LaunchCtx {
+  hasUI: boolean;
+  ui?: { notify: Notify };
+}
+
+export class Runtime {
+  config: TaskConfig = { ...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?: ExtensionAPI;
+
+  /** Labels of tasks currently in flight (single-flight guard per label). */
+  private inFlightLabels = new Set<string>();
+  /** All in-flight task promises, keyed for await-at-exit and dedupe. */
+  private inFlight = new Map<string, Promise<void>>();
+  /** Whether we've already surfaced a model-resolution failure (avoid spam). */
+  resolveFailureNotified = false;
+
+  ensureConfig(cwd: string): void {
+    if (this.configLoaded) return;
+    this.config = loadTaskConfig(cwd);
+    this.configLoaded = true;
+  }
+
+  /** True if a task with this label is currently running. */
+  isInFlight(label: string): boolean {
+    return this.inFlightLabels.has(label);
+  }
+
+  /** Number of background tasks currently running. */
+  get pendingCount(): number {
+    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: ResolveCtx,
+    override?: { provider: string; id: string },
+  ): Promise<ResolveResult> {
+    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 as { provider?: string }).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: LaunchCtx, label: string, work: () => Promise<void>): Promise<void> {
+    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<void>;
+    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: string, opts?: { display?: boolean }): void {
+    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: LaunchCtx, label: string, work: () => Promise<string | null>): Promise<void> {
+    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(): Promise<void> {
+    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: ExtensionAPI): Runtime {
+  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;
+}

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

@@ -0,0 +1,82 @@
+import {
+  type AgentContext,
+  type AgentLoopConfig,
+  type AgentTool,
+  agentLoop,
+} from "@mariozechner/pi-agent-core";
+import type { Api, Message, Model } from "@mariozechner/pi-ai";
+
+/**
+ * Thin sub-agent runner for the LLM Wiki background lane (issue #64, part of #63).
+ *
+ * Wraps `agentLoop` so background tasks (ingest synthesis, topic inference,
+ * etc.) can run a focused, single-purpose agent on a resolved model with its
+ * own system prompt and tools — mirroring pi-observational-memory's
+ * `runObserver`. The caller drives behavior entirely through `tools`
+ * (tool-side effects accumulate results); this wrapper just drives the loop to
+ * completion and drains its event stream.
+ *
+ * This is infrastructure: it makes no wiki-specific decisions. Concrete
+ * background workers (issues #65, #66) supply the prompts and tools.
+ */
+export interface RunSubAgentArgs<TApi extends Api = Api> {
+  model: Model<TApi>;
+  apiKey: string;
+  headers?: Record<string, string>;
+  /** System prompt that defines the sub-agent's role. */
+  systemPrompt: string;
+  /** The user-turn instruction/payload to process. */
+  userPrompt: string;
+  /** Tools the sub-agent may call (side effects accumulate caller-side). */
+  tools: AgentTool[];
+  /** Max output tokens per model call. Default 4096. */
+  maxTokens?: number;
+  signal?: AbortSignal;
+}
+
+/**
+ * Run a sub-agent loop to completion.
+ *
+ * Returns nothing useful directly — by design, results are collected by the
+ * `tools` the caller passes (their `execute` accumulates into caller-owned
+ * state). This keeps the runner generic across every background task type.
+ */
+export async function runSubAgent<TApi extends Api = Api>(
+  args: RunSubAgentArgs<TApi>,
+): Promise<void> {
+  const { model, apiKey, headers, systemPrompt, userPrompt, tools, maxTokens, signal } = args;
+
+  const text = userPrompt.trim();
+  if (!text) return;
+
+  const prompts: Message[] = [
+    {
+      role: "user",
+      content: [{ type: "text", text }],
+      timestamp: Date.now(),
+    },
+  ];
+
+  const context: AgentContext = {
+    systemPrompt,
+    messages: [],
+    tools,
+  };
+
+  const reasoning = (model as unknown as { reasoning?: unknown }).reasoning;
+  const config: AgentLoopConfig = {
+    model,
+    apiKey,
+    headers,
+    maxTokens: maxTokens ?? 4096,
+    convertToLlm: (msgs) => msgs as Message[],
+    toolExecution: "sequential",
+    ...(reasoning ? { reasoning: "high" as const } : {}),
+  };
+
+  const stream = agentLoop(prompts, context, config, signal);
+  for await (const _event of stream) {
+    // Drain events; tool `execute` callbacks collect results caller-side.
+  }
+  await stream.result();
+}

package/extensions/llm-wiki/lib/task-config.ts

@@ -0,0 +1,217 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { getAgentDir } from "@mariozechner/pi-coding-agent";
+
+/**
+ * Configuration for the background-task lane (issue #64, part of #63).
+ *
+ * The wiki's intelligent work (ingest synthesis, embeddings, topic inference)
+ * can run off the main agent thread on a model of the user's choosing. This
+ * module resolves that configuration from pi's namespaced settings, mirroring
+ * the approach used by pi-observational-memory.
+ *
+ * Resolution order (later wins):
+ *   1. built-in DEFAULTS
+ *   2. global settings:  <agentDir>/settings.json  → { "llm-wiki": { ... } }
+ *   3. project settings: <cwd>/.pi/settings.json    → { "llm-wiki": { ... } }
+ *
+ * When `taskModel` is unset, the background lane falls back to the session
+ * model (see Runtime.resolveModel), so the feature is zero-config by default.
+ */
+export interface TaskConfig {
+  /**
+   * Model used for background wiki tasks. When undefined, the session model
+   * is used. The surface for setting this (config field, /command, per-call
+   * override) is built in issue #69; this module only reads it.
+   */
+  taskModel?: { provider: string; id: string };
+
+  /**
+   * Embedding provider for background write-time embeddings (issue #66).
+   * Only "openai" / "openai-compatible" are supported. When undefined,
+   * embeddings are disabled entirely (silent no-op) — this is the default,
+   * so the feature is strictly opt-in.
+   */
+  embeddingProvider?: string;
+  /** Embedding model id (default: text-embedding-3-small). */
+  embeddingModel?: string;
+  /** OpenAI-compatible base URL (default: https://api.openai.com or OPENAI_BASE_URL). */
+  embeddingBaseUrl?: string;
+  /**
+   * Embedding API key. Prefer `embeddingApiKeyEnv` to avoid storing secrets in
+   * settings files; this direct field exists for parity but is discouraged.
+   */
+  embeddingApiKey?: string;
+  /** Env var name to read the embedding API key from (default: OPENAI_API_KEY). */
+  embeddingApiKeyEnv?: string;
+
+  /**
+   * Weight of the semantic (cosine) signal when blending with lexical score in
+   * hybrid recall (issue #67). 0 = pure lexical, 1 = pure semantic boost.
+   * Default 0.5. Only takes effect when embeddings exist AND an embedder is
+   * configured; otherwise recall stays 100% lexical.
+   */
+  semanticWeight?: number;
+
+  /**
+   * Two-stage recall gate (issue #68). When the vault's registered page count
+   * is STRICTLY GREATER THAN this threshold, recall switches to "links-first"
+   * mode: it returns a ranked list of links (id, title, type, score, 1-line
+   * snippet) instead of inline content previews, and the agent expands chosen
+   * links on demand via `read`. At or below the threshold, the current
+   * preview-inline behavior is preserved (no regression for small vaults).
+   *
+   * Page-count (not token-budget) was chosen deliberately: it is derived from
+   * `meta/registry.json` in O(1) with zero extra file I/O, so the gate itself
+   * never reads page bodies — token estimation would require touching every
+   * page, defeating the "cheap recall" goal. Default 50. Set to 0 to force
+   * links-first for any non-empty vault, or a very large number to always keep
+   * previews inline. Clamped to a non-negative integer.
+   */
+  recallLinksThreshold?: number;
+
+  /**
+   * Surface wiki activity in the UI (issue #77). When enabled (the default),
+   * the status line reflects recall hits and the periodic observe/retro
+   * reminder is shown to the user (`display: true`) instead of being injected
+   * silently. Set to `false` to restore the previous quiet behavior — a static
+   * status line and a hidden (`display: false`) reminder — for users who do
+   * not want any chat-level wiki notices.
+   */
+  notices?: boolean;
+}
+
+export const TASK_DEFAULTS: TaskConfig = {};
+
+/**
+ * Resolve whether user-facing wiki notices are enabled (issue #77). Defaults
+ * to `true`; only an explicit `notices: false` disables them.
+ */
+export function noticesEnabled(config: TaskConfig | undefined): boolean {
+  return config?.notices !== false;
+}
+
+const SETTINGS_KEY = "llm-wiki";
+
+function readModelSpec(value: unknown): { provider: string; id: string } | undefined {
+  if (!value || typeof value !== "object") return undefined;
+  const v = value as Record<string, unknown>;
+  if (typeof v.provider === "string" && typeof v.id === "string" && v.provider && v.id) {
+    return { provider: v.provider, id: v.id };
+  }
+  return undefined;
+}
+
+function readNamespacedConfig(path: string): Partial<TaskConfig> {
+  if (!existsSync(path)) return {};
+  try {
+    const raw = JSON.parse(readFileSync(path, "utf-8")) as Record<string, unknown>;
+    const nested = raw[SETTINGS_KEY];
+    if (!nested || typeof nested !== "object") return {};
+    const section = nested as Record<string, unknown>;
+    const out: Partial<TaskConfig> = {};
+    const taskModel = readModelSpec(section.taskModel);
+    if (taskModel) out.taskModel = taskModel;
+
+    for (const key of [
+      "embeddingProvider",
+      "embeddingModel",
+      "embeddingBaseUrl",
+      "embeddingApiKey",
+      "embeddingApiKeyEnv",
+    ] as const) {
+      const value = section[key];
+      if (typeof value === "string" && value.trim()) out[key] = value.trim();
+    }
+
+    const weight = section.semanticWeight;
+    if (typeof weight === "number" && Number.isFinite(weight)) {
+      out.semanticWeight = Math.min(1, Math.max(0, weight));
+    }
+
+    const threshold = section.recallLinksThreshold;
+    if (typeof threshold === "number" && Number.isFinite(threshold)) {
+      out.recallLinksThreshold = Math.max(0, Math.floor(threshold));
+    }
+
+    if (typeof section.notices === "boolean") {
+      out.notices = section.notices;
+    }
+    return out;
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Parse a `"provider/id"` model reference (issue #69). Splits on the FIRST
+ * slash so model ids that themselves contain slashes (e.g.
+ * `openrouter/meta/llama-3`) are preserved. Returns `undefined` for empty,
+ * slashless, or partial (`provider/` / `/id`) refs so callers can reject bad
+ * input. Whitespace is trimmed.
+ */
+export function parseModelRef(ref: string): { provider: string; id: string } | undefined {
+  const trimmed = ref.trim();
+  const slash = trimmed.indexOf("/");
+  if (slash <= 0) return undefined;
+  const provider = trimmed.slice(0, slash).trim();
+  const id = trimmed.slice(slash + 1).trim();
+  if (!provider || !id) return undefined;
+  return { provider, id };
+}
+
+/**
+ * Persist (or clear) the wiki background `taskModel` in the PROJECT settings
+ * file `<cwd>/.pi/settings.json` under the namespaced `llm-wiki` key (issue
+ * #69). Project settings win over global in `loadTaskConfig`, so this takes
+ * effect immediately on the next config load. Other top-level keys and other
+ * `llm-wiki` settings are preserved; passing `undefined` removes the key
+ * (reverting to the session model).
+ */
+export function persistTaskModel(
+  cwd: string,
+  model: { provider: string; id: string } | undefined,
+): void {
+  const settingsPath = join(cwd, ".pi", "settings.json");
+  let raw: Record<string, unknown> = {};
+  if (existsSync(settingsPath)) {
+    try {
+      const parsed = JSON.parse(readFileSync(settingsPath, "utf-8"));
+      if (parsed && typeof parsed === "object") raw = parsed as Record<string, unknown>;
+    } catch {
+      // Corrupt settings file: start from an empty object rather than throw.
+      raw = {};
+    }
+  }
+
+  const existing = raw[SETTINGS_KEY];
+  const section: Record<string, unknown> =
+    existing && typeof existing === "object" ? { ...(existing as Record<string, unknown>) } : {};
+
+  if (model) {
+    section.taskModel = { provider: model.provider, id: model.id };
+  } else {
+    // biome-ignore lint/performance/noDelete: one-off settings rewrite, not a hot path; removing the key (vs setting undefined) keeps the JSON clean
+    delete section.taskModel;
+  }
+  raw[SETTINGS_KEY] = section;
+
+  mkdirSync(dirname(settingsPath), { recursive: true });
+  writeFileSync(settingsPath, `${JSON.stringify(raw, null, 2)}\n`, "utf-8");
+}
+
+export function loadTaskConfig(cwd: string): TaskConfig {
+  let globalPath: string;
+  try {
+    globalPath = join(getAgentDir(), "settings.json");
+  } catch {
+    globalPath = "";
+  }
+  const projectPath = join(cwd, ".pi", "settings.json");
+
+  return {
+    ...TASK_DEFAULTS,
+    ...(globalPath ? readNamespacedConfig(globalPath) : {}),
+    ...readNamespacedConfig(projectPath),
+  };
+}