@astralform/js 7.1.1 → 7.2.0

package/dist/index.d.cts

@@ -1614,6 +1614,13 @@ declare class StreamManager {
      * its awaits. This can.
      */
     private turnCounter;
+    /**
+     * True while a `resync` is between its probe and its restore. Visibility and
+     * focus listeners can both fire for one return, and two overlapping resyncs
+     * would each detach the other's stream mid-flight — the second call must
+     * find the flag set and leave the first to converge.
+     */
+    private _resyncing;
     constructor(session: ChatSession);
     get state(): StreamState;
     get activeConversationId(): string | null;
@@ -1645,6 +1652,38 @@ declare class StreamManager {
     switchTo(conversationId: string, opts?: {
         skipHistoryReplay?: boolean;
     }): Promise<void>;
+    /**
+     * Re-attach to whatever the server says is live for the ACTIVE conversation.
+     *
+     * The reconnect machinery inside ``consumeEventStream`` only runs while a
+     * stream is being consumed — and a page suspended in the background (locked
+     * phone, app switch, hidden tab) can outlive it: timers are throttled or
+     * suspended, so the stall watchdog may never fire while hidden; the
+     * reconnect budget (``SSE_MAX_RECONNECTS``) can burn out in fail-fast
+     * attempts; and a 401 from a rotated access token ends the loop outright as
+     * non-retryable. What is left is a manager that believes a turn is streaming
+     * (or has given up on one that is still running) with nothing attached — and
+     * no navigation will ever fix it, because ``switchTo`` early-returns on the
+     * conversation it is already on.
+     *
+     * So the consumer calls this when the user COMES BACK
+     * (``visibilitychange → visible``, window ``focus``). One ``getActiveJob``
+     * probe, then:
+     *
+     *  - attached to exactly the job the server calls live → healthy. The stall
+     *    watchdog owns zombie recovery from here, now that timers run again.
+     *    No-op.
+     *  - anything else — attached to a job the server no longer calls live,
+     *    attached to nothing while a job runs, or idle with a live job another
+     *    tab/device started — → detach and re-run ``restore``, the same path a
+     *    conversation reopen takes, with all of its supersession and takeover
+     *    guards inherited.
+     *
+     * Skipped while a restore is already in flight (it is converging on server
+     * truth by itself) and while another resync holds the flag — see
+     * ``_resyncing``.
+     */
+    resync(): Promise<void>;
     /**
      * Create a conversation and make it active.
      *

package/dist/index.d.ts

@@ -1614,6 +1614,13 @@ declare class StreamManager {
      * its awaits. This can.
      */
     private turnCounter;
+    /**
+     * True while a `resync` is between its probe and its restore. Visibility and
+     * focus listeners can both fire for one return, and two overlapping resyncs
+     * would each detach the other's stream mid-flight — the second call must
+     * find the flag set and leave the first to converge.
+     */
+    private _resyncing;
     constructor(session: ChatSession);
     get state(): StreamState;
     get activeConversationId(): string | null;
@@ -1645,6 +1652,38 @@ declare class StreamManager {
     switchTo(conversationId: string, opts?: {
         skipHistoryReplay?: boolean;
     }): Promise<void>;
+    /**
+     * Re-attach to whatever the server says is live for the ACTIVE conversation.
+     *
+     * The reconnect machinery inside ``consumeEventStream`` only runs while a
+     * stream is being consumed — and a page suspended in the background (locked
+     * phone, app switch, hidden tab) can outlive it: timers are throttled or
+     * suspended, so the stall watchdog may never fire while hidden; the
+     * reconnect budget (``SSE_MAX_RECONNECTS``) can burn out in fail-fast
+     * attempts; and a 401 from a rotated access token ends the loop outright as
+     * non-retryable. What is left is a manager that believes a turn is streaming
+     * (or has given up on one that is still running) with nothing attached — and
+     * no navigation will ever fix it, because ``switchTo`` early-returns on the
+     * conversation it is already on.
+     *
+     * So the consumer calls this when the user COMES BACK
+     * (``visibilitychange → visible``, window ``focus``). One ``getActiveJob``
+     * probe, then:
+     *
+     *  - attached to exactly the job the server calls live → healthy. The stall
+     *    watchdog owns zombie recovery from here, now that timers run again.
+     *    No-op.
+     *  - anything else — attached to a job the server no longer calls live,
+     *    attached to nothing while a job runs, or idle with a live job another
+     *    tab/device started — → detach and re-run ``restore``, the same path a
+     *    conversation reopen takes, with all of its supersession and takeover
+     *    guards inherited.
+     *
+     * Skipped while a restore is already in flight (it is converging on server
+     * truth by itself) and while another resync holds the flag — see
+     * ``_resyncing``.
+     */
+    resync(): Promise<void>;
     /**
      * Create a conversation and make it active.
      *

package/dist/index.js

@@ -2324,6 +2324,13 @@ var StreamManager = class {
      * its awaits. This can.
      */
     this.turnCounter = 0;
+    /**
+     * True while a `resync` is between its probe and its restore. Visibility and
+     * focus listeners can both fire for one return, and two overlapping resyncs
+     * would each detach the other's stream mid-flight — the second call must
+     * find the flag set and leave the first to converge.
+     */
+    this._resyncing = false;
     this.session = session;
     this.attach();
   }
@@ -2508,6 +2515,73 @@ var StreamManager = class {
       }
     }
   }
+  // ── Resync after the page sat in the background ───────────────
+  /**
+   * Re-attach to whatever the server says is live for the ACTIVE conversation.
+   *
+   * The reconnect machinery inside ``consumeEventStream`` only runs while a
+   * stream is being consumed — and a page suspended in the background (locked
+   * phone, app switch, hidden tab) can outlive it: timers are throttled or
+   * suspended, so the stall watchdog may never fire while hidden; the
+   * reconnect budget (``SSE_MAX_RECONNECTS``) can burn out in fail-fast
+   * attempts; and a 401 from a rotated access token ends the loop outright as
+   * non-retryable. What is left is a manager that believes a turn is streaming
+   * (or has given up on one that is still running) with nothing attached — and
+   * no navigation will ever fix it, because ``switchTo`` early-returns on the
+   * conversation it is already on.
+   *
+   * So the consumer calls this when the user COMES BACK
+   * (``visibilitychange → visible``, window ``focus``). One ``getActiveJob``
+   * probe, then:
+   *
+   *  - attached to exactly the job the server calls live → healthy. The stall
+   *    watchdog owns zombie recovery from here, now that timers run again.
+   *    No-op.
+   *  - anything else — attached to a job the server no longer calls live,
+   *    attached to nothing while a job runs, or idle with a live job another
+   *    tab/device started — → detach and re-run ``restore``, the same path a
+   *    conversation reopen takes, with all of its supersession and takeover
+   *    guards inherited.
+   *
+   * Skipped while a restore is already in flight (it is converging on server
+   * truth by itself) and while another resync holds the flag — see
+   * ``_resyncing``.
+   */
+  async resync() {
+    const conversationId = this._activeConversationId;
+    if (!conversationId) return;
+    if (this._state === "restoring" || this._resyncing) return;
+    this._resyncing = true;
+    const gen = this.generation;
+    const turn = this.turnCounter;
+    try {
+      let activeJobId = null;
+      try {
+        activeJobId = (await this.session.client.getActiveJob(conversationId)).jobId;
+      } catch {
+        return;
+      }
+      if (gen !== this.generation || this.turnStarted(turn)) return;
+      const attached = this._state === "streaming" || this.session.isStreaming;
+      if (activeJobId === null && !attached) return;
+      if (activeJobId !== null && this.session.isStreaming && this.session.currentJobId === activeJobId) {
+        return;
+      }
+      this.session.detach();
+      this.session.currentJobId = null;
+      this._state = "idle";
+      try {
+        await this.restore(conversationId, gen);
+      } catch {
+      }
+    } finally {
+      this._resyncing = false;
+      const restoring = "restoring";
+      if (gen === this.generation && this._state === restoring) {
+        this.settleIdle();
+      }
+    }
+  }
   // ── Create / rename / delete conversation ─────────────────────
   /**
    * Create a conversation and make it active.