vellum 0.2.1 → 0.2.7

package/src/runtime/http-server.ts

@@ -10,8 +10,9 @@ import { resolve } from 'node:path';
 import { timingSafeEqual } from 'node:crypto';
 import { ConfigError, IngressBlockedError } from '../util/errors.js';
 import { getLogger } from '../util/logger.js';
-import { getSecureKey } from '../security/secure-keys.js';
 import { TwilioConversationRelayProvider } from '../calls/twilio-provider.js';
+import { loadConfig } from '../config/loader.js';
+import { getWebhookBaseUrl } from '../calls/twilio-webhook-urls.js';
 import type { RunOrchestrator } from './run-orchestrator.js';
 
 // Route handlers — grouped by domain
@@ -39,6 +40,10 @@ import {
   handleReplayDeadLetters,
 } from './routes/channel-routes.js';
 import * as channelDeliveryStore from '../memory/channel-delivery-store.js';
+import * as conversationStore from '../memory/conversation-store.js';
+import * as attachmentsStore from '../memory/attachments-store.js';
+import { renderHistoryContent } from '../daemon/handlers.js';
+import { deliverChannelReply } from './gateway-client.js';
 import {
   handleServePage,
   handleShareApp,
@@ -47,11 +52,16 @@ import {
   handleDeleteSharedApp,
 } from './routes/app-routes.js';
 import { handleAddSecret } from './routes/secret-routes.js';
+import {
+  handleStartCall,
+  handleGetCallStatus,
+  handleCancelCall,
+  handleAnswerCall,
+} from './routes/call-routes.js';
 import {
   handleVoiceWebhook,
   handleStatusCallback,
   handleConnectAction,
-  handleCallAnswer,
 } from '../calls/twilio-routes.js';
 import { RelayConnection, activeRelayConnections } from '../calls/relay-server.js';
 import type { RelayWebSocketData } from '../calls/relay-server.js';
@@ -113,25 +123,50 @@ function getDiskSpaceInfo(): DiskSpaceInfo | null {
  */
 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").
+ */
+const TWILIO_GATEWAY_WEBHOOK_RE = /^\/webhooks\/twilio\/(.+)$/;
+const GATEWAY_SUBPATH_MAP: Record<string, string> = {
+  voice: 'voice-webhook',
+  status: 'status',
+  'connect-action': 'connect-action',
+};
+
 /**
  * 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.
- * If the Twilio auth token is not configured, skips validation with a warning.
+ *
+ * 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.
  */
 async function validateTwilioWebhook(
   req: Request,
 ): Promise<{ body: string } | Response> {
   const rawBody = await req.text();
-  const authToken = getSecureKey('twilio_auth_token');
 
-  if (!authToken) {
-    log.warn('Twilio auth token not configured — skipping webhook signature validation');
+  // Allow explicit local-dev bypass — must be exactly "true"
+  if (process.env.TWILIO_WEBHOOK_VALIDATION_DISABLED === 'true') {
+    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');
@@ -149,16 +184,22 @@ async function validateTwilioWebhook(
   // 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.
-  const publicBaseUrl = process.env.TWILIO_WEBHOOK_BASE_URL;
+  let publicBaseUrl: string | undefined;
+  try {
+    publicBaseUrl = getWebhookBaseUrl(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.replace(/\/$/, '') + parsedUrl.pathname + parsedUrl.search
+    ? publicBaseUrl + parsedUrl.pathname + parsedUrl.search
     : req.url;
 
   const isValid = TwilioConversationRelayProvider.verifyWebhookSignature(
     publicUrl,
     params,
     signature,
+    authToken,
   );
 
   if (!isValid) {
@@ -302,11 +343,18 @@ export class RuntimeHttpServer {
 
     // ── Twilio webhook endpoints — before auth check because Twilio
     //    webhook POSTs don't include bearer tokens.
-    //    Supports both /v1/calls/twilio/* and /v1/assistants/:id/calls/twilio/*
+    //    Supports /v1/calls/twilio/*, /v1/assistants/:id/calls/twilio/*,
+    //    and gateway-compatible /webhooks/twilio/* paths.
     //    Validates X-Twilio-Signature to prevent unauthorized access. ──
     const twilioMatch = path.match(TWILIO_WEBHOOK_RE);
-    if (twilioMatch && req.method === 'POST') {
-      const twilioSubpath = twilioMatch[1];
+    const gatewayTwilioMatch = !twilioMatch ? path.match(TWILIO_GATEWAY_WEBHOOK_RE) : null;
+    const resolvedTwilioSubpath = twilioMatch
+      ? twilioMatch[1]
+      : gatewayTwilioMatch
+        ? GATEWAY_SUBPATH_MAP[gatewayTwilioMatch[1]]
+        : null;
+    if (resolvedTwilioSubpath && req.method === 'POST') {
+      const twilioSubpath = resolvedTwilioSubpath;
 
       // Validate Twilio request signature before dispatching
       const validation = await validateTwilioWebhook(req);
@@ -335,17 +383,6 @@ export class RuntimeHttpServer {
       }
     }
 
-    // ── Call answer endpoint — behind auth gate ──────────────────────
-    const callAnswerMatch = path.match(/^\/v1\/calls\/([^/]+)\/answer$/);
-    if (callAnswerMatch && req.method === 'POST') {
-      try {
-        return await handleCallAnswer(req, callAnswerMatch[1]);
-      } catch (err) {
-        log.error({ err, callSessionId: callAnswerMatch[1] }, 'Runtime HTTP handler error answering call');
-        return Response.json({ error: 'Internal server error' }, { status: 500 });
-      }
-    }
-
     // Serve shareable app pages
     const pagesMatch = path.match(/^\/pages\/([^/]+)$/);
     if (pagesMatch && req.method === 'GET') {
@@ -529,6 +566,68 @@ export class RuntimeHttpServer {
         return await handleReplayDeadLetters(req);
       }
 
+      // ── Call API routes ───────────────────────────────────────────
+      if (endpoint === 'calls/start' && req.method === 'POST') {
+        return await handleStartCall(req);
+      }
+
+      // Match calls/:callSessionId and calls/:callSessionId/cancel, calls/:callSessionId/answer
+      const callsMatch = endpoint.match(/^calls\/([^/]+?)(\/cancel|\/answer)?$/);
+      if (callsMatch) {
+        const callSessionId = callsMatch[1];
+        // Skip known sub-paths that are handled elsewhere (twilio, relay)
+        if (callSessionId !== 'twilio' && callSessionId !== 'relay' && callSessionId !== 'start') {
+          if (callsMatch[2] === '/cancel' && req.method === 'POST') {
+            return await handleCancelCall(req, callSessionId);
+          }
+          if (callsMatch[2] === '/answer' && req.method === 'POST') {
+            return await handleAnswerCall(req, callSessionId);
+          }
+          if (!callsMatch[2] && req.method === 'GET') {
+            return handleGetCallStatus(callSessionId);
+          }
+        }
+      }
+
+      // ── Internal Twilio forwarding endpoints (gateway → runtime) ──
+      // These accept JSON payloads from the gateway (which already validated
+      // the Twilio signature) and reconstruct requests for the existing
+      // Twilio route handlers.
+      if (endpoint === 'internal/twilio/voice-webhook' && req.method === 'POST') {
+        const json = await req.json() as { params: Record<string, string>; originalUrl?: string };
+        const formBody = new URLSearchParams(json.params).toString();
+        // Reconstruct request URL: keep the original URL query string (callSessionId)
+        const reconstructedUrl = json.originalUrl ?? req.url;
+        const fakeReq = new Request(reconstructedUrl, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+          body: formBody,
+        });
+        return await handleVoiceWebhook(fakeReq);
+      }
+
+      if (endpoint === 'internal/twilio/status' && req.method === 'POST') {
+        const json = await req.json() as { params: Record<string, string> };
+        const formBody = new URLSearchParams(json.params).toString();
+        const fakeReq = new Request(req.url, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+          body: formBody,
+        });
+        return await handleStatusCallback(fakeReq);
+      }
+
+      if (endpoint === 'internal/twilio/connect-action' && req.method === 'POST') {
+        const json = await req.json() as { params: Record<string, string> };
+        const formBody = new URLSearchParams(json.params).toString();
+        const fakeReq = new Request(req.url, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+          body: formBody,
+        });
+        return await handleConnectAction(fakeReq);
+      }
+
       return Response.json({ error: 'Not found', source: 'runtime' }, { status: 404 });
     } catch (err) {
       if (err instanceof IngressBlockedError) {
@@ -607,6 +706,18 @@ export class RuntimeHttpServer {
         channelDeliveryStore.linkMessage(event.id, userMessageId);
         channelDeliveryStore.markProcessed(event.id);
         log.info({ eventId: event.id }, 'Successfully replayed failed channel event');
+
+        const replyCallbackUrl = typeof payload.replyCallbackUrl === 'string'
+          ? payload.replyCallbackUrl
+          : undefined;
+        if (replyCallbackUrl) {
+          const externalChatId = typeof payload.externalChatId === 'string'
+            ? payload.externalChatId
+            : undefined;
+          if (externalChatId) {
+            await this.deliverReplyViaCallback(event.conversationId, externalChatId, replyCallbackUrl);
+          }
+        }
       } catch (err) {
         log.error({ err, eventId: event.id }, 'Retry failed for channel event');
         channelDeliveryStore.recordProcessingFailure(event.id, err);
@@ -614,6 +725,39 @@ export class RuntimeHttpServer {
     }
   }
 
+  private async deliverReplyViaCallback(
+    conversationId: string,
+    externalChatId: string,
+    callbackUrl: 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 = 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,
+          });
+        }
+        break;
+      }
+    }
+  }
+
   private handleHealth(): Response {
     return Response.json({
       status: 'healthy',

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

@@ -56,7 +56,6 @@ export async function handleUploadAttachment(req: Request): Promise<Response> {
   let attachment: attachmentsStore.StoredAttachment;
   try {
     attachment = attachmentsStore.uploadAttachment(
-      "self",
       filename,
       mimeType,
       data,
@@ -98,7 +97,7 @@ export async function handleDeleteAttachment(req: Request): Promise<Response> {
     );
   }
 
-  const result = attachmentsStore.deleteAttachment("self", attachmentId);
+  const result = attachmentsStore.deleteAttachment(attachmentId);
 
   if (result === 'not_found') {
     return Response.json(
@@ -118,7 +117,7 @@ export async function handleDeleteAttachment(req: Request): Promise<Response> {
 }
 
 export function handleGetAttachment(attachmentId: string): Response {
-  const attachment = attachmentsStore.getAttachmentById("self", attachmentId);
+  const attachment = attachmentsStore.getAttachmentById(attachmentId);
   if (!attachment) {
     return Response.json({ error: 'Attachment not found' }, { status: 404 });
   }

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

@@ -0,0 +1,140 @@
+/**
+ * Runtime HTTP route handlers for the call API.
+ *
+ * POST   /v1/calls/start              — initiate a new call
+ * GET    /v1/calls/:callSessionId      — get call status
+ * POST   /v1/calls/:callSessionId/cancel — cancel a call
+ * POST   /v1/calls/:callSessionId/answer — answer a pending question
+ */
+
+import { startCall, getCallStatus, cancelCall, answerCall } from '../../calls/call-domain.js';
+import { getConfig } from '../../config/loader.js';
+
+/**
+ * POST /v1/calls/start
+ *
+ * Body: { phoneNumber: string; task: string; context?: string; conversationId: string }
+ */
+export async function handleStartCall(req: Request): Promise<Response> {
+  if (!getConfig().calls.enabled) {
+    return Response.json(
+      { error: 'Calls feature is disabled via configuration. Set calls.enabled to true to use this feature.' },
+      { status: 403 },
+    );
+  }
+
+  let body: {
+    phoneNumber?: string;
+    task?: string;
+    context?: string;
+    conversationId?: string;
+  };
+  try {
+    body = await req.json() as typeof body;
+  } catch {
+    return Response.json({ error: 'Invalid JSON in request body' }, { status: 400 });
+  }
+
+  if (!body.conversationId) {
+    return Response.json({ error: 'conversationId is required' }, { status: 400 });
+  }
+
+  const result = await startCall({
+    phoneNumber: body.phoneNumber ?? '',
+    task: body.task ?? '',
+    context: body.context,
+    conversationId: body.conversationId,
+  });
+
+  if (!result.ok) {
+    return Response.json({ error: result.error }, { status: result.status ?? 500 });
+  }
+
+  return Response.json({
+    callSessionId: result.session.id,
+    callSid: result.callSid,
+    status: result.session.status,
+    toNumber: result.session.toNumber,
+    fromNumber: result.session.fromNumber,
+  }, { status: 201 });
+}
+
+/**
+ * GET /v1/calls/:callSessionId
+ */
+export function handleGetCallStatus(callSessionId: string): Response {
+  const result = getCallStatus(callSessionId);
+
+  if (!result.ok) {
+    return Response.json({ error: result.error }, { status: result.status ?? 500 });
+  }
+
+  const { session } = result;
+  return Response.json({
+    callSessionId: session.id,
+    conversationId: session.conversationId,
+    status: session.status,
+    toNumber: session.toNumber,
+    fromNumber: session.fromNumber,
+    provider: session.provider,
+    providerCallSid: session.providerCallSid,
+    task: session.task,
+    startedAt: session.startedAt ? new Date(session.startedAt).toISOString() : null,
+    endedAt: session.endedAt ? new Date(session.endedAt).toISOString() : null,
+    lastError: session.lastError,
+    pendingQuestion: result.pendingQuestion ?? null,
+    createdAt: new Date(session.createdAt).toISOString(),
+    updatedAt: new Date(session.updatedAt).toISOString(),
+  });
+}
+
+/**
+ * POST /v1/calls/:callSessionId/cancel
+ *
+ * Body: { reason?: string }
+ */
+export async function handleCancelCall(req: Request, callSessionId: string): Promise<Response> {
+  let reason: string | undefined;
+  try {
+    const body = await req.json() as { reason?: string };
+    reason = body.reason;
+  } catch {
+    // Empty body is fine
+  }
+
+  const result = await cancelCall({ callSessionId, reason });
+
+  if (!result.ok) {
+    return Response.json({ error: result.error }, { status: result.status ?? 500 });
+  }
+
+  return Response.json({
+    callSessionId: result.session.id,
+    status: result.session.status,
+  });
+}
+
+/**
+ * POST /v1/calls/:callSessionId/answer
+ *
+ * Body: { answer: string }
+ */
+export async function handleAnswerCall(req: Request, callSessionId: string): Promise<Response> {
+  let body: { answer?: string };
+  try {
+    body = await req.json() as typeof body;
+  } catch {
+    return Response.json({ error: 'Invalid JSON in request body' }, { status: 400 });
+  }
+
+  const result = await answerCall({
+    callSessionId,
+    answer: body.answer ?? '',
+  });
+
+  if (!result.ok) {
+    return Response.json({ error: result.error }, { status: result.status ?? 500 });
+  }
+
+  return Response.json({ ok: true, questionId: result.questionId });
+}