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

package/src/execution/__tests__/MessageThread.test.tsx

@@ -73,6 +73,7 @@ function makeExecution(opts: {
   phase?: ExecutionPhase;
   interactionMode?: InteractionMode;
   aiContent?: string;
+  error?: string;
 }): AgentExecution {
   const exec = create(AgentExecutionSchema);
 
@@ -91,6 +92,9 @@ function makeExecution(opts: {
 
   const status = create(AgentExecutionStatusSchema);
   status.phase = opts.phase ?? ExecutionPhase.EXECUTION_COMPLETED;
+  if (opts.error !== undefined) {
+    status.error = opts.error;
+  }
 
   const humanMsg = create(AgentMessageSchema);
   humanMsg.type = MessageType.MESSAGE_HUMAN;
@@ -246,6 +250,66 @@ describe("MessageThread", () => {
     expect(screen.getByText(/failed/i)).toBeTruthy();
   });
 
+  it("surfaces the server failure reason for a FAILED execution", () => {
+    const exec = makeExecution({
+      id: "exec-fail-reason",
+      phase: ExecutionPhase.EXECUTION_FAILED,
+      error: "Activity task timed out (RETRY_STATE_MAXIMUM_ATTEMPTS_REACHED)",
+    });
+
+    render(<MessageThread executions={[exec]} />);
+
+    expect(
+      screen.getByText(/Activity task timed out/i),
+    ).toBeTruthy();
+  });
+
+  it("does NOT surface a failure reason for a COMPLETED execution", () => {
+    const exec = makeExecution({
+      id: "exec-ok",
+      phase: ExecutionPhase.EXECUTION_COMPLETED,
+      error: "stale error that should be ignored",
+    });
+
+    render(<MessageThread executions={[exec]} />);
+
+    expect(screen.queryByText(/stale error/i)).toBeNull();
+  });
+
+  it("offers a Retry that resends the originating message on failure", () => {
+    const exec = makeExecution({
+      id: "exec-retry",
+      specMessage: "do the thing",
+      phase: ExecutionPhase.EXECUTION_FAILED,
+      error: "boom",
+    });
+    const onRetryExecution = vi.fn();
+
+    render(
+      <MessageThread executions={[exec]} onRetryExecution={onRetryExecution} />,
+    );
+
+    fireEvent.click(screen.getByRole("button", { name: /retry/i }));
+    expect(onRetryExecution).toHaveBeenCalledWith("do the thing");
+  });
+
+  it("renders a failed pending message with an inline Retry", () => {
+    const onRetrySend = vi.fn();
+
+    render(
+      <MessageThread
+        executions={[]}
+        pendingUserMessage="unsent message"
+        pendingMessageFailed
+        onRetrySend={onRetrySend}
+      />,
+    );
+
+    expect(screen.getByText("unsent message")).toBeTruthy();
+    fireEvent.click(screen.getByRole("button", { name: /retry/i }));
+    expect(onRetrySend).toHaveBeenCalledOnce();
+  });
+
   it("renders plan-completion card when last execution is completed Plan mode", () => {
     const exec = makeExecution({
       id: "exec-plan",

package/src/execution/__tests__/useExecutionStream.test.tsx

@@ -521,3 +521,98 @@ describe("useExecutionStream — auto-reconnect", () => {
     expect(subscribeFn).toHaveBeenCalledTimes(1);
   });
 });
+
+// ---------------------------------------------------------------------------
+// Watchdog (#175) — silent connect timeout + slow-stall hint
+// ---------------------------------------------------------------------------
+
+describe("useExecutionStream — watchdog", () => {
+  const IN_PROGRESS = ExecutionPhase.EXECUTION_IN_PROGRESS;
+
+  it("self-heals once then surfaces connectTimedOut on a silent connect", async () => {
+    // Every subscribe returns a stream that never delivers a snapshot.
+    const subscribeFn = vi.fn(
+      () => createControllableStream<AgentExecution>().generator,
+    );
+    const stigmer = createMockStigmer(
+      subscribeFn as unknown as Stigmer["agentExecution"]["subscribe"],
+    );
+
+    const { result } = renderHook(
+      () =>
+        useExecutionStream("exec-1", {
+          connectTimeoutMs: 20,
+          slowThresholdMs: 10_000,
+        }),
+      { wrapper: createWrapper(stigmer) },
+    );
+
+    // First timeout self-heals silently (no surfaced signal, a 2nd subscribe).
+    await waitFor(() => expect(subscribeFn).toHaveBeenCalledTimes(2));
+    // Second timeout surfaces the actionable signal — but never an error.
+    await waitFor(() => expect(result.current.connectTimedOut).toBe(true), {
+      timeout: 2000,
+    });
+    expect(result.current.error).toBeNull();
+  });
+
+  it("reconnect() clears connectTimedOut and re-subscribes", async () => {
+    const subscribeFn = vi.fn(
+      () => createControllableStream<AgentExecution>().generator,
+    );
+    const stigmer = createMockStigmer(
+      subscribeFn as unknown as Stigmer["agentExecution"]["subscribe"],
+    );
+
+    const { result } = renderHook(
+      () =>
+        useExecutionStream("exec-1", {
+          connectTimeoutMs: 20,
+          slowThresholdMs: 10_000,
+        }),
+      { wrapper: createWrapper(stigmer) },
+    );
+
+    await waitFor(() => expect(result.current.connectTimedOut).toBe(true), {
+      timeout: 2000,
+    });
+
+    const before = subscribeFn.mock.calls.length;
+    act(() => result.current.reconnect());
+
+    expect(result.current.connectTimedOut).toBe(false);
+    await waitFor(() =>
+      expect(subscribeFn.mock.calls.length).toBeGreaterThan(before),
+    );
+  });
+
+  it("flips isSlow on a silent live stream and clears it on the next snapshot", async () => {
+    const s = createControllableStream<AgentExecution>();
+    const subscribeFn = vi.fn(() => s.generator);
+    const stigmer = createMockStigmer(
+      subscribeFn as unknown as Stigmer["agentExecution"]["subscribe"],
+    );
+
+    const { result } = renderHook(
+      () =>
+        useExecutionStream("exec-1", {
+          connectTimeoutMs: 10_000,
+          slowThresholdMs: 20,
+        }),
+      { wrapper: createWrapper(stigmer) },
+    );
+
+    act(() => s.push(makeSnapshot(IN_PROGRESS)));
+    await waitFor(() => expect(result.current.isStreaming).toBe(true));
+
+    await waitFor(() => expect(result.current.isSlow).toBe(true), {
+      timeout: 2000,
+    });
+
+    // A terminal snapshot resolves the stall deterministically (no re-arm).
+    // The non-terminal "next snapshot clears + re-arms" path is covered without
+    // timing races in the StreamController unit test.
+    act(() => s.push(makeSnapshot(ExecutionPhase.EXECUTION_COMPLETED)));
+    await waitFor(() => expect(result.current.isSlow).toBe(false));
+  });
+});

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/internal/VirtualizedThread.tsx

@@ -41,6 +41,8 @@ export interface VirtualizedThreadProps {
   readonly org?: string;
   readonly planActionsDisabled?: boolean;
   readonly centerContent?: boolean;
+  readonly onRetrySend?: () => void;
+  readonly onRetryExecution?: (message: string) => void;
 }
 
 // ---------------------------------------------------------------------------
@@ -101,6 +103,8 @@ export function VirtualizedThread({
   org,
   planActionsDisabled,
   centerContent,
+  onRetrySend,
+  onRetryExecution,
 }: VirtualizedThreadProps) {
   const virtuosoRef = useRef<VirtuosoHandle>(null);
   const scrollerRef = useRef<HTMLDivElement | null>(null);
@@ -132,8 +136,10 @@ export function VirtualizedThread({
       onBuildFromPlan,
       org,
       planActionsDisabled,
+      onRetrySend,
+      onRetryExecution,
     }),
-    [formatToolCallSummary, onApprovalSubmit, submittingApprovalIds, onBuildFromPlan, org, planActionsDisabled],
+    [formatToolCallSummary, onApprovalSubmit, submittingApprovalIds, onBuildFromPlan, org, planActionsDisabled, onRetrySend, onRetryExecution],
   );
 
   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);
+  });
+});