@zosmaai/pi-llm-wiki 0.11.4 → 0.11.5

package/extensions/llm-wiki/index.ts

@@ -2,6 +2,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { basename, join } from "node:path";
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import { bootstrapVault } from "./lib/bootstrap.js";
+import { registerWikiDashboardCommand } from "./lib/dashboard-command.js";
 import { installGuardrails } from "./lib/guardrails.js";
 import { buildAgentStartInjection, normalizeSystemPrompt } from "./lib/inject.js";
 import { registerWikiModelCommand } from "./lib/model-command.js";
@@ -20,6 +21,7 @@ import {
 } from "./lib/recall.js";
 import { registerWikiRetro } from "./lib/retro.js";
 import { registerBackgroundRuntime } from "./lib/runtime.js";
+import { registerWikiSettingsCommand } from "./lib/settings-command.js";
 import {
   loadTaskConfig,
   noticesEnabled,
@@ -131,6 +133,8 @@ export default function (pi: ExtensionAPI) {
   // background task model. The taskModel config field + resolveModel already
   // exist; this exposes them to the user (default stays the session model).
   registerWikiModelCommand(pi, runtime);
+  registerWikiSettingsCommand(pi, runtime);
+  registerWikiDashboardCommand(pi, runtime);
   const reminderState = createReminderState();
   registerWikiObserve(pi, runtime, reminderState);
   // Visible observe/retro reminder by default (issue #77); silenced when the

package/extensions/llm-wiki/lib/dashboard-command.ts

@@ -0,0 +1,106 @@
+/**
+ * /wiki-dashboard command.
+ *
+ * Read-only mirror of /wiki-settings: one persistent screen, Esc closes.
+ * Unlike settings there is no per-key change — every line is computed once
+ * from on-disk vault state (see lib/dashboard.ts) and rendered as plain
+ * text through a Container + Text.
+ */
+import type { ExtensionAPI, ExtensionCommandContext } from "@mariozechner/pi-coding-agent";
+import { Container, Text, matchesKey } from "@mariozechner/pi-tui";
+import { type DashboardStats, collectDashboardStats } from "./dashboard.js";
+import type { Runtime } from "./runtime.js";
+
+type App = ExtensionAPI;
+
+const TYPE_ORDER = [
+  "concept",
+  "entity",
+  "source",
+  "skill",
+  "analysis",
+  "synthesis",
+  "requirement",
+  "short",
+  "shared",
+];
+const KIND_ORDER = ["observe", "retro", "synth", "intake"];
+
+function orderedPairs(counts: Record<string, number>): string {
+  const keys = Object.keys(counts);
+  const known = TYPE_ORDER.filter((k) => counts[k] !== undefined);
+  const rest = keys
+    .filter((k) => !TYPE_ORDER.includes(k))
+    .sort()
+    .slice(0, 3); // cap the tail: the dashboard is a glance, not a census
+  const all = [...known, ...rest];
+  if (all.length === 0) return "—";
+  return all.map((k) => `${k} ${counts[k]}`).join(" · ");
+}
+
+function orderedKinds(counts: Record<string, number>): string {
+  const keys = Object.keys(counts);
+  const known = KIND_ORDER.filter((k) => counts[k] !== undefined);
+  const rest = keys
+    .filter((k) => !KIND_ORDER.includes(k))
+    .sort()
+    .slice(0, 3);
+  return [...known, ...rest].map((k) => `${k} ${counts[k]}`).join(" · ");
+}
+
+function renderStatsLines(s: DashboardStats): string[] {
+  const emb = s.embEnabled ? `${s.embFiles}/${s.pageCount}` : "—";
+  return [
+    `Wiki Dashboard · ${s.root}`,
+    "",
+    `Pages   ${s.pageCount} · ${s.sizeKB}KB · ${orderedPairs(s.byType)}`,
+    `Fresh   last touch ${s.lastTouch || "never"} · stale(>30d) ${s.staleCount}`,
+    `Acts 7d ${s.last7dTotal > 0 ? orderedKinds(s.last7dByKind) : "none"} · total ${s.last7dTotal}/${s.totalEvents}`,
+    `Queue   raw ${s.rawQueue} · emb ${emb}`,
+    `Links   zero-backlink ${s.zeroBacklinks} · full scan: /wiki-lint`,
+    "",
+    "Esc to close",
+  ];
+}
+
+/** One-screen read-only TUI; handles Esc and `q`. */
+export class DashboardScreen extends Container {
+  private doneFn: (result?: unknown) => void;
+
+  constructor(lines: string[], close: (result?: unknown) => void) {
+    super();
+    this.doneFn = close;
+    this.addChild(new Text(lines.join("\n"), 1, 1));
+  }
+
+  handleInput(data: string): void {
+    // ponytail: matchesKey handles every terminal key shape (raw bytes,
+    // kitty CSI-u like \u001b[27u for Esc, ctrl combos) — a raw === "\u001b"
+    // check only works in terminals without the kitty keyboard protocol,
+    // which is exactly where Ghostty users' Esc went nowhere.
+    if (matchesKey(data, "escape") || matchesKey(data, "q")) {
+      this.doneFn();
+    }
+  }
+}
+
+/**
+ * Register the /wiki-dashboard command.
+ */
+export function registerWikiDashboardCommand(pi: ExtensionAPI, runtime: Runtime): void {
+  pi.registerCommand("wiki-dashboard", {
+    description:
+      "Show a read-only LLM Wiki dashboard (pages, freshness, activity, queue, links, emb)",
+    handler: async (_args: string, ctx: ExtensionCommandContext): Promise<void> => {
+      runtime.ensureConfig(ctx.cwd);
+      if (!ctx.hasUI) {
+        ctx.ui.notify("LLM Wiki: /wiki-dashboard requires an interactive UI.", "warning");
+        return;
+      }
+      const stats = await collectDashboardStats(ctx.cwd);
+      await ctx.ui.custom((_tui, _theme, _keybindings, close) => {
+        return new DashboardScreen(renderStatsLines(stats), close);
+      });
+    },
+  });
+}

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

@@ -0,0 +1,210 @@
+/**
+ * Read-only vault statistics for the /wiki-dashboard screen.
+ *
+ * Everything is computed from pre-existing on-disk state:
+ *  - page tree (paths.wiki + skills dir): counts, mtimes, sizes
+ *  - meta/registry.json: page types (values; keys can carry legacy prefix noise)
+ *  - meta/backlinks.json: zero-inbound pages
+ *  - meta/events.jsonl: activity stream (observes/retros/syntheses...)
+ *  - raw/sources: pending ingest queue
+ *  - emb/: embedding coverage
+ *
+ * No writes, no LLM calls, no new files. Pure reader.
+ */
+import { readFile, readdir, stat } from "node:fs/promises";
+import type { VaultPaths } from "./utils.js";
+import { readJson, resolveVaultPaths } from "./utils.js";
+
+interface PageInfo {
+  rel: string;
+  mtime: number;
+  bytes: number;
+}
+
+export interface DashboardStats {
+  /** Vault root directory, as shown in the header. */
+  root: string;
+  /** Total .md pages across wiki + skills dirs (filesystem truth). */
+  pageCount: number;
+  /** Page count by registry type; unknown types fall back to the folder name. */
+  byType: Record<string, number>;
+  /** Total page size in KB (rounded up to at least 1). */
+  sizeKB: number;
+  /** Human age of the most recent page touch: "now" | "Xm" | "Xh" | "Xd" | "". */
+  lastTouch: string;
+  /** Pages untouched for 30+ days. */
+  staleCount: number;
+  /** Event kinds (observe/retro/synth/intake/...) seen in the last 7 days. */
+  last7dByKind: Record<string, number>;
+  /** Total events in the last 7 days. */
+  last7dTotal: number;
+  /** Total parseable events recorded. */
+  totalEvents: number;
+  /** Number of raw source packets awaiting ingest (subdirs of raw/sources). */
+  rawQueue: number;
+  /** Pages with zero backlinks (from backlinks.json). */
+  zeroBacklinks: number;
+  /** .bin files in emb/ (meaningful when embeddings are enabled). */
+  embFiles: number;
+  /** Emb dir is populated — embeddings appear enabled. */
+  embEnabled: boolean;
+}
+
+/** Directories excluded from the page walk (infrastructure, not pages). */
+const SKIP_DIRS = new Set([
+  "templates",
+  "cases",
+  "outputs",
+  ".discoveries",
+  "raw",
+  "meta",
+  "emb",
+  ".git",
+]);
+
+async function walkPages(dir: string, rel: string, out: PageInfo[]): Promise<void> {
+  try {
+    const entries = await readdir(dir, { withFileTypes: true });
+    for (const e of entries) {
+      const childRel = rel === "" ? e.name : `${rel}/${e.name}`;
+      if (e.isDirectory()) {
+        if (SKIP_DIRS.has(e.name)) continue;
+        await walkPages(`${dir}/${e.name}`, childRel, out);
+        continue;
+      }
+      if (!e.name.endsWith(".md")) continue;
+      try {
+        const st = await stat(`${dir}/${e.name}`);
+        out.push({ rel: childRel, mtime: st.mtimeMs, bytes: st.size });
+      } catch {
+        // unreadable file: skip
+      }
+    }
+  } catch {
+    // missing dir (empty vault): nothing to walk
+  }
+}
+
+function humanAge(ms: number): string {
+  const mins = Math.floor(ms / 60_000);
+  if (mins < 1) return "now";
+  if (mins < 60) return `${mins}m`;
+  const hrs = Math.floor(mins / 60);
+  if (hrs < 48) return `${hrs}h`;
+  return `${Math.floor(hrs / 24)}d`;
+}
+
+async function readEvents(metaDir: string) {
+  const byKind: Record<string, number> = {};
+  let recent = 0;
+  let total = 0;
+  try {
+    const raw = await readFile(`${metaDir}/events.jsonl`, "utf-8");
+    const cutoff = Date.now() - 7 * 86400_000;
+    for (const line of raw.split("\n")) {
+      if (!line.trim()) continue;
+      let ev: { timestamp?: unknown; kind?: unknown };
+      try {
+        ev = JSON.parse(line);
+      } catch {
+        continue; // corrupted line: skip, not fatal
+      }
+      const ts = typeof ev.timestamp === "string" ? Date.parse(ev.timestamp) : Number.NaN;
+      const kind = typeof ev.kind === "string" && ev.kind ? ev.kind : "event";
+      total += 1;
+      if (Number.isFinite(ts) && ts >= cutoff) {
+        byKind[kind] = (byKind[kind] ?? 0) + 1;
+        recent += 1;
+      }
+    }
+  } catch {
+    // no events file: zeros
+  }
+  return { byKind, recent, total };
+}
+
+/**
+ * Collect all dashboard stats for the vault reachable from `cwd`.
+ * Reuses the extension's own path resolution (same root the tools see).
+ */
+export async function collectDashboardStats(cwd: string): Promise<DashboardStats> {
+  const paths: VaultPaths = resolveVaultPaths(cwd);
+
+  const pages: PageInfo[] = [];
+  await walkPages(paths.wiki, "", pages);
+  // skill pages register as type:skill and live under <dotWiki>/skills
+  try {
+    const st = await stat(`${paths.dotWiki}/skills`);
+    if (st.isDirectory()) {
+      await walkPages(`${paths.dotWiki}/skills`, "skills", pages);
+    }
+  } catch {
+    // no skills dir: fine
+  }
+
+  // type map from registry values — keys may carry legacy noise, so normalize
+  const registry = readJson<{ pages?: Record<string, { type?: string }> }>(
+    `${paths.meta}/registry.json`,
+    { pages: {} },
+  );
+  const typeByKey: Record<string, string> = {};
+  for (const [key, val] of Object.entries(registry.pages ?? {})) {
+    const norm = key.startsWith('"') ? key.slice(1) : key;
+    if (val?.type) typeByKey[norm] = val.type;
+  }
+  const byType: Record<string, number> = {};
+  for (const p of pages) {
+    const slug = p.rel.endsWith(".md") ? p.rel.slice(0, -3) : p.rel;
+    const type = typeByKey[slug] ?? p.rel.split("/")[0] ?? "other";
+    byType[type] = (byType[type] ?? 0) + 1;
+  }
+
+  let sizeBytes = 0;
+  let latestMtime = 0;
+  const staleCutoff = Date.now() - 30 * 86400_000;
+  let stale = 0;
+  for (const p of pages) {
+    sizeBytes += p.bytes;
+    if (p.mtime > latestMtime) latestMtime = p.mtime;
+    if (p.mtime < staleCutoff) stale += 1;
+  }
+
+  const events = await readEvents(paths.meta);
+
+  let rawQueue = 0;
+  try {
+    const pkts = await readdir(paths.rawSources, { withFileTypes: true });
+    for (const e of pkts) {
+      if (e.isDirectory()) rawQueue += 1; // each subdirectory is one packet
+    }
+  } catch {
+    // no raw/sources: empty queue
+  }
+
+  const backlinks = readJson<Record<string, string[]>>(`${paths.meta}/backlinks.json`, {});
+  const zeroBacklinks = Object.values(backlinks).filter((v) => (v ?? []).length === 0).length;
+
+  let embFiles = 0;
+  try {
+    const embEntries = await readdir(`${paths.dotWiki}/emb`);
+    embFiles = embEntries.filter((f) => f.endsWith(".bin")).length;
+  } catch {
+    // no emb dir: none
+  }
+
+  return {
+    root: paths.root,
+    pageCount: pages.length,
+    byType,
+    sizeKB: Math.max(1, Math.round(sizeBytes / 1024)),
+    lastTouch: pages.length === 0 ? "" : humanAge(Date.now() - latestMtime),
+    staleCount: stale,
+    last7dByKind: events.byKind,
+    last7dTotal: events.recent,
+    totalEvents: events.total,
+    rawQueue,
+    zeroBacklinks,
+    embFiles,
+    embEnabled: embFiles > 0,
+  };
+}

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

@@ -79,12 +79,34 @@ function parseMoveDestination(line: string): string | undefined {
 function scanPatchString(input: string): MutationScan {
   const paths: string[] = [];
   let sawHeader = false;
+  let sawApplyPatchHeader = false;
+  let applyPatchComplete = true;
   let sectionHasMove = false;
   let complete = true;
   const stripped = input.startsWith("\uFEFF") ? input.slice(1) : input;
 
   for (const line of stripped.split("\n")) {
-    const trimmed = line.replace(/\r$/, "").trim();
+    const raw = line.replace(/\r$/, "");
+    // apply_patch envelope headers (#162): matched on the raw (untrimmed)
+    // line so body rows (space/+/- prefixed) that quote the envelope shape
+    // are never mistaken for headers.
+    const fileOp = /^\*{3}\s+(?:update|add|delete)\s+file:\s*(\S.*)$/i.exec(raw);
+    if (fileOp) {
+      sawApplyPatchHeader = true;
+      const path = normalizeMutationPath(fileOp[1]);
+      if (path) paths.push(path);
+      else applyPatchComplete = false;
+      continue;
+    }
+    const moveTo = /^\*{3}\s+move\s+to:\s*(\S.*)$/i.exec(raw);
+    if (moveTo) {
+      sawApplyPatchHeader = true;
+      const destination = normalizeMutationPath(moveTo[1]);
+      if (destination) paths.push(destination);
+      else applyPatchComplete = false;
+      continue;
+    }
+    const trimmed = raw.trim();
     if (trimmed.startsWith("[")) {
       sawHeader = true;
       sectionHasMove = false;
@@ -102,6 +124,9 @@ function scanPatchString(input: string): MutationScan {
     }
   }
 
+  if (sawApplyPatchHeader) {
+    return { paths, complete: applyPatchComplete && paths.length > 0 };
+  }
   return { paths, complete: sawHeader && complete };
 }
 

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

@@ -63,7 +63,7 @@ export function detectHost(): HostKind {
     if (segments.includes(".pi")) return "pi";
   }
 
-  if (process.env.OMP_PROFILE !== undefined) return "omp";
+  if (process.env.OMP_PROFILE) return "omp";
   return "pi";
 }
 
@@ -123,3 +123,23 @@ export function resolveProjectSettingsPath(cwd: string, host: HostKind = detectH
 
   return join(native, "settings.json");
 }
+
+/**
+ * The global (user-level) settings file this extension writes to.
+ *
+ * Always writes to `settings.json` inside the agent dir — both hosts read it.
+ */
+export function resolveGlobalSettingsPath(host: HostKind = detectHost()): string {
+  let agentDir = "";
+  try {
+    agentDir = getAgentDir();
+  } catch {
+    agentDir = "";
+  }
+  if (!agentDir) {
+    // Fallback: ~/.pi/agent/settings.json
+    const home = process.env.HOME || "~";
+    return join(home, ".pi", "agent", "settings.json");
+  }
+  return join(agentDir, "settings.json");
+}

package/extensions/llm-wiki/lib/ingest-worker.ts

@@ -475,6 +475,8 @@ export interface RunIngestSynthesisArgs {
   signal?: AbortSignal;
   /** BCP 47 language tag for narrative content (issue #124). */
   synthesisLanguage?: string;
+  /** Max output tokens for synthesizer sub-agent (issue #160). Default 16384. */
+  synthesisMaxTokens?: number;
 }
 
 /**
@@ -496,6 +498,7 @@ export async function runIngestSynthesis(
     maxChars,
     signal,
     synthesisLanguage,
+    synthesisMaxTokens,
   } = args;
   const content = extracted.slice(0, maxChars ?? 24_000);
   if (!content.trim()) return undefined;
@@ -549,6 +552,7 @@ export async function runIngestSynthesis(
     systemPrompt,
     userPrompt,
     tools: [commitTool as AgentTool],
+    maxTokens: synthesisMaxTokens ?? 16384,
     signal,
   });
 

package/extensions/llm-wiki/lib/knowledge-document.ts

@@ -588,6 +588,22 @@ export function serializeKnowledgeDocument(document: KnowledgeDocument): string
   return body ? `---\n${yaml}---\n\n${body}\n` : `---\n${yaml}---\n`;
 }
 
+/** Escape wikilink alias pipes so generated content remains valid in Markdown tables. */
+function escapeWikilinkAliasPipes(body: string): string {
+  let inFence = false;
+  return body
+    .split("\n")
+    .map((line) => {
+      if (/^\s*(`{3,}|~{3,})/.test(line)) {
+        inFence = !inFence;
+        return line;
+      }
+      if (inFence) return line;
+      return line.replace(/\[\[([^\]\n]*?)(?<!\\)\|([^\]\n]*?)\]\]/g, "[[$1\\|$2]]");
+    })
+    .join("\n");
+}
+
 export function createKnowledgeDocument<T extends KnowledgeCreationFields>(
   path: string,
   fields: T & NoInfer<KnowledgeCreationFields>,
@@ -614,7 +630,7 @@ export function createKnowledgeDocument<T extends KnowledgeCreationFields>(
     ? { kind: "canonical" as const, value: sources }
     : { kind: "absent" as const };
 
-  const normalizedBody = body.replace(/\r\n?/g, "\n").replace(/\n*$/, "");
+  const normalizedBody = escapeWikilinkAliasPipes(body.replace(/\r\n?/g, "\n")).replace(/\n*$/, "");
 
   return {
     id: path.replace(/\.md$/, ""),
@@ -643,7 +659,9 @@ export function patchKnowledgeDocument(
     }
   }
 
-  const newBody = patch.body ?? document.body;
+  const newBody = patch.body
+    ? escapeWikilinkAliasPipes(patch.body.replace(/\r\n?/g, "\n"))
+    : document.body;
 
   return {
     ...document,

package/extensions/llm-wiki/lib/knowledge-links.ts

@@ -33,13 +33,17 @@ function diag(
   return { severity, code, path, message };
 }
 
+function normalizeWikilinkTarget(target: string): string {
+  return target.trim().replace(/\\$/, "");
+}
+
 export function extractKnowledgeLinks(body: string): KnowledgeLinks {
   const markdown: ExtractedLink[] = [];
   const wikilinks: ExtractedLink[] = [];
 
-  // Extract legacy wikilinks
+  // Extract legacy wikilinks. A table-safe alias uses an escaped pipe: [[target\\|alias]].
   for (const match of body.matchAll(/\[\[([^\]|]+)(?:\|[^\]]*)?\]\]/g)) {
-    wikilinks.push({ target: match[1].trim(), offset: match.index ?? 0 });
+    wikilinks.push({ target: normalizeWikilinkTarget(match[1]), offset: match.index ?? 0 });
   }
 
   // Parse with CommonMark AST
@@ -111,7 +115,7 @@ export function extractKnowledgeLinks(body: string): KnowledgeLinks {
 export function extractLegacyWikilinks(body: string): ExtractedLink[] {
   const links: ExtractedLink[] = [];
   for (const match of body.matchAll(/\[\[([^\]|]+)(?:\|[^\]]*)?\]\]/g)) {
-    links.push({ target: match[1].trim(), offset: match.index ?? 0 });
+    links.push({ target: normalizeWikilinkTarget(match[1]), offset: match.index ?? 0 });
   }
   return links;
 }

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

@@ -508,7 +508,7 @@ export function buildDirectoryIndexes(
       lines.push("## Directories");
       lines.push("");
       for (const subDir of [...dirs].sort(compareCodePoint)) {
-        const encoded = `${encodeRelativePath(subDir)}/`;
+        const encoded = encodeRelativePath(`${subDir}/index.md`);
         lines.push(`- [${escapeLabel(subDir)}/](${encoded})`);
       }
     }

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

@@ -345,10 +345,12 @@ export function registerObservationReminder(
     return true;
   };
   let turnsSinceLastReminder = 0;
+  let agentEndsInUserTurn = 0;
 
   pi.on("session_start", async () => {
     turnsSinceLastReminder = 0;
     reminderState.observeDoneThisSession = false;
+    agentEndsInUserTurn = 0;
   });
 
   // After compaction, reset turn counter so reminders resume
@@ -358,10 +360,18 @@ export function registerObservationReminder(
     turnsSinceLastReminder = 0;
   });
 
+  // A retry re-runs the agent within the same user turn, and pi does not
+  // forward `willRetry` to extensions (zosmaai/pi-llm-wiki#151). Only the
+  // user-role message_start separates real user turns from retried agent
+  // runs, so the per-turn agent_end count resets there.
+  pi.on("message_start", async (event) => {
+    if (event.message.role === "user") agentEndsInUserTurn = 0;
+  });
+
   pi.on("agent_end", async (event, _ctx) => {
-    // Skip reminder on retries — willRetry means pi will re-run the agent,
-    // and queuing another reminder would duplicate them (issue: connection
-    // errors cause multiple retries, each firing agent_end).
+    // Legacy guard: this pi build does not forward `willRetry` to extension
+    // events, but keep the check in case a future one does. The dedup that
+    // actually works is the per-turn agent_end count below.
     if ("willRetry" in event && (event as { willRetry?: boolean }).willRetry) return;
 
     // No wiki applies here: never nag, and never accumulate a pending reminder
@@ -372,6 +382,12 @@ export function registerObservationReminder(
     if (turnsSinceLastReminder < REMINDER_INTERVAL) return;
     if (reminderState.observeDoneThisSession) return;
 
+    // One agent_end per user turn may queue a reminder. A rate-limit storm
+    // re-runs the agent several times within the same turn, each firing
+    // agent_end, so count them and let only the first through.
+    agentEndsInUserTurn++;
+    if (agentEndsInUserTurn > 1) return;
+
     pi.sendMessage(
       {
         customType: "wiki-observe-reminder",
@@ -382,5 +398,9 @@ export function registerObservationReminder(
         deliverAs: "nextTurn",
       },
     );
+
+    // Reset the interval counter after queueing: without it the count stays
+    // at/above the threshold and every later agent_end queues a reminder.
+    turnsSinceLastReminder = 0;
   });
 }