ankka 0.10.0 → 0.11.0

package/dist/testkit/kinds.d.ts

@@ -5,12 +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 { 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;
@@ -60,6 +64,28 @@ 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;
@@ -141,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;
@@ -154,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,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));
 }
@@ -227,6 +230,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) {
+        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;
@@ -372,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();
@@ -409,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>;

package/dist/testkit/unit.js

@@ -4,7 +4,7 @@
 // reduction is the server's (`materialise.ts`), so a test cannot pass on something the sidecar would
 // not do.
 import { create } from "@bufbuild/protobuf";
-import { HttpRequestSchema } from "../_proto/ankka/protocol/v1/endpoint_pb.js";
+import { HttpRequestSchema, SocketInSchema } from "../_proto/ankka/protocol/v1/endpoint_pb.js";
 import { ComponentClient, noClient } from "../client.js";
 import { binaryCodecs, codecFor } from "../codec.js";
 import { commandContext } from "../context.js";
@@ -119,7 +119,8 @@ export class EndpointTestKit {
         const rest = withoutQuery.startsWith(prefix) ? withoutQuery.slice(prefix.length) || "/" : withoutQuery;
         const candidates = [];
         for (const [id, route] of Object.entries(this.#cls.routes)) {
-            if (route.method !== method.toUpperCase())
+            // A socket route is opened through `socket`, never answered as a GET.
+            if ((route.socket ? "SOCKET" : route.method) !== method.toUpperCase())
                 continue;
             const pattern = new RegExp("^" + route.template.replace(/[.*+?^$()|[\]\\]/g, "\\$&").replace(PLACEHOLDER, "([^/]+)") + "$");
             const m = pattern.exec(rest);
@@ -156,7 +157,15 @@ export class EndpointTestKit {
         }
         const headers = Object.entries(options.headers ?? {}).map(([name, value]) => ({ name, value }));
         const principal = options.principal
-            ? { subject: options.principal.subject, name: options.principal.name ?? undefined, email: options.principal.email ?? undefined, emailVerified: options.principal.emailVerified, roles: [...options.principal.roles] }
+            ? {
+                subject: options.principal.subject,
+                name: options.principal.name ?? undefined,
+                email: options.principal.email ?? undefined,
+                emailVerified: options.principal.emailVerified,
+                roles: [...options.principal.roles],
+                claims: { ...(options.principal.claims ?? {}) },
+                issuer: options.principal.issuer ?? undefined,
+            }
             : undefined;
         const req = create(HttpRequestSchema, {
             endpointId: this.#cls.name,
@@ -192,6 +201,34 @@ export class EndpointTestKit {
         }
         return new Response(500, "text/plain", new TextEncoder().encode(reply.message.case === "failure" ? reply.message.value.error?.message ?? "failure" : "no reply"));
     }
+    /**
+     * 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.
+     */
+    async socket(path, frames = [], options = {}) {
+        const prepared = this.#request("SOCKET", path, undefined, options);
+        if (!prepared)
+            throw new Error(`no socket route at ${path}`);
+        const requests = [
+            create(SocketInSchema, { message: { case: "open", value: prepared.req } }),
+            ...frames.map((text) => create(SocketInSchema, { message: { case: "frame", value: { kind: { case: "text", value: text } } } })),
+            create(SocketInSchema, { message: { case: "closed", value: { reason: "client" } } }),
+        ];
+        async function* script() {
+            yield* requests;
+        }
+        const sent = [];
+        for await (const out of this.#dispatcher.handleSocket(script())) {
+            if (out.message.case === "frame" && out.message.value.kind.case === "text")
+                sent.push(out.message.value.kind.value);
+            if (out.message.case === "completed")
+                return { sent, ended: "finished" };
+            if (out.message.case === "failed")
+                return { sent, ended: "failed", error: out.message.value.message };
+        }
+        return { sent, ended: "finished" };
+    }
     /** The frames of an SSE route, each string one frame. */
     async sse(path, options = {}) {
         const prepared = this.#request("GET", path, undefined, options);

package/dist/timedAction.d.ts

@@ -1,13 +1,28 @@
 import type { Metadata } from "./effects/common.ts";
-import type { ComponentClient } from "./client.ts";
+import { type ComponentClient, type Secrets } from "./client.ts";
 import type { HandlerTable } from "./handlers.ts";
 import { TimedActionEffects } from "./effects/stateless.ts";
+import { type Services } from "./services.ts";
 export declare abstract class TimedAction {
     #private;
     readonly effects: TimedActionEffects;
-    /** `ankka.timer` is the timer's id, `ankka.attempts` how many times it has fired. */
+    /** `ankka.timer` is the timer's id, `ankka.attempts` how many times it has fired, `ankka.due` the due time in epoch milliseconds. */
     get metadata(): Metadata;
+    /**
+     * The due time this run is for, from `ankka.due`: the same on every retry of one due time, and for a
+     * recurring timer a whole number of periods after the one before. `undefined` on a runtime older
+     * than protocol 1.12, which does not send it.
+     */
+    get dueTime(): Date | undefined;
     get client(): ComponentClient;
+    /** The service's secret store: values kept encrypted in the service's own database, never in a journal or a view. */
+    get secrets(): Secrets;
+    /** A unit test's store in place of the runtime's: `component.secrets = new InMemorySecrets()`. */
+    set secrets(store: Secrets);
+    /** Other services, called as this one, through the runtime: `this.services.service("orders")`. */
+    get services(): Services;
+    /** A unit test's in place of the runtime's: `component.services = new ScriptedServices()`. */
+    set services(services: Services);
     /** @internal */
     get _kind(): "timed-action";
     /** @internal */

package/dist/timedAction.js

@@ -2,20 +2,52 @@
 // sweeper delivers it here, retrying a failure with backoff.
 //
 //   static readonly actions = { remind: action("remind", s.string, (t: Reminder, id) => t.remind(id)) }
+import { secretsFor } from "./client.js";
 import { TimedActionEffects } from "./effects/stateless.js";
+import { servicesFor } from "./services.js";
 export class TimedAction {
     effects = new TimedActionEffects();
     #metadata = {};
     #client;
-    /** `ankka.timer` is the timer's id, `ankka.attempts` how many times it has fired. */
+    /** `ankka.timer` is the timer's id, `ankka.attempts` how many times it has fired, `ankka.due` the due time in epoch milliseconds. */
     get metadata() {
         return this.#metadata;
     }
+    /**
+     * The due time this run is for, from `ankka.due`: the same on every retry of one due time, and for a
+     * recurring timer a whole number of periods after the one before. `undefined` on a runtime older
+     * than protocol 1.12, which does not send it.
+     */
+    get dueTime() {
+        const raw = this.#metadata["ankka.due"];
+        if (raw === undefined || !/^-?\d+$/.test(raw.trim()))
+            return undefined;
+        const date = new Date(Number(raw.trim()));
+        return Number.isNaN(date.getTime()) ? undefined : date;
+    }
     get client() {
         if (!this.#client)
             throw new Error("client is only available inside an action");
         return this.#client;
     }
+    #secrets;
+    /** The service's secret store: values kept encrypted in the service's own database, never in a journal or a view. */
+    get secrets() {
+        return this.#secrets ?? secretsFor(this.client);
+    }
+    /** A unit test's store in place of the runtime's: `component.secrets = new InMemorySecrets()`. */
+    set secrets(store) {
+        this.#secrets = store;
+    }
+    #services;
+    /** Other services, called as this one, through the runtime: `this.services.service("orders")`. */
+    get services() {
+        return this.#services ?? servicesFor(this.client);
+    }
+    /** A unit test's in place of the runtime's: `component.services = new ScriptedServices()`. */
+    set services(services) {
+        this.#services = services;
+    }
     /** @internal */
     get _kind() {
         return "timed-action";

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.10.0";
+export declare const VERSION = "0.11.0";

package/dist/version.js

@@ -1,2 +1,2 @@
 // Written by scripts/proto.ts from package.json; do not edit. 0.0.0 in the tree, the tag's version in a release.
-export const VERSION = "0.10.0";
+export const VERSION = "0.11.0";

package/dist/view.d.ts

@@ -1,9 +1,26 @@
+import type { StartFrom } from "./startFrom.ts";
+import type { Contract } from "./contract.ts";
 import type { Shape } from "./codec.ts";
 import type { Metadata } from "./effects/common.ts";
 import type { ComponentClient } from "./client.ts";
 import type { ComponentRef } from "./client.ts";
 import { ViewEffects, type ViewEffect } from "./effects/stateless.ts";
 type MaybePromise<T> = T | Promise<T>;
+/**
+ * A question a view can be asked by name: one SQL statement over the view's own table, whose values
+ * are the `:name`s it holds. The platform checks the statement when the service starts — one that is
+ * not a single read of the view's own table stops the service, naming the view and the query — and
+ * binds each value as a parameter, never as part of the text. The answer is rows of the view's row
+ * shape, read from the statement's `payload` column.
+ */
+export interface DeclaredQuery {
+    readonly name: string;
+    readonly statement: string;
+}
+/** Declares a query for a view's `static declared`. The SDK sends the statement as written. */
+export declare function declaredQuery(name: string, statement: string): DeclaredQuery;
+/** The table a view's rows are kept in, for a declared query's statement to name. */
+export declare function tableOf(componentId: string): string;
 export declare abstract class View<E, Row> {
     #private;
     readonly effects: ViewEffects<Row>;
@@ -29,9 +46,24 @@ export interface ViewClass<E = unknown, Row = unknown, C extends View<E, Row> =
     /** The component whose changes feed the view, or `topic`. */
     readonly source?: ComponentRef;
     readonly topic?: string;
+    /** Where a topic source starts the first time its group reads the topic. */
+    readonly startFrom?: StartFrom;
+    /**
+     * Raised to have the view emptied and read again: a topic from its start position, under a group of
+     * its own, as far back as the broker retains; an entity from its first event or state. Absent is 1.
+     */
+    readonly version?: number;
+    /** The contract the topic read is expected to carry, checked at start against the project's declaration. */
+    readonly contract?: Contract;
+    /** The declared broker the topic read is on; absent is the installation's. */
+    readonly broker?: string;
+    /** Whether the partitions an instance holds are handled at once, each in order. */
+    readonly parallel?: boolean;
     readonly events: Shape<E>;
     readonly row: Shape<Row>;
     /** The query names the view answers; `get` and `all` by default. */
     readonly queries?: readonly string[];
+    /** The queries the view can be asked by name, each a statement over its own table (protocol 1.13). */
+    readonly declared?: readonly DeclaredQuery[];
 }
 export {};

package/dist/view.js

@@ -9,6 +9,14 @@
 //     onChange(event) { ... return this.effects.updateRow(...) }
 //   }
 import { ViewEffects } from "./effects/stateless.js";
+/** Declares a query for a view's `static declared`. The SDK sends the statement as written. */
+export function declaredQuery(name, statement) {
+    return Object.freeze({ name, statement });
+}
+/** The table a view's rows are kept in, for a declared query's statement to name. */
+export function tableOf(componentId) {
+    return "ankka_view_" + componentId.replace(/[^A-Za-z0-9]/g, "_");
+}
 export class View {
     effects = new ViewEffects();
     #row = null;