@acid-cat/core-ts 0.8.0 → 0.10.0

package/dist/mcp.js

@@ -1,17 +1,20 @@
 import { createSession } from "./session.js";
-import { withContext } from "./context.js";
-import { MCP_PROTOCOL_VERSION, MCP_REJECTIONS, MCP_UNKNOWN_TOOL, bundle, isJsonObject, mcpToolResult, readBounded, screenRequest } from "@acid-cat/spec-ts";
+import { openContext } from "./context.js";
+import { textStream } from "./stream.js";
+import { eventCapabilities, forbidden, listEvents, servesEvents, startEventStream, unsupportedWebhook } from "./mcp-events.js";
+import { PollLeases } from "./mcp-poll.js";
+import { KEEPALIVE_MS, MCP_PROTOCOL_VERSION, MCP_REJECTIONS, MCP_UNKNOWN_TOOL, SSE_MEDIA_TYPE, bundle, isJsonObject, mcpToolResult, readBounded, screenRequest, sseMessage } from "@acid-cat/spec-ts";
 //#region src/mcp.ts
 /**
-* The MCP binding (spec/bindings/mcp.md): an MCP server through HTTP, revision 2026-07-28, with no state on the
-* server between requests.
+* The MCP binding (spec/bindings/mcp.md): an MCP server through HTTP, revision 2026-07-28. The server keeps no state
+* between requests, except poll leases and webhook subscriptions.
 */
 /**
 * Read the members of a JSON-RPC request from a parsed body. A member that does not have its type is left out. An
 * `id` that is not a string or a number is `null`.
 */
 function readRequest(body) {
-	if (!isJsonObject(body)) return {};
+	if (!isJsonObject(body)) return { params: {} };
 	const { id, method, params } = body;
 	const meta = isJsonObject(params) ? params["_meta"] : void 0;
 	return {
@@ -19,13 +22,22 @@ function readRequest(body) {
 		method: typeof method === "string" ? method : void 0,
 		name: isJsonObject(params) && typeof params["name"] === "string" ? params["name"] : void 0,
 		arguments: isJsonObject(params) ? params["arguments"] : void 0,
+		params: isJsonObject(params) ? params : {},
 		protocolVersion: isJsonObject(meta) ? meta["io.modelcontextprotocol/protocolVersion"] : void 0
 	};
 }
-/** A web request handler for the MCP server. Each request has its own session, and with `createContext` its own context. */
+/**
+* A web request handler for the MCP server. Each request has its own session, and with `createContext` its own
+* context. Each poll lease and each webhook subscription also has its own session, opened with the context of the
+* request that started it.
+*/
 function mcpHandler(app, options) {
 	const maximumBytes = options.maximumBytes ?? 1048576;
-	return async (request) => {
+	const leases = new PollLeases(options.poll, options.clock);
+	const closeAll = async () => {
+		await Promise.allSettled([leases.close(), options.webhooks?.close()]);
+	};
+	const handle = async (request) => {
 		const screened = screenRequest(request, {
 			methods: ["POST"],
 			allowedOrigins: options.allowedOrigins,
@@ -52,30 +64,91 @@ function mcpHandler(app, options) {
 		const metaVersion = message.protocolVersion;
 		if (metaVersion === void 0) return error(400, id, -32602, "Required request metadata is missing");
 		if (metaVersion !== version) return error(400, id, -32020, "MCP-Protocol-Version header does not match request metadata");
-		return withContext(options, request, async (context) => {
+		const open = async () => {
+			const opened = await openContext(options, request);
 			const session = createSession(app, {
 				target: options.target ?? "mcp",
-				context,
-				toJsonSchema: options.toJsonSchema
+				context: opened.context,
+				toJsonSchema: options.toJsonSchema,
+				...options.bufferLimit === void 0 ? {} : { bufferLimit: options.bufferLimit }
 			});
-			try {
-				return await answer(session, message, {
-					...options,
-					instructions: options.instructions ?? app.description
-				}, request.signal);
-			} finally {
+			let closing;
+			const close = () => closing ??= (async () => {
 				await session.dispose();
+				await opened.release();
+			})();
+			return {
+				session,
+				close
+			};
+		};
+		const { session, close } = await open();
+		let streaming = false;
+		try {
+			if (message.method === "events/stream" && message.id !== null && servesEvents(session)) {
+				const started = await startEventStream(session, message.id, message.params, {
+					heartbeatMs: options.heartbeatMs ?? KEEPALIVE_MS,
+					resultMeta: serverInfoOf(options),
+					signal: request.signal
+				});
+				if ("error" in started) return error(200, id, started.error.code, started.error.message, started.error.data);
+				const { messages, cancel } = started;
+				const produce = async () => (await messages())?.map((each) => sseMessage({ data: JSON.stringify(each) }));
+				const body = textStream(produce, cancel, close);
+				streaming = true;
+				return new Response(body, {
+					status: 200,
+					headers: {
+						"Content-Type": SSE_MEDIA_TYPE,
+						"Cache-Control": "no-store"
+					}
+				});
 			}
-		});
+			if (servesEvents(session) && message.method !== void 0 && LONG_LIVED.has(message.method)) {
+				const principal = await options.principal?.(request);
+				const answered = await longLived(message.method, message.params, principal, open, leases, options.webhooks);
+				if ("error" in answered) return error(200, id, answered.error.code, answered.error.message, answered.error.data);
+				return reply(id, {
+					_meta: serverInfoOf(options),
+					resultType: "complete",
+					...answered.result
+				});
+			}
+			return await answer(session, message, {
+				...options,
+				instructions: options.instructions ?? app.description
+			}, request.signal);
+		} finally {
+			if (!streaming) await close();
+		}
 	};
+	return Object.assign(handle, {
+		close: closeAll,
+		[Symbol.asyncDispose]: closeAll
+	});
+}
+/** The methods whose state outlives the request (spec/bindings/mcp.md#subscriptions-that-outlive-a-request). */
+const LONG_LIVED = /* @__PURE__ */ new Set([
+	"events/poll",
+	"events/subscribe",
+	"events/unsubscribe"
+]);
+/** Answer `events/poll`, `events/subscribe` or `events/unsubscribe`. */
+async function longLived(method, params, principal, open, leases, webhooks) {
+	if (method === "events/poll") return leases.poll(principal, params, open);
+	if (webhooks === void 0) return { error: unsupportedWebhook };
+	if (principal === void 0) return { error: forbidden };
+	return method === "events/subscribe" ? webhooks.subscribe(principal, params, open) : webhooks.unsubscribe(principal, params);
 }
+/** The `_meta` of a result: the information about the server. */
+const serverInfoOf = (options) => ({ "io.modelcontextprotocol/serverInfo": {
+	name: options.name,
+	version: options.version
+} });
 async function answer(session, message, options, signal) {
 	const id = message.id ?? null;
 	const complete = (result, list = false) => reply(id, {
-		_meta: { "io.modelcontextprotocol/serverInfo": {
-			name: options.name,
-			version: options.version
-		} },
+		_meta: serverInfoOf(options),
 		resultType: "complete",
 		...list ? {
 			ttlMs: 0,
@@ -86,7 +159,10 @@ async function answer(session, message, options, signal) {
 	switch (message.method) {
 		case "server/discover": return complete({
 			supportedVersions: [MCP_PROTOCOL_VERSION],
-			capabilities: { tools: { listChanged: false } },
+			capabilities: {
+				tools: { listChanged: false },
+				...eventCapabilities(session)
+			},
 			...options.instructions === void 0 ? {} : { instructions: options.instructions }
 		}, true);
 		case "tools/list": return complete({ tools: listTools(session) }, true);
@@ -97,9 +173,13 @@ async function answer(session, message, options, signal) {
 			const outcome = await session.invoke(name, message.arguments ?? {}, { signal });
 			return complete(mcpToolResult(outcome, hasObjectOutput(session, name)));
 		}
-		default: return error(404, id, -32601, `Method not found: ${message.method}`);
+		case "events/list":
+			if (!servesEvents(session)) break;
+			return complete({ events: listEvents(session, options.webhooks !== void 0) }, true);
 	}
+	return error(404, id, -32601, `Method not found: ${message.method}`);
 }
+/** The tools of the available capabilities in the view of a session (spec/bindings/mcp.md#tools). */
 function listTools(session) {
 	const types = session.view.$defs ?? {};
 	return [...session.handles.values()].filter((handle) => handle.availability.getSnapshot().available).map((handle) => {
@@ -115,6 +195,7 @@ function listTools(session) {
 		};
 	});
 }
+/** True if the bundled output schema of a capability has `"type": "object"`. */
 function hasObjectOutput(session, id) {
 	const output = session.view.capabilities[id]?.output;
 	return output !== void 0 && bundle(output, session.view.$defs ?? {}).type === "object";
@@ -173,4 +254,4 @@ const messages = {
 	"not-utf8": "The request body is not UTF-8 JSON."
 };
 //#endregion
-export { mcpHandler };
+export { hasObjectOutput, listTools, mcpHandler };

package/dist/node.d.ts

@@ -1,3 +1,5 @@
+export { webhookDelivery } from "./webhook.js";
+export type { WebhookOptions } from "./webhook.js";
 /** A web request handler. */
 export type WebHandler = (request: Request) => Promise<Response> | Response;
 /**

package/dist/node.js

@@ -1,8 +1,11 @@
+import { webhookDelivery } from "./webhook.js";
 import { createServer } from "node:http";
 //#region src/node.ts
 /**
 * The functions that need Node.js. The main entry point, `@acid-cat/core-ts`, works in all runtimes.
 *
+* `webhookDelivery` sends the occurrences of webhook subscriptions of the MCP server through HTTP, with `node:https`.
+*
 * `serve` serves web request handlers, `(request: Request) => Promise<Response>`, such as the handlers of `mcpHandler`
 * and `httpHandler`, on Node.js, with only `node:http`. The server serves plain HTTP/1.1. For HTTPS, HTTP/2 or
 * middleware, use a library for web handlers.
@@ -107,6 +110,7 @@ async function send(response, outgoing) {
 		outgoing.end();
 		return;
 	}
+	outgoing.flushHeaders();
 	const reader = response.body.getReader();
 	const cancel = () => void reader.cancel().catch(() => void 0);
 	outgoing.on("close", cancel);
@@ -169,4 +173,4 @@ function bodyOf(incoming) {
 	}, { highWaterMark: 0 });
 }
 //#endregion
-export { serve };
+export { serve, webhookDelivery };

package/dist/session.d.ts

@@ -1,5 +1,34 @@
-import type { Availability, CatalogDocument, Outcome, Result } from "@acid-cat/spec-ts";
-import type { App, Capability, FailureOf, Observable, ToJsonSchema } from "./app.js";
+import type { Availability, CallFailure, CatalogDocument, Outcome, Result } from "@acid-cat/spec-ts";
+import type { App, Capability, EventDefinition, FailureOf, Observable, ToJsonSchema } from "./app.js";
+import type { Occurrences } from "./subscription.js";
+/** The options of a subscription (spec/bindings/typescript.md#event-handles). */
+export interface SubscribeOptions {
+    /** Cancel the subscription. */
+    readonly signal?: AbortSignal | undefined;
+    /** Start after this position (spec/events.md#resuming). */
+    readonly cursor?: string | undefined;
+    /** Send no occurrence that is older than this number of milliseconds. */
+    readonly maxAgeMs?: number | undefined;
+}
+/**
+ * The handle of an event (spec/bindings/typescript.md#event-handles). `session.eventHandle` gives a handle with the
+ * types of the event. A handle of `session.eventHandles` has the input type `never`: only `subscribeExternal` can
+ * subscribe with it, because it decodes the input.
+ */
+export interface EventHandle<Input = never, Payload = unknown> {
+    readonly id: string;
+    readonly description: string;
+    readonly audience: readonly string[];
+    /**
+     * A subscription with an input that is already valid. The promise resolves when the subscription has started. A call
+     * failure before the first occurrence rejects with a `CallFailureError`.
+     */
+    subscribe(input: Input, options?: SubscribeOptions): Promise<Occurrences<Payload>>;
+    /** A subscription with an input that is not trusted. The handle validates it first. */
+    subscribeExternal(input: unknown, options?: SubscribeOptions): Promise<Occurrences<unknown>>;
+}
+/** The handle of an event, with the types of its schemas. `session.eventHandle` gives it. */
+export type EventHandleOf<E> = E extends EventDefinition<never, infer Input, infer Payload, string> ? EventHandle<Input, Payload> : never;
 /**
  * The handle of a capability (spec/bindings/typescript.md#handles). `Input`, `Value`, `Failure` and `State` are the
  * types of the schemas of the capability. `session.handle` gives a handle with these types. A handle of
@@ -47,6 +76,19 @@ export interface Session<Context = unknown> {
     readonly call: <Input, Value, Failures, State, Id extends string>(capability: Capability<Context, Input, Value, Failures, State, Id>, input: unknown, options?: {
         readonly signal?: AbortSignal | undefined;
     }) => Promise<Result<Value, FailureOf<Failures>>>;
+    /** The handles of the events in the view, by id. Bindings use them. */
+    readonly eventHandles: ReadonlyMap<string, EventHandle>;
+    /**
+     * The handle of an event, with the types of the event. Only the event object that the session serves gets a handle
+     * that subscribes to it. Any other event, also one with the same id, gets a handle whose subscriptions reject as
+     * `unknown-capability`.
+     */
+    readonly eventHandle: <Input, Payload, Id extends string>(event: EventDefinition<Context, Input, Payload, Id>) => EventHandle<Input, Payload>;
+    /**
+     * A subscription with an input that is not trusted. The promise never rejects: it gives the occurrences, or the call
+     * failure before the first occurrence.
+     */
+    readonly subscribe: (id: string, input: unknown, options?: SubscribeOptions) => Promise<Occurrences<unknown> | CallFailure>;
     /** A call with an input that is not trusted. The outcome is in its JSON form. The promise never rejects. */
     readonly invoke: (id: string, input: unknown, options?: {
         readonly signal?: AbortSignal | undefined;
@@ -60,7 +102,10 @@ export interface Session<Context = unknown> {
     };
     /** The signal of the session. It aborts when the session closes. */
     readonly signal: AbortSignal;
-    /** Close the session: accept no new calls, cancel the calls in progress, and wait for them. */
+    /**
+     * Close the session: accept no new calls and subscriptions, cancel the calls in progress, end each subscription as
+     * complete, and wait for the calls.
+     */
     readonly dispose: () => Promise<void>;
     /** Close the session, as `dispose` does, at the end of the block of `await using session = createSession(…)`. */
     readonly [Symbol.asyncDispose]: () => Promise<void>;
@@ -72,6 +117,11 @@ export interface SessionOptions<Context> {
     readonly toJsonSchema: ToJsonSchema;
     /** Record a defect. The default writes it to the console. */
     readonly onDefect?: ((id: string, cause: unknown) => void) | undefined;
+    /**
+     * The number of occurrences that each subscription keeps for a client that reads slowly. When the limit is full, the
+     * oldest occurrence goes, and the next occurrence that the client reads has `truncated: true`. The default is 256.
+     */
+    readonly bufferLimit?: number | undefined;
 }
 /** Open a session for a target. */
 export declare function createSession<Context>(app: App<Context>, options: SessionOptions<Context>): Session<Context>;

package/dist/session.js

@@ -1,9 +1,21 @@
 import { catalogOf } from "./app.js";
+import { runSubscription } from "./subscription.js";
 import { AVAILABLE, CallFailureError, callFailure, isCallFailure, viewOf } from "@acid-cat/spec-ts";
 //#region src/session.ts
 /**
 * Sessions and handles (spec/invocation.md, spec/bindings/typescript.md).
 */
+/** The handle of an event that the session does not serve. Each subscription rejects as `unknown-capability`. */
+function eventOutsideView(event) {
+	const reject = () => Promise.reject(new CallFailureError(callFailure("unknown-capability", `There is no event ${event.id}.`)));
+	return {
+		id: event.id,
+		description: event.description,
+		audience: [],
+		subscribe: reject,
+		subscribeExternal: reject
+	};
+}
 /** The handle of a capability that the session does not serve. */
 function outsideView(capability) {
 	const failure = callFailure("unknown-capability", `There is no capability ${capability.id}.`);
@@ -34,7 +46,7 @@ function createSession(app, options) {
 	const running = /* @__PURE__ */ new Set();
 	const listeners = /* @__PURE__ */ new Set();
 	let subscriptions = [];
-	const onDefect = options.onDefect ?? ((id, cause) => console.error(`A capability failed with a defect: ${id}`, cause));
+	const onDefect = options.onDefect ?? ((id, cause) => console.error(`A capability or an event failed with a defect: ${id}`, cause));
 	const served = /* @__PURE__ */ new Map();
 	for (const capability of app.capabilities) {
 		if (!capability.audience.includes(options.target)) continue;
@@ -145,6 +157,102 @@ function createSession(app, options) {
 			invokeExternal
 		});
 	}
+	const servedEvents = /* @__PURE__ */ new Map();
+	for (const event of app.events ?? []) {
+		if (!event.audience.includes(options.target)) continue;
+		if (served.has(event.id) || servedEvents.has(event.id)) throw new Error(`The id ${event.id} is declared two times.`);
+		servedEvents.set(event.id, event);
+	}
+	const bufferLimit = options.bufferLimit ?? 256;
+	/**
+	* Start a subscription to an event that the session serves: the decoded input, then the provider, with cancellation.
+	* The result is the occurrences, or the call failure before the first occurrence.
+	*/
+	async function start(id, prepare, check, subscribeOptions = {}) {
+		const { signal } = subscribeOptions;
+		const cancelled = () => lifetime.signal.aborted || signal?.aborted === true;
+		if (cancelled()) return callFailure("cancelled", "The subscription was cancelled.");
+		let prepared;
+		try {
+			prepared = await prepare();
+		} catch (cause) {
+			onDefect(id, cause);
+			return callFailure("internal", "The event failed.");
+		}
+		if (cancelled()) return callFailure("cancelled", "The subscription was cancelled.");
+		if ("issues" in prepared) return callFailure("invalid-input", issueMessage(prepared.issues));
+		const controller = new AbortController();
+		let source;
+		try {
+			source = prepared.start({
+				signal: controller.signal,
+				context: options.context,
+				...subscribeOptions.cursor === void 0 ? {} : { cursor: subscribeOptions.cursor },
+				...subscribeOptions.maxAgeMs === void 0 ? {} : { maxAgeMs: subscribeOptions.maxAgeMs }
+			});
+			if (!isAsyncIterable(source)) throw new TypeError("subscribe did not give an async iterable.");
+		} catch (cause) {
+			onDefect(id, cause);
+			return callFailure("internal", "The event failed.");
+		}
+		const complete = () => running.complete();
+		const cancel = () => running.cancel();
+		const running = runSubscription({
+			name: id,
+			source,
+			check,
+			controller,
+			limit: bufferLimit,
+			onDefect: (cause) => onDefect(id, cause),
+			onEnd: () => {
+				lifetime.signal.removeEventListener("abort", complete);
+				signal?.removeEventListener("abort", cancel);
+			}
+		});
+		lifetime.signal.addEventListener("abort", complete);
+		signal?.addEventListener("abort", cancel);
+		return running.occurrences;
+	}
+	/** A subscription with an input that is not trusted. The data of each occurrence is a copy in its JSON form. */
+	async function subscribe(id, input, subscribeOptions) {
+		if (lifetime.signal.aborted || subscribeOptions?.signal?.aborted === true) return callFailure("cancelled", "The subscription was cancelled.");
+		const event = servedEvents.get(id);
+		if (event === void 0) return callFailure("unknown-capability", `There is no event ${id}.`);
+		return start(id, () => event.decode(input), (data) => checkPayload(event.payload, data, (value) => value), subscribeOptions);
+	}
+	/** Reject a call failure, as an event handle does. */
+	const opened = async (subscription) => {
+		const settled = await subscription;
+		if ("kind" in settled) throw new CallFailureError(settled);
+		return settled;
+	};
+	/** The typed handle of an event that the session serves, or the handle outside the view. */
+	function eventHandle(event) {
+		if (servedEvents.get(event.id) !== event) return eventOutsideView(event);
+		const source = (input, subscription) => event.input === void 0 ? event.subscribe({}, subscription) : event.subscribe(input, subscription);
+		const check = (data) => checkPayload(event.payload, data, () => data);
+		return {
+			id: event.id,
+			description: event.description,
+			audience: [options.target],
+			subscribe: (input, subscribeOptions) => {
+				if (lifetime.signal.aborted || subscribeOptions?.signal?.aborted === true) return Promise.reject(new CallFailureError(callFailure("cancelled", "The subscription was cancelled.")));
+				return opened(start(event.id, () => Promise.resolve({ start: (subscription) => source(input, subscription) }), check, subscribeOptions));
+			},
+			subscribeExternal: (input, subscribeOptions) => opened(subscribe(event.id, input, subscribeOptions))
+		};
+	}
+	const eventHandles = /* @__PURE__ */ new Map();
+	for (const [id, event] of servedEvents) {
+		const subscribeExternal = (input, subscribeOptions) => opened(subscribe(id, input, subscribeOptions));
+		eventHandles.set(id, {
+			id,
+			description: event.description,
+			audience: [options.target],
+			subscribe: subscribeExternal,
+			subscribeExternal
+		});
+	}
 	const unsubscribeAll = () => {
 		subscriptions.forEach((subscription) => subscription.unsubscribe());
 		subscriptions = [];
@@ -163,6 +271,9 @@ function createSession(app, options) {
 		},
 		handles,
 		handle,
+		eventHandles,
+		eventHandle,
+		subscribe,
 		call: (capability, input, callOptions) => call(capability, input, callOptions?.signal),
 		signal: lifetime.signal,
 		invoke: (id, input, callOptions) => invoke(id, input, callOptions?.signal),
@@ -185,6 +296,23 @@ function createSession(app, options) {
 function issueMessage(issues) {
 	return issues.map((issue) => `${(issue.path ?? []).map((key) => typeof key === "object" ? String(key.key) : String(key)).join(".") || "input"}: ${issue.message}`).join("; ");
 }
+/** True if a value is an async iterable. */
+function isAsyncIterable(value) {
+	return typeof value === "object" && value !== null && Symbol.asyncIterator in value && typeof value[Symbol.asyncIterator] === "function";
+}
+/**
+* Check the data of an occurrence against the payload schema, and give a copy of the output of the schema. With no
+* payload schema, the data must be an empty object, and `empty` gives the value. Data that does not agree is a defect.
+*/
+async function checkPayload(schema, data, empty) {
+	if (schema === void 0) {
+		if (typeof data !== "object" || data === null || Array.isArray(data) || Object.keys(data).length > 0) throw new Error("The data of an occurrence of an event with no payload schema is not an empty object.");
+		return structuredClone(empty(data));
+	}
+	const checked = await schema["~standard"].validate(data);
+	if (checked.issues !== void 0) throw new Error(`The data of an occurrence does not agree with the payload schema: ${checked.issues[0]?.message}`);
+	return structuredClone(checked.value);
+}
 /** An observable whose values are copies, so that a client cannot change the data of the provider. */
 function detached(source) {
 	return {

package/dist/stream.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Streams of messages for the bindings that serve events through a connection: the next occurrence or a sign that the
+ * stream is idle, and a web stream of text.
+ */
+import type { Occurrence } from "@acid-cat/spec-ts";
+import type { Occurrences } from "./subscription.js";
+/** One pull of a subscription: the next step, the error that ends it, or `idle` when nothing came in time. */
+export type Pulled<Payload> = {
+    readonly idle: true;
+} | {
+    readonly step: IteratorResult<Occurrence<Payload>, undefined>;
+} | {
+    readonly error: unknown;
+};
+/**
+ * A function that pulls the next step of a subscription. It gives `idle` when no step comes within `idleMs`
+ * milliseconds. The `next()` that waits is kept for the next pull, so no occurrence is lost.
+ */
+export declare function idlePuller<Payload>(occurrences: Occurrences<Payload>, idleMs: number): () => Promise<Pulled<Payload>>;
+/**
+ * A web stream of text. The stream calls `produce` each time that the client can take more: it gives the next messages,
+ * or `undefined` at the end. When the client cancels the stream, the stream calls `cancel`. `release` runs one time, when
+ * the stream ends in any way.
+ */
+export declare function textStream(produce: () => Promise<readonly string[] | undefined>, cancel: () => void, release: () => Promise<void>): ReadableStream<Uint8Array>;

package/dist/stream.js

@@ -0,0 +1,63 @@
+//#region src/stream.ts
+/**
+* A function that pulls the next step of a subscription. It gives `idle` when no step comes within `idleMs`
+* milliseconds. The `next()` that waits is kept for the next pull, so no occurrence is lost.
+*/
+function idlePuller(occurrences, idleMs) {
+	let pending;
+	return async () => {
+		const next = pending ??= occurrences.next().then((step) => ({ step }), (error) => ({ error }));
+		let timer;
+		const idle = new Promise((resolve) => {
+			timer = setTimeout(() => resolve({ idle: true }), idleMs);
+		});
+		try {
+			const pulled = await Promise.race([next, idle]);
+			if (!("idle" in pulled)) pending = void 0;
+			return pulled;
+		} finally {
+			clearTimeout(timer);
+		}
+	};
+}
+/**
+* A web stream of text. The stream calls `produce` each time that the client can take more: it gives the next messages,
+* or `undefined` at the end. When the client cancels the stream, the stream calls `cancel`. `release` runs one time, when
+* the stream ends in any way.
+*/
+function textStream(produce, cancel, release) {
+	const encoder = new TextEncoder();
+	let released = false;
+	let cancelled = false;
+	const releaseOnce = async () => {
+		if (released) return;
+		released = true;
+		await release();
+	};
+	return new ReadableStream({
+		async pull(controller) {
+			let messages;
+			try {
+				messages = await produce();
+			} catch (error) {
+				if (!cancelled) controller.error(error);
+				await releaseOnce();
+				return;
+			}
+			if (cancelled) return;
+			if (messages === void 0) {
+				controller.close();
+				await releaseOnce();
+				return;
+			}
+			controller.enqueue(encoder.encode(messages.join("")));
+		},
+		async cancel() {
+			cancelled = true;
+			cancel();
+			await releaseOnce();
+		}
+	}, { highWaterMark: 0 });
+}
+//#endregion
+export { idlePuller, textStream };

package/dist/subscription.d.ts

@@ -0,0 +1,39 @@
+import type { Emitted, Occurrence } from "@acid-cat/spec-ts";
+/**
+ * The occurrences of one subscription, as an async iterator (spec/bindings/typescript.md#event-handles). `return()`
+ * cancels the subscription, also while a `next()` waits: that `next()` then resolves with `done: true`. A `for await`
+ * loop that stops early calls `return()`. `await using` also cancels the subscription at the end of its block.
+ */
+export interface Occurrences<Payload> extends AsyncIterable<Occurrence<Payload>>, AsyncDisposable {
+    next(): Promise<IteratorResult<Occurrence<Payload>, undefined>>;
+    return(): Promise<IteratorResult<Occurrence<Payload>, undefined>>;
+    [Symbol.asyncIterator](): Occurrences<Payload>;
+}
+/** The number of occurrences that a subscription keeps for a client that reads slowly, if the session gives no limit. */
+export declare const DEFAULT_BUFFER_LIMIT = 256;
+export interface SubscriptionParts<Source, Payload> {
+    /** The id of the event. */
+    readonly name: string;
+    /** The occurrences of the provider. The pump starts to read them at once. */
+    readonly source: AsyncIterable<Emitted<Source>>;
+    /** Check the data of one occurrence against the payload schema, and give a copy in its JSON form. It throws if the data does not agree. */
+    readonly check: (data: Source) => Promise<Payload>;
+    /** The controller of the signal of the provider. The subscription aborts it when it ends. */
+    readonly controller: AbortController;
+    /** The maximum number of occurrences that wait for the client. */
+    readonly limit: number;
+    /** Record a defect of the provider. */
+    readonly onDefect: (cause: unknown) => void;
+    /** Called one time, when the subscription ends. */
+    readonly onEnd: () => void;
+}
+/** A subscription that runs: the iterator of the client, and the two ends that the session and the client cause. */
+export interface Running<Payload> {
+    readonly occurrences: Occurrences<Payload>;
+    /** End the subscription as cancelled: the client sees `done: true` at once. */
+    readonly cancel: () => void;
+    /** End the subscription as complete: the client reads the occurrences that wait, then sees `done: true`. */
+    readonly complete: () => void;
+}
+/** Start the pump of a subscription, and give the iterator of the client. */
+export declare function runSubscription<Source, Payload>(parts: SubscriptionParts<Source, Payload>): Running<Payload>;