@acid-cat/core-ts 0.0.0-stage → 0.1.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,68 @@
-# 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 |
+
+## 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/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/http.d.ts

@@ -0,0 +1,17 @@
+import type { App, ToJsonSchema } from "./app.js";
+export interface HttpOptions<Context> {
+    /** The origins that can call the API. A request with no `Origin` header is accepted. */
+    readonly allowedOrigins: readonly string[];
+    readonly context: Context;
+    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. */
+export declare function httpHandler<Context>(app: App<Context>, options: HttpOptions<Context>): (request: Request) => Promise<Response>;

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+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 } from "./mcp.js";
+export { httpHandler } from "./http.js";
+export type { HttpOptions } from "./http.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,610 @@
+// src/app.ts
+import { canonicalText } from "@acid-cat/catalog";
+var defineCapability = (capability) => capability;
+var capabilitiesFor = () => (capability) => capability;
+var defineApp = (app) => app;
+function catalogOf(app, options) {
+  const types = {};
+  const toJson = (schema, where) => {
+    const { $schema: _, $defs, ...json2 } = 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 json2;
+  };
+  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
+  };
+}
+var renderCatalog = (app, options) => canonicalText(catalogOf(app, options));
+
+// src/session.ts
+import { AVAILABLE, CallFailureError, callFailure, isCallFailure, viewOf } from "@acid-cat/spec-ts";
+var always = { getSnapshot: () => AVAILABLE, subscribe: () => ({ unsubscribe() {
+} }) };
+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 });
+  }
+  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(
+      (resolve2) => controller.signal.addEventListener("abort", () => resolve2(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]);
+    }
+  };
+}
+function detached(source) {
+  return {
+    getSnapshot: () => structuredClone(source.getSnapshot()),
+    subscribe: (listener) => source.subscribe((value) => listener(structuredClone(value)))
+  };
+}
+async function checkResult(capability, result) {
+  if (result.ok) {
+    if (capability.output === void 0) return { ok: true, value: result.value ?? null };
+    const checked2 = await capability.output["~standard"].validate(result.value);
+    if (checked2.issues !== void 0) throw new Error(`The output does not agree with its schema: ${checked2.issues[0]?.message}`);
+    return { ok: true, value: checked2.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 } };
+}
+
+// src/mcp.ts
+import { bundle, MCP_PROTOCOL_VERSION, MCP_REJECTIONS, MCP_UNKNOWN_TOOL, mcpToolResult, readBounded, screenRequest } from "@acid-cat/spec-ts";
+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");
+    const session = createSession(app, {
+      target: options.target ?? "mcp",
+      context: options.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 });
+}
+var 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."
+};
+
+// src/http.ts
+import { callFailure as callFailure2, httpStatus, isCallFailure as isCallFailure2, readBounded as readBounded2, screenRequest as screenRequest2 } from "@acid-cat/spec-ts";
+function httpHandler(app, options) {
+  const maximumBytes = options.maximumBytes ?? 1048576;
+  return async (request) => {
+    const screened = screenRequest2(request, {
+      methods: ["GET", "POST"],
+      allowedOrigins: options.allowedOrigins,
+      mediaType: "application/json",
+      maximumBytes
+    });
+    if (screened !== void 0) return rejection2(screened);
+    const path = new URL(request.url).pathname.slice((options.base ?? "").length);
+    const session = createSession(app, { target: options.target ?? "api", context: options.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("/capabilities/".length) : void 0;
+      if (id === void 0) return json(404, callFailure2("unknown-capability", "There is no such route."));
+      const body = await readBounded2(request, maximumBytes);
+      if ("rejection" in body) return rejection2(body.rejection);
+      let input;
+      try {
+        input = body.text === "" ? {} : JSON.parse(body.text);
+      } catch {
+        return json(422, callFailure2("invalid-input", "The request body is not JSON."));
+      }
+      const outcome = await session.invoke(decodeURIComponent(id), input, { signal: request.signal });
+      return json(httpStatus(outcome), isCallFailure2(outcome) ? { kind: outcome.kind, message: outcome.message } : outcome);
+    } finally {
+      await session.dispose();
+    }
+  };
+}
+var json = (status, body) => new Response(JSON.stringify(body), { status, headers: { "Content-Type": "application/json" } });
+var statuses = {
+  method: 405,
+  origin: 403,
+  "media-type": 415,
+  "too-large": 413,
+  "not-utf8": 400
+};
+function rejection2(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 });
+}
+
+// src/cli.ts
+import { bundle as bundle2, CLI_EXIT_CODES, cliExitCode, commandPath, isCallFailure as isCallFailure3, REFERENCE } from "@acid-cat/spec-ts";
+var UsageError = class extends Error {
+  exitCode;
+  constructor(message, exitCode) {
+    super(message);
+    this.exitCode = exitCode;
+  }
+};
+function main(app, options) {
+  const interrupt = new AbortController();
+  process.once("SIGINT", () => interrupt.abort());
+  void runCli(app, options, process.argv.slice(2), {
+    stdout: (text) => process.stdout.write(`${text}
+`),
+    stderr: (text) => process.stderr.write(`${text}
+`),
+    signal: interrupt.signal
+  }).then((code) => {
+    process.exitCode = code;
+  });
+}
+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 (isCallFailure3(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 = bundle2(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 (error2) {
+    if (!(error2 instanceof UsageError)) throw error2;
+    io.stderr(error2.message);
+    return error2.exitCode;
+  } finally {
+    await session.dispose();
+  }
+}
+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");
+}
+
+// src/webmcp.ts
+import { bundle as bundle3, CallFailureError as CallFailureError2, isCallFailure as isCallFailure4 } from "@acid-cat/spec-ts";
+function findHost() {
+  const scope = globalThis;
+  for (const candidate of [scope.document?.modelContext, scope.navigator?.modelContext]) {
+    if (typeof candidate?.registerTool === "function") return candidate;
+  }
+  return void 0;
+}
+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: bundle3(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 (isCallFailure4(outcome)) throw new CallFailureError2(outcome);
+          return outcome;
+        });
+        calls.add(call);
+        void call.finally(() => calls.delete(call)).catch(() => void 0);
+        return call;
+      }
+    };
+  };
+  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 (error2) {
+      for (const controller of added.values()) controller.abort();
+      throw error2;
+    }
+    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);
+      }
+    }
+  }
+  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 (error2) {
+          setStatus({ phase: "failed", message: error2 instanceof Error ? error2.message : "A tool could not be registered." });
+          dirty = false;
+        }
+      } while (dirty && !lifetime.signal.aborted);
+    } finally {
+      running = false;
+    }
+  }
+  const subscription = session.onChange(() => void reconcile());
+  void 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 });
+    }
+  };
+}
+
+// src/index.ts
+import { AVAILABLE as AVAILABLE2, CallFailureError as CallFailureError3, fail, ok, unavailable } from "@acid-cat/spec-ts";
+export {
+  AVAILABLE2 as AVAILABLE,
+  CallFailureError3 as 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,15 @@
+import type { App, ToJsonSchema } from "./app.js";
+export interface McpOptions<Context> {
+    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 context: Context;
+    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. */
+export declare function mcpHandler<Context>(app: App<Context>, options: McpOptions<Context>): (request: Request) => Promise<Response>;

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/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/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.1.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.1.0",
+    "@acid-cat/spec-ts": "0.1.0"
+  },
+  "devDependencies": {
+    "@acid-cat/cli": "0.1.0",
+    "@types/node": "26.6.5",
+    "esbuild": "0.28.2",
+    "playwright": "1.64.0",
+    "typescript": "7.0.2",
+    "zod": "4.6.7"
+  }
 }