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

package/src/session/SessionViewer.tsx

@@ -307,6 +307,7 @@ function ConversationColumn({
         className="flex-1"
       />
       <div className="mx-auto w-full max-w-3xl">
+        {conv.isReconnecting && <ReconnectingIndicator />}
         {conv.streamError && (
           <StreamErrorBanner
             error={conv.streamError}
@@ -546,6 +547,32 @@ 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>
+  );
+}
+
 function StreamErrorBanner({
   error,
   onReconnect,

package/src/session/useSessionConversation.ts

@@ -179,7 +179,13 @@ export interface UseSessionConversationReturn {
   /** Error from session or execution list loading, or `null` when healthy. */
   readonly loadError: Error | null;
 
-  /** Error from the execution stream, or `null` when healthy. */
+  /**
+   * `true` while the execution stream is auto-reconnecting after a transient
+   * drop. The conversation stays visible and `streamError` remains `null` —
+   * surface a subtle "Reconnecting…" hint rather than an error banner.
+   */
+  readonly isReconnecting: boolean;
+  /** Error from the execution stream, or `null` when healthy or reconnecting. */
   readonly streamError: Error | null;
   /** Reset the stream error and re-establish the execution stream subscription. */
   readonly reconnectStream: () => void;
@@ -463,6 +469,7 @@ export function useSessionConversation(
     isLoading,
     loadError,
 
+    isReconnecting: stream.isReconnecting,
     streamError: stream.error,
     reconnectStream: stream.reconnect,
   };

package/src/workflow/WorkflowExecutionHeader.tsx

@@ -82,7 +82,10 @@ export const WorkflowExecutionHeader = memo(function WorkflowExecutionHeader({
   const isRunning = RUNNING_PHASES.has(phase);
   const isPaused = phase === ExecutionPhase.EXECUTION_PAUSED;
   const isFailed = phase === ExecutionPhase.EXECUTION_FAILED;
-  const isLive = streamState.stage === "streaming" || streamState.stage === "connecting";
+  const isLive =
+    streamState.stage === "streaming" ||
+    streamState.stage === "connecting" ||
+    streamState.stage === "reconnecting";
 
   return (
     <header className={cn("flex items-center gap-3 border-b border-border px-4 py-3", className)}>

package/src/workflow/WorkflowExecutionTimeline.tsx

@@ -77,7 +77,8 @@ export const WorkflowExecutionTimeline = memo(function WorkflowExecutionTimeline
     }
   }, [events.length]);
 
-  const isLive = streamState.stage === "streaming";
+  const isLive =
+    streamState.stage === "streaming" || streamState.stage === "reconnecting";
   const isConnecting = streamState.stage === "connecting";
   const isComplete = streamState.stage === "complete";
   const isError = streamState.stage === "error";

package/src/workflow/__tests__/useWorkflowExecutionEventStream.test.tsx

@@ -1,5 +1,5 @@
 import { describe, it, expect, vi, beforeEach } from "vitest";
-import { renderHook, act } from "@testing-library/react";
+import { renderHook, act, waitFor } from "@testing-library/react";
 import type { ReactNode } from "react";
 import { createElement } from "react";
 import { create } from "@bufbuild/protobuf";
@@ -417,3 +417,119 @@ describe("useWorkflowExecutionEventStream", () => {
     expect(result.current.events[0]?.taskName).toBe("beta");
   });
 });
+
+// ---------------------------------------------------------------------------
+// Auto-reconnect (#174)
+// ---------------------------------------------------------------------------
+
+describe("useWorkflowExecutionEventStream — auto-reconnect", () => {
+  it("auto-reconnects on a transient drop and resumes from the latest sequence", async () => {
+    let call = 0;
+    const subscribeEvents = vi.fn((_req: any) => {
+      call += 1;
+      if (call === 1) {
+        return (async function* () {
+          yield makeTaskStartedEvent(5, "t5");
+          throw new TypeError("Load failed");
+        })();
+      }
+      return (async function* () {
+        yield makeTaskStartedEvent(6, "t6");
+      })();
+    });
+    const client = makeMockClient({ subscribeEvents });
+
+    const { result } = renderHook(
+      () =>
+        useWorkflowExecutionEventStream("wex-001", {
+          executionPhase: PHASE.IN_PROGRESS,
+          reconnectOptions: { baseDelayMs: 5, maxDelayMs: 5 },
+        }),
+      { wrapper: createWrapper(client) },
+    );
+
+    await waitFor(() => expect(subscribeEvents).toHaveBeenCalledTimes(2));
+    await waitFor(() => expect(result.current.events).toHaveLength(2));
+
+    // The resumed subscription continues after the last received sequence (5),
+    // so no events are lost or duplicated.
+    const secondReq = (subscribeEvents.mock.calls as unknown[][])[1]?.[0] as {
+      afterSequence: bigint;
+    };
+    expect(secondReq.afterSequence).toBe(BigInt(5));
+    expect(result.current.error).toBeNull();
+  });
+
+  it("surfaces an error after exhausting reconnect attempts", async () => {
+    const subscribeEvents = vi.fn(
+      () =>
+        (async function* () {
+          throw new TypeError("Load failed");
+        })(),
+    );
+    const client = makeMockClient({ subscribeEvents });
+
+    const { result } = renderHook(
+      () =>
+        useWorkflowExecutionEventStream("wex-001", {
+          executionPhase: PHASE.IN_PROGRESS,
+          reconnectOptions: { baseDelayMs: 1, maxDelayMs: 1, maxAttempts: 2 },
+        }),
+      { wrapper: createWrapper(client) },
+    );
+
+    await waitFor(() => expect(result.current.error).not.toBeNull(), {
+      timeout: 2000,
+    });
+    expect(result.current.streamState.stage).toBe("error");
+    // 1 initial attempt + 2 retries.
+    expect(subscribeEvents).toHaveBeenCalledTimes(3);
+  });
+
+  it("marks unsupported on UNIMPLEMENTED without retrying", async () => {
+    const subscribeEvents = vi.fn(
+      () =>
+        (async function* () {
+          throw new Error("UNIMPLEMENTED: event streaming not supported");
+        })(),
+    );
+    const client = makeMockClient({ subscribeEvents });
+
+    const { result } = renderHook(
+      () =>
+        useWorkflowExecutionEventStream("wex-001", {
+          executionPhase: PHASE.IN_PROGRESS,
+          reconnectOptions: { baseDelayMs: 1, maxDelayMs: 1 },
+        }),
+      { wrapper: createWrapper(client) },
+    );
+
+    await waitFor(() =>
+      expect(result.current.streamState.stage).toBe("unsupported"),
+    );
+    await new Promise((r) => setTimeout(r, 20));
+    expect(subscribeEvents).toHaveBeenCalledTimes(1);
+  });
+
+  it("treats a clean stream end as completion (never a reconnect loop)", async () => {
+    const subscribeEvents = vi.fn(async function* () {
+      /* no events, then clean end */
+    });
+    const client = makeMockClient({ subscribeEvents });
+
+    const { result } = renderHook(
+      () =>
+        useWorkflowExecutionEventStream("wex-001", {
+          executionPhase: PHASE.IN_PROGRESS,
+          reconnectOptions: { baseDelayMs: 1, maxDelayMs: 1 },
+        }),
+      { wrapper: createWrapper(client) },
+    );
+
+    await waitFor(() =>
+      expect(result.current.streamState.stage).toBe("complete"),
+    );
+    await new Promise((r) => setTimeout(r, 20));
+    expect(subscribeEvents).toHaveBeenCalledTimes(1);
+  });
+});

package/src/workflow/execution/useWaterfallEntries.ts

@@ -61,7 +61,8 @@ export function useWaterfallEntries({
   executionStartIso,
   executionDurationMs,
 }: UseWaterfallEntriesOptions): UseWaterfallEntriesReturn {
-  const isLive = streamState.stage === "streaming";
+  const isLive =
+    streamState.stage === "streaming" || streamState.stage === "reconnecting";
   const execStartEpoch = useMemo(
     () => (executionStartIso ? new Date(executionStartIso).getTime() : 0),
     [executionStartIso],

package/src/workflow/useWorkflowExecutionEventStream.ts

@@ -16,8 +16,15 @@ import {
   SubscribeEventsRequestSchema,
 } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/io_pb";
 import { ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/enum_pb";
+import { isTransientStreamError } from "@stigmer/sdk";
 import { useStigmer } from "../hooks";
 import { toError } from "../internal/toError";
+import {
+  computeBackoffDelay,
+  sleep,
+  DEFAULT_RECONNECT_MAX_ATTEMPTS,
+  type BackoffOptions,
+} from "../internal/backoff";
 import {
   WorkflowExecutionEventStore,
   type WorkflowEventStreamState,
@@ -41,6 +48,20 @@ export interface UseWorkflowExecutionEventStreamOptions {
    * (terminal). When omitted, defaults to live streaming.
    */
   readonly executionPhase?: ExecutionPhase;
+  /**
+   * Automatically re-establish the live subscription with exponential
+   * backoff when it drops with a transient transport error, resuming from
+   * the last received `sequence_number` (no events lost). Defaults to `true`.
+   */
+  readonly autoReconnect?: boolean;
+  /**
+   * Tune the auto-reconnect backoff schedule and attempt cap. Omitted fields
+   * fall back to SDK defaults (base 1s, ×2, max 30s, 10 attempts).
+   */
+  readonly reconnectOptions?: BackoffOptions & {
+    /** Max attempts before surfacing a terminal `error`. */
+    readonly maxAttempts?: number;
+  };
 }
 
 /** Return value of {@link useWorkflowExecutionEventStream}. */
@@ -59,9 +80,20 @@ export interface UseWorkflowExecutionEventStreamReturn {
   readonly isStreaming: boolean;
   /** `true` while connecting to the event stream. */
   readonly isConnecting: boolean;
-  /** Error from the last failed stream attempt, or `null`. */
+  /**
+   * `true` while a transient drop is being retried automatically. Accumulated
+   * events stay visible and `error` remains `null`; on success the
+   * subscription resumes from the last sequence number with no events lost.
+   */
+  readonly isReconnecting: boolean;
+  /** 1-based count of the in-flight reconnect attempt; `0` when not reconnecting. */
+  readonly reconnectAttempt: number;
+  /**
+   * Error from the last failed stream attempt, or `null`. Set only once
+   * auto-reconnect exhausts its attempts (or for a non-transient failure).
+   */
   readonly error: Error | null;
-  /** Re-establish the stream subscription. */
+  /** Re-establish the stream subscription (manual fallback). */
   readonly reconnect: () => void;
 }
 
@@ -99,8 +131,10 @@ export function isRecoveryTransition(
  * integration.
  *
  * For running executions: subscribes via `subscribeEvents` with
- * replay+live-tail. On disconnect, reconnects from the last received
- * sequence number.
+ * replay+live-tail. A transient drop auto-reconnects with exponential
+ * backoff, resuming from the last received sequence number so no events are
+ * lost; `error` is surfaced only once retries are exhausted. A clean stream
+ * end is the server's completion signal and is never retried.
  *
  * For terminal executions: loads the full event log via paginated
  * `getEventLog` calls.
@@ -136,6 +170,8 @@ export function useWorkflowExecutionEventStream(
 
   const eventTypes = options?.eventTypes;
   const executionPhase = options?.executionPhase;
+  const autoReconnect = options?.autoReconnect ?? true;
+  const reconnectOptions = options?.reconnectOptions;
 
   // Stable ref for values that should not trigger re-subscription
   const storeRef = useRef(store);
@@ -239,50 +275,90 @@ export function useWorkflowExecutionEventStream(
         }
       })();
     } else {
-      // Live-stream events for running executions
+      // Live-stream events for running executions, with auto-reconnect.
       currentStore.setStreamState({ stage: "connecting", executionId });
 
       (async () => {
-        try {
-          const afterSequence = currentStore.getLatestSequence();
-
-          for await (const event of stigmer.workflowExecution.subscribeEvents(
-            create(SubscribeEventsRequestSchema, {
-              executionId,
-              afterSequence,
-              eventTypes: eventTypes ? [...eventTypes] : [],
-            }),
-            abortController.signal,
-          )) {
-            if (abortController.signal.aborted) return;
-
-            startTransition(() => {
-              currentStore.appendEvents([event]);
-              if (currentStore.getStreamState().stage === "connecting") {
-                currentStore.setStreamState({ stage: "streaming", executionId });
-              }
-            });
-          }
-
-          if (!abortController.signal.aborted) {
-            currentStore.setStreamState({ stage: "complete", executionId });
-          }
-        } catch (err) {
-          if (abortController.signal.aborted) return;
-
-          const error = toError(err);
-          const isUnimplemented =
-            error.message.includes("UNIMPLEMENTED") ||
-            error.message.includes("unimplemented");
-
-          if (isUnimplemented) {
-            currentStore.setStreamState({ stage: "unsupported", executionId });
-          } else {
+        const signal = abortController.signal;
+        const maxAttempts =
+          reconnectOptions?.maxAttempts ?? DEFAULT_RECONNECT_MAX_ATTEMPTS;
+
+        // 1-based count of consecutive failed attempts, reset by any event.
+        let attempt = 0;
+
+        while (!signal.aborted) {
+          try {
+            // Re-read each attempt: after a drop we resume from the last
+            // sequence number, so the server replays only what we missed and
+            // no events are lost or duplicated.
+            const afterSequence = currentStore.getLatestSequence();
+
+            for await (const event of stigmer.workflowExecution.subscribeEvents(
+              create(SubscribeEventsRequestSchema, {
+                executionId,
+                afterSequence,
+                eventTypes: eventTypes ? [...eventTypes] : [],
+              }),
+              signal,
+            )) {
+              if (signal.aborted) return;
+
+              attempt = 0; // an event proves the connection is healthy
+              startTransition(() => {
+                currentStore.appendEvents([event]);
+                const stage = currentStore.getStreamState().stage;
+                if (stage === "connecting" || stage === "reconnecting") {
+                  currentStore.setStreamState({ stage: "streaming", executionId });
+                }
+              });
+            }
+
+            // A clean end of the event stream is the server's completion
+            // signal (the execution finished). Unlike the agent snapshot
+            // stream, there is no separate terminal marker to re-check, so we
+            // must NOT treat this as a premature drop — doing so would loop
+            // forever re-subscribing past the final sequence. Transient drops
+            // surface as thrown errors (handled below), not a clean end.
+            if (!signal.aborted) {
+              currentStore.setStreamState({ stage: "complete", executionId });
+            }
+            return;
+          } catch (err) {
+            if (signal.aborted) return;
+
+            const error = toError(err);
+            const isUnimplemented =
+              error.message.includes("UNIMPLEMENTED") ||
+              error.message.includes("unimplemented");
+
+            // A server without event-stream support will never recover —
+            // surface the unsupported state immediately, never retry.
+            if (isUnimplemented) {
+              currentStore.setStreamState({ stage: "unsupported", executionId });
+              return;
+            }
+
+            if (
+              !autoReconnect ||
+              !isTransientStreamError(error) ||
+              attempt >= maxAttempts
+            ) {
+              currentStore.setStreamState({ stage: "error", executionId, error });
+              return;
+            }
+
+            attempt += 1;
             currentStore.setStreamState({
-              stage: "error",
+              stage: "reconnecting",
               executionId,
+              attempt,
               error,
             });
+            try {
+              await sleep(computeBackoffDelay(attempt, reconnectOptions), signal);
+            } catch {
+              return; // aborted mid-backoff
+            }
           }
         }
       })();
@@ -302,6 +378,9 @@ export function useWorkflowExecutionEventStream(
 
   const isStreaming = streamState.stage === "streaming";
   const isConnecting = streamState.stage === "connecting";
+  const isReconnecting = streamState.stage === "reconnecting";
+  const reconnectAttempt =
+    streamState.stage === "reconnecting" ? streamState.attempt : 0;
   const error = streamState.stage === "error" ? streamState.error : null;
 
   return {
@@ -312,6 +391,8 @@ export function useWorkflowExecutionEventStream(
     totalTasks,
     isStreaming,
     isConnecting,
+    isReconnecting,
+    reconnectAttempt,
     error,
     reconnect,
   };

package/src/workflow/waterfall/WaterfallTimeline.tsx

@@ -89,7 +89,8 @@ export const WaterfallTimeline = memo(function WaterfallTimeline({
 
   // Empty state
   if (entries.length === 0) {
-    const isConnecting = streamState.stage === "connecting";
+    const isConnecting =
+      streamState.stage === "connecting" || streamState.stage === "reconnecting";
     return (
       <div className={cn("flex items-center justify-center text-xs text-[var(--stgm-muted-foreground,#737373)]", className)}>
         {isConnecting ? "Loading timeline…" : "No task data available"}