@flamingo-stack/openframe-frontend-core 0.0.750 → 0.0.751

package/src/components/chat/hooks/use-jetstream-dialog-subscription.ts

@@ -49,14 +49,16 @@ const RECOVERY_REPORT_FLOOR_MS = 5_000;
  * - Subject: `chat.{dialogId}.{topic}`
  * - When `optStartSeq` is a number, the consumer resumes at `optStartSeq + 1`
  *   (`DeliverPolicy.ByStartSequence`). When null/undefined, it live-tails
- *   (`DeliverPolicy.New`).
+ *   (`DeliverPolicy.New`) from whenever the server creates the consumer.
  * - On reconnect, the consumer is recreated starting from the highest stream
  *   sequence we've already observed + 1, so no chunk is replayed or skipped.
- * - Consumer is ephemeral with `AckPolicy.None` and the client's default
- *   inactivity threshold (overridable via `inactiveThresholdMs`).
+ * - Consumer is ephemeral with `AckPolicy.None` and nats.ws's default
+ *   inactivity threshold (`inactiveThresholdMs` only reaches a live-tail
+ *   consumer — see the option).
  * - `reconnectionCount` also counts consumer recreations and post-absence
- *   resyncs, not just NATS reconnects — see the counter's docs. Callers refetch
- *   persisted history whenever it moves.
+ *   resyncs, not just NATS reconnects — see the counter's docs.
+ * - `caughtUpCount` is when callers refetch persisted history after a gap —
+ *   not `reconnectionCount` (see its docs).
  */
 export function useJetStreamDialogSubscription({
   enabled,
@@ -84,6 +86,11 @@ export function useJetStreamDialogSubscription({
   // churn — and churn that can feed itself, since each new consumer can report
   // its own recoveries. Callers see the two summed (see the return).
   const [recoveryCount, setRecoveryCount] = useState(0);
+  const [caughtUpCount, setCaughtUpCount] = useState(0);
+  // The dialog this hook last opened a tail for, and the reconnection count it
+  // opened it at: a consumer created for the same dialog at a higher count is
+  // one coming back after a gap, which owes the caller a history refetch.
+  const tailOpenedAtRef = useRef<{ dialogId: string; count: number } | null>(null);
   // The highest sequence seen, TAGGED with the dialog it belongs to. The tag is
   // what makes the per-dialog reset implicit — a sequence from another
   // conversation simply stops matching — so the dialog-change effect below no
@@ -381,11 +388,28 @@ export function useJetStreamDialogSubscription({
     const initialOptStart = optStartSeqRef.current;
     const startSeq = resumeSeq != null ? resumeSeq + 1 : initialOptStart != null ? initialOptStart + 1 : undefined;
 
+    // A first consumer reports nothing: the caller has just loaded the history
+    // it resumes after. A reconnect or resync recreates it at a higher count,
+    // and from then on the caller's history may predate a gap.
+    const opened = tailOpenedAtRef.current;
+    let owesCatchUp = opened !== null && opened.dialogId === dialogId && reconnectionCount > opened.count;
+    if (!owesCatchUp) tailOpenedAtRef.current = { dialogId, count: reconnectionCount };
+
     let cancelled = false;
+    // Settles an owed catch-up once the replay is in, or once there can be none
+    // (a failed resume, below) — never as the tail comes back: a refetch that
+    // lands first merges without the turns the replay is still delivering, and
+    // they then render twice.
+    const settleCatchUp = () => {
+      if (cancelled || !owesCatchUp) return;
+      owesCatchUp = false;
+      setCaughtUpCount(c => c + 1);
+    };
 
     void (async () => {
+      let handle: JetStreamSubscriptionHandle;
       try {
-        const handle = await client.subscribeJetStreamOrdered(
+        handle = await client.subscribeJetStreamOrdered(
           msg => {
             if (cancelled) return;
             const streamSeq = msg.info.streamSequence;
@@ -424,27 +448,39 @@ export function useJetStreamDialogSubscription({
               const now = Date.now();
               if (now - lastRecoveryReportRef.current < RECOVERY_REPORT_FLOOR_MS) return;
               lastRecoveryReportRef.current = now;
+              owesCatchUp = true;
               setRecoveryCount(c => c + 1);
             },
+            onCaughtUp: settleCatchUp,
           },
         );
+      } catch {
+        if (cancelled) return;
+        setIsSubscribed(false);
+        // With no consumer the refetch cannot wait for a replay. The next resume
+        // still owes one (`tailOpenedAtRef` did not move), and its own catch-up
+        // refetch clears what its replay re-renders meanwhile.
+        settleCatchUp();
+        return;
+      }
 
-        if (cancelled) {
-          try {
-            handle.unsubscribe();
-          } catch {
-            // ignore
-          }
-          return;
+      if (cancelled) {
+        try {
+          handle.unsubscribe();
+        } catch {
+          // ignore
         }
+        return;
+      }
 
-        subscriptionRef.current = handle;
-        setIsSubscribed(true);
+      subscriptionRef.current = handle;
+      setIsSubscribed(true);
+      // A host callback, outside the subscribe's catch: a throw there must not
+      // read as a failed subscribe and settle the catch-up before the replay.
+      try {
         onSubscribedRef.current?.();
-      } catch {
-        if (!cancelled) {
-          setIsSubscribed(false);
-        }
+      } catch (e) {
+        console.warn('[JetStream] onSubscribed threw:', e);
       }
     })();
 
@@ -464,14 +500,14 @@ export function useJetStreamDialogSubscription({
   }, [enabled, dialogId, isConnected, streamName, topic, reconnectionCount]);
 
   // One counter for every way the tail comes back — reconnect, consumer
-  // recreation, post-absence resync — because callers do the same thing for all
-  // of them: refetch persisted history, since the gap may predate what the
-  // stream still holds. The last two are the quiet ones; no connection event
-  // fires for either.
+  // recreation, post-absence resync. The last two are the quiet ones; no
+  // connection event fires for either. `caughtUpCount` counts the same events,
+  // each once its replay is in or once it could not be resumed (see its docs).
   return {
     isConnected,
     isSubscribed,
     reconnectionCount: reconnectionCount + recoveryCount,
+    caughtUpCount,
     currentStreamSeq,
   };
 }

package/src/components/chat/types/api.types.ts

@@ -103,8 +103,9 @@ export interface UseJetStreamDialogSubscriptionOptions {
   /** Single topic to subscribe to. */
   topic: NatsMessageType;
   /**
-   * Resume from this JetStream sequence + 1. When null/undefined, the consumer starts with
-   * DeliverPolicy.New (live tail only).
+   * Resume from this JetStream sequence + 1 (0 replays everything the stream retains for the
+   * dialog). When null/undefined, the consumer starts with DeliverPolicy.New: live tail only,
+   * from whenever the server creates the consumer — after `onSubscribed` has fired.
    */
   optStartSeq?: number | null;
   onEvent?: (payload: unknown, messageType: NatsMessageType) => void;
@@ -127,8 +128,10 @@ export interface UseJetStreamDialogSubscriptionOptions {
     maxDelayMs?: number;
     multiplier?: number;
   };
-  /** Consumer inactivity threshold in ms before NATS auto-cleans it. Defaults to the
-   *  client's, and applies only to the first consumer — recreations use nats.ws's. */
+  /** Consumer inactivity threshold in ms before NATS auto-cleans it, passed to the client
+   *  (see `JetStreamOrderedSubscribeOptions.inactiveThresholdMs`). It takes effect only
+   *  while the hook live-tails (`optStartSeq` null, nothing seen yet): every other consumer
+   *  it opens starts from a sequence ≥ 1, which nats.ws gives its own default. */
   inactiveThresholdMs?: number;
   /**
    * A counter the host bumps when it knows, from outside the page, that the tail
@@ -140,7 +143,8 @@ export interface UseJetStreamDialogSubscriptionOptions {
    * either kind of knowledge bumps this instead of hoping the page noticed.
    *
    * Treated exactly like a reconnect: the consumer is rebuilt from the highest
-   * sequence already seen, and `reconnectionCount` moves so callers refetch
+   * sequence already seen, `reconnectionCount` moves, and `caughtUpCount` moves
+   * once the rebuilt consumer has replayed what it missed, so callers refetch
    * persisted history. Any increase counts; the value itself means nothing, and
    * an increase arriving alongside a `visibilitychange` costs one rebuild, not
    * two.
@@ -156,11 +160,26 @@ export interface UseJetStreamDialogSubscriptionReturn {
    * JetStream ordered-consumer recreation, the page returning to view after
    * being hidden long enough to have missed something, or a host reporting the
    * same via `resyncSignal`. All of them mean the same thing to the caller —
-   * the tail may have skipped messages, so persisted history has to be
-   * refetched. One absence counts once even when two sources report it.
-   * Starts at 0.
+   * the tail may have skipped messages. One absence counts once even when two
+   * sources report it. Starts at 0.
+   *
+   * Not the moment to refetch persisted history: the replay is still arriving
+   * when this moves. See `caughtUpCount`.
    */
   reconnectionCount: number;
+  /**
+   * Incremented once a tail that came back — any of the events
+   * `reconnectionCount` counts, recoveries past its report floor — has
+   * delivered everything the stream still held for the dialog. Refetch
+   * persisted history on this: the gap may predate what the stream retains,
+   * and only a refetch that lands after the replay merges against the turns it
+   * re-delivered. One that lands first merges without them, and they then
+   * render a second time. Also moves when such a tail could not be resumed at
+   * all, so history is not left at its pre-gap snapshot: the next resume then
+   * replays the gap over that refetch, and its own increment's refetch clears
+   * the copies. Never moves for the first consumer of a dialog. Starts at 0.
+   */
+  caughtUpCount: number;
   /** Highest JetStream stream sequence observed so far (null before first delivery). */
   currentStreamSeq: number | null;
 }

package/src/components/chat/types/network.types.ts

@@ -36,7 +36,8 @@ export interface ChunkData {
   sequenceId?: number;
   /** JetStream stream sequence, populated from JsMsg.info.streamSequence when delivered via JetStream. */
   streamSeq?: number;
-  /** Authoritative dialog streaming state at the time this chunk was emitted; consumers should mirror it into their dialog cache. */
+  /** @deprecated Not set by the ai-agent: its chunks carry no stream state, which exists only
+   *  as the GraphQL `Dialog.streamState` field (resolved from the dialog lock). Read that instead. */
   streamState?: 'IDLE' | 'STREAMING';
   type: string;
   text?: string;

package/src/nats/nats.ts

@@ -19,14 +19,25 @@ export type JetStreamDeliverPolicy = 'new' | 'byStartSequence';
 export interface JetStreamOrderedSubscribeOptions {
   streamName: string;
   filterSubject: string;
+  /**
+   * `'byStartSequence'` delivers every retained message from `optStartSeq` on.
+   * `'new'` delivers only what is published after the server creates the
+   * consumer, which happens after the returned promise resolves: a caller that
+   * acts once subscribed and must see everything that follows uses a start
+   * sequence instead.
+   */
   deliverPolicy: JetStreamDeliverPolicy;
-  /** Required when deliverPolicy === 'byStartSequence'. */
+  /**
+   * First stream sequence to deliver, for `'byStartSequence'`; ignored for
+   * `'new'`. Missing or 0 starts at the first message the stream retains.
+   */
   optStartSeq?: number;
   /**
    * Auto-cleanup the ephemeral consumer after this idle time. Defaults to
-   * nats.ws's own. Applies to the consumer created first: nats.ws only reads it
-   * when the start sequence is the one it was built with, so every consumer it
-   * recreates afterwards reverts to the library default.
+   * nats.ws's own. nats.ws reads it only while it builds the consumer at the
+   * start it was asked for — `'new'`, or `optStartSeq` 0/unset — and has
+   * delivered nothing yet. A consumer created from `optStartSeq` ≥ 1, and any
+   * recreation after a delivery, gets the library default.
    */
   inactiveThresholdMs?: number;
   /** AbortSignal to tear down the consumer. */
@@ -39,10 +50,25 @@ export interface JetStreamOrderedSubscribeOptions {
    * but everything that aged out of the stream while it was gone is
    * unrecoverable from the tail, and no connection event announces it (the
    * WebSocket never dropped). Callers that keep persisted history alongside
-   * the live tail must refetch it here, or they keep showing a snapshot from
-   * before the gap.
+   * the live tail must refetch it, or they keep showing a snapshot from before
+   * the gap — once the recreated consumer has caught up (`onCaughtUp`), not
+   * here.
    */
   onRecovered?: () => void;
+  /**
+   * The consumer has delivered everything the stream held for the subject when
+   * it was created. Fires once for the first consumer and once more for each
+   * one nats.ws recreates (`onRecovered`): after `onMessage` has handled the
+   * last message of that backlog, straight away when it was empty, or when
+   * consuming failed and nothing more will arrive. In that last case a later
+   * consumer replays the gap over a refetch made in the meantime, and the
+   * refetch on ITS `onCaughtUp` clears the copies.
+   *
+   * This is the moment to refetch persisted history after a gap. A refetch
+   * that lands while the backlog is still arriving merges without the turns it
+   * is about to replay, and the replay then renders them a second time.
+   */
+  onCaughtUp?: () => void;
 }
 
 export interface JetStreamSubscriptionHandle {
@@ -187,7 +213,7 @@ export interface NatsClient {
   /**
    * Subscribe to a JetStream subject via an ephemeral OrderedConsumer (no acks).
    * Use `optStartSeq` with `deliverPolicy: 'byStartSequence'` to resume from a known offset,
-   * or `deliverPolicy: 'new'` to live-tail.
+   * or `deliverPolicy: 'new'` to live-tail (see that option for where it starts).
    */
   subscribeJetStreamOrdered(
     onMessage: (msg: JsMsg) => void | Promise<void>,
@@ -355,21 +381,14 @@ function mapNatsTypeToStatus(
 function watchForRecovery(
   iter: ConsumerMessages,
   recreatedEvent: ConsumerEvents.OrderedConsumerRecreated,
-  onRecovered?: () => void,
+  onRecreated: (consumerName: string) => void,
 ): void {
-  if (!onRecovered) return;
   void (async () => {
     try {
       const status = await iter.status();
       for await (const event of status) {
         if (event.type !== recreatedEvent) continue;
-        try {
-          onRecovered();
-        } catch (e) {
-          // A caller that throws must not take the watch down with it — this
-          // loop is the only thing reporting recoveries for this subscription.
-          console.warn('[nats] onRecovered threw:', e);
-        }
+        onRecreated(String(event.data));
       }
     } catch {
       // Status ends with the subscription — nothing left to report.
@@ -377,6 +396,16 @@ function watchForRecovery(
   })();
 }
 
+/** A caller that throws must not take down the loop reporting to it — that
+ *  loop is the only thing reporting these events for its subscription. */
+function invokeCallback(name: string, callback: (() => void) | undefined): void {
+  try {
+    callback?.();
+  } catch (e) {
+    console.warn(`[nats] ${name} threw:`, e);
+  }
+}
+
 export function createNatsClient(options: NatsClientOptions): NatsClient {
   let nc: NatsConnection | null = null;
   let statusLoopAbort: AbortController | null = null;
@@ -632,8 +661,11 @@ export function createNatsClient(options: NatsClientOptions): NatsClient {
     const js = conn.jetstream();
     const consumer: Consumer = await js.consumers.get(opts.streamName, {
       filterSubjects: opts.filterSubject,
-      deliver_policy: nats.DeliverPolicy.StartSequence,
-      opt_start_seq: opts.optStartSeq ?? 0,
+      // nats.ws turns a start sequence of 0 into 1, so a 'new' that fell back to
+      // StartSequence replayed everything the stream retains for the subject.
+      ...(opts.deliverPolicy === 'new'
+        ? { deliver_policy: nats.DeliverPolicy.New }
+        : { deliver_policy: nats.DeliverPolicy.StartSequence, opt_start_seq: opts.optStartSeq ?? 0 }),
       // Milliseconds, NOT nanoseconds: nats.ws runs this through its own
       // `nanos()` before it reaches the server. Pre-converting here multiplied
       // it by 1e6 twice, putting the threshold ~9.5 years out — so the ephemeral
@@ -673,6 +705,25 @@ export function createNatsClient(options: NatsClientOptions): NatsClient {
       return { unsubscribe() {} };
     }
 
+    // Whether the consumer delivering now still owes `onCaughtUp` its backlog.
+    let backlogOwed = true;
+    const reportCaughtUp = () => {
+      if (!backlogOwed || closed) return;
+      backlogOwed = false;
+      invokeCallback('onCaughtUp', opts.onCaughtUp);
+    };
+    // An empty backlog has no message to say so: it shows only in the answer to
+    // CONSUMER.CREATE, which `info(true)` returns without asking the server again.
+    const reportIfNothingPending = async (consumerName?: string) => {
+      try {
+        const info = await consumer.info(true);
+        if (consumerName !== undefined && info.name !== consumerName) return;
+        if (info.num_pending === 0) reportCaughtUp();
+      } catch {
+        // A failed lookup reports nothing: the next message with `pending === 0` does instead.
+      }
+    };
+
     (async () => {
       try {
         const iter = await consumer.consume();
@@ -685,7 +736,19 @@ export function createNatsClient(options: NatsClientOptions): NatsClient {
           return;
         }
         iterRef.current = iter;
-        watchForRecovery(iter, nats.ConsumerEvents.OrderedConsumerRecreated, opts.onRecovered);
+        if (opts.onRecovered || opts.onCaughtUp) {
+          watchForRecovery(iter, nats.ConsumerEvents.OrderedConsumerRecreated, consumerName => {
+            backlogOwed = true;
+            invokeCallback('onRecovered', opts.onRecovered);
+            // nats.ws announces the recreated consumer before it records it as
+            // the current one (a promise continuation does that), so its answer
+            // is read once those have run — and only if it is the one announced.
+            setTimeout(() => {
+              void reportIfNothingPending(consumerName);
+            }, 0);
+          });
+        }
+        if (opts.onCaughtUp) await reportIfNothingPending();
         for await (const msg of iter) {
           if (closed) break;
           try {
@@ -693,9 +756,17 @@ export function createNatsClient(options: NatsClientOptions): NatsClient {
           } catch (e) {
             emitStatus({ status: 'error', data: e });
           }
+          // `pending` is what the stream still held for this consumer when it
+          // sent this message: 0 means the backlog ends here.
+          if (msg.info.pending === 0) reportCaughtUp();
         }
       } catch (e) {
-        if (!closed) emitStatus({ status: 'error', data: e });
+        if (!closed) {
+          emitStatus({ status: 'error', data: e });
+          // This consumer delivers nothing more: settle what it owed rather than
+          // leave the caller's history at its pre-gap snapshot (see `onCaughtUp`).
+          reportCaughtUp();
+        }
       }
     })().catch((e: unknown) => emitStatus({ status: 'error', data: e }));