@avasapp/agent-bridge 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Avas Enterprises
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,159 @@
+# @avasapp/agent-bridge
+
+Let coding agents drive a running React Native app directly. Seed data, flip flags, navigate and check the screen in **milliseconds**, without tapping through the app.
+
+## Demo
+
+![An agent hides a tab, turns on dark mode, fills in a form, seeds data, checks the screen and undoes it all](example/media/demo.gif)
+
+<!-- TODO: upload example/media/demo-x.mp4 in GitHub's web editor and put the URL it gives here. GitHub only plays an mp4 uploaded that way. -->
+
+[`example/flows/demo.mjs`](example/flows/demo.mjs) driving [the example app](example) in Expo Go, all on one Mac:
+
+| Call | Round trip |
+| --- | --- |
+| `bridge.ping` | 1–4 ms |
+| `screen.findText`, `screen.waitFor` (already there) | 3–9 ms |
+| `screen.fill`, `screen.press` | 20–65 ms, render included |
+| `query.pin`, `store.call`, `router.navigate` | 11–44 ms, render included |
+| 14 steps, no pauses | 0.8 s wall, 0.4 s of it waiting on a save |
+
+```
+14 steps, all local on one Mac:   0.8 s wall with no pauses
+same flow from another machine:   ~57 ms per call (network)
+same screen check via a11y tree:  450–970 ms
+```
+
+Works on Expo (dev-tools socket) and on bare React Native (CDP over Metro). Dev builds only: release builds get empty stubs.
+
+## Install
+
+```sh
+bun add -d @avasapp/agent-bridge   # or npm / yarn / pnpm
+```
+
+## In the app
+
+Mount the hook in a file that only runs in development. You choose every tool; adapters for common libraries are one import away.
+
+```tsx
+import { cdpTransport, useAgentBridge } from '@avasapp/agent-bridge'
+import { expoTransport } from '@avasapp/agent-bridge/expo'
+import { queryTools } from '@avasapp/agent-bridge/tanstack-query'
+import { storeTools } from '@avasapp/agent-bridge/zustand'
+import { mmkvTools } from '@avasapp/agent-bridge/react-native-mmkv'
+import { routerTools } from '@avasapp/agent-bridge/expo-router'
+import { networkTools } from '@avasapp/agent-bridge/network'
+import { router, useNavigationContainerRef } from 'expo-router'
+
+export function AgentBridge() {
+  const queryClient = useQueryClient()
+  useAgentBridge({
+    name: 'my-app',
+    transports: [expoTransport(), cdpTransport()],
+    tools: {
+      ...queryTools(queryClient),
+      ...storeTools({ settings: useSettingsStore, auth: useAuthStore }),
+      ...mmkvTools({ storage }),
+      ...routerTools(router, { navigation: useNavigationContainerRef() }),
+      ...networkTools(),
+      // Your own tools: any function, JSON in and out.
+      'auth.signIn': (session) => signInWith(session),
+    },
+  })
+  return null
+}
+```
+
+Every app also gets:
+
+- `screen.snapshot`: buttons, inputs, text and `testID` views on screen, with positions.
+- `screen.fill`, `screen.press`: call an input's or button's own handlers, found by `testID`, label, placeholder or text, and return once React has rendered the result.
+- `screen.waitFor`, `screen.findText`: wait for, or check, text or a target on screen.
+- `bridge.restore`: undo what the agent changed, by running every `*.restore` tool.
+- `bridge.logs`, `bridge.ping`, `bridge.tools`.
+
+Custom tools that change the screen can `await settle()` (from `@avasapp/agent-bridge`) so the next check sees the render.
+
+Errors come back on their own: each reply carries what the app logged with `console.error`, threw or left unhandled since the previous reply, tagged with the call it happened during or after.
+
+## From the agent
+
+```sh
+npx agent-bridge session start            # hold one connection; call/tools/run reuse it
+npx agent-bridge tools
+npx agent-bridge call query.pin '[["features"], {"beta": false}]'
+npx agent-bridge call screen.press '"add-plant"'
+npx agent-bridge call screen.fill '["plant-name", "Fiddle leaf fig"]'
+npx agent-bridge call screen.waitFor '"Name is required"'
+npx agent-bridge run flows/add-plant.mjs --strict   # fail if the app logged an error
+npx agent-bridge session stop             # runs bridge.restore, then disconnects
+```
+
+A session stops itself, restore included, after 15 minutes without calls (`--idle`), and reconnects if the app reloads.
+
+```ts
+import { connect } from '@avasapp/agent-bridge/client'
+
+const app = await connect({ metro: 'localhost:8081' })
+await app.call('router.navigate', '/add')
+await app.call('screen.fill', 'plant-name', 'Fiddle leaf fig')
+await app.call('screen.press', 'save-plant')
+```
+
+A flow is a module the CLI runs without a model in the loop:
+
+```js
+export default async ({ step }) => {
+  await step('flag: beta off', 'query.pin', ['features'], { beta: false })
+  await step('save empty form', 'screen.press', 'save-plant')
+  await step('error shown', 'screen.waitFor', 'Name is required')
+  await step('undo', 'bridge.restore')
+}
+```
+
+No device tool is needed. Pair one (such as agent-device) with the bridge for what it can't reach: system alerts, permission prompts, the keyboard, screenshots, and one real tap per flow.
+
+## Adapters
+
+| Import | Tools | Needs |
+| --- | --- | --- |
+| `@avasapp/agent-bridge/tanstack-query` | `query.list` `get` `set` `pin` `unpin` `unpinAll` `refetch` `invalidate` `restore` | your `QueryClient` |
+| `@avasapp/agent-bridge/zustand` | `store.list` `get` `set` `call` `restore` | your stores |
+| `@avasapp/agent-bridge/react-native-mmkv` | `mmkv.list` `keys` `get` `set` `delete` `restore` | your MMKV instances |
+| `@avasapp/agent-bridge/expo-router` | `router.navigate` `push` `replace` `back` `current` | `router` and `useNavigationContainerRef()` from expo-router |
+| `@avasapp/agent-bridge/network` | `net.log` `mock` `mocks` `unmock` `clear` `restore` | nothing: patches `fetch` and `XMLHttpRequest` in dev |
+
+A pin keeps seeded data in place through refetches until you unpin it. `net.mock('/inbox', { status: 500 })` or `{ offline: true }` fails a route; apps can fake a whole backend with `mockRequests` from the same import.
+
+## Transports
+
+| | Expo dev-tools socket | CDP |
+| --- | --- | --- |
+| Round trip, local | 0.5 ms | 1.3 ms |
+| Emoji in payloads | yes | yes (escaped for you) |
+| Works with | Expo CLI | any RN app on Metro |
+
+`connect()` tries Expo first and falls back to CDP.
+
+## Release builds
+
+Every entry point is gated on `process.env.NODE_ENV`, like `react/index.js`: Metro inlines it and a release bundle gets empty stubs. Check a bundle in CI:
+
+```sh
+npx agent-bridge assert-absent path/to/main.jsbundle
+```
+
+## Traps we hit
+
+- **Run the agent on the machine with the simulator.** Every call pays the network otherwise.
+- **Hidden tabs stay mounted.** `screen.findText` skips anything under an inactive `RNSScreen`.
+- **Expo checks the debugger's Origin** against the host Metro advertises and drops mismatches silently. The client reads it from the manifest.
+- **Expo's socket broadcasts to every app.** Calls are addressed to one device; pick it with `--device` when several are connected.
+- **Screen checks through the accessibility tree are slow** (hundreds of ms each). Check in-app, and keep one real UI check per flow.
+- **`screen.fill` skips the keyboard.** It runs the input's handlers, so validation and state are real, but autocorrect, native `maxLength` and uncontrolled inputs' native text are not.
+- **Keep your `QueryClient` in state** (`useState(() => new QueryClient())`). Created at module level, a Fast Refresh can leave the bridge holding a different client than the screen.
+
+## License
+
+MIT © Avas Enterprises

package/dist/adapters/expo-router.cjs

@@ -0,0 +1,144 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/adapters/expo-router.ts
+var expo_router_exports = {};
+__export(expo_router_exports, {
+  routerTools: () => routerTools
+});
+module.exports = __toCommonJS(expo_router_exports);
+var ROOT = "__root";
+var NOT_FOUND = "+not-found";
+var SETTLE_MS = 1e3;
+var decode = (value) => {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return value;
+  }
+};
+var isGroup = (segment) => segment.startsWith("(") && segment.endsWith(")");
+var focused = (state) => state.routes[state.index ?? 0];
+function routeFromState(state) {
+  let route = state && focused(state);
+  if (!route) return { pathname: "/", href: "/", params: {}, segments: [], name: "" };
+  if (route.name !== ROOT) {
+    const path = route.path ?? (route.name === NOT_FOUND ? "/" : `/${route.name}`);
+    return { pathname: path, href: path, params: {}, segments: [route.name], name: route.name };
+  }
+  const segments = [];
+  const raw = {};
+  let name = "";
+  let next = route.state;
+  while (next && (route = focused(next))) {
+    Object.assign(raw, route.params);
+    name = route.name;
+    segments.push(...route.name.replace(/^\//, "").split("/"));
+    next = route.state;
+  }
+  let pending = route?.params;
+  while (pending && typeof pending.screen === "string") {
+    segments.push(...pending.screen.replace(/^\//, "").split("/"));
+    name = pending.screen;
+    pending = pending.params && typeof pending.params === "object" ? pending.params : void 0;
+  }
+  if (segments.at(-1) === "index") segments.pop();
+  delete raw.screen;
+  delete raw.params;
+  const params = {};
+  for (const [key, value] of Object.entries(raw)) {
+    if (typeof value === "string") params[key] = decode(value);
+    else if (Array.isArray(value)) params[key] = value.map((v) => decode(String(v)));
+    else if (value != null) params[key] = String(value);
+  }
+  const inPath = /* @__PURE__ */ new Set();
+  const fill = (key) => {
+    inPath.add(key);
+    const value = params[key];
+    return value === void 0 ? [] : Array.isArray(value) ? value : [value];
+  };
+  const pathname = "/" + segments.filter((s) => !isGroup(s)).flatMap((s) => {
+    if (s === NOT_FOUND) return fill("not-found");
+    if (s.startsWith("[...") && s.endsWith("]")) return fill(s.slice(4, -1).replace(/\?$/, ""));
+    if (s.startsWith("[") && s.endsWith("]")) return fill(s.slice(1, -1));
+    return [s];
+  }).join("/");
+  const search = new URLSearchParams();
+  for (const [key, value] of Object.entries(params))
+    if (!inPath.has(key)) for (const v of [value].flat()) search.append(key, v);
+  const query = search.toString();
+  return { pathname, href: query ? `${pathname}?${query}` : pathname, params, segments, name };
+}
+function settle(navigation, go) {
+  return new Promise((resolve, reject) => {
+    let off;
+    const done = () => {
+      off?.();
+      clearTimeout(timer);
+      resolve();
+    };
+    const timer = setTimeout(done, navigation.addListener ? SETTLE_MS : 0);
+    off = navigation.addListener?.("__unsafe_action__", done);
+    try {
+      go();
+    } catch (error) {
+      off?.();
+      clearTimeout(timer);
+      reject(error);
+    }
+  });
+}
+function routerTools(router, options = {}) {
+  const { navigation } = options;
+  const go = (fn, value) => navigation ? settle(navigation, fn).then(() => value) : (fn(), value);
+  return {
+    "router.navigate": {
+      description: "Go to a route, reusing it if it is already in the stack.",
+      run: (href) => go(() => router.navigate(href), href)
+    },
+    "router.push": {
+      description: "Push a route.",
+      run: (href) => go(() => router.push(href), href)
+    },
+    "router.replace": {
+      description: "Replace the current route.",
+      run: (href) => go(() => router.replace(href), href)
+    },
+    "router.back": {
+      description: "Go back if possible. Returns whether it could.",
+      run: () => {
+        const could = router.canGoBack();
+        return could ? go(() => router.back(), true) : false;
+      }
+    },
+    "router.current": {
+      description: "The current route: pathname, href, params, segments, name, canGoBack.",
+      run: () => {
+        if (!navigation)
+          throw new Error(
+            "router.current needs the navigation container. Pass it: routerTools(router, { navigation: useNavigationContainerRef() }) with useNavigationContainerRef from expo-router."
+          );
+        if (navigation.isReady && !navigation.isReady())
+          throw new Error("The navigation container has not mounted yet.");
+        const state = navigation.getRootState();
+        return { ...routeFromState(state), canGoBack: router.canGoBack() };
+      }
+    }
+  };
+}

package/dist/adapters/expo-router.d.cts

@@ -0,0 +1,38 @@
+import { T as Tools } from '../types-C6DUUHnB.cjs';
+
+/** The imperative `router` from expo-router. Passed in, so this adds no dependency. */
+type RouterLike = {
+    navigate(href: never): void;
+    push(href: never): void;
+    replace(href: never): void;
+    back(): void;
+    canGoBack(): boolean;
+};
+/** The root navigation container, from `useNavigationContainerRef()` in expo-router. */
+type NavigationLike = {
+    getRootState(): unknown;
+    isReady?(): boolean;
+    addListener?(type: '__unsafe_action__', callback: () => void): () => void;
+};
+type RouterToolsOptions = {
+    /** Enables `router.current`, and makes navigation tools return once the route has changed. */
+    navigation?: NavigationLike;
+};
+/** Where the app is, as expo-router's `usePathname`, `useSegments` and `useGlobalSearchParams` would say. */
+type CurrentRoute = {
+    pathname: string;
+    /** `pathname` plus the params that are not part of the path, e.g. `/inbox?filter=unread`. */
+    href: string;
+    params: Record<string, string | string[]>;
+    segments: string[];
+    /** The focused route's name in its navigator, e.g. `index` or `[id]`. */
+    name: string;
+    canGoBack: boolean;
+};
+/**
+ * Navigate without taps. Pass `router` from `expo-router`, and
+ * `{ navigation: useNavigationContainerRef() }` to read the current route.
+ */
+declare function routerTools(router: RouterLike, options?: RouterToolsOptions): Tools;
+
+export { type CurrentRoute, type NavigationLike, type RouterLike, type RouterToolsOptions, routerTools };

package/dist/adapters/react-native-mmkv.cjs

@@ -0,0 +1,102 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/adapters/react-native-mmkv.ts
+var react_native_mmkv_exports = {};
+__export(react_native_mmkv_exports, {
+  mmkvTools: () => mmkvTools
+});
+module.exports = __toCommonJS(react_native_mmkv_exports);
+var originals = /* @__PURE__ */ new WeakMap();
+function remove(mmkv, name, key) {
+  if (mmkv.remove) mmkv.remove(key);
+  else if (mmkv.delete) mmkv.delete(key);
+  else throw new Error(`MMKV instance "${name}" has neither remove() nor delete()`);
+}
+function mmkvTools(instances) {
+  const get = (name) => {
+    const mmkv = instances[name];
+    if (!mmkv)
+      throw new Error(
+        `Unknown MMKV instance "${name}". Known: ${Object.keys(instances).join(", ")}`
+      );
+    return mmkv;
+  };
+  const beforeChange = (mmkv, key) => {
+    let saved = originals.get(mmkv);
+    if (!saved) originals.set(mmkv, saved = /* @__PURE__ */ new Map());
+    if (saved.has(key)) return;
+    const exists = mmkv.contains?.(key) ?? mmkv.getAllKeys().includes(key);
+    saved.set(key, exists ? mmkv.getString(key) ?? null : void 0);
+  };
+  return {
+    "mmkv.list": {
+      description: "Instance names.",
+      run: () => Object.keys(instances)
+    },
+    "mmkv.keys": {
+      description: "Keys in an instance.",
+      run: (name) => get(name).getAllKeys()
+    },
+    "mmkv.get": {
+      description: "A string value; parsed as JSON when {json:true}.",
+      run: (name, key, options) => {
+        const raw = get(name).getString(key);
+        return options?.json && raw !== void 0 ? JSON.parse(raw) : raw;
+      }
+    },
+    "mmkv.set": {
+      description: "Set a value. Objects and arrays are stored as JSON strings.",
+      run: (name, key, value) => {
+        const stored = typeof value === "string" || typeof value === "number" || typeof value === "boolean" ? value : JSON.stringify(value);
+        const mmkv = get(name);
+        beforeChange(mmkv, key);
+        mmkv.set(key, stored);
+        return true;
+      }
+    },
+    "mmkv.delete": {
+      description: "Delete a key.",
+      run: (name, key) => {
+        const mmkv = get(name);
+        beforeChange(mmkv, key);
+        remove(mmkv, name, key);
+        return true;
+      }
+    },
+    "mmkv.restore": {
+      description: "Undo the agent: put back keys changed with mmkv.set or mmkv.delete, deleting ones that did not exist. Returns how many.",
+      run: () => {
+        let restored = 0;
+        for (const [name, mmkv] of Object.entries(instances)) {
+          const saved = originals.get(mmkv);
+          if (!saved) continue;
+          for (const [key, value] of saved) {
+            if (value === null) continue;
+            if (value === void 0) remove(mmkv, name, key);
+            else mmkv.set(key, value);
+            restored += 1;
+          }
+          originals.delete(mmkv);
+        }
+        return restored;
+      }
+    }
+  };
+}

package/dist/adapters/react-native-mmkv.d.cts

@@ -0,0 +1,15 @@
+import { T as Tools } from '../types-C6DUUHnB.cjs';
+
+/** The MMKV surface this adapter uses. v3 has `delete`, v4 has `remove`. */
+type MMKVLike = {
+    getAllKeys: () => string[];
+    getString: (key: string) => string | undefined;
+    set: (key: string, value: string | number | boolean) => void;
+    contains?: (key: string) => boolean;
+    delete?: (key: string) => void;
+    remove?: (key: string) => unknown;
+};
+/** Read and write named MMKV instances. */
+declare function mmkvTools(instances: Record<string, MMKVLike>): Tools;
+
+export { type MMKVLike, mmkvTools };

package/dist/adapters/tanstack-query.cjs

@@ -0,0 +1,161 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/adapters/tanstack-query.ts
+var tanstack_query_exports = {};
+__export(tanstack_query_exports, {
+  queryTools: () => queryTools
+});
+module.exports = __toCommonJS(tanstack_query_exports);
+var pinStates = /* @__PURE__ */ new WeakMap();
+function pinStateFor(queryClient) {
+  let state = pinStates.get(queryClient);
+  if (!state) {
+    state = {
+      pins: /* @__PURE__ */ new Map(),
+      changed: /* @__PURE__ */ new Map(),
+      seeded: /* @__PURE__ */ new WeakSet(),
+      applying: false,
+      unsubscribe: null
+    };
+    pinStates.set(queryClient, state);
+  }
+  return state;
+}
+var rendered = () => new Promise((resolve) => setTimeout(resolve, 0));
+function queryTools(queryClient) {
+  const cache = queryClient.getQueryCache();
+  const state = pinStateFor(queryClient);
+  const { pins, seeded } = state;
+  const hashOf = (key) => cache.build(queryClient, { queryKey: key }).queryHash;
+  const apply = (key, data) => {
+    state.applying = true;
+    try {
+      queryClient.setQueryData(key, data);
+    } finally {
+      state.applying = false;
+    }
+    const stored = queryClient.getQueryData(key);
+    if (stored && typeof stored === "object") seeded.add(stored);
+  };
+  const watch = () => {
+    state.unsubscribe ?? (state.unsubscribe = cache.subscribe((event) => {
+      if (state.applying || event.type !== "updated") return;
+      const pin = pins.get(event.query.queryHash);
+      const data = event.query.state.data;
+      if (!pin || data && typeof data === "object" && seeded.has(data)) return;
+      apply(pin.key, pin.data);
+    }));
+  };
+  const unpin = (key) => {
+    const removed = pins.delete(hashOf(key));
+    if (!pins.size) {
+      state.unsubscribe?.();
+      state.unsubscribe = null;
+    }
+    if (removed)
+      void queryClient.invalidateQueries({ queryKey: key, exact: true });
+    return removed;
+  };
+  const refetchReal = (key) => {
+    const query = cache.find({ queryKey: key, exact: true });
+    if (!query) return false;
+    const queryFn = query.options.queryFn ?? queryClient.getDefaultOptions().queries?.queryFn;
+    if (!queryFn) {
+      cache.remove(query);
+      return false;
+    }
+    void queryClient.invalidateQueries({
+      queryKey: key,
+      exact: true,
+      refetchType: "all"
+    });
+    return true;
+  };
+  return {
+    "query.list": {
+      description: "Cached queries: key, status, observer count, pinned.",
+      run: () => cache.getAll().map((q) => ({
+        key: q.queryKey,
+        status: q.state.status,
+        observers: q.getObserversCount(),
+        pinned: pins.has(q.queryHash)
+      }))
+    },
+    "query.get": {
+      description: "Cached data for a query key.",
+      run: (key) => queryClient.getQueryData(key)
+    },
+    "query.set": {
+      description: "Replace cached data once. A refetch will overwrite it; use query.pin to keep it.",
+      run: async (key, data) => {
+        const hash = hashOf(key);
+        if (!state.changed.has(hash)) state.changed.set(hash, key);
+        queryClient.setQueryData(key, data);
+        await rendered();
+        return queryClient.getQueryData(key);
+      }
+    },
+    "query.pin": {
+      description: "Seed data for a query key and keep it through refetches until unpinned.",
+      run: async (key, data) => {
+        pins.set(hashOf(key), { key, data });
+        watch();
+        apply(key, data);
+        await rendered();
+        return queryClient.getQueryData(key);
+      }
+    },
+    "query.unpin": {
+      description: "Stop pinning a key and refetch its real data.",
+      run: unpin
+    },
+    "query.unpinAll": {
+      description: "Stop every pin and refetch real data.",
+      run: () => [...pins.values()].map((p) => p.key).filter((key) => unpin(key)).length
+    },
+    "query.refetch": {
+      description: "Refetch a query and return its data.",
+      run: async (key) => {
+        await queryClient.refetchQueries({ queryKey: key });
+        await rendered();
+        return queryClient.getQueryData(key);
+      }
+    },
+    "query.restore": {
+      description: "Undo the agent: unpin everything and refetch real data for keys changed with query.set.",
+      run: async () => {
+        const unpinned = [...pins.values()].map((p) => p.key);
+        const changed = [...state.changed].filter(([hash]) => !pins.has(hash)).map(([, key]) => key);
+        pins.clear();
+        state.changed.clear();
+        state.unsubscribe?.();
+        state.unsubscribe = null;
+        for (const key of unpinned) refetchReal(key);
+        const refetched = changed.filter((key) => refetchReal(key)).length;
+        await rendered();
+        return { unpinned: unpinned.length, refetched };
+      }
+    },
+    "query.invalidate": {
+      description: "Invalidate queries matching a key prefix.",
+      run: (key) => queryClient.invalidateQueries({ queryKey: key })
+    }
+  };
+}

package/dist/adapters/tanstack-query.d.cts

@@ -0,0 +1,10 @@
+import { QueryClient } from '@tanstack/query-core';
+import { T as Tools } from '../types-C6DUUHnB.cjs';
+
+/**
+ * Read and seed the TanStack Query cache. `query.pin` keeps a seed in place:
+ * when a refetch lands with real data, the seed is put back until unpinned.
+ */
+declare function queryTools(queryClient: QueryClient): Tools;
+
+export { queryTools };