ankka 0.10.0 → 0.12.0

package/dist/client.js

@@ -3,16 +3,19 @@
 // One channel per process, opened on first use so the integration testkit can learn the sidecar's
 // mapped port after construction. A client handed to a handler is scoped to that request's metadata,
 // so the sidecar records the call as a child span.
-import { createClient } from "@connectrpc/connect";
+import { Code, ConnectError, createClient } from "@connectrpc/connect";
 import { createGrpcTransport } from "@connectrpc/connect-node";
-import { Client } from "./_proto/ankka/protocol/v1/client_pb.js";
+import { Client, Overflow as ProtoOverflow } from "./_proto/ankka/protocol/v1/client_pb.js";
 import { codecFor, jsonCodec, isCodec, textCodecs, binaryCodecs, codecForManifest } from "./codec.js";
 import { CommandError } from "./effects/common.js";
 import { decodeJsonValue, reviver } from "./json.js";
 import { errorCodeFromProto, kindToProto } from "./kinds.js";
 import { metadataToProto } from "./context.js";
 import { encodePayload, decodePayload, EMPTY_PAYLOAD } from "./server/payloads.js";
+import { Duration } from "./time.js";
+import { PROTOCOL_VERSION } from "./spec.js";
 import { AutonomousAgentCalls, TaskCalls, Tasks } from "./autonomous.js";
+import { APPROVALS_SINCE, ApprovalAwaited, awaitingOf } from "./approvals.js";
 function stubOf(connection) {
     if (!connection.stub) {
         connection.transport = createGrpcTransport({ baseUrl: `http://${connection.address}` });
@@ -21,7 +24,28 @@ function stubOf(connection) {
     return connection.stub;
 }
 function errorOf(error) {
-    return { message: error.message, code: errorCodeFromProto(error.code) };
+    return { message: error.message, code: errorCodeFromProto(error.code), details: { ...(error.details ?? {}) } };
+}
+/** The first protocol whose runtime can wait for a workflow's end; an older one answers `UNIMPLEMENTED`. */
+export const AWAIT_SINCE = "1.18";
+/** A part as one line of JSON, which is what an `sse` route yields for it. */
+export function awaitPartJson(part) {
+    switch (part.kind) {
+        case "heartbeat":
+            return JSON.stringify({ heartbeat: true });
+        case "ended":
+            return JSON.stringify({ ended: part.state });
+        case "failed":
+            return JSON.stringify({ failed: { code: part.error.code, message: part.error.message, ...part.error.details } });
+        case "timed-out":
+            return JSON.stringify({ timedOut: true });
+    }
+}
+function timeoutOf(timeoutMillis) {
+    if (!(timeoutMillis > 0)) {
+        throw new CommandError({ message: `a wait for a workflow's end needs a timeout of more than zero, not ${timeoutMillis}`, code: "BAD_REQUEST" });
+    }
+    return Math.max(1, Math.floor(timeoutMillis));
 }
 function inputPayload(shape, input) {
     if (shape === undefined) {
@@ -38,6 +62,43 @@ function decodeReply(shape, payload) {
     const codec = payload ? codecForManifest(payload.manifest) : undefined;
     return (codec ?? binaryCodecs.done).decode(payload?.data ?? new Uint8Array());
 }
+function outcomeOf(reply, answer) {
+    switch (answer.result.case) {
+        case "reply":
+            return { kind: "answered", value: decodeReply(reply, answer.result.value.payload) };
+        case "approval":
+            return awaitingOf(answer.result.value);
+        case "error":
+            throw new CommandError(errorOf(answer.result.value));
+        default:
+            throw new CommandError({ message: "the sidecar answered nothing", code: "INTERNAL" });
+    }
+}
+/** Sends a decision; a runtime before approvals is reported as too old. */
+async function decideOn(connection, metadata, kind, componentId, entityId, name, approvalId, decision) {
+    try {
+        return await stubOf(connection).decide({
+            kind: kindToProto(kind),
+            componentId,
+            entityId,
+            name,
+            approvalId,
+            approved: decision.approved,
+            by: decision.by,
+            ...(decision.note ? { note: decision.note } : {}),
+            metadata: metadataToProto(metadata),
+        });
+    }
+    catch (failure) {
+        if (failure instanceof ConnectError && failure.code === Code.Unimplemented) {
+            throw new CommandError({
+                message: `the runtime beside this process cannot record a decision on an approval request, which needs protocol ${APPROVALS_SINCE}: ${failure.rawMessage}`,
+                code: "INTERNAL",
+            });
+        }
+        throw failure;
+    }
+}
 /** One call, ready to invoke or stream. */
 export class Invocation {
     #connection;
@@ -48,7 +109,9 @@ export class Invocation {
     #name;
     #input;
     #reply;
-    constructor(connection, metadata, kind, componentId, entityId, name, input, reply) {
+    #state;
+    constructor(connection, metadata, kind, componentId, entityId, name, input, reply, state) {
+        this.#state = state;
         this.#connection = connection;
         this.#metadata = metadata;
         this.#kind = kind;
@@ -68,20 +131,48 @@ export class Invocation {
             metadata: metadataToProto(this.#metadata),
         };
     }
-    /** Invokes and decodes the reply; a refusal rejects with `CommandError`. */
+    /**
+     * Invokes and decodes the reply; a refusal rejects with `CommandError`. An agent's turn that waits for a
+     * person rejects with `ApprovalAwaited`; `ask` answers it instead.
+     */
     async invoke(input) {
-        const answer = await stubOf(this.#connection).invoke(this.#request(input));
-        switch (answer.result.case) {
-            case "reply":
-                return decodeReply(this.#reply, answer.result.value.payload);
-            case "error":
-                throw new CommandError(errorOf(answer.result.value));
-            default:
-                throw new CommandError({ message: "the sidecar answered nothing", code: "INTERNAL" });
-        }
+        const outcome = await this.ask(input);
+        if (outcome.kind === "awaiting-approval")
+            throw new ApprovalAwaited(outcome.requests);
+        return outcome.value;
+    }
+    /**
+     * Sends this command to the workflow and then waits for its end, as one call: answered with the state it
+     * ended with, within `timeoutMillis` of the command being sent. A refusal of the command rejects at once and
+     * no wait begins; the command's own reply is not kept. `state` decodes it, unless the workflow class did.
+     */
+    thenAwaitEnd(timeoutMillis, state) {
+        const shape = (state ?? this.#state);
+        const calls = new Calls(this.#connection, this.#metadata, this.#kind, this.#componentId, this.#entityId, shape);
+        return new AwaitingInvocation(timeoutMillis, (input) => this.invoke(input), (left) => calls.awaitEnd(left));
+    }
+    /** Calls an agent's handler for its outcome: the model's answer, or the approval requests the turn waits on. */
+    async ask(input) {
+        return outcomeOf(this.#reply, await stubOf(this.#connection).invoke(this.#request(input)));
     }
-    /** Invokes a streaming handler; yields tokens in order; a failure rejects with `CommandError`. */
+    /**
+     * Decides one of the session's approval requests; this invocation names the handler whose turn waits.
+     * `by` names who decided and is required. When it was the turn's last awaited decision the turn goes on,
+     * and this answers as `ask` would have. A request already decided is a conflict.
+     */
+    async decide(approvalId, decision) {
+        return outcomeOf(this.#reply, await decideOn(this.#connection, this.#metadata, this.#kind, this.#componentId, this.#entityId, this.#name, approvalId, decision));
+    }
+    /** Invokes a streaming handler; yields tokens in order; a failure rejects with `CommandError`, a turn that waits with `ApprovalAwaited`. */
     async *stream(input) {
+        for await (const part of this.streamParts(input)) {
+            if (typeof part !== "string")
+                throw new ApprovalAwaited(part.requests);
+            yield part;
+        }
+    }
+    /** As `stream`, ending with one awaiting part when the turn waits for a person. */
+    async *streamParts(input) {
         for await (const token of stubOf(this.#connection).invokeStream(this.#request(input))) {
             switch (token.token.case) {
                 case "text":
@@ -91,10 +182,39 @@ export class Invocation {
                     return;
                 case "failed":
                     throw new CommandError(errorOf(token.token.value));
+                case "approval":
+                    yield awaitingOf(token.token.value);
+                    return;
             }
         }
     }
 }
+/** A command to a workflow followed by a wait for its end, with one deadline from the send. */
+export class AwaitingInvocation {
+    #timeoutMillis;
+    #send;
+    #await;
+    constructor(timeoutMillis, send, wait) {
+        this.#timeoutMillis = timeoutMillis;
+        this.#send = send;
+        this.#await = wait;
+    }
+    /** Sends the command and waits for the end; rejects as `Calls.awaitEnd` does. */
+    async invoke(input) {
+        const deadline = Date.now() + timeoutOf(this.#timeoutMillis);
+        await this.#send(input);
+        return await this.#await(Math.max(1, deadline - Date.now()));
+    }
+}
+const awaitTooOld = (failure) => {
+    if (failure instanceof ConnectError && failure.code === Code.Unimplemented) {
+        throw new CommandError({
+            message: `the runtime beside this process is too old for waiting for a workflow's end, which needs protocol ${AWAIT_SINCE}; this process speaks ${PROTOCOL_VERSION}: ${failure.rawMessage}`,
+            code: "UNAVAILABLE",
+        });
+    }
+    throw failure;
+};
 /** Calls on one component instance, by wire name. */
 export class Calls {
     #connection;
@@ -102,16 +222,67 @@ export class Calls {
     #kind;
     #componentId;
     #entityId;
-    constructor(connection, metadata, kind, componentId, entityId) {
+    #state;
+    constructor(connection, metadata, kind, componentId, entityId, state) {
         this.#connection = connection;
         this.#metadata = metadata;
         this.#kind = kind;
         this.#componentId = componentId;
         this.#entityId = entityId;
+        this.#state = state;
     }
     /** `call("add-item", LineItem, Done)`: the wire name, the input shape (omit for none) and the reply shape (omit for `done`). */
     call(name, input, reply) {
-        return new Invocation(this.#connection, this.#metadata, this.#kind, this.#componentId, this.#entityId, name, input, reply);
+        return new Invocation(this.#connection, this.#metadata, this.#kind, this.#componentId, this.#entityId, name, input, reply, this.#state);
+    }
+    #awaitRequest(timeoutMillis) {
+        return {
+            componentId: this.#componentId,
+            entityId: this.#entityId,
+            timeoutMillis: BigInt(timeoutOf(timeoutMillis)),
+            metadata: metadataToProto(this.#metadata),
+        };
+    }
+    /**
+     * Waits for this workflow's end, for at most `timeoutMillis`, and resolves with the state it ended with — at
+     * once when it already has. A workflow that failed or was deleted rejects with `CommandError` whose code is
+     * `WORKFLOW_FAILED` and whose `details` hold `step`, `reason` and `deleted`; a wait not answered in time
+     * rejects with `TIMEOUT` and the workflow runs on. A paused workflow has not ended. There is no default.
+     */
+    async awaitEnd(timeoutMillis, state) {
+        const shape = (state ?? this.#state);
+        const answer = await stubOf(this.#connection).awaitEnd(this.#awaitRequest(timeoutMillis)).catch(awaitTooOld);
+        const outcome = outcomeOf(shape, answer);
+        if (outcome.kind !== "answered")
+            throw new CommandError({ message: "a workflow answered a wait as an agent", code: "INTERNAL" });
+        return outcome.value;
+    }
+    /**
+     * The same wait as a stream, for an `sse` route that must outlast the idle timeout: a heartbeat while it goes
+     * on, then exactly one `ended`, `failed` or `timed-out` part. `awaitPartJson` renders a part as a line.
+     */
+    async *awaitEndParts(timeoutMillis, state) {
+        const shape = (state ?? this.#state);
+        try {
+            for await (const token of stubOf(this.#connection).awaitEndStream(this.#awaitRequest(timeoutMillis))) {
+                switch (token.token.case) {
+                    case "heartbeat":
+                        yield { kind: "heartbeat" };
+                        break;
+                    case "ended":
+                        yield { kind: "ended", state: decodeReply(shape, token.token.value) };
+                        return;
+                    case "failed": {
+                        const error = new CommandError(errorOf(token.token.value));
+                        yield error.code === "TIMEOUT" ? { kind: "timed-out", message: error.message } : { kind: "failed", error };
+                        return;
+                    }
+                }
+            }
+        }
+        catch (failure) {
+            awaitTooOld(failure);
+        }
     }
 }
 /** Calls on one component instance through its class's handler table, fully typed. */
@@ -124,12 +295,47 @@ export class TypedCalls {
     call(handler) {
         return this.#calls.call(handler.name, handler.input, handler.reply);
     }
+    /** For a workflow: waits for its end and resolves with its state, decoded as the class declares it. */
+    awaitEnd(timeoutMillis) {
+        return this.#calls.awaitEnd(timeoutMillis);
+    }
+    /** For a workflow: the same wait as a stream of parts. */
+    awaitEndParts(timeoutMillis) {
+        return this.#calls.awaitEndParts(timeoutMillis);
+    }
+}
+/** The first protocol in which a view's query can be streamed and watched. */
+export const VIEW_STREAMS_SINCE = "1.17";
+/** A watch ended for `reason`: `rebuilt`, `instance-stopping`, `listener-lost` or `unread`. Watch again for the rows now. */
+export class WatchEnded extends Error {
+    reason;
+    constructor(reason) {
+        super(`the watch ended: ${reason}`);
+        this.name = "WatchEnded";
+        this.reason = reason;
+    }
+}
+function overflowToProto(overflow) {
+    switch (overflow) {
+        case "dropHead":
+            return ProtoOverflow.DROP_HEAD;
+        case "dropTail":
+            return ProtoOverflow.DROP_TAIL;
+        case "dropNew":
+            return ProtoOverflow.DROP_NEW;
+        case "dropAll":
+            return ProtoOverflow.DROP_ALL;
+        case "fail":
+            return ProtoOverflow.FAIL;
+    }
 }
 /** View queries: rows come back as a JSON array decoded with the row shape. */
 export class Views {
     #connection;
-    constructor(connection) {
+    #metadata;
+    constructor(connection, metadata = {}) {
         this.#connection = connection;
+        this.#metadata = metadata;
     }
     async get(viewId, key, row) {
         const rows = await this.query(viewId, "get", key, row);
@@ -139,7 +345,101 @@ export class Views {
         return this.query(viewId, "all", null, row);
     }
     async query(viewId, name, key, row) {
-        const answer = await stubOf(this.#connection).query({ viewId, name, payload: encodePayload(textCodecs.string, key ?? "") });
+        const answer = await stubOf(this.#connection).query({ viewId, name, payload: encodePayload(textCodecs.string, key ?? ""), metadata: metadataToProto(this.#metadata) });
+        return Views.#rows(answer, row);
+    }
+    /**
+     * The rows of one of a view's declared queries, asked by name with the values it takes. At most
+     * `limit` rows, 1000 when it is not given, in the statement's own order.
+     */
+    async ask(viewId, name, values, row, limit) {
+        const answer = await stubOf(this.#connection).query({
+            viewId,
+            name,
+            metadata: metadataToProto(this.#metadata),
+            values: { ...values },
+            ...(limit !== undefined ? { limit } : {}),
+        });
+        return Views.#rows(answer, row);
+    }
+    /**
+     * The rows of `all` or one of a view's declared queries as the database yields them: nothing
+     * collected, and no limit unless one is given. A statement the database ends, or a reader that
+     * takes nothing for its timeout, throws.
+     */
+    async *stream(viewId, name, values, row, options = {}) {
+        const frames = stubOf(this.#connection).queryStream({
+            viewId,
+            name,
+            metadata: metadataToProto(this.#metadata),
+            values: { ...values },
+            ...(options.limit !== undefined ? { limit: options.limit } : {}),
+        });
+        for await (const event of Views.#frames(frames, row))
+            if (event.kind === "row")
+                yield event.row;
+    }
+    /**
+     * A watch of one of a view's declared queries, declared `{ watched: true }`: every row it matches
+     * now, then `caughtUp`, then each row as it is written and matches and a `removed` for each given row
+     * that stops matching. Throws `WatchEnded` when it ends with a reason. `unread` bounds the rows held
+     * for a reader that has not read them, and `overflow` says what happens past that bound.
+     */
+    async *watch(viewId, name, values, row, options = {}) {
+        const frames = stubOf(this.#connection).watch({
+            viewId,
+            metadata: metadataToProto(this.#metadata),
+            target: { case: "named", value: { name, values: { ...values } } },
+            ...(options.unread !== undefined ? { unreadBound: options.unread } : {}),
+            overflow: overflowToProto(options.overflow ?? "dropHead"),
+        });
+        yield* Views.#frames(frames, row);
+    }
+    /** A watch of one row by its key: the row now, then `caughtUp`, then each version and a `removed` when it is deleted. */
+    async *watchRow(viewId, key, row, options = {}) {
+        const frames = stubOf(this.#connection).watch({
+            viewId,
+            metadata: metadataToProto(this.#metadata),
+            target: { case: "key", value: key },
+            ...(options.unread !== undefined ? { unreadBound: options.unread } : {}),
+            overflow: overflowToProto(options.overflow ?? "dropHead"),
+        });
+        yield* Views.#frames(frames, row);
+    }
+    static async *#frames(frames, row) {
+        const codec = isCodec(row) ? row : codecFor(row);
+        try {
+            for await (const frame of frames) {
+                switch (frame.frame.case) {
+                    case "row":
+                        yield { kind: "row", key: frame.frame.value.key, row: codec.decode(frame.frame.value.payload?.data ?? new Uint8Array()) };
+                        break;
+                    case "removed":
+                        yield { kind: "removed", key: frame.frame.value.key };
+                        break;
+                    case "caughtUp":
+                        yield { kind: "caughtUp" };
+                        break;
+                    case "ended":
+                        throw new WatchEnded(frame.frame.value.reason);
+                    case "failed":
+                        throw new CommandError(errorOf(frame.frame.value));
+                    default:
+                        return;
+                }
+            }
+        }
+        catch (failure) {
+            if (failure instanceof ConnectError && failure.code === Code.Unimplemented) {
+                throw new CommandError({
+                    message: `the runtime beside this process does not offer view streams, which need protocol ${VIEW_STREAMS_SINCE} (this SDK speaks ${PROTOCOL_VERSION}): ${failure.rawMessage}`,
+                    code: "INTERNAL",
+                });
+            }
+            throw failure;
+        }
+    }
+    static #rows(answer, row) {
         switch (answer.result.case) {
             case "rows": {
                 const text = new TextDecoder().decode(answer.result.value.data);
@@ -159,6 +459,16 @@ export class Views {
         }
     }
 }
+const RECURRING_SINCE = "1.12";
+const MAX_PERIOD_DAYS = 36500;
+const MIN_PERIOD = Duration.ofMillis(1);
+const MAX_PERIOD = Duration.ofSeconds(MAX_PERIOD_DAYS * 86400);
+/** What is wrong with a recurring timer's period, if anything: the runtime's own rule. */
+function periodProblem(timerId, period) {
+    if (Duration.compare(period, MIN_PERIOD) >= 0 && Duration.compare(period, MAX_PERIOD) <= 0)
+        return undefined;
+    return `timer '${timerId}' has a period of ${period.toString()}; a period is from 1 millisecond to ${MAX_PERIOD_DAYS} days`;
+}
 export class Timers {
     #connection;
     constructor(connection) {
@@ -179,10 +489,161 @@ export class Timers {
             payload: inputPayload(t.input, input),
         });
     }
+    /**
+     * Schedules `target`, a timed action's handler, first after `delay` (zero or less is due at once) and
+     * then every `period` until it is cancelled or replaced. Setting it again with the same handler and
+     * period keeps its next due time, so a service may set its recurring timers every time it starts.
+     * A period outside 1 millisecond to 36,500 days is refused with `BAD_REQUEST` before anything is sent.
+     */
+    async scheduleRecurring(timerId, delay, period, target, input) {
+        const problem = periodProblem(timerId, period);
+        if (problem !== undefined)
+            throw new CommandError({ message: problem, code: "BAD_REQUEST" });
+        const t = "component" in target ? { componentId: target.component.componentId, name: target.handler.name, input: target.handler.input } : target;
+        const reply = await stubOf(this.#connection)
+            .scheduleRecurring({
+            timerId,
+            delayMillis: BigInt(delay.toMillis()),
+            periodMillis: BigInt(period.toMillis()),
+            componentId: t.componentId,
+            name: t.name,
+            payload: inputPayload(t.input, input),
+        })
+            .catch(tooOld("recurring timers", RECURRING_SINCE));
+        if (reply.error)
+            throw new CommandError(errorOf(reply.error));
+    }
+    /** Cancels the timer under `timerId`, whether it fires once or recurs. */
     async cancel(timerId) {
         await stubOf(this.#connection).cancel({ timerId });
     }
 }
+// ── The secret store (protocol 1.6) ───────────────────────────────────────────
+const SECRETS_SINCE = "1.6";
+export const MAX_SECRET_NAME_LENGTH = 253;
+export const MAX_SECRET_VALUE_BYTES = 65536;
+const SECRET_NAME_RULE = `a secret's name is 1 to ${MAX_SECRET_NAME_LENGTH} characters, each a letter, a digit, '.', '_', '-' or '/'`;
+const VALID_SECRET_NAME = new RegExp(`^[A-Za-z0-9._/-]{1,${MAX_SECRET_NAME_LENGTH}}$`);
+/** What is wrong with a secret's name, if anything: the runtime's own rule. */
+export function secretNameProblem(name) {
+    if (VALID_SECRET_NAME.test(name))
+        return undefined;
+    const shown = name.length > 40 ? `${name.slice(0, 40)}…` : name;
+    return `${SECRET_NAME_RULE}; "${shown}" is not`;
+}
+/** What is wrong with a secret's value, if anything. Never quotes the value. */
+export function secretValueProblem(value) {
+    if (value === "")
+        return "a secret's value must not be empty";
+    const size = new TextEncoder().encode(value).length;
+    return size > MAX_SECRET_VALUE_BYTES ? `a secret's value is at most ${MAX_SECRET_VALUE_BYTES} bytes as UTF-8; this one is ${size}` : undefined;
+}
+/** Turns `UNIMPLEMENTED` from a runtime older than protocol `since` into an error naming both versions. */
+function tooOld(what, since) {
+    return (failure) => {
+        if (failure instanceof ConnectError && failure.code === Code.Unimplemented) {
+            throw new CommandError({
+                message: `the runtime beside this process is too old for ${what}, which needs protocol ${since}; this process speaks ${PROTOCOL_VERSION}: ${failure.rawMessage}`,
+                code: "INTERNAL",
+            });
+        }
+        throw failure;
+    };
+}
+const secretsTooOld = tooOld("the secret store", SECRETS_SINCE);
+/**
+ * The service's secret store: named text values the runtime keeps in the service's own database,
+ * encrypted with a key this process never sees. Offered to endpoints, workflow steps, consumers,
+ * timed actions and agents; an entity and a view have no `secrets` at all.
+ *
+ * Every refusal is a `CommandError` with the runtime's code: `BAD_REQUEST` for a name or a value that
+ * breaks its rule, `INTERNAL` when the service has no secret key or a value was kept with another
+ * one, `UNAVAILABLE` when the database cannot be reached.
+ */
+export class Secrets {
+    #client;
+    /** The store reached through `client`'s sidecar; with none, every call throws. */
+    constructor(client) {
+        this.#client = client;
+    }
+    #stub() {
+        const connection = this.#client ? connectionOf.get(this.#client) : undefined;
+        if (!connection)
+            throw new Error("this secret store is not connected to a runtime; a unit test passes an InMemorySecrets");
+        return stubOf(connection);
+    }
+    /** Keeps `value` under `name`, replacing what was there. */
+    async put(name, value) {
+        const reply = await this.#stub().putSecret({ name, value }).catch(secretsTooOld);
+        if (reply.error)
+            throw new CommandError(errorOf(reply.error));
+    }
+    /** The value kept under `name`, or `undefined` when there is none. Never an empty string. */
+    async get(name) {
+        const reply = await this.#stub().getSecret({ name }).catch(secretsTooOld);
+        switch (reply.result.case) {
+            case "value":
+                return reply.result.value;
+            case "absent":
+                return undefined;
+            case "error":
+                throw new CommandError(errorOf(reply.result.value));
+            default:
+                throw new CommandError({ message: "the runtime answered a secret's read with nothing", code: "INTERNAL" });
+        }
+    }
+    /** Removes what is kept under `name`. Removing nothing is not an error. */
+    async delete(name) {
+        const reply = await this.#stub().deleteSecret({ name }).catch(secretsTooOld);
+        if (reply.error)
+            throw new CommandError(errorOf(reply.error));
+    }
+}
+/** A secret store for unit tests: a map, applying the runtime's rules with its words. */
+export class InMemorySecrets extends Secrets {
+    values = new Map();
+    async put(name, value) {
+        const problem = secretNameProblem(name) ?? secretValueProblem(value);
+        if (problem)
+            throw new CommandError({ message: problem, code: "BAD_REQUEST" });
+        this.values.set(name, value);
+    }
+    async get(name) {
+        const problem = secretNameProblem(name);
+        if (problem)
+            throw new CommandError({ message: problem, code: "BAD_REQUEST" });
+        return this.values.get(name);
+    }
+    async delete(name) {
+        const problem = secretNameProblem(name);
+        if (problem)
+            throw new CommandError({ message: problem, code: "BAD_REQUEST" });
+        this.values.delete(name);
+    }
+}
+/** A store for unit tests whose every call throws: the unit kit's default, beside `noClient()`. */
+export function noSecrets() {
+    return new Secrets(undefined);
+}
+const connectionOf = new WeakMap();
+const metadataOf = new WeakMap();
+/**
+ * @internal What a call to another service is sent through: `client`'s sidecar, and the metadata of
+ * the handler `client` was scoped to. Not a member of the client, which an entity holds too.
+ */
+export function channelOf(client) {
+    const connection = connectionOf.get(client);
+    if (!connection)
+        return undefined;
+    return { stub: () => stubOf(connection), metadata: metadataOf.get(client) ?? {} };
+}
+/**
+ * @internal The secret store reached through `client`'s sidecar. Not a member of the client, which
+ * an entity holds too: only the component kinds that may have a store call this.
+ */
+export function secretsFor(client) {
+    return new Secrets(client);
+}
 export class ComponentClient {
     #connection;
     #metadata;
@@ -191,8 +652,10 @@ export class ComponentClient {
     constructor(address = process.env.ANKKA_SIDECAR_ADDRESS ?? "127.0.0.1:9011", connection, metadata = {}) {
         this.#connection = connection ?? { address, transport: undefined, stub: undefined };
         this.#metadata = metadata;
-        this.views = new Views(this.#connection);
+        this.views = new Views(this.#connection, metadata);
         this.timers = new Timers(this.#connection);
+        connectionOf.set(this, this.#connection);
+        metadataOf.set(this, metadata);
     }
     /** Points every client sharing this connection at a new sidecar address (the integration testkit's mapped port). */
     reconnect(address) {
@@ -253,6 +716,10 @@ export class ComponentClient {
                 throw new CommandError({ message: "the sidecar answered nothing", code: "INTERNAL" });
         }
     }
+    /** @internal A decision on an approval request; a refusal rejects with `CommandError`. */
+    async _decide(kind, componentId, entityId, name, approvalId, decision) {
+        outcomeOf(undefined, await decideOn(this.#connection, this.#metadata, kind, componentId, entityId, name, approvalId, decision));
+    }
     /** @internal A streaming call whose tokens are text. */
     async *_rawStream(kind, componentId, entityId, name) {
         const request = { kind: kindToProto(kind), componentId, entityId, name, payload: EMPTY_PAYLOAD, metadata: metadataToProto(this.#metadata) };
@@ -270,7 +737,9 @@ export class ComponentClient {
     }
     /** Typed calls through a component class's handler table: `client.of(ShoppingCartEntity, cartId).call(ShoppingCartEntity.handlers.addItem).invoke(item)`. */
     of(component, entityId) {
-        return new TypedCalls(new Calls(this.#connection, this.#metadata, component.prototype._kind, component.componentId, entityId));
+        // A workflow class declares its state's shape: what a wait for its end decodes the state with.
+        const state = component.state;
+        return new TypedCalls(new Calls(this.#connection, this.#metadata, component.prototype._kind, component.componentId, entityId, state));
     }
 }
 /** A client for unit tests: every call throws, naming what was attempted. */