@avasapp/agent-bridge 0.4.2 → 0.6.0

package/README.md

@@ -1,15 +1,23 @@
 # @avasapp/agent-bridge
 
-Let coding agents drive a running React Native app directly. Seed data, flip flags, fake realtime messages, navigate and check the screen in **milliseconds**, without tapping through the app. It works alongside [agent-device](https://github.com/callstack/agent-device): agent-device opens the app and handles native UI, and agent-bridge handles everything inside the app.
+Let coding agents drive any running Expo or React Native app directly. Seed data, flip flags, fake realtime messages, navigate and check the screen in **milliseconds**, without tapping through the app. It works alongside device tools such as [agent-device](https://github.com/callstack/agent-device) and [Argent](https://github.com/software-mansion/argent): they open the app and handle native UI, and agent-bridge handles everything inside the app. Use it from a shell, from [flows](docs/cli.md) or as an [MCP server](docs/cli.md#mcp-server).
 
 ![The same checks with agent-device alone (22.4 s) and with agent-bridge (1.4 s): hide a tab, turn on dark mode, fill in a form, seed data, fake a live message and undo it all](example/media/demo.gif)
 
 The same 19 checks on [the example app](example), at real speed: 22.4 s with agent-device alone, 1.4 s with agent-bridge. Most calls take a few milliseconds ([benchmarks](docs/benchmarks.md)).
 
-Works on Expo (dev-tools socket) and on bare React Native (CDP over Metro). Dev builds only: release builds get empty stubs.
+Works on Expo (dev-tools socket) and on bare React Native (CDP over Metro). Nothing ships to users: every entry point compiles to an empty stub in release builds, and `agent-bridge assert-absent` checks a bundle in CI ([security](docs/security.md)).
 
 ## Install
 
+```sh
+npx @avasapp/agent-bridge init
+```
+
+Run it in the app. It installs the package, writes a dev-only `src/dev/agent-bridge.tsx` wired for the libraries it finds, adds a smoke flow and the agent skill, and prints the two lines to paste into your root component. Agents run it as `init --json`; see [the CLI](docs/cli.md#init).
+
+### Manual setup
+
 ```sh
 bun add -d @avasapp/agent-bridge   # or npm / yarn / pnpm
 ```
@@ -37,6 +45,10 @@ import { expoTransport } from '@avasapp/agent-bridge/expo'
 import { queryTools } from '@avasapp/agent-bridge/tanstack-query'
 import { storeTools } from '@avasapp/agent-bridge/zustand'
 import { mmkvTools } from '@avasapp/agent-bridge/react-native-mmkv'
+// import { asyncStorageTools } from '@avasapp/agent-bridge/async-storage'
+// import { secureStoreTools } from '@avasapp/agent-bridge/secure-store'
+// import { reduxTools } from '@avasapp/agent-bridge/redux'
+// import { jotaiTools } from '@avasapp/agent-bridge/jotai'
 import { routerTools } from '@avasapp/agent-bridge/expo-router'
 import { networkTools } from '@avasapp/agent-bridge/network'
 import { router, useNavigationContainerRef } from 'expo-router'
@@ -57,6 +69,12 @@ export function AgentBridge() {
         { redact: { auth: ['accessToken', 'refreshToken', 'user.phone'] } },
       ),
       ...mmkvTools({ storage }),
+      // Redux and Jotai state often holds tokens: add `redact` before wiring them.
+      // ...reduxTools(store, { redact: { auth: ['token'] } }),
+      // ...jotaiTools(getDefaultStore(), { user: userAtom }),
+      // AsyncStorage and SecureStore often hold tokens: wire them only if you accept that.
+      // ...asyncStorageTools(AsyncStorage),
+      // ...secureStoreTools(SecureStore, ['authToken'], { keychainService: 'auth' }),
       ...routerTools(router, { navigation: useNavigationContainerRef() }),
       ...networkTools(),
       // Your own tools: any function, JSON in and out.
@@ -67,35 +85,39 @@ export function AgentBridge() {
 }
 ```
 
-Every app also gets `screen.snapshot`, `screen.press`, `screen.fill`, `screen.scroll`, `screen.waitFor`, `screen.findText`, `app.reload`, and `bridge.restore` to undo everything the agent changed. See [built-in tools and restore](docs/built-in-tools.md), including how to give agents your own hooks and register their undo.
+Every app also gets `screen.snapshot` (one short line per element), `screen.press` (taps, long presses, Switch toggles), `screen.fill`, `screen.setValue` (Switch, Slider, Picker, SegmentedControl), `screen.scroll`, `screen.waitFor`, `screen.findText`, `app.reload`, and `bridge.restore` to undo everything the agent changed, even across a reload in a session. See [built-in tools and restore](docs/built-in-tools.md), including how to give agents your own hooks and register their undo.
 
 Most flows need the app in a known state first, such as a user signed in locally with every request mocked. Define that once as a [scenario](docs/scenarios.md).
 
 ## From the agent
 
 ```sh
-npx agent-bridge session start            # hold one connection; call/tools/run reuse it
-npx agent-bridge tools
-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.waitFor '"Name is required"'
-npx agent-bridge run flows/add-plant.mjs --strict   # fail if the app logged an error
-npx agent-bridge session stop             # runs bridge.restore, then disconnects
+npx @avasapp/agent-bridge session start            # hold one connection; call/tools/run reuse it
+npx @avasapp/agent-bridge tools
+npx @avasapp/agent-bridge call scenario.apply '["signedIn", {"user": {"name": "Ada"}}]'
+npx @avasapp/agent-bridge call query.pin '[["features"], {"beta": false}]'
+npx @avasapp/agent-bridge call screen.press '"add-plant"'
+npx @avasapp/agent-bridge call screen.waitFor '"Name is required"'
+npx @avasapp/agent-bridge run flows/add-plant.flow.mjs --strict   # fail if the app logged an error
+npx @avasapp/agent-bridge run flows/ --bail                        # every *.flow.mjs in order, restore after each
+npx @avasapp/agent-bridge session stop             # runs bridge.restore, then disconnects
 ```
 
-Agents should run `./node_modules/.bin/agent-bridge` (or `bunx agent-bridge`) rather than `npx`, which is slower and can print npm warnings into their output. See [the CLI](docs/cli.md) for flows, batch mode, the REPL, sessions and the `connect()` client.
+Agents should run `./node_modules/.bin/agent-bridge` rather than `npx`, which is slower and can print npm warnings into their output. See [the CLI](docs/cli.md) for flows, batch mode, the REPL, sessions and the `connect()` client. Agents that prefer MCP tools to a shell can run `agent-bridge mcp`; see [the MCP server](docs/cli.md#mcp-server).
+
+No device tool is needed. Pair one (such as agent-device or Argent) with the bridge for what it can't reach: system alerts, permission prompts, the keyboard, screenshots, and one real tap per flow. Argent's tap, swipe, screenshot and UI tree tools work next to the bridge as they are. Its debugger tools do too on Expo apps (the bridge uses the dev-tools socket) and on React Native 0.85 and later, which let several debuggers attach. Before 0.85, Metro's debugger socket takes one client at a time, so a bare React Native app on `--transport cdp` and a tool that holds the debugger open (Argent's debugger tools, React Native DevTools) can take it from each other.
 
-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.
+The screen tools measure with Fabric, so they need React Native's New Architecture; on the old one the tools that need positions fail with an error that says so (`snapshot {all: true}` and `findText` still return text, without rects).
 
 ## Docs
 
 - [Built-in tools and restore](docs/built-in-tools.md)
 - [The CLI, flows and the client](docs/cli.md)
 - [Scenarios](docs/scenarios.md): signed-in state, strict network, fixtures, gates
-- [Adapters](docs/adapters.md): TanStack Query, Zustand, MMKV, Expo Router, network
+- [Adapters](docs/adapters.md): TanStack Query, Zustand, Redux, Jotai, MMKV, AsyncStorage, SecureStore, Expo Router, React Navigation, network
 - [WebViews](docs/webviews.md)
 - [Realtime](docs/realtime.md): Ably, socket.io, any other library
+- [Device events](docs/device-events.md): deep links, app state, offline, push notifications, the clock
 - [Security and release builds](docs/security.md)
 - [Benchmarks](docs/benchmarks.md)
 

package/dist/adapters/ably.cjs

@@ -72,6 +72,21 @@ function tapListeners(tap, target, options) {
     };
   }
 }
+function tapOutgoing(tap, target, options) {
+  const methods = target;
+  for (const name of list(options.methods)) {
+    const send = methods[name];
+    if (typeof send !== "function") continue;
+    methods[name] = function(...args) {
+      try {
+        const channel = options.skip?.(this) ? void 0 : options.channel(args);
+        if (channel !== void 0) tap.sent(channel, options.describe(args));
+      } catch {
+      }
+      return send.apply(this, args);
+    };
+  }
+}
 function fakeableConnection(target, options) {
   const methods = target;
   const events = methods?.[options.events];
@@ -116,6 +131,46 @@ function realtimeAdapter(install) {
   };
 }
 
+// src/network/headers.ts
+var SECRET = /auth|cookie|token|secret|session|password|passwd|signature|api-?key|credential|jwt/i;
+
+// src/realtime/snapshot.ts
+var MAX_STRING = 2e3;
+var MAX_ITEMS = 50;
+var MAX_DEPTH = 5;
+var isPlain = (v) => {
+  const proto = Object.getPrototypeOf(v);
+  return proto === Object.prototype || proto === null;
+};
+function snapshot(value, depth = 0) {
+  if (typeof value === "string")
+    return value.length > MAX_STRING ? `${value.slice(0, MAX_STRING)}\u2026 (+${value.length - MAX_STRING} chars)` : value;
+  if (typeof value === "function") return "[function]";
+  if (!value || typeof value !== "object") return value;
+  if (ArrayBuffer.isView(value) || value instanceof ArrayBuffer)
+    return `[${value.constructor.name} ${value.byteLength} bytes]`;
+  if (depth >= MAX_DEPTH) return "[\u2026]";
+  if (Array.isArray(value)) {
+    const items = value.slice(0, MAX_ITEMS).map((v) => snapshot(v, depth + 1));
+    if (value.length > MAX_ITEMS) items.push(`\u2026 (+${value.length - MAX_ITEMS} items)`);
+    return items;
+  }
+  if (value instanceof Date) return value.toISOString();
+  if (!isPlain(value)) return `[${value.constructor?.name ?? "object"}]`;
+  const out = {};
+  for (const key of Object.keys(value).slice(0, MAX_ITEMS))
+    out[key] = snapshot(value[key], depth + 1);
+  return out;
+}
+function redact(value, depth = 0) {
+  if (!value || typeof value !== "object" || depth >= MAX_DEPTH + 1) return value;
+  if (Array.isArray(value)) return value.map((v) => redact(v, depth + 1));
+  const out = {};
+  for (const [key, v] of Object.entries(value))
+    out[key] = SECRET.test(key) ? "[redacted]" : redact(v, depth + 1);
+  return out;
+}
+
 // src/realtime/tap.ts
 var LOG_SIZE = 50;
 var ALL = "*";
@@ -159,6 +214,17 @@ function createRealtimeTap(options = {}) {
     }
     if (!dropped) entry.deliver(message, ...rest);
   }
+  const sent = (channel, summary) => {
+    log.push({
+      at: (/* @__PURE__ */ new Date()).toISOString(),
+      channel,
+      ...summary,
+      ..."data" in summary && { data: snapshot(summary.data) },
+      injected: false,
+      sent: true
+    });
+    if (log.length > LOG_SIZE) log.splice(0, log.length - LOG_SIZE);
+  };
   const wrap = (channel, listener, wrapOptions = {}) => {
     const entry = {
       deliver: listener,
@@ -208,11 +274,11 @@ function createRealtimeTap(options = {}) {
       }))
     },
     [`${ns}.log`]: {
-      description: `Recent messages, real and injected, newest first (last ${LOG_SIZE}). Filter: { channel?, event?, limit? }; clear: true empties the log after reading.`,
+      description: `Recent messages, real, injected, and ones the app sent (sent: true) (socket.emit, Ably publish), newest first (last ${LOG_SIZE}). Filter: { channel?, event?, limit?, full? }; clear: true empties the log after reading. Sent messages are copied and cut, and keys like token, password or authorization show [redacted] unless full: true.`,
       run: (filter = {}) => {
         const entries = log.filter(
           (e) => (!filter.channel || e.channel === filter.channel) && (!filter.event || e.event === filter.event)
-        ).reverse().slice(0, filter.limit ?? 20);
+        ).reverse().slice(0, filter.limit ?? 20).map((e) => e.sent && !filter.full && "data" in e ? { ...e, data: redact(e.data) } : e);
         if (filter.clear) log.length = 0;
         return entries;
       }
@@ -273,7 +339,7 @@ function createRealtimeTap(options = {}) {
         return { state: faked ?? connection.state(), real: connection.state(), faked: faked !== null };
       }
     };
-  return { wrap, tools };
+  return { wrap, sent, tools };
 }
 
 // src/adapters/ably.ts
@@ -349,6 +415,16 @@ var ablyTools = realtimeAdapter(
         channel: () => channel.name,
         accepts: ([filter], message) => accepts(filter, message)
       });
+      tapOutgoing(tap, channel, {
+        methods: "publish",
+        channel: () => channel.name,
+        describe: ([first, second]) => {
+          if (typeof first === "string") return { event: first, data: second };
+          const m = first;
+          if (Array.isArray(m)) return { data: m.map((x) => ({ event: x.name, data: x.data })) };
+          return { event: m?.name, data: m?.data, id: m?.id };
+        }
+      });
       return channel;
     };
     const registry = client.channels;

package/dist/adapters/ably.d.cts

@@ -1,4 +1,4 @@
-import { T as Tools } from '../types-BmpykP1P.cjs';
+import { T as Tools } from '../types-qlwdcGjt.cjs';
 
 /** The fields of an Ably message this adapter reads. */
 type AblyMessageLike = {
@@ -18,6 +18,7 @@ type AblyMessageLike = {
 type AblyChannelLike = {
     name: string;
     state?: string;
+    publish?(...args: never[]): unknown;
     subscribe(...args: never[]): unknown;
     unsubscribe(...args: never[]): unknown;
 };

package/dist/adapters/async-storage.cjs

@@ -0,0 +1,158 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/adapters/async-storage.ts
+var async_storage_exports = {};
+__export(async_storage_exports, {
+  asyncStorageTools: () => asyncStorageTools
+});
+module.exports = __toCommonJS(async_storage_exports);
+
+// src/adapters/storage-undo.ts
+function toStored(tool, key, value) {
+  if (typeof key !== "string" || !key)
+    throw new Error(`${tool} needs the key name as a non-empty string`);
+  if (value === void 0 || value === null)
+    throw new Error(`${tool} needs a value; use the delete tool to remove "${key}"`);
+  const stored = typeof value === "string" ? value : JSON.stringify(value);
+  if (typeof stored !== "string")
+    throw new Error(`${tool} cannot store that value as JSON`);
+  return stored;
+}
+async function change(undo, id, io, value) {
+  let entry = undo.get(id);
+  if (!entry) {
+    const original = io.read();
+    entry = { io, original, last: null };
+    undo.set(id, entry);
+    try {
+      entry.last = await original;
+    } catch (error) {
+      if (undo.get(id) === entry) undo.delete(id);
+      throw error;
+    }
+  } else {
+    await entry.original;
+  }
+  if (value === null) await io.remove();
+  else await io.write(value);
+  entry.last = value;
+}
+async function restore(undo, label) {
+  let restored = 0;
+  const skipped = [];
+  const failed = [];
+  for (const [id, entry] of [...undo]) {
+    try {
+      let original;
+      try {
+        original = await entry.original;
+      } catch {
+        undo.delete(id);
+        continue;
+      }
+      if (await entry.io.read() !== entry.last) {
+        undo.delete(id);
+        skipped.push(label(id));
+        continue;
+      }
+      if (original === null) await entry.io.remove();
+      else await entry.io.write(original);
+      undo.delete(id);
+      restored += 1;
+    } catch {
+      failed.push(label(id));
+    }
+  }
+  return { restored, skipped, failed };
+}
+function describeRestore(r, what) {
+  if (r.failed.length)
+    throw new Error(
+      `Restored ${r.restored}, could not restore: ${r.failed.join(", ")}. ${what} stay pending; run it again.`
+    );
+  return r.skipped.length ? { restored: r.restored, skipped: r.skipped } : r.restored;
+}
+
+// src/adapters/async-storage.ts
+var LIST_LIMIT = 50;
+var VALUE_CHARS = 200;
+var originals = /* @__PURE__ */ new WeakMap();
+var clip = (value) => value !== null && value.length > VALUE_CHARS ? `${value.slice(0, VALUE_CHARS)}\u2026 (${value.length} chars)` : value;
+function asyncStorageTools(storage) {
+  let undo = originals.get(storage);
+  if (!undo) originals.set(storage, undo = /* @__PURE__ */ new Map());
+  const pending = undo;
+  const apply = (key, value) => change(
+    pending,
+    key,
+    {
+      read: () => storage.getItem(key),
+      write: (v) => storage.setItem(key, v),
+      remove: () => storage.removeItem(key)
+    },
+    value
+  );
+  return {
+    "asyncStorage.list": {
+      description: "Keys with their values, cut to 200 characters. {limit} (default 50) caps the rows, {prefix} filters keys. Returns {total, keys}.",
+      run: async (options) => {
+        const all = (await storage.getAllKeys()).filter(
+          (k) => !options?.prefix || k.startsWith(options.prefix)
+        );
+        const shown = all.slice(0, options?.limit ?? LIST_LIMIT);
+        const rows = storage.multiGet ? await storage.multiGet(shown) : await Promise.all(
+          shown.map(async (k) => [k, await storage.getItem(k)])
+        );
+        return {
+          total: all.length,
+          keys: Object.fromEntries(rows.map(([k, v]) => [k, clip(v)]))
+        };
+      }
+    },
+    "asyncStorage.get": {
+      description: "A key's string value (null when missing); parsed as JSON when {json:true}.",
+      run: async (key, options) => {
+        const raw = await storage.getItem(key);
+        return options?.json && raw !== null ? JSON.parse(raw) : raw;
+      }
+    },
+    "asyncStorage.set": {
+      description: "Set a value. Objects, arrays, numbers and booleans are stored as JSON strings.",
+      run: async (key, value) => {
+        await apply(key, toStored("asyncStorage.set", key, value));
+        return true;
+      }
+    },
+    "asyncStorage.delete": {
+      description: "Delete a key.",
+      run: async (key) => {
+        if (typeof key !== "string" || !key)
+          throw new Error("asyncStorage.delete needs the key name as a non-empty string");
+        await apply(key, null);
+        return true;
+      }
+    },
+    "asyncStorage.restore": {
+      pending: () => pending.size > 0,
+      description: "Undo the agent: put back keys changed with asyncStorage.set or asyncStorage.delete, deleting ones that did not exist. Returns how many; a key the app has written since is left alone and returned in {skipped}. Lost when the JS reloads: restore before app.reload.",
+      run: async () => describeRestore(await restore(pending, (id) => id), "Those keys")
+    }
+  };
+}

package/dist/adapters/async-storage.d.cts

@@ -0,0 +1,14 @@
+import { T as Tools } from '../types-qlwdcGjt.cjs';
+
+/** The AsyncStorage surface this adapter uses. */
+type AsyncStorageLike = {
+    getAllKeys: () => Promise<readonly string[]>;
+    getItem: (key: string) => Promise<string | null>;
+    setItem: (key: string, value: string) => Promise<void>;
+    removeItem: (key: string) => Promise<void>;
+    multiGet?: (keys: readonly string[]) => Promise<readonly (readonly [string, string | null])[]>;
+};
+/** Read and write AsyncStorage. Values are returned as they are: wire a storage without secrets. */
+declare function asyncStorageTools(storage: AsyncStorageLike): Tools;
+
+export { type AsyncStorageLike, asyncStorageTools };