@stigmer/react 3.0.8-dev.20260613041848 → 3.0.8-dev.20260613071809

package/src/execution/useExecutionStream.ts

@@ -17,6 +17,8 @@ import { toError } from "../internal/toError";
 import { useStreamRate } from "../internal/dev";
 import {
   StreamController,
+  DEFAULT_CONNECT_TIMEOUT_MS,
+  DEFAULT_SLOW_THRESHOLD_MS,
   type StreamControllerSink,
 } from "../internal/stream-controller";
 import {
@@ -62,6 +64,21 @@ export interface UseExecutionStreamReturn {
    * background reconnection so a recoverable hiccup never shows as an error.
    */
   readonly error: Error | null;
+  /**
+   * `true` when the stream opened but no first snapshot arrived within the
+   * connect-timeout window, even after one silent self-heal. Distinct from
+   * `error` (a thrown/closed stream that auto-reconnect retries): this is the
+   * *silent* hang the retry loop can never observe. Surface an actionable
+   * "the agent hasn't started — Retry" affordance wired to `reconnect()`.
+   * Cleared by the next snapshot or a manual `reconnect()`. Never auto-aborts.
+   */
+  readonly connectTimedOut: boolean;
+  /**
+   * `true` when a non-terminal stream has produced no new snapshot for the
+   * slow-stall window. Purely informational ("still working — taking longer
+   * than usual"); cleared by the next snapshot. Never an error, never aborts.
+   */
+  readonly isSlow: boolean;
   /**
    * Reset error state and re-establish the stream subscription.
    *
@@ -104,6 +121,18 @@ export interface UseExecutionStreamOptions {
     /** Max attempts before surfacing a terminal `error`. */
     readonly maxAttempts?: number;
   };
+  /**
+   * Hard connect-timeout in ms: how long the stream may stay `connecting`
+   * (no first snapshot) before the watchdog self-heals once and then surfaces
+   * `connectTimedOut`. Defaults to {@link DEFAULT_CONNECT_TIMEOUT_MS} (10s).
+   */
+  readonly connectTimeoutMs?: number;
+  /**
+   * Soft slow-stall threshold in ms: how long a non-terminal stream may go
+   * without a new snapshot before `isSlow` flips on. Defaults to
+   * {@link DEFAULT_SLOW_THRESHOLD_MS} (60s).
+   */
+  readonly slowThresholdMs?: number;
 }
 
 /**
@@ -172,6 +201,17 @@ export function useExecutionStream(
   }
   const store = options?.store ?? internalStoreRef.current!;
 
+  // -- Reconnect ------------------------------------------------------------
+  const [connectKey, setConnectKey] = useState(0);
+
+  // Self-heal-once guard for the connect-timeout watchdog. A ref so it survives
+  // the reconnect that the watchdog itself triggers (the controller is reset on
+  // every teardown and therefore cannot hold it). Reset only on a genuinely
+  // fresh start — a new execution, a healthy snapshot, or a manual reconnect —
+  // never on the watchdog's own self-heal hop, so the policy is exactly:
+  // first silent timeout → reconnect once; second → surface.
+  const connectAutoRetriedRef = useRef(false);
+
   // -- Controller setup -----------------------------------------------------
   const controllerRef = useRef<StreamController | null>(null);
   if (!controllerRef.current) {
@@ -186,16 +226,36 @@ export function useExecutionStream(
           store.setStreamState(state);
         });
       },
+      onConnectTimeout() {
+        if (connectAutoRetriedRef.current) {
+          // Already self-healed once and still silent — surface an actionable
+          // signal. The store dedupes, so this never causes a render storm.
+          store.setConnectTimedOut(true);
+        } else {
+          // First silent timeout: re-establish the subscription once. Most
+          // transient hangs (buffering proxy, cold start) clear on the retry.
+          connectAutoRetriedRef.current = true;
+          setConnectKey((k) => k + 1);
+        }
+      },
+      setSlow(value) {
+        store.setSlow(value);
+      },
     };
-    controllerRef.current = new StreamController(sink);
+    controllerRef.current = new StreamController(sink, undefined, undefined, {
+      connectTimeoutMs: options?.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS,
+      slowThresholdMs: options?.slowThresholdMs ?? DEFAULT_SLOW_THRESHOLD_MS,
+    });
   }
   const controller = controllerRef.current;
 
-  // -- Reconnect ------------------------------------------------------------
-  const [connectKey, setConnectKey] = useState(0);
   const reconnect = useCallback(() => {
+    // A manual retry gives a fresh self-heal budget and clears the surfaced
+    // timeout so the affordance disappears the instant the user acts.
+    connectAutoRetriedRef.current = false;
+    store.setConnectTimedOut(false);
     setConnectKey((k) => k + 1);
-  }, []);
+  }, [store]);
 
   // -- Stream rate instrumentation ------------------------------------------
   const streamRate = useStreamRate();
@@ -222,6 +282,7 @@ export function useExecutionStream(
       controller.reset();
       store.reset();
       prevExecutionIdRef.current = null;
+      connectAutoRetriedRef.current = false;
       return;
     }
 
@@ -235,6 +296,9 @@ export function useExecutionStream(
       prevExecutionIdRef.current !== executionId
     ) {
       store.reset();
+      // A genuinely different execution earns a fresh self-heal budget; the
+      // bump that re-runs this effect on reconnect must NOT reset the guard.
+      connectAutoRetriedRef.current = false;
     }
     prevExecutionIdRef.current = executionId;
 
@@ -281,6 +345,11 @@ export function useExecutionStream(
             if (signal.aborted) return;
 
             attempt = 0; // a snapshot proves the connection is healthy
+            // The first snapshot also resolves the connect watchdog: clear any
+            // surfaced timeout and refresh the self-heal budget for any future
+            // silent stretch on this same execution.
+            connectAutoRetriedRef.current = false;
+            store.setConnectTimedOut(false);
             controller.handleSnapshot(snapshot);
             streamRateRef.current.tick(snapshot.status?.messages?.length ?? 0);
 
@@ -341,6 +410,11 @@ export function useExecutionStream(
     store.subscribe,
     store.getStreamState,
   );
+  const connectTimedOut = useSyncExternalStore(
+    store.subscribe,
+    store.getConnectTimedOut,
+  );
+  const isSlow = useSyncExternalStore(store.subscribe, store.getSlow);
 
   // -- Derive public return values ------------------------------------------
   const phase = useMemo(
@@ -364,6 +438,8 @@ export function useExecutionStream(
     isReconnecting,
     reconnectAttempt,
     error,
+    connectTimedOut,
+    isSlow,
     reconnect,
   };
 }

package/src/index.ts

@@ -180,6 +180,7 @@ export {
   isTerminalPhase,
   useCreateAgentExecution,
   useExecutionStream,
+  useAgentExecutionActions,
   useSubmitApproval,
   ExecutionPhaseBadge,
   InteractionModeBadge,
@@ -251,6 +252,8 @@ export type {
   CreateAgentExecutionResult,
   UseCreateAgentExecutionReturn,
   UseExecutionStreamReturn,
+  UseAgentExecutionActionsOptions,
+  UseAgentExecutionActionsReturn,
   UseSubmitApprovalReturn,
   ExecutionPhaseBadgeProps,
   InteractionModeBadgeProps,

package/src/internal/VirtualizedThread.tsx

@@ -41,6 +41,9 @@ export interface VirtualizedThreadProps {
   readonly org?: string;
   readonly planActionsDisabled?: boolean;
   readonly centerContent?: boolean;
+  readonly onRetrySend?: () => void;
+  readonly onRetryExecution?: (message: string) => void;
+  readonly onEditMessage?: (text: string) => void;
 }
 
 // ---------------------------------------------------------------------------
@@ -101,6 +104,9 @@ export function VirtualizedThread({
   org,
   planActionsDisabled,
   centerContent,
+  onRetrySend,
+  onRetryExecution,
+  onEditMessage,
 }: VirtualizedThreadProps) {
   const virtuosoRef = useRef<VirtuosoHandle>(null);
   const scrollerRef = useRef<HTMLDivElement | null>(null);
@@ -132,8 +138,11 @@ export function VirtualizedThread({
       onBuildFromPlan,
       org,
       planActionsDisabled,
+      onRetrySend,
+      onRetryExecution,
+      onEditMessage,
     }),
-    [formatToolCallSummary, onApprovalSubmit, submittingApprovalIds, onBuildFromPlan, org, planActionsDisabled],
+    [formatToolCallSummary, onApprovalSubmit, submittingApprovalIds, onBuildFromPlan, org, planActionsDisabled, onRetrySend, onRetryExecution, onEditMessage],
   );
 
   return (

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/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

@@ -51,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 -----------------------------------------------------------
@@ -77,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 ---------------------------------------
@@ -112,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 {