@schlessera/brain-ui-server 0.33.0 → 0.34.0

package/dist/agent/backend.js

@@ -1,3 +1,4 @@
+import { BackendProfileConfigError } from "@schlessera/brain-ui-sdk/server";
 import { createRequire } from "module";
 const LEVEL_SEVERITY = {
     debug: "DEBUG",
@@ -12,18 +13,8 @@ function toBackendLog(log) {
         ...(attrs ? { attributes: attrs } : {}),
     });
 }
-/** Reasoning levels pi accepts (mirror of pi-agent-core's `ThinkingLevel`). */
-export const PI_THINKING_LEVELS = [
-    "off",
-    "minimal",
-    "low",
-    "medium",
-    "high",
-    "xhigh",
-    "max",
-];
 const PROFILE_MEMO_MS = 5_000;
-function buildSnapshot(backends, defaultBackendId) {
+function buildSnapshot(backends, defaultBackendId, resolved = new Map(), modelSource = null) {
     if (backends.length === 0) {
         throw new Error("Backend registry requires at least one backend.");
     }
@@ -35,12 +26,31 @@ function buildSnapshot(backends, defaultBackendId) {
         byId.get(resolvedDefaultId),
         ...backends.filter((backend) => backend.id !== resolvedDefaultId),
     ];
-    return { backends: ordered, byId, defaultBackendId: resolvedDefaultId };
+    return { backends: ordered, byId, defaultBackendId: resolvedDefaultId, resolved, modelSource };
+}
+// The only runtime-discovery surface: two fixed first-party packages. The
+// environment never supplies a specifier or introduces another identity.
+const FIRST_PARTY_BACKENDS = [
+    {
+        id: "claude",
+        specifier: "@schlessera/brain-backend-claude",
+        profiles: (agent) => agent.profilesJson,
+        joinsPrimary: false,
+    },
+    {
+        id: "pi",
+        specifier: "@schlessera/brain-backend-pi",
+        profiles: (agent) => agent.piProfilesJson,
+        joinsPrimary: true,
+    },
+];
+function firstParty(id) {
+    return FIRST_PARTY_BACKENDS.find((entry) => entry.id === id);
+}
+function activeFirstPartyBackends(agent) {
+    const primary = agent.backend || "claude";
+    return FIRST_PARTY_BACKENDS.filter((entry) => entry.id === primary || (entry.joinsPrimary && Boolean(entry.profiles(agent))));
 }
-const BACKEND_SPECIFIERS = {
-    claude: "@schlessera/brain-backend-claude",
-    pi: "@schlessera/brain-backend-pi",
-};
 function unknownBackendError(primary) {
     return new Error(`AGENT_BACKEND="${primary}" does not match any configured backend ` +
         `(expected "claude" or "pi").`);
@@ -50,31 +60,23 @@ function missingBackendError(primary) {
         return new Error('AGENT_BACKEND=pi but "@schlessera/brain-backend-pi" is not installed. ' +
             "Add it (with its pi SDK dependencies) or set AGENT_BACKEND=claude.");
     }
-    return new Error(`AGENT_BACKEND=${primary} but "@schlessera/brain-backend-claude" is not installed. ` +
+    return new Error('AGENT_BACKEND=claude but "@schlessera/brain-backend-claude" is not installed. ' +
         "Add it (it carries the Claude Agent SDK) or set AGENT_BACKEND=pi.");
 }
-/**
- * Boot-time guard: the SELECTED backend's package must at least RESOLVE, so a
- * broken install refuses to start instead of reporting healthy and failing
- * every agent turn (the guarantee the old static import gave, restored without
- * giving up the lazy load — `require.resolve` never executes the module, so
- * the Agent SDK still loads on first use only). Called by `createApp()` next
- * to the auth assertions; skipped when an explicit registry is injected.
- *
- * An unrecognized AGENT_BACKEND fails here too, for the same reason.
- *
- * The `resolve` parameter exists for tests (simulating an absent package);
- * production callers pass nothing.
- */
-/** The specifier an ERR_MODULE_NOT_FOUND failed on, or null for any other error. */
+function missingConfiguredBackendError(entry) {
+    if (entry.id === "pi") {
+        return new Error('BRAIN_UI_PI_PROFILES is set but "@schlessera/brain-backend-pi" is not ' +
+            "installed. Add it (with its pi SDK dependencies) or unset the variable.");
+    }
+    return new Error('BRAIN_UI_CLAUDE_PROFILES is set but "@schlessera/brain-backend-claude" is not ' +
+        "installed. Add it (it carries the Claude Agent SDK) or unset the variable.");
+}
 function moduleNotFoundSpecifier(error) {
     if (typeof error !== "object" || error === null)
         return null;
     const { code, specifier, message } = error;
     if (code !== "ERR_MODULE_NOT_FOUND" && code !== "MODULE_NOT_FOUND")
         return null;
-    // Bun's ResolveMessage (not an Error instance) carries the failing
-    // specifier as a property; Node quotes it in the message instead.
     if (typeof specifier === "string")
         return specifier;
     if (typeof message === "string") {
@@ -84,441 +86,192 @@ function moduleNotFoundSpecifier(error) {
     }
     return null;
 }
-/**
- * Load an optional backend package, mapping ONLY "the backend package itself
- * is not installed" to the actionable install hint. Everything else — the
- * backend missing one of its OWN transitive deps, a syntax error, a throwing
- * top-level — is a different failure whose original error IS the diagnostic,
- * so it is rethrown untouched. The distinction rides on ERR_MODULE_NOT_FOUND
- * naming the specifier it failed on: a transitive miss names the transitive
- * dep, not the backend, and must not read as "backend not installed".
- *
- * `await import()` rather than `createRequire()(...)`: the backend packages
- * are ESM, and a CJS require of them under plain Node dies with
- * ERR_REQUIRE_ESM — which the old blanket catch then reported as "not
- * installed" on a machine where the package was sitting right there.
- *
- * The `importer` parameter exists for tests (simulating absent or broken
- * packages); production callers pass nothing.
- */
-export async function loadBackendModule(
-// "claude" | "pi" spelled out, NOT keyof typeof BACKEND_SPECIFIERS: the
-// keyof form drags the table's literal string types — the backend
-// specifiers — into the emitted .d.ts, which the declaration-surface gate
-// rightly refuses.
-key, importer = (specifier) => import(specifier)) {
-    const specifier = BACKEND_SPECIFIERS[key];
+export async function loadBackendModule(key, importer = (specifier) => import(specifier)) {
+    const entry = firstParty(key);
     try {
-        return await importer(specifier);
+        return await importer(entry.specifier);
     }
     catch (error) {
-        if (moduleNotFoundSpecifier(error) === specifier)
+        if (moduleNotFoundSpecifier(error) === entry.specifier) {
             throw missingBackendError(key);
+        }
         throw error;
     }
 }
-/**
- * Parse + validate the pi roster from BRAIN_UI_PI_PROFILES (a JSON array of
- * {id,label,vendor,model,thinkingLevel?}). Malformed input THROWS rather than
- * silently dropping the roster; `assertBackendResolvable` runs this at boot so
- * a bad config refuses to start instead of reporting healthy and 500ing later.
- *
- * Ids Claude's side of the picker uses or can mint later ("default",
- * "claude", "claude-*" — discovery canonicalizes every Anthropic model to a
- * claude-* alias) are rejected, as is any collision with an id declared in
- * BRAIN_UI_CLAUDE_PROFILES — a cross-backend collision otherwise surfaces as
- * a 500 on first request. Claude's own JSON is parsed leniently here: when it
- * is malformed, the Claude loader raises its own (more precise) boot error.
- */
-export function parsePiProfiles(raw, claudeProfilesRaw) {
-    if (!raw)
-        return [];
-    let inputs;
-    try {
-        inputs = JSON.parse(raw);
-    }
-    catch (err) {
-        throw new Error(`BRAIN_UI_PI_PROFILES is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
-    }
-    if (!Array.isArray(inputs)) {
-        throw new Error("BRAIN_UI_PI_PROFILES must be a JSON array.");
-    }
-    const claudeIds = new Set();
-    if (claudeProfilesRaw) {
-        try {
-            const claudeInputs = JSON.parse(claudeProfilesRaw);
-            if (Array.isArray(claudeInputs)) {
-                for (const entry of claudeInputs) {
-                    if (entry && typeof entry.id === "string")
-                        claudeIds.add(entry.id);
-                }
-            }
-        }
-        catch {
-            // Malformed Claude JSON is the Claude loader's error to raise.
-        }
+/** Load and structurally validate the one descriptor exported by a backend package. */
+export async function loadBackendDescriptor(key, importer) {
+    return backendDescriptorFromModule(key, await loadBackendModule(key, importer));
+}
+function backendDescriptorFromModule(key, loaded) {
+    const backendPackage = loaded;
+    const descriptor = backendPackage.backendModule;
+    if (!descriptor ||
+        descriptor.id !== key ||
+        typeof descriptor.resolveFromEnv !== "function" ||
+        typeof descriptor.profileSchema?.parse !== "function" ||
+        !descriptor.settingsHooks) {
+        throw new Error(`The ${key} backend package does not export a valid backendModule descriptor.`);
     }
-    const seen = new Set();
-    for (const input of inputs) {
-        if (!input || typeof input !== "object") {
-            throw new Error("Each BRAIN_UI_PI_PROFILES entry must be an object.");
-        }
-        for (const field of ["id", "label", "vendor", "model"]) {
-            if (typeof input[field] !== "string" || input[field].length === 0) {
-                throw new Error(`Each BRAIN_UI_PI_PROFILES entry needs a non-empty string ${field}.`);
-            }
-        }
-        if (input.id === "default" || /^claude(-|$)/.test(input.id)) {
-            throw new Error(`BRAIN_UI_PI_PROFILES id "${input.id}" is reserved for the Claude ` +
-                "roster (built-in default and discovered claude-* aliases).");
-        }
-        if (claudeIds.has(input.id)) {
-            throw new Error(`BRAIN_UI_PI_PROFILES id "${input.id}" collides with a ` +
-                "BRAIN_UI_CLAUDE_PROFILES entry.");
-        }
-        if (seen.has(input.id)) {
-            throw new Error(`Duplicate profile id in BRAIN_UI_PI_PROFILES: "${input.id}".`);
-        }
-        seen.add(input.id);
-        if (input.thinkingLevel !== undefined &&
-            !PI_THINKING_LEVELS.includes(input.thinkingLevel)) {
-            throw new Error(`BRAIN_UI_PI_PROFILES entry "${input.id}" has invalid thinkingLevel ` +
-                `"${input.thinkingLevel}" (expected one of ${PI_THINKING_LEVELS.join(", ")}).`);
+    return descriptor;
+}
+function parseBackendDescriptors(agent, entries, descriptors) {
+    const occupiedProfiles = [];
+    const activeIds = new Set(entries.map((entry) => entry.id));
+    const inactiveRosters = FIRST_PARTY_BACKENDS.filter((entry) => !activeIds.has(entry.id)).map((entry) => ({ backendId: entry.id, raw: entry.profiles(agent) }));
+    const parsed = new Map();
+    for (const entry of entries) {
+        const descriptor = descriptors.get(entry.id);
+        if (!descriptor) {
+            throw new Error(`Backend descriptor "${entry.id}" was not loaded.`);
+        }
+        const result = descriptor.profileSchema.parse(entry.profiles(agent), {
+            occupiedProfiles,
+            inactiveRosters,
+        });
+        if (!result.ok)
+            throw new BackendProfileConfigError(result.errors);
+        parsed.set(entry.id, { descriptor, profiles: result.profiles });
+        for (const profile of result.profiles) {
+            occupiedProfiles.push({ id: profile.id, source: descriptor.profileSchema.source });
         }
     }
-    return inputs;
+    return parsed;
 }
+/**
+ * Boot guard. It resolves active optional backend packages and synchronously
+ * loads their descriptors so backend-owned profile validation finishes before
+ * the application can report healthy. Inactive rosters are supplied as raw
+ * collision data without loading or strictly parsing their packages. Backend
+ * construction and model discovery remain lazy in the registry.
+ */
 export function assertBackendResolvable(agent, resolve = (specifier) => {
     createRequire(import.meta.url).resolve(specifier);
+}, load = (specifier) => {
+    return createRequire(import.meta.url)(specifier);
 }) {
     const primary = agent.backend || "claude";
-    if (!(primary in BACKEND_SPECIFIERS))
+    const primaryEntry = firstParty(primary);
+    if (!primaryEntry)
         throw unknownBackendError(primary);
-    const key = primary;
-    try {
-        resolve(BACKEND_SPECIFIERS[key]);
-    }
-    catch {
-        throw missingBackendError(key);
-    }
-    // BRAIN_UI_PI_PROFILES opts the pi backend in ALONGSIDE the primary — its
-    // package must resolve at boot too, or the roster silently loses those
-    // profiles on first request instead of refusing to start.
-    if (agent.piProfilesJson && key !== "pi") {
+    const entries = activeFirstPartyBackends(agent);
+    const descriptors = new Map();
+    for (const entry of entries) {
         try {
-            resolve(BACKEND_SPECIFIERS.pi);
+            resolve(entry.specifier);
         }
         catch {
-            throw new Error('BRAIN_UI_PI_PROFILES is set but "@schlessera/brain-backend-pi" is not ' +
-                "installed. Add it (with its pi SDK dependencies) or unset the variable.");
+            if (entry.id === primary)
+                throw missingBackendError(entry.id);
+            throw missingConfiguredBackendError(entry);
         }
-    }
-    // Validate the pi roster itself at boot too — the registry is built lazily,
-    // so without this a malformed BRAIN_UI_PI_PROFILES would still report a
-    // healthy startup and only fail on first request.
-    parsePiProfiles(agent.piProfilesJson, agent.profilesJson);
-}
-export function createBackendRegistry(options) {
-    const { brainPath, agent } = options;
-    const getHidden = options.getHiddenModelIds ?? (() => []);
-    const backendLog = options.log ? toBackendLog(options.log) : undefined;
-    let cachedRegistry = null;
-    let modelSource = null;
-    /**
-     * Declared profiles carrying their OWN credential env vars
-     * (authTokenEnv/apiKeyEnv) — api-billed regardless of the ambient
-     * credential. Populated when the Claude roster resolves, which happens
-     * before any profile can be listed or run.
-     */
-    const declaredApiProfileIds = new Set();
-    /** The Claude backend's id, once built — Claude's subscription path only applies to its own profiles. */
-    let claudeBackendId = null;
-    /**
-     * Base billing classification for one roster entry, BEFORE the settings
-     * override (applied last by the shared accessor surface):
-     *   - a non-Claude backend profile → by VENDOR: pi's "openai-codex" runs
-     *     only against a ChatGPT-subscription OAuth credential (the provider
-     *     has no API-key path at all) → "subscription"; every other vendor
-     *     resolves ambient API keys → "api";
-     *   - a declared Claude profile with explicit credentials → "api";
-     *   - everything ambient (built-in default, discovered models, declared
-     *     entries without their own credentials) → the env-resolved ambient
-     *     mode (subscription iff the OAuth token is present and no
-     *     ANTHROPIC_API_KEY — the Agent SDK's own precedence).
-     */
-    function classifyBilling(profile) {
-        if (claudeBackendId === null || profile.backendId !== claudeBackendId) {
-            return profile.vendor === "openai-codex" ? "subscription" : "api";
-        }
-        if (declaredApiProfileIds.has(profile.id))
-            return "api";
-        return agent.ambientBilling;
-    }
-    /**
-     * Declared profiles (built-in default + BRAIN_UI_CLAUDE_PROFILES) plus every
-     * discovered model whose id isn't already declared. Declared wins: the env
-     * stays an override mechanism, and a hand-pinned entry keeps its label and
-     * endpoint.
-     *
-     * Memoized on the discovered array's identity — `createModelSource` swaps the
-     * array only on a successful refresh, so steady state is one comparison.
-     */
-    let mergeCache = null;
-    /**
-     * User-managed OpenRouter models (Settings → Models) as declared Claude
-     * profiles — same shape a BRAIN_UI_CLAUDE_PROFILES OpenRouter entry has,
-     * but editable at runtime without an env change or redeploy.
-     */
-    function customOpenRouterInputs() {
-        const models = options.getCustomOpenRouterModels?.() ?? [];
-        return models.map((model) => ({
-            id: `openrouter:${model}`,
-            label: `${model} (OpenRouter)`,
-            vendor: "openrouter",
-            model,
-            baseUrl: "https://openrouter.ai/api",
-            authTokenEnv: "OPENROUTER_API_KEY",
-            modelAliases: true,
-            source: "declared",
-        }));
-    }
-    function mergeDiscovered(claude, declared, discovered) {
-        const custom = customOpenRouterInputs();
-        const customKey = custom.map((profile) => profile.id).join("\n");
-        if (mergeCache &&
-            mergeCache.declared === declared &&
-            mergeCache.discovered === discovered &&
-            mergeCache.customKey === customKey) {
-            return mergeCache.result;
-        }
-        const declaredIds = new Set(declared.map((profile) => profile.id));
-        const customExtra = custom.filter((input) => !declaredIds.has(input.id));
-        // OpenRouter runs on its own key: always api-billed, like an env-declared
-        // profile with explicit credentials.
-        for (const input of customExtra)
-            declaredApiProfileIds.add(input.id);
-        const knownIds = new Set([...declaredIds, ...customExtra.map((input) => input.id)]);
-        const extra = discovered.filter((input) => !knownIds.has(input.id));
-        const result = [...declared, ...claude.defineProfiles([...customExtra, ...extra])];
-        mergeCache = { declared, discovered, customKey, result };
-        return result;
-    }
-    // The built-in default profile's model. The Claude backend historically
-    // pinned the default to a specific model; after the SDK extraction the pin
-    // was lost and resumed default-profile sessions drifted to "whatever the CLI
-    // defaults to", silently changing model/behaviour/billing on every CLI bump.
-    // Re-pin it (a committed default, overridable per deploy via
-    // BRAIN_UI_CLAUDE_DEFAULT_MODEL) so the default stays on a known model.
-    function builtinDefaultProfiles(claude) {
-        return claude.defineProfiles([
-            {
-                id: "claude",
-                label: "Claude",
-                vendor: "anthropic",
-                model: agent.defaultModel,
-                modelAliases: true,
-                source: "builtin",
-            },
-        ]);
-    }
-    /**
-     * The Claude roster: the pinned built-in "claude" default first, plus any
-     * extra profiles from BRAIN_UI_CLAUDE_PROFILES (a JSON array of profile
-     * inputs: {id,label,model?,baseUrl?,authTokenEnv?,apiKeyEnv?,modelAliases?}).
-     *
-     * A malformed or duplicate-id roster THROWS — caught at boot by the registry
-     * fail-fast — rather than silently degrading to default-only and rebilling
-     * every pinned session to the subscription with nothing in the logs.
-     */
-    function loadClaudeProfiles(claude) {
-        const base = builtinDefaultProfiles(claude);
-        const raw = agent.profilesJson;
-        if (!raw)
-            return base;
-        let inputs;
         try {
-            inputs = JSON.parse(raw);
-        }
-        catch (err) {
-            throw new Error(`BRAIN_UI_CLAUDE_PROFILES is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
-        }
-        if (!Array.isArray(inputs)) {
-            throw new Error("BRAIN_UI_CLAUDE_PROFILES must be a JSON array.");
+            descriptors.set(entry.id, backendDescriptorFromModule(entry.id, load(entry.specifier)));
         }
-        // Reject duplicate ids (including collisions with the built-in "claude"): a
-        // duplicate silently shadows and can resolve to the wrong credentials.
-        const seen = new Set(base.map((profile) => profile.id));
-        for (const input of inputs) {
-            if (!input || typeof input.id !== "string" || input.id.length === 0) {
-                throw new Error("Each BRAIN_UI_CLAUDE_PROFILES entry needs a non-empty string id.");
+        catch (error) {
+            if (entry.id === primary && moduleNotFoundSpecifier(error) === entry.specifier) {
+                throw missingBackendError(entry.id);
             }
-            if (seen.has(input.id)) {
-                throw new Error(`Duplicate profile id in BRAIN_UI_CLAUDE_PROFILES: "${input.id}".`);
+            if (entry.id !== primary && moduleNotFoundSpecifier(error) === entry.specifier) {
+                throw missingConfiguredBackendError(entry);
             }
-            seen.add(input.id);
-            // The same non-empty test defineProfiles applies to requiredEnvKeys: a
-            // profile bringing its own credential env var is api-billed.
-            if (input.authTokenEnv || input.apiKeyEnv)
-                declaredApiProfileIds.add(input.id);
+            throw error;
         }
-        const declared = inputs.map((input) => ({
-            source: "declared",
-            ...input,
-        }));
-        return [...base, ...claude.defineProfiles(declared)];
     }
-    /**
-     * NEITHER backend package is a hard dependency — a deployment installs the
-     * one its AGENT_BACKEND names (both, if it switches). Loaded lazily through
-     * {@link loadBackendModule} so the server still boots without the unused
-     * one; only "the package is absent" maps to the actionable install hint,
-     * any other load failure surfaces as itself.
-     */
-    async function buildClaudeBackend() {
-        const claude = (await loadBackendModule("claude"));
-        if (typeof claude.createClaudeBackend !== "function") {
-            throw new Error('"@schlessera/brain-backend-claude" does not export createClaudeBackend.');
-        }
-        // Declared profiles are resolved EAGERLY so a malformed
-        // BRAIN_UI_CLAUDE_PROFILES still fails at boot rather than on first request.
-        const declared = loadClaudeProfiles(claude);
-        modelSource = claude.createModelSource({
-            brainPath,
-            enabled: agent.modelDiscovery,
-            ttlMs: agent.modelTtlMs,
-        });
-        const backend = claude.createClaudeBackend({
-            brainPath,
-            claudeCodePath: agent.claudeCodePath,
-            ...(backendLog ? { log: backendLog } : {}),
-            // Omitted entirely when unconfigured, so the backend's own defaults
-            // apply; an explicit [] passes through and disables confirmation.
-            ...(agent.confirmBashPatterns !== null
-                ? { confirmBashPatterns: agent.confirmBashPatterns }
-                : {}),
-            // A function, not an array: discovery refreshes in the background and the
-            // new roster has to be visible without restarting the process.
-            profiles: () => mergeDiscovered(claude, declared, modelSource?.list() ?? []),
-        });
-        claudeBackendId = backend.id;
-        return backend;
-    }
-    async function buildPiBackend() {
-        const mod = (await loadBackendModule("pi"));
-        if (typeof mod.createPiBackend !== "function") {
-            throw new Error('"@schlessera/brain-backend-pi" does not export createPiBackend.');
-        }
-        // Re-parsed here (assertBackendResolvable already validated at boot) so an
-        // injected-registry path without the boot assert still fails loudly.
-        const profiles = parsePiProfiles(agent.piProfilesJson, agent.profilesJson);
-        // A FUNCTION, so per-profile thinking overrides from settings are read on
-        // every use (roster listing AND new-session model resolution) — a change
-        // in Settings applies to the next turn without a rebuild.
-        const withOverrides = () => {
-            const overrides = options.getThinkingOverrides?.() ?? {};
-            return profiles.map((profile) => overrides[profile.id]
-                ? { ...profile, thinkingLevel: overrides[profile.id] }
-                : profile);
-        };
-        return mod.createPiBackend({
-            brainPath,
-            ...(profiles.length > 0 ? { profiles: withOverrides } : {}),
-            ...(backendLog ? { log: backendLog } : {}),
-            // Same shared confirm-pattern config as the Claude backend, so both
-            // backends stop on the same destructive bash shapes.
-            ...(agent.confirmBashPatterns !== null
-                ? { confirmBashPatterns: agent.confirmBashPatterns }
-                : {}),
-        });
+    parseBackendDescriptors(agent, entries, descriptors);
+}
+function settingsFor(hooks, readers) {
+    return {
+        ...(hooks.hiddenModelIds ? { getHiddenModelIds: readers.getHiddenModelIds } : {}),
+        ...(hooks.defaultModelId ? { getDefaultModelId: readers.getDefaultModelId } : {}),
+        ...(hooks.customOpenRouterModels
+            ? { getCustomOpenRouterModels: readers.getCustomOpenRouterModels }
+            : {}),
+        ...(hooks.thinkingOverrides
+            ? { getThinkingOverrides: readers.getThinkingOverrides }
+            : {}),
+        ...(hooks.billingOverrides
+            ? { getBillingOverrides: readers.getBillingOverrides }
+            : {}),
+    };
+}
+export function createBackendRegistry(options) {
+    const { brainPath, agent } = options;
+    const primary = agent.backend || "claude";
+    if (!firstParty(primary)) {
+        return makeRegistry(async () => {
+            throw unknownBackendError(primary);
+        }, options);
     }
+    const readers = {
+        getHiddenModelIds: options.getHiddenModelIds ?? (() => []),
+        getDefaultModelId: options.getDefaultModelId ?? (() => null),
+        getCustomOpenRouterModels: options.getCustomOpenRouterModels ?? (() => []),
+        getThinkingOverrides: options.getThinkingOverrides ?? (() => ({})),
+        getBillingOverrides: options.getBillingOverrides ?? (() => ({})),
+    };
+    const backendLog = options.log ? toBackendLog(options.log) : undefined;
+    let cachedRegistry = null;
     async function buildRegistry() {
-        const primary = agent.backend || "claude";
-        if (primary === "pi") {
-            const pi = await buildPiBackend();
-            return buildSnapshot([pi], pi.id);
-        }
-        const backends = [await buildClaudeBackend()];
-        // BRAIN_UI_PI_PROFILES opts the pi backend in ALONGSIDE claude: its
-        // profiles join the picker (e.g. OpenAI models under a ChatGPT
-        // subscription via pi's "openai-codex" vendor) while claude stays the
-        // default backend. Without the variable, behavior is unchanged.
-        if (agent.piProfilesJson) {
-            backends.push(await buildPiBackend());
-        }
-        // AGENT_BACKEND must name a configured backend. The in-process options are
-        // "claude" (default) and "pi" (handled above). An unrecognized value is a
-        // misconfiguration — fail loudly instead of silently coercing to claude and
-        // running on the wrong backend with nothing in the logs.
-        if (agent.backend && !backends.some((b) => b.id === primary)) {
-            throw unknownBackendError(primary);
+        const entries = activeFirstPartyBackends(agent);
+        const descriptors = new Map();
+        for (const entry of entries) {
+            descriptors.set(entry.id, await loadBackendDescriptor(entry.id));
+        }
+        const parsedDescriptors = parseBackendDescriptors(agent, entries, descriptors);
+        const resolved = new Map();
+        const backends = [];
+        let modelSource = null;
+        for (const entry of entries) {
+            const parsed = parsedDescriptors.get(entry.id);
+            const { descriptor } = parsed;
+            const baseContext = {
+                brainPath,
+                config: { ...agent },
+                profiles: parsed.profiles,
+                confirmBashPatterns: agent.confirmBashPatterns,
+                settings: settingsFor(descriptor.settingsHooks, readers),
+                ...(backendLog ? { log: backendLog } : {}),
+            };
+            const source = descriptor.modelSource?.(baseContext) ?? null;
+            const resolution = await descriptor.resolveFromEnv({
+                ...baseContext,
+                ...(source ? { modelSource: source } : {}),
+            });
+            if (!resolution.ok)
+                throw resolution.error;
+            if (resolution.value.backend.id !== descriptor.id) {
+                throw new Error(`Backend descriptor "${descriptor.id}" built backend "${resolution.value.backend.id}".`);
+            }
+            resolved.set(descriptor.id, resolution.value);
+            backends.push(resolution.value.backend);
+            modelSource ??= source;
         }
-        return buildSnapshot(backends, primary);
+        return buildSnapshot(backends, primary, resolved, modelSource);
     }
-    async function getRegistry() {
+    const getRegistry = () => {
         if (!cachedRegistry)
             cachedRegistry = buildRegistry();
         return cachedRegistry;
-    }
-    /**
-     * Whether the openai-codex (ChatGPT subscription) account is connected —
-     * a cheap file probe through the pi package, memoized briefly so provider
-     * listings and turn routing don't re-read the auth store on every call.
-     */
-    let codexCredentialCache = null;
-    async function hasCodexCredential() {
-        const piInPlay = Boolean(agent.piProfilesJson) || (agent.backend || "claude") === "pi";
-        if (!piInPlay)
-            return false;
-        if (codexCredentialCache && Date.now() - codexCredentialCache.at < PROFILE_MEMO_MS) {
-            return codexCredentialCache.value;
-        }
-        let value = false;
-        try {
-            const mod = (await loadBackendModule("pi"));
-            value =
-                typeof mod.hasStoredCredential === "function" &&
-                    mod.hasStoredCredential("openai-codex");
-        }
-        catch {
-            value = false;
-        }
-        codexCredentialCache = { at: Date.now(), value };
-        return value;
-    }
-    return makeRegistry(getRegistry, getHidden, async () => {
-        await getRegistry();
-        return modelSource;
-    }, options.log, {
-        classify: classifyBilling,
-        ...(options.getBillingOverrides
-            ? { getOverrides: options.getBillingOverrides }
-            : {}),
-    }, {
-        ...(options.getDefaultModelId ? { getOverride: options.getDefaultModelId } : {}),
-        auto: { vendor: "openai-codex", hasCredential: hasCodexCredential },
-    });
+    };
+    return makeRegistry(getRegistry, options);
 }
-/**
- * A registry over an explicit backend list — the seam tests (and embedders
- * with their own backend wiring) use instead of mutating module state. Takes
- * the same optional hidden-ids reader so visibility behavior matches
- * production.
- */
-export function createStaticBackendRegistry(backends, defaultBackendId = backends[0]?.id ?? "", options = {}) {
-    const snapshot = buildSnapshot(backends, defaultBackendId);
-    return makeRegistry(async () => snapshot, options.getHiddenModelIds ?? (() => []), async () => null, options.log, 
-    // No classifier: an embedder's backends carry no credential topology this
-    // registry could reason about, so only an explicit override sets a mode.
-    options.getBillingOverrides
-        ? { getOverrides: options.getBillingOverrides }
-        : {}, 
-    // No auto rule either — only the stored default applies here.
-    options.getDefaultModelId ? { getOverride: options.getDefaultModelId } : {});
+export function createStaticBackendRegistry(entries, defaultBackendId = entries[0]
+    ? "backend" in entries[0]
+        ? entries[0].backend.id
+        : entries[0].id
+    : "", options = {}) {
+    const resolved = new Map();
+    const backends = entries.map((entry) => {
+        if (!("backend" in entry))
+            return entry;
+        resolved.set(entry.backend.id, entry);
+        return entry.backend;
+    });
+    const snapshot = buildSnapshot(backends, defaultBackendId, resolved, options.modelSource ?? null);
+    return makeRegistry(async () => snapshot, options);
 }
-/** The accessor surface, shared by the config-driven and static registries. */
-function makeRegistry(getRegistry, getHidden, getModelSource, log, billing = {}, defaults = {}) {
+function makeRegistry(getRegistry, options) {
     let profileSnapshot = null;
-    /** Recompute the profile roster (memoized), asserting cross-backend id uniqueness. */
     async function getProfileSnapshot() {
         if (profileSnapshot && Date.now() - profileSnapshot.at < PROFILE_MEMO_MS) {
             return profileSnapshot;
@@ -540,57 +293,47 @@ function makeRegistry(getRegistry, getHidden, getModelSource, log, billing = {},
         profileSnapshot = { at: Date.now(), byBackend, owners };
         return profileSnapshot;
     }
-    /** A settings read failure must not take the picker down — degrade to "nothing hidden". */
     function hiddenIds() {
         try {
-            return new Set(getHidden());
+            return new Set(options.getHiddenModelIds?.() ?? []);
         }
-        catch (err) {
-            log?.emit({
+        catch (error) {
+            options.log?.emit({
                 severityText: "WARN",
                 body: "could not read hidden models; treating none as hidden",
-                attributes: { error: err instanceof Error ? err.message : String(err) },
+                attributes: { error: error instanceof Error ? error.message : String(error) },
             });
             return new Set();
         }
     }
-    /** Same degradation discipline: a failed override read means derived modes apply. */
     function billingOverrides() {
         try {
-            return billing.getOverrides?.() ?? {};
+            return options.getBillingOverrides?.() ?? {};
         }
-        catch (err) {
-            log?.emit({
+        catch (error) {
+            options.log?.emit({
                 severityText: "WARN",
                 body: "could not read billing overrides; using derived billing modes",
-                attributes: { error: err instanceof Error ? err.message : String(err) },
+                attributes: { error: error instanceof Error ? error.message : String(error) },
             });
             return {};
         }
     }
-    /**
-     * The preferred-default profile. The stored Settings override wins while it
-     * still names a roster profile (a vanished profile falls through to auto
-     * rather than pinning turns to nothing); auto is the first non-hidden
-     * roster entry of the auto vendor, but only while its credential exists.
-     * Any failure degrades to "no preference" — this must never take routing
-     * down.
-     */
     async function getPreferredProfileId() {
         try {
             const snapshot = await getProfileSnapshot();
-            const override = defaults.getOverride?.() ?? null;
+            const override = options.getDefaultModelId?.() ?? null;
             if (override && snapshot.owners.has(override))
                 return override;
-            const auto = defaults.auto;
-            if (!auto)
-                return null;
             const registry = await getRegistry();
             const hidden = hiddenIds();
             for (const backend of registry.backends) {
-                const match = (snapshot.byBackend.get(backend.id) ?? []).find((profile) => profile.vendor === auto.vendor && !hidden.has(profile.id));
+                const preference = registry.resolved.get(backend.id)?.preferredProfile;
+                if (!preference)
+                    continue;
+                const match = (snapshot.byBackend.get(backend.id) ?? []).find((profile) => preference.matches(profile) && !hidden.has(profile.id));
                 if (match)
-                    return (await auto.hasCredential()) ? match.id : null;
+                    return (await preference.hasCredential()) ? match.id : null;
             }
             return null;
         }
@@ -614,37 +357,33 @@ function makeRegistry(getRegistry, getHidden, getModelSource, log, billing = {},
         },
         async getBackendForProfile(profileId) {
             const registry = await getRegistry();
-            // Deliberately resolved against the UNFILTERED roster: a session pinned
-            // to a profile the user later hid must keep running.
             const snapshot = await getProfileSnapshot();
             const backendId = snapshot.owners.get(profileId);
             return backendId ? registry.byId.get(backendId) : undefined;
         },
         async getBackendForSession(backendId) {
             const registry = await getRegistry();
-            if (backendId) {
-                const backend = registry.byId.get(backendId);
-                if (backend)
-                    return backend;
+            if (!backendId)
+                return registry.byId.get(registry.defaultBackendId);
+            const backend = registry.byId.get(backendId);
+            if (!backend) {
+                throw new Error(`Stored backend id "${backendId}" is not configured.`);
             }
-            return registry.byId.get(registry.defaultBackendId);
+            return backend;
         },
-        async listAllProviders(options = {}) {
+        async listAllProviders(listOptions = {}) {
             const registry = await getRegistry();
             const snapshot = await getProfileSnapshot();
-            const hidden = options.includeHidden ? new Set() : hiddenIds();
-            // Read fresh on every listing (not memoized with the snapshot), so a
-            // saved override is live for the very next run without invalidation.
+            const hidden = listOptions.includeHidden ? new Set() : hiddenIds();
             const overrides = billingOverrides();
             const providers = registry.backends.flatMap((backend) => (snapshot.byBackend.get(backend.id) ?? [])
                 .filter((profile) => !hidden.has(profile.id))
                 .map((profile) => {
                 const entry = { ...profile, backendId: backend.id };
-                const billingMode = overrides[profile.id] ?? billing.classify?.(entry);
+                const billingMode = overrides[profile.id] ??
+                    registry.resolved.get(backend.id)?.classifyBilling?.(profile);
                 return billingMode ? { ...entry, billingMode } : entry;
             }));
-            // A connected subscription-auth profile leads the list: a fresh client
-            // with no stored selection defaults to providers[0].
             const preferredId = await getPreferredProfileId();
             if (preferredId) {
                 const index = providers.findIndex((provider) => provider.id === preferredId);
@@ -661,7 +400,9 @@ function makeRegistry(getRegistry, getHidden, getModelSource, log, billing = {},
                 { id: backend.id, capabilities: backend.capabilities },
             ]));
         },
-        getModelSource,
+        async getModelSource() {
+            return (await getRegistry()).modelSource;
+        },
         invalidateProfiles() {
             profileSnapshot = null;
         },