agents 0.22.0 → 0.24.0

package/dist/state/index.d.ts

@@ -0,0 +1,6 @@
+import {
+  n as StateChangeSource,
+  r as StateOptions,
+  t as State
+} from "../index-Dlgtd3Mj.js";
+export { State, StateChangeSource, StateOptions };

package/dist/state/index.js

@@ -0,0 +1,137 @@
+import { i as _classPrivateFieldInitSpec, n as _classPrivateFieldSet2, r as _assertClassBrand, t as _classPrivateFieldGet2 } from "../classPrivateFieldGet2-DZBYAB34.js";
+import { t as LifecycleCapability } from "../capability-B4WbF81e.js";
+import { t as _classPrivateMethodInitSpec } from "../classPrivateMethodInitSpec-qMjJ6sHQ.js";
+//#region src/state/index.ts
+/**
+* Namespaced KV key holding this capability's schema version. Kept separate
+* from the host's global schema version so State owns its own migrations
+* without gating the host's DDL.
+*/
+const STATE_SCHEMA_VERSION_KEY = "cf_agents:state_schema_version";
+const CURRENT_STATE_SCHEMA_VERSION = 1;
+/** Row id under which the single state value is stored in `cf_agents_state`. */
+const STATE_ROW_ID = "cf_state_row_id";
+/**
+* Legacy row written by SDKs that predate the single-row state optimization.
+* Never written now; the v1 migration deletes it.
+*/
+const LEGACY_WAS_CHANGED_ROW_ID = "cf_state_was_changed";
+/**
+* Sentinel distinguishing "state not yet loaded / never set" from a stored
+* value. A distinct object reference means falsy states (null, 0, false, "")
+* still read back as set.
+*/
+const DEFAULT_STATE = {};
+var _state = /* @__PURE__ */ new WeakMap();
+var _tableEnsured = /* @__PURE__ */ new WeakMap();
+var _options = /* @__PURE__ */ new WeakMap();
+var _State_brand = /* @__PURE__ */ new WeakSet();
+/**
+* Durable state storage for a Lifecycle Object.
+*
+* Owns the `cf_agents_state` state row, lazy load with an in-memory cache, and
+* validated persistence. Install the instance with `Lifecycle.use()`. State
+* validation and the post-change notification hook stay on the host, which
+* injects both callbacks. This capability never touches connections.
+*
+* @experimental The API surface may change before stabilizing.
+*/
+var State = class extends LifecycleCapability {
+	/**
+	* Create a durable state capability.
+	*
+	* @param options - Optional initial state and a synchronous validation hook
+	* injected by the host.
+	*/
+	constructor(options = {}) {
+		super("state");
+		_classPrivateMethodInitSpec(this, _State_brand);
+		_classPrivateFieldInitSpec(this, _state, DEFAULT_STATE);
+		_classPrivateFieldInitSpec(this, _tableEnsured, false);
+		_classPrivateFieldInitSpec(this, _options, void 0);
+		_classPrivateFieldSet2(_options, this, options);
+	}
+	/** Initialize state storage during Lifecycle startup. */
+	async onStart() {
+		if ((await this.lifecycle.storage.get(STATE_SCHEMA_VERSION_KEY) ?? 0) >= CURRENT_STATE_SCHEMA_VERSION) {
+			_classPrivateFieldSet2(_tableEnsured, this, true);
+			return;
+		}
+		_assertClassBrand(_State_brand, this, _ensureTable).call(this);
+		this.lifecycle.storage.sql.exec("DELETE FROM cf_agents_state WHERE id = ?", LEGACY_WAS_CHANGED_ROW_ID);
+		await this.lifecycle.storage.put(STATE_SCHEMA_VERSION_KEY, CURRENT_STATE_SCHEMA_VERSION);
+	}
+	/**
+	* Current state.
+	*
+	* Loads lazily from storage on first access and caches in memory. Row
+	* existence in `cf_agents_state` is the signal that state was previously
+	* set, so falsy values persist correctly. On a corrupt row, falls back to
+	* the initial state (re-persisting it) or clears the row.
+	*/
+	get() {
+		if (_classPrivateFieldGet2(_state, this) !== DEFAULT_STATE) return _classPrivateFieldGet2(_state, this);
+		_assertClassBrand(_State_brand, this, _ensureTable).call(this);
+		const result = this.lifecycle.storage.sql.exec("SELECT state FROM cf_agents_state WHERE id = ?", STATE_ROW_ID).toArray();
+		if (result.length > 0) {
+			const state = result[0].state;
+			try {
+				_classPrivateFieldSet2(_state, this, JSON.parse(state));
+			} catch (e) {
+				console.error("Failed to parse stored state, falling back to initialState:", e);
+				const initial = _classPrivateFieldGet2(_options, this).initialState;
+				if (initial !== void 0) {
+					_classPrivateFieldSet2(_state, this, initial);
+					this.set(initial, "server");
+				} else {
+					this.lifecycle.storage.sql.exec("DELETE FROM cf_agents_state WHERE id = ?", STATE_ROW_ID);
+					return;
+				}
+			}
+			return _classPrivateFieldGet2(_state, this);
+		}
+		const initial = _classPrivateFieldGet2(_options, this).initialState;
+		if (initial === void 0) return;
+		this.set(initial, "server");
+		return initial;
+	}
+	/**
+	* Validate and persist a state change, then call the change hook.
+	*
+	* @param nextState - The new state to persist.
+	* @param source - `"server"` for host-originated changes, or the originating
+	* connection for client-originated changes.
+	* @throws Whatever the injected `validateStateChange` throws.
+	*/
+	set(nextState, source = "server") {
+		_classPrivateFieldGet2(_options, this).validateStateChange?.(nextState, source);
+		_assertClassBrand(_State_brand, this, _ensureTable).call(this);
+		const serialized = JSON.stringify(nextState);
+		this.lifecycle.storage.sql.exec("INSERT OR REPLACE INTO cf_agents_state (id, state) VALUES (?, ?)", STATE_ROW_ID, serialized);
+		_classPrivateFieldSet2(_state, this, nextState);
+		let pending;
+		try {
+			pending = _classPrivateFieldGet2(_options, this).onChanged?.(nextState, source);
+		} catch (error) {
+			console.error("State onChanged hook failed:", error);
+			return;
+		}
+		if (pending) Promise.resolve(pending).catch((error) => {
+			console.error("State onChanged hook failed:", error);
+		});
+	}
+};
+function _ensureTable() {
+	if (_classPrivateFieldGet2(_tableEnsured, this)) return;
+	this.lifecycle.storage.sql.exec(`
+      CREATE TABLE IF NOT EXISTS cf_agents_state (
+        id TEXT PRIMARY KEY NOT NULL,
+        state TEXT
+      )
+    `);
+	_classPrivateFieldSet2(_tableEnsured, this, true);
+}
+//#endregion
+export { State };
+
+//# sourceMappingURL=index.js.map

package/dist/state/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../src/state/index.ts"],"sourcesContent":["import { LifecycleCapability } from \"../lifecycle/capability\";\nimport type { Connection } from \"../lifecycle/durable-object-lifecycle\";\n\n/**\n * Source of a state change: `\"server\"` for host code (e.g. `setState()`), or\n * the {@link Connection} the change arrived from. Hosts use it to exclude the\n * originating connection from a broadcast.\n */\nexport type StateChangeSource = Connection | \"server\";\n\n/**\n * Options for a {@link State} capability. Validation and the post-change hook\n * stay on the host, which passes them in; the capability owns storage and\n * change ordering.\n *\n * @experimental The API surface may change before stabilizing.\n */\nexport interface StateOptions<T = unknown> {\n  /** Seeded on first access when nothing is stored. `undefined` seeds nothing. */\n  readonly initialState?: T;\n\n  /** Called after a change is validated and persisted. May be async. */\n  readonly onChanged?: (\n    state: T,\n    source: StateChangeSource\n  ) => void | Promise<void>;\n\n  /**\n   * Synchronous gating hook run before a change is persisted. Throw to reject\n   * the change; the throw propagates to the caller of {@link State.set}.\n   */\n  readonly validateStateChange?: (\n    nextState: T,\n    source: StateChangeSource\n  ) => void;\n}\n\n/**\n * Namespaced KV key holding this capability's schema version. Kept separate\n * from the host's global schema version so State owns its own migrations\n * without gating the host's DDL.\n */\nconst STATE_SCHEMA_VERSION_KEY = \"cf_agents:state_schema_version\";\nconst CURRENT_STATE_SCHEMA_VERSION = 1;\n\n/** Row id under which the single state value is stored in `cf_agents_state`. */\nconst STATE_ROW_ID = \"cf_state_row_id\";\n\n/**\n * Legacy row written by SDKs that predate the single-row state optimization.\n * Never written now; the v1 migration deletes it.\n */\nconst LEGACY_WAS_CHANGED_ROW_ID = \"cf_state_was_changed\";\n\n/**\n * Sentinel distinguishing \"state not yet loaded / never set\" from a stored\n * value. A distinct object reference means falsy states (null, 0, false, \"\")\n * still read back as set.\n */\nconst DEFAULT_STATE = {} as unknown;\n\n/**\n * Durable state storage for a Lifecycle Object.\n *\n * Owns the `cf_agents_state` state row, lazy load with an in-memory cache, and\n * validated persistence. Install the instance with `Lifecycle.use()`. State\n * validation and the post-change notification hook stay on the host, which\n * injects both callbacks. This capability never touches connections.\n *\n * @experimental The API surface may change before stabilizing.\n */\nexport class State<T = unknown> extends LifecycleCapability {\n  #state = DEFAULT_STATE as T;\n  #tableEnsured = false;\n  readonly #options: StateOptions<T>;\n\n  /**\n   * Create a durable state capability.\n   *\n   * @param options - Optional initial state and a synchronous validation hook\n   * injected by the host.\n   */\n  constructor(options: StateOptions<T> = {}) {\n    super(\"state\");\n    this.#options = options;\n  }\n\n  // ── Lifecycle capability hooks ─────────────────────────────────────────────\n\n  /** Initialize state storage during Lifecycle startup. */\n  async onStart(): Promise<void> {\n    const version =\n      (await this.lifecycle.storage.get<number>(STATE_SCHEMA_VERSION_KEY)) ?? 0;\n    if (version >= CURRENT_STATE_SCHEMA_VERSION) {\n      this.#tableEnsured = true;\n      return;\n    }\n\n    // v1: own the table and clear the legacy wasChanged row left behind by\n    // pre-optimization SDKs (state itself lives in STATE_ROW_ID).\n    this.#ensureTable();\n    this.lifecycle.storage.sql.exec(\n      \"DELETE FROM cf_agents_state WHERE id = ?\",\n      LEGACY_WAS_CHANGED_ROW_ID\n    );\n    await this.lifecycle.storage.put(\n      STATE_SCHEMA_VERSION_KEY,\n      CURRENT_STATE_SCHEMA_VERSION\n    );\n  }\n\n  #ensureTable(): void {\n    if (this.#tableEnsured) return;\n    this.lifecycle.storage.sql.exec(`\n      CREATE TABLE IF NOT EXISTS cf_agents_state (\n        id TEXT PRIMARY KEY NOT NULL,\n        state TEXT\n      )\n    `);\n    this.#tableEnsured = true;\n  }\n\n  // ── State access ───────────────────────────────────────────────────────────\n\n  /**\n   * Current state.\n   *\n   * Loads lazily from storage on first access and caches in memory. Row\n   * existence in `cf_agents_state` is the signal that state was previously\n   * set, so falsy values persist correctly. On a corrupt row, falls back to\n   * the initial state (re-persisting it) or clears the row.\n   */\n  get(): T | undefined {\n    if (this.#state !== DEFAULT_STATE) {\n      // state was previously set, and populated internal state\n      return this.#state;\n    }\n    // looks like this is the first time the state is being accessed\n    // check if the state was set in a previous life\n    this.#ensureTable();\n    const result = this.lifecycle.storage.sql\n      .exec(\"SELECT state FROM cf_agents_state WHERE id = ?\", STATE_ROW_ID)\n      .toArray() as { state: string | null }[];\n\n    // Row existence is the signal that state was previously set.\n    // This handles all values including falsy ones (null, 0, false, \"\").\n    if (result.length > 0) {\n      const state = result[0].state as string;\n\n      try {\n        this.#state = JSON.parse(state);\n      } catch (e) {\n        console.error(\n          \"Failed to parse stored state, falling back to initialState:\",\n          e\n        );\n        const initial = this.#options.initialState;\n        if (initial !== undefined) {\n          this.#state = initial;\n          // Persist the fixed state to prevent future parse errors\n          this.set(initial, \"server\");\n        } else {\n          // No initialState defined - clear corrupted data to prevent infinite retry loop\n          this.lifecycle.storage.sql.exec(\n            \"DELETE FROM cf_agents_state WHERE id = ?\",\n            STATE_ROW_ID\n          );\n          return undefined;\n        }\n      }\n      return this.#state;\n    }\n\n    // ok, this is the first time the state is being accessed\n    // and the state was not set in a previous life\n    // so we need to set the initial state (if provided)\n    const initial = this.#options.initialState;\n    if (initial === undefined) {\n      // no initial state provided, so we return undefined\n      return undefined;\n    }\n    // initial state provided, so we set the state,\n    // update db and return the initial state\n    this.set(initial, \"server\");\n    return initial;\n  }\n\n  /**\n   * Validate and persist a state change, then call the change hook.\n   *\n   * @param nextState - The new state to persist.\n   * @param source - `\"server\"` for host-originated changes, or the originating\n   * connection for client-originated changes.\n   * @throws Whatever the injected `validateStateChange` throws.\n   */\n  set(nextState: T, source: StateChangeSource = \"server\"): void {\n    // Validation/gating hook (sync only)\n    this.#options.validateStateChange?.(nextState, source);\n    this.#ensureTable();\n\n    // Persist first, cache second: a value that fails to serialize or to\n    // write must not be served by later get() calls. Row existence in\n    // cf_agents_state is the signal that state was set.\n    const serialized = JSON.stringify(nextState);\n    this.lifecycle.storage.sql.exec(\n      \"INSERT OR REPLACE INTO cf_agents_state (id, state) VALUES (?, ?)\",\n      STATE_ROW_ID,\n      serialized\n    );\n    this.#state = nextState;\n\n    let pending: void | Promise<void>;\n    try {\n      pending = this.#options.onChanged?.(nextState, source);\n    } catch (error) {\n      console.error(\"State onChanged hook failed:\", error);\n      return;\n    }\n\n    if (pending) {\n      // Durable Objects remain active for pending I/O without waitUntil. Keep\n      // set() synchronous while ensuring asynchronous failures are observed.\n      // Promise.resolve normalizes thenables from other realms or libraries.\n      void Promise.resolve(pending).catch((error) => {\n        console.error(\"State onChanged hook failed:\", error);\n      });\n    }\n  }\n}\n"],"mappings":";;;;;;;;;AA0CA,MAAM,2BAA2B;AACjC,MAAM,+BAA+B;;AAGrC,MAAM,eAAe;;;;;AAMrB,MAAM,4BAA4B;;;;;;AAOlC,MAAM,gBAAgB,CAAC;;;;;;;;;;;;;;;AAYvB,IAAa,QAAb,cAAwC,oBAAoB;;;;;;;CAW1D,YAAY,UAA2B,CAAC,GAAG;EACzC,MAAM,OAAO;;2CAXN,aAAA;kDACO,KAAA;;EAWd,uBAAA,UAAA,MAAgB,OAAA;CAClB;;CAKA,MAAM,UAAyB;EAG7B,KADG,MAAM,KAAK,UAAU,QAAQ,IAAY,wBAAwB,KAAM,MAC3D,8BAA8B;GAC3C,uBAAA,eAAA,MAAqB,IAAA;GACrB;EACF;EAIA,kBAAA,cAAA,MAAA,YAAA,CAAA,CAAA,KAAA,IAAkB;EAClB,KAAK,UAAU,QAAQ,IAAI,KACzB,4CACA,yBACF;EACA,MAAM,KAAK,UAAU,QAAQ,IAC3B,0BACA,4BACF;CACF;;;;;;;;;CAuBA,MAAqB;EACnB,IAAA,uBAAA,QAAI,IAAA,MAAgB,eAElB,OAAA,uBAAA,QAAO,IAAA;EAIT,kBAAA,cAAA,MAAA,YAAA,CAAA,CAAA,KAAA,IAAkB;EAClB,MAAM,SAAS,KAAK,UAAU,QAAQ,IACnC,KAAK,kDAAkD,YAAY,CAAC,CACpE,QAAQ;EAIX,IAAI,OAAO,SAAS,GAAG;GACrB,MAAM,QAAQ,OAAO,EAAE,CAAC;GAExB,IAAI;IACF,uBAAA,QAAA,MAAc,KAAK,MAAM,KAAK,CAAA;GAChC,SAAS,GAAG;IACV,QAAQ,MACN,+DACA,CACF;IACA,MAAM,UAAA,uBAAA,UAAU,IAAA,CAAA,CAAc;IAC9B,IAAI,YAAY,KAAA,GAAW;KACzB,uBAAA,QAAA,MAAc,OAAA;KAEd,KAAK,IAAI,SAAS,QAAQ;IAC5B,OAAO;KAEL,KAAK,UAAU,QAAQ,IAAI,KACzB,4CACA,YACF;KACA;IACF;GACF;GACA,OAAA,uBAAA,QAAO,IAAA;EACT;EAKA,MAAM,UAAA,uBAAA,UAAU,IAAA,CAAA,CAAc;EAC9B,IAAI,YAAY,KAAA,GAEd;EAIF,KAAK,IAAI,SAAS,QAAQ;EAC1B,OAAO;CACT;;;;;;;;;CAUA,IAAI,WAAc,SAA4B,UAAgB;EAE5D,uBAAA,UAAA,IAAA,CAAA,CAAc,sBAAsB,WAAW,MAAM;EACrD,kBAAA,cAAA,MAAA,YAAA,CAAA,CAAA,KAAA,IAAkB;EAKlB,MAAM,aAAa,KAAK,UAAU,SAAS;EAC3C,KAAK,UAAU,QAAQ,IAAI,KACzB,oEACA,cACA,UACF;EACA,uBAAA,QAAA,MAAc,SAAA;EAEd,IAAI;EACJ,IAAI;GACF,UAAA,uBAAA,UAAU,IAAA,CAAA,CAAc,YAAY,WAAW,MAAM;EACvD,SAAS,OAAO;GACd,QAAQ,MAAM,gCAAgC,KAAK;GACnD;EACF;EAEA,IAAI,SAIF,QAAa,QAAQ,OAAO,CAAC,CAAC,OAAO,UAAU;GAC7C,QAAQ,MAAM,gCAAgC,KAAK;EACrD,CAAC;CAEL;AACF;AArHE,SAAA,eAAqB;CACnB,IAAA,uBAAA,eAAI,IAAA,GAAoB;CACxB,KAAK,UAAU,QAAQ,IAAI,KAAK;;;;;KAK/B;CACD,uBAAA,eAAA,MAAqB,IAAA;AACvB"}

package/dist/streams/index.d.ts

@@ -0,0 +1,120 @@
+import {
+  a as StreamJson,
+  c as StreamReadBatchesOptions,
+  d as StreamState,
+  f as StreamStatus,
+  i as StreamChunk,
+  l as StreamReadOptions,
+  n as Streams,
+  o as StreamListOptions,
+  p as StreamWriter,
+  r as StreamsOptions,
+  s as StreamOpenOptions,
+  t as DEFAULT_MAX_CHUNK_BYTES,
+  u as StreamSettleOptions
+} from "../streams-BcE8JP2X.js";
+
+//#region src/streams/errors.d.ts
+/**
+ * Error classes for the Streams capability. Each carries a stable `name` so
+ * hosts and tests can classify failures without depending on message text.
+ */
+/**
+ * Thrown when `open()` targets a terminal stream, or an append reaches a
+ * stream that settled (or was deleted) after the writer was created.
+ *
+ * @experimental The API surface may change before stabilizing.
+ */
+declare class StreamClosedError extends Error {
+  /** The stream that no longer accepts writes. */
+  readonly streamId: string;
+  constructor(streamId: string, detail: string);
+}
+/**
+ * Thrown when `read()` targets a stream that was never opened (or was
+ * deleted). `status()` returns `null` instead, for existence probes.
+ *
+ * @experimental The API surface may change before stabilizing.
+ */
+declare class StreamNotFoundError extends Error {
+  readonly streamId: string;
+  constructor(streamId: string);
+}
+/**
+ * Thrown when a chunk or metadata value is not JSON-serializable or exceeds
+ * the configured size limit.
+ *
+ * @experimental The API surface may change before stabilizing.
+ */
+declare class StreamSerializationError extends Error {
+  constructor(context: string, detail: string);
+}
+//#endregion
+//#region src/streams/sse.d.ts
+/**
+ * Options accepted by {@link sseResponse}.
+ *
+ * @experimental The API surface may change before stabilizing.
+ */
+interface SSEResponseOptions {
+  /**
+   * The incoming request. Used for resume (the `Last-Event-ID` header a
+   * reconnecting `EventSource` sends, or a `?from=` query parameter) and to
+   * abort the tail when the client disconnects (`request.signal`).
+   */
+  request?: Request;
+  /** First sequence number to yield. Overrides request-derived resume. */
+  from?: number;
+  /** Extra abort signal; composed with `request.signal`. */
+  signal?: AbortSignal;
+  /** Maximum chunks per write. Defaults to the read batch size (100). */
+  batchSize?: number;
+  /**
+   * Milliseconds between `: heartbeat` comment frames while tailing, keeping
+   * idle proxies from killing the connection. 0 disables. Default: 30000.
+   */
+  heartbeatMs?: number;
+}
+/**
+ * Serve one durable stream as a Server-Sent Events response: replay from the
+ * resume point, emit an `up-to-date` control event on reaching the tail,
+ * tail live appends, and finish with `done` (completed) or `error` (errored,
+ * carrying the recorded reason). Returns a 404 response when the stream does
+ * not exist.
+ *
+ * ```ts
+ * async onRequest(request: Request) {
+ *   return sseResponse(this.streams, "reply:123", { request });
+ * }
+ * // client: new EventSource(url) — reconnect resume is automatic.
+ * ```
+ *
+ * @experimental The API surface may change before stabilizing.
+ */
+declare function sseResponse(
+  streams: Streams,
+  streamId: string,
+  options?: SSEResponseOptions
+): Promise<Response>;
+//#endregion
+export {
+  DEFAULT_MAX_CHUNK_BYTES,
+  type SSEResponseOptions,
+  type StreamChunk,
+  StreamClosedError,
+  type StreamJson,
+  type StreamListOptions,
+  StreamNotFoundError,
+  type StreamOpenOptions,
+  type StreamReadBatchesOptions,
+  type StreamReadOptions,
+  StreamSerializationError,
+  type StreamSettleOptions,
+  type StreamState,
+  type StreamStatus,
+  type StreamWriter,
+  Streams,
+  type StreamsOptions,
+  sseResponse
+};
+//# sourceMappingURL=index.d.ts.map

package/dist/streams/index.js

@@ -0,0 +1,107 @@
+import { a as StreamSerializationError, i as StreamNotFoundError, n as Streams, r as StreamClosedError, t as DEFAULT_MAX_CHUNK_BYTES } from "../streams-CCPRV6dt.js";
+//#region src/streams/sse.ts
+const encoder = new TextEncoder();
+function resumeFrom(options) {
+	if (options.from !== void 0) return Math.max(0, options.from);
+	const request = options.request;
+	if (request) {
+		const header = request.headers.get("Last-Event-ID");
+		if (header !== null && header !== "") {
+			const lastEventId = Number(header);
+			if (Number.isInteger(lastEventId) && lastEventId >= 0) return lastEventId + 1;
+		}
+		const fromParam = new URL(request.url).searchParams.get("from");
+		if (fromParam !== null) {
+			const from = Number(fromParam);
+			if (Number.isInteger(from) && from >= 0) return from;
+		}
+	}
+	return 0;
+}
+function frame(seq, chunk) {
+	return `id: ${seq}\ndata: ${JSON.stringify(chunk)}\n\n`;
+}
+function controlFrame(event, data) {
+	return `event: ${event}\ndata: ${JSON.stringify(data)}\n\n`;
+}
+/**
+* Serve one durable stream as a Server-Sent Events response: replay from the
+* resume point, emit an `up-to-date` control event on reaching the tail,
+* tail live appends, and finish with `done` (completed) or `error` (errored,
+* carrying the recorded reason). Returns a 404 response when the stream does
+* not exist.
+*
+* ```ts
+* async onRequest(request: Request) {
+*   return sseResponse(this.streams, "reply:123", { request });
+* }
+* // client: new EventSource(url) — reconnect resume is automatic.
+* ```
+*
+* @experimental The API surface may change before stabilizing.
+*/
+async function sseResponse(streams, streamId, options = {}) {
+	if (await streams.status(streamId) === null) return new Response(`Stream "${streamId}" does not exist`, { status: 404 });
+	const from = resumeFrom(options);
+	const heartbeatMs = options.heartbeatMs ?? 3e4;
+	const abort = new AbortController();
+	const onUpstreamAbort = () => abort.abort();
+	if (options.signal?.aborted || options.request?.signal.aborted) abort.abort();
+	else {
+		options.signal?.addEventListener("abort", onUpstreamAbort, { once: true });
+		options.request?.signal.addEventListener("abort", onUpstreamAbort, { once: true });
+	}
+	let open = true;
+	const body = new ReadableStream({
+		start: (controller) => {
+			const write = (text) => {
+				if (!open) return;
+				try {
+					controller.enqueue(encoder.encode(text));
+				} catch {
+					open = false;
+				}
+			};
+			const heartbeat = heartbeatMs > 0 ? setInterval(() => write(": heartbeat\n\n"), heartbeatMs) : null;
+			const finish = () => {
+				if (heartbeat !== null) clearInterval(heartbeat);
+				options.signal?.removeEventListener("abort", onUpstreamAbort);
+				options.request?.signal.removeEventListener("abort", onUpstreamAbort);
+				if (open) {
+					open = false;
+					try {
+						controller.close();
+					} catch {}
+				}
+			};
+			(async () => {
+				try {
+					const batches = streams.readBatches(streamId, {
+						from,
+						signal: abort.signal,
+						batchSize: options.batchSize,
+						onUpToDate: () => write(controlFrame("up-to-date", {}))
+					});
+					for await (const batch of batches) write(batch.map((chunk) => frame(chunk.seq, chunk.chunk)).join(""));
+					const status = await streams.status(streamId);
+					if (status?.state === "errored") write(controlFrame("error", { reason: status.error ?? null }));
+					else write(controlFrame("done", {}));
+				} catch {} finally {
+					finish();
+				}
+			})();
+		},
+		cancel: () => {
+			open = false;
+			abort.abort();
+		}
+	});
+	return new Response(body, { headers: {
+		"content-type": "text/event-stream; charset=utf-8",
+		"cache-control": "no-store"
+	} });
+}
+//#endregion
+export { DEFAULT_MAX_CHUNK_BYTES, StreamClosedError, StreamNotFoundError, StreamSerializationError, Streams, sseResponse };
+
+//# sourceMappingURL=index.js.map

package/dist/streams/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../src/streams/sse.ts"],"sourcesContent":["/**\n * Server-Sent Events serving for durable streams: turn one stream into an\n * SSE `Response` with resume built into the protocol. Every chunk is emitted\n * with its sequence number as the SSE `id:` field, so a browser\n * `EventSource` that reconnects sends `Last-Event-ID` automatically and the\n * helper resumes from the next chunk — cursor persistence with zero client\n * code. Control events mark the replay→live transition (`up-to-date`) and\n * settlement (`done` / `error`), mirroring the stream's own lifecycle.\n */\n\nimport type { Streams } from \"./streams\";\nimport type { StreamJson } from \"./types\";\n\nconst encoder = new TextEncoder();\n\n/**\n * Options accepted by {@link sseResponse}.\n *\n * @experimental The API surface may change before stabilizing.\n */\nexport interface SSEResponseOptions {\n  /**\n   * The incoming request. Used for resume (the `Last-Event-ID` header a\n   * reconnecting `EventSource` sends, or a `?from=` query parameter) and to\n   * abort the tail when the client disconnects (`request.signal`).\n   */\n  request?: Request;\n  /** First sequence number to yield. Overrides request-derived resume. */\n  from?: number;\n  /** Extra abort signal; composed with `request.signal`. */\n  signal?: AbortSignal;\n  /** Maximum chunks per write. Defaults to the read batch size (100). */\n  batchSize?: number;\n  /**\n   * Milliseconds between `: heartbeat` comment frames while tailing, keeping\n   * idle proxies from killing the connection. 0 disables. Default: 30000.\n   */\n  heartbeatMs?: number;\n}\n\nfunction resumeFrom(options: SSEResponseOptions): number {\n  if (options.from !== undefined) return Math.max(0, options.from);\n  const request = options.request;\n  if (request) {\n    // A fresh EventSource sends no Last-Event-ID at all; Number(null) is 0,\n    // so the header must be checked for presence before parsing or every\n    // first connection would skip chunk 0.\n    const header = request.headers.get(\"Last-Event-ID\");\n    if (header !== null && header !== \"\") {\n      const lastEventId = Number(header);\n      // Last-Event-ID names the last chunk the client received; resume after.\n      if (Number.isInteger(lastEventId) && lastEventId >= 0) {\n        return lastEventId + 1;\n      }\n    }\n    const fromParam = new URL(request.url).searchParams.get(\"from\");\n    if (fromParam !== null) {\n      const from = Number(fromParam);\n      if (Number.isInteger(from) && from >= 0) return from;\n    }\n  }\n  return 0;\n}\n\nfunction frame(seq: number, chunk: StreamJson): string {\n  // JSON.stringify never emits raw newlines, so one data line is always safe.\n  return `id: ${seq}\\ndata: ${JSON.stringify(chunk)}\\n\\n`;\n}\n\nfunction controlFrame(event: string, data: StreamJson): string {\n  return `event: ${event}\\ndata: ${JSON.stringify(data)}\\n\\n`;\n}\n\n/**\n * Serve one durable stream as a Server-Sent Events response: replay from the\n * resume point, emit an `up-to-date` control event on reaching the tail,\n * tail live appends, and finish with `done` (completed) or `error` (errored,\n * carrying the recorded reason). Returns a 404 response when the stream does\n * not exist.\n *\n * ```ts\n * async onRequest(request: Request) {\n *   return sseResponse(this.streams, \"reply:123\", { request });\n * }\n * // client: new EventSource(url) — reconnect resume is automatic.\n * ```\n *\n * @experimental The API surface may change before stabilizing.\n */\nexport async function sseResponse(\n  streams: Streams,\n  streamId: string,\n  options: SSEResponseOptions = {}\n): Promise<Response> {\n  if ((await streams.status(streamId)) === null) {\n    return new Response(`Stream \"${streamId}\" does not exist`, { status: 404 });\n  }\n\n  const from = resumeFrom(options);\n  const heartbeatMs = options.heartbeatMs ?? 30_000;\n  const abort = new AbortController();\n  const onUpstreamAbort = () => abort.abort();\n  // A listener added to an already-aborted signal never fires: check first,\n  // or a pre-aborted request would tail a live stream forever.\n  if (options.signal?.aborted || options.request?.signal.aborted) {\n    abort.abort();\n  } else {\n    options.signal?.addEventListener(\"abort\", onUpstreamAbort, { once: true });\n    options.request?.signal.addEventListener(\"abort\", onUpstreamAbort, {\n      once: true\n    });\n  }\n\n  let open = true;\n  const body = new ReadableStream<Uint8Array>({\n    start: (controller) => {\n      const write = (text: string) => {\n        if (!open) return;\n        try {\n          controller.enqueue(encoder.encode(text));\n        } catch {\n          // The stream was cancelled between the check and the write (a\n          // heartbeat tick racing a client disconnect): stop writing.\n          open = false;\n        }\n      };\n      const heartbeat =\n        heartbeatMs > 0\n          ? setInterval(() => write(\": heartbeat\\n\\n\"), heartbeatMs)\n          : null;\n      const finish = () => {\n        if (heartbeat !== null) clearInterval(heartbeat);\n        options.signal?.removeEventListener(\"abort\", onUpstreamAbort);\n        options.request?.signal.removeEventListener(\"abort\", onUpstreamAbort);\n        if (open) {\n          open = false;\n          try {\n            controller.close();\n          } catch {\n            // Already cancelled by the consumer.\n          }\n        }\n      };\n\n      void (async () => {\n        try {\n          const batches = streams.readBatches(streamId, {\n            from,\n            signal: abort.signal,\n            batchSize: options.batchSize,\n            onUpToDate: () => write(controlFrame(\"up-to-date\", {}))\n          });\n          for await (const batch of batches) {\n            write(batch.map((chunk) => frame(chunk.seq, chunk.chunk)).join(\"\"));\n          }\n          const status = await streams.status(streamId);\n          if (status?.state === \"errored\") {\n            write(controlFrame(\"error\", { reason: status.error ?? null }));\n          } else {\n            write(controlFrame(\"done\", {}));\n          }\n        } catch {\n          // The client disconnected or the caller aborted: nothing to send.\n        } finally {\n          finish();\n        }\n      })();\n    },\n    cancel: () => {\n      open = false;\n      abort.abort();\n    }\n  });\n\n  return new Response(body, {\n    headers: {\n      \"content-type\": \"text/event-stream; charset=utf-8\",\n      \"cache-control\": \"no-store\"\n    }\n  });\n}\n"],"mappings":"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"}