@avasapp/agent-bridge 0.1.0 → 0.2.0

package/dist/realtime/index.cjs

@@ -0,0 +1,279 @@
+"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/realtime/index.ts
+var realtime_exports = {};
+__export(realtime_exports, {
+  createRealtimeTap: () => createRealtimeTap,
+  fakeableConnection: () => fakeableConnection,
+  realtimeAdapter: () => realtimeAdapter,
+  tapListeners: () => tapListeners
+});
+module.exports = __toCommonJS(realtime_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 accepts = options.accepts;
+      const { listener, unsubscribe } = tap.wrap(
+        channel,
+        (message, ...rest) => spread ? original.apply(target, message) : original.call(target, message, ...rest),
+        accepts ? { accepts: (m) => accepts(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 toMessage = 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 = toMessage(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 };
+}

package/dist/realtime/index.d.cts

@@ -0,0 +1,138 @@
+import { T as Tools } from '../types-C6DUUHnB.cjs';
+
+/** How a message shows up in `realtime.log`. */
+type MessageSummary = {
+    /** The event or message name, when the library has one. */
+    event?: string;
+    data?: unknown;
+    id?: string;
+};
+/** Lets the agent fake the client's connection state. */
+type RealtimeConnection = {
+    /** The client's real state, e.g. "connected". */
+    state: () => string;
+    /**
+     * Show `state` to the app instead of the real one, as if the client had
+     * moved there from `previous`. `null` goes back to the real state.
+     */
+    fake: (state: string | null, previous: string) => void;
+    /** States the agent may pick, for error messages. */
+    states?: readonly string[];
+    /** The state in which real messages flow. Defaults to "connected". */
+    live?: string;
+};
+type RealtimeTapOptions<M> = {
+    /** Tool name prefix. Defaults to "realtime"; set it when an app has two taps. */
+    namespace?: string;
+    /** What to log for a message. Defaults to the message as `data`, with its `id` if it has one. */
+    describe?: (message: M) => MessageSummary;
+    /**
+     * Builds the message `realtime.emit` delivers, from the JSON values the
+     * agent passed after the channel. Defaults to the first value.
+     */
+    toMessage?: (values: unknown[], context: {
+        channel: string;
+        id: string;
+    }) => M;
+    /** Extra fields for `realtime.channels`, e.g. the library's channel state. */
+    channelInfo?: (channel: string) => Record<string, unknown>;
+    /** Adds `realtime.connection`, to fake connection states. */
+    connection?: RealtimeConnection;
+};
+type WrapOptions<M> = {
+    /**
+     * Whether this listener would get the message from the library, e.g. an
+     * event-name filter. Injected messages skip listeners that say no.
+     */
+    accepts?: (message: M) => boolean;
+};
+type RealtimeTap<M> = {
+    /**
+     * Wraps the app's listener for `channel`. Hand `listener` to the library
+     * instead of the original, and call `unsubscribe` when the app unsubscribes.
+     * Arguments after the message reach the app's listener untouched.
+     */
+    wrap: (channel: string, listener: (message: M, ...rest: never[]) => void, options?: WrapOptions<M>) => {
+        listener: (message: M, ...rest: unknown[]) => void;
+        unsubscribe: () => void;
+    };
+    /** `realtime.*`, or `<namespace>.*`. */
+    tools: Tools;
+};
+type RealtimeLogEntry = MessageSummary & {
+    at: string;
+    channel: string;
+    injected: boolean;
+    /** Why the app didn't get it. */
+    dropped?: 'muted' | 'connection';
+};
+/**
+ * Lets the agent see, fake and drop realtime messages, whatever library
+ * delivers them. Wrap each listener with `wrap`, and add `tools` to the bridge.
+ */
+declare function createRealtimeTap<M = unknown>(options?: RealtimeTapOptions<M>): RealtimeTap<M>;
+
+type TapListenersOptions<M> = {
+    /** Methods that add a listener, e.g. "on" or ["on", "addEventListener"]. */
+    add: string | string[];
+    /** Methods that remove one, e.g. "off". */
+    remove: string | string[];
+    /**
+     * The channel a call is for, from the arguments before the listener (its
+     * "key", e.g. the event name). Return undefined to leave the call alone.
+     */
+    channel: (key: unknown[]) => string | undefined;
+    /** Whether a listener added with `key` would get `message`, e.g. an event-name filter. */
+    accepts?: (key: unknown[], message: M) => boolean;
+    /**
+     * "first" (default): the message is the listener's first argument, and the
+     * rest reach the listener untouched. "args": every argument, as an array.
+     */
+    message?: 'first' | 'args';
+};
+/**
+ * Routes a client's add/remove-listener methods through `tap`, e.g.
+ * `socket.on` / `socket.off` or `channel.subscribe` / `channel.unsubscribe`.
+ * Removing works in every usual form: all, by key, by listener, or both.
+ */
+declare function tapListeners<M>(tap: RealtimeTap<M>, target: object, options: TapListenersOptions<M>): void;
+type FakeableConnectionOptions = {
+    /** The property holding the state, e.g. "state" or "connected". */
+    property: string;
+    /** The method the client tells listeners about changes with. Silent while a state is faked. */
+    events: string;
+    /** States the agent may pick. */
+    states: readonly string[];
+    /** The state in which real messages flow. Defaults to "connected". */
+    live?: string;
+    /** Property value to state name. Defaults to the value itself. */
+    read?: (value: unknown) => string;
+    /** State name to property value. Defaults to the name itself. */
+    write?: (state: string) => unknown;
+    /**
+     * false leaves the property showing the real state. Use it when the client
+     * reads the property itself to decide whether to deliver or send (socket.io
+     * does), or faking it would hold real traffic back. Defaults to true.
+     */
+    fakeProperty?: boolean;
+    /** Tells the app about a change, through the client's own (unsilenced) events method. */
+    announce: (emit: (...args: unknown[]) => void, change: {
+        current: string;
+        previous: string;
+        faked: boolean;
+    }) => void;
+};
+/**
+ * Lets `realtime.connection` fake a client's connection state: the property
+ * reads the fake (unless `fakeProperty: false`), real changes still land
+ * underneath but aren't announced, and going back announces the real state. Undefined when `target` lacks
+ * the events method, so the tool is left out rather than broken.
+ */
+declare function fakeableConnection(target: object | undefined, options: FakeableConnectionOptions): RealtimeConnection | undefined;
+/**
+ * Turns an install function into an adapter's `xxxTools(client, options)`.
+ * The client is patched on the first call; later calls return the same tools.
+ */
+declare function realtimeAdapter<C extends object, O extends object>(install: (client: C, options: O) => Pick<RealtimeTap<unknown>, 'tools'>): (client: C, options?: O) => Tools;
+
+export { type FakeableConnectionOptions, type MessageSummary, type RealtimeConnection, type RealtimeLogEntry, type RealtimeTap, type RealtimeTapOptions, type TapListenersOptions, type WrapOptions, createRealtimeTap, fakeableConnection, realtimeAdapter, tapListeners };

package/entries/ably.cjs

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

package/entries/realtime.cjs

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

package/entries/socket.io.cjs

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

package/package.json

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

package/skills/agent-bridge/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: agent-bridge
-description: "Drive a running React Native or Expo dev build directly through @avasapp/agent-bridge: see what's on screen, fill in forms, press buttons, seed query data, flip feature flags, set store state, navigate, mock the network and undo it all, in milliseconds per call instead of tapping through the app. Use whenever you need the app in a particular state to test a change, or need to verify what a screen shows."
+description: "Drive a running React Native or Expo dev build directly through @avasapp/agent-bridge: see what's on screen, fill in forms, press buttons, seed query data, flip feature flags, set store state, navigate, mock the network, fake realtime messages and undo it all, in milliseconds per call instead of tapping through the app. Pairs with agent-device, which opens the app and covers native UI, real taps and screenshots. Use whenever you need the app in a particular state to test a change, or need to verify what a screen shows."
 ---
 
 # Driving an app with agent-bridge
@@ -8,6 +8,22 @@ description: "Drive a running React Native or Expo dev build directly through @a
 The app mounts `useAgentBridge({ tools })` in a dev build. You call those tools
 by name. Nothing is tapped, so there is no setup to click through.
 
+## Pair it with agent-device
+
+agent-bridge works inside the app's JavaScript; agent-device works the device.
+Use both, each for what it's good at:
+
+| agent-bridge | agent-device |
+| --- | --- |
+| Put the app in a state: flags, query data, store values, network mocks, realtime messages | Install and open the app, reload, relaunch |
+| Navigate, fill forms, press buttons, check text on screen | System alerts, permission prompts, native sheets, the keyboard |
+| Undo it all with `bridge.restore` | Screenshots, recordings, one real tap to prove the UI responds |
+
+A typical run: `agent-device open` the app, set up and check the screen with
+agent-bridge, then finish with one real tap or a screenshot from agent-device.
+Don't tap through setup screens or edit backend data to reach a state that one
+bridge call can set.
+
 ## Start a session
 
 ```sh
@@ -32,7 +48,7 @@ npx agent-bridge call screen.waitFor '"Name is required"'      # {"gone": true}
 
 `press` and `fill` return once the app has rendered the result, so the next
 check sees it. `fill` skips the keyboard: autocorrect and native-only input
-behaviour need one real typing step from your device tool.
+behaviour need one real typing step from agent-device.
 
 ## Get the app into a state
 
@@ -48,6 +64,25 @@ npx agent-bridge call net.log
 Arguments are a JSON array (or a single JSON value). Read the current value
 first (`query.get`, `store.get`) and change only what you need.
 
+## Realtime messages
+
+If the app has `realtime.*` tools, you can see its realtime messages and fake
+them instead of waiting for a backend to send one:
+
+```sh
+npx agent-bridge call realtime.channels                         # what the app listens on
+npx agent-bridge call realtime.log '{"channel": "chat"}'        # recent messages, real and faked
+npx agent-bridge call realtime.mute '"chat"'                    # stop real ones overwriting your state
+npx agent-bridge call realtime.emit '["chat", {"name": "message", "data": {"text": "hi"}}]'
+npx agent-bridge call realtime.connection '"disconnected"'      # null goes back to the real state
+```
+
+Copy the shape of a real message from `realtime.log` before you emit one. With
+Ably, pass `{ name, data }`; with socket.io, pass the arguments after the
+channel (the event name). Muting still lets your emitted messages through.
+`emit` fails and lists the live channels when nothing listens on yours: open
+the screen that subscribes first.
+
 ## Watch for errors
 
 Every reply carries errors the app logged or threw since the previous reply,
@@ -78,12 +113,13 @@ npx agent-bridge run flow.mjs --strict    # --strict fails if the app logged an
 npx agent-bridge session stop             # runs bridge.restore; --keep leaves the app as is
 ```
 
-`bridge.restore` unpins queries, puts back store and MMKV values and removes
-network mocks, so the next run starts from the real state.
+`bridge.restore` unpins queries, puts back store and MMKV values, removes
+network mocks, unmutes realtime channels and ends a faked connection state, so
+the next run starts from the real state.
 
 ## Traps
 
 - Run next to the simulator. From another machine every call pays the network.
 - It can't see native UI (system alerts, permission prompts, native sheets) or
-  overlap. Finish a flow with one real UI check or screenshot from your device tool.
+  overlap. Finish a flow with one real UI check or screenshot from agent-device.
 - With several apps on one Metro, pass `--device`.