ankka 0.9.1 → 0.11.0

package/dist/startFrom.js

@@ -0,0 +1,44 @@
+// Where a topic source starts, and what a view or consumer that reads a topic may declare about it.
+export const StartFrom = Object.freeze({
+    /** The oldest message the broker still holds. */
+    earliest: Object.freeze({ kind: "earliest" }),
+    /** After the newest: only what is published from then on. */
+    latest: Object.freeze({ kind: "latest" }),
+    /** The first message published at or after `when`. */
+    at(when) {
+        const atMillis = when instanceof Date ? when.getTime() : Number.NaN;
+        if (!Number.isFinite(atMillis))
+            throw new TypeError(`StartFrom.at needs a valid Date, not ${String(when)}`);
+        return Object.freeze({ kind: "at", atMillis });
+    },
+});
+/** The first protocol in which a process can declare a start position or a version. */
+export const START_POSITION_PROTOCOL = [1, 7];
+export function isStartFrom(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const kind = value.kind;
+    if (kind === "earliest" || kind === "latest")
+        return true;
+    return kind === "at" && Number.isFinite(value.atMillis);
+}
+/** The first protocol in which a process can declare a view's queries. */
+export const DECLARED_QUERY_PROTOCOL = [1, 13];
+function olderThan(protocolVersion, [wantMajor, wantMinor]) {
+    const [major, minor] = protocolVersion.split(".").map((part) => Number.parseInt(part, 10));
+    if (!Number.isFinite(major) || !Number.isFinite(minor))
+        return false;
+    return major < wantMajor || (major === wantMajor && minor < wantMinor);
+}
+/** Whether a sidecar speaking `protocolVersion` would ignore a start position and a version. */
+export function olderThanStartPositions(protocolVersion) {
+    return olderThan(protocolVersion, START_POSITION_PROTOCOL);
+}
+/** Whether a sidecar speaking `protocolVersion` would ignore a view's declared queries. */
+export function olderThanDeclaredQueries(protocolVersion) {
+    return olderThan(protocolVersion, DECLARED_QUERY_PROTOCOL);
+}
+/** Whether a sidecar speaking `protocolVersion` would ignore a topic's contract, broker and parallel reading. */
+export function olderThanContracts(protocolVersion) {
+    return olderThan(protocolVersion, [1, 14]);
+}

package/dist/testkit/index.d.ts

@@ -1,3 +1,3 @@
-export { EventSourcedTestKit, EndpointTestKit, Response, type RequestOptions, type Materialised } from "./unit.ts";
-export { KeyValueTestKit, WorkflowTestKit, ViewTestKit, ConsumerTestKit, TimedActionTestKit, AgentTestKit, ScriptedModel, type WorkflowProgress, type ModelResponse, type ModelCall, } from "./kinds.ts";
+export { EventSourcedTestKit, EndpointTestKit, Response, type RequestOptions, type Materialised, type SocketRun } from "./unit.ts";
+export { KeyValueTestKit, WorkflowTestKit, ViewTestKit, KeyedViewTestKit, ConsumerTestKit, GraphConsumerTestKit, TimedActionTestKit, AgentTestKit, ScriptedModel, type WorkflowProgress, type ModelResponse, type ModelCall, type GraphChange, } from "./kinds.ts";
 export { AnkkaTestKit, PUBLISHED_SIDECAR, sidecarImage, type AnkkaTestKitOptions, type HttpResponse, type Http, type Beside } from "./integration.ts";

package/dist/testkit/index.js

@@ -2,5 +2,5 @@
 // (Postgres and the real sidecar image in Docker). The integration testkit's Docker dependencies,
 // `testcontainers` and `@testcontainers/postgresql`, are loaded only when `AnkkaTestKit.start` runs.
 export { EventSourcedTestKit, EndpointTestKit, Response } from "./unit.js";
-export { KeyValueTestKit, WorkflowTestKit, ViewTestKit, ConsumerTestKit, TimedActionTestKit, AgentTestKit, ScriptedModel, } from "./kinds.js";
+export { KeyValueTestKit, WorkflowTestKit, ViewTestKit, KeyedViewTestKit, ConsumerTestKit, GraphConsumerTestKit, TimedActionTestKit, AgentTestKit, ScriptedModel, } from "./kinds.js";
 export { AnkkaTestKit, PUBLISHED_SIDECAR, sidecarImage } from "./integration.js";

package/dist/testkit/integration.js

@@ -12,6 +12,7 @@
 // pulls it on first use — and an unreleased one (version `0.0.0`, a checkout of the ankka repository) uses
 // `ankka-sidecar:latest`, the image `sbt sidecar/Docker/publishLocal` builds.
 import { execFileSync } from "node:child_process";
+import { randomBytes } from "node:crypto";
 import { chmodSync, mkdtempSync, readdirSync, rmSync, statSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
@@ -220,6 +221,9 @@ export class AnkkaTestKit {
             ANKKA_DB_NAME: "ankka",
             ANKKA_DB_USER: "ankka",
             ANKKA_DB_PASSWORD: "ankka",
+            // A fresh secret key per kit, so the secret store works with no setup; the caller's `env`
+            // replaces it, and `ANKKA_SECRET_KEY: ""` starts a service with none.
+            ANKKA_SECRET_KEY: randomBytes(32).toString("base64"),
             ...this.#env,
         })
             .withExposedPorts(HTTP_PORT, CALLBACK_PORT)
@@ -254,6 +258,7 @@ export class AnkkaTestKit {
             ANKKA_DB_NAME: "ankka",
             ANKKA_DB_USER: "ankka",
             ANKKA_DB_PASSWORD: "ankka",
+            ANKKA_SECRET_KEY: randomBytes(32).toString("base64"),
             ...env,
         })
             .withExposedPorts(httpPort)

package/dist/testkit/kinds.d.ts

@@ -5,11 +5,16 @@ import type { ConsumerEffect, TimedActionEffect, ViewEffect } from "../effects/s
 import type { KeyValueEntity, KeyValueEntityClass } from "../keyValueEntity.ts";
 import type { Workflow, WorkflowClass } from "../workflow.ts";
 import type { View, ViewClass } from "../view.ts";
-import type { Consumer, ConsumerClass } from "../consumer.ts";
+import type { KeyedView, KeyedViewClass } from "../keyedView.ts";
+import { type KeyedViewEffect } from "../effects/keyed.ts";
+import type { ComponentRef } from "../client.ts";
+import { type Consumer, type ConsumerClass } from "../consumer.ts";
+import { type Delta, type GraphConsumerClass } from "../graph.ts";
 import type { TimedAction, TimedActionClass } from "../timedAction.ts";
 import type { Agent, AgentClass } from "../agent.ts";
 import type { HandlerRef } from "../handlers.ts";
 import { type MaterialisedKeyValue, type MaterialisedStep, type MaterialisedWorkflowCommand } from "../materialise.ts";
+import { type AgentOutcome, type DecisionInput } from "../approvals.ts";
 /** Drives one key value entity instance through its handlers. */
 export declare class KeyValueTestKit<S, C extends KeyValueEntity<S>> {
     #private;
@@ -59,20 +64,70 @@ export declare class ViewTestKit<E, Row, C extends View<E, Row>> {
     onDelete(key: string, metadata?: Metadata): Promise<ViewEffect<Row>>;
     get(key: string): Row | null;
 }
+/**
+ * Drives one keyed view with no sidecar: a change of one of its sources goes to that source's handler,
+ * and the rows it names are written to `rows`, a later change to a key winning, as the runtime writes
+ * them. Rows round-trip through the view's row codec and events through the source's.
+ *
+ * A declared query is SQL and there is no database to run it, so the test says what each query
+ * answers. A handler that asks a query the test has not answered throws, naming it: a kit that answered
+ * no rows would pass a handler that updated nothing.
+ */
+export declare class KeyedViewTestKit<Row, C extends KeyedView<Row>> {
+    #private;
+    readonly rows: Map<string, Row>;
+    private constructor();
+    static of<Row, C extends KeyedView<Row>>(cls: KeyedViewClass<Row, C>, client?: ComponentClient): KeyedViewTestKit<Row, C>;
+    /** What the declared query `name` answers, given the values it is asked with. */
+    answering(name: string, answer: (values: Readonly<Record<string, string>>) => Row[]): this;
+    /** A change of the entity `key` of `entity`, round-tripped through that source's codec. */
+    change<E>(entity: ComponentRef, key: string, event: E): Promise<KeyedViewEffect<Row>>;
+    /** The entity `key` of `entity` was deleted. */
+    deleted(entity: ComponentRef, key: string): Promise<KeyedViewEffect<Row>>;
+    get(key: string): Row | null;
+}
 /** Feeds a consumer messages and collects what it produced. */
 export declare class ConsumerTestKit<M, Out, C extends Consumer<M, Out>> {
     #private;
-    /** Everything `produce` sent, round-tripped through the out codec. */
+    /**
+     * Everything the consumer produced, one entry per message, round-tripped through the out codec.
+     * `key` is the record key a message of `produceAll` named; absent, the message is keyed by its subject.
+     */
     readonly produced: {
         readonly payload: Out;
         readonly metadata: Metadata;
+        readonly key?: string;
     }[];
     private constructor();
     static of<M, Out, C extends Consumer<M, Out>>(cls: ConsumerClass<M, Out, C>, client?: ComponentClient): ConsumerTestKit<M, Out, C>;
-    /** A message from source instance `subject`. */
+    /**
+     * A message from source instance `subject`. The metadata says the runtime speaks this SDK's protocol
+     * version; pass `"ankka.protocol"` or `"ankka.sequence"` to say otherwise.
+     */
     onMessage(message: M, subject?: string, metadata?: Metadata): Promise<ConsumerEffect<Out>>;
     onDelete(subject?: string, metadata?: Metadata): Promise<ConsumerEffect<Out>>;
 }
+/**
+ * Feeds a graph consumer changes and answers with the elements it published: each read back from the
+ * bytes that would be published, under the key it would be published under, so a test asserts on what
+ * a reader of the topic sees.
+ */
+export declare class GraphConsumerTestKit<M> {
+    #private;
+    private constructor();
+    static of<M>(cls: GraphConsumerClass<M>, client?: ComponentClient): GraphConsumerTestKit<M>;
+    /** A change from source instance `subject` (default `"test"`) at `sequence` (default 1). */
+    onMessage(message: M, options?: GraphChange): Promise<Delta[]>;
+    /** The source instance was deleted, at `sequence`. */
+    onDelete(options?: GraphChange): Promise<Delta[]>;
+}
+/** The change a graph consumer is handed: whose it is and where in that instance's history. */
+export interface GraphChange {
+    readonly subject?: string;
+    /** The change's sequence number; `0` is a source with none, as a topic is. */
+    readonly sequence?: number | bigint;
+    readonly metadata?: Metadata;
+}
 /** Invokes a timed action's handlers as the sweeper would. */
 export declare class TimedActionTestKit<C extends TimedAction> {
     #private;
@@ -112,9 +167,15 @@ export declare class ScriptedModel {
     /** @internal */
     _next(call: ModelCall): ModelResponse;
 }
+/** Scripted MCP servers: `{ server: { tool: (args) => text } }`, called by the model as `mcp__<server>__<tool>`. */
+export type ScriptedMcp = Readonly<Record<string, Readonly<Record<string, (args: Record<string, unknown>) => string | Promise<string>>>>>;
 /**
  * Runs an agent's turn the way the sidecar does, in process: the plan, input guardrails, the model
  * (scripted), tool calls back into the agent, output guardrails, and the session's history.
+ *
+ * `mcp` scripts the agent's MCP servers, and its result guardrails check what they answer. A call to a
+ * tool that requires approval — the agent's own, or any of a server listed with `approval` — is not run:
+ * `outcome` answers with its request, `ask` rejects with `ApprovalAwaited`, and `decide` goes on.
  */
 export declare class AgentTestKit<C extends Agent> {
     #private;
@@ -125,9 +186,18 @@ export declare class AgentTestKit<C extends Agent> {
         text: string;
     }[];
     private constructor();
-    static of<C extends Agent>(cls: AgentClass<C>, sessionId: string, model: ScriptedModel, client?: ComponentClient): AgentTestKit<C>;
-    /** One turn: returns the reply text (JSON text for a `thenReplyJson` plan). A refusal or a blocked guardrail rejects with `CommandError`. */
+    static of<C extends Agent>(cls: AgentClass<C>, sessionId: string, model: ScriptedModel, client?: ComponentClient, options?: {
+        readonly mcp?: ScriptedMcp;
+    }): AgentTestKit<C>;
+    /** One turn: returns the reply text (JSON text for a `thenReplyJson` plan). A refusal or a blocked guardrail rejects with `CommandError`; a turn that waits, with `ApprovalAwaited`. */
     ask<I>(handler: HandlerRef<C, I, any, any> | string, input?: I): Promise<string>;
+    /** One turn, answered with its outcome: the reply text, or the approval requests the turn waits on. */
+    outcome<I>(handler: HandlerRef<C, I, any, any> | string, input?: I): Promise<AgentOutcome<string>>;
+    /**
+     * Decides the request the turn waits on, and goes on as the sidecar would: approved, the tool runs and the
+     * model is told its result; refused, the model is told who refused it and why.
+     */
+    decide(approvalId: string, decision: DecisionInput): Promise<AgentOutcome<string>>;
     /** A streaming handler's turn, token by token: the reply split on spaces, as a model streams words. */
     stream<I>(handler: HandlerRef<C, I, any, any> | string, input?: I): AsyncIterable<string>;
 }

package/dist/testkit/kinds.js

@@ -5,9 +5,15 @@ import { ComponentClient, noClient } from "../client.js";
 import { binaryCodecs, codecFor } from "../codec.js";
 import { commandContext } from "../context.js";
 import { CommandError, ErrorCode } from "../effects/common.js";
+import { reduceRowChanges } from "../effects/keyed.js";
+import { PROTOCOL_KEY, requireSeveralMessages } from "../consumer.js";
+import { deltaRecords, readDelta } from "../graph.js";
+import { PROTOCOL_VERSION } from "../spec.js";
 import { materialiseKeyValue, materialiseStep, materialiseWorkflowCommand } from "../materialise.js";
 import { Ankka } from "../service.js";
 import { checkPlan, runTool } from "../server/agent.js";
+import { ApprovalAwaited } from "../approvals.js";
+import { TOOL_PREFIX, toolName } from "../mcp.js";
 function roundTrip(codec, value) {
     return codec.decode(codec.encode(value));
 }
@@ -224,12 +230,95 @@ export class ViewTestKit {
         return this.rows.get(key) ?? null;
     }
 }
+/**
+ * Drives one keyed view with no sidecar: a change of one of its sources goes to that source's handler,
+ * and the rows it names are written to `rows`, a later change to a key winning, as the runtime writes
+ * them. Rows round-trip through the view's row codec and events through the source's.
+ *
+ * A declared query is SQL and there is no database to run it, so the test says what each query
+ * answers. A handler that asks a query the test has not answered throws, naming it: a kit that answered
+ * no rows would pass a handler that updated nothing.
+ */
+export class KeyedViewTestKit {
+    #registered;
+    #cls;
+    #client;
+    #answers = new Map();
+    #sequence = 0;
+    rows = new Map();
+    constructor(cls, client) {
+        this.#registered = registryFor(cls, client).component(cls.componentId);
+        this.#cls = cls;
+        this.#client = client;
+    }
+    static of(cls, client = noClient()) {
+        return new KeyedViewTestKit(cls, client);
+    }
+    /** What the declared query `name` answers, given the values it is asked with. */
+    answering(name, answer) {
+        this.#answers.set(name, answer);
+        return this;
+    }
+    #source(entity) {
+        const source = this.#registered.sources.get(entity.componentId);
+        if (!source)
+            throw new Error(`${this.#registered.id} reads no ${JSON.stringify(entity.componentId)}`);
+        return source;
+    }
+    async #apply(key, run) {
+        const view = new this.#cls();
+        const rowCodec = this.#registered.rowCodec;
+        const id = this.#registered.id;
+        const rows = {
+            get: async (k) => {
+                const row = this.rows.get(k);
+                return row === undefined ? null : roundTrip(rowCodec, row);
+            },
+            ask: async (name, values = {}) => {
+                const answer = this.#answers.get(name);
+                if (!answer)
+                    throw new Error(`${id} asked the query ${JSON.stringify(name)}, and the test has not said what it answers; say so with answering(${JSON.stringify(name)}, ...)`);
+                return answer(values).map((r) => roundTrip(rowCodec, r));
+            },
+        };
+        this.#sequence += 1;
+        const metadata = { "ce-subject": key, "ankka.sequence": String(this.#sequence) };
+        view._bind(metadata, this.#client.withMetadata(metadata), rows);
+        const effect = ((await run(view)) ?? { kind: "rows", changes: [] });
+        if (effect.kind !== "rows")
+            throw new TypeError(`${id}'s handler returned something that is not a keyed view effect`);
+        for (const [k, row] of reduceRowChanges(effect.changes)) {
+            if (row === undefined)
+                this.rows.delete(k);
+            else
+                this.rows.set(k, roundTrip(rowCodec, row));
+        }
+        return effect;
+    }
+    /** A change of the entity `key` of `entity`, round-tripped through that source's codec. */
+    change(entity, key, event) {
+        const source = this.#source(entity);
+        const wire = roundTrip(source.eventCodec, event);
+        return this.#apply(key, (v) => source.onChange(v, wire));
+    }
+    /** The entity `key` of `entity` was deleted. */
+    deleted(entity, key) {
+        const source = this.#source(entity);
+        return this.#apply(key, (v) => (source.deleted ? source.deleted(v) : undefined));
+    }
+    get(key) {
+        return this.rows.get(key) ?? null;
+    }
+}
 /** Feeds a consumer messages and collects what it produced. */
 export class ConsumerTestKit {
     #registered;
     #cls;
     #client;
-    /** Everything `produce` sent, round-tripped through the out codec. */
+    /**
+     * Everything the consumer produced, one entry per message, round-tripped through the out codec.
+     * `key` is the record key a message of `produceAll` named; absent, the message is keyed by its subject.
+     */
     produced = [];
     constructor(cls, client) {
         this.#registered = registryFor(cls, client).component(cls.componentId);
@@ -243,21 +332,75 @@ export class ConsumerTestKit {
         const consumer = new this.#cls();
         consumer._bind(metadata, this.#client.withMetadata(metadata));
         const effect = await fn(consumer);
-        if (effect.kind === "produce") {
-            const outCodec = this.#registered.outCodec;
-            if (!outCodec)
+        const outCodec = () => {
+            const codec = this.#registered.outCodec;
+            if (!codec)
                 throw new Error(`${this.#registered.id} produced a message but declares no out shape`);
-            this.produced.push({ payload: roundTrip(outCodec, effect.payload), metadata: effect.metadata });
+            return codec;
+        };
+        if (effect.kind === "produce") {
+            this.produced.push({ payload: roundTrip(outCodec(), effect.payload), metadata: effect.metadata });
+        }
+        else if (effect.kind === "produceAll" && effect.messages.length > 0) {
+            // The server's rule: several messages go only to a runtime that said it accepts them.
+            requireSeveralMessages(metadata);
+            for (const m of effect.messages) {
+                this.produced.push({ payload: roundTrip(outCodec(), m.payload), metadata: m.metadata ?? {}, ...(m.key !== undefined ? { key: m.key } : {}) });
+            }
         }
         return effect;
     }
-    /** A message from source instance `subject`. */
+    /**
+     * A message from source instance `subject`. The metadata says the runtime speaks this SDK's protocol
+     * version; pass `"ankka.protocol"` or `"ankka.sequence"` to say otherwise.
+     */
     onMessage(message, subject = "test", metadata = {}) {
         const wire = roundTrip(this.#registered.messageCodec, message);
-        return this.#apply((c) => c.onMessage(wire), { "ce-subject": subject, ...metadata });
+        return this.#apply((c) => c.onMessage(wire), { "ce-subject": subject, [PROTOCOL_KEY]: PROTOCOL_VERSION, ...metadata });
     }
     onDelete(subject = "test", metadata = {}) {
-        return this.#apply((c) => c.onDelete(), { "ce-subject": subject, ...metadata });
+        return this.#apply((c) => c.onDelete(), { "ce-subject": subject, [PROTOCOL_KEY]: PROTOCOL_VERSION, ...metadata });
+    }
+}
+/**
+ * Feeds a graph consumer changes and answers with the elements it published: each read back from the
+ * bytes that would be published, under the key it would be published under, so a test asserts on what
+ * a reader of the topic sees.
+ */
+export class GraphConsumerTestKit {
+    #registered;
+    #cls;
+    #client;
+    constructor(cls, client) {
+        this.#registered = registryFor(cls, client).component(cls.componentId);
+        this.#cls = cls;
+        this.#client = client;
+    }
+    static of(cls, client = noClient()) {
+        return new GraphConsumerTestKit(cls, client);
+    }
+    async #apply(fn, options) {
+        const metadata = {
+            "ce-subject": options.subject ?? "test",
+            "ankka.sequence": String(options.sequence ?? 1),
+            [PROTOCOL_KEY]: PROTOCOL_VERSION,
+            ...options.metadata,
+        };
+        const consumer = new this.#cls();
+        consumer._bind(metadata, this.#client.withMetadata(metadata));
+        const records = deltaRecords(await fn(consumer), metadata);
+        if (records.length > 0)
+            requireSeveralMessages(metadata);
+        return records.map((r) => readDelta(r.value, r.key));
+    }
+    /** A change from source instance `subject` (default `"test"`) at `sequence` (default 1). */
+    onMessage(message, options = {}) {
+        const wire = roundTrip(this.#registered.messageCodec, message);
+        return this.#apply((c) => c.onMessage(wire), options);
+    }
+    /** The source instance was deleted, at `sequence`. */
+    onDelete(options = {}) {
+        return this.#apply((c) => c.onDelete(), options);
     }
 }
 /** Invokes a timed action's handlers as the sweeper would. */
@@ -312,32 +455,50 @@ export class ScriptedModel {
 /**
  * Runs an agent's turn the way the sidecar does, in process: the plan, input guardrails, the model
  * (scripted), tool calls back into the agent, output guardrails, and the session's history.
+ *
+ * `mcp` scripts the agent's MCP servers, and its result guardrails check what they answer. A call to a
+ * tool that requires approval — the agent's own, or any of a server listed with `approval` — is not run:
+ * `outcome` answers with its request, `ask` rejects with `ApprovalAwaited`, and `decide` goes on.
  */
 export class AgentTestKit {
     #registered;
     #cls;
     #client;
     #model;
+    #mcp;
     sessionId;
     /** The session's memory: what the user said and the agent answered, turn after turn. */
     history = [];
-    constructor(cls, sessionId, model, client) {
+    #turn;
+    #decided = new Set();
+    #nextId = 0;
+    constructor(cls, sessionId, model, client, mcp) {
         this.#registered = registryFor(cls, client).component(cls.componentId);
         this.#cls = cls;
         this.#client = client;
         this.#model = model;
+        this.#mcp = mcp;
         this.sessionId = sessionId;
     }
-    static of(cls, sessionId, model, client = noClient()) {
-        return new AgentTestKit(cls, sessionId, model, client);
+    static of(cls, sessionId, model, client = noClient(), options = {}) {
+        return new AgentTestKit(cls, sessionId, model, client, options.mcp ?? {});
     }
     #agent() {
         const a = new this.#cls();
         a._bind(this.sessionId, {}, this.#client);
         return a;
     }
-    /** One turn: returns the reply text (JSON text for a `thenReplyJson` plan). A refusal or a blocked guardrail rejects with `CommandError`. */
+    /** One turn: returns the reply text (JSON text for a `thenReplyJson` plan). A refusal or a blocked guardrail rejects with `CommandError`; a turn that waits, with `ApprovalAwaited`. */
     async ask(handler, input) {
+        const outcome = await this.outcome(handler, input);
+        if (outcome.kind === "awaiting-approval")
+            throw new ApprovalAwaited(outcome.requests);
+        return outcome.value;
+    }
+    /** One turn, answered with its outcome: the reply text, or the approval requests the turn waits on. */
+    async outcome(handler, input) {
+        if (this.#turn?.pending)
+            throw new CommandError({ message: `session '${this.sessionId}' has a turn awaiting a decision`, code: ErrorCode.Conflict });
         const ref = findHandler(this.#registered.handlers, handler, this.#registered.cls.name);
         const wireInput = ref.input ? roundTrip(codecFor(ref.input), input) : undefined;
         const agent = this.#agent();
@@ -349,43 +510,112 @@ export class AgentTestKit {
             throw new Error(problem);
         if (plan.failure)
             throw new CommandError(plan.failure);
-        const guard = async (stage, text) => {
-            for (const name of plan.guardrailNames) {
-                const reason = await this.#registered.guardrails.get(name).check(stage, text);
-                if (reason)
-                    throw new CommandError({ message: `${name}: ${reason}`, code: ErrorCode.Forbidden });
-            }
-        };
         const user = [...plan.context, plan.user ?? ""].filter((t) => t !== "").join("\n\n");
-        await guard("input", user);
+        await this.#guard(plan, "input", user);
         const messages = plan.sessionMemory ? this.history.map((h) => ({ ...h })) : [];
         messages.push({ role: "user", text: user });
-        for (let step = 0; step <= this.#registered.maxToolCallSteps; step++) {
-            const answer = this.#model._next({ system: plan.system, messages: [...messages], tools: [...plan.toolNames] });
+        this.#turn = { plan, messages, steps: 0 };
+        return this.#goOn(this.#turn);
+    }
+    /**
+     * Decides the request the turn waits on, and goes on as the sidecar would: approved, the tool runs and the
+     * model is told its result; refused, the model is told who refused it and why.
+     */
+    async decide(approvalId, decision) {
+        if (decision.by.trim() === "")
+            throw new CommandError({ message: "a decision must name who made it", code: ErrorCode.BadRequest });
+        if (this.#decided.has(approvalId))
+            throw new CommandError({ message: `approval request '${approvalId}' is decided`, code: ErrorCode.Conflict });
+        const turn = this.#turn;
+        if (!turn?.pending || turn.pending.request.id !== approvalId) {
+            throw new CommandError({ message: `no approval request '${approvalId}' in session '${this.sessionId}'`, code: ErrorCode.NotFound });
+        }
+        const { tool, argumentsJson } = turn.pending;
+        turn.pending = undefined;
+        this.#decided.add(approvalId);
+        const result = decision.approved
+            ? await this.#run(tool, argumentsJson)
+            : `A person (${decision.by}) refused this tool call; the tool did not run.${decision.note ? ` Their note: ${decision.note}` : ""}`;
+        turn.messages.push({ role: "tool", text: result });
+        return this.#goOn(turn);
+    }
+    async #guard(plan, stage, text) {
+        for (const name of plan.guardrailNames) {
+            const reason = await this.#registered.guardrails.get(name).check(stage, text);
+            if (reason)
+                throw new CommandError({ message: `${name}: ${reason}`, code: ErrorCode.Forbidden });
+        }
+    }
+    #mcpTool(name) {
+        if (!name.startsWith(TOOL_PREFIX))
+            return undefined;
+        const rest = name.slice(TOOL_PREFIX.length);
+        const at = rest.indexOf("__");
+        return at < 0 ? undefined : { server: rest.slice(0, at), tool: rest.slice(at + 2) };
+    }
+    #offered(plan) {
+        const mcp = [...this.#registered.mcpServers.keys()].flatMap((server) => Object.keys(this.#mcp[server] ?? {}).map((tool) => toolName(server, tool)));
+        return [...plan.toolNames, ...mcp];
+    }
+    #requiresApproval(name) {
+        const mcp = this.#mcpTool(name);
+        if (mcp)
+            return this.#registered.mcpServers.get(mcp.server)?.approval !== undefined;
+        return this.#registered.tools.get(name)?.approval !== undefined;
+    }
+    async #run(name, argumentsJson) {
+        const mcp = this.#mcpTool(name);
+        try {
+            if (!mcp)
+                return await runTool(this.#registered, this.#agent(), name, argumentsJson);
+            const text = await this.#mcp[mcp.server][mcp.tool](JSON.parse(argumentsJson || "{}"));
+            for (const g of [...this.#registered.resultGuardrails.values()].sort((a, b) => a.name.localeCompare(b.name))) {
+                const reason = await g.check(name, text);
+                if (reason)
+                    return `A result guardrail refused what this tool answered, so it is not shown: ${g.name}: ${reason}`;
+            }
+            return text;
+        }
+        catch (e) {
+            return `error: ${e instanceof Error ? e.message : String(e)}`;
+        }
+    }
+    async #goOn(turn) {
+        const offered = this.#offered(turn.plan);
+        while (turn.steps <= this.#registered.maxToolCallSteps) {
+            const answer = this.#model._next({ system: turn.plan.system, messages: [...turn.messages], tools: offered });
             switch (answer.kind) {
                 case "refusal":
+                    this.#turn = undefined;
                     throw new CommandError({ message: answer.message, code: ErrorCode.BadRequest });
                 case "tool-call": {
-                    if (!plan.toolNames.includes(answer.tool))
+                    turn.steps++;
+                    if (!offered.includes(answer.tool))
                         throw new Error(`the model called ${JSON.stringify(answer.tool)}, which the plan did not offer`);
-                    let result;
-                    try {
-                        result = await runTool(this.#registered, this.#agent(), answer.tool, answer.argumentsJson);
-                    }
-                    catch (e) {
-                        result = `error: ${e instanceof Error ? e.message : String(e)}`;
+                    turn.messages.push({ role: "assistant", text: `[tool call ${answer.tool} ${answer.argumentsJson}]` });
+                    if (this.#requiresApproval(answer.tool)) {
+                        const request = Object.freeze({
+                            id: `approval-${++this.#nextId}`,
+                            tool: answer.tool,
+                            arguments: JSON.parse(answer.argumentsJson || "{}"),
+                            requestedAt: Date.now(),
+                        });
+                        turn.pending = { request, tool: answer.tool, argumentsJson: answer.argumentsJson };
+                        return { kind: "awaiting-approval", requests: [request] };
                     }
-                    messages.push({ role: "assistant", text: `[tool call ${answer.tool} ${answer.argumentsJson}]` }, { role: "tool", text: result });
+                    turn.messages.push({ role: "tool", text: await this.#run(answer.tool, answer.argumentsJson) });
                     break;
                 }
                 case "text": {
-                    await guard("output", answer.text);
-                    if (plan.sessionMemory)
-                        this.history.push({ role: "user", text: plan.user ?? "" }, { role: "assistant", text: answer.text });
-                    return answer.text;
+                    this.#turn = undefined;
+                    await this.#guard(turn.plan, "output", answer.text);
+                    if (turn.plan.sessionMemory)
+                        this.history.push({ role: "user", text: turn.plan.user ?? "" }, { role: "assistant", text: answer.text });
+                    return { kind: "answered", value: answer.text };
                 }
             }
         }
+        this.#turn = undefined;
         throw new CommandError({ message: `the agent made more than ${this.#registered.maxToolCallSteps} tool calls`, code: ErrorCode.Internal });
     }
     /** A streaming handler's turn, token by token: the reply split on spaces, as a model streams words. */

package/dist/testkit/unit.d.ts

@@ -34,15 +34,28 @@ export declare class Response {
 export interface RequestOptions {
     readonly query?: Readonly<Record<string, string | readonly string[]>>;
     readonly headers?: Readonly<Record<string, string>>;
-    readonly principal?: Principal;
+    /** The verified caller, as the runtime would hand it over; `claims` and `issuer` may be left out. */
+    readonly principal?: Omit<Principal, "claims" | "issuer"> & Partial<Pick<Principal, "claims" | "issuer">>;
     readonly metadata?: Metadata;
 }
+/** What a socket route's handler did with a scripted socket. */
+export interface SocketRun {
+    readonly sent: readonly string[];
+    readonly ended: "finished" | "failed";
+    readonly error?: string;
+}
 /** Calls an endpoint's routes by path, matching them as the sidecar's router does: literal segments outrank parameters. */
 export declare class EndpointTestKit<C extends Endpoint> {
     #private;
     private constructor();
     static of<C extends Endpoint>(cls: EndpointClass<C>, client?: ComponentClient): EndpointTestKit<C>;
     request(method: string, path: string, body?: unknown, options?: RequestOptions): Promise<Response>;
+    /**
+     * Opens a socket route with no runtime: the handler is given `frames` one at a time and then told the
+     * socket is closed, as when the client closes it after sending them. Answers what the handler sent, in
+     * order, and how it ended: `finished` when it returned, `failed` (with `error`) when it threw.
+     */
+    socket(path: string, frames?: readonly string[], options?: RequestOptions): Promise<SocketRun>;
     /** The frames of an SSE route, each string one frame. */
     sse(path: string, options?: RequestOptions): Promise<string[]>;
     get(path: string, options?: RequestOptions): Promise<Response>;