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

package/README.md

@@ -1,8 +1,10 @@
 # Holon TypeScript SDK
 
 [![CI](https://github.com/holon-sh/sdk-ts/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/holon-sh/sdk-ts/actions/workflows/ci.yml)
+[![Docs](https://img.shields.io/badge/docs-holon--labs.dev-blue)](https://holon-labs.dev/docs/)
 [![Node.js](https://img.shields.io/badge/Node.js-22%2B-5FA04E?logo=node.js&logoColor=white)](https://nodejs.org/en/download)
 [![Apache 2.0 License](https://img.shields.io/badge/license-Apache--2.0-green)](https://github.com/holon-sh/sdk-ts/blob/main/LICENSE)
+[![Discord](https://img.shields.io/badge/Discord-join-5865F2?logo=discord&logoColor=white)](https://discord.gg/jXExyBdy)
 
 This repository contains the Node.js runtime for [`holon`](https://github.com/holon-sh/cli).
 
@@ -10,14 +12,37 @@ This repository contains the Node.js runtime for [`holon`](https://github.com/ho
 
 ```sh
 npm install holon-sh@dev
-npm install -D holon-types@next
+npm install -D holon-types typescript
 ```
 
 `holon-types` is the `holon` CLI. `holon types check` brings its own TypeScript compiler and uses the project's `typescript` when one is installed.
 
+## Create an app
+
+```sh
+npx create-holon-app foo
+```
+
 ## Invoking MCP Servers
 
-The Holon TypeScript SDK allows generation of type-safe MCP clients. See [Example](https://github.com/holon-sh/cli#example) for an explanation, or [Dependencies](https://github.com/holon-sh/cli#dependencies) to understand dependency resolution.
+Declare dependencies under `sh.holon.requires` in a [`server.json`](https://modelcontextprotocol.io/registry/quickstart#step-4-create-server-json) beside the server, here the public [Hugging Face](https://huggingface.co/docs/hub/en/hf-mcp-server) MCP server:
+
+```json
+{
+  "name": "com.example/foo",
+  "version": "0.1.0",
+  "description": "Example Foo",
+  "_meta": {
+    "io.modelcontextprotocol.registry/publisher-provided": {
+      "sh.holon": {
+        "requires": {
+          "huggingface": { "url": "https://huggingface.co/mcp" }
+        }
+      }
+    }
+  }
+}
+```
 
 ### Type-checking MCP invocations
 
@@ -25,102 +50,106 @@ The Holon TypeScript SDK allows generation of type-safe MCP clients. See [Exampl
 npx holon types check
 ```
 
-`holon types generate` and `holon types check` write the clients to `generated/holon-sh/` beside your `package.json`, and map `#holon-sh` to them in its `imports`. A package that publishes code calling them lists `generated/holon-sh` in its `files`, so the projects that install it need not generate.
-
-<details open>
-<summary><h3>Call a tool</h3></summary>
+A wrong tool name or argument is a type error:
 
 ```ts
 import { apps } from "#holon-sh";
 
-export async function greet(name: string): Promise<string> {
-  const greeting = await apps.bar.tools.greet({ name }, { timeout: 5000 });
-  return greeting.result;
-}
-```
+await apps.huggingface.tools.hub_repo_search({ query: "llama" });
 
-</details>
+await apps.huggingface.tools.hub_repo_search({ limit: "3" });
+// error TS2322: Type 'string' is not assignable to type 'number'.
 
-<details open>
-<summary><h3>Handle errors</h3></summary>
+await apps.huggingface.tools.hub_repo_details({});
+// error TS2741: Property '"repo_ids"' is missing in type '{}' but required in type '{ config?: string | undefined; limit?: number | undefined; offset?: number | undefined; operations?: ("dataset_preview" | "dataset_structure" | "overview")[] | undefined; repo_ids: string[]; repo_type?: "dataset" | ... 2 more ... | undefined; split?: string | undefined; }'.
 
-```ts
-import { ToolCallError, apps } from "#holon-sh";
-
-try {
-  await apps.bar.tools.greet({ name: "world" });
-} catch (error) {
-  if (!(error instanceof ToolCallError)) throw error;
-  error.message; // includes the server's text
-  error.data;    // the server's structured content, or its text parsed as JSON
-  error.result;  // the original MCP result
-}
+await apps.huggingface.tools.hub_search({ query: "llama" });
+// error TS2339: Property 'hub_search' does not exist on type '{ readonly hf_fs: (input: { operations: { args: string[]; cmd: "attach" | "cat" | "find" | "ls" | "search" | "stat"; }[]; }, options?: ToolCallOptions | undefined) => Promise<{ results: ({ ...; } | { ...; })[]; truncated?: boolean | undefined; truncation_reason?: "output_budget" | undefined; }>; readonly hf_whoami: ...'.
 ```
 
-</details>
+## Events
 
-<details open>
-<summary><h3>Read the whole result</h3></summary>
+A server tells its clients what happens with [MCP Events](https://github.com/modelcontextprotocol/experimental-ext-triggers-events/blob/main/docs/design-sketch-proposal.md), a draft extension of the MCP Triggers & Events Working Group. The draft may change, and this follows it, so it lives under `ext`: `holon-sh/ext/events` on a server and `ext.events` on a client. Expect what is there to change.
 
-`callTool` returns the full MCP result instead of throwing:
+A server declares an event type and emits its occurrences:
 
 ```ts
-const result = await apps.bar.callTool({ name: "greet", arguments: { name: "world" } });
-if (result.resultType === "input_required") {
-  // call again with inputResponses and requestState
-} else if (result.isError) {
-  // inspect result.content
-} else {
-  result.structuredContent; // typed as Outputs["bar"]["greet"]
-}
-```
+import { createEvents } from "holon-sh/ext/events";
+
+const events = createEvents();
+const said = events.event("room.said", {
+  description: "Someone said something in a room",
+  inputSchema: z.object({ room: z.string() }),
+  payloadSchema: z.object({ text: z.string() }),
+  match: ({ room }, args) => room === args.room,
+  transform: ({ text }) => ({ text }),
+});
 
-</details>
+const server = new McpServer({ name: "rooms", version: "1.0.0" });
+events.serve(server);
 
-<details open>
-<summary><h3>Answer a server's question</h3></summary>
+said.emit({ room: "lobby", text: "hello" });
+```
 
-A tool can stop and ask for input through an [MCP elicitation](https://modelcontextprotocol.io/specification/2026-07-28/client/elicitation). Pass `elicit` to answer in place, and the call returns its usual typed output:
+A client subscribes and iterates:
 
 ```ts
-const greeting = await apps.bar.tools.greet({ name: "world" }, {
-  elicit: async ({ message }) => ({ action: "accept", content: await ask(message) }),
-});
+const subscription = await apps.rooms.ext.events.subscribe("room.said", { room: "lobby" });
+for await (const { data } of subscription) console.log(data.text);
 ```
 
-Without `elicit`, the question arrives on `ToolCallError.result`, or as an `input_required` result from `callTool`. To answer later, for example in another request, call again with `inputResponses` and `requestState`.
-
-</details>
+The client is pushed each event on a stream where the server offers one and polls otherwise. It reconnects by itself and resumes from its cursor. Emitted events are kept in the server's memory, so after a restart the client's `onGap` is called: read the current state again.
 
-<details open>
-<summary><h3>Read a resource</h3></summary>
+To hand a page its state and then its changes, a tool returns the state together with `said.cursor()`, read in the same synchronous run, and the page subscribes from that cursor: it hears every change after the state, and none twice. Occurrences emitted one after another in one run reach each subscriber in that order with nothing of the same type between them, so a group of changes is emitted together or sent as one occurrence holding a list.
 
-A provider types a JSON resource by registering it with `mimeType: "application/json"` and an `"sh.holon/outputSchema"` JSON Schema in its `_meta`. The client then offers `read` and `watch`:
+A source that keeps its own history is read through a check function instead. Its cursor is the source's own, so a client resumes across restarts with nothing skipped. Polls are answered by it, streams ask it every second, and the type can still `emit` to push at once:
 
 ```ts
-const summary = await apps.orders.resources["orders://summary"].read();
+events.event("email.received", {
+  inputSchema: z.object({ from: z.string() }),
+  payloadSchema: z.object({ subject: z.string() }),
+  check: async (cursor, { from }) => {
+    if (cursor === null) return { events: [], cursor: await mailbox.head() };
+    const { messages, head } = await mailbox.since(cursor, from);
+    return { events: messages.map(m => ({ eventId: m.id, data: { subject: m.subject } })), cursor: head };
+  },
+});
+```
 
-const controller = new AbortController();
-await apps.orders.resources["orders://summary"].watch(value => console.log(value.total), {
-  signal: controller.signal,
+An event type may also say who may subscribe, and hear when subscriptions begin and end:
+
+```ts
+const said = events.event("room.said", {
+  // ...
+  authorize: ({ room }, context) => mayRead(getContext(context).principal, room),
+  onSubscribe: ({ subscriptionId, arguments: { room } }) => {
+    listeners.set(subscriptionId, upstream.join(room, text => said.emit({ room, text }, { subscriptionId })));
+  },
+  onUnsubscribe: ({ subscriptionId }) => listeners.get(subscriptionId)?.leave(),
 });
+
+said.terminate(subscriptionId);  // terminates one subscription; said.terminate() terminates them all
+said.remove();                   // stops offering the type
 ```
 
-`watch` calls back with the current value, then on every update, until the signal aborts. It needs an endpoint binding and a server that supports resource subscriptions.
+A refused subscription is answered Forbidden, and access is checked again at each poll and heartbeat. A subscription begins when its stream opens or its first poll arrives, and ends when its last stream closes or polls stop for a while. For a signed-in caller its `id` is the same for the same user, client, agent, scopes, event type and arguments, so what is emitted to it while its client reconnects is still delivered. A caller without an identity gets a new id for each stream, and its polls share one lease per arguments with every such caller, to which nothing is emitted alone. Each type keeps its last ten thousand events for ten minutes, polls are told to come back every second, a poll subscription ends a minute after its last poll, and subscriptions are limited to ten thousand in all and a thousand per caller. Names follow the design sketch.
 
-</details>
+Poll, push and webhook delivery are here, with check functions, targeted emits, subscription hooks, authorization, ending subscriptions, limits, paged listing and removing event types. Typed event names are not. Clients are not told when the event types change: they list them again.
 
-## Identify the caller
+### Webhook delivery
 
-Inside a tool callback, `getContext(ctx.http).principal` is the user Holon admitted for the request, or `null` for anonymous requests. A `createMcpHandler` factory can pass its `McpRequestContext` instead.
+A server delivers by webhook too when `createEvents` is given the sketch's `webhookTtl`, the longest lifetime it grants a webhook subscription. Nothing else changes: `emit` reaches webhook subscribers as it does the others. A type with a check function is offered by poll and push only, since webhook delivery sends what is emitted.
 
 ```ts
-import { getContext } from "holon-sh/context";
-
-server.registerTool("whoami", {}, async ctx => {
-  const { principal } = getContext(ctx.http);
-  if (!principal) throw new Error("Sign in first.");
-  principal.claims.email; // standard OpenID claims are typed: string | undefined
-  return { content: [{ type: "text", text: `${principal.subject} at ${principal.issuer}` }] };
-});
+const events = createEvents({ webhookTtl: 30 * 60_000 });
 ```
+
+The SDK keeps each subscription, checks that its callback wants deliveries before sending any, signs each one per [Standard Webhooks](https://www.standardwebhooks.com/), retries failures, and drops a subscription its client stops refreshing. Only an authenticated caller can subscribe, and only an `https` callback at a public address is called. A type's `authorize`, hooks, `terminate`, `remove` and the limits of `createEvents` apply to webhook subscriptions as to the others, and access is checked again every thirty seconds, at each heartbeat. Subscriptions are kept in memory, so after a restart each comes back when its client next refreshes it.
+
+Every subscription expires unless its client refreshes it: one that never expires would need storage the server does not have. On Holon, an app that delivers webhooks leaves `egress` undeclared in `holon.yaml`, since declared hosts are the only ones it can reach.
+
+Subscribing by webhook is for clients that can be reached at an `https` URL. This client does not subscribe by webhook yet: a Holon app cannot serve the route a receiver needs, so it subscribes by push or poll.
+
+## Community
+
+Ask questions and share what you're building on the [Holon Discord](https://discord.gg/jXExyBdy).

package/dist/context.d.ts

@@ -0,0 +1,55 @@
+/** Standard OpenID Connect address claims. */
+export interface AddressClaims {
+    formatted?: string;
+    street_address?: string;
+    locality?: string;
+    region?: string;
+    postal_code?: string;
+    country?: string;
+    [claim: string]: unknown;
+}
+/** Standard OpenID Connect claims. Holon drops one whose value has the wrong type; other claims pass through as JSON. */
+export interface IdentityClaims {
+    name?: string;
+    given_name?: string;
+    family_name?: string;
+    middle_name?: string;
+    nickname?: string;
+    preferred_username?: string;
+    profile?: string;
+    picture?: string;
+    website?: string;
+    email?: string;
+    email_verified?: boolean;
+    gender?: string;
+    birthdate?: string;
+    zoneinfo?: string;
+    locale?: string;
+    phone_number?: string;
+    phone_number_verified?: boolean;
+    address?: AddressClaims;
+    updated_at?: number;
+    [claim: string]: unknown;
+}
+/** The user a request acts for, as Holon admitted it. */
+export interface Principal {
+    issuer: string;
+    subject: string;
+    clientId: string;
+    scopes: string[];
+    claims: IdentityClaims;
+    actor?: Record<string, unknown>;
+}
+/** The caller of the current MCP request. principal is null for anonymous requests. */
+export interface RequestContext {
+    principal: Principal | null;
+}
+/** Read the caller from the context an MCP server receives: a tool callback's ctx.http, or the McpRequestContext of a createMcpHandler factory. */
+export declare function getContext(context?: {
+    authInfo?: {
+        clientId: string;
+        scopes: string[];
+        extra?: Record<string, unknown>;
+    };
+}): RequestContext;
+//# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA,8CAA8C;AAC9C,MAAM,WAAW,aAAa;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IACxH,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CAC1B;AACD,yHAAyH;AACzH,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClG,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAClG,cAAc,CAAC,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAClG,YAAY,CAAC,EAAE,MAAM,CAAC;IAAC,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,aAAa,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IACrG,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CAC1B;AACD,yDAAyD;AACzD,MAAM,WAAW,SAAS;IAAG,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAC;IAAC,MAAM,EAAE,cAAc,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE;AAC3J,uFAAuF;AACvF,MAAM,WAAW,cAAc;IAAG,SAAS,EAAE,SAAS,GAAG,IAAI,CAAA;CAAE;AAM/D,mJAAmJ;AACnJ,wBAAgB,UAAU,CAAC,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,EAAE,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAA;CAAO,GAAG,cAAc,CAK/I"}

package/dist/context.js

@@ -0,0 +1,9 @@
+/** Read the caller from the context an MCP server receives: a tool callback's ctx.http, or the McpRequestContext of a createMcpHandler factory. */
+export function getContext(context = {}) {
+    const { authInfo } = context;
+    const { iss, sub, claims, act } = (authInfo?.extra ?? {});
+    if (!authInfo || typeof iss !== "string" || typeof sub !== "string")
+        return { principal: null };
+    return { principal: { issuer: iss, subject: sub, clientId: authInfo.clientId, scopes: authInfo.scopes, claims: claims ?? {}, ...(act && { actor: act }) } };
+}
+//# sourceMappingURL=context.js.map

package/dist/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAsBA,mJAAmJ;AACnJ,MAAM,UAAU,UAAU,CAAC,OAAO,GAA2F,EAAE;IAC7H,MAAM,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC;IAC7B,MAAM,EAAE,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,CAAC,QAAQ,EAAE,KAAK,IAAI,EAAE,CAAa,CAAC;IACtE,IAAI,CAAC,QAAQ,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;IAChG,OAAO,EAAE,SAAS,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,IAAI,EAAE,EAAE,GAAG,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC;AAC9J,CAAC"}

package/dist/ext/events.d.ts

@@ -0,0 +1,268 @@
+import type { AuthInfo, JSONRPCErrorResponse, McpServer, Server, StandardSchemaWithJSON } from "@modelcontextprotocol/server";
+import { type WebhookOptions } from "./webhooks.js";
+export type { WebhookOptions } from "./webhooks.js";
+/** The request a subscription came in, as Holon admitted it: read its caller with getContext. */
+export type SubscriptionContext = {
+    authInfo?: AuthInfo | undefined;
+} | undefined;
+/** How a subscription receives its events. */
+export type DeliveryModeName = "poll" | "push" | (string & {});
+/** A JSON-RPC error, as a subscription that is terminated or fails is told it. */
+export type EventError = JSONRPCErrorResponse["error"];
+/** A subscription as it begins: who asked, for what, and by which delivery mode. */
+export interface Subscription<A> {
+    /**
+     * The sketch's subscription_id: names the subscription to `emit` and `terminate`. For a caller with an identity it
+     * is the same for the same caller, event type and arguments, so it survives a reconnect and a poll lease that lapses. The caller is the user, the
+     * client acting for them, the agent acting for the user and the token's scopes, as Holon admitted them; two streams
+     * with the same id both receive what is emitted to it. A caller without a subject has no identity: each of its
+     * streams has an id of its own, which ends with the stream, and its polls share one lease per arguments with every
+     * such caller, to which nothing is emitted alone.
+     */
+    readonly subscriptionId: string;
+    readonly name: string;
+    readonly delivery: DeliveryModeName;
+    readonly arguments: A;
+    readonly context: SubscriptionContext;
+}
+/** An occurrence as subscriptions receive it: the sketch's EventOccurrence. `cursor` is the position after it. */
+export interface EventOccurrence<D = unknown> {
+    eventId: string;
+    name: string;
+    /** When it happened, in ISO 8601. */
+    timestamp: string;
+    data: D;
+    cursor?: string | null;
+    _meta?: Record<string, unknown>;
+}
+/**
+ * What happened after a cursor, as a check function finds it: the sketch's EventResult. Each event is an
+ * EventOccurrence whose name is the type's, and whose `eventId` (the source's own, so a client drops one it has seen)
+ * and `timestamp` are made up when not given. An event's `cursor`, the position just after it, lets a batch be cut
+ * short; without it a batch is delivered whole.
+ */
+export interface EventResult<D> {
+    /**
+     * Empty when the cursor was null: a null cursor asks only for the current position. A source without positions
+     * answers with a null cursor, is asked with null each time, and answers each time with what is new.
+     */
+    events: Array<Omit<EventOccurrence<D>, "name" | "eventId" | "timestamp" | "cursor"> & {
+        eventId?: string;
+        timestamp?: string;
+        cursor?: string;
+    }>;
+    /** The position after these events, or null when the source cannot be resumed from a position. */
+    cursor: string | null;
+    /** Events between the cursor and these were skipped, for instance because the source no longer keeps them. */
+    truncated?: boolean;
+    /** More events are ready at once after this batch. */
+    hasMore?: boolean;
+}
+/** An event type: the arguments a subscription gives, and the data each occurrence carries. */
+export interface EventDefinition<A, D> {
+    description?: string;
+    /** The arguments of a subscription. A request whose arguments do not match is refused. */
+    inputSchema: StandardSchemaWithJSON<unknown, A>;
+    /** The data of each occurrence, as subscriptions receive it. */
+    payloadSchema: StandardSchemaWithJSON;
+    /** Listed with the event type, as `_meta` is on a tool. */
+    _meta?: Record<string, unknown>;
+    /**
+     * Whether a subscription with these arguments receives an emitted event. Without it, every subscription does. When
+     * it or `transform` throws, or `transform` returns what cannot be sent as JSON, that event is skipped for that
+     * subscription: its cursor moves past it, a stream is told once with `notifications/events/error`, and the failure
+     * is logged.
+     */
+    match?: (data: D, args: A, context: SubscriptionContext) => boolean;
+    /** The data a subscription with these arguments receives of an emitted event. Without it, the data as emitted. */
+    transform?: (data: D, args: A, context: SubscriptionContext) => unknown;
+    /**
+     * What happened after a cursor, for a source that keeps its own history: polls are answered by it, and streams ask
+     * it every second. The cursor is the source's own, so it outlives the process. A null cursor asks for the
+     * current position. The function filters and shapes for the arguments itself; `match` and `transform` apply only to
+     * what is emitted. Without it, emitted events are kept in memory and polls and streams are served from there.
+     */
+    check?: (cursor: string | null, args: A, context: SubscriptionContext) => EventResult<D> | Promise<EventResult<D>>;
+    /** The delivery modes this event type offers. Every mode served unless given, except webhook for a type with a check function, which webhook delivery does not read. */
+    delivery?: DeliveryModeName[];
+    /**
+     * Whether the caller may subscribe with these arguments. A subscription is refused with Forbidden when it may not,
+     * and one already open is ended when it no longer may: each poll asks, and a stream asks at each heartbeat. A
+     * refused poll ends its lease at once.
+     */
+    authorize?: (args: A, context: SubscriptionContext) => boolean | Promise<boolean>;
+    /**
+     * The sketch's on_subscribe: called when a subscription begins, to set up what its events come from. A
+     * subscription held by two streams at once is set up once. A server that restarts calls it again on the next poll
+     * or stream, with the same id. A subscription refused by the limits never reaches it.
+     */
+    onSubscribe?: (subscription: Subscription<A>) => void | Promise<void>;
+    /**
+     * The sketch's on_unsubscribe: called when a subscription that `onSubscribe` set up ends: its last push stream
+     * closes, its poll lease lapses because polls stopped, or the app terminates it.
+     */
+    onUnsubscribe?: (subscription: Subscription<A>) => void | Promise<void>;
+}
+/** Emits occurrences of one event type to the subscriptions they match, and ends its subscriptions. */
+export interface Emitter<D> {
+    /**
+     * `eventId` lets a client drop an occurrence it has seen. Give the source's own id when it has one. With
+     * `subscriptionId`, the sketch's targeted emit, the occurrence goes to that subscription alone, whatever its arguments; it is kept like any
+     * other, so a subscription that reconnects or polls again from its cursor still has it, or is told of a gap. An
+     * event type with a check function pushes what it emits to open streams at once and does not keep it: polls and
+     * reconnecting streams learn of it from the check function, and one emitted to a subscription that does not get it
+     * on a stream is lost, so that subscription's next poll or stream is told of a gap.
+     *
+     * Emitting is synchronous. Occurrences emitted one after another in the same synchronous run reach each
+     * subscription in that order, with no other occurrence of this type between them, whether polled or pushed. So a
+     * group of changes that nothing may come between is either emitted in one run or sent as one occurrence holding a
+     * list. A subscription skips part of a group only when it is told of a gap: the group outgrew the events kept, or
+     * the subscription fell behind them. For a type with a check function the order holds among what is emitted, but
+     * not between what is emitted and what the check function finds, which may arrive later or again.
+     *
+     * The data is serialised when it is emitted, so data that cannot be sent as JSON throws here, before anything is
+     * kept or sent.
+     */
+    emit(data: D, options?: {
+        eventId?: string;
+        timestamp?: string;
+        subscriptionId?: string;
+    }): void;
+    /**
+     * The position after the last occurrence emitted, for a type without a check function. Return it with the state
+     * a tool reads, in the same synchronous run, and a client that subscribes from it hears every change after that
+     * state and none before. A type with a check function has no such position here: its cursor is the source's own,
+     * so read the source's head instead. This throws for such a type.
+     */
+    cursor(): string;
+    /**
+     * Terminates one subscription, or all of this type's: a stream is sent `notifications/events/terminated` with
+     * `error` and closed, and the next poll is answered with it. Forbidden unless given.
+     */
+    terminate(subscriptionId?: string, error?: EventError): void;
+    /**
+     * Stops offering this event type: its subscriptions end with NotFound.
+     */
+    remove(): void;
+}
+export interface EventsOptions {
+    /**
+     * The sketch's webhook_ttl, which turns webhook delivery on: the longest lifetime granted to a webhook
+     * subscription, in milliseconds. A client's suggestion is held to it, and every grant expires. Without it, webhook
+     * delivery is not offered.
+     */
+    webhookTtl?: number;
+    /** For tests of webhook delivery. */
+    webhook?: WebhookOptions;
+}
+/** A delivery mode besides poll and push: webhook. It registers its requests on each server and is listed by events/list. Not for applications. */
+export interface DeliveryMode {
+    readonly name: string;
+    serve(server: object, internals: Internals): void;
+}
+/** The event types of a process, served by each MCP server it creates. */
+export interface Events {
+    /** Declares an event type. Emit its occurrences with the returned emitter. */
+    event<A, D>(name: string, definition: EventDefinition<A, D>): Emitter<D>;
+    /** Serves events/list, events/poll and events/stream on an McpServer or a Server, and declares the extension. */
+    serve(server: McpServer | Server): void;
+    /** What a delivery mode works with. Not for applications. */
+    readonly [INTERNALS]: Internals;
+}
+/** An emitted event: kept, at a sequence, for a type without a check function; pushed only, for one with. */
+export interface Kept {
+    sequence?: number;
+    at?: number;
+    target?: string | undefined;
+    occurrence: EventOccurrence;
+}
+/** What a subscription is owed after a cursor. */
+export interface Owed {
+    events: EventOccurrence[];
+    /** Events that could not be shaped for it, and were skipped. */
+    failures?: EventError[];
+    /** Where delivery starts. */
+    start: string | null;
+    cursor: string | null;
+    truncated: boolean;
+    hasMore: boolean;
+}
+/** A subscription as a delivery mode holds it. */
+export interface Held {
+    readonly id: string;
+    readonly name: string;
+    readonly delivery: DeliveryModeName;
+    readonly arguments: unknown;
+    readonly context: SubscriptionContext;
+    /** Nothing is emitted to it alone: a poll lease shared by callers without an identity. */
+    untargetable?: boolean;
+    /** Called when the app ends the subscription. */
+    readonly end: (error: EventError) => void;
+    /** Says the hold is over. */
+    close(): void;
+}
+/** The subscription a request asks for, checked. */
+export interface Requested {
+    id: string;
+    lease: string;
+    arguments: unknown;
+    context: SubscriptionContext;
+    untargetable?: boolean;
+}
+/** A declared event type, as the delivery modes see it. */
+export interface EventTypeState {
+    readonly name: string;
+    readonly delivery: DeliveryModeName[];
+    readonly interval: number;
+    readonly check?: EventDefinition<unknown, unknown>["check"];
+    /** Whether the caller may hold the subscription, which a mode that holds subscriptions long asks again. */
+    authorize?(args: unknown, context: SubscriptionContext): boolean | Promise<boolean>;
+    /** Told each event as it is emitted: a push stream is one, and a delivery mode adds its own. */
+    readonly sinks: Set<(kept: Kept) => void>;
+    /** The subscriptions held by every mode, by id. */
+    readonly subscriptions: Map<string, {
+        held: Set<Held>;
+        ready: Promise<unknown>;
+    }>;
+}
+/** What a delivery mode works with. */
+export interface Internals {
+    readonly types: Map<string, EventTypeState>;
+    /** Checks a request, names its event type and the subscription's id. */
+    readonly subscription: (request: Record<string, unknown>, context: SubscriptionContext, delivery?: DeliveryModeName) => Promise<{
+        type: EventTypeState;
+        subscription: Requested;
+    }>;
+    /** Begins holding a subscription. */
+    readonly open: (type: EventTypeState, subscription: {
+        id: string;
+        delivery: DeliveryModeName;
+        arguments: unknown;
+        context: SubscriptionContext;
+    }, end: (error: EventError) => void) => Promise<Held>;
+    /** What a subscription is owed after a cursor. */
+    readonly read: (type: EventTypeState, subscription: Pick<Held, "id" | "arguments" | "context" | "untargetable">, cursor: string | null | undefined, options?: {
+        maxAgeMs?: number;
+        maxEvents?: number;
+    }) => Owed | Promise<Owed>;
+    /** What a subscription is owed of the events emitted. */
+    readonly since: (type: EventTypeState, subscription: Pick<Held, "id" | "arguments" | "context" | "untargetable">, cursor: string | null | undefined, maxAgeMs?: number, limit?: number) => Owed;
+    /** An emitted event as one subscription receives it, or nothing when it is not for it. */
+    readonly shape: (type: EventTypeState, kept: Kept, subscription: Pick<Held, "id" | "arguments" | "context" | "untargetable">, failed?: (error: EventError) => void) => EventOccurrence | undefined;
+    /** A type's current cursor. */
+    readonly position: (type: EventTypeState, sequence?: number) => string;
+}
+/** The identifier a server declares the Events extension under, in capabilities.extensions. */
+export declare const EVENTS_EXTENSION = "io.modelcontextprotocol/events";
+/** Reaches what a delivery mode needs of the events it serves. Not for applications. */
+export declare const INTERNALS: unique symbol;
+/**
+ * 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 declare function createEvents({ webhookTtl, webhook }?: EventsOptions): Events;
+//# sourceMappingURL=events.d.ts.map

package/dist/ext/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/ext/events.ts"],"names":[],"mappings":"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"}