@zosmaai/pi-llm-wiki 0.11.2 → 0.11.4

package/dist/mcp/operations.js

@@ -5,8 +5,9 @@
  * used by Pi tools. No operation parses YAML, scans files, scores
  * registry entries, or builds page strings itself.
  */
+import { bootstrapVault } from "../extensions/llm-wiki/lib/bootstrap.js";
 import { rebuildMetadata } from "../extensions/llm-wiki/lib/metadata.js";
-import { searchWiki } from "../extensions/llm-wiki/lib/recall.js";
+import { searchWikiLayered } from "../extensions/llm-wiki/lib/recall.js";
 import { saveInsight } from "../extensions/llm-wiki/lib/retro.js";
 import { captureFile, captureText, captureUrl } from "../extensions/llm-wiki/lib/source-packet.js";
 import { VaultWriteError, inspectVaultFormat, inspectWritableVault, } from "../extensions/llm-wiki/lib/vault-format.js";
@@ -19,9 +20,44 @@ function projectionOutcome(projection) {
             diagnostics: projection.diagnostics.map(({ code, message }) => ({ code, message })),
         };
 }
-/** Shared recall operation: calls searchWiki and appends vault diagnostics. */
+/**
+ * Shared bootstrap operation: create (or update) the vault at `paths`.
+ *
+ * This is the one operation that must work when no vault exists — every other
+ * one fails closed naming it. `bootstrapVault` is pure Node (`node:fs`,
+ * `node:path` and sibling lib modules), so it needs no model and no
+ * credentials, which is what makes it fit the MCP surface.
+ *
+ * A failed projection rebuild is reported as diagnostics alongside `ok: true`:
+ * the vault has been written to disk by then, and `wiki_lint` is the repair
+ * path, so failing the call outright would misreport what happened.
+ */
+export async function bootstrapOperation(paths, input) {
+    const result = bootstrapVault(paths, { topic: input.topic, mode: input.mode ?? "personal" });
+    if (!result.ok) {
+        return {
+            ok: false,
+            diagnostics: result.diagnostics.map(({ code, message }) => ({ code, message })),
+        };
+    }
+    const projection = projectionOutcome(result.projection);
+    return {
+        ok: true,
+        created: result.created,
+        diagnostics: projection.ok ? [] : projection.diagnostics,
+    };
+}
+/**
+ * Shared recall operation: layered search plus vault diagnostics.
+ *
+ * Layering is the shared contract, not an extension-only feature: MCP clients
+ * get the same personal + project merge the Pi `wiki_recall` tool does.
+ * `searchWikiLayered` appends personal-vault hits, deduplicates by page ID and
+ * tags personal results with `vaultLabel`. It is a no-op when no personal vault
+ * exists, or when the resolved vault IS the personal vault.
+ */
 export async function recallOperation(paths, query, maxResults = 5) {
-    const results = searchWiki(paths, query, maxResults);
+    const results = searchWikiLayered(paths, query, maxResults);
     const vaultState = inspectVaultFormat(paths);
     return {
         results,

package/docs/api.md

@@ -223,6 +223,10 @@ Deterministic health check of the wiki. Scans for orphan pages (no inbound links
 (linked but not created), and contradiction markers. Optionally auto-creates stub pages for
 knowledge gaps cited in two or more pages.
 
+Runs **asynchronously**: the tool acknowledges immediately and scans off-thread. On completion a
+UI toast fires instantly (when a UI is available) and the full health report is delivered with
+the next user message.
+
 **Parameters**
 
 | Name | Type | Required | Description |
@@ -277,9 +281,13 @@ Health is `"⚠️ Warning"` when orphan count exceeds 5, `"🔴 Empty"` when th
 
 ## wiki_rebuild_meta
 
-Force a full synchronous rebuild of all generated metadata: `registry.json`, `backlinks.json`,
+Force a full rebuild of all generated metadata: `registry.json`, `backlinks.json`,
 `index.md`, `log.md`. Use when metadata appears out of sync with actual wiki files.
 
+Runs **asynchronously**: the tool acknowledges immediately and rebuilds off-thread. On completion
+a UI toast fires instantly (when a UI is available) and the result is delivered with the next
+user message.
+
 If `meta/events.jsonl` is missing or unreadable, rebuild reports a warning and preserves existing log projections while continuing to rebuild registry, backlinks, and indexes. A present zero-byte event file is an intentional empty history.
 
 **Parameters**

package/docs/configuration.md

@@ -31,17 +31,34 @@ The personal vault lives at `~/.llm-wiki/` (or `$WIKI_HOME`) and is always avail
 | ----------------------------- | ----------- | ----------------------------------------------- |
 | `WIKI_HOME`                   | `~/.llm-wiki` | Override the personal wiki vault location     |
 | `WIKI_MARKITDOWN_TIMEOUT_MS` | 180000      | Timeout (ms) for MarkItDown PDF/text extraction |
+| `LLM_WIKI_HOST`              | auto        | Force the host layout: `pi` or `omp`            |
 
-## Pi Agent Settings
+## Agent Settings
 
-Runtime settings for the wiki's background tasks live in `.pi/settings.json` under the `llm-wiki` namespace. These can be set globally (`~/.pi/agent/settings.json`) or per-project (`<cwd>/.pi/settings.json`).
+Runtime settings for the wiki's background tasks live under the `llm-wiki`
+namespace of the host's settings file. Both host layouts are read and merged,
+lowest precedence first:
 
-| Setting               | Default | Description                                                  |
-| --------------------- | ------- | ------------------------------------------------------------ |
-| `taskModel`           | —       | Model for background tasks (`{ provider: "openai", id: "gpt-4o" }`) |
-| `synthesisLanguage`   | —       | BCP 47 language tag for ingest synthesis (e.g. `"ru"`, `"fr"`). When unset, synthesis defaults to English. |
-| `trajectories`        | false   | Enable agent-trajectory working-memory                       |
-| `notices`             | true    | Show wiki activity notices in chat                           |
+1. `<agentDir>/settings.json`, then `config.yml` / `config.yaml`
+   — `~/.pi/agent` under pi, `~/.omp/agent` under oh-my-pi
+2. `<cwd>/.pi/{settings.json,config.yml,config.yaml}`
+3. `<cwd>/.omp/{settings.json,config.yml,config.yaml}`
+
+The **host-native** project directory is applied last, so it wins: `.omp` under
+oh-my-pi, `.pi` under pi. Reading the other host's directory means a vault
+configured under pi keeps working after `omp` takes over the repository.
+
+`/wiki-model` and `/wiki-trajectories` write JSON only, into whichever project
+config directory already exists (host-native first, created if neither is
+present). A hand-authored `config.yml` is read but never rewritten.
+
+| Setting                | Default    | Description                                                  |
+| ---------------------- | ---------- | ------------------------------------------------------------ |
+| `taskModel`            | —          | Model for background tasks (`{ provider: "openai", id: "gpt-4o" }`) |
+| `synthesisLanguage`    | —          | BCP 47 language tag for ingest synthesis (e.g. `"ru"`, `"fr"`). When unset, synthesis defaults to English. |
+| `trajectories`         | false      | Enable agent-trajectory working-memory                       |
+| `notices`              | true       | Show wiki activity notices in chat                           |
+| `ambientPersonalVault` | host-dependent | Let the personal vault act as the ambient vault in projects that have no wiki. `true` under pi, `false` under oh-my-pi — see below. |
 
 Example:
 
@@ -66,6 +83,30 @@ The vault root is resolved in this priority order:
 
 This means when you're in a project with its own `.llm-wiki/`, that project wiki is active. When you're outside any project wiki, your personal `~/.llm-wiki/` takes over automatically.
 
+### Ambient surfaces in projects without a wiki
+
+Three surfaces fire without being asked: the session notice, the periodic
+observe/retro reminder, and the `before_agent_start` recall injection (plus its
+`<wiki_status>` system-prompt footer).
+
+Because vault resolution falls back to the personal vault, those surfaces would
+otherwise speak up in *every* directory as soon as `~/.llm-wiki/` exists —
+injecting reminders and unrelated cross-project recall hits into repositories
+where no wiki was ever initialized. Under oh-my-pi the plugin is installed once
+and loads in every project, so that fallback is **off** by default there; under
+pi the historical behaviour is kept.
+
+`ambientPersonalVault` overrides the host default in either direction:
+
+```json
+{ "llm-wiki": { "ambientPersonalVault": true } }
+```
+
+The gate only affects unprompted injections. Tools and slash commands are
+always registered, so `/wiki-init` and `wiki_bootstrap` work in any directory —
+and once a project has its own `.llm-wiki/`, every ambient surface turns back on
+for it.
+
 ## Page Frontmatter
 
 ```yaml

package/extensions/llm-wiki/index.ts

@@ -20,7 +20,12 @@ import {
 } from "./lib/recall.js";
 import { registerWikiRetro } from "./lib/retro.js";
 import { registerBackgroundRuntime } from "./lib/runtime.js";
-import { loadTaskConfig, noticesEnabled, trajectoriesEnabled } from "./lib/task-config.js";
+import {
+  loadTaskConfig,
+  noticesEnabled,
+  personalVaultIsAmbient,
+  trajectoriesEnabled,
+} from "./lib/task-config.js";
 import {
   registerWikiBootstrap,
   registerWikiCaptureSource,
@@ -40,7 +45,11 @@ import {
   registerWikiDistillSkills,
   registerWikiRecallSkill,
 } from "./lib/trajectory.js";
-import { migrateDoubledPersonalVault, resolveVaultPaths } from "./lib/utils.js";
+import {
+  migrateDoubledPersonalVault,
+  resolveProjectVaultRoot,
+  resolveVaultPaths,
+} from "./lib/utils.js";
 import { inspectWritableVault } from "./lib/vault-format.js";
 import { applySessionStartStatus } from "./lib/visible-status.js";
 
@@ -68,6 +77,26 @@ export default function (pi: ExtensionAPI) {
   // work. Created first so tools (e.g. wiki_ingest) can dispatch to it.
   const runtime = registerBackgroundRuntime(pi);
 
+  /**
+   * Does a wiki apply to the directory this session is working in?
+   *
+   * Gates every AMBIENT surface — the ones that speak without being asked:
+   * session bootstrap/notice, the periodic observe/retro reminder, and
+   * `before_agent_start` recall injection. Tools and commands are registered
+   * regardless, so `/wiki-init` remains the way in.
+   *
+   * `resolveVaultRoot` falls back to the personal vault when a project has
+   * none, which is why the ambient surfaces used to fire in EVERY directory
+   * once a personal vault existed — reminders and unrelated cross-project
+   * recall hits leaking into repositories that never initialized a wiki.
+   * Under omp that fallback is off by default (`llm-wiki.ambientPersonalVault`);
+   * under pi it stays on, preserving the historical behavior.
+   *
+   * Resolved per call, not once at load: `cwd` changes within a session.
+   */
+  const wikiAppliesTo = (cwd: string): boolean =>
+    resolveProjectVaultRoot(cwd) !== null || personalVaultIsAmbient(runtime.config);
+
   registerWikiBootstrap(pi);
   registerWikiCaptureSource(pi, runtime);
   registerWikiIngest(pi, runtime);
@@ -106,9 +135,11 @@ export default function (pi: ExtensionAPI) {
   registerWikiObserve(pi, runtime, reminderState);
   // Visible observe/retro reminder by default (issue #77); silenced when the
   // user sets `llm-wiki.notices: false`. Resolver reads the live config so the
-  // setting takes effect without a restart.
+  // setting takes effect without a restart. `display: false` still injects the
+  // reminder into model context, so the "no wiki here" case needs its own gate.
   registerObservationReminder(pi, reminderState, {
     display: () => noticesEnabled(runtime.config),
+    enabled: () => wikiAppliesTo(process.cwd()),
   });
 
   installGuardrails(pi, runtime);
@@ -137,6 +168,12 @@ export default function (pi: ExtensionAPI) {
       console.warn(`[llm-wiki] doubled-dotdir migration skipped: ${(err as Error).message}`);
     }
 
+    // Ambient gate. `ensureConfig` first so an explicit
+    // `llm-wiki.ambientPersonalVault` is honored on the very first session —
+    // `runtime.config` is otherwise empty until the first `turn_start`.
+    runtime.ensureConfig(process.cwd());
+    if (!wikiAppliesTo(process.cwd())) return;
+
     const paths = resolveVaultPaths(process.cwd());
     if (!existsSync(join(paths.dotWiki, "config.json"))) {
       // Silently create the wiki vault — no UI prompts. Topic/mode will be
@@ -168,9 +205,8 @@ export default function (pi: ExtensionAPI) {
 
     // Surface the "wiki active" badge and the active background task model
     // (issue #69), both gated by `llm-wiki.notices` (issue #77, regression
-    // fixed in #83, helper extracted in #84). `ensureConfig` MUST run first so
-    // the gate sees the loaded project settings.
-    runtime.ensureConfig(process.cwd());
+    // fixed in #83, helper extracted in #84). The `ensureConfig` above the
+    // ambient gate already loaded the project settings this reads.
     applySessionStartStatus({
       ui: ctx.ui,
       runtime,
@@ -196,6 +232,8 @@ export default function (pi: ExtensionAPI) {
   //    from the user's first prompt and update config via wiki_bootstrap.
   // 2. Search both personal + project vaults for relevant pages.
   pi.on("before_agent_start", async (event, ctx) => {
+    if (!wikiAppliesTo(process.cwd())) return;
+
     const paths = resolveVaultPaths(process.cwd());
     if (!existsSync(join(paths.dotWiki, "config.json"))) {
       return;

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

@@ -0,0 +1,125 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { getAgentDir } from "@mariozechner/pi-coding-agent";
+
+/**
+ * Host adapter for the two coding agents that can load this extension:
+ *
+ *  - **pi**   — `@mariozechner/pi-coding-agent`, config dir `.pi`
+ *  - **omp**  — oh-my-pi (`@oh-my-pi/pi-coding-agent`), config dir `.omp`
+ *
+ * omp rewrites `@mariozechner/pi-*` (and bare `typebox`) imports onto its own
+ * bundled packages at load time (its `legacy-pi-compat.ts`), so the *module
+ * graph* needs no changes. What does differ is the on-disk config layout:
+ *
+ * | | pi | omp |
+ * |---|---|---|
+ * | user dir      | `~/.pi/agent`   | `~/.omp/agent` |
+ * | project dir   | `<cwd>/.pi`     | `<cwd>/.omp`   |
+ * | settings file | `settings.json` | `settings.json`, then `config.yml` |
+ *
+ * omp explicitly does **not** read `.pi` (its config source order is
+ * `.omp` → `.claude` → `.codex` → `.gemini`), so a wiki configured under pi
+ * would silently lose its settings after switching hosts. This module keeps
+ * both layouts readable and picks a sensible file to write to.
+ *
+ * Everything here is additive: on pi with only a `.pi/` directory the effective
+ * behaviour is identical to the pre-compat code path, which keeps upstream
+ * merges clean.
+ */
+
+export type HostKind = "pi" | "omp";
+
+/** Project config directory name per host. */
+const CONFIG_DIR: Record<HostKind, string> = { pi: ".pi", omp: ".omp" };
+
+/** Settings file names inside a config directory, lowest → highest precedence. */
+const SETTINGS_FILES = ["settings.json", "config.yml", "config.yaml"] as const;
+
+/**
+ * Detect which agent is hosting this extension.
+ *
+ * Ordered by reliability:
+ *  1. `LLM_WIKI_HOST` — explicit escape hatch (tests, exotic embeddings).
+ *  2. The agent directory path: pi resolves `~/.pi/agent`, omp `~/.omp/agent`.
+ *     A `PI_CODING_AGENT_DIR` override that keeps the marker segment still
+ *     classifies correctly; anything else falls through.
+ *  3. `OMP_PROFILE`, which omp sets on itself whenever a profile is active.
+ *  4. Default `pi` — the historical behaviour.
+ */
+export function detectHost(): HostKind {
+  const forced = process.env.LLM_WIKI_HOST?.trim().toLowerCase();
+  if (forced === "omp" || forced === "pi") return forced;
+
+  let agentDir = "";
+  try {
+    agentDir = getAgentDir();
+  } catch {
+    agentDir = "";
+  }
+  if (agentDir) {
+    const segments = agentDir.split(/[\\/]/);
+    if (segments.includes(".omp")) return "omp";
+    if (segments.includes(".pi")) return "pi";
+  }
+
+  if (process.env.OMP_PROFILE !== undefined) return "omp";
+  return "pi";
+}
+
+/**
+ * Every project settings file that may hold `llm-wiki` configuration, ordered
+ * from lowest to highest precedence so callers can merge left-to-right.
+ *
+ * The host's *native* directory is last (wins). The foreign directory is still
+ * read so a vault configured under pi keeps working after omp takes over the
+ * repository, and vice versa. Within a directory `config.yml` follows
+ * `settings.json`, matching omp's own project-settings precedence.
+ */
+export function listProjectSettingsFiles(cwd: string, host: HostKind = detectHost()): string[] {
+  const foreign: HostKind = host === "omp" ? "pi" : "omp";
+  const files: string[] = [];
+  for (const kind of [foreign, host]) {
+    const dir = join(cwd, CONFIG_DIR[kind]);
+    for (const name of SETTINGS_FILES) files.push(join(dir, name));
+  }
+  return files;
+}
+
+/**
+ * User-level settings files, lowest → highest precedence.
+ *
+ * `getAgentDir()` already resolves per host (`~/.pi/agent` vs `~/.omp/agent`),
+ * so only the file names differ: omp migrates `settings.json` into `config.yml`
+ * on first start, and a migrated install has *only* the YAML file.
+ */
+export function listGlobalSettingsFiles(): string[] {
+  let agentDir = "";
+  try {
+    agentDir = getAgentDir();
+  } catch {
+    return [];
+  }
+  if (!agentDir) return [];
+  return SETTINGS_FILES.map((name) => join(agentDir, name));
+}
+
+/**
+ * The project settings file this extension writes to.
+ *
+ * Always JSON (`settings.json`) — both hosts read it, and rewriting a user's
+ * hand-authored `config.yml` would destroy comments and formatting.
+ *
+ * Directory choice: an already-existing project config directory wins (so a
+ * repo that only has `.pi/` keeps a single settings file), otherwise the
+ * detected host's native directory is created.
+ */
+export function resolveProjectSettingsPath(cwd: string, host: HostKind = detectHost()): string {
+  const native = join(cwd, CONFIG_DIR[host]);
+  if (existsSync(native)) return join(native, "settings.json");
+
+  const foreign = join(cwd, CONFIG_DIR[host === "omp" ? "pi" : "omp"]);
+  if (existsSync(foreign)) return join(foreign, "settings.json");
+
+  return join(native, "settings.json");
+}

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

@@ -322,11 +322,20 @@ export function buildReminderText(): string {
  * `options.display` (issue #77) controls whether the reminder is shown to the
  * user (`true`, the default) or injected silently into model context only
  * (`false`). Pass a resolver so the live `notices` config is read at send time.
+ *
+ * `options.enabled` gates the reminder entirely — note that `display: false`
+ * still injects it into model context, so it is NOT a way to switch the
+ * reminder off. Callers pass a resolver that answers "does a wiki apply to the
+ * current working directory", evaluated per turn because the session can move.
  */
 export function registerObservationReminder(
   pi: ExtensionAPI,
   reminderState: ReminderState,
-  options?: { turnsBetweenReminders?: number; display?: boolean | (() => boolean) },
+  options?: {
+    turnsBetweenReminders?: number;
+    display?: boolean | (() => boolean);
+    enabled?: () => boolean;
+  },
 ): void {
   const REMINDER_INTERVAL = options?.turnsBetweenReminders ?? 5;
   const resolveDisplay = (): boolean => {
@@ -355,6 +364,10 @@ export function registerObservationReminder(
     // errors cause multiple retries, each firing agent_end).
     if ("willRetry" in event && (event as { willRetry?: boolean }).willRetry) return;
 
+    // No wiki applies here: never nag, and never accumulate a pending reminder
+    // that would fire the moment the session moves into a wiki-bearing project.
+    if (options?.enabled && !options.enabled()) return;
+
     turnsSinceLastReminder++;
     if (turnsSinceLastReminder < REMINDER_INTERVAL) return;
     if (reminderState.observeDoneThisSession) return;

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

@@ -213,8 +213,20 @@ export class Runtime {
    */
   launchReported(ctx: LaunchCtx, label: string, work: () => Promise<string | null>): Promise<void> {
     return this.launchTask(ctx, label, async () => {
+      // Capture synchronously — after `await work()` the extension ctx may be
+      // a stale proxy (newSession/fork/switchSession/reload) and accessing
+      // ctx.hasUI or ctx.ui on it throws (see launchTask).
+      const hasUI = ctx.hasUI;
+      const ui = ctx.ui;
       const summary = await work();
-      if (summary) this.report(summary);
+      if (summary) {
+        // Instant completion feedback: the nextTurn report below is queued for
+        // the next user prompt, so without a toast a background task looks
+        // stuck. Mirrors the failure notification in launchTask and the
+        // success toast already used by wiki_ingest.
+        if (hasUI && ui) ui.notify(summary.split("\n")[0].replace(/\*\*/g, ""), "info");
+        this.report(summary);
+      }
     });
   }