@avasapp/agent-bridge 0.4.2 → 0.6.0

package/dist/runtime/index.d.cts

@@ -1,5 +1,5 @@
-import { a as Transport, A as AgentBridgeOptions } from '../types-BmpykP1P.cjs';
-export { C as CallMessage, D as DeviceInfo, L as LogEntry, O as OptionsSchema, R as RUNTIME_MARKER, b as ResultMessage, S as Scenario, c as ScenarioContext, d as Scenarios, e as ToolDefinition, f as ToolFn, g as ToolInfo, T as Tools } from '../types-BmpykP1P.cjs';
+import { a as Transport, A as AgentBridgeOptions } from '../types-qlwdcGjt.cjs';
+export { C as CallMessage, D as DeviceInfo, L as LogEntry, O as OptionsSchema, R as RUNTIME_MARKER, b as ResultMessage, S as Scenario, c as ScenarioContext, d as Scenarios, e as ToolDefinition, f as ToolFn, g as ToolInfo, T as Tools } from '../types-qlwdcGjt.cjs';
 
 /**
  * Works in any React Native app served by Metro. The client evaluates one fixed
@@ -82,6 +82,8 @@ type ScreenElement = {
     expanded?: boolean;
     /** A WebView registered with the react-native-webview adapter: drive it with `webview.*`. */
     webview?: string;
+    /** `accessibilityActions` it handles with `onAccessibilityAction`, e.g. `activate` on a swipe button. */
+    actions?: string[];
     rect: Rect | null;
     /** Only in `screen.snapshot({ all: true })`. */
     onScreen?: boolean;

package/dist/store-common-j0cHHvBr.d.cts

@@ -0,0 +1,23 @@
+/**
+ * Keeps secrets out of what store.* prints. Either dotted paths per store
+ * (`{ auth: ['accessToken', 'user.phone'] }`), or a hook called for the store
+ * value and every nested value with its dotted path; what it returns is
+ * printed instead.
+ *
+ * Paths are store paths. A `store.call` result that is a piece of the store's
+ * state (same object, e.g. `() => get().user`) is matched by where it lives; a
+ * copy or derived value (`() => ({ ...get().user })`) is not, so its paths are
+ * matched relative to the result and store paths like `user.phone` won't apply.
+ * Use the hook, or don't return secrets from actions.
+ */
+type Redact = Record<string, string[]> | ((store: string, path: string, value: unknown) => unknown);
+/**
+ * Keeps secrets out of what an adapter prints, by the name of the slice or
+ * atom: dotted paths inside it (`{ auth: ['token', 'user.phone'] }`), or `true`
+ * for all of it (`{ authToken: true }`). Or a hook called for the whole value
+ * (path `''`) and every nested value with its dotted path; what it returns is
+ * printed instead.
+ */
+type NamedRedact = Record<string, string[] | true> | ((name: string, path: string, value: unknown) => unknown);
+
+export type { NamedRedact as N, Redact as R };

package/dist/{types-BmpykP1P.d.cts → types-qlwdcGjt.d.cts}

@@ -6,6 +6,10 @@ type CallMessage = {
     args?: unknown[];
     /** Device to run on. Expo's socket broadcasts, so every app sees every call. */
     to?: string;
+    /** A session's own: the journal tag it holds, so the reply carries the journal only when it is stale. */
+    journalAck?: string;
+    /** A session's own secret; the runtime keeps the first one it gets and ignores the journal calls of anyone else. */
+    journalKey?: string;
 };
 /** An error or warning the app logged, threw or left unhandled. */
 type LogEntry = {
@@ -39,6 +43,10 @@ type ResultMessage = ({
     loadId?: string;
     /** Areas (`store`, `query`, ...) whose `*.restore` has something to undo. */
     pending?: string[];
+    /** Goes up when something persistent changed that a restore could undo. */
+    journal?: number;
+    /** What each area could undo from storage; sent only to a session that proved it holds the key and a stale tag. */
+    journalData?: Record<string, unknown>;
 };
 type ToolInfo = {
     name: string;
@@ -82,6 +90,20 @@ type ToolDefinition = ToolFn | {
     pending?: (options?: {
         detail?: boolean;
     }) => unknown;
+    /**
+     * On a `*.restore` tool: what it could undo that lives in persistent
+     * storage (so it outlives a reload), as JSON, or undefined. A session
+     * keeps it, and hands it to `adopt` after the app reloads.
+     */
+    journal?: () => unknown;
+    /**
+     * Takes what `journal` returned before a reload and re-arms the undo for
+     * it in the new load, without changing the app. Returns an
+     * `AdoptResult`.
+     */
+    adopt?: (data: unknown) => unknown;
+    /** Goes up when `journal` may have changed. Not shared state: keep it in the adapter's own module. */
+    journalRev?: () => number;
 };
 /** Tools by name. Namespace them with a dot, e.g. `query.pin`. */
 type Tools = Record<string, ToolDefinition>;

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

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

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

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

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avasapp/agent-bridge",
-  "version": "0.4.2",
+  "version": "0.6.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",
@@ -38,6 +38,14 @@
       "types": "./dist/adapters/zustand.d.cts",
       "default": "./entries/zustand.cjs"
     },
+    "./redux": {
+      "types": "./dist/adapters/redux.d.cts",
+      "default": "./entries/redux.cjs"
+    },
+    "./jotai": {
+      "types": "./dist/adapters/jotai.d.cts",
+      "default": "./entries/jotai.cjs"
+    },
     "./react-native-mmkv": {
       "types": "./dist/adapters/react-native-mmkv.d.cts",
       "default": "./entries/react-native-mmkv.cjs"
@@ -46,6 +54,10 @@
       "types": "./dist/adapters/expo-router.d.cts",
       "default": "./entries/expo-router.cjs"
     },
+    "./react-navigation": {
+      "types": "./dist/adapters/react-navigation.d.cts",
+      "default": "./entries/react-navigation.cjs"
+    },
     "./react-native-webview": {
       "types": "./dist/adapters/react-native-webview.d.cts",
       "default": "./entries/react-native-webview.cjs"
@@ -66,6 +78,18 @@
       "types": "./dist/adapters/socket-io.d.cts",
       "default": "./entries/socket.io.cjs"
     },
+    "./async-storage": {
+      "types": "./dist/adapters/async-storage.d.cts",
+      "default": "./entries/async-storage.cjs"
+    },
+    "./secure-store": {
+      "types": "./dist/adapters/secure-store.d.cts",
+      "default": "./entries/secure-store.cjs"
+    },
+    "./device": {
+      "types": "./dist/adapters/device.d.cts",
+      "default": "./entries/device.cjs"
+    },
     "./client": {
       "types": "./dist/client/index.d.ts",
       "import": "./dist/client/index.js",
@@ -92,7 +116,11 @@
     "cdp",
     "tanstack-query",
     "zustand",
+    "redux",
+    "jotai",
     "mmkv",
+    "async-storage",
+    "secure-store",
     "realtime",
     "ably",
     "socket.io",
@@ -103,8 +131,9 @@
     "build": "bun run generate && rm -rf dist && tsup",
     "test": "bun run generate && bun test src/",
     "typecheck": "bun run generate && tsc -p tsconfig.json --noEmit",
-    "check": "bun run typecheck && bun run test && bun run build && bun run check:gates",
+    "check": "bun run typecheck && bun run test && bun run build && bun run check:gates && bun run check:consumer-types",
     "check:gates": "node scripts/check-gates.mjs",
+    "check:consumer-types": "node scripts/check-consumer-types.mjs",
     "changeset": "changeset",
     "release": "bun run check && changeset publish",
     "prepublishOnly": "bun run check"
@@ -134,12 +163,15 @@
   "devDependencies": {
     "@changesets/cli": "^3.0.3",
     "@expo/devtools": "^57.0.1",
+    "@reduxjs/toolkit": "^2.14.0",
     "@tanstack/query-core": "^5.90.0",
     "@types/bun": "^1.4.2",
     "@types/react": "^19.3.0",
     "@types/ws": "^8.18.1",
     "ably": "^2.29.0",
     "happy-dom": "^20.14.5",
+    "jotai": "^3.0.2",
+    "redux-persist": "^6.0.0",
     "socket.io-client": "^4.8.4",
     "tsup": "^8.5.1",
     "typescript": "~6.0.3",

package/skills/agent-bridge/SKILL.md

@@ -26,28 +26,49 @@ 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).
 
+If the app's tools are already in your tool list as an MCP server
+(`agent-bridge mcp`; names like `screen_snapshot` for `screen.snapshot`), call
+those: each takes `args`, an array of the tool's arguments, and `full: true` for
+a result over 32 KB. If the list is empty or a call fails, call `agent_bridge_status`. A failed call keeps the session's own error (`may or may not have run`): check state before repeating a call that changes it. The rest of this skill applies the same way.
+
 ## 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.
+
+Calls take `--timeout <ms>` (default 10000) for a slow call. To drive two apps
+at once, start named sessions (`session start --name ios`, `--name android`) and
+pass `--session <name>` on each call. A session is found from the nearest
+`package.json` above where you run: a command at a monorepo root also finds the
+one session started in an app folder under it (downward only; a nested checkout
+with its own `.git` doesn't count). With several app sessions under the root it
+connects directly, so pass `--session`.
+
 A session holds one connection for all your calls. It stops itself after 15
 minutes without calls and runs `bridge.restore` when it does.
 
-A JS reload (an error screen's Retry, or `app.reload`) throws away every pending
-restore. The session notices the app is a new runtime and reports
-`app reloaded; N pending restores lost: store, query` (the areas that
-had something to undo) as a warning on the next call (also on a failed one) and
-again in `session stop`. When you see it, redo your setup: nothing you changed
-before the reload will be undone.
+A JS reload (an error screen's Retry, or `app.reload`) throws away the app's
+undo state, except what lives in storage: string `mmkv.set`/`mmkv.delete` and
+persisted zustand stores are kept by the session and still undone by
+`bridge.restore`. The session reports what it kept, and
+`app reloaded; N pending restores lost: query, ...` (the areas that had
+something to undo) for the rest, as a warning on the next call (also on a
+failed one) and again in `session stop`. For the lost ones, redo your setup:
+they will not be undone.
 
 If a call fails with `app not connected; reconnecting` or `The app is gone`, the
 session lost the app (Metro or the app is down, or mid-reload). It retries on
@@ -55,17 +76,32 @@ its 5 s health check and on your next call: wait a few seconds and call again.
 `session stop` still works. A session never moves to another app: `<app> is
 not connected; connected: …` means its app is gone and something else is there.
 
+If a call fails with `the app reloaded during <tool>; it may or may not have run`
+(or `disconnected`, `the connection dropped`), the connection dropped mid-call
+and the session did not repeat it (only read-only tools are repeated). Check the screen or state before you call again.
+
+A `timeoutMs` in the options of `screen.waitFor` or `webview.waitFor` longer
+than the call timeout stretches it, so you don't need `--timeout` for that.
+
 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,29 +121,37 @@ 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                       # one line per button, input, text on the focused screen (--json for rects)
+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
 ```
 
+Check `tools` for `router.*` (expo-router) or `nav.*` (React Navigation). `nav.*`
+takes route names (`nav.navigate Inbox`, `nav.popTo Home`), and paths only if the
+app passed `linking`; read the returned `warning`.
+
 `press` and `fill` return once the app has rendered the result, so the next
-check sees it. Arguments are a JSON array (or a single JSON value): the array is
+check sees it. `press` on plain text presses the nearest pressable ancestor.
+Unfocused tabs (native tabs included) and screens under others count as hidden.
+Screen tools need React Native's New Architecture (Fabric); where nothing can
+be measured they fail with a message saying so (`snapshot --all` and
+`findText` still return text, without rects). Arguments are a JSON array (or a single JSON value): the array is
 spread into the tool's arguments.
 
 ## 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.
+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,
@@ -123,6 +167,7 @@ from the real state.
 | Read or set query data, store values, routes, modals; get argument shapes right | [references/state.md](references/state.md) |
 | Mock or inspect requests, or deal with strict network mode | [references/network.md](references/network.md) |
 | See or fake realtime messages (`realtime.*` in `tools`) | [references/realtime.md](references/realtime.md) |
+| Fake a deep link, background, offline, a push or the clock (`device.*` in `tools`) | [references/device.md](references/device.md) |
 | Handle a result over 32 KB or an argument over ~128 KB | [references/large-data.md](references/large-data.md) |
 | Run many calls at once, write a flow file, or measure timing | [references/flows.md](references/flows.md) |
 | Understand what restore undoes, or fix a value restore got wrong | [references/restore.md](references/restore.md) |
@@ -138,4 +183,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/device.md

@@ -0,0 +1,21 @@
+# Device events (`device.*`)
+
+Only there if the app added `deviceTools`; check `bridge.tools`.
+
+```sh
+npx @avasapp/agent-bridge call device.openUrl '"myapp://orders/5"'   # deep link into the running app; returns the route when the app passes navigation
+npx @avasapp/agent-bridge call device.appState '"background"'        # then '"active"'
+npx @avasapp/agent-bridge call device.offline true                   # fetch, XHR and NetInfo; false goes back
+npx @avasapp/agent-bridge call device.notification '[{"title":"Hi","data":{"id":5}},{"tapped":true}]'
+npx @avasapp/agent-bridge call device.setTime '"2030-01-02T03:04:05Z"'   # only with time: true
+npx @avasapp/agent-bridge call device.restore
+```
+
+- `device.openUrl` is for a running app. A cold start reads its URL before the bridge can fake it: open that link with agent-device.
+- `device.offline` fails mocked requests too. Metro stays reachable.
+- Without `{tapped:true}` a notification calls the received listeners (app open); with it, the response listeners.
+- The clock moves `Date.now()` and `new Date()` only; timers do not move. After `device.setTime`, call `device.appState '"background"'` then `'"active"'` so query caches recheck staleness (`active` alone does nothing when the app is already active). JS-driven `Animated` animations and Reanimated worklets are not shifted safely.
+- `device.offline` shows in `net.log` as `(device offline)`. NetInfo is faked only for listeners, `useNetInfo` and `NetInfo.refresh`; `fetch('wifi')` and a real native network event are not.
+- `device.notification` returns `listeners`; 0 means nothing heard it.
+- `device.openUrl` also reaches `useLinkingURL()`, but `getLinkingURL()` still reads the native value.
+- `bridge.pending` lists what is set under `device`, and `bridge.restore` undoes it.

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,23 +29,23 @@ 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
 
-export default async ({ step }) => {
+export default async ({ step, expect }) => {
   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')
+  await expect.text('Name is required')   // also expect.gone, expect.route, expect.result
 }
 ```
 
 ```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:
@@ -55,6 +55,17 @@ 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.
 
+Run several at once: `run flows/` (a directory's `*.flow.mjs`), several files, or a
+glob, in order on one connection, with a pass/fail line each and a summary; exit 1 if
+any failed. `--bail` stops at the first failure, `--grep <text>` filters by name or path
+(relative to here), `--reporter json|junit` is for CI: report on stdout with all
+other output on stderr, or `--out report.xml`. Globs only match `*.flow.mjs`. Every flow ends with
+`bridge.restore`, pass or fail (it is global: through a session it also undoes what
+you set up by hand first); `--keep` skips it to debug. A failed flow prints the
+screen elements and route. `expect.text(t)`, `expect.gone(t)`, `expect.route(path)`
+and `expect.result(tool, args, match)` (a RegExp matches a string) throw readable
+messages.
+
 `step` takes the same argument shapes as `call`; see [state.md](state.md).
 
 ## Timing

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,12 @@
 # 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, headers (credential headers such as Authorization, Cookie, *-token, *-api-key cut unless {"full": true} second)
+npx @avasapp/agent-bridge call net.waitFor '[{"path": "/orders", "method": "POST"}, {"timeoutMs": 5000}]'  # wait for it to finish
+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}`)
@@ -15,6 +16,23 @@ 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.
 
+## What a mock matches
+
+A string is a URL substring: `"/orders"` also answers `/orders/5/items`. For
+exact matches use the object form (every key given must match):
+
+```sh
+call net.mock '[{"path": "/orders/:id"}, {"json": {"id": 5}}]'                 # whole path, any host, query ignored; * is the rest
+call net.mock '[{"graphql": "GetUser"}, {"json": {"data": {}}}]'               # operationName in the POST body or ?operationName=
+call net.mock '[{"path": "/search", "body": {"filter": {"status": "open"}}}, {"json": []}]'  # JSON body contains this
+```
+
+`path` ignores case and the query, takes `:name` only as a whole segment (`/items:batchGet` is literal), and a trailing slash is optional; spaces are refused (write `%20`). A mock with only `body` or `graphql` looks at every request. `body` matches objects by key (extra keys are fine) and arrays by length and
+position; form and binary bodies never match. A batched GraphQL array body
+isn't matched by `graphql`; use `body`. `net.mockFromLog` returns a `warning` when a POST body wasn't kept and the mock may answer other operations. The reply's `matches` says it in words.
+`net.waitFor` takes the same match; pass `{"sinceId": <id from net.log>}` so an
+older request doesn't satisfy it.
+
 For a mock body too big for the command line, pass it as `@file`; see
 [large-data.md](large-data.md).
 
@@ -25,8 +43,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, faked, and `sent: true` ones the app sent (credential keys are [redacted] unless `{"full":true}`)
+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,20 +1,27 @@
 # 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
+`bridge.restore` unpins queries, puts back store, MMKV, AsyncStorage and SecureStore 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.
+A JS reload throws away the app's undo state. In a session, what lives in
+storage is kept: `mmkv.set`/`mmkv.delete` of string values and `store.set`/
+`store.call` on a persisted zustand store (one made with `persist`) are still
+undone by `bridge.restore` after the reload, and the next call says
+`app reloaded; kept N undos across the reload (...)`. A value the app changed
+after your write is left alone and named. Everything else (stores that are not
+persisted, redux, jotai, AsyncStorage and SecureStore changes, queries, mocks, `onRestore`) is lost: the session warns
+`app reloaded; N pending restores lost: ...`. Redo that setup when you see it. After a reload that also lost non-persisted changes, check `bridge.pending`: `kept N undos` does not list what was lost in the same area. `not kept across reload: store:key` means that key (a Set, Date, class instance, one `partialize` renames, or one `redact` hides) is not journaled, so the reload keeps the agent's value for it; `could not re-arm after the reload: ...` means a store or MMKV instance never became ready and its undo was dropped; `<tool> was cut off; ... that undo may be lost` means a write's reply was lost and may not be journaled.
+AsyncStorage and SecureStore values stay on disk across a reload with their old values gone, so run `bridge.restore` before `app.reload`. A key the app wrote after the agent did is left alone and returned under `skipped`.
 
 ## Mocked queries
 
@@ -38,6 +45,17 @@ with `store.set` snapshots the broken one.
   keeps the current value and drops the snapshot.
 - `store.set <store> {}` arms the snapshot before you drive the UI.
 
+`redux.*` and `jotai.*` work the same way, under their own names. `redux.set`
+snapshots each slice on its first change and restore puts back only those
+slices; `redux.dispatch` snapshots the whole state on its first call, so restore
+puts all of it back, including what the app changed in other slices after that.
+A slice or atom the app changed after the agent is left alone and returned in
+`{restored, skipped}`. `redux.commit` drops the snapshots. Jotai snapshots each
+atom on its first `jotai.set`; `jotai.commit <atom>` drops one. These snapshots
+live in memory, so **restore before `app.reload`**: with redux-persist or
+`atomWithStorage` the agent's values stay saved until then. With an async
+`atomWithStorage`, `jotai.get` the atom before the first set.
+
 ## WebViews
 
 `webview.press`, `fill` and `send` change the page and app, and restore does