@avasapp/agent-bridge 0.1.0 → 0.3.0

package/dist/runtime/index.cjs

@@ -22,6 +22,7 @@ var runtime_exports = {};
 __export(runtime_exports, {
   RUNTIME_MARKER: () => RUNTIME_MARKER,
   cdpTransport: () => cdpTransport,
+  createGate: () => createGate,
   settle: () => settle,
   startAgentBridge: () => startAgentBridge,
   useAgentBridge: () => useAgentBridge
@@ -73,14 +74,15 @@ function logTools(logs) {
 // src/runtime/tools/restore.ts
 var SUFFIX = ".restore";
 var SELF = "bridge.restore";
+var LAST = "scenario.restore";
 function restoreTools(getTools) {
   return {
     [SELF]: {
-      description: "Undo what the agent changed: runs every *.restore tool in name order and returns each result or error.",
+      description: "Undo what the agent changed: runs every *.restore tool in name order, scenario.restore last, and returns each result or error.",
       run: async () => {
         const tools = getTools();
         const results = {};
-        const names = Object.keys(tools).filter((name) => name.endsWith(SUFFIX) && name !== SELF).sort();
+        const names = Object.keys(tools).filter((name) => name.endsWith(SUFFIX) && name !== SELF).sort((a, b) => Number(a === LAST) - Number(b === LAST) || a.localeCompare(b));
         for (const name of names) {
           const definition = tools[name];
           const run = typeof definition === "function" ? definition : definition.run;
@@ -98,6 +100,159 @@ function restoreTools(getTools) {
   };
 }
 
+// src/runtime/options-schema.ts
+var import_json_schema = require("@cfworker/json-schema");
+var isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+var CASCADE = /* @__PURE__ */ new Set([
+  "properties",
+  "patternProperties",
+  "additionalProperties",
+  "unevaluatedProperties",
+  "items",
+  "prefixItems",
+  "unevaluatedItems",
+  "allOf",
+  "if",
+  "then",
+  "else",
+  "dependentSchemas",
+  "$ref",
+  "false"
+]);
+var path = (instanceLocation) => instanceLocation === "#" ? "options" : `options${instanceLocation.slice(1)}`;
+function unknownKeys(schema, value, at, out) {
+  if (!isObject(schema)) return;
+  if (Array.isArray(value)) {
+    if (isObject(schema.items))
+      value.forEach((item, i) => unknownKeys(schema.items, item, `${at}/${i}`, out));
+    return;
+  }
+  if (!isObject(value) || !isObject(schema.properties)) return;
+  const props = schema.properties;
+  const open = schema.additionalProperties !== void 0 && schema.additionalProperties !== false || schema.patternProperties !== void 0 || // Composed schemas split their properties across branches; leave them to the validator.
+  ["allOf", "anyOf", "oneOf", "$ref"].some((k) => schema[k] !== void 0);
+  for (const [key, child] of Object.entries(value)) {
+    if (key in props) unknownKeys(props[key], child, `${at}/${key}`, out);
+    else if (!open)
+      out.push(`${path(at)}: unknown option "${key}". Known: ${Object.keys(props).join(", ") || "none"}`);
+  }
+}
+var validators = /* @__PURE__ */ new WeakMap();
+function checkOptions(schema, options) {
+  let validator = validators.get(schema);
+  if (!validator) {
+    validator = new import_json_schema.Validator(schema, "2020-12", false);
+    validators.set(schema, validator);
+  }
+  const value = options === void 0 ? {} : options;
+  const problems = [];
+  unknownKeys(schema, value, "#", problems);
+  const result = validator.validate(value);
+  if (!result.valid) {
+    const leaves = result.errors.filter(
+      (e) => !CASCADE.has(e.keyword) && !/\/(anyOf|oneOf)\/\d/.test(e.keywordLocation)
+    );
+    const shown = leaves.length || problems.length ? leaves : result.errors;
+    for (const e of shown) problems.push(`${path(e.instanceLocation)}: ${e.error}`);
+  }
+  return [...new Set(problems)];
+}
+
+// src/runtime/tools/scenario.ts
+var active = /* @__PURE__ */ new Map();
+var message = (error) => error instanceof Error ? error.message : String(error);
+async function runUndos(entry) {
+  const errors = [];
+  for (const undo2 of entry.undos.splice(0).reverse()) {
+    try {
+      await undo2();
+    } catch (error) {
+      errors.push(message(error));
+    }
+  }
+  return errors;
+}
+async function undo(name) {
+  const entry = active.get(name);
+  if (!entry) return [];
+  active.delete(name);
+  return (await runUndos(entry)).map((e) => `${name}: ${e}`);
+}
+function scenarioTools(getScenarios, getTools) {
+  const find = (name) => {
+    const scenarios = getScenarios();
+    const scenario = scenarios[name];
+    if (!scenario)
+      throw new Error(
+        `Unknown scenario "${name}". Known: ${Object.keys(scenarios).join(", ") || "none"}`
+      );
+    return scenario;
+  };
+  const call = async (tool, ...args) => {
+    const definition = getTools()[tool];
+    if (!definition) throw new Error(`Unknown tool "${tool}"`);
+    const run = typeof definition === "function" ? definition : definition.run;
+    return run(...args);
+  };
+  return {
+    "scenario.list": {
+      description: "Setups the app defines, e.g. a signed-in user: name, description, options (a JSON Schema), active.",
+      run: () => Object.entries(getScenarios()).map(([name, s]) => ({
+        name,
+        description: s.description,
+        options: s.options,
+        active: active.has(name)
+      })).sort((a, b) => a.name.localeCompare(b.name))
+    },
+    "scenario.apply": {
+      description: "Apply a scenario: [name, options?]. Options must fit its schema (scenario.list). Returns what it returns. Applying an active one undoes it first. bridge.restore undoes it.",
+      run: async (name, options) => {
+        const scenario = find(name);
+        if (scenario.options) {
+          const problems = checkOptions(scenario.options, options);
+          if (problems.length)
+            throw new Error(
+              `Scenario "${name}" got bad options, nothing was applied:
+- ${problems.join("\n- ")}
+scenario.list shows its options schema.`
+            );
+        }
+        const previous = await undo(name);
+        if (previous.length)
+          throw new Error(`Undoing the active "${name}" failed: ${previous.join("; ")}`);
+        const entry = { options, undos: [] };
+        active.set(name, entry);
+        const context = {
+          options,
+          call,
+          onUndo: (fn) => {
+            if (typeof fn !== "function")
+              throw new Error("onUndo takes a function");
+            entry.undos.push(fn);
+          }
+        };
+        try {
+          return await scenario.apply(context);
+        } catch (error) {
+          const errors = await undo(name);
+          const extra = errors.length ? ` (undo: ${errors.join("; ")})` : "";
+          throw new Error(`Scenario "${name}" failed: ${message(error)}${extra}`);
+        }
+      }
+    },
+    "scenario.restore": {
+      description: "Undo every active scenario, newest first. bridge.restore runs this after every other restorer.",
+      run: async () => {
+        const names = [...active.keys()].reverse();
+        const errors = [];
+        for (const name of names) errors.push(...await undo(name));
+        if (errors.length) throw new Error(errors.join("; "));
+        return names;
+      }
+    }
+  };
+}
+
 // src/runtime/tools/screen.ts
 var import_react_native = require("react-native");
 
@@ -639,12 +794,14 @@ function screenTools() {
 }
 
 // src/runtime/builtin-tools.ts
-function builtinTools(listTools, getTools, logs) {
+function builtinTools(listTools, getTools, logs, getScenarios) {
   return {
     ...bridgeTools(listTools),
     ...logTools(logs),
     ...restoreTools(getTools),
-    ...screenTools()
+    ...screenTools(),
+    // Only when the app defines scenarios, so `tools` doesn't list empty ones.
+    ...getScenarios && scenarioTools(getScenarios, getTools)
   };
 }
 
@@ -673,6 +830,38 @@ function cdpTransport() {
   };
 }
 
+// src/runtime/gate.ts
+function createGate(name) {
+  let holds = 0;
+  const listeners = /* @__PURE__ */ new Set();
+  const notify = () => {
+    for (const fn of [...listeners]) fn(holds > 0);
+  };
+  return {
+    name,
+    get closed() {
+      return holds > 0;
+    },
+    close: () => {
+      let released = false;
+      holds += 1;
+      if (holds === 1) notify();
+      return () => {
+        if (released) return;
+        released = true;
+        holds -= 1;
+        if (holds === 0) notify();
+      };
+    },
+    subscribe: (fn) => {
+      listeners.add(fn);
+      return () => {
+        listeners.delete(fn);
+      };
+    }
+  };
+}
+
 // src/runtime/logs.ts
 var CAPACITY = 200;
 var STACK_LINES = 10;
@@ -735,9 +924,9 @@ function formatArgs(args) {
   }
   parts.push(...rest.map(describe2));
   const error = args.find((a) => a instanceof Error);
-  const message = parts.join(" ");
+  const message2 = parts.join(" ");
   return {
-    message: message.length > MESSAGE_CHARS ? `${message.slice(0, MESSAGE_CHARS)}...` : message,
+    message: message2.length > MESSAGE_CHARS ? `${message2.slice(0, MESSAGE_CHARS)}...` : message2,
     ...error?.stack ? { stack: trimStack(error.stack) } : {}
   };
 }
@@ -756,9 +945,9 @@ function describe2(value) {
 var trimStack = (stack) => stack.split("\n").slice(0, STACK_LINES).join("\n");
 function installLogHooks(capture, env) {
   let quiet = 0;
-  let active = true;
+  let active2 = true;
   const record = (level, args) => {
-    if (!active || quiet) return;
+    if (!active2 || quiet) return;
     quiet++;
     try {
       capture.record(level, args);
@@ -801,7 +990,7 @@ function installLogHooks(capture, env) {
     env.addEventListener?.("unhandledrejection", onRejection);
   }
   return () => {
-    active = false;
+    active2 = false;
     if (console.error === wrappers.error) console.error = originals.error;
     if (console.warn === wrappers.warn) console.warn = originals.warn;
     if (errorUtils && originalHandler && errorUtils.getGlobalHandler() === handler2)
@@ -877,8 +1066,8 @@ function createRegistry(getTools, logs) {
       const value = await unwrap(definition).run(...call.args ?? []);
       return { id: call.id, from, ok: true, value: toJson(value), ms: ms() };
     } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
-      return { id: call.id, from, ok: false, error: message, ms: ms() };
+      const message2 = error instanceof Error ? error.message : String(error);
+      return { id: call.id, from, ok: false, error: message2, ms: ms() };
     }
   }
   return { list, dispatch };
@@ -889,9 +1078,11 @@ var randomId = () => Math.random().toString(36).slice(2, 10);
 function startAgentBridge(options = {}) {
   const deviceId = randomId();
   const userTools = () => typeof options.tools === "function" ? options.tools() : options.tools ?? {};
+  const { scenarios } = options;
+  const getScenarios = scenarios ? () => typeof scenarios === "function" ? scenarios() : scenarios : void 0;
   const logs = startLogCapture();
   const allTools = () => ({
-    ...builtinTools(() => registry.list(), allTools, logs.capture),
+    ...builtinTools(() => registry.list(), allTools, logs.capture, getScenarios),
     ...userTools()
   });
   const registry = createRegistry(allTools, logs.capture);
@@ -927,7 +1118,12 @@ function useAgentBridge(options = {}) {
       tools: () => {
         const { tools } = latest.current;
         return typeof tools === "function" ? tools() : tools ?? {};
-      }
+      },
+      // Decided at mount: scenario.* tools are there or not for the bridge's life.
+      scenarios: latest.current.scenarios ? () => {
+        const { scenarios } = latest.current;
+        return typeof scenarios === "function" ? scenarios() : scenarios ?? {};
+      } : void 0
     });
   }, []);
 }

package/dist/runtime/index.d.cts

@@ -1,5 +1,5 @@
-import { a as Transport, A as AgentBridgeOptions } from '../types-C6DUUHnB.cjs';
-export { C as CallMessage, D as DeviceInfo, L as LogEntry, R as RUNTIME_MARKER, b as ResultMessage, c as ToolDefinition, d as ToolFn, e as ToolInfo, T as Tools } from '../types-C6DUUHnB.cjs';
+import { a as Transport, A as AgentBridgeOptions } from '../types-6kKQsLC1.cjs';
+export { C as CallMessage, D as DeviceInfo, L as LogEntry, O as OptionsSchema, R as RUNTIME_MARKER, b as ResultMessage, S as Scenario, c as ScenarioContext, d as Scenarios, e as ToolDefinition, f as ToolFn, g as ToolInfo, T as Tools } from '../types-6kKQsLC1.cjs';
 
 /**
  * Works in any React Native app served by Metro. The client evaluates one fixed
@@ -8,6 +8,26 @@ export { C as CallMessage, D as DeviceInfo, L as LogEntry, R as RUNTIME_MARKER,
  */
 declare function cdpTransport(): Transport;
 
+type Gate = {
+    name: string;
+    /** True while anything holds the gate closed. */
+    readonly closed: boolean;
+    /**
+     * Closes the gate until the returned function is called. Closes are
+     * counted, so the gate opens when the last one is released. Hand the
+     * result to a scenario's `onUndo`.
+     */
+    close: () => () => void;
+    /** Calls `fn(closed)` when the gate closes or opens. Returns an unsubscribe. */
+    subscribe: (fn: (closed: boolean) => void) => () => void;
+};
+/**
+ * A switch app code checks before a side effect a scenario must hold off,
+ * e.g. connecting a realtime client with a fake token. Always open in a
+ * release build.
+ */
+declare function createGate(name: string): Gate;
+
 type SettleResult = {
     commits: number;
     ms: number;
@@ -66,4 +86,4 @@ declare function startAgentBridge(options?: AgentBridgeOptions): () => void;
  */
 declare function useAgentBridge(options?: AgentBridgeOptions): void;
 
-export { AgentBridgeOptions, type ScreenElement, type SettleResult, type Target, Transport, cdpTransport, settle, startAgentBridge, useAgentBridge };
+export { AgentBridgeOptions, type Gate, type ScreenElement, type SettleResult, type Target, Transport, cdpTransport, createGate, settle, startAgentBridge, useAgentBridge };

package/dist/{types-C6DUUHnB.d.cts → types-6kKQsLC1.d.cts}

@@ -48,6 +48,14 @@ type DeviceInfo = {
     tools: ToolInfo[];
 };
 
+/**
+ * A JSON Schema (draft 2020-12) for a scenario's options. Typed loosely, so
+ * `as const` schemas and ones generated by other libraries fit.
+ */
+type OptionsSchema = {
+    readonly [keyword: string]: unknown;
+};
+
 type ToolFn = (...args: any[]) => unknown;
 type ToolDefinition = ToolFn | {
     description?: string;
@@ -64,13 +72,44 @@ type Transport = {
     /** Starts listening; returns a function that stops. */
     start: (context: TransportContext) => () => void;
 };
+type ScenarioContext<O = unknown> = {
+    /** What the agent or flow passed to `scenario.apply`, or undefined. */
+    options: O | undefined;
+    /**
+     * Calls any bridge tool by name, e.g. `call('store.set', 'auth', {...})`.
+     * What a tool changes is undone by its own restorer in `bridge.restore`.
+     */
+    call: (tool: string, ...args: unknown[]) => Promise<unknown>;
+    /**
+     * Runs `fn` when the scenario is undone, after every other restorer. Use it
+     * for anything the tools' restorers don't cover: app mocks, gates, native
+     * state. Undo callbacks run newest first.
+     */
+    onUndo: (fn: () => unknown) => void;
+};
+/** A named setup the app defines and the agent applies, e.g. a signed-in user. */
+type Scenario<O = unknown> = {
+    description?: string;
+    /**
+     * JSON Schema (2020-12) for `options`. `scenario.apply` rejects options
+     * that don't fit before `apply` runs, and `scenario.list` shows it. Keys an
+     * object schema doesn't list are rejected unless it sets
+     * `additionalProperties`. No options are checked as `{}`.
+     */
+    options?: OptionsSchema;
+    /** Sets the app up. Its return value goes back to the agent. */
+    apply: (context: ScenarioContext<O>) => unknown;
+};
+type Scenarios = Record<string, Scenario<any>>;
 type AgentBridgeOptions = {
     /** Your tools, or a function returning them (read on every call). */
     tools?: Tools | (() => Tools);
+    /** Named setups for `scenario.*`, or a function returning them (read on every call). */
+    scenarios?: Scenarios | (() => Scenarios);
     /** How this app shows up in `agent-bridge devices`. */
     name?: string;
     /** Defaults to CDP only. Add `expoTransport()` on Expo. */
     transports?: Transport[];
 };
 
-export { type AgentBridgeOptions as A, type CallMessage as C, type DeviceInfo as D, type LogEntry as L, RUNTIME_MARKER as R, type Tools as T, type Transport as a, type ResultMessage as b, type ToolDefinition as c, type ToolFn as d, type ToolInfo as e };
+export { type AgentBridgeOptions as A, type CallMessage as C, type DeviceInfo as D, type LogEntry as L, type OptionsSchema as O, RUNTIME_MARKER as R, type Scenario as S, type Tools as T, type Transport as a, type ResultMessage as b, type ScenarioContext as c, type Scenarios as d, type ToolDefinition as e, type ToolFn as f, type ToolInfo as g };

package/entries/ably.cjs

@@ -0,0 +1,9 @@
+'use strict'
+
+// Metro inlines NODE_ENV and drops the dead branch, so a release bundle
+// never includes the bridge, the same way react/index.js works.
+if (process.env.NODE_ENV === 'production') {
+  module.exports = require('../dist/noop/ably.cjs')
+} else {
+  module.exports = require('../dist/adapters/ably.cjs')
+}

package/entries/realtime.cjs

@@ -0,0 +1,9 @@
+'use strict'
+
+// Metro inlines NODE_ENV and drops the dead branch, so a release bundle
+// never includes the bridge, the same way react/index.js works.
+if (process.env.NODE_ENV === 'production') {
+  module.exports = require('../dist/noop/realtime.cjs')
+} else {
+  module.exports = require('../dist/realtime/index.cjs')
+}

package/entries/socket.io.cjs

@@ -0,0 +1,9 @@
+'use strict'
+
+// Metro inlines NODE_ENV and drops the dead branch, so a release bundle
+// never includes the bridge, the same way react/index.js works.
+if (process.env.NODE_ENV === 'production') {
+  module.exports = require('../dist/noop/socket-io.cjs')
+} else {
+  module.exports = require('../dist/adapters/socket-io.cjs')
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avasapp/agent-bridge",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Let coding agents drive a running React Native app directly: seed state, flip flags, navigate and check the screen in about a millisecond per call, with no taps.",
   "type": "module",
   "license": "MIT",
@@ -13,8 +13,7 @@
     "url": "https://github.com/avas-app/agent-bridge/issues"
   },
   "publishConfig": {
-    "access": "public",
-    "provenance": true
+    "access": "public"
   },
   "engines": {
     "node": ">=20"
@@ -51,6 +50,18 @@
       "types": "./dist/network/index.d.cts",
       "default": "./entries/network.cjs"
     },
+    "./realtime": {
+      "types": "./dist/realtime/index.d.cts",
+      "default": "./entries/realtime.cjs"
+    },
+    "./ably": {
+      "types": "./dist/adapters/ably.d.cts",
+      "default": "./entries/ably.cjs"
+    },
+    "./socket.io": {
+      "types": "./dist/adapters/socket-io.d.cts",
+      "default": "./entries/socket.io.cjs"
+    },
     "./client": {
       "types": "./dist/client/index.d.ts",
       "import": "./dist/client/index.js",
@@ -77,7 +88,10 @@
     "cdp",
     "tanstack-query",
     "zustand",
-    "mmkv"
+    "mmkv",
+    "realtime",
+    "ably",
+    "socket.io"
   ],
   "scripts": {
     "build": "rm -rf dist && tsup",
@@ -104,6 +118,7 @@
     }
   },
   "dependencies": {
+    "@cfworker/json-schema": "^4.1.1",
     "ws": "^8.21.3"
   },
   "devDependencies": {
@@ -113,6 +128,8 @@
     "@types/bun": "^1.4.2",
     "@types/react": "^19.3.0",
     "@types/ws": "^8.18.1",
+    "ably": "^2.29.0",
+    "socket.io-client": "^4.8.4",
     "tsup": "^8.5.1",
     "typescript": "~6.0.3",
     "zustand": "^5.0.15"

package/skills/agent-bridge/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: agent-bridge
-description: "Drive a running React Native or Expo dev build directly through @avasapp/agent-bridge: see what's on screen, fill in forms, press buttons, seed query data, flip feature flags, set store state, navigate, mock the network and undo it all, in milliseconds per call instead of tapping through the app. Use whenever you need the app in a particular state to test a change, or need to verify what a screen shows."
+description: "Drive a running React Native or Expo dev build directly through @avasapp/agent-bridge: start from an app-defined scenario such as a locally signed-in user, see what's on screen, fill in forms, press buttons, seed query data, flip feature flags, set store state, navigate, mock the network, fake realtime messages and undo it all, in milliseconds per call instead of tapping through the app. Pairs with agent-device, which opens the app and covers native UI, real taps and screenshots. Use whenever you need the app in a particular state to test a change, or need to verify what a screen shows."
 ---
 
 # Driving an app with agent-bridge
@@ -8,6 +8,22 @@ description: "Drive a running React Native or Expo dev build directly through @a
 The app mounts `useAgentBridge({ tools })` in a dev build. You call those tools
 by name. Nothing is tapped, so there is no setup to click through.
 
+## Pair it with agent-device
+
+agent-bridge works inside the app's JavaScript; agent-device works the device.
+Use both, each for what it's good at:
+
+| agent-bridge | agent-device |
+| --- | --- |
+| Put the app in a state: flags, query data, store values, network mocks, realtime messages | Install and open the app, reload, relaunch |
+| Navigate, fill forms, press buttons, check text on screen | System alerts, permission prompts, native sheets, the keyboard |
+| Undo it all with `bridge.restore` | Screenshots, recordings, one real tap to prove the UI responds |
+
+A typical run: `agent-device open` the app, set up and check the screen with
+agent-bridge, then finish with one real tap or a screenshot from agent-device.
+Don't tap through setup screens or edit backend data to reach a state that one
+bridge call can set.
+
 ## Start a session
 
 ```sh
@@ -21,6 +37,30 @@ minutes without calls and runs `bridge.restore` when it does.
 If `tools` fails with "agent-bridge isn't running", the hook isn't mounted in
 this build. Say so; don't fall back to tapping silently.
 
+## Start from a scenario
+
+Apps can define named setups, such as a locally signed-in user. Use one
+instead of signing in by hand or seeding auth state yourself:
+
+```sh
+npx agent-bridge scenarios                                        # what this app defines
+npx agent-bridge call scenario.apply '["signedIn", {"user": {"name": "Ada"}}]'
+```
+
+`scenarios` shows each one's options as a JSON Schema. Bad options fail
+before anything changes, and the error lists every problem
+(`options: unknown option "usr". Known: user`): fix them and apply again.
+`bridge.restore` (and `session stop`) undoes it after everything else. A local
+scenario usually turns on strict network mode: any request no mock answers
+fails with a 501, and the reply carries an error that names it
+(`! error during …: agent-bridge strict network: no mock for GET https://…`).
+Add a mock for it (`net.mock`), don't turn strict mode off.
+`npx agent-bridge call net.strict` lists what it blocked. Strict mode sees JS
+`fetch`/XHR only, not images, WebSockets or native SDKs.
+
+If the app has no scenario for the state you need, say so. Don't sign in to a
+real account instead.
+
 ## See and use the screen
 
 ```sh
@@ -32,7 +72,7 @@ npx agent-bridge call screen.waitFor '"Name is required"'      # {"gone": true}
 
 `press` and `fill` return once the app has rendered the result, so the next
 check sees it. `fill` skips the keyboard: autocorrect and native-only input
-behaviour need one real typing step from your device tool.
+behaviour need one real typing step from agent-device.
 
 ## Get the app into a state
 
@@ -48,6 +88,25 @@ npx agent-bridge call net.log
 Arguments are a JSON array (or a single JSON value). Read the current value
 first (`query.get`, `store.get`) and change only what you need.
 
+## Realtime messages
+
+If the app has `realtime.*` tools, you can see its realtime messages and fake
+them instead of waiting for a backend to send one:
+
+```sh
+npx agent-bridge call realtime.channels                         # what the app listens on
+npx agent-bridge call realtime.log '{"channel": "chat"}'        # recent messages, real and faked
+npx agent-bridge call realtime.mute '"chat"'                    # stop real ones overwriting your state
+npx agent-bridge call realtime.emit '["chat", {"name": "message", "data": {"text": "hi"}}]'
+npx agent-bridge call realtime.connection '"disconnected"'      # null goes back to the real state
+```
+
+Copy the shape of a real message from `realtime.log` before you emit one. With
+Ably, pass `{ name, data }`; with socket.io, pass the arguments after the
+channel (the event name). Muting still lets your emitted messages through.
+`emit` fails and lists the live channels when nothing listens on yours: open
+the screen that subscribes first.
+
 ## Watch for errors
 
 Every reply carries errors the app logged or threw since the previous reply,
@@ -60,6 +119,8 @@ last 200 errors and warnings.
 Write the steps into a flow file and run it:
 
 ```js
+export const scenario = 'signedIn'   // applied first, undone after, even on failure
+
 export default async ({ step }) => {
   await step('open form', 'screen.press', 'add-plant')
   await step('save empty', 'screen.press', 'save-plant')
@@ -70,6 +131,7 @@ export default async ({ step }) => {
 
 ```sh
 npx agent-bridge run flow.mjs --strict    # --strict fails if the app logged an error
+npx agent-bridge run flow.mjs --scenario signedIn   # add a scenario the flow doesn't declare
 ```
 
 ## Clean up
@@ -78,12 +140,13 @@ npx agent-bridge run flow.mjs --strict    # --strict fails if the app logged an
 npx agent-bridge session stop             # runs bridge.restore; --keep leaves the app as is
 ```
 
-`bridge.restore` unpins queries, puts back store and MMKV values and removes
-network mocks, so the next run starts from the real state.
+`bridge.restore` unpins queries, puts back store and MMKV values, removes
+network mocks, unmutes realtime channels and ends a faked connection state,
+then undoes active scenarios, so the next run starts from the real state.
 
 ## Traps
 
 - Run next to the simulator. From another machine every call pays the network.
 - It can't see native UI (system alerts, permission prompts, native sheets) or
-  overlap. Finish a flow with one real UI check or screenshot from your device tool.
+  overlap. Finish a flow with one real UI check or screenshot from agent-device.
 - With several apps on one Metro, pass `--device`.