@acid-cat/core-ts 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hebilicious
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,92 @@
-# Temporary Holding Version
+# @acid-cat/core-ts
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Serve AcidCat capabilities 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.
+
+```sh
+pnpm add @acid-cat/core-ts
+```
+
+## Write capabilities
+
+```ts
+import { capabilitiesFor, defineApp, fail, ok } from "@acid-cat/core-ts";
+import { z } from "zod";
+
+const Offline = z.object({ _tag: z.literal("Offline") });
+const capability = capabilitiesFor<{ unit: Unit }>();
+
+export const aircon = defineApp<{ unit: Unit }>({
+  title: "Living-room air conditioner",
+  targets: { cli: { bindings: ["cli"] }, mcp: { bindings: ["mcp"] } },
+  capabilities: [
+    capability({
+      id: "aircon.power.set",
+      description: "Turn the unit on or off.",
+      audience: ["cli", "mcp"],
+      input: z.object({ on: z.boolean() }),
+      failures: { Offline },
+      run: async ({ on }, { context, signal }) => ((await context.unit.setPower(on, signal)) ? ok(null) : fail("Offline")),
+    }),
+  ],
+});
+```
+
+- `run` gets the input, an `AbortSignal` and the context. It returns `ok(value)` or `fail(tag, data)`. If it throws, the call fails as `internal`.
+- A failure schema describes the whole failure object, with its `_tag`.
+- `availability` is an optional function that returns an observable availability.
+- `state` is an optional `{ schema, source }`: the schema of the [state](../../spec/invocation.md#state), and a function that returns an observable. The handle gives it as `snapshot`.
+- `capabilitiesFor<Context>()` sets the context type one time. The other types come from the schemas.
+
+## Write the catalog
+
+```ts
+import { renderCatalog } from "@acid-cat/core-ts";
+
+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`.
+
+## Serve the capabilities
+
+| 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>` |
+| `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 |
+
+### 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:
+
+```ts
+const handler = httpHandler(aircon, {
+  allowedOrigins: [],
+  toJsonSchema,
+  createContext: () => ({ unit: connectUnit(env), [Symbol.asyncDispose]: () => disconnectUnit() }),
+});
+```
+
+### 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:
+
+```ts
+const handler = httpHandler(aircon, {
+  allowedOrigins: [],
+  toJsonSchema,
+  createContext: () => ({ unit: connectUnit(env), [Symbol.asyncDispose]: () => disconnectUnit() }),
+});
+```
+
+## Examples and tests
+
+- [`examples/aircon.ts`](examples/aircon.ts) is the air conditioner of [`examples/aircon.pkl`](../../examples/aircon.pkl), with a simulated unit. Its catalog agrees with the Pkl catalog.
+- [`examples/aircon-cli.ts`](examples/aircon-cli.ts) is its command line: `node examples/aircon-cli.ts aircon power set --on`.
+- [`examples/apis`](../../examples/apis/README.md) builds GraphQL, Cap'n Web and Elysia APIs on it, each beside the HTTP binding.
+- `moon run core-ts:test` tests sessions, handles and all bindings with a test application, and runs `acid-cat conform` against all bindings.

package/dist/app.d.ts

@@ -0,0 +1,85 @@
+import type { Availability, CatalogDocument, 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> {
+    getSnapshot(): T;
+    subscribe(listener: (value: T) => void): {
+        unsubscribe(): void;
+    };
+}
+type Output<S> = S extends StandardSchemaV1 ? StandardSchemaV1.InferOutput<S> : null;
+type FailureOf<F> = {
+    [Tag in keyof F]: {
+        readonly _tag: Tag;
+    } & (F[Tag] extends StandardSchemaV1 ? StandardSchemaV1.InferOutput<F[Tag]> : object);
+}[keyof F];
+export interface Capability<Context = unknown, Input extends StandardSchemaV1 | undefined = StandardSchemaV1 | undefined, OutputSchema extends StandardSchemaV1 | undefined = StandardSchemaV1 | undefined, Failures extends {
+    readonly [tag: string]: StandardSchemaV1;
+} = {
+    readonly [tag: string]: StandardSchemaV1;
+}> {
+    readonly id: string;
+    readonly description: string;
+    /** The targets that can use the capability. With no audience, no target can use it. */
+    readonly audience: readonly string[];
+    readonly readOnly?: boolean | undefined;
+    /** The input: an object schema. With no input schema, the input is an empty object. */
+    readonly input?: Input;
+    /** The value of a successful call. With no output schema, the value is `null`. */
+    readonly output?: OutputSchema;
+    /** The failures, by tag. The schema of a failure describes the object, without or with its `_tag`. */
+    readonly failures?: Failures;
+    /** A value that clients can observe (spec/invocation.md#state): its schema, and its source. */
+    readonly state?: {
+        readonly schema: StandardSchemaV1;
+        readonly source: (context: Context) => Observable<unknown>;
+    } | undefined;
+    /** The availability of the capability. With none, the capability is always available. */
+    readonly availability?: ((context: Context) => Observable<Availability>) | undefined;
+    readonly run: (input: Input extends StandardSchemaV1 ? StandardSchemaV1.InferOutput<Input> : Record<string, never>, call: {
+        readonly signal: AbortSignal;
+        readonly context: Context;
+    }) => Promise<Result<Output<OutputSchema>, FailureOf<Failures>>> | Result<Output<OutputSchema>, FailureOf<Failures>>;
+}
+export type AnyCapability<Context = any> = Capability<Context, any, any, any>;
+/** Declare a capability. `Context` is the type of the services that `run` receives. */
+export declare const defineCapability: <Context = unknown, Input extends StandardSchemaV1 | undefined = undefined, OutputSchema extends StandardSchemaV1 | undefined = undefined, Failures extends {
+    readonly [tag: string]: StandardSchemaV1;
+} = {}>(capability: Capability<Context, Input, OutputSchema, Failures>) => Capability<Context, Input, OutputSchema, Failures>;
+/**
+ * Declare capabilities for one context type. The other types come from the schemas:
+ *
+ * ```ts
+ * const capability = capabilitiesFor<{ unit: Unit }>();
+ * capability({ id: "aircon.power.set", input: z.object({ on: z.boolean() }), run: ({ on }, { context }) => … });
+ * ```
+ */
+export declare const capabilitiesFor: <Context>() => <Input extends StandardSchemaV1 | undefined = undefined, OutputSchema extends StandardSchemaV1 | undefined = undefined, Failures extends {
+    readonly [tag: string]: StandardSchemaV1;
+} = {}>(capability: Capability<Context, Input, OutputSchema, Failures>) => Capability<Context, Input, OutputSchema, Failures>;
+export interface Target {
+    readonly bindings: readonly string[];
+    readonly description?: string | undefined;
+    readonly options?: JsonObject | undefined;
+}
+export interface App<Context = unknown> {
+    readonly title?: string | undefined;
+    readonly description?: string | undefined;
+    readonly targets: {
+        readonly [name: string]: Target;
+    };
+    readonly capabilities: readonly AnyCapability<Context>[];
+}
+/** Declare an application. */
+export declare const defineApp: <Context = unknown>(app: App<Context>) => App<Context>;
+/** Converts a schema to JSON Schema 2020-12, for example `(schema) => z.toJSONSchema(schema)` with Zod. */
+export type ToJsonSchema = (schema: StandardSchemaV1) => JsonObject;
+/** The catalog of an application, as a JSON document. */
+export declare function catalogOf(app: App<any>, options: {
+    readonly toJsonSchema: ToJsonSchema;
+}): CatalogDocument;
+/** The catalog of an application, as text in canonical form. */
+export declare const renderCatalog: (app: App<any>, options: {
+    readonly toJsonSchema: ToJsonSchema;
+}) => string;
+export {};

package/dist/app.js

@@ -0,0 +1,62 @@
+import { canonicalText } from "@acid-cat/catalog";
+//#region src/app.ts
+/**
+* Capabilities and applications in plain TypeScript. An application writes its own catalog.
+* See spec/catalog.md.
+*/
+/** Declare a capability. `Context` is the type of the services that `run` receives. */
+const defineCapability = (capability) => capability;
+/**
+* Declare capabilities for one context type. The other types come from the schemas:
+*
+* ```ts
+* const capability = capabilitiesFor<{ unit: Unit }>();
+* capability({ id: "aircon.power.set", input: z.object({ on: z.boolean() }), run: ({ on }, { context }) => … });
+* ```
+*/
+const capabilitiesFor = () => (capability) => capability;
+/** Declare an application. */
+const defineApp = (app) => app;
+/** The catalog of an application, as a JSON document. */
+function catalogOf(app, options) {
+	const types = {};
+	const toJson = (schema, where) => {
+		const { $schema: _, $defs, ...json } = options.toJsonSchema(schema);
+		for (const [name, definition] of Object.entries($defs ?? {})) {
+			const existing = types[name];
+			if (existing !== void 0 && JSON.stringify(existing) !== JSON.stringify(definition)) throw new Error(`${where}: two different schemas have the name ${name}. Give each one its own name.`);
+			types[name] = definition;
+		}
+		return json;
+	};
+	const capabilities = {};
+	for (const capability of app.capabilities) {
+		if (capability.id in capabilities) throw new Error(`The capability ${capability.id} is declared two times.`);
+		const failures = Object.fromEntries(Object.entries(capability.failures ?? {}).map(([tag, schema]) => [tag, toJson(schema, capability.id)]));
+		capabilities[capability.id] = {
+			description: capability.description,
+			audience: capability.audience,
+			...capability.input === void 0 ? {} : { input: toJson(capability.input, capability.id) },
+			...capability.output === void 0 ? {} : { output: toJson(capability.output, capability.id) },
+			...Object.keys(failures).length === 0 ? {} : { failures },
+			...capability.readOnly === true ? { readOnly: true } : {},
+			...capability.state === void 0 ? {} : { state: toJson(capability.state.schema, capability.id) }
+		};
+	}
+	return {
+		acidcat: "0.1",
+		...app.title === void 0 ? {} : { title: app.title },
+		...app.description === void 0 ? {} : { description: app.description },
+		targets: Object.fromEntries(Object.entries(app.targets).map(([name, target]) => [name, {
+			bindings: target.bindings,
+			...target.description === void 0 ? {} : { description: target.description },
+			...target.options === void 0 ? {} : { options: target.options }
+		}])),
+		...Object.keys(types).length === 0 ? {} : { $defs: types },
+		capabilities
+	};
+}
+/** 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 };

package/dist/cli.d.ts

@@ -0,0 +1,18 @@
+import type { App, ToJsonSchema } from "./app.js";
+export interface CliOptions<Context> {
+    readonly name: string;
+    readonly version: string;
+    readonly context: Context;
+    readonly toJsonSchema: ToJsonSchema;
+    /** The target that the command line serves. The default is `"cli"`. */
+    readonly target?: string | undefined;
+}
+export interface CliIo {
+    readonly stdout: (text: string) => void;
+    readonly stderr: (text: string) => void;
+    readonly signal?: AbortSignal | undefined;
+}
+/** Run the command line as the main program of the process. An interrupt (`SIGINT`) cancels the call. */
+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

@@ -0,0 +1,163 @@
+import { createSession } from "./session.js";
+import { CLI_EXIT_CODES, REFERENCE, bundle, cliExitCode, commandPath, isCallFailure } from "@acid-cat/spec-ts";
+//#region src/cli.ts
+/**
+* The CLI binding (spec/bindings/cli.md): a command line made from the catalog.
+*/
+var UsageError = class extends Error {
+	exitCode;
+	constructor(message, exitCode) {
+		super(message);
+		this.exitCode = exitCode;
+	}
+};
+/** Run the command line as the main program of the process. An interrupt (`SIGINT`) cancels the call. */
+function main(app, options) {
+	const interrupt = new AbortController();
+	process.once("SIGINT", () => interrupt.abort());
+	runCli(app, options, process.argv.slice(2), {
+		stdout: (text) => process.stdout.write(`${text}\n`),
+		stderr: (text) => process.stderr.write(`${text}\n`),
+		signal: interrupt.signal
+	}).then((code) => {
+		process.exitCode = code;
+	});
+}
+/** 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) => ({
+		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.`);
+	const print = (outcome) => {
+		if (isCallFailure(outcome)) io.stderr(JSON.stringify({
+			kind: outcome.kind,
+			message: outcome.message
+		}));
+		else io.stdout(JSON.stringify(outcome.ok ? outcome.value : outcome.error, null, 2));
+		return cliExitCode(outcome);
+	};
+	try {
+		const [first, ...rest] = args;
+		if (first === void 0 || first === "--help" || first === "-h") {
+			io.stdout(help(options.name, commands.map(({ path }) => path.join(" "))));
+			return CLI_EXIT_CODES.value;
+		}
+		if (first === "--version" || first === "-v") {
+			io.stdout(options.version);
+			return CLI_EXIT_CODES.value;
+		}
+		if (first === "list") {
+			io.stdout(JSON.stringify([...session.handles.values()].map((handle) => ({
+				id: handle.id,
+				description: handle.description,
+				...handle.availability.getSnapshot(),
+				usage: `${options.name} ${commandPath(handle.id).join(" ")}`
+			})), null, 2));
+			return CLI_EXIT_CODES.value;
+		}
+		if (first === "call") {
+			const [id, text = "{}"] = rest;
+			if (id === void 0) throw new UsageError("Give the id of a capability.", CLI_EXIT_CODES["invalid-input"]);
+			let input;
+			try {
+				input = JSON.parse(text);
+			} catch {
+				return print({
+					kind: "invalid-input",
+					message: "The input is not JSON."
+				});
+			}
+			return print(await session.invoke(id, input, { signal: io.signal }));
+		}
+		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 = session.view.capabilities[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 }));
+	} catch (error) {
+		if (!(error instanceof UsageError)) throw error;
+		io.stderr(error.message);
+		return error.exitCode;
+	} finally {
+		await session.dispose();
+	}
+}
+/** Make the input from the flags (spec/bindings/cli.md#commands). */
+function parseFlags(args, schema) {
+	const properties = schema.properties ?? {};
+	const definitions = schema.$defs ?? {};
+	const input = {};
+	for (let index = 0; index < args.length; index += 1) {
+		const arg = args[index];
+		if (!arg.startsWith("--")) throw new UsageError(`Unexpected argument ${arg}.`, CLI_EXIT_CODES["invalid-input"]);
+		const [name, inline] = arg.slice(2).split(/=(.*)/s, 2);
+		const property = properties[name];
+		if (property === void 0) throw new UsageError(`Unknown flag --${name}.`, CLI_EXIT_CODES["invalid-input"]);
+		const type = resolve(property, definitions);
+		if (type.type === "boolean") {
+			input[name] = inline === void 0 ? true : inline === "true";
+			continue;
+		}
+		const text = inline ?? args[index += 1];
+		if (text === void 0) throw new UsageError(`The flag --${name} needs a value.`, CLI_EXIT_CODES["invalid-input"]);
+		input[name] = valueOf(name, text, type);
+	}
+	for (const name of schema.required ?? []) if (!(name in input)) throw new UsageError(`The flag --${name} is required.`, CLI_EXIT_CODES["invalid-input"]);
+	return input;
+}
+function valueOf(name, text, type) {
+	if (Array.isArray(type.enum) && type.enum.every((value) => typeof value === "string")) {
+		if (!type.enum.includes(text)) throw new UsageError(`The flag --${name} must be one of: ${type.enum.join(", ")}.`, CLI_EXIT_CODES["invalid-input"]);
+		return text;
+	}
+	if (type.type === "integer" || type.type === "number") {
+		const number = Number(text);
+		if (text.trim() === "" || !Number.isFinite(number) || type.type === "integer" && !Number.isInteger(number)) throw new UsageError(`The flag --${name} must be a ${type.type}.`, CLI_EXIT_CODES["invalid-input"]);
+		return number;
+	}
+	if (type.type === "string") return text;
+	try {
+		return JSON.parse(text);
+	} catch {
+		throw new UsageError(`The flag --${name} must be JSON.`, CLI_EXIT_CODES["invalid-input"]);
+	}
+}
+function resolve(property, definitions) {
+	const name = typeof property.$ref === "string" ? REFERENCE.exec(property.$ref)?.[1] : void 0;
+	return name === void 0 ? property : definitions[name] ?? property;
+}
+function help(name, paths) {
+	return [
+		`Usage: ${name} <command> [flags]`,
+		"",
+		"Commands:",
+		...paths.map((path) => `  ${path}`),
+		"  call <id> [input]",
+		"  list"
+	].join("\n");
+}
+function usage(name, path, description, schema) {
+	const properties = Object.keys(schema.properties ?? {});
+	const required = new Set(schema.required ?? []);
+	const flags = properties.map((property) => required.has(property) ? `--${property} <value>` : `[--${property} <value>]`);
+	return [
+		`Usage: ${name} ${[...path, ...flags].join(" ")}`,
+		"",
+		description
+	].join("\n");
+}
+//#endregion
+export { main, runCli };

package/dist/context.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The context of the web handlers: one context that all requests share, or a new context for each request.
+ */
+export type ContextOption<Context> = {
+    /** The context of all requests. */
+    readonly context: Context;
+    readonly createContext?: undefined;
+} | {
+    /**
+     * 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.
+     */
+    readonly createContext: (request: Request) => Context | Promise<Context>;
+    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>;

package/dist/context.js

@@ -0,0 +1,20 @@
+//#region src/context.ts
+/** Give the context of one request to `use`, and release it afterwards if the handler made it. */
+async function withContext(option, request, use) {
+	if (option.createContext === void 0) return use(option.context);
+	const context = await option.createContext(request);
+	try {
+		return await use(context);
+	} finally {
+		await release(context);
+	}
+}
+/** Call `Symbol.asyncDispose` or `Symbol.dispose` of a value, if it has one. */
+async function release(value) {
+	if (typeof value !== "object" || value === null) return;
+	const disposable = value;
+	if (typeof disposable[Symbol.asyncDispose] === "function") await disposable[Symbol.asyncDispose]();
+	else if (typeof disposable[Symbol.dispose] === "function") disposable[Symbol.dispose]();
+}
+//#endregion
+export { withContext };

package/dist/http.d.ts

@@ -0,0 +1,19 @@
+import type { App, ToJsonSchema } from "./app.js";
+import type { ContextOption } from "./context.js";
+/** The options of `httpHandler`. Give `context` to share one context, or `createContext` to make one for each request. */
+export type HttpOptions<Context> = HttpSettings & ContextOption<Context>;
+export interface HttpSettings {
+    /** The origins that can call the API. A request with no `Origin` header is accepted. */
+    readonly allowedOrigins: readonly string[];
+    readonly toJsonSchema: ToJsonSchema;
+    /** The target that the API serves. The default is `"api"`. */
+    readonly target?: string | undefined;
+    /** The path before `/capabilities` and `/catalog`, for example `"/api"`. The default is `""`. */
+    readonly base?: string | undefined;
+    /** Serve `GET {base}/catalog`. The default is `true`. */
+    readonly serveCatalog?: boolean | undefined;
+    /** The maximum size of a request body, in bytes. The default is 1 MiB. */
+    readonly maximumBytes?: number | undefined;
+}
+/** A web request handler for the API. Each request has its own session, and with `createContext` its own context. */
+export declare function httpHandler<Context>(app: App<Context>, options: HttpOptions<Context>): (request: Request) => Promise<Response>;

package/dist/http.js

@@ -0,0 +1,73 @@
+import { createSession } from "./session.js";
+import { withContext } from "./context.js";
+import { callFailure, httpStatus, isCallFailure, readBounded, screenRequest } from "@acid-cat/spec-ts";
+//#region src/http.ts
+/**
+* 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. */
+function httpHandler(app, options) {
+	const maximumBytes = options.maximumBytes ?? 1048576;
+	return async (request) => {
+		const screened = screenRequest(request, {
+			methods: ["GET", "POST"],
+			allowedOrigins: options.allowedOrigins,
+			mediaType: "application/json",
+			maximumBytes
+		});
+		if (screened !== void 0) return rejection(screened);
+		const path = new URL(request.url).pathname.slice((options.base ?? "").length);
+		return withContext(options, request, async (context) => {
+			const session = createSession(app, {
+				target: options.target ?? "api",
+				context,
+				toJsonSchema: options.toJsonSchema
+			});
+			try {
+				if (request.method === "GET" && path === "/capabilities") return json(200, [...session.handles.values()].map((handle) => ({
+					id: handle.id,
+					...handle.availability.getSnapshot()
+				})));
+				if (request.method === "GET" && path === "/catalog" && options.serveCatalog !== false) return json(200, session.view);
+				const id = request.method === "POST" && path.startsWith("/capabilities/") ? path.slice(14) : void 0;
+				if (id === void 0) return json(404, callFailure("unknown-capability", "There is no such route."));
+				const body = await readBounded(request, maximumBytes);
+				if ("rejection" in body) return rejection(body.rejection);
+				let input;
+				try {
+					input = body.text === "" ? {} : JSON.parse(body.text);
+				} catch {
+					return json(422, callFailure("invalid-input", "The request body is not JSON."));
+				}
+				const outcome = await session.invoke(decodeURIComponent(id), input, { signal: request.signal });
+				return json(httpStatus(outcome), isCallFailure(outcome) ? {
+					kind: outcome.kind,
+					message: outcome.message
+				} : outcome);
+			} finally {
+				await session.dispose();
+			}
+		});
+	};
+}
+const json = (status, body) => new Response(JSON.stringify(body), {
+	status,
+	headers: { "Content-Type": "application/json" }
+});
+const statuses = {
+	method: 405,
+	origin: 403,
+	"media-type": 415,
+	"too-large": 413,
+	"not-utf8": 400
+};
+function rejection(reason) {
+	const headers = new Headers({ "Cache-Control": "no-store" });
+	if (reason === "method") headers.set("Allow", "GET, POST");
+	return new Response(null, {
+		status: statuses[reason],
+		headers
+	});
+}
+//#endregion
+export { httpHandler };

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+export { capabilitiesFor, catalogOf, defineApp, defineCapability, renderCatalog } from "./app.js";
+export type { AnyCapability, App, Capability, Observable, Target, ToJsonSchema } from "./app.js";
+export { createSession } from "./session.js";
+export type { Handle, Session, SessionOptions } from "./session.js";
+export { mcpHandler } from "./mcp.js";
+export type { McpOptions, McpSettings } from "./mcp.js";
+export { httpHandler } from "./http.js";
+export type { HttpOptions, HttpSettings } from "./http.js";
+export type { ContextOption } from "./context.js";
+export { main as cliMain, runCli } from "./cli.js";
+export type { CliIo, CliOptions } from "./cli.js";
+export { findHost, installWebMcp } from "./webmcp.js";
+export type { Installation, ModelContext, ModelContextTool, Phase, Status } from "./webmcp.js";
+export type { StandardSchemaV1 } from "./standard-schema.js";
+export { AVAILABLE, CallFailureError, fail, ok, unavailable } from "@acid-cat/spec-ts";
+export type { Availability, CallFailure, CallFailureKind, Outcome, Result } from "@acid-cat/spec-ts";

package/dist/index.js

@@ -0,0 +1,8 @@
+import { capabilitiesFor, catalogOf, defineApp, defineCapability, renderCatalog } from "./app.js";
+import { createSession } from "./session.js";
+import { mcpHandler } from "./mcp.js";
+import { httpHandler } from "./http.js";
+import { main, runCli } from "./cli.js";
+import { findHost, installWebMcp } from "./webmcp.js";
+import { AVAILABLE, CallFailureError, fail, ok, unavailable } from "@acid-cat/spec-ts";
+export { AVAILABLE, CallFailureError, capabilitiesFor, catalogOf, main as cliMain, createSession, defineApp, defineCapability, fail, findHost, httpHandler, installWebMcp, mcpHandler, ok, renderCatalog, runCli, unavailable };

package/dist/mcp.d.ts

@@ -0,0 +1,17 @@
+import type { App, ToJsonSchema } from "./app.js";
+import type { ContextOption } from "./context.js";
+/** The options of `mcpHandler`. Give `context` to share one context, or `createContext` to make one for each request. */
+export type McpOptions<Context> = McpSettings & ContextOption<Context>;
+export interface McpSettings {
+    readonly name: string;
+    readonly version: string;
+    /** The origins that can call the server. A request with no `Origin` header is accepted. */
+    readonly allowedOrigins: readonly string[];
+    readonly toJsonSchema: ToJsonSchema;
+    /** The target that the server serves. The default is `"mcp"`. */
+    readonly target?: string | undefined;
+    /** The maximum size of a request body, in bytes. The default is 1 MiB. */
+    readonly maximumBytes?: number | undefined;
+}
+/** A web request handler for the MCP server. Each request has its own session, and with `createContext` its own context. */
+export declare function mcpHandler<Context>(app: App<Context>, options: McpOptions<Context>): (request: Request) => Promise<Response>;

package/dist/mcp.js

@@ -0,0 +1,155 @@
+import { createSession } from "./session.js";
+import { withContext } from "./context.js";
+import { MCP_PROTOCOL_VERSION, MCP_REJECTIONS, MCP_UNKNOWN_TOOL, bundle, mcpToolResult, readBounded, screenRequest } from "@acid-cat/spec-ts";
+//#region src/mcp.ts
+/**
+* The MCP binding (spec/bindings/mcp.md): an MCP server through HTTP, revision 2026-07-28, with no state on the
+* server between requests.
+*/
+/** A web request handler for the MCP server. Each request has its own session, and with `createContext` its own context. */
+function mcpHandler(app, options) {
+	const maximumBytes = options.maximumBytes ?? 1048576;
+	return async (request) => {
+		const screened = screenRequest(request, {
+			methods: ["POST"],
+			allowedOrigins: options.allowedOrigins,
+			mediaType: "application/json",
+			maximumBytes
+		});
+		if (screened !== void 0) return rejection(screened);
+		const body = await readBounded(request, maximumBytes);
+		if ("rejection" in body) return rejection(body.rejection);
+		let message;
+		try {
+			message = JSON.parse(body.text);
+		} catch {
+			return rejection("not-utf8");
+		}
+		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.params?._meta?.["io.modelcontextprotocol/protocolVersion"];
+		if (metaVersion === void 0) return error(400, id, -32602, "Required request metadata is missing");
+		if (metaVersion !== version) return error(400, id, -32020, "MCP-Protocol-Version header does not match request metadata");
+		return withContext(options, request, async (context) => {
+			const session = createSession(app, {
+				target: options.target ?? "mcp",
+				context,
+				toJsonSchema: options.toJsonSchema
+			});
+			try {
+				return await answer(session, message, options, request.signal);
+			} finally {
+				await session.dispose();
+			}
+		});
+	};
+}
+async function answer(session, message, options, signal) {
+	const id = message.id ?? null;
+	const complete = (result, list = false) => reply(id, {
+		_meta: { "io.modelcontextprotocol/serverInfo": {
+			name: options.name,
+			version: options.version
+		} },
+		resultType: "complete",
+		...list ? {
+			ttlMs: 0,
+			cacheScope: "private"
+		} : {},
+		...result
+	});
+	switch (message.method) {
+		case "server/discover": return complete({
+			supportedVersions: [MCP_PROTOCOL_VERSION],
+			capabilities: { tools: { listChanged: false } }
+		}, true);
+		case "tools/list": return complete({ tools: listTools(session) }, true);
+		case "tools/call": {
+			const name = message.params?.name ?? "";
+			const handle = session.handles.get(name);
+			if (handle === void 0 || !handle.availability.getSnapshot().available) return error(200, id, MCP_UNKNOWN_TOOL, `Tool '${name}' not found`);
+			const outcome = await session.invoke(name, message.params?.arguments ?? {}, { signal });
+			return complete(mcpToolResult(outcome, hasObjectOutput(session, name)));
+		}
+		default: return error(404, id, -32601, `Method not found: ${message.method}`);
+	}
+}
+function listTools(session) {
+	const types = session.view.$defs ?? {};
+	return [...session.handles.values()].filter((handle) => handle.availability.getSnapshot().available).map((handle) => {
+		const capability = session.view.capabilities[handle.id];
+		const output = capability.output === void 0 ? void 0 : bundle(capability.output, types);
+		return {
+			name: handle.id,
+			description: capability.description,
+			inputSchema: bundle(capability.input ?? { type: "object" }, types),
+			...output?.type === "object" ? { outputSchema: output } : {},
+			annotations: { readOnlyHint: capability.readOnly === true }
+		};
+	});
+}
+function hasObjectOutput(session, id) {
+	const output = session.view.capabilities[id]?.output;
+	return output !== void 0 && bundle(output, session.view.$defs ?? {}).type === "object";
+}
+function reply(id, result) {
+	return new Response(JSON.stringify({
+		jsonrpc: "2.0",
+		id,
+		result
+	}), {
+		status: 200,
+		headers: { "Content-Type": "application/json" }
+	});
+}
+function error(status, id, code, message, data) {
+	const body = {
+		jsonrpc: "2.0",
+		id,
+		error: {
+			code,
+			message,
+			...data === void 0 ? {} : { data }
+		}
+	};
+	return new Response(JSON.stringify(body), {
+		status,
+		headers: { "Content-Type": "application/json" }
+	});
+}
+function rejection(reason) {
+	const { status, code } = MCP_REJECTIONS[reason];
+	const headers = new Headers({ "Cache-Control": "no-store" });
+	if (reason === "method") headers.set("Allow", "POST");
+	if (code === void 0) return new Response(null, {
+		status,
+		headers
+	});
+	headers.set("Content-Type", "application/json");
+	return new Response(JSON.stringify({
+		jsonrpc: "2.0",
+		id: null,
+		error: {
+			code,
+			message: messages[reason]
+		}
+	}), {
+		status,
+		headers
+	});
+}
+const messages = {
+	method: "Use POST.",
+	origin: "This origin is not allowed.",
+	"media-type": "Use application/json.",
+	"too-large": "The request body is too large.",
+	"not-utf8": "The request body is not UTF-8 JSON."
+};
+//#endregion
+export { mcpHandler };

package/dist/session.d.ts

@@ -0,0 +1,47 @@
+import type { Availability, CatalogDocument, Outcome, Result } from "@acid-cat/spec-ts";
+import type { App, Observable, ToJsonSchema } from "./app.js";
+export interface Handle {
+    readonly id: string;
+    readonly description: string;
+    readonly audience: readonly string[];
+    readonly availability: Observable<Availability>;
+    /** The state of the capability, if it has one. Each value is a copy. */
+    readonly snapshot?: Observable<unknown>;
+    /** A call with an input that is already valid. A call failure rejects with a `CallFailureError`. */
+    execute(input: unknown, options?: {
+        readonly signal?: AbortSignal | undefined;
+    }): Promise<Result<unknown, unknown>>;
+    /** A call with an input that is not trusted. A call failure rejects with a `CallFailureError`. */
+    invokeExternal(input: unknown, options?: {
+        readonly signal?: AbortSignal | undefined;
+    }): Promise<Result<unknown, unknown>>;
+}
+export interface Session {
+    readonly target: string;
+    /** The view of the target. Bindings take names, descriptions and schemas from it. */
+    readonly view: CatalogDocument;
+    /** The handles of the capabilities in the view, by id. */
+    readonly handles: ReadonlyMap<string, Handle>;
+    /** A call with an input that is not trusted. The outcome is in its JSON form. The promise never rejects. */
+    invoke(id: string, input: unknown, options?: {
+        readonly signal?: AbortSignal | undefined;
+    }): Promise<Outcome<unknown, unknown>>;
+    /** An event each time the availability of a capability changes. */
+    onChange(listener: () => void): {
+        unsubscribe(): void;
+    };
+    /** The signal of the session. It aborts when the session closes. */
+    readonly signal: AbortSignal;
+    /** Close the session: accept no new calls, cancel the calls in progress, and wait for them. */
+    dispose(): Promise<void>;
+}
+export interface SessionOptions<Context> {
+    readonly target: string;
+    /** The services that each `run` receives. */
+    readonly context: Context;
+    readonly toJsonSchema: ToJsonSchema;
+    /** Record a defect. The default writes it to the console. */
+    readonly onDefect?: ((id: string, cause: unknown) => void) | undefined;
+}
+/** Open a session for a target. */
+export declare function createSession<Context>(app: App<Context>, options: SessionOptions<Context>): Session;

package/dist/session.js

@@ -0,0 +1,139 @@
+import { catalogOf } from "./app.js";
+import { AVAILABLE, CallFailureError, callFailure, isCallFailure, viewOf } from "@acid-cat/spec-ts";
+//#region src/session.ts
+/**
+* Sessions and handles (spec/invocation.md, spec/bindings/typescript.md).
+*/
+const always = {
+	getSnapshot: () => AVAILABLE,
+	subscribe: () => ({ unsubscribe() {} })
+};
+/** Open a session for a target. */
+function createSession(app, options) {
+	const view = viewOf(catalogOf(app, { toJsonSchema: options.toJsonSchema }), options.target);
+	const lifetime = new AbortController();
+	const running = /* @__PURE__ */ new Set();
+	const listeners = /* @__PURE__ */ new Set();
+	const subscriptions = [];
+	const onDefect = options.onDefect ?? ((id, cause) => console.error(`A capability failed with a defect: ${id}`, cause));
+	const served = /* @__PURE__ */ new Map();
+	for (const capability of app.capabilities) {
+		if (!(capability.id in view.capabilities)) continue;
+		const availability = capability.availability?.(options.context) ?? always;
+		subscriptions.push(availability.subscribe(() => listeners.forEach((listener) => listener())));
+		served.set(capability.id, {
+			capability,
+			availability
+		});
+	}
+	/** Run a call. The result is a result or a call failure. */
+	async function call(id, input, trusted, signal) {
+		if (lifetime.signal.aborted || signal?.aborted) return callFailure("cancelled", "The call was cancelled.");
+		const entry = served.get(id);
+		if (entry === void 0) return callFailure("unknown-capability", `There is no capability ${id}.`);
+		const availability = entry.availability.getSnapshot();
+		if (!availability.available) return callFailure("unavailable", availability.reason);
+		const { capability } = entry;
+		let decoded = input ?? {};
+		if (!trusted && capability.input !== void 0) {
+			const validated = await capability.input["~standard"].validate(input);
+			if (validated.issues !== void 0) {
+				const message = validated.issues.map((issue) => `${(issue.path ?? []).map((key) => typeof key === "object" ? String(key.key) : String(key)).join(".") || "input"}: ${issue.message}`).join("; ");
+				return callFailure("invalid-input", message);
+			}
+			decoded = validated.value;
+		}
+		const controller = new AbortController();
+		const abort = () => controller.abort();
+		lifetime.signal.addEventListener("abort", abort);
+		signal?.addEventListener("abort", abort);
+		const cancelled = new Promise((resolve) => controller.signal.addEventListener("abort", () => resolve(callFailure("cancelled", "The call was cancelled."))));
+		if (lifetime.signal.aborted || signal?.aborted) controller.abort();
+		const work = Promise.resolve().then(() => capability.run(decoded, {
+			signal: controller.signal,
+			context: options.context
+		})).then((result) => checkResult(capability, result)).catch((cause) => {
+			onDefect(id, cause);
+			return callFailure("internal", "The capability failed.");
+		});
+		const outcome = Promise.race([work, cancelled]);
+		running.add(outcome);
+		try {
+			return await outcome;
+		} finally {
+			running.delete(outcome);
+			lifetime.signal.removeEventListener("abort", abort);
+			signal?.removeEventListener("abort", abort);
+		}
+	}
+	const handles = /* @__PURE__ */ new Map();
+	for (const [id, { capability, availability }] of served) {
+		const reject = async (outcome) => {
+			const settled = await outcome;
+			if (isCallFailure(settled)) throw new CallFailureError(settled);
+			return settled;
+		};
+		const state = capability.state?.source(options.context);
+		handles.set(id, {
+			id,
+			description: capability.description,
+			audience: capability.audience,
+			availability,
+			...state === void 0 ? {} : { snapshot: detached(state) },
+			execute: (input, callOptions) => reject(call(id, input, true, callOptions?.signal)),
+			invokeExternal: (input, callOptions) => reject(call(id, input, false, callOptions?.signal))
+		});
+	}
+	return {
+		target: options.target,
+		view,
+		handles,
+		signal: lifetime.signal,
+		invoke: (id, input, callOptions) => call(id, input, false, callOptions?.signal),
+		onChange(listener) {
+			listeners.add(listener);
+			return { unsubscribe: () => listeners.delete(listener) };
+		},
+		async dispose() {
+			lifetime.abort();
+			subscriptions.forEach((subscription) => subscription.unsubscribe());
+			await Promise.allSettled([...running]);
+		}
+	};
+}
+/** An observable whose values are copies, so that a client cannot change the data of the provider. */
+function detached(source) {
+	return {
+		getSnapshot: () => structuredClone(source.getSnapshot()),
+		subscribe: (listener) => source.subscribe((value) => listener(structuredClone(value)))
+	};
+}
+/** Check a result against the output schema or the failure schemas. A result that does not agree is a defect. */
+async function checkResult(capability, result) {
+	if (result.ok) {
+		if (capability.output === void 0) return {
+			ok: true,
+			value: result.value ?? null
+		};
+		const checked = await capability.output["~standard"].validate(result.value);
+		if (checked.issues !== void 0) throw new Error(`The output does not agree with its schema: ${checked.issues[0]?.message}`);
+		return {
+			ok: true,
+			value: checked.value
+		};
+	}
+	const tag = result.error._tag;
+	const schema = tag === void 0 ? void 0 : capability.failures?.[tag];
+	if (schema === void 0) throw new Error(`The failure ${String(tag)} is not in failures.`);
+	const checked = await schema["~standard"].validate(result.error);
+	if (checked.issues !== void 0) throw new Error(`The failure ${tag} does not agree with its schema: ${checked.issues[0]?.message}`);
+	return {
+		ok: false,
+		error: {
+			_tag: tag,
+			...checked.value
+		}
+	};
+}
+//#endregion
+export { createSession };

package/dist/standard-schema.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The Standard Schema interface (https://standardschema.dev), version 1. Zod, Valibot, ArkType and other libraries
+ * implement it. The interface is copied here, as its authors recommend, so that this package has no dependency.
+ */
+export interface StandardSchemaV1<Input = unknown, Output = Input> {
+    readonly "~standard": StandardSchemaV1.Props<Input, Output>;
+}
+export declare namespace StandardSchemaV1 {
+    interface Props<Input = unknown, Output = Input> {
+        readonly version: 1;
+        readonly vendor: string;
+        readonly validate: (value: unknown) => Result<Output> | Promise<Result<Output>>;
+        readonly types?: Types<Input, Output> | undefined;
+    }
+    type Result<Output> = SuccessResult<Output> | FailureResult;
+    interface SuccessResult<Output> {
+        readonly value: Output;
+        readonly issues?: undefined;
+    }
+    interface FailureResult {
+        readonly issues: ReadonlyArray<Issue>;
+    }
+    interface Issue {
+        readonly message: string;
+        readonly path?: ReadonlyArray<PropertyKey | PathSegment> | undefined;
+    }
+    interface PathSegment {
+        readonly key: PropertyKey;
+    }
+    interface Types<Input = unknown, Output = Input> {
+        readonly input: Input;
+        readonly output: Output;
+    }
+    type InferInput<Schema extends StandardSchemaV1> = NonNullable<Schema["~standard"]["types"]>["input"];
+    type InferOutput<Schema extends StandardSchemaV1> = NonNullable<Schema["~standard"]["types"]>["output"];
+}

package/dist/webmcp.d.ts

@@ -0,0 +1,33 @@
+import type { Observable } from "./app.js";
+import type { Session } from "./session.js";
+export interface ModelContextTool {
+    readonly name: string;
+    readonly description: string;
+    readonly inputSchema: object;
+    readonly execute: (input: unknown, options?: {
+        readonly signal?: AbortSignal;
+    }) => Promise<unknown>;
+}
+export interface ModelContext {
+    readonly registerTool: (tool: ModelContextTool, options: {
+        readonly signal: AbortSignal;
+    }) => unknown;
+}
+export type Phase = "loading" | "reconciling" | "ready" | "failed" | "closing" | "disposed";
+export interface Status {
+    readonly phase: Phase;
+    readonly message: string | null;
+}
+export interface Installation {
+    readonly status: Observable<Status>;
+    /** Try the last failed update again. */
+    retry(): void;
+    /** Remove all tools, and wait for the calls in progress. */
+    dispose(): Promise<void>;
+}
+/** The WebMCP host of the page, if there is one (spec/bindings/webmcp.md#host). */
+export declare function findHost(): ModelContext | undefined;
+/** Register the capabilities of a session as tools. If there is no host, do nothing and return `undefined`. */
+export declare function installWebMcp(session: Session, options?: {
+    readonly host?: ModelContext | undefined;
+}): Installation | undefined;

package/dist/webmcp.js

@@ -0,0 +1,130 @@
+import { CallFailureError, bundle, isCallFailure } from "@acid-cat/spec-ts";
+//#region src/webmcp.ts
+/**
+* The WebMCP binding (spec/bindings/webmcp.md): register capabilities as WebMCP tools in a web page.
+*/
+/** The WebMCP host of the page, if there is one (spec/bindings/webmcp.md#host). */
+function findHost() {
+	const scope = globalThis;
+	for (const candidate of [scope.document?.modelContext, scope.navigator?.modelContext]) if (typeof candidate?.registerTool === "function") return candidate;
+}
+/** Register the capabilities of a session as tools. If there is no host, do nothing and return `undefined`. */
+function installWebMcp(session, options = {}) {
+	const host = options.host ?? findHost();
+	if (host === void 0) return void 0;
+	let status = {
+		phase: "loading",
+		message: null
+	};
+	const listeners = /* @__PURE__ */ new Set();
+	const setStatus = (next) => {
+		status = next;
+		listeners.forEach((listener) => listener(next));
+	};
+	const lifetime = new AbortController();
+	const registered = /* @__PURE__ */ new Map();
+	const calls = /* @__PURE__ */ new Set();
+	const types = session.view.$defs ?? {};
+	let running = false;
+	let dirty = false;
+	const toolFor = (id) => {
+		const capability = session.view.capabilities[id];
+		return {
+			name: id,
+			description: capability.description,
+			inputSchema: bundle(capability.input ?? { type: "object" }, types),
+			execute: (input, callOptions) => {
+				const signal = AbortSignal.any([lifetime.signal, ...callOptions?.signal ? [callOptions.signal] : []]);
+				const call = session.invoke(id, input, { signal }).then((outcome) => {
+					if (isCallFailure(outcome)) throw new CallFailureError(outcome);
+					return outcome;
+				});
+				calls.add(call);
+				call.finally(() => calls.delete(call)).catch(() => void 0);
+				return call;
+			}
+		};
+	};
+	/** One update. If it fails, the tools stay as they were before the update. */
+	async function pass() {
+		const wanted = new Set([...session.handles.values()].filter((handle) => handle.availability.getSnapshot().available).map((handle) => handle.id));
+		const added = /* @__PURE__ */ new Map();
+		try {
+			for (const id of wanted) {
+				if (registered.has(id)) continue;
+				const controller = new AbortController();
+				added.set(id, controller);
+				await host.registerTool(toolFor(id), { signal: AbortSignal.any([controller.signal, lifetime.signal]) });
+			}
+		} catch (error) {
+			for (const controller of added.values()) controller.abort();
+			throw error;
+		}
+		for (const [id, controller] of added) registered.set(id, controller);
+		for (const [id, controller] of registered) if (!wanted.has(id)) {
+			controller.abort();
+			registered.delete(id);
+		}
+	}
+	/** Run updates one at a time. A request during an update causes one more update. */
+	async function reconcile() {
+		if (lifetime.signal.aborted) return;
+		if (running) {
+			dirty = true;
+			return;
+		}
+		running = true;
+		try {
+			do {
+				dirty = false;
+				setStatus({
+					phase: "reconciling",
+					message: null
+				});
+				try {
+					await pass();
+					setStatus({
+						phase: "ready",
+						message: null
+					});
+				} catch (error) {
+					setStatus({
+						phase: "failed",
+						message: error instanceof Error ? error.message : "A tool could not be registered."
+					});
+					dirty = false;
+				}
+			} while (dirty && !lifetime.signal.aborted);
+		} finally {
+			running = false;
+		}
+	}
+	const subscription = session.onChange(() => void reconcile());
+	reconcile();
+	return {
+		status: {
+			getSnapshot: () => status,
+			subscribe(listener) {
+				listeners.add(listener);
+				return { unsubscribe: () => listeners.delete(listener) };
+			}
+		},
+		retry: () => void reconcile(),
+		async dispose() {
+			setStatus({
+				phase: "closing",
+				message: null
+			});
+			subscription.unsubscribe();
+			lifetime.abort();
+			registered.clear();
+			await Promise.allSettled([...calls]);
+			setStatus({
+				phase: "disposed",
+				message: null
+			});
+		}
+	};
+}
+//#endregion
+export { findHost, installWebMcp };

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "@acid-cat/core-ts",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "Serve AcidCat capabilities in plain TypeScript, with no Effect dependency.",
+  "keywords": [
+    "acidcat",
+    "mcp",
+    "webmcp"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Hebilicious/acidcat.git",
+    "directory": "packages/core-ts"
+  },
+  "homepage": "https://github.com/Hebilicious/acidcat/tree/main/packages/core-ts#readme",
+  "bugs": "https://github.com/Hebilicious/acidcat/issues",
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@acid-cat/catalog": "0.2.0",
+    "@acid-cat/spec-ts": "0.2.0"
+  },
+  "devDependencies": {
+    "@acid-cat/cli": "0.2.0",
+    "@types/node": "26.6.5",
+    "esbuild": "0.28.2",
+    "playwright": "1.64.0",
+    "typescript": "7.0.2",
+    "zod": "4.6.7"
+  }
 }