@avasapp/agent-bridge 0.2.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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avasapp/agent-bridge",
-  "version": "0.2.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",
@@ -118,6 +118,7 @@
     }
   },
   "dependencies": {
+    "@cfworker/json-schema": "^4.1.1",
     "ws": "^8.21.3"
   },
   "devDependencies": {

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, 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."
+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
@@ -37,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
@@ -95,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')
@@ -105,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
@@ -114,8 +141,8 @@ npx agent-bridge session stop             # runs bridge.restore; --keep leaves t
 ```
 
 `bridge.restore` unpins queries, puts back store and MMKV values, removes
-network mocks, unmutes realtime channels and ends a faked connection state, so
-the next run starts from the real state.
+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