@avasapp/agent-bridge 0.1.0 → 0.2.0

package/README.md

@@ -1,25 +1,29 @@
 # @avasapp/agent-bridge
 
-Let coding agents drive a running React Native app directly. Seed data, flip flags, navigate and check the screen in **milliseconds**, without tapping through the app.
+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.
 
 ## Demo
 
-![An agent hides a tab, turns on dark mode, fills in a form, seeds data, checks the screen and undoes it all](example/media/demo.gif)
+![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)
 
-<!-- TODO: upload example/media/demo-x.mp4 in GitHub's web editor and put the URL it gives here. GitHub only plays an mp4 uploaded that way. -->
+The same checks on [the example app](example) in Expo Go, both at real speed, all on one Mac:
 
-[`example/flows/demo.mjs`](example/flows/demo.mjs) driving [the example app](example) in Expo Go, all on one Mac:
+- **agent-device alone** ([`demo-agent-device.mjs`](example/flows/demo-agent-device.mjs)) taps and types through the UI, edits the fake backend and reloads to change the flag and the data, and asks the realtime server to push a message.
+- **agent-device + agent-bridge** ([`demo.mjs`](example/flows/demo.mjs)) makes each change with one call, then undoes them all with `bridge.restore`.
+
+agent-device 0.21.15 won't press or fill most of this screen by selector on the iOS 27 simulator ([callstack/agent-device#2996](https://github.com/callstack/agent-device/issues/2996)), so the agent-device side looks up each element's frame and taps its centre. That adds one lookup per tap or fill.
 
 | Call | Round trip |
 | --- | --- |
 | `bridge.ping` | 1–4 ms |
 | `screen.findText`, `screen.waitFor` (already there) | 3–9 ms |
-| `screen.fill`, `screen.press` | 20–65 ms, render included |
-| `query.pin`, `store.call`, `router.navigate` | 11–44 ms, render included |
-| 14 steps, no pauses | 0.8 s wall, 0.4 s of it waiting on a save |
+| `screen.fill`, `screen.press` | 20–120 ms, render included |
+| `query.pin`, `store.call`, `router.navigate` | 11–55 ms, render included |
+| 19 steps, no pauses | 1.3–1.5 s wall, 0.9 s of it waiting on the fake backend |
 
 ```
-14 steps, all local on one Mac:   0.8 s wall with no pauses
+19 steps with agent-bridge:       1.4 s wall
+same checks, agent-device alone:  22.4 s wall
 same flow from another machine:   ~57 ms per call (network)
 same screen check via a11y tree:  450–970 ms
 ```
@@ -32,6 +36,21 @@ Works on Expo (dev-tools socket) and on bare React Native (CDP over Metro). Dev
 bun add -d @avasapp/agent-bridge   # or npm / yarn / pnpm
 ```
 
+### Teach your agent
+
+The package ships an agent skill that tells your agent when and how to drive the app. Add it to Claude Code, Cursor, Codex and other agents:
+
+```sh
+npx skills add avas-app/agent-bridge
+```
+
+In Claude Code you can install it as a plugin instead:
+
+```
+/plugin marketplace add avas-app/agent-bridge
+/plugin install agent-bridge@agent-bridge
+```
+
 ## In the app
 
 Mount the hook in a file that only runs in development. You choose every tool; adapters for common libraries are one import away.
@@ -123,9 +142,77 @@ No device tool is needed. Pair one (such as agent-device) with the bridge for wh
 | `@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/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.
 
+## Realtime
+
+The realtime tools let an agent see realtime messages, send the app a fake one, and stop real ones from overwriting a state it set up. They work with any library.
+
+With Ably or socket.io, pass the client where you create it, **before the app subscribes**. Listeners added earlier stay invisible.
+
+```ts
+import { ablyTools } from '@avasapp/agent-bridge/ably'
+import { socketIoTools } from '@avasapp/agent-bridge/socket.io'
+
+export const ably = new Ably.Realtime(options)
+export const realtimeDevTools = ablyTools(ably)     // or socketIoTools(socket)
+
+// in AgentBridge: tools: { ...realtimeDevTools, ... }
+```
+
+With any other library, or your own subscribe layer, wrap each listener:
+
+```ts
+import { createRealtimeTap } from '@avasapp/agent-bridge/realtime'
+
+export const realtimeTap = createRealtimeTap()   // tools: { ...realtimeTap.tools }
+
+export function subscribe(channel: string, onMessage: (message: Message) => void) {
+  const { listener, unsubscribe } = realtimeTap.wrap(channel, onMessage)
+  const off = client.subscribe(channel, listener)
+  return () => { off(); unsubscribe() }
+}
+```
+
+```sh
+npx agent-bridge call realtime.channels
+npx agent-bridge call realtime.mute '"order-42"'                       # the real feed goes quiet
+npx agent-bridge call realtime.emit '["order-42", {"name": "status", "data": {"status": "arrived"}}]'
+npx agent-bridge call realtime.log '{"channel": "order-42"}'
+npx agent-bridge call realtime.connection '"disconnected"'             # null goes back
+```
+
+- `realtime.emit` runs the app's own handlers. Ably gets an Ably message (`{ id, name, data, timestamp }` plus what you pass), socket.io gets the arguments after the event name (`["chat", "a", "b"]` calls `listener("a", "b")`), and `createRealtimeTap` gets the value as is, or what its `toMessage` option builds.
+- `realtime.mute` drops real messages; injected ones still get through unless you pass `{ "dropInjected": true }`. `"*"` mutes every channel.
+- `realtime.connection` fakes a state through the client's own events (Ably's `connection.on` and `connection.state`, socket.io's `connect` / `disconnect`) and drops real messages until the state is `connected` again. Ably channel states don't follow. `socket.connected` keeps its real value: socket.io reads it itself, and faking it would hold real traffic back until the next reconnect.
+- `realtime.log` keeps the last 50 messages, and logs a message once however many listeners get it.
+- `createRealtimeTap` takes `describe` (what to log), `toMessage` (what `emit` delivers), `channelInfo` (extras for `realtime.channels`), `connection` (to add `realtime.connection`) and `namespace` (for a second tap).
+- socket.io `onAny` listeners don't get injected events.
+
+### Writing an adapter
+
+To patch a client instead of wrapping each listener, name its add and remove methods and say which channel a call is for. `tapListeners` handles the bookkeeping and every remove form (all, by event, by listener). `realtimeAdapter` patches each client once. A Pusher-style `channel.bind(event, fn)` is this much:
+
+```ts
+import { createRealtimeTap, realtimeAdapter, tapListeners } from '@avasapp/agent-bridge/realtime'
+
+export const pusherTools = realtimeAdapter((channel: Channel, options: {}) => {
+  const tap = createRealtimeTap()
+  tapListeners(tap, channel, {
+    add: 'bind',
+    remove: 'unbind',
+    channel: ([event]) => `${channel.name}:${event}`,   // undefined leaves a call alone
+  })
+  return tap
+})
+```
+
+Pass `accepts` when a listener filters by event, and `message: 'args'` when the message is every argument (as in socket.io). `fakeableConnection(client, { property, events, states, announce })` adds `realtime.connection`: it fakes the state property and silences the client's own change events while a fake is on. Pass `fakeProperty: false` if the client reads that property itself to decide whether to deliver or send. [`src/adapters/`](src/adapters) has the Ably and socket.io adapters built this way.
+
 ## Transports
 
 | | Expo dev-tools socket | CDP |
@@ -149,6 +236,7 @@ npx agent-bridge assert-absent path/to/main.jsbundle
 - **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.

package/dist/adapters/ably.cjs

@@ -0,0 +1,344 @@
+"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/ably.ts
+var ably_exports = {};
+__export(ably_exports, {
+  ablyTools: () => ablyTools
+});
+module.exports = __toCommonJS(ably_exports);
+
+// src/realtime/patch.ts
+var list = (names) => Array.isArray(names) ? names : [names];
+var sameKey = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+function split(args) {
+  const last = args[args.length - 1];
+  return typeof last === "function" ? { key: args.slice(0, -1), listener: last } : { key: args };
+}
+function tapListeners(tap, target, options) {
+  const methods = target;
+  const tracked = [];
+  const spread = options.message === "args";
+  for (const name of list(options.add)) {
+    const add = methods[name];
+    if (typeof add !== "function") continue;
+    methods[name] = function(...args) {
+      const { key, listener: original } = split(args);
+      const channel = original && options.channel(key);
+      if (!original || channel === void 0) return add.apply(this, args);
+      const accepts2 = options.accepts;
+      const { listener, unsubscribe } = tap.wrap(
+        channel,
+        (message, ...rest) => spread ? original.apply(target, message) : original.call(target, message, ...rest),
+        accepts2 ? { accepts: (m) => accepts2(key, m) } : {}
+      );
+      const wrapped = spread ? (...received) => listener(received) : (message, ...rest) => listener(message, ...rest);
+      tracked.push({ key, original, wrapped, unsubscribe });
+      return add.apply(this, [...key, wrapped]);
+    };
+  }
+  for (const name of list(options.remove)) {
+    const remove = methods[name];
+    if (typeof remove !== "function") continue;
+    methods[name] = function(...args) {
+      const { key, listener } = split(args);
+      const hits = tracked.filter(
+        (t) => (!listener || t.original === listener || t.original.fn === listener) && (!key.length || sameKey(t.key, key))
+      );
+      for (const hit of hits) {
+        tracked.splice(tracked.indexOf(hit), 1);
+        hit.unsubscribe();
+      }
+      if (!listener || !hits.length) return remove.apply(this, args);
+      let result;
+      for (const hit of hits) result = remove.apply(this, [...hit.key, hit.wrapped]);
+      return result;
+    };
+  }
+}
+function fakeableConnection(target, options) {
+  const methods = target;
+  const events = methods?.[options.events];
+  if (!methods || typeof events !== "function") return void 0;
+  const read = options.read ?? String;
+  const write = options.write ?? ((state) => state);
+  const values = methods;
+  let fake = null;
+  let real = values[options.property];
+  const readReal = () => read(options.fakeProperty === false ? values[options.property] : real);
+  if (options.fakeProperty !== false)
+    Object.defineProperty(target, options.property, {
+      configurable: true,
+      enumerable: true,
+      get: () => fake === null ? real : write(fake),
+      set: (value) => {
+        real = value;
+      }
+    });
+  methods[options.events] = function(...args) {
+    return fake === null ? events.apply(this, args) : void 0;
+  };
+  const emit = (...args) => void events.apply(target, args);
+  return {
+    state: readReal,
+    states: options.states,
+    live: options.live,
+    fake: (state, previous) => {
+      fake = state;
+      const current = state ?? readReal();
+      if (current !== previous)
+        options.announce(emit, { current, previous, faked: state !== null });
+    }
+  };
+}
+function realtimeAdapter(install) {
+  const taps = /* @__PURE__ */ new WeakMap();
+  return (client, options = {}) => {
+    let tools = taps.get(client);
+    if (!tools) taps.set(client, tools = install(client, options).tools);
+    return tools;
+  };
+}
+
+// src/realtime/tap.ts
+var LOG_SIZE = 50;
+var ALL = "*";
+var defaultDescribe = (message) => {
+  const id = message?.id;
+  return typeof id === "string" ? { data: message, id } : { data: message };
+};
+var sameMessage = (a, b) => a === b || Array.isArray(a) && Array.isArray(b) && a.length === b.length && a.every((v, i) => v === b[i]);
+function createRealtimeTap(options = {}) {
+  const ns = options.namespace ?? "realtime";
+  const describe = options.describe ?? defaultDescribe;
+  const toMessage2 = options.toMessage ?? ((values) => values[0]);
+  const connection = options.connection;
+  const live = connection?.live ?? "connected";
+  const channels = /* @__PURE__ */ new Map();
+  const mutes = /* @__PURE__ */ new Map();
+  const log = [];
+  const last = /* @__PURE__ */ new Map();
+  let injectedCount = 0;
+  let faked = null;
+  const muteFor = (channel) => mutes.get(channel) ?? mutes.get(ALL);
+  const liveChannels = () => [...channels.keys()].join(", ") || "none";
+  function record(channel, message, injected, dropped) {
+    log.push({
+      at: (/* @__PURE__ */ new Date()).toISOString(),
+      channel,
+      ...describe(message),
+      injected,
+      ...dropped && { dropped }
+    });
+    if (log.length > LOG_SIZE) log.splice(0, log.length - LOG_SIZE);
+  }
+  function receive(channel, entry, message, rest) {
+    const previous = last.get(channel);
+    const dropped = muteFor(channel) ? "muted" : faked !== null && faked !== live ? "connection" : void 0;
+    if (previous && !previous.seen.has(entry) && sameMessage(previous.message, message)) {
+      previous.seen.add(entry);
+    } else {
+      last.set(channel, { message, seen: /* @__PURE__ */ new Set([entry]) });
+      record(channel, message, false, dropped);
+    }
+    if (!dropped) entry.deliver(message, ...rest);
+  }
+  const wrap = (channel, listener, wrapOptions = {}) => {
+    const entry = {
+      deliver: listener,
+      accepts: wrapOptions.accepts
+    };
+    let entries = channels.get(channel);
+    if (!entries) channels.set(channel, entries = /* @__PURE__ */ new Set());
+    entries.add(entry);
+    return {
+      listener: (message, ...rest) => receive(channel, entry, message, rest),
+      unsubscribe: () => {
+        const current = channels.get(channel);
+        if (!current?.delete(entry) || current.size) return;
+        channels.delete(channel);
+        last.delete(channel);
+      }
+    };
+  };
+  function setMute(channel, mute) {
+    if (typeof channel !== "string" || !channel)
+      throw new Error(`Pass a channel name, or "${ALL}" for every channel`);
+    if (mute) mutes.set(channel, mute);
+    else if (channel === ALL) mutes.clear();
+    else mutes.delete(channel);
+    return { muted: [...mutes.keys()] };
+  }
+  function setConnection(conn, state) {
+    const shown = faked ?? conn.state();
+    if (state !== null && typeof state !== "string")
+      throw new Error('Pass a state such as "disconnected", or null for the real one');
+    if (state !== null && conn.states && !conn.states.includes(state))
+      throw new Error(
+        `Unknown state "${state}". Known: ${conn.states.join(", ")}`
+      );
+    if (state === faked) return;
+    faked = state;
+    conn.fake(state, shown);
+  }
+  const tools = {
+    [`${ns}.channels`]: {
+      description: "Channels the app listens on: listener count, muted, and what the library says about each.",
+      run: () => [...channels].map(([name, entries]) => ({
+        name,
+        listeners: entries.size,
+        muted: Boolean(muteFor(name)),
+        ...options.channelInfo?.(name)
+      }))
+    },
+    [`${ns}.log`]: {
+      description: `Recent messages, real and injected, newest first (last ${LOG_SIZE}). Filter: { channel?, event?, limit? }; clear: true empties the log after reading.`,
+      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);
+        if (filter.clear) log.length = 0;
+        return entries;
+      }
+    },
+    [`${ns}.emit`]: {
+      description: "Deliver a fake message to every listener on a channel: [channel, message]. Runs the app's own handlers. Returns { id, delivered }.",
+      run: (channel, ...values) => {
+        const entries = channels.get(channel);
+        if (!entries?.size)
+          throw new Error(
+            `Nothing listens on "${channel}". Live channels: ${liveChannels()}`
+          );
+        injectedCount += 1;
+        const message = toMessage2(values, {
+          channel,
+          id: `agent-bridge-${injectedCount}`
+        });
+        const id = describe(message).id;
+        if (muteFor(channel)?.dropInjected) {
+          record(channel, message, true, "muted");
+          return { id, delivered: 0 };
+        }
+        record(channel, message, true);
+        let delivered = 0;
+        for (const entry of [...entries]) {
+          if (entry.accepts && !entry.accepts(message)) continue;
+          entry.deliver(message);
+          delivered += 1;
+        }
+        return { id, delivered };
+      }
+    },
+    [`${ns}.mute`]: {
+      description: `Drop real messages on a channel ("${ALL}" for all) until unmuted. Injected messages still get through unless { dropInjected: true }.`,
+      run: (channel, muteOptions = {}) => setMute(channel, { dropInjected: Boolean(muteOptions.dropInjected) })
+    },
+    [`${ns}.unmute`]: {
+      description: `Stop dropping messages on a channel ("${ALL}" for all).`,
+      run: (channel) => setMute(channel, null)
+    },
+    [`${ns}.restore`]: {
+      description: "Undo the agent: unmute every channel and go back to the real connection state.",
+      run: () => {
+        const unmuted = [...mutes.keys()];
+        mutes.clear();
+        const connectionFaked = faked !== null;
+        if (connection && connectionFaked) setConnection(connection, null);
+        return { unmuted, connectionFaked };
+      }
+    }
+  };
+  if (connection)
+    tools[`${ns}.connection`] = {
+      description: `The connection state, or fake one: [state] shows the app that state${connection.states ? ` (${connection.states.join(", ")})` : ""} and drops real messages unless it is "${live}"; [null] goes back to the real one.`,
+      run: (...args) => {
+        if (args.length) setConnection(connection, args[0] ?? null);
+        return { state: faked ?? connection.state(), real: connection.state(), faked: faked !== null };
+      }
+    };
+  return { wrap, tools };
+}
+
+// src/adapters/ably.ts
+var CONNECTION_STATES = [
+  "initialized",
+  "connecting",
+  "connected",
+  "disconnected",
+  "suspended",
+  "closing",
+  "closed",
+  "failed"
+];
+function accepts(filter, message) {
+  if (typeof filter === "string") return message.name === filter;
+  if (Array.isArray(filter)) return filter.includes(message.name);
+  if (filter && typeof filter === "object") {
+    const { name, clientId } = filter;
+    return (name === void 0 || name === message.name) && (clientId === void 0 || clientId === message.clientId);
+  }
+  return true;
+}
+function toMessage(values, { id }) {
+  const [input] = values;
+  if (!input || typeof input !== "object" || Array.isArray(input))
+    throw new Error('Pass the message as { name, data }, e.g. ["chat", { "name": "typing", "data": { "user": "sam" } }]');
+  return { id, timestamp: Date.now(), ...input };
+}
+var ablyTools = realtimeAdapter(
+  (client, options) => {
+    const channels = /* @__PURE__ */ new Map();
+    const tap = createRealtimeTap({
+      namespace: options.namespace,
+      describe: (m) => ({ event: m.name, data: m.data, id: m.id }),
+      toMessage,
+      channelInfo: (name) => ({ state: channels.get(name)?.state }),
+      // ably-js's connection is an event emitter; `emit` isn't in its public types.
+      connection: fakeableConnection(client.connection, {
+        property: "state",
+        events: "emit",
+        states: CONNECTION_STATES,
+        announce: (emit, { current, previous, faked }) => emit(current, {
+          previous,
+          current,
+          event: current,
+          ...faked && { reason: { message: "Faked by agent-bridge" } }
+        })
+      })
+    });
+    const patch = (channel) => {
+      if (!channel || channels.get(channel.name) === channel) return channel;
+      channels.set(channel.name, channel);
+      tapListeners(tap, channel, {
+        add: "subscribe",
+        remove: "unsubscribe",
+        channel: () => channel.name,
+        accepts: ([filter], message) => accepts(filter, message)
+      });
+      return channel;
+    };
+    const registry = client.channels;
+    const get = registry.get;
+    registry.get = function(...args) {
+      return patch(get.apply(this, args));
+    };
+    for (const channel of Object.values(registry.all ?? {})) patch(channel);
+    return tap;
+  }
+);

package/dist/adapters/ably.d.cts

@@ -0,0 +1,37 @@
+import { T as Tools } from '../types-C6DUUHnB.cjs';
+
+/** The fields of an Ably message this adapter reads. */
+type AblyMessageLike = {
+    id?: string;
+    name?: string;
+    data?: unknown;
+    clientId?: string;
+};
+/** The Ably realtime channel surface this adapter uses. */
+type AblyChannelLike = {
+    name: string;
+    state?: string;
+    subscribe(...args: never[]): unknown;
+    unsubscribe(...args: never[]): unknown;
+};
+/** An Ably realtime client (`new Ably.Realtime(...)`), typed structurally. */
+type AblyRealtimeLike = {
+    channels: {
+        get(name: string, ...rest: never[]): AblyChannelLike;
+    };
+    connection?: {
+        state: string;
+    };
+};
+type AblyToolsOptions = {
+    /** Tool name prefix. Defaults to "realtime". */
+    namespace?: string;
+};
+/**
+ * See, fake and drop Ably messages: `realtime.*`. Patches the client, so call
+ * it where you create the client, before the app subscribes; listeners added
+ * earlier stay invisible. Calling it again with the same client is free.
+ */
+declare const ablyTools: (client: AblyRealtimeLike, options?: AblyToolsOptions | undefined) => Tools;
+
+export { type AblyChannelLike, type AblyMessageLike, type AblyRealtimeLike, type AblyToolsOptions, ablyTools };