@bivy/bivy 0.20.7-staging.2 → 0.20.7-staging.3

package/bin/bivy.mjs

@@ -1221,6 +1221,18 @@ const AGENT_SESSION_ID_FLAG = {
   gemini: "--session-id",
 };
 
+// Args a native `bivy run <agent>` adds so the session stays one Bivy can take
+// over as a chat. Codex 0.160's TUI otherwise runs its threads in a shared
+// background app-server that outlives the terminal and keeps the thread's
+// writer lock, so "Use chat" failed with "thread … already has an active writer".
+const AGENT_RUN_ARGS = {
+  codex: ["--no-daemon"],
+};
+function applyAgentRunArgs(agentId, spec) {
+  const add = (AGENT_RUN_ARGS[agentId] ?? []).filter((arg) => !(spec.args ?? []).includes(arg));
+  if (add.length) spec.args = [...add, ...(spec.args ?? [])];
+}
+
 // Args that mean the caller already chose a session (pin or resume), so we must
 // not inject our own --session-id over the top.
 const SESSION_ID_CONFLICTS = ["--session-id", "--resume", "-r", "-c", "--continue"];
@@ -2057,6 +2069,7 @@ async function cmdRun(args = []) {
   // didn't already choose one), so the on-disk session is a known, deterministic
   // resume target — the anchor for later "continue as chat" adoption.
   const pinnedSessionId = bivySession ? undefined : pinRunSessionId(agentId, resolved.spec);
+  applyAgentRunArgs(agentId, resolved.spec);
   if (bivySession) resolved.spec.sessionId = bivySession;
   if (pinnedSessionId) {
     console.log(c.dim(`session id ${pinnedSessionId} — resume in a terminal with '${agentId} --resume ${pinnedSessionId}'`));
@@ -3111,7 +3124,8 @@ async function cmdApp(args = []) {
        bivy app list [--session <id>]
        bivy app remove <app-id> [--session <id>]
        bivy app shot [app-id] [--widths 390,1280] [--themes light,dark] [--path /page] [--session <id>]
-       bivy app present [view] [--path /page] [--note "…"] [--session <id>]
+       bivy app present [view] [--path /page] [--note "…"] [--try a,b] [--session <id>]
+       bivy app scenarios [view] [--session <id>]
        bivy app share [app-id] [--view <view>] [--for 1h|1d|7d] [--view-only] [--session <id>]
        bivy app notes [app-id] [--view <view>] [--since <time>] [--session <id>]
        bivy app run [--name <name>] [--restart-on-change] [--session <id>] -- <command> [args…]
@@ -3157,6 +3171,25 @@ chooses an item — more reliable than clicking, and prints a screenshot after.
 the chat with the app at phone width (and before/after), and it opens the live
 preview. Use it when you finish a visible change, or when the user asks to see
 it. [view] is an app or view name or ID (default: the one opened last).
+--try lists scenarios (by file name) the card offers: each opens the live
+preview in that state.
+"scenarios" lists a view's scenarios and any file that can't be opened, with
+what's wrong. A scenario is a JSON file in .bivy/scenarios/<id>.json: a named
+starting point the user can open, use, and reset from the preview:
+  {"name":"Payment API down","open":"/checkout",
+   "steps":[{"click":"text=Pay"}],
+   "network":[{"match":"POST /api/payments*","status":503,"json":{"error":"down"}}]}
+Optional: "description", "view" (app or view name), "from" (another scenario
+to start from), "fresh": true (start as a new visitor). Steps: {"click":sel},
+{"fill":sel,"with":"text"}, {"press":"Enter"}, {"wait":sel or ms}; sel is a CSS
+selector or text=Visible text. Network rules answer matching requests for that
+viewer only: "status", "json" or "body", "delayMs", or "offline": true.
+Desktop apps restart in a scenario: "args" and "env" are added to the app's
+command, "api": {"env":"API_URL","target":"http://127.0.0.1:4000"} points the
+app at a proxy that applies "network", and steps are {"click":[x,y]},
+{"type":"text"}, {"press":"cmd+s"}, {"menu":"File > Open"}, {"wait":ms}. When
+you finish a visible change, add scenarios for the states it affects (errors,
+empty, slow) and pass them to present --try.
 "share" mints a reusable link to one web view and prints its URL and expiry
 (--for: 1h, 1d or 7d, default 1d; sooner if the user stops sharing in Apps, the
 app is removed or the machine restarts). [app-id] is an app ID or name, --view
@@ -3174,7 +3207,7 @@ Web previews require operator setup; see docs/apps.md.`);
   }
   if (INPUT_ACTIONS[action]) return appInput(action, rest);
   if (action === "menu") return appMenu(rest, { json });
-  if (!["publish", "list", "remove", "shot", "run", "present", "share", "notes"].includes(action)) throw new Error("Unknown app command. Run bivy app --help.");
+  if (!["publish", "list", "remove", "shot", "run", "present", "scenarios", "share", "notes"].includes(action)) throw new Error("Unknown app command. Run bivy app --help.");
   // `run -- <command> [args…]`: publish a one-window desktop app without a manifest file.
   let runManifest;
   if (action === "run") {
@@ -3220,7 +3253,7 @@ Web previews require operator setup; see docs/apps.md.`);
     }
   }
   if (action === "shot" || action === "present") {
-    for (const flag of action === "shot" ? ["--widths", "--themes", "--path"] : ["--path", "--note"]) {
+    for (const flag of action === "shot" ? ["--widths", "--themes", "--path"] : ["--path", "--note", "--try"]) {
       const i = rest.indexOf(flag);
       if (i < 0) continue;
       const value = rest[i + 1];
@@ -3228,6 +3261,7 @@ Web previews require operator setup; see docs/apps.md.`);
       if (flag === "--widths") shot.widths = value.split(",").map((w) => Number(w.trim()));
       else if (flag === "--themes") shot.themes = value.split(",").map((t) => t.trim());
       else if (flag === "--note") shot.note = value;
+      else if (flag === "--try") shot.try = value.split(",").map((id) => id.trim()).filter(Boolean);
       else shot.path = value;
       rest.splice(i, 2);
     }
@@ -3237,10 +3271,10 @@ Web previews require operator setup; see docs/apps.md.`);
   const sessionId = resolveAttachSessionId({ sessionFlag: sessionIndex >= 0 ? rest[sessionIndex + 1] : undefined, env: process.env });
   if (!sessionId) throw new Error("Set --session <id> or run inside a Bivy agent session.");
   const positional = rest.filter((_, i) => i !== sessionIndex && (sessionIndex < 0 || i !== sessionIndex + 1));
-  if (positional.some((a) => a.startsWith("-")) || (action === "shot" || action === "present" || action === "share" || action === "notes" ? positional.length > 1 : positional.length !== (action === "list" || action === "run" ? 0 : 1))) throw new Error("Invalid arguments. Run bivy app --help.");
+  if (positional.some((a) => a.startsWith("-")) || (action === "shot" || action === "present" || action === "scenarios" || action === "share" || action === "notes" ? positional.length > 1 : positional.length !== (action === "list" || action === "run" ? 0 : 1))) throw new Error("Invalid arguments. Run bivy app --help.");
   const body = { sessionId, ...shot };
   if (action === "shot" && positional[0]) body.appId = positional[0];
-  if (action === "present" && positional[0]) body.target = positional[0];
+  if ((action === "present" || action === "scenarios") && positional[0]) body.target = positional[0];
   if ((action === "share" || action === "notes") && positional[0]) body.appId = positional[0];
   if (action === "publish") {
     const file = path.resolve(positional[0]);

package/bin/codex-app-server-shim.mjs

@@ -70,6 +70,10 @@ const itemOutputs = new Map();
 const agentMessageItems = new Set();
 const reasoningItems = new Set();
 const activeObservedItems = new Set();
+// Child thread id -> the card that represents that sub-agent in the parent
+// transcript, so the child's own tool calls nest under it instead of reading
+// as the parent's work.
+const childThreadCards = new Map();
 let pendingTurnCompletion = false;
 let turnCompletionTimer = null;
 
@@ -95,8 +99,31 @@ function paramsItemId(params, fallback) {
   return String(params?.itemId || params?.callId || item?.id || fallback || "");
 }
 
+function rememberChildThreads(item) {
+  if (item.type === "subAgentActivity" && item.agentThreadId) {
+    childThreadCards.set(item.agentThreadId, `subagent-${item.agentThreadId}`);
+  } else if (item.type === "collabAgentToolCall" && item.id) {
+    for (const child of item.receiverThreadIds ?? []) {
+      if (!childThreadCards.has(child)) childThreadCards.set(child, String(item.id));
+    }
+  }
+}
+
+/** True when a notification belongs to a delegated child thread, not ours. */
+function fromChildThread(params) {
+  return Boolean(params?.threadId && threadId && params.threadId !== threadId);
+}
+
+/** `{ parentToolCallId }` for an item a child thread ran, else `{}`. */
+function childParent(params) {
+  if (!fromChildThread(params)) return {};
+  const card = childThreadCards.get(params.threadId) ?? `subagent-${params.threadId}`;
+  return { parentToolCallId: card };
+}
+
 function rememberItem(item) {
   if (!item || typeof item !== "object") return;
+  rememberChildThreads(item);
   const id = item.type === "subAgentActivity" && item.agentThreadId
     ? `subagent-${item.agentThreadId}`
     : String(item.id || "");
@@ -146,18 +173,18 @@ function appendOutput(itemId, delta) {
   return output;
 }
 
-function emitToolUpdate(itemId, name, input) {
+function emitToolUpdate(itemId, name, input, parent = {}) {
   if (!itemId) return;
-  bivy({ type: "tool.update", toolCallId: itemId, name, input });
+  bivy({ type: "tool.update", toolCallId: itemId, name, input, ...parent });
 }
 
 // App-server item/started is observational: approval-capable shell/patch calls
 // were already surfaced by requestApproval, while MCP, dynamic, and collaboration
 // items may already be running. `tool.observe` gives all of them a live,
 // persisted card without asking the user to approve work that has already begun.
-function emitToolObserved(itemId, name, input) {
+function emitToolObserved(itemId, name, input, parent = {}) {
   if (!itemId) return;
-  bivy({ type: "tool.observe", toolCallId: itemId, name, input });
+  bivy({ type: "tool.observe", toolCallId: itemId, name, input, ...parent });
 }
 
 // `turn/plan/updated` (the update_plan tool) carries the whole plan with a
@@ -214,11 +241,12 @@ function handleCompletedItem(params) {
   rememberItem(item);
   const itemId = paramsItemId(params);
   if (!item || typeof item !== "object" || !itemId) return;
+  const parent = childParent(params);
   switch (item.type) {
     case "agentMessage":
       // Child-thread prose belongs to the delegated agent, not the parent's
       // answer stream. Its lifecycle is represented by the collaboration items.
-      if (params?.threadId && threadId && params.threadId !== threadId) return;
+      if (fromChildThread(params)) return;
       if (!agentMessageItems.has(itemId) && item.text) {
         agentMessageItems.add(itemId);
         bivy({ type: "message.delta", text: String(item.text) });
@@ -240,7 +268,7 @@ function handleCompletedItem(params) {
     case "commandExecution": {
       const output = text(item.aggregatedOutput ?? itemOutputs.get(itemId));
       if (output) itemOutputs.set(itemId, output.slice(-4000));
-      emitToolUpdate(itemId, "shell", updateInput(itemId, { output }));
+      emitToolUpdate(itemId, "shell", updateInput(itemId, { output }), parent);
       const exitCode = typeof item.exitCode === "number" ? item.exitCode : undefined;
       bivy({
         type: "tool.result",
@@ -248,36 +276,37 @@ function handleCompletedItem(params) {
         name: "shell",
         result: { content: output || text(item.status || "completed"), ...(exitCode === undefined ? {} : { exitCode }) },
         isError: (exitCode !== undefined && exitCode !== 0) || item.status === "failed",
+        ...parent,
       });
       return;
     }
     case "fileChange": {
       const status = text(item.status || "completed");
       itemInputs.set(itemId, updateInput(itemId, { changes: item.changes ?? [], status }));
-      emitToolUpdate(itemId, "apply_patch", updateInput(itemId));
-      bivy({ type: "tool.result", toolCallId: itemId, name: "apply_patch", result: status, isError: status === "failed" });
+      emitToolUpdate(itemId, "apply_patch", updateInput(itemId), parent);
+      bivy({ type: "tool.result", toolCallId: itemId, name: "apply_patch", result: status, isError: status === "failed", ...parent });
       return;
     }
     case "mcpToolCall": {
       const name = text(item.tool || "mcp");
       const result = text(item.result ?? item.error ?? "");
-      bivy({ type: "tool.result", toolCallId: itemId, name, result, isError: Boolean(item.error) || item.status === "failed" });
+      bivy({ type: "tool.result", toolCallId: itemId, name, result, isError: Boolean(item.error) || item.status === "failed", ...parent });
       return;
     }
     case "dynamicToolCall": {
       const name = text(item.tool || "tool");
       const result = text(item.contentItems ?? item.result ?? item.status ?? "completed");
-      bivy({ type: "tool.result", toolCallId: itemId, name, result, isError: item.success === false || item.status === "failed" });
+      bivy({ type: "tool.result", toolCallId: itemId, name, result, isError: item.success === false || item.status === "failed", ...parent });
       return;
     }
     case "collabAgentToolCall": {
       const result = text(item.status || "completed");
-      bivy({ type: "tool.result", toolCallId: itemId, name: "spawn_agent", result, isError: item.status === "failed" });
+      bivy({ type: "tool.result", toolCallId: itemId, name: "spawn_agent", result, isError: item.status === "failed", ...parent });
       return;
     }
     case "subAgentActivity": {
       const result = text(item.kind || "completed");
-      bivy({ type: "tool.result", toolCallId: itemId, name: "subagent_activity", result, isError: item.kind === "interrupted" });
+      bivy({ type: "tool.result", toolCallId: itemId, name: "subagent_activity", result, isError: item.kind === "interrupted", ...parent });
       return;
     }
     default:
@@ -356,7 +385,8 @@ function onNotification(m) {
   // both token streams together produces character-level corruption whenever a
   // delegated agent answers concurrently. Child lifecycle remains visible via
   // collabAgentToolCall/subAgentActivity; only prose/reasoning is scoped here.
-  const fromCurrentThread = !params?.threadId || !threadId || params.threadId === threadId;
+  const fromCurrentThread = !fromChildThread(params);
+  const parent = childParent(params);
   switch (method) {
     case "item/agentMessage/delta": {
       const itemId = paramsItemId(params);
@@ -384,19 +414,19 @@ function onNotification(m) {
     case "item/commandExecution/outputDelta": {
       const itemId = paramsItemId(params);
       const output = appendOutput(itemId, params.delta);
-      emitToolUpdate(itemId, "shell", updateInput(itemId, { output }));
+      emitToolUpdate(itemId, "shell", updateInput(itemId, { output }), parent);
       return;
     }
     case "item/fileChange/outputDelta": {
       const itemId = paramsItemId(params);
       const output = appendOutput(itemId, params.delta);
-      emitToolUpdate(itemId, "apply_patch", updateInput(itemId, { output }));
+      emitToolUpdate(itemId, "apply_patch", updateInput(itemId, { output }), parent);
       return;
     }
     case "item/fileChange/patchUpdated": {
       const itemId = paramsItemId(params);
       itemInputs.set(itemId, updateInput(itemId, { changes: params.changes ?? [] }));
-      emitToolUpdate(itemId, "apply_patch", updateInput(itemId));
+      emitToolUpdate(itemId, "apply_patch", updateInput(itemId), parent);
       return;
     }
     case "item/started": {
@@ -404,12 +434,12 @@ function onNotification(m) {
       rememberItem(item);
       const itemId = paramsItemId(params);
       if (["commandExecution", "fileChange", "mcpToolCall", "dynamicToolCall", "collabAgentToolCall", "subAgentActivity"].includes(item?.type) && itemId) activeObservedItems.add(itemId);
-      if (item?.type === "commandExecution") emitToolObserved(itemId, "shell", updateInput(itemId));
-      if (item?.type === "fileChange") emitToolObserved(itemId, "apply_patch", updateInput(itemId));
-      if (item?.type === "mcpToolCall") emitToolObserved(itemId, text(item.tool || "mcp"), updateInput(itemId));
-      if (item?.type === "dynamicToolCall") emitToolObserved(itemId, text(item.tool || "tool"), updateInput(itemId));
-      if (item?.type === "collabAgentToolCall") emitToolObserved(itemId, "spawn_agent", updateInput(itemId));
-      if (item?.type === "subAgentActivity") emitToolObserved(itemId, "subagent_activity", updateInput(itemId));
+      if (item?.type === "commandExecution") emitToolObserved(itemId, "shell", updateInput(itemId), parent);
+      if (item?.type === "fileChange") emitToolObserved(itemId, "apply_patch", updateInput(itemId), parent);
+      if (item?.type === "mcpToolCall") emitToolObserved(itemId, text(item.tool || "mcp"), updateInput(itemId), parent);
+      if (item?.type === "dynamicToolCall") emitToolObserved(itemId, text(item.tool || "tool"), updateInput(itemId), parent);
+      if (item?.type === "collabAgentToolCall") emitToolObserved(itemId, "spawn_agent", updateInput(itemId), parent);
+      if (item?.type === "subAgentActivity") emitToolObserved(itemId, "subagent_activity", updateInput(itemId), parent);
       return;
     }
     case "item/completed": {
@@ -419,15 +449,20 @@ function onNotification(m) {
       return;
     }
     case "thread/tokenUsage/updated":
-      if (params?.tokenUsage) bivy({ type: "usage", usage: params.tokenUsage.last ?? params.tokenUsage.total ?? params.tokenUsage });
+      if (fromCurrentThread && params?.tokenUsage) bivy({ type: "usage", usage: params.tokenUsage.last ?? params.tokenUsage.total ?? params.tokenUsage });
       return;
     case "rawResponse/completed":
       if (params?.usage) bivy({ type: "usage", usage: params.usage });
       return;
+    // A delegated child runs its own turns on the same connection. Only the
+    // parent thread's turn lifecycle opens and seals the Bivy turn: sealing on
+    // a child's turn/completed ended the parent turn early and the parent's
+    // remaining tools and answer landed after it was closed.
     case "turn/started":
-      bivy({ type: "session.status", status: "working" });
+      if (fromCurrentThread) bivy({ type: "session.status", status: "working" });
       return;
     case "turn/completed": {
+      if (!fromCurrentThread) return;
       // The completion event is authoritative about a terminal failure: a turn
       // that hit a usage limit (or any provider error) arrives here as
       // `status: "failed"` carrying `turn.error`. Capture it directly instead of
@@ -448,6 +483,7 @@ function onNotification(m) {
       return;
     }
     case "turn/failed": {
+      if (!fromCurrentThread) return;
       // A failed turn is TERMINAL in the app-server — no `turn/completed` follows
       // it — so end the turn here rather than merely stashing the error for a
       // completion event that never arrives. Stashing (the old behavior) left the
@@ -470,7 +506,9 @@ function onNotification(m) {
       // A non-turn-scoped error notification (e.g. transient reconnect noise, per
       // the codex exec parser's read of this event). Stash it so a following
       // turn/completed surfaces it; a genuinely turn-ending failure arrives as
-      // turn/failed above, which never leaves the turn open.
+      // turn/failed above, which never leaves the turn open. A child thread's
+      // error is reported on its sub-agent card, not as the parent's failure.
+      if (!fromCurrentThread) return;
       sawError = params?.error?.message || params?.message || "Codex turn failed";
       return;
     default:
@@ -485,6 +523,19 @@ async function ensureInitialized() {
   initialized = true;
 }
 
+// Codex keeps one writer per thread. A thread still open in Codex elsewhere
+// (its TUI, or the shared background app-server Codex 0.160 runs for it) can't
+// be resumed here; say what to do instead of passing the bare error through.
+async function resumeThread(params) {
+  try {
+    return await asRequest("thread/resume", params);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (!/active writer/i.test(message)) throw error;
+    throw new Error(`${message}. The thread is still open in Codex outside Bivy: close it there, or stop Codex's background server with \`codex app-server daemon stop\`, then try again.`);
+  }
+}
+
 function threadParams(msg, extra = {}) {
   return {
     cwd: msg.workspace || process.cwd(),
@@ -511,7 +562,7 @@ async function onBivyCommand(msg) {
         // field on session.create. New hosts use the explicit session.resume
         // primitive below.
         if (typeof msg.resume === "string" && msg.resume) {
-          const resumed = await asRequest("thread/resume", threadParams(msg, { threadId: msg.resume }));
+          const resumed = await resumeThread(threadParams(msg, { threadId: msg.resume }));
           threadId = resumed?.thread?.id ?? resumed?.threadId ?? msg.resume;
           bivy({ replyTo: id, ok: true, runtimeSessionRef: threadId });
           return;
@@ -525,7 +576,7 @@ async function onBivyCommand(msg) {
         await ensureInitialized();
         const resumeRef = String(msg.runtimeSessionRef || msg.resumeRef || msg.sessionId || "");
         if (!resumeRef) { bivy({ replyTo: id, ok: false, error: "missing resume ref" }); return; }
-        const resumed = await asRequest("thread/resume", threadParams(msg, { threadId: resumeRef }));
+        const resumed = await resumeThread(threadParams(msg, { threadId: resumeRef }));
         threadId = resumed?.thread?.id ?? resumed?.threadId ?? resumeRef;
         bivy({ replyTo: id, ok: true, runtimeSessionRef: threadId });
         return;

package/dist/agent-instructions.js

@@ -36,7 +36,8 @@ export const BIVY_AGENT_NOTE = [
         "![](path) does not render a local path. A REMOTE `https://` image in markdown does render.",
     "- Something with a UI: `bivy app publish <manifest.json>` (a web server's port, a static build, a terminal) or " +
         "`bivy app run -- <command>` (a desktop app) gives the user a live preview; `bivy app shot` screenshots it so you " +
-        "can check your work; `bivy app present` tells the user a visible change is ready to look at. " +
+        "can check your work; `bivy app present` tells the user a visible change is ready to look at, and " +
+        "`.bivy/scenarios/*.json` files let them open it in the states that matter (errors, empty, slow) with `--try`. " +
         "`bivy app --help` has the details.",
     "- Proposing tasks the user could hand you (next steps, ideas, options): post each with " +
         '`bivy suggest "<complete instruction>" [--title "short label"] [--run here|subagents|new]` instead of only ' +

package/dist/agents/claude-code/runtime.js

@@ -548,7 +548,8 @@ function loadClaudeTranscript(sessionId) {
             }
             if (role === "user" && !(Array.isArray(content) && content.some((block) => block?.type === "tool_result")))
                 lastPrompt = content;
-            messages.push({ role, content, timestamp: new Date(entry?.timestamp ?? entry?.createdAt ?? Date.now()).getTime() });
+            const model = role === "assistant" && typeof entry?.message?.model === "string" && entry.message.model !== "<synthetic>" ? entry.message.model : undefined;
+            messages.push({ role, content, timestamp: new Date(entry?.timestamp ?? entry?.createdAt ?? Date.now()).getTime(), ...(model ? { model } : {}) });
             lastErrorIdx = entry?.isApiErrorMessage === true ? messages.length - 1 : -1;
         }
     }

package/dist/agents/profiles.js

@@ -32,7 +32,7 @@ export const AGENT_PROFILES = {
     },
     opencode: {
         displayName: "OpenCode",
-        behaviors: { preflight: "opencode", slashCommands: "opencode", sessionStore: "opencode" },
+        behaviors: { preflight: "opencode", prepare: "opencode-auth", slashCommands: "opencode", sessionStore: "opencode" },
         command: "opencode",
         packageName: "opencode-ai",
         // `opencode run "<prompt>"` runs one non-interactive turn and streams the
@@ -44,6 +44,9 @@ export const AGENT_PROFILES = {
         // Claude Code, and Codex clear. See `acp` below for the version fallback.
         supportTier: "supported",
         testedVersion: "1.18.33",
+        // Mixed: OpenCode keeps its own logins, and Bivy adds what it holds — API
+        // keys as env vars, a connected ChatGPT plan via the opencode-auth prepare.
+        authOwner: "mixed",
         blurb: "The most widely used open-source coding harness (OpenCode CLI).",
         // `opencode run -s <id> "<prompt>"` continues a prior session by its own id
         // (`-s, --session  session id to continue`, per `opencode run --help`).
@@ -403,12 +406,12 @@ export const AGENT_PROFILES = {
         model: {
             flag: "-m",
             models: [
-                // Official Grok CLI (1.x) advertises grok-4.6 as the default subscription
-                // model (verified against the authenticated `~/.grok/models_cache.json`,
-                // origin cli-chat-proxy.grok.com/v1/models); the older grok-4.5 /
-                // grok-4-latest / grok-code-fast-1 ids now return "unknown model id".
+                // Official Grok CLI (1.0.46) lists grok-4.7 as the default subscription
+                // model (`grok models`), with its faster build variant and grok-4.6.
                 // Keep the list honest; operators can override with BIVY_GROK_MODELS if
-                // their install exposes more.
+                // their install exposes more. The governed ACP path reads the live list.
+                { id: "grok-4.7", name: "Grok 4.7", provider: "xai" },
+                { id: "grok-4.7-build-fast", name: "Grok 4.7 Build Fast", provider: "xai" },
                 { id: "grok-4.6", name: "Grok 4.6", provider: "xai" },
             ],
         },

package/dist/apps/gateway.js

@@ -14,6 +14,8 @@ import { pressMenu, readMenuPath, readMenus } from "./menu.js";
 import { inspectorScript } from "./inspector.js";
 import { readStrokes, readElementScrolls } from "./annotate.js";
 import { contentType } from "./mime.js";
+import { loadScenarios, matchRule, planScenario, scenariosFor, summarize } from "./scenarios.js";
+import { simulate } from "./scenario-proxy.js";
 const COOKIE = "__Host-bivy-preview";
 const OPEN_PATH = "/__bivy/open";
 const REDEEM_PATH = "/__bivy/redeem";
@@ -21,6 +23,9 @@ const REVISION_PATH = "/__bivy/revision";
 const INSPECTOR_PATH = "/__bivy/inspector.js";
 const COMPARE_PATH = "/__bivy/compare";
 const NOTES_PATH = "/__bivy/notes";
+const SCENARIOS_PATH = "/__bivy/scenarios";
+const SCENARIO_PATH = "/__bivy/scenario";
+const scenarioKind = (entry) => entry.target.kind === "display" ? "desktop" : "web";
 /** Larger HTML documents pass through without the inspector. */
 const MAX_INJECT_BYTES = 5 * 1024 * 1024;
 /** Put the inspector first in <head>, so it sees errors from the app's own scripts. */
@@ -205,9 +210,6 @@ export class AppGateway {
         ["/__bivy/tokens.css", readFileSync(new URL("./tokens.css", import.meta.url))],
         ["/__bivy/styles.css", readFileSync(new URL("./styles.css", import.meta.url))],
     ]);
-    /** `reviewer`: the browser session came from a copied (shared) link.
-     *  `viewOnly`: that link came without the reviewer tools.
-     *  `embedded`: it runs framed inside a Bivy client (a third-party frame). */
     sessions = new Map();
     sockets = new Map();
     /** Connections opened by people with a copied link, so Stop sharing can end
@@ -486,6 +488,11 @@ fetch('${REDEEM_PATH}',{method:'POST',headers:{'Content-Type':'text/plain'},body
             res.end("Preview access expired. Open a new preview link from Bivy.");
             return;
         }
+        // The shell (its own origin) chooses this browser's scenario; nothing else may.
+        if (req.url === SCENARIO_PATH && req.method === "POST") {
+            await this.enterScenario(req, res, entry, session);
+            return;
+        }
         // Block cross-site mutations even if a client sends the preview cookie.
         if (!["GET", "HEAD"].includes(req.method ?? "") && req.headers.origin !== this.origin(id)) {
             res.writeHead(403);
@@ -511,6 +518,10 @@ fetch('${REDEEM_PATH}',{method:'POST',headers:{'Content-Type':'text/plain'},body
             this.compare(req, res, entry);
             return;
         }
+        if (req.url === SCENARIOS_PATH && req.method === "GET") {
+            this.scenarios(res, entry, session);
+            return;
+        }
         if (req.url === INSPECTOR_PATH && req.method === "GET") {
             res.writeHead(200, { "content-type": "text/javascript; charset=utf-8", "cache-control": "no-store" });
             res.end(inspectorScript(this.shellOrigin(id), session.reviewer === true && !session.viewOnly, session.embedded === true));
@@ -530,6 +541,9 @@ fetch('${REDEEM_PATH}',{method:'POST',headers:{'Content-Type':'text/plain'},body
             await this.display(req, res, entry);
             return;
         }
+        const rule = session.scenario && matchRule(session.scenario.network, req.method, req.url);
+        if (rule && await simulate(req, res, rule, responseHeaders({}, this.ancestors(id))))
+            return;
         const inspect = isPageLoad(req);
         // Remember the framed page so a turn reload lands where the user was.
         if (req.method === "GET" && req.headers["sec-fetch-dest"] === "iframe" && req.url.length <= 2048)
@@ -871,6 +885,80 @@ fetch('${REDEEM_PATH}',{method:'POST',headers:{'Content-Type':'text/plain'},body
         res.writeHead(200, { "content-type": "application/json" });
         res.end(JSON.stringify({ screenshot: Boolean(shot) }));
     }
+    /** The view's scenarios for the shell's switcher, and the one it's in: this
+     *  browser's for a web page, the app's for a desktop app. */
+    scenarios(res, entry, session) {
+        const { scenarios, problems } = loadScenarios(entry.workspace);
+        const kind = scenarioKind(entry);
+        const own = scenariosFor(scenarios, entry.app.name, entry.view.name, kind);
+        const active = kind === "desktop" ? entry.scenario : session.scenario;
+        res.writeHead(200, { "access-control-allow-origin": this.shellOrigin(entry.view.id), "access-control-allow-credentials": "true", vary: "Origin", "content-type": "application/json" });
+        res.end(JSON.stringify({ kind, scenarios: summarize(own, problems, entry.app.createdAt, kind), active: active ? { id: active.id, name: active.name, ...(active.simulated ? { simulated: active.simulated } : {}) } : null }));
+    }
+    /** Puts this browser in a scenario (or back in none, for an empty body) and
+     *  returns the plan the shell walks through: pages to open and steps to take.
+     *  A "fresh" scenario also expires the app's cookies this browser sent, so it
+     *  starts as a new visitor. Only the shell's origin may ask. */
+    async enterScenario(req, res, entry, session) {
+        const shell = this.shellOrigin(entry.view.id);
+        const cors = { "access-control-allow-origin": shell, "access-control-allow-credentials": "true", vary: "Origin" };
+        if (req.headers.origin !== shell) {
+            res.writeHead(403);
+            res.end();
+            return;
+        }
+        let body = "";
+        for await (const chunk of req) {
+            body += chunk.toString();
+            if (body.length > 64) {
+                res.writeHead(413, cors);
+                res.end();
+                return;
+            }
+        }
+        const id = body.trim();
+        const json = (status, value) => { res.writeHead(status, { ...cors, "content-type": "application/json" }); res.end(JSON.stringify(value)); };
+        // A desktop app is one program for everyone watching it: its scenario
+        // restarts it, and the steps run in its window before this answers.
+        if (scenarioKind(entry) === "desktop") {
+            if (!this.registry.desktopScenario) {
+                json(400, { error: "Desktop scenarios aren't available on this machine." });
+                return;
+            }
+            try {
+                json(200, await this.registry.desktopScenario(entry.view.id, id));
+            }
+            catch (error) {
+                json(400, { error: error.message });
+            }
+            return;
+        }
+        if (!id) {
+            session.scenario = undefined;
+            res.writeHead(200, { ...cors, "content-type": "application/json" });
+            res.end(JSON.stringify({ plan: null }));
+            return;
+        }
+        let plan;
+        try {
+            const own = scenariosFor(loadScenarios(entry.workspace).scenarios, entry.app.name, entry.view.name, "web");
+            plan = planScenario(own, id, "web");
+        }
+        catch (error) {
+            res.writeHead(400, { ...cors, "content-type": "application/json" });
+            res.end(JSON.stringify({ error: error.message }));
+            return;
+        }
+        session.scenario = plan;
+        const headers = { ...cors, "content-type": "application/json" };
+        if (plan.fresh) {
+            const names = (req.headers.cookie ?? "").split(";").map((part) => part.split("=", 1)[0].trim()).filter((name) => name && name !== COOKIE && /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/.test(name));
+            const expire = (name) => `${name}=; Path=/; Max-Age=0`;
+            headers["set-cookie"] = names.map((name) => session.embedded ? partitionCookie(expire(name)) : expire(name));
+        }
+        res.writeHead(200, headers);
+        res.end(JSON.stringify({ plan }));
+    }
     /** Compare shots for the shell: the list, or one PNG by index. */
     compare(req, res, entry) {
         const shots = entry.shots ?? [];

package/dist/apps/inspector.js

@@ -128,10 +128,65 @@ const marked=r=>{
     text:(el.innerText||el.getAttribute('aria-label')||el.getAttribute('alt')||'').trim().replace(/\\s+/g,' ').slice(0,120),
     rect:{x:Math.round(b.left+scrollX),y:Math.round(b.top+scrollY),width:Math.round(b.width),height:Math.round(b.height)}};});
 };
+// Scenarios: the shell walks a scenario's steps here, one at a time, the way a
+// person would (find it, scroll to it, use it), and hears back after each one.
+// A step that leaves the page ends this run; the shell picks up after it on the
+// next page. "load" ties each answer to the page load it came from.
+let leaving=false;
+addEventListener('pagehide',()=>{leaving=true;});addEventListener('beforeunload',()=>{leaving=true;});
+const sleep=ms=>new Promise(r=>setTimeout(r,ms));
+const shown=el=>Boolean(el&&el.getClientRects().length);
+const words=el=>(el.innerText||el.value||el.getAttribute('aria-label')||'').trim().replace(/\\s+/g,' ').toLowerCase();
+const find=q=>{
+  if(typeof q!=='string')return null;
+  if(q.startsWith('text=')){
+    const want=q.slice(5).trim().toLowerCase();
+    const all=[...document.querySelectorAll('a,button,[role=button],[role=link],[role=tab],[role=menuitem],[role=option],label,summary,input[type=submit],input[type=button]')].filter(shown);
+    return all.find(el=>words(el)===want)||all.find(el=>words(el).includes(want))||null;
+  }
+  try{const el=document.querySelector(q);return shown(el)?el:null;}catch{throw Error('“'+q+'” isn’t a valid selector');}
+};
+const waitFor=async q=>{for(let t=0;t<50&&!leaving;t++){const el=find(q);if(el)return el;await sleep(100);}return null;};
+const missing=q=>Error('Couldn’t find “'+q+'” within 5 seconds');
+const STEPS={
+  click:async s=>{const el=await waitFor(s.click);if(!el)throw missing(s.click);el.scrollIntoView({block:'center'});el.click();},
+  fill:async s=>{
+    const el=await waitFor(s.fill);if(!el)throw missing(s.fill);
+    const proto=el.localName==='textarea'?HTMLTextAreaElement.prototype:el.localName==='select'?HTMLSelectElement.prototype:HTMLInputElement.prototype;
+    const set=Object.getOwnPropertyDescriptor(proto,'value')?.set;if(!set)throw Error('“'+s.fill+'” isn’t a field');
+    el.scrollIntoView({block:'center'});el.focus();set.call(el,String(s.with));
+    el.dispatchEvent(new Event('input',{bubbles:true}));el.dispatchEvent(new Event('change',{bubbles:true}));
+  },
+  press:async s=>{
+    const el=document.activeElement||document.body,key=String(s.press),o={key,bubbles:true,cancelable:true};
+    const go=el.dispatchEvent(new KeyboardEvent('keydown',o));el.dispatchEvent(new KeyboardEvent('keyup',o));
+    if(go&&key==='Enter'&&el.form)el.form.requestSubmit();
+  },
+  wait:async s=>{if(typeof s.wait==='number')await sleep(Math.min(10000,Math.max(0,s.wait)));else if(!await waitFor(s.wait))throw missing(s.wait);},
+};
+async function runSteps(d){
+  const steps=Array.isArray(d.steps)?d.steps.slice(0,50):[],run=d.run,load=d.load;
+  for(let i=Math.max(0,Number(d.from)||0);i<steps.length;i++){
+    const step=steps[i]||{},kind=Object.keys(STEPS).find(k=>k in step);
+    try{if(!kind)throw Error('Unknown step');await STEPS[kind](step);}
+    catch(error){if(!leaving)post({type:'step',run,load,i,error:String(error?.message||error).slice(0,300)});return;}
+    post({type:'step',run,load,i,ok:true});
+    await sleep(250);if(leaving)return;
+  }
+  post({type:'steps-done',run,load});
+}
+// A fresh start: what this page keeps in the browser goes (the gateway expires
+// the cookies the server can see).
+const forget=()=>{
+  try{localStorage.clear();sessionStorage.clear();}catch{}
+  for(const c of document.cookie.split(';')){const name=c.split('=')[0].trim();if(name)document.cookie=name+'=; Max-Age=0; Path=/';}
+};
 addEventListener('message',e=>{
   if(!framed||e.origin!==SHELL||e.source!==parent)return;
   const d=e.data||{},n=v=>Number.isFinite(+v)?+v:0;
-  if(d.type==='bivy:note'&&REVIEWER){
+  if(d.type==='bivy:steps')void runSteps(d);
+  else if(d.type==='bivy:forget'){forget();post({type:'forgot'});}
+  else if(d.type==='bivy:note'&&REVIEWER){
     void fetch('/__bivy/notes',{method:'POST',headers:{'content-type':'application/json'},body:JSON.stringify(d.note)})
       .then(async r=>{if(!r.ok)throw Error(r.status===429?'Please wait a moment before sending another picture.':r.status===400||r.status===502?(await r.text()).slice(0,200):'Could not send. Check that the link is still valid and try again.');return r.json();})
       .then(result=>post({type:'note-sent',id:d.id,screenshot:result.screenshot===true}),error=>post({type:'note-sent',id:d.id,error:error.message}));