ankka 0.12.0 → 0.13.0

package/dist/client-keys.js

@@ -0,0 +1,182 @@
+// A service's client keys (protocol 1.20): credentials it issues for its MCP endpoint, each for one
+// subject, with an expiry, an optional scope of tools and attributes a tool reads as the principal's
+// claims. The runtime keeps them; this process sees a key once, in the answer to `issue`, and never
+// again. Offered to endpoints, MCP endpoints, timed actions and agents, as the secret store is.
+//
+//   const issued = await this.clientKeys.issue({ subject: "acme", expiry: Expiry.after({ days: 365 }), scope: ["list_jobs"] })
+//   issued.clientKey   // shown here, and nowhere again
+import { Code, ConnectError } from "@connectrpc/connect";
+import { channelOf } from "./client.js";
+import { metadataToProto } from "./context.js";
+import { CommandError, ErrorCode } from "./effects/common.js";
+import { errorCodeFromProto } from "./kinds.js";
+import { PROTOCOL_VERSION } from "./spec.js";
+import { Duration, Instant } from "./time.js";
+/** The first protocol whose runtime keeps client keys; an older one answers `UNIMPLEMENTED`. */
+export const CLIENT_KEYS_SINCE = "1.20";
+export const Expiry = Object.freeze({
+    /** After a while from now: `Expiry.after({ days: 365 })`, or a `Duration`. */
+    after(by) {
+        const millis = by instanceof Duration
+            ? by.toMillis()
+            : (by.days ?? 0) * 86_400_000 + (by.hours ?? 0) * 3_600_000 + (by.minutes ?? 0) * 60_000 + (by.seconds ?? 0) * 1_000 + (by.millis ?? 0);
+        if (!Number.isFinite(millis) || millis <= 0)
+            throw new TypeError(`a client key's expiry is a positive while, not ${millis}ms`);
+        return Object.freeze({ kind: "after", millis });
+    },
+    /** At an instant. */
+    at(when) {
+        const epochMillis = when instanceof Instant ? when.toEpochMilli() : when.getTime();
+        return Object.freeze({ kind: "at", epochMillis });
+    },
+    /** Never: admitted until it is revoked. */
+    never: Object.freeze({ kind: "never" }),
+});
+function refusalOf(error) {
+    return new CommandError({ message: error.message, code: errorCodeFromProto(error.code), details: { ...(error.details ?? {}) } });
+}
+function tooOld(failure) {
+    if (failure instanceof ConnectError && failure.code === Code.Unimplemented) {
+        throw new CommandError({
+            message: `the runtime beside this process is too old for client keys, which needs protocol ${CLIENT_KEYS_SINCE}; this process speaks ${PROTOCOL_VERSION}: ${failure.rawMessage}`,
+            code: ErrorCode.Internal,
+        });
+    }
+    throw failure;
+}
+function instant(millis) {
+    return millis === undefined ? null : Instant.ofEpochMilli(Number(millis));
+}
+/**
+ * The service's client keys, kept by the runtime. A refusal is a `CommandError` with the runtime's
+ * code: `BAD_REQUEST` for a request that breaks a rule, `UNAVAILABLE` when the service's MCP
+ * endpoints admit no client key (there is then nothing to keep them), `NOT_FOUND` for an unknown id.
+ */
+export class ClientKeys {
+    #client;
+    /** The keys reached through `client`'s sidecar; with none, every call throws. */
+    constructor(client) {
+        this.#client = client;
+    }
+    #channel() {
+        const channel = this.#client ? channelOf(this.#client) : undefined;
+        if (!channel)
+            throw new Error("these client keys are not connected to a runtime; a unit test passes an InMemoryClientKeys");
+        return channel;
+    }
+    /** Issues a key; the answer is the one place the key is ever shown. */
+    async issue(request) {
+        const { stub, metadata } = this.#channel();
+        const expiry = request.expiry;
+        const reply = await stub()
+            .issueClientKey({
+            subject: request.subject,
+            expiry: expiry.kind === "after"
+                ? { case: "afterMillis", value: BigInt(expiry.millis) }
+                : expiry.kind === "at"
+                    ? { case: "atEpochMillis", value: BigInt(expiry.epochMillis) }
+                    : { case: "never", value: true },
+            ...(request.endpoint !== undefined ? { endpoint: request.endpoint } : {}),
+            scope: [...(request.scope ?? [])],
+            attributes: { ...(request.attributes ?? {}) },
+            ...(request.label !== undefined ? { label: request.label } : {}),
+            metadata: metadataToProto(metadata),
+        })
+            .catch(tooOld);
+        switch (reply.reply.case) {
+            case "issued":
+                return Object.freeze({ id: reply.reply.value.id, clientKey: reply.reply.value.clientKey });
+            case "error":
+                throw refusalOf(reply.reply.value);
+            default:
+                throw new CommandError({ message: "the runtime answered an issue with nothing", code: ErrorCode.Internal });
+        }
+    }
+    /** Every client key of the service, revoked ones included; never a key itself. */
+    async list() {
+        const { stub, metadata } = this.#channel();
+        const reply = await stub().listClientKeys({ metadata: metadataToProto(metadata) }).catch(tooOld);
+        if (reply.error)
+            throw refusalOf(reply.error);
+        return reply.keys.map((k) => Object.freeze({
+            id: k.id,
+            subject: k.subject,
+            attributes: Object.freeze({ ...k.attributes }),
+            label: k.label ?? null,
+            endpoint: k.endpoint,
+            scope: Object.freeze([...k.scope]),
+            issuedAt: Instant.ofEpochMilli(Number(k.issuedAtMillis)),
+            expiresAt: instant(k.expiresAtMillis),
+            lastUsed: instant(k.lastUsedMillis),
+            revokedAt: instant(k.revokedAtMillis),
+        }));
+    }
+    /** Revokes a key: refused on its next request on every instance. Revoking twice is not an error. */
+    async revoke(id) {
+        const { stub, metadata } = this.#channel();
+        const reply = await stub().revokeClientKey({ id, metadata: metadataToProto(metadata) }).catch(tooOld);
+        if (reply.error)
+            throw refusalOf(reply.error);
+    }
+}
+/** Client keys for unit tests: a map, issuing keys that look like the runtime's and applying its rules. */
+export class InMemoryClientKeys extends ClientKeys {
+    #keys = new Map();
+    #next = 0;
+    constructor() {
+        super(undefined);
+    }
+    /** The key issued under `id`, which a test may present; the runtime shows it only once. */
+    keyOf(id) {
+        return this.#keys.get(id)?.clientKey;
+    }
+    async issue(request) {
+        if (typeof request.subject !== "string" || request.subject.trim() === "") {
+            throw new CommandError({ message: "a client key needs a subject", code: ErrorCode.BadRequest });
+        }
+        const attributes = request.attributes ?? {};
+        if (Object.keys(attributes).length > 16)
+            throw new CommandError({ message: "a client key carries at most 16 attributes", code: ErrorCode.BadRequest });
+        for (const [name, value] of Object.entries(attributes)) {
+            if (name.length > 256 || value.length > 256)
+                throw new CommandError({ message: `attribute '${name.slice(0, 40)}' is longer than 256 characters`, code: ErrorCode.BadRequest });
+        }
+        this.#next += 1;
+        const id = `ck_${this.#next}`;
+        const clientKey = `ak_test_${id}_${Math.random().toString(36).slice(2)}`;
+        const now = Instant.now();
+        const expiry = request.expiry;
+        const expiresAt = expiry.kind === "after" ? Instant.ofEpochMilli(now.toEpochMilli() + expiry.millis) : expiry.kind === "at" ? Instant.ofEpochMilli(expiry.epochMillis) : null;
+        const summary = Object.freeze({
+            id,
+            subject: request.subject,
+            attributes: Object.freeze({ ...attributes }),
+            label: request.label ?? null,
+            endpoint: request.endpoint ?? "",
+            scope: Object.freeze([...(request.scope ?? [])]),
+            issuedAt: now,
+            expiresAt,
+            lastUsed: null,
+            revokedAt: null,
+        });
+        this.#keys.set(id, { summary, clientKey });
+        return Object.freeze({ id, clientKey });
+    }
+    async list() {
+        return [...this.#keys.values()].map((k) => k.summary);
+    }
+    async revoke(id) {
+        const held = this.#keys.get(id);
+        if (!held)
+            throw new CommandError({ message: `no client key '${id}'`, code: ErrorCode.NotFound });
+        if (held.summary.revokedAt === null)
+            this.#keys.set(id, { ...held, summary: Object.freeze({ ...held.summary, revokedAt: Instant.now() }) });
+    }
+}
+/**
+ * @internal The client keys reached through `client`'s sidecar. Not a member of the client, which an
+ * entity holds too: only the component kinds that may issue keys call this.
+ */
+export function clientKeysFor(client) {
+    return new ClientKeys(client);
+}

package/dist/consumer.d.ts

@@ -3,6 +3,7 @@ import type { Contract, Publication } from "./contract.ts";
 import type { Shape } from "./codec.ts";
 import type { Metadata } from "./effects/common.ts";
 import { type ComponentClient, type ComponentRef, type Secrets } from "./client.ts";
+import { type Buckets } from "./storage.ts";
 import { ConsumerEffects, type ConsumerEffect } from "./effects/stateless.ts";
 import { type Services } from "./services.ts";
 import type { Standing } from "./standing.ts";
@@ -40,6 +41,10 @@ export declare abstract class Consumer<M, Out = never> {
     get secrets(): Secrets;
     /** A unit test's store in place of the runtime's: `component.secrets = new InMemorySecrets()`. */
     set secrets(store: Secrets);
+    /** The service's buckets: `this.storage.default`, or `this.storage.bucket("photos")`. */
+    get storage(): Buckets;
+    /** A unit test's store in place of the runtime's: `component.storage = new InMemoryBuckets()`. */
+    set storage(buckets: Buckets);
     /** Other services, called as this one, through the runtime: `this.services.service("orders")`. */
     get services(): Services;
     /** A unit test's in place of the runtime's: `component.services = new ScriptedServices()`. */

package/dist/consumer.js

@@ -1,5 +1,6 @@
 // A consumer: reacts to a source's changes, optionally producing onward to a topic.
 import { secretsFor } from "./client.js";
+import { processStorage } from "./storage.js";
 import { ConsumerEffects } from "./effects/stateless.js";
 import { servicesFor } from "./services.js";
 /** The metadata entry a runtime sets on a consumer's request to say what it speaks: its protocol version. */
@@ -70,6 +71,15 @@ export class Consumer {
     set secrets(store) {
         this.#secrets = store;
     }
+    #storage;
+    /** The service's buckets: `this.storage.default`, or `this.storage.bucket("photos")`. */
+    get storage() {
+        return this.#storage ?? processStorage();
+    }
+    /** A unit test's store in place of the runtime's: `component.storage = new InMemoryBuckets()`. */
+    set storage(buckets) {
+        this.#storage = buckets;
+    }
     #services;
     /** Other services, called as this one, through the runtime: `this.services.service("orders")`. */
     get services() {

package/dist/endpoint.d.ts

@@ -1,4 +1,6 @@
+import { type ClientKeys } from "./client-keys.ts";
 import { type ComponentClient, type Secrets } from "./client.ts";
+import { type Buckets } from "./storage.ts";
 import { type RequestContext } from "./context.ts";
 import type { Acl, RouteTable } from "./routes.ts";
 import { type Services } from "./services.ts";
@@ -12,10 +14,18 @@ export declare abstract class Endpoint {
     get secrets(): Secrets;
     /** A unit test's store in place of the runtime's: `component.secrets = new InMemorySecrets()`. */
     set secrets(store: Secrets);
+    /** The service's buckets: `this.storage.default`, or `this.storage.bucket("photos")`. */
+    get storage(): Buckets;
+    /** A unit test's store in place of the runtime's: `component.storage = new InMemoryBuckets()`. */
+    set storage(buckets: Buckets);
     /** Other services, called as this one, through the runtime: `this.services.service("orders")`. */
     get services(): Services;
     /** A unit test's in place of the runtime's: `component.services = new ScriptedServices()`. */
     set services(services: Services);
+    /** The service's client keys (1.20): issued for its MCP endpoint, kept by the runtime, each shown once. */
+    get clientKeys(): ClientKeys;
+    /** A unit test's in place of the runtime's: `component.clientKeys = new InMemoryClientKeys()`. */
+    set clientKeys(keys: ClientKeys);
     /** @internal */
     _bindClient(client: ComponentClient | undefined): void;
 }

package/dist/endpoint.js

@@ -8,7 +8,9 @@
 //     static readonly routes = { getCart: get("/{cartId}", ShoppingCart, (ep: ShoppingCartEndpoint, req) => ep.getCart(req.params.cartId)) }
 //     getCart(cartId: string) { return this.client.of(ShoppingCartEntity, cartId).call(ShoppingCartEntity.handlers.getCart).invoke() }
 //   }
+import { clientKeysFor } from "./client-keys.js";
 import { secretsFor } from "./client.js";
+import { processStorage } from "./storage.js";
 import { currentRequest, requestIfAny } from "./context.js";
 import { servicesFor } from "./services.js";
 export class Endpoint {
@@ -33,6 +35,15 @@ export class Endpoint {
     set secrets(store) {
         this.#secrets = store;
     }
+    #storage;
+    /** The service's buckets: `this.storage.default`, or `this.storage.bucket("photos")`. */
+    get storage() {
+        return this.#storage ?? processStorage();
+    }
+    /** A unit test's store in place of the runtime's: `component.storage = new InMemoryBuckets()`. */
+    set storage(buckets) {
+        this.#storage = buckets;
+    }
     #services;
     /** Other services, called as this one, through the runtime: `this.services.service("orders")`. */
     get services() {
@@ -42,6 +53,15 @@ export class Endpoint {
     set services(services) {
         this.#services = services;
     }
+    #clientKeys;
+    /** The service's client keys (1.20): issued for its MCP endpoint, kept by the runtime, each shown once. */
+    get clientKeys() {
+        return this.#clientKeys ?? clientKeysFor(this.client);
+    }
+    /** A unit test's in place of the runtime's: `component.clientKeys = new InMemoryClientKeys()`. */
+    set clientKeys(keys) {
+        this.#clientKeys = keys;
+    }
     /** @internal */
     _bindClient(client) {
         this.#client = client;

package/dist/graph.d.ts

@@ -2,6 +2,7 @@ import type { StartFrom } from "./startFrom.ts";
 import { type Codec, type Shape } from "./codec.ts";
 import type { EffectLike, Metadata } from "./effects/common.ts";
 import { type ComponentClient, type ComponentRef, type Secrets } from "./client.ts";
+import { type Buckets } from "./storage.ts";
 import { type Services } from "./services.ts";
 import type { Standing } from "./standing.ts";
 type MaybePromise<T> = T | Promise<T>;
@@ -146,6 +147,10 @@ export declare abstract class GraphConsumer<M> {
     get secrets(): Secrets;
     /** A unit test's store in place of the runtime's: `component.secrets = new InMemorySecrets()`. */
     set secrets(store: Secrets);
+    /** The service's buckets: `this.storage.default`, or `this.storage.bucket("photos")`. */
+    get storage(): Buckets;
+    /** A unit test's store in place of the runtime's: `component.storage = new InMemoryBuckets()`. */
+    set storage(buckets: Buckets);
     /** Other services, called as this one, through the runtime: `this.services.service("orders")`. */
     get services(): Services;
     /** A unit test's in place of the runtime's: `component.services = new ScriptedServices()`. */

package/dist/graph.js

@@ -16,6 +16,7 @@
 //   }
 import { JSON_CONTENT } from "./codec.js";
 import { secretsFor } from "./client.js";
+import { processStorage } from "./storage.js";
 import { sequenceNumberOf } from "./consumer.js";
 import { renderDouble, reviver } from "./json.js";
 import { servicesFor } from "./services.js";
@@ -426,6 +427,15 @@ export class GraphConsumer {
     set secrets(store) {
         this.#secrets = store;
     }
+    #storage;
+    /** The service's buckets: `this.storage.default`, or `this.storage.bucket("photos")`. */
+    get storage() {
+        return this.#storage ?? processStorage();
+    }
+    /** A unit test's store in place of the runtime's: `component.storage = new InMemoryBuckets()`. */
+    set storage(buckets) {
+        this.#storage = buckets;
+    }
     #services;
     /** Other services, called as this one, through the runtime: `this.services.service("orders")`. */
     get services() {

package/dist/index.d.ts

@@ -25,14 +25,19 @@ 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, sseEvents, type SseEvent, socket, type RouteRef, type RouteOptions, type RouteTable, type Params, type ParamNames, type HttpMethod } from "./routes.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";

package/dist/index.js

@@ -36,14 +36,19 @@ 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, sseEvents, socket } from "./routes.js";
 export { Query, Headers } from "./context.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";

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 {};