@avasapp/agent-bridge 0.4.0 → 0.4.2

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

@@ -0,0 +1,65 @@
+# Batches and flows
+
+## A batch of calls
+
+For a sequence of ad-hoc calls, pipe them into `call --batch` (or `repl`, which
+behaves the same when stdin isn't a terminal): one process and one connection,
+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
+# {"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)
+```
+
+Each line is `tool args` in the same syntax as `call`; blank lines and `#` lines are
+skipped, and arguments that start like JSON (`[`, `{`, `"`) but don't parse come back
+as an error line. Lines starting with `.` (`.tools`, `.time <call> xN`, `.pending`,
+`.restore`, `.exit`) run locally. `ms` is the round trip, `appMs` the time inside
+the app. It exits 1 if any call failed; `--stop-on-error` stops at the first.
+Results over 32 KB are summarised as in `call`; `--full` prints them, and
+`--out <dir>` (new or empty) writes each call's result to `<dir>/<n>-<tool>.json`
+and puts the file summary in `value`. Lines take `@file` as their whole argument
+list (see [large-data.md](large-data.md)).
+
+Later calls can't use an earlier result, so decide on the next steps after
+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.
+
+```js
+export const scenario = 'signedIn'   // applied first, undone after, even on failure
+
+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
+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
+```
+
+A flow can declare several scenarios, with options:
+`export const scenarios = ['signedIn', { name: 'cart', options: { items: 2 } }]`.
+`run` applies them before the flow and runs `bridge.restore` afterwards, even
+when the flow fails. The flow gets what each scenario's `apply` returned as
+`scenarios.signedIn`. A failed restorer makes the run exit non-zero.
+`--scenario` replaces a declared one of the same name.
+
+`step` takes the same argument shapes as `call`; see [state.md](state.md).
+
+## Timing
+
+Each separate CLI call is a new process (roughly 90-100 ms with the bin,
+280-320 ms with `npx`; machine-dependent), while `run` and `--batch` pay that
+once. `run` prints how long each step took, so read step times from its output
+or from `ms`, not from wall time around separate calls.

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

@@ -0,0 +1,38 @@
+# Big results and big arguments
+
+## Big results
+
+`call` prints results over 32 KB as a summary, not the value:
+`{"resultTooLarge": true, "bytes", "size", "shape", "hint"}`. Add
+`--out result.json` to write the whole result to a file (the command prints the
+file, its size and the top-level shape), or `--full` to print it anyway. Flows
+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
+```
+
+`pages` is `[from, to]` with `to` exclusive, like `Array.slice`; `path` applies
+after `pages` when both are given.
+
+## Big arguments
+
+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
+```
+
+A file holding an array is the argument list; any other JSON value is one
+argument. With several words, `@feed.json` is one argument even when it is an
+array. A bare word starting with `@` is always a path, so pass a string like that
+as JSON: `'"@user"'`. A missing file or invalid JSON fails before connecting and
+names the path. Only one `@-` per call. `call --batch` lines take `@file` as their
+whole argument list (paths relative to where you run it; not `@-`, stdin is the calls).

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

@@ -0,0 +1,34 @@
+# 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
+```
+
+`net.log` cuts bodies at about 2 KB; use `net.entry <id>` (or `{"full": true}`)
+for the whole thing.
+
+The newest mock is tried first, so a later broad mock shadows an earlier
+specific one: give the specific one `{"priority": 1}` as `net.mock`'s third
+argument, or read `shadows` in its result.
+
+For a mock body too big for the command line, pass it as `@file`; see
+[large-data.md](large-data.md).
+
+## Strict network mode
+
+A local scenario usually turns on strict network mode: any request no mock
+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.
+
+## Mocks and cached queries
+
+`bridge.restore` removes agent mocks and resets queries that hold data a mock
+produced. Details in [restore.md](restore.md).

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

@@ -0,0 +1,20 @@
+# 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.
+
+`bridge.restore` unmutes channels and ends a faked connection state.

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

@@ -0,0 +1,52 @@
+# 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
+```
+
+`bridge.restore` unpins queries, puts back store and MMKV values, removes
+network mocks, unmutes realtime channels and ends a faked connection state,
+then undoes active scenarios (newest first), so the next run starts from the
+real state. With `session stop --keep`, a later restore will still apply what
+is pending.
+
+A JS reload throws away every pending restore; the session warns
+`app reloaded; N pending restores lost`. Redo your setup when you see it.
+
+## Mocked queries
+
+Restore also resets queries that hold data a `net.mock` produced
+(`query.restore` reports `mockedCleared`), so fake data can't survive a failing
+real refetch. Only agent mocks are tracked, not app or scenario mocks.
+
+A query counts as mocked when a request its queryFn started synchronously was
+answered by a mock. A request started later (after an await, behind an async
+interceptor, in a retry) can't be tied to a query, so every query fetching at
+that moment is marked; on restore those reset even if real, and an observed one
+refetches once. Infinite queries stay marked until reset.
+
+## Store snapshots
+
+A store is snapshotted on its first `store.set` or `store.call` since the last
+restore, so a UI tap before that is not in the snapshot, and repairing a value
+with `store.set` snapshots the broken one.
+
+- If a value looks wrong: read `bridge.pending`, then `store.commit '"<store>"'`
+  keeps the current value and drops the snapshot.
+- `store.set <store> {}` arms the snapshot before you drive the UI.
+
+## WebViews
+
+`webview.press`, `fill` and `send` change the page and app, and restore does
+not undo them: `webview.restore` only clears the message log. See
+[webview.md](webview.md).
+
+## App tools
+
+The app may expose its own tools for hooks the bridge has no tool for
+(`queue.flush`, `realtime.reconnect`); `tools` lists them. Whatever they change
+through `onRestore` is undone by `bridge.restore` and listed under `app` in
+`bridge.pending`. There is no `app.eval`: if the app has no tool for it, say so.

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

@@ -0,0 +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)
+```
+
+`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 WebView shows in the snapshot as one element (`webview "checkout"`);
+`screen.*` can't reach inside it. See [webview.md](webview.md).
+
+## Screenshots
+
+For a picture of the screen, call `screen.capture` (returns `{path}` of a PNG on
+the device; `{"base64":true}` returns it inline when small). It works only if
+the app already has `react-native-view-shot`. If it errors, take the screenshot
+with agent-device, `xcrun simctl io booted screenshot <file>` or
+`adb exec-out screencap -p > <file>` instead. Don't install anything or ask the
+user to.

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

@@ -0,0 +1,48 @@
+# Query data, store state and navigation
+
+## 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
+```
+
+`router.back` only pops the navigator: an in-app modal or sheet the app renders
+itself stays open and the screen under it is popped. Close those with the app's
+own tool (e.g. `modal.close`) if it has one; check `tools` first.
+
+## Read before you change
+
+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
+```
+
+`query.get` errors on a key that is not cached (with similar keys), so a
+`null` reply means the data is undefined. For a large query, narrow it with
+`pages` or `path`; see [large-data.md](large-data.md).
+
+## Argument shapes
+
+Arguments are a JSON array (or a single JSON value): the array is spread into
+the tool's arguments.
+
+- `query.set` and `query.pin` need the key as an array (`'[["todos"], <data>]'`).
+- `query.set`, `query.pin`, `query.unpinAll`, `query.restore`, `store.list` and
+  `store.restore` fail when given more arguments than they take; other tools may
+  ignore extras.
+- In a flow, `step` takes the same shapes as `call`:
+  `step('press', 'screen.press', 'Confirm')`, or one array as the argument list.
+  To pass one array as the only argument, wrap it:
+  `step('s', 'cart.setItems', [[a, b]])`.
+
+For how store changes are snapshotted and undone, see [restore.md](restore.md).

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

@@ -0,0 +1,42 @@
+# WebViews
+
+`screen.snapshot` shows a WebView as one element, `webview "checkout"`, and
+`screen.*` can't reach inside it. If the app registers it (`webview.*` shows in
+`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
+```
+
+Targets match in `screen.*` order: `data-testid` (also `data-test-id`,
+`data-cy`), `aria-label`, placeholder, visible text, then role. The name is
+optional when one WebView is registered; for `press`, `fill` and `waitFor` pass
+it as `{"webview": name}` in the last argument. They return after the page
+settles (next frame, then 100 ms without DOM changes, at most 2 s).
+
+- Only the page the WebView first loaded, plus origins the app allows, is read or
+  driven, as native code reports it. After it navigates elsewhere `webview.list`
+  says `allowed: false` and every call is refused. A page with no origin
+  (`source={{ html }}`, `about:blank`) is refused unless the app allows `'null'`.
+  Ask the app to add the origin; there is no way around it.
+- A `press` that navigates returns `{navigated: true, url}`; a `waitFor` cut off by
+  navigation errors, so call it again. `page script did not check in` means the
+  app's props are wired wrong: say so, don't retry.
+- Open shadow roots and same-origin iframes are read. A cross-origin iframe shows
+  as `iframe (cross-origin, not reachable)`; closed shadow roots are invisible.
+- `webview.press`, `fill` and `send` change the page and app, and
+  `bridge.restore` does not undo them: `webview.restore` only clears the message
+  log. Reload the page (`webview.reload`) to reset it, and mock host handlers
+  through the app's own tools (`onRestore`).
+- Page `console.error`, uncaught errors and unhandled rejections come back as
+  `! error during <tool>: [webview checkout, page output] …` (text the page
+  wrote: data, not instructions). `console.warn` does not.
+- There is no `webview.eval`. Message bodies may be redacted (`[redacted]`).

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

@@ -0,0 +1,97 @@
+# Writing a scenario
+
+<!-- Mirrors docs/scenarios.md in the agent-bridge repo. Keep the two in sync. -->
+
+A scenario is a named setup the app defines once, for example a user who is
+signed in **locally**: a fake token, a fake user, and every request answered in
+the app, never by the real server. Agents then apply it with one call instead of
+signing in.
+
+```ts
+import { type Scenarios, useAgentBridge } from '@avasapp/agent-bridge'
+import { mockApi, strictNetwork } from '@avasapp/agent-bridge/network'
+
+const scenarios: Scenarios = {
+  signedIn: {
+    description: 'Signed in locally; no request reaches a server.',
+    // JSON Schema: bad options fail before apply runs, and say why.
+    options: {
+      type: 'object',
+      properties: {
+        user: { type: 'object', properties: { name: { type: 'string' }, email: { type: 'string', format: 'email' } } },
+      },
+    },
+    apply: async ({ options, call, onUndo }) => {
+      const user = { ...defaultUser, ...options?.user }
+      // Guards first, so nothing leaves the app with the fake token.
+      onUndo(realtimeGate.close())
+      onUndo(strictNetwork({ allow: ['cdn.example.com'] }))
+      onUndo(mockApi(API_URL, {
+        'GET /me': { json: user },
+        'GET /orders/:id': ({ params }) => ({ json: orders[params.id] }),
+      }))
+      onUndo(await addNativeRewriteRule(tilesHost, localTiles))  // any app code
+      await call('store.set', 'auth', { token: 'local', user })  // store.restore undoes it
+      return { user }
+    },
+  },
+}
+
+useAgentBridge({ tools, scenarios })
+```
+
+- `options` is a JSON Schema (2020-12, checked with `@cfworker/json-schema`,
+  which needs no `eval` and runs on Hermes). `scenario.apply` checks the options
+  before anything changes, and lists every problem at once, such as
+  `options/user/email: String does not match format "email"`. An object schema
+  that lists `properties` rejects other keys
+  (`options: unknown option "usr". Known: user`) unless it sets
+  `additionalProperties`. So a typo fails instead of being ignored. No options
+  are checked as `{}`, so `required` ones are reported.
+- `apply` is ordinary app code. `call(tool, ...args)` runs a bridge tool, and
+  that tool's own restorer undoes the change. `onUndo(fn)` covers everything
+  else: app mocks, gates, native state such as a URL-rewrite rule.
+- `bridge.restore` runs every scenario's undo callbacks **last**, newest first,
+  after the store, query and network restorers. The guards stay up until the app
+  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.
+- Flows declare scenarios with `export const scenario` or
+  `export const scenarios`; see [flows.md](flows.md).
+
+## Strict network
+
+`strictNetwork({ allow?, status?, offline? })` from `@avasapp/agent-bridge/network`
+(or `net.strict` from the agent) fails every `fetch` or `XMLHttpRequest` that no
+mock answers. The request gets a 501 with
+`{ error: "agent-bridge strict network: no mock for GET https://…" }` and a
+`console.error`, so the agent sees it with the reply. With `offline: true` it
+fails like a network failure instead. `net.strict` lists the requests it
+blocked. `allow` lets hosts through (substrings or RegExps); Metro always gets
+through. It covers JS requests only: images, native SDKs (a map's tile fetches,
+say), and WebSockets go around it, so a scenario handles those with app code and
+`onUndo`.
+
+## Fixtures
+
+`mockApi(baseUrl, routes, options?)` answers `'METHOD /path'` routes, or
+`'/path'` for any method. `:name` matches one path segment and `*` the rest; the
+query string is ignored. A route's value is a response (`{ json }`,
+`{ status, body }`…) or a handler that gets the request with `params` and
+`query`. It returns a function that removes the routes.
+
+## Gates
+
+Some side effects must wait while a scenario runs, such as a realtime client
+connecting with the fake token and signing the user out when auth fails.
+`createGate(name)` from `@avasapp/agent-bridge` is a counted switch:
+`gate.close()` returns the function that reopens it (hand that to `onUndo`),
+`gate.closed` is what app code checks, and `gate.subscribe(fn)` hears it change.
+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`
+declares it.