@nopeek/agent-bridge 0.4.2 → 0.5.1

package/dist/backends.d.ts

@@ -8,6 +8,8 @@ export declare function soulPath(homeDir: string, handle: string): string;
  * Returns the soul path.
  */
 export declare function provisionSoul(handle: string, homeDir: string): string;
+/** Resolve a binary: $<ENVVAR> > PATH (command -v) > common install dirs. */
+export declare function resolveBin(name: string, envVar: string): string | null;
 /**
  * Deterministic per-(bot, channel) session UUID so each chat is one running
  * Claude conversation. UUIDv5-ish (sha1 of the key formatted as a UUID) —
@@ -23,6 +25,7 @@ export declare function sessionUuid(handle: string, channelId: string): string;
  * host powers from wherever the bridge happens to run.
  */
 export declare function claudeBrain(cfg: BridgeConfig): Brain;
+export declare function hermesHome(): string;
 /**
  * Create (or reuse) the bot's isolated Hermes profile: its own SOUL.md and
  * memories/, inheriting the main install's model config and provider auth

package/dist/backends.js

@@ -62,7 +62,7 @@ export function provisionSoul(handle, homeDir) {
 }
 // ----------------------------------------------------------------- helpers ----
 /** Resolve a binary: $<ENVVAR> > PATH (command -v) > common install dirs. */
-function resolveBin(name, envVar) {
+export function resolveBin(name, envVar) {
     const fromEnv = process.env[envVar];
     if (fromEnv)
         return fromEnv;
@@ -232,7 +232,7 @@ export function claudeBrain(cfg) {
     };
 }
 // ----------------------------------------------------------------- hermes ----
-function hermesHome() {
+export function hermesHome() {
     return process.env.HERMES_HOME || "/Volumes/x10drive/hermes";
 }
 /** Hermes profile-local soul (mirrors tools/hermes/SOUL-template.md). */

package/dist/bot.d.ts

@@ -1,10 +1,12 @@
-import type { BridgeConfig } from "./config.js";
+import type { BridgeConfig, BrainBackend } from "./config.js";
 export interface BotInfo {
     userId: string;
     handle: string;
     nickname?: string;
     ownerType?: string;
     ownerId?: string;
+    /** Server-mediated backend from runtime/bots or adopt_bot (optional). */
+    backend?: BrainBackend;
 }
 export declare class BotRunner {
     readonly info: BotInfo;
@@ -23,6 +25,9 @@ export declare class BotRunner {
     private log;
     private logErr;
     constructor(info: BotInfo, cfg: BridgeConfig);
+    /** Re-read the effective brain (e.g. after a live server backend change) so
+     *  status reflects it immediately. The next message re-resolves regardless. */
+    refreshBrainKind(): void;
     /** Fire-and-forget: runs the connect loop in the background, isolated. */
     start(): void;
     stop(): void;

package/dist/bot.js

@@ -38,6 +38,12 @@ export class BotRunner {
         this.log = (m) => console.log(`${tag} ${m}`);
         this.logErr = (m) => console.error(`${tag} ${m}`);
     }
+    /** Re-read the effective brain (e.g. after a live server backend change) so
+     *  status reflects it immediately. The next message re-resolves regardless. */
+    refreshBrainKind() {
+        this.brainKind = resolveBrain(this.cfg, this.info.handle).kind;
+        this.log(`brain re-resolved live: ${this.brainKind}`);
+    }
     /** Fire-and-forget: runs the connect loop in the background, isolated. */
     start() {
         void this.run().catch((err) => {

package/dist/brain.d.ts

@@ -19,8 +19,12 @@ export interface ResolvedBrain {
     kind: string;
 }
 /**
- * Pick the brain for one bot. Per-bot precedence within a BRAIN_MAP entry:
- * cmd > url > backend (native claude/hermes/echo) > echo; then the globals:
- * BRAIN_CMD > BRAIN_URL > echo.
+ * Pick the brain for one bot. Precedence:
+ *   1. LOCAL per-bot override (BRAIN_MAP["<handle>"], set via the 127.0.0.1 API
+ *      on this computer): cmd > url > backend (claude/hermes/echo) > echo. This
+ *      ALWAYS wins — a same-computer power user's choice is never overridden.
+ *   2. SERVER backend (cfg.serverBackends["<handle>"], chosen from the phone and
+ *      pushed down the control socket) — only when there's no local override.
+ *   3. Globals: BRAIN_CMD > BRAIN_URL > echo.
  */
 export declare function resolveBrain(cfg: BridgeConfig, handle: string): ResolvedBrain;

package/dist/brain.js

@@ -128,12 +128,17 @@ function urlBrain(url, timeoutMs) {
 /** Zero-config smoke test. */
 const echoBrain = async (text) => `You said: ${text}`;
 /**
- * Pick the brain for one bot. Per-bot precedence within a BRAIN_MAP entry:
- * cmd > url > backend (native claude/hermes/echo) > echo; then the globals:
- * BRAIN_CMD > BRAIN_URL > echo.
+ * Pick the brain for one bot. Precedence:
+ *   1. LOCAL per-bot override (BRAIN_MAP["<handle>"], set via the 127.0.0.1 API
+ *      on this computer): cmd > url > backend (claude/hermes/echo) > echo. This
+ *      ALWAYS wins — a same-computer power user's choice is never overridden.
+ *   2. SERVER backend (cfg.serverBackends["<handle>"], chosen from the phone and
+ *      pushed down the control socket) — only when there's no local override.
+ *   3. Globals: BRAIN_CMD > BRAIN_URL > echo.
  */
 export function resolveBrain(cfg, handle) {
-    const override = cfg.brainMap[handle.replace(/^@/, "")];
+    const h = handle.replace(/^@/, "");
+    const override = cfg.brainMap[h];
     if (override?.cmd)
         return { brain: cmdBrain(override.cmd, cfg.brainTimeoutMs), kind: "cmd (per-bot)" };
     if (override?.url)
@@ -144,6 +149,14 @@ export function resolveBrain(cfg, handle) {
         return { brain: hermesBrain(cfg), kind: "hermes (per-bot)" };
     if (override?.backend === "echo" || override?.echo)
         return { brain: echoBrain, kind: "echo (per-bot)" };
+    // No local override — honor the server-mediated backend if one was pushed.
+    const server = cfg.serverBackends[h];
+    if (server === "claude")
+        return { brain: claudeBrain(cfg), kind: "claude (server)" };
+    if (server === "hermes")
+        return { brain: hermesBrain(cfg), kind: "hermes (server)" };
+    if (server === "echo")
+        return { brain: echoBrain, kind: "echo (server)" };
     if (cfg.brainCmd)
         return { brain: cmdBrain(cfg.brainCmd, cfg.brainTimeoutMs), kind: "cmd" };
     if (cfg.brainUrl)

package/dist/bridge.d.ts

@@ -1,5 +1,5 @@
 import type { BridgeConfig, BrainSpec } from "./config.js";
-export declare const VERSION = "0.4.2";
+export declare const VERSION = "0.5.1";
 export interface PairRequest {
     pairingSecret: string;
     appId: string;
@@ -25,6 +25,7 @@ export declare class BridgeApp {
     readonly startedAt: number;
     private bots;
     private control;
+    private capabilitiesTimer;
     private stopped;
     constructor(cfg: BridgeConfig);
     get paired(): boolean;
@@ -43,6 +44,15 @@ export declare class BridgeApp {
     unpair(): void;
     /** Apply a brain change live (next message uses it) and persist it. */
     setBrains(patch: BrainsPatch): void;
+    /**
+     * Record a SERVER-provided backend for a handle and make it take effect.
+     * Kept SEPARATE from brainMap (which holds local 127.0.0.1 overrides): a
+     * local override always wins in resolveBrain, so the server backend is stored
+     * either way but is inert while a local override exists. When it IS the
+     * effective brain (no local override), provision the soul/profile up front so
+     * the very first message doesn't wait on it. Persisted for reconnects.
+     */
+    private applyServerBackend;
     statusMinimal(): Record<string, unknown>;
     statusFull(): Record<string, unknown>;
     private startBot;

package/dist/bridge.js

@@ -12,8 +12,11 @@ import { BotRunner } from "./bot.js";
 import { ControlSocket } from "./control.js";
 import { resolveBrain } from "./brain.js";
 import { provisionSoul } from "./backends.js";
+import { reportCapabilities } from "./capabilities.js";
 import { isBrainBackend } from "./config.js";
-export const VERSION = "0.4.2";
+export const VERSION = "0.5.1";
+/** How often to re-probe + report brain availability to the server. */
+const CAPABILITIES_INTERVAL_MS = 5 * 60_000;
 export class PairError extends Error {
     code;
     constructor(code, message) {
@@ -26,6 +29,7 @@ export class BridgeApp {
     startedAt = Date.now();
     bots = new Map(); // botUserId -> runner
     control = null;
+    capabilitiesTimer = null;
     stopped = false;
     constructor(cfg) {
         this.cfg = cfg;
@@ -140,6 +144,37 @@ export class BridgeApp {
         saveSettings(this.cfg);
         console.log(`[bridge] brains updated: default=${this.cfg.brainCmd ? "cmd" : this.cfg.brainUrl ? "url" : "echo"}, ${Object.keys(this.cfg.brainMap).length} per-bot override(s)`);
     }
+    /**
+     * Record a SERVER-provided backend for a handle and make it take effect.
+     * Kept SEPARATE from brainMap (which holds local 127.0.0.1 overrides): a
+     * local override always wins in resolveBrain, so the server backend is stored
+     * either way but is inert while a local override exists. When it IS the
+     * effective brain (no local override), provision the soul/profile up front so
+     * the very first message doesn't wait on it. Persisted for reconnects.
+     */
+    applyServerBackend(rawHandle, backend) {
+        const handle = rawHandle.replace(/^@/, "");
+        const changed = this.cfg.serverBackends[handle] !== backend;
+        this.cfg.serverBackends[handle] = backend;
+        if (changed) {
+            saveSettings(this.cfg);
+            console.log(`[bridge] server backend for @${handle} = ${backend}`);
+        }
+        const hasLocalOverride = Boolean(this.cfg.brainMap[handle]);
+        if (hasLocalOverride) {
+            // Local override wins and is untouched; the server backend stays recorded
+            // but does not drive this bot until the local override is cleared.
+            return;
+        }
+        if (backend !== "echo") {
+            try {
+                provisionSoul(handle, this.cfg.homeDir);
+            }
+            catch (err) {
+                console.error(`[bridge] soul provisioning for @${handle} failed: ${err.message}`);
+            }
+        }
+    }
     // -------------------------------------------------------------- status ----
     statusMinimal() {
         return {
@@ -164,6 +199,7 @@ export class BridgeApp {
                         ? { url: this.cfg.brainUrl }
                         : { echo: true },
                 map: this.cfg.brainMap,
+                serverBackends: this.cfg.serverBackends,
                 provisionCmd: this.cfg.brainProvisionCmd,
             },
             bots: [...this.bots.values()].map((b) => ({
@@ -247,8 +283,13 @@ export class BridgeApp {
         }
         const { bots: list } = (await res.json());
         console.log(`[bridge] runtime owns ${list.length} bot(s): ${list.map((b) => `@${b.handle}`).join(", ") || "(none yet)"}`);
-        for (const info of list)
+        for (const info of list) {
+            // Record any server-mediated backend BEFORE starting the runner so its
+            // first brain resolution already sees it (local overrides still win).
+            if (info.backend)
+                this.applyServerBackend(info.handle, info.backend);
             this.startBot(info);
+        }
     }
     startCore() {
         if (this.stopped || this.control)
@@ -260,9 +301,14 @@ export class BridgeApp {
                 void this.syncBots().catch((err) => {
                     console.error(`[bridge] bot sync failed: ${err.message}`);
                 });
+                // Report which brains this computer can run so the phone's picker is
+                // current (initial connect + every reconnect). Non-fatal on failure.
+                void reportCapabilities(this.cfg);
             },
             onAdoptBot: (f) => {
-                this.startBot({ userId: f.botUserId, handle: f.handle, ownerId: f.ownerUserId });
+                if (f.backend)
+                    this.applyServerBackend(f.handle, f.backend);
+                this.startBot({ userId: f.botUserId, handle: f.handle, ownerId: f.ownerUserId, backend: f.backend });
             },
             onGrantChanged: (f) => {
                 // Access changed for a bot — re-pull its allow list so enforcement is
@@ -271,6 +317,20 @@ export class BridgeApp {
                 if (runner)
                     void runner.refreshAccess();
             },
+            onBotConfig: (f) => {
+                // The owner changed this bot's brain from the phone. Record the server
+                // backend and re-resolve live — the runner resolves per message off the
+                // shared cfg, so the NEXT message already uses it; we also refresh the
+                // cached kind so status reflects it immediately. A running bot is keyed
+                // by userId; map it to a handle via its runner.
+                const runner = this.bots.get(f.botUserId);
+                if (!runner) {
+                    console.log(`[bridge] bot_config_changed for ${f.botUserId} not running yet — applied on next sync/adopt`);
+                    return;
+                }
+                this.applyServerBackend(runner.info.handle, f.backend);
+                runner.refreshBrainKind();
+            },
         });
         // Bots first (so a control-socket hiccup doesn't delay serving), then the
         // control socket, whose auth.ok triggers a redundant-but-safe re-sync.
@@ -278,8 +338,20 @@ export class BridgeApp {
             console.error(`[bridge] initial bot sync failed (will retry on control auth): ${err.message}`);
         });
         this.control.start();
+        // Re-probe + report brain availability every ~5 min so a login/logout on
+        // this computer surfaces in the phone's picker without a reconnect. The
+        // onAuthed handler covers initial + reconnect reports; this covers drift.
+        // unref so a running interval never keeps the process alive on its own.
+        this.capabilitiesTimer = setInterval(() => {
+            void reportCapabilities(this.cfg);
+        }, CAPABILITIES_INTERVAL_MS);
+        this.capabilitiesTimer.unref?.();
     }
     stopCore() {
+        if (this.capabilitiesTimer) {
+            clearInterval(this.capabilitiesTimer);
+            this.capabilitiesTimer = null;
+        }
         this.control?.stop();
         this.control = null;
         for (const b of this.bots.values())

package/dist/capabilities.d.ts

@@ -0,0 +1,23 @@
+import type { BridgeConfig } from "./config.js";
+/** One backend's readiness. `reason` is a short human string when unavailable. */
+export interface BackendCapability {
+    available: boolean;
+    reason?: string;
+}
+export interface Capabilities {
+    claude: BackendCapability;
+    hermes: BackendCapability;
+}
+/**
+ * Probe which native brains are ready on this computer. Best-effort and FREE:
+ * binary resolution + credential file/keychain/env presence only, never a paid
+ * model call. Echo is always available and isn't probed.
+ */
+export declare function probeCapabilities(_cfg: BridgeConfig): Promise<Capabilities>;
+/**
+ * Probe, then PUT the result to the server so the phone's picker reflects it.
+ * Authed with the runtime pairing token — the SAME Bearer auth the bridge uses
+ * for GET /runtime/bots (see bridge.ts syncBots). Non-fatal: a failed report is
+ * logged and retried on the next tick (control reconnect or the 5-min interval).
+ */
+export declare function reportCapabilities(cfg: BridgeConfig): Promise<void>;

package/dist/capabilities.js

@@ -0,0 +1,153 @@
+// Brain availability probe — the phone's "Create a bot" picker only offers the
+// brains this computer can actually run. We probe locally (is the CLI installed?
+// is it logged in?) and report up to the server over REST with the runtime
+// pairing token; the server aggregates it into the per-app brain-options picker.
+//
+// Hard rule: the probe is FREE. It never makes a paid model call. It only looks
+// at what's on disk / in env / in the keychain — binary resolution, credential
+// files, env vars. Echo is always available (local, no login) so it isn't probed.
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { homedir, platform } from "node:os";
+import { join } from "node:path";
+import { resolveBin, hermesHome } from "./backends.js";
+// Reasons are stable strings the app renders verbatim ("Claude — not logged in").
+const NOT_INSTALLED = "not installed";
+const NOT_LOGGED_IN = "not logged in";
+// -------------------------------------------------------------- claude ----
+/**
+ * Is Claude Code logged in on this host? Any ONE of these is enough — we never
+ * make a request, just check for the presence of a credential:
+ *   - ~/.claude/.credentials.json exists (the file-based OAuth store)
+ *   - $CLAUDE_CODE_OAUTH_TOKEN or $ANTHROPIC_API_KEY is set
+ *   - (macOS) the Claude Code keychain item exists (best-effort; errors swallowed)
+ */
+function claudeHasCredentials() {
+    if (existsSync(join(homedir(), ".claude", ".credentials.json")))
+        return true;
+    if (process.env.CLAUDE_CODE_OAUTH_TOKEN || process.env.ANTHROPIC_API_KEY)
+        return true;
+    if (platform() === "darwin" && macKeychainHas("Claude Code-credentials"))
+        return true;
+    return false;
+}
+/** Best-effort macOS keychain lookup by service name. Never throws. */
+function macKeychainHas(service) {
+    try {
+        const r = spawnSync("security", ["find-generic-password", "-s", service], {
+            encoding: "utf8",
+            timeout: 5_000,
+        });
+        return r.status === 0;
+    }
+    catch {
+        return false;
+    }
+}
+function probeClaude() {
+    // Binary first: no `claude` on PATH (or $CLAUDE_BIN) → nothing to log into.
+    const bin = resolveBin("claude", "CLAUDE_BIN");
+    if (!bin)
+        return { available: false, reason: NOT_INSTALLED };
+    if (!claudeHasCredentials())
+        return { available: false, reason: NOT_LOGGED_IN };
+    return { available: true };
+}
+// -------------------------------------------------------------- hermes ----
+/**
+ * Read the base Hermes auth.json (the credential the per-bot souls' auth is
+ * symlinked to — see provisionHermesProfile) and decide if it's still valid.
+ * A revoked xAI OAuth login leaves the file in place but with empty tokens and
+ * a `last_auth_error` / `relogin_required` marker — that's "not logged in", not
+ * "not installed". FREE: file read only, no refresh attempt.
+ *
+ * Returns: "valid" | "revoked" | "missing".
+ */
+function hermesCredentialState() {
+    const authPath = join(hermesHome(), "auth.json");
+    if (!existsSync(authPath))
+        return "missing";
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(authPath, "utf8"));
+    }
+    catch {
+        return "revoked"; // present but unparseable → treat as invalid, not missing
+    }
+    const providers = parsed?.providers;
+    if (!providers || typeof providers !== "object")
+        return "revoked";
+    // Valid if ANY provider has live tokens and isn't flagged for re-login.
+    for (const p of Object.values(providers)) {
+        const prov = p;
+        if (prov?.relogin_required === true)
+            continue;
+        const tokens = prov?.tokens;
+        const hasTokens = tokens != null && typeof tokens === "object" && Object.keys(tokens).length > 0;
+        if (hasTokens)
+            return "valid";
+    }
+    return "revoked";
+}
+function probeHermes() {
+    // Binary first: no `hermes` on PATH (or $HERMES_BIN) → not installed.
+    const bin = resolveBin("hermes", "HERMES_BIN");
+    if (!bin)
+        return { available: false, reason: NOT_INSTALLED };
+    // The base profile the per-bot souls are cloned from = $HERMES_HOME/config.yaml.
+    if (!existsSync(join(hermesHome(), "config.yaml")))
+        return { available: false, reason: NOT_INSTALLED };
+    const cred = hermesCredentialState();
+    if (cred === "valid")
+        return { available: true };
+    // Base profile is present but its credential is missing or revoked → login issue.
+    return { available: false, reason: NOT_LOGGED_IN };
+}
+// ------------------------------------------------------------- public ----
+/**
+ * Probe which native brains are ready on this computer. Best-effort and FREE:
+ * binary resolution + credential file/keychain/env presence only, never a paid
+ * model call. Echo is always available and isn't probed.
+ */
+export async function probeCapabilities(_cfg) {
+    return { claude: probeClaude(), hermes: probeHermes() };
+}
+function summarize(c) {
+    return c.available ? "ok" : (c.reason ?? "unavailable");
+}
+/**
+ * Probe, then PUT the result to the server so the phone's picker reflects it.
+ * Authed with the runtime pairing token — the SAME Bearer auth the bridge uses
+ * for GET /runtime/bots (see bridge.ts syncBots). Non-fatal: a failed report is
+ * logged and retried on the next tick (control reconnect or the 5-min interval).
+ */
+export async function reportCapabilities(cfg) {
+    if (!cfg.pairingCode)
+        return; // unpaired — nothing to report to
+    let caps;
+    try {
+        caps = await probeCapabilities(cfg);
+    }
+    catch (err) {
+        console.error(`[caps] probe failed: ${err.message}`);
+        return;
+    }
+    console.log(`[caps] claude=${summarize(caps.claude)} hermes=${summarize(caps.hermes)}`);
+    try {
+        const res = await fetch(`${cfg.apiUrl}/v1/runtime/capabilities`, {
+            method: "PUT",
+            headers: {
+                authorization: `Bearer ${cfg.pairingCode}`,
+                "content-type": "application/json",
+            },
+            body: JSON.stringify({ backends: { claude: caps.claude, hermes: caps.hermes } }),
+            signal: AbortSignal.timeout(15_000),
+        });
+        if (!res.ok) {
+            console.error(`[caps] report failed: PUT /v1/runtime/capabilities HTTP ${res.status}`);
+        }
+    }
+    catch (err) {
+        console.error(`[caps] report failed: ${err.message}`);
+    }
+}

package/dist/config.d.ts

@@ -22,8 +22,18 @@ export interface BridgeConfig {
     brainCmd: string | null;
     /** Global brain: webhook POSTed {text, botHandle, botUserId, channelId, senderUserId}. */
     brainUrl: string | null;
-    /** Per-handle overrides: { "<handle>": {"cmd": "…"} | {"url": "…"} }. */
+    /** Per-handle overrides: { "<handle>": {"cmd": "…"} | {"url": "…"} }.
+     *  These are LOCAL overrides set via the 127.0.0.1 API on this computer and
+     *  ALWAYS win over a server-provided backend. */
     brainMap: Record<string, BrainSpec>;
+    /**
+     * Server-mediated backends, keyed by bot handle. The owner picks a bot's
+     * brain (claude|hermes|echo) FROM THE PHONE; the server pushes it down the
+     * control socket and it lands here. Consulted by resolveBrain ONLY when the
+     * handle has no local `brainMap` override — a local override always wins.
+     * Persisted so a reconnect keeps the choice even before the next sync.
+     */
+    serverBackends: Record<string, BrainBackend>;
     /**
      * Auto-provisioner: run ONCE for each adopted bot that has no BRAIN_MAP
      * entry (env: NOPEEK_BOT_HANDLE, NOPEEK_BOT_USER_ID). Its trimmed stdout

package/dist/config.js

@@ -141,6 +141,27 @@ function parseBrainMap(raw) {
     }
     return out;
 }
+/** Parse the persisted server-backend map ({"<handle>":"claude"|…}). Lenient:
+ *  a corrupt/partial value never crashes the bridge — bad entries are dropped. */
+function parseServerBackends(raw) {
+    if (!raw)
+        return {};
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return {};
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+        return {};
+    const out = {};
+    for (const [handle, backend] of Object.entries(parsed)) {
+        if (isBrainBackend(backend))
+            out[handle.replace(/^@/, "")] = backend;
+    }
+    return out;
+}
 function settingsPath(homeDir) {
     return join(homeDir, "settings.json");
 }
@@ -199,6 +220,8 @@ export function loadConfig(argv = process.argv.slice(2)) {
         brainCmd: get("brain-cmd") ?? null,
         brainUrl: get("brain-url") ?? null,
         brainMap: parseBrainMap(get("brain-map")),
+        // Server-provided (no CLI flag): env/config/persisted-settings only.
+        serverBackends: parseServerBackends(process.env.NOPEEK_SERVER_BACKENDS ?? file.NOPEEK_SERVER_BACKENDS ?? saved.NOPEEK_SERVER_BACKENDS),
         brainProvisionCmd: get("brain-provision-cmd") ?? null,
         brainTimeoutMs,
         port,
@@ -222,6 +245,9 @@ export function saveSettings(cfg) {
         ...(cfg.brainCmd ? { BRAIN_CMD: cfg.brainCmd } : {}),
         ...(cfg.brainUrl ? { BRAIN_URL: cfg.brainUrl } : {}),
         ...(Object.keys(cfg.brainMap).length ? { BRAIN_MAP: JSON.stringify(cfg.brainMap) } : {}),
+        ...(Object.keys(cfg.serverBackends).length
+            ? { NOPEEK_SERVER_BACKENDS: JSON.stringify(cfg.serverBackends) }
+            : {}),
         ...(cfg.brainProvisionCmd ? { BRAIN_PROVISION_CMD: cfg.brainProvisionCmd } : {}),
         ...(cfg.declineMessage ? { NOPEEK_DECLINE_MESSAGE: cfg.declineMessage } : {}),
     };

package/dist/control.d.ts

@@ -1,10 +1,17 @@
-import type { BridgeConfig } from "./config.js";
+import type { BridgeConfig, BrainBackend } from "./config.js";
 export interface AdoptBotFrame {
     type: "adopt_bot";
     botUserId: string;
     appId: string;
     ownerUserId: string;
     handle: string;
+    /** Server-mediated backend picked from the phone (optional). */
+    backend?: BrainBackend;
+}
+export interface BotConfigChangedFrame {
+    type: "bot_config_changed";
+    botUserId: string;
+    backend: BrainBackend;
 }
 export interface BotGrantChangedFrame {
     type: "bot_grant_changed";
@@ -18,6 +25,8 @@ export interface ControlHandlers {
     onAuthed: (runtimeId: string) => void;
     onAdoptBot: (frame: AdoptBotFrame) => void;
     onGrantChanged: (frame: BotGrantChangedFrame) => void;
+    /** Server pushed a new backend for a running bot — re-resolve its brain live. */
+    onBotConfig: (frame: BotConfigChangedFrame) => void;
 }
 export declare class ControlSocket {
     connected: boolean;

package/dist/control.js

@@ -1,3 +1,4 @@
+import { isBrainBackend } from "./config.js";
 export class ControlSocket {
     connected = false;
     runtimeId = null;
@@ -80,6 +81,16 @@ export class ControlSocket {
                 this.handlers.onAdoptBot(f);
                 return;
             }
+            case "bot_config_changed": {
+                const f = frame;
+                if (!isBrainBackend(f.backend)) {
+                    console.error(`[control] bot_config_changed with invalid backend "${String(f.backend)}" ignored`);
+                    return;
+                }
+                console.log(`[control] bot_config_changed bot=${f.botUserId} backend=${f.backend}`);
+                this.handlers.onBotConfig(f);
+                return;
+            }
             case "bot_grant_changed": {
                 const f = frame;
                 // TODO(grants): enforce these — for now bots answer everyone in their

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nopeek/agent-bridge",
-  "version": "0.4.2",
+  "version": "0.5.1",
   "description": "Run your own agents as E2EE NoPeek bots. Pairs with a one-time code, runs every bot you own, and pipes messages to any command or webhook.",
   "type": "module",
   "license": "MIT",