@avasapp/agent-bridge 0.4.2 → 0.5.0

package/skills/agent-bridge/SKILL.md

@@ -26,8 +26,9 @@ bridge call can set.
 
 ## Run the CLI directly
 
-The examples say `npx agent-bridge` for brevity. Prefer the installed bin,
-`./node_modules/.bin/agent-bridge` (or `bunx agent-bridge`): `npx` loads npm's
+The examples say `npx @avasapp/agent-bridge`; never drop the scope, because
+`agent-bridge` on npm is an unrelated package. Prefer the installed bin,
+`./node_modules/.bin/agent-bridge` (with bun too): `npx` loads npm's
 config on every call, so a project `.npmrc` with keys npm doesn't know prints
 `npm warn Unknown project config` into your output each time, and it adds
 roughly 200 ms more startup per call (machine-dependent).
@@ -35,10 +36,15 @@ roughly 200 ms more startup per call (machine-dependent).
 ## 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
+npx @avasapp/agent-bridge session start            # add --metro host:port if Metro isn't on localhost:8081
+npx @avasapp/agent-bridge tools                    # what this app exposes
 ```
 
+If Metro runs on another port, pass the same `--metro` (or set
+`AGENT_BRIDGE_METRO`) on every command that doesn't go through the session. A
+`Nothing is listening on …` error names the Metro it found instead and its apps;
+check it's yours before switching to it.
+
 A session holds one connection for all your calls. It stops itself after 15
 minutes without calls and runs `bridge.restore` when it does.
 
@@ -58,14 +64,22 @@ not connected; connected: …` means its app is gone and something else is there
 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.
 
+If the app doesn't have the package or a bridge file yet, run
+`npx @avasapp/agent-bridge init --json` in the app (`--dir apps/x` from a
+monorepo root). It writes `src/dev/agent-bridge.tsx` but never edits the root
+layout: paste `mount.snippet` into `mount.file` as `mount.note` says. Ask the
+user about each entry in `choices` it reports as `open` (such as network
+tools), then rerun with the `flag` it names, or add its `lines` by hand when
+there's no flag. Then follow `next`, from `runFrom`.
+
 ## 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"}}]'
+npx @avasapp/agent-bridge scenarios                                        # what this app defines
+npx @avasapp/agent-bridge call scenario.apply '["signedIn", {"user": {"name": "Ada"}}]'
 ```
 
 `scenarios` shows each one's options as a JSON Schema. Bad options fail
@@ -85,11 +99,11 @@ real account instead. If you're asked to add one, read
 ## See and use the screen
 
 ```sh
-npx agent-bridge call screen.snapshot                       # buttons, inputs, text on the focused 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
-npx agent-bridge call router.navigate /inbox
+npx @avasapp/agent-bridge call screen.snapshot                       # buttons, inputs, text on the focused screen
+npx @avasapp/agent-bridge call screen.press '"add-plant"'            # by testID, label or text
+npx @avasapp/agent-bridge call screen.fill '["plant-name", "Fern"]'  # runs the input's handlers
+npx @avasapp/agent-bridge call screen.waitFor '"Name is required"'   # {"gone": true} waits for it to go
+npx @avasapp/agent-bridge call router.navigate /inbox
 ```
 
 `press` and `fill` return once the app has rendered the result, so the next
@@ -100,14 +114,14 @@ spread into the tool's arguments.
 
 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.
+failures of the step they name. `npx @avasapp/agent-bridge call bridge.logs`
+shows the last 200 errors and warnings.
 
 ## Clean up
 
 ```sh
-npx agent-bridge call bridge.pending      # what restore will put back, per area
-npx agent-bridge session stop             # runs bridge.restore; --keep leaves the app as is
+npx @avasapp/agent-bridge call bridge.pending      # what restore will put back, per area
+npx @avasapp/agent-bridge session stop             # runs bridge.restore; --keep leaves the app as is
 ```
 
 `bridge.restore` unpins queries, puts back store values, removes network mocks,
@@ -138,4 +152,7 @@ The app may expose its own tools for hooks the bridge has no tool for
   overlap. Finish a flow with one real UI check or screenshot from agent-device.
 - `fill` skips the keyboard: autocorrect and native-only input behaviour need
   one real typing step from agent-device.
+- Swipe and drag gestures need agent-device, unless the control is screen-reader
+  operable: `press` sends its `activate` accessibility action (see
+  [references/screen.md](references/screen.md)).
 - With several apps on one Metro, pass `--device`.

package/skills/agent-bridge/references/flows.md

@@ -8,7 +8,7 @@ one JSON line back per call.
 
 ```sh
 printf '%s\n' 'router.navigate /inbox' 'screen.waitFor "Inbox"' 'screen.snapshot' \
-  | npx agent-bridge call --batch --stop-on-error
+  | npx @avasapp/agent-bridge call --batch --stop-on-error
 # {"tool":"router.navigate","ok":true,"ms":1.8,"appMs":1,"value":...}
 # {"tool":"screen.waitFor","ok":false,"ms":2003.1,"error":"..."}   (plus "logs"/"notice" when present)
 ```
@@ -29,7 +29,8 @@ reading the output.
 ## A flow file
 
 Write the steps into a flow file and run it when a step depends on an earlier
-result, and for timing checks.
+result, and for timing checks. Name it `flows/<name>.flow.mjs` in the app: plain
+`.mjs`, never under `app/`, never `*.test.*`.
 
 ```js
 export const scenario = 'signedIn'   // applied first, undone after, even on failure
@@ -43,9 +44,9 @@ 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
-npx agent-bridge run flow.mjs --scenario 'signedIn={"user":{"name":"Ada"}}'   # with options
+npx @avasapp/agent-bridge run flows/check.flow.mjs --strict    # --strict fails if the app logged an error
+npx @avasapp/agent-bridge run flows/check.flow.mjs --scenario signedIn   # add a scenario the flow doesn't declare
+npx @avasapp/agent-bridge run flows/check.flow.mjs --scenario 'signedIn={"user":{"name":"Ada"}}'   # with options
 ```
 
 A flow can declare several scenarios, with options:

package/skills/agent-bridge/references/large-data.md

@@ -11,9 +11,9 @@ and `connect()` always get the full value.
 Narrow the call before reaching for `--out`:
 
 ```sh
-npx agent-bridge call query.get '["feed", {"pages": [0, 2]}]'          # first two pages of an infinite query, plus totalPages
-npx agent-bridge call query.get '["feed", {"path": "pages.0.items"}]'  # just that value
-npx agent-bridge call net.mocks '[{"full": true}]'   # net.mocks cuts bodies over ~2 KB unless full
+npx @avasapp/agent-bridge call query.get '["feed", {"pages": [0, 2]}]'          # first two pages of an infinite query, plus totalPages
+npx @avasapp/agent-bridge call query.get '["feed", {"path": "pages.0.items"}]'  # just that value
+npx @avasapp/agent-bridge call net.mocks '[{"full": true}]'   # net.mocks cuts bodies over ~2 KB unless full
 ```
 
 `pages` is `[from, to]` with `to` exclusive, like `Array.slice`; `path` applies
@@ -25,9 +25,9 @@ The shell caps one argument at about 128 KB on Linux. For a bigger value (a long
 feed, a large `net.mock` body), write JSON to a file and pass `@file`:
 
 ```sh
-npx agent-bridge call query.pin @args.json                  # the file is the argument list, like the inline form
-npx agent-bridge call net.mock '"/feed"' @feed.json         # several words: each is one argument; @file is its JSON as-is
-some-generator | npx agent-bridge call store.set @-         # @- reads stdin
+npx @avasapp/agent-bridge call query.pin @args.json                  # the file is the argument list, like the inline form
+npx @avasapp/agent-bridge call net.mock '"/feed"' @feed.json         # several words: each is one argument; @file is its JSON as-is
+some-generator | npx @avasapp/agent-bridge call store.set @-         # @- reads stdin
 ```
 
 A file holding an array is the argument list; any other JSON value is one

package/skills/agent-bridge/references/network.md

@@ -1,11 +1,11 @@
 # Network mocks and logs
 
 ```sh
-npx agent-bridge call net.mock '["/inbox", {"status": 500}]'   # or {"offline": true}
-npx agent-bridge call net.log '[{"since": 1700000000000}]'     # entries carry startedAt (epoch ms)
-npx agent-bridge call net.entry 3                              # one request, bodies whole
-npx agent-bridge call net.mockFromLog '[3, {"user": {"name": "Moss"}}]'  # a real response, patched
-npx agent-bridge call net.mocks '[{"full": true}]'             # active mocks; bodies over ~2 KB are cut unless full
+npx @avasapp/agent-bridge call net.mock '["/inbox", {"status": 500}]'   # or {"offline": true}
+npx @avasapp/agent-bridge call net.log '[{"since": 1700000000000}]'     # entries carry startedAt (epoch ms)
+npx @avasapp/agent-bridge call net.entry 3                              # one request, bodies whole
+npx @avasapp/agent-bridge call net.mockFromLog '[3, {"user": {"name": "Moss"}}]'  # a real response, patched
+npx @avasapp/agent-bridge call net.mocks '[{"full": true}]'             # active mocks; bodies over ~2 KB are cut unless full
 ```
 
 `net.log` cuts bodies at about 2 KB; use `net.entry <id>` (or `{"full": true}`)
@@ -25,8 +25,8 @@ 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.
+`npx @avasapp/agent-bridge call net.strict` lists what it blocked. Strict mode
+sees JS `fetch`/XHR only, not images, WebSockets or native SDKs.
 
 ## Mocks and cached queries
 

package/skills/agent-bridge/references/realtime.md

@@ -4,11 +4,11 @@ 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
+npx @avasapp/agent-bridge call realtime.channels                         # what the app listens on
+npx @avasapp/agent-bridge call realtime.log '{"channel": "chat"}'        # recent messages, real and faked
+npx @avasapp/agent-bridge call realtime.mute '"chat"'                    # stop real ones overwriting your state
+npx @avasapp/agent-bridge call realtime.emit '["chat", {"name": "message", "data": {"text": "hi"}}]'
+npx @avasapp/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

package/skills/agent-bridge/references/restore.md

@@ -1,10 +1,10 @@
 # What restore undoes
 
 ```sh
-npx agent-bridge call bridge.pending      # what restore will put back, per area
-npx agent-bridge session stop --dry-run   # the same, and keeps the session
-npx agent-bridge session stop             # runs bridge.restore
-npx agent-bridge session stop --keep      # leaves the app as is; warns about anything still pending
+npx @avasapp/agent-bridge call bridge.pending      # what restore will put back, per area
+npx @avasapp/agent-bridge session stop --dry-run   # the same, and keeps the session
+npx @avasapp/agent-bridge session stop             # runs bridge.restore
+npx @avasapp/agent-bridge session stop --keep      # leaves the app as is; warns about anything still pending
 ```
 
 `bridge.restore` unpins queries, puts back store and MMKV values, removes

package/skills/agent-bridge/references/screen.md

@@ -1,22 +1,30 @@
 # See and use the screen
 
 ```sh
-npx agent-bridge call screen.snapshot                          # buttons, inputs, text on the focused screen (`hidden` counts what was skipped; {"all":true} lists everything)
-npx agent-bridge call screen.findText "Payment"                 # text or accessibility label; {"labels":false} for text only
-npx agent-bridge call screen.press '"add-plant"'               # by testID, label or text
-npx agent-bridge call screen.press '[{"at":[350,60]}]'          # icon-only button: by point; {"index":1} picks among matches; {"force":true} presses disabled
-npx agent-bridge call screen.press '["save-plant", {"scroll":true}]'   # scrolls an off-screen target into view first
-npx agent-bridge call screen.scroll '"Notes"'                   # bring a target to the middle of its ScrollView/FlatList; {"toEnd":true}, {"by":400}, [{"toEnd":true},{"within":"list"}]
-npx agent-bridge call screen.refresh                            # pull to refresh (the RefreshControl's onRefresh); then screen.waitFor the data
-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
-npx agent-bridge call screen.waitFor '["Section title", {"scroll":true}]'   # also below the fold: scrolls it into view (not with gone)
+npx @avasapp/agent-bridge call screen.snapshot                          # buttons, inputs, text on the focused screen (`hidden` counts what was skipped; {"all":true} lists everything)
+npx @avasapp/agent-bridge call screen.findText "Payment"                 # text or accessibility label; {"labels":false} for text only
+npx @avasapp/agent-bridge call screen.press '"add-plant"'               # by testID, label or text
+npx @avasapp/agent-bridge call screen.press '[{"at":[350,60]}]'          # icon-only button: by point; {"index":1} picks among matches; {"force":true} presses disabled
+npx @avasapp/agent-bridge call screen.press '["save-plant", {"scroll":true}]'   # scrolls an off-screen target into view first
+npx @avasapp/agent-bridge call screen.press '"Swipe to confirm"'        # no onPress: sends the "activate" accessibility action
+npx @avasapp/agent-bridge call screen.press '["Volume", {"action":"increment"}]'   # any action in the element's snapshot `actions`
+npx @avasapp/agent-bridge call screen.scroll '"Notes"'                   # bring a target to the middle of its ScrollView/FlatList; {"toEnd":true}, {"by":400}, [{"toEnd":true},{"within":"list"}]
+npx @avasapp/agent-bridge call screen.refresh                            # pull to refresh (the RefreshControl's onRefresh); then screen.waitFor the data
+npx @avasapp/agent-bridge call screen.fill '["plant-name", "Fern"]'     # runs the input's handlers
+npx @avasapp/agent-bridge call screen.waitFor '"Name is required"'      # {"gone": true} waits for it to go
+npx @avasapp/agent-bridge call screen.waitFor '["Section title", {"scroll":true}]'   # also below the fold: scrolls it into view (not with gone)
 ```
 
 `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 agent-device.
 
+A swipe-to-confirm or slider with no `onPress` shows as a button (or a view)
+with `actions` in the snapshot. `press` calls its `onAccessibilityAction` with
+`activate`, as a screen reader's double tap does, and the reply says
+`via: "accessibilityAction:activate"`. A gesture control with no `actions`
+needs a real swipe from agent-device.
+
 A WebView shows in the snapshot as one element (`webview "checkout"`);
 `screen.*` can't reach inside it. See [webview.md](webview.md).
 

package/skills/agent-bridge/references/state.md

@@ -3,11 +3,11 @@
 ## Set 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 router.dismiss                            # closes a route-based modal
+npx @avasapp/agent-bridge call query.pin '[["features"], <data>]'       # stays through refetches
+npx @avasapp/agent-bridge call store.call '["settings", "setTheme", "dark"]'
+npx @avasapp/agent-bridge call router.navigate /inbox
+npx @avasapp/agent-bridge call router.current
+npx @avasapp/agent-bridge call router.dismiss                            # closes a route-based modal
 ```
 
 `router.back` only pops the navigator: an in-app modal or sheet the app renders
@@ -19,12 +19,12 @@ own tool (e.g. `modal.close`) if it has one; check `tools` first.
 Read the current value first and change only what you need:
 
 ```sh
-npx agent-bridge call query.get '["todos", 1]'             # a flat key or '[["todos", 1]]'
-npx agent-bridge call query.list '["todos"]'               # key prefix; shows isStale, isInvalidated, fetchStatus
-npx agent-bridge call query.refetch '["todos"]'            # {matched, refetched, data}; errors when nothing matches
-npx agent-bridge call store.get '["app", "auth.isLoggedIn"]'   # or ["app","auth","isLoggedIn"]
-npx agent-bridge call store.get '["app", {"pick": ["auth.isLoggedIn", "settings.fontScale"]}]'
-npx agent-bridge call store.get '["app", {"keys": true}]'  # top-level keys and types, no values
+npx @avasapp/agent-bridge call query.get '["todos", 1]'             # a flat key or '[["todos", 1]]'
+npx @avasapp/agent-bridge call query.list '["todos"]'               # key prefix; shows isStale, isInvalidated, fetchStatus
+npx @avasapp/agent-bridge call query.refetch '["todos"]'            # {matched, refetched, data}; errors when nothing matches
+npx @avasapp/agent-bridge call store.get '["app", "auth.isLoggedIn"]'   # or ["app","auth","isLoggedIn"]
+npx @avasapp/agent-bridge call store.get '["app", {"pick": ["auth.isLoggedIn", "settings.fontScale"]}]'
+npx @avasapp/agent-bridge call store.get '["app", {"keys": true}]'  # top-level keys and types, no values
 ```
 
 `query.get` errors on a key that is not cached (with similar keys), so a

package/skills/agent-bridge/references/webview.md

@@ -5,15 +5,15 @@
 `tools`), use the same verbs on the page:
 
 ```sh
-npx agent-bridge call webview.list                              # name, url, loaded, allowed
-npx agent-bridge call webview.snapshot '"checkout"'             # buttons, links, inputs, text in the page
-npx agent-bridge call webview.press '["Pay now", {"webview": "checkout"}]'
-npx agent-bridge call webview.fill '["Email", "ada@example.com"]'   # {"submit":true} presses Enter
-npx agent-bridge call webview.waitFor '["Payment complete", {"timeoutMs": 8000}]'   # {"gone":true}
-npx agent-bridge call webview.messages '"checkout"'             # page <-> app, last 100, bodies cut at 2 KB
-npx agent-bridge call webview.message 17                        # one in full
-npx agent-bridge call webview.send '["checkout", {"type": "auth", "ok": true}]'      # as if the app sent it
-npx agent-bridge call webview.receive '["checkout", {"type": "done"}]'               # runs the app's onMessage
+npx @avasapp/agent-bridge call webview.list                              # name, url, loaded, allowed
+npx @avasapp/agent-bridge call webview.snapshot '"checkout"'             # buttons, links, inputs, text in the page
+npx @avasapp/agent-bridge call webview.press '["Pay now", {"webview": "checkout"}]'
+npx @avasapp/agent-bridge call webview.fill '["Email", "ada@example.com"]'   # {"submit":true} presses Enter
+npx @avasapp/agent-bridge call webview.waitFor '["Payment complete", {"timeoutMs": 8000}]'   # {"gone":true}
+npx @avasapp/agent-bridge call webview.messages '"checkout"'             # page <-> app, last 100, bodies cut at 2 KB
+npx @avasapp/agent-bridge call webview.message 17                        # one in full
+npx @avasapp/agent-bridge call webview.send '["checkout", {"type": "auth", "ok": true}]'      # as if the app sent it
+npx @avasapp/agent-bridge call webview.receive '["checkout", {"type": "done"}]'               # runs the app's onMessage
 ```
 
 Targets match in `screen.*` order: `data-testid` (also `data-test-id`,

package/skills/agent-bridge/references/writing-scenarios.md

@@ -56,8 +56,8 @@ useAgentBridge({ tools, scenarios })
   is back in its real state. If `apply` throws, the callbacks it had registered
   run straight away.
 - Tools: `scenario.list`, `scenario.apply [name, options?]` (applying an active
-  one again undoes it first) and `scenario.restore`. `npx agent-bridge scenarios`
-  lists them.
+  one again undoes it first) and `scenario.restore`.
+  `npx @avasapp/agent-bridge scenarios` lists them.
 - Flows declare scenarios with `export const scenario` or
   `export const scenarios`; see [flows.md](flows.md).
 
@@ -93,5 +93,5 @@ In a release build it's always open. `realtime.connection` isn't enough on its
 own: it hides the state from the app, but the client still connects.
 
 The agent-bridge repo's example app has a complete local `signedIn` in
-`example/src/dev/scenarios.ts`, and `example/flows/checks/signed-in.mjs`
+`example/src/dev/scenarios.ts`, and `example/flows/checks/signed-in.flow.mjs`
 declares it.