@vinaverse/client 0.1.0-alpha.6 → 0.1.0-alpha.8

package/dist/agent/index.cjs

@@ -1816,6 +1816,7 @@ var ConversationStore = class {
       throw new RangeError(`A message is at most ${MAX_TEXT} characters.`);
     const id = (this.options.createId ?? randomId)();
     this.sent.set(id, { text: text2, order: lastOrder(this.engine.state()) + 0.5 });
+    this.tellActivity({ type: "message_sent", id });
     if (!this.session) {
       this.early.set(id, text2);
       void this.ensureSession("open");
@@ -2063,9 +2064,30 @@ var ConversationStore = class {
     this.lastStatus = status;
     this.update();
   }
+  /** The app's analytics hears of a step; what it throws is reported (`onError`), never in the way of a send or a frame. */
+  tellActivity(activity) {
+    try {
+      this.options.onActivity?.(activity);
+    } catch (error) {
+      this.options.onError?.(error);
+    }
+  }
+  /** The live frames analytics hears of: a reply finished, cards drawn. */
+  activity(frame) {
+    if (!this.options.onActivity) return;
+    const on = (a) => this.tellActivity(a);
+    if (frame.type === "message.completed" && typeof frame.turn_id === "string")
+      on({ type: "reply_completed", turnId: frame.turn_id });
+    if (frame.type === "ui.cards" && Array.isArray(frame.cards)) {
+      for (const card of frame.cards)
+        if (typeof card.id === "string" && typeof card.kind === "string")
+          on({ type: "card_shown", cardId: card.id, kind: card.kind });
+    }
+  }
   event(event) {
     const frame = event;
     const str2 = (v) => typeof v === "string" ? v : null;
+    this.activity(frame);
     const add = (key, kind, data) => {
       if (this.system.some((s) => s.item.key === key)) return;
       this.system = [
@@ -2448,7 +2470,106 @@ var AgentRefusal = class extends Error {
   reason;
   code;
 };
+var GREETED = "vinaverse.greeted";
+var GREETED_BEFORE = "vinaverse.agent.greeted";
+function greetedKey(subject, mode) {
+  return `${GREETED}.${JSON.stringify([subject, mode])}`;
+}
+function tupleOf(key, prefix) {
+  if (!key.startsWith(`${prefix}.[`)) return null;
+  try {
+    const t = JSON.parse(key.slice(prefix.length + 1));
+    return Array.isArray(t) ? t : null;
+  } catch {
+    return null;
+  }
+}
+function legacyTranscripts(keys, prefix) {
+  const out = [];
+  for (const key of keys) {
+    const t = tupleOf(key, prefix);
+    if (t)
+      out.push(
+        `${prefix}.${t[1] ?? "guest"}|${t[2]}|${t[3] ?? "-"}|${t[4] ?? "chat"}`
+      );
+  }
+  return out;
+}
+function legacyGreetings(pairs) {
+  const out = [];
+  for (const [subject, mode] of pairs)
+    out.push(`${GREETED_BEFORE}.${subject ?? "guest"}:${mode}`);
+  return out;
+}
 var NOT_KEPT = /* @__PURE__ */ new Set(["starting", "unavailable", "unauthorized", "closed"]);
+var CLEARED = { screen: "other" };
+function hashKey(key, salt) {
+  return `k${sha256(`${salt}\0${key}`).slice(0, 32)}`;
+}
+var K;
+var H;
+function sha256(text2) {
+  if (!K || !H) {
+    K = [];
+    H = [];
+    for (let n = 2; K.length < 64; n++) {
+      let prime = true;
+      for (let d = 2; d * d <= n; d++) if (n % d === 0) prime = false;
+      if (!prime) continue;
+      if (H.length < 8) H.push(Math.sqrt(n) % 1 * 2 ** 32 | 0);
+      K.push(Math.cbrt(n) % 1 * 2 ** 32 | 0);
+    }
+  }
+  const bytes = [];
+  const s = encodeURIComponent(text2);
+  for (let i = 0; i < s.length; i++)
+    if (s[i] === "%") {
+      bytes.push(Number.parseInt(s.slice(i + 1, i + 3), 16));
+      i += 2;
+    } else bytes.push(s.charCodeAt(i));
+  const bits = bytes.length * 8;
+  bytes.push(128);
+  while (bytes.length % 64 !== 56) bytes.push(0);
+  for (const word of [Math.floor(bits / 2 ** 32), bits >>> 0])
+    bytes.push(
+      word >>> 24,
+      word >>> 16 & 255,
+      word >>> 8 & 255,
+      word & 255
+    );
+  const h = [...H];
+  const w = new Array(64);
+  const ror = (x, n) => x >>> n | x << 32 - n;
+  for (let at = 0; at < bytes.length; at += 64) {
+    for (let i = 0; i < 64; i++) {
+      if (i < 16) {
+        const b2 = at + i * 4;
+        w[i] = bytes[b2] << 24 | bytes[b2 + 1] << 16 | bytes[b2 + 2] << 8 | bytes[b2 + 3];
+      } else {
+        const x = w[i - 15];
+        const y = w[i - 2];
+        w[i] = w[i - 16] + (ror(x, 7) ^ ror(x, 18) ^ x >>> 3) + w[i - 7] + (ror(y, 17) ^ ror(y, 19) ^ y >>> 10) | 0;
+      }
+    }
+    let [a, b, c, d, e, f, g, k] = h;
+    for (let i = 0; i < 64; i++) {
+      const t1 = k + (ror(e, 6) ^ ror(e, 11) ^ ror(e, 25)) + (e & f ^ ~e & g) + K[i] + w[i] | 0;
+      const t2 = (ror(a, 2) ^ ror(a, 13) ^ ror(a, 22)) + (a & b ^ a & c ^ b & c) | 0;
+      k = g;
+      g = f;
+      f = e;
+      e = d + t1 | 0;
+      d = c;
+      c = b;
+      b = a;
+      a = t1 + t2 | 0;
+    }
+    [a, b, c, d, e, f, g, k].forEach((v, i) => {
+      h[i] = h[i] + v | 0;
+    });
+  }
+  return h.map((v) => (v >>> 0).toString(16).padStart(8, "0")).join("");
+}
 var NO_FEATURES = {
   history: false,
   memory: false,
@@ -2456,8 +2577,14 @@ var NO_FEATURES = {
   businessSetup: false
 };
 var SYSTEM_CLOCK = { now: () => Date.now() };
-function agentKey(key) {
-  return `${key.subject ?? "guest"}|${key.mode}|${key.scope ?? "-"}|${key.thread ?? "chat"}`;
+function agentKey(key, agent = null) {
+  return JSON.stringify([
+    agent,
+    key.subject,
+    key.mode,
+    key.scope ?? null,
+    key.thread ?? "chat"
+  ]);
 }
 var samePlace = (a, b) => a?.screen === b?.screen && (a?.entity?.type ?? null) === (b?.entity?.type ?? null) && (a?.entity?.id ?? null) === (b?.entity?.id ?? null) && JSON.stringify(a?.filters ?? null) === JSON.stringify(b?.filters ?? null);
 function usable(session, insecure) {
@@ -2467,9 +2594,12 @@ function warnInsecure(insecure, warn) {
   if (!(insecure.realtime || insecure.turns)) return;
   if (globalThis.__DEV__ === true) return;
   warn(
-    "@vinaverse/client/agent: insecureAddresses lets sessions use plaintext ws:// or http:// addresses. It is for mocks and local development only; remove it from release builds."
+    "@vinaverse/client/agent: insecureAddresses lets sessions use plaintext ws:// or http:// addresses. For mocks and local development only.",
+    { code: "insecure_addresses" }
   );
 }
+var OPEN_KEPT_MS = 24 * 36e5;
+var MAX_WAITING = 100;
 function createAgentRuntime(options) {
   const { backend } = options;
   const policy = {
@@ -2487,7 +2617,76 @@ function createAgentRuntime(options) {
   let status = null;
   let reading = null;
   let sessionName = null;
-  const emit = (event) => options.onEvent?.(event);
+  let generation = 0;
+  const keyOf = (key) => agentKey(key, options.agent ?? null);
+  const prefix = options.conversation?.persistenceKey ?? "vinaverse.agent";
+  const storage = guardedStorage(
+    options.conversation?.persistence,
+    prefix,
+    () => generation
+  );
+  const greetings = guardedStorage(
+    options.greetingStorage,
+    GREETED,
+    () => generation
+  );
+  const warn = options.onWarning ?? ((m) => console.warn(m));
+  const isolated = (what, call) => {
+    try {
+      call();
+    } catch (error) {
+      warn(
+        `@vinaverse/client/agent: the app's ${what} threw (${error instanceof Error ? error.message : String(error)}); the conversation went on.`,
+        { code: "callback_threw", callback: what }
+      );
+    }
+  };
+  const saltStore = options.conversation?.persistence ?? options.greetingStorage;
+  const saltKey = `${prefix}:salt`;
+  let salt = null;
+  const waiting = [];
+  const loadSalt = () => {
+    if (!options.onEvent) return;
+    const settle = (kept2) => {
+      if (salt !== null) return;
+      if (kept2) salt = kept2;
+      else {
+        salt = randomId().slice(3);
+        void Promise.resolve(saltStore?.setItem(saltKey, salt)).catch(
+          () => void 0
+        );
+      }
+      for (const event of waiting.splice(0)) deliver(event);
+    };
+    try {
+      const got = saltStore?.getItem(saltKey);
+      if (typeof got === "string" || got == null) settle(got);
+      else got.then(settle, () => settle(null));
+    } catch {
+      settle(null);
+    }
+  };
+  const deliver = (event) => isolated(
+    "onEvent",
+    () => options.onEvent?.(
+      event.key ? { ...event, key: hashKey(event.key, salt ?? "") } : event
+    )
+  );
+  let dropping = false;
+  const emit = (event) => {
+    if (!options.onEvent) return;
+    if (salt !== null) return deliver(event);
+    if (waiting.push(event) > MAX_WAITING) {
+      waiting.shift();
+      if (!dropping)
+        warn(
+          "@vinaverse/client/agent: the analytics salt is still being read from storage; the oldest events are dropped.",
+          { code: "events_dropped" }
+        );
+      dropping = true;
+    }
+  };
+  loadSalt();
   const changed = () => {
     for (const l of [...listeners]) l();
   };
@@ -2499,6 +2698,7 @@ function createAgentRuntime(options) {
     const entry = live.get(k);
     if (!entry) return;
     live.delete(k);
+    clearTimeout(entry.timer);
     entry.store.dispose();
     emit({ type: "conversation_ended", key: k });
     changed();
@@ -2511,32 +2711,45 @@ function createAgentRuntime(options) {
   );
   async function open(entry, key, request) {
     if (live.get(entry.key) !== entry) throw new AgentRefusal("unavailable");
-    const told = entry.place;
-    const conversationId = request.conversationId ?? current.get(entry.key) ?? null;
+    const held = entry.failedOpen && clock.now() - entry.failedOpen.at < OPEN_KEPT_MS ? entry.failedOpen : void 0;
+    entry.failedOpen = void 0;
+    const asked = held ? {
+      ...held.request,
+      ...request.signal ? { signal: request.signal } : {}
+    } : {
+      ...request,
+      conversationId: request.conversationId ?? current.get(entry.key) ?? null,
+      key,
+      openId: `op_${randomId().slice(3)}`,
+      agent: options.agent ?? null,
+      place: entry.place,
+      placeRevision: ++entry.revision,
+      entryPoint: entry.entryPoint
+    };
+    const { conversationId, openId, place: told } = asked;
     let session;
     try {
       session = await patiently(
-        () => backend.openSession({
-          ...request,
-          conversationId,
-          key,
-          place: told,
-          entryPoint: entry.entryPoint
-        }),
+        () => backend.openSession(asked),
         request.signal,
         entry.key
       );
       if (!usable(session, insecure))
         throw new AgentRefusal("unavailable", {
           reason: "invalid_session",
-          message: "The session is not usable (an id, a secret, a wss:// realtime_url and an https:// turns_url)."
+          message: "Unusable session: an id, a secret, wss:// and https:// addresses."
         });
     } catch (error) {
       if (live.get(entry.key) === entry) {
-        const failure = error instanceof AgentRefusal ? error.kind === "ended" && conversationId !== null ? "ended" : "unavailable" : policy.isRetryable(error) ? "unreachable" : "unavailable";
+        const failure = isRefusal(error) ? error.kind === "ended" && conversationId !== null ? "ended" : "unavailable" : policy.isRetryable(error) ? "unreachable" : "unavailable";
         const reason = reasonOf(error, failure);
-        const code = error instanceof AgentRefusal ? error.code : codeOf(error);
-        update(entry, { failure, reason, code });
+        const code = isRefusal(error) ? error.code : codeOf(error);
+        if (failure === "unreachable") {
+          const { signal, ...again } = asked;
+          entry.failedOpen = { request: again, at: held?.at ?? clock.now() };
+        }
+        const unsettled = reason === "unknown_open" ? String(field(error, "openId") ?? openId) : null;
+        update(entry, { failure, reason, code, openId: unsettled });
         emit({ type: "session_failed", key: entry.key, failure, reason });
       }
       throw error;
@@ -2555,7 +2768,9 @@ function createAgentRuntime(options) {
       failure: null,
       reason: null,
       code: null,
+      openId: null,
       sessionId: session.id,
+      conversationId: session.conversation_id ?? conversationId,
       moved: !samePlace(told, entry.place)
     });
     emit({
@@ -2566,25 +2781,106 @@ function createAgentRuntime(options) {
     });
     return session;
   }
-  const kept = (k) => `${options.conversation?.persistenceKey ?? "vinaverse.agent"}.${k}`;
+  const kept = (k) => `${prefix}.${k}`;
+  const signOut = async (erasing) => {
+    generation++;
+    if (erasing) salt = null;
+    for (const entry of live.values()) {
+      clearTimeout(entry.timer);
+      entry.store.clear();
+    }
+    const known = /* @__PURE__ */ new Set([...live.keys(), ...current.keys()]);
+    live.clear();
+    current.clear();
+    sessionName = null;
+    status = null;
+    reading = null;
+    changed();
+    const pairs = [];
+    await Promise.all([
+      backend.endSessions?.().catch(() => void 0),
+      storage?.purge(
+        [`${prefix}.`],
+        (keys) => {
+          const all = /* @__PURE__ */ new Set([...keys, ...[...known].map(kept)]);
+          for (const key of all) {
+            const t = tupleOf(key, prefix);
+            if (t) pairs.push([t[1], t[2]]);
+          }
+          return [
+            ...all,
+            ...legacyTranscripts(all, prefix),
+            ...options.legacyKeys ?? []
+          ];
+        },
+        `${GREETED}.`
+      )
+    ]);
+    if (!erasing) return;
+    await Promise.all([
+      Promise.resolve(saltStore?.removeItem(saltKey)).catch(() => void 0),
+      greetings?.purge([`${GREETED}.`, `${GREETED_BEFORE}.`], (keys) => {
+        for (const key of keys) {
+          const t = tupleOf(key, GREETED);
+          if (t) pairs.push([t[0], t[1]]);
+        }
+        return [...legacyGreetings(pairs), ...options.legacyKeys ?? []];
+      })
+    ]);
+    loadSalt();
+  };
+  const forget = (k) => {
+    current.delete(k);
+    const entry = live.get(k);
+    if (entry) {
+      entry.store.clear();
+      end(k);
+    } else void storage?.removeItem(kept(k));
+  };
+  const activity = (entry, a) => {
+    const sessionId = entry.state.sessionId;
+    if (a.type === "reply_completed" && sessionId) {
+      entry.turns.set(a.turnId, sessionId);
+      update(entry, {});
+    }
+    emit({
+      type: a.type,
+      key: entry.key,
+      ...sessionId ? { sessionId } : {},
+      ...a.type === "reply_completed" ? { turnId: a.turnId } : {},
+      ...a.type === "card_shown" ? { cardId: a.cardId, kind: a.kind } : {}
+    });
+  };
   function make(key) {
-    const k = agentKey(key);
+    const k = keyOf(key);
     const own = options.conversation ?? {};
     const refresh = backend.refreshSecret?.bind(backend);
     const entry = {
       key: k,
       store: createConversation({
         ...own,
-        ...own.persistence ? {
+        ...storage ? {
+          persistence: storage,
           persistenceKey: kept(k)
         } : {},
+        onActivity: (a) => {
+          activity(entry, a);
+          isolated("onActivity", () => own.onActivity?.(a));
+        },
         getSession: (request) => open(entry, key, request),
         ...refresh ? {
-          refreshSecret: (id) => patiently(() => refresh(id), void 0, k)
+          // A refusal (`session_closed`) is the store's cue to go on in a new session, never a fault.
+          refreshSecret: (id) => patiently(() => refresh(id), void 0, k).catch((error) => {
+            throw isRefusal(error) ? new VinaverseClientError(
+              "needs_new_session",
+              error.message
+            ) : error;
+          })
         } : {},
         clock,
         onError: (error) => {
-          if (!(error instanceof AgentRefusal)) own.onError?.(error);
+          if (!isRefusal(error) && codeOf(error) !== "needs_new_session")
+            own.onError?.(error);
         }
       }),
       listeners: /* @__PURE__ */ new Set(),
@@ -2594,7 +2890,9 @@ function createAgentRuntime(options) {
         code: null,
         moved: false,
         ratings: /* @__PURE__ */ new Map(),
-        sessionId: null
+        sessionId: null,
+        conversationId: current.get(k) ?? null,
+        openId: null
       },
       place: null,
       told: null,
@@ -2604,32 +2902,59 @@ function createAgentRuntime(options) {
       shown: 0,
       started: false,
       suspended: false,
-      sentOnce: /* @__PURE__ */ new Set()
+      sentOnce: /* @__PURE__ */ new Set(),
+      timer: void 0,
+      turns: /* @__PURE__ */ new Map(),
+      failedOpen: void 0
     };
     return entry;
   }
   const over = (entry) => entry.expiresAt !== null && entry.expiresAt <= clock.now();
+  const expireLater = (entry) => {
+    clearTimeout(entry.timer);
+    if (entry.expiresAt === null) return;
+    entry.timer = setTimeout(
+      () => {
+        entry.timer = void 0;
+        if (live.get(entry.key) !== entry || entry.shown > 0) return;
+        if (over(entry)) end(entry.key);
+        else expireLater(entry);
+      },
+      Math.max(0, entry.expiresAt - clock.now())
+    );
+  };
   const tell = (entry, at) => {
-    entry.place = at.place ?? null;
-    entry.entryPoint = at.entryPoint ?? null;
+    if (at.place !== void 0) entry.place = at.place;
+    if (at.entryPoint !== void 0) entry.entryPoint = at.entryPoint;
     const sessionId = entry.state.sessionId;
     const moved = sessionId !== null && !samePlace(entry.told, entry.place);
     update(entry, { moved });
-    const place = entry.place;
-    if (!moved || !place || !backend.updateContext || sessionId === null)
-      return;
-    const revision = ++entry.revision;
-    backend.updateContext(sessionId, place, revision).then(
-      () => {
-        if (live.get(entry.key) !== entry || entry.revision !== revision)
-          return;
-        entry.told = place;
-        update(entry, { moved: !samePlace(entry.told, entry.place) });
-        emit({ type: "context_updated", key: entry.key, sessionId });
-      },
-      () => void 0
-      // not served, or refused: the question about this place stays the way to say it
-    );
+    const updateContext = backend.updateContext?.bind(backend);
+    if (!moved || !updateContext || sessionId === null) return;
+    const asked = generation;
+    const current2 = () => asked === generation && live.get(entry.key) === entry && entry.state.sessionId === sessionId;
+    const send = (again) => {
+      const place = entry.place;
+      const revision = ++entry.revision;
+      updateContext(sessionId, place ?? CLEARED, revision).then(
+        () => {
+          if (!current2() || entry.revision !== revision) return;
+          entry.told = place;
+          update(entry, { moved: !samePlace(entry.told, entry.place) });
+          emit({ type: "context_updated", key: entry.key, sessionId });
+        },
+        (error) => {
+          const theirs = field(error, "currentRevision");
+          const conflict = field(error, "outcome") === "context_conflict" || field(error, "reason") === "conflict";
+          if (!conflict || again || !current2() || entry.revision !== revision)
+            return;
+          if (typeof theirs === "number" && theirs >= entry.revision)
+            entry.revision = theirs;
+          send(true);
+        }
+      );
+    };
+    send(false);
   };
   function handle(entry) {
     return {
@@ -2642,6 +2967,8 @@ function createAgentRuntime(options) {
           return () => void 0;
         }
         entry.shown++;
+        clearTimeout(entry.timer);
+        entry.timer = void 0;
         if (entry.suspended) {
           entry.suspended = false;
           entry.store.setForeground(true);
@@ -2663,6 +2990,7 @@ function createAgentRuntime(options) {
           }
           entry.suspended = true;
           entry.store.setForeground(false);
+          expireLater(entry);
         };
       },
       tell: (at) => tell(entry, at),
@@ -2672,13 +3000,18 @@ function createAgentRuntime(options) {
         return () => entry.listeners.delete(listener);
       },
       retry() {
-        update(entry, { failure: null, reason: null, code: null });
+        update(entry, {
+          failure: null,
+          reason: null,
+          code: null,
+          openId: null
+        });
         entry.store.start();
       },
+      canRate: (turnId) => entry.turns.has(turnId),
       rate(turnId, rating) {
-        const sessionId = entry.state.sessionId;
-        if (sessionId === null || entry.state.ratings.get(turnId) === rating)
-          return;
+        const sessionId = entry.turns.get(turnId);
+        if (!sessionId || entry.state.ratings.get(turnId) === rating) return;
         update(entry, {
           ratings: new Map(entry.state.ratings).set(turnId, rating)
         });
@@ -2694,7 +3027,7 @@ function createAgentRuntime(options) {
   }
   const handles = /* @__PURE__ */ new WeakMap();
   const lookup = (key) => {
-    const k = agentKey(key);
+    const k = keyOf(key);
     let entry = live.get(k);
     if (!entry) {
       entry = make(key);
@@ -2709,63 +3042,72 @@ function createAgentRuntime(options) {
   };
   return {
     conversation(key) {
-      const k = agentKey(key);
+      const k = keyOf(key);
       const entry = live.get(k);
       if (entry && entry.shown === 0 && over(entry)) end(k);
       return lookup(key);
     },
     peek: lookup,
     startNew(key) {
-      const k = agentKey(key);
+      const k = keyOf(key);
       current.delete(k);
       end(k);
     },
     dispose(key) {
-      end(agentKey(key));
+      end(keyOf(key));
+    },
+    forget(key) {
+      forget(keyOf(key));
+    },
+    sweep() {
+      for (const entry of [...live.values()])
+        if (entry.shown === 0 && over(entry)) end(entry.key);
     },
     continue(key, conversationId) {
-      const k = agentKey(key);
+      const k = keyOf(key);
       if (current.get(k) !== conversationId) {
+        forget(k);
         current.set(k, conversationId);
-        const entry = live.get(k);
-        if (entry) {
-          entry.store.clear();
-          end(k);
-        } else {
-          try {
-            void Promise.resolve(
-              options.conversation?.persistence?.removeItem(kept(k))
-            ).catch(() => void 0);
-          } catch {
-          }
-        }
       }
       return lookup(key);
     },
     async signOut() {
-      for (const entry of live.values()) entry.store.clear();
-      live.clear();
-      current.clear();
-      sessionName = null;
-      changed();
-      await backend.endSessions?.().catch(() => void 0);
+      await signOut(false);
+    },
+    async erase() {
+      await signOut(true);
     },
+    async deleteConversation(key, conversationId) {
+      if (!backend.deleteConversation)
+        throw new Error(
+          "@vinaverse/client/agent: deleteConversation needs AgentBackend.deleteConversation."
+        );
+      await backend.deleteConversation(conversationId);
+      const k = keyOf(key);
+      const continued = current.get(k) ?? live.get(k)?.store.getSnapshot().conversationId ?? null;
+      if (continued === conversationId) forget(k);
+    },
+    greetings: greetings ?? null,
     status() {
       if (status && clock.now() - status.at < staleMs)
         return Promise.resolve(status.value);
-      reading ??= readStatus(backend).then(
+      if (reading) return reading;
+      const asked = generation;
+      const read = readStatus(backend).then(
         (value) => {
+          if (asked !== generation) return value;
           reading = null;
           status = { value, at: clock.now() };
           changed();
           return value;
         },
         (error) => {
-          reading = null;
+          if (asked === generation) reading = null;
           throw error;
         }
       );
-      return reading;
+      reading = read;
+      return read;
     },
     getStatus: () => status?.value ?? null,
     getName: () => sessionName ?? status?.value.displayName ?? null,
@@ -2776,6 +3118,100 @@ function createAgentRuntime(options) {
     emit
   };
 }
+function guardedStorage(raw, prefix, generation) {
+  if (!raw) return void 0;
+  const indexKey = `${prefix}:index`;
+  const chains = /* @__PURE__ */ new Map();
+  const pending = /* @__PURE__ */ new Map();
+  const queued = (key, op) => {
+    pending.set(key, (pending.get(key) ?? 0) + 1);
+    const run = (chains.get(key) ?? Promise.resolve()).then(op);
+    const settled = run.then(
+      () => void 0,
+      () => void 0
+    );
+    chains.set(key, settled);
+    void settled.then(() => {
+      const left = (pending.get(key) ?? 1) - 1;
+      if (left > 0) pending.set(key, left);
+      else {
+        pending.delete(key);
+        if (chains.get(key) === settled) chains.delete(key);
+      }
+    });
+    return run;
+  };
+  const safe = (p) => p.catch(() => void 0);
+  const readIndex = async () => {
+    try {
+      const value = await raw.getItem(indexKey);
+      const list3 = value ? JSON.parse(value) : [];
+      return new Set(
+        Array.isArray(list3) ? list3.filter((k) => typeof k === "string") : []
+      );
+    } catch {
+      return /* @__PURE__ */ new Set();
+    }
+  };
+  const listed = /* @__PURE__ */ new Set();
+  const list2 = (key) => {
+    if (listed.has(key)) return;
+    listed.add(key);
+    void safe(
+      queued(indexKey, async () => {
+        const all = await readIndex();
+        if (all.has(key)) return;
+        all.add(key);
+        await raw.setItem(indexKey, JSON.stringify([...all]));
+      })
+    );
+  };
+  return {
+    getItem(key) {
+      const asked = generation();
+      const read = pending.has(key) ? queued(key, () => raw.getItem(key)) : raw.getItem(key);
+      if (typeof read === "string" || read === null) return read;
+      return Promise.resolve(read).then(
+        (v) => asked === generation() ? v ?? null : null,
+        () => null
+      );
+    },
+    setItem(key, value) {
+      const asked = generation();
+      return safe(
+        queued(key, () => {
+          if (asked !== generation()) return;
+          list2(key);
+          return raw.setItem(key, value);
+        })
+      );
+    },
+    removeItem: (key) => safe(queued(key, () => raw.removeItem(key))),
+    /**
+     * Everything kept: the index, what the app's storage finds under `under` (`removePrefix`, else `keys`), and `extra`
+     * (older key shapes). Nothing under `keep` goes, so `removePrefix` is used only for a prefix that cannot reach it.
+     */
+    async purge(under, extra = () => [], keep) {
+      const all = /* @__PURE__ */ new Set([...listed, ...await readIndex()]);
+      listed.clear();
+      for (const p of under)
+        try {
+          if (raw.removePrefix && !keep?.startsWith(p))
+            await raw.removePrefix(p);
+          else if (raw.keys) {
+            for (const key of await raw.keys(p))
+              if (!keep || !key.startsWith(keep)) all.add(key);
+          }
+        } catch {
+        }
+      for (const key of extra(all)) all.add(key);
+      await Promise.all(
+        [...all].map((key) => safe(queued(key, () => raw.removeItem(key))))
+      );
+      await safe(queued(indexKey, () => raw.removeItem(indexKey)));
+    }
+  };
+}
 async function readStatus(backend) {
   const read = backend.status ? await backend.status() : { available: true };
   const available = read.available === true;
@@ -2793,10 +3229,20 @@ async function readStatus(backend) {
     }
   };
 }
+function isRefusal(error) {
+  return error instanceof AgentRefusal || field(error, "name") === "AgentRefusal" && (field(error, "kind") === "ended" || field(error, "kind") === "unavailable");
+}
 var field = (error, name) => typeof error === "object" && error !== null ? error[name] : void 0;
 var retryable = (error) => field(error, "retryable") === true;
 var REASONS = /* @__PURE__ */ new Set([
   "ended",
+  "not_found",
+  "expired",
+  "mismatch",
+  "completed",
+  "forbidden",
+  "conflict",
+  "unknown_open",
   "auth",
   "off",
   "rate_limited",
@@ -2806,7 +3252,7 @@ var REASONS = /* @__PURE__ */ new Set([
   "unknown"
 ]);
 function reasonOf(error, failure) {
-  if (error instanceof AgentRefusal) return error.reason;
+  if (isRefusal(error)) return error.reason;
   const given = field(error, "reason");
   if (typeof given === "string" && REASONS.has(given))
     return given;
@@ -2817,7 +3263,7 @@ function reasonOf(error, failure) {
   return failure === "unreachable" ? "network" : "unknown";
 }
 function codeOf(error) {
-  const code = field(error, "code");
+  const code = field(error, "code") ?? field(error, "outcome");
   return typeof code === "string" ? code : null;
 }
 async function retrying(run, policy, signal, onRetry) {
@@ -2825,9 +3271,11 @@ async function retrying(run, policy, signal, onRetry) {
     try {
       return await run();
     } catch (error) {
-      const wait = policy.delays[attempt];
-      if (wait === void 0 || !policy.isRetryable(error) || signal?.aborted)
+      const delay = policy.delays[attempt];
+      if (delay === void 0 || !policy.isRetryable(error) || signal?.aborted)
         throw error;
+      const asked = field(error, "retryAfterMs");
+      const wait = typeof asked === "number" && asked > delay ? Math.min(asked, 6e4) : delay;
       await new Promise((resolve, reject) => {
         const timer = setTimeout(() => {
           signal?.removeEventListener("abort", stop);
@@ -2847,6 +3295,9 @@ async function retrying(run, policy, signal, onRetry) {
 exports.AgentRefusal = AgentRefusal;
 exports.agentKey = agentKey;
 exports.createAgentRuntime = createAgentRuntime;
+exports.greetedKey = greetedKey;
+exports.hashKey = hashKey;
+exports.isRefusal = isRefusal;
 exports.readCard = readCard;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map