vellum 0.2.2 → 0.2.8

package/src/memory/runs-store.ts

@@ -36,7 +36,6 @@ export interface PendingConfirmation {
 
 export interface Run {
   id: string;
-  assistantId: string;
   conversationId: string;
   messageId: string | null;
   status: RunStatus;
@@ -66,7 +65,6 @@ function rowToRun(row: typeof messageRuns.$inferSelect): Run {
   }
   return {
     id: row.id,
-    assistantId: row.assistantId,
     conversationId: row.conversationId,
     messageId: row.messageId,
     status: row.status as RunStatus,
@@ -94,7 +92,6 @@ export function createRun(
 
   const row = {
     id,
-    assistantId: 'self',
     conversationId,
     messageId: messageId ?? null,
     status: 'running' as const,

package/src/memory/schema.ts

@@ -148,7 +148,6 @@ export const memoryJobs = sqliteTable('memory_jobs', {
 
 export const conversationKeys = sqliteTable('conversation_keys', {
   id: text('id').primaryKey(),
-  assistantId: text('assistant_id').notNull(),
   conversationKey: text('conversation_key').notNull(),
   conversationId: text('conversation_id')
     .notNull()
@@ -158,7 +157,6 @@ export const conversationKeys = sqliteTable('conversation_keys', {
 
 export const attachments = sqliteTable('attachments', {
   id: text('id').primaryKey(),
-  assistantId: text('assistant_id').notNull(),
   originalFilename: text('original_filename').notNull(),
   mimeType: text('mime_type').notNull(),
   sizeBytes: integer('size_bytes').notNull(),
@@ -183,7 +181,6 @@ export const messageAttachments = sqliteTable('message_attachments', {
 
 export const channelInboundEvents = sqliteTable('channel_inbound_events', {
   id: text('id').primaryKey(),
-  assistantId: text('assistant_id').notNull(),
   sourceChannel: text('source_channel').notNull(),
   externalChatId: text('external_chat_id').notNull(),
   externalMessageId: text('external_message_id').notNull(),
@@ -207,7 +204,6 @@ export const channelInboundEvents = sqliteTable('channel_inbound_events', {
 
 export const messageRuns = sqliteTable('message_runs', {
   id: text('id').primaryKey(),
-  assistantId: text('assistant_id').notNull(),
   conversationId: text('conversation_id')
     .notNull()
     .references(() => conversations.id, { onDelete: 'cascade' }),

package/src/runtime/gateway-client.ts

@@ -0,0 +1,36 @@
+import { getLogger } from '../util/logger.js';
+import type { RuntimeAttachmentMetadata } from './http-types.js';
+
+const log = getLogger('gateway-client');
+
+const DELIVERY_TIMEOUT_MS = 30_000;
+
+export interface ChannelReplyPayload {
+  chatId: string;
+  text?: string;
+  assistantId?: string;
+  attachments?: RuntimeAttachmentMetadata[];
+}
+
+export async function deliverChannelReply(
+  callbackUrl: string,
+  payload: ChannelReplyPayload,
+): Promise<void> {
+  const response = await fetch(callbackUrl, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(payload),
+    signal: AbortSignal.timeout(DELIVERY_TIMEOUT_MS),
+  });
+
+  if (!response.ok) {
+    const body = await response.text().catch(() => '<unreadable>');
+    log.error(
+      { status: response.status, body, callbackUrl, chatId: payload.chatId },
+      'Channel reply delivery failed',
+    );
+    throw new Error(`Channel reply delivery failed (${response.status}): ${body}`);
+  }
+
+  log.info({ chatId: payload.chatId, callbackUrl }, 'Channel reply delivered');
+}

package/src/runtime/http-server.ts

@@ -11,6 +11,8 @@ import { timingSafeEqual } from 'node:crypto';
 import { ConfigError, IngressBlockedError } from '../util/errors.js';
 import { getLogger } from '../util/logger.js';
 import { TwilioConversationRelayProvider } from '../calls/twilio-provider.js';
+import { loadConfig } from '../config/loader.js';
+import { getPublicBaseUrl } from '../inbound/public-ingress-urls.js';
 import type { RunOrchestrator } from './run-orchestrator.js';
 
 // Route handlers — grouped by domain
@@ -38,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,
@@ -59,6 +65,7 @@ import {
 } from '../calls/twilio-routes.js';
 import { RelayConnection, activeRelayConnections } from '../calls/relay-server.js';
 import type { RelayWebSocketData } from '../calls/relay-server.js';
+import { consumeCallback, consumeCallbackError } from '../security/oauth-callback-registry.js';
 
 // Re-export shared types so existing consumers don't need to update imports
 export type {
@@ -131,6 +138,35 @@ const GATEWAY_SUBPATH_MAP: Record<string, string> = {
   'connect-action': 'connect-action',
 };
 
+/**
+ * Direct Twilio webhook subpaths that are blocked in gateway_only mode.
+ * Internal forwarding endpoints (gateway→runtime) are unaffected.
+ */
+const GATEWAY_ONLY_BLOCKED_SUBPATHS = new Set(['voice-webhook', 'status', 'connect-action']);
+
+/**
+ * Check if a request origin is from localhost / loopback.
+ */
+function isLoopbackOrigin(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;
+    return host === '127.0.0.1' || host === '::1' || host === 'localhost';
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Check if a hostname is a loopback address.
+ */
+function isLoopbackHost(hostname: string): boolean {
+  return hostname === '127.0.0.1' || hostname === '::1' || hostname === 'localhost';
+}
+
 /**
  * Validate a Twilio webhook request's X-Twilio-Signature header.
  *
@@ -178,10 +214,15 @@ 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 = 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.replace(/\/$/, '') + parsedUrl.pathname + parsedUrl.search
+    ? publicBaseUrl + parsedUrl.pathname + parsedUrl.search
     : req.url;
 
   const isValid = TwilioConversationRelayProvider.verifyWebhookSignature(
@@ -278,6 +319,19 @@ export class RuntimeHttpServer {
       }, 30_000);
     }
 
+    // Startup guard: log gateway-only mode warnings
+    try {
+      const config = loadConfig();
+      if (config.ingress.mode === 'gateway_only') {
+        log.info('Running in gateway-only ingress mode. Direct webhook routes disabled.');
+        if (!isLoopbackHost(this.hostname)) {
+          log.warn('gateway-only mode is enabled but RUNTIME_HTTP_HOST is not bound to loopback. This may expose the runtime to direct public access.');
+        }
+      }
+    } catch {
+      // Config loading may fail during startup — don't block server start
+    }
+
     log.info({ port: this.port, hostname: this.hostname, auth: !!this.bearerToken }, 'Runtime HTTP server listening');
   }
 
@@ -316,6 +370,15 @@ export class RuntimeHttpServer {
     // WebSocket upgrade for ConversationRelay — before auth check because
     // Twilio WebSocket connections don't use bearer tokens.
     if (path.startsWith('/v1/calls/relay') && req.headers.get('upgrade')?.toLowerCase() === 'websocket') {
+      // In gateway_only mode, only allow relay connections from localhost
+      const config = loadConfig();
+      if (config.ingress.mode === 'gateway_only' && !isLoopbackOrigin(req)) {
+        return Response.json(
+          { error: 'Direct relay access disabled in gateway-only mode', code: 'GATEWAY_ONLY' },
+          { status: 403 },
+        );
+      }
+
       const wsUrl = new URL(req.url);
       const callSessionId = wsUrl.searchParams.get('callSessionId');
       if (!callSessionId) {
@@ -345,6 +408,15 @@ export class RuntimeHttpServer {
     if (resolvedTwilioSubpath && req.method === 'POST') {
       const twilioSubpath = resolvedTwilioSubpath;
 
+      // In gateway_only mode, block direct Twilio webhook routes
+      const ingressConfig = loadConfig();
+      if (ingressConfig.ingress.mode === 'gateway_only' && GATEWAY_ONLY_BLOCKED_SUBPATHS.has(twilioSubpath)) {
+        return Response.json(
+          { error: 'Direct webhook access disabled in gateway-only mode. Use the gateway.', code: 'GATEWAY_ONLY' },
+          { status: 410 },
+        );
+      }
+
       // Validate Twilio request signature before dispatching
       const validation = await validateTwilioWebhook(req);
       if (validation instanceof Response) return validation;
@@ -617,6 +689,27 @@ export class RuntimeHttpServer {
         return await handleConnectAction(fakeReq);
       }
 
+      // ── Internal OAuth callback endpoint (gateway → runtime) ──
+      if (endpoint === 'internal/oauth/callback' && req.method === 'POST') {
+        const json = await req.json() as { state: string; code?: string; error?: string };
+        if (!json.state) {
+          return Response.json({ error: 'Missing state parameter' }, { status: 400 });
+        }
+        if (json.error) {
+          const consumed = consumeCallbackError(json.state, json.error);
+          return consumed
+            ? Response.json({ ok: true })
+            : Response.json({ error: 'Unknown state' }, { status: 404 });
+        }
+        if (json.code) {
+          const consumed = consumeCallback(json.state, json.code);
+          return consumed
+            ? Response.json({ ok: true })
+            : Response.json({ error: 'Unknown state' }, { status: 404 });
+        }
+        return Response.json({ error: 'Missing code or error parameter' }, { status: 400 });
+      }
+
       return Response.json({ error: 'Not found', source: 'runtime' }, { status: 404 });
     } catch (err) {
       if (err instanceof IngressBlockedError) {
@@ -695,6 +788,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);
@@ -702,6 +807,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/channel-routes.ts

@@ -10,10 +10,10 @@ 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 type {
   MessageProcessor,
   RuntimeAttachmentMetadata,
-  RuntimeMessagePayload,
 } from '../http-types.js';
 
 const log = getLogger('runtime-http');
@@ -54,6 +54,7 @@ export async function handleChannelInbound(
     senderExternalUserId?: string;
     senderUsername?: string;
     sourceMetadata?: Record<string, unknown>;
+    replyCallbackUrl?: string;
   };
 
   const {
@@ -185,41 +186,92 @@ export async function handleChannelInbound(
     ? sourceMetadata.uxBrief.trim()
     : undefined;
 
-  // For new (non-duplicate) messages, run the agent loop to generate a reply.
-  let processingSucceeded = false;
+  const replyCallbackUrl = body.replyCallbackUrl;
+
+  // For new (non-duplicate) messages, run the secret ingress check
+  // synchronously, then fire off the agent loop in the background.
   if (!result.duplicate && processMessage) {
+    // Persist the raw payload first so dead-lettered events can always be
+    // replayed. If the ingress check later detects secrets we clear it
+    // before throwing, so secret-bearing content is never left on disk.
+    channelDeliveryStore.storePayload(result.eventId, {
+      sourceChannel, externalChatId, externalMessageId, content,
+      attachmentIds, sourceMetadata: body.sourceMetadata,
+      senderName: body.senderName,
+      senderExternalUserId: body.senderExternalUserId,
+      senderUsername: body.senderUsername,
+      replyCallbackUrl,
+    });
+
+    const contentToCheck = content ?? '';
+    let ingressCheck: ReturnType<typeof checkIngressForSecrets>;
     try {
-      // Persist the raw payload first so dead-lettered events can always be
-      // replayed. If the ingress check later detects secrets we clear it
-      // before throwing, so secret-bearing content is never left on disk.
-      channelDeliveryStore.storePayload(result.eventId, {
-        sourceChannel, externalChatId, externalMessageId, content,
-        attachmentIds, sourceMetadata: body.sourceMetadata,
-        senderName: body.senderName,
-        senderExternalUserId: body.senderExternalUserId,
-        senderUsername: body.senderUsername,
-      });
+      ingressCheck = checkIngressForSecrets(contentToCheck);
+    } catch (checkErr) {
+      channelDeliveryStore.clearPayload(result.eventId);
+      throw checkErr;
+    }
+    if (ingressCheck.blocked) {
+      channelDeliveryStore.clearPayload(result.eventId);
+      throw new IngressBlockedError(ingressCheck.userNotice!, ingressCheck.detectedTypes);
+    }
 
-      const contentToCheck = content ?? '';
-      let ingressCheck: ReturnType<typeof checkIngressForSecrets>;
-      try {
-        ingressCheck = checkIngressForSecrets(contentToCheck);
-      } catch (checkErr) {
-        // If the secret check itself throws (e.g. ConfigError from corrupt
-        // config), clear the stored payload so secret-bearing content is
-        // never left on disk.
-        channelDeliveryStore.clearPayload(result.eventId);
-        throw checkErr;
-      }
-      if (ingressCheck.blocked) {
-        channelDeliveryStore.clearPayload(result.eventId);
-        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,
+    });
+  }
+
+  return Response.json({
+    accepted: result.accepted,
+    duplicate: result.duplicate,
+    eventId: result.eventId,
+  });
+}
 
+interface BackgroundProcessingParams {
+  processMessage: MessageProcessor;
+  conversationId: string;
+  eventId: string;
+  content: string;
+  attachmentIds?: string[];
+  sourceChannel: string;
+  externalChatId: string;
+  metadataHints: string[];
+  metadataUxBrief?: string;
+  replyCallbackUrl?: string;
+}
+
+function processChannelMessageInBackground(params: BackgroundProcessingParams): void {
+  const {
+    processMessage,
+    conversationId,
+    eventId,
+    content,
+    attachmentIds,
+    sourceChannel,
+    externalChatId,
+    metadataHints,
+    metadataUxBrief,
+    replyCallbackUrl,
+  } = params;
+
+  (async () => {
+    try {
       const { messageId: userMessageId } = await processMessage(
-        result.conversationId,
-        content ?? '',
-        hasAttachments ? attachmentIds : undefined,
+        conversationId,
+        content,
+        attachmentIds,
         {
           transport: {
             channelId: sourceChannel,
@@ -229,60 +281,50 @@ export async function handleChannelInbound(
         },
         sourceChannel,
       );
-      // Link the user message to the inbound event so edits can find it later
-      channelDeliveryStore.linkMessage(result.eventId, userMessageId);
-      channelDeliveryStore.markProcessed(result.eventId);
-      processingSucceeded = true;
+      channelDeliveryStore.linkMessage(eventId, userMessageId);
+      channelDeliveryStore.markProcessed(eventId);
+
+      if (replyCallbackUrl) {
+        await deliverReplyViaCallback(conversationId, externalChatId, replyCallbackUrl);
+      }
     } catch (err) {
-      // Secret ingress blocks are not retryable — let the top-level handler return 422
-      if (err instanceof IngressBlockedError) throw err;
-      log.error({ err, conversationId: result.conversationId }, 'Failed to process channel inbound message');
-      channelDeliveryStore.recordProcessingFailure(result.eventId, err);
+      log.error({ err, conversationId }, 'Background channel message processing failed');
+      channelDeliveryStore.recordProcessingFailure(eventId, err);
     }
-  }
+  })();
+}
 
-  // Only look up the assistant reply when processing succeeded for a new
-  // (non-duplicate) message.  For duplicates or failed processing, returning
-  // a stale assistant message could cause the caller to resend old replies.
-  let assistantMessage: RuntimeMessagePayload | undefined;
-  if (processingSucceeded) {
-    const msgs = conversationStore.getMessages(result.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,
-        }));
-
-        // Include the reply if it has text or attachments
-        if (rendered.text || replyAttachments.length > 0) {
-          assistantMessage = {
-            id: msgs[i].id,
-            role: 'assistant',
-            content: rendered.text,
-            timestamp: new Date(msgs[i].createdAt).toISOString(),
-            attachments: replyAttachments,
-          };
-        }
-        break;
+async function 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: 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,
+        });
       }
+      break;
     }
   }
-
-  return Response.json({
-    accepted: result.accepted,
-    duplicate: result.duplicate,
-    eventId: result.eventId,
-    ...(assistantMessage ? { assistantMessage } : {}),
-  });
 }
 
 export function handleListDeadLetters(): Response {

package/src/security/oauth-callback-registry.ts

@@ -0,0 +1,56 @@
+/**
+ * In-memory registry for pending OAuth callback states.
+ * Used by the gateway-routed OAuth flow to resolve authorization codes
+ * back to the runtime code that initiated the OAuth handshake.
+ */
+
+interface PendingCallback {
+  resolve: (code: string) => void;
+  reject: (error: Error) => void;
+  timer: ReturnType<typeof setTimeout>;
+}
+
+const pendingCallbacks = new Map<string, PendingCallback>();
+const DEFAULT_TTL_MS = 5 * 60 * 1000; // 5 minutes
+
+export function registerPendingCallback(
+  state: string,
+  resolve: (code: string) => void,
+  reject: (error: Error) => void,
+  ttlMs = DEFAULT_TTL_MS,
+): void {
+  const timer = setTimeout(() => {
+    const entry = pendingCallbacks.get(state);
+    if (entry) {
+      pendingCallbacks.delete(state);
+      entry.reject(new Error('OAuth callback timed out'));
+    }
+  }, ttlMs);
+
+  pendingCallbacks.set(state, { resolve, reject, timer });
+}
+
+export function consumeCallback(state: string, code: string): boolean {
+  const entry = pendingCallbacks.get(state);
+  if (!entry) return false;
+  clearTimeout(entry.timer);
+  pendingCallbacks.delete(state);
+  entry.resolve(code);
+  return true;
+}
+
+export function consumeCallbackError(state: string, error: string): boolean {
+  const entry = pendingCallbacks.get(state);
+  if (!entry) return false;
+  clearTimeout(entry.timer);
+  pendingCallbacks.delete(state);
+  entry.reject(new Error(error));
+  return true;
+}
+
+export function clearAllCallbacks(): void {
+  for (const entry of pendingCallbacks.values()) {
+    clearTimeout(entry.timer);
+  }
+  pendingCallbacks.clear();
+}