@acid-cat/core-ts 0.9.0 → 0.10.1

package/dist/mcp-poll.js

@@ -0,0 +1,181 @@
+import { systemClock } from "./clock.js";
+import { endMessage, invalidParams, subscriptionParams } from "./mcp-events.js";
+import { isMaxAgeMs } from "./session.js";
+import { MCP_EVENT_ERRORS, MCP_POLL_DEFAULTS, canonicalJson, decodePollCursor, encodePollCursor, mcpSubscribeError } from "@acid-cat/spec-ts";
+// src/mcp-poll.ts
+/**
+* Poll delivery through MCP (spec/bindings/mcp.md#poll): `events/poll` reads the occurrences of a poll lease. A lease
+* holds one subscription, in a session of its own, and a buffer of its occurrences. The HTTP and the stdio transports
+* share this module. It works in all runtimes.
+*/
+/** The poll leases of one server. `close` ends them all. */
+var PollLeases = class {
+	#leases = /* @__PURE__ */ new Map();
+	/** The leases that start, by key. A second poll with the same key waits for the first. */
+	#starting = /* @__PURE__ */ new Map();
+	#leaseMs;
+	#bufferLimit;
+	#maxEvents;
+	#nextPollMs;
+	#clock;
+	#closed = false;
+	constructor(options = {}, clock = systemClock) {
+		this.#leaseMs = options.leaseMs ?? MCP_POLL_DEFAULTS.leaseMs;
+		this.#bufferLimit = options.bufferLimit ?? MCP_POLL_DEFAULTS.bufferLimit;
+		this.#maxEvents = options.maxEvents ?? MCP_POLL_DEFAULTS.maxEvents;
+		this.#nextPollMs = options.nextPollMs ?? MCP_POLL_DEFAULTS.nextPollMs;
+		this.#clock = clock;
+	}
+	/** The number of leases, for tests. */
+	get size() {
+		return this.#leases.size;
+	}
+	/**
+	* 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.
+	*/
+	async poll(principal, params, open) {
+		const read = subscriptionParams(params);
+		if ("error" in read) return read;
+		const { maxEvents = this.#maxEvents } = params;
+		if (typeof maxEvents !== "number" || !Number.isSafeInteger(maxEvents) || maxEvents < 1) return invalidParams("maxEvents must be a positive integer.");
+		const key = canonicalJson([
+			principal ?? null,
+			read.name,
+			read.input
+		]);
+		await this.#starting.get(key);
+		const lease = this.#leases.get(key);
+		if (lease?.failure !== void 0) {
+			await this.#end(lease);
+			return { error: {
+				code: MCP_EVENT_ERRORS.internal,
+				message: lease.failure
+			} };
+		}
+		const position = read.cursor === void 0 ? void 0 : decodePollCursor(read.cursor);
+		if (lease === void 0) {
+			const provider = read.cursor === void 0 ? void 0 : position?.provider;
+			const maxAgeMs = provider === void 0 && isMaxAgeMs(read.maxAgeMs) ? void 0 : read.maxAgeMs;
+			const started = this.#start(key, read.name, read.input, provider, maxAgeMs, open);
+			this.#starting.set(key, started);
+			const answer = await started.finally(() => this.#starting.delete(key));
+			if ("error" in answer) return answer;
+			return this.#result([], this.#cursorOf(answer, 0), read.cursor !== void 0 && provider === void 0, false);
+		}
+		if (!isMaxAgeMs(read.maxAgeMs)) return invalidParams("maxAgeMs must be an integer that is 0 or more.");
+		this.#renew(lease);
+		if (read.cursor === void 0) return this.#result([], this.#cursorOf(lease, lease.newest), false, false);
+		if (position?.lease === lease.id) return this.#read(lease, position.position, maxEvents, read.cursor);
+		return this.#result([], this.#cursorOf(lease, lease.newest), true, false);
+	}
+	/** End all leases. */
+	async close() {
+		this.#closed = true;
+		await Promise.allSettled(this.#starting.values());
+		await Promise.allSettled([...this.#leases.values()].map((lease) => this.#end(lease)));
+	}
+	/** Start a lease: open its session, subscribe, and keep the occurrences. A failure before the first occurrence starts no lease. */
+	async #start(key, name, input, provider, maxAgeMs, open) {
+		const own = await open();
+		const subscribed = await own.session.subscribe(name, input, {
+			...provider === void 0 ? {} : { cursor: provider },
+			...maxAgeMs === void 0 ? {} : { maxAgeMs }
+		});
+		if ("kind" in subscribed || this.#closed) {
+			if (!("kind" in subscribed)) await subscribed.return();
+			await own.close();
+			if ("kind" in subscribed) return { error: mcpSubscribeError(subscribed) };
+			return { error: {
+				code: MCP_EVENT_ERRORS.internal,
+				message: "The server is closing."
+			} };
+		}
+		const lease = {
+			id: crypto.randomUUID(),
+			key,
+			own,
+			occurrences: subscribed,
+			entries: [],
+			newest: 0,
+			startProvider: provider,
+			lastProvider: provider,
+			failure: void 0,
+			ended: false,
+			cancelTimer: () => {}
+		};
+		this.#leases.set(key, lease);
+		this.#renew(lease);
+		this.#pump(lease);
+		return lease;
+	}
+	/** Read the occurrences of the subscription of a lease into its buffer, until the subscription ends. */
+	async #pump(lease) {
+		try {
+			for (let step = await lease.occurrences.next(); step.done !== true; step = await lease.occurrences.next()) {
+				const occurrence = step.value;
+				if (occurrence.cursor !== void 0) lease.lastProvider = occurrence.cursor;
+				lease.newest += 1;
+				lease.entries.push({
+					position: lease.newest,
+					occurrence,
+					provider: lease.lastProvider
+				});
+				if (lease.entries.length > this.#bufferLimit) lease.entries.shift();
+			}
+		} catch (error) {
+			if (!lease.ended) lease.failure = endMessage(error);
+		}
+		if (!lease.ended) await lease.own.close();
+	}
+	/** Renew a lease: it ends when it gets no poll for the lease time. */
+	#renew(lease) {
+		lease.cancelTimer();
+		lease.cancelTimer = this.#clock.schedule(() => void this.#end(lease), this.#leaseMs);
+	}
+	/** End a lease: cancel its subscription, close its session, and forget it. */
+	async #end(lease) {
+		if (lease.ended) return;
+		lease.ended = true;
+		lease.cancelTimer();
+		if (this.#leases.get(lease.key) === lease) this.#leases.delete(lease.key);
+		await lease.occurrences.return();
+		await lease.own.close();
+	}
+	/** The occurrences of a lease after a position, at most `maxEvents`. */
+	#read(lease, after, maxEvents, requestCursor) {
+		const older = after < (lease.entries[0]?.position ?? lease.newest + 1) - 1;
+		const available = lease.entries.filter((entry) => entry.position > after);
+		const events = available.slice(0, maxEvents);
+		const last = events.at(-1);
+		const truncated = older || events.some((entry) => entry.occurrence.truncated === true);
+		return this.#result(events.map((entry) => withoutTruncated(entry.occurrence)), last === void 0 ? requestCursor : this.#cursorOf(lease, last.position), truncated, available.length > maxEvents);
+	}
+	/** The cursor of a position of a lease. */
+	#cursorOf(lease, position) {
+		const provider = position === 0 ? lease.startProvider : position >= lease.newest ? lease.lastProvider : lease.entries.find((entry) => entry.position === position)?.provider;
+		return encodePollCursor(provider === void 0 ? {
+			lease: lease.id,
+			position
+		} : {
+			lease: lease.id,
+			position,
+			provider
+		});
+	}
+	#result(events, cursor, truncated, hasMore) {
+		return { result: {
+			events: [...events],
+			cursor,
+			truncated,
+			hasMore,
+			nextPollMs: this.#nextPollMs
+		} };
+	}
+};
+/** An occurrence without `truncated`, as an item of `events`. */
+function withoutTruncated(occurrence) {
+	const { truncated: _, ...rest } = occurrence;
+	return { ...rest };
+}
+export { PollLeases };

package/dist/mcp-stdio.d.ts

@@ -1,4 +1,6 @@
 import type { App, ToJsonSchema } from "./app.js";
+import type { Clock } from "./clock.js";
+import type { PollOptions } from "./mcp-poll.js";
 export interface McpStdioOptions<Context> {
     readonly name: string;
     readonly version: string;
@@ -9,6 +11,17 @@ export interface McpStdioOptions<Context> {
     readonly toJsonSchema: ToJsonSchema;
     /** The target that the server serves. The default is `"mcp"`. */
     readonly target?: string | undefined;
+    /** The time with nothing sent on an `events/stream` request after which the server sends a heartbeat, in milliseconds. The default is 15 seconds. */
+    readonly heartbeatMs?: number | undefined;
+    /** The number of occurrences that each subscription keeps for a client that reads slowly. The default is 256. */
+    readonly bufferLimit?: number | undefined;
+    /**
+     * The settings of poll delivery: the lease time, the size of the buffer, `maxEvents` and `nextPollMs`. Each lease
+     * has a session of its own with `context`. The leases have no identity, because the process serves one client.
+     */
+    readonly poll?: PollOptions | undefined;
+    /** The clock of the poll leases. The default is the clock of the system. Tests give a clock that they control. */
+    readonly clock?: Clock | undefined;
 }
 export interface McpStdioIo {
     /** Standard input: bytes or text, one JSON-RPC message on each line. */

package/dist/mcp-stdio.js

@@ -1,7 +1,9 @@
-import { createSession } from "./session.js";
 import { hasObjectOutput, listTools } from "./mcp.js";
-import { MCP_PROTOCOL_VERSION, MCP_UNKNOWN_TOOL, isJsonObject, mcpToolResult } from "@acid-cat/spec-ts";
-//#region src/mcp-stdio.ts
+import { eventCapabilities, listEvents, servesEvents, startEventStream, unsupportedWebhook } from "./mcp-events.js";
+import { PollLeases } from "./mcp-poll.js";
+import { createSession } from "./session.js";
+import { KEEPALIVE_MS, MCP_PROTOCOL_VERSION, MCP_UNKNOWN_TOOL, isJsonObject, mcpToolResult } from "@acid-cat/spec-ts";
+// src/mcp-stdio.ts
 /**
 * The MCP binding through standard input and standard output (spec/bindings/mcp.md#stdio). The process is one session.
 * The server serves revision 2026-07-28, and the `initialize` handshake of revisions 2025-11-25 and 2025-06-18.
@@ -30,13 +32,32 @@ async function runMcpStdio(app, options, io) {
 	const session = createSession(app, {
 		target: options.target ?? "mcp",
 		context: options.context,
-		toJsonSchema: options.toJsonSchema
+		toJsonSchema: options.toJsonSchema,
+		...options.bufferLimit === void 0 ? {} : { bufferLimit: options.bufferLimit }
 	});
 	const instructions = options.instructions ?? app.description;
+	const open = () => {
+		const own = createSession(app, {
+			target: options.target ?? "mcp",
+			context: options.context,
+			toJsonSchema: options.toJsonSchema,
+			...options.bufferLimit === void 0 ? {} : { bufferLimit: options.bufferLimit }
+		});
+		return Promise.resolve({
+			session: own,
+			close: own.dispose
+		});
+	};
+	const leases = new PollLeases(options.poll, options.clock);
 	const server = new StdioServer(session, {
-		...options,
-		instructions
-	}, io.write);
+		name: options.name,
+		version: options.version,
+		instructions,
+		heartbeatMs: options.heartbeatMs ?? KEEPALIVE_MS
+	}, io.write, {
+		leases,
+		open
+	});
 	try {
 		for await (const line of lines(io.input)) server.receive(line);
 	} finally {
@@ -73,14 +94,23 @@ var StdioServer = class {
 	#write;
 	/** The calls in progress, by request id. `notifications/cancelled` aborts them. */
 	#calls = /* @__PURE__ */ new Map();
+	/**
+	* The `events/stream` requests in progress, by request id. `notifications/cancelled` aborts them. When the session
+	* closes, their subscriptions end as complete, so they are not aborted then.
+	*/
+	#streams = /* @__PURE__ */ new Map();
+	/** The work of each `events/stream` request. `close` waits for it, so that the last result is written. */
+	#streaming = /* @__PURE__ */ new Set();
 	/** The open `subscriptions/listen` requests of revision 2026-07-28 that asked for tool list changes. */
 	#subscriptions = /* @__PURE__ */ new Set();
 	/** True after the `initialize` handshake: the client then gets `notifications/tools/list_changed` with no subscription. */
 	#initialized = false;
 	#listed;
 	#changes;
-	constructor(session, options, write) {
+	#poll;
+	constructor(session, options, write, poll) {
 		this.#session = session;
+		this.#poll = poll;
 		this.#options = options;
 		this.#write = write;
 		this.#listed = this.#availableIds();
@@ -108,18 +138,21 @@ var StdioServer = class {
 			id: message.id ?? null
 		});
 	}
-	/** Close the session: stop the subscriptions, and cancel the calls in progress. */
+	/** Close the session: stop the subscriptions and the poll leases, and cancel the calls in progress. */
 	async close() {
 		this.#changes.unsubscribe();
+		await this.#poll.leases.close();
 		this.#subscriptions.clear();
 		for (const controller of this.#calls.values()) controller.abort();
 		await this.#session.dispose();
+		await Promise.allSettled(this.#streaming);
 	}
 	#notification(message) {
 		if (message.method !== "notifications/cancelled") return;
 		const requestId = message.params["requestId"];
 		if (typeof requestId !== "string" && typeof requestId !== "number") return;
 		this.#calls.get(requestId)?.abort();
+		this.#streams.get(requestId)?.abort();
 		this.#subscriptions.delete(requestId);
 	}
 	async #request(message) {
@@ -130,10 +163,7 @@ var StdioServer = class {
 		if (modern && protocolVersion !== MCP_PROTOCOL_VERSION) return this.#error(id, -32022, `Unsupported protocol version ${JSON.stringify(protocolVersion)}`, { supported: SUPPORTED_VERSIONS });
 		/** The result of a request: in revision 2026-07-28 it has the server information and a result type. */
 		const complete = (result, list = false) => this.#result(id, modern ? {
-			_meta: { "io.modelcontextprotocol/serverInfo": {
-				name: this.#options.name,
-				version: this.#options.version
-			} },
+			_meta: this.#serverInfo(),
 			resultType: "complete",
 			...list ? {
 				ttlMs: 0,
@@ -144,14 +174,65 @@ var StdioServer = class {
 		switch (method) {
 			case "server/discover": return complete({
 				supportedVersions: SUPPORTED_VERSIONS,
-				capabilities: { tools: { listChanged: true } },
+				capabilities: {
+					tools: { listChanged: true },
+					...eventCapabilities(this.#session)
+				},
 				...this.#options.instructions === void 0 ? {} : { instructions: this.#options.instructions }
 			}, true);
 			case "subscriptions/listen": return this.#listen(id, message.params);
 			case "tools/list": return complete({ tools: listTools(this.#session) }, true);
 			case "tools/call": return this.#call(id, message.params, complete);
-			default: return this.#error(id, -32601, `Method not found: ${method}`);
 		}
+		if (modern && servesEvents(this.#session)) switch (method) {
+			case "events/list": return complete({ events: listEvents(this.#session) }, true);
+			case "events/poll": {
+				const answered = await this.#poll.leases.poll(void 0, message.params, this.#poll.open);
+				if ("error" in answered) return this.#error(id, answered.error.code, answered.error.message, answered.error.data);
+				return complete(answered.result);
+			}
+			case "events/unsubscribe":
+			case "events/subscribe": {
+				const { code, message: text, data } = unsupportedWebhook;
+				return this.#error(id, code, text, data);
+			}
+			case "events/stream": if (id !== null) {
+				const work = this.#stream(id, message.params).finally(() => this.#streaming.delete(work));
+				this.#streaming.add(work);
+				return work;
+			}
+		}
+		return this.#error(id, -32601, `Method not found: ${method}`);
+	}
+	/**
+	* An `events/stream` request: the messages of the subscription go to standard output. `notifications/cancelled` with
+	* the id of the request cancels it, and then the server sends nothing more for it.
+	*/
+	async #stream(id, params) {
+		const controller = new AbortController();
+		this.#streams.set(id, controller);
+		try {
+			const started = await startEventStream(this.#session, id, params, {
+				heartbeatMs: this.#options.heartbeatMs,
+				resultMeta: this.#serverInfo(),
+				signal: controller.signal
+			});
+			if (controller.signal.aborted) return;
+			if ("error" in started) return this.#error(id, started.error.code, started.error.message, started.error.data);
+			for (let messages = await started.messages(); messages !== void 0; messages = await started.messages()) {
+				if (controller.signal.aborted) return;
+				messages.forEach((message) => this.#send(message));
+			}
+		} finally {
+			if (this.#streams.get(id) === controller) this.#streams.delete(id);
+		}
+	}
+	/** The `_meta` of a result of revision 2026-07-28: the information about the server. */
+	#serverInfo() {
+		return { "io.modelcontextprotocol/serverInfo": {
+			name: this.#options.name,
+			version: this.#options.version
+		} };
 	}
 	/** The `initialize` handshake. The server selects the revision of the client if it serves it, or else its latest. */
 	#initialize(id, offered) {
@@ -240,5 +321,4 @@ var StdioServer = class {
 		this.#write(`${JSON.stringify(message)}\n`);
 	}
 };
-//#endregion
 export { main, runMcpStdio };

package/dist/mcp.d.ts

@@ -1,5 +1,9 @@
+import type { JsonObject } from "@acid-cat/spec-ts";
 import type { App, ToJsonSchema } from "./app.js";
 import type { ContextOption } from "./context.js";
+import type { Clock } from "./clock.js";
+import type { WebhookDelivery } from "./mcp-events.js";
+import type { PollOptions } from "./mcp-poll.js";
 import type { Session } from "./session.js";
 /** The options of `mcpHandler`. Give `context` to share one context, or `createContext` to make one for each request. */
 export type McpOptions<Context> = McpSettings & ContextOption<Context>;
@@ -18,15 +22,47 @@ export interface McpSettings {
     readonly target?: string | 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 an `events/stream` response after which the server sends a heartbeat, in milliseconds. The default is 15 seconds. */
+    readonly heartbeatMs?: number | undefined;
+    /** The number of occurrences that each subscription keeps for a client that reads slowly. The default is 256. */
+    readonly bufferLimit?: number | undefined;
+    /**
+     * The identity of the client of a request: the principal (spec/bindings/mcp.md#webhook). It is part of the key of a
+     * poll lease and of a webhook subscription. `undefined` means that the request has no identity. With no function, no
+     * request has an identity.
+     */
+    readonly principal?: ((request: Request) => string | undefined | Promise<string | undefined>) | undefined;
+    /** The settings of poll delivery: the lease time, the size of the buffer, `maxEvents` and `nextPollMs`. */
+    readonly poll?: PollOptions | undefined;
+    /**
+     * Webhook delivery. It is off when this member is absent. `webhookDelivery` of `@acid-cat/core-ts/node` makes it.
+     * A request to `events/subscribe` or `events/unsubscribe` with no principal gets `Forbidden`.
+     */
+    readonly webhooks?: WebhookDelivery | undefined;
+    /** The clock of the poll leases. The default is the clock of the system. Tests give a clock that they control. */
+    readonly clock?: Clock | undefined;
+}
+/**
+ * The web request handler of an MCP server through HTTP. `close` ends the poll leases and the webhook subscriptions.
+ * `await using` calls it at the end of its block.
+ */
+export interface McpHandler {
+    (request: Request): Promise<Response>;
+    readonly close: () => Promise<void>;
+    readonly [Symbol.asyncDispose]: () => Promise<void>;
 }
-/** A web request handler for the MCP server. Each request has its own session, and with `createContext` its own context. */
-export declare function mcpHandler<Context>(app: App<Context>, options: McpOptions<Context>): (request: Request) => Promise<Response>;
+/**
+ * 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.
+ */
+export declare function mcpHandler<Context>(app: App<Context>, options: McpOptions<Context>): McpHandler;
 /** The tools of the available capabilities in the view of a session (spec/bindings/mcp.md#tools). */
 export declare function listTools(session: Session): {
     name: string;
     description: string;
-    inputSchema: import("@acid-cat/spec-ts").JsonObject;
-    outputSchema?: import("@acid-cat/spec-ts").JsonObject;
+    inputSchema: JsonObject;
+    outputSchema?: JsonObject;
     annotations: {
         readOnlyHint: boolean;
     };

package/dist/mcp.js

@@ -1,17 +1,20 @@
+import { openContext } from "./context.js";
+import { eventCapabilities, forbidden, listEvents, servesEvents, startEventStream, unsupportedWebhook } from "./mcp-events.js";
+import { PollLeases } from "./mcp-poll.js";
 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";
-//#region src/mcp.ts
+import { textStream } from "./stream.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";
+// 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,8 +173,11 @@ 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) {
@@ -174,5 +253,4 @@ const messages = {
 	"too-large": "The request body is too large.",
 	"not-utf8": "The request body is not UTF-8 JSON."
 };
-//#endregion
 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
+// 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);
@@ -168,5 +172,4 @@ function bodyOf(incoming) {
 		}
 	}, { highWaterMark: 0 });
 }
-//#endregion
-export { serve };
+export { serve, webhookDelivery };