@avasapp/agent-bridge 0.1.0

package/dist/runtime/index.d.cts

@@ -0,0 +1,69 @@
+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';
+
+/**
+ * Works in any React Native app served by Metro. The client evaluates one fixed
+ * entry point with an ASCII-only JSON payload, and the app pushes the result
+ * back through a CDP binding (Hermes can't `awaitPromise` RN's promises).
+ */
+declare function cdpTransport(): Transport;
+
+type SettleResult = {
+    commits: number;
+    ms: number;
+};
+/**
+ * Resolves once React has committed the renders queued so far: after a tick
+ * (TanStack Query notifies on a timeout), then until a frame passes with no
+ * commit and nothing queued. Returns right away when nothing was queued, and
+ * gives up after `maxMs` (default 500).
+ */
+declare function settle(options?: {
+    maxMs?: number;
+}): Promise<SettleResult>;
+
+type Rect = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+
+type ElementKind = 'button' | 'input' | 'text' | 'view';
+type ScreenElement = {
+    kind: ElementKind;
+    text?: string;
+    testID?: string;
+    label?: string;
+    placeholder?: string;
+    value?: string;
+    editable?: boolean;
+    role?: string;
+    disabled?: boolean;
+    rect: Rect | null;
+    /** Only in `screen.snapshot({ all: true })`. */
+    onScreen?: boolean;
+};
+
+/**
+ * What to act on. A string tries testID, then label, then placeholder, then
+ * visible text (exact, then substring). An object must match every field it
+ * sets; `index` picks one of several matches.
+ */
+type Target = string | {
+    testID?: string;
+    label?: string;
+    placeholder?: string;
+    text?: string;
+    index?: number;
+};
+
+/** Starts the bridge outside React. Returns a function that stops it. */
+declare function startAgentBridge(options?: AgentBridgeOptions): () => void;
+/**
+ * Exposes `tools` to coding agents while mounted. Tools are read on every call,
+ * so passing a fresh object each render is fine. Transports start once.
+ */
+declare function useAgentBridge(options?: AgentBridgeOptions): void;
+
+export { AgentBridgeOptions, type ScreenElement, type SettleResult, type Target, Transport, cdpTransport, settle, startAgentBridge, useAgentBridge };

package/dist/types-C6DUUHnB.d.cts

@@ -0,0 +1,76 @@
+/** `agent-bridge assert-absent` fails when a bundle contains this string. */
+declare const RUNTIME_MARKER = "@avasapp/agent-bridge/runtime";
+type CallMessage = {
+    id: string;
+    tool: string;
+    args?: unknown[];
+    /** Device to run on. Expo's socket broadcasts, so every app sees every call. */
+    to?: string;
+};
+/** An error or warning the app logged, threw or left unhandled. */
+type LogEntry = {
+    level: 'error' | 'warn';
+    message: string;
+    /** First lines of the stack, when there was an Error. */
+    stack?: string;
+    /** Date.now() in the app. */
+    at: number;
+    /** The tool that was running when it was logged. */
+    during?: string;
+    /** Otherwise, the last tool that had finished. */
+    after?: string;
+};
+/** `logs`: errors the app recorded since its previous reply. Old clients ignore it. */
+type ResultMessage = ({
+    id: string;
+    from: string;
+    ok: true;
+    value: unknown;
+    ms: number;
+} | {
+    id: string;
+    from: string;
+    ok: false;
+    error: string;
+    ms: number;
+}) & {
+    logs?: LogEntry[];
+};
+type ToolInfo = {
+    name: string;
+    description?: string;
+};
+type DeviceInfo = {
+    deviceId: string;
+    name: string;
+    platform: string;
+    protocol: number;
+    tools: ToolInfo[];
+};
+
+type ToolFn = (...args: any[]) => unknown;
+type ToolDefinition = ToolFn | {
+    description?: string;
+    run: ToolFn;
+};
+/** Tools by name. Namespace them with a dot, e.g. `query.pin`. */
+type Tools = Record<string, ToolDefinition>;
+type TransportContext = {
+    info: () => DeviceInfo;
+    dispatch: (call: CallMessage) => Promise<ResultMessage>;
+};
+type Transport = {
+    name: string;
+    /** Starts listening; returns a function that stops. */
+    start: (context: TransportContext) => () => void;
+};
+type AgentBridgeOptions = {
+    /** Your tools, or a function returning them (read on every call). */
+    tools?: Tools | (() => Tools);
+    /** 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 };

package/entries/expo-router.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/expo-router.cjs')
+} else {
+  module.exports = require('../dist/adapters/expo-router.cjs')
+}

package/entries/expo.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/expo.cjs')
+} else {
+  module.exports = require('../dist/expo/index.cjs')
+}

package/entries/index.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/index.cjs')
+} else {
+  module.exports = require('../dist/runtime/index.cjs')
+}

package/entries/network.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/network.cjs')
+} else {
+  module.exports = require('../dist/network/index.cjs')
+}

package/entries/react-native-mmkv.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/react-native-mmkv.cjs')
+} else {
+  module.exports = require('../dist/adapters/react-native-mmkv.cjs')
+}

package/entries/tanstack-query.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/tanstack-query.cjs')
+} else {
+  module.exports = require('../dist/adapters/tanstack-query.cjs')
+}

package/entries/zustand.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/zustand.cjs')
+} else {
+  module.exports = require('../dist/adapters/zustand.cjs')
+}

package/package.json

@@ -0,0 +1,120 @@
+{
+  "name": "@avasapp/agent-bridge",
+  "version": "0.1.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",
+  "homepage": "https://github.com/avas-app/agent-bridge#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/avas-app/agent-bridge.git"
+  },
+  "bugs": {
+    "url": "https://github.com/avas-app/agent-bridge/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "sideEffects": false,
+  "main": "./entries/index.cjs",
+  "types": "./dist/runtime/index.d.cts",
+  "exports": {
+    ".": {
+      "types": "./dist/runtime/index.d.cts",
+      "default": "./entries/index.cjs"
+    },
+    "./expo": {
+      "types": "./dist/expo/index.d.cts",
+      "default": "./entries/expo.cjs"
+    },
+    "./tanstack-query": {
+      "types": "./dist/adapters/tanstack-query.d.cts",
+      "default": "./entries/tanstack-query.cjs"
+    },
+    "./zustand": {
+      "types": "./dist/adapters/zustand.d.cts",
+      "default": "./entries/zustand.cjs"
+    },
+    "./react-native-mmkv": {
+      "types": "./dist/adapters/react-native-mmkv.d.cts",
+      "default": "./entries/react-native-mmkv.cjs"
+    },
+    "./expo-router": {
+      "types": "./dist/adapters/expo-router.d.cts",
+      "default": "./entries/expo-router.cjs"
+    },
+    "./network": {
+      "types": "./dist/network/index.d.cts",
+      "default": "./entries/network.cjs"
+    },
+    "./client": {
+      "types": "./dist/client/index.d.ts",
+      "import": "./dist/client/index.js",
+      "require": "./dist/client/index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "agent-bridge": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "entries",
+    "skills"
+  ],
+  "keywords": [
+    "react-native",
+    "expo",
+    "ai",
+    "agents",
+    "testing",
+    "e2e",
+    "devtools",
+    "cdp",
+    "tanstack-query",
+    "zustand",
+    "mmkv"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && tsup",
+    "test": "bun test src/",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "check": "bun run typecheck && bun run test && bun run build && bun run check:gates",
+    "check:gates": "node scripts/check-gates.mjs",
+    "changeset": "changeset",
+    "release": "bun run check && changeset publish",
+    "prepublishOnly": "bun run check"
+  },
+  "peerDependencies": {
+    "@tanstack/query-core": ">=5",
+    "expo": ">=52",
+    "react": ">=18",
+    "react-native": ">=0.76"
+  },
+  "peerDependenciesMeta": {
+    "@tanstack/query-core": {
+      "optional": true
+    },
+    "expo": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "ws": "^8.21.3"
+  },
+  "devDependencies": {
+    "@changesets/cli": "^3.0.3",
+    "@expo/devtools": "^57.0.1",
+    "@tanstack/query-core": "^5.90.0",
+    "@types/bun": "^1.4.2",
+    "@types/react": "^19.3.0",
+    "@types/ws": "^8.18.1",
+    "tsup": "^8.5.1",
+    "typescript": "~6.0.3",
+    "zustand": "^5.0.15"
+  }
+}

package/skills/agent-bridge/SKILL.md

@@ -0,0 +1,89 @@
+---
+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."
+---
+
+# Driving an app with agent-bridge
+
+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.
+
+## Start a session
+
+```sh
+npx agent-bridge session start            # add --metro host:port if Metro isn't on localhost:8081
+npx agent-bridge tools                    # what this app exposes
+```
+
+A session holds one connection for all your calls. It stops itself after 15
+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.
+
+## See and use the screen
+
+```sh
+npx agent-bridge call screen.snapshot                          # buttons, inputs, text on screen
+npx agent-bridge call screen.press '"add-plant"'               # by testID, label or text
+npx agent-bridge call screen.fill '["plant-name", "Fern"]'     # runs the input's handlers
+npx agent-bridge call screen.waitFor '"Name is required"'      # {"gone": true} waits for it to go
+```
+
+`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.
+
+## Get the app into a state
+
+```sh
+npx agent-bridge call query.pin '[["features"], <data>]'       # stays through refetches
+npx agent-bridge call store.call '["settings", "setTheme", "dark"]'
+npx agent-bridge call router.navigate /inbox
+npx agent-bridge call router.current
+npx agent-bridge call net.mock '["/inbox", {"status": 500}]'   # or {"offline": true}
+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.
+
+## Watch for errors
+
+Every reply carries errors the app logged or threw since the previous reply,
+printed as `! error during <tool>` or `! error after <tool>`. Treat them as
+failures of the step they name. `npx agent-bridge call bridge.logs` shows the
+last 200 errors and warnings.
+
+## Repeat without the model
+
+Write the steps into a flow file and run it:
+
+```js
+export default async ({ step }) => {
+  await step('open form', 'screen.press', 'add-plant')
+  await step('save empty', 'screen.press', 'save-plant')
+  await step('error shown', 'screen.waitFor', 'Name is required')
+  await step('undo', 'bridge.restore')
+}
+```
+
+```sh
+npx agent-bridge run flow.mjs --strict    # --strict fails if the app logged an error
+```
+
+## Clean up
+
+```sh
+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.
+
+## 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.
+- With several apps on one Metro, pass `--device`.