@avasapp/agent-bridge 0.5.0 → 0.6.0

package/dist/adapters/redux.d.cts

@@ -0,0 +1,28 @@
+import { T as Tools } from '../types-qlwdcGjt.cjs';
+import { N as NamedRedact } from '../store-common-j0cHHvBr.cjs';
+
+/** Anything with a Redux store's shape, including Redux Toolkit's configureStore. */
+type ReduxStoreLike = {
+    getState: () => unknown;
+    dispatch(action: {
+        type: string;
+        payload?: unknown;
+    }): unknown;
+};
+
+type ReduxToolsOptions = {
+    /** By slice name, as `{ auth: ['token'] }` or `{ session: true }`, or a hook `(slice, path, value)`. */
+    redact?: NamedRedact;
+};
+/**
+ * Wrap the root reducer so the bridge can replace the state (redux.set and
+ * restore): `bridgeReducer(rootReducer)`. With redux-persist, wrap the reducer
+ * inside persistReducer: `persistReducer(config, bridgeReducer(rootReducer))`,
+ * so the saved copy follows. Release builds get the noop stub, which returns
+ * the reducer unchanged.
+ */
+declare function bridgeReducer<R extends (state: any, action: any) => any>(reducer: R): R;
+/** Read, set, dispatch to and restore a Redux store. */
+declare function reduxTools(store: ReduxStoreLike, options?: ReduxToolsOptions): Tools;
+
+export { NamedRedact as ReduxRedact, type ReduxStoreLike, type ReduxToolsOptions, bridgeReducer, reduxTools };

package/dist/adapters/secure-store.cjs

@@ -0,0 +1,169 @@
+"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/secure-store.ts
+var secure_store_exports = {};
+__export(secure_store_exports, {
+  secureStoreTools: () => secureStoreTools
+});
+module.exports = __toCommonJS(secure_store_exports);
+
+// src/adapters/storage-undo.ts
+function toStored(tool, key, value) {
+  if (typeof key !== "string" || !key)
+    throw new Error(`${tool} needs the key name as a non-empty string`);
+  if (value === void 0 || value === null)
+    throw new Error(`${tool} needs a value; use the delete tool to remove "${key}"`);
+  const stored = typeof value === "string" ? value : JSON.stringify(value);
+  if (typeof stored !== "string")
+    throw new Error(`${tool} cannot store that value as JSON`);
+  return stored;
+}
+async function change(undo, id, io, value) {
+  let entry = undo.get(id);
+  if (!entry) {
+    const original = io.read();
+    entry = { io, original, last: null };
+    undo.set(id, entry);
+    try {
+      entry.last = await original;
+    } catch (error) {
+      if (undo.get(id) === entry) undo.delete(id);
+      throw error;
+    }
+  } else {
+    await entry.original;
+  }
+  if (value === null) await io.remove();
+  else await io.write(value);
+  entry.last = value;
+}
+async function restore(undo, label) {
+  let restored = 0;
+  const skipped = [];
+  const failed = [];
+  for (const [id, entry] of [...undo]) {
+    try {
+      let original;
+      try {
+        original = await entry.original;
+      } catch {
+        undo.delete(id);
+        continue;
+      }
+      if (await entry.io.read() !== entry.last) {
+        undo.delete(id);
+        skipped.push(label(id));
+        continue;
+      }
+      if (original === null) await entry.io.remove();
+      else await entry.io.write(original);
+      undo.delete(id);
+      restored += 1;
+    } catch {
+      failed.push(label(id));
+    }
+  }
+  return { restored, skipped, failed };
+}
+function describeRestore(r, what) {
+  if (r.failed.length)
+    throw new Error(
+      `Restored ${r.restored}, could not restore: ${r.failed.join(", ")}. ${what} stay pending; run it again.`
+    );
+  return r.skipped.length ? { restored: r.restored, skipped: r.skipped } : r.restored;
+}
+
+// src/adapters/secure-store.ts
+var originals = /* @__PURE__ */ new WeakMap();
+var hide = (value) => value === null ? null : `[redacted, ${value.length} chars]`;
+function secureStoreTools(store, keys = [], options) {
+  let undo = originals.get(store);
+  if (!undo) originals.set(store, undo = /* @__PURE__ */ new Map());
+  const pending = undo;
+  const optionsFor = (key) => typeof options === "function" ? options(key) : options;
+  const guarded = (key) => optionsFor(key)?.requireAuthentication === true;
+  const idOf = (key) => {
+    const o = optionsFor(key);
+    return JSON.stringify([o?.keychainService ?? "", o?.accessGroup ?? "", key]);
+  };
+  const apply = async (key, value) => {
+    const o = optionsFor(key);
+    const io = {
+      read: () => store.getItemAsync(key, o),
+      write: (v) => store.setItemAsync(key, v, o),
+      remove: () => store.deleteItemAsync(key, o)
+    };
+    try {
+      await change(pending, idOf(key), io, value);
+    } catch (error) {
+      if (guarded(key) && !pending.has(idOf(key)))
+        throw new Error(
+          `Could not read the protected key "${key}" to save its old value (${error instanceof Error ? error.message : String(error)}); nothing was changed.`
+        );
+      throw error;
+    }
+  };
+  return {
+    "secureStore.list": {
+      description: "The keys the app passed to secureStoreTools, each with whether it is set and its length. Keys the app protects with requireAuthentication are not read (they would prompt): they show {authRequired:true}. SecureStore cannot list keys itself: for any other key, call secureStore.get with its name. Values are not shown.",
+      run: async () => Object.fromEntries(
+        await Promise.all(
+          keys.map(async (k) => {
+            if (guarded(k)) return [k, { authRequired: true }];
+            const v = await store.getItemAsync(k, optionsFor(k));
+            return [k, v === null ? { set: false } : { set: true, length: v.length }];
+          })
+        )
+      )
+    },
+    "secureStore.get": {
+      description: "A key's value, redacted to its length unless {full:true}; null when missing. Pass the key name: SecureStore has no key listing.",
+      run: async (key, getOptions) => {
+        const value = await store.getItemAsync(key, optionsFor(key));
+        return getOptions?.full ? value : hide(value);
+      }
+    },
+    "secureStore.set": {
+      description: "Set a value (a string; other values are stored as JSON). The old value is kept in memory for secureStore.restore.",
+      run: async (key, value) => {
+        await apply(key, toStored("secureStore.set", key, value));
+        return true;
+      }
+    },
+    "secureStore.delete": {
+      description: "Delete a key.",
+      run: async (key) => {
+        if (typeof key !== "string" || !key)
+          throw new Error("secureStore.delete needs the key name as a non-empty string");
+        await apply(key, null);
+        return true;
+      }
+    },
+    "secureStore.restore": {
+      // Always a plain true: bridge.pending must not show key names or values.
+      pending: () => pending.size > 0,
+      description: "Undo the agent: put back keys changed with secureStore.set or secureStore.delete (with the same options), deleting ones that did not exist. Returns how many; a key the app has written since is left alone and returned in {skipped}. Lost when the JS reloads: restore before app.reload.",
+      run: async () => describeRestore(
+        await restore(pending, (id) => JSON.parse(id)[2]),
+        "Those keys"
+      )
+    }
+  };
+}

package/dist/adapters/secure-store.d.cts

@@ -0,0 +1,28 @@
+import { T as Tools } from '../types-qlwdcGjt.cjs';
+
+/** The options expo-secure-store takes on every call. */
+type SecureStoreOptions = {
+    keychainService?: string;
+    keychainAccessible?: number;
+    requireAuthentication?: boolean;
+    authenticationPrompt?: string;
+    accessGroup?: string;
+};
+/** The expo-secure-store surface this adapter uses (`import * as SecureStore`). */
+type SecureStoreLike = {
+    getItemAsync: (key: string, options?: SecureStoreOptions) => Promise<string | null>;
+    setItemAsync: (key: string, value: string, options?: SecureStoreOptions) => Promise<void>;
+    deleteItemAsync: (key: string, options?: SecureStoreOptions) => Promise<void>;
+};
+/** One options object for every key, or a function that picks them per key. */
+type SecureStoreOptionsFor = SecureStoreOptions | ((key: string) => SecureStoreOptions | undefined);
+/**
+ * Read and write expo-secure-store. Its values are secrets, so reads are
+ * redacted unless {full:true}. It cannot list keys: pass the ones the app
+ * knows as `keys` to let `secureStore.list` show them. `options` must match
+ * what the app passes (a `keychainService` picks a different item), as one
+ * object or a function of the key.
+ */
+declare function secureStoreTools(store: SecureStoreLike, keys?: readonly string[], options?: SecureStoreOptionsFor): Tools;
+
+export { type SecureStoreLike, type SecureStoreOptions, type SecureStoreOptionsFor, secureStoreTools };

package/dist/adapters/socket-io.cjs

@@ -72,6 +72,21 @@ function tapListeners(tap, target, options) {
     };
   }
 }
+function tapOutgoing(tap, target, options) {
+  const methods = target;
+  for (const name of list(options.methods)) {
+    const send = methods[name];
+    if (typeof send !== "function") continue;
+    methods[name] = function(...args) {
+      try {
+        const channel = options.skip?.(this) ? void 0 : options.channel(args);
+        if (channel !== void 0) tap.sent(channel, options.describe(args));
+      } catch {
+      }
+      return send.apply(this, args);
+    };
+  }
+}
 function fakeableConnection(target, options) {
   const methods = target;
   const events = methods?.[options.events];
@@ -116,6 +131,46 @@ function realtimeAdapter(install) {
   };
 }
 
+// src/network/headers.ts
+var SECRET = /auth|cookie|token|secret|session|password|passwd|signature|api-?key|credential|jwt/i;
+
+// src/realtime/snapshot.ts
+var MAX_STRING = 2e3;
+var MAX_ITEMS = 50;
+var MAX_DEPTH = 5;
+var isPlain = (v) => {
+  const proto = Object.getPrototypeOf(v);
+  return proto === Object.prototype || proto === null;
+};
+function snapshot(value, depth = 0) {
+  if (typeof value === "string")
+    return value.length > MAX_STRING ? `${value.slice(0, MAX_STRING)}\u2026 (+${value.length - MAX_STRING} chars)` : value;
+  if (typeof value === "function") return "[function]";
+  if (!value || typeof value !== "object") return value;
+  if (ArrayBuffer.isView(value) || value instanceof ArrayBuffer)
+    return `[${value.constructor.name} ${value.byteLength} bytes]`;
+  if (depth >= MAX_DEPTH) return "[\u2026]";
+  if (Array.isArray(value)) {
+    const items = value.slice(0, MAX_ITEMS).map((v) => snapshot(v, depth + 1));
+    if (value.length > MAX_ITEMS) items.push(`\u2026 (+${value.length - MAX_ITEMS} items)`);
+    return items;
+  }
+  if (value instanceof Date) return value.toISOString();
+  if (!isPlain(value)) return `[${value.constructor?.name ?? "object"}]`;
+  const out = {};
+  for (const key of Object.keys(value).slice(0, MAX_ITEMS))
+    out[key] = snapshot(value[key], depth + 1);
+  return out;
+}
+function redact(value, depth = 0) {
+  if (!value || typeof value !== "object" || depth >= MAX_DEPTH + 1) return value;
+  if (Array.isArray(value)) return value.map((v) => redact(v, depth + 1));
+  const out = {};
+  for (const [key, v] of Object.entries(value))
+    out[key] = SECRET.test(key) ? "[redacted]" : redact(v, depth + 1);
+  return out;
+}
+
 // src/realtime/tap.ts
 var LOG_SIZE = 50;
 var ALL = "*";
@@ -159,6 +214,17 @@ function createRealtimeTap(options = {}) {
     }
     if (!dropped) entry.deliver(message, ...rest);
   }
+  const sent = (channel, summary) => {
+    log.push({
+      at: (/* @__PURE__ */ new Date()).toISOString(),
+      channel,
+      ...summary,
+      ..."data" in summary && { data: snapshot(summary.data) },
+      injected: false,
+      sent: true
+    });
+    if (log.length > LOG_SIZE) log.splice(0, log.length - LOG_SIZE);
+  };
   const wrap = (channel, listener, wrapOptions = {}) => {
     const entry = {
       deliver: listener,
@@ -208,11 +274,11 @@ function createRealtimeTap(options = {}) {
       }))
     },
     [`${ns}.log`]: {
-      description: `Recent messages, real and injected, newest first (last ${LOG_SIZE}). Filter: { channel?, event?, limit? }; clear: true empties the log after reading.`,
+      description: `Recent messages, real, injected, and ones the app sent (sent: true) (socket.emit, Ably publish), newest first (last ${LOG_SIZE}). Filter: { channel?, event?, limit?, full? }; clear: true empties the log after reading. Sent messages are copied and cut, and keys like token, password or authorization show [redacted] unless full: true.`,
       run: (filter = {}) => {
         const entries = log.filter(
           (e) => (!filter.channel || e.channel === filter.channel) && (!filter.event || e.event === filter.event)
-        ).reverse().slice(0, filter.limit ?? 20);
+        ).reverse().slice(0, filter.limit ?? 20).map((e) => e.sent && !filter.full && "data" in e ? { ...e, data: redact(e.data) } : e);
         if (filter.clear) log.length = 0;
         return entries;
       }
@@ -273,7 +339,7 @@ function createRealtimeTap(options = {}) {
         return { state: faked ?? connection.state(), real: connection.state(), faked: faked !== null };
       }
     };
-  return { wrap, tools };
+  return { wrap, sent, tools };
 }
 
 // src/adapters/socket-io.ts
@@ -314,6 +380,14 @@ var socketIoTools = realtimeAdapter(
       channel: ([event]) => typeof event === "string" && !RESERVED.has(event) ? event : void 0,
       message: "args"
     });
+    tapOutgoing(tap, socket, {
+      methods: "emit",
+      channel: ([event]) => typeof event === "string" && !RESERVED.has(event) ? event : void 0,
+      // socket.io's retry queue calls emit again for the same message.
+      skip: (target) => Boolean(target.flags?.fromQueue),
+      // Always the argument list, so emit('x', [1, 2]) and emit('x', 1, 2) differ.
+      describe: ([, ...args]) => ({ data: args.filter((a) => typeof a !== "function") })
+    });
     return tap;
   }
 );

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

@@ -1,4 +1,4 @@
-import { T as Tools } from '../types-BmpykP1P.cjs';
+import { T as Tools } from '../types-qlwdcGjt.cjs';
 
 type Listener = (...args: any[]) => void;
 /** A socket.io client socket (`io(url)`), typed structurally. */
@@ -6,6 +6,7 @@ type SocketLike = {
     on(event: string, listener: Listener): unknown;
     off(event?: string, listener?: Listener): unknown;
     connected?: boolean;
+    emit?(event: string, ...args: never[]): unknown;
 };
 type SocketIoToolsOptions = {
     /** Tool name prefix. Defaults to "realtime". */

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

@@ -1,4 +1,4 @@
-import { T as Tools } from '../types-BmpykP1P.cjs';
+import { T as Tools } from '../types-qlwdcGjt.cjs';
 
 /** A TanStack Query `QueryClient`, e.g. from `useQueryClient()`. */
 type QueryClientLike = {

package/dist/adapters/zustand.cjs

@@ -43,8 +43,7 @@ function toJson(value) {
   return text === void 0 ? null : JSON.parse(text);
 }
 
-// src/adapters/zustand.ts
-var snapshots = /* @__PURE__ */ new WeakMap();
+// src/adapters/store-common.ts
 var isObject = (value) => typeof value === "object" && value !== null;
 function toPath(part) {
   if (typeof part === "string") return part === "" ? [] : part.split(".");
@@ -52,7 +51,7 @@ function toPath(part) {
   if (Array.isArray(part) && part.every((p) => typeof p === "string" || typeof p === "number"))
     return part;
   throw new Error(
-    `A store path is a dotted string or an array of segments, got ${JSON.stringify(part)}`
+    `A path is a dotted string or an array of segments, got ${JSON.stringify(part)}`
   );
 }
 function at(value, path) {
@@ -62,7 +61,7 @@ function at(value, path) {
   );
 }
 var kindOf = (v) => v === null ? "null" : Array.isArray(v) ? "array" : typeof v;
-function readState(state, given) {
+function readState(state, given, tool = "store.get") {
   const args = given.filter((a) => a != null);
   const last = args.at(-1);
   const isOptions = isObject(last) && !Array.isArray(last);
@@ -70,12 +69,12 @@ function readState(state, given) {
   const unknown = Object.keys(options).filter((k) => k !== "pick" && k !== "keys");
   if (unknown.length)
     throw new Error(
-      `Unknown store.get option ${unknown.map((k) => `"${k}"`).join(", ")}. Options: pick, keys`
+      `Unknown ${tool} option ${unknown.map((k) => `"${k}"`).join(", ")}. Options: pick, keys`
     );
   const value = at(state, (isOptions ? args.slice(0, -1) : args).flatMap(toPath));
   if (options.pick !== void 0) {
     if (!Array.isArray(options.pick))
-      throw new Error("store.get pick is an array of paths");
+      throw new Error(`${tool} pick is an array of paths`);
     return Object.fromEntries(
       options.pick.map((p) => [
         Array.isArray(p) ? p.join(".") : String(p),
@@ -87,17 +86,6 @@ function readState(state, given) {
     return isObject(value) ? Object.fromEntries(Object.entries(value).map(([k, v]) => [k, kindOf(v)])) : kindOf(value);
   return value;
 }
-function restore(store, snapshot) {
-  const current = store.getState();
-  if (!isObject(snapshot) || !isObject(current)) {
-    store.setState(snapshot, true);
-    return;
-  }
-  const actions = Object.fromEntries(
-    Object.entries(current).filter(([, v]) => typeof v === "function")
-  );
-  store.setState({ ...snapshot, ...actions }, true);
-}
 var PREVIEW = 200;
 function preview(value) {
   try {
@@ -109,10 +97,11 @@ function preview(value) {
     return "[unserializable]";
   }
 }
-function differences(snapshot, current, show) {
+function differences(snapshot, current, show, only) {
   if (!isObject(snapshot) || !isObject(current)) return {};
   const out = {};
   for (const k of /* @__PURE__ */ new Set([...Object.keys(snapshot), ...Object.keys(current)])) {
+    if (only && !only.has(k)) continue;
     const a = snapshot[k];
     const b = current[k];
     if (typeof a === "function" || typeof b === "function") continue;
@@ -137,6 +126,79 @@ function redactValue(redact, name, value, path, seen = []) {
   ]);
   return Array.isArray(value) ? entries.map(([, v]) => v) : Object.fromEntries(entries);
 }
+
+// src/adapters/zustand.ts
+var HYDRATION_WAIT_MS = 2e3;
+var rev = 0;
+function survivesJson(v, depth = 0) {
+  if (v === null || typeof v === "string" || typeof v === "boolean") return true;
+  if (typeof v === "number") return Number.isFinite(v);
+  if (depth > 50 || !isObject(v)) return false;
+  if (Array.isArray(v)) return v.every((x) => survivesJson(x, depth + 1));
+  const proto = Object.getPrototypeOf(v);
+  if (proto !== Object.prototype && proto !== null) return false;
+  return Object.values(v).every((x) => x === void 0 || survivesJson(x, depth + 1));
+}
+var ok = (v) => v === void 0 || survivesJson(v);
+var has = (x, k) => x[k] !== void 0;
+function persisted(store, state) {
+  try {
+    const partialize = store.persist?.getOptions?.().partialize;
+    const part = partialize ? partialize(state) : state;
+    if (!isObject(part) || Array.isArray(part)) return void 0;
+    const raw = Object.fromEntries(Object.entries(part).filter(([, v]) => typeof v !== "function"));
+    const refused = /* @__PURE__ */ new Set();
+    if (partialize && isObject(state)) {
+      for (const [k, v] of Object.entries(raw)) if (!(k in state) || !Object.is(state[k], v)) refused.add(k);
+    }
+    return { raw, refused };
+  } catch {
+    return void 0;
+  }
+}
+var differs = (a, b) => ok(a) && ok(b) ? !same(a, b) : !Object.is(a, b);
+var json = (v) => JSON.parse(JSON.stringify(v));
+var same = (a, b) => {
+  if (Object.is(a, b)) return true;
+  if (!isObject(a) || !isObject(b) || Array.isArray(a) !== Array.isArray(b)) return false;
+  const keys = /* @__PURE__ */ new Set([...Object.keys(a), ...Object.keys(b)]);
+  return [...keys].every((k) => same(a[k], b[k]));
+};
+async function hydrated(store) {
+  const p = store.persist;
+  if (!p?.hasHydrated || p.hasHydrated()) return true;
+  return new Promise((resolve) => {
+    const off = p.onFinishHydration?.(() => finish(true));
+    const timer = setTimeout(() => finish(false), HYDRATION_WAIT_MS);
+    function finish(ok2) {
+      clearTimeout(timer);
+      off?.();
+      resolve(ok2);
+    }
+  });
+}
+var snapshots = /* @__PURE__ */ new WeakMap();
+var adoptedKeys = /* @__PURE__ */ new WeakMap();
+function restore(store, snapshot, only) {
+  const current = store.getState();
+  if (only && isObject(snapshot) && isObject(current)) {
+    const next = { ...current };
+    for (const k of only) {
+      if (k in snapshot) next[k] = snapshot[k];
+      else delete next[k];
+    }
+    store.setState(next, true);
+    return;
+  }
+  if (!isObject(snapshot) || !isObject(current)) {
+    store.setState(snapshot, true);
+    return;
+  }
+  const actions = Object.fromEntries(
+    Object.entries(current).filter(([, v]) => typeof v === "function")
+  );
+  store.setState({ ...snapshot, ...actions }, true);
+}
 function storeTools(stores, options = {}) {
   const out = (name, value, path = "") => redactValue(options.redact, name, value, path);
   const get = (name) => {
@@ -147,8 +209,26 @@ function storeTools(stores, options = {}) {
       );
     return store;
   };
+  const hidden = (name, k, ...values) => {
+    const { redact } = options;
+    if (!redact) return false;
+    if (typeof redact !== "function")
+      return !!redact[name]?.some((p) => p === k || p.startsWith(`${k}.`) || k.startsWith(`${p}.`));
+    return values.some((v) => !same(redactValue(redact, name, v, k), v));
+  };
   const beforeChange = (store) => {
-    if (!snapshots.has(store)) snapshots.set(store, store.getState());
+    rev += 1;
+    const only = adoptedKeys.get(store);
+    if (only) {
+      const next = { ...store.getState() };
+      const saved = snapshots.get(store);
+      for (const k of only) {
+        if (k in saved) next[k] = saved[k];
+        else delete next[k];
+      }
+      snapshots.set(store, next);
+      adoptedKeys.delete(store);
+    } else if (!snapshots.has(store)) snapshots.set(store, store.getState());
   };
   return {
     "store.list": {
@@ -183,7 +263,12 @@ function storeTools(stores, options = {}) {
           throw new Error(`Store "${name}" has no action "${action}"`);
         beforeChange(store);
         const before = store.getState();
-        const result = await fn(...args);
+        let result;
+        try {
+          result = await fn(...args);
+        } finally {
+          rev += 1;
+        }
         const after = store.getState();
         if (result !== void 0 && result !== before && result !== after) {
           const key = isObject(after) ? Object.keys(after).find((k) => after[k] === result) : void 0;
@@ -203,6 +288,8 @@ function storeTools(stores, options = {}) {
       description: "Keep a store as it is now: drops its pending snapshot, so bridge.restore leaves it alone and the next store.set or store.call snapshots again from this state. Use it after repairing a value that was already wrong when the snapshot was taken. Returns { store, committed } (committed: false when nothing was pending).",
       run: (name) => {
         const store = get(name);
+        rev += 1;
+        adoptedKeys.delete(store);
         return { store: name, committed: snapshots.delete(store) };
       }
     },
@@ -210,6 +297,87 @@ function storeTools(stores, options = {}) {
       maxArgs: 0,
       // Per store, its snapshot against now (secrets redacted), so an agent can
       // tell what a restore will put back before it does.
+      journalRev: () => rev,
+      // Persisted stores only: others are rebuilt from scratch on reload.
+      journal: () => {
+        const out2 = {};
+        for (const [name, store] of Object.entries(stores)) {
+          if (!store.persist || !snapshots.has(store)) continue;
+          const before = persisted(store, snapshots.get(store));
+          const now = persisted(store, store.getState());
+          if (!before || !now) continue;
+          const entry = { original: {}, after: {} };
+          const skipped = [];
+          const only = adoptedKeys.get(store);
+          for (const k of /* @__PURE__ */ new Set([...Object.keys(before.raw), ...Object.keys(now.raw)])) {
+            if (only && !only.has(k)) continue;
+            const a = before.raw[k];
+            const b = now.raw[k];
+            if (!differs(a, b)) continue;
+            if (before.refused.has(k) || now.refused.has(k) || !ok(a) || !ok(b) || hidden(name, k, a, b)) {
+              skipped.push(k);
+              continue;
+            }
+            if (has(before.raw, k)) entry.original[k] = json(a);
+            if (has(now.raw, k)) entry.after[k] = json(b);
+          }
+          if (skipped.length) entry.skipped = skipped;
+          if (skipped.length || Object.keys(entry.original).length || Object.keys(entry.after).length) out2[name] = entry;
+        }
+        return Object.keys(out2).length ? out2 : void 0;
+      },
+      adopt: async (raw) => {
+        const data = isObject(raw) && !Array.isArray(raw) ? raw : {};
+        const result = { adopted: [], already: [], changed: [] };
+        const retry = {};
+        const ready = await Promise.all(
+          Object.keys(data).map((n) => stores[n] ? hydrated(stores[n]) : false)
+        );
+        const names = Object.keys(data);
+        for (const [name, entry] of Object.entries(data)) {
+          const store = stores[name];
+          const skipped = entry?.skipped;
+          if (!isObject(entry) || !isObject(entry.original) || !isObject(entry.after) || skipped !== void 0 && !(Array.isArray(skipped) && skipped.every((k) => typeof k === "string"))) {
+            (result.invalid ?? (result.invalid = [])).push(name);
+            continue;
+          }
+          if (!store || !ready[names.indexOf(name)]) {
+            retry[name] = entry;
+            continue;
+          }
+          for (const k of skipped ?? []) (result.notKept ?? (result.notKept = [])).push(`${name}:${k}`);
+          const now = persisted(store, store.getState());
+          const saved = snapshots.has(store) && !adoptedKeys.has(store) ? persisted(store, snapshots.get(store)) : void 0;
+          const eq = (x, y, k) => has(x, k) === has(y, k) && (!has(x, k) || same(x[k], y[k]));
+          const back = [];
+          for (const k of /* @__PURE__ */ new Set([...Object.keys(entry.original), ...Object.keys(entry.after)])) {
+            const label = `${name}:${k}`;
+            if (!now || now.refused.has(k) || !ok(now.raw[k])) {
+              (result.notKept ?? (result.notKept = [])).push(label);
+              continue;
+            }
+            const savedFake = !!saved && ok(saved.raw[k]) && eq(saved.raw, entry.after, k);
+            if (!savedFake && eq(now.raw, entry.original, k)) result.already.push(label);
+            else if (savedFake || eq(now.raw, entry.after, k)) {
+              back.push(k);
+              result.adopted.push(label);
+            } else result.changed.push(label);
+          }
+          if (back.length) {
+            if (!snapshots.has(store)) adoptedKeys.set(store, /* @__PURE__ */ new Set());
+            const next = { ...snapshots.get(store) ?? store.getState() };
+            for (const k of back) {
+              if (k in entry.original) next[k] = entry.original[k];
+              else delete next[k];
+              adoptedKeys.get(store)?.add(k);
+            }
+            snapshots.set(store, next);
+            rev += 1;
+          }
+        }
+        if (Object.keys(retry).length) result.retry = retry;
+        return result;
+      },
       pending: ({ detail } = {}) => {
         const changed = Object.entries(stores).filter(([, s]) => snapshots.has(s));
         if (!changed.length) return false;
@@ -220,7 +388,8 @@ function storeTools(stores, options = {}) {
             differences(
               snapshots.get(store),
               store.getState(),
-              (key, value) => out(name, value, key)
+              (key, value) => out(name, value, key),
+              adoptedKeys.get(store)
             )
           ])
         );
@@ -228,8 +397,10 @@ function storeTools(stores, options = {}) {
       description: "Undo the agent: put back each store changed with store.set or store.call, to its state at the first of those (store.commit drops a snapshot). Returns their names.",
       run: () => Object.entries(stores).flatMap(([name, store]) => {
         if (!snapshots.has(store)) return [];
-        restore(store, snapshots.get(store));
+        rev += 1;
+        restore(store, snapshots.get(store), adoptedKeys.get(store));
         snapshots.delete(store);
+        adoptedKeys.delete(store);
         return [name];
       })
     }