@acid-cat/core-ts 0.10.2 → 0.11.0

package/README.md

@@ -33,7 +33,7 @@ export const aircon = defineApp<{ unit: Unit }>({
 });
 ```
 
-- `run` gets the input, an `AbortSignal` and the context. It returns `ok(value)` or `fail(failure)`, for example `fail({ _tag: "Offline", since })`. The types check that the value agrees with the output schema, that the failure has a tag of `failures`, and that it has the members of the schema of that tag. If `run` throws, the call fails as `internal`.
+- `run` gets the input, and `{ signal, context, target }`: an `AbortSignal`, the context, and the target of the session, for example `"mcp"` or `"cli"`. It returns `ok(value)` or `fail(failure)`, for example `fail({ _tag: "Offline", since })`. The types check that the value agrees with the output schema, that the failure has a tag of `failures`, and that it has the members of the schema of that tag. If `run` throws, the call fails as `internal`.
 - With an input schema, `run` gets the output of the schema. With none, it gets an empty object.
 - A failure schema describes the whole failure object, with its `_tag`.
 - `availability` is an optional function that returns an observable availability. A session reads it with `getSnapshot` when a call comes in. It subscribes to it only while `onChange` or the handle has listeners.
@@ -66,7 +66,7 @@ export const statusChanged = event({
 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.
+- `subscribe` gets the input, and `{ signal, context, target, cursor, maxAgeMs }`. `target` is the target of the session. 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.
@@ -97,6 +97,7 @@ Standard Schema does not convert to JSON Schema. Give the converter of your sche
 | `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 |
+| `httpClient(url, options)` | [CLI](../../spec/bindings/cli.md#server), [HTTP](../../spec/bindings/http.md) | A client of the HTTP binding of a server, for the option `remote` of the command line |
 | `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) |
 
@@ -115,7 +116,7 @@ The options `bufferLimit` of `createSession`, `httpHandler`, `mcpHandler` and `r
 
 ### 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.
+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 the context that `createContext` made for that request. 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.
 
@@ -273,6 +274,30 @@ const handler = httpHandler(aircon, {
 });
 ```
 
+`createContext` can refuse a request: it gives `refuse(status, message, headers?)` in place of a context. Use it to authenticate the caller, and give the caller to the capabilities in the context:
+
+```ts
+import { httpHandler, refuse } from "@acid-cat/core-ts";
+
+const handler = httpHandler(aircon, {
+  allowedOrigins: [],
+  toJsonSchema,
+  createContext: async (request) => {
+    const caller = await accounts.caller(request.headers.get("Authorization"));
+    if (caller === undefined) return refuse(401, "Give a valid token.", { "WWW-Authenticate": "Bearer" });
+    return { unit, caller };
+  },
+});
+```
+
+- A refusal answers the request with its status, its headers, the media type `application/json`, and the body `{ "message" }`. The handler opens no session. No capability runs, and no subscription starts. The message shows no internal data.
+- The status of a refusal is an integer from 400 to 599. `refuse` throws a `RangeError` for another status.
+- `isRefusal(value)` tells if a value is a refusal that `refuse` made.
+- The handler releases the context after the answer, or when the stream of a subscription ends.
+- Through MCP, a poll lease or a webhook subscription uses the context of the request that started it. The handler calls `createContext` once for each request. It releases the context when the answer is done and each lease and webhook subscription of the request has ended.
+- Set the option `principal` of `mcpHandler` too, from the same caller. A poll lease is keyed by the principal, the event and the input: with no principal, two callers that poll the same event with the same input share one lease, and the second caller reads the occurrences of the session of the first caller.
+- The command line and MCP through stdio have one context for the program.
+
 ### Command line
 
 The command line has one command for each capability in the view of the `cli` target. The words of the id give the path of the command. A shared prefix only contains other commands: if the path of a capability is the start of the path of another capability, for example `aircon.status` and `aircon.status.get`, `runCli` rejects and `cliMain` stops the program with an error when it starts. Each top-level property of the input is a flag with the same name, for example `--celsius 22` or `--celsius=22`. A boolean property is a switch, for example `--on`. A property with an array of strings, numbers or values of a string enum is a repeated flag: each occurrence gives one item, in the order of the flags. A repeated flag that occurs once can also give the whole array as JSON text. Other properties take JSON text. For example, with the command line of the air conditioner, [`examples/aircon/core-ts/cli.ts`](../../examples/aircon/core-ts/cli.ts):
@@ -316,6 +341,27 @@ const report: CliCommand<{ unit: Unit }> = {
 cliMain(aircon, { name: "aircon", version: "0.1.0", context: { unit }, toJsonSchema, description: "Control the air conditioner.", commands: [report] });
 ```
 
+### Command line of a server
+
+The command line can serve a view of an application that runs on a server ([Server](../../spec/bindings/cli.md#server)). Give the option `remote` of `cliMain` and `runCli` a client of the HTTP binding of the server: `httpClient(url, { headers?, fetch? })`. The commands, the flags and the help still come from the view in the program. Each call is `POST {url}/capabilities/{id}`, `list` gets the availability from `GET {url}/capabilities`, and `watch` is `POST {url}/events/{id}`, with the cursor in `Last-Event-ID` and `maxAgeMs` in the query.
+
+- A capability that the server does not list is unavailable in `list`.
+- A server that does not answer is the call failure `unavailable`, with exit code 4. An answer that the HTTP binding does not give is `internal`, with exit code 5.
+- An interrupt (`SIGINT`) closes the request, so the server cancels the call or the subscription. The exit code is 130.
+- The client sends `headers` with each request, for example a token in `Authorization`. The command line never writes them. `httpClient` throws when the URL is not an `http` or `https` URL, when it has a user name, a password, a query or a fragment, and when a header is not valid. The error does not contain the value of a header.
+
+Serve the HTTP binding with the target of the command line, so that both have the same view. [`examples/aircon/core-ts/serve.ts`](../../examples/aircon/core-ts/serve.ts) serves it, and [`examples/aircon/core-ts/cli.ts`](../../examples/aircon/core-ts/cli.ts) sends to it when `AIRCON_URL` is set:
+
+```ts
+// On the server.
+serve({ "/cli": httpHandler(aircon, { allowedOrigins: [], target: "cli", base: "/cli", context: { unit }, toJsonSchema }) }, { hostname: "0.0.0.0", port: 8080 });
+
+// In the command line.
+cliMain(aircon, { name: "aircon", version: "0.1.0", context: { unit: new Unit() }, toJsonSchema, remote: httpClient("http://pi.local:8080/cli", { headers: { Authorization: `Bearer ${token}` } }) });
+```
+
+The client works alone too: `capabilities()`, `invoke(id, input, { signal })` and `subscribe(id, input, { signal, cursor, maxAgeMs })`. No method rejects: each one gives the call failure.
+
 ## Examples and tests
 
 - [`examples/aircon/core-ts`](../../examples/aircon/README.md) is an air conditioner written with this package, with its command line. [`examples/aircon/apis`](../../examples/aircon/README.md#apis) builds GraphQL, Cap'n Web and Elysia APIs on it, each beside the HTTP binding.

package/dist/app.d.ts

@@ -23,10 +23,12 @@ export type FailureOf<Failures> = {
 export type FailureSchemas<Failures> = {
     readonly [Tag in keyof Failures]: StandardSchemaV1<unknown, Failures[Tag]>;
 };
-/** What `run` receives beside the input: the signal of the call, and the context. */
+/** What `run` receives beside the input: the signal of the call, the context, and the target of the session. */
 export interface Call<Context> {
     readonly signal: AbortSignal;
     readonly context: Context;
+    /** The target of the session, for example `"mcp"` or `"cli"`. */
+    readonly target: string;
 }
 /** The function of a capability. Its result has the types of the output schema and of the failure schemas. */
 export type Run<Context, Input, Value, Failures> = (input: Input, call: Call<Context>) => Promise<Result<NoInfer<Value>, NoInfer<FailureOf<Failures>>>> | Result<NoInfer<Value>, NoInfer<FailureOf<Failures>>>;
@@ -122,12 +124,15 @@ 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.
+ * What `subscribe` receives beside the input: the signal of the subscription, the context, the target of the session,
+ * 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 target of the session, for example `"mcp"` or `"cli"`. */
+    readonly target: string;
     /** 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. */

package/dist/cli.d.ts

@@ -1,4 +1,5 @@
 import type { App, ToJsonSchema } from "./app.js";
+import type { HttpClient } from "./http-client.js";
 export interface CliOptions<Context> {
     readonly name: string;
     readonly version: string;
@@ -16,6 +17,13 @@ export interface CliOptions<Context> {
      * the command of a capability (spec/bindings/cli.md#commands).
      */
     readonly commands?: readonly CliCommand<Context>[] | undefined;
+    /**
+     * The HTTP binding of the application in another process or on another machine (spec/bindings/cli.md#server). With
+     * it, the command line sends each call, the availability of `list` and each subscription of `watch` to that server.
+     * The commands still come from the view of `target` in this program. Serve the HTTP binding with the same target, for
+     * example `httpHandler(app, { target: "cli", … })`. The commands of the application still get `context`.
+     */
+    readonly remote?: HttpClient | undefined;
 }
 export interface CliIo {
     readonly stdout: (text: string) => void;
@@ -32,7 +40,10 @@ 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 or the subscription. */
-export declare function main<Context>(app: App<Context>, options: CliOptions<Context>): void;
+/**
+ * Run the command line as the main program of the process. An interrupt (`SIGINT`) cancels the call or the subscription.
+ * The default arguments are the arguments of the process.
+ */
+export declare function main<Context>(app: App<Context>, options: CliOptions<Context>, args?: readonly string[]): 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,40 @@
+import { catalogOf } from "./app.js";
 import { createSession } from "./session.js";
-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";
+import { CLI_EXIT_CODES, CLI_RESUME_FLAGS, CLI_WATCH_EXIT_CODES, CallFailureError, bundle, cliEventUsage, cliExitCode, cliFlags, cliJsonArray, cliRepeatedItems, cliResolve, cliUsage, commandPath, isCallFailure, isJsonObject, unavailable, viewOf } from "@acid-cat/spec-ts";
 // src/cli.ts
 /**
 * The CLI binding (spec/bindings/cli.md): a command line made from the catalog.
 */
+function localProvider(app, options) {
+	const session = createSession(app, {
+		target: options.target ?? "cli",
+		context: options.context,
+		toJsonSchema: options.toJsonSchema
+	});
+	return {
+		get view() {
+			return session.view;
+		},
+		availability: async () => new Map([...session.handles.values()].map((handle) => [handle.id, handle.availability.getSnapshot()])),
+		invoke: (id, input, signal) => session.invoke(id, input, { signal }),
+		subscribe: (id, input, subscribeOptions) => session.subscribe(id, input, subscribeOptions),
+		dispose: () => session.dispose()
+	};
+}
+function remoteProvider(app, options, client) {
+	const view = viewOf(catalogOf(app, { toJsonSchema: options.toJsonSchema }), options.target ?? "cli");
+	return {
+		view,
+		availability: async (signal) => {
+			const served = await client.capabilities({ signal });
+			if ("kind" in served) return served;
+			return new Map(Object.keys(view.capabilities).map((id) => [id, served.get(id) ?? unavailable("The server does not serve this capability.")]));
+		},
+		invoke: (id, input, signal) => client.invoke(id, input, { signal }),
+		subscribe: (id, input, subscribeOptions) => client.subscribe(id, input, subscribeOptions),
+		dispose: async () => void 0
+	};
+}
 /** The commands of the command line itself. No other command can have their names. */
 const GENERIC_COMMANDS = [
 	"call",
@@ -17,11 +48,14 @@ 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 or the subscription. */
-function main(app, options) {
+/**
+* Run the command line as the main program of the process. An interrupt (`SIGINT`) cancels the call or the subscription.
+* The default arguments are the arguments of the process.
+*/
+function main(app, options, args = process.argv.slice(2)) {
 	const interrupt = new AbortController();
 	process.once("SIGINT", () => interrupt.abort());
-	runCli(app, options, process.argv.slice(2), {
+	runCli(app, options, args, {
 		stdout: (text) => process.stdout.write(`${text}\n`),
 		stderr: (text) => process.stderr.write(`${text}\n`),
 		signal: interrupt.signal
@@ -31,13 +65,10 @@ function main(app, options) {
 }
 /** Run the command line with arguments. The result is the exit code (spec/bindings/cli.md#outcomes). */
 async function runCli(app, options, args, io) {
-	const session = createSession(app, {
-		target: options.target ?? "cli",
-		context: options.context,
-		toJsonSchema: options.toJsonSchema
-	});
-	const types = session.view.$defs ?? {};
-	const commands = Object.keys(session.view.capabilities).map((id) => ({
+	const provider = options.remote === void 0 ? localProvider(app, options) : remoteProvider(app, options, options.remote);
+	const view = provider.view;
+	const types = view.$defs ?? {};
+	const commands = Object.keys(view.capabilities).map((id) => ({
 		id,
 		path: commandPath(id)
 	}));
@@ -46,7 +77,7 @@ async function runCli(app, options, args, io) {
 		const longer = commands.find((other) => other.path.length > path.length && path.every((word, index) => other.path[index] === word));
 		if (longer !== void 0) throw new Error(`The command ${path.join(" ")} is also the start of the command ${longer.path.join(" ")}. A shared prefix only contains other commands.`);
 	}
-	for (const [id, event] of Object.entries(session.view.events ?? {})) {
+	for (const [id, event] of Object.entries(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.`);
@@ -71,7 +102,7 @@ async function runCli(app, options, args, io) {
 		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];
+		const event = view.events?.[id];
 		let input = {};
 		if (event !== void 0) {
 			const schema = bundle(event.input ?? { type: "object" }, types);
@@ -97,7 +128,7 @@ async function runCli(app, options, args, io) {
 				}
 			}
 		}
-		const subscribed = await session.subscribe(id, input, {
+		const subscribed = await provider.subscribe(id, input, {
 			signal: io.signal,
 			...resume
 		});
@@ -120,7 +151,7 @@ async function runCli(app, options, args, io) {
 		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(" ")), Object.keys(session.view.events ?? {}).length > 0, added));
+			io.stdout(help(options.name, description, commands.map(({ path }) => path.join(" ")), Object.keys(view.events ?? {}).length > 0, added));
 			return CLI_EXIT_CODES.value;
 		}
 		if (first === "--version" || first === "-v") {
@@ -128,16 +159,15 @@ async function runCli(app, options, args, io) {
 			return CLI_EXIT_CODES.value;
 		}
 		if (first === "list") {
-			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))
-				};
-			}), ...Object.entries(session.view.events ?? {}).map(([id, event]) => ({
+			const availability = await provider.availability(io.signal);
+			if ("kind" in availability) return print(availability);
+			io.stdout(JSON.stringify([...Object.entries(view.capabilities).map(([id, capability]) => ({
+				kind: "capability",
+				id,
+				description: capability.description,
+				...availability.get(id) ?? unavailable("There is no such capability."),
+				usage: cliUsage(options.name, id, capability.input === void 0 ? void 0 : bundle(capability.input, types))
+			})), ...Object.entries(view.events ?? {}).map(([id, event]) => ({
 				kind: "event",
 				id,
 				description: event.description,
@@ -152,12 +182,23 @@ async function runCli(app, options, args, io) {
 			try {
 				input = JSON.parse(text);
 			} catch {
+				if (provider.view.capabilities[id] === void 0) return print({
+					kind: "unknown-capability",
+					message: `There is no capability ${id}.`
+				});
+				const availability = await provider.availability(io.signal);
+				if ("kind" in availability) return print(availability);
+				const state = availability.get(id);
+				if (state !== void 0 && !state.available) return print({
+					kind: "unavailable",
+					message: state.reason
+				});
 				return print({
 					kind: "invalid-input",
 					message: "The input is not JSON."
 				});
 			}
-			return print(await session.invoke(id, input, { signal: io.signal }));
+			return print(await provider.invoke(id, input, io.signal));
 		}
 		if (first === "watch") return await watch(rest);
 		const command = added.find(({ name }) => name === first);
@@ -167,20 +208,20 @@ async function runCli(app, options, args, io) {
 		});
 		const match = commands.filter(({ path }) => path.every((word, index) => args[index] === word)).sort((a, b) => b.path.length - a.path.length)[0];
 		if (match === void 0) throw new UsageError(`There is no command ${args.filter((arg) => !arg.startsWith("-")).join(" ")}.`, CLI_EXIT_CODES["unknown-capability"]);
-		const capability = viewCapability(session.view, match.id);
+		const capability = viewCapability(view, match.id);
 		const schema = bundle(capability.input ?? { type: "object" }, types);
 		const flagArgs = args.slice(match.path.length);
 		if (flagArgs.includes("--help") || flagArgs.includes("-h")) {
 			io.stdout(usage(options.name, match.path, capability.description, schema));
 			return CLI_EXIT_CODES.value;
 		}
-		return print(await session.invoke(match.id, parseFlags(flagArgs, schema), { signal: io.signal }));
+		return print(await provider.invoke(match.id, parseFlags(flagArgs, schema), io.signal));
 	} catch (error) {
 		if (!(error instanceof UsageError)) throw error;
 		io.stderr(error.message);
 		return error.exitCode;
 	} finally {
-		await session.dispose();
+		await provider.dispose();
 	}
 }
 /**

package/dist/context.d.ts

@@ -1,5 +1,6 @@
 /**
- * The context of the web handlers: one context that all requests share, or a new context for each request.
+ * The context of the web handlers: one context that all requests share, or a new context for each request. The
+ * function that makes the context of a request can refuse the request (spec/bindings/README.md#remote-bindings).
  */
 export type ContextOption<Context> = {
     /** The context of all requests. */
@@ -9,18 +10,45 @@ export type ContextOption<Context> = {
     /**
      * Make the context of one request. The handler calls it for each request that passes the screening. When the
      * context has `Symbol.asyncDispose` or `Symbol.dispose`, the handler calls it after the response, as a `using`
-     * declaration does.
+     * declaration does. Through MCP, a poll lease or a webhook subscription that the request starts keeps the context:
+     * the handler calls it when the last of them ends. Give a `Refusal` from `refuse` to answer the request with no session: for example `401` when
+     * the request has no valid token.
      */
-    readonly createContext: (request: Request) => Context | Promise<Context>;
+    readonly createContext: (request: Request) => Context | Refusal | Promise<Context | Refusal>;
     readonly context?: undefined;
 };
-/** Give the context of one request to `use`, and release it afterwards if the handler made it. */
-export declare function withContext<Context, A>(option: ContextOption<Context>, request: Request, use: (context: Context) => Promise<A>): Promise<A>;
+/** The key that marks a refusal. A context cannot have it by accident. */
+declare const refusalKey: unique symbol;
+/** The answer that refuses a request before the handler opens a session. `refuse` makes it. */
+export interface Refusal {
+    readonly [refusalKey]: true;
+    /** The status of the answer, for example `401` or `403`. */
+    readonly status: number;
+    /** The text of the answer, in its JSON body `{ "message" }`. Show no internal data. */
+    readonly message: string;
+    /** The other headers of the answer, for example `WWW-Authenticate`. */
+    readonly headers: Headers;
+}
 /**
- * The context of one request, and the function that releases it if the handler made it. A response with a stream, such
- * as the stream of a subscription, releases the context when the stream ends.
+ * Refuse a request: `createContext` gives the result instead of a context. The handler answers with `status`, the media
+ * type `application/json`, the body `{ "message": message }`, and `headers`. No capability runs, and no subscription
+ * starts. `status` must be an integer from 400 to 599: an other value throws a `RangeError`.
  */
-export declare function openContext<Context>(option: ContextOption<Context>, request: Request): Promise<{
+export declare function refuse(status: number, message: string, headers?: HeadersInit): Refusal;
+/** Tell if a value is a refusal that `refuse` made. */
+export declare function isRefusal(value: unknown): value is Refusal;
+/** The answer of a refused request. */
+export declare function refusalResponse(refusal: Refusal): Response;
+/** The context of one request, and the function that releases it if the handler made it. */
+export interface OpenedContext<Context> {
     readonly context: Context;
     readonly release: () => Promise<void>;
+}
+/**
+ * The context of one request, or the refusal of the request. A response with a stream, such as the stream of a
+ * subscription, releases the context when the stream ends.
+ */
+export declare function openContext<Context>(option: ContextOption<Context>, request: Request): Promise<OpenedContext<Context> | {
+    readonly refusal: Refusal;
 }>;
+export {};

package/dist/context.js

@@ -1,17 +1,47 @@
 // src/context.ts
+/** The key that marks a refusal. A context cannot have it by accident. */
+const refusalKey = Symbol("acid-cat.refusal");
 /**
-* The context of one request, and the function that releases it if the handler made it. A response with a stream, such
-* as the stream of a subscription, releases the context when the stream ends.
+* Refuse a request: `createContext` gives the result instead of a context. The handler answers with `status`, the media
+* type `application/json`, the body `{ "message": message }`, and `headers`. No capability runs, and no subscription
+* starts. `status` must be an integer from 400 to 599: an other value throws a `RangeError`.
+*/
+function refuse(status, message, headers) {
+	if (!Number.isInteger(status) || status < 400 || status > 599) throw new RangeError(`The status of a refusal must be an integer from 400 to 599, not ${status}.`);
+	return {
+		[refusalKey]: true,
+		status,
+		message,
+		headers: new Headers(headers)
+	};
+}
+/** Tell if a value is a refusal that `refuse` made. */
+function isRefusal(value) {
+	return typeof value === "object" && value !== null && refusalKey in value && value[refusalKey] === true && "status" in value && typeof value.status === "number" && "message" in value && typeof value.message === "string" && "headers" in value && value.headers instanceof Headers;
+}
+/** The answer of a refused request. */
+function refusalResponse(refusal) {
+	const headers = new Headers(refusal.headers);
+	headers.set("Content-Type", "application/json");
+	return new Response(JSON.stringify({ message: refusal.message }), {
+		status: refusal.status,
+		headers
+	});
+}
+/**
+* The context of one request, or the refusal of the request. A response with a stream, such as the stream of a
+* subscription, releases the context when the stream ends.
 */
 async function openContext(option, request) {
 	if (option.createContext === void 0) return {
 		context: option.context,
 		release: () => Promise.resolve()
 	};
-	const context = await option.createContext(request);
+	const made = await option.createContext(request);
+	if (isRefusal(made)) return { refusal: made };
 	return {
-		context,
-		release: () => release(context)
+		context: made,
+		release: () => release(made)
 	};
 }
 /** Call `Symbol.asyncDispose` or `Symbol.dispose` of a value, if it has one. */
@@ -24,4 +54,4 @@ async function release(value) {
 }
 /** Tell if a value is a function. A function can take any arguments, and its result is not known. */
 const isFunction = (value) => typeof value === "function";
-export { openContext };
+export { isRefusal, openContext, refusalResponse, refuse };

package/dist/http-client.d.ts

@@ -0,0 +1,62 @@
+import type { Availability, CallFailure, Occurrence, Outcome } from "@acid-cat/spec-ts";
+export interface HttpClientOptions {
+    /**
+     * The headers to send with each request, for example `{ Authorization: "Bearer …" }`. The client never writes them in
+     * a message or an error.
+     */
+    readonly headers?: Readonly<Record<string, string>> | undefined;
+    /** The function that sends the requests. The default is the global `fetch`. */
+    readonly fetch?: typeof fetch | undefined;
+}
+export interface HttpSubscribeOptions {
+    /** Abort to close the request. The server then cancels the subscription, and the occurrences end. */
+    readonly signal?: AbortSignal | undefined;
+    /** The cursor to resume after, sent as `Last-Event-ID`. */
+    readonly cursor?: string | undefined;
+    /** The oldest occurrence to replay, in milliseconds, sent as the query parameter `maxAgeMs`. */
+    readonly maxAgeMs?: number | undefined;
+}
+/**
+ * A client of an HTTP binding at a base URL. No method rejects: a server that does not answer is the call failure
+ * `unavailable`, an answer that the HTTP binding does not give is `internal`, and an abort is `cancelled`.
+ */
+export interface HttpClient {
+    /** The base URL, without its last `/`. */
+    readonly base: string;
+    /** The capabilities of the view of the server, by id, with their availability: `GET {base}/capabilities`. */
+    capabilities(options?: {
+        readonly signal?: AbortSignal | undefined;
+    }): Promise<ReadonlyMap<string, Availability> | CallFailure>;
+    /** Call a capability: `POST {base}/capabilities/{id}`. Abort the signal to close the request: the server then cancels the call. */
+    invoke(id: string, input: unknown, options?: {
+        readonly signal?: AbortSignal | undefined;
+    }): Promise<Outcome<unknown, unknown>>;
+    /**
+     * Subscribe to an event: `POST {base}/events/{id}`. The result is the occurrences, or the call failure before the first
+     * occurrence. The occurrences reject with a `CallFailureError` when the subscription ends with a call failure, and end
+     * with no error when the signal aborts.
+     */
+    subscribe(id: string, input: unknown, options?: HttpSubscribeOptions): Promise<AsyncIterable<Occurrence> | CallFailure>;
+}
+/**
+ * A client of the HTTP binding at `url`, an `http` or `https` URL, for example `http://pi.local:8080/cli`. It throws
+ * when the URL or a header is not valid. The error does not contain the value of a header.
+ */
+export declare function httpClient(url: string, options?: HttpClientOptions): HttpClient;
+/** A message of a stream of server-sent events. */
+interface Message {
+    readonly event: string;
+    readonly data: string;
+}
+/**
+ * The parser of a stream of server-sent events (https://html.spec.whatwg.org/multipage/server-sent-events.html): lines
+ * end with CRLF, LF or CR, a line that starts with `:` is a comment, and a blank line ends a message. It reads the
+ * fields `event` and `data`, and ignores the others, also `id`: the cursor of an occurrence is in its data. It gives a
+ * message with no data only when its event is `complete`.
+ */
+export declare class SseParser {
+    #private;
+    /** Give the next text of the stream. The result is the messages that it ends. */
+    push(text: string): Message[];
+}
+export {};

package/dist/http-client.js

@@ -0,0 +1,265 @@
+import { AVAILABLE, CALL_FAILURE_KINDS, CallFailureError, SSE_MEDIA_TYPE, callFailure, isJsonObject, isOccurrence, unavailable } from "@acid-cat/spec-ts";
+// src/http-client.ts
+/**
+* A client of the HTTP binding (spec/bindings/http.md). The command line uses it to call the capabilities and follow
+* the events of an application that runs in another process or on another machine (spec/bindings/cli.md#server).
+*/
+/** The largest answer that the client reads, in bytes. */
+const MAXIMUM_ANSWER = 67108864;
+/**
+* A client of the HTTP binding at `url`, an `http` or `https` URL, for example `http://pi.local:8080/cli`. It throws
+* when the URL or a header is not valid. The error does not contain the value of a header.
+*/
+function httpClient(url, options = {}) {
+	let parsed;
+	try {
+		parsed = new URL(url);
+	} catch {
+		throw new Error("The URL of the server is not a URL.");
+	}
+	if (parsed.protocol !== "http:" && parsed.protocol !== "https:") throw new Error("The URL of the server is not an http or https URL.");
+	if (parsed.search !== "" || parsed.hash !== "") throw new Error("The URL of the server must not have a query or a fragment.");
+	if (parsed.username !== "" || parsed.password !== "") throw new Error("The URL of the server must not have a user name or a password. Give them in a header.");
+	const base = `${parsed.origin}${parsed.pathname}`.replace(/\/+$/, "");
+	const headers = new Headers();
+	for (const [name, value] of Object.entries(options.headers ?? {})) try {
+		headers.append(name, value);
+	} catch {
+		throw new Error(`The header ${/^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/.test(name) ? name : "with that name"} is not valid.`);
+	}
+	const send = options.fetch ?? fetch;
+	const notAnswering = () => callFailure("unavailable", `The server at ${base} does not answer.`);
+	/** Send a request. The result is the response, or the call failure when the server does not answer or the signal aborts. */
+	async function request(method, path, init) {
+		if (aborted(init.signal)) return cancelled();
+		const requestHeaders = new Headers(headers);
+		requestHeaders.set("Accept", "application/json, text/event-stream");
+		if (init.lastEventId !== void 0) try {
+			requestHeaders.set("Last-Event-ID", init.lastEventId);
+		} catch {
+			return callFailure("invalid-input", "The cursor cannot be sent in the header Last-Event-ID.");
+		}
+		let body;
+		if (method === "POST") {
+			requestHeaders.set("Content-Type", "application/json");
+			body = JSON.stringify(init.body ?? {});
+		}
+		try {
+			return await send(`${base}${path}`, {
+				method,
+				headers: requestHeaders,
+				...body === void 0 ? {} : { body },
+				...init.signal === void 0 ? {} : { signal: init.signal }
+			});
+		} catch {
+			return aborted(init.signal) ? cancelled() : notAnswering();
+		}
+	}
+	/** The status and the JSON body of an answer, or the call failure when it is not JSON. */
+	async function read(response, signal) {
+		const text = await boundedText(response, signal);
+		if (typeof text !== "string") return text;
+		try {
+			return {
+				status: response.status,
+				body: JSON.parse(text)
+			};
+		} catch {
+			return notAnAnswer();
+		}
+	}
+	return {
+		base,
+		async capabilities(callOptions = {}) {
+			const response = await request("GET", "/capabilities", { signal: callOptions.signal });
+			if (!(response instanceof Response)) return response;
+			const answer = await read(response, callOptions.signal);
+			if (!("status" in answer)) return answer;
+			if (answer.status !== 200) return failureOf(answer.body);
+			if (!Array.isArray(answer.body)) return notAnAnswer();
+			const served = /* @__PURE__ */ new Map();
+			for (const item of answer.body) {
+				const entry = availabilityEntry(item);
+				if (entry === void 0) return notAnAnswer();
+				served.set(entry.id, entry.availability);
+			}
+			return served;
+		},
+		async invoke(id, input, callOptions = {}) {
+			const response = await request("POST", `/capabilities/${encodeURIComponent(id)}`, {
+				body: input,
+				signal: callOptions.signal
+			});
+			if (!(response instanceof Response)) return response;
+			const answer = await read(response, callOptions.signal);
+			if (!("status" in answer)) return answer;
+			if (answer.status !== 200) return failureOf(answer.body);
+			const { body } = answer;
+			if (isJsonObject(body) && body.ok === true && "value" in body) return {
+				ok: true,
+				value: body.value
+			};
+			if (isJsonObject(body) && body.ok === false && "error" in body) return {
+				ok: false,
+				error: body.error
+			};
+			return notAnAnswer();
+		},
+		async subscribe(id, input, subscribeOptions = {}) {
+			const query = subscribeOptions.maxAgeMs === void 0 ? "" : `?maxAgeMs=${encodeURIComponent(String(subscribeOptions.maxAgeMs))}`;
+			const response = await request("POST", `/events/${encodeURIComponent(id)}${query}`, {
+				body: input,
+				signal: subscribeOptions.signal,
+				lastEventId: subscribeOptions.cursor
+			});
+			if (!(response instanceof Response)) return response;
+			if (response.status !== 200) {
+				const answer = await read(response, subscribeOptions.signal);
+				return "status" in answer ? failureOf(answer.body) : answer;
+			}
+			if ((response.headers.get("Content-Type") ?? "").split(";")[0]?.trim().toLowerCase() !== SSE_MEDIA_TYPE || response.body === null) {
+				await response.body?.cancel().catch(() => void 0);
+				return notAnAnswer();
+			}
+			return occurrencesOf(response.body, subscribeOptions.signal);
+		}
+	};
+}
+/** True if the signal aborted. A function, so that TypeScript does not keep a test of the signal from before an await. */
+const aborted = (signal) => signal?.aborted === true;
+const cancelled = () => callFailure("cancelled", "The call was cancelled.");
+const notAnAnswer = () => callFailure("internal", "The server gave an answer that the HTTP binding does not give.");
+const broken = () => callFailure("internal", "The connection to the server broke.");
+const isCallFailureKind = (value) => CALL_FAILURE_KINDS.some((kind) => kind === value);
+/** The call failure in the body of an answer, or `internal` when the body is not a call failure. */
+function failureOf(body) {
+	if (isJsonObject(body) && isCallFailureKind(body.kind) && typeof body.message === "string") return callFailure(body.kind, body.message);
+	return notAnAnswer();
+}
+/** One item of `GET {base}/capabilities`, or `undefined` when it is not one. */
+function availabilityEntry(item) {
+	if (!isJsonObject(item) || typeof item.id !== "string") return void 0;
+	if (item.available === true) return {
+		id: item.id,
+		availability: AVAILABLE
+	};
+	if (item.available === false && typeof item.reason === "string") return {
+		id: item.id,
+		availability: unavailable(item.reason)
+	};
+}
+/** The text of a body, at most `MAXIMUM_ANSWER` bytes, or the call failure when it cannot be read. */
+async function boundedText(response, signal) {
+	if (response.body === null) return "";
+	const reader = response.body.getReader();
+	const decoder = new TextDecoder();
+	let text = "";
+	let size = 0;
+	try {
+		for (;;) {
+			const chunk = await reader.read();
+			if (chunk.done) return text + decoder.decode();
+			size += chunk.value.byteLength;
+			if (size > MAXIMUM_ANSWER) {
+				await reader.cancel().catch(() => void 0);
+				return notAnAnswer();
+			}
+			text += decoder.decode(chunk.value, { stream: true });
+		}
+	} catch {
+		return aborted(signal) ? cancelled() : broken();
+	}
+}
+/**
+* The parser of a stream of server-sent events (https://html.spec.whatwg.org/multipage/server-sent-events.html): lines
+* end with CRLF, LF or CR, a line that starts with `:` is a comment, and a blank line ends a message. It reads the
+* fields `event` and `data`, and ignores the others, also `id`: the cursor of an occurrence is in its data. It gives a
+* message with no data only when its event is `complete`.
+*/
+var SseParser = class {
+	#buffer = "";
+	#event = "";
+	#data = [];
+	#started = false;
+	/** Give the next text of the stream. The result is the messages that it ends. */
+	push(text) {
+		this.#buffer += text;
+		if (!this.#started && this.#buffer.length > 0) {
+			this.#started = true;
+			if (this.#buffer.startsWith("")) this.#buffer = this.#buffer.slice(1);
+		}
+		const messages = [];
+		for (;;) {
+			const end = this.#buffer.search(/\r\n|\n|\r/);
+			if (end < 0) break;
+			if (this.#buffer[end] === "\r" && end === this.#buffer.length - 1) break;
+			const line = this.#buffer.slice(0, end);
+			this.#buffer = this.#buffer.slice(end + (this.#buffer.startsWith("\r\n", end) ? 2 : 1));
+			const message = this.#line(line);
+			if (message !== void 0) messages.push(message);
+		}
+		return messages;
+	}
+	#line(line) {
+		if (line === "") {
+			const message = {
+				event: this.#event === "" ? "message" : this.#event,
+				data: this.#data.join("\n")
+			};
+			const empty = this.#data.length === 0;
+			this.#event = "";
+			this.#data = [];
+			return empty && message.event !== "complete" ? void 0 : message;
+		}
+		if (line.startsWith(":")) return void 0;
+		const colon = line.indexOf(":");
+		const field = colon < 0 ? line : line.slice(0, colon);
+		const raw = colon < 0 ? "" : line.slice(colon + 1);
+		const value = raw.startsWith(" ") ? raw.slice(1) : raw;
+		if (field === "event") this.#event = value;
+		else if (field === "data") this.#data.push(value);
+	}
+};
+/** Parse JSON text, or give `undefined` when it is not JSON. */
+function parseJson(text) {
+	try {
+		return { value: JSON.parse(text) };
+	} catch {
+		return;
+	}
+}
+/**
+* The occurrences of a stream of server-sent events of the HTTP binding. `next` is an occurrence, `complete` the end,
+* and `error` the end with its call failure. A stream that ends with no `complete` or `error` is `internal`.
+*/
+async function* occurrencesOf(body, signal) {
+	const reader = body.getReader();
+	const decoder = new TextDecoder();
+	const parser = new SseParser();
+	try {
+		for (;;) {
+			let chunk;
+			try {
+				chunk = await reader.read();
+			} catch {
+				if (aborted(signal)) return;
+				throw new CallFailureError(broken());
+			}
+			if (chunk.done) {
+				if (aborted(signal)) return;
+				throw new CallFailureError(broken());
+			}
+			for (const message of parser.push(decoder.decode(chunk.value, { stream: true }))) {
+				const data = parseJson(message.data);
+				if (message.event === "next") {
+					if (data === void 0 || !isOccurrence(data.value)) throw new CallFailureError(notAnAnswer());
+					yield data.value;
+				} else if (message.event === "complete") return;
+				else if (message.event === "error") throw new CallFailureError(data === void 0 ? notAnAnswer() : failureOf(data.value));
+			}
+		}
+	} finally {
+		await reader.cancel().catch(() => void 0);
+	}
+}
+export { SseParser, httpClient };

package/dist/http.d.ts

@@ -19,5 +19,8 @@ export interface HttpSettings {
     /** The number of occurrences that each subscription keeps for a client that reads slowly. The default is 256. */
     readonly bufferLimit?: number | undefined;
 }
-/** A web request handler for the API. Each request has its own session, and with `createContext` its own context. */
+/**
+ * A web request handler for the API. Each request has its own session, and with `createContext` its own context.
+ * `createContext` can refuse a request: then the handler answers with the refusal, and opens no session.
+ */
 export declare function httpHandler<Context>(app: App<Context>, options: HttpOptions<Context>): (request: Request) => Promise<Response>;

package/dist/http.js

@@ -1,4 +1,4 @@
-import { openContext } from "./context.js";
+import { openContext, refusalResponse } from "./context.js";
 import { createSession } from "./session.js";
 import { idlePuller, textStream } from "./stream.js";
 import { CallFailureError, KEEPALIVE_MS, SSE_MEDIA_TYPE, callFailure, httpEventMessage, httpStatus, isCallFailure, readBounded, screenRequest } from "@acid-cat/spec-ts";
@@ -6,7 +6,10 @@ import { CallFailureError, KEEPALIVE_MS, SSE_MEDIA_TYPE, callFailure, httpEventM
 /**
 * The HTTP binding (spec/bindings/http.md): JSON through HTTP.
 */
-/** A web request handler for the API. Each request has its own session, and with `createContext` its own context. */
+/**
+* A web request handler for the API. Each request has its own session, and with `createContext` its own context.
+* `createContext` can refuse a request: then the handler answers with the refusal, and opens no session.
+*/
 function httpHandler(app, options) {
 	const maximumBytes = options.maximumBytes ?? 1048576;
 	return async (request) => {
@@ -22,6 +25,7 @@ function httpHandler(app, options) {
 		const url = new URL(request.url);
 		const path = url.pathname.slice((options.base ?? "").length);
 		const opened = await openContext(options, request);
+		if ("refusal" in opened) return refusalResponse(opened.refusal);
 		const session = createSession(app, {
 			target: options.target ?? "api",
 			context: opened.context,

package/dist/index.d.ts

@@ -16,9 +16,12 @@ export { main as mcpStdioMain, runMcpStdio } from "./mcp-stdio.js";
 export type { McpStdioIo, McpStdioOptions } from "./mcp-stdio.js";
 export { httpHandler } from "./http.js";
 export type { HttpOptions, HttpSettings } from "./http.js";
-export type { ContextOption } from "./context.js";
+export { isRefusal, refuse } from "./context.js";
+export type { ContextOption, Refusal } from "./context.js";
 export { main as cliMain, runCli } from "./cli.js";
 export type { CliCommand, CliIo, CliOptions } from "./cli.js";
+export { httpClient } from "./http-client.js";
+export type { HttpClient, HttpClientOptions, HttpSubscribeOptions } from "./http-client.js";
 export { findHost, installWebMcp } from "./webmcp.js";
 export type { Installation, ModelContext, ModelContextTool, Phase, Status } from "./webmcp.js";
 export type { StandardSchemaV1 } from "./standard-schema.js";

package/dist/index.js

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

package/dist/mcp.d.ts

@@ -53,8 +53,10 @@ export interface McpHandler {
 }
 /**
  * A web request handler for the MCP server. Each request has its own session, and with `createContext` its own
- * context. Each poll lease and each webhook subscription also has its own session, opened with the context of the
- * request that started it.
+ * context. `createContext` can refuse a request: then the handler answers with the refusal, and opens no session.
+ * Each poll lease and each webhook subscription also has its own session, with the context of the request that
+ * started it. The handler releases that context when the answer is done and each of those leases and subscriptions
+ * has ended.
  */
 export declare function mcpHandler<Context>(app: App<Context>, options: McpOptions<Context>): McpHandler;
 /** The tools of the available capabilities in the view of a session (spec/bindings/mcp.md#tools). */

package/dist/mcp.js

@@ -1,4 +1,4 @@
-import { openContext } from "./context.js";
+import { openContext, refusalResponse } from "./context.js";
 import { eventCapabilities, forbidden, listEvents, servesEvents, startEventStream, unsupportedWebhook } from "./mcp-events.js";
 import { PollLeases } from "./mcp-poll.js";
 import { createSession } from "./session.js";
@@ -28,8 +28,10 @@ function readRequest(body) {
 }
 /**
 * A web request handler for the MCP server. Each request has its own session, and with `createContext` its own
-* context. Each poll lease and each webhook subscription also has its own session, opened with the context of the
-* request that started it.
+* context. `createContext` can refuse a request: then the handler answers with the refusal, and opens no session.
+* Each poll lease and each webhook subscription also has its own session, with the context of the request that
+* started it. The handler releases that context when the answer is done and each of those leases and subscriptions
+* has ended.
 */
 function mcpHandler(app, options) {
 	const maximumBytes = options.maximumBytes ?? 1048576;
@@ -53,19 +55,17 @@ function mcpHandler(app, options) {
 		} catch {
 			return rejection("not-utf8");
 		}
-		const version = request.headers.get("MCP-Protocol-Version");
+		const opened = await openContext(options, request);
+		if ("refusal" in opened) return refusalResponse(opened.refusal);
+		const unanswerable = revisionError(request, message);
+		if (unanswerable !== void 0) {
+			await opened.release();
+			return unanswerable;
+		}
 		const id = message.id ?? null;
-		if (version === null) return error(400, id, -32020, "MCP-Protocol-Version header is required");
-		if (version !== MCP_PROTOCOL_VERSION) return error(400, id, -32022, `Unsupported protocol version ${version}`, { supported: [MCP_PROTOCOL_VERSION] });
-		if (message.id === void 0) return new Response(null, {
-			status: 200,
-			headers: { "Content-Type": "application/json" }
-		});
-		const metaVersion = message.protocolVersion;
-		if (metaVersion === void 0) return error(400, id, -32602, "Required request metadata is missing");
-		if (metaVersion !== version) return error(400, id, -32020, "MCP-Protocol-Version header does not match request metadata");
+		let holders = 0;
 		const open = async () => {
-			const opened = await openContext(options, request);
+			holders += 1;
 			const session = createSession(app, {
 				target: options.target ?? "mcp",
 				context: opened.context,
@@ -74,8 +74,12 @@ function mcpHandler(app, options) {
 			});
 			let closing;
 			const close = () => closing ??= (async () => {
-				await session.dispose();
-				await opened.release();
+				try {
+					await session.dispose();
+				} finally {
+					holders -= 1;
+					if (holders === 0) await opened.release();
+				}
 			})();
 			return {
 				session,
@@ -85,7 +89,7 @@ function mcpHandler(app, options) {
 		const { session, close } = await open();
 		let streaming = false;
 		try {
-			if (message.method === "events/stream" && message.id !== null && servesEvents(session)) {
+			if (message.method === "events/stream" && message.id !== null && message.id !== void 0 && servesEvents(session)) {
 				const started = await startEventStream(session, message.id, message.params, {
 					heartbeatMs: options.heartbeatMs ?? KEEPALIVE_MS,
 					resultMeta: serverInfoOf(options),
@@ -127,6 +131,23 @@ function mcpHandler(app, options) {
 		[Symbol.asyncDispose]: closeAll
 	});
 }
+/**
+* The error answer of a request that does not name revision 2026-07-28 correctly, or the empty answer of a
+* notification. `undefined` for a request that the server answers.
+*/
+function revisionError(request, message) {
+	const version = request.headers.get("MCP-Protocol-Version");
+	const id = message.id ?? null;
+	if (version === null) return error(400, id, -32020, "MCP-Protocol-Version header is required");
+	if (version !== MCP_PROTOCOL_VERSION) return error(400, id, -32022, `Unsupported protocol version ${version}`, { supported: [MCP_PROTOCOL_VERSION] });
+	if (message.id === void 0) return new Response(null, {
+		status: 200,
+		headers: { "Content-Type": "application/json" }
+	});
+	const metaVersion = message.protocolVersion;
+	if (metaVersion === void 0) return error(400, id, -32602, "Required request metadata is missing");
+	if (metaVersion !== version) return error(400, id, -32020, "MCP-Protocol-Version header does not match request metadata");
+}
 /** The methods whose state outlives the request (spec/bindings/mcp.md#subscriptions-that-outlive-a-request). */
 const LONG_LIVED = /* @__PURE__ */ new Set([
 	"events/poll",

package/dist/session.js

@@ -86,7 +86,8 @@ function createSession(app, options) {
 		if (lifetime.signal.aborted || signal?.aborted) controller.abort();
 		const work = Promise.resolve().then(() => prepared.start({
 			signal: controller.signal,
-			context: options.context
+			context: options.context,
+			target: options.target
 		})).catch((cause) => {
 			onDefect(id, cause);
 			return callFailure("internal", "The capability failed.");
@@ -199,6 +200,7 @@ function createSession(app, options) {
 			source = prepared.start({
 				signal: controller.signal,
 				context: options.context,
+				target: options.target,
 				...subscribeOptions.cursor === void 0 ? {} : { cursor: subscribeOptions.cursor },
 				...subscribeOptions.maxAgeMs === void 0 ? {} : { maxAgeMs: subscribeOptions.maxAgeMs }
 			});

package/dist/webhook.js

@@ -35,7 +35,9 @@ function webhookDelivery(options = {}) {
 	const subscriptions = /* @__PURE__ */ new Map();
 	/** The subscriptions that start, by key. A second request with the same key waits for the first. */
 	const starting = /* @__PURE__ */ new Map();
-	/** The pairs of principal and URL that agreed to get deliveries, while the process runs. */
+	/** The new subscriptions of each principal that are starting now, so that they count for the limit. */
+	const admitted = /* @__PURE__ */ new Map();
+	/** The pairs of principal and URL, as the client sent it, that agreed to get deliveries, while the process runs. */
 	const verified = /* @__PURE__ */ new Set();
 	const pumps = /* @__PURE__ */ new Set();
 	let closed = false;
@@ -127,8 +129,8 @@ function webhookDelivery(options = {}) {
 		subscription.cancelExpiry = clock.schedule(() => void end(subscription), lifetime);
 	}
 	/** Verify that the endpoint agrees to get deliveries for this principal. The result is the reason of a failure. */
-	async function verify(principal, url, id, secret) {
-		const pair = canonicalJson([principal, url.href]);
+	async function verify(principal, rawUrl, url, id, secret) {
+		const pair = canonicalJson([principal, rawUrl]);
 		if (verified.has(pair) || options.allow?.(url) === true) return void 0;
 		const challenge = randomBytes(24).toString("base64url");
 		const body = JSON.stringify({
@@ -158,7 +160,7 @@ function webhookDelivery(options = {}) {
 	} });
 	/** Start a new subscription: subscribe in a session of its own, verify the endpoint, then send the occurrences. */
 	async function start(principal, key, url, secret, request, open) {
-		if ([...subscriptions.values()].filter((each) => each.principal === principal).length >= settings.maxSubscriptions) return { error: {
+		if ([...subscriptions.values()].filter((each) => each.principal === principal).length + (admitted.get(principal) ?? 0) >= settings.maxSubscriptions) return { error: {
 			code: MCP_EVENT_ERRORS.resourceExhausted,
 			message: "Too many webhook subscriptions.",
 			data: {
@@ -166,6 +168,24 @@ function webhookDelivery(options = {}) {
 				max: settings.maxSubscriptions
 			}
 		} };
+		admitted.set(principal, (admitted.get(principal) ?? 0) + 1);
+		let held = true;
+		/** Stop counting the subscription as starting. It runs once: when the subscription exists, or when the start fails. */
+		const release = () => {
+			if (!held) return;
+			held = false;
+			const left = (admitted.get(principal) ?? 1) - 1;
+			if (left === 0) admitted.delete(principal);
+			else admitted.set(principal, left);
+		};
+		try {
+			return await startAdmitted(principal, key, url, secret, request, open, release);
+		} finally {
+			release();
+		}
+	}
+	/** Start a subscription that the limit admitted. `release` runs in the same step that adds the subscription. */
+	async function startAdmitted(principal, key, url, secret, request, open, release) {
 		const id = await webhookSubscriptionId(principal, request.rawUrl, request.name, request.input);
 		const own = await open();
 		const subscribed = await own.session.subscribe(request.name, request.input, {
@@ -176,7 +196,7 @@ function webhookDelivery(options = {}) {
 			await own.close();
 			return { error: mcpSubscribeError(subscribed) };
 		}
-		const reason = closed ? "connection_refused" : await verify(principal, url, id, secret);
+		const reason = closed ? "connection_refused" : await verify(principal, request.rawUrl, url, id, secret);
 		if (reason !== void 0 || closed) {
 			await subscribed.return();
 			await own.close();
@@ -198,6 +218,7 @@ function webhookDelivery(options = {}) {
 			lastDeliveryAt: null,
 			lastError: null
 		};
+		release();
 		subscriptions.set(key, subscription);
 		grant(subscription, request.ttlMs);
 		const work = pump(subscription).finally(() => pumps.delete(work));
@@ -210,7 +231,7 @@ function webhookDelivery(options = {}) {
 			if ("error" in read) return read;
 			const { url, secret } = read;
 			const key = subscriptionKey(principal, read.rawUrl, read.name, read.input);
-			await starting.get(key);
+			for (let pending = starting.get(key); pending !== void 0; pending = starting.get(key)) await pending.catch(() => void 0);
 			const existing = subscriptions.get(key);
 			if (existing !== void 0) {
 				if (!isMaxAgeMs(read.maxAgeMs)) return invalidParams("maxAgeMs must be an integer that is 0 or more.");
@@ -226,7 +247,9 @@ function webhookDelivery(options = {}) {
 			}
 			const started = start(principal, key, url, secret, read, open);
 			starting.set(key, started);
-			return started.finally(() => starting.delete(key));
+			return started.finally(() => {
+				if (starting.get(key) === started) starting.delete(key);
+			});
 		},
 		unsubscribe(principal, params) {
 			const { name, arguments: input = {}, delivery } = params;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@acid-cat/core-ts",
-  "version": "0.10.2",
+  "version": "0.11.0",
   "description": "Serve AcidCat capabilities and events in plain TypeScript, with no Effect dependency.",
   "keywords": [
     "acidcat",
@@ -36,12 +36,12 @@
     "access": "public"
   },
   "dependencies": {
-    "@acid-cat/catalog": "0.10.2",
-    "@acid-cat/mcp-handshake": "0.10.2",
-    "@acid-cat/spec-ts": "0.10.2"
+    "@acid-cat/catalog": "0.11.0",
+    "@acid-cat/mcp-handshake": "0.11.0",
+    "@acid-cat/spec-ts": "0.11.0"
   },
   "devDependencies": {
-    "@acid-cat/cli": "0.10.2",
+    "@acid-cat/cli": "0.11.0",
     "@types/node": "26.6.6",
     "esbuild": "0.28.2",
     "graphql": "17.1.0",