@osolmaz/pi-workflows 0.16.0 → 0.16.2

package/src/channels/protocol.ts

@@ -0,0 +1,333 @@
+import { createHash } from "node:crypto";
+import type { JsonValue } from "../state/json.js";
+import type { HumanDecisionChannelRequest, HumanDecisionResponse } from "../workflows/types.js";
+
+export const CHANNEL_ADAPTER_PROTOCOL_SCHEMA = "pi-workflows.channel-adapter.v1" as const;
+
+export type TelegramMessageReference = {
+  chatId: string;
+  messageId: string;
+  recipientIndex: number;
+  partIndex: number;
+  contentDigest: string;
+};
+
+type ChannelAdapterMessageBase = {
+  schema: typeof CHANNEL_ADAPTER_PROTOCOL_SCHEMA;
+  adapterEpoch: string;
+  profile: string;
+  sequence: number;
+  expectedRevision: number;
+  stableMessageId: string;
+};
+
+export type ChannelAdapterMessage =
+  | (ChannelAdapterMessageBase & {
+      kind: "channel.ready";
+      cursor: number;
+    })
+  | (ChannelAdapterMessageBase & {
+      kind: "channel.present";
+      decisionId: string;
+      requestDigest: string;
+      attemptId: string;
+      state: "confirmed" | "failed" | "unknown";
+      messages: TelegramMessageReference[];
+      errorCode?: string;
+    })
+  | (ChannelAdapterMessageBase & {
+      kind: "channel.answer";
+      decisionId: string;
+      requestDigest: string;
+      response: HumanDecisionResponse;
+      actorId: string;
+      chatId: string;
+      eventId: string;
+      idempotencyKey: string;
+      cursor: number;
+    })
+  | (ChannelAdapterMessageBase & {
+      kind: "channel.settle";
+      decisionId: string;
+      requestDigest: string;
+      attemptId: string;
+      state: "confirmed" | "failed" | "unknown";
+      errorCode?: string;
+    })
+  | (ChannelAdapterMessageBase & {
+      kind: "channel.exiting";
+      cursor: number;
+    });
+
+export type ChannelAdapterCommand =
+  | {
+      kind: "channel.present";
+      stableMessageId: string;
+      attemptId: string;
+      request: HumanDecisionChannelRequest;
+    }
+  | {
+      kind: "channel.settle";
+      stableMessageId: string;
+      attemptId: string;
+      request: HumanDecisionChannelRequest;
+      outcome: "accepted" | "cancelled" | "expired";
+      response?: HumanDecisionResponse;
+      messages: TelegramMessageReference[];
+    }
+  | {
+      kind: "channel.poll";
+      cursor: number;
+      requests: HumanDecisionChannelRequest[];
+    }
+  | { kind: "channel.stop" };
+
+export type ChannelAdapterResponse = {
+  schema: typeof CHANNEL_ADAPTER_PROTOCOL_SCHEMA;
+  type: "response";
+  sequence: number;
+  outcome: "accepted" | "rejected";
+  revision: number;
+  command: ChannelAdapterCommand | null;
+  error?: string;
+};
+
+export type ChannelAdapterLaunch = {
+  schema: "pi-workflows.channel-adapter-launch.v1";
+  adapterEpoch: string;
+  profile: string;
+  token: string;
+  allowedUserIds: string[];
+  allowedChatIds: string[];
+  apiBase?: string;
+};
+
+export function encodeChannelLine(value: ChannelAdapterMessage | ChannelAdapterResponse): Buffer {
+  return Buffer.from(`${JSON.stringify(value)}\n`, "utf8");
+}
+
+export function parseChannelAdapterMessage(frame: Buffer): ChannelAdapterMessage {
+  const value = parseObject(frame, "channel adapter message");
+  requireBase(value);
+  const kind = value.kind;
+  if (kind === "channel.ready" || kind === "channel.exiting") {
+    requireNonNegativeInteger(value.cursor, "channel cursor");
+  } else if (kind === "channel.present") {
+    requireText(value.decisionId, "decisionId");
+    requireText(value.requestDigest, "requestDigest");
+    requireText(value.attemptId, "attemptId");
+    requireOneOf(value.state, ["confirmed", "failed", "unknown"], "presentation state");
+    if (!Array.isArray(value.messages)) throw new Error("Channel message references are invalid");
+    value.messages.forEach(validateMessageReference);
+    requireOptionalText(value.errorCode, "errorCode");
+  } else if (kind === "channel.answer") {
+    requireText(value.decisionId, "decisionId");
+    requireText(value.requestDigest, "requestDigest");
+    validateDecisionResponse(value.response);
+    requireText(value.actorId, "actorId");
+    requireText(value.chatId, "chatId");
+    requireText(value.eventId, "eventId");
+    requireText(value.idempotencyKey, "idempotencyKey");
+    requireNonNegativeInteger(value.cursor, "channel cursor");
+  } else if (kind === "channel.settle") {
+    requireText(value.decisionId, "decisionId");
+    requireText(value.requestDigest, "requestDigest");
+    requireText(value.attemptId, "attemptId");
+    requireOneOf(value.state, ["confirmed", "failed", "unknown"], "settlement state");
+    requireOptionalText(value.errorCode, "errorCode");
+  } else {
+    throw new Error("Channel adapter message kind is invalid");
+  }
+  return value as unknown as ChannelAdapterMessage;
+}
+
+export function parseChannelAdapterResponse(frame: Buffer): ChannelAdapterResponse {
+  const value = parseObject(frame, "channel adapter response");
+  if (
+    value.schema !== CHANNEL_ADAPTER_PROTOCOL_SCHEMA ||
+    value.type !== "response" ||
+    !Number.isSafeInteger(value.sequence) ||
+    (value.outcome !== "accepted" && value.outcome !== "rejected") ||
+    !Number.isSafeInteger(value.revision)
+  ) {
+    throw new Error("Channel adapter response is invalid");
+  }
+  requirePositiveInteger(value.sequence, "channel response sequence");
+  requireNonNegativeInteger(value.revision, "channel response revision");
+  requireOptionalText(value.error, "channel response error");
+  validateCommand(value.command);
+  return value as unknown as ChannelAdapterResponse;
+}
+
+export function parseChannelAdapterLaunch(value: unknown): ChannelAdapterLaunch {
+  const launch = requireObject(value, "channel adapter launch envelope");
+  if (launch.schema !== "pi-workflows.channel-adapter-launch.v1") {
+    throw new Error("Channel adapter launch envelope is invalid");
+  }
+  requireText(launch.adapterEpoch, "adapterEpoch");
+  requireText(launch.profile, "profile");
+  requireText(launch.token, "token");
+  requireStringArray(launch.allowedUserIds, "allowedUserIds");
+  requireStringArray(launch.allowedChatIds, "allowedChatIds");
+  requireOptionalText(launch.apiBase, "apiBase");
+  return launch as ChannelAdapterLaunch;
+}
+
+export function channelResponse(
+  message: ChannelAdapterMessage,
+  outcome: ChannelAdapterResponse["outcome"],
+  revision: number,
+  command: ChannelAdapterCommand | null,
+  error?: string,
+): ChannelAdapterResponse {
+  return {
+    schema: CHANNEL_ADAPTER_PROTOCOL_SCHEMA,
+    type: "response",
+    sequence: message.sequence,
+    outcome,
+    revision,
+    command,
+    ...(error === undefined ? {} : { error }),
+  };
+}
+
+export function channelStableMessageId(parts: readonly string[]): string {
+  return `channel-${createHash("sha256").update(parts.join("\0")).digest("hex")}`;
+}
+
+function requireBase(value: Record<string, unknown>): void {
+  if (value.schema !== CHANNEL_ADAPTER_PROTOCOL_SCHEMA) {
+    throw new Error("Channel adapter message is invalid");
+  }
+  requireText(value.adapterEpoch, "adapterEpoch");
+  requireText(value.profile, "profile");
+  requirePositiveInteger(value.sequence, "channel sequence");
+  requireNonNegativeInteger(value.expectedRevision, "channel expected revision");
+  requireText(value.stableMessageId, "stableMessageId");
+}
+
+function validateCommand(value: unknown): void {
+  if (value === null) return;
+  const command = requireObject(value, "channel command");
+  if (command.kind === "channel.stop") return;
+  if (command.kind === "channel.present") {
+    requireText(command.stableMessageId, "stableMessageId");
+    requireText(command.attemptId, "attemptId");
+    validateChannelRequest(command.request);
+    return;
+  }
+  if (command.kind === "channel.settle") {
+    requireText(command.stableMessageId, "stableMessageId");
+    requireText(command.attemptId, "attemptId");
+    validateChannelRequest(command.request);
+    requireOneOf(command.outcome, ["accepted", "cancelled", "expired"], "settlement outcome");
+    if (command.response !== undefined) validateDecisionResponse(command.response);
+    if (!Array.isArray(command.messages)) throw new Error("Channel message references are invalid");
+    command.messages.forEach(validateMessageReference);
+    return;
+  }
+  if (command.kind === "channel.poll") {
+    requireNonNegativeInteger(command.cursor, "channel cursor");
+    if (!Array.isArray(command.requests)) throw new Error("Channel poll requests are invalid");
+    command.requests.forEach(validateChannelRequest);
+    return;
+  }
+  throw new Error("Channel adapter command kind is invalid");
+}
+
+function validateChannelRequest(value: unknown): void {
+  const request = requireObject(value, "human decision channel request");
+  if (
+    request.schema !== "pi-workflows.human-decision-channel-request.v1" ||
+    request.sourceSchema !== "pi-workflows.human-decision-request.v1" ||
+    Object.hasOwn(request, "subject")
+  ) {
+    throw new Error("Human decision channel request is invalid");
+  }
+  for (const field of [
+    "decisionId",
+    "requestDigest",
+    "runId",
+    "workflowName",
+    "nodeId",
+    "attemptId",
+    "audience",
+    "title",
+    "presentationDigest",
+    "createdAt",
+  ]) {
+    requireText(request[field], field);
+  }
+  requireNonNegativeInteger(request.revision, "decision revision");
+  requireObject(request.presentation, "decision presentation");
+  requireObject(request.choices, "decision choices");
+  requireOptionalText(request.expiresAt, "decision expiry");
+  if (request.defaultResponse !== undefined) validateDecisionResponse(request.defaultResponse);
+}
+
+function validateDecisionResponse(value: unknown): void {
+  const response = requireObject(value, "human decision response");
+  requireText(response.choice, "decision choice");
+  if (response.input === undefined) return;
+  const input = requireObject(response.input, "decision input");
+  if (Object.values(input).some((item) => typeof item !== "string")) {
+    throw new Error("Decision input values must be strings");
+  }
+}
+
+function validateMessageReference(value: unknown): void {
+  const reference = requireObject(value, "Telegram message reference");
+  requireText(reference.chatId, "Telegram chat ID");
+  requireText(reference.messageId, "Telegram message ID");
+  requireNonNegativeInteger(reference.recipientIndex, "Telegram recipient index");
+  requireNonNegativeInteger(reference.partIndex, "Telegram part index");
+  requireText(reference.contentDigest, "Telegram content digest");
+}
+
+function requireObject(value: unknown, label: string): Record<string, unknown> {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${label} must be an object`);
+  }
+  return value as Record<string, unknown>;
+}
+
+function requireText(value: unknown, label: string): asserts value is string {
+  if (typeof value !== "string" || value.length === 0) throw new Error(`${label} is invalid`);
+}
+
+function requireOptionalText(value: unknown, label: string): void {
+  if (value !== undefined) requireText(value, label);
+}
+
+function requirePositiveInteger(value: unknown, label: string): void {
+  if (!Number.isSafeInteger(value) || (value as number) <= 0)
+    throw new Error(`${label} is invalid`);
+}
+
+function requireNonNegativeInteger(value: unknown, label: string): void {
+  if (!Number.isSafeInteger(value) || (value as number) < 0) throw new Error(`${label} is invalid`);
+}
+
+function requireStringArray(value: unknown, label: string): asserts value is string[] {
+  if (
+    !Array.isArray(value) ||
+    value.length === 0 ||
+    value.some((item) => typeof item !== "string" || item.length === 0)
+  ) {
+    throw new Error(`${label} is invalid`);
+  }
+}
+
+function requireOneOf(value: unknown, allowed: readonly string[], label: string): void {
+  if (typeof value !== "string" || !allowed.includes(value)) throw new Error(`${label} is invalid`);
+}
+
+function parseObject(frame: Buffer, label: string): Record<string, unknown> {
+  let value: JsonValue;
+  try {
+    value = JSON.parse(frame.toString("utf8")) as JsonValue;
+  } catch {
+    throw new Error(`${label} is not valid JSON`);
+  }
+  return requireObject(value, label);
+}

package/src/channels/telegram.ts

@@ -0,0 +1,335 @@
+import { createHmac } from "node:crypto";
+import { decisionDocumentSegments, digestCanonical } from "../workflows/decision-presentation.js";
+import type { HumanDecisionChannelRequest, HumanDecisionResponse } from "../workflows/types.js";
+import type { TelegramFetch } from "./config.js";
+import type { TelegramMessageReference } from "./protocol.js";
+
+const DEFAULT_API_BASE = "https://api.telegram.org";
+const TELEGRAM_TEXT_LIMIT = 4_096;
+const CALLBACK_PREFIX = "pw:";
+const REPLY_TOKEN_PREFIX = "Reply token: ";
+
+export type TelegramVerifiedAnswer = {
+  request: HumanDecisionChannelRequest;
+  response: HumanDecisionResponse;
+  actorId: string;
+  chatId: string;
+  eventId: string;
+  cursor: number;
+};
+
+export class TelegramAdapter {
+  private requests: HumanDecisionChannelRequest[] = [];
+  private readonly allowedUsers: Set<string>;
+  private readonly allowedChats: Set<string>;
+  private readonly request: TelegramFetch;
+
+  constructor(
+    private readonly options: {
+      profile: string;
+      token: string;
+      allowedUserIds: readonly string[];
+      allowedChatIds: readonly string[];
+      fetchFn?: TelegramFetch;
+      apiBase?: string;
+    },
+  ) {
+    this.allowedUsers = new Set(options.allowedUserIds);
+    this.allowedChats = new Set(options.allowedChatIds);
+    this.request = options.fetchFn ?? (fetch as TelegramFetch);
+  }
+
+  setRequests(requests: readonly HumanDecisionChannelRequest[]): void {
+    this.requests = [...requests];
+  }
+
+  async present(request: HumanDecisionChannelRequest): Promise<TelegramMessageReference[]> {
+    const parts = renderTelegramParts(request);
+    const references: TelegramMessageReference[] = [];
+    const keyboard = this.keyboard(request);
+    for (const [recipientIndex, chatId] of [...this.allowedChats].entries()) {
+      for (const [partIndex, text] of parts.entries()) {
+        const result = await this.call("sendMessage", {
+          chat_id: chatId,
+          text,
+          ...(partIndex === parts.length - 1
+            ? { reply_markup: { inline_keyboard: keyboard } }
+            : {}),
+        });
+        const messageId = integerField(result, "message_id", "Telegram sendMessage result");
+        references.push({
+          chatId,
+          messageId: String(messageId),
+          recipientIndex,
+          partIndex,
+          contentDigest: digestCanonical(text),
+        });
+      }
+    }
+    return references;
+  }
+
+  async poll(cursor: number): Promise<{ cursor: number; answers: TelegramVerifiedAnswer[] }> {
+    const result = await this.call("getUpdates", {
+      offset: cursor,
+      timeout: 1,
+      allowed_updates: ["callback_query", "message"],
+    });
+    if (!Array.isArray(result)) throw new Error("Telegram getUpdates result must be an array");
+    let nextCursor = cursor;
+    const answers: TelegramVerifiedAnswer[] = [];
+    for (const raw of result) {
+      const update = asRecord(raw);
+      if (update === null || !Number.isSafeInteger(update.update_id)) continue;
+      const updateId = update.update_id as number;
+      nextCursor = Math.max(nextCursor, updateId + 1);
+      const answer = await this.handleUpdate(update, updateId + 1);
+      if (answer !== undefined) answers.push(answer);
+    }
+    return { cursor: nextCursor, answers };
+  }
+
+  async settle(
+    outcome: "accepted" | "cancelled" | "expired",
+    response: HumanDecisionResponse | undefined,
+    messages: readonly TelegramMessageReference[],
+  ): Promise<void> {
+    const seenChats = new Set<string>();
+    for (const message of messages) {
+      await this.call("editMessageReplyMarkup", {
+        chat_id: message.chatId,
+        message_id: Number.parseInt(message.messageId, 10),
+        reply_markup: { inline_keyboard: [] },
+      });
+      if (seenChats.has(message.chatId)) continue;
+      seenChats.add(message.chatId);
+      const selection = response?.choice === undefined ? "" : ` (${response.choice})`;
+      await this.call("sendMessage", {
+        chat_id: message.chatId,
+        text: `Decision ${outcome}${selection}.`,
+      });
+    }
+  }
+
+  private async handleUpdate(
+    update: Record<string, unknown>,
+    cursor: number,
+  ): Promise<TelegramVerifiedAnswer | undefined> {
+    const callback = asRecord(update.callback_query);
+    if (callback !== null) return await this.handleCallback(callback, cursor);
+    const message = asRecord(update.message);
+    if (message !== null) return await this.handleReply(message, cursor);
+    return undefined;
+  }
+
+  private async handleCallback(
+    callback: Record<string, unknown>,
+    cursor: number,
+  ): Promise<TelegramVerifiedAnswer | undefined> {
+    const callbackId = stringField(callback, "id");
+    const actor = asRecord(callback.from);
+    const message = asRecord(callback.message);
+    const chat = asRecord(message?.chat);
+    const actorId = numericText(actor?.id);
+    const chatId = numericText(chat?.id);
+    const data = typeof callback.data === "string" ? callback.data : "";
+    if (
+      callbackId === undefined ||
+      actorId === undefined ||
+      chatId === undefined ||
+      !this.allowedUsers.has(actorId) ||
+      !this.allowedChats.has(chatId)
+    ) {
+      if (callbackId !== undefined) {
+        await this.answerCallback(callbackId, "This decision answer is not authorized.");
+      }
+      return undefined;
+    }
+    const binding = this.callbackBinding(data);
+    if (binding === undefined) {
+      await this.answerCallback(callbackId, "This decision choice is no longer active.");
+      return undefined;
+    }
+    const choice = binding.request.choices[binding.choice];
+    if (choice === undefined) return undefined;
+    if (choice.input !== undefined) {
+      const token = this.replyToken(binding.request, binding.choice);
+      await this.call("sendMessage", {
+        chat_id: chatId,
+        text: `${choice.input.prompt}\n${REPLY_TOKEN_PREFIX}${token}`,
+        reply_markup: { force_reply: true, selective: true },
+      });
+      await this.answerCallback(callbackId, "Reply to the new prompt.");
+      return undefined;
+    }
+    await this.answerCallback(callbackId, "Answer received.");
+    return {
+      request: binding.request,
+      response: { choice: binding.choice },
+      actorId,
+      chatId,
+      eventId: callbackId,
+      cursor,
+    };
+  }
+
+  private async handleReply(
+    message: Record<string, unknown>,
+    cursor: number,
+  ): Promise<TelegramVerifiedAnswer | undefined> {
+    const actorId = numericText(asRecord(message.from)?.id);
+    const chatId = numericText(asRecord(message.chat)?.id);
+    const text = typeof message.text === "string" ? message.text.trim() : "";
+    const replyText = asRecord(message.reply_to_message)?.text;
+    const eventId = numericText(message.message_id);
+    if (
+      actorId === undefined ||
+      chatId === undefined ||
+      eventId === undefined ||
+      text.length === 0 ||
+      typeof replyText !== "string" ||
+      !this.allowedUsers.has(actorId) ||
+      !this.allowedChats.has(chatId)
+    ) {
+      return undefined;
+    }
+    const marker = replyText.lastIndexOf(REPLY_TOKEN_PREFIX);
+    if (marker < 0) return undefined;
+    const token = replyText
+      .slice(marker + REPLY_TOKEN_PREFIX.length)
+      .trim()
+      .split(/\s/u)[0];
+    if (token === undefined) return undefined;
+    const binding = this.replyBinding(token);
+    if (binding === undefined) return undefined;
+    const choice = binding.request.choices[binding.choice];
+    if (choice?.input === undefined) return undefined;
+    return {
+      request: binding.request,
+      response: { choice: binding.choice, input: { [choice.input.name]: text } },
+      actorId,
+      chatId,
+      eventId,
+      cursor,
+    };
+  }
+
+  private keyboard(request: HumanDecisionChannelRequest): Array<Array<Record<string, string>>> {
+    return Object.entries(request.choices).map(([choice, definition]) => [
+      {
+        text: definition.label,
+        callback_data: `${CALLBACK_PREFIX}${this.callbackToken(request, choice)}`,
+      },
+    ]);
+  }
+
+  private callbackBinding(
+    data: string,
+  ): { request: HumanDecisionChannelRequest; choice: string } | undefined {
+    if (!data.startsWith(CALLBACK_PREFIX)) return undefined;
+    const token = data.slice(CALLBACK_PREFIX.length);
+    for (const request of this.requests) {
+      for (const choice of Object.keys(request.choices)) {
+        if (this.callbackToken(request, choice) === token) return { request, choice };
+      }
+    }
+    return undefined;
+  }
+
+  private replyBinding(
+    token: string,
+  ): { request: HumanDecisionChannelRequest; choice: string } | undefined {
+    for (const request of this.requests) {
+      for (const [choice, definition] of Object.entries(request.choices)) {
+        if (definition.input !== undefined && this.replyToken(request, choice) === token) {
+          return { request, choice };
+        }
+      }
+    }
+    return undefined;
+  }
+
+  private callbackToken(request: HumanDecisionChannelRequest, choice: string): string {
+    return this.token("callback", request, choice);
+  }
+
+  private replyToken(request: HumanDecisionChannelRequest, choice: string): string {
+    return this.token("reply", request, choice);
+  }
+
+  private token(
+    purpose: "callback" | "reply",
+    request: HumanDecisionChannelRequest,
+    choice: string,
+  ): string {
+    return createHmac("sha256", this.options.token)
+      .update(`${purpose}\0${this.options.profile}\0${request.requestDigest}\0${choice}`)
+      .digest("base64url")
+      .slice(0, 32);
+  }
+
+  private async answerCallback(callbackQueryId: string, text: string): Promise<void> {
+    await this.call("answerCallbackQuery", { callback_query_id: callbackQueryId, text });
+  }
+
+  private async call(method: string, payload: Record<string, unknown>): Promise<unknown> {
+    const apiBase = this.options.apiBase ?? DEFAULT_API_BASE;
+    const response = await this.request(
+      `${apiBase}/bot${encodeURIComponent(this.options.token)}/${method}`,
+      {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(payload),
+      },
+    );
+    if (!response.ok) throw new Error(`Telegram ${method} failed with HTTP ${response.status}`);
+    const body = asRecord(await response.json());
+    if (body?.ok !== true) throw new Error(`Telegram ${method} was rejected`);
+    return body.result;
+  }
+}
+
+export function renderDecisionText(request: HumanDecisionChannelRequest): string {
+  return decisionDocumentSegments(request)
+    .map((segment) => segment.text)
+    .join("\n\n");
+}
+
+export function renderTelegramParts(request: HumanDecisionChannelRequest): string[] {
+  const text = renderDecisionText(request);
+  if (text.length <= TELEGRAM_TEXT_LIMIT) return [text];
+  const parts: string[] = [];
+  let remaining = text;
+  while (remaining.length > TELEGRAM_TEXT_LIMIT) {
+    const window = remaining.slice(0, TELEGRAM_TEXT_LIMIT);
+    const boundary = Math.max(window.lastIndexOf("\n\n"), window.lastIndexOf("\n"));
+    const cut = boundary > TELEGRAM_TEXT_LIMIT / 2 ? boundary : TELEGRAM_TEXT_LIMIT;
+    parts.push(remaining.slice(0, cut));
+    remaining = remaining.slice(cut).replace(/^\n+/u, "");
+  }
+  if (remaining.length > 0) parts.push(remaining);
+  return parts;
+}
+
+function integerField(value: unknown, field: string, label: string): number {
+  const record = asRecord(value);
+  const result = record?.[field];
+  if (!Number.isSafeInteger(result)) throw new Error(`${label} ${field} must be an integer`);
+  return result as number;
+}
+
+function stringField(value: Record<string, unknown>, field: string): string | undefined {
+  return typeof value[field] === "string" ? (value[field] as string) : undefined;
+}
+
+function numericText(value: unknown): string | undefined {
+  if (typeof value === "number" && Number.isSafeInteger(value)) return String(value);
+  if (typeof value === "string" && /^-?[0-9]+$/u.test(value)) return value;
+  return undefined;
+}
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : null;
+}

package/src/client/client.ts

@@ -182,12 +182,16 @@ export class WorkflowClient {
   async watchSession(
     sessionId: string,
     listener: (event: ClientEvent) => void,
-    options: { subscriptionId?: string } = {},
+    options: { subscriptionId?: string; coordinator?: boolean } = {},
   ): Promise<() => Promise<void>> {
     return await this.subscribe(
       "view.session.watch",
       undefined,
-      { subscriptionId: options.subscriptionId ?? randomUUID(), sessionId },
+      {
+        subscriptionId: options.subscriptionId ?? randomUUID(),
+        sessionId,
+        ...(options.coordinator === undefined ? {} : { coordinator: options.coordinator }),
+      },
       listener,
     );
   }

package/src/client/index.ts

@@ -15,10 +15,11 @@ export {
   type ClientResponse,
 } from "./protocol.js";
 export type {
-  OriginActivityReport,
+  WorkflowBranchReport,
   WorkflowDisplay,
   WorkflowDisplayStatus,
   WorkflowRunSummary,
   WorkflowRunView,
   WorkflowSessionView,
+  WorkflowTurnReport,
 } from "./view.js";