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

package/src/internal/stream-controller.ts

@@ -1,5 +1,5 @@
 import type { AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
-import type { ConversationStore } from "./store/conversation-store";
+import type { StreamState } from "./store/conversation-store";
 import { isTerminalPhase } from "../execution/execution-phases";
 import { ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 
@@ -7,25 +7,26 @@ import { ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/agentexecutio
 // Types
 // ---------------------------------------------------------------------------
 
-export type ControllerStage =
-  | "idle"
-  | "connecting"
-  | "streaming"
-  | "complete"
-  | "error";
-
-export type ControllerState =
-  | { readonly stage: "idle" }
-  | { readonly stage: "connecting"; readonly executionId: string }
-  | { readonly stage: "streaming"; readonly executionId: string }
-  | { readonly stage: "complete"; readonly executionId: string }
-  | {
-      readonly stage: "error";
-      readonly executionId: string;
-      readonly error: Error;
-    };
-
-const IDLE: ControllerState = { stage: "idle" };
+// The controller's FSM state is exactly the store's `StreamState` — they
+// were once duplicated unions kept in lock-step by hand. The controller
+// reuses the store's type so the lifecycle (including the `reconnecting`
+// stage) is defined in one place and can never drift.
+
+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
@@ -36,7 +37,28 @@ export interface StreamControllerSink {
   /** Ingest a snapshot into the store (applies structural sharing). */
   ingestSnapshot(snapshot: AgentExecution): void;
   /** Transition the store's stream lifecycle state. */
-  setStreamState(state: ControllerState): void;
+  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;
 }
 
 // ---------------------------------------------------------------------------
@@ -58,13 +80,21 @@ export interface StreamControllerSink {
  * (typically `requestAnimationFrame`).
  */
 export class StreamController {
-  private _state: ControllerState = IDLE;
+  private _state: StreamState = IDLE;
   private _bufferedSnapshot: AgentExecution | null = null;
   private _rafId: number | null = null;
   private _sink: StreamControllerSink;
   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"
@@ -73,14 +103,23 @@ 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). */
-  get state(): ControllerState {
+  get state(): StreamState {
     return this._state;
   }
 
@@ -91,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 });
   }
 
@@ -108,12 +152,23 @@ 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 {
-      if (this._state.stage === "connecting") {
+      // 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"
+      ) {
         this._transition({ stage: "streaming", executionId });
       }
       this._bufferedSnapshot = snapshot;
@@ -121,6 +176,25 @@ export class StreamController {
     }
   }
 
+  /**
+   * Enter the `reconnecting` stage after a transient drop. Unlike
+   * {@link start}, this preserves the buffered snapshot and never resets the
+   * store, so the last-known-good conversation stays on screen while the
+   * background retry is in flight. No-op once idle (the subscription is
+   * already torn down).
+   */
+  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 });
+  }
+
   /**
    * Handle stream completion (iterator exhausted without error).
    * If we still have a buffered snapshot, flush it first.
@@ -129,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 });
@@ -143,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") {
@@ -171,7 +251,7 @@ export class StreamController {
     return this._state.executionId;
   }
 
-  private _transition(next: ControllerState): void {
+  private _transition(next: StreamState): void {
     this._state = next;
     this._sink.setStreamState(next);
   }
@@ -198,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

@@ -290,12 +290,24 @@ function ConversationColumn({
   const { conv } = flow;
   const sendError = flow.submitError ?? conv.sendError ?? conv.approvalError;
 
+  // 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],
+  );
+
   return (
     <div className="flex h-full min-w-0 flex-col">
       <MessageThread
         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}
         workspaceEntries={conv.workspaceEntries}
@@ -307,6 +319,11 @@ function ConversationColumn({
         className="flex-1"
       />
       <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}
@@ -546,6 +563,78 @@ function SendErrorBanner({ error }: { error: Error }) {
   );
 }
 
+function ReconnectingIndicator() {
+  return (
+    <div
+      role="status"
+      aria-live="polite"
+      className="flex items-center gap-2 border-t border-border bg-muted px-4 py-2 text-sm text-muted-foreground"
+    >
+      <svg
+        width="14"
+        height="14"
+        viewBox="0 0 24 24"
+        fill="none"
+        stroke="currentColor"
+        strokeWidth="2"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+        className="shrink-0 animate-spin motion-reduce:animate-none"
+        aria-hidden="true"
+      >
+        <path d="M21 12a9 9 0 1 1-6.219-8.56" />
+      </svg>
+      <span className="truncate">Reconnecting…</span>
+    </div>
+  );
+}
+
+/**
+ * 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

@@ -306,6 +306,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);