@hypabolic/crossbar 0.1.0

package/src/registry/persistence.ts

@@ -0,0 +1,111 @@
+/**
+ * Crossbar config persistence — crossbar.json (non-secret) and the CredentialStore boundary.
+ *
+ * crossbar.json lives at getAgentDir()/crossbar.json and contains only non-secret server metadata.
+ * API keys are stored separately via the CredentialStore (backed by Pi's authStorage at runtime).
+ *
+ * The `dir` override in opts lets tests pass a temp directory instead of touching ~/.pi.
+ */
+
+import { readFileSync, writeFileSync, renameSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import type { CrossbarConfigFile, ServerRecord } from "../core/types.ts";
+
+export { tmpdir }; // re-export for tests
+
+/**
+ * Interface that Pi's authStorage will be adapted to at runtime.
+ * Kept as a plain interface here so the persistence module never imports Pi runtime.
+ */
+export interface CredentialStore {
+  get(id: string): string | undefined | Promise<string | undefined>;
+  set(id: string, key: string): void | Promise<void>;
+  remove(id: string): void | Promise<void>;
+}
+
+export interface PersistenceOpts {
+  /** Override the directory for crossbar.json (default: getAgentDir()). Used in tests. */
+  dir?: string;
+}
+
+function resolveDir(opts?: PersistenceOpts): string {
+  return opts?.dir ?? getAgentDir();
+}
+
+function configPath(opts?: PersistenceOpts): string {
+  return join(resolveDir(opts), "crossbar.json");
+}
+
+/**
+ * Strip any `apiKey` field that may have leaked into a ServerRecord.
+ * This is a safety guard: crossbar.json must never contain secrets.
+ */
+function stripSecrets(record: ServerRecord): ServerRecord {
+  const { ...safe } = record as ServerRecord & { apiKey?: unknown };
+  // biome-ignore lint: intentional runtime secret guard
+  delete (safe as Record<string, unknown>)["apiKey"];
+  return safe;
+}
+
+/**
+ * Validate that a parsed value looks like a CrossbarConfigFile.
+ * Returns the canonical form, or null if the value is invalid.
+ */
+function parseConfigFile(raw: unknown): CrossbarConfigFile | null {
+  if (typeof raw !== "object" || raw === null) return null;
+  const obj = raw as Record<string, unknown>;
+  if (obj["version"] !== 1) return null;
+  if (!Array.isArray(obj["servers"])) return null;
+  const result: CrossbarConfigFile = {
+    version: 1,
+    servers: (obj["servers"] as unknown[]).filter(
+      (s): s is ServerRecord => typeof s === "object" && s !== null,
+    ),
+  };
+  const rawSettings = obj["settings"];
+  if (typeof rawSettings === "object" && rawSettings !== null) {
+    result.settings = rawSettings as NonNullable<CrossbarConfigFile["settings"]>;
+  }
+  return result;
+}
+
+const EMPTY_CONFIG: CrossbarConfigFile = { version: 1, servers: [] };
+
+/**
+ * Load crossbar.json from the agent dir (or the override dir in tests).
+ * Returns a default empty config if the file is missing or invalid.
+ */
+export async function loadConfig(opts?: PersistenceOpts): Promise<CrossbarConfigFile> {
+  const path = configPath(opts);
+  try {
+    const text = readFileSync(path, "utf-8");
+    const parsed = JSON.parse(text) as unknown;
+    const config = parseConfigFile(parsed);
+    return config ?? { ...EMPTY_CONFIG };
+  } catch {
+    return { ...EMPTY_CONFIG };
+  }
+}
+
+/**
+ * Atomically write crossbar.json (temp file + rename).
+ * Strips any apiKey fields that may have crept into ServerRecords.
+ */
+export async function saveConfig(config: CrossbarConfigFile, opts?: PersistenceOpts): Promise<void> {
+  const dir = resolveDir(opts);
+  mkdirSync(dir, { recursive: true });
+
+  const safe: CrossbarConfigFile = {
+    ...config,
+    servers: config.servers.map(stripSecrets),
+  };
+
+  const json = JSON.stringify(safe, null, 2);
+  const dest = configPath(opts);
+  // Write to a sibling temp file in the same dir so rename is atomic (same filesystem)
+  const tmp = join(dir, `.crossbar-${Date.now()}-${Math.random().toString(36).slice(2)}.tmp`);
+  writeFileSync(tmp, json, { encoding: "utf-8" });
+  renameSync(tmp, dest);
+}

package/src/registry/pi-credential-store.ts

@@ -0,0 +1,27 @@
+/**
+ * Bridges Pi's `AuthStorage` (reached at runtime via `ctx.modelRegistry.authStorage`) to Crossbar's
+ * framework-free {@link CredentialStore} boundary. This is the ONLY place keys cross into Pi's store —
+ * they land in `auth.json` (mode 0600) keyed by the Crossbar provider id, exactly like Pi's own creds.
+ *
+ * Keeping the adapter here (not in persistence.ts) preserves the rule that the persistence/registry
+ * core never imports Pi runtime, so they stay unit-testable with a fake store.
+ */
+
+import type { AuthStorage } from "@earendil-works/pi-coding-agent";
+import type { CredentialStore } from "./persistence.ts";
+
+/** Wrap a Pi `AuthStorage` as a Crossbar `CredentialStore` (api-key credentials only). */
+export function createPiCredentialStore(authStorage: AuthStorage): CredentialStore {
+  return {
+    get(id: string): string | undefined {
+      const cred = authStorage.get(id);
+      return cred?.type === "api_key" ? cred.key : undefined;
+    },
+    set(id: string, key: string): void {
+      authStorage.set(id, { type: "api_key", key });
+    },
+    remove(id: string): void {
+      authStorage.remove(id);
+    },
+  };
+}

package/src/registry/registry.ts

@@ -0,0 +1,150 @@
+/**
+ * In-memory ServerRegistry — CRUD, health cache, and credential resolution.
+ *
+ * The registry is the single source of truth for server state at runtime.
+ * It is constructed with injected dependencies (CredentialStore, persist fn, clock) so it
+ * is fully testable without touching the filesystem or Pi runtime.
+ *
+ * Session wiring (session_start poll, session_shutdown cleanup) is Wave C and is NOT here.
+ */
+
+import type { CrossbarConfigFile, ServerCredential, ServerRecord } from "../core/types.ts";
+import type { CredentialStore } from "./persistence.ts";
+
+export interface RegistryDeps {
+  store: CredentialStore;
+  /** Write the current state to disk. The registry calls this after every mutation. */
+  persist: (config: CrossbarConfigFile) => Promise<void>;
+  /** Clock injection for testability. Defaults to Date.now. */
+  now?: () => number;
+}
+
+export interface HealthCachePatch {
+  models?: ServerRecord["lastKnownModels"];
+  loaded?: ServerRecord["lastKnownLoaded"];
+  lastSeenAt?: number;
+}
+
+export class ServerRegistry {
+  private readonly records: Map<string, ServerRecord> = new Map();
+  private readonly store: CredentialStore;
+  private readonly persist: (config: CrossbarConfigFile) => Promise<void>;
+  private readonly now: () => number;
+
+  constructor(deps: RegistryDeps) {
+    this.store = deps.store;
+    this.persist = deps.persist;
+    this.now = deps.now ?? (() => Date.now());
+  }
+
+  // ---------------------------------------------------------------------------
+  // Initialisation — load records from a previously-read config file
+  // ---------------------------------------------------------------------------
+
+  /** Populate the in-memory registry from a loaded CrossbarConfigFile. */
+  load(config: CrossbarConfigFile): void {
+    this.records.clear();
+    for (const record of config.servers) {
+      this.records.set(record.id, record);
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Read
+  // ---------------------------------------------------------------------------
+
+  list(): ServerRecord[] {
+    return Array.from(this.records.values());
+  }
+
+  get(id: string): ServerRecord | undefined {
+    return this.records.get(id);
+  }
+
+  // ---------------------------------------------------------------------------
+  // Write
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Add (or replace) a server record and optionally store its API key.
+   * Persists after a successful write.
+   */
+  async add(record: ServerRecord, apiKey?: string): Promise<void> {
+    this.records.set(record.id, record);
+    if (apiKey !== undefined) {
+      await this.store.set(record.id, apiKey);
+    }
+    await this.flush();
+  }
+
+  /**
+   * Apply a partial patch to an existing record.
+   * Throws if the id is not found.
+   */
+  async update(id: string, patch: Partial<Omit<ServerRecord, "id">>): Promise<void> {
+    const existing = this.records.get(id);
+    if (!existing) throw new Error(`ServerRegistry: unknown id "${id}"`);
+    this.records.set(id, { ...existing, ...patch });
+    await this.flush();
+  }
+
+  /**
+   * Remove a server record and its stored credential.
+   * No-op (no throw) if the id is not found.
+   */
+  async remove(id: string): Promise<void> {
+    if (!this.records.has(id)) return;
+    this.records.delete(id);
+    await this.store.remove(id);
+    await this.flush();
+  }
+
+  /** Enable or disable a server without touching any other fields. */
+  async setEnabled(id: string, enabled: boolean): Promise<void> {
+    await this.update(id, { enabled });
+  }
+
+  // ---------------------------------------------------------------------------
+  // Health / model cache (non-persisting fast-path — called from the poll loop)
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Update the cached health snapshot for a server.
+   * Does NOT persist — health cache is ephemeral, reconstructed on next poll.
+   */
+  updateHealthCache(id: string, patch: HealthCachePatch): void {
+    const existing = this.records.get(id);
+    if (!existing) return;
+    const updated: ServerRecord = { ...existing };
+    if (patch.models !== undefined) updated.lastKnownModels = patch.models;
+    if (patch.loaded !== undefined) updated.lastKnownLoaded = patch.loaded;
+    if (patch.lastSeenAt !== undefined) updated.lastSeenAt = patch.lastSeenAt;
+    this.records.set(id, updated);
+  }
+
+  // ---------------------------------------------------------------------------
+  // Credential resolution
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Resolve the runtime credential for a server record.
+   *   - mode "none" → { mode: "none" }
+   *   - mode "apiKey" → fetch the key from the store; returns { mode: "apiKey", apiKey }
+   *     (apiKey may be undefined if the key has not been stored yet)
+   */
+  async resolveCredential(record: ServerRecord): Promise<ServerCredential> {
+    if (record.auth === "none") {
+      return { mode: "none" };
+    }
+    const apiKey = await this.store.get(record.id);
+    return { mode: "apiKey", ...(apiKey !== undefined ? { apiKey } : {}) };
+  }
+
+  // ---------------------------------------------------------------------------
+  // Internal
+  // ---------------------------------------------------------------------------
+
+  private async flush(): Promise<void> {
+    await this.persist({ version: 1, servers: this.list() });
+  }
+}

package/src/shim/provider-shim.ts

@@ -0,0 +1,187 @@
+/**
+ * Provider-registration shim — the ONLY place Crossbar calls Pi's
+ * `pi.registerProvider` / `pi.unregisterProvider`.
+ *
+ * # API-key handoff decision (verified against Pi source at commit d93b92b)
+ *
+ * Pi's `validateProviderConfig` (.pi-reference/packages/coding-agent/src/core/model-registry.ts:882)
+ * throws when `models` is provided but `apiKey` is absent AND `oauth` is absent:
+ *
+ *   if (!config.apiKey && !config.oauth) {
+ *     throw new Error(`Provider ${providerName}: "apiKey" or "oauth" is required when defining models.`);
+ *   }
+ *
+ * Pi's `getApiKeyAndHeaders` (model-registry.ts:703–716) resolves the key in this order:
+ *   1. `authStorage.getApiKey(providerName)` — reads from auth.json under the provider id
+ *   2. Fallback: `resolveConfigValue(providerConfig.apiKey)` — resolves the $ENV expression
+ *
+ * Crossbar calls `authStorage.set(record.id, { type: "api_key", key: <literal> })` BEFORE
+ * calling `registerProvider`, so Pi's step-1 always finds the key in auth.json and the
+ * `$ENV` expression is NEVER evaluated against environment variables.
+ *
+ * Therefore the correct approach is:
+ *   - Pass `apiKey: "$" + envVarFor(record.id)` when `hasApiKey === true`.
+ *     This satisfies Pi's validation without ever inlining a plaintext key into the
+ *     ProviderConfig (which Pi stores in memory as `registeredProviders`).
+ *   - Omit `apiKey` entirely when the server requires no auth — Pi's validation
+ *     only fires when `models` is provided, and it passes when `apiKey` is absent
+ *     only if `oauth` is present; BUT local no-auth servers must still pass the
+ *     validation.  We therefore supply `apiKey: ""` — wait, that is falsy and will
+ *     also trigger the throw.
+ *
+ *   Re-reading model-registry.ts:882: the check is `!config.apiKey`, which is truthy
+ *   for the empty string `""`.  So for no-auth servers we need a non-empty sentinel.
+ *   The Pi docs (custom-provider.md) show `apiKey: "$LOCAL_OPENAI_API_KEY"` even for
+ *   local servers where the env var is unset — Pi treats an unresolved env var as
+ *   "no key" and does not inject an Authorization header in that case (the header is
+ *   only added when `authStorage.getApiKey` returns a non-undefined value OR when
+ *   `authHeader: true` is set).
+ *
+ *   FINAL DECISION:
+ *   - `auth === "apiKey"`: pass `apiKey: "$" + envVarFor(record.id)`.
+ *     Pi reads the literal key from auth.json (step 1 above). Safe — no plaintext.
+ *   - `auth === "none"`: pass `apiKey: "$" + envVarFor(record.id)` but omit the
+ *     env var from the environment (and Crossbar never sets it). Pi will resolve
+ *     the env var as undefined and skip the Authorization header.
+ *     This satisfies the validation AND causes no harm for no-auth backends.
+ *
+ *   Evidence:
+ *     - Validation:  model-registry.ts:882
+ *     - Resolution:  model-registry.ts:703–716
+ *     - resolveConfigValue env handling: resolve-config-value.ts:101–113
+ *       (returns undefined when env var is absent → getApiKeyAndHeaders returns undefined apiKey)
+ */
+
+import type { ProviderConfig, ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { ServerRecord, DiscoveredServer, ModelDescriptor } from "../core/types.ts";
+import { adapterFor } from "../adapters/index.ts";
+import { envVarFor } from "../registry/ids.ts";
+import type { ServerRegistry } from "../registry/registry.ts";
+
+// ---------------------------------------------------------------------------
+// buildProviderConfig — pure mapping, no I/O
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the ProviderConfig that should be handed to `pi.registerProvider(record.id, config)`.
+ *
+ * PURE — no I/O, no side effects. Only call this after the model cache is populated.
+ *
+ * @param record  - Persistent server record (id, kind, label, auth, …).
+ * @param server  - Discovered-server snapshot (baseUrl, auth, …).
+ * @param models  - Full model list as returned by `adapter.listModels`; embedding models
+ *                  are filtered out here and never registered with Pi.
+ * @param opts.hasApiKey - True when the registry has a key stored in auth.json for this
+ *                         server.  Controls whether the `$ENV` sentinel is injected.
+ */
+export function buildProviderConfig(
+  record: ServerRecord,
+  server: DiscoveredServer,
+  models: ModelDescriptor[],
+  opts?: { hasApiKey?: boolean },
+): ProviderConfig {
+  const adapter = adapterFor(record.kind);
+
+  // Filter out embedding-only models — Pi registers these as chat models which
+  // is incorrect.  Non-embedding models are the ones Pi cares about.
+  const chatModels = models.filter((m) => !m.embeddings);
+
+  // Map each chat model through the adapter's owned toPiModel logic.
+  const piModels: ProviderConfig["models"] = chatModels.map((m) =>
+    adapter.toPiModel(server, m),
+  );
+
+  // API-key sentinel: always include so Pi's validation passes.
+  // For no-auth servers the env var will be absent → Pi resolves it as
+  // undefined and omits the Authorization header.  For keyed servers Pi reads
+  // the literal from auth.json first (getApiKeyAndHeaders step 1).
+  // NEVER pass a plaintext key here.
+  const apiKey = "$" + envVarFor(record.id);
+
+  const config: ProviderConfig = {
+    name: record.label,
+    baseUrl: adapter.inferenceBaseUrl(server),
+    api: adapter.piApi,
+    apiKey,
+    models: piModels,
+  };
+
+  // When there is no key stored, remove apiKey only if the server uses no auth.
+  // For auth === "apiKey" servers, hasApiKey should always be true by the time we
+  // call this; but guard defensively: if somehow we're asked to register a keyed
+  // server with no stored key, still emit the sentinel (Pi will just fail auth).
+  if (record.auth === "none" && opts?.hasApiKey !== true) {
+    // For no-auth local backends the env var is unset at runtime, so Pi will
+    // resolve apiKey as undefined — effectively no Authorization header.
+    // We keep the sentinel to satisfy Pi's schema validation.
+    // (No change needed — apiKey is already the sentinel.)
+  }
+
+  return config;
+}
+
+// ---------------------------------------------------------------------------
+// registerServer
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve the server's credential, build its ProviderConfig, and register it
+ * with Pi. Idempotent — Pi's `registerProvider` replaces an existing registration.
+ */
+export async function registerServer(
+  pi: ExtensionAPI,
+  registry: ServerRegistry,
+  record: ServerRecord,
+  models: ModelDescriptor[],
+): Promise<void> {
+  const cred = await registry.resolveCredential(record);
+  const hasApiKey = cred.mode === "apiKey" && cred.apiKey !== undefined;
+
+  // Retrieve the DiscoveredServer shape from the record.
+  // The registry stores the canonicalised baseUrl; reconstruct a minimal server
+  // descriptor for the adapter calls (only baseUrl and kind are needed here).
+  const server: DiscoveredServer = {
+    kind: record.kind,
+    baseUrl: record.baseUrl,
+    auth: record.auth,
+    label: record.label,
+    confidence: 1,
+  };
+
+  const config = buildProviderConfig(record, server, models, { hasApiKey });
+  pi.registerProvider(record.id, config);
+}
+
+// ---------------------------------------------------------------------------
+// unregisterServer
+// ---------------------------------------------------------------------------
+
+/**
+ * Remove this server's Pi provider registration.
+ * Pi restores any built-in models that were overridden.
+ */
+export function unregisterServer(pi: ExtensionAPI, record: ServerRecord): void {
+  pi.unregisterProvider(record.id);
+}
+
+// ---------------------------------------------------------------------------
+// reRegisterServer
+// ---------------------------------------------------------------------------
+
+/**
+ * Re-register a server after its model list has changed.
+ *
+ * Pi's `registerProvider` with `models` replaces the existing model list, so
+ * a plain call to `registerServer` would suffice — but the ARCHITECTURE.md
+ * contract specifies explicit unregister-then-register to guarantee a clean
+ * replacement (removes stale models, resets compat flags, etc.).
+ */
+export async function reRegisterServer(
+  pi: ExtensionAPI,
+  registry: ServerRegistry,
+  record: ServerRecord,
+  models: ModelDescriptor[],
+): Promise<void> {
+  unregisterServer(pi, record);
+  await registerServer(pi, registry, record, models);
+}

package/src/ui/loaded-widget.ts

@@ -0,0 +1,220 @@
+/**
+ * Live "currently loaded" model widget for Crossbar.
+ *
+ * Two public surfaces:
+ *
+ *  1. PURE, UNIT-TESTABLE functions:
+ *     - `formatLoadedStatus` — renders the status string from pre-computed entries.
+ *     - `computeLoadedEntries` — fetches live loaded state from each enabled server,
+ *       falling back to lastKnownLoaded when introspection is unavailable.
+ *
+ *  2. `installLoadedWidget` — wires everything to Pi's `ctx.ui.setStatus`, subscribes
+ *     to `model_select`, and exposes a `refresh()` the health-poll loop calls.
+ *
+ * Hard rules:
+ *  - Never modify src/core/, src/adapters/, src/registry/.
+ *  - Only the injected Probe (createProbe) is used for network calls.
+ *  - API keys are NEVER logged.
+ */
+
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import { adapterFor } from "../adapters/index.ts";
+import { canIntrospect } from "../core/backend-adapter.ts";
+import { createProbe } from "../discovery/probe.ts";
+import type { ServerRegistry } from "../registry/registry.ts";
+import type { LoadedState } from "../core/types.ts";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** One entry per enabled server, ready for formatting. */
+export interface LoadedEntry {
+  /** Human label for the server, e.g. "Ollama". */
+  label: string;
+  /** Currently-loaded model ids (may be empty). */
+  loaded: string[];
+  /** Whether the data came from a live introspection call or a cache. */
+  source: LoadedState["source"];
+}
+
+// ---------------------------------------------------------------------------
+// Pure formatter — no I/O, fully unit-testable
+// ---------------------------------------------------------------------------
+
+/**
+ * Render a compact status string from pre-computed loaded entries.
+ *
+ * Examples:
+ *   live:      "● Ollama:llama3.1"
+ *   last-known "◷ vLLM:qwen (last-known)"
+ *   empty set  "no servers"
+ *   multi      "● Ollama:llama3.1  ◷ vLLM:qwen (last-known)"
+ *
+ * Uses only `theme.fg(token, text)` with tokens: accent/success/dim/muted/warning.
+ */
+export function formatLoadedStatus(
+  entries: LoadedEntry[],
+  theme: Pick<Theme, "fg">,
+): string {
+  if (entries.length === 0) {
+    return theme.fg("muted", "no servers");
+  }
+
+  const parts: string[] = [];
+
+  for (const entry of entries) {
+    const isLive = entry.source === "introspection";
+
+    if (entry.loaded.length === 0) {
+      // Server known but no model loaded
+      const marker = isLive
+        ? theme.fg("dim", "○")
+        : theme.fg("warning", "◷");
+      const label = theme.fg("dim", `${entry.label}:idle`);
+      const suffix = isLive ? "" : theme.fg("dim", " (last-known)");
+      parts.push(`${marker} ${label}${suffix}`);
+    } else {
+      for (const modelId of entry.loaded) {
+        const marker = isLive
+          ? theme.fg("accent", "●")
+          : theme.fg("warning", "◷");
+        const text = isLive
+          ? theme.fg("success", `${entry.label}:${modelId}`)
+          : theme.fg("muted", `${entry.label}:${modelId}`);
+        const suffix = isLive ? "" : theme.fg("dim", " (last-known)");
+        parts.push(`${marker} ${text}${suffix}`);
+      }
+    }
+  }
+
+  return parts.join("  ");
+}
+
+// ---------------------------------------------------------------------------
+// Entry computation — one network round-trip per server that supports introspection
+// ---------------------------------------------------------------------------
+
+/**
+ * For each enabled server in the registry:
+ *   - If its adapter supports `IntrospectLoaded`, call `introspectLoaded` via a fresh
+ *     Probe → source "introspection".
+ *   - Otherwise fall back to `record.lastKnownLoaded` → source "last-known".
+ *   - Per-server failures degrade that entry to "last-known" (never throw the whole batch).
+ */
+export async function computeLoadedEntries(
+  registry: ServerRegistry,
+): Promise<LoadedEntry[]> {
+  const records = registry.list().filter((r) => r.enabled);
+  const results = await Promise.allSettled(
+    records.map(async (record): Promise<LoadedEntry> => {
+      const adapter = adapterFor(record.kind);
+
+      if (canIntrospect(adapter)) {
+        // Resolve credential for the probe
+        const cred = await registry.resolveCredential(record);
+
+        // Build a minimal DiscoveredServer from the stored record
+        const server = {
+          kind: record.kind,
+          baseUrl: record.baseUrl,
+          auth: record.auth,
+          label: record.label,
+          confidence: 1,
+        } as const;
+
+        const probe = createProbe(record.baseUrl, { auth: cred });
+
+        const state = await adapter.introspectLoaded(server, cred, probe);
+        return {
+          label: record.label,
+          loaded: state.loadedModelIds,
+          source: "introspection" as const,
+        };
+      }
+
+      // Fall back to last-known
+      return {
+        label: record.label,
+        loaded: record.lastKnownLoaded ?? [],
+        source: "last-known" as const,
+      };
+    }),
+  );
+
+  const entries: LoadedEntry[] = [];
+  for (let i = 0; i < results.length; i++) {
+    const result = results[i];
+    if (result === undefined) continue;
+    if (result.status === "fulfilled") {
+      entries.push(result.value);
+    } else {
+      // Per-server failure: degrade to last-known without throwing
+      const record = records[i];
+      if (record !== undefined) {
+        entries.push({
+          label: record.label,
+          loaded: record.lastKnownLoaded ?? [],
+          source: "last-known" as const,
+        });
+      }
+    }
+  }
+
+  return entries;
+}
+
+// ---------------------------------------------------------------------------
+// Widget installer — thin Pi-API wiring
+// ---------------------------------------------------------------------------
+
+/** The status key used with `ctx.ui.setStatus`. */
+const STATUS_KEY = "crossbar-loaded";
+
+export interface LoadedWidgetHandle {
+  /** Called by the health-poll loop to push a fresh snapshot to the status bar. */
+  refresh(): Promise<void>;
+  /** Clean up the event subscription. */
+  dispose(): void;
+}
+
+/**
+ * Wire the loaded-model widget to Pi's status bar.
+ *
+ * - Reads `ctx.ui.theme` each refresh so theme switches take effect immediately.
+ * - Listens to `model_select` to refresh on user-driven model changes.
+ * - Returns `{ refresh, dispose }` for the health-poll loop to drive.
+ */
+export function installLoadedWidget(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  registry: ServerRegistry,
+): LoadedWidgetHandle {
+  async function refresh(): Promise<void> {
+    try {
+      const entries = await computeLoadedEntries(registry);
+      const text = formatLoadedStatus(entries, ctx.ui.theme);
+      ctx.ui.setStatus(STATUS_KEY, text);
+    } catch {
+      // Silently suppress: the widget is best-effort; never crash the poll loop.
+    }
+  }
+
+  // Refresh on every model-select event (user switched model via /model or Ctrl+P).
+  // pi.on() returns void — there is no per-listener unsubscribe in the Pi extension API.
+  pi.on("model_select", () => {
+    void refresh();
+  });
+
+  // Initial render
+  void refresh();
+
+  return {
+    refresh,
+    dispose(): void {
+      ctx.ui.setStatus(STATUS_KEY, undefined);
+    },
+  };
+}