@stigmer/react 3.0.8-dev.20260612122433 → 3.0.8-dev.20260613051837

package/src/internal/__tests__/stream-controller.test.ts

@@ -10,6 +10,7 @@ import {
   StreamController,
   type StreamControllerSink,
 } from "../stream-controller";
+import type { StreamState } from "../store/conversation-store";
 
 // ---------------------------------------------------------------------------
 // Helpers
@@ -32,19 +33,64 @@ function makeSnapshot(
 function createTestSink(): StreamControllerSink & {
   snapshots: AgentExecution[];
   states: Array<{ stage: string; executionId?: string; error?: Error }>;
+  connectTimeouts: number;
+  slow: boolean[];
 } {
   const snapshots: AgentExecution[] = [];
   const states: Array<{ stage: string; executionId?: string; error?: Error }> =
     [];
-  return {
+  const slow: boolean[] = [];
+  const sink = {
     snapshots,
     states,
-    ingestSnapshot(snapshot) {
+    connectTimeouts: 0,
+    slow,
+    ingestSnapshot(snapshot: AgentExecution) {
       snapshots.push(snapshot);
     },
-    setStreamState(state) {
+    setStreamState(state: StreamState) {
       states.push(state as never);
     },
+    onConnectTimeout() {
+      sink.connectTimeouts += 1;
+    },
+    setSlow(value: boolean) {
+      slow.push(value);
+    },
+  };
+  return sink;
+}
+
+/**
+ * Manual watchdog clock: records armed timers without firing them. Tests fire
+ * a specific timer explicitly by its configured duration, so no real time is
+ * consumed and existing (non-watchdog) tests are unaffected — their timers are
+ * simply recorded and discarded.
+ */
+function createManualTimers() {
+  const timers = new Map<number, { cb: () => void; ms: number }>();
+  let nextId = 1;
+  return {
+    setTimer(cb: () => void, ms: number): number {
+      const id = nextId++;
+      timers.set(id, { cb, ms });
+      return id;
+    },
+    clearTimer(id: number): void {
+      timers.delete(id);
+    },
+    /** Fire every currently-armed timer whose duration equals `ms`. */
+    fire(ms: number): void {
+      for (const [id, t] of [...timers]) {
+        if (t.ms === ms) {
+          timers.delete(id);
+          t.cb();
+        }
+      }
+    },
+    get pending(): number {
+      return timers.size;
+    },
   };
 }
 
@@ -80,19 +126,27 @@ function createSynchronousScheduler() {
 // Tests
 // ---------------------------------------------------------------------------
 
+// Distinct, small watchdog durations so a test can fire one timer without the
+// other (the manual clock fires by exact duration).
+const CONNECT_MS = 100;
+const SLOW_MS = 500;
+
 describe("StreamController", () => {
   let sink: ReturnType<typeof createTestSink>;
   let scheduler: ReturnType<typeof createSynchronousScheduler>;
+  let timers: ReturnType<typeof createManualTimers>;
   let controller: StreamController;
 
   beforeEach(() => {
     sink = createTestSink();
     scheduler = createSynchronousScheduler();
-    controller = new StreamController(
-      sink,
-      scheduler.schedule,
-      scheduler.cancel,
-    );
+    timers = createManualTimers();
+    controller = new StreamController(sink, scheduler.schedule, scheduler.cancel, {
+      setTimer: timers.setTimer,
+      clearTimer: timers.clearTimer,
+      connectTimeoutMs: CONNECT_MS,
+      slowThresholdMs: SLOW_MS,
+    });
   });
 
   describe("initial state", () => {
@@ -393,6 +447,101 @@ describe("StreamController", () => {
     });
   });
 
+  describe("watchdog — connect timeout", () => {
+    it("fires onConnectTimeout while still connecting", () => {
+      controller.start("exec-1");
+      timers.fire(CONNECT_MS);
+      expect(sink.connectTimeouts).toBe(1);
+    });
+
+    it("does not fire once a first snapshot arrives (connect timer cleared)", () => {
+      controller.start("exec-1");
+      controller.handleSnapshot(
+        makeSnapshot(ExecutionPhase.EXECUTION_IN_PROGRESS),
+      );
+      timers.fire(CONNECT_MS);
+      expect(sink.connectTimeouts).toBe(0);
+    });
+
+    it("does not fire after a terminal snapshot", () => {
+      controller.start("exec-1");
+      controller.handleSnapshot(
+        makeSnapshot(ExecutionPhase.EXECUTION_FAILED),
+      );
+      timers.fire(CONNECT_MS);
+      expect(sink.connectTimeouts).toBe(0);
+    });
+
+    it("does not fire after reset", () => {
+      controller.start("exec-1");
+      controller.reset();
+      timers.fire(CONNECT_MS);
+      expect(sink.connectTimeouts).toBe(0);
+    });
+
+    it("stands down while auto-reconnect is in flight", () => {
+      controller.start("exec-1");
+      controller.handleReconnecting(1, new Error("drop"));
+      timers.fire(CONNECT_MS);
+      expect(sink.connectTimeouts).toBe(0);
+    });
+  });
+
+  describe("watchdog — slow stall", () => {
+    it("sets the slow hint after the threshold while streaming", () => {
+      controller.start("exec-1");
+      controller.handleSnapshot(
+        makeSnapshot(ExecutionPhase.EXECUTION_IN_PROGRESS),
+      );
+      timers.fire(SLOW_MS);
+      expect(sink.slow.at(-1)).toBe(true);
+    });
+
+    it("clears the slow hint on the next snapshot", () => {
+      controller.start("exec-1");
+      timers.fire(SLOW_MS);
+      expect(sink.slow.at(-1)).toBe(true);
+
+      controller.handleSnapshot(
+        makeSnapshot(ExecutionPhase.EXECUTION_IN_PROGRESS),
+      );
+      // Re-arming on a fresh snapshot clears the prior hint.
+      expect(sink.slow.at(-1)).toBe(false);
+    });
+
+    it("clears the slow hint on a terminal snapshot", () => {
+      controller.start("exec-1");
+      timers.fire(SLOW_MS);
+      expect(sink.slow.at(-1)).toBe(true);
+
+      controller.handleSnapshot(
+        makeSnapshot(ExecutionPhase.EXECUTION_COMPLETED),
+      );
+      expect(sink.slow.at(-1)).toBe(false);
+    });
+
+    it("clears the slow hint and timer on reset", () => {
+      controller.start("exec-1");
+      timers.fire(SLOW_MS);
+      controller.reset();
+      expect(sink.slow.at(-1)).toBe(false);
+      // The (already fired) timer leaves nothing armed; a stray fire is a no-op.
+      const before = sink.slow.length;
+      timers.fire(SLOW_MS);
+      expect(sink.slow.length).toBe(before);
+    });
+
+    it("does not fire after reaching a terminal phase", () => {
+      controller.start("exec-1");
+      controller.handleSnapshot(
+        makeSnapshot(ExecutionPhase.EXECUTION_COMPLETED),
+      );
+      const before = sink.slow.length;
+      timers.fire(SLOW_MS);
+      expect(sink.slow.length).toBe(before);
+    });
+  });
+
   describe("default constructor (browser rAF binding)", () => {
     let mockRaf: ReturnType<typeof vi.fn>;
     let mockCaf: ReturnType<typeof vi.fn>;
@@ -415,7 +564,10 @@ describe("StreamController", () => {
     });
 
     it("does not throw when using default scheduleFlush/cancelFlush", () => {
-      const defaultController = new StreamController(sink);
+      const defaultController = new StreamController(sink, undefined, undefined, {
+        setTimer: timers.setTimer,
+        clearTimer: timers.clearTimer,
+      });
       defaultController.start("exec-1");
 
       expect(() => {
@@ -428,7 +580,10 @@ describe("StreamController", () => {
     });
 
     it("delegates cancelFlush to cancelAnimationFrame", () => {
-      const defaultController = new StreamController(sink);
+      const defaultController = new StreamController(sink, undefined, undefined, {
+        setTimer: timers.setTimer,
+        clearTimer: timers.clearTimer,
+      });
       defaultController.start("exec-1");
       defaultController.handleSnapshot(
         makeSnapshot(ExecutionPhase.EXECUTION_IN_PROGRESS),

package/src/internal/__tests__/useFetch.test.tsx

@@ -0,0 +1,59 @@
+import { describe, it, expect, vi } from "vitest";
+import { renderHook, act, waitFor } from "@testing-library/react";
+import { useFetch } from "../useFetch";
+
+// ---------------------------------------------------------------------------
+// useFetch — refetchOnWindowFocus (#175 re-discovery)
+// ---------------------------------------------------------------------------
+//
+// No FetchCacheProvider is mounted; useFetch tolerates a null cache, so these
+// tests exercise the focus/visibility refetch path in isolation.
+
+describe("useFetch — refetchOnWindowFocus", () => {
+  it("refetches when the window regains focus", async () => {
+    const fetchFn = vi.fn().mockResolvedValue("data");
+
+    renderHook(() =>
+      useFetch(fetchFn, ["k"], "initial", { refetchOnWindowFocus: true }),
+    );
+
+    await waitFor(() => expect(fetchFn).toHaveBeenCalledTimes(1));
+
+    act(() => {
+      window.dispatchEvent(new Event("focus"));
+    });
+
+    await waitFor(() => expect(fetchFn).toHaveBeenCalledTimes(2));
+  });
+
+  it("does not refetch on focus when the option is off (default)", async () => {
+    const fetchFn = vi.fn().mockResolvedValue("data");
+
+    renderHook(() => useFetch(fetchFn, ["k"], "initial"));
+
+    await waitFor(() => expect(fetchFn).toHaveBeenCalledTimes(1));
+
+    act(() => {
+      window.dispatchEvent(new Event("focus"));
+    });
+
+    // Give any (incorrectly registered) listener a chance to fire.
+    await new Promise((r) => setTimeout(r, 30));
+    expect(fetchFn).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not register focus refetch when fetching is disabled", async () => {
+    renderHook(() =>
+      useFetch<string>(null, ["k"], "initial", { refetchOnWindowFocus: true }),
+    );
+
+    act(() => {
+      window.dispatchEvent(new Event("focus"));
+    });
+
+    // Nothing to assert beyond "does not throw" — a null fetchFn must not
+    // attach a listener that would call into a non-existent fetch.
+    await new Promise((r) => setTimeout(r, 10));
+    expect(true).toBe(true);
+  });
+});

package/src/internal/backoff.ts

@@ -0,0 +1,100 @@
+/**
+ * Exponential-backoff scheduling for resilient stream reconnection.
+ *
+ * Pure and framework-agnostic — the timing math is a plain function and the
+ * wait is a cancelable promise, so both are exhaustively unit-testable
+ * without React or fake DOM (mirrors the codebase's extract-the-pure-core
+ * convention, e.g. `computeFollowCenter` / `isRecoveryTransition`).
+ *
+ * @internal Not part of the public `@stigmer/react` API.
+ */
+
+/** Tunable backoff schedule. All fields optional — sensible defaults apply. */
+export interface BackoffOptions {
+  /** Delay before the first retry, in milliseconds. */
+  readonly baseDelayMs?: number;
+  /** Upper bound on any single delay, in milliseconds. */
+  readonly maxDelayMs?: number;
+  /** Multiplier applied per attempt (`base * factor^(attempt-1)`). */
+  readonly factor?: number;
+}
+
+/** Delay before the first reconnect attempt. */
+export const DEFAULT_RECONNECT_BASE_DELAY_MS = 1_000;
+/** Ceiling for any single reconnect delay. */
+export const DEFAULT_RECONNECT_MAX_DELAY_MS = 30_000;
+/** Per-attempt growth multiplier. */
+export const DEFAULT_RECONNECT_FACTOR = 2;
+/**
+ * Attempts before giving up and surfacing a terminal error. With the
+ * defaults above this is ≈ several minutes of outage before the user sees
+ * an error banner — long enough to ride out sleep/wake and network blips,
+ * bounded enough to avoid an unbounded background loop against a stream
+ * that will never recover (e.g. a deleted execution).
+ */
+export const DEFAULT_RECONNECT_MAX_ATTEMPTS = 10;
+
+/**
+ * Compute the backoff delay (ms) for a 1-based reconnect attempt.
+ *
+ * Exponential growth (`base * factor^(attempt-1)`) capped at `maxDelayMs`,
+ * then **full jitter** — a uniform random point in `[0, capped]`. Full
+ * jitter (AWS, "Exponential Backoff And Jitter") de-synchronizes a fleet of
+ * clients that all dropped at the same instant, preventing a reconnect
+ * thundering herd against a recovering server.
+ *
+ * `random` is injectable purely so tests can assert exact values; callers
+ * should omit it.
+ */
+export function computeBackoffDelay(
+  attempt: number,
+  opts?: BackoffOptions,
+  random: () => number = Math.random,
+): number {
+  const base = opts?.baseDelayMs ?? DEFAULT_RECONNECT_BASE_DELAY_MS;
+  const max = opts?.maxDelayMs ?? DEFAULT_RECONNECT_MAX_DELAY_MS;
+  const factor = opts?.factor ?? DEFAULT_RECONNECT_FACTOR;
+
+  const safeAttempt = Math.max(1, Math.floor(attempt));
+  const exponential = base * factor ** (safeAttempt - 1);
+  const capped = Math.min(exponential, max);
+  return Math.round(random() * capped);
+}
+
+/** Rejection reason for an aborted {@link sleep}, distinguishable by name. */
+export class AbortError extends Error {
+  constructor() {
+    super("The operation was aborted.");
+    this.name = "AbortError";
+  }
+}
+
+/**
+ * Promise-based delay that settles after `ms`, or rejects immediately with
+ * {@link AbortError} if `signal` is (or becomes) aborted.
+ *
+ * The timer is cleared and the abort listener removed on every exit path, so
+ * a reconnect wait leaves nothing pending when a component unmounts or the
+ * subscription is torn down mid-backoff — no leaked timer, no resubscribe
+ * after teardown.
+ */
+export function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise<void>((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(new AbortError());
+      return;
+    }
+
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(new AbortError());
+    };
+
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}

package/src/internal/store/__tests__/conversation-store.test.ts

@@ -190,6 +190,67 @@ describe("ConversationStore", () => {
     });
   });
 
+  describe("watchdog signals", () => {
+    it("connectTimedOut: defaults false, notifies only on change", () => {
+      const store = new ConversationStore();
+      expect(store.getConnectTimedOut()).toBe(false);
+
+      const listener = vi.fn();
+      store.subscribe(listener);
+
+      store.setConnectTimedOut(true);
+      expect(store.getConnectTimedOut()).toBe(true);
+      expect(listener).toHaveBeenCalledTimes(1);
+
+      store.setConnectTimedOut(true);
+      expect(listener).toHaveBeenCalledTimes(1); // no-op on same value
+
+      store.setConnectTimedOut(false);
+      expect(store.getConnectTimedOut()).toBe(false);
+      expect(listener).toHaveBeenCalledTimes(2);
+    });
+
+    it("isSlow: defaults false, notifies only on change", () => {
+      const store = new ConversationStore();
+      expect(store.getSlow()).toBe(false);
+
+      const listener = vi.fn();
+      store.subscribe(listener);
+
+      store.setSlow(true);
+      expect(store.getSlow()).toBe(true);
+      expect(listener).toHaveBeenCalledTimes(1);
+
+      store.setSlow(true);
+      expect(listener).toHaveBeenCalledTimes(1);
+    });
+
+    it("reset clears both watchdog signals", () => {
+      const store = new ConversationStore();
+      store.setConnectTimedOut(true);
+      store.setSlow(true);
+
+      const listener = vi.fn();
+      store.subscribe(listener);
+
+      store.reset();
+      expect(store.getConnectTimedOut()).toBe(false);
+      expect(store.getSlow()).toBe(false);
+      expect(listener).toHaveBeenCalledTimes(1);
+    });
+
+    it("reset notifies when only a watchdog signal was set", () => {
+      const store = new ConversationStore();
+      store.setSlow(true);
+
+      const listener = vi.fn();
+      store.subscribe(listener);
+
+      store.reset();
+      expect(listener).toHaveBeenCalledTimes(1);
+    });
+  });
+
   describe("reset", () => {
     it("clears execution and stream state", () => {
       const store = new ConversationStore();

package/src/internal/store/conversation-store.ts

@@ -9,6 +9,19 @@ export type StreamState =
   | { readonly stage: "idle" }
   | { readonly stage: "connecting"; readonly executionId: string }
   | { readonly stage: "streaming"; readonly executionId: string }
+  | {
+      /**
+       * A non-terminal stream drop is being retried in the background. The
+       * last-known-good snapshot stays visible and no error is surfaced —
+       * the public `error` only appears once retries are exhausted. `attempt`
+       * is the 1-based retry count; `error` is the transient cause, retained
+       * for diagnostics (it is not shown to the user while reconnecting).
+       */
+      readonly stage: "reconnecting";
+      readonly executionId: string;
+      readonly attempt: number;
+      readonly error: Error;
+    }
   | { readonly stage: "complete"; readonly executionId: string }
   | {
       readonly stage: "error";
@@ -38,6 +51,8 @@ type Listener = () => void;
 export class ConversationStore {
   private _execution: AgentExecution | null = null;
   private _streamState: StreamState = IDLE_STATE;
+  private _connectTimedOut = false;
+  private _isSlow = false;
   private _listeners = new Set<Listener>();
 
   // -- Ingestion -----------------------------------------------------------
@@ -64,16 +79,47 @@ export class ConversationStore {
     this._notify();
   }
 
+  /**
+   * Set the hard connect-timeout signal — the stream opened but no first
+   * snapshot arrived within the watchdog window even after a silent retry.
+   *
+   * Orthogonal to {@link setStreamState}: the stream may still be live, so
+   * this is **not** a lifecycle stage and deliberately does not touch the
+   * `error` stage (that is auto-reconnect's domain). Booleans are stable by
+   * value, so no snapshot caching is needed; listeners fire only on change.
+   */
+  setConnectTimedOut(value: boolean): void {
+    if (this._connectTimedOut === value) return;
+    this._connectTimedOut = value;
+    this._notify();
+  }
+
+  /**
+   * Set the soft slow-stall hint — the stream is non-terminal but has gone
+   * silent past the watchdog window. Purely informational ("still working,
+   * taking longer than usual"); cleared by the next snapshot. Never aborts.
+   */
+  setSlow(value: boolean): void {
+    if (this._isSlow === value) return;
+    this._isSlow = value;
+    this._notify();
+  }
+
   /**
    * Reset to initial state. Used when the session identity changes
    * or the hook unmounts.
    */
   reset(): void {
-    const wasIdle =
-      this._execution === null && this._streamState.stage === "idle";
+    const wasClean =
+      this._execution === null &&
+      this._streamState.stage === "idle" &&
+      !this._connectTimedOut &&
+      !this._isSlow;
     this._execution = null;
     this._streamState = IDLE_STATE;
-    if (!wasIdle) this._notify();
+    this._connectTimedOut = false;
+    this._isSlow = false;
+    if (!wasClean) this._notify();
   }
 
   // -- useSyncExternalStore contract ---------------------------------------
@@ -99,6 +145,16 @@ export class ConversationStore {
     return this._streamState;
   };
 
+  /** Stable snapshot selector for the hard connect-timeout signal. */
+  getConnectTimedOut = (): boolean => {
+    return this._connectTimedOut;
+  };
+
+  /** Stable snapshot selector for the soft slow-stall hint. */
+  getSlow = (): boolean => {
+    return this._isSlow;
+  };
+
   // -- Internal ------------------------------------------------------------
 
   private _notify(): void {
@@ -122,6 +178,15 @@ function streamStateEqual(a: StreamState, b: StreamState): boolean {
     a.error === b.error
   )
     return true;
+  // Each retry bumps `attempt`, so two reconnecting states are only equal
+  // when the attempt matches — every attempt must re-notify subscribers.
+  if (
+    a.stage === "reconnecting" &&
+    b.stage === "reconnecting" &&
+    a.executionId === b.executionId &&
+    a.attempt === b.attempt
+  )
+    return true;
   if ("executionId" in a && "executionId" in b)
     return a.executionId === b.executionId;
   return false;

package/src/internal/store/workflow-execution-event-store.ts

@@ -10,6 +10,19 @@ export type WorkflowEventStreamState =
   | { readonly stage: "idle" }
   | { readonly stage: "connecting"; readonly executionId: string }
   | { readonly stage: "streaming"; readonly executionId: string }
+  | {
+      /**
+       * A non-terminal event stream drop is being retried in the background.
+       * Accumulated events stay visible and no error is surfaced until retries
+       * are exhausted. On reconnect the subscription resumes from the last
+       * received `sequence_number`, so no events are lost. `attempt` is the
+       * 1-based retry count; `error` is the transient cause (diagnostic only).
+       */
+      readonly stage: "reconnecting";
+      readonly executionId: string;
+      readonly attempt: number;
+      readonly error: Error;
+    }
   | { readonly stage: "complete"; readonly executionId: string }
   | {
       readonly stage: "error";
@@ -422,6 +435,15 @@ function streamStateEqual(
     a.error === b.error
   )
     return true;
+  // Each retry bumps `attempt`, so two reconnecting states are only equal
+  // when the attempt matches — every attempt must re-notify subscribers.
+  if (
+    a.stage === "reconnecting" &&
+    b.stage === "reconnecting" &&
+    a.executionId === b.executionId &&
+    a.attempt === b.attempt
+  )
+    return true;
   if ("executionId" in a && "executionId" in b)
     return a.executionId === b.executionId;
   return false;