@vellumai/assistant 0.11.6 → 0.11.7-staging.2

package/src/notifications/adapters/telegram.ts

@@ -23,7 +23,7 @@ import type {
   DeliveryResult,
   NotificationChannel,
 } from "../types.js";
-import { resolveMessageText } from "./shared.js";
+import { appendPlainTextFallback, resolveMessageText } from "./shared.js";
 
 const log = getLogger("notif-adapter-telegram");
 
@@ -74,13 +74,10 @@ export class TelegramAdapter implements ChannelAdapter {
 
       // When falling back from rich delivery, append the plain-text
       // instructions so the guardian still knows how to approve/reject.
-      const fallbackText =
-        approval?.plainTextFallback &&
-        !messageText.includes(approval.plainTextFallback)
-          ? `${messageText}\n\n${approval.plainTextFallback}`
-          : messageText;
-
-      const sent = await sendTelegramReply(chatId, fallbackText);
+      const sent = await sendTelegramReply(
+        chatId,
+        appendPlainTextFallback(messageText, approval),
+      );
 
       log.info(
         { sourceEventName: payload.sourceEventName, chatId },

package/src/notifications/approval-card-data.ts

@@ -29,11 +29,13 @@ import {
 } from "./approval-card-builder.js";
 import {
   buildGuardianRequestCodeInstruction,
+  buildQuestionDeliveryText,
   buildToolApprovalSourceView,
   type GuardianQuestionPayload,
   type LenientToolApprovalPayload,
   LenientToolApprovalPayloadSchema,
   parseGuardianQuestionPayload,
+  type PendingQuestionGuardianPayload,
   resolveGuardianInstructionModeFromFields,
   resolveGuardianInstructionModeFromPayload,
 } from "./guardian-question-mode.js";
@@ -122,12 +124,21 @@ export interface ToolApprovalCardData {
   card: ApprovalCardParams;
 }
 
+/** Resolved card data for an `ask_question` prompt awaiting an answer. */
+export interface QuestionCardData {
+  kind: "question";
+  card: ApprovalCardParams;
+}
+
 /**
  * Channel-agnostic approval card content, resolved once from `contextPayload`.
  * The discriminant `kind` lets consumers branch on the approval type without
  * re-parsing the payload.
  */
-export type ApprovalCardData = AccessRequestCardData | ToolApprovalCardData;
+export type ApprovalCardData =
+  | AccessRequestCardData
+  | ToolApprovalCardData
+  | QuestionCardData;
 
 // ── Shared source rendering ──────────────────────────────────────────────────
 
@@ -335,6 +346,65 @@ function extractToolApprovalCard(
   };
 }
 
+/**
+ * Shape a parked `ask_question` prompt into card params.
+ *
+ * The question itself is the subject, so it leads; the options become the
+ * card's actions under the index-based token scheme the resolver maps back to
+ * the pending interaction, plus an explicit skip. Channels without buttons get
+ * the same options enumerated in `fallbackText`, so the answer is reachable by
+ * a request-code reply on a channel that can only carry text.
+ */
+function extractQuestionCard(
+  p: PendingQuestionGuardianPayload,
+): ApprovalCardParams {
+  const metadata: Array<{ label: string; value: string }> = [];
+  const sourceView = buildToolApprovalSourceView(p);
+  const sourceRow = sourceMetadataRow(
+    nonEmpty(p.sourceChannel),
+    sourceView?.chatId,
+    sourceView?.isSlackDm ?? false,
+  );
+  if (sourceRow) {
+    metadata.push(sourceRow);
+  }
+
+  const options = p.options ?? [];
+  const bodyParts: string[] = [];
+  if (options.length > 0) {
+    bodyParts.push(
+      options
+        .map((option, index) => `${index + 1}. ${option.label}`)
+        .join("\n"),
+    );
+  }
+  if (sourceView?.permalink) {
+    bodyParts.push(viewMessageLine(sourceView.permalink));
+  }
+
+  return {
+    // Deliberately the tool-approval prefix rather than one of its own: the
+    // withdrawal path recomputes a card's surface id from the request kind,
+    // and `pending_question` already maps here. A new prefix would orphan
+    // every question card written before it.
+    surfaceIdPrefix: TOOL_APPROVAL_SURFACE_PREFIX,
+    cardTitle: "Question",
+    primaryLine: p.questionText,
+    subtitle: "Waiting on your answer",
+    body: bodyParts.join("\n\n"),
+    metadata,
+    requestId: nonEmpty(p.requestId),
+    // Empty rather than absent, and empty rather than the answer options.
+    // Absent means the generic Approve/Reject pair, which is the wrong verb
+    // for a question. The options themselves are not offered here because the
+    // in-app surface route resolves only approval actions, so an `answer_`
+    // button on this card would be inert; channel buttons come from the
+    // broadcaster, whose taps the guardian reply router does resolve.
+    actions: [],
+    fallbackText: buildQuestionDeliveryText(p),
+  };
+}
+
 /**
  * Resolve a guardian.question payload into tool-approval card params, or
  * `null` when it does not represent a tool approval.
@@ -343,6 +413,21 @@ function extractToolApprovalCard(
  * to lenient field extraction so cards still render when optional fields are
  * absent.
  */
+function resolveQuestionCard(
+  payload: Record<string, unknown>,
+): ApprovalCardParams | null {
+  const parsed = parseGuardianQuestionPayload(payload);
+  if (!parsed || parsed.requestKind !== "pending_question") {
+    return null;
+  }
+  // A `pending_question` carrying a tool name is a tool approval wearing the
+  // question kind, and the mode table says so; leave it to the approval card.
+  if (resolveGuardianInstructionModeFromPayload(parsed).mode !== "answer") {
+    return null;
+  }
+  return extractQuestionCard(parsed);
+}
+
 function resolveToolApprovalCard(
   payload: Record<string, unknown>,
 ): ApprovalCardParams | null {
@@ -388,6 +473,14 @@ export function resolveApprovalCardData(
   }
 
   if (sourceEventName === "guardian.question") {
+    // Both kinds arrive under this one event, split by instruction mode: a
+    // question is asked, an approval is granted, and the tool-approval
+    // resolver accepts only `approval`. Ask about the question first, since a
+    // `pending_question` carrying a tool name is an approval either way.
+    const question = resolveQuestionCard(contextPayload);
+    if (question) {
+      return { kind: "question", card: question };
+    }
     const card = resolveToolApprovalCard(contextPayload);
     return card ? { kind: "tool_approval", card } : null;
   }

package/src/notifications/background-failure-signal.ts

@@ -0,0 +1,116 @@
+import type { BackgroundJobErrorKind } from "../runtime/background-job-runner.js";
+import { getLogger } from "../util/logger.js";
+import { activityFailedDedupeKey } from "./activity-failed-dedupe.js";
+import { emitNotificationSignal } from "./emit-signal.js";
+import type { NotificationSourceChannel } from "./signal.js";
+
+const log = getLogger("background-failure-signal");
+
+/**
+ * One background failure, as a producer reports it.
+ *
+ * The classification fields are the authored attribution carried out of the
+ * failing turn (`TurnFailure`): `failureSummary` is the classifier's
+ * user-facing message, and `profileName`/`connectionName` name the route the
+ * call actually resolved. Producers whose failures never ran a turn (a
+ * timeout, a bootstrap crash, a data job's own exception) leave them unset
+ * and the signal degrades to the classified kind.
+ */
+export interface BackgroundFailureReport {
+  /** Stable job identifier for logs and per-job dedupe, e.g. `heartbeat`. */
+  jobName: string;
+  /** Human-facing job label for notification copy. Defaults to `jobName`. */
+  displayName?: string;
+  sourceChannel: NotificationSourceChannel;
+  /** Conversation or job id the notification links back to. */
+  sourceContextId: string;
+  errorKind: BackgroundJobErrorKind;
+  /** Raw error text, carried for debugging; copy prefers `failureSummary`. */
+  errorMessage: string;
+  /** Stable classified code (`ConversationErrorCode`), when classified. */
+  failureCode?: string;
+  /** The classification's authored user-facing message, when carried. */
+  failureSummary?: string;
+  /** The classification's machine-readable category, when carried. */
+  errorCategory?: string;
+  /**
+   * Connection row the failing call resolved, when carried. The most precise
+   * route identity, so it leads the dedupe-scope hierarchy.
+   */
+  connectionName?: string;
+  /** Profile key the failing call resolved, when carried. */
+  profileName?: string;
+  /**
+   * Recomputed single-route profile key (see `resolveSingleRouteProfileKey`).
+   * Used only when the failure carries no attribution of its own.
+   */
+  fallbackProviderScope?: string;
+}
+
+/**
+ * The single emission seam for background-job failure notifications.
+ *
+ * Owns the payload shape, the dedupe-key derivation, and the attention hints
+ * so every producer (the background-job runner, the scheduler's
+ * retries-exhausted alert, standalone data jobs) reports the same way and a
+ * new producer cannot invent a divergent one. Fire-and-forget: emission
+ * errors are logged, never thrown, because a notification failure must not
+ * break the job path that reports it.
+ *
+ * The dedupe scope is the most precise route identity the failure carries:
+ * the resolved connection, else the resolved profile, else the recomputed
+ * fallback. Failures carrying less precision can split an incident into an
+ * extra notification (never merge two incidents into one), and the split
+ * shrinks as more paths carry attribution.
+ */
+export function emitBackgroundFailureSignal(
+  report: BackgroundFailureReport,
+): void {
+  const providerScope =
+    report.connectionName ?? report.profileName ?? report.fallbackProviderScope;
+  emitNotificationSignal({
+    sourceChannel: report.sourceChannel,
+    sourceContextId: report.sourceContextId,
+    sourceEventName: "activity.failed",
+    dedupeKey: activityFailedDedupeKey({
+      jobName: report.jobName,
+      errorKind: report.errorKind,
+      ...(report.failureCode !== undefined
+        ? { failureCode: report.failureCode }
+        : {}),
+      ...(providerScope !== undefined ? { providerScope } : {}),
+    }),
+    contextPayload: {
+      jobName: report.displayName ?? report.jobName,
+      errorMessage: report.errorMessage,
+      errorKind: report.errorKind,
+      ...(report.failureCode !== undefined
+        ? { failureCode: report.failureCode }
+        : {}),
+      ...(report.failureSummary !== undefined
+        ? { failureSummary: report.failureSummary }
+        : {}),
+      ...(report.errorCategory !== undefined
+        ? { errorCategory: report.errorCategory }
+        : {}),
+      ...(report.connectionName !== undefined
+        ? { connectionName: report.connectionName }
+        : {}),
+    },
+    attentionHints: {
+      requiresAction: false,
+      urgency: "medium",
+      isAsyncBackground: true,
+      visibleInSourceNow: false,
+    },
+  }).catch((emitErr) => {
+    log.warn(
+      {
+        err: emitErr instanceof Error ? emitErr.message : String(emitErr),
+        jobName: report.jobName,
+        sourceContextId: report.sourceContextId,
+      },
+      "Failed to emit background-failure notification",
+    );
+  });
+}

package/src/notifications/broadcaster.ts

@@ -33,11 +33,10 @@ import {
 } from "./deliveries-store.js";
 import { resolveDestinations } from "./destination-resolver.js";
 import {
-  buildQuestionOptionActionId,
+  buildQuestionAnswerActions,
   buildToolApprovalSourceView,
   parseGuardianQuestionPayload,
   parseInteractiveApprovalPayload,
-  QUESTION_SKIP_ACTION_ID,
   resolveGuardianInstructionModeFromPayload,
   type ToolApprovalSourceView,
 } from "./guardian-question-mode.js";
@@ -188,14 +187,9 @@ function resolveQuestionOptionsContext(
   return {
     approval: {
       requestId,
-      actions: [
-        ...options.map((option, index) => ({
-          id: buildQuestionOptionActionId(index),
-          label: option.label,
-        })),
-        { id: QUESTION_SKIP_ACTION_ID, label: "Skip" },
-      ],
+      actions: buildQuestionAnswerActions(options),
       plainTextFallback: `Reply "${code} <your answer>".`,
+      intent: "question",
     },
   };
 }

package/src/notifications/copy-composer.ts

@@ -10,6 +10,7 @@
  */
 
 import { normalizeTitle } from "../util/short-title.js";
+import { truncate } from "../util/truncate.js";
 import {
   accessRequestCardTitle,
   buildAccessRequestContractText,
@@ -41,6 +42,33 @@ import type { NotificationChannel, RenderedChannelCopy } from "./types.js";
 
 type CopyTemplate = (payload: Record<string, unknown>) => RenderedChannelCopy;
 
+/**
+ * Failure prose for an `activity.failed` payload with no authored
+ * classification message. The classified kind supplies the readable part,
+ * and the raw error text is appended only when it reads as prose: a
+ * stack-shaped or constant-shaped message (PROVIDER_BILLING and friends)
+ * says nothing to the person reading the notification and never lands in
+ * the body.
+ */
+function describeUnclassifiedFailure(payload: Record<string, unknown>): string {
+  const kind = str(payload.errorKind, "exception");
+  const opening =
+    kind === "timeout"
+      ? "It ran out of time before finishing."
+      : kind === "model_provider"
+        ? "The model provider did not respond."
+        : "It stopped with an error.";
+  const raw =
+    typeof payload.errorMessage === "string"
+      ? payload.errorMessage.replace(/\s+/g, " ").trim()
+      : "";
+  const readable =
+    raw.length > 0 &&
+    raw.length <= 200 &&
+    !/[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)+/.test(raw);
+  return readable ? `${opening} ${raw}` : opening;
+}
+
 function str(value: unknown, fallback: string): string {
   if (typeof value === "string" && value.length > 0) {
     return value;
@@ -335,16 +363,21 @@ const TEMPLATES: Partial<Record<NotificationSourceEventName, CopyTemplate>> = {
 
   "activity.failed": (payload) => {
     const jobName = str(payload.jobName, "background job");
-    const errorKind = str(payload.errorKind, "exception");
-    const rawMessage =
-      typeof payload.errorMessage === "string"
-        ? payload.errorMessage
-        : "no message";
-    const truncated =
-      rawMessage.length > 200 ? rawMessage.slice(0, 200) + "…" : rawMessage;
+    // The classifier's authored user-facing message rides the payload as
+    // `failureSummary` when the failing turn carried its classification;
+    // it already says what happened and what to do about it.
+    // Authored messages are short by construction, but the classifier's
+    // fallback branches can embed provider error text, so bound the body
+    // like any other untrusted payload string.
+    const summary = truncate(
+      typeof payload.failureSummary === "string"
+        ? payload.failureSummary.trim()
+        : "",
+      300,
+    );
     return {
       title: `Background job failed: ${jobName}`,
-      body: `${errorKind}: ${truncated}`,
+      body: summary !== "" ? summary : describeUnclassifiedFailure(payload),
     };
   },
 

package/src/notifications/decision-engine.ts

@@ -48,8 +48,11 @@ import { composeFallbackCopy, resolveTitle } from "./copy-composer.js";
 import { createDecision } from "./decisions-store.js";
 import {
   buildGuardianRequestCodeInstruction,
+  buildQuestionDeliveryText,
   hasGuardianRequestCodeInstruction,
+  parseGuardianQuestionPayload,
   parseInteractiveApprovalPayload,
+  resolveGuardianInstructionModeFromPayload,
   resolveGuardianQuestionInstructionMode,
   stripConflictingGuardianRequestInstructions,
   stripGuardianRequestCodeInstructions,
@@ -744,6 +747,55 @@ function ensureSeedContentBlocks(
   };
 }
 
+/**
+ * Pin a question's channel text to the question itself.
+ *
+ * Every other notification's copy is composed here, and for most of them a
+ * paraphrase is an improvement. A question is the exception: the guardian is
+ * being asked to choose between these words, and the composed copy replaces
+ * `title` / `body` / `deliveryText` wholesale, so a summary of the question
+ * arrives where the question should be and the options never appear at all.
+ * Runs on every decision path for the same reason the seed-block guard does.
+ *
+ * Scoped to answer mode. A `pending_question` carrying a tool name is a voice
+ * tool approval, where composed copy is the right thing.
+ */
+function pinQuestionDeliveryCopy(
+  decision: NotificationDecision,
+  signal: NotificationSignal,
+): NotificationDecision {
+  if (signal.sourceEventName !== "guardian.question") {
+    return decision;
+  }
+  const parsed = parseGuardianQuestionPayload(signal.contextPayload);
+  if (
+    !parsed ||
+    parsed.requestKind !== "pending_question" ||
+    resolveGuardianInstructionModeFromPayload(parsed).mode !== "answer"
+  ) {
+    return decision;
+  }
+
+  const text = buildQuestionDeliveryText(parsed);
+  const nextCopy: Partial<Record<NotificationChannel, RenderedChannelCopy>> = {
+    ...decision.renderedCopy,
+  };
+  for (const channel of Object.keys(nextCopy) as NotificationChannel[]) {
+    const copy = nextCopy[channel];
+    if (!copy) {
+      continue;
+    }
+    nextCopy[channel] = {
+      ...copy,
+      body: text,
+      deliveryText: text,
+      conversationSeedMessage: text,
+    };
+  }
+
+  return { ...decision, renderedCopy: nextCopy };
+}
+
 /**
  * Tool-approval and tool-grant notifications need a Surface card with
  * Approve/Reject buttons on all decision paths.
@@ -943,6 +995,7 @@ function buildPassThroughDecision(params: {
   };
   decision = enforceGuardianRequestCode(decision, signal);
   decision = enforceToolApprovalSeedBlocks(decision, signal);
+  decision = pinQuestionDeliveryCopy(decision, signal);
   decision = enforceAccessRequestInstructions(decision, signal);
   decision = enforceGuardianRequestConversationAffinity(decision, signal);
   decision = enforceConversationAffinity(
@@ -1068,6 +1121,7 @@ export async function evaluateSignal(
     let decision = buildFallbackDecision(signal, availableChannels);
     decision = enforceGuardianRequestCode(decision, signal);
     decision = enforceToolApprovalSeedBlocks(decision, signal);
+    decision = pinQuestionDeliveryCopy(decision, signal);
     decision = enforceAccessRequestInstructions(decision, signal);
     decision = enforceGuardianRequestConversationAffinity(decision, signal);
     decision = enforceConversationAffinity(
@@ -1098,6 +1152,7 @@ export async function evaluateSignal(
 
   decision = enforceGuardianRequestCode(decision, signal);
   decision = enforceToolApprovalSeedBlocks(decision, signal);
+  decision = pinQuestionDeliveryCopy(decision, signal);
   decision = enforceAccessRequestInstructions(decision, signal);
   decision = enforceGuardianRequestConversationAffinity(decision, signal);
   decision = enforceConversationAffinity(

package/src/notifications/destination-resolver.ts

@@ -66,10 +66,9 @@ export function resolveDestinations(
       continue;
     }
 
-    // After the deliverability check, `channel` is guaranteed to be a
-    // NotificationChannel — TypeScript cannot infer this from the runtime
-    // guard, so we narrow with a switch over known deliverable values.
-    switch (channel as NotificationChannel) {
+    // `isNotificationDeliverable` is a type predicate, so past this point
+    // `channel` is a NotificationChannel and the switch below is exhaustive.
+    switch (channel) {
       case "vellum": {
         // Vellum delivery is local — no external endpoint required.
         // Include the guardianPrincipalId so the adapter can annotate
@@ -155,6 +154,44 @@ export function resolveDestinations(
         );
         break;
       }
+      case "discord": {
+        const guardian = resolveGuardian(guardians, "discord");
+        // The endpoint is the guardian's user snowflake: the person, never a
+        // stored room id. User and channel snowflakes are indistinguishable
+        // bare numbers, so the adapter resolves the DM channel from the
+        // person at send time and a guild room can never become a delivery
+        // target. The binding context reuses the conversation the guardian
+        // verified in, which the verification intercept scopes to the DM
+        // lane; delivery stays DM-safe regardless, since it never reads
+        // this id.
+        if (guardian?.address) {
+          result.set("discord", {
+            channel: "discord",
+            endpoint: guardian.address,
+            metadata: {
+              externalUserId: guardian.address,
+            },
+            ...(guardian.externalChatId
+              ? {
+                  bindingContext: {
+                    sourceChannel: "discord" as const,
+                    externalChatId: guardian.externalChatId,
+                    externalUserId: guardian.address,
+                  },
+                }
+              : {}),
+          });
+        }
+        log.debug(
+          {
+            channel: "discord",
+            source: "guardian-delivery",
+            hasEndpoint: !!guardian?.address,
+          },
+          "destination resolved",
+        );
+        break;
+      }
       case "platform": {
         // Platform delivery goes through the daemon's VellumPlatformClient —
         // no external binding needed. Include guardianPrincipalId so the
@@ -180,7 +217,10 @@ export function resolveDestinations(
         break;
       }
       default: {
-        // Future deliverable channels without a resolver — skip silently.
+        // Exhaustive over NotificationChannel: a channel whose policy turns
+        // deliveryEnabled on must answer addressing here at compile time,
+        // because a silent skip is how a half-wired channel disappears.
+        channel satisfies never;
         break;
       }
     }

package/src/notifications/emit-signal.ts

@@ -22,6 +22,7 @@ import { isPlatformClientConfigured } from "../platform/client.js";
 import { broadcastMessage } from "../runtime/assistant-event-hub.js";
 import { getLogger } from "../util/logger.js";
 import { withSqliteRetry } from "../util/sqlite-retry.js";
+import { DiscordAdapter } from "./adapters/discord.js";
 import { VellumAdapter } from "./adapters/macos.js";
 import { PlatformPushAdapter } from "./adapters/platform.js";
 import { SlackAdapter } from "./adapters/slack.js";
@@ -64,6 +65,7 @@ export function getBroadcaster(): NotificationBroadcaster {
       new VellumAdapter(broadcastMessage),
       new TelegramAdapter(),
       new SlackAdapter(),
+      new DiscordAdapter(),
       new PlatformPushAdapter(),
     ]);
 
@@ -117,9 +119,6 @@ export async function getConnectedChannels(): Promise<NotificationChannel[]> {
   // unreachable, so binding-based connectivity falls back to the local read.
   const guardians = await getGuardianDelivery();
 
-  // getDeliverableChannels() returns ChannelId[] but every returned channel
-  // has deliveryEnabled: true, making it a valid NotificationChannel at
-  // runtime. We iterate over the broad type and narrow via the switch.
   for (const channel of getDeliverableChannels()) {
     switch (channel) {
       case "vellum":
@@ -153,9 +152,24 @@ export async function getConnectedChannels(): Promise<NotificationChannel[]> {
         }
         break;
       }
+      case "discord": {
+        // Connected when a verified guardian binding names a user to DM,
+        // mirroring destination-resolver: the person is the endpoint, and
+        // the adapter resolves the DM channel from them at send time.
+        const guardian = guardians
+          ? guardianForChannel(guardians, channel)
+          : undefined;
+        if (guardian?.address) {
+          channels.push(channel);
+        }
+        break;
+      }
       default:
-        // Future deliverable channels — skip until a connectivity check
-        // is implemented for them.
+        // Exhaustive over NotificationChannel: a channel whose policy turns
+        // deliveryEnabled on must answer connectivity here at compile time.
+        // A silent skip is how a half-wired channel disappears without a
+        // trace, so the compiler holds the door instead.
+        channel satisfies never;
         break;
     }
   }

package/src/notifications/guardian-question-mode.ts

@@ -250,6 +250,63 @@ export function buildQuestionOptionActionId(index: number): string {
   return `answer_${index}`;
 }
 
+/**
+ * The full answer action set for a question's options: one action per option
+ * in the interaction's own order, then an explicit skip.
+ *
+ * Shared because a question is rendered twice from the same options, once as
+ * an approval-metadata action set for a channel transport and once as card
+ * actions on the in-app surface, and the two must agree: the resolver maps
+ * the index back to the pending interaction, so a divergence answers the
+ * wrong option rather than failing.
+ */
+/**
+ * The message text for a question that must be answered: the question, its
+ * options numbered as they are ordered, and how to reply by reference code.
+ *
+ * Deterministic on purpose. A notification's channel copy is otherwise
+ * composed by the decision engine, and a question is the one payload that
+ * cannot survive being paraphrased: the guardian is being asked to choose
+ * between these words, so the words have to arrive.
+ */
+export function buildQuestionDeliveryText(p: {
+  questionText: string;
+  requestCode?: string;
+  options?: readonly { label: string }[];
+}): string {
+  const parts = [p.questionText];
+  const options = p.options ?? [];
+  if (options.length > 0) {
+    parts.push(
+      options
+        .map((option, index) => `${index + 1}. ${option.label}`)
+        .join("\n"),
+    );
+  }
+  const requestCode = p.requestCode?.trim();
+  if (requestCode) {
+    parts.push(
+      buildGuardianRequestCodeInstruction(requestCode.toUpperCase(), "answer"),
+    );
+  }
+  return parts.join("\n\n");
+}
+
+export function buildQuestionAnswerActions(
+  options: readonly { label: string }[],
+): Array<{ id: string; label: string }> {
+  if (options.length === 0) {
+    return [];
+  }
+  return [
+    ...options.map((option, index) => ({
+      id: buildQuestionOptionActionId(index),
+      label: option.label,
+    })),
+    { id: QUESTION_SKIP_ACTION_ID, label: "Skip" },
+  ];
+}
+
 export type QuestionAnswerSelection =
   | { kind: "option"; index: number }
   | { kind: "skip" };