@vellumai/assistant 0.3.5 → 0.3.6

package/src/runtime/http-types.ts

@@ -1,17 +1,66 @@
 /**
  * Shared types for the runtime HTTP server and its route handlers.
  */
+import type { ChannelId } from '../channels/types.js';
 import type { RunOrchestrator } from './run-orchestrator.js';
 import type { GuardianRuntimeContext } from '../daemon/session-runtime-assembly.js';
+import type { ApprovalMessageContext, ComposeApprovalMessageGenerativeOptions } from './approval-message-composer.js';
+
+/**
+ * Daemon-injected function that generates approval copy using a provider.
+ * Returns generated text or `null` on failure (caller falls back to deterministic text).
+ */
+export type ApprovalCopyGenerator = (
+  context: ApprovalMessageContext,
+  options?: ComposeApprovalMessageGenerativeOptions,
+) => Promise<string | null>;
+
+// ---------------------------------------------------------------------------
+// Approval conversation flow types
+// ---------------------------------------------------------------------------
+
+/** The disposition returned by the approval conversation engine. */
+export type ApprovalConversationDisposition =
+  | 'keep_pending'
+  | 'approve_once'
+  | 'approve_always'
+  | 'reject';
+
+/** Structured result from a single turn of the approval conversation. */
+export interface ApprovalConversationResult {
+  disposition: ApprovalConversationDisposition;
+  replyText: string;
+  /** Required when there are multiple pending approvals and the disposition is decision-bearing. */
+  targetRunId?: string;
+}
+
+/** Input context for the approval conversation engine. */
+export interface ApprovalConversationContext {
+  toolName: string;
+  allowedActions: string[];
+  role: 'requester' | 'guardian';
+  pendingApprovals: Array<{ runId: string; toolName: string }>;
+  userMessage: string;
+}
+
+/**
+ * Daemon-injected function that processes one turn of an approval conversation.
+ * Takes conversation context and returns a structured approval decision + reply.
+ */
+export type ApprovalConversationGenerator = (
+  context: ApprovalConversationContext,
+) => Promise<ApprovalConversationResult>;
 
 export interface RuntimeMessageSessionOptions {
   transport?: {
-    channelId: string;
+    channelId: ChannelId;
     hints?: string[];
     uxBrief?: string;
   };
   assistantId?: string;
   guardianContext?: GuardianRuntimeContext;
+  /** Channel command intent metadata (e.g. Telegram /start). */
+  commandIntent?: { type: string; payload?: string; languageCode?: string };
 }
 
 export type MessageProcessor = (
@@ -19,7 +68,7 @@ export type MessageProcessor = (
   content: string,
   attachmentIds?: string[],
   options?: RuntimeMessageSessionOptions,
-  sourceChannel?: string,
+  sourceChannel?: ChannelId,
 ) => Promise<{ messageId: string }>;
 
 /**
@@ -32,7 +81,7 @@ export type NonBlockingMessageProcessor = (
   content: string,
   attachmentIds?: string[],
   options?: RuntimeMessageSessionOptions,
-  sourceChannel?: string,
+  sourceChannel?: ChannelId,
 ) => Promise<{ messageId: string }>;
 
 export interface RuntimeHttpServerOptions {
@@ -48,6 +97,10 @@ export interface RuntimeHttpServerOptions {
   runOrchestrator?: RunOrchestrator;
   /** Root directory for interface files on disk. */
   interfacesDir?: string;
+  /** Daemon-injected generator for approval copy (provider-backed). */
+  approvalCopyGenerator?: ApprovalCopyGenerator;
+  /** Daemon-injected generator for conversational approval flow (provider-backed). */
+  approvalConversationGenerator?: ApprovalConversationGenerator;
 }
 
 export interface RuntimeAttachmentMetadata {

package/src/runtime/middleware/auth.ts

@@ -0,0 +1,116 @@
+/**
+ * Auth middleware: bearer token validation, private network checks,
+ * and gateway-origin verification.
+ */
+
+import { timingSafeEqual } from 'node:crypto';
+
+/**
+ * Constant-time comparison of two bearer tokens to prevent timing attacks.
+ */
+export function verifyBearerToken(provided: string, expected: string): boolean {
+  const a = Buffer.from(provided);
+  const b = Buffer.from(expected);
+  if (a.length !== b.length) return false;
+  return timingSafeEqual(a, b);
+}
+
+/**
+ * Check if a hostname is a loopback address.
+ */
+export function isLoopbackHost(hostname: string): boolean {
+  return hostname === '127.0.0.1' || hostname === '::1' || hostname === 'localhost';
+}
+
+/**
+ * @internal Exported for testing.
+ *
+ * Determine whether an IP address string belongs to a private/internal
+ * network range:
+ *   - Loopback: 127.0.0.0/8, ::1
+ *   - RFC 1918: 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16
+ *   - Link-local: 169.254.0.0/16
+ *   - IPv6 unique local: fc00::/7 (fc00::--fdff::)
+ *   - IPv4-mapped IPv6 variants of all of the above (::ffff:x.x.x.x)
+ */
+export function isPrivateAddress(addr: string): boolean {
+  // Handle IPv4-mapped IPv6 (e.g. ::ffff:10.0.0.1) -- extract the IPv4 part
+  const v4Mapped = addr.match(/^::ffff:(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/i);
+  const normalized = v4Mapped ? v4Mapped[1] : addr;
+
+  // IPv4 checks
+  if (normalized.includes('.')) {
+    const parts = normalized.split('.').map(Number);
+    if (parts.length !== 4 || parts.some(p => isNaN(p) || p < 0 || p > 255)) return false;
+
+    // Loopback: 127.0.0.0/8
+    if (parts[0] === 127) return true;
+    // 10.0.0.0/8
+    if (parts[0] === 10) return true;
+    // 172.16.0.0/12 (172.16.x.x -- 172.31.x.x)
+    if (parts[0] === 172 && parts[1] >= 16 && parts[1] <= 31) return true;
+    // 192.168.0.0/16
+    if (parts[0] === 192 && parts[1] === 168) return true;
+    // Link-local: 169.254.0.0/16
+    if (parts[0] === 169 && parts[1] === 254) return true;
+
+    return false;
+  }
+
+  // IPv6 checks
+  const lower = normalized.toLowerCase();
+  // Loopback
+  if (lower === '::1') return true;
+  // Unique local: fc00::/7 (fc00:: through fdff::)
+  if (lower.startsWith('fc') || lower.startsWith('fd')) return true;
+  // Link-local: fe80::/10
+  if (lower.startsWith('fe80')) return true;
+
+  return false;
+}
+
+/**
+ * Check if the actual peer/remote address of a connection is from a
+ * private/internal network. Uses Bun's server.requestIP() to get the
+ * real peer address, which cannot be spoofed unlike the Origin header.
+ *
+ * Accepts loopback, RFC 1918 private IPv4, link-local, and RFC 4193
+ * unique-local IPv6 -- including their IPv4-mapped IPv6 forms. This
+ * supports container/pod deployments (e.g. Kubernetes sidecars) where
+ * gateway and runtime communicate over pod-internal private IPs.
+ */
+export function isPrivateNetworkPeer(server: { requestIP(req: Request): { address: string; family: string; port: number } | null }, req: Request): boolean {
+  const ip = server.requestIP(req);
+  if (!ip) return false;
+  return isPrivateAddress(ip.address);
+}
+
+/**
+ * Check if a request origin is from a private/internal network address.
+ * Extracts the hostname from the Origin header and validates it against
+ * isPrivateAddress(), consistent with the isPrivateNetworkPeer check.
+ */
+export function isPrivateNetworkOrigin(req: Request): boolean {
+  const origin = req.headers.get('origin');
+  // No origin header (e.g., server-initiated or same-origin) -- allow
+  if (!origin) return true;
+  try {
+    const url = new URL(origin);
+    const host = url.hostname;
+    if (host === 'localhost') return true;
+    // URL.hostname wraps IPv6 addresses in brackets (e.g. "[::1]") -- strip them
+    const rawHost = host.startsWith('[') && host.endsWith(']') ? host.slice(1, -1) : host;
+    return isPrivateAddress(rawHost);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Extract and validate a bearer token from the Authorization header.
+ * Returns the token string if present, or null.
+ */
+export function extractBearerToken(req: Request): string | null {
+  const authHeader = req.headers.get('authorization');
+  return authHeader?.startsWith('Bearer ') ? authHeader.slice(7) : null;
+}

package/src/runtime/middleware/error-handler.ts

@@ -0,0 +1,33 @@
+/**
+ * Centralized error handling for runtime HTTP request dispatch.
+ */
+
+import { ConfigError, IngressBlockedError } from '../../util/errors.js';
+import { getLogger } from '../../util/logger.js';
+
+const log = getLogger('runtime-http');
+
+/**
+ * Wrap an async endpoint handler with standard error handling.
+ * Catches IngressBlockedError (422), ConfigError (422), and generic errors (500).
+ */
+export async function withErrorHandling(
+  endpoint: string,
+  handler: () => Promise<Response>,
+): Promise<Response> {
+  try {
+    return await handler();
+  } catch (err) {
+    if (err instanceof IngressBlockedError) {
+      log.warn({ endpoint, detectedTypes: err.detectedTypes }, 'Blocked HTTP request containing secrets');
+      return Response.json({ error: err.message, code: err.code }, { status: 422 });
+    }
+    if (err instanceof ConfigError) {
+      log.warn({ err, endpoint }, 'Runtime HTTP config error');
+      return Response.json({ error: err.message, code: err.code }, { status: 422 });
+    }
+    log.error({ err, endpoint }, 'Runtime HTTP handler error');
+    const message = err instanceof Error ? err.message : 'Internal server error';
+    return Response.json({ error: message }, { status: 500 });
+  }
+}

package/src/runtime/middleware/twilio-validation.ts

@@ -0,0 +1,127 @@
+/**
+ * Twilio webhook signature validation and related constants.
+ */
+
+import { getLogger } from '../../util/logger.js';
+import { isTwilioWebhookValidationDisabled } from '../../config/env.js';
+import { TwilioConversationRelayProvider } from '../../calls/twilio-provider.js';
+import { loadConfig } from '../../config/loader.js';
+import { getPublicBaseUrl } from '../../inbound/public-ingress-urls.js';
+
+const log = getLogger('runtime-http');
+
+/**
+ * Regex to extract the Twilio webhook subpath from both top-level and
+ * assistant-scoped route shapes:
+ *   /v1/calls/twilio/<subpath>
+ *   /v1/assistants/<id>/calls/twilio/<subpath>
+ */
+export const TWILIO_WEBHOOK_RE = /^\/v1\/(?:assistants\/[^/]+\/)?calls\/twilio\/(.+)$/;
+
+/**
+ * Gateway-compatible Twilio webhook paths:
+ *   /webhooks/twilio/<subpath>
+ *
+ * Maps gateway path segments to the internal subpath names used by the
+ * dispatcher below (e.g. "voice" -> "voice-webhook").
+ */
+export const TWILIO_GATEWAY_WEBHOOK_RE = /^\/webhooks\/twilio\/(.+)$/;
+export const GATEWAY_SUBPATH_MAP: Record<string, string> = {
+  voice: 'voice-webhook',
+  status: 'status',
+  'connect-action': 'connect-action',
+  sms: 'sms',
+};
+
+/**
+ * Direct Twilio webhook subpaths that are blocked in gateway_only mode.
+ * Includes all public-facing webhook paths (voice, status, connect-action, SMS)
+ * because the runtime must never serve as a direct ingress for external webhooks.
+ * Internal forwarding endpoints (gateway->runtime) are unaffected.
+ */
+export const GATEWAY_ONLY_BLOCKED_SUBPATHS = new Set(['voice-webhook', 'status', 'connect-action', 'sms']);
+
+/**
+ * Validate a Twilio webhook request's X-Twilio-Signature header.
+ *
+ * Returns the raw body text on success so callers can reconstruct the Request
+ * for downstream handlers (which also need to read the body).
+ * Returns a 403 Response if signature validation fails.
+ *
+ * Fail-closed: if the auth token is not configured, the request is rejected
+ * with 403 rather than silently skipping validation. An explicit local-dev
+ * bypass is available via TWILIO_WEBHOOK_VALIDATION_DISABLED=true.
+ */
+export async function validateTwilioWebhook(
+  req: Request,
+): Promise<{ body: string } | Response> {
+  const rawBody = await req.text();
+
+  // Allow explicit local-dev bypass -- must be exactly "true"
+  if (isTwilioWebhookValidationDisabled()) {
+    log.warn('Twilio webhook signature validation explicitly disabled via TWILIO_WEBHOOK_VALIDATION_DISABLED');
+    return { body: rawBody };
+  }
+
+  const authToken = TwilioConversationRelayProvider.getAuthToken();
+
+  // Fail-closed: reject if no auth token is configured
+  if (!authToken) {
+    log.error('Twilio auth token not configured — rejecting webhook request (fail-closed)');
+    return Response.json({ error: 'Forbidden' }, { status: 403 });
+  }
+
+  const signature = req.headers.get('x-twilio-signature');
+  if (!signature) {
+    log.warn('Twilio webhook request missing X-Twilio-Signature header');
+    return Response.json({ error: 'Forbidden' }, { status: 403 });
+  }
+
+  // Parse form-urlencoded body into key-value params for signature computation
+  const params: Record<string, string> = {};
+  const formData = new URLSearchParams(rawBody);
+  for (const [key, value] of formData.entries()) {
+    params[key] = value;
+  }
+
+  // Reconstruct the public-facing URL that Twilio signed against.
+  // Behind proxies/gateways, req.url is the local server URL (e.g.
+  // http://127.0.0.1:7821/...) which differs from the public URL Twilio
+  // used to compute the HMAC-SHA1 signature.
+  let publicBaseUrl: string | undefined;
+  try {
+    publicBaseUrl = getPublicBaseUrl(loadConfig());
+  } catch {
+    // No webhook base URL configured -- fall back to using req.url as-is
+  }
+  const parsedUrl = new URL(req.url);
+  const publicUrl = publicBaseUrl
+    ? publicBaseUrl + parsedUrl.pathname + parsedUrl.search
+    : req.url;
+
+  const isValid = TwilioConversationRelayProvider.verifyWebhookSignature(
+    publicUrl,
+    params,
+    signature,
+    authToken,
+  );
+
+  if (!isValid) {
+    log.warn('Twilio webhook signature validation failed');
+    return Response.json({ error: 'Forbidden' }, { status: 403 });
+  }
+
+  return { body: rawBody };
+}
+
+/**
+ * Re-create a Request with the same method, headers, and URL but with a
+ * pre-read body string so downstream handlers can call req.text() again.
+ */
+export function cloneRequestWithBody(original: Request, body: string): Request {
+  return new Request(original.url, {
+    method: original.method,
+    headers: original.headers,
+    body,
+  });
+}

package/src/runtime/routes/app-routes.ts

@@ -22,7 +22,7 @@ const HTML_ESCAPE_MAP: Record<string, string> = {
 let designSystemCssCache: string | null = null;
 
 function loadDesignSystemCss(): string {
-  if (designSystemCssCache !== null) return designSystemCssCache;
+  if (designSystemCssCache != null) return designSystemCssCache;
   try {
     const cssPath = join(
       import.meta.dirname ?? __dirname,

package/src/runtime/routes/call-routes.ts

@@ -12,10 +12,33 @@ import { startCall, getCallStatus, cancelCall, answerCall, relayInstruction } fr
 import { getConfig } from '../../config/loader.js';
 import { VALID_CALLER_IDENTITY_MODES } from '../../config/schema.js';
 
+// ── Idempotency cache ─────────────────────────────────────────────────────────
+// Stores serialized 201 responses keyed by idempotencyKey for 5 minutes so
+// that network-retry duplicates from the client don't start a second call.
+
+const IDEMPOTENCY_TTL_MS = 5 * 60 * 1000; // 5 minutes
+
+interface IdempotencyEntry {
+  body: unknown;
+  expiresAt: number;
+}
+
+const idempotencyCache = new Map<string, IdempotencyEntry>();
+
+function pruneIdempotencyCache(): void {
+  const now = Date.now();
+  for (const [key, entry] of idempotencyCache) {
+    if (entry.expiresAt <= now) idempotencyCache.delete(key);
+  }
+}
+
 /**
  * POST /v1/calls/start
  *
- * Body: { phoneNumber: string; task: string; context?: string; conversationId: string; callerIdentityMode?: 'assistant_number' | 'user_number' }
+ * Body: { phoneNumber: string; task: string; context?: string; conversationId: string; callerIdentityMode?: 'assistant_number' | 'user_number'; idempotencyKey?: string }
+ *
+ * Optional `idempotencyKey`: if supplied, duplicate requests with the same key
+ * within 5 minutes return the cached 201 response without starting a second call.
  */
 export async function handleStartCall(req: Request, assistantId: string = 'self'): Promise<Response> {
   if (!getConfig().calls.enabled) {
@@ -31,6 +54,7 @@ export async function handleStartCall(req: Request, assistantId: string = 'self'
     context?: string;
     conversationId?: string;
     callerIdentityMode?: 'assistant_number' | 'user_number';
+    idempotencyKey?: string;
   };
   try {
     body = await req.json() as typeof body;
@@ -38,7 +62,7 @@ export async function handleStartCall(req: Request, assistantId: string = 'self'
     return Response.json({ error: 'Invalid JSON in request body' }, { status: 400 });
   }
 
-  if (typeof body !== 'object' || body === null || Array.isArray(body)) {
+  if (typeof body !== 'object' || body == null || Array.isArray(body)) {
     return Response.json({ error: 'Request body must be a JSON object' }, { status: 400 });
   }
 
@@ -54,6 +78,19 @@ export async function handleStartCall(req: Request, assistantId: string = 'self'
     );
   }
 
+  // Idempotency check: return cached response for duplicate requests
+  const idempotencyKey = typeof body.idempotencyKey === 'string' && body.idempotencyKey
+    ? body.idempotencyKey
+    : null;
+
+  if (idempotencyKey) {
+    pruneIdempotencyCache();
+    const cached = idempotencyCache.get(idempotencyKey);
+    if (cached && cached.expiresAt > Date.now()) {
+      return Response.json(cached.body, { status: 201 });
+    }
+  }
+
   const result = await startCall({
     phoneNumber: body.phoneNumber ?? '',
     task: body.task ?? '',
@@ -67,14 +104,20 @@ export async function handleStartCall(req: Request, assistantId: string = 'self'
     return Response.json({ error: result.error }, { status: result.status ?? 500 });
   }
 
-  return Response.json({
+  const responseBody = {
     callSessionId: result.session.id,
     callSid: result.callSid,
     status: result.session.status,
     toNumber: result.session.toNumber,
     fromNumber: result.session.fromNumber,
     callerIdentityMode: result.callerIdentityMode,
-  }, { status: 201 });
+  };
+
+  if (idempotencyKey) {
+    idempotencyCache.set(idempotencyKey, { body: responseBody, expiresAt: Date.now() + IDEMPOTENCY_TTL_MS });
+  }
+
+  return Response.json(responseBody, { status: 201 });
 }
 
 /**
@@ -145,7 +188,7 @@ export async function handleAnswerCall(req: Request, callSessionId: string): Pro
     return Response.json({ error: 'Invalid JSON in request body' }, { status: 400 });
   }
 
-  if (typeof body !== 'object' || body === null || Array.isArray(body)) {
+  if (typeof body !== 'object' || body == null || Array.isArray(body)) {
     return Response.json({ error: 'Request body must be a JSON object' }, { status: 400 });
   }
 
@@ -174,7 +217,7 @@ export async function handleInstructionCall(req: Request, callSessionId: string)
     return Response.json({ error: 'Invalid JSON in request body' }, { status: 400 });
   }
 
-  if (typeof body !== 'object' || body === null || Array.isArray(body)) {
+  if (typeof body !== 'object' || body == null || Array.isArray(body)) {
     return Response.json({ error: 'Request body must be a JSON object' }, { status: 400 });
   }
 

package/src/runtime/routes/channel-delivery-routes.ts

@@ -0,0 +1,170 @@
+/**
+ * Channel delivery routes: delivery ack, dead letters, reply delivery,
+ * and post-decision delivery scheduling.
+ */
+import * as conversationStore from '../../memory/conversation-store.js';
+import * as attachmentsStore from '../../memory/attachments-store.js';
+import * as channelDeliveryStore from '../../memory/channel-delivery-store.js';
+import { renderHistoryContent } from '../../daemon/handlers.js';
+import { getLogger } from '../../util/logger.js';
+import { deliverChannelReply } from '../gateway-client.js';
+import type { RuntimeAttachmentMetadata } from '../http-types.js';
+import type { RunOrchestrator } from '../run-orchestrator.js';
+import { POST_DECISION_POLL_INTERVAL_MS, POST_DECISION_POLL_MAX_WAIT_MS } from './channel-route-shared.js';
+
+const log = getLogger('runtime-http');
+
+// ---------------------------------------------------------------------------
+// Dead letter management
+// ---------------------------------------------------------------------------
+
+export function handleListDeadLetters(): Response {
+  const events = channelDeliveryStore.getDeadLetterEvents();
+  return Response.json({ events });
+}
+
+export async function handleReplayDeadLetters(req: Request): Promise<Response> {
+  const body = await req.json() as { eventIds?: string[] };
+  const eventIds = body.eventIds;
+
+  if (!Array.isArray(eventIds) || eventIds.length === 0) {
+    return Response.json({ error: 'eventIds array is required' }, { status: 400 });
+  }
+
+  const replayed = channelDeliveryStore.replayDeadLetters(eventIds);
+  return Response.json({ replayed });
+}
+
+// ---------------------------------------------------------------------------
+// Delivery acknowledgement
+// ---------------------------------------------------------------------------
+
+export async function handleChannelDeliveryAck(req: Request): Promise<Response> {
+  const body = await req.json() as {
+    sourceChannel?: string;
+    externalChatId?: string;
+    externalMessageId?: string;
+  };
+
+  const { sourceChannel, externalChatId, externalMessageId } = body;
+
+  if (!sourceChannel || typeof sourceChannel !== 'string') {
+    return Response.json({ error: 'sourceChannel is required' }, { status: 400 });
+  }
+  if (!externalChatId || typeof externalChatId !== 'string') {
+    return Response.json({ error: 'externalChatId is required' }, { status: 400 });
+  }
+  if (!externalMessageId || typeof externalMessageId !== 'string') {
+    return Response.json({ error: 'externalMessageId is required' }, { status: 400 });
+  }
+
+  const acked = channelDeliveryStore.acknowledgeDelivery(
+    sourceChannel,
+    externalChatId,
+    externalMessageId,
+  );
+
+  if (!acked) {
+    return Response.json({ error: 'Inbound event not found' }, { status: 404 });
+  }
+
+  return new Response(null, { status: 204 });
+}
+
+// ---------------------------------------------------------------------------
+// Reply delivery via callback
+// ---------------------------------------------------------------------------
+
+export async function deliverReplyViaCallback(
+  conversationId: string,
+  externalChatId: string,
+  callbackUrl: string,
+  bearerToken?: string,
+  assistantId?: string,
+): Promise<void> {
+  const msgs = conversationStore.getMessages(conversationId);
+  for (let i = msgs.length - 1; i >= 0; i--) {
+    if (msgs[i].role === 'assistant') {
+      let parsed: unknown;
+      try { parsed = JSON.parse(msgs[i].content); } catch { parsed = msgs[i].content; }
+      const rendered = renderHistoryContent(parsed);
+
+      const linked = attachmentsStore.getAttachmentMetadataForMessage(msgs[i].id);
+      const replyAttachments: RuntimeAttachmentMetadata[] = linked.map((a) => ({
+        id: a.id,
+        filename: a.originalFilename,
+        mimeType: a.mimeType,
+        sizeBytes: a.sizeBytes,
+        kind: a.kind,
+      }));
+
+      if (rendered.text || replyAttachments.length > 0) {
+        await deliverChannelReply(callbackUrl, {
+          chatId: externalChatId,
+          text: rendered.text || undefined,
+          attachments: replyAttachments.length > 0 ? replyAttachments : undefined,
+          assistantId,
+        }, bearerToken);
+      }
+      break;
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Post-decision delivery scheduling
+// ---------------------------------------------------------------------------
+
+/**
+ * Fire-and-forget: after a decision is applied via `handleApprovalInterception`,
+ * poll the run briefly for terminal state and deliver the final reply. This
+ * handles the case where the original poll in `processChannelMessageWithApprovals`
+ * has already exited due to the 5-minute timeout.
+ *
+ * Uses the same `claimRunDelivery` guard as the main poll to guarantee
+ * at-most-once delivery: whichever poller reaches terminal state first
+ * claims the delivery, and the other silently skips it.
+ */
+export function schedulePostDecisionDelivery(
+  orchestrator: RunOrchestrator,
+  runId: string,
+  conversationId: string,
+  externalChatId: string,
+  replyCallbackUrl: string,
+  bearerToken?: string,
+  assistantId?: string,
+): void {
+  (async () => {
+    try {
+      const startTime = Date.now();
+      while (Date.now() - startTime < POST_DECISION_POLL_MAX_WAIT_MS) {
+        await new Promise((resolve) => setTimeout(resolve, POST_DECISION_POLL_INTERVAL_MS));
+        const current = orchestrator.getRun(runId);
+        if (!current) break;
+        if (current.status === 'completed' || current.status === 'failed') {
+          if (channelDeliveryStore.claimRunDelivery(runId)) {
+            try {
+              await deliverReplyViaCallback(
+                conversationId,
+                externalChatId,
+                replyCallbackUrl,
+                bearerToken,
+                assistantId,
+              );
+            } catch (deliveryErr) {
+              channelDeliveryStore.resetRunDeliveryClaim(runId);
+              throw deliveryErr;
+            }
+          }
+          return;
+        }
+      }
+      log.warn(
+        { runId, conversationId },
+        'Post-decision delivery poll timed out without run reaching terminal state',
+      );
+    } catch (err) {
+      log.error({ err, runId, conversationId }, 'Post-decision delivery failed');
+    }
+  })();
+}