@bivy/bivy 0.6.0-staging.84 → 0.6.0-staging.86

package/dist/runtime/index.js

@@ -40,6 +40,21 @@ import { ensureCodexAuth } from "./codex-auth.js";
 import { parserFactoryFor } from "./cli-parsers.js";
 import { sandboxTier, sandboxArgsFor, codexSandboxPolicy } from "../harness/sandbox.js";
 import { ProtocolRuntime, protocolRuntimeFromEnv, protocolCommandsFromEnv } from "./protocol.js";
+import { codexSlashCommands, opencodeSlashCommands } from "./slash-commands.js";
+/**
+ * On-disk slash commands (custom prompts/commands) for the CLI agents that keep
+ * them as markdown on the node — Codex's `$CODEX_HOME/prompts`, opencode's
+ * global + project `command` dirs. Populates their composer menu and makes an
+ * invoked `/name` actually run (see SlashCommandProvider). Any other agent has no
+ * such directory convention, so it returns undefined (no agent-native commands).
+ */
+function cliSlashCommands(id) {
+    if (id === "codex")
+        return codexSlashCommands();
+    if (id === "opencode")
+        return opencodeSlashCommands();
+    return undefined;
+}
 export * from "./types.js";
 export { NodeCredentialResolver, createCredentialStore } from "./credentials.js";
 const PI_CAPABILITIES = {
@@ -982,6 +997,11 @@ function codexApprovalsInfo() {
             packages: false,
             fork: false,
             sessionDiscovery: true,
+            // getUsage() returns the shim's real token/cost snapshot, and `codex resume
+            // <id>` reopens the thread in Codex's TUI — advertise both so the catalog
+            // (and the pre-session picker) match what the session actually backs.
+            usageReporting: true,
+            interactiveTui: installed,
             // The governed/resumable Codex variant is the one that owns native
             // discovery+adoption (issue #156) — not the plain exec runtime below —
             // so an adopted session gets per-tool approvals from the moment it's
@@ -1098,7 +1118,12 @@ function codexAppServerRuntime(credsDir, tier) {
                 ],
             },
         ],
-        capabilities: { toolInterception: true, modelSelection: true, resume: true, nativeSessionDiscovery: true, nativeSessionAdoption: true },
+        // usageReporting: ProtocolSession.getUsage() already returns the shim's real
+        // token/cost snapshot — advertise it so the catalog matches what's backed.
+        // interactiveTui: `codex resume <rolloutId>` reopens the exact thread in
+        // Codex's own TUI (the same verified command as native discovery/takeover),
+        // gated on the codex binary being present — mirrors Claude's interactiveTui.
+        capabilities: { toolInterception: true, modelSelection: true, resume: true, usageReporting: true, interactiveTui: commandAvailable("codex"), nativeSessionDiscovery: true, nativeSessionAdoption: true },
         // Resume: the shim reconnects a prior thread via thread/resume by its rollout
         // id, and history preloads from the same on-disk rollout the exec path reads —
         // so takeover/reopen continues a governed session. (Validated on codex-cli
@@ -1115,6 +1140,15 @@ function codexAppServerRuntime(credsDir, tier) {
         // Bivy didn't start, so a pre-existing `codex` session can be adopted here
         // (the governed variant), never the plain exec runtime below.
         discoverNativeSessions: () => discoverNativeCodexSessions(),
+        // Codex custom prompts ($CODEX_HOME/prompts/*.md) → composer slash menu; an
+        // invoked one is expanded and sent as the turn (the app-server doesn't expand
+        // /prompt names itself). resolveCodexHome() matches the prepare'd CODEX_HOME.
+        slashCommands: codexSlashCommands(),
+        // "Continue in terminal": resume this exact thread in Codex's TUI by its
+        // rollout id. `codex resume <id>` is the same command native discovery and
+        // takeover already use (server.ts RESUME/NATIVE_RESUME maps); `env` carries
+        // the minted CODEX_HOME so the TUI reads the same auth.json chat did.
+        interactiveTui: ({ sessionRef, env }) => (sessionRef ? { command: "codex", args: ["resume", sessionRef], env } : null),
     });
 }
 // --- #2: the GENERAL ACP adapter (Agent Client Protocol) --------------------
@@ -1135,6 +1169,7 @@ function acpShimPath() {
  * ACP promotion path so both wrap agents identically.
  */
 function acpRuntimeOptions(opts) {
+    const slashCommands = cliSlashCommands(opts.id);
     return {
         id: opts.id,
         displayName: opts.displayName,
@@ -1144,6 +1179,9 @@ function acpRuntimeOptions(opts) {
         // the FIRST session (before the shim's hello lands); the hello confirms them.
         capabilities: { toolInterception: true, resume: true },
         resumable: true,
+        // An ACP-promoted opencode still surfaces/expands its on-disk commands (the
+        // ACP handshake doesn't carry them); a bare ACP agent has none.
+        ...(slashCommands ? { slashCommands } : {}),
         ...(opts.credsDir ? { credentials: createCredentialStore(opts.credsDir) } : {}),
     };
 }
@@ -1658,5 +1696,5 @@ function makeCliRuntime(id, options) {
                     : [a.replace(/\{id\}/g, sessionId).replace(/\{tier\}/g, tier)]),
             }
             : {};
-    return new ProcessRuntime({ id, displayName: spec.displayName, command: spec.command, args: runArgs, promptMode: spec.promptMode, credentials: createCredentialStore(options.credsDir), parserFactory: parserFactoryFor(parserId), preflight, prepare, model: cliModelConfig(id), thinking: cliThinkingConfig(id), usageReporting: cliUsageReporting(id), ...resumeOpts });
+    return new ProcessRuntime({ id, displayName: spec.displayName, command: spec.command, args: runArgs, promptMode: spec.promptMode, credentials: createCredentialStore(options.credsDir), parserFactory: parserFactoryFor(parserId), preflight, prepare, model: cliModelConfig(id), thinking: cliThinkingConfig(id), usageReporting: cliUsageReporting(id), slashCommands: cliSlashCommands(id), ...resumeOpts });
 }

package/dist/runtime/process.js

@@ -193,6 +193,17 @@ class ProcessSession {
     setName(name) {
         this.name = name;
     }
+    /** The agent's on-disk slash commands for this workspace (Codex prompts,
+     *  opencode commands). Best-effort and display-only: any read failure yields an
+     *  empty menu, never a throw. */
+    getCommands() {
+        try {
+            return this.runtimeOptions.slashCommands?.list(this.cwd) ?? [];
+        }
+        catch {
+            return [];
+        }
+    }
     async suggestName() {
         // The generic CLI "dumb-pipe" runtime has no model of its own to name a
         // session with. Returning a raw 60-char truncation of the first message here
@@ -216,6 +227,17 @@ class ProcessSession {
         const prompt = text.trim();
         if (!prompt)
             return;
+        // A `/name args` line that matches an on-disk command runs the command by
+        // sending its expanded body to the agent; the transcript still shows what the
+        // user typed. Any non-command line (incl. a leading slash that isn't one)
+        // passes through untouched. Best-effort — a read failure sends the raw line.
+        let promptToSend;
+        try {
+            promptToSend = this.runtimeOptions.slashCommands?.expand(this.cwd, prompt) ?? prompt;
+        }
+        catch {
+            promptToSend = prompt;
+        }
         this.messages.push({ role: "user", content: prompt, timestamp: Date.now() });
         this.streaming = true;
         this.emit({ type: "agent_start" });
@@ -244,7 +266,7 @@ class ProcessSession {
             const idx = Math.min(Math.max(at, 0), argsWithFlags.length);
             argsWithFlags = [...argsWithFlags.slice(0, idx), ...inject, ...argsWithFlags.slice(idx)];
         }
-        const args = this.runtimeOptions.promptMode === "argv" ? [...argsWithFlags, prompt] : argsWithFlags;
+        const args = this.runtimeOptions.promptMode === "argv" ? [...argsWithFlags, promptToSend] : argsWithFlags;
         // Resolve credentials per prompt so freshly-refreshed OAuth tokens (and keys
         // added after this session started) reach the agent. The vault wins over any
         // ambient key so Bivy's shared sign-in is authoritative.
@@ -380,7 +402,7 @@ class ProcessSession {
             this.emit({ type: "agent_end", code, signal });
         });
         if (this.runtimeOptions.promptMode !== "argv") {
-            child.stdin.end(`${prompt}\n`);
+            child.stdin.end(`${promptToSend}\n`);
         }
         else {
             // Prompt is already in argv. Still close stdin so agents that also read it

package/dist/runtime/protocol.js

@@ -5,6 +5,7 @@ import { randomUUID } from "node:crypto";
 import { EventEmitter } from "node:events";
 import { buildAgentCredentialEnv } from "./credentials.js";
 import { bivySessionEnv } from "./session-env.js";
+import { mergeAgentCommands } from "./slash-commands.js";
 import { extractTokenUsage } from "./cli-parsers.js";
 /** A protocol `usage` message → UsageSnapshot (reuses the CLI token-key scan). */
 function parseProtocolUsage(raw) {
@@ -247,6 +248,42 @@ class ProtocolSession {
         await this.open();
         await this.command("command.invoke", { sessionId: this.id, runtimeSessionRef: this.runtimeSessionRef, name, args: args ?? "" });
     }
+    /** The session's slash commands: on-disk custom prompts (Codex/opencode) merged
+     *  with whatever the shim advertised in its hello, disk winning a collision.
+     *  Best-effort and display-only — a read failure just drops the on-disk set. */
+    getCommands() {
+        let disk;
+        try {
+            disk = this.runtimeOptions.slashCommands?.list(this.cwd);
+        }
+        catch {
+            disk = undefined;
+        }
+        return mergeAgentCommands(disk, this.capabilitiesRef.commands);
+    }
+    /**
+     * Resume this session in the agent's own interactive TUI (see the runtimeOptions
+     * hook). Resolves the same launch env a turn would — `prepare` (e.g. Codex
+     * mints CODEX_HOME + auth.json) then credentials — so the TUI opens with the
+     * identical auth as chat. Returns null when the runtime has no TUI hook or there
+     * is no session ref to resume yet (the daemon then surfaces "no TUI available").
+     */
+    async interactiveTuiCommand() {
+        const hook = this.runtimeOptions.interactiveTui;
+        if (!hook)
+            return null;
+        const credentialEnv = this.runtimeOptions.credentials
+            ? await buildAgentCredentialEnv(this.runtimeOptions.credentials, undefined, this.currentModelProvider).catch(() => ({}))
+            : {};
+        let prepareEnv = this.prepareEnv;
+        if (this.runtimeOptions.prepare) {
+            prepareEnv =
+                (await Promise.resolve(this.runtimeOptions.prepare({ ...process.env, ...this.runtimeOptions.env, ...credentialEnv })).catch(() => undefined)) ??
+                    prepareEnv;
+        }
+        const env = { ...this.runtimeOptions.env, ...credentialEnv, ...prepareEnv };
+        return hook({ sessionRef: this.runtimeSessionRef ?? this.resumeRef, cwd: this.cwd, env });
+    }
     getName() { return this.name; }
     setName(name) { this.name = name; }
     async suggestName(firstPrompt) {
@@ -556,6 +593,17 @@ class ProtocolSession {
         const images = (options?.images ?? []).map((img) => ({ type: "image", data: img.data, mimeType: img.mimeType }));
         if (!prompt && !images.length)
             return;
+        // A `/name args` line matching an on-disk custom prompt runs the command by
+        // sending its expanded body; the transcript still shows what the user typed.
+        // Non-command lines pass through untouched. Best-effort — a read failure sends
+        // the raw line.
+        let textToSend;
+        try {
+            textToSend = this.runtimeOptions.slashCommands?.expand(this.cwd, prompt) ?? prompt;
+        }
+        catch {
+            textToSend = prompt;
+        }
         this.messages.push({ role: "user", content: prompt, timestamp: Date.now() });
         this.streaming = true;
         this.assistantText = "";
@@ -566,7 +614,7 @@ class ProtocolSession {
         await this.command("chat.send", {
             sessionId: this.id,
             runtimeSessionRef: this.runtimeSessionRef,
-            text: prompt,
+            text: textToSend,
             // Optional multimodal + streaming hints. Present only when the caller
             // supplied them, so a text-only turn keeps the exact payload it always had.
             ...(images.length ? { images } : {}),

package/dist/runtime/slash-commands.js

@@ -0,0 +1,246 @@
+// SPDX-License-Identifier: FSL-1.1-ALv2
+// Copyright (c) 2026 Petter André Sjulstad
+//
+// Filesystem-sourced slash commands for agents whose "slash commands" are custom
+// prompt/command markdown files on disk — Codex's `$CODEX_HOME/prompts/*.md` and
+// opencode's `command/*.md` dirs — rather than something learned from a live
+// handshake the way Claude (SDK `init`) and Pi (its extension runner) already do.
+// This is what gives Codex and opencode a real slash menu in the composer instead
+// of the empty state Phase 1 added for them. Two responsibilities:
+//
+//  1. Discovery — enumerate those files as `AgentCommand[]` so `getCommands()` can
+//     advertise them and the composer offers them in autocomplete.
+//  2. Local expansion — when the user actually invokes `/name args`, read the file
+//     and return its expanded body so the command RUNS, instead of the literal
+//     text "/name" being sent to the model. Codex and opencode expand custom
+//     prompts only in their interactive TUI, not on the non-interactive
+//     run/app-server path Bivy drives, so Bivy expands them itself. Substitution
+//     mirrors what those agents document: `$ARGUMENTS` → the whole argument
+//     string, `$1`..`$9` → positional words; unused trailing args are appended
+//     when the body carries no placeholder (matching Codex's own behaviour). We
+//     do NOT emulate opencode's `!shell` / `@file` macros — the expanded body is
+//     sent verbatim for those, a documented, graceful partial.
+//
+// Everything is best-effort and synchronous: an unreadable dir yields no commands
+// and `expand()` returns undefined, so the caller falls back to the exact prior
+// "forward the raw slash line" behaviour. `expand()` returning undefined for any
+// line that isn't a known command means ordinary prompts — and a leading slash
+// that happens not to be a command — pass through untouched.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+const DEFAULT_LIMIT = 300;
+const DEFAULT_DEPTH = 3;
+/**
+ * Parse a markdown command file into its display description and prompt body.
+ * A leading `---` YAML frontmatter block contributes `description` (the only key
+ * we read); its body is everything after the block. With no frontmatter the body
+ * is the whole file and the description falls back to the first non-empty line
+ * (stripped of leading markdown heading/list markers, truncated for the menu).
+ * Exported for unit tests.
+ */
+export function parseCommandMarkdown(content) {
+    let description;
+    let body = content;
+    const fm = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/.exec(content);
+    if (fm) {
+        body = content.slice(fm[0].length);
+        for (const line of fm[1].split(/\r?\n/)) {
+            const m = /^\s*description\s*:\s*(.+?)\s*$/i.exec(line);
+            if (m) {
+                description = stripQuotes(m[1]);
+                break;
+            }
+        }
+    }
+    if (!description) {
+        for (const raw of body.split(/\r?\n/)) {
+            const line = raw.trim();
+            if (!line)
+                continue;
+            description = line.replace(/^[#>*\-\s]+/, "").trim() || undefined;
+            break;
+        }
+    }
+    if (description && description.length > 80)
+        description = `${description.slice(0, 79)}…`;
+    return { description, body: body.trim() };
+}
+function stripQuotes(value) {
+    const v = value.trim();
+    if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) {
+        return v.slice(1, -1);
+    }
+    return v;
+}
+/**
+ * Expand a command body against its argument string, mirroring Codex/opencode:
+ * `$ARGUMENTS` → the full argument string, `$1`..`$9` → positional words (missing
+ * ones → empty). When the body references no placeholder and args were supplied,
+ * they're appended (Codex appends unused args rather than dropping them).
+ * Exported for unit tests.
+ */
+export function expandCommandBody(body, argString) {
+    const args = argString.trim();
+    const positional = args ? args.split(/\s+/) : [];
+    let used = false;
+    let out = body.replace(/\$ARGUMENTS\b/g, () => {
+        used = true;
+        return args;
+    });
+    out = out.replace(/\$([1-9])/g, (_m, d) => {
+        used = true;
+        return positional[Number(d) - 1] ?? "";
+    });
+    if (!used && args)
+        out = `${out.replace(/\s+$/, "")}\n\n${args}`;
+    return out.trim();
+}
+/** The command name (without leading slash) a "/name args" line invokes, or null. */
+function parseInvocation(line) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith("/"))
+        return null;
+    const ws = trimmed.search(/\s/);
+    const name = (ws === -1 ? trimmed.slice(1) : trimmed.slice(1, ws)).trim();
+    if (!name)
+        return null;
+    const args = ws === -1 ? "" : trimmed.slice(ws + 1).trim();
+    return { name, args };
+}
+/**
+ * Recursively collect `*.md` under `dir` as `relativePath (no .md)` → absolute
+ * path, where the relative path is POSIX-joined ("/") from the top `dir` so a
+ * subdirectory file namespaces (opencode's `git/commit.md` → `git/commit`).
+ */
+function collectMarkdown(dir, prefix, depth, limit, out) {
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return; // missing/unreadable dir — no commands from here
+    }
+    for (const entry of entries) {
+        if (out.size >= limit)
+            return;
+        if (entry.name.startsWith("."))
+            continue;
+        const abs = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            if (depth > 0)
+                collectMarkdown(abs, prefix ? `${prefix}/${entry.name}` : entry.name, depth - 1, limit, out);
+        }
+        else if (entry.isFile() && entry.name.toLowerCase().endsWith(".md")) {
+            const rel = entry.name.slice(0, -3);
+            out.set(prefix ? `${prefix}/${rel}` : rel, abs);
+        }
+    }
+}
+/**
+ * Build the `/name` → file map for a session: scan each dir (later dirs win a
+ * collision), namespacing subdirectory files with "/" (opencode's convention;
+ * Codex prompts are flat). Best-effort — unreadable dirs contribute nothing.
+ */
+function indexCommands(dirs, depth, limit) {
+    const byName = new Map();
+    for (const dir of dirs) {
+        const found = new Map();
+        collectMarkdown(dir, "", depth, limit, found);
+        for (const [rel, abs] of found) {
+            byName.set(`/${rel}`, abs);
+        }
+    }
+    return byName;
+}
+function readCommandFile(name, abs) {
+    let content;
+    try {
+        content = fs.readFileSync(abs, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+    const { description, body } = parseCommandMarkdown(content);
+    return { name, description, body };
+}
+/**
+ * A `SlashCommandProvider` backed by markdown files in `opts.dirs(cwd)`. Used to
+ * give Codex (`$CODEX_HOME/prompts`) and opencode (global + project `command`
+ * dirs) their slash menus — see `codexSlashCommands` / `opencodeSlashCommands`.
+ */
+export function markdownSlashCommands(opts) {
+    const depth = opts.depth ?? DEFAULT_DEPTH;
+    const limit = opts.limit ?? DEFAULT_LIMIT;
+    return {
+        list(cwd) {
+            const index = indexCommands(opts.dirs(cwd), depth, limit);
+            const out = [];
+            for (const [name, abs] of index) {
+                const file = readCommandFile(name, abs);
+                if (!file)
+                    continue;
+                const command = { name };
+                if (file.description)
+                    command.description = file.description;
+                out.push(command);
+            }
+            out.sort((a, b) => a.name.localeCompare(b.name));
+            return out;
+        },
+        expand(cwd, line) {
+            const invocation = parseInvocation(line);
+            if (!invocation)
+                return undefined;
+            const index = indexCommands(opts.dirs(cwd), depth, limit);
+            const abs = index.get(`/${invocation.name}`);
+            if (!abs)
+                return undefined;
+            const file = readCommandFile(`/${invocation.name}`, abs);
+            if (!file)
+                return undefined;
+            return expandCommandBody(file.body, invocation.args);
+        },
+    };
+}
+/** Codex's home dir, exactly as the CLI resolves it (`$CODEX_HOME` or `~/.codex`). */
+function codexHome() {
+    return process.env.CODEX_HOME?.trim() || path.join(os.homedir(), ".codex");
+}
+/** The user's global opencode config dir (`$XDG_CONFIG_HOME` or `~/.config`). */
+function opencodeConfigDir() {
+    return process.env.XDG_CONFIG_HOME?.trim() || path.join(os.homedir(), ".config");
+}
+/** Codex custom prompts (`$CODEX_HOME/prompts/*.md`) → `/name` commands. */
+export function codexSlashCommands() {
+    return markdownSlashCommands({ dirs: () => [path.join(codexHome(), "prompts")] });
+}
+/**
+ * opencode custom commands — the global `command` dir plus the project-local
+ * `.opencode/command` (which shadows the global on a name collision). See
+ * opencode.ai/docs/commands.
+ */
+export function opencodeSlashCommands() {
+    return markdownSlashCommands({
+        dirs: (cwd) => [path.join(opencodeConfigDir(), "opencode", "command"), path.join(cwd, ".opencode", "command")],
+    });
+}
+/**
+ * Merge disk-sourced commands with any the runtime already advertised (e.g. a
+ * protocol shim's hello), disk winning a name collision. Used by ProtocolSession
+ * so hello-advertised commands and on-disk prompts coexist. First occurrence of
+ * each name (disk first) wins; input order is otherwise preserved.
+ */
+export function mergeAgentCommands(...groups) {
+    const seen = new Set();
+    const out = [];
+    for (const group of groups) {
+        for (const command of group ?? []) {
+            if (!command?.name || seen.has(command.name))
+                continue;
+            seen.add(command.name);
+            out.push(command);
+        }
+    }
+    return out;
+}

package/dist/server.js

@@ -3084,6 +3084,7 @@ const RELAY_COMMANDS = {
     },
     async "models.list"(msg) {
         const requestedSessionId = typeof msg.sessionId === "string" && msg.sessionId ? msg.sessionId : undefined;
+        const wantedRuntimeId = typeof msg.runtimeId === "string" && msg.runtimeId ? msg.runtimeId : undefined;
         let record;
         try {
             record = requestedSessionId ? await resolveOrResumeSession(requestedSessionId, msg.path) : active;
@@ -3096,7 +3097,12 @@ const RELAY_COMMANDS = {
             relay?.sendEvent({ type: "session.error", sessionId: requestedSessionId, error: "Session not found" });
             return;
         }
-        record ??= await sessionForModelQuery();
+        // On a draft (no session id), a runtime hint from the composer takes
+        // precedence so an agent switch previews *that* agent's models even if a
+        // stale `active` on another runtime lingers on the node.
+        if (!requestedSessionId && wantedRuntimeId && record?.runtimeId !== wantedRuntimeId)
+            record = null;
+        record ??= await sessionForModelQuery(wantedRuntimeId);
         const session = record.session;
         const current = session.getCurrentModel();
         const models = await publicModelsList(session, current);
@@ -3108,6 +3114,17 @@ const RELAY_COMMANDS = {
         // (e.g. Claude) — the "Claude shows Codex models" bug.
         relay?.sendEvent({ type: "models.list", sessionId: record.id, runtimeId: record.runtimeId, current: current ? publicModel(current, current) : null, models, thinking });
     },
+    "models.prefetch"(msg) {
+        // The composer's agent picker opened: warm the scratch session for each
+        // offered agent in the background so the first switch to any of them answers
+        // instantly. Fire-and-forget — no reply; the follow-up models.list carries
+        // the result. Ignore anything but a bounded string[] of runtime ids.
+        const ids = Array.isArray(msg.runtimeIds)
+            ? msg.runtimeIds.filter((id) => typeof id === "string" && !!id).slice(0, 16)
+            : [];
+        if (ids.length)
+            prefetchModels(ids);
+    },
     async "model.select"(msg) {
         const requestedSessionId = typeof msg.sessionId === "string" && msg.sessionId ? msg.sessionId : undefined;
         let record;
@@ -8055,32 +8072,75 @@ async function resolveOrResumeSession(sessionId, sessionPath) {
 // races the runtime.select that switches the default agent, pin the pill to the
 // *previous* runtime (the reported agent-switching bug). Mirror how session.new/
 // session.open already refuse to touch `active` for remote clients: reuse a
-// single non-active scratch session on the current default runtime instead of
-// spawning a fresh runtime process on every picker read.
-let modelQueryScratch;
-let modelQueryScratchPending;
-async function sessionForModelQuery() {
-    if (active)
+// non-active scratch session per runtime instead of spawning a fresh runtime
+// process on every picker read.
+//
+// Keyed by runtime id, not a single slot: switching agents (Claude → Codex →
+// Claude) used to evict and re-spawn the one scratch on every switch — the
+// "switching agent takes a long time before models appear" bug. A map keeps one
+// warm scratch per runtime so a switch back to an agent already viewed this
+// session answers from the live session with no re-spawn, and `prefetchModels`
+// can warm several ahead of the first pick.
+const modelQueryScratch = new Map();
+const modelQueryScratchPending = new Map();
+async function sessionForModelQuery(runtimeId) {
+    const wanted = resolveRuntimeId(runtimeId);
+    // A live active session answers for itself — but only when it IS the runtime
+    // being queried, so a prefetch/draft read for a *different* agent doesn't get
+    // the active session's (wrong-runtime) model list.
+    if (active && active.runtimeId === wanted)
         return active;
-    const wanted = resolveRuntimeId();
-    if (modelQueryScratch &&
-        openSessions.has(modelQueryScratch.id) &&
-        modelQueryScratch.runtimeId === wanted &&
-        !sessionBusy(modelQueryScratch)) {
-        touchSession(modelQueryScratch);
-        return modelQueryScratch;
-    }
-    // De-dupe concurrent picker reads. Without this, a WS models.list and an HTTP
-    // GET /api/models fired together on page load both miss the reuse guard above
-    // (the scratch assignment only lands after createSession resolves ~0.3s later)
-    // and each stand up a session, leaving two empty rows a fraction of a second
-    // apart. Collapse concurrent builds onto one promise, mirroring resumingSessions.
-    if (modelQueryScratchPending)
-        return modelQueryScratchPending;
-    modelQueryScratchPending = createSession(defaultWorkspace, undefined, { makeActive: false, ephemeral: true })
-        .then((rec) => { modelQueryScratch = rec; return rec; })
-        .finally(() => { modelQueryScratchPending = undefined; });
-    return modelQueryScratchPending;
+    const cached = modelQueryScratch.get(wanted);
+    if (cached && openSessions.has(cached.id) && cached.runtimeId === wanted && !sessionBusy(cached)) {
+        touchSession(cached);
+        return cached;
+    }
+    // De-dupe concurrent picker reads per runtime. Without this, a WS models.list
+    // and an HTTP GET /api/models fired together on page load both miss the reuse
+    // guard above (the scratch assignment only lands after createSession resolves
+    // ~0.3s later) and each stand up a session, leaving two empty rows a fraction
+    // of a second apart. Collapse concurrent builds onto one promise per runtime,
+    // mirroring resumingSessions.
+    const inflight = modelQueryScratchPending.get(wanted);
+    if (inflight)
+        return inflight;
+    const build = createSession(defaultWorkspace, undefined, { makeActive: false, ephemeral: true, runtimeId: wanted })
+        .then((rec) => { modelQueryScratch.set(wanted, rec); return rec; })
+        .finally(() => { modelQueryScratchPending.delete(wanted); });
+    modelQueryScratchPending.set(wanted, build);
+    return build;
+}
+/**
+ * Warm the model-query scratch for one or more runtimes in the background so the
+ * first agent switch to any of them answers instantly instead of paying the
+ * runtime spin-up on the critical path. Fired when the agent picker opens (see
+ * the `models.prefetch` command). Best-effort and de-duped: a runtime already
+ * warm (or being warmed) is a no-op, and a spin-up failure is swallowed — the
+ * normal models.list path will surface any real error when the user picks it.
+ */
+function prefetchModels(runtimeIds) {
+    const wanted = [];
+    for (const id of runtimeIds) {
+        let resolved;
+        try {
+            resolved = resolveRuntimeId(id);
+        }
+        catch {
+            continue; // unknown/uninstalled agent — nothing to warm
+        }
+        if (wanted.includes(resolved))
+            continue;
+        const cached = modelQueryScratch.get(resolved);
+        if (cached && openSessions.has(cached.id) && !sessionBusy(cached))
+            continue;
+        if (modelQueryScratchPending.has(resolved))
+            continue;
+        wanted.push(resolved);
+    }
+    // Warm serially, not in a burst: spinning up every agent subprocess at once
+    // would spike a small node's memory/CPU right as the user is interacting. Each
+    // build is cached (and de-duped) so this cost is paid at most once per runtime.
+    void wanted.reduce((chain, id) => chain.then(() => sessionForModelQuery(id).then(() => undefined, () => undefined)), Promise.resolve());
 }
 async function createRepoSession(parsed, opts = {}) {
     const token = await resolveTokenForRepo(parsed.owner, parsed.repo);
@@ -8971,10 +9031,13 @@ app.get("/api/models", async (req, res, next) => {
     try {
         const requestedSessionId = typeof req.query.sessionId === "string" && req.query.sessionId ? req.query.sessionId : undefined;
         const requestedPath = typeof req.query.path === "string" ? req.query.path : undefined;
+        const wantedRuntimeId = typeof req.query.runtimeId === "string" && req.query.runtimeId ? req.query.runtimeId : undefined;
         let record = requestedSessionId ? await resolveOrResumeSession(requestedSessionId, requestedPath) : active;
         if (requestedSessionId && !record)
             return res.status(404).json({ error: "Session not found" });
-        record ??= await sessionForModelQuery();
+        if (!requestedSessionId && wantedRuntimeId && record?.runtimeId !== wantedRuntimeId)
+            record = undefined;
+        record ??= await sessionForModelQuery(wantedRuntimeId);
         const session = record.session;
         const current = session.getCurrentModel();
         const models = await publicModelsList(session, current);
@@ -8985,6 +9048,17 @@ app.get("/api/models", async (req, res, next) => {
         next(error);
     }
 });
+// Warm the per-runtime model-query scratch ahead of the first agent switch (see
+// prefetchModels). Fire-and-forget: returns immediately while the runtimes spin
+// up in the background, so the picker never blocks on it.
+app.post("/api/models/prefetch", (req, res) => {
+    const ids = Array.isArray(req.body?.runtimeIds)
+        ? req.body.runtimeIds.filter((id) => typeof id === "string" && !!id).slice(0, 16)
+        : [];
+    if (ids.length)
+        prefetchModels(ids);
+    res.json({ ok: true });
+});
 app.post("/api/models/select", async (req, res, next) => {
     try {
         const requestedSessionId = typeof req.body?.sessionId === "string" && req.body.sessionId ? req.body.sessionId : undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bivy/bivy",
-  "version": "0.6.0-staging.84",
+  "version": "0.6.0-staging.86",
   "type": "module",
   "license": "FSL-1.1-ALv2",
   "description": "Run coding agents on machines you own. Source-available, self-hostable agent workspace.",