@avasapp/agent-bridge 0.3.0 → 0.4.0

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

@@ -0,0 +1,79 @@
+import { T as Tools } from '../types-BmpykP1P.cjs';
+
+/** What the adapter needs from a react-native-webview instance. */
+type WebViewLike = {
+    injectJavaScript: (script: string) => void;
+    postMessage: (data: string) => void;
+    reload: () => void;
+};
+/**
+ * Keeps secrets out of the message log. Either dotted paths into JSON message
+ * bodies (`['token', 'user.phone']`), or a hook called for the whole body
+ * (`path` is `''`) and every nested value of a JSON body with its dotted path;
+ * what it returns is logged instead. Redaction is by key: a secret inside a
+ * string value is not found by a path list; scrub values in the hook. A body that isn't JSON (a script from
+ * `injectJavaScript`, plain text) can only be redacted by the hook.
+ */
+type WebViewRedact = string[] | ((webview: string, path: string, value: unknown) => unknown);
+type WebViewOptions = {
+    /** What agents call this WebView: `webview.press`'s `webview` option, `webview.snapshot <name>`. */
+    name: string;
+    /** Origins besides the page the WebView first loads that may be read and driven, e.g. `https://pay.example.com`. */
+    allowedOrigins?: string[];
+    redact?: WebViewRedact;
+    /** Your own `injectedJavaScriptBeforeContentLoaded`; it runs after the adapter's. */
+    injectedJavaScriptBeforeContentLoaded?: string;
+    /** The adapter listens to these; pass yours here so spreading `props` doesn't replace them. */
+    onLoadStart?: (event: NativeEvent) => void;
+    onLoadEnd?: (event: NativeEvent) => void;
+    onNavigationStateChange?: (event: NativeNavState) => void;
+    /** How long a call waits for the page to load and its script to check in (default 10 000 ms). */
+    firstLoadTimeoutMs?: number;
+};
+/** What react-native-webview tells the app, from native code, not from the page. */
+type NativeEvent = {
+    nativeEvent?: {
+        url?: string;
+        isTopFrame?: boolean;
+    };
+};
+type NativeNavState = {
+    url?: string;
+    loading?: boolean;
+};
+
+/**
+ * Registers a react-native-webview so agents can read and drive it. Spread
+ * `props` on the WebView and give it `wrap(onMessage)` as its `onMessage`:
+ *
+ * ```tsx
+ * const ref = useRef<WebView>(null)
+ * const webview = useWebViewTools(ref, { name: 'checkout' })
+ * <WebView ref={ref} {...webview.props} onMessage={webview.wrap(onMessage)} />
+ * ```
+ *
+ * The bridge's own replies never reach `onMessage`. Add `webviewTools()` to the
+ * bridge's tools.
+ */
+declare function useWebViewTools(ref: {
+    current: WebViewLike | null;
+}, options: WebViewOptions): {
+    props: {
+        injectedJavaScriptBeforeContentLoaded: string;
+        injectedJavaScriptBeforeContentLoadedForMainFrameOnly: true;
+        onLoadStart: (event: NativeEvent) => void;
+        onLoadEnd: (event: NativeEvent) => void;
+        onNavigationStateChange: (state: NativeNavState) => void;
+    };
+    wrap: (onMessage?: (event: never) => unknown) => (event: {
+        nativeEvent?: {
+            data?: unknown;
+            url?: string;
+            isTopFrame?: boolean;
+        };
+    }) => unknown;
+};
+/** Read and drive the WebViews registered with `useWebViewTools`. */
+declare function webviewTools(): Tools;
+
+export { type WebViewLike, type WebViewOptions, type WebViewRedact, useWebViewTools, webviewTools };

package/dist/adapters/socket-io.cjs

@@ -218,7 +218,7 @@ function createRealtimeTap(options = {}) {
       }
     },
     [`${ns}.emit`]: {
-      description: "Deliver a fake message to every listener on a channel: [channel, message]. Runs the app's own handlers. Returns { id, delivered }.",
+      description: "Deliver a fake message to every listener on a channel: [channel, message]. Runs the app's own handlers. Returns { id, delivered }." + (options.emitUsage ? ` ${options.emitUsage}` : ""),
       run: (channel, ...values) => {
         const entries = channels.get(channel);
         if (!entries?.size)
@@ -254,6 +254,7 @@ function createRealtimeTap(options = {}) {
       run: (channel) => setMute(channel, null)
     },
     [`${ns}.restore`]: {
+      pending: () => mutes.size > 0 || faked !== null,
       description: "Undo the agent: unmute every channel and go back to the real connection state.",
       run: () => {
         const unmuted = [...mutes.keys()];
@@ -294,6 +295,7 @@ var socketIoTools = realtimeAdapter(
         return { data: values.length === 1 ? values[0] : values };
       },
       toMessage: (values) => values,
+      emitUsage: `socket.io: the channel is the event name and the rest are the listener's arguments, so ["chat", "a", "b"] calls listener("a", "b"). Do not repeat the event name in the arguments.`,
       // socket.io-client announces lifecycle events with emitReserved.
       connection: fakeableConnection(socket, {
         property: "connected",

package/dist/adapters/socket-io.d.cts

@@ -1,4 +1,4 @@
-import { T as Tools } from '../types-6kKQsLC1.cjs';
+import { T as Tools } from '../types-BmpykP1P.cjs';
 
 type Listener = (...args: any[]) => void;
 /** A socket.io client socket (`io(url)`), typed structurally. */

package/dist/adapters/tanstack-query.cjs

@@ -23,6 +23,151 @@ __export(tanstack_query_exports, {
   queryTools: () => queryTools
 });
 module.exports = __toCommonJS(tanstack_query_exports);
+var import_query_core = require("@tanstack/query-core");
+
+// src/shared/mock-signal.ts
+var KEY = /* @__PURE__ */ Symbol.for("@avasapp/agent-bridge/mock-signal");
+var listeners = () => {
+  const g = globalThis;
+  return g[KEY] ?? (g[KEY] = /* @__PURE__ */ new Set());
+};
+function onMockSignal(listener) {
+  const all = listeners();
+  all.add(listener);
+  return () => {
+    all.delete(listener);
+  };
+}
+
+// src/adapters/query-mocked.ts
+var KEY2 = /* @__PURE__ */ Symbol.for("@avasapp/agent-bridge/query-mocked");
+var trackers = globalThis[KEY2] ?? (globalThis[KEY2] = /* @__PURE__ */ new WeakMap());
+var isInfinite = (query) => query.queryType === "infinite" || !!query.options.behavior;
+function trackMockedQueries(queryClient, isPinned) {
+  const existing = trackers.get(queryClient);
+  if (existing) {
+    existing.isPinned = isPinned;
+    return existing;
+  }
+  const cache = queryClient.getQueryCache();
+  const mocked = /* @__PURE__ */ new Map();
+  const inflight = /* @__PURE__ */ new Map();
+  const instrumented = /* @__PURE__ */ new WeakSet();
+  const holder = { current: null };
+  let cleared = 0;
+  const newFetch = () => ({
+    own: /* @__PURE__ */ new Set(),
+    ids: /* @__PURE__ */ new Set(),
+    loose: /* @__PURE__ */ new Set(),
+    fetchMore: false,
+    gone: false
+  });
+  const reset = (hash) => {
+    const query = cache.get(hash);
+    if (!query || tracker.isPinned(hash)) return;
+    cleared += 1;
+    queryClient.resetQueries({ queryKey: query.queryKey, exact: true }).catch(() => {
+    });
+  };
+  const instrument = (query) => {
+    if (instrumented.has(query)) return;
+    instrumented.add(query);
+    const original = query.fetch.bind(query);
+    query.fetch = ((...args) => {
+      let f = inflight.get(query.queryHash);
+      if (!f) inflight.set(query.queryHash, f = newFetch());
+      const outer = holder.current;
+      holder.current = f;
+      try {
+        return original(...args);
+      } finally {
+        holder.current = outer;
+      }
+    });
+  };
+  for (const query of cache.getAll()) instrument(query);
+  const build = cache.build.bind(cache);
+  cache.build = ((...args) => {
+    const query = build(...args);
+    instrument(query);
+    return query;
+  });
+  cache.subscribe((event) => {
+    if (event.type !== "updated") return;
+    const { query, action } = event;
+    const hash = query.queryHash;
+    if (action.type === "fetch") {
+      let f = inflight.get(hash);
+      if (!f) inflight.set(hash, f = newFetch());
+      if (action.meta?.fetchMore) f.fetchMore = true;
+    } else if (action.type === "success") {
+      if (action.manual) {
+        if (!inflight.has(hash)) mocked.delete(hash);
+        return;
+      }
+      const f = inflight.get(hash);
+      inflight.delete(hash);
+      if (!f) return;
+      const used = answeredBy(f);
+      const before = mocked.get(hash);
+      if (used.size) {
+        if (f.gone) {
+          mocked.delete(hash);
+          reset(hash);
+        } else mocked.set(hash, /* @__PURE__ */ new Set([...before ?? [], ...used]));
+      } else if (before && !f.fetchMore && !isInfinite(query)) {
+        mocked.delete(hash);
+      }
+    } else if (query.state.fetchStatus === "idle") {
+      inflight.delete(hash);
+    }
+  });
+  const tracker = {
+    isPinned,
+    pending: () => mocked.size > 0,
+    takeCleared: () => {
+      const n = cleared;
+      cleared = 0;
+      return n;
+    },
+    clear: (ids) => {
+      const before = cleared;
+      for (const [hash, from] of [...mocked]) {
+        if (ids && !ids.some((id) => from.has(id))) continue;
+        mocked.delete(hash);
+        reset(hash);
+      }
+      return cleared - before;
+    }
+  };
+  trackers.set(queryClient, tracker);
+  listen(new WeakRef(tracker), inflight, holder);
+  return tracker;
+}
+var answeredBy = (f) => /* @__PURE__ */ new Set([...f.ids, ...f.loose]);
+function listen(ref, inflight, holder) {
+  const stop = onMockSignal({
+    started: (requestId) => {
+      if (!ref.deref()) return stop();
+      holder.current?.own.add(requestId);
+    },
+    answered: (mockId, requestId) => {
+      if (!ref.deref()) return stop();
+      const owner = [...inflight.values()].find((f) => f.own.has(requestId));
+      if (owner) owner.ids.add(mockId);
+      else for (const f of inflight.values()) f.loose.add(mockId);
+    },
+    removed: (ids) => {
+      const tracker = ref.deref();
+      if (!tracker) return stop();
+      for (const f of inflight.values())
+        if (!ids || [...answeredBy(f)].some((id) => ids.includes(id))) f.gone = true;
+      tracker.clear(ids);
+    }
+  });
+}
+
+// src/adapters/tanstack-query.ts
 var pinStates = /* @__PURE__ */ new WeakMap();
 function pinStateFor(queryClient) {
   let state = pinStates.get(queryClient);
@@ -39,11 +184,56 @@ function pinStateFor(queryClient) {
   return state;
 }
 var rendered = () => new Promise((resolve) => setTimeout(resolve, 0));
+var keyOf = (args) => args.length === 1 && Array.isArray(args[0]) ? args[0] : args;
+var isGetOptions = (v) => !!v && typeof v === "object" && !Array.isArray(v) && Object.keys(v).length > 0 && Object.keys(v).every((k) => k === "pages" || k === "path");
+function slicePages(data, range) {
+  const infinite = data;
+  if (!infinite || !Array.isArray(infinite.pages))
+    throw new Error("pages only applies to an infinite query (data with a pages array)");
+  const [from, to] = Array.isArray(range) ? range : [range];
+  if (typeof from !== "number" || to !== void 0 && typeof to !== "number")
+    throw new Error(
+      `pages is [from, to] (to exclusive, like Array.slice) or a start index, got ${JSON.stringify(range)}`
+    );
+  return {
+    ...infinite,
+    pages: infinite.pages.slice(from, to),
+    ...Array.isArray(infinite.pageParams) && {
+      pageParams: infinite.pageParams.slice(from, to)
+    },
+    totalPages: infinite.pages.length
+  };
+}
+function atPath(value, path) {
+  const segments = typeof path === "string" ? path.split(".").filter(Boolean) : Array.isArray(path) && path.every((p) => typeof p === "string" || typeof p === "number") ? path : null;
+  if (!segments)
+    throw new Error(
+      `path is a dotted string or an array of segments, got ${JSON.stringify(path)}`
+    );
+  let current = value;
+  segments.forEach((segment, i) => {
+    if (current === null || typeof current !== "object" || !(String(segment) in current)) {
+      const where = segments.slice(0, i).join(".") || "the data";
+      const has = current && typeof current === "object" ? Array.isArray(current) ? `an array of ${current.length}` : `keys ${Object.keys(current).slice(0, 10).join(", ") || "(none)"}` : JSON.stringify(current) ?? "undefined";
+      throw new Error(`No "${segment}" in ${where}: it has ${has}`);
+    }
+    current = current[segment];
+  });
+  return current;
+}
 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 existingHash = (key) => cache.find({ queryKey: key, exact: true })?.queryHash ?? (0, import_query_core.hashKey)(key);
+  const arrayKey = (tool, key) => {
+    if (!Array.isArray(key))
+      throw new Error(
+        `${tool} takes the key as an array, got ${JSON.stringify(key)}. Wrap it: [[${JSON.stringify(key)}], <data>]`
+      );
+    return key;
+  };
   const apply = (key, data) => {
     state.applying = true;
     try {
@@ -63,8 +253,8 @@ function queryTools(queryClient) {
       apply(pin.key, pin.data);
     }));
   };
-  const unpin = (key) => {
-    const removed = pins.delete(hashOf(key));
+  const unpinKey = (key, hash = existingHash(key)) => {
+    const removed = pins.delete(hash);
     if (!pins.size) {
       state.unsubscribe?.();
       state.unsubscribe = null;
@@ -73,6 +263,7 @@ function queryTools(queryClient) {
       void queryClient.invalidateQueries({ queryKey: key, exact: true });
     return removed;
   };
+  const unpin = (...args) => unpinKey(keyOf(args));
   const refetchReal = (key) => {
     const query = cache.find({ queryKey: key, exact: true });
     if (!query) return false;
@@ -88,23 +279,46 @@ function queryTools(queryClient) {
     });
     return true;
   };
+  const mocked = trackMockedQueries(queryClient, (hash) => pins.has(hash));
   return {
     "query.list": {
-      description: "Cached queries: key, status, observer count, pinned.",
-      run: () => cache.getAll().map((q) => ({
+      description: 'Cached queries: key, status, fetchStatus, observer count, pinned, isStale, isInvalidated, dataUpdatedAt, errorUpdatedAt. Optional key prefix filter, e.g. ("todos") or (["todos", 1]).',
+      run: (...args) => cache.findAll(args.length ? { queryKey: keyOf(args) } : {}).map((q) => ({
         key: q.queryKey,
         status: q.state.status,
+        fetchStatus: q.state.fetchStatus,
         observers: q.getObserversCount(),
-        pinned: pins.has(q.queryHash)
+        pinned: pins.has(q.queryHash),
+        isStale: q.isStale(),
+        isInvalidated: q.state.isInvalidated,
+        dataUpdatedAt: q.state.dataUpdatedAt,
+        errorUpdatedAt: q.state.errorUpdatedAt
       }))
     },
     "query.get": {
-      description: "Cached data for a query key.",
-      run: (key) => queryClient.getQueryData(key)
+      description: 'Cached data for a query key, e.g. ("todos", 1) or (["todos", 1]). Errors when no such query is cached, listing keys that start the same. For a big one, a last { pages: [from, to] } returns only those pages of an infinite query (to exclusive, like Array.slice; adds totalPages), and { path: "pages.0.items" } returns only the value there (after pages, if both).',
+      run: (...args) => {
+        const last = args[args.length - 1];
+        const options = args.length > 1 && isGetOptions(last) && !cache.find({ queryKey: keyOf(args), exact: true }) ? last : void 0;
+        const key = keyOf(options ? args.slice(0, -1) : args);
+        if (!key.length) throw new Error("query.get needs a query key");
+        if (!cache.find({ queryKey: key, exact: true })) {
+          const near = cache.findAll({ queryKey: key.slice(0, 1) }).slice(0, 5).map((q) => JSON.stringify(q.queryKey));
+          throw new Error(
+            `No cached query with key ${JSON.stringify(key)}.${near.length ? ` Similar: ${near.join(", ")}` : " See query.list."}`
+          );
+        }
+        let data = queryClient.getQueryData(key);
+        if (options?.pages !== void 0) data = slicePages(data, options.pages);
+        if (options?.path !== void 0) data = atPath(data, options.path);
+        return data;
+      }
     },
     "query.set": {
+      maxArgs: 2,
       description: "Replace cached data once. A refetch will overwrite it; use query.pin to keep it.",
-      run: async (key, data) => {
+      run: async (given, data) => {
+        const key = arrayKey("query.set", given);
         const hash = hashOf(key);
         if (!state.changed.has(hash)) state.changed.set(hash, key);
         queryClient.setQueryData(key, data);
@@ -113,8 +327,10 @@ function queryTools(queryClient) {
       }
     },
     "query.pin": {
+      maxArgs: 2,
       description: "Seed data for a query key and keep it through refetches until unpinned.",
-      run: async (key, data) => {
+      run: async (given, data) => {
+        const key = arrayKey("query.pin", given);
         pins.set(hashOf(key), { key, data });
         watch();
         apply(key, data);
@@ -127,19 +343,40 @@ function queryTools(queryClient) {
       run: unpin
     },
     "query.unpinAll": {
+      maxArgs: 0,
       description: "Stop every pin and refetch real data.",
-      run: () => [...pins.values()].map((p) => p.key).filter((key) => unpin(key)).length
+      run: () => [...pins].filter(([hash, { key }]) => unpinKey(key, hash)).length
     },
     "query.refetch": {
-      description: "Refetch a query and return its data.",
-      run: async (key) => {
+      description: 'Refetch the queries matching a key prefix, e.g. ("todos", 1) or (["todos", 1]). Returns { matched, refetched, data } (data of the exact key); errors when none match or none can be refetched (disabled, or no queryFn).',
+      run: async (...args) => {
+        const key = keyOf(args);
+        const found = cache.findAll({ queryKey: key });
+        if (!found.length)
+          throw new Error(
+            `No cached query matches key ${JSON.stringify(key)}. See query.list.`
+          );
+        const defaultFn = queryClient.getDefaultOptions().queries?.queryFn;
+        const refetched = found.filter(
+          (q) => !q.isDisabled() && (q.options.queryFn ?? defaultFn)
+        ).length;
+        if (!refetched)
+          throw new Error(
+            `${found.length} cached ${found.length === 1 ? "query matches" : "queries match"} key ${JSON.stringify(key)}, but none can be refetched (disabled, or no queryFn).`
+          );
         await queryClient.refetchQueries({ queryKey: key });
         await rendered();
-        return queryClient.getQueryData(key);
+        return {
+          matched: found.length,
+          refetched,
+          data: queryClient.getQueryData(key)
+        };
       }
     },
     "query.restore": {
-      description: "Undo the agent: unpin everything and refetch real data for keys changed with query.set.",
+      maxArgs: 0,
+      pending: () => pins.size > 0 || state.changed.size > 0 || mocked.pending(),
+      description: "Undo the agent: unpin everything, refetch real data for keys changed with query.set, and reset queries that fetched while a net.mock answered (net.unmock and net.restore do this too). Returns { unpinned, refetched, mockedCleared }.",
       run: async () => {
         const unpinned = [...pins.values()].map((p) => p.key);
         const changed = [...state.changed].filter(([hash]) => !pins.has(hash)).map(([, key]) => key);
@@ -149,13 +386,15 @@ function queryTools(queryClient) {
         state.unsubscribe = null;
         for (const key of unpinned) refetchReal(key);
         const refetched = changed.filter((key) => refetchReal(key)).length;
+        mocked.clear();
+        const mockedCleared = mocked.takeCleared();
         await rendered();
-        return { unpinned: unpinned.length, refetched };
+        return { unpinned: unpinned.length, refetched, mockedCleared };
       }
     },
     "query.invalidate": {
-      description: "Invalidate queries matching a key prefix.",
-      run: (key) => queryClient.invalidateQueries({ queryKey: key })
+      description: 'Invalidate queries matching a key prefix, e.g. ("todos") or (["todos"]).',
+      run: (...args) => queryClient.invalidateQueries({ queryKey: keyOf(args) })
     }
   };
 }

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

@@ -1,5 +1,5 @@
 import { QueryClient } from '@tanstack/query-core';
-import { T as Tools } from '../types-6kKQsLC1.cjs';
+import { T as Tools } from '../types-BmpykP1P.cjs';
 
 /**
  * Read and seed the TanStack Query cache. `query.pin` keeps a seed in place: