@blackbelt-technology/pi-agent-dashboard 0.4.6 → 0.5.0

package/packages/extension/src/__tests__/server-launcher.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from "vitest";
-import { resolveServerCliPath, buildSpawnArgs } from "../server-launcher.js";
+import { resolveServerCliPath, buildSpawnArgs, buildSpawnEnv } from "../server-launcher.js";
 import { existsSync } from "node:fs";
 import path from "node:path";
 
@@ -58,4 +58,27 @@ describe("server-launcher", () => {
       expect(args).toEqual(["--port", "3000", "--pi-port", "4000"]);
     });
   });
+
+  describe("buildSpawnEnv", () => {
+    it("always includes DASHBOARD_STARTER=Bridge", () => {
+      const env = buildSpawnEnv({});
+      expect(env["DASHBOARD_STARTER"]).toBe("Bridge");
+    });
+
+    it("overrides any existing DASHBOARD_STARTER in baseEnv", () => {
+      const env = buildSpawnEnv({ DASHBOARD_STARTER: "Standalone" });
+      expect(env["DASHBOARD_STARTER"]).toBe("Bridge");
+    });
+
+    it("preserves other env vars from baseEnv", () => {
+      const env = buildSpawnEnv({ MY_VAR: "hello" });
+      expect(env["MY_VAR"]).toBe("hello");
+      expect(env["DASHBOARD_STARTER"]).toBe("Bridge");
+    });
+
+    it("filters out undefined values from baseEnv", () => {
+      const env = buildSpawnEnv({ DEFINED: "yes", UNDEF: undefined });
+      expect(Object.keys(env)).not.toContain("UNDEF");
+    });
+  });
 });

package/packages/extension/src/bridge.ts

@@ -27,7 +27,7 @@ import { PromptBus } from "./prompt-bus.js";
 import { DashboardDefaultAdapter } from "./dashboard-default-adapter.js";
 import { registerAskUserTool } from "./ask-user-tool.js";
 import { decodeMultiselectAnswer } from "./multiselect-decode.js";
-import { activate as activateProviderRegister, onProviderChanged, reloadProviders } from "./provider-register.js";
+import { activate as activateProviderRegister, onProviderChanged, reloadProviders, buildProviderCatalogue } from "./provider-register.js";
 import type { FlowInfo } from "@blackbelt-technology/pi-dashboard-shared/types.js";
 import { startMetricsMonitor, stopMetricsMonitor, collectMetrics } from "./process-metrics.js";
 import { scanChildProcesses } from "./process-scanner.js";
@@ -37,6 +37,7 @@ import { sendStateSync as _sendStateSync, replaySessionEntries as _replaySession
 import { sendModelUpdateIfChanged as _sendModelUpdateIfChanged, sendSessionNameIfChanged as _sendSessionNameIfChanged, sendGitInfoIfChanged as _sendGitInfoIfChanged, sendJjStateIfChanged as _sendJjStateIfChanged, resetReconnectCaches as _resetReconnectCaches } from "./model-tracker.js";
 import { registerFlowEventListeners, FLOW_EVENT_MAP, SUBAGENT_EVENT_MAP } from "./flow-event-wiring.js";
 import { refreshUiModules, subscribeUiInvalidate, handleUiManagement, type UiModulesBridgeCtx } from "./ui-modules.js";
+import { inlineMessageText, type ReadFileOutcome } from "./markdown-image-inliner.js";
 
 const HEARTBEAT_INTERVAL = 15_000;
 const GIT_POLL_INTERVAL = 30_000;
@@ -209,6 +210,96 @@ function initBridge(pi: ExtensionAPI) {
   let appendMessageWrapped = false;
   let lastWrappedSm: any = null;
 
+  // ---------------------------------------------------------------------
+  // Markdown-image inliner state (chat-markdown-local-images-and-math).
+  // Per-sessionId set of asset hashes for which an `asset_register` has
+  // already been emitted on this WebSocket. Survives across message events
+  // within the same session; reset when the session id changes (in
+  // session_start). The Map keys are sessionId strings.
+  // ---------------------------------------------------------------------
+  const emittedAssetHashesBySession = new Map<string, Set<string>>();
+  function getEmittedAssetHashes(sid: string): Set<string> {
+    let s = emittedAssetHashesBySession.get(sid);
+    if (!s) {
+      s = new Set<string>();
+      emittedAssetHashesBySession.set(sid, s);
+    }
+    return s;
+  }
+
+  /**
+   * Synchronous fs probe + read for the inliner. Wraps `fs.statSync` /
+   * `fs.readFileSync` and maps Node errno strings to the
+   * `ReadFileOutcome.kind` enum used by the pure inliner. Order: stat
+   * first so directories report EISDIR even when the path has no file
+   * extension.
+   */
+  function inlinerReadFile(absolutePath: string): ReadFileOutcome {
+    try {
+      const st = fs.statSync(absolutePath);
+      if (st.isDirectory()) return { ok: false, kind: "EISDIR" };
+      if (!st.isFile()) return { ok: false, kind: "EOTHER" };
+      const bytes = fs.readFileSync(absolutePath);
+      return { ok: true, bytes };
+    } catch (err: any) {
+      const code = err?.code;
+      if (code === "ENOENT") return { ok: false, kind: "ENOENT" };
+      if (code === "EACCES") return { ok: false, kind: "EACCES" };
+      if (code === "EISDIR") return { ok: false, kind: "EISDIR" };
+      return { ok: false, kind: "EOTHER" };
+    }
+  }
+
+  /**
+   * Apply the markdown-image inliner to an assistant message_update /
+   * message_end event. Mutates `event.message.content` in place (string
+   * → rewritten string; array<{type:"text",text}> → rewritten text in
+   * each text block). Emits `asset_register` messages BEFORE returning so
+   * the caller's subsequent `connection.send(eventForward)` lands AFTER
+   * the assets it references. User-role and thinking events are no-ops.
+   */
+  function maybeInlineAssistantImages(event: any): void {
+    const msg = event?.message;
+    if (!msg || typeof msg !== "object") return;
+    if (msg.role !== "assistant") return;
+    // Use the *current* live cwd if available; fall back to the bridge
+    // process cwd. The inliner resolves relative `./pic.png` against this.
+    const cwd = (cachedCtx?.cwd as string | undefined) ?? process.cwd();
+    const alreadyEmitted = getEmittedAssetHashes(sessionId);
+    const allAssets: { hash: string; mimeType: string; data: string }[] = [];
+
+    const rewriteOne = (text: string): string => {
+      const r = inlineMessageText(text, {
+        readFile: inlinerReadFile,
+        cwd,
+        alreadyEmitted,
+      });
+      for (const a of r.assetsToEmit) allAssets.push(a);
+      return r.rewritten;
+    };
+
+    if (typeof msg.content === "string") {
+      msg.content = rewriteOne(msg.content);
+    } else if (Array.isArray(msg.content)) {
+      for (const block of msg.content) {
+        if (block && typeof block === "object" && block.type === "text" && typeof block.text === "string") {
+          block.text = rewriteOne(block.text);
+        }
+      }
+    }
+
+    // Send each new asset BEFORE the (rewritten) message event lands.
+    for (const a of allAssets) {
+      connection.send({
+        type: "asset_register",
+        sessionId,
+        hash: a.hash,
+        mimeType: a.mimeType,
+        data: a.data,
+      });
+    }
+  }
+
   /**
    * Wrap ctx.sessionManager.appendMessage once per session so that when pi
    * generates an entry id we capture it in the WeakMap and emit
@@ -330,6 +421,8 @@ function initBridge(pi: ExtensionAPI) {
               id: m.id,
             }));
             connection.send({ type: "models_list", sessionId, models });
+            // See change: replace-hardcoded-provider-lists.
+            connection.send({ type: "providers_list", sessionId, providers: buildProviderCatalogue() });
           } catch (err) { console.error("[dashboard] models_list push failed:", err); }
         }
         return;
@@ -765,6 +858,11 @@ function initBridge(pi: ExtensionAPI) {
         if (messageRef && typeof messageRef === "object" && !pendingNonces.has(messageRef as object)) {
           pendingNonces.set(messageRef as object, nonce);
         }
+        // Apply markdown image inliner to assistant content. Mutates
+        // event.message.content in place AND ships any new asset_register
+        // messages immediately so they precede the deferred message_end
+        // send below. See change: chat-markdown-local-images-and-math.
+        maybeInlineAssistantImages(event);
         setTimeout(() => {
           if (!isActive() || !sessionReady) return;
           const entryId =
@@ -778,6 +876,13 @@ function initBridge(pi: ExtensionAPI) {
         return;
       }
 
+      // Apply markdown image inliner to assistant message_update events.
+      // For other event types this is a no-op (role check inside the helper).
+      // See change: chat-markdown-local-images-and-math.
+      if (eventType === "message_update") {
+        maybeInlineAssistantImages(event);
+      }
+
       const msg = mapEventToProtocol(sessionId, event);
       connection.send(msg);
     }));
@@ -1155,6 +1260,8 @@ function initBridge(pi: ExtensionAPI) {
           id: m.id,
         }));
         connection.send({ type: "models_list", sessionId, models });
+        // See change: replace-hardcoded-provider-lists.
+        connection.send({ type: "providers_list", sessionId, providers: buildProviderCatalogue() });
       } catch { /* modelRegistry not available */ }
     }
 
@@ -1374,6 +1481,8 @@ function initBridge(pi: ExtensionAPI) {
           id: m.id,
         }));
         connection.send({ type: "models_list", sessionId, models });
+        // See change: replace-hardcoded-provider-lists.
+        connection.send({ type: "providers_list", sessionId, providers: buildProviderCatalogue() });
       } catch { /* ignore */ }
 
       // Retry pending default model — custom provider may now have its models

package/packages/extension/src/command-handler.ts

@@ -12,6 +12,7 @@ import { killProcessByPgid } from "./process-scanner.js";
 import type { FileEntry, PiSessionInfo } from "@blackbelt-technology/pi-dashboard-shared/types.js";
 import { filterHiddenCommands } from "./bridge-context.js";
 import { expandPromptTemplateFromDisk } from "./prompt-expander.js";
+import { buildProviderCatalogue } from "./provider-register.js";
 
 const IGNORE_DIRS = new Set([".git", "node_modules", ".next", "dist", "build", ".cache", "__pycache__", ".venv"]);
 const MAX_RESULTS = 20;
@@ -344,6 +345,11 @@ export function createCommandHandler(
           return { type: "models_list", sessionId, models: [] };
         }
 
+        case "request_providers": {
+          // See change: replace-hardcoded-provider-lists.
+          return { type: "providers_list", sessionId, providers: buildProviderCatalogue() };
+        }
+
         case "set_thinking_level":
           if (options?.setThinkingLevel) {
             options.setThinkingLevel(msg.level);

package/packages/extension/src/markdown-image-inliner.ts

@@ -0,0 +1,268 @@
+/**
+ * Markdown image inliner for the bridge.
+ *
+ * Scans assistant message text for fully-closed `![alt](src)` markdown image
+ * tokens, reads any local-path file references, hashes the bytes, and
+ * rewrites the token to `![alt](pi-asset:<hash>)`. Bytes ride out of band
+ * via `asset_register` events (one per unique hash per session). The text
+ * itself only ever carries the short `pi-asset:<hash>` token, keeping
+ * streaming `message_update` events bandwidth-bounded.
+ *
+ * The core helper `inlineMessageText` is **pure** — all I/O is delegated to
+ * the injected `readFile` callback so tests can drive every branch with
+ * memory fixtures. The bridge wires `readFile = node:fs.readFileSync` plus
+ * a per-session `alreadyEmitted: Set<string>` of hashes already shipped.
+ *
+ * See change: chat-markdown-local-images-and-math.
+ */
+import { createHash } from "node:crypto";
+import path from "node:path";
+
+/** Per-image hard cap (decision D8). */
+export const MAX_PER_IMAGE_BYTES = 5 * 1024 * 1024;
+/** Per-message cumulative cap on **newly-inlined** asset bytes (decision D8). */
+export const MAX_PER_MESSAGE_BYTES = 20 * 1024 * 1024;
+
+/** MIME allowlist keyed by lowercased extension. Decision D8. */
+const MIME_BY_EXT: Record<string, string> = {
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".webp": "image/webp",
+  ".svg": "image/svg+xml",
+  ".avif": "image/avif",
+  ".bmp": "image/bmp",
+};
+
+/** Matches a fully-closed `![alt](src)` markdown image token. */
+const IMAGE_TOKEN_RE = /!\[([^\]\n]*)\]\(([^)\n\s]+)\)/g;
+
+export interface ParsedImageToken {
+  /** The full original `![alt](src)` substring. */
+  token: string;
+  alt: string;
+  src: string;
+  /** Start offset within the input text. */
+  index: number;
+  length: number;
+}
+
+/**
+ * Find every fully-closed `![alt](src)` token in `text`. Partial tokens
+ * (e.g. `![alt](/path/x` without closing `)`) are NOT returned — the
+ * regex requires the closing paren. Tokens spanning newlines are NOT
+ * returned (markdown doesn't allow newlines inside the URL portion).
+ */
+export function parseImageTokens(text: string): ParsedImageToken[] {
+  const out: ParsedImageToken[] = [];
+  let match: RegExpExecArray | null;
+  IMAGE_TOKEN_RE.lastIndex = 0;
+  while ((match = IMAGE_TOKEN_RE.exec(text)) !== null) {
+    out.push({
+      token: match[0],
+      alt: match[1] ?? "",
+      src: match[2] ?? "",
+      index: match.index,
+      length: match[0].length,
+    });
+  }
+  return out;
+}
+
+/**
+ * Returns true iff `src` looks like a local filesystem path (i.e. NOT an
+ * already-resolved web URL, data URL, blob URL, fragment, or pre-rewritten
+ * `pi-asset:<hash>` token). Idempotency hinges on `pi-asset:` returning
+ * `false` here.
+ */
+export function isLocalSrc(src: string): boolean {
+  if (!src) return false;
+  if (src.startsWith("data:")) return false;
+  if (src.startsWith("blob:")) return false;
+  if (src.startsWith("http://")) return false;
+  if (src.startsWith("https://")) return false;
+  if (src.startsWith("pi-asset:")) return false;
+  if (src.startsWith("#")) return false;
+  // `file://` prefix — treat the rest as a local path.
+  return true;
+}
+
+/**
+ * Resolve `src` to an absolute path against `cwd`. `file://` prefix is
+ * stripped. Absolute paths pass through. Relative paths resolve against
+ * `cwd`.
+ */
+export function resolveLocalPath(src: string, cwd: string): string {
+  let raw = src;
+  if (raw.startsWith("file://")) raw = raw.slice("file://".length);
+  if (path.isAbsolute(raw)) return raw;
+  return path.resolve(cwd, raw);
+}
+
+/**
+ * Detect MIME from the file extension (case-insensitive). Returns null
+ * if the extension is not in the image allowlist.
+ */
+export function mimeFromExtension(filePath: string): string | null {
+  const ext = path.extname(filePath).toLowerCase();
+  return MIME_BY_EXT[ext] ?? null;
+}
+
+/**
+ * Hash file bytes to a 16-hex-char identifier (sha256 truncated). Decision D4.
+ */
+export function hashBytes(buf: Buffer): string {
+  return createHash("sha256").update(buf).digest("hex").slice(0, 16);
+}
+
+/** Format a byte count to a one-decimal MB string for placeholder text. */
+function formatMB(bytes: number): string {
+  return (bytes / (1024 * 1024)).toFixed(1);
+}
+
+/** Bridge-side per-file read result; thin enough to mock in tests. */
+export interface ReadFileResult {
+  ok: true;
+  bytes: Buffer;
+}
+export interface ReadFileError {
+  ok: false;
+  /** Use ENOENT/EACCES/EISDIR/EOTHER. EACCES is folded into ENOENT in placeholder text. */
+  kind: "ENOENT" | "EACCES" | "EISDIR" | "EOTHER";
+}
+export type ReadFileOutcome = ReadFileResult | ReadFileError;
+
+export interface InlineOptions {
+  /** Synchronous file-read callback. Bridge wires this to `node:fs.readFileSync` + `fs.statSync`. */
+  readFile: (absolutePath: string) => ReadFileOutcome;
+  /** Working directory used to resolve relative srcs. */
+  cwd: string;
+  /**
+   * Per-session set of hashes for which an `asset_register` has already been
+   * emitted. The inliner checks-then-adds so dedup is automatic across
+   * multiple message events within the same session.
+   */
+  alreadyEmitted: Set<string>;
+  /** Override the per-image cap. Default `MAX_PER_IMAGE_BYTES`. */
+  maxPerImageBytes?: number;
+  /** Override the per-message cap. Default `MAX_PER_MESSAGE_BYTES`. */
+  maxPerMessageBytes?: number;
+}
+
+export interface AssetToEmit {
+  hash: string;
+  mimeType: string;
+  /** Base64-encoded bytes ready for the `asset_register` message. */
+  data: string;
+}
+
+export interface InlineResult {
+  /** The rewritten text with every applicable token replaced. */
+  rewritten: string;
+  /** Newly-discovered assets to emit BEFORE the message_update / message_end. */
+  assetsToEmit: AssetToEmit[];
+}
+
+/**
+ * Pure inliner. Scans `text` for image tokens; rewrites local-path tokens
+ * either to `![alt](pi-asset:<hash>)` (success) or to a visible placeholder
+ * text (file too large / unsupported MIME / read error / message budget
+ * exhausted). Tokens with web/data/blob/pi-asset/# srcs pass through
+ * unchanged. Idempotent — re-running on already-rewritten text yields the
+ * same output (because `pi-asset:` returns `false` from `isLocalSrc`).
+ */
+export function inlineMessageText(text: string, opts: InlineOptions): InlineResult {
+  const tokens = parseImageTokens(text);
+  if (tokens.length === 0) {
+    return { rewritten: text, assetsToEmit: [] };
+  }
+
+  const maxPerImage = opts.maxPerImageBytes ?? MAX_PER_IMAGE_BYTES;
+  const maxPerMessage = opts.maxPerMessageBytes ?? MAX_PER_MESSAGE_BYTES;
+
+  const assetsToEmit: AssetToEmit[] = [];
+  let bytesInThisMessage = 0;
+
+  // Build the rewritten string by stitching segments separated by token
+  // replacements. Walk tokens left-to-right; tokens that pass through
+  // unchanged keep their original substring.
+  const out: string[] = [];
+  let cursor = 0;
+
+  for (const tok of tokens) {
+    // Append the segment before this token verbatim.
+    out.push(text.slice(cursor, tok.index));
+    cursor = tok.index + tok.length;
+
+    if (!isLocalSrc(tok.src)) {
+      // External / data: / pi-asset: / fragment — pass through unchanged.
+      out.push(tok.token);
+      continue;
+    }
+
+    const absPath = resolveLocalPath(tok.src, opts.cwd);
+
+    // Order matters here:
+    //   1. readFile FIRST so EISDIR / ENOENT / EACCES are reported with
+    //      their proper placeholders even when the path has no extension
+    //      (e.g. `/home/me` resolving to a directory).
+    //   2. mimeFromExtension after a successful read so an existing file
+    //      with a non-image extension reports "unsupported image type"
+    //      rather than a generic read failure.
+    //   3. hashBytes so we can consult `alreadyEmitted` BEFORE the
+    //      per-image and per-message caps. Already-registered assets bypass
+    //      caps because their bytes were paid for on the previous emission.
+    //   4. Per-image cap and per-message budget gate ONLY new emissions.
+    const outcome = opts.readFile(absPath);
+    if (!outcome.ok) {
+      // EACCES is folded into ENOENT placeholder to avoid leaking permission
+      // existence. EISDIR / EOTHER use the generic "read failed" wording.
+      if (outcome.kind === "ENOENT" || outcome.kind === "EACCES") {
+        out.push(`[image not found: ${tok.src}]`);
+      } else {
+        out.push(`[image read failed: ${tok.src}]`);
+      }
+      continue;
+    }
+
+    const mime = mimeFromExtension(absPath);
+    if (!mime) {
+      out.push(`[unsupported image type: ${tok.src}]`);
+      continue;
+    }
+
+    const hash = hashBytes(outcome.bytes);
+
+    if (opts.alreadyEmitted.has(hash)) {
+      // Bytes already shipped earlier in the session — only the token rewrites.
+      // Caps are bypassed: dedup means no new bytes go on the wire.
+      out.push(`![${tok.alt}](pi-asset:${hash})`);
+      continue;
+    }
+
+    const size = outcome.bytes.length;
+    if (size > maxPerImage) {
+      out.push(`[image too large: ${tok.src} (${formatMB(size)} MB)]`);
+      continue;
+    }
+
+    // New asset. Check the per-message budget before committing.
+    if (bytesInThisMessage + size > maxPerMessage) {
+      out.push(`[message asset budget exhausted: ${tok.src}]`);
+      continue;
+    }
+
+    bytesInThisMessage += size;
+    opts.alreadyEmitted.add(hash);
+    assetsToEmit.push({
+      hash,
+      mimeType: mime,
+      data: outcome.bytes.toString("base64"),
+    });
+    out.push(`![${tok.alt}](pi-asset:${hash})`);
+  }
+
+  out.push(text.slice(cursor));
+  return { rewritten: out.join(""), assetsToEmit };
+}

package/packages/extension/src/prompt-expander.ts

@@ -6,8 +6,9 @@
  * by reading template/skill files directly and expanding them.
  */
 import { readFileSync, existsSync } from "node:fs";
-import { join, resolve } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import { readdirSync, statSync } from "node:fs";
+import { buildSkillBlock } from "@blackbelt-technology/pi-dashboard-shared/skill-block-parser.js";
 
 /** Scan directories for .md prompt template files */
 function findPromptTemplates(cwd: string): Map<string, string> {
@@ -97,7 +98,26 @@ export function expandPromptTemplateFromDisk(text: string, cwd: string, pi?: any
 
   try {
     const content = readTemplate(filePath);
-    // Simple arg substitution: replace $1, $2, etc. or just append args
+
+    // Skill detection: either the local-scan key starts with `skill:` or the
+    // pi.getCommands() fallback resolved a command whose `source === "skill"`
+    // (we re-check below). Skill expansions wrap in pi's `<skill>` envelope so
+    // the dashboard ingress path is byte-identical to pi's own _expandSkillCommand,
+    // which lets the client and server recover the slash-command form.
+    // See change: render-skill-invocations-collapsibly.
+    const isSkill = isSkillResolution(templateName, filePath, pi);
+    if (isSkill) {
+      const bareName = templateName.replace(/^skill:/, "");
+      return buildSkillBlock({
+        name: bareName,
+        filePath,
+        baseDir: dirname(filePath),
+        body: content,
+        userArgs: argsString || undefined,
+      });
+    }
+
+    // Plain prompt templates: append args after a blank line, no wrapper.
     if (argsString) {
       return `${content}\n\n${argsString}`;
     }
@@ -106,3 +126,31 @@ export function expandPromptTemplateFromDisk(text: string, cwd: string, pi?: any
     return text;
   }
 }
+
+/**
+ * Detect whether the resolved `filePath` came from a skill source.
+ *
+ * The local-scan key tells us directly when it starts with `skill:`. For the
+ * pi.getCommands() fallback we re-query and check `source === "skill"` against
+ * the same templateName.
+ */
+function isSkillResolution(
+  templateName: string,
+  filePath: string,
+  pi: any | undefined,
+): boolean {
+  if (templateName.startsWith("skill:")) return true;
+  // The colon-alias path (e.g. /opsx:continue) maps to a hyphen filename and is
+  // a prompt template, not a skill. Skills always use the `skill:` prefix in
+  // both the local scan and pi.getCommands().
+  if (!pi?.getCommands) return false;
+  try {
+    const commands = pi.getCommands();
+    const match = commands.find(
+      (c: any) => c.name === templateName && c.source === "skill" && c.path === filePath,
+    );
+    return !!match;
+  } catch {
+    return false;
+  }
+}

package/packages/extension/src/provider-register.ts

@@ -15,6 +15,7 @@ import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
+import type { ProviderInfo } from "@blackbelt-technology/pi-dashboard-shared/types.js";
 
 // -- Types ----------------------------------------------------------------
 
@@ -288,6 +289,122 @@ export function getSessionInfo(): { provider: string; modelId: string } {
   return { provider: currentSessionProvider, modelId: currentSessionModelId };
 }
 
+// -- Provider catalogue (for dashboard /api/provider-auth/status) -------
+//
+// Pure derivation: given a captured `ModelRegistry` and the pi-ai
+// helpers (`findEnvKeys`, `getEnvApiKey`), build a flat ProviderInfo[]
+// covering every OAuth provider plus every distinct provider id from
+// `getAll()`. The bridge pushes this to the server alongside
+// `models_list`. See change: replace-hardcoded-provider-lists.
+
+type PiAiHelpers = {
+  findEnvKeys?: (id: string) => string[] | undefined;
+  getEnvApiKey?: (id: string) => string | undefined;
+};
+
+export function _buildProviderCatalogue(
+  modelRegistry: any,
+  piAi: PiAiHelpers,
+  customIds: ReadonlySet<string> = new Set(),
+): ProviderInfo[] {
+  if (!modelRegistry) return [];
+  const oauthIds = new Set<string>(
+    (modelRegistry.authStorage?.getOAuthProviders?.() ?? []).map((p: any) => p.id),
+  );
+  // The catalogue is the complete picture of what pi knows about —
+  // built-in providers, OAuth providers, AND custom providers registered
+  // by the dashboard via pi.registerProvider() from ~/.pi/agent/providers.json.
+  // Custom providers carry `custom: true` so consumers can decide what
+  // to surface where (e.g. the auth UI suppresses their API-key rows
+  // because they're managed by the LLM Providers settings section).
+  // Filtering decisions belong to consumers, not to this function.
+  // See change: replace-hardcoded-provider-lists.
+  const allIds = new Set<string>(oauthIds);
+  for (const m of (modelRegistry.getAll?.() ?? []) as Array<{ provider?: string }>) {
+    if (m.provider) allIds.add(m.provider);
+  }
+  return [...allIds].map((id) => {
+    let displayName = id;
+    try {
+      displayName = modelRegistry.getProviderDisplayName?.(id) ?? id;
+    } catch { /* fallback to id */ }
+    let configured = false;
+    let source: ProviderInfo["source"];
+    try {
+      const status = modelRegistry.authStorage?.getAuthStatus?.(id);
+      if (status) {
+        configured = !!status.configured;
+        source = status.source;
+      }
+    } catch { /* ignore */ }
+    let expires: number | undefined;
+    try {
+      const cred = modelRegistry.authStorage?.get?.(id);
+      if (cred?.type === "oauth" && typeof cred.expires === "number") {
+        expires = cred.expires;
+      }
+    } catch { /* ignore */ }
+    let envVar: string | undefined;
+    let ambient: boolean | undefined;
+    try {
+      const keys = piAi.findEnvKeys?.(id);
+      if (keys && keys.length > 0) envVar = keys[0];
+      if (piAi.getEnvApiKey?.(id) === "<authenticated>") ambient = true;
+    } catch { /* ignore */ }
+    return {
+      id,
+      displayName,
+      hasOAuth: oauthIds.has(id),
+      configured,
+      source,
+      envVar,
+      ambient,
+      expires,
+      custom: customIds.has(id) || undefined,
+    };
+  });
+}
+
+// Lazy-cached pi-ai module (in scope inside pi's process).
+let _piAiModule: PiAiHelpers | null = null;
+let _piAiLoadAttempted = false;
+async function loadPiAi(): Promise<PiAiHelpers> {
+  if (_piAiModule) return _piAiModule;
+  if (_piAiLoadAttempted) return {};
+  _piAiLoadAttempted = true;
+  try {
+    const mod: any = await import("@mariozechner/pi-ai");
+    _piAiModule = { findEnvKeys: mod.findEnvKeys, getEnvApiKey: mod.getEnvApiKey };
+    return _piAiModule;
+  } catch {
+    return {};
+  }
+}
+
+// Eagerly kick off pi-ai load at module import time so env-var hints
+// are populated by the time the first session_register fires. Failure
+// is silent; `buildProviderCatalogue` falls back to {} which still
+// produces a valid catalogue minus envVar/ambient hints.
+void loadPiAi();
+
+/**
+ * Public wrapper: returns the current provider catalogue, or [] when
+ * the model registry has not been captured yet. Marks providers the
+ * bridge itself registered (from `~/.pi/agent/providers.json` via
+ * `pi.registerProvider()`) with `custom: true` so consumers can
+ * suppress their API-key auth rows (those are managed by the LLM
+ * Providers settings section). The catalogue itself is complete —
+ * including custom providers — so other consumers (e.g. diagnostics)
+ * see the full picture.
+ */
+export function buildProviderCatalogue(): ProviderInfo[] {
+  const mr = getModelRegistry();
+  if (!mr) return [];
+  const piAi = _piAiModule ?? {};
+  const customIds = new Set<string>(lastRegistered.keys());
+  return _buildProviderCatalogue(mr, piAi, customIds);
+}
+
 export function getModelDisplayName(modelId: string): string {
   if (piRef) {
     const data: any = {};