@avasapp/agent-bridge 0.2.0 → 0.3.0

package/README.md

@@ -101,6 +101,8 @@ Errors come back on their own: each reply carries what the app logged with `cons
 ```sh
 npx agent-bridge session start            # hold one connection; call/tools/run reuse it
 npx agent-bridge tools
+npx agent-bridge scenarios                # setups the app defines, e.g. signedIn
+npx agent-bridge call scenario.apply '["signedIn", {"user": {"name": "Ada"}}]'
 npx agent-bridge call query.pin '[["features"], {"beta": false}]'
 npx agent-bridge call screen.press '"add-plant"'
 npx agent-bridge call screen.fill '["plant-name", "Fiddle leaf fig"]'
@@ -123,6 +125,8 @@ await app.call('screen.press', 'save-plant')
 A flow is a module the CLI runs without a model in the loop:
 
 ```js
+export const scenario = 'signedIn'   // optional: see Scenarios
+
 export default async ({ step }) => {
   await step('flag: beta off', 'query.pin', ['features'], { beta: false })
   await step('save empty form', 'screen.press', 'save-plant')
@@ -131,8 +135,71 @@ export default async ({ step }) => {
 }
 ```
 
+To run flows from your own script or CI job, import them and pass them to `runFlow`. It applies declared scenarios, restores afterwards, and throws what the flow threw:
+
+```ts
+import { connect, runFlow } from '@avasapp/agent-bridge/client'
+import * as mainTabs from './flows/main-tabs.flow.mjs'
+
+const app = await connect({ metro: 'localhost:8081' })
+const { errors, restoreErrors } = await runFlow(app, mainTabs, { scenarios: [{ name: 'signedIn' }] })
+app.close()
+if (errors || restoreErrors.length) process.exit(1)
+```
+
 No device tool is needed. Pair one (such as agent-device) with the bridge for what it can't reach: system alerts, permission prompts, the keyboard, screenshots, and one real tap per flow.
 
+## Scenarios
+
+Most flows need the app in a known state first, above all a signed-in user. A scenario is a named setup the app defines once, for example a user who is signed in **locally**: a fake token, a fake user, and every request answered in the app, never by the real server.
+
+```ts
+import { type Scenarios, useAgentBridge } from '@avasapp/agent-bridge'
+import { mockApi, strictNetwork } from '@avasapp/agent-bridge/network'
+
+const scenarios: Scenarios = {
+  signedIn: {
+    description: 'Signed in locally; no request reaches a server.',
+    // JSON Schema: bad options fail before apply runs, and say why.
+    options: {
+      type: 'object',
+      properties: {
+        user: { type: 'object', properties: { name: { type: 'string' }, email: { type: 'string', format: 'email' } } },
+      },
+    },
+    apply: async ({ options, call, onUndo }) => {
+      const user = { ...defaultUser, ...options?.user }
+      // Guards first, so nothing leaves the app with the fake token.
+      onUndo(realtimeGate.close())
+      onUndo(strictNetwork({ allow: ['cdn.example.com'] }))
+      onUndo(mockApi(API_URL, {
+        'GET /me': { json: user },
+        'GET /orders/:id': ({ params }) => ({ json: orders[params.id] }),
+      }))
+      onUndo(await addNativeRewriteRule(tilesHost, localTiles))  // any app code
+      await call('store.set', 'auth', { token: 'local', user })  // store.restore undoes it
+      return { user }
+    },
+  },
+}
+
+useAgentBridge({ tools, scenarios })
+```
+
+- `options` is a JSON Schema (2020-12, checked with [`@cfworker/json-schema`](https://github.com/cfworker/cfworker/tree/main/packages/json-schema), which needs no `eval` and runs on Hermes). `scenario.apply` checks the options before anything changes, and lists every problem at once, such as `options/user/email: String does not match format "email"`. An object schema that lists `properties` rejects other keys (`options: unknown option "usr". Known: user`) unless it sets `additionalProperties`. So a typo fails instead of being ignored. No options are checked as `{}`, so `required` ones are reported.
+- `apply` is ordinary app code. `call(tool, ...args)` runs a bridge tool, and that tool's own restorer undoes the change. `onUndo(fn)` covers everything else: app mocks, gates, native state such as a URL-rewrite rule.
+- `bridge.restore` runs every scenario's undo callbacks **last**, newest first, after the store, query and network restorers. The guards stay up until the app is back in its real state. If `apply` throws, the callbacks it had registered run straight away.
+- Tools: `scenario.list`, `scenario.apply [name, options?]` (applying an active one again undoes it first) and `scenario.restore`. `npx agent-bridge scenarios` lists them.
+- A flow declares what it needs with `export const scenario = 'signedIn'`, or `export const scenarios = ['signedIn', { name: 'cart', options: { items: 2 } }]`. `agent-bridge run` applies them before the flow and runs `bridge.restore` afterwards, even when the flow fails. The flow gets what each `apply` returned as `scenarios.signedIn`. A failed restorer makes the run exit non-zero. `run --scenario signedIn` adds one to any flow, with JSON options after `=` (`--scenario 'signedIn={"user":{"name":"Ada"}}'`); it replaces a declared one of the same name.
+
+**Strict network.** `strictNetwork({ allow?, status?, offline? })` from `@avasapp/agent-bridge/network` (or `net.strict` from the agent) fails every `fetch` or `XMLHttpRequest` that no mock answers. The request gets a 501 with `{ error: "agent-bridge strict network: no mock for GET https://…" }` and a `console.error`, so the agent sees it with the reply. With `offline: true` it fails like a network failure instead. `net.strict` lists the requests it blocked. `allow` lets hosts through (substrings or RegExps); Metro always gets through. It covers JS requests only: images, native SDKs (a map's tile fetches, say), and WebSockets go around it, so a scenario handles those with app code and `onUndo`.
+
+**Fixtures.** `mockApi(baseUrl, routes, options?)` answers `'METHOD /path'` routes, or `'/path'` for any method. `:name` matches one path segment and `*` the rest; the query string is ignored. A route's value is a response (`{ json }`, `{ status, body }`…) or a handler that gets the request with `params` and `query`. It returns a function that removes the routes.
+
+**Gates.** Some side effects must wait while a scenario runs, such as a realtime client connecting with the fake token and signing the user out when auth fails. `createGate(name)` from `@avasapp/agent-bridge` is a counted switch: `gate.close()` returns the function that reopens it (hand that to `onUndo`), `gate.closed` is what app code checks, and `gate.subscribe(fn)` hears it change. In a release build it's always open. `realtime.connection` isn't enough on its own: it hides the state from the app, but the client still connects.
+
+The example app's [`src/dev/scenarios.ts`](example/src/dev/scenarios.ts) is a complete local `signedIn`, and [`flows/checks/signed-in.mjs`](example/flows/checks/signed-in.mjs) declares it.
+
 ## Adapters
 
 | Import | Tools | Needs |
@@ -141,12 +208,12 @@ No device tool is needed. Pair one (such as agent-device) with the bridge for wh
 | `@avasapp/agent-bridge/zustand` | `store.list` `get` `set` `call` `restore` | your stores |
 | `@avasapp/agent-bridge/react-native-mmkv` | `mmkv.list` `keys` `get` `set` `delete` `restore` | your MMKV instances |
 | `@avasapp/agent-bridge/expo-router` | `router.navigate` `push` `replace` `back` `current` | `router` and `useNavigationContainerRef()` from expo-router |
-| `@avasapp/agent-bridge/network` | `net.log` `mock` `mocks` `unmock` `clear` `restore` | nothing: patches `fetch` and `XMLHttpRequest` in dev |
+| `@avasapp/agent-bridge/network` | `net.log` `mock` `mocks` `unmock` `strict` `clear` `restore` | nothing: patches `fetch` and `XMLHttpRequest` in dev |
 | `@avasapp/agent-bridge/ably` | `realtime.channels` `log` `emit` `mute` `unmute` `connection` `restore` | your Ably `Realtime` client |
 | `@avasapp/agent-bridge/socket.io` | `realtime.channels` `log` `emit` `mute` `unmute` `connection` `restore` | your socket.io `Socket` |
 | `@avasapp/agent-bridge/realtime` | `realtime.channels` `log` `emit` `mute` `unmute` `restore` | two lines in your own subscribe function |
 
-A pin keeps seeded data in place through refetches until you unpin it. `net.mock('/inbox', { status: 500 })` or `{ offline: true }` fails a route; apps can fake a whole backend with `mockRequests` from the same import.
+A pin keeps seeded data in place through refetches until you unpin it. `net.mock('/inbox', { status: 500 })` or `{ offline: true }` fails a route; apps can fake a whole backend with `mockRequests` or `mockApi` from the same import, and turn on strict mode with `strictNetwork`.
 
 ## Realtime
 
@@ -231,16 +298,11 @@ Every entry point is gated on `process.env.NODE_ENV`, like `react/index.js`: Met
 npx agent-bridge assert-absent path/to/main.jsbundle
 ```
 
-## Traps we hit
+## What runs where
 
-- **Run the agent on the machine with the simulator.** Every call pays the network otherwise.
-- **Hidden tabs stay mounted.** `screen.findText` skips anything under an inactive `RNSScreen`.
-- **Expo checks the debugger's Origin** against the host Metro advertises and drops mismatches silently. The client reads it from the manifest.
-- **Expo Go on Android has no CDP `Runtime.evaluate`.** Use the Expo socket there (the default); CDP works in dev builds and in Expo Go on iOS.
-- **Expo's socket broadcasts to every app.** Calls are addressed to one device; pick it with `--device` when several are connected.
-- **Screen checks through the accessibility tree are slow** (hundreds of ms each). Check in-app, and keep one real UI check per flow.
-- **`screen.fill` skips the keyboard.** It runs the input's handlers, so validation and state are real, but autocorrect, native `maxLength` and uncontrolled inputs' native text are not.
-- **Keep your `QueryClient` in state** (`useState(() => new QueryClient())`). Created at module level, a Fast Refresh can leave the bridge holding a different client than the screen.
+- **On your machine:** `agent-bridge run` and `runFlow` run the flow module you point them at, with your permissions, the same as `node flow.mjs`. Only run flows you'd run as scripts. In CI, don't run flows from untrusted forks with secrets in the environment, as with any test.
+- **In the app:** the bridge only calls tools and scenarios the app registered. Arguments and scenario options arrive as JSON data. Over CDP the client evaluates one fixed call with the message as a JSON string; the Expo transport sends plain JSON. Nothing the agent sends is evaluated as code.
+- **Who can reach it:** anyone who can reach Metro's debugger can already run any code in a dev build. The bridge adds no new way in, and release builds carry none of it (`assert-absent` checks).
 
 ## License
 

package/dist/adapters/ably.d.cts

@@ -1,4 +1,4 @@
-import { T as Tools } from '../types-C6DUUHnB.cjs';
+import { T as Tools } from '../types-6kKQsLC1.cjs';
 
 /** The fields of an Ably message this adapter reads. */
 type AblyMessageLike = {

package/dist/adapters/expo-router.d.cts

@@ -1,4 +1,4 @@
-import { T as Tools } from '../types-C6DUUHnB.cjs';
+import { T as Tools } from '../types-6kKQsLC1.cjs';
 
 /** The imperative `router` from expo-router. Passed in, so this adds no dependency. */
 type RouterLike = {

package/dist/adapters/react-native-mmkv.d.cts

@@ -1,4 +1,4 @@
-import { T as Tools } from '../types-C6DUUHnB.cjs';
+import { T as Tools } from '../types-6kKQsLC1.cjs';
 
 /** The MMKV surface this adapter uses. v3 has `delete`, v4 has `remove`. */
 type MMKVLike = {

package/dist/adapters/socket-io.d.cts

@@ -1,4 +1,4 @@
-import { T as Tools } from '../types-C6DUUHnB.cjs';
+import { T as Tools } from '../types-6kKQsLC1.cjs';
 
 type Listener = (...args: any[]) => void;
 /** A socket.io client socket (`io(url)`), typed structurally. */

package/dist/adapters/tanstack-query.d.cts

@@ -1,5 +1,5 @@
 import { QueryClient } from '@tanstack/query-core';
-import { T as Tools } from '../types-C6DUUHnB.cjs';
+import { T as Tools } from '../types-6kKQsLC1.cjs';
 
 /**
  * Read and seed the TanStack Query cache. `query.pin` keeps a seed in place:

package/dist/adapters/zustand.d.cts

@@ -1,4 +1,4 @@
-import { T as Tools } from '../types-C6DUUHnB.cjs';
+import { T as Tools } from '../types-6kKQsLC1.cjs';
 
 /** Anything with zustand's store shape. */
 type StoreLike = {

package/dist/{chunk-LBYZ5JHF.js → chunk-S2FYN2R5.js}

@@ -291,6 +291,119 @@ async function openConnection(options = {}) {
   }
 }
 
+// src/client/log-lines.ts
+function logLine(entry) {
+  const where = entry.during ? ` during ${entry.during}` : entry.after ? ` after ${entry.after}` : "";
+  const first = entry.message.split("\n")[0] ?? "";
+  const text = first.length > 300 ? `${first.slice(0, 300)}...` : first;
+  return `! ${entry.level}${where}: ${text}`;
+}
+
+// src/client/flow.ts
+function flowScenarios(flow) {
+  const declared = [
+    ...flow.scenario === void 0 ? [] : [flow.scenario],
+    ...flow.scenarios ?? []
+  ];
+  return declared.map((s) => {
+    if (typeof s === "string") return { name: s };
+    if (s && typeof s === "object" && typeof s.name === "string") return s;
+    throw new Error(
+      `A flow's scenario is a name or { name, options }, not ${JSON.stringify(s)}`
+    );
+  });
+}
+function parseScenarioFlag(value) {
+  const at = value.indexOf("=");
+  if (at === -1) return { name: value };
+  const name = value.slice(0, at);
+  const raw = value.slice(at + 1);
+  try {
+    return { name, options: JSON.parse(raw) };
+  } catch {
+    throw new Error(
+      `--scenario ${name}: the options after "=" must be JSON, got ${raw}`
+    );
+  }
+}
+function mergeScenarios(declared, extra) {
+  const names = new Set(extra.map((s) => s.name));
+  return [...declared.filter((s) => !names.has(s.name)), ...extra];
+}
+var failedLogs = (error) => error instanceof AgentBridgeCallError ? error.logs : [];
+async function runFlow(bridge, flow, options = {}) {
+  const print = options.print ?? console.log;
+  const needs = mergeScenarios(flowScenarios(flow), options.scenarios ?? []);
+  let n = 0;
+  let total = 0;
+  let errors = 0;
+  const t0 = performance.now();
+  const report = (logs) => {
+    errors += logs.length;
+    for (const e of logs) print(`   ${logLine(e)}`);
+  };
+  const timed = async (tool, ...args) => {
+    try {
+      const result = await bridge.timed(tool, ...args);
+      report(result.logs);
+      return result;
+    } catch (error) {
+      report(failedLogs(error));
+      throw error;
+    }
+  };
+  const call = async (tool, ...args) => (await timed(tool, ...args)).value;
+  const step = async (label, tool, ...args) => {
+    const { value, ms, logs } = await bridge.timed(tool, ...args).catch((error) => {
+      report(failedLogs(error));
+      throw error;
+    });
+    total += ms;
+    print(
+      `${String(++n).padStart(2, "0")} ${label.padEnd(30)} ${ms.toFixed(1).padStart(7)} ms`
+    );
+    report(logs);
+    return value;
+  };
+  const restoreErrors = [];
+  const applied = {};
+  if (needs.length && !bridge.tools().some((t) => t.name === "scenario.apply"))
+    throw new Error(
+      `The flow needs scenario "${needs[0].name}", but the app defines none: pass \`scenarios\` to useAgentBridge.`
+    );
+  try {
+    for (const { name, options: options2 } of needs) {
+      const args = options2 === void 0 ? [name] : [name, options2];
+      applied[name] = await step(`scenario ${name}`, "scenario.apply", ...args);
+    }
+    await flow.default({
+      bridge: { ...bridge, timed, call },
+      call,
+      step,
+      scenarios: applied
+    });
+  } finally {
+    if (needs.length) {
+      try {
+        const result = await step("restore", "bridge.restore");
+        for (const [name, value] of Object.entries(result ?? {})) {
+          const error = value?.error;
+          if (error !== void 0) restoreErrors.push(`${name}: ${String(error)}`);
+        }
+      } catch (error) {
+        restoreErrors.push(
+          `bridge.restore: ${error instanceof Error ? error.message : String(error)}`
+        );
+      }
+      for (const e of restoreErrors) print(`   ! restore failed: ${e}`);
+    }
+  }
+  print(
+    `${n} steps, ${total.toFixed(1)} ms in calls, ${(performance.now() - t0).toFixed(0)} ms wall (${bridge.transport})${errors ? `, ${errors} error${errors === 1 ? "" : "s"}` : ""}`
+  );
+  return { steps: n, errors, restoreErrors };
+}
+
 // src/client/session/client.ts
 import { createConnection } from "net";
 import { createInterface } from "readline";
@@ -559,6 +672,10 @@ export {
   metroHost,
   RUNTIME_MARKER,
   openConnection,
+  logLine,
+  flowScenarios,
+  parseScenarioFlag,
+  runFlow,
   stateDir,
   sessionFiles,
   checkName,

package/dist/cli.js

@@ -5,21 +5,25 @@ import {
   checkName,
   connect,
   connectSession,
+  flowScenarios,
   formatDuration,
   isAlive,
   listDevices,
   listSessions,
+  logLine,
   metroHost,
   openConnection,
   parseDuration,
+  parseScenarioFlag,
   pickSession,
   readSession,
   removeSessionFiles,
+  runFlow,
   sessionFiles,
   sessionRequest,
   stateDir,
   writePrivate
-} from "./chunk-LBYZ5JHF.js";
+} from "./chunk-S2FYN2R5.js";
 
 // src/cli.ts
 import { readFile } from "fs/promises";
@@ -27,14 +31,6 @@ import { resolve } from "path";
 import { pathToFileURL } from "url";
 import { parseArgs } from "util";
 
-// src/client/log-lines.ts
-function logLine(entry) {
-  const where = entry.during ? ` during ${entry.during}` : entry.after ? ` after ${entry.after}` : "";
-  const first = entry.message.split("\n")[0] ?? "";
-  const text = first.length > 300 ? `${first.slice(0, 300)}...` : first;
-  return `! ${entry.level}${where}: ${text}`;
-}
-
 // src/client/session/cli.ts
 import { spawn } from "child_process";
 import { existsSync, readFileSync, rmSync as rmSync2 } from "fs";
@@ -480,6 +476,9 @@ Usage
   agent-bridge tools                      Tools the app exposes
   agent-bridge call <tool> [args]         Call a tool. args: a JSON array, or one JSON value
   agent-bridge run <flow.mjs|.ts>         Run a flow: export default async ({ step, call }) => {}
+                                          export const scenario = 'signedIn' applies it first
+                                          and runs bridge.restore after, even on failure
+  agent-bridge scenarios                  Scenarios the app defines (scenario.apply applies one)
   agent-bridge assert-absent <files...>   Fail if a release bundle contains the bridge
 
 Sessions: one connection for all of an agent's calls
@@ -494,6 +493,8 @@ Options
   --transport <name>     auto (default), expo or cdp
   --timeout <ms>         Per-call timeout (default 10000)
   --strict               run: exit non-zero if the app logged an error
+  --scenario <name>      run: also apply this scenario (repeatable). Options as
+                         JSON after "=": --scenario 'signedIn={"user":{"name":"Ada"}}'
   --session <name>       Use this session (env AGENT_BRIDGE_SESSION)
   --no-session           Connect directly even if a session is running
 `;
@@ -517,6 +518,7 @@ async function main() {
       transport: { type: "string" },
       timeout: { type: "string" },
       strict: { type: "boolean" },
+      scenario: { type: "string", multiple: true },
       name: { type: "string" },
       idle: { type: "string" },
       keep: { type: "boolean" },
@@ -583,47 +585,34 @@ async function main() {
       const [file] = rest;
       if (!file) throw new Error("Usage: agent-bridge run <flow file>");
       const flow = await import(pathToFileURL(resolve(file)).href);
+      flowScenarios(flow);
+      const extra = (values.scenario ?? []).map(parseScenarioFlag);
       return withBridge(async (bridge) => {
-        let n = 0;
-        let total = 0;
-        let errors = 0;
-        const t0 = performance.now();
-        const report = (logs) => {
-          errors += logs.length;
-          for (const e of logs) console.log(`   ${logLine(e)}`);
-        };
-        const timed = async (tool, ...args) => {
-          try {
-            const result = await bridge.timed(tool, ...args);
-            report(result.logs);
-            return result;
-          } catch (error) {
-            report(failedLogs(error));
-            throw error;
-          }
-        };
-        const call = async (tool, ...args) => (await timed(tool, ...args)).value;
-        const step = async (label, tool, ...args) => {
-          const { value, ms, logs } = await bridge.timed(tool, ...args).catch(
-            (error) => {
-              report(failedLogs(error));
-              throw error;
-            }
+        const { errors, restoreErrors } = await runFlow(bridge, flow, {
+          scenarios: extra
+        });
+        if (values.strict && errors || restoreErrors.length)
+          process.exitCode = 1;
+      });
+    }
+    case "scenarios":
+      return withBridge(async (bridge) => {
+        if (!bridge.tools().some((t) => t.name === "scenario.list")) {
+          console.log(
+            `${bridge.device.name} defines no scenarios (pass \`scenarios\` to useAgentBridge).`
           );
-          total += ms;
+          return;
+        }
+        const list2 = await bridge.call("scenario.list");
+        console.log(`${bridge.device.name} via ${bridge.transport}`);
+        for (const s of list2) {
           console.log(
-            `${String(++n).padStart(2, "0")} ${label.padEnd(30)} ${ms.toFixed(1).padStart(7)} ms`
+            `  ${s.name.padEnd(20)} ${s.active ? "(active) " : ""}${s.description ?? ""}`
           );
-          report(logs);
-          return value;
-        };
-        await flow.default({ bridge: { ...bridge, timed, call }, call, step });
-        console.log(
-          `${n} steps, ${total.toFixed(1)} ms in calls, ${(performance.now() - t0).toFixed(0)} ms wall (${bridge.transport})${errors ? `, ${errors} error${errors === 1 ? "" : "s"}` : ""}`
-        );
-        if (values.strict && errors) process.exitCode = 1;
+          if (s.options)
+            console.log(`  ${"".padEnd(20)} options: ${JSON.stringify(s.options)}`);
+        }
       });
-    }
     case "session":
       return sessionCommand(rest[0], values);
     case DAEMON_COMMAND:

package/dist/client/index.cjs

@@ -34,7 +34,8 @@ __export(client_exports, {
   connect: () => connect,
   connectSession: () => connectSession,
   listDevices: () => listDevices,
-  listSessions: () => listSessions
+  listSessions: () => listSessions,
+  runFlow: () => runFlow
 });
 module.exports = __toCommonJS(client_exports);
 
@@ -330,6 +331,106 @@ async function openConnection(options = {}) {
   }
 }
 
+// src/client/log-lines.ts
+function logLine(entry) {
+  const where = entry.during ? ` during ${entry.during}` : entry.after ? ` after ${entry.after}` : "";
+  const first = entry.message.split("\n")[0] ?? "";
+  const text = first.length > 300 ? `${first.slice(0, 300)}...` : first;
+  return `! ${entry.level}${where}: ${text}`;
+}
+
+// src/client/flow.ts
+function flowScenarios(flow) {
+  const declared = [
+    ...flow.scenario === void 0 ? [] : [flow.scenario],
+    ...flow.scenarios ?? []
+  ];
+  return declared.map((s) => {
+    if (typeof s === "string") return { name: s };
+    if (s && typeof s === "object" && typeof s.name === "string") return s;
+    throw new Error(
+      `A flow's scenario is a name or { name, options }, not ${JSON.stringify(s)}`
+    );
+  });
+}
+function mergeScenarios(declared, extra) {
+  const names = new Set(extra.map((s) => s.name));
+  return [...declared.filter((s) => !names.has(s.name)), ...extra];
+}
+var failedLogs = (error) => error instanceof AgentBridgeCallError ? error.logs : [];
+async function runFlow(bridge, flow, options = {}) {
+  const print = options.print ?? console.log;
+  const needs = mergeScenarios(flowScenarios(flow), options.scenarios ?? []);
+  let n = 0;
+  let total = 0;
+  let errors = 0;
+  const t0 = performance.now();
+  const report = (logs) => {
+    errors += logs.length;
+    for (const e of logs) print(`   ${logLine(e)}`);
+  };
+  const timed = async (tool, ...args) => {
+    try {
+      const result = await bridge.timed(tool, ...args);
+      report(result.logs);
+      return result;
+    } catch (error) {
+      report(failedLogs(error));
+      throw error;
+    }
+  };
+  const call = async (tool, ...args) => (await timed(tool, ...args)).value;
+  const step = async (label, tool, ...args) => {
+    const { value, ms, logs } = await bridge.timed(tool, ...args).catch((error) => {
+      report(failedLogs(error));
+      throw error;
+    });
+    total += ms;
+    print(
+      `${String(++n).padStart(2, "0")} ${label.padEnd(30)} ${ms.toFixed(1).padStart(7)} ms`
+    );
+    report(logs);
+    return value;
+  };
+  const restoreErrors = [];
+  const applied = {};
+  if (needs.length && !bridge.tools().some((t) => t.name === "scenario.apply"))
+    throw new Error(
+      `The flow needs scenario "${needs[0].name}", but the app defines none: pass \`scenarios\` to useAgentBridge.`
+    );
+  try {
+    for (const { name, options: options2 } of needs) {
+      const args = options2 === void 0 ? [name] : [name, options2];
+      applied[name] = await step(`scenario ${name}`, "scenario.apply", ...args);
+    }
+    await flow.default({
+      bridge: { ...bridge, timed, call },
+      call,
+      step,
+      scenarios: applied
+    });
+  } finally {
+    if (needs.length) {
+      try {
+        const result = await step("restore", "bridge.restore");
+        for (const [name, value] of Object.entries(result ?? {})) {
+          const error = value?.error;
+          if (error !== void 0) restoreErrors.push(`${name}: ${String(error)}`);
+        }
+      } catch (error) {
+        restoreErrors.push(
+          `bridge.restore: ${error instanceof Error ? error.message : String(error)}`
+        );
+      }
+      for (const e of restoreErrors) print(`   ! restore failed: ${e}`);
+    }
+  }
+  print(
+    `${n} steps, ${total.toFixed(1)} ms in calls, ${(performance.now() - t0).toFixed(0)} ms wall (${bridge.transport})${errors ? `, ${errors} error${errors === 1 ? "" : "s"}` : ""}`
+  );
+  return { steps: n, errors, restoreErrors };
+}
+
 // src/client/session/client.ts
 var import_node_net = require("net");
 var import_node_readline = require("readline");
@@ -567,5 +668,6 @@ async function listDevices(options = {}) {
   connect,
   connectSession,
   listDevices,
-  listSessions
+  listSessions,
+  runFlow
 });

package/dist/client/index.d.ts

@@ -25,6 +25,49 @@ type DeviceInfo = {
 
 type TransportName = 'expo' | 'cdp';
 
+/** A scenario a flow needs: a name, or a name with options. */
+type FlowScenario = string | {
+    name: string;
+    options?: unknown;
+};
+type FlowApi = {
+    bridge: AgentBridge;
+    call: AgentBridge['call'];
+    step: (label: string, tool: string, ...args: unknown[]) => Promise<unknown>;
+    /** What each declared scenario's apply returned, by name. */
+    scenarios: Record<string, unknown>;
+};
+/** A flow file: `export default async ({ step, call }) => {}`, plus what it needs. */
+type FlowModule = {
+    default: (api: FlowApi) => Promise<void>;
+    /** Applied before the flow and undone after it, even when it fails. */
+    scenario?: FlowScenario;
+    scenarios?: FlowScenario[];
+};
+type FlowResult = {
+    steps: number;
+    /** Errors the app logged during the flow. */
+    errors: number;
+    /** Restorers that failed in the closing bridge.restore, with why. */
+    restoreErrors: string[];
+};
+type RunFlowOptions = {
+    /** Where step lines go. Default: console.log. */
+    print?: (line: string) => void;
+    /** More scenarios to apply, e.g. from `--scenario`; one of the same name replaces the flow's. */
+    scenarios?: Array<{
+        name: string;
+        options?: unknown;
+    }>;
+};
+/**
+ * Runs a flow module you imported: applies its scenarios, runs it, and when
+ * there were any, undoes everything with bridge.restore afterwards, even
+ * when it fails. Throws what the flow threw; otherwise returns how it went.
+ * It runs only the code you hand it, in this process.
+ */
+declare function runFlow(bridge: AgentBridge, flow: FlowModule, options?: RunFlowOptions): Promise<FlowResult>;
+
 /** What a running session writes next to its socket. Readable only by the user. */
 type SessionState = {
     name: string;
@@ -109,4 +152,4 @@ type ListedDevice = {
 /** Apps with the bridge on Expo's socket, plus every React Native page Metro knows. */
 declare function listDevices(options?: Pick<ConnectOptions, 'metro'>): Promise<ListedDevice[]>;
 
-export { type AgentBridge, AgentBridgeCallError, type ConnectOptions, type DeviceInfo, type ListedDevice, type LogEntry, type SessionConnectOptions, type SessionState, type Timed, type ToolInfo, type TransportName, connect, connectSession, listDevices, listSessions };
+export { type AgentBridge, AgentBridgeCallError, type ConnectOptions, type DeviceInfo, type FlowApi, type FlowModule, type FlowResult, type FlowScenario, type ListedDevice, type LogEntry, type RunFlowOptions, type SessionConnectOptions, type SessionState, type Timed, type ToolInfo, type TransportName, connect, connectSession, listDevices, listSessions, runFlow };

package/dist/client/index.js

@@ -3,12 +3,14 @@ import {
   connect,
   connectSession,
   listDevices,
-  listSessions
-} from "../chunk-LBYZ5JHF.js";
+  listSessions,
+  runFlow
+} from "../chunk-S2FYN2R5.js";
 export {
   AgentBridgeCallError,
   connect,
   connectSession,
   listDevices,
-  listSessions
+  listSessions,
+  runFlow
 };

package/dist/expo/index.d.cts

@@ -1,4 +1,4 @@
-import { a as Transport } from '../types-C6DUUHnB.cjs';
+import { a as Transport } from '../types-6kKQsLC1.cjs';
 
 /**
  * Plain JSON over Expo's dev-tools plugin socket: no string evaluation, emoji