@acid-cat/core-ts 0.9.0 → 0.10.1

package/dist/clock.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The time of the server: the current time, and timers. Poll leases and webhook subscriptions use it, so that a test
+ * can control the time.
+ */
+export interface Clock {
+    /** The current time, in milliseconds since the epoch. */
+    readonly now: () => number;
+    /** Call `callback` after `ms` milliseconds. The result cancels the timer. */
+    readonly schedule: (callback: () => void, ms: number) => () => void;
+}
+/** The clock of the system: `Date.now` and `setTimeout`. */
+export declare const systemClock: Clock;
+/** Wait `ms` milliseconds on a clock. The wait ends early, with `false`, when the signal aborts. */
+export declare function sleep(clock: Clock, ms: number, signal: AbortSignal): Promise<boolean>;

package/dist/clock.js

@@ -0,0 +1,25 @@
+// src/clock.ts
+/** The clock of the system: `Date.now` and `setTimeout`. */
+const systemClock = {
+	now: () => Date.now(),
+	schedule: (callback, ms) => {
+		const timer = setTimeout(callback, ms);
+		return () => clearTimeout(timer);
+	}
+};
+/** Wait `ms` milliseconds on a clock. The wait ends early, with `false`, when the signal aborts. */
+function sleep(clock, ms, signal) {
+	return new Promise((resolve) => {
+		if (signal.aborted) return resolve(false);
+		const stop = () => {
+			cancel();
+			resolve(false);
+		};
+		const cancel = clock.schedule(() => {
+			signal.removeEventListener("abort", stop);
+			resolve(true);
+		}, ms);
+		signal.addEventListener("abort", stop, { once: true });
+	});
+}
+export { sleep, systemClock };

package/dist/context.d.ts

@@ -16,3 +16,11 @@ export type ContextOption<Context> = {
 };
 /** Give the context of one request to `use`, and release it afterwards if the handler made it. */
 export declare function withContext<Context, A>(option: ContextOption<Context>, request: Request, use: (context: Context) => Promise<A>): Promise<A>;
+/**
+ * The context of one request, and the function that releases it if the handler made it. A response with a stream, such
+ * as the stream of a subscription, releases the context when the stream ends.
+ */
+export declare function openContext<Context>(option: ContextOption<Context>, request: Request): Promise<{
+    readonly context: Context;
+    readonly release: () => Promise<void>;
+}>;

package/dist/context.js

@@ -1,13 +1,18 @@
-//#region src/context.ts
-/** Give the context of one request to `use`, and release it afterwards if the handler made it. */
-async function withContext(option, request, use) {
-	if (option.createContext === void 0) return use(option.context);
+// src/context.ts
+/**
+* The context of one request, and the function that releases it if the handler made it. A response with a stream, such
+* as the stream of a subscription, releases the context when the stream ends.
+*/
+async function openContext(option, request) {
+	if (option.createContext === void 0) return {
+		context: option.context,
+		release: () => Promise.resolve()
+	};
 	const context = await option.createContext(request);
-	try {
-		return await use(context);
-	} finally {
-		await release(context);
-	}
+	return {
+		context,
+		release: () => release(context)
+	};
 }
 /** Call `Symbol.asyncDispose` or `Symbol.dispose` of a value, if it has one. */
 async function release(value) {
@@ -19,5 +24,4 @@ async function release(value) {
 }
 /** Tell if a value is a function. A function can take any arguments, and its result is not known. */
 const isFunction = (value) => typeof value === "function";
-//#endregion
-export { withContext };
+export { openContext };

package/dist/http.d.ts

@@ -14,6 +14,10 @@ export interface HttpSettings {
     readonly serveCatalog?: boolean | undefined;
     /** The maximum size of a request body, in bytes. The default is 1 MiB. */
     readonly maximumBytes?: number | undefined;
+    /** The time with nothing sent on the stream of a subscription after which the binding sends a comment line, in milliseconds. The default is 15 seconds. */
+    readonly keepaliveMs?: number | undefined;
+    /** The number of occurrences that each subscription keeps for a client that reads slowly. The default is 256. */
+    readonly bufferLimit?: number | undefined;
 }
 /** A web request handler for the API. Each request has its own session, and with `createContext` its own context. */
 export declare function httpHandler<Context>(app: App<Context>, options: HttpOptions<Context>): (request: Request) => Promise<Response>;

package/dist/http.js

@@ -1,7 +1,8 @@
+import { openContext } from "./context.js";
 import { createSession } from "./session.js";
-import { withContext } from "./context.js";
-import { callFailure, httpStatus, isCallFailure, readBounded, screenRequest } from "@acid-cat/spec-ts";
-//#region src/http.ts
+import { idlePuller, textStream } from "./stream.js";
+import { CallFailureError, KEEPALIVE_MS, SSE_MEDIA_TYPE, callFailure, httpEventMessage, httpStatus, isCallFailure, readBounded, screenRequest } from "@acid-cat/spec-ts";
+// src/http.ts
 /**
 * The HTTP binding (spec/bindings/http.md): JSON through HTTP.
 */
@@ -18,38 +19,142 @@ function httpHandler(app, options) {
 		if (screened !== void 0) return rejection(screened);
 		const body = await readBounded(request, maximumBytes);
 		if ("rejection" in body) return rejection(body.rejection);
-		const path = new URL(request.url).pathname.slice((options.base ?? "").length);
-		return withContext(options, request, async (context) => {
-			const session = createSession(app, {
-				target: options.target ?? "api",
-				context,
-				toJsonSchema: options.toJsonSchema
-			});
+		const url = new URL(request.url);
+		const path = url.pathname.slice((options.base ?? "").length);
+		const opened = await openContext(options, request);
+		const session = createSession(app, {
+			target: options.target ?? "api",
+			context: opened.context,
+			toJsonSchema: options.toJsonSchema,
+			...options.bufferLimit === void 0 ? {} : { bufferLimit: options.bufferLimit }
+		});
+		const close = async () => {
+			await session.dispose();
+			await opened.release();
+		};
+		let streaming = false;
+		try {
+			if (request.method === "GET" && path === "/capabilities") return json(200, [...session.handles.values()].map((handle) => ({
+				id: handle.id,
+				...handle.availability.getSnapshot()
+			})));
+			if (request.method === "GET" && path === "/events") return json(200, [...session.eventHandles.keys()].map((id) => ({ id })));
+			if (request.method === "GET" && path === "/catalog" && options.serveCatalog !== false) return json(200, session.view);
+			const route = request.method === "POST" ? postRoute(path) : void 0;
+			if (route === void 0) return json(404, callFailure("unknown-capability", "There is no such route."));
+			const id = decodedId(route.id);
+			if (id === void 0) return json(404, callFailure("unknown-capability", "There is no such route."));
+			let input;
 			try {
-				if (request.method === "GET" && path === "/capabilities") return json(200, [...session.handles.values()].map((handle) => ({
-					id: handle.id,
-					...handle.availability.getSnapshot()
-				})));
-				if (request.method === "GET" && path === "/catalog" && options.serveCatalog !== false) return json(200, session.view);
-				const id = request.method === "POST" && path.startsWith("/capabilities/") ? path.slice(14) : void 0;
-				if (id === void 0) return json(404, callFailure("unknown-capability", "There is no such route."));
-				let input;
-				try {
-					input = body.text === "" ? {} : JSON.parse(body.text);
-				} catch {
-					return json(422, callFailure("invalid-input", "The request body is not JSON."));
-				}
-				const outcome = await session.invoke(decodeURIComponent(id), input, { signal: request.signal });
-				return json(httpStatus(outcome), isCallFailure(outcome) ? {
-					kind: outcome.kind,
-					message: outcome.message
-				} : outcome);
-			} finally {
-				await session.dispose();
+				input = body.text === "" ? {} : JSON.parse(body.text);
+			} catch {
+				const failure = notJson(session, route.kind, id, request.signal);
+				return json(httpStatus(failure), failureBody(failure));
 			}
-		});
+			if (route.kind === "capability") {
+				const outcome = await session.invoke(id, input, { signal: request.signal });
+				return json(httpStatus(outcome), isCallFailure(outcome) ? failureBody(outcome) : outcome);
+			}
+			const subscribed = await subscribe(session, id, input, url, request, {
+				keepaliveMs: options.keepaliveMs ?? KEEPALIVE_MS,
+				close
+			});
+			streaming = subscribed.streaming;
+			return subscribed.response;
+		} finally {
+			if (!streaming) await close();
+		}
+	};
+}
+/** The capability or the event of a `POST` route, or `undefined` for another path. */
+function postRoute(path) {
+	if (path.startsWith("/capabilities/")) return {
+		kind: "capability",
+		id: path.slice(14)
+	};
+	if (path.startsWith("/events/")) return {
+		kind: "event",
+		id: path.slice(8)
+	};
+}
+/** The id of a route with its escapes decoded, or `undefined` if an escape is malformed, as in `%E0`. */
+function decodedId(encoded) {
+	try {
+		return decodeURIComponent(encoded);
+	} catch {
+		return;
+	}
+}
+/**
+* The call failure of a request whose body is not JSON. The kinds before `invalid-input` apply first
+* (spec/invocation.md#call-failures, spec/events.md#subscribing): `cancelled`, `unknown-capability`, then `unavailable`
+* for a capability.
+*/
+function notJson(session, kind, id, signal) {
+	if (session.signal.aborted || signal.aborted) return callFailure("cancelled", "The call was cancelled.");
+	if (kind === "event") {
+		if (!session.eventHandles.has(id)) return callFailure("unknown-capability", `There is no event ${id}.`);
+	} else {
+		const handle = session.handles.get(id);
+		if (handle === void 0) return callFailure("unknown-capability", `There is no capability ${id}.`);
+		const availability = handle.availability.getSnapshot();
+		if (!availability.available) return callFailure("unavailable", availability.reason);
+	}
+	return callFailure("invalid-input", "The request body is not JSON.");
+}
+/**
+* Subscribe to an event (spec/bindings/http.md#events). A call failure before the first occurrence is a JSON answer.
+* After that, the answer is a stream of server-sent events, which closes the session when it ends.
+*/
+async function subscribe(session, id, input, url, request, stream) {
+	const maxAge = url.searchParams.get("maxAgeMs");
+	const maxAgeMs = maxAge === null ? void 0 : /^[0-9]+$/.test(maxAge) ? Number(maxAge) : NaN;
+	const cursor = request.headers.get("Last-Event-ID") ?? void 0;
+	const subscribed = await session.subscribe(id, input, {
+		signal: request.signal,
+		...cursor === void 0 ? {} : { cursor },
+		...maxAgeMs === void 0 ? {} : { maxAgeMs }
+	});
+	if ("kind" in subscribed) return {
+		response: json(httpStatus(subscribed), failureBody(subscribed)),
+		streaming: false
+	};
+	const pull = idlePuller(subscribed, stream.keepaliveMs);
+	let ended = false;
+	const produce = async () => {
+		if (ended) return void 0;
+		const pulled = await pull();
+		if ("idle" in pulled) return [httpEventMessage.keepalive()];
+		if ("error" in pulled) {
+			ended = true;
+			return [httpEventMessage.error(internalOf(pulled.error))];
+		}
+		if (pulled.step.done === true) {
+			ended = true;
+			return [httpEventMessage.complete()];
+		}
+		return [httpEventMessage.next(pulled.step.value)];
+	};
+	const body = textStream(produce, () => void subscribed.return(), stream.close);
+	return {
+		response: new Response(body, {
+			status: 200,
+			headers: {
+				"Content-Type": SSE_MEDIA_TYPE,
+				"Cache-Control": "no-store"
+			}
+		}),
+		streaming: true
 	};
 }
+/** The call failure that ends a subscription. A subscription ends only with `internal`. */
+function internalOf(error) {
+	return error instanceof CallFailureError ? callFailure(error.kind, error.message) : callFailure("internal", "The event failed.");
+}
+const failureBody = (failure) => ({
+	kind: failure.kind,
+	message: failure.message
+});
 const json = (status, body) => new Response(JSON.stringify(body), {
 	status,
 	headers: { "Content-Type": "application/json" }
@@ -69,5 +174,4 @@ function rejection(reason) {
 		headers
 	});
 }
-//#endregion
 export { httpHandler };

package/dist/index.d.ts

@@ -1,9 +1,17 @@
-export { capabilitiesFor, catalogOf, defineApp, defineCapability, renderCatalog } from "./app.js";
-export type { AnyCapability, App, Call, Capability, CapabilityDeclaration, CapabilityFactory, EmptyInput, FailureOf, Observable, Target, ToJsonSchema } from "./app.js";
+export { capabilitiesFor, catalogOf, defineApp, defineCapability, defineEvent, eventsFor, renderCatalog } from "./app.js";
+export type { AnyCapability, AnyEventDefinition, App, Call, Capability, CapabilityDeclaration, CapabilityFactory, EmptyInput, EventDeclaration, EventDefinition, EventFactory, FailureOf, Observable, Subscribe, Subscription, Target, ToJsonSchema, } from "./app.js";
 export { createSession } from "./session.js";
-export type { Handle, HandleOf, Session, SessionOptions } from "./session.js";
+export type { EventHandle, EventHandleOf, Handle, HandleOf, Session, SessionOptions, SubscribeOptions } from "./session.js";
+export { DEFAULT_BUFFER_LIMIT } from "./subscription.js";
+export type { Occurrences } from "./subscription.js";
 export { mcpHandler } from "./mcp.js";
-export type { McpOptions, McpSettings } from "./mcp.js";
+export type { McpHandler, McpOptions, McpSettings } from "./mcp.js";
+export type { PollOptions } from "./mcp-poll.js";
+export type { JsonRpcError, OpenSession, OwnSession, RpcAnswer, WebhookDelivery } from "./mcp-events.js";
+export { systemClock } from "./clock.js";
+export type { Clock } from "./clock.js";
+export { mcpHandshake } from "@acid-cat/mcp-handshake";
+export type { McpHandshakeOptions } from "@acid-cat/mcp-handshake";
 export { main as mcpStdioMain, runMcpStdio } from "./mcp-stdio.js";
 export type { McpStdioIo, McpStdioOptions } from "./mcp-stdio.js";
 export { httpHandler } from "./http.js";
@@ -15,4 +23,4 @@ export { findHost, installWebMcp } from "./webmcp.js";
 export type { Installation, ModelContext, ModelContextTool, Phase, Status } from "./webmcp.js";
 export type { StandardSchemaV1 } from "./standard-schema.js";
 export { AVAILABLE, CallFailureError, fail, ok, unavailable } from "@acid-cat/spec-ts";
-export type { Availability, CallFailure, CallFailureKind, Outcome, Result } from "@acid-cat/spec-ts";
+export type { Availability, CallFailure, CallFailureKind, Emitted, Occurrence, Outcome, Result } from "@acid-cat/spec-ts";

package/dist/index.js

@@ -1,9 +1,12 @@
-import { capabilitiesFor, catalogOf, defineApp, defineCapability, renderCatalog } from "./app.js";
+import { capabilitiesFor, catalogOf, defineApp, defineCapability, defineEvent, eventsFor, renderCatalog } from "./app.js";
 import { createSession } from "./session.js";
+import { DEFAULT_BUFFER_LIMIT } from "./subscription.js";
 import { mcpHandler } from "./mcp.js";
+import { systemClock } from "./clock.js";
 import { main as main$1, runMcpStdio } from "./mcp-stdio.js";
 import { httpHandler } from "./http.js";
 import { main, runCli } from "./cli.js";
 import { findHost, installWebMcp } from "./webmcp.js";
 import { AVAILABLE, CallFailureError, fail, ok, unavailable } from "@acid-cat/spec-ts";
-export { AVAILABLE, CallFailureError, capabilitiesFor, catalogOf, main as cliMain, createSession, defineApp, defineCapability, fail, findHost, httpHandler, installWebMcp, mcpHandler, main$1 as mcpStdioMain, ok, renderCatalog, runCli, runMcpStdio, unavailable };
+import { mcpHandshake } from "@acid-cat/mcp-handshake";
+export { AVAILABLE, CallFailureError, DEFAULT_BUFFER_LIMIT, capabilitiesFor, catalogOf, main as cliMain, createSession, defineApp, defineCapability, defineEvent, eventsFor, fail, findHost, httpHandler, installWebMcp, mcpHandler, mcpHandshake, main$1 as mcpStdioMain, ok, renderCatalog, runCli, runMcpStdio, systemClock, unavailable };

package/dist/mcp-events.d.ts

@@ -0,0 +1,90 @@
+import type { JsonObject } from "@acid-cat/spec-ts";
+import type { Session } from "./session.js";
+/** A JSON-RPC error. */
+export interface JsonRpcError {
+    readonly code: number;
+    readonly message: string;
+    readonly data?: JsonObject;
+}
+/** True if the view of the session has events. The server serves the extension only then. */
+export declare const servesEvents: (session: Session) => boolean;
+/** The members that the capabilities of `server/discover` get for events: the extension, if the view has events. */
+export declare const eventCapabilities: (session: Session) => JsonObject;
+/** The entries of `events/list`: one for each event in the view. `webhook` is true when webhook delivery is on. */
+export declare function listEvents(session: Session, webhook?: boolean): JsonObject[];
+/** The error of `events/subscribe` and `events/unsubscribe` when webhook delivery is off, or through stdio. */
+export declare const unsupportedWebhook: JsonRpcError;
+/** The answer to a request: its result, with no `resultType` and no `_meta`, or a JSON-RPC error. */
+export type RpcAnswer = {
+    readonly result: JsonObject;
+} | {
+    readonly error: JsonRpcError;
+};
+/**
+ * A session of its own for a poll lease or a webhook subscription (spec/bindings/mcp.md#subscriptions-that-outlive-a-request).
+ * `close` closes the session, and releases its context. A second call does nothing more.
+ */
+export interface OwnSession {
+    readonly session: Session;
+    readonly close: () => Promise<void>;
+}
+/** Open a session of its own, with the identity and the services of the request that starts the lease or the subscription. */
+export type OpenSession = () => Promise<OwnSession>;
+/**
+ * Webhook delivery (spec/bindings/mcp.md#webhook), as the MCP server through HTTP uses it. `webhookDelivery` of
+ * `@acid-cat/core-ts/node` makes one. The server checks the principal before it calls these functions.
+ */
+export interface WebhookDelivery {
+    /** Answer `events/subscribe`. */
+    readonly subscribe: (principal: string, params: JsonObject, open: OpenSession) => Promise<RpcAnswer>;
+    /** Answer `events/unsubscribe`. */
+    readonly unsubscribe: (principal: string, params: JsonObject) => Promise<RpcAnswer>;
+    /** End all webhook subscriptions. */
+    readonly close: () => Promise<void>;
+}
+/** The error `Forbidden`: a request to `events/subscribe` or `events/unsubscribe` with no principal. */
+export declare const forbidden: JsonRpcError;
+/** The error `-32602` with a message. */
+export declare const invalidParams: (message: string) => {
+    readonly error: JsonRpcError;
+};
+/**
+ * Read the subscription parameters (spec/bindings/mcp.md#events): the id, the input, the cursor and `maxAgeMs`. An
+ * absent cursor and a `null` cursor are the same. The input is `{}` when `arguments` is absent.
+ *
+ * This function does not check `maxAgeMs`: an unknown id comes before an invalid `maxAgeMs` (spec/events.md#subscribing),
+ * so the session checks it after the id. A `maxAgeMs` that is not a number is `NaN`, which the session rejects.
+ */
+export declare function subscriptionParams(params: JsonObject): {
+    readonly error: JsonRpcError;
+} | {
+    readonly name: string;
+    readonly input: unknown;
+    readonly cursor: string | undefined;
+    readonly maxAgeMs: number | undefined;
+};
+/** The message of the call failure that ends a subscription. A subscription ends only with `internal`. */
+export declare const endMessage: (error: unknown) => string;
+/**
+ * The messages of one `events/stream` request, as a function that gives the next messages each time that it is called,
+ * or `undefined` after the result. `id` is the id of the request.
+ */
+export type StreamMessages = () => Promise<readonly JsonObject[] | undefined>;
+export interface StreamSettings {
+    /** The time with nothing sent after which the server sends a heartbeat, in milliseconds. */
+    readonly heartbeatMs: number;
+    /** The `_meta` members of the result beside the subscription id, for example the server information. */
+    readonly resultMeta: JsonObject;
+    readonly signal: AbortSignal;
+}
+/**
+ * Start the subscription of an `events/stream` request. The result is the JSON-RPC error before the first occurrence,
+ * or the messages of the stream: `notifications/events/active`, then the occurrences and the heartbeats, then the
+ * result. `cancel` cancels the subscription.
+ */
+export declare function startEventStream(session: Session, id: string | number, params: JsonObject, settings: StreamSettings): Promise<{
+    readonly error: JsonRpcError;
+} | {
+    readonly messages: StreamMessages;
+    readonly cancel: () => void;
+}>;

package/dist/mcp-events.js

@@ -0,0 +1,130 @@
+import { idlePuller } from "./stream.js";
+import { CallFailureError, MCP_EVENTS_EXTENSION, MCP_EVENT_ERRORS, MCP_SUBSCRIPTION_ID, bundle, mcpEventEntry, mcpEventParams, mcpSubscribeError } from "@acid-cat/spec-ts";
+// src/mcp-events.ts
+/**
+* Events through MCP (spec/bindings/mcp.md#events): the MCP events extension. This module serves push delivery, and
+* declares the parts that poll and webhook delivery share. The HTTP and the stdio transports share these functions.
+*/
+/** True if the view of the session has events. The server serves the extension only then. */
+const servesEvents = (session) => Object.keys(session.view.events ?? {}).length > 0;
+/** The members that the capabilities of `server/discover` get for events: the extension, if the view has events. */
+const eventCapabilities = (session) => servesEvents(session) ? { extensions: { [MCP_EVENTS_EXTENSION]: {} } } : {};
+/** The entries of `events/list`: one for each event in the view. `webhook` is true when webhook delivery is on. */
+function listEvents(session, webhook = false) {
+	const types = session.view.$defs ?? {};
+	return Object.entries(session.view.events ?? {}).map(([id, event]) => mcpEventEntry(id, event.description, event.input === void 0 ? void 0 : bundle(event.input, types), event.payload === void 0 ? void 0 : bundle(event.payload, types), webhook));
+}
+/** The error of `events/subscribe` and `events/unsubscribe` when webhook delivery is off, or through stdio. */
+const unsupportedWebhook = {
+	code: MCP_EVENT_ERRORS.unsupported,
+	message: "Unsupported",
+	data: {
+		feature: "deliveryMode",
+		value: "webhook"
+	}
+};
+/** The error `Forbidden`: a request to `events/subscribe` or `events/unsubscribe` with no principal. */
+const forbidden = {
+	code: MCP_EVENT_ERRORS.forbidden,
+	message: "Forbidden"
+};
+/** The error `-32602` with a message. */
+const invalidParams = (message) => ({ error: {
+	code: MCP_EVENT_ERRORS.invalidParams,
+	message
+} });
+/**
+* Read the subscription parameters (spec/bindings/mcp.md#events): the id, the input, the cursor and `maxAgeMs`. An
+* absent cursor and a `null` cursor are the same. The input is `{}` when `arguments` is absent.
+*
+* This function does not check `maxAgeMs`: an unknown id comes before an invalid `maxAgeMs` (spec/events.md#subscribing),
+* so the session checks it after the id. A `maxAgeMs` that is not a number is `NaN`, which the session rejects.
+*/
+function subscriptionParams(params) {
+	const { name, arguments: input, cursor, maxAgeMs } = params;
+	if (cursor !== void 0 && cursor !== null && typeof cursor !== "string") return invalidParams("cursor must be a string or null.");
+	return {
+		name: typeof name === "string" ? name : "",
+		input: input ?? {},
+		cursor: typeof cursor === "string" ? cursor : void 0,
+		maxAgeMs: maxAgeMs === void 0 || maxAgeMs === null ? void 0 : typeof maxAgeMs === "number" ? maxAgeMs : NaN
+	};
+}
+/** The message of the call failure that ends a subscription. A subscription ends only with `internal`. */
+const endMessage = (error) => error instanceof CallFailureError ? error.message : "The event failed.";
+/**
+* Start the subscription of an `events/stream` request. The result is the JSON-RPC error before the first occurrence,
+* or the messages of the stream: `notifications/events/active`, then the occurrences and the heartbeats, then the
+* result. `cancel` cancels the subscription.
+*/
+async function startEventStream(session, id, params, settings) {
+	const read = subscriptionParams(params);
+	if ("error" in read) return read;
+	const { cursor, maxAgeMs } = read;
+	const subscribed = await session.subscribe(read.name, read.input, {
+		signal: settings.signal,
+		...cursor === void 0 ? {} : { cursor },
+		...maxAgeMs === void 0 ? {} : { maxAgeMs }
+	});
+	if ("kind" in subscribed) return { error: mcpSubscribeError(subscribed) };
+	const meta = { [MCP_SUBSCRIPTION_ID]: id };
+	const notification = (method, members) => ({
+		jsonrpc: "2.0",
+		method: `notifications/events/${method}`,
+		params: {
+			...members,
+			_meta: meta
+		}
+	});
+	const result = {
+		jsonrpc: "2.0",
+		id,
+		result: {
+			resultType: "complete",
+			_meta: {
+				...settings.resultMeta,
+				...meta
+			}
+		}
+	};
+	const pull = idlePuller(subscribed, settings.heartbeatMs);
+	let state = "start";
+	let lastCursor = null;
+	const messages = async () => {
+		if (state === "ended") return void 0;
+		if (state === "start") {
+			state = "open";
+			return [notification("active", { truncated: false })];
+		}
+		const pulled = await pull();
+		if ("idle" in pulled) return [notification("heartbeat", { cursor: lastCursor })];
+		if ("error" in pulled) {
+			state = "ended";
+			return [notification("terminated", { error: {
+				code: MCP_EVENT_ERRORS.internal,
+				message: endMessage(pulled.error)
+			} }), result];
+		}
+		if (pulled.step.done === true) {
+			state = "ended";
+			return [result];
+		}
+		const occurrence = pulled.step.value;
+		if (occurrence.cursor !== void 0) lastCursor = occurrence.cursor;
+		const event = {
+			jsonrpc: "2.0",
+			method: "notifications/events/event",
+			params: mcpEventParams(occurrence, id)
+		};
+		if (occurrence.truncated !== true) return [event];
+		return [notification("active", {
+			truncated: true,
+			...occurrence.cursor === void 0 ? {} : { cursor: occurrence.cursor }
+		}), event];
+	};
+	return {
+		messages,
+		cancel: () => void subscribed.return()
+	};
+}
+export { endMessage, eventCapabilities, forbidden, invalidParams, listEvents, servesEvents, startEventStream, subscriptionParams, unsupportedWebhook };

package/dist/mcp-poll.d.ts

@@ -0,0 +1,28 @@
+import type { JsonObject } from "@acid-cat/spec-ts";
+import type { Clock } from "./clock.js";
+import type { OpenSession, RpcAnswer } from "./mcp-events.js";
+/** The settings of poll delivery. Each one has the default of spec/bindings/mcp.md#poll. */
+export interface PollOptions {
+    /** The time after the last poll at which a lease ends, in milliseconds. The default is 5 minutes. */
+    readonly leaseMs?: number | undefined;
+    /** The number of occurrences that each lease keeps. The default is 1000. */
+    readonly bufferLimit?: number | undefined;
+    /** The number of occurrences in a result when the request gives no `maxEvents`. The default is 100. */
+    readonly maxEvents?: number | undefined;
+    /** The `nextPollMs` of each result. The default is 2000. */
+    readonly nextPollMs?: number | undefined;
+}
+/** The poll leases of one server. `close` ends them all. */
+export declare class PollLeases {
+    #private;
+    constructor(options?: PollOptions, clock?: Clock);
+    /** The number of leases, for tests. */
+    get size(): number;
+    /**
+     * Answer `events/poll`. `principal` is the identity of the client, or `undefined` if the deployment gives none.
+     * `open` opens the session of a new lease.
+     */
+    poll(principal: string | undefined, params: JsonObject, open: OpenSession): Promise<RpcAnswer>;
+    /** End all leases. */
+    close(): Promise<void>;
+}