@tanstack/ai-client 0.22.1 → 0.23.0

package/dist/esm/connection-adapters.js

@@ -1,611 +1,1026 @@
-import { EventType, uiMessagesToWire } from "@tanstack/ai/client";
-import { getResponseStreamReader, createResponseStreamTextDecoder } from "./response-stream.js";
+import { createResponseStreamTextDecoder, getResponseStreamReader } from "./response-stream.js";
 import { parseSseDataLine } from "./sse-utils.js";
-const chunkRunIds = /* @__PURE__ */ new WeakMap();
+import { EventType, uiMessagesToWire } from "@tanstack/ai/client";
+//#region src/connection-adapters.ts
+/**
+* Associates connect-wrapped chunks with the run they were produced under.
+* Content events (TEXT_MESSAGE_CONTENT, TOOL_CALL_*, …) carry no `runId` of
+* their own, so the connect wrapper stamps the caller's run id here. Lets
+* run-scoped consumers (e.g. clear-during-stream suppression) attribute those
+* otherwise-runless chunks to their originating request.
+*/
+var chunkRunIds = /* @__PURE__ */ new WeakMap();
+/**
+* Resolve a chunk's run id, preferring the value on the chunk itself
+* (RUN_STARTED / RUN_FINISHED / RUN_ERROR carry one) and falling back to the
+* run the connect wrapper stamped it with.
+*/
 function getChunkRunId(chunk) {
-  return "runId" in chunk && typeof chunk.runId === "string" ? chunk.runId : chunkRunIds.get(chunk);
+	return chunkRunIds.get(chunk) ?? ("runId" in chunk && typeof chunk.runId === "string" ? chunk.runId : void 0);
+}
+/**
+* Thrown when an SSE/HTTP stream ends with a non-empty unterminated buffer.
+* Indicates the connection was cut mid-line (server crash, dropped TCP, proxy
+* timeout) so the partial content cannot be safely parsed.
+*/
+var StreamTruncatedError = class extends Error {
+	constructor() {
+		super("Stream ended with unterminated trailing data — connection was likely cut short.");
+		this.name = "StreamTruncatedError";
+	}
+};
+var StreamReadError = class extends Error {
+	constructor(cause) {
+		super("Stream response body read failed", { cause });
+		this.name = "StreamReadError";
+	}
+};
+/**
+* Thrown when a durable (id-tagged) run's stream ends with no terminal event
+* and a reconnect makes no forward progress — the run cannot complete, so the
+* consumer must not be left silently hanging on a stream that just stops.
+*/
+var DurableStreamIncompleteError = class extends Error {
+	constructor() {
+		super("Durable run ended without a terminal event and could not resume — the run did not complete.");
+		this.name = "DurableStreamIncompleteError";
+	}
+};
+/**
+* Thrown when a durable run exceeds its reconnect ceiling. Bounds the
+* otherwise-unbounded reconnect loop so a flapping producer (or a proxy that
+* rolls the socket after every event) surfaces a failure instead of
+* reconnecting without end.
+*/
+var StreamReconnectLimitError = class extends Error {
+	constructor(attempts) {
+		super(`Durable run exceeded its reconnect ceiling of ${attempts} attempts — giving up.`);
+		this.name = "StreamReconnectLimitError";
+	}
+};
+function resolveReconnectOptions(options) {
+	const maxAttempts = options?.maxAttempts ?? 5;
+	const delayMs = options?.delayMs ?? 250;
+	if (!Number.isInteger(maxAttempts) || maxAttempts < 0) throw new Error(`Invalid reconnect.maxAttempts: ${maxAttempts}. Must be a non-negative integer.`);
+	if (!Number.isFinite(delayMs) || delayMs < 0) throw new Error(`Invalid reconnect.delayMs: ${delayMs}. Must be a non-negative finite number.`);
+	return {
+		maxAttempts,
+		delayMs
+	};
 }
-class StreamTruncatedError extends Error {
-  constructor() {
-    super(
-      "Stream ended with unterminated trailing data — connection was likely cut short."
-    );
-    this.name = "StreamTruncatedError";
-  }
+/** Resolve after `ms`, or immediately once `signal` aborts. Never rejects. */
+function abortableDelay(ms, signal) {
+	if (ms <= 0 || signal?.aborted) return Promise.resolve();
+	return new Promise((resolve) => {
+		const onAbort = () => {
+			clearTimeout(timer);
+			resolve();
+		};
+		const timer = setTimeout(() => {
+			signal?.removeEventListener("abort", onAbort);
+			resolve();
+		}, ms);
+		signal?.addEventListener("abort", onAbort, { once: true });
+	});
 }
 function generateRunId(prefix) {
-  return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+	return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
 }
+/**
+* Asserts an id is present when synthesizing a terminal event. The chat
+* client always supplies `runContext.threadId` / `runContext.runId`, so an
+* absent id at this layer indicates the adapter was wired up by a caller
+* that bypassed that contract — surface it rather than fabricating one.
+*/
 function requireSyntheticId(value, field) {
-  if (!value) {
-    throw new Error(
-      `Cannot synthesize terminal event: ${field} not supplied via runContext and not observed in the upstream stream.`
-    );
-  }
-  return value;
+	if (!value) throw new Error(`Cannot synthesize terminal event: ${field} not supplied via runContext and not observed in the upstream stream.`);
+	return value;
 }
+/**
+* Merge custom headers into request headers
+*/
 function mergeHeaders(customHeaders) {
-  if (!customHeaders) {
-    return {};
-  }
-  if (customHeaders instanceof Headers) {
-    const result = {};
-    customHeaders.forEach((value, key) => {
-      result[key] = value;
-    });
-    return result;
-  }
-  return customHeaders;
+	if (!customHeaders) return {};
+	if (customHeaders instanceof Headers) {
+		const result = {};
+		customHeaders.forEach((value, key) => {
+			result[key] = value;
+		});
+		return result;
+	}
+	return customHeaders;
 }
+/**
+* Request header carrying the client-chosen run id to a delivery-durability
+* sink. The durable log is then keyed by the SAME id the client already holds,
+* so a later join/resume can address the run without first reading back a
+* server-generated id. Sent as a header — NOT a query param — so the POST URL
+* stays byte-identical to a plain, non-durable request; a server that isn't
+* durable simply ignores the header. (The GET join path keeps `?runId` in the
+* query, since a GET has no body/handler contract to disturb.)
+*/
+var RUN_ID_HEADER = "X-Run-Id";
+function runIdHeader(runId) {
+	return runId === void 0 ? {} : { [RUN_ID_HEADER]: runId };
+}
+function withSearchParams(url, values) {
+	const hashIndex = url.indexOf("#");
+	const hash = hashIndex === -1 ? "" : url.slice(hashIndex);
+	const withoutHash = hashIndex === -1 ? url : url.slice(0, hashIndex);
+	const queryIndex = withoutHash.indexOf("?");
+	const base = queryIndex === -1 ? withoutHash : withoutHash.slice(0, queryIndex);
+	const search = new URLSearchParams(queryIndex === -1 ? "" : withoutHash.slice(queryIndex + 1));
+	for (const [key, value] of Object.entries(values)) search.set(key, value);
+	const query = search.toString();
+	return `${base}${query.length === 0 ? "" : `?${query}`}${hash}`;
+}
+/**
+* Read lines from a stream (newline-delimited)
+*/
 async function* readStreamLines(reader, abortSignal) {
-  try {
-    const decoder = createResponseStreamTextDecoder();
-    let buffer = "";
-    while (!abortSignal?.aborted) {
-      const { done, value } = await reader.read();
-      if (done) break;
-      buffer += decoder.decode(value, { stream: true });
-      const lines = buffer.split("\n");
-      buffer = lines.pop() || "";
-      for (const line of lines) {
-        if (line.trim()) {
-          yield line;
-        }
-      }
-    }
-    if (buffer.trim() && !abortSignal?.aborted) {
-      throw new StreamTruncatedError();
-    }
-  } finally {
-    reader.releaseLock();
-  }
+	try {
+		const decoder = createResponseStreamTextDecoder();
+		let buffer = "";
+		while (!abortSignal?.aborted) {
+			let result;
+			try {
+				result = await reader.read();
+			} catch (error) {
+				if (abortSignal?.aborted) return;
+				throw new StreamReadError(error);
+			}
+			const { done, value } = result;
+			if (done) break;
+			buffer += decoder.decode(value, { stream: true });
+			const lines = buffer.split("\n");
+			buffer = lines.pop() || "";
+			for (const line of lines) {
+				const normalized = line.endsWith("\r") ? line.slice(0, -1) : line;
+				if (normalized.trim()) yield normalized;
+			}
+		}
+		buffer += decoder.decode();
+		if (buffer.trim() && !abortSignal?.aborted) throw new StreamTruncatedError();
+	} finally {
+		reader.releaseLock();
+	}
+}
+/**
+* Type guard for a durable NDJSON envelope `{ id, chunk }`. NDJSON has no
+* native event-id field, so durability rides the offset inside the payload.
+* A bare `StreamChunk` always has a top-level `type`, and the envelope never
+* does, so the two forms are unambiguous — a non-durable line stays bare.
+*/
+function isNdjsonEnvelope(value) {
+	return typeof value === "object" && value !== null && "chunk" in value && "id" in value && typeof value.id === "string" && !("type" in value);
+}
+/**
+* Parse SSE-format lines into stream events, pairing each chunk with the `id:`
+* offset of the event it arrived on. Shared by the fetch- and XHR-backed SSE
+* adapters so both track delivery offsets identically.
+*
+* Accepts either `data: {...}` lines or bare JSON lines. Skips comments
+* starting with `:` (proxies and CDNs inject these as keepalives) and the
+* `event:` / `retry:` SSE control fields. A `[DONE]` sentinel is treated as a
+* terminal event: a synthesized RUN_FINISHED is yielded using the most recent
+* upstream `threadId` / `runId` (falling back to `fallbackIds`), so the
+* consumer sees a clean terminal event with real correlation ids.
+*
+* A JSON parse failure throws — the consumer surfaces it as an error.
+*/
+async function* linesToSSEEvents(lines, fallbackIds) {
+	let lastThreadId;
+	let lastRunId;
+	let lastModel;
+	let pendingId;
+	for await (const line of lines) {
+		if (line === "id" || line.startsWith("id:")) {
+			const rawId = line === "id" ? "" : line.slice(3);
+			pendingId = rawId.startsWith(" ") ? rawId.slice(1) : rawId;
+			continue;
+		}
+		if (line.startsWith(":") || line.startsWith("event:") || line.startsWith("retry:")) continue;
+		const data = parseSseDataLine(line);
+		if (data === "[DONE]") {
+			yield { chunk: {
+				type: EventType.RUN_FINISHED,
+				threadId: lastThreadId ?? fallbackIds?.threadId ?? "",
+				runId: lastRunId ?? fallbackIds?.runId ?? "",
+				model: lastModel ?? "",
+				timestamp: Date.now(),
+				finishReason: "stop"
+			} };
+			return;
+		}
+		const chunk = JSON.parse(data);
+		if ("threadId" in chunk && typeof chunk.threadId === "string") lastThreadId = chunk.threadId;
+		if ("runId" in chunk && typeof chunk.runId === "string") lastRunId = chunk.runId;
+		if ("model" in chunk && typeof chunk.model === "string") lastModel = chunk.model;
+		const id = pendingId;
+		pendingId = void 0;
+		yield {
+			chunk,
+			...id !== void 0 ? { id } : {}
+		};
+	}
+}
+/**
+* Parse NDJSON-format lines into stream events. Durable streams emit each line
+* as an `{ id, chunk }` envelope carrying the delivery offset; non-durable
+* streams emit bare chunks. Both are auto-detected (see {@link isNdjsonEnvelope}),
+* so an untagged stream behaves exactly as a plain single fetch used to.
+*/
+async function* linesToNdjsonEvents(lines) {
+	for await (const line of lines) {
+		const parsed = JSON.parse(line);
+		if (isNdjsonEnvelope(parsed)) yield {
+			chunk: parsed.chunk,
+			id: parsed.id
+		};
+		else yield { chunk: parsed };
+	}
+}
+function assertResponseOk(response) {
+	if (!response.ok) throw new Error(`HTTP error! status: ${response.status} ${response.statusText}`);
+}
+/**
+* GET the hydration endpoint for a thread and parse its JSON `{ messages,
+* activeRun }` body. This is the transport-agnostic reconnect probe: keyed on
+* the STABLE thread id, it returns the stored transcript and — if a run is still
+* generating — a cursor the caller tails via `joinRun`. Shared by every fetch/
+* XHR adapter so the client never has to know which transport is in use.
+*/
+async function fetchThreadHydration(fetchClient, url, headers, credentials, threadId) {
+	const response = await fetchClient(withSearchParams(url, { threadId }), {
+		method: "GET",
+		headers: {
+			Accept: "application/json",
+			...headers
+		},
+		credentials
+	});
+	assertResponseOk(response);
+	const data = await response.json();
+	const activeRun = data.activeRun && typeof data.activeRun.runId === "string" ? { runId: data.activeRun.runId } : null;
+	const interrupts = data.interrupts && typeof data.interrupts.runId === "string" && Array.isArray(data.interrupts.pending) && data.interrupts.pending.length > 0 ? {
+		runId: data.interrupts.runId,
+		pending: data.interrupts.pending
+	} : null;
+	return {
+		messages: Array.isArray(data.messages) ? data.messages : [],
+		activeRun,
+		interrupts
+	};
+}
+/**
+* GET the hydration endpoint for a generation thread and parse its JSON
+* `{ resumeSnapshot, activeRun }` body. Mirrors {@link fetchThreadHydration} for
+* the generation clients: keyed on the stable thread id, it returns the last
+* generation's resume snapshot (re-validated client-side before adoption) and —
+* if a run is still generating — a cursor. Shared by every fetch/XHR adapter.
+*/
+async function fetchGenerationHydration(fetchClient, url, headers, credentials, threadId) {
+	const response = await fetchClient(withSearchParams(url, { threadId }), {
+		method: "GET",
+		headers: {
+			Accept: "application/json",
+			...headers
+		},
+		credentials
+	});
+	assertResponseOk(response);
+	const raw = await response.json();
+	if (raw === null) return {
+		resumeSnapshot: null,
+		activeRun: null
+	};
+	if (typeof raw !== "object" || Array.isArray(raw)) throw new Error(`Generation hydration expected a JSON object from ${url}, received ${Array.isArray(raw) ? "an array" : typeof raw}.`);
+	const data = raw;
+	const activeRun = data.activeRun && typeof data.activeRun.runId === "string" ? { runId: data.activeRun.runId } : null;
+	return {
+		resumeSnapshot: data.resumeSnapshot ?? null,
+		activeRun
+	};
+}
+/** Yield SSE stream events (chunk + offset) from a fetch Response body. */
+async function* responseToSSEEvents(response, abortSignal, fallbackIds) {
+	assertResponseOk(response);
+	yield* linesToSSEEvents(readStreamLines(getResponseStreamReader(response), abortSignal), fallbackIds);
+}
+/** Yield NDJSON stream events (chunk + offset) from a fetch Response body. */
+async function* responseToNdjsonEvents(response, abortSignal) {
+	assertResponseOk(response);
+	yield* linesToNdjsonEvents(readStreamLines(getResponseStreamReader(response), abortSignal));
 }
 async function* responseToSSEChunks(response, abortSignal) {
-  if (!response.ok) {
-    throw new Error(
-      `HTTP error! status: ${response.status} ${response.statusText}`
-    );
-  }
-  const reader = getResponseStreamReader(response);
-  let lastThreadId;
-  let lastRunId;
-  let lastModel;
-  for await (const line of readStreamLines(reader, abortSignal)) {
-    if (line.startsWith(":") || line.startsWith("event:") || line.startsWith("id:") || line.startsWith("retry:")) {
-      continue;
-    }
-    const data = parseSseDataLine(line);
-    if (data === "[DONE]") {
-      const synthetic = {
-        type: EventType.RUN_FINISHED,
-        threadId: lastThreadId ?? "",
-        runId: lastRunId ?? "",
-        model: lastModel ?? "",
-        timestamp: Date.now(),
-        finishReason: "stop"
-      };
-      yield synthetic;
-      return;
-    }
-    const chunk = JSON.parse(data);
-    if ("threadId" in chunk && typeof chunk.threadId === "string") {
-      lastThreadId = chunk.threadId;
-    }
-    if ("runId" in chunk && typeof chunk.runId === "string") {
-      lastRunId = chunk.runId;
-    }
-    if ("model" in chunk && typeof chunk.model === "string") {
-      lastModel = chunk.model;
-    }
-    yield chunk;
-  }
+	for await (const { chunk } of responseToSSEEvents(response, abortSignal)) yield chunk;
 }
+/**
+* Build a fetch-backed {@link StreamEventSource}. `parseResponse` decodes the
+* body into events (SSE or NDJSON) — the reconnect engine is identical for both.
+*/
+function fetchEventSource(fetchClient, url, requestInit, parseResponse) {
+	return async function* (extraHeaders, abortSignal) {
+		let response;
+		try {
+			response = await fetchClient(url, {
+				...requestInit,
+				headers: {
+					...requestInit.headers,
+					...extraHeaders
+				},
+				...abortSignal ? { signal: abortSignal } : {}
+			});
+		} catch (error) {
+			throw new StreamReadError(error);
+		}
+		yield* parseResponse(response, abortSignal);
+	};
+}
+/**
+* Drive a {@link StreamEventSource} with native-style resumability. Each event's
+* adapter-owned delivery offset (its `id`) is remembered; if the connection
+* drops or ends before a terminal event, the source is re-opened with a
+* `Last-Event-ID` header so the server replays strictly after the last offset.
+* Already-seen offsets are de-duped, so an overlapping replay is safe.
+*
+* When the server does NOT tag events (no durability), no offset is ever seen,
+* so no reconnect happens — behaviour is identical to a plain single request.
+* This engine is transport-agnostic: fetch/XHR × SSE/NDJSON all share it, the
+* only difference being the {@link StreamEventSource} they pass in.
+*/
+async function* resumableStream(openEventSource, abortSignal, reconnectOptions) {
+	const seen = /* @__PURE__ */ new Set();
+	let lastEventId;
+	const reconnect = resolveReconnectOptions(reconnectOptions);
+	let reconnectAttempts = 0;
+	async function waitBeforeReconnect(madeProgress) {
+		if (madeProgress) reconnectAttempts = 0;
+		else {
+			reconnectAttempts += 1;
+			if (reconnectAttempts > reconnect.maxAttempts) throw new StreamReconnectLimitError(reconnect.maxAttempts);
+		}
+		await abortableDelay(reconnect.delayMs, abortSignal);
+	}
+	for (;;) {
+		if (abortSignal?.aborted) return;
+		const extraHeaders = lastEventId !== void 0 ? { "Last-Event-ID": lastEventId } : {};
+		let sawTerminal = false;
+		let progressed = false;
+		try {
+			for await (const { chunk, id } of openEventSource(extraHeaders, abortSignal)) {
+				if (id !== void 0) if (id === "") {
+					lastEventId = void 0;
+					seen.clear();
+				} else {
+					if (seen.has(id)) continue;
+					seen.add(id);
+					lastEventId = id;
+				}
+				progressed = true;
+				if (chunk.type === "RUN_FINISHED" || chunk.type === "RUN_ERROR") sawTerminal = true;
+				yield chunk;
+			}
+		} catch (error) {
+			if (abortSignal?.aborted) return;
+			if ((error instanceof StreamTruncatedError || error instanceof StreamReadError) && lastEventId !== void 0) {
+				await waitBeforeReconnect(progressed);
+				continue;
+			}
+			throw error;
+		}
+		if (abortSignal?.aborted) return;
+		if (sawTerminal) return;
+		if (lastEventId !== void 0) {
+			if (progressed) {
+				await waitBeforeReconnect(true);
+				continue;
+			}
+			throw new DurableStreamIncompleteError();
+		}
+		return;
+	}
+}
+/**
+* Normalize a ConnectionAdapter to subscribe/send operations.
+*
+* If a connection provides native subscribe/send, that mode is used.
+* Otherwise, connect() is wrapped using an async queue.
+*/
 function normalizeConnectionAdapter(connection) {
-  if (!connection) {
-    throw new Error("Connection adapter is required");
-  }
-  const hasConnect = "connect" in connection;
-  const hasSubscribe = "subscribe" in connection;
-  const hasSend = "send" in connection;
-  if (hasConnect && (hasSubscribe || hasSend)) {
-    throw new Error(
-      "Connection adapter must provide either connect or both subscribe and send, not both modes"
-    );
-  }
-  if (hasSubscribe && hasSend) {
-    return {
-      subscribe: connection.subscribe.bind(connection),
-      send: connection.send.bind(connection)
-    };
-  }
-  if (!hasConnect) {
-    throw new Error(
-      "Connection adapter must provide either connect or both subscribe and send"
-    );
-  }
-  let activeBuffer = [];
-  let activeWaiters = [];
-  function push(chunk, runId) {
-    if (runId) {
-      chunkRunIds.set(chunk, runId);
-    }
-    const waiter = activeWaiters.shift();
-    if (waiter) {
-      waiter(chunk);
-    } else {
-      activeBuffer.push(chunk);
-    }
-  }
-  return {
-    subscribe(abortSignal) {
-      const myBuffer = activeBuffer.splice(0);
-      const myWaiters = [];
-      activeBuffer = myBuffer;
-      activeWaiters = myWaiters;
-      return (async function* () {
-        while (!abortSignal?.aborted) {
-          let chunk;
-          const buffered = myBuffer.shift();
-          if (buffered !== void 0) {
-            chunk = buffered;
-          } else {
-            chunk = await new Promise((resolve) => {
-              const onAbort = () => resolve(null);
-              myWaiters.push((c) => {
-                abortSignal?.removeEventListener("abort", onAbort);
-                resolve(c);
-              });
-              abortSignal?.addEventListener("abort", onAbort, { once: true });
-            });
-          }
-          if (chunk !== null) yield chunk;
-        }
-      })();
-    },
-    async send(messages, data, abortSignal, runContext) {
-      let hasTerminalEvent = false;
-      let upstreamThreadId;
-      let upstreamRunId;
-      try {
-        const stream2 = connection.connect(
-          messages,
-          data,
-          abortSignal,
-          runContext
-        );
-        for await (const chunk of stream2) {
-          if ("threadId" in chunk && typeof chunk.threadId === "string") {
-            upstreamThreadId = chunk.threadId;
-          }
-          if ("runId" in chunk && typeof chunk.runId === "string") {
-            upstreamRunId = chunk.runId;
-          }
-          if (chunk.type === "RUN_FINISHED" || chunk.type === "RUN_ERROR") {
-            hasTerminalEvent = true;
-          }
-          push(chunk, runContext?.runId);
-        }
-        if (!abortSignal?.aborted && !hasTerminalEvent) {
-          const synthetic = {
-            type: EventType.RUN_FINISHED,
-            threadId: requireSyntheticId(
-              upstreamThreadId ?? runContext?.threadId,
-              "threadId"
-            ),
-            runId: requireSyntheticId(
-              upstreamRunId ?? runContext?.runId,
-              "runId"
-            ),
-            model: "connect-wrapper",
-            timestamp: Date.now(),
-            finishReason: "stop"
-          };
-          push(synthetic);
-        }
-      } catch (err) {
-        if (!abortSignal?.aborted && !hasTerminalEvent) {
-          const message = err instanceof Error ? err.message : "Unknown error in connect()";
-          const synthetic = {
-            type: EventType.RUN_ERROR,
-            threadId: requireSyntheticId(
-              upstreamThreadId ?? runContext?.threadId,
-              "threadId"
-            ),
-            runId: requireSyntheticId(
-              upstreamRunId ?? runContext?.runId,
-              "runId"
-            ),
-            timestamp: Date.now(),
-            message
-          };
-          push(synthetic);
-        }
-        throw err;
-      }
-    }
-  };
+	if (!connection) throw new Error("Connection adapter is required");
+	const hasConnect = "connect" in connection;
+	const hasSubscribe = "subscribe" in connection;
+	const hasSend = "send" in connection;
+	if (hasConnect && (hasSubscribe || hasSend)) throw new Error("Connection adapter must provide either connect or both subscribe and send, not both modes");
+	if (hasSubscribe && hasSend) {
+		const joinRun = connection.joinRun?.bind(connection);
+		const hydrate = connection.hydrate?.bind(connection);
+		return {
+			subscribe: connection.subscribe.bind(connection),
+			send: connection.send.bind(connection),
+			...joinRun ? { joinRun } : {},
+			...hydrate ? { hydrate } : {}
+		};
+	}
+	if (!hasConnect) throw new Error("Connection adapter must provide either connect or both subscribe and send");
+	let activeBuffer = [];
+	let activeWaiters = [];
+	function push(chunk, runId) {
+		if (runId) chunkRunIds.set(chunk, runId);
+		const waiter = activeWaiters.shift();
+		if (waiter) waiter(chunk);
+		else activeBuffer.push(chunk);
+	}
+	return {
+		subscribe(abortSignal) {
+			const myBuffer = activeBuffer.splice(0);
+			const myWaiters = [];
+			activeBuffer = myBuffer;
+			activeWaiters = myWaiters;
+			return (async function* () {
+				while (!abortSignal?.aborted) {
+					let chunk;
+					const buffered = myBuffer.shift();
+					if (buffered !== void 0) chunk = buffered;
+					else chunk = await new Promise((resolve) => {
+						const onAbort = () => resolve(null);
+						myWaiters.push((c) => {
+							abortSignal?.removeEventListener("abort", onAbort);
+							resolve(c);
+						});
+						abortSignal?.addEventListener("abort", onAbort, { once: true });
+					});
+					if (chunk !== null) yield chunk;
+				}
+			})();
+		},
+		async send(messages, data, abortSignal, runContext) {
+			let hasTerminalEvent = false;
+			let upstreamThreadId;
+			let upstreamRunId;
+			try {
+				const stream = connection.connect(messages, data, abortSignal, runContext);
+				for await (const chunk of stream) {
+					if ("threadId" in chunk && typeof chunk.threadId === "string") upstreamThreadId = chunk.threadId;
+					if ("runId" in chunk && typeof chunk.runId === "string") upstreamRunId = chunk.runId;
+					if (chunk.type === "RUN_FINISHED" || chunk.type === "RUN_ERROR") hasTerminalEvent = true;
+					push(chunk, runContext?.runId);
+				}
+				if (!abortSignal?.aborted && !hasTerminalEvent) push({
+					type: EventType.RUN_FINISHED,
+					threadId: requireSyntheticId(upstreamThreadId ?? runContext?.threadId, "threadId"),
+					runId: requireSyntheticId(upstreamRunId ?? runContext?.runId, "runId"),
+					model: "connect-wrapper",
+					timestamp: Date.now(),
+					finishReason: "stop"
+				});
+			} catch (err) {
+				if (!abortSignal?.aborted && !hasTerminalEvent) try {
+					const message = err instanceof Error ? err.message : "Unknown error in connect()";
+					push({
+						type: EventType.RUN_ERROR,
+						threadId: requireSyntheticId(upstreamThreadId ?? runContext?.threadId, "threadId"),
+						runId: requireSyntheticId(upstreamRunId ?? runContext?.runId, "runId"),
+						timestamp: Date.now(),
+						message
+					});
+				} catch {}
+				throw err;
+			}
+		},
+		...typeof connection.joinRun === "function" ? { joinRun: (runId, abortSignal) => connection.joinRun(runId, abortSignal) } : {},
+		...(() => {
+			const hydrate = connection.hydrate;
+			return typeof hydrate === "function" ? { hydrate: (threadId) => hydrate(threadId) } : {};
+		})()
+	};
 }
 function buildRunAgentInputBody(messages, data, runContext, options) {
-  const wireMessages = uiMessagesToWire(messages);
-  const forwardedProps = {
-    ...options.body,
-    ...runContext?.forwardedProps ?? {},
-    ...data
-  };
-  return {
-    threadId: runContext?.threadId ?? generateRunId("thread"),
-    runId: runContext?.runId ?? generateRunId("run"),
-    ...runContext?.parentRunId !== void 0 && {
-      parentRunId: runContext.parentRunId
-    },
-    state: {},
-    messages: wireMessages,
-    tools: runContext?.clientTools ?? [],
-    context: [],
-    forwardedProps,
-    // Backward-compat mirror of `forwardedProps` under the legacy field name.
-    data: { ...forwardedProps }
-  };
+	const wireMessages = uiMessagesToWire(messages);
+	const forwardedProps = {
+		...options.body,
+		...runContext?.forwardedProps ?? {},
+		...data
+	};
+	return {
+		threadId: runContext?.threadId ?? generateRunId("thread"),
+		runId: runContext?.runId ?? generateRunId("run"),
+		...runContext?.parentRunId !== void 0 && { parentRunId: runContext.parentRunId },
+		...runContext?.resume !== void 0 && { resume: runContext.resume },
+		state: {},
+		messages: wireMessages,
+		tools: runContext?.clientTools ?? [],
+		context: [],
+		forwardedProps,
+		data: { ...forwardedProps }
+	};
 }
+/**
+* Create a Server-Sent Events connection adapter
+*
+* @param url - The API endpoint URL (or a function that returns the URL)
+* @param options - Fetch options (headers, credentials, body, etc.) or a function that returns options (can be async)
+* @returns A connection adapter for SSE streams
+*
+* @example
+* ```typescript
+* // Static URL
+* const connection = fetchServerSentEvents('/api/chat');
+*
+* // Dynamic URL
+* const connection = fetchServerSentEvents(() => `/api/chat?user=${userId}`);
+*
+* // With options
+* const connection = fetchServerSentEvents('/api/chat', {
+*   headers: { 'Authorization': 'Bearer token' }
+* });
+*
+* // With dynamic options
+* const connection = fetchServerSentEvents('/api/chat', () => ({
+*   headers: { 'Authorization': `Bearer ${getToken()}` }
+* }));
+*
+* // With additional body data
+* const connection = fetchServerSentEvents('/api/chat', async () => ({
+*   body: {
+*     provider: 'openai',
+*     model: 'gpt-5.5',
+*   }
+* }));
+* ```
+*/
 function fetchServerSentEvents(url, options = {}) {
-  return {
-    async *connect(messages, data, abortSignal, runContext) {
-      const resolvedUrl = typeof url === "function" ? url() : url;
-      const resolvedOptions = typeof options === "function" ? await options() : options;
-      const requestHeaders = {
-        "Content-Type": "application/json",
-        ...mergeHeaders(resolvedOptions.headers)
-      };
-      const requestBody = buildRunAgentInputBody(
-        messages,
-        data,
-        runContext,
-        resolvedOptions
-      );
-      const fetchClient = resolvedOptions.fetchClient ?? fetch;
-      const signal = abortSignal || resolvedOptions.signal;
-      const response = await fetchClient(resolvedUrl, {
-        method: "POST",
-        headers: requestHeaders,
-        body: JSON.stringify(requestBody),
-        credentials: resolvedOptions.credentials || "same-origin",
-        ...signal ? { signal } : {}
-      });
-      yield* responseToSSEChunks(response, abortSignal);
-    }
-  };
+	return {
+		async *connect(messages, data, abortSignal, runContext) {
+			const resolvedUrl = typeof url === "function" ? url() : url;
+			const resolvedOptions = typeof options === "function" ? await options() : options;
+			const requestHeaders = {
+				"Content-Type": "application/json",
+				...mergeHeaders(resolvedOptions.headers),
+				...runIdHeader(runContext?.runId)
+			};
+			const requestBody = buildRunAgentInputBody(messages, data, runContext, resolvedOptions);
+			const fetchClient = resolvedOptions.fetchClient ?? fetch;
+			const signal = abortSignal || resolvedOptions.signal;
+			yield* resumableStream(fetchEventSource(fetchClient, resolvedUrl, {
+				method: "POST",
+				headers: requestHeaders,
+				body: JSON.stringify(requestBody),
+				credentials: resolvedOptions.credentials || "same-origin"
+			}, (response, sseSignal) => responseToSSEEvents(response, sseSignal, {
+				...runContext?.threadId !== void 0 ? { threadId: runContext.threadId } : {},
+				...runContext?.runId !== void 0 ? { runId: runContext.runId } : {}
+			})), signal, resolvedOptions.reconnect);
+		},
+		async *joinRun(runId, abortSignal) {
+			const resolvedUrl = typeof url === "function" ? url() : url;
+			const resolvedOptions = typeof options === "function" ? await options() : options;
+			const joinUrl = withSearchParams(resolvedUrl, {
+				offset: "-1",
+				runId
+			});
+			const requestHeaders = { ...mergeHeaders(resolvedOptions.headers) };
+			const fetchClient = resolvedOptions.fetchClient ?? fetch;
+			const signal = abortSignal || resolvedOptions.signal;
+			yield* resumableStream(fetchEventSource(fetchClient, joinUrl, {
+				method: "GET",
+				headers: requestHeaders,
+				credentials: resolvedOptions.credentials || "same-origin"
+			}, (response, sseSignal) => responseToSSEEvents(response, sseSignal, { runId })), signal, resolvedOptions.reconnect);
+		},
+		async hydrate(threadId) {
+			const resolvedUrl = typeof url === "function" ? url() : url;
+			const resolvedOptions = typeof options === "function" ? await options() : options;
+			return fetchThreadHydration(resolvedOptions.fetchClient ?? fetch, resolvedUrl, mergeHeaders(resolvedOptions.headers), resolvedOptions.credentials || "same-origin", threadId);
+		},
+		async hydrateGeneration(threadId) {
+			const resolvedUrl = typeof url === "function" ? url() : url;
+			const resolvedOptions = typeof options === "function" ? await options() : options;
+			return fetchGenerationHydration(resolvedOptions.fetchClient ?? fetch, resolvedUrl, mergeHeaders(resolvedOptions.headers), resolvedOptions.credentials || "same-origin", threadId);
+		}
+	};
 }
+/**
+* Create an HTTP streaming connection adapter (for raw streaming without SSE format)
+*
+* @param url - The API endpoint URL (or a function that returns the URL)
+* @param options - Fetch options (headers, credentials, body, etc.) or a function that returns options (can be async)
+* @returns A connection adapter for HTTP streams
+*
+* @example
+* ```typescript
+* // Static URL
+* const connection = fetchHttpStream('/api/chat');
+*
+* // Dynamic URL
+* const connection = fetchHttpStream(() => `/api/chat?user=${userId}`);
+*
+* // With options
+* const connection = fetchHttpStream('/api/chat', {
+*   headers: { 'Authorization': 'Bearer token' }
+* });
+*
+* // With dynamic options
+* const connection = fetchHttpStream('/api/chat', () => ({
+*   headers: { 'Authorization': `Bearer ${getToken()}` }
+* }));
+*
+* // With additional body data
+* const connection = fetchHttpStream('/api/chat', async () => ({
+*   body: {
+*     provider: 'openai',
+*     model: 'gpt-5.5',
+*   }
+* }));
+* ```
+*/
 function fetchHttpStream(url, options = {}) {
-  return {
-    async *connect(messages, data, abortSignal, runContext) {
-      const resolvedUrl = typeof url === "function" ? url() : url;
-      const resolvedOptions = typeof options === "function" ? await options() : options;
-      const requestHeaders = {
-        "Content-Type": "application/json",
-        ...mergeHeaders(resolvedOptions.headers)
-      };
-      const requestBody = buildRunAgentInputBody(
-        messages,
-        data,
-        runContext,
-        resolvedOptions
-      );
-      const fetchClient = resolvedOptions.fetchClient ?? fetch;
-      const signal = abortSignal || resolvedOptions.signal;
-      const response = await fetchClient(resolvedUrl, {
-        method: "POST",
-        headers: requestHeaders,
-        body: JSON.stringify(requestBody),
-        credentials: resolvedOptions.credentials || "same-origin",
-        ...signal ? { signal } : {}
-      });
-      if (!response.ok) {
-        throw new Error(
-          `HTTP error! status: ${response.status} ${response.statusText}`
-        );
-      }
-      const reader = getResponseStreamReader(response);
-      for await (const line of readStreamLines(reader, abortSignal)) {
-        yield JSON.parse(line);
-      }
-    }
-  };
+	return {
+		async *connect(messages, data, abortSignal, runContext) {
+			const resolvedUrl = typeof url === "function" ? url() : url;
+			const resolvedOptions = typeof options === "function" ? await options() : options;
+			const requestHeaders = {
+				"Content-Type": "application/json",
+				...mergeHeaders(resolvedOptions.headers),
+				...runIdHeader(runContext?.runId)
+			};
+			const requestBody = buildRunAgentInputBody(messages, data, runContext, resolvedOptions);
+			const fetchClient = resolvedOptions.fetchClient ?? fetch;
+			const signal = abortSignal || resolvedOptions.signal;
+			yield* resumableStream(fetchEventSource(fetchClient, resolvedUrl, {
+				method: "POST",
+				headers: requestHeaders,
+				body: JSON.stringify(requestBody),
+				credentials: resolvedOptions.credentials || "same-origin"
+			}, responseToNdjsonEvents), signal, resolvedOptions.reconnect);
+		},
+		async *joinRun(runId, abortSignal) {
+			const resolvedUrl = typeof url === "function" ? url() : url;
+			const resolvedOptions = typeof options === "function" ? await options() : options;
+			const joinUrl = withSearchParams(resolvedUrl, {
+				offset: "-1",
+				runId
+			});
+			const requestHeaders = { ...mergeHeaders(resolvedOptions.headers) };
+			const fetchClient = resolvedOptions.fetchClient ?? fetch;
+			const signal = abortSignal || resolvedOptions.signal;
+			yield* resumableStream(fetchEventSource(fetchClient, joinUrl, {
+				method: "GET",
+				headers: requestHeaders,
+				credentials: resolvedOptions.credentials || "same-origin"
+			}, responseToNdjsonEvents), signal, resolvedOptions.reconnect);
+		},
+		async hydrate(threadId) {
+			const resolvedUrl = typeof url === "function" ? url() : url;
+			const resolvedOptions = typeof options === "function" ? await options() : options;
+			return fetchThreadHydration(resolvedOptions.fetchClient ?? fetch, resolvedUrl, mergeHeaders(resolvedOptions.headers), resolvedOptions.credentials || "same-origin", threadId);
+		},
+		async hydrateGeneration(threadId) {
+			const resolvedUrl = typeof url === "function" ? url() : url;
+			const resolvedOptions = typeof options === "function" ? await options() : options;
+			return fetchGenerationHydration(resolvedOptions.fetchClient ?? fetch, resolvedUrl, mergeHeaders(resolvedOptions.headers), resolvedOptions.credentials || "same-origin", threadId);
+		}
+	};
 }
 function createDefaultXMLHttpRequest() {
-  if (typeof globalThis.XMLHttpRequest !== "function") {
-    throw new Error("XMLHttpRequest is not available in this runtime");
-  }
-  return new globalThis.XMLHttpRequest();
+	if (typeof globalThis.XMLHttpRequest !== "function") throw new Error("XMLHttpRequest is not available in this runtime");
+	return new globalThis.XMLHttpRequest();
 }
 function cleanupXhr(xhr, abortSignal, onAbort) {
-  xhr.onprogress = null;
-  xhr.onload = null;
-  xhr.onerror = null;
-  xhr.onabort = null;
-  xhr.onloadend = null;
-  if (abortSignal && onAbort) {
-    abortSignal.removeEventListener("abort", onAbort);
-  }
+	xhr.onprogress = null;
+	xhr.onload = null;
+	xhr.onerror = null;
+	xhr.onabort = null;
+	xhr.onloadend = null;
+	if (abortSignal && onAbort) abortSignal.removeEventListener("abort", onAbort);
 }
 function readXhrLines(xhr, abortSignal) {
-  let offset = 0;
-  let buffer = "";
-  const lines = [];
-  const waiters = [];
-  let done = false;
-  let aborted = false;
-  let error;
-  let onAbort;
-  const wake = () => {
-    const waiter = waiters.shift();
-    waiter?.();
-  };
-  const enqueueDelta = () => {
-    if (xhr.status !== 0 && (xhr.status < 200 || xhr.status >= 300)) {
-      error = new Error(`XHR error! status: ${xhr.status} ${xhr.statusText}`);
-      done = true;
-      return;
-    }
-    const responseText = xhr.responseText;
-    if (responseText.length <= offset) {
-      return;
-    }
-    buffer += responseText.slice(offset);
-    offset = responseText.length;
-    const splitLines = buffer.split("\n");
-    buffer = splitLines.pop() ?? "";
-    for (const line of splitLines) {
-      const normalized = line.endsWith("\r") ? line.slice(0, -1) : line;
-      if (normalized.trim()) {
-        lines.push(normalized);
-      }
-    }
-  };
-  const finish = () => {
-    enqueueDelta();
-    if (xhr.status < 200 || xhr.status >= 300) {
-      error = new Error(`XHR error! status: ${xhr.status} ${xhr.statusText}`);
-    } else if (buffer.trim() && !aborted) {
-      error = new StreamTruncatedError();
-    }
-    done = true;
-    wake();
-  };
-  xhr.onprogress = () => {
-    enqueueDelta();
-    wake();
-  };
-  xhr.onload = finish;
-  xhr.onerror = () => {
-    error = new Error("XHR request failed");
-    done = true;
-    wake();
-  };
-  xhr.onabort = () => {
-    aborted = true;
-    done = true;
-    wake();
-  };
-  xhr.onloadend = () => {
-    if (!done) {
-      finish();
-    }
-  };
-  if (abortSignal) {
-    onAbort = () => {
-      aborted = true;
-      xhr.abort();
-    };
-    if (abortSignal.aborted) {
-      onAbort();
-    } else {
-      abortSignal.addEventListener("abort", onAbort, { once: true });
-    }
-  }
-  return (async function* () {
-    try {
-      while (true) {
-        const line = lines.shift();
-        if (line !== void 0) {
-          yield line;
-          continue;
-        }
-        if (error) {
-          throw error;
-        }
-        if (done || abortSignal?.aborted) {
-          return;
-        }
-        await new Promise((resolve) => {
-          waiters.push(resolve);
-        });
-      }
-    } finally {
-      cleanupXhr(xhr, abortSignal, onAbort);
-    }
-  })();
-}
-function createConfiguredXhrRequest(url, options, messages, data, runContext) {
-  const xhr = options.xhrFactory?.() ?? createDefaultXMLHttpRequest();
-  xhr.open("POST", url);
-  if (options.withCredentials !== void 0) {
-    xhr.withCredentials = options.withCredentials;
-  }
-  const requestHeaders = {
-    "Content-Type": "application/json",
-    ...mergeHeaders(options.headers)
-  };
-  for (const [name, value] of Object.entries(requestHeaders)) {
-    xhr.setRequestHeader(name, value);
-  }
-  const requestBody = buildRunAgentInputBody(
-    messages,
-    data,
-    runContext,
-    options
-  );
-  return { xhr, body: JSON.stringify(requestBody) };
+	let offset = 0;
+	let buffer = "";
+	const lines = [];
+	const waiters = [];
+	let done = false;
+	let aborted = false;
+	let error;
+	let onAbort;
+	const wake = () => {
+		waiters.shift()?.();
+	};
+	const enqueueDelta = () => {
+		if (xhr.status !== 0 && (xhr.status < 200 || xhr.status >= 300)) {
+			error = /* @__PURE__ */ new Error(`XHR error! status: ${xhr.status} ${xhr.statusText}`);
+			done = true;
+			return;
+		}
+		const responseText = xhr.responseText;
+		if (responseText.length <= offset) return;
+		buffer += responseText.slice(offset);
+		offset = responseText.length;
+		const splitLines = buffer.split("\n");
+		buffer = splitLines.pop() ?? "";
+		for (const line of splitLines) {
+			const normalized = line.endsWith("\r") ? line.slice(0, -1) : line;
+			if (normalized.trim()) lines.push(normalized);
+		}
+	};
+	const finish = () => {
+		enqueueDelta();
+		if (xhr.status !== 0 && (xhr.status < 200 || xhr.status >= 300)) error = /* @__PURE__ */ new Error(`XHR error! status: ${xhr.status} ${xhr.statusText}`);
+		else if (buffer.trim() && !aborted) error = new StreamTruncatedError();
+		done = true;
+		wake();
+	};
+	xhr.onprogress = () => {
+		enqueueDelta();
+		wake();
+	};
+	xhr.onload = finish;
+	xhr.onerror = () => {
+		error = new StreamReadError(/* @__PURE__ */ new Error("XHR request failed"));
+		done = true;
+		wake();
+	};
+	xhr.onabort = () => {
+		aborted = true;
+		done = true;
+		wake();
+	};
+	xhr.onloadend = () => {
+		if (!done) finish();
+	};
+	if (abortSignal) {
+		onAbort = () => {
+			aborted = true;
+			xhr.abort();
+		};
+		if (abortSignal.aborted) onAbort();
+		else abortSignal.addEventListener("abort", onAbort, { once: true });
+	}
+	return (async function* () {
+		try {
+			while (true) {
+				const line = lines.shift();
+				if (line !== void 0) {
+					yield line;
+					continue;
+				}
+				if (error) throw error;
+				if (done || abortSignal?.aborted) return;
+				await new Promise((resolve) => {
+					waiters.push(resolve);
+				});
+			}
+		} finally {
+			cleanupXhr(xhr, abortSignal, onAbort);
+		}
+	})();
+}
+function createConfiguredXhrRequest(url, options, messages, data, runContext, method = "POST", extraHeaders = {}) {
+	const xhr = options.xhrFactory?.() ?? createDefaultXMLHttpRequest();
+	xhr.open(method, url);
+	if (options.withCredentials !== void 0) xhr.withCredentials = options.withCredentials;
+	const requestHeaders = {
+		"Content-Type": "application/json",
+		...mergeHeaders(options.headers),
+		...method === "POST" ? runIdHeader(runContext?.runId) : {},
+		...extraHeaders
+	};
+	for (const [name, value] of Object.entries(requestHeaders)) xhr.setRequestHeader(name, value);
+	const requestBody = buildRunAgentInputBody(messages, data, runContext, options);
+	return {
+		xhr,
+		body: JSON.stringify(requestBody)
+	};
 }
 async function resolveXhrConnectionOptions(options) {
-  return typeof options === "function" ? await options() : options;
+	return typeof options === "function" ? await options() : options;
 }
+/**
+* Build an XHR-backed {@link StreamEventSource}. `parseLines` decodes the raw
+* newline-delimited body into events (SSE or NDJSON); the reconnect engine is
+* shared with the fetch adapters. A fresh XHR is opened per attempt, so a
+* `Last-Event-ID` reconnect header (via `extraHeaders`) is applied at open time.
+*/
+function xhrEventSource(url, options, method, messages, data, runContext, parseLines) {
+	return async function* (extraHeaders, abortSignal) {
+		const request = createConfiguredXhrRequest(url, options, messages, data, runContext, method, extraHeaders);
+		const lines = readXhrLines(request.xhr, abortSignal);
+		if (abortSignal?.aborted) {
+			await lines.next();
+			return;
+		}
+		request.xhr.send(method === "GET" ? null : request.body);
+		try {
+			yield* parseLines(lines);
+		} finally {
+			if (!abortSignal?.aborted) request.xhr.abort();
+		}
+	};
+}
+/** SSE line parser bound to the run's ids for a `[DONE]` fallback. */
+function xhrSSEParser(runContext) {
+	const fallbackIds = {
+		...runContext?.threadId !== void 0 ? { threadId: runContext.threadId } : {},
+		...runContext?.runId !== void 0 ? { runId: runContext.runId } : {}
+	};
+	return (lines) => linesToSSEEvents(lines, fallbackIds);
+}
+/**
+* Create an XMLHttpRequest-backed Server-Sent Events connection adapter.
+*
+* Resumable: against a durable (`id:`-tagged) server response, a dropped socket
+* auto-reconnects with `Last-Event-ID` and de-dupes the replayed prefix, and
+* `joinRun` attaches to an existing run from the start. A non-durable response
+* is a single plain request, exactly as before.
+*/
 function xhrServerSentEvents(url, options = {}) {
-  return {
-    async *connect(messages, data, abortSignal, runContext) {
-      const resolvedUrl = typeof url === "function" ? url() : url;
-      const resolvedOptions = await resolveXhrConnectionOptions(options);
-      const signal = abortSignal || resolvedOptions.signal;
-      const request = createConfiguredXhrRequest(
-        resolvedUrl,
-        resolvedOptions,
-        messages,
-        data,
-        runContext
-      );
-      const lines = readXhrLines(request.xhr, signal);
-      if (signal?.aborted) {
-        await lines.next();
-        return;
-      }
-      request.xhr.send(request.body);
-      let lastThreadId;
-      let lastRunId;
-      let lastModel;
-      for await (const line of lines) {
-        if (line.startsWith(":") || line.startsWith("event:") || line.startsWith("id:") || line.startsWith("retry:")) {
-          continue;
-        }
-        const chunkData = parseSseDataLine(line);
-        if (chunkData === "[DONE]") {
-          const synthetic = {
-            type: EventType.RUN_FINISHED,
-            threadId: lastThreadId ?? runContext?.threadId ?? "",
-            runId: lastRunId ?? runContext?.runId ?? "",
-            model: lastModel ?? "",
-            timestamp: Date.now(),
-            finishReason: "stop"
-          };
-          request.xhr.abort();
-          yield synthetic;
-          return;
-        }
-        const chunk = JSON.parse(chunkData);
-        if ("threadId" in chunk && typeof chunk.threadId === "string") {
-          lastThreadId = chunk.threadId;
-        }
-        if ("runId" in chunk && typeof chunk.runId === "string") {
-          lastRunId = chunk.runId;
-        }
-        if ("model" in chunk && typeof chunk.model === "string") {
-          lastModel = chunk.model;
-        }
-        yield chunk;
-      }
-    }
-  };
+	return {
+		async *connect(messages, data, abortSignal, runContext) {
+			const resolvedUrl = typeof url === "function" ? url() : url;
+			const resolvedOptions = await resolveXhrConnectionOptions(options);
+			const signal = abortSignal || resolvedOptions.signal;
+			yield* resumableStream(xhrEventSource(resolvedUrl, resolvedOptions, "POST", messages, data, runContext, xhrSSEParser(runContext)), signal, resolvedOptions.reconnect);
+		},
+		async *joinRun(runId, abortSignal) {
+			const resolvedUrl = typeof url === "function" ? url() : url;
+			const resolvedOptions = await resolveXhrConnectionOptions(options);
+			const signal = abortSignal || resolvedOptions.signal;
+			yield* resumableStream(xhrEventSource(withSearchParams(resolvedUrl, {
+				offset: "-1",
+				runId
+			}), resolvedOptions, "GET", [], void 0, void 0, (lines) => linesToSSEEvents(lines, { runId })), signal, resolvedOptions.reconnect);
+		},
+		async hydrate(threadId) {
+			const resolvedUrl = typeof url === "function" ? url() : url;
+			const resolvedOptions = await resolveXhrConnectionOptions(options);
+			return fetchThreadHydration(fetch, resolvedUrl, mergeHeaders(resolvedOptions.headers), resolvedOptions.withCredentials ? "include" : "same-origin", threadId);
+		},
+		async hydrateGeneration(threadId) {
+			const resolvedUrl = typeof url === "function" ? url() : url;
+			const resolvedOptions = await resolveXhrConnectionOptions(options);
+			return fetchGenerationHydration(fetch, resolvedUrl, mergeHeaders(resolvedOptions.headers), resolvedOptions.withCredentials ? "include" : "same-origin", threadId);
+		}
+	};
 }
+/**
+* Create an XMLHttpRequest-backed newline-delimited JSON stream adapter.
+*
+* Resumable: against a durable (envelope-tagged) server response, a dropped
+* socket auto-reconnects with `Last-Event-ID` and de-dupes the replayed prefix,
+* and `joinRun` attaches to an existing run from the start. A non-durable
+* (bare-line) response is a single plain request, exactly as before.
+*/
 function xhrHttpStream(url, options = {}) {
-  return {
-    async *connect(messages, data, abortSignal, runContext) {
-      const resolvedUrl = typeof url === "function" ? url() : url;
-      const resolvedOptions = await resolveXhrConnectionOptions(options);
-      const signal = abortSignal || resolvedOptions.signal;
-      const request = createConfiguredXhrRequest(
-        resolvedUrl,
-        resolvedOptions,
-        messages,
-        data,
-        runContext
-      );
-      const lines = readXhrLines(request.xhr, signal);
-      if (signal?.aborted) {
-        await lines.next();
-        return;
-      }
-      request.xhr.send(request.body);
-      for await (const line of lines) {
-        yield JSON.parse(line);
-      }
-    }
-  };
-}
-function stream(streamFactory) {
-  return {
-    async *connect(messages, data, abortSignal) {
-      yield* streamFactory(messages, data, abortSignal);
-    }
-  };
+	return {
+		async *connect(messages, data, abortSignal, runContext) {
+			const resolvedUrl = typeof url === "function" ? url() : url;
+			const resolvedOptions = await resolveXhrConnectionOptions(options);
+			const signal = abortSignal || resolvedOptions.signal;
+			yield* resumableStream(xhrEventSource(resolvedUrl, resolvedOptions, "POST", messages, data, runContext, linesToNdjsonEvents), signal, resolvedOptions.reconnect);
+		},
+		async *joinRun(runId, abortSignal) {
+			const resolvedUrl = typeof url === "function" ? url() : url;
+			const resolvedOptions = await resolveXhrConnectionOptions(options);
+			const signal = abortSignal || resolvedOptions.signal;
+			yield* resumableStream(xhrEventSource(withSearchParams(resolvedUrl, {
+				offset: "-1",
+				runId
+			}), resolvedOptions, "GET", [], void 0, void 0, linesToNdjsonEvents), signal, resolvedOptions.reconnect);
+		},
+		async hydrate(threadId) {
+			const resolvedUrl = typeof url === "function" ? url() : url;
+			const resolvedOptions = await resolveXhrConnectionOptions(options);
+			return fetchThreadHydration(fetch, resolvedUrl, mergeHeaders(resolvedOptions.headers), resolvedOptions.withCredentials ? "include" : "same-origin", threadId);
+		},
+		async hydrateGeneration(threadId) {
+			const resolvedUrl = typeof url === "function" ? url() : url;
+			const resolvedOptions = await resolveXhrConnectionOptions(options);
+			return fetchGenerationHydration(fetch, resolvedUrl, mergeHeaders(resolvedOptions.headers), resolvedOptions.withCredentials ? "include" : "same-origin", threadId);
+		}
+	};
+}
+/**
+* Create a direct stream connection adapter (for server functions or direct streams)
+*
+* @param streamFactory - A function that returns an async iterable of StreamChunks
+* @param handlers - Optional persistence handlers (`hydrate`,
+* `hydrateGeneration`, `joinRun`) that let server-driven persistence work
+* without an HTTP endpoint — each is usually a one-line server-function call
+* @returns A connection adapter for direct streams
+*
+* @example
+* ```typescript
+* // With TanStack Start server function
+* const connection = stream(() => serverFunction({ messages }));
+*
+* const client = new ChatClient({ connection });
+*
+* // With generation persistence over server functions
+* const connection = stream(
+*   () => generateImageFn({ data: input }),
+*   {
+*     hydrateGeneration: (threadId) => getImageHydrationFn({ data: threadId }),
+*     joinRun: (runId) => joinImageRunFn({ data: runId }),
+*   },
+* );
+* ```
+*/
+function stream(streamFactory, handlers) {
+	return {
+		async *connect(messages, data, abortSignal) {
+			yield* streamFactory(messages, data, abortSignal);
+		},
+		...handlers?.hydrate ? { hydrate: handlers.hydrate } : {},
+		...handlers?.hydrateGeneration ? { hydrateGeneration: handlers.hydrateGeneration } : {},
+		...handlers?.joinRun ? { joinRun: handlers.joinRun } : {}
+	};
 }
+/**
+* Wrap a `ChatFetcher` as a `ConnectConnectionAdapter` so the chat client can
+* consume it through the same `subscribe`/`send` plumbing used for SSE /
+* HTTP-stream / RPC connections. May return either a `Response` (parsed as
+* SSE) or an `AsyncIterable<StreamChunk>` (yielded directly).
+*
+* @internal
+*/
 function fetcherToConnectionAdapter(fetcher) {
-  return {
-    async *connect(messages, data, abortSignal, runContext) {
-      if (!abortSignal) {
-        throw new Error(
-          "fetcherToConnectionAdapter requires an AbortSignal — the chat client always supplies one."
-        );
-      }
-      if (!runContext) {
-        throw new Error(
-          "fetcherToConnectionAdapter requires a RunAgentInputContext — the chat client always supplies one."
-        );
-      }
-      const uiMessages = messages;
-      const result = await fetcher(
-        {
-          messages: uiMessages,
-          data,
-          threadId: runContext.threadId,
-          runId: runContext.runId
-        },
-        { signal: abortSignal }
-      );
-      if (result instanceof Response) {
-        yield* responseToSSEChunks(result, abortSignal);
-      } else {
-        yield* abortableIterable(result, abortSignal);
-      }
-    }
-  };
+	return { async *connect(messages, data, abortSignal, runContext) {
+		if (!abortSignal) throw new Error("fetcherToConnectionAdapter requires an AbortSignal — the chat client always supplies one.");
+		if (!runContext) throw new Error("fetcherToConnectionAdapter requires a RunAgentInputContext — the chat client always supplies one.");
+		const result = await fetcher({
+			messages,
+			data,
+			threadId: runContext.threadId,
+			runId: runContext.runId
+		}, { signal: abortSignal });
+		if (result instanceof Response) yield* responseToSSEChunks(result, abortSignal);
+		else yield* abortableIterable(result, abortSignal);
+	} };
 }
+/**
+* Wrap an AsyncIterable so iteration aborts when `signal` fires. Without
+* this, a fetcher that returns a generator ignoring its signal would leave
+* the for-await loop hanging until the iterable naturally ends.
+*/
 async function* abortableIterable(iterable, signal) {
-  if (signal.aborted) return;
-  const iterator = iterable[Symbol.asyncIterator]();
-  const abortPromise = new Promise(
-    (resolve) => {
-      signal.addEventListener(
-        "abort",
-        () => resolve({ done: true, value: void 0 }),
-        { once: true }
-      );
-    }
-  );
-  try {
-    while (true) {
-      const result = await Promise.race([iterator.next(), abortPromise]);
-      if (result.done) return;
-      yield result.value;
-    }
-  } finally {
-    await iterator.return?.();
-  }
-}
-function rpcStream(rpcCall) {
-  return {
-    async *connect(messages, data, abortSignal) {
-      yield* rpcCall(messages, data, abortSignal);
-    }
-  };
-}
-export {
-  StreamTruncatedError,
-  fetchHttpStream,
-  fetchServerSentEvents,
-  fetcherToConnectionAdapter,
-  getChunkRunId,
-  normalizeConnectionAdapter,
-  rpcStream,
-  stream,
-  xhrHttpStream,
-  xhrServerSentEvents
-};
-//# sourceMappingURL=connection-adapters.js.map
+	if (signal.aborted) return;
+	const iterator = iterable[Symbol.asyncIterator]();
+	const abortPromise = new Promise((resolve) => {
+		signal.addEventListener("abort", () => resolve({
+			done: true,
+			value: void 0
+		}), { once: true });
+	});
+	try {
+		while (true) {
+			const result = await Promise.race([iterator.next(), abortPromise]);
+			if (result.done) return;
+			yield result.value;
+		}
+	} finally {
+		await iterator.return?.();
+	}
+}
+/**
+* Create an RPC stream connection adapter (for RPC-based streaming like Cap'n Web RPC)
+*
+* @param rpcCall - A function that accepts messages and returns an async iterable of StreamChunks
+* @param handlers - Optional persistence handlers (`hydrate`,
+* `hydrateGeneration`, `joinRun`) that let server-driven persistence work
+* without an HTTP endpoint — each is usually a one-line RPC call
+* @returns A connection adapter for RPC streams
+*
+* @example
+* ```typescript
+* // With Cap'n Web RPC
+* const connection = rpcStream((messages, data) =>
+*   api.streamMurfResponse(messages, data)
+* );
+*
+* const client = new ChatClient({ connection });
+*
+* // With generation persistence over RPC
+* const connection = rpcStream(
+*   (messages, data) => api.streamMurfResponse(messages, data),
+*   {
+*     hydrateGeneration: (threadId) => api.getGenerationHydration(threadId),
+*     joinRun: (runId) => api.replayRun(runId),
+*   },
+* );
+* ```
+*/
+function rpcStream(rpcCall, handlers) {
+	return {
+		async *connect(messages, data, abortSignal) {
+			yield* rpcCall(messages, data, abortSignal);
+		},
+		...handlers?.hydrate ? { hydrate: handlers.hydrate } : {},
+		...handlers?.hydrateGeneration ? { hydrateGeneration: handlers.hydrateGeneration } : {},
+		...handlers?.joinRun ? { joinRun: handlers.joinRun } : {}
+	};
+}
+//#endregion
+export { DurableStreamIncompleteError, StreamReconnectLimitError, StreamTruncatedError, fetchHttpStream, fetchServerSentEvents, fetcherToConnectionAdapter, getChunkRunId, normalizeConnectionAdapter, rpcStream, stream, xhrHttpStream, xhrServerSentEvents };
+
+//# sourceMappingURL=connection-adapters.js.map