holon-sh 0.0.1-dev.7 → 0.0.1-dev.9

package/dist/ext/events.js

@@ -0,0 +1,619 @@
+// The server side of MCP Events, as the Triggers & Events Working Group's design sketch defines it:
+// https://github.com/modelcontextprotocol/experimental-ext-triggers-events/blob/main/docs/design-sketch-proposal.md
+// The draft is experimental, so this lives under ext and may change with it.
+// It serves the poll and push delivery modes, and webhook delivery when given a webhookTtl, from a module of its own
+// that reaches the event types through the internals below. Names follow the sketch, and types are the MCP SDK's own
+// wherever it has them.
+import { ProtocolError, ProtocolErrorCode, SUBSCRIPTION_ID_META_KEY } from "@modelcontextprotocol/server";
+import { webhooks } from "./webhooks.js";
+/** The identifier a server declares the Events extension under, in capabilities.extensions. */
+export const EVENTS_EXTENSION = "io.modelcontextprotocol/events";
+/** Reaches what a delivery mode needs of the events it serves. Not for applications. */
+export const INTERNALS = Symbol.for("holon-sh.events.internals");
+const INVALID_PARAMS = ProtocolErrorCode.InvalidParams;
+const INTERNAL_ERROR = ProtocolErrorCode.InternalError;
+// The sketch's general-purpose codes, provisional until the specification allocates them.
+const NOT_FOUND = -32023;
+const FORBIDDEN = -32024;
+const RESOURCE_EXHAUSTED = -32025;
+const UNSUPPORTED = -32026;
+// Requests are checked here, against each event type's own schema.
+const params = { "~standard": { version: 1, vendor: "holon-sh", validate: (value) => ({ value: value ?? {} }) } };
+const refusal = ({ code, message, data }) => new ProtocolError(code, message, data);
+const removed = { code: NOT_FOUND, message: "NotFound", data: { kind: "event" } };
+const forbidden = { code: FORBIDDEN, message: "Forbidden" };
+// What a client is told of a failure: its code when it is a JSON-RPC one, and its message.
+const described = (error) => ({
+    code: Number.isInteger(error?.code) ? error.code : INTERNAL_ERROR,
+    message: error?.message || "InternalError",
+    ...(error?.data !== undefined && { data: error.data }),
+});
+// Arguments are the same subscription whatever order their keys came in.
+const canonical = (value) => Array.isArray(value) ? value.map(canonical)
+    : value && typeof value === "object" ? Object.fromEntries(Object.keys(value).sort().map(key => [key, canonical(value[key])]))
+        : value;
+// Who asked, as Holon admitted them: the user, the client acting for them, the agent when one acts for the user, and
+// what the token allows. A caller without a subject has no identity: nobody can tell it from another such caller.
+const caller = (context) => {
+    const authInfo = context?.authInfo;
+    const { iss = null, sub, act = null } = authInfo?.extra ?? {};
+    if (!authInfo || typeof sub !== "string")
+        return null;
+    return JSON.stringify(canonical([iss, sub, authInfo.clientId ?? null, act, [...authInfo.scopes ?? []].sort()]));
+};
+const hex = (bytes) => [...bytes].map(byte => byte.toString(16).padStart(2, "0")).join("");
+// A subscription's id is the same for the same caller, event type and arguments, so it survives reconnects and poll
+// leases, as a webhook subscription's does. It is made with the global crypto, which needs no node:crypto at load.
+const identify = async (who, name, args) => {
+    const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(JSON.stringify([who, name, canonical(args)])));
+    return `sub_${hex(new Uint8Array(digest, 0, 16))}`;
+};
+// A caller without an identity gets an id of its own for each stream.
+const unique = () => `sub_${hex(crypto.getRandomValues(new Uint8Array(16)))}`;
+// A teardown that fails has nobody to tell, and must not take the process down.
+const settle = (run) => { Promise.resolve().then(run).catch(() => { }); };
+const integer = (value, minimum) => value === undefined || Number.isInteger(value) && value >= minimum;
+// What each type without a check function keeps of what it emits, for polls and reconnecting streams: the sketch's
+// emit buffer.
+const KEPT_EVENTS = 10_000;
+const KEPT_AGE = 10 * 60_000;
+// How long a poll is told to wait before the next, and how often a stream asks a check function.
+const INTERVAL = 1000;
+// How often a stream hears from the server when nothing happens, as the sketch recommends.
+const HEARTBEAT = 30_000;
+// How long a poll subscription lasts after its last poll: the sketch's poll subscription TTL.
+const POLL_SUBSCRIPTION_TTL = 60_000;
+// How many subscriptions may be held at once, by every delivery mode, and by one caller. Callers without an identity
+// cannot be told apart, so they count together as one caller.
+const MAX_SUBSCRIPTIONS = 10_000;
+const MAX_SUBSCRIPTIONS_PER_CALLER = 1000;
+// How many event types events/list returns at a time.
+const PAGE_SIZE = 100;
+/**
+ * Event types a process emits and the MCP servers it creates serve, in the poll and push delivery modes of MCP Events,
+ * the draft extension of the Triggers & Events Working Group. Each type keeps the last ten thousand events it emits,
+ * for ten minutes, for polls and for streams that reconnect: those cursors last as long as the process, and after a
+ * restart a client is told that events were skipped. A type with a check function uses its source's cursors instead,
+ * which outlive the process. A type is asked again, and a poll told to come back, every second. A stream hears from
+ * the server every thirty seconds.
+ */
+export function createEvents({ webhookTtl, webhook } = {}) {
+    const modes = webhookTtl === undefined ? [] : [webhooks({ ...webhook, ttl: webhookTtl, heartbeat: HEARTBEAT })];
+    const offered = ["poll", "push", ...modes.map(mode => mode.name)];
+    // Cursors are positions in this process's memory. One from another process names nothing here. The name is made
+    // without node:crypto, which is not there when a server is evaluated for its contract.
+    const epoch = `${Date.now().toString(36)}${Math.random().toString(36).slice(2, 10)}`;
+    const types = new Map();
+    let declared = 0;
+    let subscribed = 0;
+    const callers = new Map();
+    const position = (type, sequence = type.sequence) => `${epoch}.${sequence}`;
+    // An event emitted to one subscription that it could not be given is owed to it as a gap, on its next poll or
+    // stream. The ids owed one are as many as the events a type keeps.
+    const owe = (type, id) => {
+        type.owed.delete(id);
+        type.owed.set(id, true);
+        if (type.owed.size > KEPT_EVENTS)
+            type.owed.delete(type.owed.keys().next().value);
+    };
+    // What a subscription is owed after a cursor from the events emitted: the ones for it, in order, where delivery
+    // starts, and where it now stands. A null cursor starts from now, and so does one from another process. One past
+    // the events still kept starts from the oldest kept, and says that events were skipped.
+    const since = (state, subscription, cursor, maxAgeMs, limit = Infinity) => {
+        const type = state;
+        const now = { events: [], start: position(type), cursor: position(type), hasMore: false };
+        if (cursor == null)
+            return { ...now, truncated: false };
+        const [process, text] = cursor.split(".");
+        const sequence = Number(text);
+        if (process !== epoch || !Number.isInteger(sequence) || sequence > type.sequence)
+            return { ...now, truncated: true };
+        const floor = maxAgeMs === undefined ? -Infinity : Date.now() - maxAgeMs;
+        const later = type.kept.filter(kept => kept.sequence > sequence);
+        const recent = later.filter(kept => kept.at >= floor);
+        const truncated = sequence < type.dropped || recent.length < later.length;
+        const events = [];
+        const failures = [];
+        let reached = recent.length ? recent[0].sequence - 1 : type.sequence;
+        const start = position(type, reached);
+        for (const kept of recent) {
+            if (events.length === limit)
+                return { events, failures, start, cursor: position(type, reached), truncated, hasMore: true };
+            reached = kept.sequence;
+            const event = shape(type, kept, subscription, error => failures.push(error));
+            if (event)
+                events.push(event);
+        }
+        return { events, failures, start, cursor: position(type), truncated, hasMore: false };
+    };
+    // What a subscription is owed after a cursor from the type's check function. The cursor is the author's own. Each
+    // event is placed at its own cursor when it has one, so a batch can be cut short; otherwise at the cursor before
+    // the batch, which is safe to resume from. After a gap, delivery starts from the position the check reached.
+    const checked = async (type, { arguments: args, context }, cursor, maxAgeMs, limit = Infinity) => {
+        const result = await type.check(cursor ?? null, args, context);
+        const next = result?.cursor ?? null;
+        // A null cursor asks for the current position and nothing before it, except of a source that has no positions:
+        // each check of that is asked with null, and answers with what is new.
+        if (cursor == null && next !== null)
+            return { events: [], start: next, cursor: next, truncated: false, hasMore: false };
+        const items = result?.events ?? [];
+        const floor = maxAgeMs === undefined || cursor == null ? -Infinity : Date.now() - maxAgeMs;
+        let truncated = next !== null && Boolean(result.truncated);
+        const events = [];
+        const failures = [];
+        let reached = cursor ?? null;
+        let cuttable = false;
+        const answer = (end, hasMore) => ({ events, failures, start: truncated || !events.length ? end : cursor ?? null, cursor: end, truncated, hasMore });
+        for (const [index, item] of items.entries()) {
+            if (events.length === limit && cuttable)
+                return answer(reached, true);
+            const after = index === items.length - 1 ? next : item.cursor ?? reached;
+            const { eventId = crypto.randomUUID(), timestamp = new Date().toISOString(), data, _meta } = item;
+            if (Date.parse(timestamp) < floor)
+                truncated = next !== null;
+            else if (serialisable(type, eventId, { data, _meta }, error => failures.push(error)))
+                events.push({ eventId, name: type.name, timestamp, data, ...(_meta && { _meta }), cursor: after });
+            reached = after;
+            cuttable = item.cursor != null;
+        }
+        return answer(next, Boolean(result.hasMore));
+    };
+    // What a subscription is owed after a cursor, whichever way its type learns of events.
+    const read = (type, subscription, cursor, { maxAgeMs, maxEvents } = {}) => type.check ? checked(type, subscription, cursor, maxAgeMs, maxEvents) : since(type, subscription, cursor, maxAgeMs, maxEvents);
+    // The occurrence a subscription receives, or nothing when it is not for it. An event emitted to one subscription
+    // is for that one alone, and its arguments are not asked.
+    // An event that cannot be shaped for a subscription, because `match` or `transform` throws or what `transform`
+    // returns cannot be sent as JSON, is skipped for that subscription alone, so its cursor moves past it. It is
+    // logged, and `failed` hears of it so a stream can say so once.
+    const shape = (state, { sequence, target, occurrence }, { id, untargetable, arguments: args, context }, failed) => {
+        const type = state;
+        let data;
+        try {
+            if (target !== undefined ? untargetable || target !== id : type.match && !type.match(occurrence.data, args, context))
+                return undefined;
+            data = type.transform ? type.transform(occurrence.data, args, context) : occurrence.data;
+            if (type.transform)
+                JSON.stringify(data);
+        }
+        catch (error) {
+            skipped(type, occurrence.eventId, error, failed);
+            return undefined;
+        }
+        return { ...occurrence, data, ...(sequence !== undefined && { cursor: position(type, sequence) }) };
+    };
+    const skipped = (type, eventId, error, failed) => {
+        console.error(`holon-sh/ext/events: event ${eventId} of ${type.name} was skipped for a subscription:`, error);
+        failed?.({ code: INTERNAL_ERROR, message: `Event ${eventId} could not be delivered and was skipped`, data: { eventId, reason: String(error?.message ?? error) } });
+    };
+    // What a check function found is skipped in the same way when it cannot be sent as JSON.
+    const serialisable = (type, eventId, value, failed) => {
+        try {
+            JSON.stringify(value);
+            return true;
+        }
+        catch (error) {
+            skipped(type, eventId, error, failed);
+            return false;
+        }
+    };
+    // The event type and arguments a request names, checked as the sketch's errors require, in its order: the type,
+    // the delivery mode, the request's own fields, the arguments, and then whether the caller may subscribe. A caller
+    // refused loses what it holds of that subscription at once.
+    const subscription = async ({ name, arguments: args = {}, cursor, maxAgeMs, maxEvents }, context, delivery) => {
+        const type = types.get(name);
+        if (!type)
+            throw refusal(removed);
+        if (delivery && !type.delivery.includes(delivery))
+            throw refusal({ code: UNSUPPORTED, message: "Unsupported", data: { feature: "deliveryMode", value: delivery } });
+        if (cursor != null && typeof cursor !== "string")
+            throw new ProtocolError(INVALID_PARAMS, "cursor must be a string or null");
+        if (!integer(maxAgeMs, 0))
+            throw new ProtocolError(INVALID_PARAMS, "maxAgeMs must be a non-negative integer");
+        if (!integer(maxEvents, 1))
+            throw new ProtocolError(INVALID_PARAMS, "maxEvents must be a positive integer");
+        const checked = await type.inputSchema["~standard"].validate(args);
+        if (checked.issues)
+            throw new ProtocolError(INVALID_PARAMS, `Invalid arguments for ${name}: ${checked.issues.map(issue => issue.message).join("; ")}`);
+        const who = caller(context);
+        // Polls share a lease per caller and arguments, and callers without an identity share one per arguments.
+        const lease = await identify(who, type.name, checked.value);
+        if (type.authorize && !(await type.authorize(checked.value, context))) {
+            endSubscription(type, lease, forbidden);
+            // This refusal is the answer the poll lease would have given, so the next poll begins afresh.
+            leases.delete(lease);
+            throw refusal(forbidden);
+        }
+        return { type, subscription: { id: who === null ? unique() : lease, lease, arguments: checked.value, context } };
+    };
+    const endSubscription = (type, id, error) => {
+        for (const held of [...type.subscriptions.get(id)?.held ?? []])
+            held.end(error);
+    };
+    // Begins holding a subscription, by a stream, a poll lease or another delivery mode: counted against the limits
+    // first, so a refused one provisions nothing. The type's onSubscribe is called when the first hold of an id
+    // begins, and its onUnsubscribe when the last ends, so two streams of one subscription set it up once. `end` is how
+    // the delivery mode is told the app terminated it; `close` is how the mode says its hold is over.
+    const open = async (state, { id, delivery, arguments: args, context }, end) => {
+        const type = state;
+        if (types.get(type.name) !== type)
+            throw refusal(removed);
+        // Callers without an identity cannot be told apart, so they count together as one.
+        const who = caller(context) ?? "anonymous";
+        if (subscribed >= MAX_SUBSCRIPTIONS)
+            throw refusal({ code: RESOURCE_EXHAUSTED, message: "ResourceExhausted", data: { limit: "subscriptions", max: MAX_SUBSCRIPTIONS } });
+        if ((callers.get(who) ?? 0) >= MAX_SUBSCRIPTIONS_PER_CALLER)
+            throw refusal({ code: RESOURCE_EXHAUSTED, message: "ResourceExhausted", data: { limit: "subscriptionsPerCaller", max: MAX_SUBSCRIPTIONS_PER_CALLER } });
+        subscribed++;
+        callers.set(who, (callers.get(who) ?? 0) + 1);
+        let entry = type.subscriptions.get(id);
+        if (!entry) {
+            const subscription = { subscriptionId: id, name: type.name, delivery, arguments: args, context };
+            const ready = Promise.resolve().then(() => type.onSubscribe?.(subscription)).then(() => subscription);
+            ready.catch(() => { });
+            entry = { held: new Set(), ready };
+            type.subscriptions.set(id, entry);
+        }
+        const current = entry;
+        let closed = false;
+        const held = { id, name: type.name, delivery, arguments: args, context, end, close() {
+                if (closed)
+                    return;
+                closed = true;
+                subscribed--;
+                const count = callers.get(who) ?? 1;
+                if (count === 1)
+                    callers.delete(who);
+                else
+                    callers.set(who, count - 1);
+                current.held.delete(held);
+                if (current.held.size)
+                    return;
+                if (type.subscriptions.get(id) === current)
+                    type.subscriptions.delete(id);
+                // Only a subscription that was set up is told it ended.
+                current.ready.then(subscription => { if (type.onUnsubscribe)
+                    settle(() => type.onUnsubscribe(subscription)); }, () => { });
+            } };
+        current.held.add(held);
+        try {
+            await current.ready;
+        }
+        catch (error) {
+            held.close();
+            throw error;
+        }
+        // The type was removed while the subscription was being set up.
+        if (types.get(type.name) !== type) {
+            held.close();
+            throw refusal(removed);
+        }
+        return held;
+    };
+    // Poll subscriptions are leased: the first poll of a subscription begins one, each poll renews it, and it ends
+    // when polls stop for a minute, many of the intervals the poll was told to wait.
+    const leases = new Map();
+    const lease = async (type, { lease: key, ...subscribed }) => {
+        // A lease shared by callers without an identity is nobody's in particular, so nothing is emitted to it alone.
+        const shared = key !== subscribed.id;
+        let lent = leases.get(key);
+        if (lent && (lent.ended || lent.type !== type)) {
+            leases.delete(key);
+            clearTimeout(lent.timer);
+            lent.release?.();
+            // The poll after one the app ended is answered with why, and the one after it begins afresh.
+            if (lent.ended && lent.type === type)
+                throw refusal(lent.ended);
+            lent = undefined;
+        }
+        if (!lent) {
+            const fresh = { type };
+            lent = fresh;
+            leases.set(key, fresh);
+            fresh.opening = open(type, { ...subscribed, id: key, delivery: "poll" }, error => {
+                fresh.ended = error;
+                fresh.release?.();
+            });
+            fresh.opening.then(held => {
+                if (shared)
+                    held.untargetable = true;
+                fresh.release = () => held.close();
+                if (fresh.ended)
+                    held.close();
+            }, () => { if (leases.get(key) === fresh)
+                leases.delete(key); });
+        }
+        const current = lent;
+        const held = await current.opening;
+        // Ended while it was being set up.
+        if (current.ended) {
+            leases.delete(key);
+            throw refusal(current.ended);
+        }
+        clearTimeout(current.timer);
+        current.timer = setTimeout(() => {
+            if (leases.get(key) === current)
+                leases.delete(key);
+            held.close();
+        }, POLL_SUBSCRIPTION_TTL);
+        current.timer.unref?.();
+        return held;
+    };
+    // What a delivery mode works with: `subscription` checks a request, names its event type and the subscription's
+    // id, `open` begins holding a subscription, `read` gives a subscription what it is owed after a cursor (`since` and
+    // `shape` for emitted events alone), `position` is a type's cursor, a type's `sinks` hear what is emitted, and its
+    // `subscriptions` are the ones held by every mode, by id.
+    const internals = { types, subscription, open, read, since, shape, position };
+    return {
+        [INTERNALS]: internals,
+        /**
+         * Declares an event type and returns the function that emits it. `match` decides which subscriptions receive an
+         * event from their arguments, and `transform` shapes its data for each. `check` returns what happened after a
+         * cursor, for event types whose source keeps its own history.
+         */
+        event(name, { description, inputSchema, payloadSchema, _meta, match, transform, check, delivery = offered.filter(mode => !check || mode !== "webhook"), authorize, onSubscribe, onUnsubscribe }) {
+            if (types.has(name))
+                throw new Error(`Event ${name} is already declared.`);
+            const unknown = delivery.filter(mode => !offered.includes(mode));
+            if (unknown.length || !delivery.length)
+                throw new Error(`Event ${name} is delivered by ${delivery.join(", ") || "nothing"}, but only ${offered.join(", ")} are served.`);
+            // Webhook delivery sends what is emitted, and does not ask a check function.
+            if (check && delivery.includes("webhook"))
+                throw new Error(`Event ${name} has a check function, which webhook delivery does not read.`);
+            const type = {
+                name, order: ++declared, description, inputSchema, payloadSchema, _meta, match, transform, check: check, interval: INTERVAL, delivery, authorize, onSubscribe, onUnsubscribe,
+                sequence: 0, dropped: 0, kept: [], sinks: new Set(), subscriptions: new Map(), owed: new Map(),
+            };
+            types.set(name, type);
+            return {
+                emit(data, { eventId = crypto.randomUUID(), timestamp = new Date().toISOString(), subscriptionId: target } = {}) {
+                    const occurrence = { eventId, name, timestamp, data };
+                    // Data that cannot be sent as JSON is refused here, before anything is kept or sent.
+                    JSON.stringify(occurrence);
+                    // A type with a check function is asked for what polls are owed, so what it emits is pushed and not kept.
+                    if (type.check) {
+                        // An event for one subscription that has no stream to take it is lost.
+                        if (target !== undefined && ![...type.subscriptions.get(target)?.held ?? []].some(held => held.delivery !== "poll"))
+                            owe(type, target);
+                        for (const sink of type.sinks)
+                            sink({ target, occurrence });
+                        return;
+                    }
+                    // An event for one subscription is kept like any other, so the subscription has it when it comes back.
+                    const kept = { sequence: ++type.sequence, at: Date.now(), target, occurrence };
+                    type.kept.push(kept);
+                    while (type.kept.length > KEPT_EVENTS || type.kept[0].at < kept.at - KEPT_AGE)
+                        type.dropped = type.kept.shift().sequence;
+                    for (const sink of type.sinks)
+                        sink(kept);
+                },
+                cursor() {
+                    if (type.check)
+                        throw new Error(`Event ${name} has a check function, whose cursor is its source's own.`);
+                    return position(type);
+                },
+                terminate(id, error = forbidden) {
+                    if (id !== undefined)
+                        return endSubscription(type, id, error);
+                    for (const each of [...type.subscriptions.keys()])
+                        endSubscription(type, each, error);
+                },
+                remove() {
+                    if (types.get(name) !== type)
+                        return;
+                    types.delete(name);
+                    for (const each of [...type.subscriptions.keys()])
+                        endSubscription(type, each, removed);
+                },
+            };
+        },
+        /** Serves the declared event types on an MCP server: events/list, events/poll and events/stream. */
+        serve(mcp) {
+            const underlying = "server" in mcp ? mcp.server : mcp;
+            // The custom methods are registered through the parts of the server this module uses.
+            const server = underlying;
+            // The sketch declares capabilities.events. The MCP SDK's client drops top-level capabilities it does not know,
+            // so the extension is declared under capabilities.extensions too, where SDK clients read it.
+            // Clients are never told the event types changed: over Holon's stateless HTTP, the notification reaches none.
+            server.registerCapabilities({ events: { listChanged: false }, extensions: { [EVENTS_EXTENSION]: { listChanged: false } } });
+            const json = (schema) => schema["~standard"].jsonSchema.input({ target: "draft-2020-12" });
+            server.setRequestHandler("events/list", { params }, request => {
+                const all = [...types.values()];
+                let start = 0;
+                if (request.cursor != null) {
+                    const after = Number(request.cursor);
+                    if (typeof request.cursor !== "string" || !Number.isInteger(after))
+                        throw new ProtocolError(INVALID_PARAMS, "Invalid cursor for events/list");
+                    start = all.findIndex(type => type.order > after);
+                    if (start < 0)
+                        start = all.length;
+                }
+                const page = all.slice(start, start + PAGE_SIZE);
+                return {
+                    events: page.map(type => ({
+                        name: type.name,
+                        ...(type.description && { description: type.description }),
+                        delivery: type.delivery,
+                        inputSchema: json(type.inputSchema),
+                        payloadSchema: json(type.payloadSchema),
+                        ...(type._meta && { _meta: type._meta }),
+                    })),
+                    ...(start + PAGE_SIZE < all.length && { nextCursor: String(page.at(-1).order) }),
+                };
+            });
+            for (const mode of modes)
+                mode.serve(underlying, internals);
+            server.setRequestHandler("events/poll", { params }, async (request, ctx) => {
+                const { type, subscription: subscribed } = await subscription(request, ctx.http, "poll");
+                const held = await lease(type, subscribed);
+                // Each poll is answered for its own caller, with the lease's id.
+                const { events, start, failures, truncated, ...rest } = await read(type, { ...subscribed, id: held.id, untargetable: held.untargetable }, request.cursor, request);
+                const lost = !held.untargetable && type.owed.delete(held.id);
+                // A poll carries its cursor once, for the whole response.
+                return { events: events.map(({ cursor, ...event }) => event), ...rest, truncated: truncated || lost, nextPollMs: type.interval };
+            });
+            server.setRequestHandler("events/stream", { params }, async (request, ctx) => {
+                const { type: state, subscription: subscribed } = await subscription(request, ctx.http, "push");
+                const type = state;
+                const { signal } = ctx.mcpReq;
+                const meta = { [SUBSCRIPTION_ID_META_KEY]: ctx.mcpReq.id };
+                let done = false;
+                let ending;
+                let wake = () => { };
+                const finish = () => {
+                    done = true;
+                    wake();
+                };
+                const held = await open(type, { ...subscribed, delivery: "push" }, error => {
+                    ending = error;
+                    finish();
+                });
+                // A client that left while the subscription was being set up is not waited for.
+                if (signal.aborted) {
+                    held.close();
+                    return { _meta: {} };
+                }
+                // Ended while it was being set up: no stream is opened, and the request is refused.
+                if (ending) {
+                    held.close();
+                    throw refusal(ending);
+                }
+                signal.addEventListener("abort", finish, { once: true });
+                // A stream that cannot be written to is over.
+                const notify = async (method, body) => {
+                    if (signal.aborted)
+                        return;
+                    try {
+                        await ctx.mcpReq.notify({ method: `notifications/events/${method}`, params: { ...body, _meta: meta } });
+                    }
+                    catch {
+                        finish();
+                    }
+                };
+                // The stream follows its cursor: emitted events wake it, and a type with a check function is asked again
+                // every interval. What it is owed waits in the buffer or the source, not here, so a slow client is not owed
+                // more memory than one batch; when what it is owed is no longer kept, it is told of the gap.
+                let cursor = request.cursor ?? null;
+                let behind = true;
+                // What a type with a check function emitted and the stream has yet to send. The check function finds it
+                // too, so when too much waits the oldest is let go.
+                const pushed = [];
+                const sink = (kept) => {
+                    if (type.check) {
+                        pushed.push(kept);
+                        if (pushed.length > KEPT_EVENTS)
+                            pushed.shift();
+                    }
+                    else
+                        behind = true;
+                    wake();
+                };
+                type.sinks.add(sink);
+                let beat;
+                let beating = false;
+                const heartbeats = () => setInterval(async () => {
+                    if (beating)
+                        return;
+                    beating = true;
+                    try {
+                        // Access is checked again while the subscription lasts, and one that is lost ends it.
+                        if (type.authorize && !(await type.authorize(subscribed.arguments, subscribed.context)))
+                            return endSubscription(type, held.id, forbidden);
+                        await notify("heartbeat", { cursor });
+                    }
+                    catch (error) {
+                        await notify("error", { error: described(error) });
+                    }
+                    finally {
+                        beating = false;
+                    }
+                }, HEARTBEAT);
+                let first = true;
+                try {
+                    let due = 0;
+                    while (!done) {
+                        if (type.check ? Date.now() >= due : behind) {
+                            behind = false;
+                            let result;
+                            try {
+                                result = await read(type, held, cursor, { ...(first && request.maxAgeMs !== undefined && { maxAgeMs: request.maxAgeMs }) });
+                            }
+                            catch (error) {
+                                // Without a first answer there is no stream to tell, and the request fails.
+                                if (first)
+                                    throw error;
+                                await notify("error", { error: described(error) });
+                            }
+                            due = Date.now() + type.interval;
+                            if (result) {
+                                // A check function's gap is told after the events that follow it, at the position after them, since
+                                // the position before them is not known and the client's cursor must not go back. The stream is
+                                // confirmed before anything else is said on it.
+                                const after = type.check && result.truncated && !first;
+                                const truncated = result.truncated || first && type.owed.delete(held.id);
+                                if (first || truncated && !after)
+                                    await notify("active", { cursor: type.check && result.truncated ? cursor : result.start, truncated });
+                                if (first)
+                                    beat = heartbeats();
+                                first = false;
+                                for (const error of result.failures ?? [])
+                                    await notify("error", { error });
+                                for (const event of result.events) {
+                                    if (done)
+                                        break;
+                                    await notify("event", event);
+                                    cursor = event.cursor ?? null;
+                                }
+                                if (done)
+                                    break;
+                                cursor = result.cursor;
+                                if (after)
+                                    await notify("active", { cursor, truncated: true });
+                                if (result.hasMore) {
+                                    due = 0;
+                                    behind = true;
+                                }
+                            }
+                        }
+                        // What a type with a check function emits is sent at once, at the cursor the stream has reached.
+                        while (pushed.length && !done) {
+                            let failure;
+                            const event = shape(type, pushed.shift(), held, error => { failure = error; });
+                            if (failure)
+                                await notify("error", { error: failure });
+                            if (event)
+                                await notify("event", { ...event, cursor });
+                        }
+                        if (done)
+                            break;
+                        let timer;
+                        await new Promise(resolve => {
+                            wake = resolve;
+                            if (done || pushed.length || (!type.check && behind))
+                                resolve();
+                            else if (type.check)
+                                timer = setTimeout(resolve, Math.max(0, due - Date.now()));
+                        });
+                        clearTimeout(timer);
+                        wake = () => { };
+                    }
+                    if (ending) {
+                        if (first)
+                            throw refusal(ending);
+                        await notify("terminated", { error: ending });
+                    }
+                }
+                finally {
+                    clearInterval(beat);
+                    type.sinks.delete(sink);
+                    // What was emitted to this subscription alone and not sent is owed to it as a gap when it comes back.
+                    if (held.id === subscribed.lease && pushed.some(kept => kept.target === held.id))
+                        owe(type, held.id);
+                    held.close();
+                }
+                // The final frame, sent when the server ends the stream; when the client did, nobody is listening.
+                return { _meta: {} };
+            });
+        },
+    };
+}
+//# sourceMappingURL=events.js.map