ankka 0.6.0

package/dist/routes.js

@@ -0,0 +1,79 @@
+// Route declarations for an endpoint's static `routes` table, and the access rules. A route names its
+// template, its body and reply shapes and the function that runs it; the sidecar serves the route,
+// applies the access rule and forwards the request, and the process only runs the handler.
+//
+//   static readonly routes = {
+//     addItem: post("/{cartId}/items", LineItem, Done, (ep: CartEndpoint, req, item) => ep.addItem(req.params.cartId, item)),
+//     getCart: get("/{cartId}", ShoppingCart, (ep: CartEndpoint, req) => ep.getCart(req.params.cartId)),
+//   }
+//
+// `req.params` is typed from the template: "/{cartId}/items" gives { cartId: string }.
+import { isCodec } from "./codec.js";
+/** Who may call: everyone, no one, or authenticated callers only. There is no default. */
+export const Acl = Object.freeze({
+    allowAll: "allow-all",
+    denyAll: "deny-all",
+    authenticated: "authenticated",
+});
+/** Thrown from a route handler to answer a status other than 200 with a plain-text message. */
+export class HttpProblem extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.name = "HttpProblem";
+        this.status = status;
+    }
+}
+const TEMPLATE = /^(\/(?:[^/{}]+|\{[A-Za-z_][A-Za-z0-9_]*\})?)*$/;
+export function parseTemplate(template) {
+    if (typeof template !== "string" || !template.startsWith("/") || !TEMPLATE.test(template) || template.includes("//")) {
+        throw new TypeError(`not a route template: ${JSON.stringify(template)} (segments are literals or {name})`);
+    }
+    const names = [...template.matchAll(/\{([A-Za-z_][A-Za-z0-9_]*)\}/g)].map((m) => m[1]);
+    if (new Set(names).size !== names.length)
+        throw new TypeError(`route template ${template} repeats a parameter`);
+    return names;
+}
+function route(method, template, body, reply, run, options, streaming) {
+    const paramNames = parseTemplate(template);
+    if (typeof run !== "function")
+        throw new TypeError(`route ${method} ${template}: the handler is not a function`);
+    if (method === "GET" && body !== undefined)
+        throw new TypeError(`route GET ${template} cannot have a body`);
+    const paramShapes = options?.params ?? {};
+    for (const name of Object.keys(paramShapes)) {
+        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 });
+}
+function isShape(x) {
+    return typeof x === "object" && x !== null && (typeof x.kind === "string" || isCodec(x));
+}
+/** A GET route: `get("/{cartId}", ShoppingCart, (ep: CartEndpoint, req) => ep.getCart(req.params.cartId))`. */
+export function get(template, reply, run, options) {
+    return route("GET", template, undefined, reply, run, options, false);
+}
+function withBody(method) {
+    function declare(template, ...rest) {
+        if (typeof rest[1] === "function") {
+            const [reply, run, options] = rest;
+            return route(method, template, undefined, reply, run, options, false);
+        }
+        const [body, reply, run, options] = rest;
+        if (!isShape(body))
+            throw new TypeError(`route ${method} ${template}: expected a body shape`);
+        return route(method, template, body, reply, run, options, false);
+    }
+    return declare;
+}
+/** A POST route, with a body (`post(template, Body, Reply, run)`) or without (`post(template, Reply, run)`). */
+export const post = withBody("POST");
+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 sse(template, run, options) {
+    return route("GET", template, undefined, undefined, run, options, true);
+}

package/dist/schema.d.ts

@@ -0,0 +1,112 @@
+import type { Duration, Instant, LocalDate, LocalDateTime } from "./time.ts";
+/** The one value of type `Done`: a handler that has nothing to say. */
+export declare const done: Readonly<{
+    readonly done: true;
+}>;
+export type Done = typeof done;
+export type ScalarKind = "string" | "int" | "long" | "double" | "boolean" | "instant" | "duration" | "localDate" | "localDateTime" | "bytes" | "unit" | "done";
+/** The structure of a schema, without its type parameter. `resolve` narrows away `lazy`. */
+export type Shape = {
+    readonly kind: ScalarKind;
+} | {
+    readonly kind: "option";
+    readonly inner: Schema;
+} | {
+    readonly kind: "list";
+    readonly inner: Schema;
+} | {
+    readonly kind: "stringMap";
+    readonly inner: Schema;
+} | {
+    readonly kind: "record";
+    readonly name: string;
+    readonly fields: Readonly<Record<string, Schema>>;
+} | {
+    readonly kind: "sumType";
+    readonly name: string;
+    readonly cases: Readonly<Record<string, Readonly<Record<string, Schema>>>>;
+} | {
+    readonly kind: "enumeration";
+    readonly name: string;
+    readonly values: readonly string[];
+} | {
+    readonly kind: "lazy";
+    readonly thunk: () => Schema;
+};
+interface Typed<T> {
+    /** Phantom: carries the TypeScript type. Never set. */
+    readonly _type?: T;
+}
+/** A shape declaration carrying the TypeScript type it describes. */
+export type Schema<T = unknown> = Typed<T> & Shape;
+/** The TypeScript type a schema describes: `type Cart = Infer<typeof Cart>`. */
+export type Infer<S> = S extends Typed<infer T> ? T : never;
+type Simplify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+type InferFields<F extends Readonly<Record<string, Schema>>> = Simplify<{
+    [K in keyof F]: Infer<F[K]>;
+}>;
+type InferCases<C extends Readonly<Record<string, Readonly<Record<string, Schema>>>>> = {
+    [K in keyof C & string]: Simplify<{
+        type: K;
+    } & InferFields<C[K]>>;
+}[keyof C & string];
+export declare class SchemaError extends Error {
+    constructor(message: string);
+}
+/** The schema builders. `import { s } from "ankka"` and declare shapes with `s.record(...)`. */
+export declare const s: Readonly<{
+    /** A JSON string. At top level: the `string` text payload. */
+    string: Schema<string>;
+    /** A whole number within ±2⁵³, as a JavaScript `number`. At top level: the `int` text payload. */
+    int: Schema<number>;
+    /** A 64-bit whole number, as a `bigint`, lossless past 2⁵³. At top level: the `long` text payload. */
+    long: Schema<bigint>;
+    /** A double-precision number, rendered as the Scala codecs render it (`1.0`, `1.0E10`). */
+    double: Schema<number>;
+    boolean: Schema<boolean>;
+    /** ISO-8601 in UTC with 0, 3, 6 or 9 fractional digits. */
+    instant: Schema<Instant>;
+    /** ISO-8601, `PT1.5S`. */
+    duration: Schema<Duration>;
+    localDate: Schema<LocalDate>;
+    localDateTime: Schema<LocalDateTime>;
+    /** Base64 inside JSON; at top level the raw `bytes` payload. */
+    bytes: Schema<Uint8Array<ArrayBufferLike>>;
+    /** No value: the `unit` payload of zero bytes. */
+    unit: Schema<undefined>;
+    /** `T | null`: written as `null` when absent; an absent field reads as `null`. */
+    option<T>(inner: Schema<T>): Schema<T | null>;
+    list<T>(inner: Schema<T>): Schema<T[]>;
+    stringMap<T>(inner: Schema<T>): Schema<Record<string, T>>;
+    /** A record: a JSON object with every field written, in declaration order. `name` is the default manifest. */
+    record<F extends Readonly<Record<string, Schema>>>(name: string, fields: F): Schema<InferFields<F>>;
+    /**
+     * A sum type: each case is an object carrying `"type": "<CaseName>"` and the case's fields, which is
+     * also how a TypeScript discriminated union reads. `s.sumType("Event", { Added: { item: Item }, Done: {} })`
+     * gives `{ type: "Added"; item: Item } | { type: "Done" }`.
+     */
+    sumType<C extends Readonly<Record<string, Readonly<Record<string, Schema>>>>>(name: string, cases: C): Schema<InferCases<C>>;
+    /** A fieldless enumeration used as a field: `{"type":"Ready"}` on the wire, `"Ready"` in TypeScript. */
+    enumeration<const V extends readonly [string, ...string[]]>(name: string, ...values: V): Schema<V[number]>;
+    /** A reference to a schema declared later, for recursive shapes: `s.list(s.lazy(() => Tree))`. */
+    lazy<T>(thunk: () => Schema<T>): Schema<T>;
+}>;
+/** The schema of `done`: the empty `done` payload. */
+export declare const Done: Schema<Done>;
+type Resolved<T> = Typed<T> & Exclude<Shape, {
+    kind: "lazy";
+}>;
+/** Follows `lazy` references to the schema they name. */
+export declare function resolve<T>(schema: Schema<T>): Resolved<T>;
+/** A short description for error messages: `record Cart`, `list<int>`, `string`. */
+export declare function describe(schema: Schema): string;
+/** The default manifest for a schema: a record's, sum type's or enumeration's name; a scalar's text manifest. */
+export declare function defaultManifest(schema: Schema): string;
+/**
+ * JSON Schema (draft 2020-12 vocabulary) for a shape, as an agent tool's input needs it. Objects refuse
+ * unknown properties; integers are `integer`; instants are `string` with `format: date-time`.
+ */
+export declare function toJsonSchema(schema: Schema): Record<string, unknown>;
+export {};

package/dist/schema.js

@@ -0,0 +1,200 @@
+// Shape declarations. TypeScript erases its types, so every value that crosses the protocol is
+// declared once as a `Schema`, and two things are derived from it: the static type (`Infer`) and the
+// codec (`codec.ts`). A schema does what a validation library would not for this encoding: it says
+// whether a number is an `int` or a `double`, carries a `long` as `bigint`, and names records so the
+// default manifest exists. Nothing here performs I/O or touches JSON; that is `json.ts`.
+/** The one value of type `Done`: a handler that has nothing to say. */
+export const done = Object.freeze({ done: true });
+export class SchemaError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "SchemaError";
+    }
+}
+function scalar(kind) {
+    return Object.freeze({ kind });
+}
+function checkName(what, name) {
+    if (typeof name !== "string" || name.trim() === "")
+        throw new SchemaError(`a ${what} needs a name`);
+}
+/** The schema builders. `import { s } from "ankka"` and declare shapes with `s.record(...)`. */
+export const s = Object.freeze({
+    /** A JSON string. At top level: the `string` text payload. */
+    string: scalar("string"),
+    /** A whole number within ±2⁵³, as a JavaScript `number`. At top level: the `int` text payload. */
+    int: scalar("int"),
+    /** A 64-bit whole number, as a `bigint`, lossless past 2⁵³. At top level: the `long` text payload. */
+    long: scalar("long"),
+    /** A double-precision number, rendered as the Scala codecs render it (`1.0`, `1.0E10`). */
+    double: scalar("double"),
+    boolean: scalar("boolean"),
+    /** ISO-8601 in UTC with 0, 3, 6 or 9 fractional digits. */
+    instant: scalar("instant"),
+    /** ISO-8601, `PT1.5S`. */
+    duration: scalar("duration"),
+    localDate: scalar("localDate"),
+    localDateTime: scalar("localDateTime"),
+    /** Base64 inside JSON; at top level the raw `bytes` payload. */
+    bytes: scalar("bytes"),
+    /** No value: the `unit` payload of zero bytes. */
+    unit: scalar("unit"),
+    /** `T | null`: written as `null` when absent; an absent field reads as `null`. */
+    option(inner) {
+        return Object.freeze({ kind: "option", inner });
+    },
+    list(inner) {
+        return Object.freeze({ kind: "list", inner });
+    },
+    stringMap(inner) {
+        return Object.freeze({ kind: "stringMap", inner });
+    },
+    /** A record: a JSON object with every field written, in declaration order. `name` is the default manifest. */
+    record(name, fields) {
+        checkName("record", name);
+        return Object.freeze({ kind: "record", name, fields: Object.freeze({ ...fields }) });
+    },
+    /**
+     * A sum type: each case is an object carrying `"type": "<CaseName>"` and the case's fields, which is
+     * also how a TypeScript discriminated union reads. `s.sumType("Event", { Added: { item: Item }, Done: {} })`
+     * gives `{ type: "Added"; item: Item } | { type: "Done" }`.
+     */
+    sumType(name, cases) {
+        checkName("sum type", name);
+        const names = Object.keys(cases);
+        if (names.length === 0)
+            throw new SchemaError(`sum type ${name} has no cases`);
+        for (const c of names) {
+            if (c === "type")
+                throw new SchemaError(`sum type ${name}: a case cannot be named "type", the discriminator`);
+            if ("type" in cases[c])
+                throw new SchemaError(`sum type ${name}, case ${c}: a field cannot be named "type", the discriminator`);
+        }
+        const frozen = {};
+        for (const c of names)
+            frozen[c] = Object.freeze({ ...cases[c] });
+        return Object.freeze({ kind: "sumType", name, cases: Object.freeze(frozen) });
+    },
+    /** A fieldless enumeration used as a field: `{"type":"Ready"}` on the wire, `"Ready"` in TypeScript. */
+    enumeration(name, ...values) {
+        checkName("enumeration", name);
+        if (new Set(values).size !== values.length)
+            throw new SchemaError(`enumeration ${name} repeats a value`);
+        return Object.freeze({ kind: "enumeration", name, values: Object.freeze([...values]) });
+    },
+    /** A reference to a schema declared later, for recursive shapes: `s.list(s.lazy(() => Tree))`. */
+    lazy(thunk) {
+        return Object.freeze({ kind: "lazy", thunk });
+    },
+});
+/** The schema of `done`: the empty `done` payload. */
+export const Done = scalar("done");
+/** Follows `lazy` references to the schema they name. */
+export function resolve(schema) {
+    let current = schema;
+    for (let i = 0; i < 64 && current.kind === "lazy"; i++)
+        current = current.thunk();
+    if (current.kind === "lazy")
+        throw new SchemaError("a lazy schema never resolves");
+    return current;
+}
+/** A short description for error messages: `record Cart`, `list<int>`, `string`. */
+export function describe(schema) {
+    const r = resolve(schema);
+    switch (r.kind) {
+        case "record":
+            return `record ${r.name}`;
+        case "sumType":
+            return `sum type ${r.name}`;
+        case "enumeration":
+            return `enumeration ${r.name}`;
+        case "option":
+            return `option<${describe(r.inner)}>`;
+        case "list":
+            return `list<${describe(r.inner)}>`;
+        case "stringMap":
+            return `map<string, ${describe(r.inner)}>`;
+        default:
+            return r.kind;
+    }
+}
+/** The default manifest for a schema: a record's, sum type's or enumeration's name; a scalar's text manifest. */
+export function defaultManifest(schema) {
+    const r = resolve(schema);
+    switch (r.kind) {
+        case "record":
+        case "sumType":
+        case "enumeration":
+            return r.name;
+        case "option":
+            return `option[${defaultManifest(r.inner)}]`;
+        case "list":
+            return `list[${defaultManifest(r.inner)}]`;
+        case "stringMap":
+            return `map[${defaultManifest(r.inner)}]`;
+        default:
+            return r.kind;
+    }
+}
+/**
+ * JSON Schema (draft 2020-12 vocabulary) for a shape, as an agent tool's input needs it. Objects refuse
+ * unknown properties; integers are `integer`; instants are `string` with `format: date-time`.
+ */
+export function toJsonSchema(schema) {
+    const r = resolve(schema);
+    switch (r.kind) {
+        case "string":
+            return { type: "string" };
+        case "int":
+        case "long":
+            return { type: "integer" };
+        case "double":
+            return { type: "number" };
+        case "boolean":
+            return { type: "boolean" };
+        case "instant":
+            return { type: "string", format: "date-time" };
+        case "duration":
+            return { type: "string", format: "duration" };
+        case "localDate":
+            return { type: "string", format: "date" };
+        case "localDateTime":
+            return { type: "string", format: "date-time" };
+        case "bytes":
+            return { type: "string", contentEncoding: "base64" };
+        case "unit":
+        case "done":
+            return { type: "null" };
+        case "option":
+            return { anyOf: [toJsonSchema(r.inner), { type: "null" }] };
+        case "list":
+            return { type: "array", items: toJsonSchema(r.inner) };
+        case "stringMap":
+            return { type: "object", additionalProperties: toJsonSchema(r.inner) };
+        case "record":
+            return objectSchema(r.fields);
+        case "sumType":
+            return {
+                oneOf: Object.entries(r.cases).map(([name, fields]) => {
+                    const o = objectSchema(fields);
+                    return {
+                        ...o,
+                        properties: { type: { const: name }, ...o.properties },
+                        required: ["type", ...o.required],
+                    };
+                }),
+            };
+        case "enumeration":
+            return { type: "object", properties: { type: { enum: [...r.values] } }, required: ["type"], additionalProperties: false };
+    }
+}
+function objectSchema(fields) {
+    const properties = {};
+    const required = [];
+    for (const [name, field] of Object.entries(fields)) {
+        properties[name] = toJsonSchema(field);
+        if (resolve(field).kind !== "option")
+            required.push(name);
+    }
+    return { type: "object", properties, required, additionalProperties: false };
+}

package/dist/server/agent.d.ts

@@ -0,0 +1,14 @@
+import type { ConnectRouter } from "@connectrpc/connect";
+import { type GuardrailRequest, type GuardrailResult, type PlanReply, type PlanRequest, type ToolRequest, type ToolResult } from "../_proto/ankka/protocol/v1/agent_pb.ts";
+import type { AgentEffect } from "../effects/agent.ts";
+import type { Agent } from "../agent.ts";
+import type { RegisteredAgent } from "../service.ts";
+import type { ServerContext } from "./server.ts";
+/** Checks a plan against the declaration: a plan may only name tools and guardrails discovery declared. */
+export declare function checkPlan(registered: RegisteredAgent, effect: AgentEffect<unknown>): string | undefined;
+export declare function handlePlan(req: PlanRequest, ctx: ServerContext): Promise<PlanReply>;
+/** Runs a tool: the model's arguments, as JSON text, decoded with the tool's input shape; the result as text for the model. */
+export declare function runTool(registered: RegisteredAgent, agent: Agent, name: string, argumentsJson: string): Promise<string>;
+export declare function handleTool(req: ToolRequest, ctx: ServerContext): Promise<ToolResult>;
+export declare function handleGuardrail(req: GuardrailRequest, ctx: ServerContext): Promise<GuardrailResult>;
+export declare function agentRoutes(router: ConnectRouter, ctx: ServerContext): void;

package/dist/server/agent.js

@@ -0,0 +1,113 @@
+// The agent conversation: the sidecar asks this process to plan (an AgentEffect as data), to run a tool
+// with the model's arguments, and to check a guardrail. The loop, the memory and the model's key are
+// the sidecar's.
+import { create } from "@bufbuild/protobuf";
+import { Agent as AgentService, AgentPlan_Memory, GuardrailRequest_Stage, GuardrailResultSchema, PlanReplySchema, ToolResultSchema, } from "../_proto/ankka/protocol/v1/agent_pb.js";
+import { codecFor, isCodec } from "../codec.js";
+import { metadataFromProto } from "../context.js";
+import { ErrorCode } from "../effects/common.js";
+import { decodeJsonValue, reviver } from "../json.js";
+import { errorCodeToProto } from "../kinds.js";
+import { decodePayload } from "./payloads.js";
+function messageOf(e) {
+    return e instanceof Error ? e.message : String(e);
+}
+function planFailure(commandId, error) {
+    return create(PlanReplySchema, { message: { case: "failure", value: { commandId, error: { message: error.message, code: errorCodeToProto(error.code) } } } });
+}
+/** Checks a plan against the declaration: a plan may only name tools and guardrails discovery declared. */
+export function checkPlan(registered, effect) {
+    const unknown = [...effect.toolNames.filter((t) => !registered.tools.has(t)).map((t) => `tool ${JSON.stringify(t)}`), ...effect.guardrailNames.filter((g) => !registered.guardrails.has(g)).map((g) => `guardrail ${JSON.stringify(g)}`)];
+    return unknown.length > 0 ? `${registered.id}: the plan names undeclared ${unknown.join(", ")}` : undefined;
+}
+export async function handlePlan(req, ctx) {
+    const registered = ctx.registry.of("agent", req.componentId);
+    if (!registered)
+        return planFailure(0n, { message: `no agent ${JSON.stringify(req.componentId)} is registered`, code: ErrorCode.NotFound });
+    const handler = registered.handlers.get(req.name);
+    if (!handler)
+        return planFailure(0n, { message: `no handler ${JSON.stringify(req.name)} on ${registered.id}`, code: ErrorCode.NotFound });
+    const metadata = metadataFromProto(req.metadata);
+    const agent = new registered.cls();
+    agent._bind(req.sessionId, metadata, ctx.client.withMetadata(metadata));
+    let effect;
+    try {
+        const input = handler.input ? decodePayload(codecFor(handler.input), req.payload) : undefined;
+        effect = (await handler.run(agent, input));
+        if (effect?.kind !== "agent")
+            throw new TypeError(`${registered.id}/${req.name} returned something that is not an agent effect`);
+        const problem = checkPlan(registered, effect);
+        if (problem)
+            throw new Error(problem);
+    }
+    catch (e) {
+        ctx.log(`ankka: agent ${registered.id}/${req.sessionId}/${req.name} threw: ${messageOf(e)}`);
+        return planFailure(0n, { message: messageOf(e), code: ErrorCode.Internal });
+    }
+    return create(PlanReplySchema, {
+        message: {
+            case: "plan",
+            value: {
+                ...(effect.model !== null ? { model: effect.model } : {}),
+                ...(effect.system !== null ? { system: effect.system } : {}),
+                ...(effect.user !== null ? { user: effect.user } : {}),
+                context: [...effect.context],
+                memory: effect.sessionMemory ? AgentPlan_Memory.SESSION : AgentPlan_Memory.NONE,
+                tools: [...effect.toolNames],
+                guardrails: [...effect.guardrailNames],
+                responseShape: effect.jsonReply ? { shape: { case: "json", value: { schemaHint: effect.schemaHint } } } : { shape: { case: "text", value: {} } },
+                ...(effect.failure ? { failure: { message: effect.failure.message, code: errorCodeToProto(effect.failure.code) } } : {}),
+            },
+        },
+    });
+}
+/** Runs a tool: the model's arguments, as JSON text, decoded with the tool's input shape; the result as text for the model. */
+export async function runTool(registered, agent, name, argumentsJson) {
+    const tool = registered.tools.get(name);
+    if (!tool)
+        throw new Error(`no tool ${JSON.stringify(name)} on ${registered.id}`);
+    let input;
+    if (isCodec(tool.input))
+        input = tool.input.decode(new TextEncoder().encode(argumentsJson));
+    else
+        input = decodeJsonValue(tool.input, JSON.parse(argumentsJson || "{}", reviver));
+    const result = await tool.run(agent, input);
+    return typeof result === "string" ? result : JSON.stringify(result, (_k, v) => (typeof v === "bigint" ? v.toString() : v));
+}
+export async function handleTool(req, ctx) {
+    const registered = ctx.registry.of("agent", req.componentId);
+    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);
+    try {
+        return create(ToolResultSchema, { result: { case: "ok", value: await runTool(registered, agent, req.tool, req.argumentsJson) } });
+    }
+    catch (e) {
+        // A tool error is fed back to the model, which usually corrects itself.
+        return create(ToolResultSchema, { result: { case: "error", value: messageOf(e) } });
+    }
+}
+export async function handleGuardrail(req, ctx) {
+    const registered = ctx.registry.of("agent", req.componentId);
+    const 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);
+        return reason === null || reason === undefined
+            ? create(GuardrailResultSchema, { result: { case: "pass", value: {} } })
+            : create(GuardrailResultSchema, { result: { case: "block", value: reason } });
+    }
+    catch (e) {
+        ctx.log(`ankka: guardrail ${registered.id}/${req.guardrail} threw: ${messageOf(e)}`);
+        return create(GuardrailResultSchema, { result: { case: "block", value: `guardrail ${req.guardrail} failed: ${messageOf(e)}` } });
+    }
+}
+export function agentRoutes(router, ctx) {
+    router.service(AgentService, {
+        plan: (req) => handlePlan(req, ctx),
+        invokeTool: (req) => handleTool(req, ctx),
+        checkGuardrail: (req) => handleGuardrail(req, ctx),
+    });
+}

package/dist/server/discovery.d.ts

@@ -0,0 +1,5 @@
+import type { ConnectRouter } from "@connectrpc/connect";
+import { type Spec } from "../_proto/ankka/protocol/v1/discovery_pb.ts";
+/** 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;

package/dist/server/discovery.js

@@ -0,0 +1,21 @@
+// Discovery: the first conversation. The sidecar asks what we host; we answer with the Spec the
+// registry renders. `ReportError` is how the sidecar tells us why it refused to start — logged, and kept
+// so a service can expose it (the conformance reference does, at GET /conformance/problems).
+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";
+/** 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})`);
+            return spec();
+        },
+        async reportError(problem) {
+            log(`ankka: the sidecar refused to start: ${problem.message}`);
+            problems.push(problem.message);
+            return create(EmptySchema);
+        },
+    });
+}

package/dist/server/eventSourced.d.ts

@@ -0,0 +1,12 @@
+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 { RetentionSchema } from "../_proto/ankka/protocol/v1/payload_pb.ts";
+import { type Retention } from "../effects/common.ts";
+import type { ServerContext } from "./server.ts";
+type RetentionInit = MessageInitShape<typeof RetentionSchema>;
+/** 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;
+export declare function handleEventSourced(requests: AsyncIterable<EventSourcedIn>, ctx: ServerContext): AsyncIterable<EventSourcedOut>;
+export {};