Skip to content

A desktop coding agent with free access to frontier models.

TypeScript
6.1 KB
Raw Blame
/**
 * Generation-aware reconnect lifecycle for the workspace event stream.
 *
 * The stream must never park in a terminal dead state: 401/403/404 from the
 * subscribe call can mean a permanently invalid token, but the same statuses
 * occur transiently while the local server restarts or the runtime generation
 * rotates. Auth-shaped failures therefore keep retrying on a slower bounded
 * exponential schedule, and `notifyGenerationChanged` (a rotated token or a
 * new runtime generation) restarts a parked stream immediately with fresh
 * backoff instead of waiting out stale failure evidence.
 *
 * This module is dependency-free on purpose so specs can drive it directly.
 */

export type SyncStreamPhase =
  | "connecting"
  | "live"
  | "reconnecting"
  | "auth-blocked"
  | "stale";

type SyncStreamLifecycleOptions = {
  subscribe: (signal: AbortSignal) => Promise<AsyncIterable<unknown>>;
  onEvent: (event: unknown) => void;
  /**
   * Runs on every successful (re)connect, before events flow. Owners
   * level-reconcile active run statuses here so a cached idle recorded while
   * the stream was down cannot mask work that continued on the server.
   */
  onConnected?: (signal: AbortSignal) => void;
  onPhaseChange?: (phase: SyncStreamPhase) => void;
  isAuthError?: (error: unknown) => boolean;
  retryInitialDelayMs?: number;
  retryMaxDelayMs?: number;
  authRetryInitialDelayMs?: number;
  authRetryMaxDelayMs?: number;
  staleStreamMs?: number;
  watchdogIntervalMs?: number;
};

export type SyncStreamLifecycle = {
  /**
   * The credential or runtime generation behind `subscribe` changed. Resets
   * both backoff schedules and, when no healthy connection exists, reconnects
   * immediately. A healthy stream keeps flowing: if the server cuts it over
   * the rotation, the ordinary retry path reconnects with the new generation.
   */
  notifyGenerationChanged: () => void;
  getPhase: () => SyncStreamPhase;
  dispose: () => void;
};

export function startSyncStreamLifecycle(options: SyncStreamLifecycleOptions): SyncStreamLifecycle {
  const retryInitialDelayMs = options.retryInitialDelayMs ?? 1_000;
  const retryMaxDelayMs = options.retryMaxDelayMs ?? 10_000;
  const authRetryInitialDelayMs = options.authRetryInitialDelayMs ?? 5_000;
  const authRetryMaxDelayMs = options.authRetryMaxDelayMs ?? 60_000;
  const staleStreamMs = options.staleStreamMs ?? 30_000;
  const watchdogIntervalMs = options.watchdogIntervalMs ?? 10_000;
  const isAuthError = options.isAuthError ?? (() => false);

  const controller = new AbortController();
  let disposed = false;
  let retryTimer: ReturnType<typeof setTimeout> | null = null;
  let activeConnectionController: AbortController | null = null;
  let lastEventAt = Date.now();
  let retryDelayMs = retryInitialDelayMs;
  let authRetryDelayMs = authRetryInitialDelayMs;
  let generation = 0;
  let phase: SyncStreamPhase = "connecting";

  const setPhase = (next: SyncStreamPhase) => {
    if (phase === next) return;
    phase = next;
    options.onPhaseChange?.(next);
  };

  const scheduleRetry = (reason: "reconnecting" | "auth-blocked" | "stale") => {
    if (disposed || controller.signal.aborted || retryTimer) return;
    activeConnectionController = null;
    setPhase(reason);
    const delayMs = reason === "auth-blocked" ? authRetryDelayMs : retryDelayMs;
    retryTimer = setTimeout(() => {
      retryTimer = null;
      void connect();
    }, delayMs);
    if (reason === "auth-blocked") {
      authRetryDelayMs = Math.min(authRetryDelayMs * 2, authRetryMaxDelayMs);
    } else {
      retryDelayMs = Math.min(retryDelayMs * 2, retryMaxDelayMs);
    }
  };

  const connect = async () => {
    const connectionController = new AbortController();
    activeConnectionController = connectionController;
    const connectGeneration = generation;
    setPhase("connecting");
    try {
      const stream = await options.subscribe(connectionController.signal);
      retryDelayMs = retryInitialDelayMs;
      authRetryDelayMs = authRetryInitialDelayMs;
      lastEventAt = Date.now();
      setPhase("live");
      options.onConnected?.(connectionController.signal);
      for await (const raw of stream) {
        if (controller.signal.aborted || connectionController.signal.aborted) return;
        lastEventAt = Date.now();
        options.onEvent(raw);
      }
      if (!controller.signal.aborted && activeConnectionController === connectionController) {
        scheduleRetry("reconnecting");
      }
    } catch (error) {
      if (controller.signal.aborted) return;
      if (connectionController.signal.aborted || !isAuthError(error)) {
        scheduleRetry("reconnecting");
      } else if (generation !== connectGeneration) {
        // The generation rotated while this attempt was in flight, so its
        // auth failure is stale evidence about the previous generation.
        scheduleRetry("reconnecting");
      } else {
        scheduleRetry("auth-blocked");
      }
    } finally {
      if (activeConnectionController === connectionController) activeConnectionController = null;
    }
  };

  const notifyGenerationChanged = () => {
    if (disposed || controller.signal.aborted) return;
    generation += 1;
    // New generation: previous failures no longer predict the next attempt.
    retryDelayMs = retryInitialDelayMs;
    authRetryDelayMs = authRetryInitialDelayMs;
    const active = activeConnectionController;
    if (active && !active.signal.aborted) return;
    if (retryTimer) {
      clearTimeout(retryTimer);
      retryTimer = null;
    }
    void connect();
  };

  options.onPhaseChange?.(phase);
  void connect();
  const watchdogTimer = setInterval(() => {
    if (disposed || controller.signal.aborted || retryTimer) return;
    const active = activeConnectionController;
    if (!active || active.signal.aborted) return;
    if (Date.now() - lastEventAt < staleStreamMs) return;
    active.abort();
    scheduleRetry("stale");
  }, watchdogIntervalMs);

  return {
    notifyGenerationChanged,
    getPhase: () => phase,
    dispose: () => {
      disposed = true;
      if (retryTimer) clearTimeout(retryTimer);
      clearInterval(watchdogTimer);
      activeConnectionController?.abort();
      controller.abort();
    },
  };
}