ankka 0.10.0 → 0.11.0

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 { secretsFor } from "./client.js";
 import { currentRequest, requestIfAny } from "./context.js";
+import { servicesFor } from "./services.js";
 export class Endpoint {
     #client;
     /** The request being handled: path parameters, query, headers, principal. Request-scoped. */
@@ -22,6 +24,24 @@ export class Endpoint {
         const request = requestIfAny();
         return request ? this.#client.withMetadata(request.metadata) : this.#client;
     }
+    #secrets;
+    /** The service's secret store: values kept encrypted in the service's own database, never in a journal or a view. */
+    get secrets() {
+        return this.#secrets ?? secretsFor(this.client);
+    }
+    /** A unit test's store in place of the runtime's: `component.secrets = new InMemorySecrets()`. */
+    set secrets(store) {
+        this.#secrets = store;
+    }
+    #services;
+    /** Other services, called as this one, through the runtime: `this.services.service("orders")`. */
+    get services() {
+        return this.#services ?? servicesFor(this.client);
+    }
+    /** A unit test's in place of the runtime's: `component.services = new ScriptedServices()`. */
+    set services(services) {
+        this.#services = services;
+    }
     /** @internal */
     _bindClient(client) {
         this.#client = client;

package/dist/graph.d.ts

@@ -1,6 +1,8 @@
+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, ComponentRef } from "./client.ts";
+import { type ComponentClient, type ComponentRef, type Secrets } from "./client.ts";
+import { type Services } from "./services.ts";
 type MaybePromise<T> = T | Promise<T>;
 /** The contract's name: the manifest and the `ce-type` of every delta. */
 export declare const GRAPH_DELTA_SCHEMA = "ankka.graph-delta.v1";
@@ -137,6 +139,14 @@ export declare abstract class GraphConsumer<M> {
     /** The change's sequence number, which is the version of every element that states none. */
     get sequenceNumber(): bigint | undefined;
     get client(): ComponentClient;
+    /** The service's secret store: values kept encrypted in the service's own database, never in a journal or a view. */
+    get secrets(): Secrets;
+    /** A unit test's store in place of the runtime's: `component.secrets = new InMemorySecrets()`. */
+    set secrets(store: Secrets);
+    /** 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);
     /** @internal */
     get _kind(): "consumer";
     abstract onMessage(message: M): MaybePromise<GraphEffect>;
@@ -150,6 +160,10 @@ export interface GraphConsumerClass<M = unknown, C extends GraphConsumer<M> = Gr
     readonly componentId: string;
     readonly source?: ComponentRef;
     readonly topic?: string;
+    /** Where a topic source starts the first time its group reads the topic. */
+    readonly startFrom?: StartFrom;
+    /** Raised to read the topic again from the start position, under a group of its own. Absent is 1. */
+    readonly version?: number;
     readonly message: Shape<M>;
     /** The delta topic. It must be compacted to hold the graph; the pipeline that reads it creates it so. */
     readonly producesTo: string;

package/dist/graph.js

@@ -15,8 +15,10 @@
 //     }
 //   }
 import { JSON_CONTENT } from "./codec.js";
+import { secretsFor } from "./client.js";
 import { sequenceNumberOf } from "./consumer.js";
 import { renderDouble, reviver } from "./json.js";
+import { servicesFor } from "./services.js";
 /** The contract's name: the manifest and the `ce-type` of every delta. */
 export const GRAPH_DELTA_SCHEMA = "ankka.graph-delta.v1";
 /** The record key of every delta for the node `id`. */
@@ -410,6 +412,24 @@ export class GraphConsumer {
             throw new Error("client is only available inside onMessage or onDelete");
         return this.#client;
     }
+    #secrets;
+    /** The service's secret store: values kept encrypted in the service's own database, never in a journal or a view. */
+    get secrets() {
+        return this.#secrets ?? secretsFor(this.client);
+    }
+    /** A unit test's store in place of the runtime's: `component.secrets = new InMemorySecrets()`. */
+    set secrets(store) {
+        this.#secrets = store;
+    }
+    #services;
+    /** Other services, called as this one, through the runtime: `this.services.service("orders")`. */
+    get services() {
+        return this.#services ?? servicesFor(this.client);
+    }
+    /** A unit test's in place of the runtime's: `component.services = new ScriptedServices()`. */
+    set services(services) {
+        this.#services = services;
+    }
     /** @internal */
     get _kind() {
         return "consumer";

package/dist/handlers.d.ts

@@ -1,3 +1,4 @@
+import { type Approval } from "./approvals.ts";
 import type { Shape } from "./codec.ts";
 import type { EffectLike, ReadOnlyLike } from "./effects/common.ts";
 export type HandlerKind = "command" | "query" | "stream" | "step" | "action";
@@ -35,14 +36,21 @@ export declare function step<C, E extends EffectLike>(name: string, run: (self:
 /** A timed action: `action("remind", s.string, (t, id) => t.remind(id))`. */
 export declare function action<C, I, E extends EffectLike>(name: string, input: Shape<I>, run: (self: C, input: I) => MaybePromise<E>): HandlerRef<C, I, undefined, E>;
 export declare function action<C, E extends EffectLike>(name: string, run: (self: C) => MaybePromise<E>): HandlerRef<C, undefined, undefined, E>;
-/** An agent tool: the model sees `description` and the JSON Schema of `input`; the process runs `run`. */
+/**
+ * An agent tool: the model sees `description` and the JSON Schema of `input`; the process runs `run`.
+ * With `approval`, the tool waits for a person's decision before it runs: the caller is answered with an
+ * approval request, and the turn goes on when someone decides it.
+ */
 export interface ToolRef<C = unknown, I = unknown> {
     readonly name: string;
     readonly description: string;
     readonly input: Shape<I>;
     readonly run: (self: C, input: I) => MaybePromise<unknown>;
+    readonly approval?: Approval;
 }
-export declare function tool<C, I>(name: string, description: string, input: Shape<I>, run: (self: C, input: I) => MaybePromise<unknown>): ToolRef<C, I>;
+export declare function tool<C, I>(name: string, description: string, input: Shape<I>, run: (self: C, input: I) => MaybePromise<unknown>, options?: {
+    readonly approval?: Approval;
+}): ToolRef<C, I>;
 export type GuardrailStage = "input" | "output";
 /** An agent guardrail: returns a reason to block, or `null` to let the text through. */
 export interface GuardrailRef {

package/dist/handlers.js

@@ -2,6 +2,7 @@
 // and `guardrails` tables. Each carries the wire name, the input and reply schemas, and the function
 // that runs it. The wire name is declared here and nowhere else; renaming the method it calls changes
 // nothing on the wire. These are plain values, so the registry can read them without reflection.
+import { approvalProblem } from "./approvals.js";
 function ref(kind, name, input, reply, run, flags) {
     if (typeof name !== "string" || name.trim() === "")
         throw new TypeError(`a ${kind} needs a wire name`);
@@ -49,13 +50,16 @@ export function action(name, ...rest) {
     const [run] = rest;
     return ref("action", name, undefined, undefined, run, { readOnly: false, streaming: false });
 }
-export function tool(name, description, input, run) {
+export function tool(name, description, input, run, options = {}) {
     if (typeof name !== "string" || name.trim() === "")
         throw new TypeError("a tool needs a name");
     if (typeof description !== "string" || description.trim() === "") {
         throw new TypeError(`tool ${name}: a tool needs a description, or the model cannot choose it`);
     }
-    return Object.freeze({ name, description, input, run });
+    const problem = approvalProblem(options.approval);
+    if (problem)
+        throw new TypeError(`tool ${name}: ${problem}`);
+    return Object.freeze({ name, description, input, run, ...(options.approval !== undefined ? { approval: options.approval } : {}) });
 }
 export function guardrail(name, check) {
     if (typeof name !== "string" || name.trim() === "")

package/dist/index.d.ts

@@ -12,20 +12,28 @@ export { KeyValueEntity, type KeyValueEntityClass } from "./keyValueEntity.ts";
 export { WorkflowEffects, StepEffects, WorkflowUpdateBuilder, StepUpdateBuilder, workflowSettings, type WorkflowEffect, type WorkflowReadOnlyEffect, type WorkflowCommandEffect, type StepEffect, type StepOutcome, type StepRef, type PauseOptions, type WorkflowSettings, type StepSettings, type Recovery, } from "./effects/workflow.ts";
 export { Workflow, type WorkflowClass } from "./workflow.ts";
 export { ViewEffects, ConsumerEffects, TimedActionEffects, type ViewEffect, type ConsumerEffect, type OutgoingMessage, type TimedActionEffect } from "./effects/stateless.ts";
-export { View, type ViewClass } from "./view.ts";
+export { View, declaredQuery, tableOf, type DeclaredQuery, type ViewClass } from "./view.ts";
+export { KeyedView, on, type KeyedSource, type KeyedViewClass, type ViewRows } from "./keyedView.ts";
+export { KeyedViewEffects, type KeyedViewEffect, type RowChange } from "./effects/keyed.ts";
 export { Consumer, ProtocolVersionError, type ConsumerClass } from "./consumer.ts";
+export { Contract, CONTRACT_NAME_RULE, fingerprintOf, type Publication } from "./contract.ts";
 export { GRAPH_DELTA_SCHEMA, Graph, GraphConsumer, GraphEffects, GraphError, edgeKey, elementKey, graphDeltaCodec, nodeKey, readDelta, type Delta, type Element, type GraphConsumerClass, type GraphEffect, type GraphFault, type Properties, type PropertyValue, type Scalar, type Version, } from "./graph.ts";
 export { TimedAction, type TimedActionClass } from "./timedAction.ts";
 export { AgentEffects, type AgentEffect } from "./effects/agent.ts";
 export { Agent, type AgentClass } from "./agent.ts";
+export { ApprovalAwaited, APPROVALS_SINCE, type AgentOutcome, type Approval, type ApprovalRequest, type DecisionInput } from "./approvals.ts";
+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 { Acl, Callers, type CallerMatcher, type CallersAcl, HttpProblem, get, post, put, patch, del, sse, type RouteRef, type RouteOptions, type RouteTable, type Params, type ParamNames, type HttpMethod } from "./routes.ts";
+export { type Socket, SocketClosed } from "./socket.ts";
+export { Acl, Callers, type CallerMatcher, type CallersAcl, HttpProblem, get, post, put, patch, del, sse, sseEvent, type SseEvent, socket, type RouteRef, type RouteOptions, type RouteTable, type Params, type ParamNames, type HttpMethod } from "./routes.ts";
 export { type CommandContext, type RequestContext, type Principal, type Caller, Query, Headers } from "./context.ts";
-export { ComponentClient, Calls, TypedCalls, Invocation, Views, Timers, type TimerTarget, type ComponentRef } from "./client.ts";
-export { Ankka, ServiceBuilder, Registry, RegistrationError, type ServiceOptions, type RegisteredComponent, type RegisteredEndpoint, type Source, type RegisteredEventSourced, type RegisteredKeyValue, type RegisteredWorkflow, type RegisteredView, type RegisteredConsumer, type RegisteredTimedAction, type RegisteredAgent, } from "./service.ts";
+export { ComponentClient, Calls, TypedCalls, Invocation, Views, Timers, Secrets, InMemorySecrets, noSecrets, type TimerTarget, type TimedActionTarget, type ComponentRef } from "./client.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 { PROTOCOL_VERSION, SDK_NAME } from "./spec.ts";
+export { StartFrom } from "./startFrom.ts";
 export { materialiseEventSourced, materialiseKeyValue, materialiseWorkflowCommand, materialiseStep, type Materialised, type MaterialisedKeyValue, type MaterialisedWorkflowCommand, type MaterialisedStep, } from "./materialise.ts";
 export type { ComponentKind } from "./kinds.ts";

package/dist/index.js

@@ -23,19 +23,27 @@ export { KeyValueEntity } from "./keyValueEntity.js";
 export { WorkflowEffects, StepEffects, WorkflowUpdateBuilder, StepUpdateBuilder, workflowSettings, } from "./effects/workflow.js";
 export { Workflow } from "./workflow.js";
 export { ViewEffects, ConsumerEffects, TimedActionEffects } from "./effects/stateless.js";
-export { View } from "./view.js";
+export { View, declaredQuery, tableOf } from "./view.js";
+export { KeyedView, on } from "./keyedView.js";
+export { KeyedViewEffects } from "./effects/keyed.js";
 export { Consumer, ProtocolVersionError } from "./consumer.js";
+export { Contract, CONTRACT_NAME_RULE, fingerprintOf } from "./contract.js";
 export { GRAPH_DELTA_SCHEMA, Graph, GraphConsumer, GraphEffects, GraphError, edgeKey, elementKey, graphDeltaCodec, nodeKey, readDelta, } from "./graph.js";
 export { TimedAction } from "./timedAction.js";
 export { AgentEffects } from "./effects/agent.js";
 export { Agent } from "./agent.js";
+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 { Acl, Callers, HttpProblem, get, post, put, patch, del, sse } from "./routes.js";
+export { SocketClosed } from "./socket.js";
+export { Acl, Callers, HttpProblem, get, post, put, patch, del, sse, sseEvent, socket } from "./routes.js";
 export { Query, Headers } from "./context.js";
-export { ComponentClient, Calls, TypedCalls, Invocation, Views, Timers } from "./client.js";
+export { ComponentClient, Calls, TypedCalls, Invocation, Views, Timers, Secrets, InMemorySecrets, noSecrets } from "./client.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 { PROTOCOL_VERSION, SDK_NAME } from "./spec.js";
+export { StartFrom } from "./startFrom.js";
 export { materialiseEventSourced, materialiseKeyValue, materialiseWorkflowCommand, materialiseStep, } from "./materialise.js";

package/dist/keyedView.d.ts

@@ -0,0 +1,56 @@
+import type { Shape } from "./codec.ts";
+import type { Metadata } from "./effects/common.ts";
+import type { ComponentClient, ComponentRef } from "./client.ts";
+import { KeyedViewEffects, type KeyedViewEffect } from "./effects/keyed.ts";
+import type { DeclaredQuery } from "./view.ts";
+type MaybePromise<T> = T | Promise<T>;
+/** A keyed view's own rows, for the length of one change. It reaches no other view. */
+export interface ViewRows<Row> {
+    /** The row under `key`, or `null`. */
+    get(key: string): Promise<Row | null>;
+    /** The rows of one of this view's declared queries, asked with its values. */
+    ask(name: string, values?: Readonly<Record<string, string>>): Promise<Row[]>;
+}
+/** One source of a keyed view, and what the view does with each of its changes and with its entity's deletion. */
+export interface KeyedSource<V = any, E = any> {
+    readonly source: ComponentRef;
+    readonly events: Shape<E>;
+    readonly onChange: (view: V, event: E) => MaybePromise<KeyedViewEffect<any>>;
+    readonly deleted?: (view: V) => MaybePromise<KeyedViewEffect<any>>;
+}
+/**
+ * Declares a source of a keyed view: the entity whose changes it reads, the shape of those changes, and
+ * the handler for each. When the entity is deleted the view does nothing unless `deleted` names rows.
+ */
+export declare function on<V, E>(source: ComponentRef, events: Shape<E>, onChange: (view: V, event: E) => MaybePromise<KeyedViewEffect<any>>, options?: {
+    readonly deleted?: (view: V) => MaybePromise<KeyedViewEffect<any>>;
+}): KeyedSource<V, E>;
+export declare abstract class KeyedView<Row> {
+    #private;
+    readonly effects: KeyedViewEffects<Row>;
+    /** The change's metadata: `ce-subject` is the source entity's id, `ankka.sequence` its sequence number. */
+    get metadata(): Metadata;
+    /** The id of the entity the change came from. */
+    get subject(): string;
+    /** This view's own rows, by key or by one of its declared queries. */
+    get rows(): ViewRows<Row>;
+    get client(): ComponentClient;
+    /** @internal */
+    get _kind(): "view";
+    /** @internal */
+    _bind(metadata: Metadata, client: ComponentClient | undefined, rows: ViewRows<Row>): void;
+}
+export interface KeyedViewClass<Row = unknown, C extends KeyedView<Row> = KeyedView<Row>> {
+    new (): C;
+    readonly componentId: string;
+    readonly row: Shape<Row>;
+    /** One per entity the view reads, declared with `on(...)`. */
+    readonly sources: readonly KeyedSource<C, any>[];
+    /** Raised to have the view emptied and every source read again from its beginning. Absent is 1. */
+    readonly version?: number;
+    /** The queries the view can be asked by name, by its own handlers among others. */
+    readonly declared?: readonly DeclaredQuery[];
+}
+/** The rows a keyed view reads through the component client, on its own id. */
+export declare function clientRows<Row>(client: ComponentClient, viewId: string, row: Shape<Row>): ViewRows<Row>;
+export {};

package/dist/keyedView.js

@@ -0,0 +1,67 @@
+// A keyed view: several entities' changes, each through a handler of its own, written to whichever rows
+// a change is about, by key. The sidecar runs one projection per source and handles one change at a
+// time across all of them; this process only says which rows each change writes.
+//
+//   export class Shipments extends KeyedView<ShipmentRow> {
+//     static readonly componentId = "shipments"
+//     static readonly row = ShipmentRowShape
+//     static readonly sources = [
+//       on(ShipmentEntity, ShipmentEvents, (v: Shipments, e) => v.onShipment(e)),
+//       on(CustomerEntity, CustomerEvents, (v: Shipments, e) => v.onCustomer(e)),
+//     ]
+//     static readonly declared = [declaredQuery("of-customer", `SELECT payload FROM ${tableOf("shipments")} WHERE ...`)]
+//     async onCustomer(event: CustomerEvent) {
+//       const theirs = await this.rows.ask("of-customer", { customer: this.subject })
+//       return this.effects.updateRows(theirs.map((r) => [r.shipmentId, { ...r, name: event.name }]))
+//     }
+//   }
+import { KeyedViewEffects } from "./effects/keyed.js";
+/**
+ * Declares a source of a keyed view: the entity whose changes it reads, the shape of those changes, and
+ * the handler for each. When the entity is deleted the view does nothing unless `deleted` names rows.
+ */
+export function on(source, events, onChange, options = {}) {
+    return Object.freeze({ source, events, onChange, ...(options.deleted ? { deleted: options.deleted } : {}) });
+}
+export class KeyedView {
+    effects = new KeyedViewEffects();
+    #metadata = {};
+    #client;
+    #rows;
+    /** The change's metadata: `ce-subject` is the source entity's id, `ankka.sequence` its sequence number. */
+    get metadata() {
+        return this.#metadata;
+    }
+    /** The id of the entity the change came from. */
+    get subject() {
+        return this.#metadata["ce-subject"] ?? "";
+    }
+    /** This view's own rows, by key or by one of its declared queries. */
+    get rows() {
+        if (!this.#rows)
+            throw new Error("rows are only available inside a keyed view's handler");
+        return this.#rows;
+    }
+    get client() {
+        if (!this.#client)
+            throw new Error("client is only available inside a keyed view's handler");
+        return this.#client;
+    }
+    /** @internal */
+    get _kind() {
+        return "view";
+    }
+    /** @internal */
+    _bind(metadata, client, rows) {
+        this.#metadata = metadata;
+        this.#client = client;
+        this.#rows = rows;
+    }
+}
+/** The rows a keyed view reads through the component client, on its own id. */
+export function clientRows(client, viewId, row) {
+    return {
+        get: (key) => client.views.get(viewId, key, row),
+        ask: (name, values = {}) => client.views.ask(viewId, name, values, row),
+    };
+}

package/dist/mcp.d.ts

@@ -0,0 +1,57 @@
+import { type Approval } from "./approvals.ts";
+export declare const VARIABLE_PREFIX = "ANKKA_MCP_";
+export declare const TOOL_PREFIX = "mcp__";
+type MaybePromise<T> = T | Promise<T>;
+export interface McpServerOptions {
+    /** Where the server is; `ANKKA_MCP_<NAME>_URL` replaces it, and is required when neither this nor `service` is given. */
+    readonly url?: string;
+    /** An ankka service, called as one, at `path` (by default `/mcp`), in `project` (by default this one). */
+    readonly service?: string;
+    readonly project?: string;
+    readonly path?: string;
+    /** A header's name and the `ANKKA_MCP_` variable its value is read from. */
+    readonly headers?: Readonly<Record<string, string>>;
+    /** Every tool of the server waits for a person. */
+    readonly approval?: Approval;
+}
+export interface McpServerRef extends McpServerOptions {
+    readonly name: string;
+}
+/** An MCP server the agent lists under `name`, lower-case letters, digits and hyphens. */
+export declare function mcpServer(name: string, options?: McpServerOptions): McpServerRef;
+/** Checks what an MCP server's tool answered before the model is told it: a reason to withhold it, or `null`. */
+export interface ResultGuardrailRef {
+    readonly name: string;
+    readonly check: (tool: string, text: string) => MaybePromise<string | null>;
+}
+export declare function resultGuardrail(name: string, check: (tool: string, text: string) => MaybePromise<string | null>): ResultGuardrailRef;
+/** The name a server's tool is offered to the model under. */
+export declare function toolName(server: string, tool: string): string;
+/** What is wrong with one server, in the sidecar's words. */
+export declare function serverProblems(server: McpServerRef): string[];
+/** The discovery form of a server. */
+export declare function serverToProto(server: McpServerRef): {
+    name: string;
+    address: {
+        case: "url";
+        value: string;
+    } | {
+        case: "service";
+        value: {
+            name: string;
+            path: string;
+            project?: string | undefined;
+        };
+    } | {
+        value?: undefined;
+        case: undefined;
+    };
+    headers: {
+        name: string;
+        variable: string;
+    }[];
+    approval?: {
+        withinMillis?: bigint;
+    } | undefined;
+};
+export {};

package/dist/mcp.js

@@ -0,0 +1,64 @@
+// MCP servers an agent offers the model, and the guardrails that check what they answer.
+//
+// The sidecar connects to each server when it starts, reads its tools and offers them to the model as
+// `mcp__<server>__<tool>`. This process is never asked to run one, and never sees a credential: a
+// header's value is read from a variable on the sidecar, and only `ANKKA_MCP_` variables reach it. What a
+// server's tool answers is put through the agent's result guardrails, which this process answers,
+// before the model is told it.
+//
+//   static readonly mcpServers = { tickets: mcpServer("tickets", { headers: { Authorization: "ANKKA_MCP_TICKETS_TOKEN" } }) }
+//   static readonly resultGuardrails = { noInstructions: resultGuardrail("no-instructions", (tool, text) => null) }
+import { approvalProblem, approvalToProto } from "./approvals.js";
+export const VARIABLE_PREFIX = "ANKKA_MCP_";
+export const TOOL_PREFIX = "mcp__";
+const NAME = /^[a-z0-9-]+$/;
+/** An MCP server the agent lists under `name`, lower-case letters, digits and hyphens. */
+export function mcpServer(name, options = {}) {
+    return Object.freeze({ ...options, name });
+}
+export function resultGuardrail(name, check) {
+    if (typeof name !== "string" || name.trim() === "")
+        throw new TypeError("a result guardrail needs a name");
+    return Object.freeze({ name, check });
+}
+/** The name a server's tool is offered to the model under. */
+export function toolName(server, tool) {
+    return `${TOOL_PREFIX}${server}__${tool}`;
+}
+/** What is wrong with one server, in the sidecar's words. */
+export function serverProblems(server) {
+    const found = [];
+    const name = server.name;
+    if (!NAME.test(name))
+        found.push(`an MCP server's name is lower-case letters, digits and hyphens ([a-z0-9-]), not '${name}'`);
+    if (server.url !== undefined && server.service !== undefined)
+        found.push(`MCP server '${name}' has both a URL and a service; give one`);
+    if (server.url !== undefined && server.url.trim() === "")
+        found.push(`MCP server '${name}' needs a URL`);
+    for (const [header, variable] of Object.entries(server.headers ?? {})) {
+        if (header.trim() === "")
+            found.push(`MCP server '${name}' has a header with no name`);
+        else if (!variable.startsWith(VARIABLE_PREFIX)) {
+            found.push(`MCP server '${name}': the header '${header}' takes its value from '${variable}', which must start ${VARIABLE_PREFIX} — only those variables reach the platform's program, which is what connects to the server`);
+        }
+    }
+    const approval = approvalProblem(server.approval);
+    if (approval)
+        found.push(`MCP server '${name}': ${approval}`);
+    return found;
+}
+/** The discovery form of a server. */
+export function serverToProto(server) {
+    const approval = approvalToProto(server.approval);
+    const address = server.url !== undefined
+        ? { case: "url", value: server.url }
+        : server.service !== undefined
+            ? { case: "service", value: { name: server.service, path: server.path ?? "/mcp", ...(server.project !== undefined ? { project: server.project } : {}) } }
+            : { case: undefined };
+    return {
+        name: server.name,
+        address,
+        headers: Object.entries(server.headers ?? {}).map(([name, variable]) => ({ name, variable })),
+        ...(approval !== undefined ? { approval } : {}),
+    };
+}

package/dist/routes.d.ts

@@ -1,3 +1,4 @@
+import type { Socket } from "./socket.ts";
 import type { Shape } from "./codec.ts";
 import type { RequestContext } from "./context.ts";
 import type { Infer, Schema } from "./schema.ts";
@@ -74,8 +75,10 @@ export interface RouteRef<Ep = unknown, P = unknown, B = unknown, R = unknown> {
     readonly body: Shape<B> | undefined;
     readonly reply: Shape<R> | undefined;
     readonly streaming: boolean;
+    /** Answered by opening a socket (protocol 1.9); `run`'s third argument is then the `Socket`. */
+    readonly socket: boolean;
     readonly acl: Acl | undefined;
-    readonly run: (self: Ep, request: RequestContext<P>, body: B) => MaybePromise<R> | AsyncIterable<string>;
+    readonly run: (self: Ep, request: RequestContext<P>, body: B) => MaybePromise<R> | AsyncIterable<string | SseEvent>;
 }
 export declare function parseTemplate(template: string): string[];
 type NoBodyRun<Ep, T extends string, PS, R> = (self: Ep, request: RequestContext<Params<T, PS>>) => MaybePromise<R>;
@@ -100,8 +103,25 @@ export declare const del: {
     <Ep, T extends string, B, R, PS extends Readonly<Record<string, Schema>> = {}>(template: T, body: Shape<B>, reply: Shape<R>, run: BodyRun<Ep, T, PS, B, R>, options?: RouteOptions<PS>): RouteRef<Ep, Params<T, PS>, B, R>;
     <Ep, T extends string, R, PS extends Readonly<Record<string, Schema>> = {}>(template: T, reply: Shape<R>, run: NoBodyRun<Ep, T, PS, R>, options?: RouteOptions<PS>): RouteRef<Ep, Params<T, PS>, undefined, R>;
 };
-/** A server-sent-events route: the handler returns an `AsyncIterable<string>`, one frame per string. */
-export declare function sse<Ep, T extends string, PS extends Readonly<Record<string, Schema>> = {}>(template: T, run: (self: Ep, request: RequestContext<Params<T, PS>>) => AsyncIterable<string> | Promise<AsyncIterable<string>>, options?: RouteOptions<PS>): RouteRef<Ep, Params<T, PS>, undefined, never>;
+/**
+ * A server-sent event under a name of its own, which an `sse` handler may yield beside text: an agent
+ * turn that stops for approval ends its stream with `sseEvent("approval", requests)`. `value` is sent as
+ * JSON. Needs protocol 1.11 of the runtime.
+ */
+export interface SseEvent {
+    readonly kind: "sse-event";
+    readonly name: string;
+    readonly value: unknown;
+}
+export declare function sseEvent(name: string, value: unknown): SseEvent;
+/** A server-sent-events route: the handler returns an `AsyncIterable<string | SseEvent>`, one frame per string, and may yield an `SseEvent` among them. */
+export declare function sse<Ep, T extends string, PS extends Readonly<Record<string, Schema>> = {}>(template: T, run: (self: Ep, request: RequestContext<Params<T, PS>>) => AsyncIterable<string | SseEvent> | Promise<AsyncIterable<string | SseEvent>>, options?: RouteOptions<PS>): RouteRef<Ep, Params<T, PS>, undefined, never>;
+/**
+ * A socket route: `socket("/{room}", async (ep: Rooms, req, socket) => { for await (const t of socket) await socket.send(t) })`.
+ * The handler runs for as long as the socket is open, with the opening request as `req` throughout.
+ * Needs protocol 1.9 of the runtime.
+ */
+export declare function socket<Ep, T extends string, PS extends Readonly<Record<string, Schema>> = {}>(template: T, run: (self: Ep, request: RequestContext<Params<T, PS>>, socket: Socket) => Promise<void>, options?: RouteOptions<PS>): RouteRef<Ep, Params<T, PS>, Socket, void>;
 /** The routes table type an endpoint declares. */
 export type RouteTable<Ep> = Readonly<Record<string, RouteRef<Ep, any, any, any>>>;
 export {};

package/dist/routes.js

@@ -57,7 +57,7 @@ export function parseTemplate(template) {
         throw new TypeError(`route template ${template} repeats a parameter`);
     return names;
 }
-function route(method, template, body, reply, run, options, streaming) {
+function route(method, template, body, reply, run, options, streaming, socket = false) {
     const paramNames = parseTemplate(template);
     if (typeof run !== "function")
         throw new TypeError(`route ${method} ${template}: the handler is not a function`);
@@ -68,7 +68,7 @@ function route(method, template, body, reply, run, options, streaming) {
         if (!paramNames.includes(name))
             throw new TypeError(`route ${method} ${template}: params names ${name}, which is not in the template`);
     }
-    return Object.freeze({ method, template, paramNames, paramShapes, body, reply, streaming, acl: options?.acl, run });
+    return Object.freeze({ method, template, paramNames, paramShapes, body, reply, streaming, socket, acl: options?.acl, run });
 }
 function isShape(x) {
     return typeof x === "object" && x !== null && (typeof x.kind === "string" || isCodec(x));
@@ -96,7 +96,20 @@ 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 server-sent-events route: the handler returns an `AsyncIterable<string>`, one frame per string. */
+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)}`);
+    return Object.freeze({ kind: "sse-event", name, value });
+}
+/** A server-sent-events route: the handler returns an `AsyncIterable<string | SseEvent>`, one frame per string, and may yield an `SseEvent` among them. */
 export function sse(template, run, options) {
     return route("GET", template, undefined, undefined, run, options, true);
 }
+/**
+ * A socket route: `socket("/{room}", async (ep: Rooms, req, socket) => { for await (const t of socket) await socket.send(t) })`.
+ * The handler runs for as long as the socket is open, with the opening request as `req` throughout.
+ * Needs protocol 1.9 of the runtime.
+ */
+export function socket(template, run, options) {
+    return route("GET", template, undefined, undefined, run, options, false, true);
+}

package/dist/server/agent.js

@@ -84,7 +84,10 @@ export async function handleTool(req, ctx) {
     if (!registered)
         return create(ToolResultSchema, { result: { case: "error", value: `no agent ${JSON.stringify(req.componentId)} is registered` } });
     const agent = new registered.cls();
-    agent._bind(req.sessionId, {}, ctx.client);
+    // What the sidecar says about the tool's run: its trace, and the agent's handler as the caller of
+    // whatever the tool calls. A sidecar before 1.3 sends none.
+    const metadata = metadataFromProto(req.metadata);
+    agent._bind(req.sessionId, metadata, ctx.client.withMetadata(metadata));
     try {
         return create(ToolResultSchema, { result: { case: "ok", value: await runTool(registered, agent, req.tool, req.argumentsJson) } });
     }
@@ -95,11 +98,16 @@ export async function handleTool(req, ctx) {
 }
 export async function handleGuardrail(req, ctx) {
     const registered = ctx.registry.of("agent", req.componentId) ?? ctx.registry.of("autonomous-agent", req.componentId);
-    const guardrail = registered?.guardrails.get(req.guardrail);
+    // RESULT (1.11): what an MCP server's tool answered, checked by one of the agent's result guardrails,
+    // which are declared apart from its other guardrails.
+    const result = req.stage === GuardrailRequest_Stage.RESULT;
+    const guardrail = result ? registered?.resultGuardrails.get(req.guardrail) : registered?.guardrails.get(req.guardrail);
     if (!registered || !guardrail)
         return create(GuardrailResultSchema, { result: { case: "block", value: `no guardrail ${JSON.stringify(req.guardrail)} on ${req.componentId}` } });
     try {
-        const reason = await guardrail.check(req.stage === GuardrailRequest_Stage.OUTPUT ? "output" : "input", req.text);
+        const reason = result
+            ? await guardrail.check(req.tool ?? "", req.text)
+            : await guardrail.check(req.stage === GuardrailRequest_Stage.OUTPUT ? "output" : "input", req.text);
         return reason === null || reason === undefined
             ? create(GuardrailResultSchema, { result: { case: "pass", value: {} } })
             : create(GuardrailResultSchema, { result: { case: "block", value: reason } });
@@ -114,7 +122,7 @@ async function handleAutonomousTool(registered, req, ctx) {
     if (!tool)
         return create(ToolResultSchema, { result: { case: "error", value: `no tool ${JSON.stringify(req.tool)} on ${registered.id}` } });
     const agent = new registered.cls();
-    agent._bind(req.sessionId, ctx.client);
+    agent._bind(req.sessionId, ctx.client.withMetadata(metadataFromProto(req.metadata)));
     try {
         let input;
         if (isCodec(tool.input))

package/dist/server/discovery.d.ts

@@ -1,5 +1,16 @@
-import type { ConnectRouter } from "@connectrpc/connect";
+import { type ConnectRouter } from "@connectrpc/connect";
 import { type Spec } from "../_proto/ankka/protocol/v1/discovery_pb.ts";
+/**
+ * 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 declare function refusal(spec: Spec, sidecarProtocol: string): string | undefined;
 /** 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;
+/** The protocol version whose runtimes serve socket routes. */
+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;