@zosmaai/pi-llm-wiki 0.11.4 → 0.11.6

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

@@ -1,6 +1,7 @@
 import type { Definition, Link, LinkReference, Nodes, Root } from "mdast";
 import { fromMarkdown } from "mdast-util-from-markdown";
 import type { KnowledgeDiagnostic } from "./knowledge-document.js";
+import { slugify } from "./utils.js";
 import { compareCodePoint } from "./vault-format.js";
 
 export interface ExtractedLink {
@@ -33,13 +34,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,11 +116,79 @@ 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;
 }
 
+// ── Wikilink normalization ──────────────────────────────────────────
+
+export interface WikilinkIndex {
+  /** NFC-normalized id → canonical id. */
+  byExact: Map<string, string>;
+  /** Slugified full path → matching canonical ids. */
+  byNormPath: Map<string, string[]>;
+  /** Slugified basename (no folder) → matching canonical ids. */
+  byNormSlug: Map<string, string[]>;
+}
+
+export function buildWikilinkIndex(ids: Iterable<string>): WikilinkIndex {
+  const byExact = new Map<string, string>();
+  const byNormPath = new Map<string, string[]>();
+  const byNormSlug = new Map<string, string[]>();
+
+  function push<K>(map: Map<K, string[]>, key: K, value: string): void {
+    const existing = map.get(key);
+    if (existing) existing.push(value);
+    else map.set(key, [value]);
+  }
+
+  for (const id of ids) {
+    byExact.set(id.normalize("NFC"), id);
+    const segments = id.split("/");
+    const normFull = segments.map((s) => slugify(s)).join("/");
+    const normBase = slugify(segments[segments.length - 1]);
+    push(byNormPath, normFull, id);
+    push(byNormSlug, normBase, id);
+  }
+
+  return { byExact, byNormPath, byNormSlug };
+}
+
+export type WikilinkResolution =
+  | { kind: "resolved"; id: string }
+  | { kind: "ambiguous"; target: string; candidates: string[] }
+  | { kind: "missing"; target: string };
+
+export function resolveWikilink(target: string, index: WikilinkIndex): WikilinkResolution {
+  const cleaned = target.trim().replace(/\\$/, "");
+  if (!cleaned) return { kind: "missing", target: "" };
+
+  // Fast path: exact NFC match
+  const exact = index.byExact.get(cleaned.normalize("NFC"));
+  if (exact) return { kind: "resolved", id: exact };
+
+  // Normalized full path (fixes case/space/slug drift in folder-qualified links)
+  const normFull = cleaned
+    .split("/")
+    .map((s) => slugify(s))
+    .join("/");
+  const pathHits = index.byNormPath.get(normFull);
+  if (pathHits && pathHits.length === 1) return { kind: "resolved", id: pathHits[0] };
+  if (pathHits && pathHits.length > 1)
+    return { kind: "ambiguous", target: cleaned, candidates: pathHits };
+
+  // Bare title: match by slugified basename (handles [[zosma harness]] → entities/zosma-harness)
+  if (!cleaned.includes("/")) {
+    const baseHits = index.byNormSlug.get(slugify(cleaned));
+    if (baseHits && baseHits.length === 1) return { kind: "resolved", id: baseHits[0] };
+    if (baseHits && baseHits.length > 1)
+      return { kind: "ambiguous", target: cleaned, candidates: baseHits };
+  }
+
+  return { kind: "missing", target: cleaned };
+}
+
 function resolveMarkdownTarget(
   target: string,
   sourceId: string,
@@ -200,19 +273,10 @@ function resolveMarkdownTarget(
   return { kind: "empty" };
 }
 
-function resolveWikilinkTarget(
-  target: string,
-): { kind: "concept"; id: string } | { kind: "empty" } {
-  // Wikilinks are already bundle-relative concept IDs
-  const cleaned = target.trim();
-  if (!cleaned) return { kind: "empty" };
-  return { kind: "concept", id: cleaned };
-}
-
 export function buildResolvedBacklinks(
   sourceId: string,
   body: string,
-  knownIds: Set<string>,
+  index: WikilinkIndex,
 ): ResolvedBacklinks {
   const diagnostics: KnowledgeDiagnostic[] = [];
   const unresolved: UnresolvedKnowledgeLink[] = [];
@@ -241,37 +305,38 @@ export function buildResolvedBacklinks(
         ),
       );
     } else if (resolved.kind === "concept") {
-      const normalizedId = resolved.id.normalize("NFC");
-      if (knownIds.has(normalizedId)) {
-        targets.add(normalizedId);
+      const canonical = index.byExact.get(resolved.id.normalize("NFC"));
+      if (canonical) {
+        targets.add(canonical);
       } else {
-        unresolved.push({ target: normalizedId, syntax: "markdown" });
+        unresolved.push({ target: resolved.id, syntax: "markdown" });
         diagnostics.push(
-          diag("warning", "link_unresolved", `${sourceId}.md`, `Unresolved link: ${normalizedId}`),
+          diag("warning", "link_unresolved", `${sourceId}.md`, `Unresolved link: ${resolved.id}`),
         );
       }
     }
     // external and empty are silently ignored
   }
 
-  // Process wikilinks
+  // Process wikilinks (lenient: exact → normalized path → bare title)
   for (const link of allLinks.wikilinks) {
-    const resolved = resolveWikilinkTarget(link.target);
-    if (resolved.kind === "concept") {
-      const normalizedId = resolved.id.normalize("NFC");
-      if (knownIds.has(normalizedId)) {
-        targets.add(normalizedId);
-      } else {
-        unresolved.push({ target: normalizedId, syntax: "wikilink" });
-        diagnostics.push(
-          diag(
-            "warning",
-            "link_unresolved",
-            `${sourceId}.md`,
-            `Unresolved wikilink: ${normalizedId}`,
-          ),
-        );
-      }
+    const res = resolveWikilink(link.target, index);
+    if (res.kind === "resolved") {
+      targets.add(res.id);
+    } else if (res.kind === "ambiguous") {
+      diagnostics.push(
+        diag(
+          "warning",
+          "link_ambiguous",
+          `${sourceId}.md`,
+          `Ambiguous wikilink: ${res.target} (candidates: ${res.candidates.join(", ")})`,
+        ),
+      );
+    } else {
+      unresolved.push({ target: res.target, syntax: "wikilink" });
+      diagnostics.push(
+        diag("warning", "link_unresolved", `${sourceId}.md`, `Unresolved wikilink: ${res.target}`),
+      );
     }
   }
 
@@ -280,3 +345,111 @@ export function buildResolvedBacklinks(
 
   return { targets: sorted, unresolved, diagnostics };
 }
+
+/**
+ * Pre-write wikilink gate mode (issue #172). Two independent behaviors, not a
+ * severity ladder:
+ *   1. resolvable-but-drifted links (target exists): leave vs. rewrite-to-canonical
+ *   2. unresolvable links (target absent — a forward reference / gap): ignore vs. report vs. reject
+ *
+ *   off       = leave + ignore   (opt-out; zero behavior change)
+ *   warn      = leave + report   (default; non-mutating, non-blocking, surfaces issues)
+ *   normalize = rewrite + report (fixes resolvable links; still reports gaps)
+ *   strict    = leave + reject   (blocks the write with the bad links named; agent retry signal)
+ *
+ * A link that RESOLVES is never flagged — only normalized. Only missing/ambiguous targets
+ * produce diagnostics.
+ */
+export type WikilinkValidationMode = "off" | "warn" | "strict" | "normalize";
+
+// ── Pre-write validation & normalization (issue #172, Layer 2) ─────────
+
+export interface WikilinkAuditResult {
+  /** Unresolved / ambiguous link diagnostics (empty for "off" / clean bodies). */
+  diagnostics: KnowledgeDiagnostic[];
+  /** The body after normalization (identical to input unless normalize rewrote links). */
+  body: string;
+  /** True only when normalize changed the body. */
+  changed: boolean;
+}
+
+const WIKILINK_REPLACE_RE = /\[\[([^\]|]+)(\|[^\]]*)?\]\]/g;
+
+/**
+ * Audit a markdown body's wikilinks against the page index.
+ *
+ * - Collects `link_unresolved` / `link_ambiguous` diagnostics for every link
+ *   that does not resolve to exactly one page (skipped for "off").
+ * - In "normalize" mode, additionally rewrites each link that DOES resolve to
+ *   its canonical page id. Only the target token is replaced (the parser's own
+ *   regex is reused), so `|alias`, escaping, and surrounding text are preserved.
+ *
+ * Pure: no I/O. The caller supplies the index (typically `buildWikilinkIndex`
+ * over existing page ids plus the ids created by the same commit).
+ */
+export function auditWikilinks(
+  body: string,
+  index: WikilinkIndex,
+  sourceId: string,
+  mode: WikilinkValidationMode,
+): WikilinkAuditResult {
+  if (mode === "off") return { diagnostics: [], body, changed: false };
+
+  const diagnostics: KnowledgeDiagnostic[] = [];
+  for (const { target } of extractKnowledgeLinks(body).wikilinks) {
+    const resolved = resolveWikilink(target, index);
+    if (resolved.kind === "ambiguous") {
+      diagnostics.push({
+        severity: "warning",
+        code: "link_ambiguous",
+        path: sourceId,
+        message: `Wikilink target "${target}" matches multiple pages (${resolved.candidates.join(", ")}).`,
+      });
+    } else if (resolved.kind === "missing") {
+      diagnostics.push({
+        severity: "warning",
+        code: "link_unresolved",
+        path: sourceId,
+        message: `Wikilink target "${target}" does not match any page.`,
+      });
+    }
+  }
+
+  let out = body;
+  if (mode === "normalize") {
+    out = body.replace(WIKILINK_REPLACE_RE, (full, raw: string, alias: string | undefined) => {
+      const resolved = resolveWikilink(normalizeWikilinkTarget(raw), index);
+      return resolved.kind === "resolved" ? `[[${resolved.id}${alias ?? ""}]]` : full;
+    });
+  }
+
+  return { diagnostics, body: out, changed: out !== body };
+}
+export interface WikilinkGateResult {
+  /** false only when mode === "strict" AND there are unresolvable/ambiguous links. */
+  ok: boolean;
+  /** The body to write (normalized when mode === "normalize", else the input). */
+  body: string;
+  /** Unresolved / ambiguous link diagnostics (empty for "off" / clean bodies). */
+  diagnostics: KnowledgeDiagnostic[];
+}
+
+/**
+ * Apply the pre-write wikilink gate to a body. Wraps {@link auditWikilinks}:
+ * blocks (ok:false) only in strict mode with issues, rewrites in normalize mode,
+ * and always returns the diagnostics so callers can surface them (warn/normalize).
+ */
+export function applyWikilinkGate(
+  body: string,
+  index: WikilinkIndex,
+  sourceId: string,
+  mode: WikilinkValidationMode,
+): WikilinkGateResult {
+  if (mode === "off") return { ok: true, body, diagnostics: [] };
+  const audit = auditWikilinks(body, index, sourceId, mode);
+  return {
+    ok: !(mode === "strict" && audit.diagnostics.length > 0),
+    body: mode === "normalize" ? audit.body : body,
+    diagnostics: audit.diagnostics,
+  };
+}

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

@@ -11,7 +11,11 @@ import {
 } from "node:fs";
 import { dirname, join } from "node:path";
 import type { KnowledgeDiagnostic, KnowledgeDocument } from "./knowledge-document.js";
-import { buildResolvedBacklinks } from "./knowledge-links.js";
+import {
+  type WikilinkIndex,
+  buildResolvedBacklinks,
+  buildWikilinkIndex,
+} from "./knowledge-links.js";
 import { type VaultPaths, isPathWithin, readJson } from "./utils.js";
 import {
   assertWritableVault,
@@ -86,8 +90,8 @@ export function rebuildMetadata(paths: VaultPaths): ProjectionResult {
   const registry = buildRegistry(paths, documents);
 
   // Step 4: Build backlinks from discovered documents
-  const knownIds = new Set(documents.map((d) => d.id));
-  const backlinks = buildBacklinks(documents, knownIds, allDiagnostics);
+  const wikilinkIndex = buildWikilinkIndex(documents.map((d) => d.id));
+  const backlinks = buildBacklinks(documents, wikilinkIndex, allDiagnostics);
 
   const eventSource = readEventSource(join(paths.meta, "events.jsonl"));
   const eventLogResult = eventSource.available ? buildOkfLog(eventSource.content) : undefined;
@@ -245,7 +249,7 @@ function getSemanticTitle(doc: KnowledgeDocument): string {
 /** Build backlinks from discovered documents using shared link resolution. */
 function buildBacklinks(
   documents: KnowledgeDocument[],
-  knownIds: Set<string>,
+  index: WikilinkIndex,
   diagnostics: KnowledgeDiagnostic[],
 ): Backlinks {
   const inbound: Backlinks = {};
@@ -257,7 +261,7 @@ function buildBacklinks(
 
   // Resolve links for each document
   for (const doc of documents) {
-    const result = buildResolvedBacklinks(doc.id, doc.body, knownIds);
+    const result = buildResolvedBacklinks(doc.id, doc.body, index);
     diagnostics.push(...result.diagnostics);
     for (const target of result.targets) {
       if (inbound[target] && !inbound[target].includes(doc.id)) {
@@ -508,7 +512,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;
   });
 }

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

@@ -1,11 +1,13 @@
-import { dirname, resolve } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import { Type } from "typebox";
 import { scheduleReindex } from "./indexing.js";
 import { createKnowledgeDocument, writeKnowledgeDocumentFile } from "./knowledge-document.js";
+import { applyWikilinkGate, buildWikilinkIndex } from "./knowledge-links.js";
 import { appendEvent, rebuildMetadataLight } from "./metadata.js";
 import type { Runtime } from "./runtime.js";
-import { type VaultPaths, fmtDate, resolveVaultPaths } from "./utils.js";
+import { loadTaskConfig, resolveWikilinkValidation } from "./task-config.js";
+import { type VaultPaths, fmtDate, readJson, resolveVaultPaths } from "./utils.js";
 import { assertWritableVault, inspectWritableVault } from "./vault-format.js";
 
 // ─── Public API ────────────────────────────────────────
@@ -150,9 +152,44 @@ export function registerWikiRetro(pi: ExtensionAPI, runtime?: Runtime): void {
         };
       }
 
+      // Pre-write wikilink gate (#172): validate/normalize caller-supplied body.
+      const mode = resolveWikilinkValidation(loadTaskConfig(ctx.cwd ?? process.cwd()));
+      let body = params.body;
+      let wikilinkIssues: string[] = [];
+      if (mode !== "off") {
+        const registry = readJson<{ pages: Record<string, unknown> }>(
+          join(paths.meta, "registry.json"),
+          { pages: {} },
+        );
+        const gate = applyWikilinkGate(
+          body,
+          buildWikilinkIndex(Object.keys(registry.pages)),
+          `sources/${params.slug}`,
+          mode,
+        );
+        wikilinkIssues = gate.diagnostics.map((d) => d.message);
+        if (!gate.ok) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Rejected write — unresolved/ambiguous wikilinks:\n${wikilinkIssues
+                  .map((m) => `- ${m}`)
+                  .join("\n")}`,
+              },
+            ],
+            details: { error: "link_validation", issues: wikilinkIssues } as Record<
+              string,
+              unknown
+            >,
+            isError: true,
+          };
+        }
+        if (mode === "normalize") body = gate.body;
+      }
       let result: RetroResult;
       try {
-        result = saveInsight(paths, params.slug, params.title, params.body, params.category, {
+        result = saveInsight(paths, params.slug, params.title, body, params.category, {
           rebuild: !runtime,
         });
       } catch (error: unknown) {
@@ -169,6 +206,9 @@ export function registerWikiRetro(pi: ExtensionAPI, runtime?: Runtime): void {
         scheduleReindex(runtime, { hasUI: ctx.hasUI, ui: ctx.ui }, paths);
       }
 
+      const gateNote = wikilinkIssues.length
+        ? `\n\n⚠️ ${wikilinkIssues.length} wikilink issue(s):\n${wikilinkIssues.map((m) => `- ${m}`).join("\n")}`
+        : "";
       return {
         content: [
           {
@@ -179,13 +219,17 @@ export function registerWikiRetro(pi: ExtensionAPI, runtime?: Runtime): void {
               `- Page: \`${result.sourcePagePath}\``,
               "",
               "This insight will be auto-surfaced by wiki_recall in future sessions.",
-            ].join("\n"),
+              gateNote,
+            ]
+              .filter(Boolean)
+              .join("\n"),
           },
         ],
         details: {
           slug: params.slug,
           title: params.title,
           category: params.category || null,
+          wikilinkIssues,
         } as Record<string, unknown>,
       };
     },

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

@@ -133,11 +133,11 @@ export class Runtime {
     }
 
     const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
-    if (!auth.ok || !auth.apiKey) {
+    if (!auth.ok) {
       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 };
+    return { ok: true, model, apiKey: auth.apiKey ?? "", headers: auth.headers };
   }
 
   /**