agents 0.21.0 → 0.23.0

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-D6tJ0NN9.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-DZKgAj9b.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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"}

package/dist/streams-D6tJ0NN9.d.ts

@@ -0,0 +1,370 @@
+import { s as LifecycleCapability } from "./capability-runner-Be_-PLR1.js";
+
+//#region src/streams/types.d.ts
+/**
+ * JSON-serializable data accepted as stream chunks and metadata.
+ *
+ * @experimental The API surface may change before stabilizing.
+ */
+type StreamJson =
+  | string
+  | number
+  | boolean
+  | null
+  | StreamJson[]
+  | {
+      [key: string]: StreamJson;
+    };
+/**
+ * States a stream moves through. A stream is `streaming` from `open()` until
+ * its producer settles it; both terminal states keep the chunk log readable.
+ *
+ * @experimental The API surface may change before stabilizing.
+ */
+type StreamState = "streaming" | "completed" | "errored";
+/**
+ * One durable chunk. `seq` is the stream's monotonic cursor: 0-based,
+ * assigned at append time, and stable across replays.
+ *
+ * @experimental The API surface may change before stabilizing.
+ */
+interface StreamChunk {
+  readonly seq: number;
+  readonly chunk: StreamJson;
+}
+/**
+ * Read-only status of one stream — the recovery-evidence surface a Task's
+ * `recover` callback consults.
+ *
+ * @experimental The API surface may change before stabilizing.
+ */
+interface StreamStatus {
+  streamId: string;
+  state: StreamState;
+  /** The next sequence number to be assigned == durable chunk count. */
+  cursor: number;
+  /** Application lookup key assigned at `open()`, when one was. */
+  tag?: string;
+  metadata?: Record<string, StreamJson>;
+  /** Reason recorded by `error()`, when the state is `errored`. */
+  error?: string;
+  createdAt: number;
+  /**
+   * Last write activity: advances with every append and with settlement.
+   * The liveness signal retention policies key off — a `streaming` stream
+   * whose `updatedAt` is old has a producer that stopped appending. (For a
+   * live stream this is derived from the chunk log's newest entry; the
+   * stored row is only stamped at open and settle.)
+   */
+  updatedAt: number;
+  closedAt?: number;
+}
+/**
+ * Producer handle returned by `Streams.open()`. Appends are synchronous
+ * durable writes; a terminal stream rejects further appends.
+ *
+ * @experimental The API surface may change before stabilizing.
+ */
+interface StreamWriter {
+  readonly streamId: string;
+  /** The next sequence number to be assigned. */
+  readonly cursor: number;
+  /** Durably append one chunk and wake live readers. Returns its `seq`. */
+  append(chunk: StreamJson): number;
+  /**
+   * Settle the stream as completed. No-op if already terminal or deleted:
+   * `options.commit` runs only when this call ends the stream.
+   */
+  close(options?: StreamSettleOptions): void;
+  /** Settle the stream as errored. Same no-op contract as {@link close}. */
+  error(reason?: string, options?: StreamSettleOptions): void;
+}
+/**
+ * The cutover: settle a stream, run the caller's own synchronous writes
+ * (typically persisting the finished message), and discard the stream's
+ * rows, all in ONE SQLite transaction. A crash leaves either the live
+ * stream or the finished message, never neither. `commit` must not await
+ * and must not throw for a reason it wants ignored: a throw rolls the
+ * settle back and leaves the stream live.
+ *
+ * Settlement stays idempotent: on a stream already terminal or deleted,
+ * `commit` does not run and nothing is discarded. Events and reader wakeups
+ * fire after the transaction commits, never for a rolled-back cutover.
+ *
+ * @experimental The API surface may change before stabilizing.
+ */
+interface StreamSettleOptions {
+  /** Synchronous writes to commit with the settlement. */
+  readonly commit?: () => void;
+  /**
+   * Delete the stream's rows in the same transaction. The stream ceases
+   * to exist (`status()` returns null); readers tailing it end. Use when
+   * the chunks have been handed off, so nothing is left to sweep later.
+   */
+  readonly discard?: boolean;
+}
+/** Options accepted by `Streams.open()`. */
+interface StreamOpenOptions {
+  /** JSON metadata retained with the stream. */
+  metadata?: Record<string, StreamJson>;
+  /**
+   * Indexed application lookup key, set once at creation. Deliberately not
+   * unique: an operation that produces successive streams (a retried turn, a
+   * regenerated reply) stamps each with the same tag, and
+   * `list({ tag, limit: 1 })` finds the latest. Reopening a live stream with
+   * a *different* tag throws — a config conflict, not a new stream.
+   */
+  tag?: string;
+}
+/** Options accepted by `Streams.read()`. */
+interface StreamReadOptions {
+  /** First sequence number to yield (inclusive). Defaults to 0. */
+  from?: number;
+  /** Abort a read that is tailing a live stream. */
+  signal?: AbortSignal;
+}
+/** Options accepted by `Streams.readBatches()`. */
+interface StreamReadBatchesOptions extends StreamReadOptions {
+  /** Maximum chunks per yielded batch. Defaults to 100. */
+  batchSize?: number;
+  /**
+   * Invoked once, the first time the reader reaches the durable tail —
+   * i.e. every chunk stored so far has been yielded. Distinct from the
+   * stream ending: a live stream is "up to date" while tailing. Useful as a
+   * transition signal (flush replayed UI, show a live indicator).
+   */
+  onUpToDate?: () => void;
+}
+/** Filters accepted by `Streams.list()`. */
+interface StreamListOptions {
+  state?: StreamState | StreamState[];
+  /** Only streams opened with this exact tag (indexed). */
+  tag?: string;
+  limit?: number;
+}
+/**
+ * @internal Raw `cf_agents_streams` SQLite row.
+ *
+ * While `state` is `streaming`, `chunk_count` and `updated_at` are NOT
+ * maintained per append (appends write only the chunk log; the log's tail
+ * is authoritative — see `Streams.#tail`). Both are stamped exact by the
+ * settle UPDATE, so terminal rows read straight through. Consumers of a
+ * live row must derive cursor/liveness rather than trust these columns.
+ */
+type StreamRow = {
+  stream_id: string;
+  state: StreamState;
+  tag: string | null;
+  metadata: string | null;
+  error_message: string | null;
+  chunk_count: number;
+  created_at: number;
+  updated_at: number;
+  closed_at: number | null;
+};
+/** @internal One chunk as read back from a `cf_agents_stream_blocks` row. */
+type StreamChunkRow = {
+  stream_id: string;
+  seq: number;
+  chunk: string;
+  created_at: number;
+};
+//#endregion
+//#region src/streams/streams.d.ts
+/** Default ceiling for one serialized chunk (1 MiB). */
+declare const DEFAULT_MAX_CHUNK_BYTES = 1048576;
+/**
+ * Policy for a Streams capability.
+ *
+ * @experimental The API surface may change before stabilizing.
+ */
+interface StreamsOptions {
+  /** Ceiling for one serialized chunk. Default: 1 MiB. */
+  readonly maxChunkBytes?: number;
+}
+/**
+ * @internal Synchronous operations returned by
+ * {@link Streams.__DO_NOT_USE_WILL_BREAK__sync}. For same-isolate first-party
+ * machinery only (the chat `ResumableStream` adapter); every method bypasses
+ * `lifecycle.ready()`, so the caller owns startup ordering.
+ */
+interface StreamsSyncInternal {
+  /** Idempotent DDL — safe to call before the Lifecycle starts. */
+  ensureTables(): void;
+  getStream(streamId: string): StreamRow | undefined;
+  /** Insert a live stream row (no idempotency — caller checks first). */
+  insertStream(
+    streamId: string,
+    tag: string | null,
+    metadata: Record<string, StreamJson> | undefined
+  ): void;
+  /** The read-fenced append: one chunk insert at the log tail, reader wakeup. */
+  append(streamId: string, chunk: StreamJson): number;
+  /**
+   * The newest chunk's timestamp, or null for an empty log. One PK-served
+   * read — the per-append liveness signal retention sweeps verify against
+   * (a live row's `updated_at` is set at open and not bumped by appends).
+   */
+  lastChunkAt(streamId: string): number | null;
+  /**
+   * Segments durably appended so far: the chunk log's tail, read in the
+   * calling synchronous block. Zero for an unknown stream.
+   */
+  cursor(streamId: string): number;
+  /**
+   * Observe every deletion of a stream's rows — the public `delete()`, the
+   * aperture's own deletes, and a cutover's discard — with the row and its
+   * cursor as they were just before removal, in the same synchronous block
+   * (and, for a cutover, the same transaction). Hooks must be synchronous
+   * and must not await: the cutover runs them inside `transactionSync`.
+   * The chat adapter uses this to keep its recovery progress marker exact
+   * however a chat row leaves the table. Returns the unsubscribe: an owner
+   * constructed again (a host whose startup retried) must drop its earlier
+   * hook, or a deletion is observed once per construction.
+   */
+  onDelete(hook: (row: StreamRow, cursor: number) => void): () => void;
+  /**
+   * Idempotent settlement with events and reader wakeup. With `options`,
+   * the settle, the caller's `commit` writes and the log discard run in
+   * one SQLite transaction (see {@link StreamSettleOptions}). Returns
+   * whether the stream transitioned; on a repeat or a deleted stream the
+   * `commit` callback does not run.
+   */
+  settle(
+    streamId: string,
+    state: "completed" | "errored",
+    reason: string | null,
+    options?: StreamSettleOptions
+  ): boolean;
+  /** Delete a stream and its chunks regardless of state. */
+  deleteUnchecked(streamId: string): void;
+  /** Delete many streams and their chunks regardless of state, silently. */
+  deleteMany(streamIds: string[]): void;
+  /**
+   * One page of a stream's chunk log from `fromSeq` (inclusive), ordered by
+   * seq. Paged rather than read-it-all so replaying a large stream holds
+   * one page of segment bodies in memory, not the whole turn.
+   */
+  readChunks(
+    streamId: string,
+    fromSeq: number,
+    limit: number
+  ): StreamChunkRow[];
+  /** Every stream row, newest first (created_at, then insertion order). */
+  listRows(): StreamRow[];
+  /**
+   * Every row carrying a tag, newest first, optionally narrowed to one
+   * state. Tags are non-unique and the table is shared across producers,
+   * so callers apply their own ownership filter (e.g. chat's metadata
+   * marker) rather than trusting the newest row.
+   */
+  rowsByTag(tag: string, state?: StreamState): StreamRow[];
+  /**
+   * Import one historical stream row verbatim (migrations, test seeding):
+   * explicit timestamps and count, no events, no wakeups.
+   */
+  importStream(row: {
+    streamId: string;
+    state: StreamState;
+    tag: string | null;
+    metadata: Record<string, StreamJson> | undefined;
+    chunkCount: number;
+    createdAt: number;
+    updatedAt: number;
+    closedAt: number | null;
+  }): void;
+  /**
+   * Import one historical chunk at the log's tail: one INSERT, nothing else.
+   * The stream row is not touched — importers pass the final `chunkCount`
+   * and `updatedAt` to {@link importStream}, so the row is exact at rest
+   * without a per-chunk row write.
+   */
+  importChunk(streamId: string, chunk: StreamJson, createdAt: number): void;
+}
+/**
+ * Durable incremental output for a Lifecycle Object.
+ *
+ * `open()` a stream, `append()` chunks (synchronous durable writes that wake
+ * live readers), and settle it with `close()` or `error()`. `read()` replays
+ * persisted chunks from a cursor and then tails live appends; `status()`
+ * reports the state and cursor — the recovery evidence a Task's `recover`
+ * callback consults after its producer was interrupted.
+ *
+ * @experimental The API surface may change before stabilizing.
+ */
+declare class Streams extends LifecycleCapability {
+  #private;
+  constructor(options?: StreamsOptions);
+  /** Migrate stream storage during Lifecycle startup. */
+  onStart(): Promise<void>;
+  /**
+   * Open a stream for writing. Idempotent on the id: reopening a live stream
+   * returns a writer positioned at its current cursor; reopening a terminal
+   * stream throws {@link StreamClosedError}.
+   */
+  open(streamId: string, options?: StreamOpenOptions): Promise<StreamWriter>;
+  /**
+   * Replay persisted chunks from `from` (inclusive), then tail live appends
+   * until the stream settles. Ends when the stream reaches a terminal state
+   * and every durable chunk has been yielded; a read of an `errored` stream
+   * still yields its chunks and then simply ends — consult {@link status}
+   * for the terminal outcome. Aborting `options.signal` throws its reason.
+   */
+  read(
+    streamId: string,
+    options?: StreamReadOptions
+  ): AsyncGenerator<StreamChunk, void, undefined>;
+  /**
+   * Batched form of {@link read}: yields non-empty arrays of consecutive
+   * chunks instead of one chunk at a time. Replay yields up to
+   * `options.batchSize` chunks per array; a live tail yields everything
+   * that accumulated since the last wakeup as one array — so a consumer
+   * paying per write (an SSE flush, an RPC hop, a history append) pays
+   * once per backlog, not once per chunk. Same lifecycle as {@link read}:
+   * ends when the stream settles and every durable chunk has been
+   * yielded; aborting `options.signal` throws its reason.
+   */
+  readBatches(
+    streamId: string,
+    options?: StreamReadBatchesOptions
+  ): AsyncGenerator<StreamChunk[], void, undefined>;
+  /** Read one stream's state and cursor, or null when it does not exist. */
+  status(streamId: string): Promise<StreamStatus | null>;
+  /** List streams, newest first. */
+  list(options?: StreamListOptions): Promise<StreamStatus[]>;
+  /**
+   * Delete one terminal stream and its chunk log.
+   *
+   * @returns True when a terminal stream was deleted; false when none
+   * exists. Throws on a live stream — settle it first.
+   */
+  delete(streamId: string): Promise<boolean>;
+  /**
+   * @internal Synchronous storage operations for same-isolate first-party
+   * machinery — today the chat `ResumableStream` adapter, whose whole public
+   * surface is synchronous and constructed before the Lifecycle starts.
+   * Bypasses `lifecycle.ready()`: the caller owns startup ordering. The
+   * invariant-bearing writes (append fence, settlement, wakeups, events) go
+   * through the same private methods as the public API, so live readers and
+   * diagnostics observe aperture writes exactly like capability writes. Will
+   * break without notice; never use from application code.
+   */
+  __DO_NOT_USE_WILL_BREAK__sync(): StreamsSyncInternal;
+}
+//#endregion
+export {
+  StreamJson as a,
+  StreamReadBatchesOptions as c,
+  StreamState as d,
+  StreamStatus as f,
+  StreamChunk as i,
+  StreamReadOptions as l,
+  Streams as n,
+  StreamListOptions as o,
+  StreamWriter as p,
+  StreamsOptions as r,
+  StreamOpenOptions as s,
+  DEFAULT_MAX_CHUNK_BYTES as t,
+  StreamSettleOptions as u
+};
+//# sourceMappingURL=streams-D6tJ0NN9.d.ts.map