ankka 0.12.0 → 0.14.0

package/dist/server/http.js

@@ -11,7 +11,7 @@ import { Headers, Query, metadataFromProto, withRequest } from "../context.js";
 import { CommandError, ErrorCode, httpStatusOf } from "../effects/common.js";
 import { DecodingError } from "../json.js";
 import { errorCodeToProto } from "../kinds.js";
-import { HttpProblem } from "../routes.js";
+import { HttpProblem, RawReply } from "../routes.js";
 import { done, resolve } from "../schema.js";
 import { SocketClosed, socketOf } from "../socket.js";
 import { AsyncQueue } from "./queue.js";
@@ -25,7 +25,8 @@ function failureReply(message) {
 function messageOf(e) {
     return e instanceof Error ? e.message : String(e);
 }
-function principalOf(req) {
+/** The principal the sidecar verified, for a route or a tool call; never the credential. */
+export function principalOf(req) {
     const p = req.principal;
     if (!p)
         return null;
@@ -40,7 +41,7 @@ function principalOf(req) {
     });
 }
 /** The caller the sidecar established; a sidecar that predates protocol 1.1 sends none, which reads as local. */
-function callerOf(req) {
+export function callerOf(req) {
     const kind = req.caller?.kind;
     switch (kind?.case) {
         case "gateway":
@@ -54,7 +55,7 @@ function callerOf(req) {
     }
 }
 /** A path parameter as its declared schema: strings as they are, scalars through their text codec. */
-function parseParam(name, text, shape) {
+export function parseParam(name, text, shape) {
     if (!shape)
         return text;
     const r = resolve(shape);
@@ -71,6 +72,9 @@ function parseParam(name, text, shape) {
     }
 }
 function encodeResult(route, result) {
+    if (result instanceof RawReply) {
+        return create(HttpReplySchema, { message: { case: "response", value: { status: result.status, contentType: result.contentType, body: result.body, headers: [] } } });
+    }
     if (result === undefined || result === done) {
         return create(HttpReplySchema, { message: { case: "response", value: { status: 204, contentType: "", body: new Uint8Array(), headers: [] } } });
     }
@@ -93,6 +97,8 @@ export function createHttpDispatcher(ctx) {
         if (!instance) {
             instance = new endpoint.cls();
             instance._bindClient(ctx.client);
+            if (ctx.storage)
+                instance.storage = ctx.storage;
             instances.set(endpoint.id, instance);
         }
         try {

package/dist/server/mcp.d.ts

@@ -0,0 +1,17 @@
+import type { ConnectRouter } from "@connectrpc/connect";
+import { type McpToolReply, type McpToolRequest } from "../_proto/ankka/protocol/v1/mcp_pb.ts";
+import { type Shape } from "../codec.ts";
+import type { ServerContext } from "./server.ts";
+/** What a tool answered: its text, and the same as structured content when it is a JSON object. */
+export interface ToolAnswer {
+    readonly text: string;
+    readonly structuredJson?: string;
+}
+/** A tool's result as text and structured content, encoded with its reply shape when it has one. */
+export declare function answerOf(value: unknown, reply: Shape<unknown> | undefined): ToolAnswer;
+export interface McpDispatcher {
+    invokeTool(req: McpToolRequest): Promise<McpToolReply>;
+}
+/** The behaviour behind `Mcp.InvokeTool`, over the registry's MCP endpoints. */
+export declare function createMcpDispatcher(ctx: ServerContext): McpDispatcher;
+export declare function mcpRoutes(router: ConnectRouter, ctx: ServerContext): void;

package/dist/server/mcp.js

@@ -0,0 +1,157 @@
+// A tool of one of this process's MCP endpoints (protocol 1.20). The platform answered the protocol,
+// verified the credential and checked the arguments against the tool's schema; here the tool runs, as
+// a route does in `http.ts`: the call in the async context (`this.request`, with the principal and the
+// caller, never the credential), the run awaited, and its outcome answered as `ok`, `error` (the tool
+// error a client is shown) or `failure` (this process could not run it at all).
+//
+// `createMcpDispatcher` is the whole behaviour; the Connect servicer and the unit tests both call it.
+import { create } from "@bufbuild/protobuf";
+import { Mcp, McpToolReplySchema } from "../_proto/ankka/protocol/v1/mcp_pb.js";
+import { codecFor, isCodec } from "../codec.js";
+import { Headers, Query, metadataFromProto, withRequest } from "../context.js";
+import { CommandError, ErrorCode } from "../effects/common.js";
+import { decodeJsonValue, reviver } from "../json.js";
+import { errorCodeToProto } from "../kinds.js";
+import { HttpProblem } from "../routes.js";
+import { done } from "../schema.js";
+import { callerOf, parseParam, principalOf } from "./http.js";
+const utf8 = new TextEncoder();
+const utf8Decoder = new TextDecoder();
+function messageOf(e) {
+    return e instanceof Error ? e.message : String(e);
+}
+function isPlainObject(x) {
+    return typeof x === "object" && x !== null && !Array.isArray(x);
+}
+function structured(text) {
+    try {
+        return isPlainObject(JSON.parse(text)) ? { text, structuredJson: text } : { text };
+    }
+    catch {
+        return { text };
+    }
+}
+/** A tool's result as text and structured content, encoded with its reply shape when it has one. */
+export function answerOf(value, reply) {
+    if (value === undefined || value === done)
+        return { text: "done" };
+    if (typeof value === "string" && (reply === undefined || codecFor(reply).contentType === "text/plain"))
+        return { text: value };
+    if (reply === undefined)
+        return structured(JSON.stringify(value, (_k, v) => (typeof v === "bigint" ? v.toString() : v)));
+    const codec = codecFor(reply);
+    const text = utf8Decoder.decode(codec.encode(value));
+    return codec.contentType === "application/json" ? structured(text) : { text };
+}
+/** An argument as a handler's input: through its codec when it has one, else its schema. */
+function decodeArgument(shape, raw) {
+    if (isCodec(shape))
+        return shape.decode(utf8.encode(JSON.stringify(raw)));
+    return decodeJsonValue(shape, raw);
+}
+class ToolRefusal extends Error {
+}
+/** The behaviour behind `Mcp.InvokeTool`, over the registry's MCP endpoints. */
+export function createMcpDispatcher(ctx) {
+    const instances = new Map();
+    function instanceOf(id, cls) {
+        let instance = instances.get(id);
+        if (!instance) {
+            instance = new cls();
+            instance._bindClient(ctx.client);
+            instances.set(id, instance);
+        }
+        return instance;
+    }
+    async function runHandler(run, args, self) {
+        const id = args[run.id];
+        if (typeof id !== "string" || id === "")
+            throw new ToolRefusal(`parameter '${run.id}': expected a non-empty string`);
+        const handler = run.handler;
+        let input;
+        if (run.input?.kind === "merge") {
+            const { [run.id]: _id, ...rest } = args;
+            input = decodeArgument(handler.input, rest);
+        }
+        else if (run.input?.kind === "argument") {
+            input = decodeArgument(handler.input, args[run.input.name]);
+        }
+        const client = self.client;
+        const calls = run.componentKind === "event-sourced"
+            ? client.forEventSourcedEntity(run.componentId, id)
+            : run.componentKind === "key-value"
+                ? client.forKeyValueEntity(run.componentId, id)
+                : client.forWorkflow(run.componentId, id);
+        const result = await calls.call(handler.name, handler.input, handler.reply).invoke(input);
+        return answerOf(result, handler.reply);
+    }
+    async function runRoute(run, args, call) {
+        const endpoint = ctx.registry.endpoint(run.endpointId);
+        if (!endpoint)
+            throw new Error(`the endpoint ${run.endpointId} is not registered`);
+        const route = run.route;
+        const params = {};
+        for (const name of run.paramNames) {
+            const raw = args[name];
+            if (typeof raw !== "string" && typeof raw !== "number")
+                throw new ToolRefusal(`parameter '${name}': expected a string`);
+            params[name] = parseParam(name, String(raw), route.paramShapes[name]);
+        }
+        const body = route.body ? codecFor(route.body).decode(utf8.encode(JSON.stringify(args.body ?? {}))) : undefined;
+        const request = Object.freeze({ ...call, params: Object.freeze(params) });
+        const instance = instanceOf(endpoint.id, endpoint.cls);
+        const result = await withRequest(request, () => route.run(instance, request, body));
+        return answerOf(result, route.reply);
+    }
+    async function run(endpoint, tool, req) {
+        const parsed = req.argumentsJson.trim() === "" ? {} : JSON.parse(req.argumentsJson, reviver);
+        if (!isPlainObject(parsed))
+            throw new ToolRefusal("the arguments must be an object");
+        const args = parsed;
+        const self = instanceOf(endpoint.id, endpoint.cls);
+        const call = Object.freeze({
+            params: Object.freeze({}),
+            query: new Query([]),
+            headers: new Headers([]),
+            principal: principalOf(req),
+            metadata: metadataFromProto(req.metadata),
+            caller: callerOf(req),
+        });
+        return withRequest(call, async () => {
+            switch (tool.run.kind) {
+                case "function":
+                    return answerOf(await tool.run.run(decodeArgument(tool.run.input, args), self), tool.run.reply);
+                case "handler":
+                    return runHandler(tool.run, args, self);
+                case "route":
+                    return runRoute(tool.run, args, call);
+            }
+        });
+    }
+    return {
+        async invokeTool(req) {
+            const endpoint = ctx.registry.mcpEndpoint(req.endpointId);
+            const tool = endpoint?.tools.find((t) => t.name === req.tool);
+            if (!endpoint || !tool) {
+                return create(McpToolReplySchema, {
+                    reply: { case: "failure", value: { commandId: 0n, error: { message: `no tool ${req.endpointId}/${req.tool} is registered`, code: errorCodeToProto(ErrorCode.NotFound) } } },
+                });
+            }
+            try {
+                const answer = await run(endpoint, tool, req);
+                return create(McpToolReplySchema, { reply: { case: "ok", value: { text: answer.text, ...(answer.structuredJson !== undefined ? { structuredJson: answer.structuredJson } : {}) } } });
+            }
+            catch (e) {
+                // A refusal, a decoding failure or a throw: the tool error the client is shown, which a model can act on.
+                if (!(e instanceof CommandError || e instanceof HttpProblem || e instanceof ToolRefusal)) {
+                    ctx.log(`ankka: tool ${endpoint.path} ${tool.name} threw: ${e instanceof Error ? `${e.name}: ${e.message}` : String(e)}`);
+                }
+                return create(McpToolReplySchema, { reply: { case: "error", value: messageOf(e) } });
+            }
+        },
+    };
+}
+export function mcpRoutes(router, ctx) {
+    const dispatcher = createMcpDispatcher(ctx);
+    router.service(Mcp, { invokeTool: (req) => dispatcher.invokeTool(req) });
+}

package/dist/server/server.d.ts

@@ -1,5 +1,6 @@
-import type { Registry } from "../service.ts";
+import { Registry } from "../service.ts";
 import type { ComponentClient } from "../client.ts";
+import { type Buckets } from "../storage.ts";
 export interface ServerOptions {
     /** `127.0.0.1` by default; `0.0.0.0` for the testkit; anything else is refused. */
     readonly host?: string;
@@ -8,12 +9,21 @@ export interface ServerOptions {
     /** The largest message accepted from the sidecar; 64 MiB by default. */
     readonly readMaxBytes?: number;
     readonly log?: (message: string) => void;
+    /**
+     * The service's buckets, in place of the store `ANKKA_STORAGE_BACKEND` and the `ANKKA_S3_*` variables
+     * choose: the integration testkit's in-memory store.
+     */
+    readonly storage?: Buckets;
+    /** Where `service.json` is read from for the buckets it declares; the working directory by default. */
+    readonly serviceDirectory?: string;
 }
 /** What every servicer needs. */
 export interface ServerContext {
     readonly registry: Registry;
     readonly client: ComponentClient;
     readonly log: (message: string) => void;
+    /** The buckets every endpoint instance is given; the process's store when absent. */
+    readonly storage?: Buckets;
 }
 export declare class Server {
     #private;

package/dist/server/server.js

@@ -4,6 +4,9 @@
 // the integration testkit, whose sidecar reaches this process from a container.
 import { createServer } from "node:http2";
 import { connectNodeAdapter } from "@connectrpc/connect-node";
+import { Registry } from "../service.js";
+import { _setProcessStorage, chooseStorage, DirectoryBuckets } from "../storage.js";
+import { DirectoryStorageEndpoint } from "./storageEndpoint.js";
 import { renderSpec } from "../spec.js";
 import { discoveryRoutes } from "./discovery.js";
 import { eventSourcedRoutes } from "./eventSourced.js";
@@ -12,6 +15,13 @@ import { workflowRoutes } from "./workflow.js";
 import { statelessRoutes } from "./stateless.js";
 import { agentRoutes } from "./agent.js";
 import { httpRoutes } from "./http.js";
+import { mcpRoutes } from "./mcp.js";
+/** The registry with the directory store's endpoint, which serves the URLs that store signs. */
+function withStorageEndpoint(registry) {
+    const cls = DirectoryStorageEndpoint;
+    const endpoint = Object.freeze({ id: cls.name, cls, prefix: cls.prefix, acl: cls.acl, routes: new Map(Object.entries(cls.routes)) });
+    return new Registry(registry.components, new Map([...registry.endpoints, [endpoint.id, endpoint]]));
+}
 const LOOPBACK = new Set(["127.0.0.1", "localhost", "::1", "0.0.0.0", "::"]);
 export class Server {
     #context;
@@ -39,6 +49,14 @@ export class Server {
         const port = this.#options.port ?? Number(process.env.ANKKA_PROCESS_PORT ?? 9010);
         if (!Number.isInteger(port) || port < 0 || port > 65535)
             throw new Error(`not a port: ${String(port)}`);
+        // The service's buckets: the store given, or the one the environment chooses. A directory store's
+        // URLs are answered by an endpoint this process declares at /_ankka/storage.
+        const given = this.#options.storage;
+        const chosen = given ? { backend: "given", buckets: given } : chooseStorage(process.env, { ...(this.#options.serviceDirectory ? { serviceDirectory: this.#options.serviceDirectory } : {}) });
+        _setProcessStorage(chosen.buckets);
+        const registry = chosen.buckets instanceof DirectoryBuckets ? withStorageEndpoint(this.#context.registry) : this.#context.registry;
+        this.#context = { ...this.#context, registry, storage: chosen.buckets };
+        this.#context.log(`ankka: object storage is ${chosen.backend}${chosen.buckets instanceof DirectoryBuckets ? ` at ${chosen.buckets.root}` : ""}`);
         const handler = connectNodeAdapter({
             routes: (router) => {
                 discoveryRoutes(router, () => renderSpec(this.#context.registry), this.#context.log);
@@ -48,6 +66,7 @@ export class Server {
                 statelessRoutes(router, this.#context);
                 agentRoutes(router, this.#context);
                 httpRoutes(router, this.#context);
+                mcpRoutes(router, this.#context);
             },
             shutdownSignal: this.#shutdown.signal,
             readMaxBytes: this.#options.readMaxBytes ?? 64 * 1024 * 1024,

package/dist/server/storageEndpoint.d.ts

@@ -0,0 +1,14 @@
+import { Endpoint } from "../endpoint.ts";
+import { Acl, RawReply, type RouteRef } from "../routes.ts";
+type Params = Readonly<Record<string, string>>;
+export declare class DirectoryStorageEndpoint extends Endpoint {
+    #private;
+    static readonly prefix = "/_ankka/storage";
+    static readonly acl: Acl;
+    /** @internal The SDK's own endpoint under `/_ankka`, which registration admits. */
+    static readonly _sdkReserved = true;
+    static readonly routes: Readonly<Record<string, RouteRef<DirectoryStorageEndpoint, any, any, any>>>;
+    read(params: Params, depth: number): Promise<RawReply>;
+    keep(params: Params, depth: number, body: Uint8Array): Promise<RawReply>;
+}
+export {};

package/dist/server/storageEndpoint.js

@@ -0,0 +1,82 @@
+// What a TypeScript service on a developer's machine serves at `/_ankka/storage/<bucket>/<name>` while its
+// store is a directory (feature 055, research R12): the signed URLs and public addresses that store
+// makes, answered through the sidecar like any route, so a browser reads and keeps through them as it
+// would through an object store's. The runtime's `DirectoryStorageEndpoint` says the same in Scala.
+//
+// The token is the whole of the authority, as a signature is on an object store: a `GET` reads with a
+// token for `read`, or with none on a public bucket; a `PUT` keeps with a token for `keep`. Anything
+// else is `403`, and an object not there `404`. The sidecar matches a route by whole segments and an
+// object's name holds slashes, so one route is declared per depth, up to `MAX_ADDRESS_SEGMENTS`; a
+// deeper name travels as one segment with its slashes encoded.
+import { binaryCodecs } from "../codec.js";
+import { Endpoint } from "../endpoint.js";
+import { Acl, get, HttpProblem, put, RawReply } from "../routes.js";
+import { DirectoryBuckets, MAX_ADDRESS_SEGMENTS, STORAGE_PATH } from "../storage.js";
+/** A segment as the sidecar forwards it, encoded; one that is not valid encoding is taken as it is. */
+function decoded(segment) {
+    try {
+        return decodeURIComponent(segment);
+    }
+    catch {
+        return segment;
+    }
+}
+/** The bucket's segment and the object's name a request's path parameters spell. */
+function addressed(params, depth) {
+    const parts = [];
+    for (let i = 1; i <= depth; i++)
+        parts.push(decoded(params[`n${i}`] ?? ""));
+    return { segment: decoded(params.bucket ?? ""), objectName: parts.join("/") };
+}
+const NOWHERE = "no object at this address";
+const UNSIGNED = "this address is not signed for that, or its signature has expired";
+export class DirectoryStorageEndpoint extends Endpoint {
+    static prefix = STORAGE_PATH;
+    static acl = Acl.allowAll;
+    /** @internal The SDK's own endpoint under `/_ankka`, which registration admits. */
+    static _sdkReserved = true;
+    static routes = (() => {
+        const table = {};
+        for (let depth = 1; depth <= MAX_ADDRESS_SEGMENTS; depth++) {
+            const template = "/{bucket}" + Array.from({ length: depth }, (_, i) => `/{n${i + 1}}`).join("");
+            table[`read${depth}`] = get(template, binaryCodecs.bytes, (ep, req) => ep.read(req.params, depth));
+            table[`keep${depth}`] = put(template, binaryCodecs.bytes, binaryCodecs.bytes, (ep, req, body) => ep.keep(req.params, depth, body));
+        }
+        return Object.freeze(table);
+    })();
+    #store(segment) {
+        const store = this.storage;
+        if (!(store instanceof DirectoryBuckets))
+            throw new HttpProblem(404, NOWHERE);
+        const found = store.bySegment(segment);
+        if (!found)
+            throw new HttpProblem(404, NOWHERE);
+        return { store, bucket: found.bucket, segment: found.segment };
+    }
+    #signedFor(store, segment, objectName, access) {
+        const q = this.request.query;
+        const expires = Number(q.get("expires") ?? "");
+        const token = q.get("token");
+        return q.get("access") === access && token !== null && Number.isInteger(expires) && store.admits(segment, objectName, access, expires, token);
+    }
+    async read(params, depth) {
+        const { segment, objectName } = addressed(params, depth);
+        const { store, bucket } = this.#store(segment);
+        const open = bucket.exposure === "public" && bucket.name !== undefined;
+        if (!open && !this.#signedFor(store, segment, objectName, "read"))
+            throw new HttpProblem(403, UNSIGNED);
+        const object = await bucket.get(objectName);
+        if (!object)
+            throw new HttpProblem(404, `no object '${objectName}'`);
+        return new RawReply(200, object.contentType, await object.bytes());
+    }
+    async keep(params, depth, body) {
+        const { segment, objectName } = addressed(params, depth);
+        const { store, bucket } = this.#store(segment);
+        if (!this.#signedFor(store, segment, objectName, "keep"))
+            throw new HttpProblem(403, UNSIGNED);
+        const contentType = this.request.headers.get("content-type") ?? "application/octet-stream";
+        await bucket.put(objectName, body, { contentType });
+        return new RawReply(200, "text/plain; charset=utf-8", new Uint8Array());
+    }
+}

package/dist/service.d.ts

@@ -13,6 +13,7 @@ import { Agent, type AgentClass } from "./agent.ts";
 import { type McpServerRef, type ResultGuardrailRef } from "./mcp.ts";
 import { AutonomousAgent, type AutonomousAgentClass, type TaskType } from "./autonomous.ts";
 import { Endpoint, type EndpointClass } from "./endpoint.ts";
+import { McpEndpoint, type McpEndpointClass, type RegisteredMcpEndpoint } from "./mcp-endpoint.ts";
 import type { GuardrailRef, HandlerRef, ToolRef } from "./handlers.ts";
 import type { RouteRef, Acl } from "./routes.ts";
 import { ComponentClient } from "./client.ts";
@@ -150,7 +151,10 @@ export interface RegisteredEndpoint {
 export declare class Registry {
     readonly components: ReadonlyMap<string, RegisteredComponent>;
     readonly endpoints: ReadonlyMap<string, RegisteredEndpoint>;
-    constructor(components: ReadonlyMap<string, RegisteredComponent>, endpoints: ReadonlyMap<string, RegisteredEndpoint>);
+    /** The MCP endpoints (1.20), by id, their references resolved. */
+    readonly mcpEndpoints: ReadonlyMap<string, RegisteredMcpEndpoint>;
+    constructor(components: ReadonlyMap<string, RegisteredComponent>, endpoints: ReadonlyMap<string, RegisteredEndpoint>, mcpEndpoints?: ReadonlyMap<string, RegisteredMcpEndpoint>);
+    mcpEndpoint(id: string): RegisteredMcpEndpoint | undefined;
     component(id: string): RegisteredComponent | undefined;
     /** The component `id` when it is of `kind`. */
     of<K extends RegisteredComponent["kind"]>(kind: K, id: string): Extract<RegisteredComponent, {
@@ -185,6 +189,7 @@ export declare class ServiceBuilder {
     register<C extends TimedAction>(cls: TimedActionClass<C>): this;
     register<C extends Agent>(cls: AgentClass<C>): this;
     register<C extends AutonomousAgent>(cls: AutonomousAgentClass<C>): this;
+    register<C extends McpEndpoint>(cls: McpEndpointClass<C>): this;
     register<C extends Endpoint>(cls: EndpointClass<C>): this;
     /** Validates every registration and returns the registry, or throws a `RegistrationError` naming every problem. */
     validate(): Registry;

package/dist/service.js

@@ -18,7 +18,8 @@ import { Agent } from "./agent.js";
 import { serverProblems, TOOL_PREFIX } from "./mcp.js";
 import { AutonomousAgent, COMPLETE_TASK, FAIL_TASK } from "./autonomous.js";
 import { Endpoint } from "./endpoint.js";
-import { isAcl } from "./routes.js";
+import { McpEndpoint, registerMcpEndpoint } from "./mcp-endpoint.js";
+import { isAcl, isEndpointAcl } from "./routes.js";
 import { ComponentClient } from "./client.js";
 import { Server } from "./server/server.js";
 import { renderSpec } from "./spec.js";
@@ -26,11 +27,17 @@ import { renderSpec } from "./spec.js";
 export class Registry {
     components;
     endpoints;
-    constructor(components, endpoints) {
+    /** The MCP endpoints (1.20), by id, their references resolved. */
+    mcpEndpoints;
+    constructor(components, endpoints, mcpEndpoints = new Map()) {
         this.components = components;
         this.endpoints = endpoints;
+        this.mcpEndpoints = mcpEndpoints;
         Object.freeze(this);
     }
+    mcpEndpoint(id) {
+        return this.mcpEndpoints.get(id);
+    }
     component(id) {
         return this.components.get(id);
     }
@@ -83,6 +90,7 @@ export class ServiceBuilder {
         const components = new Map();
         const endpoints = new Map();
         const prefixes = new Map();
+        const mcpClasses = [];
         const add = (r, cls) => {
             if (!r)
                 return;
@@ -112,6 +120,9 @@ export class ServiceBuilder {
                 add(registerAgent(cls, problems), cls);
             else if (extendsBase(cls, AutonomousAgent))
                 add(registerAutonomousAgent(cls, problems), cls);
+            // Before Endpoint: an MCP endpoint is one, served by the platform rather than by routes.
+            else if (extendsBase(cls, McpEndpoint))
+                mcpClasses.push(cls);
             else if (extendsBase(cls, Endpoint)) {
                 const ep = cls;
                 if (typeof ep.prefix === "string") {
@@ -129,12 +140,35 @@ export class ServiceBuilder {
                 }
             }
             else {
-                problems.push(`${nameOf(cls)} is not a component class: it must extend EventSourcedEntity, KeyValueEntity, Workflow, View, KeyedView, Consumer, GraphConsumer, TimedAction, Agent, AutonomousAgent or Endpoint`);
+                problems.push(`${nameOf(cls)} is not a component class: it must extend EventSourcedEntity, KeyValueEntity, Workflow, View, KeyedView, Consumer, GraphConsumer, TimedAction, Agent, AutonomousAgent, Endpoint or McpEndpoint`);
+            }
+        }
+        // MCP endpoints last: their references name the components and endpoints registered above.
+        const mcpEndpoints = new Map();
+        const mcpPaths = new Map();
+        for (const cls of mcpClasses) {
+            const r = registerMcpEndpoint(cls, components, endpoints, problems);
+            if (!r)
+                continue;
+            const other = mcpPaths.get(r.path);
+            if (other)
+                problems.push(`MCP endpoints ${other} and ${r.id} share the path ${r.path}`);
+            mcpPaths.set(r.path, r.id);
+            for (const e of endpoints.values()) {
+                for (const route of e.routes.values()) {
+                    const full = route.template === "/" ? e.prefix : e.prefix === "/" ? route.template : `${e.prefix}${route.template}`;
+                    if (full === r.path)
+                        problems.push(`${r.id}: its path ${r.path} is also the route ${route.method} ${full} of ${e.id}`);
+                }
             }
+            if (mcpEndpoints.has(r.id))
+                problems.push(`two MCP endpoints are named ${r.id}`);
+            else
+                mcpEndpoints.set(r.id, r);
         }
         if (problems.length > 0)
             throw new RegistrationError(problems);
-        return new Registry(components, endpoints);
+        return new Registry(components, endpoints, mcpEndpoints);
     }
     /** The discovery `Spec` for what is registered, without listening. */
     spec() {
@@ -635,9 +669,16 @@ function registerEndpoint(cls, problems) {
     if (typeof cls.prefix !== "string" || !cls.prefix.startsWith("/") || (cls.prefix.length > 1 && cls.prefix.endsWith("/"))) {
         fail(`needs a static prefix starting with "/" and not ending with one, not ${JSON.stringify(cls.prefix)}`);
     }
+    else if ((cls.prefix === "/_ankka" || cls.prefix.startsWith("/_ankka/")) && cls._sdkReserved !== true) {
+        // The SDK's own directory-store endpoint is the one exception, as the sidecar admits it alone.
+        fail(`prefix '${cls.prefix}' is under /_ankka, which is the runtime's`);
+    }
     if (!isAcl(cls.acl)) {
         fail(`needs a static acl — Acl.allowAll, Acl.denyAll, Acl.authenticated or Acl.allowCallers(...). An unstated access rule is a decision nobody made`);
     }
+    else if (!isEndpointAcl(cls.acl)) {
+        fail("admits client keys or states Acl.anyOf, which only an MCP endpoint can: extend McpEndpoint");
+    }
     const routes = new Map();
     const seen = new Map();
     if (typeof cls.routes !== "object" || cls.routes === null) {
@@ -657,6 +698,8 @@ function registerEndpoint(cls, problems) {
             seen.set(key, id);
             if (r.acl !== undefined && !isAcl(r.acl))
                 fail(`routes.${id}: unknown acl ${JSON.stringify(r.acl)}`);
+            else if (r.acl !== undefined && !isEndpointAcl(r.acl))
+                fail(`routes.${id} admits client keys or states Acl.anyOf, which only an MCP endpoint can`);
             routes.set(id, r);
         }
     }

package/dist/sigv4.d.ts

@@ -0,0 +1,47 @@
+/** A key pair. Never printed whole: `toString` hides the secret. */
+export declare class Credentials {
+    #private;
+    readonly accessKey: string;
+    constructor(accessKey: string, secretKey: string);
+    /** @internal */
+    get _secretKey(): string;
+    toString(): string;
+    toJSON(): string;
+}
+export declare const ALGORITHM = "AWS4-HMAC-SHA256";
+/** The payload hash a put sends so its body is streamed once and never hashed. */
+export declare const UNSIGNED_PAYLOAD = "UNSIGNED-PAYLOAD";
+export declare function sha256Hex(data: Uint8Array | string): string;
+export declare function hmac(key: Uint8Array | string, data: string): Buffer;
+/** The hash of an empty payload. */
+export declare const EMPTY_PAYLOAD: string;
+/** RFC 3986 encoding as SigV4 states it: unreserved characters kept, everything else `%XX` of its UTF-8 bytes. */
+export declare function encode(text: string, encodeSlash: boolean): string;
+/** One request: the endpoint's scheme and authority, a decoded path and decoded query pairs. */
+export declare class SignedRequest {
+    readonly method: string;
+    readonly endpoint: URL;
+    readonly path: string;
+    readonly query: readonly (readonly [string, string])[];
+    constructor(method: string, endpoint: URL | string, path: string, query?: readonly (readonly [string, string])[]);
+    /** The `host` header's value: the host, with the port when the endpoint names one. */
+    get host(): string;
+    get canonicalPath(): string;
+    get canonicalQuery(): string;
+    /** The URL the request is sent to: the same encoding as the one signed. */
+    get url(): string;
+    withQuery(more: readonly (readonly [string, string])[]): SignedRequest;
+}
+/** `20150830T123600Z`. */
+export declare function amzDate(now: Date): string;
+/**
+ * The headers to send with `request` so the store believes it: `x-amz-date` and `Authorization`.
+ * `headers` are the ones to sign beside `host` and `x-amz-date` — an S3 request includes
+ * `x-amz-content-sha256` among them — and are sent as given.
+ */
+export declare function sign(request: SignedRequest, headers: Readonly<Record<string, string>>, payloadHash: string, credentials: Credentials, region: string, service: string, now: Date): {
+    "x-amz-date": string;
+    Authorization: string;
+};
+/** A URL anyone may use, until it expires, for `request`'s method on its path. Signs `host` alone. */
+export declare function presign(request: SignedRequest, credentials: Credentials, region: string, service: string, expiresSeconds: number, now: Date): string;