Add KVStorageComposite, IndexedDB storage and SSE change streams

- Every KV storage emits change events (base class owns writeMany/removeMany/
  writeIfAbsent; implementations provide protected apply* methods)
- KVStorageHttpServer streams changes over SSE (GET /events) with a resumable
  history; KVStorageHttp.watch() subscribes and resumes via Last-Event-ID
- KVStorageIndexedDB for local persistence
- KVStorageComposite keeps replicas of a source in sync: local reads, resume
  instead of full sync, offline outbox replayed in order, echo tracking
- Values may contain bigint/Uint8Array (Extended JSON over the network)
- Vendor sse-session, event-emitter and extended-json (no runtime deps)
- Freeze child nodes so shadowed state on children fails loudly
- CI on Node 22, 24 and 26

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017Qxbkp4tA7G5SCWjzWuxmE

src/utils/sse-session/async-push-iterator.ts

@@ -0,0 +1,85 @@
+// Vendored from https://git.harvmaster.com/Harvmaster/sse-session (commit c08267e85c).
+// Local changes: import paths, uses ../event-emitter.ts, tryAsync folded into SSESession.
+
+/**
+ * An async iterable queue that bridges push-based producers and pull-based consumers.
+ *
+ * Composes an internal {@link ReadableStream} instead of extending it, so producers
+ * call {@link push} while consumers use standard async iteration (`for await...of`).
+ *
+ * ```ts
+ * const messages = new AsyncPushIterator<SSEvent>();
+ *
+ * // Producer (elsewhere)
+ * messages.push(event);
+ *
+ * // Consumer
+ * for await (const event of messages) {
+ *   handle(event);
+ * }
+ * ```
+ *
+ * {@link Symbol.asyncIterator} returns `stream.values({ preventCancel: true })` so
+ * breaking out of `for await...of` does not cancel the underlying stream. That
+ * matters for long-lived sessions where the producer keeps pushing after a consumer
+ * stops reading early (for example, test helpers that only collect a fixed count).
+ */
+export class AsyncPushIterator<T> {
+  /** ReadableStream backing the async iterator returned from {@link Symbol.asyncIterator}. */
+  private readonly stream: ReadableStream<T>
+
+  /** Controller used to enqueue values and close the stream from {@link push} and {@link close}. */
+  private controller: ReadableStreamDefaultController<T> | undefined
+
+  /** When true, no more values are accepted and iteration eventually completes. */
+  public closed = false
+
+  public constructor() {
+    // `start`'s `this` is the underlying source object when using a plain method.
+    // An arrow function captures the class instance so the controller is stored here.
+    this.stream = new ReadableStream({
+      start: (controller: ReadableStreamDefaultController<T>): void => {
+        this.controller = controller
+      },
+    })
+  }
+
+  /**
+   * Enqueues a value for the consumer.
+   *
+   * After {@link close}, pushes are silently dropped.
+   *
+   * @param value - The next value to yield from the iterator.
+   */
+  push(value: T): void {
+    if (this.closed) return
+
+    this.controller?.enqueue(value)
+  }
+
+  /**
+   * Ends the stream.
+   *
+   * Marks the iterator closed so future {@link push} calls are ignored.
+   * Buffered values are still yielded before iteration completes.
+   */
+  close(): void {
+    this.closed = true
+
+    try {
+      this.controller?.close()
+    } catch {
+      // The reader may already have released or cancelled the stream.
+    }
+  }
+
+  /**
+   * Returns an async iterator over the composed stream.
+   *
+   * Uses `preventCancel: true` so early `break` from `for await...of` does not
+   * close the stream and block later pushes.
+   */
+  [Symbol.asyncIterator](): AsyncIterableIterator<T> {
+    return this.stream.values({ preventCancel: true })
+  }
+}

src/utils/sse-session/exponential-backoff.ts

@@ -0,0 +1,251 @@
+// Vendored from https://git.harvmaster.com/Harvmaster/sse-session (commit c08267e85c).
+// Local changes: import paths, uses ../event-emitter.ts, tryAsync folded into SSESession.
+
+/**
+ * Exponential backoff is a technique used to retry a function after a delay.
+ *
+ * The delay increases exponentially with each attempt, up to a maximum delay.
+ *
+ * The jitter is a random amount of time added to the delay to prevent thundering herd problems.
+ *
+ * The growth rate is the factor by which the delay increases with each attempt.
+ */
+export class ExponentialBackoff {
+  /**
+   * Create a new ExponentialBackoff instance
+   *
+   * @param config - The configuration for the exponential backoff
+   * @returns The ExponentialBackoff instance
+   */
+  static from(config?: Partial<ExponentialBackoffOptions>): ExponentialBackoff {
+    const backoff = new ExponentialBackoff(config)
+
+    return backoff
+  }
+
+  /**
+   * Run the function with exponential backoff
+   *
+   * @param fn - The function to run
+   * @param onError - The callback to call when an error occurs
+   * @param options - The configuration for the exponential backoff
+   *
+   * @throws An AggregateError with all the errors that were thrown by the task function
+   *
+   * @returns The result of the function
+   */
+  static run<T>(
+    fn: (context: ExpontialBackoffCallbackContext) => Promise<T>,
+    onError = (_error: Error, _context: ExpontialBackoffCallbackContext): void => {},
+    options?: Partial<ExponentialBackoffOptions>,
+  ): Promise<T> {
+    const backoff = ExponentialBackoff.from(options)
+
+    return backoff.run(fn, onError)
+  }
+
+  private readonly options: ExponentialBackoffOptions
+
+  /**
+   * Creates a new exponential-backoff instance.
+   *
+   * Unspecified options use the defaults listed below.
+   *
+   * @param options - Exponential-backoff configuration overrides.
+   * @param options.maxDelay - Maximum delay between retries. Default: `10_000` ms.
+   * @param options.maxAttempts - Maximum number of attempts; `0` retries indefinitely. Default: `10`.
+   * @param options.baseDelay - Delay used as the basis for the first retry. Default: `1_000` ms.
+   * @param options.growthRate - Multiplier applied to the delay after each attempt. Default: `2`.
+   * @param options.jitter - Random proportional variation applied to each delay. Default: `0.1`.
+   */
+  constructor(options: Partial<ExponentialBackoffOptions> = {}) {
+    this.options = {
+      maxDelay: 10_000,
+      maxAttempts: 10,
+      baseDelay: 1_000,
+      growthRate: 2,
+      jitter: 0.1,
+      ...options,
+    }
+
+    ExponentialBackoff.validateOptions(this.options)
+  }
+
+  /**
+   * Run the function with exponential backoff
+   *
+   * If the function fails but we have not hit the max attempts, the error will be passed to the onError callback
+   * and the function will be retried with an exponential delay
+   *
+   * If the function fails and we have hit the max attempts, an AggregateError will be thrown with all the errors that were thrown by the task function
+   *
+   * @param fn - The function to run
+   * @param onError - The callback to call when an error occurs
+   *
+   * @throws An AggregateError with all the errors that were thrown by the task function
+   *
+   * @returns The result of the function
+   */
+  async run<T>(
+    fn: (context: ExpontialBackoffCallbackContext) => Promise<T>,
+    onError = (_error: Error, _context: ExpontialBackoffCallbackContext): void => {},
+  ): Promise<T> {
+    const abortController = new AbortController()
+
+    const context: ExpontialBackoffCallbackContext = {
+      errors: [],
+      attempt: 1,
+      options: { ...this.options },
+      nextDelay: 0,
+      signal: abortController.signal,
+      abort: (reason?: unknown) => abortController.abort(reason),
+    }
+
+    while (context.options.maxAttempts === 0 || context.attempt <= context.options.maxAttempts) {
+      context.nextDelay = ExponentialBackoff.calculateDelay(context.options, context.attempt - 1)
+
+      try {
+        // Await the promise before returning so its execution context remains in the try-catch
+        // If we didn't await, this `run` function would successfully return and any errors would not be caught here.
+        return await fn(context)
+      } catch (error) {
+        // Store the error in case we fail every attempt
+        const errorInstance = error instanceof Error ? error : new Error(`${error}`)
+        context.errors.push(errorInstance)
+        await onError(errorInstance, context)
+      }
+
+      // If the abort controller is aborted, throw an error
+      if (abortController.signal.aborted) {
+        const reasonError = abortController.signal.reason instanceof Error ? abortController.signal.reason : new Error(`${abortController.signal.reason}`)
+        throw new Error('Exponential backoff aborted', { cause: reasonError })
+      }
+
+      // If we have hit the max attempts, break out of the loop
+      const unlimitedAttempts = context.options.maxAttempts === 0
+      if (!unlimitedAttempts && context.attempt >= context.options.maxAttempts) {
+        break
+      }
+
+      // Wait before going to the next attempt
+      await this.wait(context.nextDelay, abortController.signal)
+
+      context.attempt++
+    }
+
+    // We completed the loop without ever succeeding. Throw an ExponentialBackoffMaxRetriesHitError with all the errors we got
+    throw new AggregateError(context.errors, 'Exponential backoff max retries hit')
+  }
+
+  private wait(delay: number, signal: AbortSignal): Promise<void> {
+    return new Promise((resolve, reject) => {
+      // Set a timeout to resolve the promise
+      const timeout = setTimeout(() => {
+        resolve()
+      }, delay)
+
+      // If the signal is aborted, reject the promise
+      signal.addEventListener('abort', () => {
+        clearTimeout(timeout)
+        reject(new Error('Exponential backoff aborted'))
+      })
+    })
+  }
+
+  /**
+   * Calculate the delay before we should attempt to retry
+   *
+   * NOTE: The maximum delay is (maxDelay * (1 + jitter))
+   *
+   * @param attempt
+   * @returns The time in milliseconds before another attempt should be made
+   */
+  public static calculateDelay(options: ExponentialBackoffOptions, attempt: number): number {
+    // Get the power of the growth rate
+    const power = options.growthRate ** attempt
+
+    // Get the delay before jitter or limit
+    const rawDelay = options.baseDelay * power
+
+    // Cap the delay to the maximum. Do this before the jitter so jitter does not become larger than delay
+    const cappedDelay = Math.min(rawDelay, options.maxDelay)
+
+    // Get a random number for the amount to "jitter" the delay by
+    const jitterAmount = Math.random()
+
+    // Calculate the jitter
+    const jitter = jitterAmount * options.jitter * cappedDelay
+
+    // Subtract the jitter from the delay
+    return cappedDelay - jitter
+  }
+
+  /**
+   * Validate the options, ensure that no values are NaN
+   * @param options
+   */
+  public static validateOptions(options: ExponentialBackoffOptions): void {
+    const keys = Object.keys(options) as (keyof ExponentialBackoffOptions)[]
+
+    for (const key of keys) {
+      if (!isFinite(options[key])) {
+        throw new Error(`Invalid option: ${key} is not finite`)
+      }
+
+      if (key === 'jitter' && (options[key] < 0 || options[key] > 1)) {
+        throw new Error(`Invalid option: jitter is not between 0 and 1`)
+      }
+
+      if (options[key] < 0) {
+        throw new Error(`Invalid option: ${key} is less than 0`)
+      }
+    }
+  }
+}
+
+export type ExponentialBackoffOptions = {
+  /**
+   * The maximum delay between attempts in milliseconds
+   */
+  maxDelay: number
+
+  /**
+   * The maximum number of attempts. Passing 0 will result in infinite attempts.
+   */
+  maxAttempts: number
+
+  /**
+   * The base delay between attempts in milliseconds
+   */
+  baseDelay: number
+
+  /**
+   * The growth rate of the delay
+   */
+  growthRate: number
+
+  /**
+   * The jitter of the delay as a percentage of growthRate
+   */
+  jitter: number
+}
+
+export type ExpontialBackoffCallbackContext = {
+  /** The errors that have occurred */
+  errors: Error[]
+
+  /** The current attempt */
+  attempt: number
+
+  /** The options for the exponential backoff */
+  options: ExponentialBackoffOptions
+
+  /** The next delay before the next attempt */
+  nextDelay: number
+
+  /** The abort signal */
+  signal: AbortSignal
+
+  /** The abort function */
+  abort: (reason?: unknown) => void
+}

src/utils/sse-session/index.ts

@@ -0,0 +1,5 @@
+export * from './types.js'
+export * from './sse-session.js'
+export * from './sse-event-parser.js'
+export * from './async-push-iterator.js'
+export * from './exponential-backoff.js'

src/utils/sse-session/sse-event-parser.ts

@@ -0,0 +1,214 @@
+// Vendored from https://git.harvmaster.com/Harvmaster/sse-session (commit c08267e85c).
+// Local changes: import paths, uses ../event-emitter.ts, tryAsync folded into SSESession.
+
+import type { SSEvent } from './types.js'
+
+/**
+ * Optional encoders used when decoding incoming SSE bytes and re-encoding
+ * any buffered remainder between chunks.
+ */
+export interface SSEEventParserOptions {
+  /** Decodes raw stream bytes into text. Defaults to a new `TextDecoder`. */
+  textDecoder: TextDecoder
+}
+
+/**
+ * Regex that splits decoded SSE text into lines.
+ *
+ * The SSE wire format is line-oriented (`field: value` per line). Servers may
+ * send `\r\n` (HTTP default), `\n` (Unix), or `\r` (legacy Mac). Matching all
+ * three keeps parsing correct regardless of platform or server implementation.
+ */
+export const SSE_LINE_ENDINGS = /\r\n|\r|\n/
+
+/**
+ * Regex that matches the single optional leading space in an SSE field value.
+ *
+ * Per the SSE spec, `field: value` may include one space immediately after the
+ * colon; that space is not part of the value. Used with `.replace()` to strip
+ * it when parsing lines such as `data: hello` → `hello`.
+ */
+export const SSE_FIELD_VALUE_REGEX = /^ /
+
+/**
+ * The newline character used when normalizing SSE text internally.
+ *
+ * Used to join consecutive `data:` lines into one payload and to reassemble
+ * buffered partial lines between streamed chunks before the next parse call.
+ */
+export const NEW_LINE = '\n'
+
+/**
+ * Incrementally parses Server-Sent Events (SSE) from streamed byte chunks.
+ *
+ * SSE payloads are line-oriented: each event is a sequence of `field: value`
+ * lines terminated by a blank line. This parser accepts arbitrary chunk
+ * boundaries from a live HTTP response body and emits only complete events.
+ *
+ * Typical usage is one parser instance per connection, calling {@link parseEvents}
+ * for each chunk received from the stream:
+ *
+ * ```ts
+ * const parser = new SSEEventParser();
+ *
+ * for await (const chunk of response.body) {
+ *   for (const event of parser.parseEvents(chunk)) {
+ *     // handle event.data, event.event, event.id, event.retry
+ *   }
+ * }
+ * ```
+ *
+ * Supported fields follow the SSE spec: `data`, `event`, `id`, and `retry`.
+ * Multiple `data:` lines in one event are joined with `\n`. An event is only
+ * emitted once a blank line is seen and at least one `data` field was collected.
+ */
+export class SSEEventParser {
+  private readonly textDecoder: TextDecoder
+
+  /** Bytes from a partial line or incomplete event, carried over to the next chunk. */
+  private messageBuffer: string = ''
+
+  /**
+   * Creates a parser for one SSE stream.
+   *
+   * Inject custom encoders in tests or when a non-default character encoding
+   * is required; production callers can rely on the defaults.
+   *
+   * @param options - Optional text encoders for decode/encode of stream bytes.
+   */
+  constructor(options: Partial<SSEEventParserOptions> = {}) {
+    this.textDecoder = options.textDecoder ?? new TextDecoder()
+  }
+
+  /**
+   * Clears any buffered bytes from a partial line or incomplete event.
+   *
+   * Call when abandoning a transport so the next connection does not prepend
+   * stale bytes to incoming chunks.
+   */
+  public reset(): void {
+    // Clear the message buffer
+    this.messageBuffer = ''
+
+    // Reset the decoder to clear any buffered bytes
+    this.textDecoder.decode()
+  }
+
+  /**
+   * Parses all complete SSE events contained in a newly received chunk.
+   *
+   * The chunk is appended to any bytes buffered from earlier calls. Complete
+   * events (blank-line delimited blocks with at least one `data` field) are
+   * returned immediately; any trailing partial line or in-progress event stays
+   * in the internal buffer until a later chunk completes it.
+   *
+   * @param chunk - Newly received SSE stream bytes.
+   * @returns Zero or more complete parsed SSE events from this chunk.
+   */
+  public parseEvents(chunk: Uint8Array): SSEvent[] {
+    const lines = this.getBufferedLines(chunk)
+
+    // The final split item is the incomplete remainder after the final line
+    // ending. It must not be processed as a complete SSE line.
+    const completeLines = lines.slice(0, -1)
+
+    const events: SSEvent[] = []
+    let event: Partial<SSEvent> = {}
+    let processedLineCount = 0
+
+    for (const [index, line] of completeLines.entries()) {
+      // A blank line indicates the end of an event. If we have received data, we can complete the event
+      if (line === '') {
+        if (event.data !== undefined) {
+          // Cast event when pushing to an SSE Event so it changes from Partial<SSEvent> to SSEvent
+          // The "Partial" can safely be removed as we have guaranteed that `data` is defined
+          events.push(event as SSEvent)
+        }
+
+        event = {}
+        processedLineCount = index + 1
+
+        continue
+      }
+
+      this.parseLine(line, event)
+    }
+
+    this.storeRemainingLines(lines, processedLineCount)
+
+    return events
+  }
+
+  /**
+   * Appends a new chunk to the buffered bytes and splits the combined payload
+   * into lines.
+   *
+   * Accepts `\r\n`, `\r`, and `\n` line endings so events parse correctly
+   * regardless of server or platform conventions.
+   */
+  private getBufferedLines(chunk: Uint8Array): string[] {
+    this.messageBuffer += this.textDecoder.decode(chunk, { stream: true })
+
+    return this.messageBuffer.split(SSE_LINE_ENDINGS)
+  }
+
+  /**
+   * Parses one SSE field line into an in-progress event.
+   *
+   * Lines starting with a colon are ignored as comments. A single optional space after the colon
+   * is stripped from the field value, per the SSE spec.
+   */
+  private parseLine(line: string, event: Partial<SSEvent>): void {
+    // Split the line at the first colon. Before the first colon is the field, after the first colon is the value.
+    const [field, ...valueArray] = line.split(':')
+
+    // Join the rest of the array back together to get the value as it was before the split.
+    // If the value has a space at the start, remove it (according to the SSE spec)
+    const value = valueArray.join(':').replace(SSE_FIELD_VALUE_REGEX, '')
+
+    switch (field) {
+      case 'data':
+        event.data = event.data !== undefined ? `${event.data}${NEW_LINE}${value}` : value
+
+        return
+
+      case 'event':
+        event.event = value
+
+        return
+
+      case 'id':
+        event.id = value
+
+        return
+
+      case 'retry':
+        this.parseRetry(value, event)
+
+        return
+    }
+  }
+
+  /**
+   * Applies a numeric `retry:` field to an in-progress event.
+   *
+   * Non-numeric values are ignored rather than failing the parse.
+   */
+  private parseRetry(value: string, event: Partial<SSEvent>): void {
+    const retry = parseInt(value, 10)
+
+    if (!isNaN(retry)) {
+      event.retry = retry
+    }
+  }
+
+  /**
+   * Preserves incomplete trailing lines for the next received chunk.
+   *
+   * Only lines that were fully processed (through a completed event boundary)
+   * are discarded; the remainder is re-encoded into {@link messageBuffer}.
+   */
+  private storeRemainingLines(lines: string[], processedLineCount: number): void {
+    this.messageBuffer = lines.slice(processedLineCount).join(NEW_LINE)
+  }
+}

src/utils/sse-session/sse-session.ts

@@ -0,0 +1,471 @@
+// Vendored from https://git.harvmaster.com/Harvmaster/sse-session (commit c08267e85c).
+// Local changes: import paths, uses ../event-emitter.ts, tryAsync folded into SSESession.
+
+import type { SSESessionOptions, SSESessionEventMap, SSEvent } from './types.js'
+
+import { EventEmitter } from '../event-emitter.js'
+import { AsyncPushIterator } from './async-push-iterator.js'
+import { ExponentialBackoff } from './exponential-backoff.js'
+
+import { SSEEventParser } from './sse-event-parser.js'
+
+/**
+ * A fetch-based Server-Sent Events (SSE) client with reconnect and optional
+ * browser tab visibility handling.
+ *
+ * Each session maintains one HTTP streaming connection at a time. Incoming
+ * bytes are parsed into {@link SSEvent} objects and delivered through two
+ * surfaces:
+ *
+ * - **Events** — `"connected"`, `"message"`, `"disconnected"`, `"error"`,
+ *   and `"closed"` on the session itself (extends {@link EventEmitter}).
+ * - **Messages** — {@link messages}, an async iterable for `for await...of`
+ *   consumers.
+ *
+ * Typical usage:
+ *
+ * ```ts
+ * const session = await SSESession.create("/events");
+ *
+ * session.on("message", (event) => console.log(event.data));
+ *
+ * for await (const event of session.messages) {
+ *   handle(event);
+ * }
+ * ```
+ *
+ * ## Lifecycle
+ *
+ * - {@link connect} opens (or reopens) the transport. It resolves once the
+ *   HTTP stream is established; reading continues in the background.
+ * - {@link abort} stops the in-flight fetch without ending the session.
+ *   Used internally for tab visibility. The {@link messages} iterator stays
+ *   open so an existing consumer resumes when the tab becomes visible again.
+ * - {@link disconnect} aborts the transport, closes {@link messages}, emits
+ *   `"closed"`, and disables attached visibility handlers until the next
+ *   manual {@link connect}.
+ *
+ * Automatic reconnect is controlled by {@link SSESessionOptions.persistent}
+ * (server closed the stream) and
+ * {@link SSESessionOptions.attemptReconnect} (transport error).
+ *
+ * ## Connection supersession
+ *
+ * Each {@link connect} or {@link abort} bumps an internal `connectionId`.
+ * Background read loops capture their id at start and exit quietly when a
+ * newer connection supersedes them, avoiding duplicate events or errors from
+ * stale transports.
+ */
+export class SSESession extends EventEmitter<SSESessionEventMap> {
+  /**
+   * Creates a session and waits until the first connection is established.
+   *
+   * @param url - The SSE endpoint URL.
+   * @param options - Configuration merged with instance defaults.
+   * @returns A connected session.
+   * @throws When the initial connection cannot be established.
+   */
+  static async create(url: string, options: Partial<SSESessionOptions> = {}): Promise<SSESession> {
+    const client = new SSESession(url, options)
+    await client.connect()
+
+    return client
+  }
+
+  /**
+   * Enables SSE resume semantics by sending `Last-Event-ID` on reconnect.
+   *
+   * Listens for incoming `"message"` events and remembers the most recent
+   * {@link SSEvent.id}. On every subsequent connect or reconnect, the session's
+   * {@link onRequest} hook is wrapped so that header is attached when an id is
+   * known, allowing the server to replay only events the client has not yet
+   * received.
+   *
+   * The existing {@link onRequest} callback is preserved and runs after the
+   * header is applied, so auth or other header mutations continue to work.
+   *
+   * Attach as early in the session lifetime as possible. When added after
+   * {@link create}, the initial connection omits the header (no id yet);
+   * all later reconnects include it. To instrument before the first connect,
+   * call this on the session returned from {@link withBrowserVisibility}
+   * before awaiting a separate {@link connect} when the tab starts hidden.
+   *
+   * ```ts
+   * const session = await SSESession.create(url);
+   * await SSESession.addLastEventIdReconnect(session);
+   * // Reconnects send Last-Event-ID once an event with an id is received.
+   * ```
+   *
+   * @param client - The session to instrument.
+   * @returns The same session, for chaining.
+   */
+  static async addLastEventIdReconnect(client: SSESession): Promise<SSESession> {
+    let lastEventId: string | undefined
+
+    client.on('message', (event) => {
+      // If the event has no id, we should not update the lastEventId and instead keep the old one.
+      lastEventId = event.id ?? lastEventId
+    })
+
+    const originalOnRequest = client.options.onRequest
+
+    client.options.onRequest = async (request: RequestInit): Promise<RequestInit> => {
+      if (lastEventId) {
+        request.headers = { ...request.headers, 'Last-Event-ID': lastEventId }
+      }
+
+      return originalOnRequest(request)
+    }
+
+    return client
+  }
+
+  /**
+   * Pauses and resumes a session based on browser tab visibility.
+   *
+   * Uses the Page Visibility API (`document.visibilitychange`):
+   *
+   * - **hidden** — {@link abort} stops the active fetch. {@link messages}
+   *   stays open; `"disconnected"` fires but `"closed"` does not.
+   * - **visible** — {@link connect} re-establishes the stream if needed.
+   *
+   * The listener is removed when {@link disconnect} emits `"closed"`, and
+   * re-attached automatically on the next `"connected"` event.
+   *
+   * No-op in non-browser environments where `document` is undefined.
+   *
+   * @param client - The session to manage.
+   */
+  static addBrowserVisibilityHandler(client: SSESession): SSESession {
+    if (typeof document === 'undefined') return client
+
+    const handleVisibilityChange = (): void => {
+      if (document.visibilityState === 'hidden') {
+        void client.abort()
+
+        return
+      }
+
+      client.connect().catch(() => {
+        // connect() reports failures via onError and the "error" event.
+      })
+    }
+
+    document.addEventListener('visibilitychange', handleVisibilityChange)
+
+    // Stop managing visibility after an explicit disconnect; re-register
+    // when the same instance is manually connected again.
+    client.once('closed', () => {
+      document.removeEventListener('visibilitychange', handleVisibilityChange)
+
+      client.once('connected', () => {
+        SSESession.addBrowserVisibilityHandler(client)
+      })
+    })
+
+    return client
+  }
+
+  /** SSE endpoint URL for this session. */
+  private readonly url: string
+
+  /**
+   * Per-instance configuration.
+   *
+   * Defaults live on the instance field (not a shared static) so each session
+   * gets its own {@link SSEEventParser} and {@link ExponentialBackoff}.
+   */
+  public options: SSESessionOptions = {
+    fetch: (...args) => fetch(...args),
+    method: 'GET',
+    headers: {
+      Accept: 'text/event-stream',
+      'Cache-Control': 'no-cache',
+    },
+    body: new FormData(),
+
+    onRequest: (request) => Promise.resolve(request),
+    onConnected: () => {},
+    onDisconnected: () => {},
+    onError: (error) => console.error('SSEClient error:', error),
+
+    // Retry the initial fetch until it succeeds (maxAttempts: 0 = unlimited).
+    retry: new ExponentialBackoff({
+      baseDelay: 1000,
+      maxDelay: 10000,
+      maxAttempts: 0,
+      growthRate: 1.3,
+      jitter: 0.3,
+    }),
+
+    attemptReconnect: true,
+    persistent: false,
+
+    eventParser: new SSEEventParser(),
+  }
+
+  /** AbortController for the currently active fetch, if any. */
+  private controller: AbortController | null = null
+
+  /**
+   * Asynchronous stream of parsed SSE events for the active connection.
+   *
+   * Stays open across {@link abort} and automatic reconnects so an existing
+   * `for await` consumer keeps receiving events after visibility resumes.
+   *
+   * Closes when:
+   * - the server ends the stream and {@link SSESessionOptions.persistent}
+   *   is false,
+   * - {@link disconnect} is called, or
+   * - a transport error occurs with
+   *   {@link SSESessionOptions.attemptReconnect} disabled.
+   *
+   * A later {@link connect} replaces this with a new iterator when the
+   * previous one was closed. Consumers should read from `session.messages`
+   * rather than caching a reference across terminal disconnects.
+   */
+  public messages: AsyncPushIterator<SSEvent> = new AsyncPushIterator<SSEvent>()
+
+  public constructor(url: string, options: Partial<SSESessionOptions> = {}) {
+    super()
+
+    this.url = url
+    this.options = {
+      ...this.options,
+      ...options,
+      // Shallow merge would drop default headers when options.headers is set.
+      headers: { ...this.options.headers, ...options.headers },
+    }
+  }
+
+  /**
+   * Connects or reconnects to the SSE endpoint.
+   *
+   * Resolves once the HTTP stream is established and `"connected"` has been
+   * emitted. Body reading continues asynchronously in the background via
+   * {@link readStream}.
+   *
+   * @throws When the fetch retry policy exhausts attempts or the connection
+   *   is superseded before the reader is handed off (in the latter case the
+   *   promise resolves without throwing).
+   */
+  public async connect(): Promise<void> {
+    // If there is already a controller present, we are already connected.
+    if (this.controller) return
+
+    // Prepare for a fresh transport. Parser state from an abandoned connection
+    // must not bleed into the next one; reopen messages if a prior terminal
+    // close ended the consumer's iteration loop.
+    // NOTE: The resetEventParser may be out of spec and should not be done here: https://html.spec.whatwg.org/multipage/server-sent-events.html#event-stream-interpretation
+    this.options.eventParser.reset()
+
+    // If the last messages iterator wasnt closed, we keep it around as this is likely a reconnect.
+    if (this.messages.closed) {
+      this.messages = new AsyncPushIterator<SSEvent>()
+    }
+
+    const controller = new AbortController()
+    this.controller = controller
+
+    const { method, headers, body } = this.options
+
+    const fetchBody = method === 'POST' ? body : null
+
+    const fetchOptions: RequestInit = {
+      method,
+      headers: headers || {},
+      body: fetchBody ?? null,
+      signal: controller.signal,
+      cache: 'no-store',
+    }
+
+    let reader: ReadableStreamDefaultReader<Uint8Array>
+
+    try {
+      reader = await this.options.retry.run(() => this.createReader(fetchOptions))
+    } catch (error) {
+      // A newer abort/connect superseded this attempt — leave state to the winner.
+      if (this.controller !== controller) return
+
+      this.controller = null
+
+      await this.notifyDisconnected()
+      await this.notifyError(error)
+      this.messages.close()
+
+      throw error
+    }
+
+    // Connection succeeded but was already replaced (for example abort during fetch).
+    if (this.controller !== controller) {
+      await reader.cancel()
+
+      return
+    }
+
+    await SSESession.tryAsync(
+      () => this.options.onConnected(),
+      (error) => this.notifyError(error),
+    )
+    this.emit('connected', undefined)
+
+    // Fire-and-forget: connect() resolves while the stream is consumed.
+    this.readStream(reader, controller).catch((error) => {
+      this.options.onError(error)
+    })
+  }
+
+  /**
+   * Aborts only the currently active transport.
+   *
+   * The session remains reusable: {@link messages} stays open, visibility
+   * handling stays attached, and {@link connect} can reopen the stream.
+   * Partial parser state from the abandoned transport is discarded.
+   *
+   * Emits `"disconnected"` but not `"closed"`.
+   */
+  public async abort(): Promise<void> {
+    if (!this.controller) return
+
+    // Grab the current controller to ensure we are aborting the correct one.
+    const controller = this.controller
+    this.controller = null
+
+    // Invalidate any in-flight read loop and fetch for this transport.
+    controller.abort()
+    this.options.eventParser.reset()
+
+    await this.notifyDisconnected()
+  }
+
+  /**
+   * Terminates the session and disables attached visibility handling until
+   * the same instance is manually {@link connect connected} again.
+   *
+   * Closes {@link messages} and emits `"closed"`.
+   */
+  public async disconnect(): Promise<void> {
+    this.messages.close()
+    this.emit('closed', undefined)
+
+    if (this.controller) {
+      await this.abort()
+    } else {
+      this.options.eventParser.reset()
+    }
+  }
+
+  /**
+   * Performs the HTTP request and returns a reader for the response body.
+   *
+   * {@link SSESessionOptions.onRequest} may mutate headers (for example auth
+   * tokens or `Last-Event-ID`) before the fetch runs.
+   */
+  private async createReader(fetchOptions: RequestInit): Promise<ReadableStreamDefaultReader<Uint8Array>> {
+    const requestOptions = await this.options.onRequest(fetchOptions)
+    const response = await this.options.fetch(this.url, requestOptions)
+
+    if (!response.ok) {
+      const responseCode = response.status
+      const responseText = await response.text()
+
+      const error = new Error(`HTTP error: ${responseCode} ${responseText}`)
+      void this.notifyError(error)
+      throw error
+    }
+
+    if (!response.body) {
+      const error = new Error('HTTP error: Response body is null')
+      void this.notifyError(error)
+      throw error
+    }
+
+    return response.body.getReader()
+  }
+
+  /**
+   * Reads bytes from an established stream until it ends, errors, or is
+   * superseded by a newer connection.
+   */
+  private async readStream(reader: ReadableStreamDefaultReader<Uint8Array>, controller: AbortController): Promise<void> {
+    try {
+      while (this.controller === controller) {
+        const { done, value } = await reader.read()
+
+        // abort() or a newer connect() may have landed while we were awaiting.
+        if (this.controller !== controller) return
+
+        if (done) {
+          this.controller = null
+
+          await this.notifyDisconnected()
+
+          if (this.options.persistent) {
+            // Server closed gracefully — reopen unless the consumer opted out.
+            await this.connect()
+          } else {
+            this.messages.close()
+          }
+
+          return
+        }
+
+        // Some environments yield `{ done: false, value: undefined }`.
+        if (!value) continue
+
+        for (const event of this.options.eventParser.parseEvents(value)) {
+          this.emit('message', event)
+          this.messages.push(event)
+        }
+      }
+    } catch (error) {
+      // If the controller is different, we already started a new connection and it would be confusing to handle this error.
+      if (controller !== this.controller) return
+
+      // Invalidate the current controller to allow for reconnection if needed
+      this.controller = null
+
+      await this.notifyDisconnected()
+
+      // Expected path for abort() — do not treat as an error or reconnect.
+      if (controller.signal.aborted) return
+
+      await this.notifyError(error)
+
+      if (this.options.attemptReconnect) {
+        await this.connect()
+      } else {
+        this.messages.close()
+      }
+    }
+  }
+
+  /** Invokes {@link SSESessionOptions.onDisconnected} and emits `"disconnected"`. */
+  private async notifyDisconnected(): Promise<void> {
+    await SSESession.tryAsync(
+      () => this.options.onDisconnected(),
+      (error) => this.options.onError(error),
+    )
+    this.emit('disconnected', undefined)
+  }
+
+  /** Invokes {@link SSESessionOptions.onError} and emits `"error"`. */
+  private async notifyError(error: unknown): Promise<void> {
+    const errorInstance = error instanceof Error ? error : new Error(String(error))
+
+    await SSESession.tryAsync(
+      () => this.options.onError(errorInstance),
+      (callbackError) => console.error('SSESession error:', callbackError),
+    )
+    this.emit('error', errorInstance)
+  }
+
+  /** Runs `fn`, passing any error to `onError` instead of throwing. */
+  private static async tryAsync(fn: () => unknown, onError?: (error: Error) => void): Promise<void> {
+    try {
+      await fn()
+    } catch (error) {
+      onError?.(error instanceof Error ? error : new Error(`${error}`))
+    }
+  }
+}

src/utils/sse-session/types.ts

@@ -0,0 +1,145 @@
+// Vendored from https://git.harvmaster.com/Harvmaster/sse-session (commit c08267e85c).
+// Local changes: import paths, uses ../event-emitter.ts, tryAsync folded into SSESession.
+
+export type SSERequestInit = {
+  /**
+   * The HTTP method to use.
+   */
+  method: 'GET' | 'POST'
+
+  /**
+   * Request headers sent on every connect and reconnect.
+   */
+  headers?: Record<string, string>
+
+  /**
+   * Request body for POST-based SSE endpoints.
+   */
+  body?: string | FormData
+}
+
+/**
+ * The fetch function to use.
+ *
+ * NOTE: This is compatible with Browser/Node's native "fetch" function.
+ *       We use this in place of "typeof fetch" so that we can accept non-standard URLs ("url" is a "string" here).
+ *       For example, a LibP2P adapter might not use a standardized URL format (and might only include "path").
+ *       This would cause a type error as native fetch expects type "URL".
+ */
+export type SSERequestFunction = {
+  fetch: (url: string, options: RequestInit) => Promise<Response>
+}
+
+/**
+ * Lifecycle hooks invoked by {@link SSESession} during connect, read, and teardown.
+ */
+export type SSESessionCallbacks = {
+  /**
+   * Called before each fetch so callers can attach auth headers, cookies, or
+   * a `Last-Event-ID` for resume semantics.
+   */
+  onRequest: (request: RequestInit) => Promise<RequestInit>
+
+  /**
+   * Called after the HTTP stream is established and before body reading begins.
+   */
+  onConnected: () => void
+
+  /**
+   * Called when the active transport ends — including {@link SSESession.abort},
+   * server stream completion, and errors. Not paired with {@link SSESessionCallbacks.onConnected}
+   * when the initial connect never succeeds.
+   */
+  onDisconnected: () => void
+
+  /**
+   * Called on fetch or read failures. Not invoked for intentional
+   * {@link SSESession.abort} aborts.
+   */
+  onError: (error: Error) => void
+}
+
+export type SSESessionRetryInterface = {
+  /**
+   * Retry policy used while establishing the HTTP connection in
+   * {@link SSESession.connect}. Defaults to {@link ExponentialBackoff} with
+   * unlimited attempts.
+   */
+  retry: {
+    run<T>(fn: () => Promise<T>, onError?: (error: Error) => void): Promise<T>
+  }
+}
+
+export interface SSEParser {
+  /**
+   * Incremental SSE frame parser for the response body.
+   *
+   * {@link SSEEventParser.reset} is called by the session when abandoning a
+   * transport so partial frames do not carry over to the next connection.
+   */
+  eventParser: {
+    parseEvents(buffer: Uint8Array): SSEvent[]
+    reset(): void
+  }
+}
+
+export type SSELifecycleOptions = {
+  /**
+   * When true, {@link SSESession} calls {@link SSESession.connect} again after
+   * a transport **error** (not an intentional abort).
+   */
+  attemptReconnect: boolean
+
+  /**
+   * When true, {@link SSESession} calls {@link SSESession.connect} again after
+   * the **server** closes the stream normally (`done`).
+   */
+  persistent: boolean
+}
+
+/**
+ * Events emitted by {@link SSESession}.
+ *
+ * - `"connected"` — HTTP stream established.
+ * - `"message"` — A complete SSE event was parsed.
+ * - `"disconnected"` — The active transport ended (including {@link SSESession.abort}).
+ * - `"error"` — An unexpected fetch or read failure.
+ * - `"closed"` — {@link SSESession.disconnect} was called; visibility handling is detached.
+ */
+export type SSESessionEventMap = {
+  connected: void
+  disconnected: void
+  error: Error
+  message: SSEvent
+  closed: void
+}
+
+/**
+ * Configuration for {@link SSESession}.
+ */
+export type SSESessionOptions = SSESessionCallbacks & SSERequestInit & SSERequestFunction & SSESessionRetryInterface & SSELifecycleOptions & SSEParser
+
+/**
+ * Represents a Server-Sent Event.
+ */
+export interface SSEvent {
+  /**
+   * Event data.
+   */
+  data: string
+
+  /**
+   * Event type.
+   */
+  event?: string
+
+  /**
+   * Event ID.
+   */
+  id?: string
+
+  /**
+   * Reconnection time in milliseconds.
+   */
+  retry?: number
+}