@vellumai/assistant 0.10.12 → 0.11.0-staging.1

package/src/permissions/question-guardian-request.test.ts

@@ -0,0 +1,222 @@
+/**
+ * Tests for the ask_question → guardian-request promotion gating
+ * (`question-guardian-request.ts`): promotes only single-question batches
+ * asked by the guardian on a card-capable channel, reconciles a prompt that
+ * resolved before the row landed, and never throws.
+ */
+
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+import type { QuestionRequestEvent } from "../api/events/question-request.js";
+
+const createGuardianRequestMock = mock(
+  (params: Record<string, unknown>): Promise<Record<string, unknown>> =>
+    Promise.resolve({ ...params, requestCode: "ABC123" }),
+);
+const expireGuardianRequestMock = mock((_id: string) => Promise.resolve());
+const bridgeMock = mock((_params: Record<string, unknown>) =>
+  Promise.resolve({ bridged: true as const, signalId: "req-1" }),
+);
+const withdrawCardsMock = mock((_params: Record<string, unknown>) =>
+  Promise.resolve(),
+);
+
+let trustContext: Record<string, unknown> | undefined;
+let pendingInteraction: { kind: string } | undefined;
+let rowAfterExpire: Record<string, unknown> | null = null;
+
+mock.module("../daemon/conversation-registry.js", () => ({
+  findConversation: (_id: string) =>
+    trustContext ? { trustContext, assistantId: "self" } : undefined,
+}));
+mock.module("../channels/gateway-guardian-requests.js", () => ({
+  createGuardianRequest: (params: Record<string, unknown>) =>
+    createGuardianRequestMock(params),
+  expireGuardianRequest: (id: string) => expireGuardianRequestMock(id),
+  getGuardianRequestOrNull: (_id: string) => Promise.resolve(rowAfterExpire),
+}));
+mock.module("../approvals/guardian-card-withdrawal.js", () => ({
+  withdrawGuardianRequestCards: (params: Record<string, unknown>) =>
+    withdrawCardsMock(params),
+}));
+mock.module("../runtime/question-request-guardian-bridge.js", () => ({
+  bridgeQuestionRequestToGuardian: (params: Record<string, unknown>) =>
+    bridgeMock(params),
+}));
+mock.module("../runtime/pending-interactions.js", () => ({
+  get: (_id: string) => pendingInteraction,
+}));
+
+const { createGuardianRequestForQuestion, settlePromotedQuestionRequest } =
+  await import("./question-guardian-request.js");
+
+/** Let the settle helper's fire-and-forget chain drain. */
+const flush = () => new Promise((resolve) => setTimeout(resolve, 10));
+
+const entry = {
+  id: "q1",
+  question: "Which fruit?",
+  options: [
+    { id: "apple", label: "Apple" },
+    { id: "banana", label: "Banana" },
+  ],
+};
+
+function makeEvent(
+  overrides: Partial<QuestionRequestEvent> = {},
+): QuestionRequestEvent {
+  return {
+    type: "question_request",
+    requestId: "req-1",
+    questions: [entry],
+    question: entry.question,
+    options: entry.options,
+    conversationId: "conv-1",
+    ...overrides,
+  };
+}
+
+function guardianTrustContext(
+  overrides: Record<string, unknown> = {},
+): Record<string, unknown> {
+  return {
+    trustClass: "guardian",
+    sourceChannel: "telegram",
+    guardianPrincipalId: "prin-guardian",
+    guardianExternalUserId: "tg-guardian",
+    requesterExternalUserId: "tg-guardian",
+    requesterChatId: "chat-1",
+    ...overrides,
+  };
+}
+
+beforeEach(() => {
+  createGuardianRequestMock.mockClear();
+  expireGuardianRequestMock.mockClear();
+  bridgeMock.mockClear();
+  withdrawCardsMock.mockClear();
+  trustContext = guardianTrustContext();
+  pendingInteraction = { kind: "question" };
+  rowAfterExpire = null;
+});
+
+describe("createGuardianRequestForQuestion gating", () => {
+  test("promotes a guardian's single question on a card-capable channel and bridges it", async () => {
+    await createGuardianRequestForQuestion(makeEvent(), "conv-1");
+
+    expect(createGuardianRequestMock).toHaveBeenCalledTimes(1);
+    expect(createGuardianRequestMock.mock.calls[0]?.[0]).toMatchObject({
+      id: "req-1",
+      kind: "pending_question",
+      sourceChannel: "telegram",
+      sourceConversationId: "conv-1",
+      guardianPrincipalId: "prin-guardian",
+      questionText: "Which fruit?",
+      status: "pending",
+    });
+    expect(bridgeMock).toHaveBeenCalledTimes(1);
+    expect(bridgeMock.mock.calls[0]?.[0]).toMatchObject({
+      conversationId: "conv-1",
+      question: entry,
+    });
+    expect(expireGuardianRequestMock).not.toHaveBeenCalled();
+  });
+
+  test("skips multi-question batches", async () => {
+    await createGuardianRequestForQuestion(
+      makeEvent({
+        questions: [entry, { ...entry, id: "q2", question: "Which size?" }],
+      }),
+      "conv-1",
+    );
+    expect(createGuardianRequestMock).not.toHaveBeenCalled();
+  });
+
+  test("skips non-guardian turns", async () => {
+    trustContext = guardianTrustContext({ trustClass: "trusted_contact" });
+    await createGuardianRequestForQuestion(makeEvent(), "conv-1");
+    expect(createGuardianRequestMock).not.toHaveBeenCalled();
+  });
+
+  test("skips channels without question-card delivery (whatsapp, vellum)", async () => {
+    trustContext = guardianTrustContext({ sourceChannel: "whatsapp" });
+    await createGuardianRequestForQuestion(makeEvent(), "conv-1");
+    trustContext = guardianTrustContext({ sourceChannel: "vellum" });
+    await createGuardianRequestForQuestion(makeEvent(), "conv-1");
+    expect(createGuardianRequestMock).not.toHaveBeenCalled();
+  });
+
+  test("skips guardian turns with no bound principal", async () => {
+    trustContext = guardianTrustContext({ guardianPrincipalId: undefined });
+    await createGuardianRequestForQuestion(makeEvent(), "conv-1");
+    expect(createGuardianRequestMock).not.toHaveBeenCalled();
+  });
+
+  test("expires the row instead of bridging when the prompt already resolved", async () => {
+    pendingInteraction = undefined;
+    await createGuardianRequestForQuestion(makeEvent(), "conv-1");
+
+    expect(createGuardianRequestMock).toHaveBeenCalledTimes(1);
+    expect(expireGuardianRequestMock).toHaveBeenCalledTimes(1);
+    expect(bridgeMock).not.toHaveBeenCalled();
+  });
+
+  test("never throws when the gateway create fails", async () => {
+    createGuardianRequestMock.mockImplementationOnce(() =>
+      Promise.reject(new Error("gateway down")),
+    );
+    await expect(
+      createGuardianRequestForQuestion(makeEvent(), "conv-1"),
+    ).resolves.toBeUndefined();
+  });
+});
+
+describe("settlePromotedQuestionRequest", () => {
+  test("expires the promoted row and withdraws its cards once", async () => {
+    await createGuardianRequestForQuestion(makeEvent(), "conv-1");
+    rowAfterExpire = {
+      id: "req-1",
+      kind: "pending_question",
+      status: "expired",
+    };
+
+    settlePromotedQuestionRequest("req-1");
+    await flush();
+
+    expect(expireGuardianRequestMock).toHaveBeenCalledTimes(1);
+    expect(expireGuardianRequestMock.mock.calls[0]?.[0]).toBe("req-1");
+    expect(withdrawCardsMock).toHaveBeenCalledTimes(1);
+    expect(withdrawCardsMock.mock.calls[0]?.[0]).toMatchObject({
+      status: "expired",
+    });
+
+    // The promotion is consumed: a second settle is a no-op.
+    settlePromotedQuestionRequest("req-1");
+    await flush();
+    expect(expireGuardianRequestMock).toHaveBeenCalledTimes(1);
+  });
+
+  test("skips withdrawal when the row was already decided by the pipeline", async () => {
+    await createGuardianRequestForQuestion(makeEvent(), "conv-1");
+    // The expire CAS missed — the row reads its decided status, meaning the
+    // decision primitive already withdrew the cards.
+    rowAfterExpire = {
+      id: "req-1",
+      kind: "pending_question",
+      status: "approved",
+    };
+
+    settlePromotedQuestionRequest("req-1");
+    await flush();
+
+    expect(expireGuardianRequestMock).toHaveBeenCalledTimes(1);
+    expect(withdrawCardsMock).not.toHaveBeenCalled();
+  });
+
+  test("is a no-op for requests that never promoted", async () => {
+    settlePromotedQuestionRequest("req-never-promoted");
+    await flush();
+    expect(expireGuardianRequestMock).not.toHaveBeenCalled();
+    expect(withdrawCardsMock).not.toHaveBeenCalled();
+  });
+});

package/src/permissions/question-guardian-request.ts

@@ -0,0 +1,179 @@
+/**
+ * Promote a parked `ask_question` prompt into a guardian request and notify
+ * the guardian through the notification pipeline.
+ *
+ * Called fire-and-forget by {@link QuestionPrompter} right after it registers
+ * the pending `question` interaction, mirroring how confirmations are promoted
+ * (`confirmation-guardian-request.ts`). The request row makes the question
+ * answerable on channels: the notification broadcaster renders the options as
+ * card actions, and a tap / request-code reply / bare text routes back through
+ * the guardian reply router to the `pending_question` resolver, which settles
+ * the parked interaction.
+ *
+ * Gating — inverted from the confirmation bridge, which escalates a
+ * NON-guardian's confirmation TO the guardian:
+ *  - `ask_question` targets whoever is chatting, so promotion only makes sense
+ *    when the chatter IS the guardian (the pipeline delivers to the guardian's
+ *    own channels — the same chat they're in). Non-guardian turns keep the
+ *    tool's plain-text fallback.
+ *  - Only single-question batches promote: one card, one answer, one resolve.
+ *  - Only channel turns promote (`channelSupportsGuardianQuestionCards`):
+ *    app turns already render the SSE question card, and voice turns have
+ *    their own pending-question dispatch in the calls domain.
+ *
+ * The heavy dependencies are loaded lazily so importing this module — and
+ * therefore the prompter — stays cheap and free of import-time side effects.
+ */
+
+import type { QuestionRequestEvent } from "../api/events/question-request.js";
+import { getConfig } from "../config/loader.js";
+import { channelSupportsGuardianQuestionCards } from "../daemon/channel-ui-capability.js";
+import { getLogger } from "../util/logger.js";
+
+const log = getLogger("question-guardian-request");
+
+/**
+ * requestIds this process promoted to a guardian request. Lets the prompt's
+ * settle path expire the row without a gateway round-trip for the (common)
+ * app-only questions that never promoted; a daemon restart loses the set, and
+ * boot's interaction-bound expiry covers those rows instead.
+ */
+const promotedQuestionRequestIds = new Set<string>();
+
+/**
+ * Expire the promoted guardian-request row for a settled question prompt and
+ * withdraw its delivered cards. Called from the prompter's settle funnel for
+ * EVERY outcome (answered on any surface, timed out, aborted, superseded), so
+ * a row can never outlive its interaction and get matched against a later,
+ * unrelated channel message — and so an app-side answer visibly deactivates
+ * the channel card rather than leaving live buttons.
+ *
+ * When the pipeline itself resolved the question the row is already decided:
+ * the expire's status CAS misses and the post-expire status check skips
+ * withdrawal (the decision primitive already withdrew on decide). Failures are
+ * logged and swallowed; the periodic orphan sweep and boot expiry remain the
+ * backstops.
+ */
+export function settlePromotedQuestionRequest(requestId: string): void {
+  if (!promotedQuestionRequestIds.delete(requestId)) {
+    return;
+  }
+  void (async () => {
+    const { expireGuardianRequest, getGuardianRequestOrNull } =
+      await import("../channels/gateway-guardian-requests.js");
+    await expireGuardianRequest(requestId);
+    // Withdraw cards only when the expire actually transitioned the row —
+    // gated on a fresh read since the expire CAS reports no outcome.
+    const row = await getGuardianRequestOrNull(requestId);
+    if (row?.status !== "expired") {
+      return;
+    }
+    const { withdrawGuardianRequestCards } =
+      await import("../approvals/guardian-card-withdrawal.js");
+    await withdrawGuardianRequestCards({ request: row, status: "expired" });
+  })().catch((err) => {
+    log.debug(
+      { err, requestId },
+      "Failed to expire promoted question request on settle; sweep will catch it",
+    );
+  });
+}
+
+/**
+ * Create a `pending_question` guardian request + notification for a parked
+ * `ask_question` prompt, when the turn qualifies (see module doc). Safe to
+ * call fire-and-forget; failures are logged, never thrown — the prompt still
+ * resolves via the app card or times out.
+ */
+export async function createGuardianRequestForQuestion(
+  msg: QuestionRequestEvent,
+  conversationId: string,
+): Promise<void> {
+  try {
+    if (msg.questions.length !== 1) {
+      return;
+    }
+
+    const [
+      { findConversation },
+      { createGuardianRequest, expireGuardianRequest },
+      { bridgeQuestionRequestToGuardian },
+    ] = await Promise.all([
+      import("../daemon/conversation-registry.js"),
+      import("../channels/gateway-guardian-requests.js"),
+      import("../runtime/question-request-guardian-bridge.js"),
+    ]);
+
+    const conversation = findConversation(conversationId);
+    // The prompter runs inside the emitting turn — bind to the turn's trust
+    // snapshot so a concurrent context mutation can't repoint the request.
+    const trustContext =
+      conversation?.currentTurnTrustContext ?? conversation?.trustContext;
+    if (!conversation || !trustContext) {
+      return;
+    }
+
+    const sourceChannel = trustContext.sourceChannel;
+    if (!channelSupportsGuardianQuestionCards(sourceChannel)) {
+      return;
+    }
+    if (trustContext.trustClass !== "guardian") {
+      return;
+    }
+    // Questions are answerable only by the bound guardian principal.
+    const guardianPrincipalId = trustContext.guardianPrincipalId;
+    if (!guardianPrincipalId) {
+      log.warn(
+        { conversationId, requestId: msg.requestId, sourceChannel },
+        "Skipping question guardian request: guardian turn has no bound principal",
+      );
+      return;
+    }
+
+    const entry = msg.questions[0]!;
+    const guardianRequest = await createGuardianRequest({
+      id: msg.requestId,
+      kind: "pending_question",
+      sourceChannel,
+      sourceConversationId: conversationId,
+      requesterExternalUserId: trustContext.requesterExternalUserId,
+      requesterChatId: trustContext.requesterChatId ?? undefined,
+      guardianExternalUserId: trustContext.guardianExternalUserId,
+      guardianPrincipalId,
+      questionText: entry.question,
+      status: "pending",
+      expiresAt:
+        Date.now() + getConfig().timeouts.questionResponseTimeoutSec * 1000,
+    });
+
+    promotedQuestionRequestIds.add(guardianRequest.id);
+
+    // The prompt is answerable via the app card before this fire-and-forget
+    // create lands; if it already resolved, expire the fresh row instead of
+    // stranding a decidable request for a settled prompt.
+    const { get: getPendingInteraction } =
+      await import("../runtime/pending-interactions.js");
+    const pending = getPendingInteraction(msg.requestId);
+    if (!pending || pending.kind !== "question") {
+      promotedQuestionRequestIds.delete(guardianRequest.id);
+      await expireGuardianRequest(guardianRequest.id);
+      log.info(
+        { conversationId, requestId: msg.requestId },
+        "Question resolved before its guardian request landed; expired the row",
+      );
+      return;
+    }
+
+    await bridgeQuestionRequestToGuardian({
+      guardianRequest,
+      trustContext,
+      conversationId,
+      question: entry,
+    });
+  } catch (err) {
+    log.warn(
+      { err, conversationId, requestId: msg.requestId },
+      "Failed to create guardian request for question; channel answers will not work for it",
+    );
+  }
+}

package/src/permissions/question-prompter.test.ts

@@ -2,7 +2,7 @@ import { beforeEach, describe, expect, mock, test } from "bun:test";
 
 import { setConfig } from "../__tests__/helpers/set-config.js";
 import type { QuestionRequestEvent } from "../api/events/question-request.js";
-import type { ServerMessage } from "../daemon/message-protocol.js";
+import type { AssistantEvent } from "../api/index.js";
 import type {
   QuestionBatchSubmission,
   QuestionPromptResult,
@@ -48,7 +48,7 @@ mock.module("../runtime/pending-interactions.js", () => ({
   register: (id: string, entry: MockInteraction) => _piStore.set(id, entry),
   resolve: (id: string) => {
     const e = _piStore.get(id);
-    if (e?.timer != null) clearTimeout(e.timer);
+    if (e?.timer != null) {clearTimeout(e.timer);}
     _piStore.delete(id);
     return e;
   },
@@ -66,18 +66,18 @@ mock.module("../runtime/pending-interactions.js", () => ({
 // prompter would have broadcast — but preserve every other export from
 // the real module so other tests in the same `bun test` run (which
 // share module-level mocks) still see e.g. `assistantEventHub`.
-let _sentBuffer: ServerMessage[] = [];
+let _sentBuffer: AssistantEvent[] = [];
 const realEventHub = await import("../runtime/assistant-event-hub.js");
 mock.module("../runtime/assistant-event-hub.js", () => ({
   ...realEventHub,
-  broadcastMessage: (msg: ServerMessage) => _sentBuffer.push(msg),
+  broadcastMessage: (msg: AssistantEvent) => _sentBuffer.push(msg),
 }));
 
 const { QuestionPrompter, QuestionBatchValidationError, buildBatchEntries } =
   await import("./question-prompter.js");
 
 function makePrompter() {
-  const sent: ServerMessage[] = [];
+  const sent: AssistantEvent[] = [];
   _sentBuffer = sent;
   const prompter = new QuestionPrompter();
   return { prompter, sent };
@@ -106,7 +106,7 @@ function resolveBatch(
     submissions,
   );
   const result: QuestionPromptResult = { entries, overall: "completed" };
-  if (interaction.timer != null) clearTimeout(interaction.timer);
+  if (interaction.timer != null) {clearTimeout(interaction.timer);}
   _piStore.delete(requestId);
   interaction.rpcResolve?.(result);
   return result;
@@ -128,7 +128,7 @@ function closeBatch(requestId: string): QuestionPromptResult {
     })),
     overall: "closed",
   };
-  if (interaction.timer != null) clearTimeout(interaction.timer);
+  if (interaction.timer != null) {clearTimeout(interaction.timer);}
   _piStore.delete(requestId);
   interaction.rpcResolve?.(result);
   return result;
@@ -412,7 +412,7 @@ describe("QuestionPrompter", () => {
     // Simulate `removeByConversation` clearing the registry entry before
     // the abort signal fires.
     const interaction = _piStore.get(req.requestId);
-    if (interaction?.timer != null) clearTimeout(interaction.timer);
+    if (interaction?.timer != null) {clearTimeout(interaction.timer);}
     _piStore.delete(req.requestId);
 
     ac.abort();

package/src/permissions/question-prompter.ts

@@ -9,6 +9,10 @@ import { broadcastMessage } from "../runtime/assistant-event-hub.js";
 import * as pendingInteractions from "../runtime/pending-interactions.js";
 import { AssistantError, ErrorCode } from "../util/errors.js";
 import { getLogger } from "../util/logger.js";
+import {
+  createGuardianRequestForQuestion,
+  settlePromotedQuestionRequest,
+} from "./question-guardian-request.js";
 
 const log = getLogger("question-prompter");
 
@@ -227,6 +231,13 @@ export class QuestionPrompter {
         // so this fallback only fires for timeout / abort / removeByConversation —
         // all cancellation-shaped outcomes.
         pendingInteractions.resolve(requestId, "cancelled");
+        // A promoted guardian-request row must not outlive the interaction:
+        // left pending (e.g. the app card answered, or the prompt timed out),
+        // it would still look decidable to the channel reply router and could
+        // swallow the guardian's next unrelated message. No-op for questions
+        // that never promoted, and a CAS-miss no-op when the pipeline itself
+        // decided the row.
+        settlePromotedQuestionRequest(requestId);
         fn();
       };
 
@@ -295,6 +306,13 @@ export class QuestionPrompter {
       };
 
       broadcastMessage(msg);
+
+      // Promote the question to a guardian request so channel answers (option
+      // taps, request-code replies, bare text) can resolve it through the
+      // guardian-request pipeline. Mirrors the confirmation prompter's
+      // promotion; the gating (guardian turn, card-capable channel,
+      // single-question batch) lives in the promotion module.
+      void createGuardianRequestForQuestion(msg, conversationId);
     });
   }
 }

package/src/permissions/secret-prompter.ts

@@ -1,7 +1,7 @@
 import { v4 as uuid } from "uuid";
 
+import type { SecretRequestEvent } from "../api/index.js";
 import { getConfig } from "../config/loader.js";
-import type { ServerMessage } from "../daemon/message-protocol.js";
 import { broadcastMessage } from "../runtime/assistant-event-hub.js";
 import * as pendingInteractions from "../runtime/pending-interactions.js";
 import { AssistantError, ErrorCode } from "../util/errors.js";
@@ -11,8 +11,6 @@ import type {
   SecretPromptResult,
 } from "./secret-prompt-types.js";
 
-type SecretRequestMessage = Extract<ServerMessage, { type: "secret_request" }>;
-
 const log = getLogger("secret-prompter");
 
 export interface SecretPrompterChannelContext {
@@ -109,7 +107,7 @@ export class SecretPrompter {
       });
       this.ownedIds.add(requestId);
 
-      const msg: SecretRequestMessage = {
+      const msg: SecretRequestEvent = {
         type: "secret_request",
         requestId,
         service,