@zosmaai/pi-llm-wiki 0.11.5 → 0.11.7

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

@@ -13,9 +13,15 @@ import {
   serializeKnowledgeDocument,
   writeKnowledgeDocumentFile,
 } from "./knowledge-document.js";
+import {
+  type WikilinkValidationMode,
+  auditWikilinks,
+  buildWikilinkIndex,
+} from "./knowledge-links.js";
 import { appendEvent, rebuildMetadataLight } from "./metadata.js";
 import { runSubAgent } from "./subagent.js";
-import { type VaultPaths, fmtDate, slugify } from "./utils.js";
+import { resolveWikilinkValidation } from "./task-config.js";
+import { type VaultPaths, fmtDate, readJson, slugify } from "./utils.js";
 import { VaultWriteError, assertWritableVault } from "./vault-format.js";
 
 /**
@@ -84,6 +90,8 @@ export interface CommitResult {
   entitiesLinked: string[];
   conceptsLinked: string[];
   contradictions: number;
+  /** Wikilink gate diagnostics from `commitSynthesis` (warn/normalize modes). */
+  wikilinkDiagnostics?: KnowledgeDiagnostic[];
 }
 
 export type CommitSynthesisOutcome =
@@ -186,43 +194,23 @@ function getHeadings(lang?: string): Record<string, string> {
   };
 }
 
-function buildEntityPageBody(
-  title: string,
-  description: string,
-  sourceId: string,
-  lang?: string,
-): string {
+function buildEntityPageBody(title: string, description: string, sourceId: string): string {
   const desc = description.trim() || "One-line description.";
-  const h = getHeadings(lang);
   return `# ${title}
 
 ${desc}
 
-## ${h.overview}
-
-[Key facts]
-
 ## Links
 
 - [${sourceId}](/sources/${sourceId}.md)`;
 }
 
-function buildConceptPageBody(
-  title: string,
-  definition: string,
-  sourceId: string,
-  lang?: string,
-): string {
+function buildConceptPageBody(title: string, definition: string, sourceId: string): string {
   const def = definition.trim() || "One-line definition.";
-  const h = getHeadings(lang);
   return `# ${title}
 
 ${def}
 
-## ${h.definition}
-
-[Clear explanation]
-
 ## Links
 
 - [${sourceId}](/sources/${sourceId}.md)`;
@@ -321,6 +309,28 @@ export function buildIngestedSourcePage(
   return serializeKnowledgeDocument(doc);
 }
 
+/**
+ * Build the wikilink index used by the pre-write gate: every existing page id
+ * (from the registry) plus the page ids this commit is about to create, so a
+ * link to a sibling created in the same ingest resolves instead of
+ * false-positiving as missing.
+ */
+function buildIngestAuditIndex(
+  paths: VaultPaths,
+  sourceId: string,
+  data: SynthesisData,
+): ReturnType<typeof buildWikilinkIndex> {
+  const registry = readJson<{ pages: Record<string, unknown> }>(join(paths.meta, "registry.json"), {
+    pages: {},
+  });
+  const newIds = [
+    `sources/${sourceId}`,
+    ...data.entities.filter((e) => slugify(e.title)).map((e) => `entities/${slugify(e.title)}`),
+    ...data.concepts.filter((c) => slugify(c.title)).map((c) => `concepts/${slugify(c.title)}`),
+  ];
+  return buildWikilinkIndex([...Object.keys(registry.pages), ...newIds]);
+}
+
 /**
  * Persist a synthesis deterministically: rewrite the source page (status →
  * ingested), create missing entity/concept pages (existing pages are linked,
@@ -333,6 +343,7 @@ export function commitSynthesis(
   data: SynthesisData,
   date: string = fmtDate(),
   lang?: string,
+  wikilinkValidation?: WikilinkValidationMode,
 ): CommitSynthesisOutcome {
   const result: CommitResult = {
     sourceId,
@@ -353,6 +364,24 @@ export function commitSynthesis(
     throw error;
   }
 
+  // Pre-write wikilink gate (issue #172, Layer 2). Applies only to the
+  // model-authored source body; entity/concept pages are generated templates.
+  const mode = resolveWikilinkValidation({ wikilinkValidation });
+  let sourceBody = buildIngestedSourcePageBody(manifest, data, date, lang);
+  if (mode !== "off") {
+    const audit = auditWikilinks(
+      sourceBody,
+      buildIngestAuditIndex(paths, sourceId, data),
+      sourceId,
+      mode,
+    );
+    if (mode === "strict" && audit.diagnostics.length > 0) {
+      return { ok: false, sourceId, diagnostics: audit.diagnostics };
+    }
+    if (mode === "normalize") sourceBody = audit.body;
+    if (audit.diagnostics.length > 0) result.wikilinkDiagnostics = audit.diagnostics;
+  }
+
   // Patch existing documents so unknown fields, legacy sources, and titles survive.
   let sourceDocument: KnowledgeDocument;
   if (existsSync(result.sourcePage)) {
@@ -360,7 +389,7 @@ export function commitSynthesis(
     if (!parsed.ok) return { ok: false, sourceId, diagnostics: parsed.diagnostics };
     sourceDocument = patchKnowledgeDocument(parsed.document, {
       fields: { status: "ingested", updated: date },
-      body: buildIngestedSourcePageBody(manifest, data, date, lang),
+      body: sourceBody,
     });
   } else {
     sourceDocument = createKnowledgeDocument(
@@ -375,7 +404,7 @@ export function commitSynthesis(
         status: "ingested",
         updated: date,
       },
-      buildIngestedSourcePageBody(manifest, data, date, lang),
+      sourceBody,
     );
   }
   mkdirSync(join(paths.wiki, "sources"), { recursive: true });
@@ -399,7 +428,7 @@ export function commitSynthesis(
           created: date,
           updated: date,
         },
-        buildEntityPageBody(e.title, e.description, sourceId, lang),
+        buildEntityPageBody(e.title, e.description, sourceId),
         [{ id: sourceId, resource: `/sources/${sourceId}.md` }],
       );
       writeKnowledgeDocumentFile(pagePath, entityDoc);
@@ -425,7 +454,7 @@ export function commitSynthesis(
           created: date,
           updated: date,
         },
-        buildConceptPageBody(c.title, c.definition, sourceId, lang),
+        buildConceptPageBody(c.title, c.definition, sourceId),
         [{ id: sourceId, resource: `/sources/${sourceId}.md` }],
       );
       writeKnowledgeDocumentFile(pagePath, conceptDoc);
@@ -477,6 +506,8 @@ export interface RunIngestSynthesisArgs {
   synthesisLanguage?: string;
   /** Max output tokens for synthesizer sub-agent (issue #160). Default 16384. */
   synthesisMaxTokens?: number;
+  /** Wikilink write-gate mode for the ingested source body (issue #172). */
+  wikilinkValidation?: WikilinkValidationMode;
 }
 
 /**
@@ -499,6 +530,7 @@ export async function runIngestSynthesis(
     signal,
     synthesisLanguage,
     synthesisMaxTokens,
+    wikilinkValidation,
   } = args;
   const content = extracted.slice(0, maxChars ?? 24_000);
   if (!content.trim()) return undefined;
@@ -524,6 +556,7 @@ export async function runIngestSynthesis(
         params,
         undefined,
         synthesisLanguage,
+        wikilinkValidation,
       );
       if (!outcome.ok) {
         return {

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

@@ -21,6 +21,7 @@ export type DiagnosticCode =
   | "okf_version_mismatch"
   | "link_path_escape"
   | "link_unresolved"
+  | "link_ambiguous"
   | "event_source_missing"
   | "event_source_unreadable"
   | "event_invalid_json"

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 {
@@ -120,6 +121,74 @@ export function extractLegacyWikilinks(body: string): ExtractedLink[] {
   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,
@@ -204,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[] = [];
@@ -245,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}`),
+      );
     }
   }
 
@@ -284,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)) {

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 };
   }
 
   /**