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

package/src/execution/useExecutionStream.ts

@@ -11,6 +11,7 @@ import {
 } from "react";
 import type { AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
 import { ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { isTransientStreamError } from "@stigmer/sdk";
 import { useStigmer } from "../hooks";
 import { toError } from "../internal/toError";
 import { useStreamRate } from "../internal/dev";
@@ -18,7 +19,13 @@ import {
   StreamController,
   type StreamControllerSink,
 } from "../internal/stream-controller";
-import { ConversationStore, type StreamState } from "../internal/store";
+import {
+  computeBackoffDelay,
+  sleep,
+  DEFAULT_RECONNECT_MAX_ATTEMPTS,
+  type BackoffOptions,
+} from "../internal/backoff";
+import { ConversationStore } from "../internal/store";
 import { isTerminalPhase } from "./execution-phases";
 
 /** Return value of {@link useExecutionStream}. */
@@ -37,14 +44,31 @@ export interface UseExecutionStreamReturn {
   readonly isStreaming: boolean;
   /** `true` after subscription starts but before the first snapshot arrives. */
   readonly isConnecting: boolean;
-  /** Error from the last failed stream attempt, or `null` when healthy. */
+  /**
+   * `true` while a transient drop is being retried automatically in the
+   * background. The last snapshot stays visible and `error` remains `null` —
+   * surface a subtle "Reconnecting…" affordance, not an error. Becomes
+   * `false` once a snapshot is received (back to `isStreaming`) or retries
+   * are exhausted (then `error` is set).
+   */
+  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` when healthy.
+   *
+   * Only set once auto-reconnect has exhausted its attempts (or for a
+   * non-transient failure that is not retried). It stays `null` throughout
+   * background reconnection so a recoverable hiccup never shows as an error.
+   */
   readonly error: Error | null;
   /**
    * Reset error state and re-establish the stream subscription.
    *
-   * Works in any lifecycle state — error, complete, or mid-stream.
-   * Uses the `connectKey` counter pattern consistent with `refetch()`
-   * in other SDK hooks.
+   * The fallback after auto-reconnect exhausts, and a manual escape hatch in
+   * any lifecycle state — error, complete, or mid-stream. Resets the retry
+   * counter and preserves the last snapshot (no flash to empty). Uses the
+   * `connectKey` counter pattern consistent with `refetch()` in other SDK hooks.
    */
   readonly reconnect: () => void;
 }
@@ -65,6 +89,21 @@ export interface UseExecutionStreamOptions {
    * preserving backward compatibility for standalone usage.
    */
   readonly store?: ConversationStore;
+  /**
+   * Automatically re-establish the subscription with exponential backoff
+   * when a non-terminal stream drops (transport error, idle timeout, laptop
+   * sleep). Defaults to `true`. Set `false` to opt out and surface every
+   * drop as an immediate `error` for manual `reconnect()`.
+   */
+  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;
+  };
 }
 
 /**
@@ -73,7 +112,18 @@ export interface UseExecutionStreamOptions {
  *
  * Manages the full subscription lifecycle through a finite state
  * machine: connection establishment, rAF-coalesced snapshot streaming,
- * terminal-phase detection, error handling, and manual reconnection.
+ * terminal-phase detection, automatic reconnection with exponential
+ * backoff on transient drops, and manual reconnection as the fallback.
+ *
+ * **Resilience:** a non-terminal stream drop — whether a thrown transport
+ * error (WebKit "Load failed", `fetch failed`, `Unavailable`) or a graceful
+ * server close mid-run (idle timeout, load-balancer recycle) — is retried
+ * automatically with backoff. The last snapshot stays visible
+ * (`isReconnecting`), the access token is re-read on each attempt via the
+ * per-request interceptor, and `error` is surfaced only once attempts are
+ * exhausted. Completion is decided by the terminal phase, never by the
+ * stream merely ending (a graceful close of a running execution reconnects
+ * rather than falsely reporting "complete"). Opt out via `autoReconnect: false`.
  *
  * **Performance characteristics:**
  * - Non-terminal snapshots are coalesced via `requestAnimationFrame`
@@ -152,6 +202,17 @@ export function useExecutionStream(
   const streamRateRef = useRef(streamRate);
   streamRateRef.current = streamRate;
 
+  // -- Reconnect config (ref-backed so option identity churn never resubscribes)
+  const autoReconnect = options?.autoReconnect ?? true;
+  const reconnectOptions = options?.reconnectOptions;
+  const configRef = useRef({ autoReconnect, reconnectOptions });
+  configRef.current = { autoReconnect, reconnectOptions };
+
+  // Tracks the execution the store currently holds, so we reset the store on
+  // a genuine identity change (A → B) but preserve it across reconnects of the
+  // SAME execution. Mirrors useWorkflowExecutionEventStream / useFetch.
+  const prevExecutionIdRef = useRef<string | null>(null);
+
   // -- Subscription effect --------------------------------------------------
   // Note: controller, store, and streamRate are ref-backed stable objects —
   // they MUST NOT appear in the deps array. Including them would cause
@@ -160,45 +221,117 @@ export function useExecutionStream(
     if (!executionId) {
       controller.reset();
       store.reset();
+      prevExecutionIdRef.current = null;
       return;
     }
 
+    // Reset only when switching to a different execution. Crucially we do NOT
+    // reset the store on reconnect (connectKey bump) or on cleanup — that
+    // would wipe the conversation to an empty "Connecting…" on every retry.
+    // The full-snapshot subscribe re-delivers the entire state on reconnect,
+    // so keeping the last-known-good snapshot is both correct and seamless.
+    if (
+      prevExecutionIdRef.current !== null &&
+      prevExecutionIdRef.current !== executionId
+    ) {
+      store.reset();
+    }
+    prevExecutionIdRef.current = executionId;
+
     const abortController = new AbortController();
+    const signal = abortController.signal;
     controller.start(executionId);
 
     (async () => {
-      try {
-        for await (const snapshot of stigmer.agentExecution.subscribe(
-          executionId,
-          abortController.signal,
-        )) {
-          if (abortController.signal.aborted) return;
-
-          controller.handleSnapshot(snapshot);
-          streamRateRef.current.tick(
-            snapshot.status?.messages?.length ?? 0,
-          );
-
-          const phase =
-            snapshot.status?.phase ??
-            ExecutionPhase.EXECUTION_PHASE_UNSPECIFIED;
-          if (isTerminalPhase(phase)) break;
+      const { autoReconnect: auto, reconnectOptions: backoff } =
+        configRef.current;
+      const maxAttempts = backoff?.maxAttempts ?? DEFAULT_RECONNECT_MAX_ATTEMPTS;
+
+      // 1-based count of consecutive failed attempts. Reset to 0 by any
+      // successful snapshot, so each healthy stretch gets a fresh backoff
+      // budget rather than inheriting the previous outage's attempt count.
+      let attempt = 0;
+
+      // Schedule the next retry after `error`, or stop. Returns `true` when
+      // the loop should continue (a retry was scheduled), `false` when it
+      // should exit (opted out, exhausted, or aborted). Shared by the
+      // thrown-error and premature-end paths so both converge on one policy.
+      const scheduleRetry = async (error: Error): Promise<boolean> => {
+        if (!auto || attempt >= maxAttempts) {
+          controller.handleError(error);
+          return false;
         }
+        attempt += 1;
+        controller.handleReconnecting(attempt, error);
+        try {
+          await sleep(computeBackoffDelay(attempt, backoff), signal);
+        } catch {
+          return false; // aborted mid-backoff
+        }
+        return !signal.aborted;
+      };
+
+      while (!signal.aborted) {
+        let sawTerminal = false;
+        try {
+          for await (const snapshot of stigmer.agentExecution.subscribe(
+            executionId,
+            signal,
+          )) {
+            if (signal.aborted) return;
+
+            attempt = 0; // a snapshot proves the connection is healthy
+            controller.handleSnapshot(snapshot);
+            streamRateRef.current.tick(snapshot.status?.messages?.length ?? 0);
 
-        if (!abortController.signal.aborted) {
+            const phase =
+              snapshot.status?.phase ??
+              ExecutionPhase.EXECUTION_PHASE_UNSPECIFIED;
+            if (isTerminalPhase(phase)) {
+              sawTerminal = true;
+              break;
+            }
+          }
+        } catch (err) {
+          if (signal.aborted) return;
+          const error = toError(err);
+          // Only known-transient transport noise is retried. A non-transient
+          // error (not-found, invalid-argument, …) is deterministic — the
+          // same request would fail identically, so surface it immediately.
+          if (!auto || !isTransientStreamError(error)) {
+            controller.handleError(error);
+            return;
+          }
+          if (await scheduleRetry(error)) continue;
+          return;
+        }
+
+        if (signal.aborted) return;
+
+        if (sawTerminal) {
+          // handleSnapshot already transitioned to `complete`; flush any
+          // buffered frame and finish. Completion is decided by the terminal
+          // phase, never by the stream merely ending.
           controller.handleStreamEnd();
           streamRateRef.current.summary();
+          return;
         }
-      } catch (err) {
-        if (abortController.signal.aborted) return;
-        controller.handleError(toError(err));
+
+        // The iterator finished without a terminal phase: the server closed a
+        // still-running stream (idle timeout, load-balancer recycle, pod
+        // restart). This is transient by definition — reconnect and the next
+        // full snapshot reconciles whatever changed (including, if it ended
+        // meanwhile, the terminal state we missed).
+        if (await scheduleRetry(new Error("The connection was interrupted."))) {
+          continue;
+        }
+        return;
       }
     })();
 
     return () => {
       abortController.abort();
       controller.reset();
-      store.reset();
     };
   }, [executionId, stigmer, connectKey]);
 
@@ -218,8 +351,19 @@ export function useExecutionStream(
 
   const isStreaming = streamState.stage === "streaming";
   const isConnecting = streamState.stage === "connecting";
-  const error =
-    streamState.stage === "error" ? streamState.error : null;
+  const isReconnecting = streamState.stage === "reconnecting";
+  const reconnectAttempt =
+    streamState.stage === "reconnecting" ? streamState.attempt : 0;
+  const error = streamState.stage === "error" ? streamState.error : null;
 
-  return { execution, phase, isStreaming, isConnecting, error, reconnect };
+  return {
+    execution,
+    phase,
+    isStreaming,
+    isConnecting,
+    isReconnecting,
+    reconnectAttempt,
+    error,
+    reconnect,
+  };
 }

package/src/internal/__tests__/backoff.test.ts

@@ -0,0 +1,99 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import {
+  computeBackoffDelay,
+  sleep,
+  AbortError,
+  DEFAULT_RECONNECT_BASE_DELAY_MS,
+  DEFAULT_RECONNECT_MAX_DELAY_MS,
+} from "../backoff";
+
+describe("computeBackoffDelay", () => {
+  // random=()=>1 collapses full jitter to its upper bound, exposing the raw
+  // exponential schedule for exact assertions.
+  const noJitter = () => 1;
+
+  it("grows exponentially from the base delay", () => {
+    expect(computeBackoffDelay(1, undefined, noJitter)).toBe(
+      DEFAULT_RECONNECT_BASE_DELAY_MS,
+    );
+    expect(computeBackoffDelay(2, undefined, noJitter)).toBe(2_000);
+    expect(computeBackoffDelay(3, undefined, noJitter)).toBe(4_000);
+    expect(computeBackoffDelay(5, undefined, noJitter)).toBe(16_000);
+  });
+
+  it("caps at maxDelayMs", () => {
+    // attempt 6 → 32_000 raw, clamped to the 30_000 ceiling.
+    expect(computeBackoffDelay(6, undefined, noJitter)).toBe(
+      DEFAULT_RECONNECT_MAX_DELAY_MS,
+    );
+    expect(computeBackoffDelay(50, undefined, noJitter)).toBe(
+      DEFAULT_RECONNECT_MAX_DELAY_MS,
+    );
+  });
+
+  it("applies full jitter within [0, capped]", () => {
+    expect(computeBackoffDelay(3, undefined, () => 0)).toBe(0);
+    expect(computeBackoffDelay(3, undefined, () => 0.5)).toBe(2_000);
+    for (let i = 0; i < 200; i++) {
+      const d = computeBackoffDelay(4); // real Math.random
+      expect(d).toBeGreaterThanOrEqual(0);
+      expect(d).toBeLessThanOrEqual(8_000);
+    }
+  });
+
+  it("honors custom options", () => {
+    const opts = { baseDelayMs: 100, factor: 3, maxDelayMs: 1_000 };
+    expect(computeBackoffDelay(1, opts, noJitter)).toBe(100);
+    expect(computeBackoffDelay(2, opts, noJitter)).toBe(300);
+    expect(computeBackoffDelay(3, opts, noJitter)).toBe(900);
+    expect(computeBackoffDelay(4, opts, noJitter)).toBe(1_000); // 2700 capped
+  });
+
+  it("treats attempt < 1 as the first attempt", () => {
+    expect(computeBackoffDelay(0, undefined, noJitter)).toBe(
+      DEFAULT_RECONNECT_BASE_DELAY_MS,
+    );
+    expect(computeBackoffDelay(-5, undefined, noJitter)).toBe(
+      DEFAULT_RECONNECT_BASE_DELAY_MS,
+    );
+  });
+});
+
+describe("sleep", () => {
+  beforeEach(() => vi.useFakeTimers());
+  afterEach(() => vi.useRealTimers());
+
+  it("resolves after the delay", async () => {
+    const settled = vi.fn();
+    const p = sleep(1_000).then(settled);
+    await vi.advanceTimersByTimeAsync(999);
+    expect(settled).not.toHaveBeenCalled();
+    await vi.advanceTimersByTimeAsync(1);
+    await p;
+    expect(settled).toHaveBeenCalledOnce();
+  });
+
+  it("rejects immediately with AbortError when the signal is already aborted", async () => {
+    const ac = new AbortController();
+    ac.abort();
+    await expect(sleep(1_000, ac.signal)).rejects.toBeInstanceOf(AbortError);
+  });
+
+  it("rejects when aborted mid-wait and leaves no pending timer", async () => {
+    const ac = new AbortController();
+    const p = sleep(10_000, ac.signal);
+    ac.abort();
+    await expect(p).rejects.toBeInstanceOf(AbortError);
+    // No timer should survive the abort — advancing time settles nothing.
+    expect(vi.getTimerCount()).toBe(0);
+  });
+
+  it("does not reject after resolving (listener removed on success)", async () => {
+    const ac = new AbortController();
+    const p = sleep(500, ac.signal);
+    await vi.advanceTimersByTimeAsync(500);
+    await expect(p).resolves.toBeUndefined();
+    // Aborting after the fact must not produce an unhandled rejection.
+    expect(() => ac.abort()).not.toThrow();
+  });
+});

package/src/internal/backoff.ts

@@ -0,0 +1,100 @@
+/**
+ * Exponential-backoff scheduling for resilient stream reconnection.
+ *
+ * Pure and framework-agnostic — the timing math is a plain function and the
+ * wait is a cancelable promise, so both are exhaustively unit-testable
+ * without React or fake DOM (mirrors the codebase's extract-the-pure-core
+ * convention, e.g. `computeFollowCenter` / `isRecoveryTransition`).
+ *
+ * @internal Not part of the public `@stigmer/react` API.
+ */
+
+/** Tunable backoff schedule. All fields optional — sensible defaults apply. */
+export interface BackoffOptions {
+  /** Delay before the first retry, in milliseconds. */
+  readonly baseDelayMs?: number;
+  /** Upper bound on any single delay, in milliseconds. */
+  readonly maxDelayMs?: number;
+  /** Multiplier applied per attempt (`base * factor^(attempt-1)`). */
+  readonly factor?: number;
+}
+
+/** Delay before the first reconnect attempt. */
+export const DEFAULT_RECONNECT_BASE_DELAY_MS = 1_000;
+/** Ceiling for any single reconnect delay. */
+export const DEFAULT_RECONNECT_MAX_DELAY_MS = 30_000;
+/** Per-attempt growth multiplier. */
+export const DEFAULT_RECONNECT_FACTOR = 2;
+/**
+ * Attempts before giving up and surfacing a terminal error. With the
+ * defaults above this is ≈ several minutes of outage before the user sees
+ * an error banner — long enough to ride out sleep/wake and network blips,
+ * bounded enough to avoid an unbounded background loop against a stream
+ * that will never recover (e.g. a deleted execution).
+ */
+export const DEFAULT_RECONNECT_MAX_ATTEMPTS = 10;
+
+/**
+ * Compute the backoff delay (ms) for a 1-based reconnect attempt.
+ *
+ * Exponential growth (`base * factor^(attempt-1)`) capped at `maxDelayMs`,
+ * then **full jitter** — a uniform random point in `[0, capped]`. Full
+ * jitter (AWS, "Exponential Backoff And Jitter") de-synchronizes a fleet of
+ * clients that all dropped at the same instant, preventing a reconnect
+ * thundering herd against a recovering server.
+ *
+ * `random` is injectable purely so tests can assert exact values; callers
+ * should omit it.
+ */
+export function computeBackoffDelay(
+  attempt: number,
+  opts?: BackoffOptions,
+  random: () => number = Math.random,
+): number {
+  const base = opts?.baseDelayMs ?? DEFAULT_RECONNECT_BASE_DELAY_MS;
+  const max = opts?.maxDelayMs ?? DEFAULT_RECONNECT_MAX_DELAY_MS;
+  const factor = opts?.factor ?? DEFAULT_RECONNECT_FACTOR;
+
+  const safeAttempt = Math.max(1, Math.floor(attempt));
+  const exponential = base * factor ** (safeAttempt - 1);
+  const capped = Math.min(exponential, max);
+  return Math.round(random() * capped);
+}
+
+/** Rejection reason for an aborted {@link sleep}, distinguishable by name. */
+export class AbortError extends Error {
+  constructor() {
+    super("The operation was aborted.");
+    this.name = "AbortError";
+  }
+}
+
+/**
+ * Promise-based delay that settles after `ms`, or rejects immediately with
+ * {@link AbortError} if `signal` is (or becomes) aborted.
+ *
+ * The timer is cleared and the abort listener removed on every exit path, so
+ * a reconnect wait leaves nothing pending when a component unmounts or the
+ * subscription is torn down mid-backoff — no leaked timer, no resubscribe
+ * after teardown.
+ */
+export function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise<void>((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(new AbortError());
+      return;
+    }
+
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(new AbortError());
+    };
+
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}

package/src/internal/store/conversation-store.ts

@@ -9,6 +9,19 @@ export type StreamState =
   | { readonly stage: "idle" }
   | { readonly stage: "connecting"; readonly executionId: string }
   | { readonly stage: "streaming"; readonly executionId: string }
+  | {
+      /**
+       * A non-terminal stream drop is being retried in the background. The
+       * last-known-good snapshot stays visible and no error is surfaced —
+       * the public `error` only appears once retries are exhausted. `attempt`
+       * is the 1-based retry count; `error` is the transient cause, retained
+       * for diagnostics (it is not shown to the user while reconnecting).
+       */
+      readonly stage: "reconnecting";
+      readonly executionId: string;
+      readonly attempt: number;
+      readonly error: Error;
+    }
   | { readonly stage: "complete"; readonly executionId: string }
   | {
       readonly stage: "error";
@@ -122,6 +135,15 @@ function streamStateEqual(a: StreamState, b: StreamState): boolean {
     a.error === b.error
   )
     return true;
+  // Each retry bumps `attempt`, so two reconnecting states are only equal
+  // when the attempt matches — every attempt must re-notify subscribers.
+  if (
+    a.stage === "reconnecting" &&
+    b.stage === "reconnecting" &&
+    a.executionId === b.executionId &&
+    a.attempt === b.attempt
+  )
+    return true;
   if ("executionId" in a && "executionId" in b)
     return a.executionId === b.executionId;
   return false;

package/src/internal/store/workflow-execution-event-store.ts

@@ -10,6 +10,19 @@ export type WorkflowEventStreamState =
   | { readonly stage: "idle" }
   | { readonly stage: "connecting"; readonly executionId: string }
   | { readonly stage: "streaming"; readonly executionId: string }
+  | {
+      /**
+       * A non-terminal event stream drop is being retried in the background.
+       * Accumulated events stay visible and no error is surfaced until retries
+       * are exhausted. On reconnect the subscription resumes from the last
+       * received `sequence_number`, so no events are lost. `attempt` is the
+       * 1-based retry count; `error` is the transient cause (diagnostic only).
+       */
+      readonly stage: "reconnecting";
+      readonly executionId: string;
+      readonly attempt: number;
+      readonly error: Error;
+    }
   | { readonly stage: "complete"; readonly executionId: string }
   | {
       readonly stage: "error";
@@ -422,6 +435,15 @@ function streamStateEqual(
     a.error === b.error
   )
     return true;
+  // Each retry bumps `attempt`, so two reconnecting states are only equal
+  // when the attempt matches — every attempt must re-notify subscribers.
+  if (
+    a.stage === "reconnecting" &&
+    b.stage === "reconnecting" &&
+    a.executionId === b.executionId &&
+    a.attempt === b.attempt
+  )
+    return true;
   if ("executionId" in a && "executionId" in b)
     return a.executionId === b.executionId;
   return false;

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,12 @@ 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" };
 
 /**
  * Callback interface for the stream controller to communicate with
@@ -36,7 +23,7 @@ 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;
 }
 
 // ---------------------------------------------------------------------------
@@ -58,7 +45,7 @@ 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;
@@ -80,7 +67,7 @@ export class StreamController {
   }
 
   /** Current FSM state (read-only). */
-  get state(): ControllerState {
+  get state(): StreamState {
     return this._state;
   }
 
@@ -113,7 +100,12 @@ export class StreamController {
       this._sink.ingestSnapshot(snapshot);
       this._transition({ stage: "complete", executionId });
     } else {
-      if (this._state.stage === "connecting") {
+      // A snapshot proves the (re)connection is healthy: 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 +113,19 @@ 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;
+    this._transition({ stage: "reconnecting", executionId, attempt, error });
+  }
+
   /**
    * Handle stream completion (iterator exhausted without error).
    * If we still have a buffered snapshot, flush it first.
@@ -171,7 +176,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);
   }