@acid-cat/core-ts 0.8.0 → 0.10.0

package/README.md

@@ -1,8 +1,8 @@
 # @acid-cat/core-ts
 
-Serve AcidCat capabilities in plain TypeScript. npm package: `@acid-cat/core-ts`.
+Serve AcidCat capabilities and events in plain TypeScript. npm package: `@acid-cat/core-ts`.
 
-This package has no Effect dependency. A capability returns a promise. Inputs are validated with any library that implements [Standard Schema](https://standardschema.dev), for example Zod, Valibot or ArkType. The application writes its own catalog.
+This package has no Effect dependency. A capability returns a promise. An event gives an async iterable. Inputs are validated with any library that implements [Standard Schema](https://standardschema.dev), for example Zod, Valibot or ArkType. The application writes its own catalog.
 
 ```sh
 pnpm add @acid-cat/core-ts
@@ -42,6 +42,39 @@ export const aircon = defineApp<{ unit: Unit }>({
 - `defineCapability` and `capabilitiesFor` keep the literal type of `id`, so that an application can type its ids. `run`, `availability` and `state` all get the same `Context`.
 - An application lists only capabilities that `defineCapability` or `capabilitiesFor` made. Each one has `decode`, which validates an input that is not trusted with the input schema and then gives the call of `run`. A session calls it, because there the type of the input is not known.
 
+## Write events
+
+An [event](../../spec/events.md) is a kind of thing that happens, and that clients can follow. `subscribe` gives an async iterable, for example an async generator, with one value for each occurrence.
+
+```ts
+import { eventsFor } from "@acid-cat/core-ts";
+
+const Status = z.object({ on: z.boolean(), celsius: z.number() }).meta({ id: "Status" });
+const event = eventsFor<{ unit: Unit }>();
+
+export const statusChanged = event({
+  id: "aircon.status.changed",
+  description: "The status of the unit changed. The occurrence gives the new status.",
+  audience: ["app", "mcp"],
+  input: z.object({}),
+  payload: Status,
+  async *subscribe(_input, { context, signal }) {
+    for await (const status of context.unit.changes(signal)) yield { data: status };
+  },
+});
+
+export const aircon = defineApp<{ unit: Unit }>({ targets, capabilities: [powerSet], events: [statusChanged] });
+```
+
+- `subscribe` gets the input, and `{ signal, context, cursor, maxAgeMs }`. The signal aborts when the subscription ends, in all ways. Stop the work and release the resources then.
+- Each value is `{ data }`, and optionally `eventId`, `timestamp`, `cursor` and `truncated`. Give the `eventId` of the source if it has one. With none, the session makes a unique id. With no `timestamp`, the session uses the time at which it gets the value.
+- `data` must agree with the payload schema. The session gives the client the output of the schema, as a copy. With no payload schema, `data` must be an empty object.
+- If `subscribe` throws before it gives an iterable, the subscription fails as `internal` before it starts. If the iterable throws, or gives data that does not agree with the payload schema, the subscription ends with `internal`. The details go to `onDefect`, not to the client.
+- When the iterable ends, the subscription is complete.
+- The session asks for the first value before the promise of `subscribe` resolves. Thus the body of an async generator runs until its first `await` or `yield` before the client gets the iterable. Register a listener on the source before that point, and the subscription gets each change after `subscribe` resolves.
+- To resume, give a `cursor` with each value. A client can give a `cursor` and `maxAgeMs` when it subscribes. Start after the cursor, and send no occurrence older than `maxAgeMs`. If you skip occurrences, give `truncated: true` on the first value. An event that gives no cursors ignores them.
+- `defineEvent` and `eventsFor` keep the literal type of `id`. Capabilities and events share one set of ids.
+
 ## Write the catalog
 
 ```ts
@@ -51,20 +84,93 @@ const toJsonSchema = (schema) => z.toJSONSchema(schema, { target: "draft-2020-12
 await writeFile("acidcat.catalog.json", renderCatalog(aircon, { toJsonSchema })); // canonical form
 ```
 
-Standard Schema does not convert to JSON Schema. Give the converter of your schema library as `toJsonSchema`.
+Standard Schema does not convert to JSON Schema. Give the converter of your schema library as `toJsonSchema`. The catalog has an `events` member when the application has events.
 
-## Serve the capabilities
+## Serve the capabilities and the events
 
 | Function | Binding | Result |
 | --- | --- | --- |
-| `createSession(app, options)` | [TypeScript](../../spec/bindings/typescript.md) | A session with a handle for each capability in the view |
-| `mcpHandler(app, options)` | [MCP](../../spec/bindings/mcp.md) | `(request: Request) => Promise<Response>` |
+| `createSession(app, options)` | [TypeScript](../../spec/bindings/typescript.md) | A session with a handle for each capability and an event handle for each event in the view |
+| `mcpHandler(app, options)` | [MCP](../../spec/bindings/mcp.md#http) through HTTP | `(request: Request) => Promise<Response>` |
+| `mcpHandshake(handler)` | [MCP](../../spec/bindings/mcp.md#earlier-revisions-through-http) through HTTP, for earlier revisions | The handler, which also serves the `initialize` handshake of earlier revisions. From [`@acid-cat/mcp-handshake`](../mcp-handshake) |
+| `mcpStdioMain(app, options)`, `runMcpStdio(…)` | [MCP](../../spec/bindings/mcp.md#stdio) through stdio | The MCP server of the process, or a promise that resolves when the input ends |
 | `httpHandler(app, options)` | [HTTP](../../spec/bindings/http.md) | `(request: Request) => Promise<Response>` |
 | `cliMain(app, options)`, `runCli(…)` | [CLI](../../spec/bindings/cli.md) | The command line of the process, or an exit code |
-| `installWebMcp(session)` | [WebMCP](../../spec/bindings/webmcp.md) | Tools in the page, with a status |
+| `installWebMcp(session)` | [WebMCP](../../spec/bindings/webmcp.md) | Tools in the page, with a status. WebMCP serves no events |
 | `serve(handler, options)`, from `@acid-cat/core-ts/node` | MCP and HTTP | A Node.js server for the web handlers. See [Serve on Node.js](#serve-on-nodejs) |
 
-When the signal of a request aborts, `mcpHandler` and `httpHandler` cancel the call of the request.
+When the signal of a request aborts, `mcpHandler` and `httpHandler` cancel the call or the subscription of the request.
+
+Each binding serves the events of its view:
+
+| Binding | Events |
+| --- | --- |
+| TypeScript | `session.eventHandle(event).subscribe(input)`. See [Event handles](#event-handles) |
+| HTTP | `GET {base}/events` lists them. `POST {base}/events/{id}` gives a stream of server-sent events: `event: next` for each occurrence, then `event: complete`, or `event: error` with `internal`. `Last-Event-ID` gives the cursor, and `?maxAgeMs=` gives `maxAgeMs`. The option `keepaliveMs` (15 seconds) sets the time after which an idle stream gets a comment line |
+| MCP | The MCP events extension, revision `2026-07-28` only: `events/list`, push delivery with `events/stream`, poll delivery with `events/poll`, and webhook delivery with `events/subscribe` and `events/unsubscribe` through HTTP if the deployment turns it on. Through HTTP, the answer to `events/stream` is a stream of server-sent events. The option `heartbeatMs` (15 seconds) sets the time after which an idle stream gets `notifications/events/heartbeat`. A client with the `initialize` handshake gets no events. See [MCP poll and webhook delivery](#mcp-poll-and-webhook-delivery) |
+| CLI | `watch <id>` writes each occurrence on one line. See [Command line](#command-line) |
+
+The options `bufferLimit` of `createSession`, `httpHandler`, `mcpHandler` and `runMcpStdio` set the number of occurrences that each subscription keeps for a client that reads slowly. The default is 256. When the limit is full, the oldest occurrence goes, and the next occurrence that the client reads has `truncated: true`.
+
+### MCP poll and webhook delivery
+
+A poll lease and a webhook subscription continue after the request that started them. Each one holds its subscription in a session of its own. Through HTTP, that session has the context of the request that started it: the shared `context`, or a new one from `createContext`. Through stdio, it has the `context` of the process. The session closes when the lease or the webhook subscription ends. This state is in memory: when the process stops, it is lost, and clients start again with their cursors.
+
+`handler.close()` of `mcpHandler` ends all leases and webhook subscriptions. `await using handler = mcpHandler(…)` calls it at the end of the block. Through stdio, the end of standard input ends them.
+
+**Poll.** `events/poll` reads the occurrences of a lease (spec/bindings/mcp.md#poll). Both `mcpHandler` and `runMcpStdio` serve it. The key of a lease is the principal, the id and the input, so two polls of the same client with the same input read one lease. The option `poll` sets the limits:
+
+| Option of `poll` | Default | Use |
+| --- | --- | --- |
+| `leaseMs` | 5 minutes | A lease that gets no poll for this time ends, and its subscription is cancelled |
+| `bufferLimit` | 1000 | The number of occurrences that each lease keeps. When the buffer is full, the oldest occurrence goes. A cursor older than the buffer gets `truncated: true` |
+| `maxEvents` | 100 | The number of occurrences in a result when the request gives no `maxEvents` |
+| `nextPollMs` | 2000 | The `nextPollMs` of each result |
+
+The cursor of a poll tells the lease, the position in its buffer, and the last cursor of the provider. When a lease ended, a poll with its cursor starts a new lease that resumes after that cursor of the provider, with `maxAgeMs`.
+
+**Principal.** The option `principal(request)` of `mcpHandler` gives the identity of the client of a request, for example the subject of a verified token, or `undefined` when the request has none. It is part of the key of a lease and of a webhook subscription, so that one client cannot read the lease of another. Through stdio, the process serves one client, and leases have no principal.
+
+**Webhook.** Webhook delivery is off by default, and only through HTTP. Turn it on with the option `webhooks`, and `webhookDelivery(options)` from `@acid-cat/core-ts/node`. It sends each occurrence in a signed `POST` request to the URL of the client (spec/bindings/mcp.md#webhook). It needs `principal`: a request with no principal gets `Forbidden`.
+
+```ts
+import { mcpHandler } from "@acid-cat/core-ts";
+import { serve, webhookDelivery } from "@acid-cat/core-ts/node";
+
+const mcp = mcpHandler(aircon, {
+  name: "aircon",
+  version: "1.0.0",
+  allowedOrigins: [],
+  toJsonSchema,
+  context: { unit },
+  principal: (request) => verifiedSubject(request), // string | undefined
+  webhooks: webhookDelivery({ maxTtlMs: 3_600_000 }),
+});
+await serve({ "/mcp": mcp });
+```
+
+| Option of `webhookDelivery` | Default | Use |
+| --- | --- | --- |
+| `allow(url)` | None | The allowlist. A URL for which it gives `true` gets deliveries with no verification |
+| `allowPrivateNetworks` | `false` | Connect also to addresses that are not globally routable. Only for tests and private networks |
+| `ca` | None | Certificates of authorities, in PEM form, to trust beside the default ones |
+| `maxTtlMs`, `minTtlMs` | 1 hour, 1 minute | The limits of the lifetime that the server grants for `ttlMs` |
+| `maxSubscriptions` | 100 | The maximum number of webhook subscriptions of one principal. Over it, `ResourceExhausted` |
+| `attempts`, `retryWindowMs` | 5, 15 minutes | The attempts of one delivery, and the time in which the server makes them |
+| `retryDelayMs(attempt)` | 10 s, 30 s, 90 s, 270 s | The wait before the next attempt |
+| `timeoutMs` | 5 seconds | The time that the server waits for each answer |
+| `rotationGraceMs` | 5 minutes | After a new secret, the time in which the server signs with the old secret and the new secret |
+
+Each pair of principal and URL must agree to get deliveries before the first delivery: the URL is in the allowlist, or the endpoint answers the `verification` message with its challenge. The server keeps each verification while the process runs. A refresh with the same key grants a new lifetime and replaces the secret. The server sends the deliveries of a subscription one at a time, in order. The `cursor` of each delivery is the watermark: the last cursor of an occurrence whose delivery succeeded or was abandoned.
+
+Security of webhook delivery:
+
+- The URL must use `https`. The server checks the certificate of the endpoint.
+- For each request, the server resolves the host name, and connects only to an address that is globally routable, unless `allowPrivateNetworks` is `true`. It connects to the address that it checked, with the host name in the `Host` header and in TLS, so a change of DNS between the check and the connection has no effect. It does not follow redirects.
+- `lastError` and the reason of `CallbackEndpointError` are categories, for example `http_4xx` or `tls_error`. The server gives no text of the answer of the endpoint.
+- The server never logs or returns a secret.
+
+The option `clock` of `mcpHandler`, `runMcpStdio` and `webhookDelivery` gives the time and the timers of leases, lifetimes and retries. The default is the clock of the system. Tests give a clock that they control.
 
 ### Serve on Node.js
 
@@ -89,7 +195,22 @@ console.log(server.url); // http://127.0.0.1:3000
 
 `serve` resolves when the server listens. `server.close()` stops it, and `await using server = await serve(…)` closes it at the end of the block. When a client closes its connection, the signal of its request aborts, so the handler cancels the call.
 
-`serve` gives a plain HTTP/1.1 server. For more, use a library for web handlers, for example [srvx](https://srvx.h3.dev): HTTPS, HTTP/2, middleware, or the same server code on Bun and Deno. Give it the handler. Make sure that the library aborts the signal of a request when the client closes the connection. If it does not, a closed connection does not cancel the call.
+`serve` gives a plain HTTP/1.1 server. It does not serve HTTPS. When clients connect through a network, end TLS before the server, in the platform: a load balancer, the ingress of a Kubernetes cluster (for example with cert-manager for the certificates), or a tunnel such as Cloudflare Tunnel. The platform sends plain HTTP to the server on its private network. Set `hostname` to `0.0.0.0` or `::`, so that the platform can connect. Do not put a TLS proxy in the process in front of `serve`.
+
+For more, use a library for web handlers, for example [srvx](https://srvx.h3.dev): HTTPS in the process, when TLS must reach the server, HTTP/2, middleware, or the same server code on Bun and Deno. Give it the handler. Make sure that the library aborts the signal of a request when the client closes the connection. If it does not, a closed connection does not cancel the call.
+
+### MCP through stdio
+
+An MCP client, for example a coding agent, can start the server as a local process. `mcpStdioMain` serves the standard input and output of the process. The process is one session, with one `context`. The server serves revision `2026-07-28`, and the `initialize` handshake of revisions `2025-11-25` and `2025-06-18`. When the availability of a capability changes, the server sends `notifications/tools/list_changed`. `notifications/cancelled` cancels a call or an `events/stream` request. When standard input ends, the session closes: the calls in progress are cancelled, and each subscription is complete.
+
+```ts
+#!/usr/bin/env node
+import { mcpStdioMain } from "@acid-cat/core-ts";
+
+mcpStdioMain(aircon, { name: "aircon", version: "1.0.0", context: { unit }, toJsonSchema });
+```
+
+Standard output carries only MCP messages. The session writes defects to standard error. Do not write to standard output from a capability. `runMcpStdio(app, options, { input, write })` is the same server on any stream: `input` is an async iterable of bytes or text, for example a `ReadableStream`, and `write` writes one line. It works in all runtimes.
 
 ### Typed calls and handles
 
@@ -116,6 +237,29 @@ power.availability.subscribe(render);
 await power.execute({ on: true });
 ```
 
+### Event handles
+
+`session.eventHandle(event)` gives the event handle of an event (spec/bindings/typescript.md#event-handles), with the types of its schemas. `session.eventHandles` is the map of the event handles by id, for bindings. A handle of the map has the input type `never`: subscribe with `subscribeExternal`, which validates the input.
+
+```ts
+const status = session.eventHandle(statusChanged);
+for await (const occurrence of await status.subscribe({})) {
+  render(occurrence.data); // { on: boolean; celsius: number }
+}
+```
+
+- The promise of `subscribe` resolves when the subscription has started. Before that, it rejects with a `CallFailureError`: `unknown-capability` for an event that the session does not serve, `invalid-input` for an input that does not agree with the schema, and `cancelled` when the session closes or the signal aborts.
+- The result is an async iterator of occurrences: `eventId`, `name`, `timestamp`, `data`, and `cursor` and `truncated` if they are present. `return()` cancels the subscription, also while a `next()` waits: that `next()` resolves with `done: true`. `await using` also cancels it at the end of the block.
+- The options are `signal`, `cursor` and `maxAgeMs`.
+- When the session closes, each subscription is complete. With `internal`, `next()` rejects with a `CallFailureError`, then resolves with `done: true`.
+- A session can hold any number of subscriptions at the same time. To cancel one does not change the others.
+
+A GraphQL server can use an event handle as the source of a subscription. Return the promise of `subscribe` from the `subscribe` resolver of the field. GraphQL calls `return()` when the client ends the subscription, through WebSockets (graphql-ws) or server-sent events (graphql-sse, GraphQL Yoga):
+
+```ts
+subscription: { statusChanged: { subscribe: () => status.subscribe({}), resolve: (occurrence) => occurrence.data } }
+```
+
 ### Context for each request
 
 `mcpHandler` and `httpHandler` take `context` or `createContext`. With `context`, all requests share one context. With `createContext(request)`, the handler makes a new context for each request that passes the screening. Use it when a request must not use objects that an earlier request made, for example on Cloudflare Workers, or when a stateful service must not be shared between callers. When the context has `Symbol.asyncDispose` or `Symbol.dispose`, the handler calls it after the response:
@@ -140,11 +284,20 @@ node cli.ts aircon schedule set --days '[]'                                   #
 node cli.ts list                                                             # the usage of each command
 ```
 
-`list` gives a usage line for each capability. The usage of a repeated flag ends with `...`, for example `--days <mon|tue|wed|thu|fri|sat|sun>... [--hours <integer>...]`. See the [CLI binding](../../spec/bindings/cli.md#commands) for all the rules.
+`list` gives a usage line for each capability, then for each event. Each item has `kind`: `"capability"` or `"event"`. The usage of a repeated flag ends with `...`, for example `--days <mon|tue|wed|thu|fri|sat|sun>... [--hours <integer>...]`. See the [CLI binding](../../spec/bindings/cli.md#commands) for all the rules.
+
+`watch <id>` subscribes to an event. The flags come from the input schema, with the same rules as for a capability. If the input schema has no top-level `properties` member, `watch <id> '<json>'` takes the input as JSON text. Each occurrence goes to standard output as JSON on one line, with its cursor. The exit code is 0 when the subscription is complete, 130 after an interrupt (`SIGINT`), and 5 after `internal`, with `{ "kind", "message" }` on standard error. A failure before the first occurrence has the exit code of a call.
+
+`--cursor <cursor>` and `--max-age-ms <integer>` resume the subscription after a cursor, in the flags form and in the JSON form. A script can keep the last cursor, and resume with it after the program stops. A `--max-age-ms` that is not a whole number exits with 3. These two flags are not properties of the input: if the input schema of an event has a top-level property `cursor` or `max-age-ms`, `runCli` throws when it starts.
+
+```sh
+node cli.ts watch aircon.status.changed
+node cli.ts watch aircon.status.changed --cursor 41 --max-age-ms 300000
+```
 
 ### Commands of the application
 
-The option `commands` of `cliMain` and `runCli` adds commands of the application beside the commands of the capabilities, `call` and `list`. A command has a `name`, a `description` for the help, and `run(args, io)`. `run` gets the arguments after the name of the command, and `io` with `stdout`, `stderr`, `signal` and the `context`. It returns the exit code. The name must not be `call`, `list`, the name of another command of the application, or the first word of the command of a capability. If it is, `runCli` throws. The option `description` gives the text at the top of the help. The default is the description of the application, then its title, then the name of the program.
+The option `commands` of `cliMain` and `runCli` adds commands of the application beside the commands of the capabilities, `call`, `list` and `watch`. A command has a `name`, a `description` for the help, and `run(args, io)`. `run` gets the arguments after the name of the command, and `io` with `stdout`, `stderr`, `signal` and the `context`. It returns the exit code. The name must not be `call`, `list`, `watch`, the name of another command of the application, or the first word of the command of a capability. If it is, `runCli` throws. The option `description` gives the text at the top of the help. The default is the description of the application, then its title, then the name of the program.
 
 ```ts
 import { cliMain } from "@acid-cat/core-ts";
@@ -168,3 +321,4 @@ cliMain(aircon, { name: "aircon", version: "0.1.0", context: { unit }, toJsonSch
 - `moon run core-ts:test` tests sessions, handles and all bindings with a test application, and runs `acid-cat conform` against all bindings. Each test application is in `test/`:
   - [`test/fixture.ts`](test/fixture.ts) has one capability for each behavior that `acid-cat conform` tests.
   - [`test/kettle.ts`](test/kettle.ts) is an electric kettle, simulated in memory. Its tests examine the catalog that the core writes, named types, state, availability, typed handles and the command line.
+  - [`test/sensors.ts`](test/sensors.ts) is a set of temperature sensors, simulated in memory. Its tests examine events through each binding: occurrences, the ends of a subscription, slow clients, cursors, and a GraphQL subscription with graphql-js.

package/dist/app.d.ts

@@ -1,4 +1,4 @@
-import type { Availability, CatalogDocument, JsonObject, Result } from "@acid-cat/spec-ts";
+import type { Availability, CatalogDocument, Emitted, JsonObject, Result } from "@acid-cat/spec-ts";
 import type { StandardSchemaV1 } from "./standard-schema.js";
 /** A value that can change, and that a client can follow (spec/bindings/typescript.md#handles). */
 export interface Observable<T> {
@@ -121,6 +121,76 @@ export interface CapabilityFactory<Context> {
  * ```
  */
 export declare const capabilitiesFor: <Context>() => CapabilityFactory<Context>;
+/**
+ * What `subscribe` receives beside the input: the signal of the subscription, the context, and where the subscription
+ * starts (spec/events.md#resuming). The signal aborts when the subscription ends, in all ways.
+ */
+export interface Subscription<Context> {
+    readonly signal: AbortSignal;
+    readonly context: Context;
+    /** The cursor of the client. With none, the subscription starts now. */
+    readonly cursor?: string | undefined;
+    /** The client wants no occurrence that is older than this number of milliseconds. */
+    readonly maxAgeMs?: number | undefined;
+}
+/**
+ * The function of an event. It gives one value for each occurrence, in order, until the signal aborts or the source
+ * has no more occurrences. Each `data` must agree with the payload schema.
+ */
+export type Subscribe<Context, Input, Payload> = (input: Input, subscription: Subscription<Context>) => AsyncIterable<Emitted<NoInfer<Payload>>>;
+/** The members of an event that do not depend on its input. */
+export interface EventParts<Payload, Id extends string> {
+    readonly id: Id;
+    readonly description: string;
+    /** The targets that can use the event. With no audience, no target can use it. */
+    readonly audience: readonly string[];
+    /** The schema of the `data` of each occurrence: an object schema. With no payload schema, the data is an empty object. */
+    readonly payload?: StandardSchemaV1<unknown, Payload> | undefined;
+}
+/** An event with an input schema. `subscribe` receives the output of the schema. */
+export interface EventWithInput<Context, Input, Payload> {
+    readonly input: StandardSchemaV1<unknown, Input>;
+    readonly subscribe: Subscribe<Context, Input, Payload>;
+}
+/** An event with no input schema. `subscribe` receives an empty object. */
+export interface EventWithoutInput<Context, Payload> {
+    readonly input?: undefined;
+    readonly subscribe: Subscribe<Context, EmptyInput, Payload>;
+}
+/** An event as an application declares it (spec/events.md). `Input` and `Payload` are the outputs of its schemas. */
+export type EventDeclaration<Context, Input, Payload, Id extends string> = EventParts<Payload, Id> & (EventWithInput<Context, Input, Payload> | EventWithoutInput<Context, Payload>);
+/** The result of `decode` of an event: the issues of an input that is not valid, or the start of the subscription. */
+export type DecodedEvent<Context> = {
+    readonly issues: readonly StandardSchemaV1.Issue[];
+} | {
+    readonly start: (subscription: Subscription<Context>) => AsyncIterable<Emitted<unknown>>;
+};
+/** An event that `defineEvent` or `eventsFor` made: its declaration, and `decode`. */
+export type EventDefinition<Context = unknown, Input = EmptyInput, Payload = EmptyInput, Id extends string = string> = EventDeclaration<Context, Input, Payload, Id> & {
+    readonly decode: (input: unknown) => Promise<DecodedEvent<Context>>;
+};
+/** Any event whose services the context `Context` gives, whatever its schemas are. */
+export interface AnyEventDefinition<Context = never> {
+    readonly id: string;
+    readonly description: string;
+    readonly audience: readonly string[];
+    readonly input?: StandardSchemaV1 | undefined;
+    readonly payload?: StandardSchemaV1 | undefined;
+    readonly decode: (input: unknown) => Promise<DecodedEvent<Context>>;
+}
+/**
+ * Declare an event. `Context` is the type of the services that `subscribe` receives. The other types come from the
+ * schemas, and the id keeps its literal type.
+ */
+export declare function defineEvent<Context = unknown, Input = EmptyInput, Payload = EmptyInput, const Id extends string = string>(declaration: EventParts<Payload, Id> & EventWithInput<Context, Input, Payload>): EventDefinition<Context, Input, Payload, Id>;
+export declare function defineEvent<Context = unknown, Payload = EmptyInput, const Id extends string = string>(declaration: EventParts<Payload, Id> & EventWithoutInput<Context, Payload>): EventDefinition<Context, EmptyInput, Payload, Id>;
+/** The function that `eventsFor` gives: `defineEvent`, with one context type. */
+export interface EventFactory<Context> {
+    <Input, Payload = EmptyInput, const Id extends string = string>(declaration: EventParts<Payload, Id> & EventWithInput<Context, Input, Payload>): EventDefinition<Context, Input, Payload, Id>;
+    <Payload = EmptyInput, const Id extends string = string>(declaration: EventParts<Payload, Id> & EventWithoutInput<Context, Payload>): EventDefinition<Context, EmptyInput, Payload, Id>;
+}
+/** Declare events for one context type, as `capabilitiesFor` does for capabilities. */
+export declare const eventsFor: <Context>() => EventFactory<Context>;
 export interface Target {
     readonly bindings: readonly string[];
     readonly description?: string | undefined;
@@ -133,6 +203,8 @@ export interface App<Context = unknown> {
         readonly [name: string]: Target;
     };
     readonly capabilities: readonly AnyCapability<Context>[];
+    /** The events (spec/events.md). Capabilities and events share one set of ids. */
+    readonly events?: readonly AnyEventDefinition<Context>[] | undefined;
 }
 /** Declare an application. */
 export declare const defineApp: <Context = unknown>(app: App<Context>) => App<Context>;

package/dist/app.js

@@ -34,6 +34,27 @@ function decoderOf(declaration) {
 * ```
 */
 const capabilitiesFor = () => defineCapability;
+function defineEvent(declaration) {
+	if (declaration.input === void 0) {
+		const { subscribe } = declaration;
+		return {
+			...declaration,
+			decode: () => Promise.resolve({ start: (subscription) => subscribe({}, subscription) })
+		};
+	}
+	const { input: schema, subscribe } = declaration;
+	return {
+		...declaration,
+		decode: async (input) => {
+			const validated = await schema["~standard"].validate(input);
+			if (validated.issues !== void 0) return { issues: validated.issues };
+			const { value } = validated;
+			return { start: (subscription) => subscribe(value, subscription) };
+		}
+	};
+}
+/** Declare events for one context type, as `capabilitiesFor` does for capabilities. */
+const eventsFor = () => defineEvent;
 /** Declare an application. */
 const defineApp = (app) => app;
 const catalogs = /* @__PURE__ */ new WeakMap();
@@ -80,6 +101,16 @@ function write(app, toJsonSchema) {
 			...capability.state === void 0 ? {} : { state: toJson(capability.state.schema, capability.id) }
 		};
 	}
+	const events = {};
+	for (const event of app.events ?? []) {
+		if (event.id in capabilities || event.id in events) throw new Error(`The id ${event.id} is declared two times.`);
+		events[event.id] = {
+			description: event.description,
+			audience: event.audience,
+			...event.input === void 0 ? {} : { input: objectInput(toJson(event.input, event.id), types) },
+			...event.payload === void 0 ? {} : { payload: objectInput(toJson(event.payload, event.id), types) }
+		};
+	}
 	return {
 		acidcat: "0.1",
 		...app.title === void 0 ? {} : { title: app.title },
@@ -90,10 +121,11 @@ function write(app, toJsonSchema) {
 			...target.options === void 0 ? {} : { options: target.options }
 		}])),
 		...Object.keys(types).length === 0 ? {} : { $defs: types },
-		capabilities
+		capabilities,
+		...Object.keys(events).length === 0 ? {} : { events }
 	};
 }
 /** The catalog of an application, as text in canonical form. */
 const renderCatalog = (app, options) => canonicalText(catalogOf(app, options));
 //#endregion
-export { capabilitiesFor, catalogOf, defineApp, defineCapability, renderCatalog };
+export { capabilitiesFor, catalogOf, defineApp, defineCapability, defineEvent, eventsFor, renderCatalog };

package/dist/cli.d.ts

@@ -11,9 +11,9 @@ export interface CliOptions<Context> {
      */
     readonly description?: string | undefined;
     /**
-     * The commands of the application, beside the commands of the capabilities, `call` and `list`. The name of each one
-     * must not be `call`, `list`, the name of another command of the application, or the first word of the command of a
-     * capability (spec/bindings/cli.md#commands).
+     * The commands of the application, beside the commands of the capabilities, `call`, `list` and `watch`. The name of
+     * each one must not be `call`, `list`, `watch`, the name of another command of the application, or the first word of
+     * the command of a capability (spec/bindings/cli.md#commands).
      */
     readonly commands?: readonly CliCommand<Context>[] | undefined;
 }
@@ -32,7 +32,7 @@ export interface CliCommand<Context> {
         readonly context: Context;
     }): number | Promise<number>;
 }
-/** Run the command line as the main program of the process. An interrupt (`SIGINT`) cancels the call. */
+/** Run the command line as the main program of the process. An interrupt (`SIGINT`) cancels the call or the subscription. */
 export declare function main<Context>(app: App<Context>, options: CliOptions<Context>): void;
 /** Run the command line with arguments. The result is the exit code (spec/bindings/cli.md#outcomes). */
 export declare function runCli<Context>(app: App<Context>, options: CliOptions<Context>, args: readonly string[], io: CliIo): Promise<number>;

package/dist/cli.js

@@ -1,9 +1,15 @@
 import { createSession } from "./session.js";
-import { CLI_EXIT_CODES, bundle, cliExitCode, cliFlags, cliJsonArray, cliRepeatedItems, cliResolve, cliUsage, commandPath, isCallFailure, isJsonObject } from "@acid-cat/spec-ts";
+import { CLI_EXIT_CODES, CLI_RESUME_FLAGS, CLI_WATCH_EXIT_CODES, CallFailureError, bundle, cliEventUsage, cliExitCode, cliFlags, cliJsonArray, cliRepeatedItems, cliResolve, cliUsage, commandPath, isCallFailure, isJsonObject } from "@acid-cat/spec-ts";
 //#region src/cli.ts
 /**
 * The CLI binding (spec/bindings/cli.md): a command line made from the catalog.
 */
+/** The commands of the command line itself. No other command can have their names. */
+const GENERIC_COMMANDS = [
+	"call",
+	"list",
+	"watch"
+];
 var UsageError = class extends Error {
 	exitCode;
 	constructor(message, exitCode) {
@@ -11,7 +17,7 @@ var UsageError = class extends Error {
 		this.exitCode = exitCode;
 	}
 };
-/** Run the command line as the main program of the process. An interrupt (`SIGINT`) cancels the call. */
+/** Run the command line as the main program of the process. An interrupt (`SIGINT`) cancels the call or the subscription. */
 function main(app, options) {
 	const interrupt = new AbortController();
 	process.once("SIGINT", () => interrupt.abort());
@@ -35,30 +41,82 @@ async function runCli(app, options, args, io) {
 		id,
 		path: commandPath(id)
 	}));
-	for (const { path } of commands) if (path[0] === "call" || path[0] === "list") throw new Error(`The command ${path.join(" ")} has the same name as a command of the command line.`);
+	for (const { path } of commands) if (path[0] !== void 0 && GENERIC_COMMANDS.includes(path[0])) throw new Error(`The command ${path.join(" ")} has the same name as a command of the command line.`);
+	for (const [id, event] of Object.entries(session.view.events ?? {})) {
+		const properties = event.input === void 0 ? void 0 : bundle(event.input, types).properties;
+		const taken = CLI_RESUME_FLAGS.find((flag) => isJsonObject(properties) && flag in properties);
+		if (taken !== void 0) throw new Error(`The input of the event ${id} has a property ${taken}, which is a flag of watch.`);
+	}
 	const added = options.commands ?? [];
-	const taken = /* @__PURE__ */ new Set([
-		"call",
-		"list",
-		...commands.flatMap(({ path }) => path.slice(0, 1))
-	]);
+	const taken = /* @__PURE__ */ new Set([...GENERIC_COMMANDS, ...commands.flatMap(({ path }) => path.slice(0, 1))]);
 	for (const command of added) {
 		if (taken.has(command.name)) throw new Error(`The command ${command.name} of the application has the same name as another command.`);
 		taken.add(command.name);
 	}
+	const printFailure = (failure) => io.stderr(JSON.stringify({
+		kind: failure.kind,
+		message: failure.message
+	}));
 	const print = (outcome) => {
-		if (isCallFailure(outcome)) io.stderr(JSON.stringify({
-			kind: outcome.kind,
-			message: outcome.message
-		}));
+		if (isCallFailure(outcome)) printFailure(outcome);
 		else io.stdout(JSON.stringify(outcome.ok ? outcome.value : outcome.error, null, 2));
 		return cliExitCode(outcome);
 	};
+	/** Subscribe to an event, and write each occurrence on one line (spec/bindings/cli.md#events). */
+	const watch = async (rest) => {
+		const [id, ...args] = rest;
+		const { flagArgs, resume } = resumeFlags(args);
+		if (id === void 0) throw new UsageError("Give the id of an event.", CLI_EXIT_CODES["invalid-input"]);
+		const event = session.view.events?.[id];
+		let input = {};
+		if (event !== void 0) {
+			const schema = bundle(event.input ?? { type: "object" }, types);
+			if (flagArgs.includes("--help") || flagArgs.includes("-h")) {
+				io.stdout([
+					`Usage: ${cliEventUsage(options.name, id, event.input === void 0 ? void 0 : schema)}`,
+					"",
+					event.description
+				].join("\n"));
+				return CLI_EXIT_CODES.value;
+			}
+			if (schema.properties !== void 0) input = parseFlags(flagArgs, schema);
+			else {
+				const [text = "{}", extra] = flagArgs;
+				if (extra !== void 0) throw new UsageError(`Unexpected argument ${extra}.`, CLI_EXIT_CODES["invalid-input"]);
+				try {
+					input = JSON.parse(text);
+				} catch {
+					return print({
+						kind: "invalid-input",
+						message: "The input is not JSON."
+					});
+				}
+			}
+		}
+		const subscribed = await session.subscribe(id, input, {
+			signal: io.signal,
+			...resume
+		});
+		if ("kind" in subscribed) return print(subscribed);
+		try {
+			for await (const occurrence of subscribed) io.stdout(JSON.stringify(occurrence));
+		} catch (error) {
+			printFailure(error instanceof CallFailureError ? {
+				kind: error.kind,
+				message: error.message
+			} : {
+				kind: "internal",
+				message: "The event failed."
+			});
+			return CLI_WATCH_EXIT_CODES.internal;
+		}
+		return io.signal?.aborted === true ? CLI_WATCH_EXIT_CODES.cancelled : CLI_WATCH_EXIT_CODES.complete;
+	};
 	try {
 		const [first, ...rest] = args;
 		if (first === void 0 || first === "--help" || first === "-h") {
 			const description = options.description ?? app.description ?? app.title ?? options.name;
-			io.stdout(help(options.name, description, commands.map(({ path }) => path.join(" ")), added));
+			io.stdout(help(options.name, description, commands.map(({ path }) => path.join(" ")), Object.keys(session.view.events ?? {}).length > 0, added));
 			return CLI_EXIT_CODES.value;
 		}
 		if (first === "--version" || first === "-v") {
@@ -66,15 +124,21 @@ async function runCli(app, options, args, io) {
 			return CLI_EXIT_CODES.value;
 		}
 		if (first === "list") {
-			io.stdout(JSON.stringify([...session.handles.values()].map((handle) => {
+			io.stdout(JSON.stringify([...[...session.handles.values()].map((handle) => {
 				const input = viewCapability(session.view, handle.id).input;
 				return {
+					kind: "capability",
 					id: handle.id,
 					description: handle.description,
 					...handle.availability.getSnapshot(),
 					usage: cliUsage(options.name, handle.id, input === void 0 ? void 0 : bundle(input, types))
 				};
-			}), null, 2));
+			}), ...Object.entries(session.view.events ?? {}).map(([id, event]) => ({
+				kind: "event",
+				id,
+				description: event.description,
+				usage: cliEventUsage(options.name, id, event.input === void 0 ? void 0 : bundle(event.input, types))
+			}))], null, 2));
 			return CLI_EXIT_CODES.value;
 		}
 		if (first === "call") {
@@ -91,6 +155,7 @@ async function runCli(app, options, args, io) {
 			}
 			return print(await session.invoke(id, input, { signal: io.signal }));
 		}
+		if (first === "watch") return await watch(rest);
 		const command = added.find(({ name }) => name === first);
 		if (command !== void 0) return await command.run(rest, {
 			...io,
@@ -114,6 +179,35 @@ async function runCli(app, options, args, io) {
 		await session.dispose();
 	}
 }
+/**
+* Take `--cursor` and `--max-age-ms` out of the arguments of `watch` (spec/bindings/cli.md#events). The result is the
+* other arguments, and the cursor and `maxAgeMs` of the subscription.
+*/
+function resumeFlags(args) {
+	const flagArgs = [];
+	const resume = {};
+	const remaining = args.values();
+	for (const arg of remaining) {
+		const [name = "", inline] = arg.startsWith("--") ? arg.slice(2).split(/=(.*)/s, 2) : [];
+		if (name !== "cursor" && name !== "max-age-ms") {
+			flagArgs.push(arg);
+			continue;
+		}
+		const text = inline ?? remaining.next().value;
+		if (text === void 0) throw new UsageError(`The flag --${name} needs a value.`, CLI_EXIT_CODES["invalid-input"]);
+		if (name === "cursor") {
+			resume.cursor = text;
+			continue;
+		}
+		const maxAgeMs = Number(text);
+		if (!/^[0-9]+$/.test(text) || !Number.isSafeInteger(maxAgeMs)) throw new UsageError("The flag --max-age-ms must be a whole number of milliseconds.", CLI_EXIT_CODES["invalid-input"]);
+		resume.maxAgeMs = maxAgeMs;
+	}
+	return {
+		flagArgs,
+		resume
+	};
+}
 /** Make the input from the flags (spec/bindings/cli.md#commands). */
 function parseFlags(args, schema) {
 	const properties = objectOrEmpty(schema.properties);
@@ -174,7 +268,7 @@ function viewCapability(view, id) {
 	if (capability === void 0) throw new Error(`The view of the session has no capability ${id}.`);
 	return capability;
 }
-function help(name, description, paths, added) {
+function help(name, description, paths, hasEvents, added) {
 	return [
 		description,
 		"",
@@ -184,6 +278,7 @@ function help(name, description, paths, added) {
 		...paths.map((path) => `  ${path}`),
 		"  call <id> [input]",
 		"  list",
+		...hasEvents ? ["  watch <id> [flags] [--cursor <string>] [--max-age-ms <integer>]"] : [],
 		...added.map((command) => `  ${command.name}  ${command.description}`)
 	].join("\n");
 }

package/dist/clock.d.ts

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