ankka 0.11.0 → 0.13.0

package/dist/routes.js

@@ -11,12 +11,15 @@
 import { isCodec } from "./codec.js";
 /**
  * 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 const Callers = Object.freeze({
     internet: Object.freeze({ kind: "internet" }),
     anyInProject: Object.freeze({ kind: "anyInProject" }),
     self: Object.freeze({ kind: "self" }),
+    granted: Object.freeze({ kind: "granted" }),
     service(name, options) {
         return Object.freeze(options?.project !== undefined ? { kind: "service", name, project: options.project } : { kind: "service", name });
     },
@@ -25,19 +28,31 @@ export const Acl = Object.freeze({
     allowAll: "allow-all",
     denyAll: "deny-all",
     authenticated: "authenticated",
+    /** A client key issued for the MCP endpoint (protocol 1.20); its subject and attributes are the principal. */
+    clientKeys: "client-keys",
     allowCallers(first, ...rest) {
         return Object.freeze({ kind: "callers", callers: Object.freeze([first, ...rest]) });
     },
+    /** Admitted when any of the rules admits; for an MCP endpoint or one of its tools. */
+    anyOf(first, ...rest) {
+        return Object.freeze({ kind: "anyOf", acls: Object.freeze([first, ...rest]) });
+    },
 });
-/** 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 function isAcl(x) {
-    if (x === "allow-all" || x === "deny-all" || x === "authenticated")
+    if (x === "allow-all" || x === "deny-all" || x === "authenticated" || x === "client-keys")
         return true;
     if (typeof x !== "object" || x === null)
         return false;
     const rule = x;
+    if (rule.kind === "anyOf")
+        return Array.isArray(rule.acls) && rule.acls.length > 0 && rule.acls.every(isAcl);
     return rule.kind === "callers" && Array.isArray(rule.callers) && rule.callers.length > 0;
 }
+/** Whether `acl` is one an HTTP endpoint or route can state: neither client keys nor `anyOf`, which are an MCP endpoint's. */
+export function isEndpointAcl(acl) {
+    return acl !== "client-keys" && !(typeof acl === "object" && acl.kind === "anyOf");
+}
 /** Thrown from a route handler to answer a status other than 200 with a plain-text message. */
 export class HttpProblem extends Error {
     status;
@@ -47,6 +62,21 @@ export class HttpProblem extends Error {
         this.status = status;
     }
 }
+/**
+ * @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 class RawReply {
+    status;
+    contentType;
+    body;
+    constructor(status, contentType, body) {
+        this.status = status;
+        this.contentType = contentType;
+        this.body = body;
+        Object.freeze(this);
+    }
+}
 const TEMPLATE = /^(\/(?:[^/{}]+|\{[A-Za-z_][A-Za-z0-9_]*\})?)*$/;
 export function parseTemplate(template) {
     if (typeof template !== "string" || !template.startsWith("/") || !TEMPLATE.test(template) || template.includes("//")) {
@@ -96,6 +126,29 @@ export const put = withBody("PUT");
 export const patch = withBody("PATCH");
 /** A DELETE route; `delete` is a reserved word, so `del`. */
 export const del = withBody("DELETE");
+/**
+ * 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 async function* sseEvents(watch) {
+    try {
+        for await (const event of watch) {
+            if (event.kind === "row")
+                yield sseEvent("row", { key: event.key, row: event.row });
+            else if (event.kind === "removed")
+                yield sseEvent("removed", { key: event.key });
+            else
+                yield sseEvent("caught-up", {});
+        }
+    }
+    catch (failure) {
+        if (failure instanceof Error && failure.name === "WatchEnded")
+            yield sseEvent("ended", { reason: failure.reason });
+        else
+            throw failure;
+    }
+}
 export function sseEvent(name, value) {
     if (typeof name !== "string" || name === "" || /[\r\n]/.test(name))
         throw new TypeError(`an event name must be one non-empty line, not ${JSON.stringify(name)}`);

package/dist/server/discovery.d.ts

@@ -6,6 +6,8 @@ import { type Spec } from "../_proto/ankka/protocol/v1/discovery_pb.ts";
  * naming what declares them, rather than served wrong.
  */
 export declare function refusal(spec: Spec, sidecarProtocol: string): string | undefined;
+/** The protocol version whose runtimes admit a process's endpoint at `/_ankka/storage`. */
+export declare const STORAGE_SINCE: readonly [number, number];
 /** Every problem the sidecar has reported to this process, in order. */
 export declare const problems: string[];
 export declare function discoveryRoutes(router: ConnectRouter, spec: () => Spec, log?: (message: string) => void): void;
@@ -14,3 +16,13 @@ export declare const SOCKETS_SINCE: readonly [number, number];
 /** Why `spec` cannot be declared to a runtime speaking `runtime`, or undefined. A runtime before 1.9
  * does not know a socket route, and would serve it as a plain GET. */
 export declare function socketRefusal(spec: Spec, runtime: string): string | undefined;
+/** The protocol version whose runtimes admit granted callers. */
+export declare const GRANTS_SINCE: readonly [number, number];
+/** Why `spec` cannot be declared to a runtime speaking `runtime`, or undefined. A runtime before 1.15
+ * does not know `Callers.granted`, and would admit nobody by it. */
+export declare function grantsRefusal(spec: Spec, runtime: string): string | undefined;
+/** The protocol version whose runtimes serve a process's MCP endpoint. */
+export declare const MCP_SINCE: readonly [number, number];
+/** Why `spec` cannot be declared to a runtime speaking `runtime`, or undefined. A runtime before 1.20
+ * does not know an MCP endpoint, and would serve nothing at its path. */
+export declare function mcpRefusal(spec: Spec, runtime: string): string | undefined;

package/dist/server/discovery.js

@@ -6,14 +6,60 @@ import { create } from "@bufbuild/protobuf";
 import { Discovery } from "../_proto/ankka/protocol/v1/discovery_pb.js";
 import { EmptySchema } from "../_proto/ankka/protocol/v1/payload_pb.js";
 import { PROTOCOL_VERSION } from "../spec.js";
-import { olderThanContracts, olderThanDeclaredQueries, olderThanStartPositions } from "../startFrom.js";
+import { Kind } from "../_proto/ankka/protocol/v1/discovery_pb.js";
+import { STORAGE_PATH } from "../storage.js";
+import { olderThan, olderThanContracts, olderThanDeclaredQueries, olderThanStartPositions, olderThanViewStreams, olderThanWorkflowSources } from "../startFrom.js";
 /**
  * A sidecar older than 1.7 would ignore where a topic source starts and its version: a consumer
  * declared `latest` would read everything, and a raised version would rebuild nothing. Refused,
  * naming what declares them, rather than served wrong.
  */
 export function refusal(spec, sidecarProtocol) {
-    return startPositionRefusal(spec, sidecarProtocol) ?? declaredQueryRefusal(spec, sidecarProtocol) ?? contractRefusal(spec, sidecarProtocol);
+    return (workflowSourceRefusal(spec, sidecarProtocol) ??
+        startPositionRefusal(spec, sidecarProtocol) ??
+        declaredQueryRefusal(spec, sidecarProtocol) ??
+        contractRefusal(spec, sidecarProtocol) ??
+        watchedQueryRefusal(spec, sidecarProtocol) ??
+        // Last: a reason an older sidecar has too is named first, by the version it needs.
+        replicationRefusal(spec, sidecarProtocol));
+}
+/**
+ * A sidecar older than 1.19 would host a replicated entity at one installation and say nothing, and
+ * would hand a consumer given mirrored changes only the changes written here. Refused at discovery,
+ * naming the components and the version.
+ */
+function replicationRefusal(spec, sidecarProtocol) {
+    if (!olderThan(sidecarProtocol, [1, 19]))
+        return undefined;
+    const replicated = spec.components
+        .filter((c) => (c.detail.case === "eventSourced" && c.detail.value.replicated) ||
+        (c.detail.case === "consumer" && c.detail.value.mirroredChanges))
+        .map((c) => c.id);
+    if (replicated.length === 0)
+        return undefined;
+    return (`${replicated.join(", ")} declare replication, which needs protocol 1.19: ` +
+        `the sidecar speaks protocol ${sidecarProtocol}, and this SDK ${PROTOCOL_VERSION}. Run a sidecar speaking 1.19 or later.`);
+}
+/**
+ * A sidecar older than 1.16 would not read a workflow as a source: a view or consumer that does would
+ * be handed nothing. Refused at discovery, naming them.
+ */
+function workflowSourceRefusal(spec, sidecarProtocol) {
+    if (!olderThanWorkflowSources(sidecarProtocol))
+        return undefined;
+    const reading = spec.components
+        .filter((c) => {
+        const d = c.detail;
+        if (d.case !== "view" && d.case !== "consumer")
+            return false;
+        const sources = d.case === "view" ? [d.value.source, ...d.value.sources] : [d.value.source];
+        return sources.some((s) => s?.source.case === "component" && s.source.value.kind === Kind.WORKFLOW);
+    })
+        .map((c) => c.id);
+    if (reading.length === 0)
+        return undefined;
+    return (`${reading.join(", ")} read a workflow, which the sidecar does not know: ` +
+        `it speaks protocol ${sidecarProtocol}, and this SDK ${PROTOCOL_VERSION}. Run a sidecar speaking 1.16 or later.`);
 }
 /**
  * A sidecar older than 1.14 would ignore a topic's contract, broker and parallel reading and a
@@ -39,6 +85,21 @@ function contractRefusal(spec, sidecarProtocol) {
     return (`${declaring.join(", ")} declare a topic's contract, broker or parallel reading, which the sidecar ignores: ` +
         `it speaks protocol ${sidecarProtocol}, and this SDK ${PROTOCOL_VERSION}. Run a sidecar speaking 1.14 or later.`);
 }
+/**
+ * A sidecar older than 1.17 would not know that a view's query may be watched, and a watch of it would
+ * be refused at its first asking. Refused at discovery, naming the views.
+ */
+function watchedQueryRefusal(spec, sidecarProtocol) {
+    if (!olderThanViewStreams(sidecarProtocol))
+        return undefined;
+    const watching = spec.components
+        .filter((c) => c.detail.case === "view" && c.detail.value.declaredQueries.some((q) => q.watched))
+        .map((c) => c.id);
+    if (watching.length === 0)
+        return undefined;
+    return (`${watching.join(", ")} declare a watched query, which the sidecar does not know: ` +
+        `it speaks protocol ${sidecarProtocol}, and this SDK ${PROTOCOL_VERSION}. Run a sidecar speaking 1.17 or later.`);
+}
 /**
  * A sidecar older than 1.13 would ignore a view's declared queries, would read a keyed view as having
  * no source, and would refuse a version on a view that reads an entity as applying only to a topic.
@@ -77,14 +138,26 @@ function startPositionRefusal(spec, sidecarProtocol) {
     return (`${declaring.join(", ")} declare where a topic source starts or its version, which the sidecar ignores: ` +
         `it speaks protocol ${sidecarProtocol}, and this SDK ${PROTOCOL_VERSION}. Run a sidecar speaking 1.7 or later.`);
 }
+/** The protocol version whose runtimes admit a process's endpoint at `/_ankka/storage`. */
+export const STORAGE_SINCE = [1, 21];
 /** Every problem the sidecar has reported to this process, in order. */
 export const problems = [];
 export function discoveryRoutes(router, spec, log = console.error) {
     router.service(Discovery, {
         async discover(info) {
             log(`ankka: discovery from sidecar (protocol ${info.protocolVersion}, runtime ${info.runtimeVersion})`);
-            const answer = spec();
-            const why = refusal(answer, info.protocolVersion) ?? socketRefusal(answer, info.protocolVersion);
+            let answer = spec();
+            // A runtime before 1.21 refuses a process's endpoint under /_ankka; the directory store's URLs then
+            // go unanswered, and nothing else of the store needs the runtime.
+            if (olderThan(info.protocolVersion, STORAGE_SINCE) && answer.endpoints.some((e) => e.prefix === STORAGE_PATH)) {
+                log(`ankka: the sidecar speaks protocol ${info.protocolVersion}; the directory store's URLs at ${STORAGE_PATH} need 1.21 and are not served`);
+                answer = { ...answer, endpoints: answer.endpoints.filter((e) => e.prefix !== STORAGE_PATH) };
+            }
+            const why = refusal(answer, info.protocolVersion) ??
+                socketRefusal(answer, info.protocolVersion) ??
+                grantsRefusal(answer, info.protocolVersion) ??
+                // Last: an older runtime is told the oldest thing it lacks first.
+                mcpRefusal(answer, info.protocolVersion);
             if (why !== undefined) {
                 log(`ankka: ${why}`);
                 problems.push(why);
@@ -113,3 +186,41 @@ export function socketRefusal(spec, runtime) {
         return undefined;
     return `this runtime speaks protocol ${runtime || "unknown"}; a socket route needs 1.9 (${routes.join(", ")})`;
 }
+/** The protocol version whose runtimes admit granted callers. */
+export const GRANTS_SINCE = [1, 15];
+/** Why `spec` cannot be declared to a runtime speaking `runtime`, or undefined. A runtime before 1.15
+ * does not know `Callers.granted`, and would admit nobody by it. */
+export function grantsRefusal(spec, runtime) {
+    const grants = (callers) => callers.some((m) => m.kind.case === "granted");
+    const endpoints = spec.endpoints
+        .filter((e) => grants(e.allowCallers) || e.routes.some((r) => grants(r.allowCallers)))
+        .map((e) => e.id);
+    // Another project's topic is 1.15's too: an older runtime would read it as this project's.
+    for (const c of spec.components) {
+        const d = c.detail;
+        const sources = d.case === "view" ? [d.value.source, ...d.value.sources] : d.case === "consumer" ? [d.value.source] : [];
+        const publishes = d.case === "consumer" && d.value.produces?.project !== undefined;
+        if (sources.some((s) => s?.project !== undefined) || publishes)
+            endpoints.push(c.id);
+    }
+    if (endpoints.length === 0)
+        return undefined;
+    const [major, minor] = runtime.split(".").map((part) => Number.parseInt(part, 10));
+    const speaks = Number.isFinite(major) && Number.isFinite(minor) ? [major, minor] : [0, 0];
+    if (speaks[0] > GRANTS_SINCE[0] || (speaks[0] === GRANTS_SINCE[0] && speaks[1] >= GRANTS_SINCE[1]))
+        return undefined;
+    return `this runtime speaks protocol ${runtime || "unknown"}; granted callers and another project's topics need 1.15 (${endpoints.join(", ")})`;
+}
+/** The protocol version whose runtimes serve a process's MCP endpoint. */
+export const MCP_SINCE = [1, 20];
+/** Why `spec` cannot be declared to a runtime speaking `runtime`, or undefined. A runtime before 1.20
+ * does not know an MCP endpoint, and would serve nothing at its path. */
+export function mcpRefusal(spec, runtime) {
+    if (spec.mcpEndpoints.length === 0)
+        return undefined;
+    const [major, minor] = runtime.split(".").map((part) => Number.parseInt(part, 10));
+    const speaks = Number.isFinite(major) && Number.isFinite(minor) ? [major, minor] : [0, 0];
+    if (speaks[0] > MCP_SINCE[0] || (speaks[0] === MCP_SINCE[0] && speaks[1] >= MCP_SINCE[1]))
+        return undefined;
+    return `this runtime speaks protocol ${runtime || "unknown"}; an MCP endpoint needs 1.20 (${spec.mcpEndpoints.map((e) => e.path).join(", ")})`;
+}

package/dist/server/eventSourced.d.ts

@@ -1,10 +1,13 @@
 import type { ConnectRouter } from "@connectrpc/connect";
 import { type MessageInitShape } from "@bufbuild/protobuf";
-import { type EventSourcedIn, type EventSourcedOut } from "../_proto/ankka/protocol/v1/event_sourced_pb.ts";
+import { type ReplicationChangeSchema, type EventSourcedIn, type EventSourcedOut } from "../_proto/ankka/protocol/v1/event_sourced_pb.ts";
 import type { RetentionSchema } from "../_proto/ankka/protocol/v1/payload_pb.ts";
 import { type Retention } from "../effects/common.ts";
+import type { ReplicationChange } from "../effects/eventSourced.ts";
 import type { ServerContext } from "./server.ts";
 type RetentionInit = MessageInitShape<typeof RetentionSchema>;
+/** A replicated entity's handover or change to its replication set, as the reply carries it (1.19). */
+export declare function replicationToProto(change: ReplicationChange | undefined): MessageInitShape<typeof ReplicationChangeSchema> | undefined;
 /** Retention as the protocol carries it; `undefined` when the effect asked for none. */
 export declare function retentionToProto(retention: Retention | null): RetentionInit | undefined;
 export declare function eventSourcedRoutes(router: ConnectRouter, ctx: ServerContext): void;

package/dist/server/eventSourced.js

@@ -9,12 +9,20 @@
 import { create } from "@bufbuild/protobuf";
 import { EventSourced, EventSourcedOutSchema, } from "../_proto/ankka/protocol/v1/event_sourced_pb.js";
 import { codecFor } from "../codec.js";
-import { commandContext, metadataFromProto } from "../context.js";
+import { commandContext, eventContext, metadataFromProto } from "../context.js";
 import { ErrorCode } from "../effects/common.js";
 import { binaryCodecs } from "../codec.js";
 import { errorCodeToProto } from "../kinds.js";
 import { materialiseEventSourced } from "../materialise.js";
 import { decodePayload, encodePayload } from "./payloads.js";
+/** A replicated entity's handover or change to its replication set, as the reply carries it (1.19). */
+export function replicationToProto(change) {
+    if (!change)
+        return undefined;
+    return change.kind === "hand-over"
+        ? { change: { case: "handOverTo", value: change.to } }
+        : { change: { case: "set", value: { add: [...change.add], remove: [...change.remove] } } };
+}
 /** Retention as the protocol carries it; `undefined` when the effect asked for none. */
 export function retentionToProto(retention) {
     if (!retention)
@@ -43,10 +51,13 @@ export async function* handleEventSourced(requests, ctx) {
     let entityId = "";
     let state;
     let sequence = 0n;
+    // This installation, for a replicated entity (1.19): null on a service that names none.
+    let here = null;
     for await (const m of requests) {
         switch (m.message.case) {
             case "init": {
                 const init = m.message.value;
+                here = init.installation || null;
                 const found = ctx.registry.component(init.componentId);
                 if (!found || found.kind !== "event-sourced") {
                     yield failure(0n, { message: `no event sourced entity ${JSON.stringify(init.componentId)} is registered`, code: ErrorCode.NotFound });
@@ -80,7 +91,8 @@ export async function* handleEventSourced(requests, ctx) {
                 }
                 const ev = m.message.value;
                 try {
-                    state = entity.applyEvent(state, decodePayload(registered.eventCodec, ev.payload));
+                    const written = ev.installation || here;
+                    state = entity.applyEvent(state, decodePayload(registered.eventCodec, ev.payload), eventContext(written, written === here, ev.sequence));
                     sequence = ev.sequence;
                 }
                 catch (e) {
@@ -95,7 +107,7 @@ export async function* handleEventSourced(requests, ctx) {
                     yield failure(m.message.value.id, { message: "a command arrived before Init", code: ErrorCode.Internal });
                     return;
                 }
-                const result = await runCommand(registered, entity, entityId, state, sequence, m.message.value, ctx);
+                const result = await runCommand(registered, entity, entityId, state, sequence, m.message.value, ctx, here);
                 yield result.out;
                 if (result.newState !== undefined) {
                     state = result.newState.state;
@@ -108,7 +120,7 @@ export async function* handleEventSourced(requests, ctx) {
         }
     }
 }
-async function runCommand(registered, entity, entityId, state, sequence, cmd, ctx) {
+async function runCommand(registered, entity, entityId, state, sequence, cmd, ctx, here = null) {
     const handler = registered.handlers.get(cmd.name);
     if (!handler)
         return { out: failure(cmd.id, { message: `no handler ${JSON.stringify(cmd.name)} on ${registered.id}`, code: ErrorCode.NotFound }) };
@@ -120,7 +132,7 @@ async function runCommand(registered, entity, entityId, state, sequence, cmd, ct
         return { out: failure(cmd.id, { message: `${registered.id}/${cmd.name}: the input could not be decoded: ${messageOf(e)}`, code: ErrorCode.BadRequest }) };
     }
     const metadata = metadataFromProto(cmd.metadata);
-    const context = commandContext(registered.id, entityId, sequence, metadata);
+    const context = commandContext(registered.id, entityId, sequence, metadata, undefined, cmd.installation || null, cmd.atHome);
     let effect;
     entity._bindCommand(state, context, ctx.client.withMetadata(metadata));
     try {
@@ -137,7 +149,12 @@ async function runCommand(registered, entity, entityId, state, sequence, cmd, ct
         return { out: failure(cmd.id, { message: `${registered.id}/${cmd.name} is a query and returned a persisting effect`, code: ErrorCode.Internal }) };
     }
     try {
-        const m = materialiseEventSourced(effect, state, (s, e) => entity.applyEvent(s, e));
+        let applied = sequence;
+        const m = materialiseEventSourced(effect, state, (s, e) => {
+            applied += 1n;
+            return entity.applyEvent(s, e, eventContext(here, true, applied));
+        });
+        const replication = !m.error && effect.kind === "persist" ? replicationToProto(effect.replication) : undefined;
         const events = m.events.map((e) => encodePayload(registered.eventCodec, e));
         const replyCodec = handler.reply ? codecFor(handler.reply) : binaryCodecs.done;
         const outcome = m.error
@@ -154,6 +171,7 @@ async function runCommand(registered, entity, entityId, state, sequence, cmd, ct
                     retention: retentionToProto(m.retention),
                     outcome,
                     snapshot: cmd.snapshotRequested ? encodePayload(registered.stateCodec, m.newState) : undefined,
+                    replication,
                 },
             },
         });

package/dist/server/http.d.ts

@@ -1,6 +1,14 @@
 import type { ConnectRouter } from "@connectrpc/connect";
 import { type HttpRequest, type HttpReply, type SocketIn, type SocketOut, type StreamFrame } from "../_proto/ankka/protocol/v1/endpoint_pb.ts";
+import { type Caller, type Principal } from "../context.ts";
+import { type Schema } from "../schema.ts";
 import type { ServerContext } from "./server.ts";
+/** The principal the sidecar verified, for a route or a tool call; never the credential. */
+export declare function principalOf(req: Pick<HttpRequest, "principal">): Principal | null;
+/** The caller the sidecar established; a sidecar that predates protocol 1.1 sends none, which reads as local. */
+export declare function callerOf(req: Pick<HttpRequest, "caller">): Caller;
+/** A path parameter as its declared schema: strings as they are, scalars through their text codec. */
+export declare function parseParam(name: string, text: string, shape: Schema | undefined): unknown;
 export interface HttpDispatcher {
     handle(req: HttpRequest): Promise<HttpReply>;
     handleStream(req: HttpRequest): AsyncIterable<StreamFrame>;

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,19 +41,21 @@ 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":
             return Object.freeze({ kind: "gateway" });
         case "service":
             return Object.freeze({ kind: "service", project: kind.value.project, name: kind.value.name });
+        case "machine":
+            return Object.freeze({ kind: "machine", organization: kind.value.organization, name: kind.value.name });
         default:
             return Object.freeze({ kind: "local" });
     }
 }
 /** 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);
@@ -69,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: [] } } });
     }
@@ -91,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) });
+}