ankka 0.11.0 → 0.13.0

package/dist/index.d.ts

@@ -5,7 +5,7 @@ export { EncodingError, DecodingError, renderDouble } from "./json.ts";
 export { Instant, Duration, LocalDate, LocalDateTime } from "./time.ts";
 export { ErrorCode, CommandError, Outcome, Retention, httpStatusOf, type ErrorDetail, type Metadata, type EffectLike, type ReadOnlyLike } from "./effects/common.ts";
 export { command, query, stream, step, action, tool, guardrail, type HandlerRef, type ToolRef, type GuardrailRef, type GuardrailStage, type HandlerTable } from "./handlers.ts";
-export { PersistBuilder, EventSourcedEffects, type PersistEffect, type ReadOnlyEffect, type EventSourcedEffect } from "./effects/eventSourced.ts";
+export { PersistBuilder, EventSourcedEffects, type PersistEffect, type ReadOnlyEffect, type EventSourcedEffect, type ReplicationChange } from "./effects/eventSourced.ts";
 export { EventSourcedEntity, type EventSourcedEntityClass } from "./eventSourcedEntity.ts";
 export { UpdateBuilder, KeyValueEffects, type UpdateEffect, type KeyValueReadOnlyEffect, type KeyValueEffect } from "./effects/keyValue.ts";
 export { KeyValueEntity, type KeyValueEntityClass } from "./keyValueEntity.ts";
@@ -25,15 +25,21 @@ export { ApprovalAwaited, APPROVALS_SINCE, type AgentOutcome, type Approval, typ
 export { mcpServer, resultGuardrail, toolName, type McpServerOptions, type McpServerRef, type ResultGuardrailRef } from "./mcp.ts";
 export { AutonomousAgent, AutonomousAgentCalls, TaskCalls, Tasks, accepted, rejected, taskAcceptance, taskRule, taskType, type Accepted, type AgentState, type Attachment, type AutonomousAgentClass, type AutonomousSettings, type Notification, type Rejected, type TaskAcceptance, type TaskRule, type TaskSnapshot, type TaskType, } from "./autonomous.ts";
 export { Endpoint, type EndpointClass } from "./endpoint.ts";
+export { McpEndpoint, ToolTable, tools, MCP_ENDPOINTS_SINCE, type McpEndpointClass, type DeclaredTool, type ToolOptions, type ReferenceOptions, type RegisteredMcpEndpoint, type RegisteredMcpTool, type ToolRun, } from "./mcp-endpoint.ts";
+export { ClientKeys, InMemoryClientKeys, Expiry, CLIENT_KEYS_SINCE, type IssueClientKey, type IssuedClientKey, type ClientKeySummary, } from "./client-keys.ts";
 export { type Socket, SocketClosed } from "./socket.ts";
-export { Acl, Callers, type CallerMatcher, type CallersAcl, HttpProblem, get, post, put, patch, del, sse, sseEvent, type SseEvent, socket, type RouteRef, type RouteOptions, type RouteTable, type Params, type ParamNames, type HttpMethod } from "./routes.ts";
-export { type CommandContext, type RequestContext, type Principal, type Caller, Query, Headers } from "./context.ts";
-export { ComponentClient, Calls, TypedCalls, Invocation, Views, Timers, Secrets, InMemorySecrets, noSecrets, type TimerTarget, type TimedActionTarget, type ComponentRef } from "./client.ts";
+export { Acl, Callers, type CallerMatcher, type CallersAcl, type AnyOfAcl, HttpProblem, get, post, put, patch, del, sse, sseEvent, sseEvents, type SseEvent, socket, type RouteRef, type RouteOptions, type RouteTable, type Params, type ParamNames, type HttpMethod } from "./routes.ts";
+export { type CommandContext, type EventContext, type RequestContext, type Principal, type Caller, Query, Headers } from "./context.ts";
+export { ComponentClient, Calls, TypedCalls, Invocation, AwaitingInvocation, AWAIT_SINCE, awaitPartJson, Views, Timers, Secrets, InMemorySecrets, noSecrets, WatchEnded, VIEW_STREAMS_SINCE, type AwaitPart, type WatchEvent, type WatchOptions, type Overflow, type TimerTarget, type TimedActionTarget, type ComponentRef } from "./client.ts";
+export { ObjectRules, StorageRefusals, InMemoryBuckets, DirectoryBuckets, S3Buckets, S3Bucket, noStorage, chooseStorage, declaredBuckets, processStorage, s3Settings, bucketNameOf, bucketVariableSuffix, localAddress, STORAGE_PATH, type Buckets, type Bucket, type BucketExposure, type SignedAccess, type StoredObject, type ObjectInfo, type ObjectEntry, type PutOptions, type InMemoryBucketsOptions, type DirectoryBucketsOptions, type DeclaredBuckets, type S3Settings, type S3Target, type NamedTarget, type StorageBackend, type ChosenStorage, type StorageChoiceOptions, } from "./storage.ts";
+export { Credentials, SignedRequest, sign as signRequest, presign as presignUrl } from "./sigv4.ts";
 export { Services, ServiceClient, ScriptedServices, noServices, ServiceError, ServiceUnresolvable, ServiceIdentityMismatch, ServiceUnanswered, ServiceCallFailed, type ServiceResponse, type ServiceRequest, type ServiceHeaders, } from "./services.ts";
 export { Ankka, ServiceBuilder, Registry, RegistrationError, type ServiceOptions, type RegisteredComponent, type RegisteredEndpoint, type Source, type RegisteredEventSourced, type RegisteredKeyValue, type RegisteredWorkflow, type RegisteredView, type RegisteredKeyedView, type RegisteredKeyedSource, type RegisteredConsumer, type RegisteredTimedAction, type RegisteredAgent, } from "./service.ts";
 export { Server, type ServerOptions } from "./server/server.ts";
 export { problems as sidecarProblems } from "./server/discovery.ts";
+export { createMcpDispatcher, type McpDispatcher, type ToolAnswer } from "./server/mcp.ts";
 export { PROTOCOL_VERSION, SDK_NAME } from "./spec.ts";
 export { StartFrom } from "./startFrom.ts";
+export { isTerminal, isUnknown, type Standing, type StandingStatus } from "./standing.ts";
 export { materialiseEventSourced, materialiseKeyValue, materialiseWorkflowCommand, materialiseStep, type Materialised, type MaterialisedKeyValue, type MaterialisedWorkflowCommand, type MaterialisedStep, } from "./materialise.ts";
 export type { ComponentKind } from "./kinds.ts";

package/dist/index.js

@@ -36,14 +36,20 @@ export { ApprovalAwaited, APPROVALS_SINCE } from "./approvals.js";
 export { mcpServer, resultGuardrail, toolName } from "./mcp.js";
 export { AutonomousAgent, AutonomousAgentCalls, TaskCalls, Tasks, accepted, rejected, taskAcceptance, taskRule, taskType, } from "./autonomous.js";
 export { Endpoint } from "./endpoint.js";
+export { McpEndpoint, ToolTable, tools, MCP_ENDPOINTS_SINCE, } from "./mcp-endpoint.js";
+export { ClientKeys, InMemoryClientKeys, Expiry, CLIENT_KEYS_SINCE, } from "./client-keys.js";
 export { SocketClosed } from "./socket.js";
-export { Acl, Callers, HttpProblem, get, post, put, patch, del, sse, sseEvent, socket } from "./routes.js";
+export { Acl, Callers, HttpProblem, get, post, put, patch, del, sse, sseEvent, sseEvents, socket } from "./routes.js";
 export { Query, Headers } from "./context.js";
-export { ComponentClient, Calls, TypedCalls, Invocation, Views, Timers, Secrets, InMemorySecrets, noSecrets } from "./client.js";
+export { ComponentClient, Calls, TypedCalls, Invocation, AwaitingInvocation, AWAIT_SINCE, awaitPartJson, Views, Timers, Secrets, InMemorySecrets, noSecrets, WatchEnded, VIEW_STREAMS_SINCE } from "./client.js";
+export { ObjectRules, StorageRefusals, InMemoryBuckets, DirectoryBuckets, S3Buckets, S3Bucket, noStorage, chooseStorage, declaredBuckets, processStorage, s3Settings, bucketNameOf, bucketVariableSuffix, localAddress, STORAGE_PATH, } from "./storage.js";
+export { Credentials, SignedRequest, sign as signRequest, presign as presignUrl } from "./sigv4.js";
 export { Services, ServiceClient, ScriptedServices, noServices, ServiceError, ServiceUnresolvable, ServiceIdentityMismatch, ServiceUnanswered, ServiceCallFailed, } from "./services.js";
 export { Ankka, ServiceBuilder, Registry, RegistrationError, } from "./service.js";
 export { Server } from "./server/server.js";
 export { problems as sidecarProblems } from "./server/discovery.js";
+export { createMcpDispatcher } from "./server/mcp.js";
 export { PROTOCOL_VERSION, SDK_NAME } from "./spec.js";
 export { StartFrom } from "./startFrom.js";
+export { isTerminal, isUnknown } from "./standing.js";
 export { materialiseEventSourced, materialiseKeyValue, materialiseWorkflowCommand, materialiseStep, } from "./materialise.js";

package/dist/keyedView.d.ts

@@ -3,6 +3,7 @@ import type { Metadata } from "./effects/common.ts";
 import type { ComponentClient, ComponentRef } from "./client.ts";
 import { KeyedViewEffects, type KeyedViewEffect } from "./effects/keyed.ts";
 import type { DeclaredQuery } from "./view.ts";
+import type { Standing } from "./standing.ts";
 type MaybePromise<T> = T | Promise<T>;
 /** A keyed view's own rows, for the length of one change. It reaches no other view. */
 export interface ViewRows<Row> {
@@ -32,13 +33,15 @@ export declare abstract class KeyedView<Row> {
     get metadata(): Metadata;
     /** The id of the entity the change came from. */
     get subject(): string;
+    /** Of a change from a workflow: where it stood once the effect that recorded the state was applied. `undefined` for a change from an entity or a topic. */
+    get standing(): Standing | undefined;
     /** This view's own rows, by key or by one of its declared queries. */
     get rows(): ViewRows<Row>;
     get client(): ComponentClient;
     /** @internal */
     get _kind(): "view";
     /** @internal */
-    _bind(metadata: Metadata, client: ComponentClient | undefined, rows: ViewRows<Row>): void;
+    _bind(metadata: Metadata, client: ComponentClient | undefined, rows: ViewRows<Row>, standing?: Standing): void;
 }
 export interface KeyedViewClass<Row = unknown, C extends KeyedView<Row> = KeyedView<Row>> {
     new (): C;

package/dist/keyedView.js

@@ -26,6 +26,7 @@ export function on(source, events, onChange, options = {}) {
 export class KeyedView {
     effects = new KeyedViewEffects();
     #metadata = {};
+    #standing = undefined;
     #client;
     #rows;
     /** The change's metadata: `ce-subject` is the source entity's id, `ankka.sequence` its sequence number. */
@@ -36,6 +37,10 @@ export class KeyedView {
     get subject() {
         return this.#metadata["ce-subject"] ?? "";
     }
+    /** Of a change from a workflow: where it stood once the effect that recorded the state was applied. `undefined` for a change from an entity or a topic. */
+    get standing() {
+        return this.#standing;
+    }
     /** This view's own rows, by key or by one of its declared queries. */
     get rows() {
         if (!this.#rows)
@@ -52,8 +57,9 @@ export class KeyedView {
         return "view";
     }
     /** @internal */
-    _bind(metadata, client, rows) {
+    _bind(metadata, client, rows, standing) {
         this.#metadata = metadata;
+        this.#standing = standing;
         this.#client = client;
         this.#rows = rows;
     }

package/dist/kinds.js

@@ -30,6 +30,8 @@ const CODE_TO_PROTO = Object.freeze({
     CONFLICT: ProtoErrorCode.CONFLICT,
     TIMEOUT: ProtoErrorCode.TIMEOUT,
     UNAVAILABLE: ProtoErrorCode.UNAVAILABLE,
+    WORKFLOW_FAILED: ProtoErrorCode.WORKFLOW_FAILED,
+    NOT_HOME: ProtoErrorCode.NOT_HOME,
 });
 export function errorCodeToProto(code) {
     return CODE_TO_PROTO[code];

package/dist/mcp-endpoint.d.ts

@@ -0,0 +1,144 @@
+import { type Codec, type Shape } from "./codec.ts";
+import type { ComponentRef } from "./client.ts";
+import { Endpoint } from "./endpoint.ts";
+import type { HandlerRef } from "./handlers.ts";
+import { type Acl, type HttpMethod, type RouteRef } from "./routes.ts";
+import type { ComponentKind } from "./kinds.ts";
+import type { EndpointClass } from "./endpoint.ts";
+import type { RegisteredComponent, RegisteredEndpoint } from "./service.ts";
+type MaybePromise<T> = T | Promise<T>;
+/** The first protocol whose runtime serves a process's MCP endpoint. */
+export declare const MCP_ENDPOINTS_SINCE = "1.20";
+/** What a tool name may be: what MCP clients accept everywhere. */
+export declare const TOOL_NAME: RegExp;
+/**
+ * The base of an MCP endpoint. One instance serves every call, so the call's principal and caller are
+ * on `this.request`, as for an HTTP endpoint; `client`, `secrets`, `services` and `clientKeys` likewise.
+ */
+export declare abstract class McpEndpoint extends Endpoint {
+}
+/** One tool as declared, before its references are resolved. */
+export type DeclaredTool<Ep> = {
+    readonly kind: "tool";
+    readonly name: string;
+    readonly description: string;
+    readonly input: Shape<any>;
+    readonly reply: Shape<any> | undefined;
+    readonly run: (args: any, self: Ep) => MaybePromise<unknown>;
+    readonly acl: Acl | undefined;
+} | {
+    readonly kind: "command" | "query";
+    readonly name: string;
+    readonly description: string;
+    readonly component: ComponentRef;
+    readonly handler: string;
+    /** The argument holding the entity's or workflow's id. */
+    readonly id: string;
+    /** The argument holding the handler's input; absent merges a record input's fields beside the id. */
+    readonly input: string | undefined;
+    readonly acl: Acl | undefined;
+} | {
+    readonly kind: "route";
+    readonly name: string;
+    readonly description: string;
+    readonly endpoint: EndpointClass<any>;
+    readonly method: HttpMethod;
+    /** The full path: the endpoint's prefix and the route's template, `/orders/{day}`. */
+    readonly path: string;
+    readonly acl: Acl | undefined;
+};
+export interface ToolOptions {
+    /** Who may call this tool, beside the endpoint's rule; client keys and `anyOf` are allowed. */
+    readonly acl?: Acl;
+}
+export interface ReferenceOptions extends ToolOptions {
+    /** The argument that names the entity or workflow. */
+    readonly id: string;
+    /** The argument holding the handler's input, when it is not to be merged beside the id. */
+    readonly input?: string;
+}
+/** The tools of an MCP endpoint, built as `tools<CartMcp>().tool(...).command(...)`. */
+export declare class ToolTable<Ep = McpEndpoint> {
+    #private;
+    readonly declared: readonly DeclaredTool<Ep>[];
+    constructor(declared?: readonly DeclaredTool<Ep>[]);
+    /**
+     * A tool this process runs: its arguments decoded with `input` (a record schema becomes the tool's
+     * object schema), its answer encoded with `reply` (a string answers as text; an object also as
+     * structured content). A thrown error or a refusal is the tool error the client is shown.
+     */
+    tool<I, R>(name: string, description: string, input: Shape<I>, reply: Shape<R> | undefined, run: (args: I, self: Ep) => MaybePromise<R>, options?: ToolOptions): ToolTable<Ep>;
+    /** A tool that runs a command of a component, by its wire name: `command("checkout", "...", ShoppingCart, "checkout", { id: "cartId" })`. */
+    command(name: string, description: string, component: ComponentRef, handler: string | HandlerRef<any, any, any, any>, options: ReferenceOptions): ToolTable<Ep>;
+    /** A tool that runs a query of a component; it cannot change anything. */
+    query(name: string, description: string, component: ComponentRef, handler: string | HandlerRef<any, any, any, any>, options: ReferenceOptions): ToolTable<Ep>;
+    /** A tool that calls a route of one of this service's endpoints, in process: its path names are the arguments, and `body` the body. */
+    route(name: string, description: string, endpoint: EndpointClass<any>, method: HttpMethod, path: string, options?: ToolOptions): ToolTable<Ep>;
+}
+/** An empty tool table to build on. */
+export declare function tools<Ep = McpEndpoint>(): ToolTable<Ep>;
+/** The statics an MCP endpoint class declares; `register` constrains on this type. */
+export interface McpEndpointClass<C extends McpEndpoint = McpEndpoint> {
+    new (): C;
+    /** `/mcp`: where the endpoint is served, on the service's own hostnames. */
+    readonly path: string;
+    /** Who may connect: `Acl.clientKeys`, `Acl.authenticated`, `Acl.anyOf(...)`. There is no default. */
+    readonly acl: Acl;
+    readonly tools: ToolTable<C>;
+    /** The platform signs people in for clients that cannot hold a token (needs `authenticated` in the rule). */
+    readonly brokered?: boolean;
+    /** The server's name in `initialize`; the class name when absent. */
+    readonly serverName?: string;
+    readonly serverVersion?: string;
+}
+/** How a resolved tool is run; data the server interprets. */
+export type ToolRun = {
+    readonly kind: "function";
+    readonly input: Shape<any>;
+    readonly reply: Shape<any> | undefined;
+    readonly run: (args: any, self: McpEndpoint) => MaybePromise<unknown>;
+} | {
+    readonly kind: "handler";
+    readonly componentKind: ComponentKind;
+    readonly componentId: string;
+    readonly handler: HandlerRef<any, any, any, any>;
+    readonly id: string;
+    /** `merge`: a record input's fields sit beside the id; a name: the input is that argument; absent: there is none. */
+    readonly input: {
+        readonly kind: "merge";
+    } | {
+        readonly kind: "argument";
+        readonly name: string;
+    } | undefined;
+} | {
+    readonly kind: "route";
+    readonly endpointId: string;
+    readonly route: RouteRef<any, any, any, any>;
+    readonly paramNames: readonly string[];
+};
+export interface RegisteredMcpTool {
+    readonly name: string;
+    readonly description: string;
+    /** The JSON Schema of the arguments, which the platform checks before the process is asked. */
+    readonly inputSchema: Record<string, unknown>;
+    readonly acl: Acl | undefined;
+    readonly run: ToolRun;
+}
+export interface RegisteredMcpEndpoint {
+    readonly id: string;
+    readonly cls: McpEndpointClass<any>;
+    readonly path: string;
+    readonly acl: Acl;
+    readonly tools: readonly RegisteredMcpTool[];
+    readonly brokered: boolean;
+    readonly serverName: string | undefined;
+    readonly serverVersion: string | undefined;
+}
+/**
+ * Resolves an MCP endpoint class against the registered components and endpoints, collecting every
+ * problem. A reference to a component or route that is not registered is refused here, before start.
+ */
+export declare function registerMcpEndpoint(cls: McpEndpointClass<any>, components: ReadonlyMap<string, RegisteredComponent>, endpoints: ReadonlyMap<string, RegisteredEndpoint>, problems: string[]): RegisteredMcpEndpoint | undefined;
+/** The codec a tool's own reply is encoded with, when it declares one. */
+export declare function replyCodecOf(reply: Shape<any> | undefined): Codec<unknown> | undefined;
+export {};

package/dist/mcp-endpoint.js

@@ -0,0 +1,256 @@
+// An MCP endpoint (protocol 1.20): a path, an access rule and a table of tools, which the platform
+// serves to any MCP client over Streamable HTTP. The platform answers the protocol, verifies the
+// credential (a client key or a token), checks the arguments against each tool's schema and asks this
+// process to run the tool; the process never sees the credential, only the principal it stood for.
+//
+//   export class CartMcp extends McpEndpoint {
+//     static readonly path = "/mcp"
+//     static readonly acl = Acl.anyOf(Acl.clientKeys, Acl.authenticated)
+//     static readonly tools = tools<CartMcp>()
+//       .tool("get_cart", "Reads one cart", s.record("GetCart", { cartId: s.string }), Cart,
+//             (args, ep) => ep.client.of(ShoppingCart, args.cartId).call(ShoppingCart.handlers.getCart).invoke())
+//       .command("checkout", "Checks a cart out", ShoppingCart, "checkout", { id: "cartId" })
+//   }
+//
+// A tool is either run by this process's own function, or a reference to a component's handler or to
+// a route of one of this service's endpoints. References are resolved at registration, so one that
+// names something not registered stops the service before it starts.
+var _a;
+import { codecFor, isCodec } from "./codec.js";
+import { Endpoint } from "./endpoint.js";
+import { isAcl, parseTemplate } from "./routes.js";
+import { resolve, toJsonSchema } from "./schema.js";
+/** The first protocol whose runtime serves a process's MCP endpoint. */
+export const MCP_ENDPOINTS_SINCE = "1.20";
+/** What a tool name may be: what MCP clients accept everywhere. */
+export const TOOL_NAME = /^[a-z0-9_-]{1,128}$/;
+/**
+ * The base of an MCP endpoint. One instance serves every call, so the call's principal and caller are
+ * on `this.request`, as for an HTTP endpoint; `client`, `secrets`, `services` and `clientKeys` likewise.
+ */
+export class McpEndpoint extends Endpoint {
+}
+/** The tools of an MCP endpoint, built as `tools<CartMcp>().tool(...).command(...)`. */
+export class ToolTable {
+    declared;
+    constructor(declared = []) {
+        this.declared = Object.freeze([...declared]);
+        Object.freeze(this);
+    }
+    #with(tool) {
+        return new _a([...this.declared, Object.freeze(tool)]);
+    }
+    /**
+     * A tool this process runs: its arguments decoded with `input` (a record schema becomes the tool's
+     * object schema), its answer encoded with `reply` (a string answers as text; an object also as
+     * structured content). A thrown error or a refusal is the tool error the client is shown.
+     */
+    tool(name, description, input, reply, run, options) {
+        return this.#with({ kind: "tool", name, description, input, reply, run: run, acl: options?.acl });
+    }
+    /** A tool that runs a command of a component, by its wire name: `command("checkout", "...", ShoppingCart, "checkout", { id: "cartId" })`. */
+    command(name, description, component, handler, options) {
+        return this.#reference("command", name, description, component, handler, options);
+    }
+    /** A tool that runs a query of a component; it cannot change anything. */
+    query(name, description, component, handler, options) {
+        return this.#reference("query", name, description, component, handler, options);
+    }
+    /** A tool that calls a route of one of this service's endpoints, in process: its path names are the arguments, and `body` the body. */
+    route(name, description, endpoint, method, path, options) {
+        return this.#with({ kind: "route", name, description, endpoint, method, path, acl: options?.acl });
+    }
+    #reference(kind, name, description, component, handler, options) {
+        const wire = typeof handler === "string" ? handler : handler?.name;
+        return this.#with({ kind, name, description, component, handler: wire, id: options?.id, input: options?.input, acl: options?.acl });
+    }
+}
+_a = ToolTable;
+/** An empty tool table to build on. */
+export function tools() {
+    return new ToolTable();
+}
+function hasTokens(acl) {
+    if (acl === "authenticated")
+        return true;
+    return typeof acl === "object" && acl.kind === "anyOf" && acl.acls.some(hasTokens);
+}
+function objectSchema(properties, required) {
+    return { type: "object", properties, required, additionalProperties: false };
+}
+/** The JSON Schema of a tool's own input: an object schema, whatever the shape (a codec admits any object). */
+function inputSchemaOf(input) {
+    if (isCodec(input))
+        return { type: "object" };
+    const schema = toJsonSchema(input);
+    if (schema.type !== "object")
+        return `its input must be a record, so its arguments are an object; it is ${String(resolve(input).kind)}`;
+    return schema;
+}
+/**
+ * Resolves an MCP endpoint class against the registered components and endpoints, collecting every
+ * problem. A reference to a component or route that is not registered is refused here, before start.
+ */
+export function registerMcpEndpoint(cls, components, endpoints, problems) {
+    const name = typeof cls === "function" && cls.name ? cls.name : String(cls);
+    let ok = true;
+    const fail = (m) => {
+        problems.push(`${name}: ${m}`);
+        ok = false;
+    };
+    const path = cls.path;
+    if (typeof path !== "string" || !path.startsWith("/") || (path.length > 1 && path.endsWith("/")) || path.includes("{")) {
+        fail(`needs a static path starting with "/", with no parameters and not ending with "/", not ${JSON.stringify(path)}`);
+    }
+    else if (path.startsWith("/_ankka/"))
+        fail(`path ${path} is the platform's`);
+    if (!isAcl(cls.acl))
+        fail("needs a static acl — Acl.clientKeys, Acl.authenticated, Acl.anyOf(...) or another rule. An unstated access rule is a decision nobody made");
+    if (cls.brokered !== undefined && typeof cls.brokered !== "boolean")
+        fail("brokered must be true or false");
+    if (cls.brokered === true && isAcl(cls.acl) && !hasTokens(cls.acl))
+        fail("is brokered, which signs people in with the service's issuer; its acl must admit Acl.authenticated");
+    for (const [what, value] of [["serverName", cls.serverName], ["serverVersion", cls.serverVersion]]) {
+        if (value !== undefined && (typeof value !== "string" || value.trim() === ""))
+            fail(`${what} must be a non-empty string`);
+    }
+    const table = cls.tools;
+    if (!(table instanceof ToolTable)) {
+        fail("needs a static tools table: tools().tool(...)");
+        return undefined;
+    }
+    if (table.declared.length === 0)
+        fail("declares no tool; an MCP endpoint needs at least one");
+    const resolved = [];
+    const seen = new Set();
+    for (const t of table.declared) {
+        const where = `tool '${t.name}'`;
+        if (typeof t.name !== "string" || !TOOL_NAME.test(t.name)) {
+            fail(`tool '${String(t.name)}' is not a tool name ([a-z0-9_-]+, at most 128 characters)`);
+            continue;
+        }
+        if (seen.has(t.name))
+            fail(`declares the tool '${t.name}' twice`);
+        seen.add(t.name);
+        if (typeof t.description !== "string" || t.description.trim() === "")
+            fail(`${where} needs a description; it is what a model reads to choose it`);
+        if (t.acl !== undefined && !isAcl(t.acl))
+            fail(`${where}: unknown acl ${JSON.stringify(t.acl)}`);
+        const tool = resolveTool(t, where, components, endpoints, fail);
+        if (tool)
+            resolved.push(tool);
+    }
+    if (!ok)
+        return undefined;
+    return Object.freeze({
+        id: name,
+        cls,
+        path,
+        acl: cls.acl,
+        tools: Object.freeze(resolved),
+        brokered: cls.brokered === true,
+        serverName: cls.serverName,
+        serverVersion: cls.serverVersion,
+    });
+}
+function resolveTool(t, where, components, endpoints, fail) {
+    const base = { name: t.name, description: t.description, acl: t.acl };
+    switch (t.kind) {
+        case "tool": {
+            if (typeof t.run !== "function") {
+                fail(`${where}: the handler is not a function`);
+                return undefined;
+            }
+            const schema = typeof t.input === "object" && t.input !== null ? inputSchemaOf(t.input) : "it needs an input shape";
+            if (typeof schema === "string") {
+                fail(`${where}: ${schema}`);
+                return undefined;
+            }
+            return Object.freeze({ ...base, inputSchema: schema, run: Object.freeze({ kind: "function", input: t.input, reply: t.reply, run: t.run }) });
+        }
+        case "command":
+        case "query": {
+            const componentId = t.component?.componentId;
+            const registered = typeof componentId === "string" ? components.get(componentId) : undefined;
+            if (!registered || registered.cls !== t.component) {
+                fail(`${where} refers to the component ${typeof componentId === "string" ? componentId : String(t.component)}, which is not registered`);
+                return undefined;
+            }
+            if (registered.kind !== "event-sourced" && registered.kind !== "key-value" && registered.kind !== "workflow") {
+                fail(`${where} refers to ${registered.id}, a ${registered.kind}; a reference names an entity's or a workflow's handler`);
+                return undefined;
+            }
+            const handler = registered.handlers.get(t.handler);
+            if (!handler) {
+                fail(`${where} refers to the handler '${String(t.handler)}' of ${registered.id}, which it does not declare`);
+                return undefined;
+            }
+            if (t.kind === "query" && !handler.readOnly)
+                fail(`${where} is a query of '${handler.name}', which is a command`);
+            if (t.kind === "command" && handler.readOnly)
+                fail(`${where} is a command of '${handler.name}', which is a query; declare it with query(...)`);
+            if (handler.streaming)
+                fail(`${where} refers to '${handler.name}', which streams; a tool answers once`);
+            if (typeof t.id !== "string" || t.id.trim() === "") {
+                fail(`${where} needs the argument that names the ${registered.kind === "workflow" ? "workflow" : "entity"}: { id: "cartId" }`);
+                return undefined;
+            }
+            const properties = { [t.id]: { type: "string", description: `The id of the ${registered.id}` } };
+            const required = [t.id];
+            let input;
+            if (handler.input !== undefined) {
+                const shape = handler.input;
+                const json = isCodec(shape) ? { type: "object" } : toJsonSchema(shape);
+                if (t.input !== undefined || json.type !== "object" || isCodec(shape)) {
+                    const argument = t.input ?? "input";
+                    if (argument === t.id)
+                        fail(`${where}: the id and the input are both the argument '${argument}'`);
+                    properties[argument] = json;
+                    required.push(argument);
+                    input = { kind: "argument", name: argument };
+                }
+                else {
+                    const fields = (json.properties ?? {});
+                    if (t.id in fields)
+                        fail(`${where}: the input has a field '${t.id}', which is the id's argument; name the input with { input: "..." }`);
+                    Object.assign(properties, fields);
+                    required.push(...(json.required ?? []));
+                    input = { kind: "merge" };
+                }
+            }
+            else if (t.input !== undefined)
+                fail(`${where} names an input argument, but '${handler.name}' takes no input`);
+            return Object.freeze({
+                ...base,
+                inputSchema: objectSchema(properties, required),
+                run: Object.freeze({ kind: "handler", componentKind: registered.kind, componentId: registered.id, handler, id: t.id, input }),
+            });
+        }
+        case "route": {
+            const endpoint = [...endpoints.values()].find((e) => e.cls === t.endpoint);
+            if (!endpoint) {
+                fail(`${where} refers to the endpoint ${typeof t.endpoint === "function" ? t.endpoint.name : String(t.endpoint)}, which is not registered`);
+                return undefined;
+            }
+            const relative = typeof t.path === "string" && t.path.startsWith(endpoint.prefix) ? t.path.slice(endpoint.prefix === "/" ? 0 : endpoint.prefix.length) || "/" : undefined;
+            const route = relative === undefined ? undefined : [...endpoint.routes.values()].find((r) => r.method === t.method && r.template === relative);
+            if (!route) {
+                fail(`${where} refers to ${t.method} ${t.path}, which ${endpoint.id} does not declare`);
+                return undefined;
+            }
+            if (route.streaming || route.socket) {
+                fail(`${where} refers to ${t.method} ${t.path}, which streams; a tool answers once`);
+                return undefined;
+            }
+            const paramNames = parseTemplate(route.template);
+            const properties = Object.fromEntries(paramNames.map((n) => [n, { type: "string" }]));
+            if (route.body !== undefined)
+                properties.body = { type: "object" };
+            return Object.freeze({ ...base, inputSchema: objectSchema(properties, [...paramNames]), run: Object.freeze({ kind: "route", endpointId: endpoint.id, route, paramNames }) });
+        }
+    }
+}
+/** The codec a tool's own reply is encoded with, when it declares one. */
+export function replyCodecOf(reply) {
+    return reply === undefined ? undefined : codecFor(reply);
+}

package/dist/routes.d.ts

@@ -13,15 +13,20 @@ export type CallerMatcher = {
     readonly kind: "anyInProject";
 } | {
     readonly kind: "self";
+} | {
+    readonly kind: "granted";
 };
 /**
  * The callers an endpoint can name: `Acl.allowCallers(Callers.internet, Callers.service("orders"))`. A named
- * service is in this service's own project unless `project` names another.
+ * service is in this service's own project unless `project` names another. `Callers.granted` is whoever this
+ * service's project has granted the route to — a service of another project, or a registered machine
+ * (protocol 1.15); a route that does not name it can never be granted.
  */
 export declare const Callers: Readonly<{
     internet: CallerMatcher;
     anyInProject: CallerMatcher;
     self: CallerMatcher;
+    granted: CallerMatcher;
     service(name: string, options?: {
         readonly project?: string;
     }): CallerMatcher;
@@ -31,25 +36,48 @@ export interface CallersAcl {
     readonly kind: "callers";
     readonly callers: readonly CallerMatcher[];
 }
+/** Admitted when any of `acls` admits: an MCP endpoint's rule (protocol 1.20), `Acl.anyOf(Acl.clientKeys, Acl.authenticated)`. */
+export interface AnyOfAcl {
+    readonly kind: "anyOf";
+    readonly acls: readonly Acl[];
+}
 /**
  * Who may call: everyone, no one, authenticated callers only, or only the callers named. There is no default.
+ * An MCP endpoint may also admit a client key issued for it (`Acl.clientKeys`), and any of several rules
+ * (`Acl.anyOf`); an HTTP endpoint refuses both at registration.
  *
  * Outside a cluster every caller is `{ kind: "local" }`, and `allowCallers` admits it.
  */
-export type Acl = "allow-all" | "deny-all" | "authenticated" | CallersAcl;
+export type Acl = "allow-all" | "deny-all" | "authenticated" | "client-keys" | CallersAcl | AnyOfAcl;
 export declare const Acl: Readonly<{
     allowAll: Acl;
     denyAll: Acl;
     authenticated: Acl;
+    /** A client key issued for the MCP endpoint (protocol 1.20); its subject and attributes are the principal. */
+    clientKeys: Acl;
     allowCallers(first: CallerMatcher, ...rest: CallerMatcher[]): Acl;
+    /** Admitted when any of the rules admits; for an MCP endpoint or one of its tools. */
+    anyOf(first: Acl, ...rest: Acl[]): Acl;
 }>;
-/** Whether `x` is an access rule: one of the three words, or a non-empty callers rule. */
+/** Whether `x` is an access rule: one of the words, a non-empty callers rule, or a non-empty `anyOf` of rules. */
 export declare function isAcl(x: unknown): x is Acl;
+/** Whether `acl` is one an HTTP endpoint or route can state: neither client keys nor `anyOf`, which are an MCP endpoint's. */
+export declare function isEndpointAcl(acl: Acl): boolean;
 /** Thrown from a route handler to answer a status other than 200 with a plain-text message. */
 export declare class HttpProblem extends Error {
     readonly status: number;
     constructor(status: number, message: string);
 }
+/**
+ * @internal An answer whose status and content type the handler chooses, its body as given: the
+ * directory store's objects, served under the content type each was kept with.
+ */
+export declare class RawReply {
+    readonly status: number;
+    readonly contentType: string;
+    readonly body: Uint8Array;
+    constructor(status: number, contentType: string, body: Uint8Array);
+}
 export type HttpMethod = "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
 type MaybePromise<T> = T | Promise<T>;
 /** The parameter names in a template: `ParamNames<"/{cartId}/items/{productId}">` is `"cartId" | "productId"`. */
@@ -113,6 +141,21 @@ export interface SseEvent {
     readonly name: string;
     readonly value: unknown;
 }
+/**
+ * A watch as server-sent events, for an `sse` route: each row as `row` carrying the key and the row,
+ * each removal as `removed`, the marker as `caught-up`, and a watch that ended with a reason as a last
+ * event `ended` carrying it, so a page is told why.
+ */
+export declare function sseEvents<Row>(watch: AsyncIterable<{
+    readonly kind: "row";
+    readonly key: string;
+    readonly row: Row;
+} | {
+    readonly kind: "removed";
+    readonly key: string;
+} | {
+    readonly kind: "caughtUp";
+}>): AsyncIterable<SseEvent>;
 export declare function sseEvent(name: string, value: unknown): SseEvent;
 /** A server-sent-events route: the handler returns an `AsyncIterable<string | SseEvent>`, one frame per string, and may yield an `SseEvent` among them. */
 export declare function sse<Ep, T extends string, PS extends Readonly<Record<string, Schema>> = {}>(template: T, run: (self: Ep, request: RequestContext<Params<T, PS>>) => AsyncIterable<string | SseEvent> | Promise<AsyncIterable<string | SseEvent>>, options?: RouteOptions<PS>): RouteRef<Ep, Params<T, PS>, undefined, never>;