@athenaintel/react 0.41.2 → 0.42.1

package/dist/threads/index-triggered-refresh.cjs

@@ -0,0 +1,164 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const react = require("react");
+const INDEX_REFRESH_DEBOUNCE_MS = 750;
+const INDEX_REFRESH_MAX_WAIT_MS = 3e3;
+const INDEX_REFRESH_HIDDEN_TAB_DELAY_MS = 1500;
+const INDEX_REFRESH_JITTER_MS = 300;
+const INDEX_REFRESH_MAX_ATTEMPTS = 3;
+const INDEX_REFRESH_RETRY_BASE_MS = 1e4;
+const DEFAULT_TIMING = {
+  debounceMs: INDEX_REFRESH_DEBOUNCE_MS,
+  hiddenTabDelayMs: INDEX_REFRESH_HIDDEN_TAB_DELAY_MS,
+  jitterMs: INDEX_REFRESH_JITTER_MS,
+  maxWaitMs: INDEX_REFRESH_MAX_WAIT_MS,
+  maxAttempts: INDEX_REFRESH_MAX_ATTEMPTS,
+  retryBaseMs: INDEX_REFRESH_RETRY_BASE_MS
+};
+class IndexRefreshLedger {
+  constructor(timing) {
+    __publicField(this, "settled", /* @__PURE__ */ new Set());
+    __publicField(this, "inFlight", /* @__PURE__ */ new Set());
+    __publicField(this, "failures", /* @__PURE__ */ new Map());
+    this.timing = timing;
+  }
+  /** The keys a refresh should be sent for now. */
+  due(keys, now) {
+    return keys.filter((key) => {
+      if (this.settled.has(key) || this.inFlight.has(key)) return false;
+      const failure = this.failures.get(key);
+      return failure === void 0 || failure.retryAt <= now;
+    });
+  }
+  /** When the earliest of these keys that failed is due again; `null` if none waits. */
+  nextRetryAt(keys) {
+    let next = null;
+    for (const key of keys) {
+      if (this.settled.has(key) || this.inFlight.has(key)) continue;
+      const failure = this.failures.get(key);
+      if (failure && (next === null || failure.retryAt < next)) next = failure.retryAt;
+    }
+    return next;
+  }
+  begin(keys) {
+    for (const key of keys) this.inFlight.add(key);
+  }
+  succeed(keys) {
+    for (const key of keys) {
+      this.inFlight.delete(key);
+      this.failures.delete(key);
+      this.settled.add(key);
+    }
+  }
+  fail(keys, now) {
+    var _a;
+    for (const key of keys) {
+      this.inFlight.delete(key);
+      const attempts = (((_a = this.failures.get(key)) == null ? void 0 : _a.attempts) ?? 0) + 1;
+      if (attempts >= this.timing.maxAttempts) {
+        this.failures.delete(key);
+        this.settled.add(key);
+        continue;
+      }
+      this.failures.set(key, {
+        attempts,
+        retryAt: now + this.timing.retryBaseMs * 2 ** (attempts - 1)
+      });
+    }
+  }
+}
+function refreshSucceeded(result) {
+  if (result === null || typeof result !== "object") return true;
+  const { status, isError } = result;
+  return status !== "error" && isError !== true;
+}
+function useIndexTriggeredRefresh({
+  pending,
+  refresh,
+  enabled,
+  tabShare,
+  shareKey,
+  timing
+}) {
+  const resolvedTiming = { ...DEFAULT_TIMING, ...timing };
+  const timingRef = react.useRef(resolvedTiming);
+  timingRef.current = resolvedTiming;
+  const ledgerRef = react.useRef(null);
+  ledgerRef.current ?? (ledgerRef.current = new IndexRefreshLedger(resolvedTiming));
+  const refreshRef = react.useRef(refresh);
+  refreshRef.current = refresh;
+  const tabShareRef = react.useRef(tabShare);
+  tabShareRef.current = tabShare;
+  const firstDueAtRef = react.useRef(null);
+  const mountedRef = react.useRef(true);
+  react.useEffect(() => {
+    mountedRef.current = true;
+    return () => {
+      mountedRef.current = false;
+    };
+  }, []);
+  const [tick, setTick] = react.useState(0);
+  const bump = () => {
+    if (mountedRef.current) setTick((value) => value + 1);
+  };
+  const pendingKey = JSON.stringify(pending);
+  react.useEffect(() => {
+    var _a;
+    if (!enabled) return;
+    const ledger = ledgerRef.current;
+    if (!ledger) return;
+    const { debounceMs, maxWaitMs, hiddenTabDelayMs, jitterMs } = timingRef.current;
+    const keys = JSON.parse(pendingKey);
+    const now = Date.now();
+    const due = ledger.due(keys, now);
+    if (due.length === 0) {
+      firstDueAtRef.current = null;
+      const retryAt = ledger.nextRetryAt(keys);
+      if (retryAt === null) return;
+      const retryId = setTimeout(bump, Math.max(0, retryAt - now));
+      return () => clearTimeout(retryId);
+    }
+    const claimedUntil = shareKey ? ((_a = tabShareRef.current) == null ? void 0 : _a.claimedUntil(shareKey)) ?? null : null;
+    if (claimedUntil !== null) {
+      const claimId = setTimeout(bump, Math.max(0, claimedUntil - now));
+      return () => clearTimeout(claimId);
+    }
+    firstDueAtRef.current ?? (firstDueAtRef.current = now);
+    const isHidden = typeof document !== "undefined" && document.visibilityState === "hidden";
+    const stagger = (isHidden ? hiddenTabDelayMs : 0) + Math.random() * jitterMs;
+    const delay = Math.max(0, Math.min(debounceMs, firstDueAtRef.current + maxWaitMs - now)) + stagger;
+    const flushId = setTimeout(() => {
+      var _a2, _b;
+      firstDueAtRef.current = null;
+      const sending = ledger.due(keys, Date.now());
+      if (sending.length === 0) return;
+      if (shareKey && ((_a2 = tabShareRef.current) == null ? void 0 : _a2.claimedUntil(shareKey)) != null) {
+        bump();
+        return;
+      }
+      if (shareKey) (_b = tabShareRef.current) == null ? void 0 : _b.claim(shareKey);
+      ledger.begin(sending);
+      void Promise.resolve().then(() => refreshRef.current()).then(
+        (result) => {
+          if (refreshSucceeded(result)) ledger.succeed(sending);
+          else ledger.fail(sending, Date.now());
+        },
+        () => ledger.fail(sending, Date.now())
+      ).finally(bump);
+    }, delay);
+    return () => clearTimeout(flushId);
+  }, [enabled, pendingKey, shareKey, tick]);
+}
+exports.INDEX_REFRESH_DEBOUNCE_MS = INDEX_REFRESH_DEBOUNCE_MS;
+exports.INDEX_REFRESH_HIDDEN_TAB_DELAY_MS = INDEX_REFRESH_HIDDEN_TAB_DELAY_MS;
+exports.INDEX_REFRESH_JITTER_MS = INDEX_REFRESH_JITTER_MS;
+exports.INDEX_REFRESH_MAX_ATTEMPTS = INDEX_REFRESH_MAX_ATTEMPTS;
+exports.INDEX_REFRESH_MAX_WAIT_MS = INDEX_REFRESH_MAX_WAIT_MS;
+exports.INDEX_REFRESH_RETRY_BASE_MS = INDEX_REFRESH_RETRY_BASE_MS;
+exports.IndexRefreshLedger = IndexRefreshLedger;
+exports.refreshSucceeded = refreshSucceeded;
+exports.useIndexTriggeredRefresh = useIndexTriggeredRefresh;
+//# sourceMappingURL=index-triggered-refresh.cjs.map

package/dist/threads/index-triggered-refresh.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-triggered-refresh.cjs","sources":["../../src/threads/index-triggered-refresh.ts"],"sourcesContent":["/**\n * The refresh a list runs when the pushed conversation index knows a thread\n * the list does not show yet (a session just started here or in another tab,\n * or one that just came to match a filter). Shared by the sidebar provider\n * and `useAthenaSessions`.\n *\n * - **Coalesced.** One push rarely comes alone (a new session is created,\n *   titled and starts running within a second), and every open tab hears\n *   each one. Keys that become due are gathered for\n *   {@link INDEX_REFRESH_DEBOUNCE_MS} after the last change (at most\n *   {@link INDEX_REFRESH_MAX_WAIT_MS} after the first), and nothing is sent\n *   while the list is already fetching: that fetch may list the row, and the\n *   keys are looked at again once it lands.\n * - **One tab for all.** With a `tabShare`, the tab that is about to refresh\n *   claims the list first; the user's other tabs hold their own refresh\n *   while the claim stands and take the page it shares\n *   (`session-list-tab-share.ts`). A claim that lapses without a page lets\n *   them refresh themselves.\n * - **Retried.** A key is settled only by a refresh that SUCCEEDED. A refused\n *   one (429, network, a deploy restart) is tried again after\n *   {@link INDEX_REFRESH_RETRY_BASE_MS}, doubling, at most\n *   {@link INDEX_REFRESH_MAX_ATTEMPTS} times, so a thread the list\n *   legitimately never shows (another app, a search) cannot loop.\n */\nimport { useEffect, useRef, useState } from 'react';\nimport type { SessionListTabShare } from './session-list-tab-share';\n\n/** Quiet time gathered after the last change before the refresh is sent. */\nexport const INDEX_REFRESH_DEBOUNCE_MS = 750;\n/** The longest a due key waits for quiet before its refresh is sent anyway. */\nexport const INDEX_REFRESH_MAX_WAIT_MS = 3_000;\n/**\n * Extra wait for a tab nobody is looking at, so the visible tab is usually the\n * one that claims a list and reads it for the others.\n */\nexport const INDEX_REFRESH_HIDDEN_TAB_DELAY_MS = 1_500;\n/** Up to this much random wait on top, so tabs that heard the same push do not flush together. */\nexport const INDEX_REFRESH_JITTER_MS = 300;\n/** Refreshes tried per key before it is given up on. */\nexport const INDEX_REFRESH_MAX_ATTEMPTS = 3;\n/**\n * Wait before the first retry; each later retry waits twice as long. Long enough that a refusal\n * from the per-minute request window has a chance to clear (the list query has already retried\n * on its own by then).\n */\nexport const INDEX_REFRESH_RETRY_BASE_MS = 10_000;\n\nexport interface IndexRefreshTiming {\n  debounceMs: number;\n  hiddenTabDelayMs: number;\n  jitterMs: number;\n  maxWaitMs: number;\n  maxAttempts: number;\n  retryBaseMs: number;\n}\n\nconst DEFAULT_TIMING: IndexRefreshTiming = {\n  debounceMs: INDEX_REFRESH_DEBOUNCE_MS,\n  hiddenTabDelayMs: INDEX_REFRESH_HIDDEN_TAB_DELAY_MS,\n  jitterMs: INDEX_REFRESH_JITTER_MS,\n  maxWaitMs: INDEX_REFRESH_MAX_WAIT_MS,\n  maxAttempts: INDEX_REFRESH_MAX_ATTEMPTS,\n  retryBaseMs: INDEX_REFRESH_RETRY_BASE_MS,\n};\n\n/**\n * What each key has cost so far: settled (a refresh succeeded, or it ran out\n * of attempts), in flight, or failed N times and next due at an instant.\n * Exported for tests.\n */\nexport class IndexRefreshLedger {\n  private readonly settled = new Set<string>();\n  private readonly inFlight = new Set<string>();\n  private readonly failures = new Map<string, { attempts: number; retryAt: number }>();\n\n  constructor(private readonly timing: Pick<IndexRefreshTiming, 'maxAttempts' | 'retryBaseMs'>) {}\n\n  /** The keys a refresh should be sent for now. */\n  due(keys: readonly string[], now: number): string[] {\n    return keys.filter((key) => {\n      if (this.settled.has(key) || this.inFlight.has(key)) return false;\n      const failure = this.failures.get(key);\n      return failure === undefined || failure.retryAt <= now;\n    });\n  }\n\n  /** When the earliest of these keys that failed is due again; `null` if none waits. */\n  nextRetryAt(keys: readonly string[]): number | null {\n    let next: number | null = null;\n    for (const key of keys) {\n      if (this.settled.has(key) || this.inFlight.has(key)) continue;\n      const failure = this.failures.get(key);\n      if (failure && (next === null || failure.retryAt < next)) next = failure.retryAt;\n    }\n    return next;\n  }\n\n  begin(keys: readonly string[]): void {\n    for (const key of keys) this.inFlight.add(key);\n  }\n\n  succeed(keys: readonly string[]): void {\n    for (const key of keys) {\n      this.inFlight.delete(key);\n      this.failures.delete(key);\n      this.settled.add(key);\n    }\n  }\n\n  fail(keys: readonly string[], now: number): void {\n    for (const key of keys) {\n      this.inFlight.delete(key);\n      const attempts = (this.failures.get(key)?.attempts ?? 0) + 1;\n      if (attempts >= this.timing.maxAttempts) {\n        this.failures.delete(key);\n        this.settled.add(key);\n        continue;\n      }\n      this.failures.set(key, {\n        attempts,\n        retryAt: now + this.timing.retryBaseMs * 2 ** (attempts - 1),\n      });\n    }\n  }\n}\n\n/**\n * Whether a list refresh answered. `useConversationList().refresh` resolves\n * with the query result rather than throwing, so a refused fetch shows as\n * `status: 'error'`. Exported for tests.\n */\nexport function refreshSucceeded(result: unknown): boolean {\n  if (result === null || typeof result !== 'object') return true;\n  const { status, isError } = result as { status?: unknown; isError?: unknown };\n  return status !== 'error' && isError !== true;\n}\n\n/**\n * Run `refresh` for the `pending` keys (the threads, or thread versions, the\n * index knows and the list does not show), coalesced and retried as described\n * above. `enabled` false holds everything (no index yet, the first page not\n * read, or a fetch of the list already in flight); pending keys are looked at\n * again when it turns true.\n */\nexport function useIndexTriggeredRefresh({\n  pending,\n  refresh,\n  enabled,\n  tabShare,\n  shareKey,\n  timing,\n}: {\n  pending: readonly string[];\n  refresh: () => Promise<unknown>;\n  enabled: boolean;\n  /** The user's other open tabs, and this list's name among them (its first-page query key). */\n  tabShare?: SessionListTabShare;\n  shareKey?: string;\n  /** Overrides for tests. */\n  timing?: Partial<IndexRefreshTiming>;\n}): void {\n  const resolvedTiming = { ...DEFAULT_TIMING, ...timing };\n  const timingRef = useRef(resolvedTiming);\n  timingRef.current = resolvedTiming;\n  const ledgerRef = useRef<IndexRefreshLedger | null>(null);\n  ledgerRef.current ??= new IndexRefreshLedger(resolvedTiming);\n  const refreshRef = useRef(refresh);\n  refreshRef.current = refresh;\n  const tabShareRef = useRef(tabShare);\n  tabShareRef.current = tabShare;\n  // When the oldest key now waiting for quiet first became due.\n  const firstDueAtRef = useRef<number | null>(null);\n  const mountedRef = useRef(true);\n  useEffect(() => {\n    mountedRef.current = true;\n    return () => {\n      mountedRef.current = false;\n    };\n  }, []);\n  // Bumped when a refresh settles or a retry falls due, so the keys are looked at again.\n  const [tick, setTick] = useState(0);\n  const bump = () => {\n    if (mountedRef.current) setTick((value) => value + 1);\n  };\n\n  // A stable key, so a fresh array with the same keys does not restart the wait.\n  const pendingKey = JSON.stringify(pending);\n  useEffect(() => {\n    if (!enabled) return;\n    const ledger = ledgerRef.current;\n    if (!ledger) return;\n    const { debounceMs, maxWaitMs, hiddenTabDelayMs, jitterMs } = timingRef.current;\n    const keys = JSON.parse(pendingKey) as string[];\n    const now = Date.now();\n    const due = ledger.due(keys, now);\n    if (due.length === 0) {\n      firstDueAtRef.current = null;\n      const retryAt = ledger.nextRetryAt(keys);\n      if (retryAt === null) return;\n      const retryId = setTimeout(bump, Math.max(0, retryAt - now));\n      return () => clearTimeout(retryId);\n    }\n    // Another tab is reading this list: its page will be shared here. Look\n    // again once its claim lapses, in case it never arrives.\n    const claimedUntil = shareKey ? (tabShareRef.current?.claimedUntil(shareKey) ?? null) : null;\n    if (claimedUntil !== null) {\n      const claimId = setTimeout(bump, Math.max(0, claimedUntil - now));\n      return () => clearTimeout(claimId);\n    }\n    firstDueAtRef.current ??= now;\n    const isHidden = typeof document !== 'undefined' && document.visibilityState === 'hidden';\n    const stagger = (isHidden ? hiddenTabDelayMs : 0) + Math.random() * jitterMs;\n    const delay =\n      Math.max(0, Math.min(debounceMs, firstDueAtRef.current + maxWaitMs - now)) + stagger;\n    const flushId = setTimeout(() => {\n      firstDueAtRef.current = null;\n      const sending = ledger.due(keys, Date.now());\n      if (sending.length === 0) return;\n      if (shareKey && tabShareRef.current?.claimedUntil(shareKey) != null) {\n        bump();\n        return;\n      }\n      if (shareKey) tabShareRef.current?.claim(shareKey);\n      ledger.begin(sending);\n      void Promise.resolve()\n        .then(() => refreshRef.current())\n        .then(\n          (result) => {\n            if (refreshSucceeded(result)) ledger.succeed(sending);\n            else ledger.fail(sending, Date.now());\n          },\n          () => ledger.fail(sending, Date.now()),\n        )\n        .finally(bump);\n    }, delay);\n    return () => clearTimeout(flushId);\n    // `bump` only sets state; `tick` re-runs this after a settle or a retry falls due.\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [enabled, pendingKey, shareKey, tick]);\n}\n"],"names":["useRef","useEffect","useState","_a"],"mappings":"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"}

package/dist/threads/index-triggered-refresh.d.ts

@@ -0,0 +1,70 @@
+import type { SessionListTabShare } from './session-list-tab-share';
+/** Quiet time gathered after the last change before the refresh is sent. */
+export declare const INDEX_REFRESH_DEBOUNCE_MS = 750;
+/** The longest a due key waits for quiet before its refresh is sent anyway. */
+export declare const INDEX_REFRESH_MAX_WAIT_MS = 3000;
+/**
+ * Extra wait for a tab nobody is looking at, so the visible tab is usually the
+ * one that claims a list and reads it for the others.
+ */
+export declare const INDEX_REFRESH_HIDDEN_TAB_DELAY_MS = 1500;
+/** Up to this much random wait on top, so tabs that heard the same push do not flush together. */
+export declare const INDEX_REFRESH_JITTER_MS = 300;
+/** Refreshes tried per key before it is given up on. */
+export declare const INDEX_REFRESH_MAX_ATTEMPTS = 3;
+/**
+ * Wait before the first retry; each later retry waits twice as long. Long enough that a refusal
+ * from the per-minute request window has a chance to clear (the list query has already retried
+ * on its own by then).
+ */
+export declare const INDEX_REFRESH_RETRY_BASE_MS = 10000;
+export interface IndexRefreshTiming {
+    debounceMs: number;
+    hiddenTabDelayMs: number;
+    jitterMs: number;
+    maxWaitMs: number;
+    maxAttempts: number;
+    retryBaseMs: number;
+}
+/**
+ * What each key has cost so far: settled (a refresh succeeded, or it ran out
+ * of attempts), in flight, or failed N times and next due at an instant.
+ * Exported for tests.
+ */
+export declare class IndexRefreshLedger {
+    private readonly timing;
+    private readonly settled;
+    private readonly inFlight;
+    private readonly failures;
+    constructor(timing: Pick<IndexRefreshTiming, 'maxAttempts' | 'retryBaseMs'>);
+    /** The keys a refresh should be sent for now. */
+    due(keys: readonly string[], now: number): string[];
+    /** When the earliest of these keys that failed is due again; `null` if none waits. */
+    nextRetryAt(keys: readonly string[]): number | null;
+    begin(keys: readonly string[]): void;
+    succeed(keys: readonly string[]): void;
+    fail(keys: readonly string[], now: number): void;
+}
+/**
+ * Whether a list refresh answered. `useConversationList().refresh` resolves
+ * with the query result rather than throwing, so a refused fetch shows as
+ * `status: 'error'`. Exported for tests.
+ */
+export declare function refreshSucceeded(result: unknown): boolean;
+/**
+ * Run `refresh` for the `pending` keys (the threads, or thread versions, the
+ * index knows and the list does not show), coalesced and retried as described
+ * above. `enabled` false holds everything (no index yet, the first page not
+ * read, or a fetch of the list already in flight); pending keys are looked at
+ * again when it turns true.
+ */
+export declare function useIndexTriggeredRefresh({ pending, refresh, enabled, tabShare, shareKey, timing, }: {
+    pending: readonly string[];
+    refresh: () => Promise<unknown>;
+    enabled: boolean;
+    /** The user's other open tabs, and this list's name among them (its first-page query key). */
+    tabShare?: SessionListTabShare;
+    shareKey?: string;
+    /** Overrides for tests. */
+    timing?: Partial<IndexRefreshTiming>;
+}): void;

package/dist/threads/index-triggered-refresh.js

@@ -0,0 +1,164 @@
+var __defProp = Object.defineProperty;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+import { useRef, useEffect, useState } from "react";
+const INDEX_REFRESH_DEBOUNCE_MS = 750;
+const INDEX_REFRESH_MAX_WAIT_MS = 3e3;
+const INDEX_REFRESH_HIDDEN_TAB_DELAY_MS = 1500;
+const INDEX_REFRESH_JITTER_MS = 300;
+const INDEX_REFRESH_MAX_ATTEMPTS = 3;
+const INDEX_REFRESH_RETRY_BASE_MS = 1e4;
+const DEFAULT_TIMING = {
+  debounceMs: INDEX_REFRESH_DEBOUNCE_MS,
+  hiddenTabDelayMs: INDEX_REFRESH_HIDDEN_TAB_DELAY_MS,
+  jitterMs: INDEX_REFRESH_JITTER_MS,
+  maxWaitMs: INDEX_REFRESH_MAX_WAIT_MS,
+  maxAttempts: INDEX_REFRESH_MAX_ATTEMPTS,
+  retryBaseMs: INDEX_REFRESH_RETRY_BASE_MS
+};
+class IndexRefreshLedger {
+  constructor(timing) {
+    __publicField(this, "settled", /* @__PURE__ */ new Set());
+    __publicField(this, "inFlight", /* @__PURE__ */ new Set());
+    __publicField(this, "failures", /* @__PURE__ */ new Map());
+    this.timing = timing;
+  }
+  /** The keys a refresh should be sent for now. */
+  due(keys, now) {
+    return keys.filter((key) => {
+      if (this.settled.has(key) || this.inFlight.has(key)) return false;
+      const failure = this.failures.get(key);
+      return failure === void 0 || failure.retryAt <= now;
+    });
+  }
+  /** When the earliest of these keys that failed is due again; `null` if none waits. */
+  nextRetryAt(keys) {
+    let next = null;
+    for (const key of keys) {
+      if (this.settled.has(key) || this.inFlight.has(key)) continue;
+      const failure = this.failures.get(key);
+      if (failure && (next === null || failure.retryAt < next)) next = failure.retryAt;
+    }
+    return next;
+  }
+  begin(keys) {
+    for (const key of keys) this.inFlight.add(key);
+  }
+  succeed(keys) {
+    for (const key of keys) {
+      this.inFlight.delete(key);
+      this.failures.delete(key);
+      this.settled.add(key);
+    }
+  }
+  fail(keys, now) {
+    var _a;
+    for (const key of keys) {
+      this.inFlight.delete(key);
+      const attempts = (((_a = this.failures.get(key)) == null ? void 0 : _a.attempts) ?? 0) + 1;
+      if (attempts >= this.timing.maxAttempts) {
+        this.failures.delete(key);
+        this.settled.add(key);
+        continue;
+      }
+      this.failures.set(key, {
+        attempts,
+        retryAt: now + this.timing.retryBaseMs * 2 ** (attempts - 1)
+      });
+    }
+  }
+}
+function refreshSucceeded(result) {
+  if (result === null || typeof result !== "object") return true;
+  const { status, isError } = result;
+  return status !== "error" && isError !== true;
+}
+function useIndexTriggeredRefresh({
+  pending,
+  refresh,
+  enabled,
+  tabShare,
+  shareKey,
+  timing
+}) {
+  const resolvedTiming = { ...DEFAULT_TIMING, ...timing };
+  const timingRef = useRef(resolvedTiming);
+  timingRef.current = resolvedTiming;
+  const ledgerRef = useRef(null);
+  ledgerRef.current ?? (ledgerRef.current = new IndexRefreshLedger(resolvedTiming));
+  const refreshRef = useRef(refresh);
+  refreshRef.current = refresh;
+  const tabShareRef = useRef(tabShare);
+  tabShareRef.current = tabShare;
+  const firstDueAtRef = useRef(null);
+  const mountedRef = useRef(true);
+  useEffect(() => {
+    mountedRef.current = true;
+    return () => {
+      mountedRef.current = false;
+    };
+  }, []);
+  const [tick, setTick] = useState(0);
+  const bump = () => {
+    if (mountedRef.current) setTick((value) => value + 1);
+  };
+  const pendingKey = JSON.stringify(pending);
+  useEffect(() => {
+    var _a;
+    if (!enabled) return;
+    const ledger = ledgerRef.current;
+    if (!ledger) return;
+    const { debounceMs, maxWaitMs, hiddenTabDelayMs, jitterMs } = timingRef.current;
+    const keys = JSON.parse(pendingKey);
+    const now = Date.now();
+    const due = ledger.due(keys, now);
+    if (due.length === 0) {
+      firstDueAtRef.current = null;
+      const retryAt = ledger.nextRetryAt(keys);
+      if (retryAt === null) return;
+      const retryId = setTimeout(bump, Math.max(0, retryAt - now));
+      return () => clearTimeout(retryId);
+    }
+    const claimedUntil = shareKey ? ((_a = tabShareRef.current) == null ? void 0 : _a.claimedUntil(shareKey)) ?? null : null;
+    if (claimedUntil !== null) {
+      const claimId = setTimeout(bump, Math.max(0, claimedUntil - now));
+      return () => clearTimeout(claimId);
+    }
+    firstDueAtRef.current ?? (firstDueAtRef.current = now);
+    const isHidden = typeof document !== "undefined" && document.visibilityState === "hidden";
+    const stagger = (isHidden ? hiddenTabDelayMs : 0) + Math.random() * jitterMs;
+    const delay = Math.max(0, Math.min(debounceMs, firstDueAtRef.current + maxWaitMs - now)) + stagger;
+    const flushId = setTimeout(() => {
+      var _a2, _b;
+      firstDueAtRef.current = null;
+      const sending = ledger.due(keys, Date.now());
+      if (sending.length === 0) return;
+      if (shareKey && ((_a2 = tabShareRef.current) == null ? void 0 : _a2.claimedUntil(shareKey)) != null) {
+        bump();
+        return;
+      }
+      if (shareKey) (_b = tabShareRef.current) == null ? void 0 : _b.claim(shareKey);
+      ledger.begin(sending);
+      void Promise.resolve().then(() => refreshRef.current()).then(
+        (result) => {
+          if (refreshSucceeded(result)) ledger.succeed(sending);
+          else ledger.fail(sending, Date.now());
+        },
+        () => ledger.fail(sending, Date.now())
+      ).finally(bump);
+    }, delay);
+    return () => clearTimeout(flushId);
+  }, [enabled, pendingKey, shareKey, tick]);
+}
+export {
+  INDEX_REFRESH_DEBOUNCE_MS,
+  INDEX_REFRESH_HIDDEN_TAB_DELAY_MS,
+  INDEX_REFRESH_JITTER_MS,
+  INDEX_REFRESH_MAX_ATTEMPTS,
+  INDEX_REFRESH_MAX_WAIT_MS,
+  INDEX_REFRESH_RETRY_BASE_MS,
+  IndexRefreshLedger,
+  refreshSucceeded,
+  useIndexTriggeredRefresh
+};
+//# sourceMappingURL=index-triggered-refresh.js.map

package/dist/threads/index-triggered-refresh.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-triggered-refresh.js","sources":["../../src/threads/index-triggered-refresh.ts"],"sourcesContent":["/**\n * The refresh a list runs when the pushed conversation index knows a thread\n * the list does not show yet (a session just started here or in another tab,\n * or one that just came to match a filter). Shared by the sidebar provider\n * and `useAthenaSessions`.\n *\n * - **Coalesced.** One push rarely comes alone (a new session is created,\n *   titled and starts running within a second), and every open tab hears\n *   each one. Keys that become due are gathered for\n *   {@link INDEX_REFRESH_DEBOUNCE_MS} after the last change (at most\n *   {@link INDEX_REFRESH_MAX_WAIT_MS} after the first), and nothing is sent\n *   while the list is already fetching: that fetch may list the row, and the\n *   keys are looked at again once it lands.\n * - **One tab for all.** With a `tabShare`, the tab that is about to refresh\n *   claims the list first; the user's other tabs hold their own refresh\n *   while the claim stands and take the page it shares\n *   (`session-list-tab-share.ts`). A claim that lapses without a page lets\n *   them refresh themselves.\n * - **Retried.** A key is settled only by a refresh that SUCCEEDED. A refused\n *   one (429, network, a deploy restart) is tried again after\n *   {@link INDEX_REFRESH_RETRY_BASE_MS}, doubling, at most\n *   {@link INDEX_REFRESH_MAX_ATTEMPTS} times, so a thread the list\n *   legitimately never shows (another app, a search) cannot loop.\n */\nimport { useEffect, useRef, useState } from 'react';\nimport type { SessionListTabShare } from './session-list-tab-share';\n\n/** Quiet time gathered after the last change before the refresh is sent. */\nexport const INDEX_REFRESH_DEBOUNCE_MS = 750;\n/** The longest a due key waits for quiet before its refresh is sent anyway. */\nexport const INDEX_REFRESH_MAX_WAIT_MS = 3_000;\n/**\n * Extra wait for a tab nobody is looking at, so the visible tab is usually the\n * one that claims a list and reads it for the others.\n */\nexport const INDEX_REFRESH_HIDDEN_TAB_DELAY_MS = 1_500;\n/** Up to this much random wait on top, so tabs that heard the same push do not flush together. */\nexport const INDEX_REFRESH_JITTER_MS = 300;\n/** Refreshes tried per key before it is given up on. */\nexport const INDEX_REFRESH_MAX_ATTEMPTS = 3;\n/**\n * Wait before the first retry; each later retry waits twice as long. Long enough that a refusal\n * from the per-minute request window has a chance to clear (the list query has already retried\n * on its own by then).\n */\nexport const INDEX_REFRESH_RETRY_BASE_MS = 10_000;\n\nexport interface IndexRefreshTiming {\n  debounceMs: number;\n  hiddenTabDelayMs: number;\n  jitterMs: number;\n  maxWaitMs: number;\n  maxAttempts: number;\n  retryBaseMs: number;\n}\n\nconst DEFAULT_TIMING: IndexRefreshTiming = {\n  debounceMs: INDEX_REFRESH_DEBOUNCE_MS,\n  hiddenTabDelayMs: INDEX_REFRESH_HIDDEN_TAB_DELAY_MS,\n  jitterMs: INDEX_REFRESH_JITTER_MS,\n  maxWaitMs: INDEX_REFRESH_MAX_WAIT_MS,\n  maxAttempts: INDEX_REFRESH_MAX_ATTEMPTS,\n  retryBaseMs: INDEX_REFRESH_RETRY_BASE_MS,\n};\n\n/**\n * What each key has cost so far: settled (a refresh succeeded, or it ran out\n * of attempts), in flight, or failed N times and next due at an instant.\n * Exported for tests.\n */\nexport class IndexRefreshLedger {\n  private readonly settled = new Set<string>();\n  private readonly inFlight = new Set<string>();\n  private readonly failures = new Map<string, { attempts: number; retryAt: number }>();\n\n  constructor(private readonly timing: Pick<IndexRefreshTiming, 'maxAttempts' | 'retryBaseMs'>) {}\n\n  /** The keys a refresh should be sent for now. */\n  due(keys: readonly string[], now: number): string[] {\n    return keys.filter((key) => {\n      if (this.settled.has(key) || this.inFlight.has(key)) return false;\n      const failure = this.failures.get(key);\n      return failure === undefined || failure.retryAt <= now;\n    });\n  }\n\n  /** When the earliest of these keys that failed is due again; `null` if none waits. */\n  nextRetryAt(keys: readonly string[]): number | null {\n    let next: number | null = null;\n    for (const key of keys) {\n      if (this.settled.has(key) || this.inFlight.has(key)) continue;\n      const failure = this.failures.get(key);\n      if (failure && (next === null || failure.retryAt < next)) next = failure.retryAt;\n    }\n    return next;\n  }\n\n  begin(keys: readonly string[]): void {\n    for (const key of keys) this.inFlight.add(key);\n  }\n\n  succeed(keys: readonly string[]): void {\n    for (const key of keys) {\n      this.inFlight.delete(key);\n      this.failures.delete(key);\n      this.settled.add(key);\n    }\n  }\n\n  fail(keys: readonly string[], now: number): void {\n    for (const key of keys) {\n      this.inFlight.delete(key);\n      const attempts = (this.failures.get(key)?.attempts ?? 0) + 1;\n      if (attempts >= this.timing.maxAttempts) {\n        this.failures.delete(key);\n        this.settled.add(key);\n        continue;\n      }\n      this.failures.set(key, {\n        attempts,\n        retryAt: now + this.timing.retryBaseMs * 2 ** (attempts - 1),\n      });\n    }\n  }\n}\n\n/**\n * Whether a list refresh answered. `useConversationList().refresh` resolves\n * with the query result rather than throwing, so a refused fetch shows as\n * `status: 'error'`. Exported for tests.\n */\nexport function refreshSucceeded(result: unknown): boolean {\n  if (result === null || typeof result !== 'object') return true;\n  const { status, isError } = result as { status?: unknown; isError?: unknown };\n  return status !== 'error' && isError !== true;\n}\n\n/**\n * Run `refresh` for the `pending` keys (the threads, or thread versions, the\n * index knows and the list does not show), coalesced and retried as described\n * above. `enabled` false holds everything (no index yet, the first page not\n * read, or a fetch of the list already in flight); pending keys are looked at\n * again when it turns true.\n */\nexport function useIndexTriggeredRefresh({\n  pending,\n  refresh,\n  enabled,\n  tabShare,\n  shareKey,\n  timing,\n}: {\n  pending: readonly string[];\n  refresh: () => Promise<unknown>;\n  enabled: boolean;\n  /** The user's other open tabs, and this list's name among them (its first-page query key). */\n  tabShare?: SessionListTabShare;\n  shareKey?: string;\n  /** Overrides for tests. */\n  timing?: Partial<IndexRefreshTiming>;\n}): void {\n  const resolvedTiming = { ...DEFAULT_TIMING, ...timing };\n  const timingRef = useRef(resolvedTiming);\n  timingRef.current = resolvedTiming;\n  const ledgerRef = useRef<IndexRefreshLedger | null>(null);\n  ledgerRef.current ??= new IndexRefreshLedger(resolvedTiming);\n  const refreshRef = useRef(refresh);\n  refreshRef.current = refresh;\n  const tabShareRef = useRef(tabShare);\n  tabShareRef.current = tabShare;\n  // When the oldest key now waiting for quiet first became due.\n  const firstDueAtRef = useRef<number | null>(null);\n  const mountedRef = useRef(true);\n  useEffect(() => {\n    mountedRef.current = true;\n    return () => {\n      mountedRef.current = false;\n    };\n  }, []);\n  // Bumped when a refresh settles or a retry falls due, so the keys are looked at again.\n  const [tick, setTick] = useState(0);\n  const bump = () => {\n    if (mountedRef.current) setTick((value) => value + 1);\n  };\n\n  // A stable key, so a fresh array with the same keys does not restart the wait.\n  const pendingKey = JSON.stringify(pending);\n  useEffect(() => {\n    if (!enabled) return;\n    const ledger = ledgerRef.current;\n    if (!ledger) return;\n    const { debounceMs, maxWaitMs, hiddenTabDelayMs, jitterMs } = timingRef.current;\n    const keys = JSON.parse(pendingKey) as string[];\n    const now = Date.now();\n    const due = ledger.due(keys, now);\n    if (due.length === 0) {\n      firstDueAtRef.current = null;\n      const retryAt = ledger.nextRetryAt(keys);\n      if (retryAt === null) return;\n      const retryId = setTimeout(bump, Math.max(0, retryAt - now));\n      return () => clearTimeout(retryId);\n    }\n    // Another tab is reading this list: its page will be shared here. Look\n    // again once its claim lapses, in case it never arrives.\n    const claimedUntil = shareKey ? (tabShareRef.current?.claimedUntil(shareKey) ?? null) : null;\n    if (claimedUntil !== null) {\n      const claimId = setTimeout(bump, Math.max(0, claimedUntil - now));\n      return () => clearTimeout(claimId);\n    }\n    firstDueAtRef.current ??= now;\n    const isHidden = typeof document !== 'undefined' && document.visibilityState === 'hidden';\n    const stagger = (isHidden ? hiddenTabDelayMs : 0) + Math.random() * jitterMs;\n    const delay =\n      Math.max(0, Math.min(debounceMs, firstDueAtRef.current + maxWaitMs - now)) + stagger;\n    const flushId = setTimeout(() => {\n      firstDueAtRef.current = null;\n      const sending = ledger.due(keys, Date.now());\n      if (sending.length === 0) return;\n      if (shareKey && tabShareRef.current?.claimedUntil(shareKey) != null) {\n        bump();\n        return;\n      }\n      if (shareKey) tabShareRef.current?.claim(shareKey);\n      ledger.begin(sending);\n      void Promise.resolve()\n        .then(() => refreshRef.current())\n        .then(\n          (result) => {\n            if (refreshSucceeded(result)) ledger.succeed(sending);\n            else ledger.fail(sending, Date.now());\n          },\n          () => ledger.fail(sending, Date.now()),\n        )\n        .finally(bump);\n    }, delay);\n    return () => clearTimeout(flushId);\n    // `bump` only sets state; `tick` re-runs this after a settle or a retry falls due.\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [enabled, pendingKey, shareKey, tick]);\n}\n"],"names":["_a"],"mappings":"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"}

package/dist/threads/offline-session-list.cjs

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const react = require("react");
+const conversationList = require("../agent-runtime/src/conversation-list.cjs");
+const OFFLINE_SESSION_LIST_KEY = "session-list";
+const MAX_OFFLINE_SESSION_LIST_PAGES = 4;
+const RESTORED_UPDATED_AT = 1;
+function isSessionListFirstPage(queryKey) {
+  return queryKey[0] === conversationList.CONVERSATION_LIST_QUERY_KEY_ROOT && queryKey[4] === "first-page";
+}
+function isFirstPageKey(queryKey) {
+  return Array.isArray(queryKey) && queryKey.length === 5 && isSessionListFirstPage(queryKey) && typeof queryKey[1] === "string" && typeof queryKey[2] === "string" && typeof queryKey[3] === "number";
+}
+function isConversationRow(row) {
+  if (typeof row !== "object" || row === null) return false;
+  const { threadId, title, updatedAt } = row;
+  return typeof threadId === "string" && typeof title === "string" && typeof updatedAt === "string";
+}
+function isConversationListPage(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const { items, hasMore, totalCount } = value;
+  return Array.isArray(items) && items.every(isConversationRow) && typeof hasMore === "boolean" && (totalCount === null || typeof totalCount === "number");
+}
+function isKeptPage(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const { queryKey, data } = value;
+  return isFirstPageKey(queryKey) && isConversationListPage(data);
+}
+function useOfflineSessionList({
+  queryClient,
+  offlineList
+}) {
+  const mirror = offlineList == null ? void 0 : offlineList.mirror;
+  const ownerId = offlineList == null ? void 0 : offlineList.ownerId;
+  const boundOwner = react.useRef(null);
+  react.useEffect(() => {
+    if (!mirror || !ownerId) return;
+    if (boundOwner.current !== null && boundOwner.current !== ownerId) {
+      void queryClient.cancelQueries({ queryKey: [conversationList.CONVERSATION_LIST_QUERY_KEY_ROOT] });
+      queryClient.removeQueries({ queryKey: [conversationList.CONVERSATION_LIST_QUERY_KEY_ROOT] });
+    }
+    boundOwner.current = ownerId;
+    const boundAt = Date.now();
+    let stopped = false;
+    void mirror.loadList({ ownerId, listKey: OFFLINE_SESSION_LIST_KEY }).then((kept) => {
+      if (stopped || !kept || !Array.isArray(kept.value)) return;
+      for (const page of kept.value) {
+        if (!isKeptPage(page)) continue;
+        if (queryClient.getQueryData(page.queryKey) !== void 0) continue;
+        queryClient.setQueryData(page.queryKey, page.data, { updatedAt: RESTORED_UPDATED_AT });
+      }
+    });
+    const write = () => {
+      const pages = queryClient.getQueryCache().findAll({ predicate: (query) => isSessionListFirstPage(query.queryKey) }).filter(
+        (query) => query.state.status === "success" && query.state.dataUpdatedAt >= boundAt && isConversationListPage(query.state.data)
+      ).sort((a, b) => b.state.dataUpdatedAt - a.state.dataUpdatedAt).slice(0, MAX_OFFLINE_SESSION_LIST_PAGES).map((query) => ({ queryKey: query.queryKey, data: query.state.data }));
+      if (pages.length > 0) mirror.writeList({ ownerId, listKey: OFFLINE_SESSION_LIST_KEY, value: pages });
+    };
+    const unsubscribe = queryClient.getQueryCache().subscribe((event) => {
+      if (event.type !== "updated" || event.action.type !== "success") return;
+      if (!isSessionListFirstPage(event.query.queryKey)) return;
+      if (event.query.state.dataUpdatedAt === RESTORED_UPDATED_AT) return;
+      write();
+    });
+    return () => {
+      stopped = true;
+      unsubscribe();
+    };
+  }, [queryClient, mirror, ownerId]);
+}
+exports.MAX_OFFLINE_SESSION_LIST_PAGES = MAX_OFFLINE_SESSION_LIST_PAGES;
+exports.OFFLINE_SESSION_LIST_KEY = OFFLINE_SESSION_LIST_KEY;
+exports.isSessionListFirstPage = isSessionListFirstPage;
+exports.useOfflineSessionList = useOfflineSessionList;
+//# sourceMappingURL=offline-session-list.cjs.map

package/dist/threads/offline-session-list.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"offline-session-list.cjs","sources":["../../src/threads/offline-session-list.ts"],"sourcesContent":["import {\n  CONVERSATION_LIST_QUERY_KEY_ROOT,\n  type ConversationListPage,\n  type ThreadSnapshotMirror,\n} from '@athenaintel/agent-runtime';\nimport type { QueryClient, QueryKey } from '@tanstack/react-query';\nimport { useEffect, useRef } from 'react';\n\n/** Under this name the list's pages are kept, per owner. */\nexport const OFFLINE_SESSION_LIST_KEY = 'session-list';\n/** The first pages kept: one per filter the list was read with, the newest first. */\nexport const MAX_OFFLINE_SESSION_LIST_PAGES = 4;\n/**\n * Restored pages are stamped this old, so they paint at once and are read again on mount whenever\n * Athena can be reached (and never replace a page already read in this provider).\n */\nconst RESTORED_UPDATED_AT = 1;\n\ninterface KeptPage {\n  queryKey: QueryKey;\n  data: ConversationListPage;\n}\n\n/** A conversation list's live first page (`conversationListQueryKeys.firstPage`). */\nexport function isSessionListFirstPage(queryKey: QueryKey): boolean {\n  return queryKey[0] === CONVERSATION_LIST_QUERY_KEY_ROOT && queryKey[4] === 'first-page';\n}\n\n/** Exactly `conversationListQueryKeys.firstPage(scopeKey, filterKey, pageSize)`. */\nfunction isFirstPageKey(queryKey: unknown): queryKey is QueryKey {\n  return (\n    Array.isArray(queryKey) &&\n    queryKey.length === 5 &&\n    isSessionListFirstPage(queryKey) &&\n    typeof queryKey[1] === 'string' &&\n    typeof queryKey[2] === 'string' &&\n    typeof queryKey[3] === 'number'\n  );\n}\n\nfunction isConversationRow(row: unknown): boolean {\n  if (typeof row !== 'object' || row === null) return false;\n  const { threadId, title, updatedAt } = row as Record<string, unknown>;\n  return typeof threadId === 'string' && typeof title === 'string' && typeof updatedAt === 'string';\n}\n\n/** A page the list can render: its rows carry the fields every row reads. */\nfunction isConversationListPage(value: unknown): value is ConversationListPage {\n  if (typeof value !== 'object' || value === null) return false;\n  const { items, hasMore, totalCount } = value as Record<string, unknown>;\n  return (\n    Array.isArray(items) &&\n    items.every(isConversationRow) &&\n    typeof hasMore === 'boolean' &&\n    (totalCount === null || typeof totalCount === 'number')\n  );\n}\n\nfunction isKeptPage(value: unknown): value is KeptPage {\n  if (typeof value !== 'object' || value === null) return false;\n  const { queryKey, data } = value as Record<string, unknown>;\n  return isFirstPageKey(queryKey) && isConversationListPage(data);\n}\n\n/**\n * The session list's first pages, kept on this device sealed under the host's key\n * (`offlineList`'s mirror, `AthenaProvider`'s `offlineHistory`): restored into the list's own query\n * client before it is read, so the list paints at once and reads while Athena can't be reached,\n * and written back (debounced by the mirror) each time a first page is read. Without `offlineList`,\n * nothing.\n *\n * Owner-bound. A list kept for one owner is never restored for another, and a change of owner\n * drops every page of the list's cache before the new owner's are restored (in API-key mode two\n * people read the same list keys); only pages read since the owner was bound are kept for them. A\n * restored page that is not a list page the rows can render is left out.\n */\nexport function useOfflineSessionList({\n  queryClient,\n  offlineList,\n}: {\n  queryClient: QueryClient;\n  offlineList: { mirror: ThreadSnapshotMirror; ownerId: string } | undefined;\n}): void {\n  const mirror = offlineList?.mirror;\n  const ownerId = offlineList?.ownerId;\n  const boundOwner = useRef<string | null>(null);\n  useEffect(() => {\n    if (!mirror || !ownerId) return;\n    if (boundOwner.current !== null && boundOwner.current !== ownerId) {\n      void queryClient.cancelQueries({ queryKey: [CONVERSATION_LIST_QUERY_KEY_ROOT] });\n      queryClient.removeQueries({ queryKey: [CONVERSATION_LIST_QUERY_KEY_ROOT] });\n    }\n    boundOwner.current = ownerId;\n    const boundAt = Date.now();\n    let stopped = false;\n    void mirror.loadList({ ownerId, listKey: OFFLINE_SESSION_LIST_KEY }).then((kept) => {\n      if (stopped || !kept || !Array.isArray(kept.value)) return;\n      for (const page of kept.value) {\n        if (!isKeptPage(page)) continue;\n        if (queryClient.getQueryData(page.queryKey) !== undefined) continue;\n        queryClient.setQueryData(page.queryKey, page.data, { updatedAt: RESTORED_UPDATED_AT });\n      }\n    });\n    const write = (): void => {\n      const pages: KeptPage[] = queryClient\n        .getQueryCache()\n        .findAll({ predicate: (query) => isSessionListFirstPage(query.queryKey) })\n        .filter(\n          (query) =>\n            query.state.status === 'success' &&\n            query.state.dataUpdatedAt >= boundAt &&\n            isConversationListPage(query.state.data),\n        )\n        .sort((a, b) => b.state.dataUpdatedAt - a.state.dataUpdatedAt)\n        .slice(0, MAX_OFFLINE_SESSION_LIST_PAGES)\n        .map((query) => ({ queryKey: query.queryKey, data: query.state.data as ConversationListPage }));\n      if (pages.length > 0) mirror.writeList({ ownerId, listKey: OFFLINE_SESSION_LIST_KEY, value: pages });\n    };\n    const unsubscribe = queryClient.getQueryCache().subscribe((event) => {\n      if (event.type !== 'updated' || event.action.type !== 'success') return;\n      if (!isSessionListFirstPage(event.query.queryKey)) return;\n      // A page restored from the device is not news to write back.\n      if (event.query.state.dataUpdatedAt === RESTORED_UPDATED_AT) return;\n      write();\n    });\n    return () => {\n      stopped = true;\n      unsubscribe();\n    };\n  }, [queryClient, mirror, ownerId]);\n}\n"],"names":["CONVERSATION_LIST_QUERY_KEY_ROOT","useRef","useEffect"],"mappings":"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"}

package/dist/threads/offline-session-list.d.ts

@@ -0,0 +1,27 @@
+import { type ThreadSnapshotMirror } from '../agent-runtime/src/index';
+import type { QueryClient, QueryKey } from '@tanstack/react-query';
+/** Under this name the list's pages are kept, per owner. */
+export declare const OFFLINE_SESSION_LIST_KEY = "session-list";
+/** The first pages kept: one per filter the list was read with, the newest first. */
+export declare const MAX_OFFLINE_SESSION_LIST_PAGES = 4;
+/** A conversation list's live first page (`conversationListQueryKeys.firstPage`). */
+export declare function isSessionListFirstPage(queryKey: QueryKey): boolean;
+/**
+ * The session list's first pages, kept on this device sealed under the host's key
+ * (`offlineList`'s mirror, `AthenaProvider`'s `offlineHistory`): restored into the list's own query
+ * client before it is read, so the list paints at once and reads while Athena can't be reached,
+ * and written back (debounced by the mirror) each time a first page is read. Without `offlineList`,
+ * nothing.
+ *
+ * Owner-bound. A list kept for one owner is never restored for another, and a change of owner
+ * drops every page of the list's cache before the new owner's are restored (in API-key mode two
+ * people read the same list keys); only pages read since the owner was bound are kept for them. A
+ * restored page that is not a list page the rows can render is left out.
+ */
+export declare function useOfflineSessionList({ queryClient, offlineList, }: {
+    queryClient: QueryClient;
+    offlineList: {
+        mirror: ThreadSnapshotMirror;
+        ownerId: string;
+    } | undefined;
+}): void;