vellum 0.2.12 → 0.2.14

package/src/runtime/http-server.ts

@@ -44,6 +44,7 @@ import {
 } from './routes/channel-routes.js';
 import * as channelDeliveryStore from '../memory/channel-delivery-store.js';
 import * as conversationStore from '../memory/conversation-store.js';
+import * as externalConversationStore from '../memory/external-conversation-store.js';
 import * as attachmentsStore from '../memory/attachments-store.js';
 import { renderHistoryContent } from '../daemon/handlers.js';
 import { deliverChannelReply } from './gateway-client.js';
@@ -60,6 +61,7 @@ import {
   handleGetCallStatus,
   handleCancelCall,
   handleAnswerCall,
+  handleInstructionCall,
 } from './routes/call-routes.js';
 import {
   handleVoiceWebhook,
@@ -616,13 +618,28 @@ export class RuntimeHttpServer {
       if (endpoint === 'conversations' && req.method === 'GET') {
         const limit = Number(url.searchParams.get('limit') ?? 50);
         const conversations = conversationStore.listConversations(limit);
+        const bindings = externalConversationStore.getBindingsForConversations(
+          conversations.map((c) => c.id),
+        );
         return Response.json({
-          sessions: conversations.map((c) => ({
-            id: c.id,
-            title: c.title ?? 'Untitled',
-            updatedAt: c.updatedAt,
-            threadType: c.threadType === 'private' ? 'private' : 'standard',
-          })),
+          sessions: conversations.map((c) => {
+            const binding = bindings.get(c.id);
+            return {
+              id: c.id,
+              title: c.title ?? 'Untitled',
+              updatedAt: c.updatedAt,
+              threadType: c.threadType === 'private' ? 'private' : 'standard',
+              ...(binding ? {
+                channelBinding: {
+                  sourceChannel: binding.sourceChannel,
+                  externalChatId: binding.externalChatId,
+                  externalUserId: binding.externalUserId,
+                  displayName: binding.displayName,
+                  username: binding.username,
+                },
+              } : {}),
+            };
+          }),
         });
       }
 
@@ -700,7 +717,7 @@ export class RuntimeHttpServer {
       }
 
       if (endpoint === 'channels/inbound' && req.method === 'POST') {
-        return await handleChannelInbound(req, this.processMessage, this.bearerToken);
+        return await handleChannelInbound(req, this.processMessage, this.bearerToken, this.runOrchestrator);
       }
 
       if (endpoint === 'channels/delivery-ack' && req.method === 'POST') {
@@ -720,8 +737,8 @@ export class RuntimeHttpServer {
         return await handleStartCall(req);
       }
 
-      // Match calls/:callSessionId and calls/:callSessionId/cancel, calls/:callSessionId/answer
-      const callsMatch = endpoint.match(/^calls\/([^/]+?)(\/cancel|\/answer)?$/);
+      // Match calls/:callSessionId and calls/:callSessionId/cancel, calls/:callSessionId/answer, calls/:callSessionId/instruction
+      const callsMatch = endpoint.match(/^calls\/([^/]+?)(\/cancel|\/answer|\/instruction)?$/);
       if (callsMatch) {
         const callSessionId = callsMatch[1];
         // Skip known sub-paths that are handled elsewhere (twilio, relay)
@@ -732,6 +749,9 @@ export class RuntimeHttpServer {
           if (callsMatch[2] === '/answer' && req.method === 'POST') {
             return await handleAnswerCall(req, callSessionId);
           }
+          if (callsMatch[2] === '/instruction' && req.method === 'POST') {
+            return await handleInstructionCall(req, callSessionId);
+          }
           if (!callsMatch[2] && req.method === 'GET') {
             return handleGetCallStatus(callSessionId);
           }

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

@@ -5,15 +5,17 @@
  * GET    /v1/calls/:callSessionId      — get call status
  * POST   /v1/calls/:callSessionId/cancel — cancel a call
  * POST   /v1/calls/:callSessionId/answer — answer a pending question
+ * POST   /v1/calls/:callSessionId/instruction — relay an instruction to an active call
  */
 
-import { startCall, getCallStatus, cancelCall, answerCall } from '../../calls/call-domain.js';
+import { startCall, getCallStatus, cancelCall, answerCall, relayInstruction } from '../../calls/call-domain.js';
 import { getConfig } from '../../config/loader.js';
+import { VALID_CALLER_IDENTITY_MODES } from '../../config/schema.js';
 
 /**
  * POST /v1/calls/start
  *
- * Body: { phoneNumber: string; task: string; context?: string; conversationId: string }
+ * Body: { phoneNumber: string; task: string; context?: string; conversationId: string; callerIdentityMode?: 'assistant_number' | 'user_number' }
  */
 export async function handleStartCall(req: Request): Promise<Response> {
   if (!getConfig().calls.enabled) {
@@ -28,6 +30,7 @@ export async function handleStartCall(req: Request): Promise<Response> {
     task?: string;
     context?: string;
     conversationId?: string;
+    callerIdentityMode?: 'assistant_number' | 'user_number';
   };
   try {
     body = await req.json() as typeof body;
@@ -35,15 +38,28 @@ export async function handleStartCall(req: Request): Promise<Response> {
     return Response.json({ error: 'Invalid JSON in request body' }, { status: 400 });
   }
 
+  if (typeof body !== 'object' || body === null || Array.isArray(body)) {
+    return Response.json({ error: 'Request body must be a JSON object' }, { status: 400 });
+  }
+
   if (!body.conversationId) {
     return Response.json({ error: 'conversationId is required' }, { status: 400 });
   }
 
+  if (body.callerIdentityMode != null &&
+      !(VALID_CALLER_IDENTITY_MODES as readonly string[]).includes(body.callerIdentityMode as string)) {
+    return Response.json(
+      { error: `Invalid callerIdentityMode: "${body.callerIdentityMode}". Must be one of: ${VALID_CALLER_IDENTITY_MODES.join(', ')}` },
+      { status: 400 },
+    );
+  }
+
   const result = await startCall({
     phoneNumber: body.phoneNumber ?? '',
     task: body.task ?? '',
     context: body.context,
     conversationId: body.conversationId,
+    callerIdentityMode: body.callerIdentityMode,
   });
 
   if (!result.ok) {
@@ -56,6 +72,7 @@ export async function handleStartCall(req: Request): Promise<Response> {
     status: result.session.status,
     toNumber: result.session.toNumber,
     fromNumber: result.session.fromNumber,
+    callerIdentityMode: result.callerIdentityMode,
   }, { status: 201 });
 }
 
@@ -127,6 +144,10 @@ 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)) {
+    return Response.json({ error: 'Request body must be a JSON object' }, { status: 400 });
+  }
+
   const result = await answerCall({
     callSessionId,
     answer: body.answer ?? '',
@@ -138,3 +159,32 @@ export async function handleAnswerCall(req: Request, callSessionId: string): Pro
 
   return Response.json({ ok: true, questionId: result.questionId });
 }
+
+/**
+ * POST /v1/calls/:callSessionId/instruction
+ *
+ * Body: { instruction: string }
+ */
+export async function handleInstructionCall(req: Request, callSessionId: string): Promise<Response> {
+  let body: { instruction?: string };
+  try {
+    body = await req.json() as typeof body;
+  } catch {
+    return Response.json({ error: 'Invalid JSON in request body' }, { status: 400 });
+  }
+
+  if (typeof body !== 'object' || body === null || Array.isArray(body)) {
+    return Response.json({ error: 'Request body must be a JSON object' }, { status: 400 });
+  }
+
+  const result = await relayInstruction({
+    callSessionId,
+    instructionText: body.instruction ?? '',
+  });
+
+  if (!result.ok) {
+    return Response.json({ error: result.error }, { status: result.status ?? 500 });
+  }
+
+  return Response.json({ ok: true });
+}

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

@@ -6,11 +6,22 @@ import { deleteConversationKey } from '../../memory/conversation-key-store.js';
 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 * as externalConversationStore from '../../memory/external-conversation-store.js';
+import { getPendingConfirmationsByConversation } from '../../memory/runs-store.js';
 import { renderHistoryContent } from '../../daemon/handlers.js';
 import { checkIngressForSecrets } from '../../security/secret-ingress.js';
 import { IngressBlockedError } from '../../util/errors.js';
 import { getLogger } from '../../util/logger.js';
-import { deliverChannelReply } from '../gateway-client.js';
+import { deliverChannelReply, deliverApprovalPrompt } from '../gateway-client.js';
+import { parseApprovalDecision } from '../channel-approval-parser.js';
+import {
+  getChannelApprovalPrompt,
+  buildApprovalUIMetadata,
+  handleChannelDecision,
+  buildReminderPrompt,
+} from '../channel-approvals.js';
+import type { ApprovalAction, ApprovalDecisionResult } from '../channel-approval-types.js';
+import type { RunOrchestrator } from '../run-orchestrator.js';
 import type {
   MessageProcessor,
   RuntimeAttachmentMetadata,
@@ -18,6 +29,32 @@ import type {
 
 const log = getLogger('runtime-http');
 
+// ---------------------------------------------------------------------------
+// Feature flag
+// ---------------------------------------------------------------------------
+
+export function isChannelApprovalsEnabled(): boolean {
+  return process.env.CHANNEL_APPROVALS_ENABLED === 'true';
+}
+
+// ---------------------------------------------------------------------------
+// Callback data parser — format: "apr:<runId>:<action>"
+// ---------------------------------------------------------------------------
+
+const VALID_ACTIONS: ReadonlySet<string> = new Set<string>([
+  'approve_once',
+  'approve_always',
+  'reject',
+]);
+
+function parseCallbackData(data: string): ApprovalDecisionResult | null {
+  const parts = data.split(':');
+  if (parts.length < 3 || parts[0] !== 'apr') return null;
+  const action = parts.slice(2).join(':');
+  if (!VALID_ACTIONS.has(action)) return null;
+  return { action: action as ApprovalAction, source: 'telegram_button' };
+}
+
 export async function handleDeleteConversation(req: Request): Promise<Response> {
   const body = await req.json() as {
     sourceChannel?: string;
@@ -35,6 +72,7 @@ export async function handleDeleteConversation(req: Request): Promise<Response>
 
   const conversationKey = `${sourceChannel}:${externalChatId}`;
   deleteConversationKey(conversationKey);
+  externalConversationStore.deleteBindingByChannelChat(sourceChannel, externalChatId);
 
   return Response.json({ ok: true });
 }
@@ -43,6 +81,7 @@ export async function handleChannelInbound(
   req: Request,
   processMessage?: MessageProcessor,
   bearerToken?: string,
+  runOrchestrator?: RunOrchestrator,
 ): Promise<Response> {
   const body = await req.json() as {
     sourceChannel?: string;
@@ -56,6 +95,8 @@ export async function handleChannelInbound(
     senderUsername?: string;
     sourceMetadata?: Record<string, unknown>;
     replyCallbackUrl?: string;
+    callbackQueryId?: string;
+    callbackData?: string;
   };
 
   const {
@@ -179,6 +220,16 @@ export async function handleChannelInbound(
     { sourceMessageId },
   );
 
+  // Upsert external conversation binding with sender metadata
+  externalConversationStore.upsertBinding({
+    conversationId: result.conversationId,
+    sourceChannel,
+    externalChatId,
+    externalUserId: body.senderExternalUserId ?? null,
+    displayName: body.senderName ?? null,
+    username: body.senderUsername ?? null,
+  });
+
   const metadataHintsRaw = sourceMetadata?.hints;
   const metadataHints = Array.isArray(metadataHintsRaw)
     ? metadataHintsRaw.filter((hint): hint is string => typeof hint === 'string' && hint.trim().length > 0)
@@ -189,6 +240,33 @@ export async function handleChannelInbound(
 
   const replyCallbackUrl = body.replyCallbackUrl;
 
+  // ── Approval interception (gated behind feature flag) ──
+  if (
+    isChannelApprovalsEnabled() &&
+    runOrchestrator &&
+    replyCallbackUrl &&
+    !result.duplicate
+  ) {
+    const approvalResult = await handleApprovalInterception({
+      conversationId: result.conversationId,
+      callbackData: body.callbackData,
+      content: trimmedContent,
+      externalChatId,
+      replyCallbackUrl,
+      bearerToken,
+      orchestrator: runOrchestrator,
+    });
+
+    if (approvalResult.handled) {
+      return Response.json({
+        accepted: true,
+        duplicate: false,
+        eventId: result.eventId,
+        approval: approvalResult.type,
+      });
+    }
+  }
+
   // For new (non-duplicate) messages, run the secret ingress check
   // synchronously, then fire off the agent loop in the background.
   if (!result.duplicate && processMessage) {
@@ -217,21 +295,40 @@ export async function handleChannelInbound(
       throw new IngressBlockedError(ingressCheck.userNotice!, ingressCheck.detectedTypes);
     }
 
-    // Fire-and-forget: process the message and deliver the reply in the background.
-    // The HTTP response returns immediately so the gateway webhook is not blocked.
-    processChannelMessageInBackground({
-      processMessage,
-      conversationId: result.conversationId,
-      eventId: result.eventId,
-      content: content ?? '',
-      attachmentIds: hasAttachments ? attachmentIds : undefined,
-      sourceChannel,
-      externalChatId,
-      metadataHints,
-      metadataUxBrief,
-      replyCallbackUrl,
-      bearerToken,
-    });
+    // When approval flow is enabled and we have an orchestrator, use the
+    // orchestrator-backed path which properly intercepts confirmation_request
+    // events and sends proactive approval prompts to the channel.
+    const useApprovalPath =
+      isChannelApprovalsEnabled() && runOrchestrator && replyCallbackUrl;
+
+    if (useApprovalPath) {
+      processChannelMessageWithApprovals({
+        orchestrator: runOrchestrator,
+        conversationId: result.conversationId,
+        eventId: result.eventId,
+        content: content ?? '',
+        attachmentIds: hasAttachments ? attachmentIds : undefined,
+        externalChatId,
+        replyCallbackUrl,
+        bearerToken,
+      });
+    } else {
+      // Fire-and-forget: process the message and deliver the reply in the background.
+      // The HTTP response returns immediately so the gateway webhook is not blocked.
+      processChannelMessageInBackground({
+        processMessage,
+        conversationId: result.conversationId,
+        eventId: result.eventId,
+        content: content ?? '',
+        attachmentIds: hasAttachments ? attachmentIds : undefined,
+        sourceChannel,
+        externalChatId,
+        metadataHints,
+        metadataUxBrief,
+        replyCallbackUrl,
+        bearerToken,
+      });
+    }
   }
 
   return Response.json({
@@ -298,6 +395,189 @@ function processChannelMessageInBackground(params: BackgroundProcessingParams):
   })();
 }
 
+// ---------------------------------------------------------------------------
+// Orchestrator-backed channel processing with approval prompt delivery
+// ---------------------------------------------------------------------------
+
+const RUN_POLL_INTERVAL_MS = 500;
+const RUN_POLL_MAX_WAIT_MS = 300_000; // 5 minutes
+
+interface ApprovalProcessingParams {
+  orchestrator: RunOrchestrator;
+  conversationId: string;
+  eventId: string;
+  content: string;
+  attachmentIds?: string[];
+  externalChatId: string;
+  replyCallbackUrl: string;
+  bearerToken?: string;
+}
+
+/**
+ * Process a channel message using the run orchestrator so that
+ * `confirmation_request` events are intercepted and written to the
+ * runs store. Polls the run until it reaches a terminal state,
+ * sending approval prompts when `needs_confirmation` is detected.
+ */
+function processChannelMessageWithApprovals(params: ApprovalProcessingParams): void {
+  const {
+    orchestrator,
+    conversationId,
+    eventId,
+    content,
+    attachmentIds,
+    externalChatId,
+    replyCallbackUrl,
+    bearerToken,
+  } = params;
+
+  (async () => {
+    try {
+      const run = await orchestrator.startRun(conversationId, content, attachmentIds);
+
+      // Poll the run until it reaches a terminal state, delivering approval
+      // prompts when it transitions to needs_confirmation.
+      const startTime = Date.now();
+      let lastStatus = run.status;
+
+      while (Date.now() - startTime < RUN_POLL_MAX_WAIT_MS) {
+        await new Promise((resolve) => setTimeout(resolve, RUN_POLL_INTERVAL_MS));
+
+        const current = orchestrator.getRun(run.id);
+        if (!current) break;
+
+        if (current.status === 'needs_confirmation' && lastStatus !== 'needs_confirmation') {
+          // Run just transitioned to needs_confirmation — send approval prompt
+          const prompt = getChannelApprovalPrompt(conversationId);
+          if (prompt) {
+            const pending = getPendingConfirmationsByConversation(conversationId);
+            if (pending.length > 0) {
+              const uiMetadata = buildApprovalUIMetadata(prompt, pending[0]);
+              try {
+                await deliverApprovalPrompt(
+                  replyCallbackUrl,
+                  externalChatId,
+                  prompt.promptText,
+                  uiMetadata,
+                  bearerToken,
+                );
+              } catch (err) {
+                log.error({ err, runId: run.id }, 'Failed to deliver approval prompt for channel run');
+              }
+            }
+          }
+        }
+
+        lastStatus = current.status;
+
+        if (current.status === 'completed' || current.status === 'failed') {
+          break;
+        }
+      }
+
+      channelDeliveryStore.markProcessed(eventId);
+
+      // Deliver the final assistant reply
+      await deliverReplyViaCallback(conversationId, externalChatId, replyCallbackUrl, bearerToken);
+    } catch (err) {
+      log.error({ err, conversationId }, 'Approval-aware channel message processing failed');
+      channelDeliveryStore.recordProcessingFailure(eventId, err);
+    }
+  })();
+}
+
+// ---------------------------------------------------------------------------
+// Approval interception
+// ---------------------------------------------------------------------------
+
+interface ApprovalInterceptionParams {
+  conversationId: string;
+  callbackData?: string;
+  content: string;
+  externalChatId: string;
+  replyCallbackUrl: string;
+  bearerToken?: string;
+  orchestrator: RunOrchestrator;
+}
+
+interface ApprovalInterceptionResult {
+  handled: boolean;
+  type?: 'decision_applied' | 'reminder_sent';
+}
+
+/**
+ * Check for pending approvals and handle inbound messages accordingly.
+ *
+ * Returns `{ handled: true }` when the message was consumed by the approval
+ * flow (either as a decision or a reminder), so the caller should NOT proceed
+ * to normal message processing.
+ */
+async function handleApprovalInterception(
+  params: ApprovalInterceptionParams,
+): Promise<ApprovalInterceptionResult> {
+  const {
+    conversationId,
+    callbackData,
+    content,
+    externalChatId,
+    replyCallbackUrl,
+    bearerToken,
+    orchestrator,
+  } = params;
+
+  const pendingPrompt = getChannelApprovalPrompt(conversationId);
+  if (!pendingPrompt) return { handled: false };
+
+  // Try to extract a decision from callback data (button press) first,
+  // then fall back to plain-text parsing.
+  let decision: ApprovalDecisionResult | null = null;
+
+  if (callbackData) {
+    decision = parseCallbackData(callbackData);
+  }
+
+  if (!decision && content) {
+    decision = parseApprovalDecision(content);
+  }
+
+  if (decision) {
+    const result = handleChannelDecision(conversationId, decision, orchestrator);
+
+    if (result.applied) {
+      // Deliver the run's result back to the channel once the decision is applied.
+      // The run will resume in the background; deliver whatever assistant reply
+      // is available now (there may not be one yet if the run is still processing).
+      try {
+        await deliverReplyViaCallback(conversationId, externalChatId, replyCallbackUrl, bearerToken);
+      } catch (err) {
+        log.error({ err, conversationId }, 'Failed to deliver post-decision reply');
+      }
+    }
+
+    return { handled: true, type: 'decision_applied' };
+  }
+
+  // The message is not a decision — send a reminder with the approval buttons.
+  const reminder = buildReminderPrompt(pendingPrompt);
+  const pending = getPendingConfirmationsByConversation(conversationId);
+  if (pending.length > 0) {
+    const uiMetadata = buildApprovalUIMetadata(reminder, pending[0]);
+    try {
+      await deliverApprovalPrompt(
+        replyCallbackUrl,
+        externalChatId,
+        reminder.promptText,
+        uiMetadata,
+        bearerToken,
+      );
+    } catch (err) {
+      log.error({ err, conversationId }, 'Failed to deliver approval reminder');
+    }
+  }
+
+  return { handled: true, type: 'reminder_sent' };
+}
+
 async function deliverReplyViaCallback(
   conversationId: string,
   externalChatId: string,

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

@@ -46,19 +46,26 @@ export function handleListMessages(
   url: URL,
   interfacesDir: string | null,
 ): Response {
+  const conversationId = url.searchParams.get('conversationId');
   const conversationKey = url.searchParams.get('conversationKey');
-  if (!conversationKey) {
+
+  let resolvedConversationId: string | undefined;
+  if (conversationId) {
+    resolvedConversationId = conversationId;
+  } else if (conversationKey) {
+    const mapping = getConversationByKey(conversationKey);
+    resolvedConversationId = mapping?.conversationId;
+  } else {
     return Response.json(
-      { error: 'conversationKey query parameter is required' },
+      { error: 'conversationKey or conversationId query parameter is required' },
       { status: 400 },
     );
   }
 
-  const mapping = getConversationByKey(conversationKey);
-  if (!mapping) {
+  if (!resolvedConversationId) {
     return Response.json({ messages: [] });
   }
-  const rawMessages = conversationStore.getMessages(mapping.conversationId);
+  const rawMessages = conversationStore.getMessages(resolvedConversationId);
 
   // Parse content blocks and extract text + tool calls
   const parsed = rawMessages.map((msg) => {