deepline 0.3.236 → 0.3.238

package/dist/bundling-sources/sdk/src/runs/observe-transport.ts

@@ -1,45 +1,10 @@
-import { DeeplineError } from '../errors.js';
-import {
-  buildPlayRunStatusSnapshot,
-  diffPlayRunStreamEvents,
-  isTerminalPlayRunLiveStatus,
-  resolvePlayRunLogGap,
-  EMPTY_PLAY_RUN_STREAM_DIFF_STATE,
-  type LedgerBackedRunLike,
-  type PlayRunStreamDiffState,
-  type PlayRunStreamEvent,
-} from '../../../shared_libs/play-runtime/run-snapshot-stream.js';
-
 /**
- * Run Observe Transport (ADR-0008).
+ * Compatibility export retained for SDK callers that imported the old error.
+ * Run watching now uses authenticated REST snapshot polling and does not throw
+ * this error.
  *
- * Watches one Play Run by subscribing directly to the Convex Run Snapshot:
- *
- *   1. `POST /api/v2/runs/:runId/observe-grant` mints a short-lived Run
- *      Observe Grant JWT (the Deepline app stays the only auth authority).
- *   2. A lazily-imported `convex/browser` ConvexClient authenticates with the
- *      grant and subscribes to `runObservers.getPlayRunSnapshotForObserver`.
- *   3. Each snapshot update is run through the shared snapshot differ, so the
- *      emitted `play.*` events are identical to the legacy SSE stream.
- *
- * Steady-state observation therefore holds no Vercel function open and never
- * consults the coordinator. The legacy SSE reconnect loop remains only as the
- * support-window fallback: callers catch
- * {@link RunObserveTransportUnavailableError} (grant endpoint missing on an
- * older/unconfigured server, or Convex unreachable) and fall back with a
- * single visible notice.
- */
-
-/** Grant response from POST /api/v2/runs/:runId/observe-grant. */
-export type RunObserveGrantResponse = {
-  convexUrl: string;
-  token: string;
-  expiresAt: number;
-};
-
-/**
- * Bootstrap failure: this server/deployment cannot serve the subscription
- * transport. Callers fall back to the support-window SSE stream (ADR-0008).
+ * @deprecated The subscription transport has been removed. Use
+ * `client.watchRunEvents()` or `client.runs.watch()`.
  */
 export class RunObserveTransportUnavailableError extends Error {
   constructor(
@@ -50,431 +15,3 @@ export class RunObserveTransportUnavailableError extends Error {
     this.name = 'RunObserveTransportUnavailableError';
   }
 }
-
-type ObserveHttp = {
-  post<T = unknown>(path: string, body: unknown): Promise<T>;
-};
-
-export type ObserveRunEventsOptions = {
-  http: ObserveHttp;
-  runId: string;
-  signal?: AbortSignal;
-  /**
-   * Display-only notices (human mode): websocket reconnecting >10s, or a
-   * non-terminal run with no snapshot update for >120s.
-   */
-  onNotice?: (message: string) => void;
-};
-
-/** How long to wait for the first snapshot before declaring Convex unreachable. */
-const OBSERVE_BOOTSTRAP_TIMEOUT_MS = 10_000;
-/** Surface a "reconnecting" notice when the websocket is down this long. */
-const OBSERVE_RECONNECT_NOTICE_MS = 10_000;
-/** Display-only staleness warning for non-terminal runs. */
-const OBSERVE_STALE_WARNING_MS = 120_000;
-const OBSERVE_WATCHDOG_TICK_MS = 5_000;
-/** Re-mint the grant slightly before expiry. */
-const GRANT_REFRESH_MARGIN_MS = 5 * 60_000;
-const BACKFILL_PAGE_LIMIT = 1000;
-const BACKFILL_MAX_PAGES = 30;
-
-const OBSERVER_SNAPSHOT_QUERY = 'runObservers:getPlayRunSnapshotForObserver';
-const OBSERVER_LOG_PAGE_QUERY = 'runObservers:getRunLogPageForObserver';
-
-function errorText(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
-}
-
-async function mintRunObserveGrant(
-  http: ObserveHttp,
-  runId: string,
-): Promise<RunObserveGrantResponse> {
-  let response: unknown;
-  try {
-    response = await http.post(
-      `/api/v2/runs/${encodeURIComponent(runId)}/observe-grant`,
-      {},
-    );
-  } catch (error) {
-    if (error instanceof DeeplineError) {
-      // 401/403 are real auth failures on a server that HAS the endpoint —
-      // surface them loudly. 404/405 mean an older server without the grant
-      // route; 5xx/503 means the deployment cannot mint grants. Both of those
-      // are bootstrap failures handled by the dated SSE fallback (ADR-0008).
-      if (error.statusCode === 401 || error.statusCode === 403) {
-        throw error;
-      }
-      throw new RunObserveTransportUnavailableError(
-        `observe-grant endpoint unavailable (${error.statusCode ?? 'network'}): ${error.message}`,
-        'grant_endpoint_unavailable',
-      );
-    }
-    throw new RunObserveTransportUnavailableError(
-      `observe-grant request failed: ${errorText(error)}`,
-      'grant_request_failed',
-    );
-  }
-  const grant = response as Partial<RunObserveGrantResponse> | null;
-  if (
-    !grant ||
-    typeof grant.convexUrl !== 'string' ||
-    !grant.convexUrl.trim() ||
-    typeof grant.token !== 'string' ||
-    !grant.token.trim() ||
-    typeof grant.expiresAt !== 'number'
-  ) {
-    throw new RunObserveTransportUnavailableError(
-      'observe-grant endpoint returned an invalid grant payload.',
-      'grant_payload_invalid',
-    );
-  }
-  return grant as RunObserveGrantResponse;
-}
-
-type ObserverRunDoc = LedgerBackedRunLike & { status: string };
-
-type ObserverRunLogPage = {
-  runId: string;
-  lastStoredSeq: number;
-  entries: Array<{ seq: number; line: string }>;
-} | null;
-
-type QueueItem =
-  | { kind: 'run'; run: ObserverRunDoc | null }
-  | { kind: 'error'; error: unknown };
-
-/**
- * Log-gap backfill from the durable Run Log Stream (ADR-0009). Log line
- * bodies live in `playRunLogChunks` with exact absolute sequence numbers
- * (they are no longer persisted to `playRunEvents`), so the grant-scoped
- * `getRunLogPageForObserver` query returns precisely the missing seq range.
- * Returns null when the page read fails or the range is not fully stored —
- * the differ's loud `[stream] N log lines not retained` marker remains the
- * truth in that case.
- */
-async function backfillLogGap(input: {
-  queryLogPage: (
-    afterSeq: number,
-    limit: number,
-  ) => Promise<ObserverRunLogPage>;
-  lastLogSeq: number;
-  tailFirstSeq: number;
-}): Promise<string[] | null> {
-  const lines: string[] = [];
-  let cursor = input.lastLogSeq;
-  for (let page = 0; page < BACKFILL_MAX_PAGES; page += 1) {
-    if (cursor >= input.tailFirstSeq - 1) {
-      break;
-    }
-    let logPage: ObserverRunLogPage;
-    try {
-      logPage = await input.queryLogPage(
-        cursor,
-        Math.min(BACKFILL_PAGE_LIMIT, input.tailFirstSeq - 1 - cursor),
-      );
-    } catch {
-      return null;
-    }
-    const entries = (logPage?.entries ?? []).filter(
-      (entry) => entry.seq > cursor && entry.seq < input.tailFirstSeq,
-    );
-    if (entries.length === 0) {
-      break;
-    }
-    for (const entry of entries) {
-      if (entry.seq !== cursor + 1) {
-        // Stored seqs must be dense for the emitted payload's `firstSeq` to
-        // describe a contiguous run; a hole (e.g. a legacy run whose chunk
-        // storage starts mid-run) falls back to the differ's loud marker.
-        return null;
-      }
-      lines.push(entry.line);
-      cursor = entry.seq;
-    }
-  }
-  if (cursor < input.tailFirstSeq - 1) {
-    return null;
-  }
-  return lines;
-}
-
-/**
- * Subscribe to one run's snapshot and yield the same `play.*` live events the
- * SSE stream emits, ending after the terminal snapshot has been emitted.
- *
- * Failure contract:
- * - bootstrap failure → {@link RunObserveTransportUnavailableError} (caller
- *   falls back to SSE with one notice)
- * - snapshot `null` → loud `RUN_NOT_FOUND`
- * - grant rejected after one re-mint → loud failure
- * - websocket drops mid-run → Convex client auto-reconnects; a display-only
- *   "reconnecting" notice surfaces after 10s
- */
-export async function* observeRunEvents(
-  options: ObserveRunEventsOptions,
-): AsyncGenerator<PlayRunStreamEvent> {
-  const { http, runId } = options;
-  let grant = await mintRunObserveGrant(http, runId);
-
-  let convexBrowser: typeof import('convex/browser');
-  let convexServer: typeof import('convex/server');
-  try {
-    // Lazy: non-watch commands never load the Convex client.
-    convexBrowser = await import('convex/browser');
-    convexServer = await import('convex/server');
-  } catch (error) {
-    throw new RunObserveTransportUnavailableError(
-      `convex client module unavailable: ${errorText(error)}`,
-      'convex_module_unavailable',
-    );
-  }
-
-  let webSocketConstructor: typeof WebSocket | undefined;
-  if (typeof WebSocket === 'undefined') {
-    // Node 18/20 have no global WebSocket; use the ws shim.
-    try {
-      // Optional transport helper: thin SDK installs omit this and fall back to
-      // the canonical SSE tail path instead of pulling a websocket stack.
-      const wsModuleName = 'ws';
-      const ws = (await import(wsModuleName)) as { default: unknown };
-      webSocketConstructor = ws.default as typeof WebSocket;
-    } catch (error) {
-      throw new RunObserveTransportUnavailableError(
-        `no WebSocket implementation available: ${errorText(error)}`,
-        'websocket_unavailable',
-      );
-    }
-  }
-
-  const snapshotQuery = convexServer.makeFunctionReference<'query'>(
-    OBSERVER_SNAPSHOT_QUERY,
-  );
-  const logPageQuery = convexServer.makeFunctionReference<'query'>(
-    OBSERVER_LOG_PAGE_QUERY,
-  );
-
-  const client = new convexBrowser.ConvexClient(grant.convexUrl, {
-    ...(webSocketConstructor ? { webSocketConstructor } : {}),
-    unsavedChangesWarning: false,
-  });
-
-  const queue: QueueItem[] = [];
-  let wake: (() => void) | null = null;
-  const push = (item: QueueItem) => {
-    queue.push(item);
-    wake?.();
-    wake = null;
-  };
-
-  let lastForcedRefreshAt = 0;
-  client.setAuth(async ({ forceRefreshToken }) => {
-    const now = Date.now();
-    if (!forceRefreshToken && grant.expiresAt - now > GRANT_REFRESH_MARGIN_MS) {
-      return grant.token;
-    }
-    if (forceRefreshToken && now - lastForcedRefreshAt < 5_000) {
-      // Convex rejected a token we just re-minted: one re-mint retry has
-      // already happened, so fail loudly instead of looping silently.
-      push({
-        kind: 'error',
-        error: new DeeplineError(
-          `Run observe grant for ${runId} was rejected after a re-mint. ` +
-            'The server and Convex deployment disagree on the grant issuer/JWKS.',
-          401,
-          'RUN_OBSERVE_GRANT_REJECTED',
-        ),
-      });
-      return null;
-    }
-    if (forceRefreshToken) {
-      lastForcedRefreshAt = now;
-    }
-    try {
-      grant = await mintRunObserveGrant(http, runId);
-      return grant.token;
-    } catch (error) {
-      push({ kind: 'error', error });
-      return null;
-    }
-  });
-
-  const unsubscribe = client.onUpdate(
-    snapshotQuery,
-    { workflowId: runId },
-    (run) => push({ kind: 'run', run: (run ?? null) as ObserverRunDoc | null }),
-    (error) => push({ kind: 'error', error }),
-  );
-
-  let lastUpdateAt = Date.now();
-  let lastStatusTerminal = false;
-  let disconnectedSince: number | null = null;
-  let warnedReconnecting = false;
-  let warnedStale = false;
-  const watchdog = setInterval(() => {
-    const now = Date.now();
-    try {
-      const connectionState = client.connectionState();
-      if (connectionState.isWebSocketConnected) {
-        disconnectedSince = null;
-        warnedReconnecting = false;
-      } else {
-        disconnectedSince ??= now;
-        if (
-          !warnedReconnecting &&
-          now - disconnectedSince >= OBSERVE_RECONNECT_NOTICE_MS
-        ) {
-          warnedReconnecting = true;
-          options.onNotice?.(
-            `[observe] connection lost; reconnecting to live run ${runId}…`,
-          );
-        }
-      }
-    } catch {
-      // connectionState is diagnostic only.
-    }
-    if (
-      !lastStatusTerminal &&
-      !warnedStale &&
-      now - lastUpdateAt >= OBSERVE_STALE_WARNING_MS
-    ) {
-      warnedStale = true;
-      options.onNotice?.(
-        `[observe] no live updates for ${Math.round((now - lastUpdateAt) / 1000)}s; ` +
-          `run ${runId} may be stalled (status checks continue)`,
-      );
-    }
-  }, OBSERVE_WATCHDOG_TICK_MS);
-  // Don't keep the process alive for the watchdog.
-  watchdog.unref?.();
-
-  const abortListener = () =>
-    push({
-      kind: 'error',
-      error: new DeeplineError(
-        'Run observation aborted.',
-        undefined,
-        'ABORTED',
-      ),
-    });
-  options.signal?.addEventListener('abort', abortListener, { once: true });
-
-  let diffState: PlayRunStreamDiffState = EMPTY_PLAY_RUN_STREAM_DIFF_STATE;
-  const streamId = ['observe', runId].join(':');
-  let sawFirstSnapshot = false;
-
-  try {
-    for (;;) {
-      if (queue.length === 0) {
-        const waitForItem = new Promise<void>((resolve) => {
-          wake = resolve;
-        });
-        if (!sawFirstSnapshot) {
-          // Convex unreachable is a bootstrap failure: no first result within
-          // the bootstrap window means the caller should fall back to SSE.
-          const timedOut = await Promise.race([
-            waitForItem.then(() => false),
-            new Promise<boolean>((resolve) =>
-              setTimeout(() => resolve(true), OBSERVE_BOOTSTRAP_TIMEOUT_MS),
-            ),
-          ]);
-          if (timedOut && queue.length === 0) {
-            throw new RunObserveTransportUnavailableError(
-              `no snapshot from Convex at ${grant.convexUrl} within ${OBSERVE_BOOTSTRAP_TIMEOUT_MS}ms`,
-              'convex_unreachable',
-            );
-          }
-        } else {
-          await waitForItem;
-        }
-        continue;
-      }
-
-      const item = queue.shift()!;
-      if (item.kind === 'error') {
-        if (options.signal?.aborted) {
-          return;
-        }
-        throw item.error;
-      }
-
-      sawFirstSnapshot = true;
-      lastUpdateAt = Date.now();
-      warnedStale = false;
-
-      if (item.run === null) {
-        throw new DeeplineError(
-          `Run ${runId} was not found (or is not visible to this grant).`,
-          404,
-          'RUN_NOT_FOUND',
-        );
-      }
-
-      const snapshot = buildPlayRunStatusSnapshot({ run: item.run });
-      lastStatusTerminal = isTerminalPlayRunLiveStatus(snapshot.status);
-
-      // Backfill log lines that rotated out of the retained tail window from
-      // the durable Run Log Stream before diffing, so the differ emits the
-      // retained tail without its loud gap marker. First-connect to an
-      // in-flight run (lastLogSeq === 0) is intentionally NOT backfilled:
-      // watchers get the tail plus the marker pointing at `runs logs`.
-      const gap = resolvePlayRunLogGap(snapshot, diffState.lastLogSeq);
-      if (gap && diffState.lastLogSeq > 0) {
-        const backfilled = await backfillLogGap({
-          queryLogPage: (afterSeq, limit) =>
-            client.query(logPageQuery, {
-              workflowId: runId,
-              afterSeq,
-              limit,
-            }) as Promise<ObserverRunLogPage>,
-          lastLogSeq: diffState.lastLogSeq,
-          tailFirstSeq: gap.tailFirstSeq,
-        });
-        if (backfilled && backfilled.length > 0) {
-          yield {
-            cursor: String(snapshot.updatedAt ?? Date.now()),
-            streamId,
-            scope: 'play',
-            type: 'play.run.log',
-            at: new Date().toISOString(),
-            payload: {
-              runId: snapshot.runId,
-              lines: backfilled,
-              source: 'worker',
-              firstSeq: diffState.lastLogSeq + 1,
-              totalLogCount: snapshot.totalLogCount,
-            },
-          };
-          diffState = { ...diffState, lastLogSeq: gap.tailFirstSeq - 1 };
-        }
-      }
-
-      const { events, next } = diffPlayRunStreamEvents({
-        streamId,
-        snapshot,
-        previous: diffState,
-      });
-      diffState = next;
-      // Snapshot event first, mirroring the SSE stream's ordering.
-      const ordered = [
-        ...events.filter((event) => event.type === 'play.run.snapshot'),
-        ...events.filter((event) => event.type !== 'play.run.snapshot'),
-      ];
-      for (const event of ordered) {
-        yield event;
-      }
-
-      if (lastStatusTerminal) {
-        return;
-      }
-    }
-  } finally {
-    clearInterval(watchdog);
-    options.signal?.removeEventListener('abort', abortListener);
-    try {
-      unsubscribe();
-    } catch {
-      // Already closed.
-    }
-    await client.close().catch(() => undefined);
-  }
-}

package/dist/bundling-sources/sdk/src/runs/watch-polling.ts

@@ -0,0 +1,220 @@
+import {
+  diffPlayRunStreamEvents,
+  EMPTY_PLAY_RUN_STREAM_DIFF_STATE,
+  isTerminalPlayRunLiveStatus,
+  resolvePlayRunLogGap,
+  type PlayRunLiveSnapshot,
+  type PlayRunStreamDiffState,
+  type PlayRunStreamEvent,
+} from '../../../shared_libs/play-runtime/run-snapshot-stream.js';
+import { isTransientPlayRunReadError } from '../stream-reconnect.js';
+
+/** The watch endpoint is a small authenticated REST read, polled every two seconds. */
+export const RUN_WATCH_POLL_INTERVAL_MS = 2_000;
+
+type WatchHttp = {
+  get<T = unknown>(
+    path: string,
+    options?: { signal?: AbortSignal },
+  ): Promise<T>;
+};
+
+export type WatchRunEventsOptions = {
+  http: WatchHttp;
+  runId: string;
+  signal?: AbortSignal;
+  /** @internal Test seam; production callers use the fixed two-second cadence. */
+  pollIntervalMs?: number;
+  onNotice?: (message: string) => void;
+  onRetry?: (info: {
+    attempt: number;
+    delayMs: number;
+    reason: string;
+  }) => void;
+};
+
+type WatchSnapshotResponse = {
+  runId: string;
+  snapshot: PlayRunLiveSnapshot;
+};
+
+type WatchRunLogPage = {
+  entries: Array<{ seq: number; line: string }>;
+};
+
+function waitForNextPoll(ms: number, signal?: AbortSignal): Promise<boolean> {
+  if (signal?.aborted) {
+    return Promise.resolve(false);
+  }
+  return new Promise((resolve) => {
+    const finish = (elapsed: boolean) => {
+      clearTimeout(timeout);
+      signal?.removeEventListener('abort', onAbort);
+      resolve(elapsed);
+    };
+    const onAbort = () => finish(false);
+    const timeout = setTimeout(() => finish(true), ms);
+    signal?.addEventListener('abort', onAbort, { once: true });
+  });
+}
+
+function readSnapshotResponse(
+  response: unknown,
+  runId: string,
+): WatchSnapshotResponse {
+  if (!response || typeof response !== 'object' || Array.isArray(response)) {
+    throw new Error('Run watch returned an invalid snapshot response.');
+  }
+  const record = response as Record<string, unknown>;
+  const snapshot = record.snapshot;
+  if (
+    record.runId !== runId ||
+    !snapshot ||
+    typeof snapshot !== 'object' ||
+    Array.isArray(snapshot) ||
+    (snapshot as Record<string, unknown>).runId !== runId ||
+    typeof (snapshot as Record<string, unknown>).status !== 'string' ||
+    !Array.isArray((snapshot as Record<string, unknown>).logs) ||
+    !((snapshot as Record<string, unknown>).logs as unknown[]).every(
+      (line) => typeof line === 'string',
+    ) ||
+    typeof (snapshot as Record<string, unknown>).totalLogCount !== 'number' ||
+    !Array.isArray((snapshot as Record<string, unknown>).nodeStates)
+  ) {
+    throw new Error(`Run watch returned an invalid snapshot for ${runId}.`);
+  }
+  return { runId, snapshot: snapshot as PlayRunLiveSnapshot };
+}
+
+async function backfillRotatedLogTail(input: {
+  http: WatchHttp;
+  runId: string;
+  snapshot: PlayRunLiveSnapshot;
+  previous: PlayRunStreamDiffState;
+  signal?: AbortSignal;
+}): Promise<PlayRunLiveSnapshot> {
+  // A late first attach intentionally shows the retained tail and its gap
+  // marker. Backfill only lines that rotated out after this watcher attached.
+  if (!input.previous.runSignature) {
+    return input.snapshot;
+  }
+  const gap = resolvePlayRunLogGap(input.snapshot, input.previous.lastLogSeq);
+  if (!gap) {
+    return input.snapshot;
+  }
+
+  const lines: string[] = [];
+  let cursor = input.previous.lastLogSeq;
+  const targetSeq = gap.tailFirstSeq - 1;
+  while (cursor < targetSeq) {
+    const limit = Math.min(1_000, targetSeq - cursor);
+    const page = await input.http.get<WatchRunLogPage>(
+      `/api/v2/runs/${encodeURIComponent(input.runId)}/logs?afterSeq=${cursor}&limit=${limit}`,
+      { signal: input.signal },
+    );
+    if (!page || !Array.isArray(page.entries) || page.entries.length === 0) {
+      return input.snapshot;
+    }
+    for (const entry of page.entries) {
+      if (
+        !entry ||
+        entry.seq !== cursor + 1 ||
+        typeof entry.line !== 'string'
+      ) {
+        return input.snapshot;
+      }
+      lines.push(entry.line);
+      cursor = entry.seq;
+    }
+  }
+  if (cursor !== targetSeq) {
+    return input.snapshot;
+  }
+  return { ...input.snapshot, logs: [...lines, ...input.snapshot.logs] };
+}
+
+/**
+ * Poll the authenticated run snapshot and emit the canonical `play.*` events.
+ * No Convex observer token, WebSocket, or server-held SSE connection is used.
+ */
+export async function* watchRunEvents(
+  options: WatchRunEventsOptions,
+): AsyncGenerator<PlayRunStreamEvent> {
+  const { http, runId, signal } = options;
+  const path = `/api/v2/runs/${encodeURIComponent(runId)}?watchSnapshot=true`;
+  const streamId = `play-run-watch:${runId}`;
+  const pollIntervalMs = options.pollIntervalMs ?? RUN_WATCH_POLL_INTERVAL_MS;
+  let previous: PlayRunStreamDiffState = EMPTY_PLAY_RUN_STREAM_DIFF_STATE;
+  let consecutiveFailures = 0;
+  let outageNoticeSent = false;
+
+  while (!signal?.aborted) {
+    const pollStartedAt = Date.now();
+    let snapshot: PlayRunLiveSnapshot;
+    try {
+      const response = await http.get<unknown>(path, { signal });
+      snapshot = await backfillRotatedLogTail({
+        http,
+        runId,
+        snapshot: readSnapshotResponse(response, runId).snapshot,
+        previous,
+        signal,
+      });
+    } catch (error) {
+      if (signal?.aborted) {
+        return;
+      }
+      if (!isTransientPlayRunReadError(error)) {
+        throw error;
+      }
+      consecutiveFailures += 1;
+      const reason = error instanceof Error ? error.message : String(error);
+      if (!outageNoticeSent) {
+        options.onRetry?.({
+          attempt: consecutiveFailures,
+          delayMs: pollIntervalMs,
+          reason,
+        });
+        options.onNotice?.(
+          `[watch] run snapshot request failed; retrying every ${pollIntervalMs / 1_000}s (${reason})`,
+        );
+        outageNoticeSent = true;
+      }
+      const remaining = Math.max(
+        0,
+        pollIntervalMs - (Date.now() - pollStartedAt),
+      );
+      if (!(await waitForNextPoll(remaining, signal))) {
+        return;
+      }
+      continue;
+    }
+
+    if (outageNoticeSent) {
+      options.onNotice?.('[watch] run snapshot polling recovered');
+      outageNoticeSent = false;
+    }
+    consecutiveFailures = 0;
+
+    const diff = diffPlayRunStreamEvents({
+      streamId,
+      snapshot,
+      previous,
+    });
+    previous = diff.next;
+    for (const event of diff.events) {
+      yield event;
+    }
+    if (isTerminalPlayRunLiveStatus(snapshot.status)) {
+      return;
+    }
+
+    const remaining = Math.max(
+      0,
+      pollIntervalMs - (Date.now() - pollStartedAt),
+    );
+    if (!(await waitForNextPoll(remaining, signal))) {
+      return;
+    }
+  }
+}