ankka 0.10.0 → 0.12.0

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,12 +5,17 @@ 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 { 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";
+import type { Standing } from "../standing.ts";
 /** Drives one key value entity instance through its handlers. */
 export declare class KeyValueTestKit<S, C extends KeyValueEntity<S>> {
     #private;
@@ -54,12 +59,37 @@ export declare class ViewTestKit<E, Row, C extends View<E, Row>> {
     readonly rows: Map<string, Row>;
     private constructor();
     static of<E, Row, C extends View<E, Row>>(cls: ViewClass<E, Row, C>, client?: ComponentClient): ViewTestKit<E, Row, C>;
-    /** A change from source instance `key`: the event, round-tripped through the source's event codec. */
-    onChange(key: string, event: E, metadata?: Metadata): Promise<ViewEffect<Row>>;
+    /**
+     * A change from source instance `key`: the event, round-tripped through the source's event codec.
+     * `standing` is a workflow's, for a view whose source is one.
+     */
+    onChange(key: string, event: E, metadata?: Metadata, standing?: Standing): Promise<ViewEffect<Row>>;
     /** The source instance `key` was deleted. */
     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 `key` of `entity`, round-tripped through that source's codec; `standing` a workflow's. */
+    change<E>(entity: ComponentRef, key: string, event: E, standing?: Standing): 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;
@@ -78,7 +108,7 @@ export declare class ConsumerTestKit<M, Out, C extends Consumer<M, Out>> {
      * 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>>;
+    onMessage(message: M, subject?: string, metadata?: Metadata, standing?: Standing): Promise<ConsumerEffect<Out>>;
     onDelete(subject?: string, metadata?: Metadata): Promise<ConsumerEffect<Out>>;
 }
 /**
@@ -141,9 +171,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;
@@ -154,9 +190,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,12 +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));
 }
@@ -196,11 +199,11 @@ export class ViewTestKit {
     static of(cls, client = noClient()) {
         return new ViewTestKit(cls, client);
     }
-    async #apply(key, fn, metadata) {
+    async #apply(key, fn, metadata, standing) {
         const view = new this.#cls();
         const rowCodec = this.#registered.rowCodec;
         const current = this.rows.get(key);
-        view._bind(current === undefined ? null : roundTrip(rowCodec, current), { "ce-subject": key, ...metadata }, this.#client.withMetadata(metadata));
+        view._bind(current === undefined ? null : roundTrip(rowCodec, current), { "ce-subject": key, ...metadata }, this.#client.withMetadata(metadata), standing);
         const effect = await fn(view);
         switch (effect.kind) {
             case "update-row":
@@ -214,10 +217,13 @@ export class ViewTestKit {
         }
         return effect;
     }
-    /** A change from source instance `key`: the event, round-tripped through the source's event codec. */
-    onChange(key, event, metadata = {}) {
+    /**
+     * A change from source instance `key`: the event, round-tripped through the source's event codec.
+     * `standing` is a workflow's, for a view whose source is one.
+     */
+    onChange(key, event, metadata = {}, standing) {
         const wire = roundTrip(this.#registered.eventCodec, event);
-        return this.#apply(key, (v) => v.onChange(wire), metadata);
+        return this.#apply(key, (v) => v.onChange(wire), metadata, standing);
     }
     /** The source instance `key` was deleted. */
     onDelete(key, metadata = {}) {
@@ -227,6 +233,86 @@ 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, standing) {
+        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, standing);
+        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 `key` of `entity`, round-tripped through that source's codec; `standing` a workflow's. */
+    change(entity, key, event, standing) {
+        const source = this.#source(entity);
+        const wire = roundTrip(source.eventCodec, event);
+        return this.#apply(key, (v) => source.onChange(v, wire), standing);
+    }
+    /** 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;
@@ -245,9 +331,9 @@ export class ConsumerTestKit {
     static of(cls, client = noClient()) {
         return new ConsumerTestKit(cls, client);
     }
-    async #apply(fn, metadata) {
+    async #apply(fn, metadata, standing) {
         const consumer = new this.#cls();
-        consumer._bind(metadata, this.#client.withMetadata(metadata));
+        consumer._bind(metadata, this.#client.withMetadata(metadata), standing);
         const effect = await fn(consumer);
         const outCodec = () => {
             const codec = this.#registered.outCodec;
@@ -271,9 +357,9 @@ export class ConsumerTestKit {
      * 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 = {}) {
+    onMessage(message, subject = "test", metadata = {}, standing) {
         const wire = roundTrip(this.#registered.messageCodec, message);
-        return this.#apply((c) => c.onMessage(wire), { "ce-subject": subject, [PROTOCOL_KEY]: PROTOCOL_VERSION, ...metadata });
+        return this.#apply((c) => c.onMessage(wire), { "ce-subject": subject, [PROTOCOL_KEY]: PROTOCOL_VERSION, ...metadata }, standing);
     }
     onDelete(subject = "test", metadata = {}) {
         return this.#apply((c) => c.onDelete(), { "ce-subject": subject, [PROTOCOL_KEY]: PROTOCOL_VERSION, ...metadata });
@@ -372,32 +458,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();
@@ -409,43 +513,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

@@ -1,15 +1,29 @@
 import { ComponentClient } from "../client.ts";
 import { type Principal } from "../context.ts";
-import type { ErrorDetail, Metadata, Retention } from "../effects/common.ts";
+import { type ErrorDetail, type Metadata, type Retention } from "../effects/common.ts";
+import type { ReplicationChange } from "../effects/eventSourced.ts";
 import type { Endpoint, EndpointClass } from "../endpoint.ts";
 import { EventSourcedEntity, type EventSourcedEntityClass } from "../eventSourcedEntity.ts";
 import type { HandlerRef } from "../handlers.ts";
 import { type Materialised } from "../materialise.ts";
 export type { Materialised };
 /** Drives one event sourced entity instance through its handlers, folding events as it goes. */
+/** How a replicated entity's copy stands in the test kit (1.19); `installation` is the copy's own. */
+export type ReplicationMode = {
+    readonly kind: "unreplicated";
+} | {
+    readonly kind: "home";
+    readonly installation?: string;
+} | {
+    readonly kind: "follower";
+    readonly home: string;
+    readonly installation?: string;
+};
 export declare class EventSourcedTestKit<S, E, C extends EventSourcedEntity<S, E>> {
     #private;
     readonly entityId: string;
+    /** The handover or change to the replication set the last call asked for, if any. */
+    lastReplication: ReplicationChange | undefined;
     /** The state now, after every call so far. */
     state: S;
     /** The sequence number of the last event, `0n` before any. */
@@ -18,7 +32,18 @@ export declare class EventSourcedTestKit<S, E, C extends EventSourcedEntity<S, E
     readonly allEvents: E[];
     private constructor();
     /** A kit for `cls` as instance `entityId`. Calls to other components reach `client`, which by default refuses them. */
-    static of<S, E, C extends EventSourcedEntity<S, E>>(cls: EventSourcedEntityClass<S, E, C>, entityId?: string, client?: ComponentClient): EventSourcedTestKit<S, E, C>;
+    static of<S, E, C extends EventSourcedEntity<S, E>>(cls: EventSourcedEntityClass<S, E, C>, entityId?: string, client?: ComponentClient, 
+    /**
+     * How a replicated entity's copy stands (1.19): `{ kind: "home" }`, where every command runs, or
+     * `{ kind: "follower", home }`, where a command that may persist is refused `NOT_HOME` and a query is
+     * answered from what `replay` gave it. Not replicated by default.
+     */
+    mode?: ReplicationMode): EventSourcedTestKit<S, E, C>;
+    /**
+     * Applies `events` as history the copy already holds, written at `writtenAt` (this installation by
+     * default): for a follower, what it has mirrored from its home.
+     */
+    replay(events: readonly E[], writtenAt?: string | null): void;
     /** Sends a command or query and returns what its effect amounts to. */
     call<I, R>(handler: HandlerRef<C, I, R, any> | string, input?: I, metadata?: Metadata): Promise<Materialised<S, E, R>>;
 }
@@ -34,15 +59,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>;