@vellumai/assistant 0.10.12 → 0.11.0-staging.2

package/src/providers/openai/chat-completions-provider.ts

@@ -6,7 +6,12 @@ import { ProviderError, type ProviderErrorReason } from "../../util/errors.js";
 import { getLogger } from "../../util/logger.js";
 import { extractRetryAfterMs } from "../../util/retry.js";
 import { escapeXmlAttr } from "../../util/xml.js";
-import { base64Source, resolveMediaReferences } from "../media-resolve.js";
+import {
+  base64Source,
+  mediaSourceByteLength,
+  resolveMediaReferences,
+} from "../media-resolve.js";
+import { modelSupportsAudioInput } from "../model-catalog.js";
 import { PLACEHOLDER_EMPTY_TURN } from "../placeholder-sentinels.js";
 import { createStreamTimeout } from "../stream-timeout.js";
 import { createToolProgressEmitter } from "../tool-progress-events.js";
@@ -35,6 +40,11 @@ import {
   coerceObjectParamsToJsonString,
   decodeCoercedObjectArgs,
 } from "./coerce-object-args.js";
+import {
+  isOpenAICompatInlineAudio,
+  OPENAI_COMPAT_MAX_INLINE_AUDIO_BYTES,
+  openAIInputAudioFormat,
+} from "./input-audio.js";
 
 /**
  * Detect OpenAI-compatible context-overflow signals on an `OpenAI.APIError`.
@@ -336,6 +346,10 @@ export class OpenAIChatCompletionsProvider implements Provider {
       options.coerceObjectArgsToJsonString ?? false;
   }
 
+  get defaultModel(): string {
+    return this.model;
+  }
+
   async sendMessage(
     messages: Message[],
     options?: SendMessageOptions,
@@ -359,7 +373,11 @@ export class OpenAIChatCompletionsProvider implements Provider {
     const coercedObjectKeys = new Map<string, string[]>();
 
     try {
-      const openaiMessages = this.toOpenAIMessages(messages, systemPrompt);
+      const openaiMessages = this.toOpenAIMessages(
+        messages,
+        systemPrompt,
+        modelSupportsAudioInput(modelOverride ?? this.model),
+      );
 
       const params: OpenAI.Chat.Completions.ChatCompletionCreateParamsStreaming =
         {
@@ -893,6 +911,7 @@ export class OpenAIChatCompletionsProvider implements Provider {
   private toOpenAIMessages(
     messages: Message[],
     systemPrompt?: string,
+    audioInputEnabled = false,
   ): OpenAI.Chat.Completions.ChatCompletionMessageParam[] {
     // Swap any persisted attachment references back to inline base64 before
     // serializing, so the block transforms below can read `source.data`.
@@ -923,9 +942,9 @@ export class OpenAIChatCompletionsProvider implements Provider {
         );
 
         // Emit tool results as separate tool-role messages
-        // OpenAI's API only supports string content in tool messages, so images
-        // from contentBlocks are collected and injected as a user message below.
-        const toolResultImages: ContentBlock[] = [];
+        // OpenAI's API only supports string content in tool messages, so media
+        // from contentBlocks is collected and injected as a user message below.
+        const toolResultMedia: ContentBlock[] = [];
         for (const tr of toolResults) {
           let textContent = tr.content;
           if (tr.contentBlocks && tr.contentBlocks.length > 0) {
@@ -939,7 +958,18 @@ export class OpenAIChatCompletionsProvider implements Provider {
               textContent = textContent + "\n" + extraText.join("\n");
             }
             for (const cb of tr.contentBlocks) {
-              if (cb.type === "image") toolResultImages.push(cb);
+              if (cb.type === "image") {
+                toolResultMedia.push(cb);
+              } else if (
+                audioInputEnabled &&
+                cb.type === "file" &&
+                isOpenAICompatInlineAudio(
+                  cb.source.media_type,
+                  mediaSourceByteLength(cb.source),
+                )
+              ) {
+                toolResultMedia.push(cb);
+              }
             }
           }
           result.push({
@@ -949,12 +979,13 @@ export class OpenAIChatCompletionsProvider implements Provider {
           });
         }
 
-        // Emit remaining content + any tool result images as a user message.
-        // Images from tool results (e.g. browser_screenshot) must go in a user
-        // message because OpenAI-compatible APIs don't support images in tool messages.
-        const userContent = [...otherBlocks, ...toolResultImages];
+        // Emit remaining content + any tool result media as a user message.
+        // Media from tool results (e.g. browser_screenshot, audio a tool read)
+        // must go in a user message because OpenAI-compatible APIs don't
+        // support media parts in tool messages.
+        const userContent = [...otherBlocks, ...toolResultMedia];
         if (userContent.length > 0) {
-          result.push(this.toOpenAIUserMessage(userContent));
+          result.push(this.toOpenAIUserMessage(userContent, audioInputEnabled));
         }
       }
     }
@@ -1035,9 +1066,10 @@ export class OpenAIChatCompletionsProvider implements Provider {
     return result;
   }
 
-  /** Convert user content blocks (text, image) to an OpenAI user message. */
+  /** Convert user content blocks (text, image, audio) to an OpenAI user message. */
   private toOpenAIUserMessage(
     blocks: ContentBlock[],
+    audioInputEnabled = false,
   ): OpenAI.Chat.Completions.ChatCompletionUserMessageParam {
     // If only a single text block, use plain string (simpler, fewer tokens)
     if (blocks.length === 1 && blocks[0].type === "text") {
@@ -1066,12 +1098,28 @@ export class OpenAIChatCompletionsProvider implements Provider {
             });
           }
           break;
-        case "file":
-          parts.push({
-            type: "text",
-            text: this.fileBlockToText(block),
-          });
+        case "file": {
+          const audioFormat = audioInputEnabled
+            ? openAIInputAudioFormat(block.source.media_type)
+            : null;
+          if (
+            audioFormat !== null &&
+            mediaSourceByteLength(block.source) <=
+              OPENAI_COMPAT_MAX_INLINE_AUDIO_BYTES
+          ) {
+            const audioSrc = base64Source(block.source);
+            parts.push({
+              type: "input_audio",
+              input_audio: { data: audioSrc.data, format: audioFormat },
+            });
+          } else {
+            parts.push({
+              type: "text",
+              text: this.fileBlockToText(block),
+            });
+          }
           break;
+        }
         case "server_tool_use":
           parts.push({
             type: "text",

package/src/providers/openai/input-audio.ts

@@ -0,0 +1,76 @@
+/**
+ * Shared source of truth for how OpenAI-compatible chat-completions providers
+ * ingest inline audio: which MIME types map onto the wire `input_audio.format`
+ * enum, the inline size cap, and the token-cost heuristic. The provider
+ * transform (`chat-completions-provider.ts`) and the context budgeter
+ * (`context/token-estimator.ts`) both read these — if they disagreed about
+ * which audio is sent inline, the budgeter would mis-count what the provider
+ * actually ships.
+ *
+ * Wire shape (OpenAI chat-completions spec):
+ *   { type: "input_audio", input_audio: { data: <base64>, format: "wav"|"mp3" } }
+ *
+ * m4a/ogg/flac/opus are deliberately absent: the spec's `format` enum is
+ * wav|mp3 only. Whether a given model receives audio at all is gated by the
+ * catalog `supportsAudioInput` capability (`modelSupportsAudioInput`), not
+ * here — this module only decides eligibility of the payload itself.
+ */
+
+export type OpenAIInputAudioFormat = "wav" | "mp3";
+
+const MIME_TO_INPUT_AUDIO_FORMAT: ReadonlyMap<string, OpenAIInputAudioFormat> =
+  new Map([
+    ["audio/wav", "wav"],
+    ["audio/x-wav", "wav"],
+    ["audio/wave", "wav"],
+    ["audio/mpeg", "mp3"],
+    ["audio/mp3", "mp3"],
+  ]);
+
+/**
+ * Map a stored attachment MIME type onto the `input_audio.format` enum, or
+ * `null` when the type is not sent inline.
+ */
+export function openAIInputAudioFormat(
+  mimeType: string,
+): OpenAIInputAudioFormat | null {
+  return MIME_TO_INPUT_AUDIO_FORMAT.get(mimeType.toLowerCase()) ?? null;
+}
+
+/**
+ * Max raw bytes of audio sent inline. Base64 inflates the payload ~4/3, so
+ * 12 MB raw ≈ 16 MB encoded — headroom for the rest of the prompt under
+ * typical request-size limits (same rationale as the Gemini inline-audio cap).
+ */
+export const OPENAI_COMPAT_MAX_INLINE_AUDIO_BYTES = 12 * 1024 * 1024;
+
+/**
+ * True when an audio media source of this MIME type and byte length is
+ * eligible to be sent inline as an `input_audio` part (given a model whose
+ * catalog entry carries `supportsAudioInput`).
+ */
+export function isOpenAICompatInlineAudio(
+  mimeType: string,
+  byteLength: number,
+): boolean {
+  return (
+    openAIInputAudioFormat(mimeType) !== null &&
+    byteLength <= OPENAI_COMPAT_MAX_INLINE_AUDIO_BYTES
+  );
+}
+
+/**
+ * Audio-native chat-completions models bill audio by duration, not payload
+ * size (measured on Baseten's Inkling: ~20 tokens/sec — 127 audio tokens for
+ * a 6.3 s clip). Duration is approximated from byte length at compressed-audio
+ * rates (~16 KB/s); for uncompressed PCM wavs this overestimates duration and
+ * therefore tokens — the safe direction for the compaction pre-check
+ * (compact early, never overflow).
+ */
+const AUDIO_TOKENS_PER_SECOND = 20;
+const APPROX_AUDIO_BYTES_PER_SECOND = 16_000;
+
+export function estimateOpenAICompatAudioTokens(byteLength: number): number {
+  const approxSeconds = byteLength / APPROX_AUDIO_BYTES_PER_SECOND;
+  return Math.ceil(approxSeconds * AUDIO_TOKENS_PER_SECOND);
+}

package/src/providers/openrouter/client.ts

@@ -118,7 +118,6 @@ export class OpenRouterResponsesProvider extends OpenAIResponsesProvider {
 
 export class OpenRouterProvider extends OpenAIChatCompletionsProvider {
   private readonly openRouterApiKey: string;
-  private readonly defaultModel: string;
   private readonly resolvedBaseURL: string;
   private readonly providerStreamTimeoutMs: number | undefined;
   private readonly useNativeWebSearch: boolean;
@@ -141,7 +140,6 @@ export class OpenRouterProvider extends OpenAIChatCompletionsProvider {
       backfillEmptyAssistantContent: true,
     });
     this.openRouterApiKey = apiKey;
-    this.defaultModel = model;
     this.resolvedBaseURL = baseURL;
     this.providerStreamTimeoutMs = options.streamTimeoutMs;
     this.useNativeWebSearch = options.useNativeWebSearch ?? false;

package/src/providers/platform-proxy/constants.ts

@@ -51,6 +51,10 @@ export const PLATFORM_PROVIDER_META: Record<string, ManagedProviderMeta> = {
     managed: true,
     proxyPath: "/v1/runtime-proxy/together",
   },
+  poolside: {
+    name: "poolside",
+    managed: false,
+  },
   openrouter: {
     name: "openrouter",
     managed: false,

package/src/providers/poolside/client.ts

@@ -0,0 +1,42 @@
+import {
+  type ApiKeyValidationResult,
+  validateOpenAICompatibleApiKey,
+} from "../openai/api-key-validation.js";
+import { OpenAIChatCompletionsProvider } from "../openai/chat-completions-provider.js";
+
+export interface PoolsideProviderOptions {
+  baseURL?: string;
+  streamTimeoutMs?: number;
+}
+
+/** Poolside exposes a single OpenAI-compatible inference endpoint. */
+const DEFAULT_POOLSIDE_BASE_URL = "https://inference.poolside.ai";
+
+export async function validatePoolsideApiKey(
+  apiKey: string,
+): Promise<ApiKeyValidationResult> {
+  return validateOpenAICompatibleApiKey({
+    apiKey,
+    baseURL: DEFAULT_POOLSIDE_BASE_URL,
+    providerLabel: "Poolside",
+  });
+}
+
+export class PoolsideProvider extends OpenAIChatCompletionsProvider {
+  constructor(
+    apiKey: string,
+    model: string,
+    options: PoolsideProviderOptions = {},
+  ) {
+    super(apiKey, model, {
+      baseURL: options.baseURL?.trim() || DEFAULT_POOLSIDE_BASE_URL,
+      providerName: "poolside",
+      providerLabel: "Poolside",
+      streamTimeoutMs: options.streamTimeoutMs,
+      // Poolside's Laguna models emit chain of thought via `reasoning_content`
+      // rather than inline `<think>` tags. The base provider parses this field
+      // into thinking blocks and replays it on multi-turn requests.
+      assistantReasoningField: "reasoning_content",
+    });
+  }
+}

package/src/providers/registry.ts

@@ -35,8 +35,32 @@ const providers = new Map<string, Provider>();
 const routingSources = new Map<string, "user-key" | "managed-proxy">();
 const NATIVE_WEB_SEARCH_PROVIDER_IDS = new Set(["anthropic", "openai"]);
 
+/**
+ * A cached per-connection provider and the wall-clock time it goes stale.
+ *
+ * The credential store is the source of truth for a connection's API key; a
+ * resolved provider bakes that key into its auth headers and is only a cache of
+ * it. `expiresAt` bounds how long a cached provider is trusted before the key
+ * is re-read from the store, so a credential rotated out-of-band (e.g. the
+ * platform reprovisioning the assistant API key) is picked up on its own — in
+ * every process that holds this cache, with no cross-process invalidation.
+ */
+interface CachedConnectionProvider {
+  provider: Provider;
+  expiresAt: number;
+}
+
+/**
+ * How long a resolved per-connection provider is served from cache before it is
+ * re-resolved from the credential store. Bounds credential staleness in any
+ * process holding the cache (the daemon and each sidecar worker) to this
+ * window. Kept short enough that a rotated key self-heals quickly, long enough
+ * that repeated resolutions within a burst still reuse one adapter.
+ */
+const CONNECTION_PROVIDER_CACHE_TTL_MS = 60_000;
+
 /** Per-connection provider cache, keyed by connection name, effective provider, and model. */
-const connectionProviders = new Map<string, Provider>();
+const connectionProviders = new Map<string, CachedConnectionProvider>();
 
 function getConnectionProviderCacheKey(
   connection: ProviderConnection,
@@ -75,7 +99,6 @@ export interface ProvidersConfig {
   services: {
     inference: Record<string, never>;
     "image-generation": {
-      mode: "managed" | "your-own";
       provider: string;
       model: string;
     };
@@ -257,9 +280,12 @@ export async function initializeProviders(
 /**
  * Resolve a provider instance for a named `provider_connection`.
  *
- * Results are cached in `connectionProviders` for the lifetime of the
- * current `initializeProviders` invocation (cleared on next boot). This
- * prevents redundant vault reads for repeated calls to the same connection.
+ * Results are cached in `connectionProviders` to avoid redundant vault reads
+ * for repeated calls to the same connection. A cached provider bakes in the
+ * credential it resolved, so each entry carries a TTL
+ * ({@link CONNECTION_PROVIDER_CACHE_TTL_MS}): once it expires the credential is
+ * re-read from the store, bounding how long an out-of-band key rotation stays
+ * stale. Entries are also cleared eagerly on connection mutations and boot.
  *
  * Returns null when:
  *   - The connection doesn't exist in the DB
@@ -292,9 +318,12 @@ export async function resolveProviderFromConnection(
     effectiveProvider,
   );
   const cached = connectionProviders.get(cacheKey);
-  if (cached) {
-    return cached;
+  if (cached && cached.expiresAt > Date.now()) {
+    return cached.provider;
   }
+  // A stale entry is a miss: fall through to re-resolve. The credential is
+  // re-read from the store below, so a key rotated since the entry was cached
+  // is picked up here rather than served stale forever.
 
   const authResult = await resolveAuth(connection.auth, effectiveProvider, {
     baseUrl: connection.baseUrl,
@@ -341,7 +370,10 @@ export async function resolveProviderFromConnection(
   );
 
   if (provider) {
-    connectionProviders.set(cacheKey, provider);
+    connectionProviders.set(cacheKey, {
+      provider,
+      expiresAt: Date.now() + CONNECTION_PROVIDER_CACHE_TTL_MS,
+    });
   }
 
   return provider;

package/src/providers/retry.ts

@@ -57,6 +57,7 @@ const EFFORT_SUPPORTED_PROVIDERS = new Set([
   "fireworks",
   "together",
   "baseten",
+  "poolside",
 ]);
 
 // For these providers, disabling reasoning is encoded through the same effort
@@ -69,6 +70,7 @@ const DISABLED_THINKING_USES_EFFORT_PROVIDERS = new Set([
   "openrouter",
   "vercel-ai-gateway",
   "baseten",
+  "poolside",
 ]);
 
 // Whether a disabled `thinking` config must be encoded as `effort: "none"`

package/src/providers/types.ts

@@ -128,6 +128,36 @@ export interface WebSearchToolResultContent {
   content: unknown; // Opaque — encrypted_content in search results is provider-specific
 }
 
+/**
+ * A client-rendered UI card persisted into conversation history: call
+ * summaries, guardian approval cards, skill cards, wake notices, document
+ * previews.
+ *
+ * This is a rendering instruction, not model context — providers drop it when
+ * serializing history. Producers therefore pair the surface with a sibling
+ * `text` block flagged `_surfaceFallback` (see
+ * `notifications/approval-card-builder.ts`); that text is what feeds the model,
+ * search indexing, CLI display, and channel replies.
+ *
+ * `data` is deliberately opaque: its concrete shape is selected by
+ * `surfaceType` and owned by `daemon/message-types/surfaces.ts`.
+ */
+export interface UiSurfaceContent {
+  type: "ui_surface";
+  surfaceId: string;
+  surfaceType: string;
+  title?: string;
+  data?: Record<string, unknown>;
+  actions?: unknown[];
+  /**
+   * Free-form, matching `CurrentTurnSurface.display` — NOT the `inline` /
+   * `panel` enum of the `ui_surface_show` wire event. Persisted surfaces carry
+   * whatever the `ui_show` tool wrote, so this must not narrow.
+   */
+  display?: string;
+  completed?: boolean;
+}
+
 export type ContentBlock =
   | TextContent
   | ThinkingContent
@@ -137,7 +167,8 @@ export type ContentBlock =
   | ToolUseContent
   | ToolResultContent
   | ServerToolUseContent
-  | WebSearchToolResultContent;
+  | WebSearchToolResultContent
+  | UiSurfaceContent;
 
 export interface Message {
   role: "user" | "assistant";
@@ -337,6 +368,13 @@ export interface Provider {
    * Falls back to `name` when unset.
    */
   tokenEstimationProvider?: string;
+  /**
+   * Model id this instance dispatches when a call carries no per-call model
+   * override. Consumed by the local token estimator for model-keyed rules
+   * (e.g. audio-capable OpenAI-compatible models). Optional: providers whose
+   * estimation rules are provider-wide need not expose it.
+   */
+  defaultModel?: string;
   /**
    * True when this provider instance was constructed to run web search
    * server-side (provider-native). The native search only activates when a

package/src/providers/vercel-ai-gateway/client.ts

@@ -26,7 +26,6 @@ const DEFAULT_VERCEL_AI_GATEWAY_BASE_URL = "https://ai-gateway.vercel.sh/v1";
 
 export class VercelAIGatewayProvider extends OpenAIChatCompletionsProvider {
   private readonly gatewayApiKey: string;
-  private readonly defaultModel: string;
   private readonly resolvedBaseURL: string;
   private readonly providerStreamTimeoutMs: number | undefined;
   private readonly useNativeWebSearch: boolean;
@@ -50,7 +49,6 @@ export class VercelAIGatewayProvider extends OpenAIChatCompletionsProvider {
       backfillEmptyAssistantContent: true,
     });
     this.gatewayApiKey = apiKey;
-    this.defaultModel = model;
     this.resolvedBaseURL = baseURL;
     this.providerStreamTimeoutMs = options.streamTimeoutMs;
     this.useNativeWebSearch = options.useNativeWebSearch ?? false;

package/src/runtime/AGENTS.md

@@ -157,13 +157,15 @@ All CDP-backed browser tools (`browser_navigate`, `browser_snapshot`, `browser_s
 
 **Test coverage:** Regression tests for `browser_mode` wiring live in `__tests__/headless-browser-mode.test.ts`. E2E regression tests for backend precedence live in `__tests__/host-browser-e2e-cloud.test.ts` (extension path and macOS SSE bridge path) and `__tests__/conversation-routes-disk-view.test.ts` (macOS fallback path). Unit tests for pinned candidate construction and failover live in `tools/browser/cdp-client/__tests__/factory.test.ts`. Browser status tests covering macOS host-browser diagnostics live in `tools/browser/__tests__/browser-status.test.ts`.
 
-### Channel approvals (Telegram, Slack)
+### Interactive requests on channels (approvals, questions)
 
-Channel approval flows use `requestId` (not `runId`) as the primary identifier:
+**The guardian-request pipeline is the canonical rail for anything interactive on a channel** — cards with buttons, request-code replies, emoji reactions, typed answers. The end-to-end map (promotion → gateway `guardian_requests` row → notification broadcaster → per-channel adapters → reply router → decision primitive → per-kind resolver) lives in [docs/guardian-request-flow.md](../../docs/guardian-request-flow.md). New interactive features extend that pipeline's seams; do NOT add per-feature watchers, callback schemes, or inbound intercepts.
 
-- Telegram callback buttons encode `apr:<requestId>:<action>` in `callback_data`.
-- Guardian approval records in the gateway-owned `guardian_requests` table (and their `guardian_request_deliveries`) link via `requestId`; the daemon reads/writes them through the `channels/gateway-guardian-requests.ts` client.
-- The conversational approval engine classifies user intent and resolves via `conversation.handleConfirmationResponse(requestId, decision)`.
+Identifiers and plumbing notes:
+
+- Channel flows use `requestId` (not `runId`) as the primary identifier. Callback buttons encode `apr:<requestId>:<action>` in `callback_data`; answer-option buttons on question cards use action tokens `answer_<idx>` / `answer_skip` under the same prefix.
+- Guardian request records live in the gateway-owned `guardian_requests` table (and their `guardian_request_deliveries`); the daemon reads/writes them through the `channels/gateway-guardian-requests.ts` client.
+- Legacy in-turn interception (`routes/guardian-approval-interception.ts` + the approval prompt watcher) still serves a guardian's own tool-approval prompts mid-turn, resolving via `conversation.handleConfirmationResponse(requestId, decision)`. It is a legacy rail — the reply router runs first; converge new work on the pipeline.
 
 ### Channel verification: gateway-owned
 

package/src/runtime/__tests__/question-request-guardian-bridge.test.ts

@@ -0,0 +1,173 @@
+/**
+ * Tests for the question → guardian.question bridge
+ * (`question-request-guardian-bridge.ts`): the emitted signal must be
+ * deliverable (NOT source-active suppressed) and carry the option payload the
+ * broadcaster renders; identity guards skip emission rather than misroute.
+ */
+
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+import type { GuardianRequestWire } from "../../channels/gateway-guardian-requests.js";
+
+const emitSignalMock = mock(
+  (_params: Record<string, unknown>): Promise<Record<string, unknown>> =>
+    Promise.resolve({ signalId: "sig-1", deliveryResults: [] }),
+);
+const recordCardDeliveryMock = mock((_params: Record<string, unknown>) =>
+  Promise.resolve(undefined),
+);
+const recordDeliveriesMock = mock((_params: Record<string, unknown>) =>
+  Promise.resolve(),
+);
+
+let binding: { guardianExternalUserId: string } | null = null;
+
+mock.module("../../notifications/emit-signal.js", () => ({
+  emitNotificationSignal: (params: Record<string, unknown>) =>
+    emitSignalMock(params),
+}));
+mock.module("../../notifications/guardian-delivery-recorder.js", () => ({
+  recordApprovalCardDelivery: (params: Record<string, unknown>) =>
+    recordCardDeliveryMock(params),
+  recordGuardianRequestDeliveries: (params: Record<string, unknown>) =>
+    recordDeliveriesMock(params),
+}));
+mock.module("../channel-verification-service.js", () => ({
+  getGuardianBinding: () => Promise.resolve(binding),
+}));
+// The vellum-card pin mirrors the target conversation's source; no DB here,
+// so resolve "conversation not found" and let the helper fall back to "user".
+mock.module("../../persistence/conversation-crud.js", () => ({
+  getConversation: () => null,
+}));
+
+const { bridgeQuestionRequestToGuardian } =
+  await import("../question-request-guardian-bridge.js");
+
+function makeRequest(
+  overrides: Partial<GuardianRequestWire> = {},
+): GuardianRequestWire {
+  return {
+    id: "req-1",
+    kind: "pending_question",
+    sourceType: "channel",
+    sourceChannel: "telegram",
+    sourceConversationId: "conv-1",
+    requesterExternalUserId: "tg-guardian",
+    requesterChatId: "chat-1",
+    guardianExternalUserId: "tg-guardian",
+    guardianPrincipalId: "prin-guardian",
+    callSessionId: null,
+    pendingQuestionId: null,
+    questionText: "Which fruit?",
+    requestCode: "ABC123",
+    toolName: null,
+    inputDigest: null,
+    commandPreview: null,
+    riskLevel: null,
+    activityText: null,
+    executionTarget: null,
+    requesterSignals: null,
+    requestTrigger: null,
+    status: "pending",
+    answerText: null,
+    decidedByExternalUserId: null,
+    decidedByPrincipalId: null,
+    followupState: null,
+    expiresAt: null,
+    createdAt: 0,
+    updatedAt: 0,
+    ...overrides,
+  };
+}
+
+const trustContext = {
+  trustClass: "guardian",
+  sourceChannel: "telegram",
+  guardianPrincipalId: "prin-guardian",
+  guardianExternalUserId: "tg-guardian",
+  requesterExternalUserId: "tg-guardian",
+  requesterChatId: "chat-1",
+} as never;
+
+const question = {
+  id: "q1",
+  question: "Which fruit?",
+  options: [
+    { id: "apple", label: "Apple" },
+    { id: "banana", label: "Banana" },
+  ],
+};
+
+beforeEach(() => {
+  emitSignalMock.mockClear();
+  recordCardDeliveryMock.mockClear();
+  recordDeliveriesMock.mockClear();
+  binding = { guardianExternalUserId: "tg-guardian" };
+});
+
+describe("bridgeQuestionRequestToGuardian", () => {
+  test("emits a DELIVERABLE guardian.question signal carrying the options", async () => {
+    const result = await bridgeQuestionRequestToGuardian({
+      guardianRequest: makeRequest(),
+      trustContext,
+      conversationId: "conv-1",
+      question,
+    });
+
+    expect(result).toMatchObject({ bridged: true });
+    expect(emitSignalMock).toHaveBeenCalledTimes(1);
+    const signal = emitSignalMock.mock.calls[0]?.[0] as {
+      attentionHints: Record<string, unknown>;
+      contextPayload: Record<string, unknown>;
+      conversationAffinityHint?: Record<string, string>;
+    };
+    // The in-app card is pinned to the conversation the question was asked
+    // in — never left to LLM conversation routing.
+    expect(signal.conversationAffinityHint).toEqual({ vellum: "conv-1" });
+    // REGRESSION PIN: visibleInSourceNow is a hard suppression pre-gate in
+    // emitNotificationSignal. The question card is the channel's ONLY way to
+    // display the parked prompt — a true here silently suppresses every
+    // question card and the tool hangs until the prompt timeout.
+    expect(signal.attentionHints.visibleInSourceNow).toBe(false);
+    expect(signal.contextPayload).toMatchObject({
+      requestKind: "pending_question",
+      requestId: "req-1",
+      questionText: "Which fruit?",
+      options: [
+        { id: "apple", label: "Apple" },
+        { id: "banana", label: "Banana" },
+      ],
+    });
+  });
+
+  test("skips emission when no guardian binding exists for the channel", async () => {
+    binding = null;
+    const result = await bridgeQuestionRequestToGuardian({
+      guardianRequest: makeRequest(),
+      trustContext,
+      conversationId: "conv-1",
+      question,
+    });
+    expect(result).toMatchObject({
+      skipped: true,
+      reason: "no_guardian_binding",
+    });
+    expect(emitSignalMock).not.toHaveBeenCalled();
+  });
+
+  test("skips emission when the binding identity no longer matches (rebind guard)", async () => {
+    binding = { guardianExternalUserId: "tg-someone-else" };
+    const result = await bridgeQuestionRequestToGuardian({
+      guardianRequest: makeRequest(),
+      trustContext,
+      conversationId: "conv-1",
+      question,
+    });
+    expect(result).toMatchObject({
+      skipped: true,
+      reason: "binding_identity_mismatch",
+    });
+    expect(emitSignalMock).not.toHaveBeenCalled();
+  });
+});