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

package/src/internal/stream-controller.ts

@@ -14,6 +14,20 @@ import { ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/agentexecutio
 
 const IDLE: StreamState = { stage: "idle" };
 
+/**
+ * Hard connect-timeout: time the stream may stay `connecting` (no first
+ * snapshot) before the watchdog acts. Sized well above a healthy connect
+ * (the server sends the initial snapshot in ~1 RTT) yet short enough that a
+ * silent hang surfaces an affordance within a few seconds, not minutes.
+ */
+export const DEFAULT_CONNECT_TIMEOUT_MS = 10_000;
+/**
+ * Soft slow-stall threshold: a non-terminal stream that produces no new
+ * snapshot for this long flips an informational "still working" hint. Long
+ * enough that ordinary model thinking-time never trips it.
+ */
+export const DEFAULT_SLOW_THRESHOLD_MS = 60_000;
+
 /**
  * Callback interface for the stream controller to communicate with
  * its host (the React hook). All mutations to external state go
@@ -24,6 +38,27 @@ export interface StreamControllerSink {
   ingestSnapshot(snapshot: AgentExecution): void;
   /** Transition the store's stream lifecycle state. */
   setStreamState(state: StreamState): void;
+  /**
+   * The hard connect-timeout elapsed while still `connecting`. The host owns
+   * the self-heal-once-then-surface policy (it holds the `connectKey` reconnect
+   * counter and the per-subscription guard that survives a reconnect, which
+   * the controller — reset on every teardown — cannot).
+   */
+  onConnectTimeout(): void;
+  /** Set or clear the soft slow-stall hint signal. */
+  setSlow(value: boolean): void;
+}
+
+/**
+ * Injectable watchdog configuration. Timers default to `setTimeout`/
+ * `clearTimeout`; tests pass fakes so the watchdog is exercised without real
+ * time. Mirrors the existing `scheduleFlush`/`cancelFlush` injection idiom.
+ */
+export interface StreamControllerWatchdog {
+  readonly setTimer?: (cb: () => void, ms: number) => number;
+  readonly clearTimer?: (id: number) => void;
+  readonly connectTimeoutMs?: number;
+  readonly slowThresholdMs?: number;
 }
 
 // ---------------------------------------------------------------------------
@@ -52,6 +87,14 @@ export class StreamController {
   private _scheduleFlush: (cb: () => void) => number;
   private _cancelFlush: (id: number) => void;
 
+  // -- Watchdog ------------------------------------------------------------
+  private _setTimer: (cb: () => void, ms: number) => number;
+  private _clearTimer: (id: number) => void;
+  private _connectTimeoutMs: number;
+  private _slowThresholdMs: number;
+  private _connectTimerId: number | null = null;
+  private _slowTimerId: number | null = null;
+
   constructor(
     sink: StreamControllerSink,
     scheduleFlush: (cb: () => void) => number = typeof requestAnimationFrame !== "undefined"
@@ -60,10 +103,19 @@ export class StreamController {
     cancelFlush: (id: number) => void = typeof cancelAnimationFrame !== "undefined"
       ? (id: number) => cancelAnimationFrame(id)
       : (id: number) => clearTimeout(id),
+    watchdog?: StreamControllerWatchdog,
   ) {
     this._sink = sink;
     this._scheduleFlush = scheduleFlush;
     this._cancelFlush = cancelFlush;
+    this._setTimer =
+      watchdog?.setTimer ??
+      ((cb, ms) => setTimeout(cb, ms) as unknown as number);
+    this._clearTimer = watchdog?.clearTimer ?? ((id) => clearTimeout(id));
+    this._connectTimeoutMs =
+      watchdog?.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS;
+    this._slowThresholdMs =
+      watchdog?.slowThresholdMs ?? DEFAULT_SLOW_THRESHOLD_MS;
   }
 
   /** Current FSM state (read-only). */
@@ -78,6 +130,11 @@ export class StreamController {
   start(executionId: string): void {
     this._cancelPendingFlush();
     this._bufferedSnapshot = null;
+    // Arm both watchdogs the moment we begin connecting. The connect-timeout
+    // guards the first snapshot; the slow-stall hint guards every quiet stretch
+    // thereafter. Both are reset by the next snapshot and cleared on any exit.
+    this._armConnectTimer();
+    this._armSlowTimer();
     this._transition({ stage: "connecting", executionId });
   }
 
@@ -95,13 +152,19 @@ export class StreamController {
     const terminal = isTerminalPhase(phase);
 
     if (terminal) {
+      this._cancelWatchdogs();
+      this._sink.setSlow(false);
       this._cancelPendingFlush();
       this._bufferedSnapshot = null;
       this._sink.ingestSnapshot(snapshot);
       this._transition({ stage: "complete", executionId });
     } else {
-      // A snapshot proves the (re)connection is healthy: advance from either
-      // the initial `connecting` or a `reconnecting` retry into `streaming`.
+      // A snapshot proves the (re)connection is healthy: the connect-timeout no
+      // longer applies, and the slow-stall window restarts from now.
+      this._cancelConnectTimer();
+      this._armSlowTimer();
+      // Advance from either the initial `connecting` or a `reconnecting` retry
+      // into `streaming`.
       if (
         this._state.stage === "connecting" ||
         this._state.stage === "reconnecting"
@@ -123,6 +186,12 @@ export class StreamController {
   handleReconnecting(attempt: number, error: Error): void {
     const executionId = this._activeExecutionId();
     if (!executionId) return;
+    // Auto-reconnect (#174) has taken over with its own visible affordance and
+    // bounded attempt budget, so the silence watchdogs stand down — they exist
+    // for the case where the stream stalls *without* a drop. The slow hint is
+    // cleared so "reconnecting" and "slow" never show at once.
+    this._cancelWatchdogs();
+    this._sink.setSlow(false);
     this._transition({ stage: "reconnecting", executionId, attempt, error });
   }
 
@@ -134,6 +203,8 @@ export class StreamController {
     const executionId = this._activeExecutionId();
     if (!executionId) return;
 
+    this._cancelWatchdogs();
+    this._sink.setSlow(false);
     this._flushBuffer();
     if (this._state.stage !== "complete") {
       this._transition({ stage: "complete", executionId });
@@ -148,13 +219,17 @@ export class StreamController {
     const executionId = this._activeExecutionId();
     if (!executionId) return;
 
+    this._cancelWatchdogs();
+    this._sink.setSlow(false);
     this._cancelPendingFlush();
     this._flushBuffer();
     this._transition({ stage: "error", executionId, error });
   }
 
-  /** Reset to idle. Cancels any pending flush. */
+  /** Reset to idle. Cancels any pending flush and watchdog timers. */
   reset(): void {
+    this._cancelWatchdogs();
+    this._sink.setSlow(false);
     this._cancelPendingFlush();
     this._bufferedSnapshot = null;
     if (this._state.stage !== "idle") {
@@ -203,4 +278,49 @@ export class StreamController {
       this._rafId = null;
     }
   }
+
+  // -- Watchdog timers ------------------------------------------------------
+
+  private _armConnectTimer(): void {
+    this._cancelConnectTimer();
+    this._connectTimerId = this._setTimer(() => {
+      this._connectTimerId = null;
+      // Only meaningful while still awaiting the first snapshot; any later
+      // stage has its own handling and has already cleared this timer.
+      if (this._state.stage !== "connecting") return;
+      this._sink.onConnectTimeout();
+    }, this._connectTimeoutMs);
+  }
+
+  private _armSlowTimer(): void {
+    this._cancelSlowTimer();
+    // Re-arming means activity just resumed (or is starting), so a prior slow
+    // hint no longer holds — clear it before counting the next quiet stretch.
+    this._sink.setSlow(false);
+    this._slowTimerId = this._setTimer(() => {
+      this._slowTimerId = null;
+      if (this._state.stage !== "connecting" && this._state.stage !== "streaming")
+        return;
+      this._sink.setSlow(true);
+    }, this._slowThresholdMs);
+  }
+
+  private _cancelConnectTimer(): void {
+    if (this._connectTimerId !== null) {
+      this._clearTimer(this._connectTimerId);
+      this._connectTimerId = null;
+    }
+  }
+
+  private _cancelSlowTimer(): void {
+    if (this._slowTimerId !== null) {
+      this._clearTimer(this._slowTimerId);
+      this._slowTimerId = null;
+    }
+  }
+
+  private _cancelWatchdogs(): void {
+    this._cancelConnectTimer();
+    this._cancelSlowTimer();
+  }
 }

package/src/internal/useFetch.ts

@@ -15,6 +15,14 @@ export interface UseFetchOptions {
    */
   readonly refetchInterval?: number | false;
 
+  /**
+   * Re-fetch when the window regains focus or the tab becomes visible
+   * again. Covers the app-relaunch / tab-switch case where data may have
+   * gone stale while the app was backgrounded. A focus refetch is skipped
+   * while a fetch is already in flight. Defaults to `false`.
+   */
+  readonly refetchOnWindowFocus?: boolean;
+
   /**
    * Stable string key for cross-mount caching.
    *
@@ -183,6 +191,24 @@ export function useFetch<T>(
     return () => clearInterval(id);
   }, [refetchInterval, fetchFn, refetch]);
 
+  const refetchOnWindowFocus = options?.refetchOnWindowFocus;
+  useEffect(() => {
+    if (!refetchOnWindowFocus || !fetchFn) return;
+    if (typeof window === "undefined") return;
+    const onActive = () => {
+      if (!isFetchingRef.current) refetch();
+    };
+    const onVisible = () => {
+      if (document.visibilityState === "visible") onActive();
+    };
+    window.addEventListener("focus", onActive);
+    document.addEventListener("visibilitychange", onVisible);
+    return () => {
+      window.removeEventListener("focus", onActive);
+      document.removeEventListener("visibilitychange", onVisible);
+    };
+  }, [refetchOnWindowFocus, fetchFn, refetch]);
+
   const isLoading = isFetching && !hasDataRef.current;
   const isRefetching = isFetching && hasDataRef.current;
 

package/src/session/SessionViewer.tsx

@@ -288,7 +288,37 @@ function ConversationColumn({
   isEndUser,
 }: ConversationColumnProps) {
   const { conv } = flow;
-  const sendError = flow.submitError ?? conv.sendError ?? conv.approvalError;
+  const sendError =
+    flow.submitError ?? conv.sendError ?? conv.approvalError ?? conv.stopError;
+
+  // Retry a terminal-failed execution by resending its originating message
+  // through the full submit pipeline (agent override, runtime-env, workspace).
+  const onRetryExecution = useCallback(
+    (message: string) => {
+      void flow.handleSubmit(message);
+    },
+    [flow.handleSubmit],
+  );
+
+  // Stop the in-flight turn (graceful cancel, escalating to terminate on a
+  // repeat press). Only wired while the active execution is stoppable.
+  const handleStop = useCallback(() => {
+    void conv.stop();
+  }, [conv.stop]);
+
+  // Edit-and-resubmit: stop the in-flight turn and pre-fill the composer with
+  // the original text. The append-only execution log can't be rewritten, so
+  // the user reviews the prefilled message and resubmits it as a NEW execution
+  // through the normal Send pipeline. The cancelled turn stays in history with
+  // its phase badge — an honest record rather than a silent edit.
+  const handleEditMessage = useCallback(
+    (text: string) => {
+      void conv.stop();
+      composerRef.current?.setMessage(text);
+      composerRef.current?.focus();
+    },
+    [conv.stop, composerRef],
+  );
 
   return (
     <div className="flex h-full min-w-0 flex-col">
@@ -296,8 +326,12 @@ function ConversationColumn({
         executions={conv.completedExecutions}
         activeStreamExecution={conv.activeStreamExecution}
         pendingUserMessage={conv.pendingUserMessage}
+        pendingMessageFailed={!!conv.sendError && !!conv.pendingUserMessage}
+        onRetrySend={conv.retryLastSend}
+        onRetryExecution={onRetryExecution}
         onApprovalSubmit={flow.submitApproval}
         submittingApprovalIds={conv.submittingApprovalIds}
+        onEditMessage={conv.isStoppable ? handleEditMessage : undefined}
         workspaceEntries={conv.workspaceEntries}
         sandboxWorkspaceRoot={flow.sandboxWorkspaceRoot}
         onBuildFromPlan={onBuildFromPlan}
@@ -308,6 +342,10 @@ function ConversationColumn({
       />
       <div className="mx-auto w-full max-w-3xl">
         {conv.isReconnecting && <ReconnectingIndicator />}
+        {conv.connectTimedOut && (
+          <ConnectTimedOutBanner onRetry={conv.reconnectStream} />
+        )}
+        {conv.isSlow && !conv.connectTimedOut && <SlowIndicator />}
         {conv.streamError && (
           <StreamErrorBanner
             error={conv.streamError}
@@ -323,6 +361,8 @@ function ConversationColumn({
           onSubmit={flow.handleSubmit}
           isSubmitting={conv.isSending}
           disabled={!conv.canSendFollowUp}
+          onStop={conv.isStoppable ? handleStop : undefined}
+          isStopping={conv.isStopping}
           org={org}
           harness={flow.harness}
           defaultModelId={modelId}
@@ -573,6 +613,52 @@ function ReconnectingIndicator() {
   );
 }
 
+/**
+ * Actionable banner for the connect-timeout watchdog: the stream opened but
+ * never delivered a first snapshot — the agent hasn't started. Mirrors
+ * {@link StreamErrorBanner}'s shape (message + Retry) since both resolve via
+ * the same `reconnect()` path, but its copy names the specific failure.
+ */
+function ConnectTimedOutBanner({ onRetry }: { onRetry: () => void }) {
+  return (
+    <div role="alert" className="flex items-center gap-3 border-t border-border bg-muted px-4 py-2.5">
+      <p className="min-w-0 flex-1 truncate text-sm text-muted-foreground">
+        The agent hasn&rsquo;t started yet.
+      </p>
+      <button
+        type="button"
+        onClick={onRetry}
+        className="inline-flex shrink-0 items-center gap-1.5 rounded-md border border-border px-2 py-1 text-xs font-medium hover:bg-card"
+      >
+        Retry
+      </button>
+    </div>
+  );
+}
+
+/**
+ * Low-weight informational hint for the slow-stall watchdog: a live stream has
+ * gone quiet longer than usual. Never an error and offers no action — the
+ * stream is still expected to resume on its own.
+ */
+function SlowIndicator() {
+  return (
+    <div
+      role="status"
+      aria-live="polite"
+      className="flex items-center gap-2 border-t border-border-muted px-4 py-1.5 text-xs text-muted-foreground"
+    >
+      <span className="relative flex h-2 w-2 shrink-0" aria-hidden="true">
+        <span className="absolute inline-flex h-full w-full animate-ping rounded-full bg-muted-foreground opacity-75 motion-reduce:animate-none" />
+        <span className="relative inline-flex h-2 w-2 rounded-full bg-muted-foreground" />
+      </span>
+      <span className="min-w-0 flex-1 truncate">
+        Still working — this is taking longer than usual.
+      </span>
+    </div>
+  );
+}
+
 function StreamErrorBanner({
   error,
   onReconnect,

package/src/session/__tests__/useSessionConversation.test.tsx

@@ -81,6 +81,8 @@ interface MockMethods {
   executionCreate: ReturnType<typeof vi.fn>;
   subscribe: ReturnType<typeof vi.fn>;
   submitApproval: ReturnType<typeof vi.fn>;
+  cancel?: ReturnType<typeof vi.fn>;
+  terminate?: ReturnType<typeof vi.fn>;
 }
 
 function createMockStigmer(methods: MockMethods): Stigmer {
@@ -93,6 +95,8 @@ function createMockStigmer(methods: MockMethods): Stigmer {
       create: methods.executionCreate,
       subscribe: methods.subscribe,
       submitApproval: methods.submitApproval,
+      cancel: methods.cancel,
+      terminate: methods.terminate,
     },
   } as unknown as Stigmer;
 }
@@ -118,6 +122,8 @@ describe("useSessionConversation", () => {
       executionCreate: vi.fn(),
       subscribe: vi.fn().mockReturnValue(stream.generator),
       submitApproval: vi.fn().mockResolvedValue({}),
+      cancel: vi.fn().mockResolvedValue(makeExecution("e1", ExecutionPhase.EXECUTION_CANCELLED)),
+      terminate: vi.fn().mockResolvedValue(makeExecution("e1", ExecutionPhase.EXECUTION_TERMINATED)),
     };
     mockStigmer = createMockStigmer(methods);
   });
@@ -306,6 +312,59 @@ describe("useSessionConversation", () => {
     });
   });
 
+  it("preserves the message and surfaces sendError when the send fails", async () => {
+    methods.listBySession.mockResolvedValue({ entries: [] });
+    methods.executionCreate.mockRejectedValue(new Error("create boom"));
+
+    const { result } = renderHook(
+      () => useSessionConversation("session-1", "org"),
+      { wrapper: createWrapper(mockStigmer) },
+    );
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    await act(async () => {
+      await result.current.sendFollowUp("keep me");
+    });
+
+    // The failure is surfaced and the user's text is NOT lost.
+    expect(result.current.sendError?.message).toBe("create boom");
+    expect(result.current.pendingUserMessage).toBe("keep me");
+  });
+
+  it("retryLastSend resubmits the same message after a failure", async () => {
+    methods.listBySession.mockResolvedValue({ entries: [] });
+    methods.executionCreate.mockRejectedValueOnce(new Error("boom"));
+    const retried = makeExecution("e-retry", ExecutionPhase.EXECUTION_PENDING);
+    retried.metadata!.id = "e-retry";
+    methods.executionCreate.mockResolvedValue(retried);
+
+    const { result } = renderHook(
+      () => useSessionConversation("session-1", "org"),
+      { wrapper: createWrapper(mockStigmer) },
+    );
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    await act(async () => {
+      await result.current.sendFollowUp("retry me");
+    });
+    expect(result.current.sendError).not.toBeNull();
+
+    await act(async () => {
+      result.current.retryLastSend();
+    });
+
+    await waitFor(() =>
+      expect(methods.executionCreate).toHaveBeenCalledTimes(2),
+    );
+    expect(methods.executionCreate).toHaveBeenLastCalledWith(
+      expect.objectContaining({ message: "retry me" }),
+    );
+    // The retry cleared the prior failure for the new attempt.
+    expect(result.current.sendError).toBeNull();
+  });
+
   it("full follow-up lifecycle: active execution completes → canSendFollowUp → sendFollowUp succeeds", async () => {
     // Start with one IN_PROGRESS execution (simulates a Cursor execution running)
     const activeExec = makeExecution("exec-1", ExecutionPhase.EXECUTION_IN_PROGRESS);
@@ -358,6 +417,92 @@ describe("useSessionConversation", () => {
       }),
     );
   });
+
+  it("isStoppable is false when no execution is active", async () => {
+    const completed = makeExecution("e1", ExecutionPhase.EXECUTION_COMPLETED);
+    methods.listBySession.mockResolvedValue({ entries: [completed] });
+
+    const { result } = renderHook(
+      () => useSessionConversation("session-1", "org"),
+      { wrapper: createWrapper(mockStigmer) },
+    );
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+    expect(result.current.isStoppable).toBe(false);
+  });
+
+  it("isStoppable becomes true once the active execution streams IN_PROGRESS", async () => {
+    const active = makeExecution("e1", ExecutionPhase.EXECUTION_IN_PROGRESS);
+    methods.listBySession.mockResolvedValue({ entries: [active] });
+
+    const execStream = createControllableStream<AgentExecution>();
+    methods.subscribe.mockReturnValue(execStream.generator);
+
+    const { result } = renderHook(
+      () => useSessionConversation("session-1", "org"),
+      { wrapper: createWrapper(mockStigmer) },
+    );
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    act(() => {
+      execStream.push(makeExecution("e1", ExecutionPhase.EXECUTION_IN_PROGRESS));
+    });
+
+    await waitFor(() => expect(result.current.isStoppable).toBe(true));
+  });
+
+  it("stop() cancels the active execution, then escalates to terminate on repeat", async () => {
+    const active = makeExecution("e1", ExecutionPhase.EXECUTION_IN_PROGRESS);
+    methods.listBySession.mockResolvedValue({ entries: [active] });
+
+    const execStream = createControllableStream<AgentExecution>();
+    methods.subscribe.mockReturnValue(execStream.generator);
+
+    const { result } = renderHook(
+      () => useSessionConversation("session-1", "org"),
+      { wrapper: createWrapper(mockStigmer) },
+    );
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    act(() => {
+      execStream.push(makeExecution("e1", ExecutionPhase.EXECUTION_IN_PROGRESS));
+    });
+    await waitFor(() => expect(result.current.isStoppable).toBe(true));
+
+    await act(async () => {
+      await result.current.stop("Stop from chat");
+    });
+    expect(methods.cancel).toHaveBeenCalledTimes(1);
+    expect(methods.cancel!.mock.calls[0][0]).toMatchObject({ id: "e1" });
+    expect(methods.terminate).not.toHaveBeenCalled();
+
+    await act(async () => {
+      await result.current.stop("Stop from chat");
+    });
+    expect(methods.cancel).toHaveBeenCalledTimes(1);
+    expect(methods.terminate).toHaveBeenCalledTimes(1);
+  });
+
+  it("stop() is a no-op when nothing is stoppable", async () => {
+    const completed = makeExecution("e1", ExecutionPhase.EXECUTION_COMPLETED);
+    methods.listBySession.mockResolvedValue({ entries: [completed] });
+
+    const { result } = renderHook(
+      () => useSessionConversation("session-1", "org"),
+      { wrapper: createWrapper(mockStigmer) },
+    );
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    await act(async () => {
+      await result.current.stop();
+    });
+
+    expect(methods.cancel).not.toHaveBeenCalled();
+    expect(methods.terminate).not.toHaveBeenCalled();
+  });
 });
 
 describe("useSessionConversation — local runner worker lifecycle", () => {