@vellumai/vellum-gateway 0.1.7

package/src/http/routes/runtime-proxy.ts

@@ -0,0 +1,143 @@
+import type { GatewayConfig } from "../../config.js";
+import { getLogger } from "../../logger.js";
+import { validateBearerToken } from "../auth/bearer.js";
+
+const log = getLogger("runtime-proxy");
+
+const HOP_BY_HOP_HEADERS = [
+  "connection",
+  "keep-alive",
+  "proxy-authenticate",
+  "proxy-authorization",
+  "te",
+  "trailer",
+  "transfer-encoding",
+  "upgrade",
+];
+
+function stripHopByHop(headers: Headers): Headers {
+  const cleaned = new Headers(headers);
+
+  // Also strip any headers listed in the Connection header value
+  const connectionValue = cleaned.get("connection");
+  if (connectionValue) {
+    for (const name of connectionValue.split(",")) {
+      const trimmed = name.trim().toLowerCase();
+      if (trimmed) {
+        try {
+          cleaned.delete(trimmed);
+        } catch {
+          // Ignore invalid header names (e.g., malformed Connection tokens like "@@@")
+        }
+      }
+    }
+  }
+
+  for (const h of HOP_BY_HOP_HEADERS) {
+    cleaned.delete(h);
+  }
+  return cleaned;
+}
+
+export function createRuntimeProxyHandler(config: GatewayConfig) {
+  return async (req: Request): Promise<Response> => {
+    const start = performance.now();
+    const url = new URL(req.url);
+
+    if (config.runtimeProxyRequireAuth && req.method !== "OPTIONS") {
+      if (!config.runtimeProxyBearerToken) {
+        return Response.json({ error: "Server misconfigured" }, { status: 500 });
+      }
+      const authResult = validateBearerToken(
+        req.headers.get("authorization"),
+        config.runtimeProxyBearerToken,
+      );
+      if (!authResult.authorized) {
+        return Response.json({ error: "Unauthorized" }, { status: 401 });
+      }
+    }
+
+    const upstream = `${config.assistantRuntimeBaseUrl}${url.pathname}${url.search}`;
+
+    const reqHeaders = stripHopByHop(new Headers(req.headers));
+    reqHeaders.delete("host");
+    // Only strip the authorization header when the gateway consumed it for its
+    // own auth check. When auth is not required, the header may be intended for
+    // the upstream service and must be forwarded.
+    if (config.runtimeProxyRequireAuth) {
+      reqHeaders.delete("authorization");
+    }
+
+    // Add the runtime's bearer token so the upstream accepts the request
+    if (config.runtimeBearerToken) {
+      reqHeaders.set("authorization", `Bearer ${config.runtimeBearerToken}`);
+    }
+
+    if (config.runtimeProxyBearerToken) {
+      reqHeaders.set("authorization", `Bearer ${config.runtimeProxyBearerToken}`);
+    }
+
+    // Use a manual AbortController so the timeout only covers the connection
+    // phase (waiting for response headers). Once headers arrive, the timeout is
+    // cleared so streaming responses (SSE, chunked) can run indefinitely.
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => {
+      controller.abort(new DOMException("The operation was aborted due to timeout", "TimeoutError"));
+    }, config.runtimeTimeoutMs);
+
+    let response: Response;
+    try {
+      response = await fetch(upstream, {
+        method: req.method,
+        headers: reqHeaders,
+        body: req.body,
+        // @ts-expect-error Bun supports duplex on Request
+        duplex: "half",
+        signal: controller.signal,
+      });
+      clearTimeout(timeoutId);
+    } catch (err) {
+      clearTimeout(timeoutId);
+      const duration = Math.round(performance.now() - start);
+      if (err instanceof DOMException && err.name === "TimeoutError") {
+        log.error(
+          { method: req.method, path: url.pathname, duration, timeoutMs: config.runtimeTimeoutMs },
+          "Upstream request timed out",
+        );
+        return Response.json({ error: "Gateway Timeout" }, { status: 504 });
+      }
+      log.error(
+        { err, method: req.method, path: url.pathname, duration },
+        "Upstream connection failed",
+      );
+      return Response.json({ error: "Bad Gateway" }, { status: 502 });
+    }
+
+    const resHeaders = stripHopByHop(new Headers(response.headers));
+    const duration = Math.round(performance.now() - start);
+
+    if (response.status >= 400) {
+      const body = await response.text();
+      const level = response.status >= 500 ? "error" : "warn";
+      const bodySnippet = body.length > 256 ? body.slice(0, 256) + "…[truncated]" : body;
+      log[level](
+        { method: req.method, path: url.pathname, status: response.status, duration, body: bodySnippet },
+        "Upstream returned error",
+      );
+      return new Response(body, {
+        status: response.status,
+        headers: resHeaders,
+      });
+    }
+
+    log.info(
+      { method: req.method, path: url.pathname, status: response.status, duration },
+      "Proxy request completed",
+    );
+
+    return new Response(response.body, {
+      status: response.status,
+      headers: resHeaders,
+    });
+  };
+}

package/src/http/routes/telegram-webhook.ts

@@ -0,0 +1,272 @@
+import type { GatewayConfig } from "../../config.js";
+import { DedupCache } from "../../dedup-cache.js";
+import { handleInbound, type InboundResult } from "../../handlers/handle-inbound.js";
+import { getLogger } from "../../logger.js";
+import { resolveAssistant, isRejection } from "../../routing/resolve-assistant.js";
+import { AttachmentValidationError, resetConversation, uploadAttachment } from "../../runtime/client.js";
+import { downloadTelegramFile } from "../../telegram/download.js";
+import { normalizeTelegramUpdate } from "../../telegram/normalize.js";
+import { sendTelegramReply, sendTypingIndicator } from "../../telegram/send.js";
+import { verifyWebhookSecret } from "../../telegram/verify.js";
+
+const log = getLogger("telegram-webhook");
+
+const MAX_TYPING_DURATION_MS = 60_000;
+const MAX_TYPING_FAILURES = 3;
+export const TELEGRAM_CHANNEL_TRANSPORT_HINTS = [
+  "chat-first-medium",
+  "channel-safe-onboarding",
+  "defer-dashboard-only-tasks",
+] as const;
+export const TELEGRAM_CHANNEL_TRANSPORT_UX_BRIEF =
+  "Telegram is chat-only. Complete channel-safe steps in-channel and defer dashboard-only Home Base tasks to desktop.";
+
+export function buildTelegramTransportMetadata(): { hints: string[]; uxBrief: string } {
+  return {
+    hints: [...TELEGRAM_CHANNEL_TRANSPORT_HINTS],
+    uxBrief: TELEGRAM_CHANNEL_TRANSPORT_UX_BRIEF,
+  };
+}
+
+export type OnReply = (
+  chatId: string,
+  result: InboundResult,
+  assistantId: string,
+) => Promise<void>;
+
+export function createTelegramWebhookHandler(
+  config: GatewayConfig,
+  onReply?: OnReply,
+) {
+  const dedupCache = new DedupCache();
+
+  return async (req: Request): Promise<Response> => {
+    if (req.method !== "POST") {
+      return Response.json({ error: "Method not allowed" }, { status: 405 });
+    }
+
+    // Payload size guard
+    const contentLength = req.headers.get("content-length");
+    if (contentLength && Number(contentLength) > config.maxWebhookPayloadBytes) {
+      log.warn({ contentLength }, "Webhook payload too large");
+      return Response.json({ error: "Payload too large" }, { status: 413 });
+    }
+
+    // Verify webhook secret
+    if (!config.telegramWebhookSecret || !verifyWebhookSecret(req.headers, config.telegramWebhookSecret)) {
+      log.warn("Telegram webhook request failed secret verification");
+      return Response.json({ error: "Unauthorized" }, { status: 401 });
+    }
+
+    let rawBody: string;
+    try {
+      rawBody = await req.text();
+    } catch {
+      return Response.json({ error: "Failed to read body" }, { status: 400 });
+    }
+
+    if (Buffer.byteLength(rawBody) > config.maxWebhookPayloadBytes) {
+      log.warn({ bodyLength: Buffer.byteLength(rawBody) }, "Webhook payload too large");
+      return Response.json({ error: "Payload too large" }, { status: 413 });
+    }
+
+    let payload: Record<string, unknown>;
+    try {
+      payload = JSON.parse(rawBody) as Record<string, unknown>;
+    } catch {
+      return Response.json({ error: "Invalid JSON" }, { status: 400 });
+    }
+
+    // Dedup check — reserve the update_id immediately so concurrent retries
+    // are blocked even while the first request is still processing.
+    const updateId = typeof payload.update_id === "number" ? payload.update_id : undefined;
+    if (updateId !== undefined) {
+      const reserved = dedupCache.reserve(updateId);
+      if (!reserved) {
+        log.info({ updateId }, "Duplicate update_id, returning cached response");
+        const cached = dedupCache.get(updateId)!;
+        return new Response(cached.body, {
+          status: cached.status,
+          headers: { "content-type": "application/json" },
+        });
+      }
+    }
+
+    // Helper: build a JSON response and update the cache with the final result
+    const respond = (body: Record<string, unknown>, status = 200): Response => {
+      const json = JSON.stringify(body);
+      if (updateId !== undefined) {
+        dedupCache.set(updateId, json, status);
+      }
+      return new Response(json, {
+        status,
+        headers: { "content-type": "application/json" },
+      });
+    };
+
+    // Normalize the update
+    const normalized = normalizeTelegramUpdate(payload);
+    if (!normalized) {
+      return respond({ ok: true });
+    }
+
+    // Handle /new command — reset conversation before it reaches the runtime
+    if (normalized.message.content.trim() === "/new") {
+      const routing = resolveAssistant(
+        config,
+        normalized.message.externalChatId,
+        normalized.sender.externalUserId,
+      );
+
+      if (!isRejection(routing)) {
+        try {
+          await resetConversation(
+            config,
+            routing.assistantId,
+            normalized.sourceChannel,
+            normalized.message.externalChatId,
+          );
+          sendTelegramReply(config, normalized.message.externalChatId, "Starting a new conversation!").catch((err) => {
+            log.error({ err }, "Failed to send /new confirmation");
+          });
+        } catch (err) {
+          log.error({ err }, "Failed to reset conversation");
+          sendTelegramReply(config, normalized.message.externalChatId, "Failed to reset conversation. Please try again.").catch((replyErr) => {
+            log.error({ err: replyErr }, "Failed to send /new error reply");
+          });
+        }
+      }
+
+      return respond({ ok: true });
+    }
+
+    // Edits don't produce a new reply, so skip typing indicator and attachments
+    const isEdit = !!normalized.message.isEdit;
+
+    // Check routing early so we can gate attachments and typing indicator
+    const chatId = normalized.message.externalChatId;
+    const routing = resolveAssistant(
+      config,
+      chatId,
+      normalized.sender.externalUserId,
+    );
+    const routable = !isRejection(routing);
+
+    // Download and upload attachments if present (skip for edits — the runtime
+    // edit path only updates text content and doesn't link new attachments)
+    let attachmentIds: string[] | undefined;
+    const eventAttachments = normalized.message.attachments;
+    if (eventAttachments && eventAttachments.length > 0 && routable && !isEdit) {
+      try {
+        attachmentIds = [];
+
+        // Filter oversized attachments
+        const eligible = eventAttachments.filter((att) => {
+          if (att.fileSize !== undefined && att.fileSize > config.maxAttachmentBytes) {
+            log.warn(
+              { fileId: att.fileId, fileSize: att.fileSize, limit: config.maxAttachmentBytes },
+              "Skipping oversized attachment",
+            );
+            return false;
+          }
+          return true;
+        });
+
+        // Process with bounded concurrency. Validation errors (unsupported
+        // MIME type, dangerous extension) are skipped so that a bad attachment
+        // doesn't drop the user's message. Transient errors (download timeout,
+        // upload 5xx, network failures) are propagated so that Telegram retries
+        // the webhook delivery.
+        for (let i = 0; i < eligible.length; i += config.maxAttachmentConcurrency) {
+          const batch = eligible.slice(i, i + config.maxAttachmentConcurrency);
+          const results = await Promise.allSettled(
+            batch.map(async (att) => {
+              const downloaded = await downloadTelegramFile(config, att.fileId, {
+                fileName: att.fileName,
+                mimeType: att.mimeType,
+              });
+              return uploadAttachment(config, routing.assistantId, downloaded);
+            }),
+          );
+          for (const result of results) {
+            if (result.status === 'fulfilled') {
+              attachmentIds.push(result.value.id);
+            } else if (result.reason instanceof AttachmentValidationError) {
+              log.warn({ err: result.reason }, "Skipping attachment with validation error");
+            } else {
+              // Transient failure — propagate so the webhook returns 500 and
+              // Telegram retries the update delivery.
+              throw result.reason;
+            }
+          }
+        }
+      } catch (err) {
+        // Transient attachment failure — return 500 so Telegram retries.
+        // Use Response.json() instead of respond() to bypass the dedup cache,
+        // otherwise the cached 500 prevents Telegram retries from being processed.
+        log.error({ err }, "Attachment processing failed with transient error");
+        if (updateId !== undefined) dedupCache.unreserve(updateId);
+        return Response.json({ error: "Attachment processing failed" }, { status: 500 });
+      }
+    }
+
+    // Start typing indicator only for routable chats with new messages.
+    // A safety timeout ensures the interval is cleared even if handleInbound hangs.
+    // Cancel early if the Telegram API fails repeatedly (MAX_TYPING_FAILURES consecutive).
+    let typingInterval: ReturnType<typeof setInterval> | undefined;
+    let typingTimeout: ReturnType<typeof setTimeout> | undefined;
+    const clearTyping = () => {
+      clearInterval(typingInterval);
+      clearTimeout(typingTimeout);
+    };
+    if (routable && !isEdit) {
+      let consecutiveFailures = 0;
+      // Fire-and-forget: don't track the initial call's result to avoid
+      // race conditions with the interval's consecutiveFailures counter.
+      sendTypingIndicator(config, chatId);
+      typingInterval = setInterval(async () => {
+        const ok = await sendTypingIndicator(config, chatId);
+        if (ok) {
+          consecutiveFailures = 0;
+        } else {
+          consecutiveFailures++;
+          if (consecutiveFailures >= MAX_TYPING_FAILURES) {
+            log.warn({ chatId, consecutiveFailures }, "Typing indicator cancelled after repeated failures");
+            clearTyping();
+          }
+        }
+      }, 5000);
+      typingTimeout = setTimeout(clearTyping, MAX_TYPING_DURATION_MS);
+    }
+
+    // Process inbound and only acknowledge after successful delivery
+    let result: InboundResult;
+    try {
+      result = await handleInbound(config, normalized, {
+        attachmentIds,
+        transportMetadata: buildTelegramTransportMetadata(),
+      });
+    } catch (err) {
+      log.error({ err, updateId: payload.update_id }, "Failed to process inbound event");
+      if (updateId !== undefined) dedupCache.unreserve(updateId);
+      return Response.json({ error: "Internal error" }, { status: 500 });
+    } finally {
+      clearTyping();
+    }
+
+    if (!result.forwarded && !result.rejected) {
+      log.error({ updateId: payload.update_id }, "Failed to forward inbound event");
+      if (updateId !== undefined) dedupCache.unreserve(updateId);
+      return Response.json({ error: "Internal error" }, { status: 500 });
+    }
+
+    // Fire reply asynchronously so webhook ack is not blocked by outbound send
+    if (onReply && !isRejection(routing) && !result.rejected && result.runtimeResponse?.assistantMessage) {
+      onReply(normalized.message.externalChatId, result, routing.assistantId).catch((err) => {
+        log.error({ err, updateId: payload.update_id }, "Failed to send reply");
+      });
+    }
+
+    return respond({ ok: true });
+  };
+}

package/src/index.ts

@@ -0,0 +1,117 @@
+import { loadConfig } from "./config.js";
+import { createRuntimeProxyHandler } from "./http/routes/runtime-proxy.js";
+import { createTelegramWebhookHandler } from "./http/routes/telegram-webhook.js";
+import { getLogger, initLogger } from "./logger.js";
+import { buildSchema } from "./schema.js";
+import { callTelegramApi } from "./telegram/api.js";
+import { sendTelegramAttachments, sendTelegramReply } from "./telegram/send.js";
+
+const log = getLogger("main");
+
+let draining = false;
+
+function main() {
+  const config = loadConfig();
+  initLogger(config.logFile);
+
+  log.info("Starting Vellum Gateway...");
+
+  const telegramConfigured = !!(config.telegramBotToken && config.telegramWebhookSecret);
+
+  const handleTelegramWebhook = telegramConfigured
+    ? createTelegramWebhookHandler(
+        config,
+        async (chatId, result, assistantId) => {
+          const msg = result.runtimeResponse?.assistantMessage;
+          const content = msg?.content;
+          const attachments = msg?.attachments ?? [];
+
+          if (!content && attachments.length === 0) {
+            return;
+          }
+
+          try {
+            if (content) {
+              await sendTelegramReply(config, chatId, content);
+            }
+          } catch (err) {
+            log.error({ err, chatId }, "Failed to send Telegram reply");
+          }
+
+          if (attachments.length > 0) {
+            try {
+              await sendTelegramAttachments(config, chatId, assistantId, attachments);
+            } catch (err) {
+              log.error({ err, chatId }, "Failed to send Telegram attachments");
+            }
+          }
+        },
+      )
+    : null;
+
+  const handleRuntimeProxy = config.runtimeProxyEnabled
+    ? createRuntimeProxyHandler(config)
+    : null;
+
+  const server = Bun.serve({
+    port: config.port,
+    async fetch(req) {
+      const url = new URL(req.url);
+
+      if (url.pathname === "/healthz") {
+        return Response.json({ status: "ok" });
+      }
+
+      if (url.pathname === "/schema") {
+        return Response.json(buildSchema());
+      }
+
+      if (url.pathname === "/readyz") {
+        if (draining) {
+          return Response.json({ status: "draining" }, { status: 503 });
+        }
+        return Response.json({ status: "ok" });
+      }
+
+      if (url.pathname === "/webhooks/telegram") {
+        if (!handleTelegramWebhook) {
+          return Response.json(
+            { error: "Telegram integration not configured" },
+            { status: 503 },
+          );
+        }
+        return handleTelegramWebhook(req);
+      }
+
+      if (handleRuntimeProxy) {
+        return handleRuntimeProxy(req);
+      }
+
+      return Response.json({ error: "Not found", source: "gateway" }, { status: 404 });
+    },
+  });
+
+  log.info({ port: server.port }, "Gateway HTTP server listening");
+
+  if (telegramConfigured) {
+    callTelegramApi(config, "setMyCommands", {
+      commands: [{ command: "new", description: "Start a new conversation" }],
+    }).catch((err) => {
+      log.error({ err }, "Failed to register Telegram bot commands");
+    });
+  }
+
+  const drainMs = config.shutdownDrainMs;
+
+  process.on("SIGTERM", () => {
+    log.info("SIGTERM received, starting graceful shutdown");
+    draining = true;
+    setTimeout(() => {
+      log.info("Drain window elapsed, stopping server");
+      server.stop(true);
+      process.exit(0);
+    }, drainMs);
+  });
+}
+
+main();

package/src/logger.ts

@@ -0,0 +1,103 @@
+import { existsSync, mkdirSync, readdirSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import pino from "pino";
+
+export type LogFileConfig = {
+  dir: string | undefined;
+  retentionDays: number;
+};
+
+const LOG_FILE_PREFIX = "gateway-";
+const LOG_FILE_SUFFIX = ".log";
+const LOG_FILE_PATTERN = /^gateway-(\d{4}-\d{2}-\d{2})\.log$/;
+
+function formatDate(date: Date): string {
+  const y = date.getUTCFullYear();
+  const m = String(date.getUTCMonth() + 1).padStart(2, "0");
+  const d = String(date.getUTCDate()).padStart(2, "0");
+  return `${y}-${m}-${d}`;
+}
+
+function logFilePathForDate(dir: string, date: Date): string {
+  return join(dir, `${LOG_FILE_PREFIX}${formatDate(date)}${LOG_FILE_SUFFIX}`);
+}
+
+export function pruneOldLogFiles(dir: string, retentionDays: number): number {
+  if (!existsSync(dir)) return 0;
+
+  const cutoff = new Date();
+  cutoff.setUTCDate(cutoff.getUTCDate() - retentionDays);
+  cutoff.setUTCHours(0, 0, 0, 0);
+
+  let removed = 0;
+  for (const name of readdirSync(dir)) {
+    const match = LOG_FILE_PATTERN.exec(name);
+    if (!match) continue;
+    const fileDate = new Date(match[1] + "T00:00:00Z");
+    if (fileDate < cutoff) {
+      try {
+        unlinkSync(join(dir, name));
+        removed++;
+      } catch {
+        // best-effort
+      }
+    }
+  }
+  return removed;
+}
+
+let rootLogger: pino.Logger | null = null;
+let activeLogDate: string | null = null;
+let activeConfig: LogFileConfig | null = null;
+
+function buildLogger(config: LogFileConfig | null): pino.Logger {
+  if (!config?.dir) {
+    return pino({ name: "gateway" });
+  }
+
+  if (!existsSync(config.dir)) {
+    mkdirSync(config.dir, { recursive: true });
+  }
+
+  const today = formatDate(new Date());
+  const filePath = logFilePathForDate(config.dir, new Date());
+  const fileStream = pino.destination({ dest: filePath, sync: false, mkdir: true });
+
+  activeLogDate = today;
+  activeConfig = config;
+
+  return pino(
+    { name: "gateway" },
+    pino.multistream([
+      { stream: fileStream, level: "info" as const },
+      { stream: pino.destination(1), level: "info" as const },
+    ]),
+  );
+}
+
+function ensureCurrentDate(): void {
+  if (!activeConfig?.dir || !activeLogDate) return;
+  const today = formatDate(new Date());
+  if (today !== activeLogDate) {
+    rootLogger = buildLogger(activeConfig);
+  }
+}
+
+export function initLogger(config: LogFileConfig): void {
+  rootLogger = buildLogger(config);
+
+  if (config.dir && config.retentionDays > 0) {
+    const removed = pruneOldLogFiles(config.dir, config.retentionDays);
+    if (removed > 0) {
+      rootLogger.info({ removed, retentionDays: config.retentionDays }, "Pruned old log files");
+    }
+  }
+}
+
+export function getLogger(name: string): pino.Logger {
+  ensureCurrentDate();
+  if (!rootLogger) {
+    rootLogger = buildLogger(null);
+  }
+  return rootLogger.child({ module: name });
+}

package/src/routing/resolve-assistant.ts

@@ -0,0 +1,45 @@
+import type { GatewayConfig } from "../config.js";
+import { getLogger } from "../logger.js";
+import type { RoutingOutcome } from "./types.js";
+
+const log = getLogger("routing");
+
+export function resolveAssistant(
+  config: GatewayConfig,
+  chatId: string,
+  userId: string,
+): RoutingOutcome {
+  // Priority 1: explicit chat_id route
+  for (const entry of config.routingEntries) {
+    if (entry.type === "chat_id" && entry.key === chatId) {
+      log.debug({ chatId, assistantId: entry.assistantId }, "Resolved by chat_id");
+      return { assistantId: entry.assistantId, routeSource: "chat_id" };
+    }
+  }
+
+  // Priority 2: explicit user_id route
+  for (const entry of config.routingEntries) {
+    if (entry.type === "user_id" && entry.key === userId) {
+      log.debug({ userId, assistantId: entry.assistantId }, "Resolved by user_id");
+      return { assistantId: entry.assistantId, routeSource: "user_id" };
+    }
+  }
+
+  // Priority 3: apply unmapped policy
+  if (config.unmappedPolicy === "default" && config.defaultAssistantId) {
+    log.debug(
+      { chatId, userId, assistantId: config.defaultAssistantId },
+      "Resolved by default policy",
+    );
+    return { assistantId: config.defaultAssistantId, routeSource: "default" };
+  }
+
+  log.info({ chatId, userId }, "No route matched, rejecting");
+  return { rejected: true, reason: "No route configured for this chat" };
+}
+
+export function isRejection(
+  outcome: RoutingOutcome,
+): outcome is { rejected: true; reason: string } {
+  return "rejected" in outcome && outcome.rejected === true;
+}

package/src/routing/types.ts

@@ -0,0 +1,11 @@
+export type RouteResult = {
+  assistantId: string;
+  routeSource: "chat_id" | "user_id" | "default";
+};
+
+export type RouteRejection = {
+  rejected: true;
+  reason: string;
+};
+
+export type RoutingOutcome = RouteResult | RouteRejection;