vellum 0.2.13 → 0.2.14

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/events-routes.ts

@@ -8,64 +8,133 @@
  */
 
 import { getOrCreateConversation } from '../../memory/conversation-key-store.js';
-import { assistantEventHub } from '../assistant-event-hub.js';
-import { formatSseFrame } from '../assistant-event.js';
+import { assistantEventHub, AssistantEventHub } from '../assistant-event-hub.js';
+import { formatSseFrame, formatSseHeartbeat } from '../assistant-event.js';
 import type { AssistantEventSubscription } from '../assistant-event-hub.js';
 
+/** Keep-alive comment sent to idle clients every 30 s by default. */
+const DEFAULT_HEARTBEAT_INTERVAL_MS = 30_000;
+
 /**
  * Stream assistant events as Server-Sent Events for a specific conversation.
  *
  * Query params:
  *   conversationKey — required; scopes the stream to one conversation.
+ *
+ * Options (for testing):
+ *   hub               — override the event hub (defaults to process singleton).
+ *   heartbeatIntervalMs — how often to emit keep-alive comments (default 30 s).
  */
 export function handleSubscribeAssistantEvents(
   req: Request,
   url: URL,
+  options?: {
+    hub?: AssistantEventHub;
+    heartbeatIntervalMs?: number;
+  },
 ): Response {
   const conversationKey = url.searchParams.get('conversationKey');
   if (!conversationKey) {
     return Response.json({ error: 'conversationKey is required' }, { status: 400 });
   }
 
+  const hub = options?.hub ?? assistantEventHub;
+  const heartbeatIntervalMs = options?.heartbeatIntervalMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS;
+
   const mapping = getOrCreateConversation(conversationKey);
   const encoder = new TextEncoder();
-  let sub: AssistantEventSubscription | null = null;
+
+  // ── Eager subscribe ──────────────────────────────────────────────────────
+  // Subscribe before creating the ReadableStream so the callback and onEvict
+  // closures are in place before events can arrive.  `controllerRef` is set
+  // synchronously inside ReadableStream's start(), so it is non-null by the
+  // time any event or eviction fires.
+  // 'self' is the assistantId that RunOrchestrator assigns to all HTTP-run
+  // events (see buildAssistantEvent('self', ...) in run-orchestrator.ts).
+  let controllerRef: ReadableStreamDefaultController<Uint8Array> | null = null;
+  let heartbeatTimer: ReturnType<typeof setInterval> | null = null;
+  let sub!: AssistantEventSubscription;
+
+  function cleanup() {
+    if (heartbeatTimer) { clearInterval(heartbeatTimer); heartbeatTimer = null; }
+    try { controllerRef?.close(); } catch { /* already closed */ }
+  }
+
+  try {
+    sub = hub.subscribe(
+      { assistantId: 'self', sessionId: mapping.conversationId },
+      (event) => {
+        const controller = controllerRef;
+        if (!controller) return;
+        try {
+          // Shed stalled consumers: desiredSize <= 0 means the 16-event buffer
+          // is full and the client isn't draining it.
+          if (controller.desiredSize !== null && controller.desiredSize <= 0) {
+            sub.dispose();
+            cleanup();
+            return;
+          }
+          controller.enqueue(encoder.encode(formatSseFrame(event)));
+        } catch {
+          sub.dispose();
+          cleanup();
+        }
+      },
+      {
+        // Called by the hub when a newer connection evicts this one (capacity
+        // management: oldest subscriber out, newest in).
+        onEvict: cleanup,
+      },
+    );
+  } catch (err) {
+    if (err instanceof RangeError) {
+      return Response.json({ error: 'Too many concurrent connections' }, { status: 503 });
+    }
+    throw err;
+  }
 
   // Allow up to 16 queued frames before treating the consumer as stalled.
   // This absorbs normal token-stream bursts without prematurely closing the
   // connection, while still shedding genuinely slow clients.
-  const stream = new ReadableStream({
+  const stream = new ReadableStream<Uint8Array>({
     start(controller) {
-      // 'self' is the assistantId that RunOrchestrator assigns to all HTTP-run events
-      // (see buildAssistantEvent('self', ...) in run-orchestrator.ts). This endpoint
-      // is part of the HTTP runtime API, so only HTTP-run events are relevant here.
-      // IPC/daemon events use a different assistantId ('default') and reach desktop
-      // clients through a separate channel — they are intentionally excluded.
-      sub = assistantEventHub.subscribe(
-        { assistantId: 'self', sessionId: mapping.conversationId },
-        (event) => {
-          try {
-            // Shed stalled consumers: desiredSize <= 0 means the 16-event buffer
-            // is full and the client isn't draining it.
-            if (controller.desiredSize !== null && controller.desiredSize <= 0) {
-              sub?.dispose();
-              try { controller.close(); } catch { /* already closed */ }
-              return;
-            }
-            controller.enqueue(encoder.encode(formatSseFrame(event)));
-          } catch {
-            sub?.dispose();
+      controllerRef = controller;
+
+      // If the client already disconnected before start() ran, clean up
+      // immediately — the abort event fires once and won't be re-dispatched.
+      if (req.signal.aborted) {
+        sub.dispose();
+        cleanup();
+        return;
+      }
+
+      // Send a keep-alive comment on each interval to prevent proxies and
+      // load-balancers from treating idle connections as timed out.
+      heartbeatTimer = setInterval(() => {
+        try {
+          // Apply the same slow-consumer guard as the event path: stop
+          // feeding heartbeats into a queue the client is not draining.
+          if (controller.desiredSize !== null && controller.desiredSize <= 0) {
+            sub.dispose();
+            cleanup();
+            return;
           }
-        },
-      );
+          controller.enqueue(encoder.encode(formatSseHeartbeat()));
+        } catch {
+          // Controller already closed (e.g. client disconnected).
+          sub.dispose();
+          cleanup();
+        }
+      }, heartbeatIntervalMs);
 
       req.signal.addEventListener('abort', () => {
-        sub?.dispose();
-        try { controller.close(); } catch { /* already closed */ }
+        sub.dispose();
+        cleanup();
       }, { once: true });
     },
     cancel() {
-      sub?.dispose();
+      sub.dispose();
+      cleanup();
     },
   }, new CountQueuingStrategy({ highWaterMark: 16 }));
 

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

@@ -200,13 +200,8 @@ export async function handleAddTrustRule(
   }
 
   try {
-    // Intentionally omit executionTarget: core tools (bash, file_*, etc.)
-    // have no executionTarget in their PolicyContext, so a rule with one
-    // would never match and users would keep getting re-prompted.
-    addRule(confirmation.toolName, pattern, scope, decision, 100, {
-      principalKind: confirmation.principalKind,
-      principalId: confirmation.principalId,
-      principalVersion: confirmation.principalVersion,
+    addRule(confirmation.toolName, pattern, scope, decision, undefined, {
+      executionTarget: confirmation.executionTarget,
     });
     log.info(
       { tool: confirmation.toolName, pattern, scope, decision, runId },

package/src/runtime/run-orchestrator.ts

@@ -131,9 +131,6 @@ export class RunOrchestrator {
           executionTarget: msg.executionTarget,
           allowlistOptions: msg.allowlistOptions,
           scopeOptions: msg.scopeOptions,
-          principalKind: msg.principalKind,
-          principalId: msg.principalId,
-          principalVersion: msg.principalVersion,
           persistentDecisionsAllowed: msg.persistentDecisionsAllowed,
         });
         this.pending.set(run.id, {