ankka 0.11.0 → 0.13.0

package/dist/client-keys.js

@@ -0,0 +1,182 @@
+// A service's client keys (protocol 1.20): credentials it issues for its MCP endpoint, each for one
+// subject, with an expiry, an optional scope of tools and attributes a tool reads as the principal's
+// claims. The runtime keeps them; this process sees a key once, in the answer to `issue`, and never
+// again. Offered to endpoints, MCP endpoints, timed actions and agents, as the secret store is.
+//
+//   const issued = await this.clientKeys.issue({ subject: "acme", expiry: Expiry.after({ days: 365 }), scope: ["list_jobs"] })
+//   issued.clientKey   // shown here, and nowhere again
+import { Code, ConnectError } from "@connectrpc/connect";
+import { channelOf } from "./client.js";
+import { metadataToProto } from "./context.js";
+import { CommandError, ErrorCode } from "./effects/common.js";
+import { errorCodeFromProto } from "./kinds.js";
+import { PROTOCOL_VERSION } from "./spec.js";
+import { Duration, Instant } from "./time.js";
+/** The first protocol whose runtime keeps client keys; an older one answers `UNIMPLEMENTED`. */
+export const CLIENT_KEYS_SINCE = "1.20";
+export const Expiry = Object.freeze({
+    /** After a while from now: `Expiry.after({ days: 365 })`, or a `Duration`. */
+    after(by) {
+        const millis = by instanceof Duration
+            ? by.toMillis()
+            : (by.days ?? 0) * 86_400_000 + (by.hours ?? 0) * 3_600_000 + (by.minutes ?? 0) * 60_000 + (by.seconds ?? 0) * 1_000 + (by.millis ?? 0);
+        if (!Number.isFinite(millis) || millis <= 0)
+            throw new TypeError(`a client key's expiry is a positive while, not ${millis}ms`);
+        return Object.freeze({ kind: "after", millis });
+    },
+    /** At an instant. */
+    at(when) {
+        const epochMillis = when instanceof Instant ? when.toEpochMilli() : when.getTime();
+        return Object.freeze({ kind: "at", epochMillis });
+    },
+    /** Never: admitted until it is revoked. */
+    never: Object.freeze({ kind: "never" }),
+});
+function refusalOf(error) {
+    return new CommandError({ message: error.message, code: errorCodeFromProto(error.code), details: { ...(error.details ?? {}) } });
+}
+function tooOld(failure) {
+    if (failure instanceof ConnectError && failure.code === Code.Unimplemented) {
+        throw new CommandError({
+            message: `the runtime beside this process is too old for client keys, which needs protocol ${CLIENT_KEYS_SINCE}; this process speaks ${PROTOCOL_VERSION}: ${failure.rawMessage}`,
+            code: ErrorCode.Internal,
+        });
+    }
+    throw failure;
+}
+function instant(millis) {
+    return millis === undefined ? null : Instant.ofEpochMilli(Number(millis));
+}
+/**
+ * The service's client keys, kept by the runtime. A refusal is a `CommandError` with the runtime's
+ * code: `BAD_REQUEST` for a request that breaks a rule, `UNAVAILABLE` when the service's MCP
+ * endpoints admit no client key (there is then nothing to keep them), `NOT_FOUND` for an unknown id.
+ */
+export class ClientKeys {
+    #client;
+    /** The keys reached through `client`'s sidecar; with none, every call throws. */
+    constructor(client) {
+        this.#client = client;
+    }
+    #channel() {
+        const channel = this.#client ? channelOf(this.#client) : undefined;
+        if (!channel)
+            throw new Error("these client keys are not connected to a runtime; a unit test passes an InMemoryClientKeys");
+        return channel;
+    }
+    /** Issues a key; the answer is the one place the key is ever shown. */
+    async issue(request) {
+        const { stub, metadata } = this.#channel();
+        const expiry = request.expiry;
+        const reply = await stub()
+            .issueClientKey({
+            subject: request.subject,
+            expiry: expiry.kind === "after"
+                ? { case: "afterMillis", value: BigInt(expiry.millis) }
+                : expiry.kind === "at"
+                    ? { case: "atEpochMillis", value: BigInt(expiry.epochMillis) }
+                    : { case: "never", value: true },
+            ...(request.endpoint !== undefined ? { endpoint: request.endpoint } : {}),
+            scope: [...(request.scope ?? [])],
+            attributes: { ...(request.attributes ?? {}) },
+            ...(request.label !== undefined ? { label: request.label } : {}),
+            metadata: metadataToProto(metadata),
+        })
+            .catch(tooOld);
+        switch (reply.reply.case) {
+            case "issued":
+                return Object.freeze({ id: reply.reply.value.id, clientKey: reply.reply.value.clientKey });
+            case "error":
+                throw refusalOf(reply.reply.value);
+            default:
+                throw new CommandError({ message: "the runtime answered an issue with nothing", code: ErrorCode.Internal });
+        }
+    }
+    /** Every client key of the service, revoked ones included; never a key itself. */
+    async list() {
+        const { stub, metadata } = this.#channel();
+        const reply = await stub().listClientKeys({ metadata: metadataToProto(metadata) }).catch(tooOld);
+        if (reply.error)
+            throw refusalOf(reply.error);
+        return reply.keys.map((k) => Object.freeze({
+            id: k.id,
+            subject: k.subject,
+            attributes: Object.freeze({ ...k.attributes }),
+            label: k.label ?? null,
+            endpoint: k.endpoint,
+            scope: Object.freeze([...k.scope]),
+            issuedAt: Instant.ofEpochMilli(Number(k.issuedAtMillis)),
+            expiresAt: instant(k.expiresAtMillis),
+            lastUsed: instant(k.lastUsedMillis),
+            revokedAt: instant(k.revokedAtMillis),
+        }));
+    }
+    /** Revokes a key: refused on its next request on every instance. Revoking twice is not an error. */
+    async revoke(id) {
+        const { stub, metadata } = this.#channel();
+        const reply = await stub().revokeClientKey({ id, metadata: metadataToProto(metadata) }).catch(tooOld);
+        if (reply.error)
+            throw refusalOf(reply.error);
+    }
+}
+/** Client keys for unit tests: a map, issuing keys that look like the runtime's and applying its rules. */
+export class InMemoryClientKeys extends ClientKeys {
+    #keys = new Map();
+    #next = 0;
+    constructor() {
+        super(undefined);
+    }
+    /** The key issued under `id`, which a test may present; the runtime shows it only once. */
+    keyOf(id) {
+        return this.#keys.get(id)?.clientKey;
+    }
+    async issue(request) {
+        if (typeof request.subject !== "string" || request.subject.trim() === "") {
+            throw new CommandError({ message: "a client key needs a subject", code: ErrorCode.BadRequest });
+        }
+        const attributes = request.attributes ?? {};
+        if (Object.keys(attributes).length > 16)
+            throw new CommandError({ message: "a client key carries at most 16 attributes", code: ErrorCode.BadRequest });
+        for (const [name, value] of Object.entries(attributes)) {
+            if (name.length > 256 || value.length > 256)
+                throw new CommandError({ message: `attribute '${name.slice(0, 40)}' is longer than 256 characters`, code: ErrorCode.BadRequest });
+        }
+        this.#next += 1;
+        const id = `ck_${this.#next}`;
+        const clientKey = `ak_test_${id}_${Math.random().toString(36).slice(2)}`;
+        const now = Instant.now();
+        const expiry = request.expiry;
+        const expiresAt = expiry.kind === "after" ? Instant.ofEpochMilli(now.toEpochMilli() + expiry.millis) : expiry.kind === "at" ? Instant.ofEpochMilli(expiry.epochMillis) : null;
+        const summary = Object.freeze({
+            id,
+            subject: request.subject,
+            attributes: Object.freeze({ ...attributes }),
+            label: request.label ?? null,
+            endpoint: request.endpoint ?? "",
+            scope: Object.freeze([...(request.scope ?? [])]),
+            issuedAt: now,
+            expiresAt,
+            lastUsed: null,
+            revokedAt: null,
+        });
+        this.#keys.set(id, { summary, clientKey });
+        return Object.freeze({ id, clientKey });
+    }
+    async list() {
+        return [...this.#keys.values()].map((k) => k.summary);
+    }
+    async revoke(id) {
+        const held = this.#keys.get(id);
+        if (!held)
+            throw new CommandError({ message: `no client key '${id}'`, code: ErrorCode.NotFound });
+        if (held.summary.revokedAt === null)
+            this.#keys.set(id, { ...held, summary: Object.freeze({ ...held.summary, revokedAt: Instant.now() }) });
+    }
+}
+/**
+ * @internal The client keys reached through `client`'s sidecar. Not a member of the client, which an
+ * entity holds too: only the component kinds that may issue keys call this.
+ */
+export function clientKeysFor(client) {
+    return new ClientKeys(client);
+}

package/dist/client.d.ts

@@ -1,7 +1,7 @@
 import { type Client as ConnectClient, type Transport } from "@connectrpc/connect";
 import { Client } from "./_proto/ankka/protocol/v1/client_pb.ts";
 import { jsonCodec, type Shape } from "./codec.ts";
-import { type Metadata } from "./effects/common.ts";
+import { CommandError, type Metadata } from "./effects/common.ts";
 import type { HandlerRef } from "./handlers.ts";
 import { type ComponentKind } from "./kinds.ts";
 import { Duration } from "./time.ts";
@@ -19,15 +19,38 @@ interface Connection {
     transport: Transport | undefined;
     stub: ConnectClient<typeof Client> | undefined;
 }
+/** The first protocol whose runtime can wait for a workflow's end; an older one answers `UNIMPLEMENTED`. */
+export declare const AWAIT_SINCE = "1.18";
+/** One part of a wait served as a stream: the wait goes on, or how it ended. */
+export type AwaitPart<S> = {
+    readonly kind: "heartbeat";
+} | {
+    readonly kind: "ended";
+    readonly state: S;
+} | {
+    readonly kind: "failed";
+    readonly error: CommandError;
+} | {
+    readonly kind: "timed-out";
+    readonly message: string;
+};
+/** A part as one line of JSON, which is what an `sse` route yields for it. */
+export declare function awaitPartJson<S>(part: AwaitPart<S>): string;
 /** One call, ready to invoke or stream. */
 export declare class Invocation<I, R> {
     #private;
-    constructor(connection: Connection, metadata: Metadata, kind: ComponentKind, componentId: string, entityId: string, name: string, input: Shape<I> | undefined, reply: Shape<R> | undefined);
+    constructor(connection: Connection, metadata: Metadata, kind: ComponentKind, componentId: string, entityId: string, name: string, input: Shape<I> | undefined, reply: Shape<R> | undefined, state?: Shape<unknown>);
     /**
      * 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.
      */
     invoke(input?: I): Promise<R>;
+    /**
+     * 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<S>(timeoutMillis: number, state?: Shape<S>): AwaitingInvocation<I, S>;
     /** Calls an agent's handler for its outcome: the model's answer, or the approval requests the turn waits on. */
     ask(input?: I): Promise<AgentOutcome<R>>;
     /**
@@ -43,12 +66,31 @@ export declare class Invocation<I, R> {
         kind: "awaiting-approval";
     }>>;
 }
+/** A command to a workflow followed by a wait for its end, with one deadline from the send. */
+export declare class AwaitingInvocation<I, S> {
+    #private;
+    constructor(timeoutMillis: number, send: (input: I | undefined) => Promise<unknown>, wait: (leftMillis: number) => Promise<S>);
+    /** Sends the command and waits for the end; rejects as `Calls.awaitEnd` does. */
+    invoke(input?: I): Promise<S>;
+}
 /** Calls on one component instance, by wire name. */
 export declare class Calls {
     #private;
-    constructor(connection: Connection, metadata: Metadata, kind: ComponentKind, componentId: string, entityId: string);
+    constructor(connection: Connection, metadata: Metadata, kind: ComponentKind, componentId: string, entityId: string, state?: Shape<unknown>);
     /** `call("add-item", LineItem, Done)`: the wire name, the input shape (omit for none) and the reply shape (omit for `done`). */
     call<I = undefined, R = unknown>(name: string, input?: Shape<I>, reply?: Shape<R>): Invocation<I, R>;
+    /**
+     * 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.
+     */
+    awaitEnd<S>(timeoutMillis: number, state?: Shape<S>): Promise<S>;
+    /**
+     * 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.
+     */
+    awaitEndParts<S>(timeoutMillis: number, state?: Shape<S>): AsyncIterable<AwaitPart<S>>;
 }
 /** Calls on one component instance through its class's handler table, fully typed. */
 export declare class TypedCalls<C> {
@@ -56,7 +98,41 @@ export declare class TypedCalls<C> {
     constructor(calls: Calls);
     /** `call(ShoppingCartEntity.handlers.addItem)`: the handler's wire name and shapes come from the declaration. */
     call<I, R>(handler: HandlerRef<C, I, R, any>): Invocation<I, R>;
+    /** For a workflow: waits for its end and resolves with its state, decoded as the class declares it. */
+    awaitEnd<S = StateOf<C>>(timeoutMillis: number): Promise<S>;
+    /** For a workflow: the same wait as a stream of parts. */
+    awaitEndParts<S = StateOf<C>>(timeoutMillis: number): AsyncIterable<AwaitPart<S>>;
+}
+/** The first protocol in which a view's query can be streamed and watched. */
+export declare const VIEW_STREAMS_SINCE = "1.17";
+/** What a watch of a view gives: a row as the query sees it now, a removal of one it gave, or the caught-up marker. */
+export type WatchEvent<Row> = {
+    readonly kind: "row";
+    readonly key: string;
+    readonly row: Row;
+} | {
+    readonly kind: "removed";
+    readonly key: string;
+} | {
+    readonly kind: "caughtUp";
+};
+/** What a watch does past its unread bound: none slows the view. */
+export type Overflow = "dropHead" | "dropTail" | "dropNew" | "dropAll" | "fail";
+export interface WatchOptions {
+    /** How many unread rows the watch holds, one per key; the instance's own bound when absent. */
+    readonly unread?: number;
+    /** What it does past that bound; `dropHead`, the row changed longest ago, when absent. */
+    readonly overflow?: Overflow;
 }
+/** A watch ended for `reason`: `rebuilt`, `instance-stopping`, `listener-lost` or `unread`. Watch again for the rows now. */
+export declare class WatchEnded extends Error {
+    readonly reason: string;
+    constructor(reason: string);
+}
+/** A workflow instance's state type, read from its `state` getter. */
+type StateOf<C> = C extends {
+    readonly state: infer S;
+} ? S : unknown;
 /** View queries: rows come back as a JSON array decoded with the row shape. */
 export declare class Views {
     #private;
@@ -69,6 +145,23 @@ export declare class Views {
      * `limit` rows, 1000 when it is not given, in the statement's own order.
      */
     ask<Row>(viewId: string, name: string, values: Readonly<Record<string, string>>, row: Shape<Row>, limit?: number): Promise<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.
+     */
+    stream<Row>(viewId: string, name: string, values: Readonly<Record<string, string>>, row: Shape<Row>, options?: {
+        readonly limit?: number;
+    }): AsyncIterable<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.
+     */
+    watch<Row>(viewId: string, name: string, values: Readonly<Record<string, string>>, row: Shape<Row>, options?: WatchOptions): AsyncIterable<WatchEvent<Row>>;
+    /** A watch of one row by its key: the row now, then `caughtUp`, then each version and a `removed` when it is deleted. */
+    watchRow<Row>(viewId: string, key: string, row: Shape<Row>, options?: WatchOptions): AsyncIterable<WatchEvent<Row>>;
 }
 /** What a timer fires: a component class and one of its handlers, or the same by name. */
 export type TimerTarget = {

package/dist/client.js

@@ -5,7 +5,7 @@
 // so the sidecar records the call as a child span.
 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";
@@ -24,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) {
@@ -88,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;
@@ -118,6 +141,16 @@ export class Invocation {
             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)));
@@ -156,6 +189,32 @@ export class Invocation {
         }
     }
 }
+/** 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;
@@ -163,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. */
@@ -185,6 +295,39 @@ 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 {
@@ -219,6 +362,83 @@ export class Views {
         });
         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": {
@@ -517,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. */