@vellumai/vellum-gateway 0.1.7

package/src/__tests__/telegram-send-attachments.test.ts

@@ -0,0 +1,185 @@
+import { describe, test, expect, mock, afterEach } from "bun:test";
+import { sendTelegramAttachments } from "../telegram/send.js";
+import type { RuntimeAttachmentMeta } from "../runtime/client.js";
+import type { GatewayConfig } from "../config.js";
+
+const makeConfig = (overrides: Partial<GatewayConfig> = {}): GatewayConfig => ({
+  telegramBotToken: "tok",
+  telegramWebhookSecret: "wh-ver",
+  telegramApiBaseUrl: "https://api.telegram.org",
+  assistantRuntimeBaseUrl: "http://localhost:7821",
+  routingEntries: [],
+  defaultAssistantId: undefined,
+  unmappedPolicy: "reject",
+  port: 7830,
+  runtimeBearerToken: undefined,
+  runtimeProxyEnabled: false,
+  runtimeProxyRequireAuth: true,
+  runtimeProxyBearerToken: undefined,
+  shutdownDrainMs: 5000,
+  runtimeTimeoutMs: 30000,
+  runtimeMaxRetries: 2,
+  runtimeInitialBackoffMs: 500,
+  telegramInitialBackoffMs: 1000,
+  telegramMaxRetries: 3,
+  telegramTimeoutMs: 15000,
+  maxWebhookPayloadBytes: 1048576,
+  logFile: { dir: undefined, retentionDays: 30 },
+  maxAttachmentBytes: 20971520,
+  maxAttachmentConcurrency: 3,
+  ...overrides,
+});
+
+const telegramOk = { ok: true, result: { message_id: 1 } };
+
+function mockFetch(fn: (url: string, init?: RequestInit) => Promise<Response>) {
+  const m = mock(fn);
+  Object.assign(m, { preconnect: () => {} });
+  globalThis.fetch = m as unknown as typeof fetch;
+  return m;
+}
+
+describe("sendTelegramAttachments", () => {
+  const originalFetch = globalThis.fetch;
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+  });
+
+  test("sends image attachment via sendPhoto", async () => {
+    const calls: string[] = [];
+
+    mockFetch(async (url: string) => {
+      calls.push(url);
+      // Runtime download endpoint
+      if (url.includes("/attachments/att-1")) {
+        return new Response(
+          JSON.stringify({
+            id: "att-1",
+            filename: "photo.png",
+            mimeType: "image/png",
+            sizeBytes: 100,
+            kind: "generated_image",
+            data: "iVBORw0KGgo=",
+          }),
+        );
+      }
+      // Telegram sendPhoto
+      return new Response(JSON.stringify(telegramOk));
+    });
+
+    const config = makeConfig();
+    const meta: RuntimeAttachmentMeta = {
+      id: "att-1",
+      filename: "photo.png",
+      mimeType: "image/png",
+      sizeBytes: 100,
+      kind: "generated_image",
+    };
+
+    await sendTelegramAttachments(config, "chat-1", "assistant-a", [meta]);
+
+    // Should have called: 1) runtime download, 2) telegram sendPhoto
+    expect(calls).toHaveLength(2);
+    expect(calls[0]).toContain("/attachments/att-1");
+    expect(calls[1]).toContain("sendPhoto");
+  });
+
+  test("sends non-image attachment via sendDocument", async () => {
+    const calls: string[] = [];
+
+    mockFetch(async (url: string) => {
+      calls.push(url);
+      if (url.includes("/attachments/att-2")) {
+        return new Response(
+          JSON.stringify({
+            id: "att-2",
+            filename: "report.pdf",
+            mimeType: "application/pdf",
+            sizeBytes: 200,
+            kind: "filesystem",
+            data: "JVBER",
+          }),
+        );
+      }
+      return new Response(JSON.stringify(telegramOk));
+    });
+
+    const config = makeConfig();
+    const meta: RuntimeAttachmentMeta = {
+      id: "att-2",
+      filename: "report.pdf",
+      mimeType: "application/pdf",
+      sizeBytes: 200,
+      kind: "filesystem",
+    };
+
+    await sendTelegramAttachments(config, "chat-1", "assistant-a", [meta]);
+
+    expect(calls).toHaveLength(2);
+    expect(calls[0]).toContain("/attachments/att-2");
+    expect(calls[1]).toContain("sendDocument");
+  });
+
+  test("skips oversized attachments and sends failure notice", async () => {
+    const calls: string[] = [];
+
+    mockFetch(async (url: string) => {
+      calls.push(url);
+      return new Response(JSON.stringify(telegramOk));
+    });
+
+    const config = makeConfig({ maxAttachmentBytes: 50 });
+    const meta: RuntimeAttachmentMeta = {
+      id: "att-3",
+      filename: "huge.zip",
+      mimeType: "application/zip",
+      sizeBytes: 100, // exceeds 50 byte limit
+      kind: "filesystem",
+    };
+
+    await sendTelegramAttachments(config, "chat-1", "assistant-a", [meta]);
+
+    // Should have sent only the failure notice via sendMessage
+    expect(calls).toHaveLength(1);
+    expect(calls[0]).toContain("sendMessage");
+  });
+
+  test("continues sending remaining attachments on individual failure", async () => {
+    const calls: string[] = [];
+
+    mockFetch(async (url: string) => {
+      calls.push(url);
+      // First attachment download fails
+      if (url.includes("/attachments/att-fail")) {
+        return new Response('{"error":"not found"}', { status: 404 });
+      }
+      // Second attachment succeeds
+      if (url.includes("/attachments/att-ok")) {
+        return new Response(
+          JSON.stringify({
+            id: "att-ok",
+            filename: "good.png",
+            mimeType: "image/png",
+            sizeBytes: 50,
+            kind: "generated_image",
+            data: "iVBORw0KGgo=",
+          }),
+        );
+      }
+      return new Response(JSON.stringify(telegramOk));
+    });
+
+    const config = makeConfig();
+    const attachments: RuntimeAttachmentMeta[] = [
+      { id: "att-fail", filename: "bad.png", mimeType: "image/png", sizeBytes: 50, kind: "generated_image" },
+      { id: "att-ok", filename: "good.png", mimeType: "image/png", sizeBytes: 50, kind: "generated_image" },
+    ];
+
+    await sendTelegramAttachments(config, "chat-1", "assistant-a", attachments);
+
+    // Should have: download att-fail (fail), download att-ok, sendPhoto for att-ok, sendMessage for notice
+    expect(calls.filter((u) => u.includes("sendPhoto"))).toHaveLength(1);
+    expect(calls.filter((u) => u.includes("sendMessage"))).toHaveLength(1);
+  });
+});

package/src/cli/schema.ts

@@ -0,0 +1,8 @@
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { buildSchema } from "../schema.js";
+
+const filePath = join(tmpdir(), `vellum-gateway-schema-${Date.now()}.json`);
+writeFileSync(filePath, JSON.stringify(buildSchema(), null, 2) + "\n");
+console.log(filePath);

package/src/config.ts

@@ -0,0 +1,254 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { getLogger, type LogFileConfig } from "./logger.js";
+
+const log = getLogger("config");
+
+export type RoutingEntry = {
+  type: "chat_id" | "user_id";
+  key: string;
+  assistantId: string;
+};
+
+export type GatewayConfig = {
+  assistantRuntimeBaseUrl: string;
+  defaultAssistantId: string | undefined;
+  logFile: LogFileConfig;
+  maxAttachmentBytes: number;
+  maxAttachmentConcurrency: number;
+  maxWebhookPayloadBytes: number;
+  port: number;
+  routingEntries: RoutingEntry[];
+  /** Bearer token sent to the assistant runtime on gateway-to-runtime calls. */
+  runtimeBearerToken: string | undefined;
+  runtimeInitialBackoffMs: number;
+  runtimeMaxRetries: number;
+  runtimeProxyBearerToken: string | undefined;
+  runtimeProxyEnabled: boolean;
+  runtimeProxyRequireAuth: boolean;
+  runtimeTimeoutMs: number;
+  shutdownDrainMs: number;
+  telegramApiBaseUrl: string;
+  telegramBotToken: string | undefined;
+  telegramInitialBackoffMs: number;
+  telegramMaxRetries: number;
+  telegramTimeoutMs: number;
+  telegramWebhookSecret: string | undefined;
+  unmappedPolicy: "reject" | "default";
+};
+
+function parseRoutingJson(raw: string): RoutingEntry[] {
+  let parsed: Record<string, string>;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error("GATEWAY_ASSISTANT_ROUTING_JSON is not valid JSON");
+  }
+
+  const entries: RoutingEntry[] = [];
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new Error("GATEWAY_ASSISTANT_ROUTING_JSON must be a JSON object");
+  }
+  for (const [key, assistantId] of Object.entries(parsed)) {
+    if (typeof assistantId !== "string" || !assistantId) {
+      throw new Error(`Invalid assistant ID for routing key "${key}"`);
+    }
+    if (key.startsWith("chat:")) {
+      entries.push({ type: "chat_id", key: key.slice(5), assistantId });
+    } else if (key.startsWith("user:")) {
+      entries.push({ type: "user_id", key: key.slice(5), assistantId });
+    } else {
+      throw new Error(
+        `Invalid routing key "${key}": must start with "chat:" or "user:"`,
+      );
+    }
+  }
+  return entries;
+}
+
+function readHttpTokenFile(): string | null {
+  const tokenPath = process.env.VELLUM_HTTP_TOKEN_PATH
+    ?? join(process.env.BASE_DATA_DIR?.trim() || homedir(), ".vellum", "http-token");
+  try {
+    return readFileSync(tokenPath, "utf-8").trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+export function loadConfig(): GatewayConfig {
+  const telegramBotToken = process.env.TELEGRAM_BOT_TOKEN || undefined;
+  const telegramWebhookSecret = process.env.TELEGRAM_WEBHOOK_SECRET || undefined;
+
+  const telegramApiBaseUrl =
+    process.env.TELEGRAM_API_BASE_URL || "https://api.telegram.org";
+
+  const runtimePort = process.env.RUNTIME_HTTP_PORT || "7821";
+  const assistantRuntimeBaseUrl =
+    process.env.ASSISTANT_RUNTIME_BASE_URL || `http://localhost:${runtimePort}`;
+
+  const routingJson = process.env.GATEWAY_ASSISTANT_ROUTING_JSON || "{}";
+  const routingEntries = parseRoutingJson(routingJson);
+
+  const defaultAssistantId =
+    process.env.GATEWAY_DEFAULT_ASSISTANT_ID || undefined;
+
+  const unmappedPolicyRaw = process.env.GATEWAY_UNMAPPED_POLICY || "reject";
+  if (unmappedPolicyRaw !== "reject" && unmappedPolicyRaw !== "default") {
+    throw new Error(
+      `GATEWAY_UNMAPPED_POLICY must be "reject" or "default", got "${unmappedPolicyRaw}"`,
+    );
+  }
+  const unmappedPolicy = unmappedPolicyRaw;
+
+  if (unmappedPolicy === "default" && !defaultAssistantId) {
+    throw new Error(
+      'GATEWAY_DEFAULT_ASSISTANT_ID is required when GATEWAY_UNMAPPED_POLICY is "default"',
+    );
+  }
+
+  const portRaw = process.env.GATEWAY_PORT || "7830";
+  const port = Number(portRaw);
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    throw new Error("GATEWAY_PORT must be a valid port number");
+  }
+
+  const proxyEnabledRaw = process.env.GATEWAY_RUNTIME_PROXY_ENABLED;
+  if (proxyEnabledRaw !== undefined && proxyEnabledRaw !== "true" && proxyEnabledRaw !== "false") {
+    throw new Error(
+      `GATEWAY_RUNTIME_PROXY_ENABLED must be "true" or "false", got "${proxyEnabledRaw}"`,
+    );
+  }
+  const runtimeProxyEnabled = proxyEnabledRaw === "true";
+
+  const proxyRequireAuthRaw = process.env.GATEWAY_RUNTIME_PROXY_REQUIRE_AUTH;
+  if (proxyRequireAuthRaw !== undefined && proxyRequireAuthRaw !== "true" && proxyRequireAuthRaw !== "false") {
+    throw new Error(
+      `GATEWAY_RUNTIME_PROXY_REQUIRE_AUTH must be "true" or "false", got "${proxyRequireAuthRaw}"`,
+    );
+  }
+  const runtimeProxyRequireAuth = proxyRequireAuthRaw !== "false";
+
+  const runtimeBearerToken =
+    process.env.RUNTIME_BEARER_TOKEN || undefined;
+
+  const runtimeProxyBearerToken =
+    process.env.RUNTIME_PROXY_BEARER_TOKEN || readHttpTokenFile() || undefined;
+
+  const MAX_TIMEOUT_MS = 2_147_483_647; // 2^31 - 1, max safe setTimeout delay
+
+  const shutdownDrainMsRaw = process.env.GATEWAY_SHUTDOWN_DRAIN_MS || "5000";
+  const shutdownDrainMs = Number(shutdownDrainMsRaw);
+  if (!Number.isFinite(shutdownDrainMs) || shutdownDrainMs < 0) {
+    throw new Error("GATEWAY_SHUTDOWN_DRAIN_MS must be a non-negative number");
+  }
+  if (shutdownDrainMs > MAX_TIMEOUT_MS) {
+    throw new Error(
+      `GATEWAY_SHUTDOWN_DRAIN_MS must not exceed ${MAX_TIMEOUT_MS} (setTimeout max safe delay)`,
+    );
+  }
+
+  const runtimeTimeoutMs = Number(process.env.GATEWAY_RUNTIME_TIMEOUT_MS || "30000");
+  if (!Number.isFinite(runtimeTimeoutMs) || runtimeTimeoutMs <= 0) {
+    throw new Error("GATEWAY_RUNTIME_TIMEOUT_MS must be a positive number");
+  }
+
+  const runtimeMaxRetries = Number(process.env.GATEWAY_RUNTIME_MAX_RETRIES || "2");
+  if (!Number.isInteger(runtimeMaxRetries) || runtimeMaxRetries < 0) {
+    throw new Error("GATEWAY_RUNTIME_MAX_RETRIES must be a non-negative integer");
+  }
+
+  const runtimeInitialBackoffMs = Number(process.env.GATEWAY_RUNTIME_INITIAL_BACKOFF_MS || "500");
+  if (!Number.isFinite(runtimeInitialBackoffMs) || runtimeInitialBackoffMs <= 0) {
+    throw new Error("GATEWAY_RUNTIME_INITIAL_BACKOFF_MS must be a positive number");
+  }
+
+  const telegramTimeoutMs = Number(process.env.GATEWAY_TELEGRAM_TIMEOUT_MS || "15000");
+  if (!Number.isFinite(telegramTimeoutMs) || telegramTimeoutMs <= 0) {
+    throw new Error("GATEWAY_TELEGRAM_TIMEOUT_MS must be a positive number");
+  }
+
+  const telegramMaxRetries = Number(process.env.GATEWAY_TELEGRAM_MAX_RETRIES || "3");
+  if (!Number.isInteger(telegramMaxRetries) || telegramMaxRetries < 0) {
+    throw new Error("GATEWAY_TELEGRAM_MAX_RETRIES must be a non-negative integer");
+  }
+
+  const telegramInitialBackoffMs = Number(process.env.GATEWAY_TELEGRAM_INITIAL_BACKOFF_MS || "1000");
+  if (!Number.isFinite(telegramInitialBackoffMs) || telegramInitialBackoffMs <= 0) {
+    throw new Error("GATEWAY_TELEGRAM_INITIAL_BACKOFF_MS must be a positive number");
+  }
+
+  const maxWebhookPayloadBytes = Number(process.env.GATEWAY_MAX_WEBHOOK_PAYLOAD_BYTES || String(1024 * 1024));
+  if (!Number.isFinite(maxWebhookPayloadBytes) || maxWebhookPayloadBytes <= 0) {
+    throw new Error("GATEWAY_MAX_WEBHOOK_PAYLOAD_BYTES must be a positive number");
+  }
+
+  const maxAttachmentBytes = Number(process.env.GATEWAY_MAX_ATTACHMENT_BYTES || String(20 * 1024 * 1024));
+  if (!Number.isFinite(maxAttachmentBytes) || maxAttachmentBytes <= 0) {
+    throw new Error("GATEWAY_MAX_ATTACHMENT_BYTES must be a positive number");
+  }
+
+  const maxAttachmentConcurrency = Number(process.env.GATEWAY_MAX_ATTACHMENT_CONCURRENCY || "3");
+  if (!Number.isInteger(maxAttachmentConcurrency) || maxAttachmentConcurrency < 1) {
+    throw new Error("GATEWAY_MAX_ATTACHMENT_CONCURRENCY must be a positive integer");
+  }
+
+  if (runtimeProxyEnabled && runtimeProxyRequireAuth && !runtimeProxyBearerToken) {
+    throw new Error(
+      "RUNTIME_PROXY_BEARER_TOKEN is required when proxy is enabled with auth required",
+    );
+  }
+
+  const logFileDir = process.env.GATEWAY_LOG_DIR || undefined;
+
+  const logFileRetentionDays = Number(process.env.GATEWAY_LOG_RETENTION_DAYS || "30");
+  if (!Number.isInteger(logFileRetentionDays) || logFileRetentionDays < 1) {
+    throw new Error("GATEWAY_LOG_RETENTION_DAYS must be a positive integer");
+  }
+
+  const logFile: LogFileConfig = {
+    dir: logFileDir,
+    retentionDays: logFileRetentionDays,
+  };
+
+  log.info(
+    {
+      telegramApiBaseUrl,
+      assistantRuntimeBaseUrl,
+      routingEntryCount: routingEntries.length,
+      unmappedPolicy,
+      hasDefaultAssistant: !!defaultAssistantId,
+      port,
+      runtimeProxyEnabled,
+      runtimeProxyRequireAuth,
+    },
+    "Configuration loaded",
+  );
+
+  return {
+    assistantRuntimeBaseUrl,
+    defaultAssistantId,
+    logFile,
+    maxAttachmentBytes,
+    maxAttachmentConcurrency,
+    maxWebhookPayloadBytes,
+    port,
+    routingEntries,
+    runtimeBearerToken,
+    runtimeInitialBackoffMs,
+    runtimeMaxRetries,
+    runtimeProxyBearerToken,
+    runtimeProxyEnabled,
+    runtimeProxyRequireAuth,
+    runtimeTimeoutMs,
+    shutdownDrainMs,
+    telegramApiBaseUrl,
+    telegramBotToken,
+    telegramInitialBackoffMs,
+    telegramMaxRetries,
+    telegramTimeoutMs,
+    telegramWebhookSecret,
+    unmappedPolicy,
+  };
+}

package/src/dedup-cache.ts

@@ -0,0 +1,104 @@
+import { getLogger } from "./logger.js";
+
+const log = getLogger("dedup-cache");
+
+interface CacheEntry {
+  body: string;
+  status: number;
+  expiresAt: number;
+  /** When true, the first handler is still processing this update_id. */
+  processing?: boolean;
+}
+
+/**
+ * In-memory TTL cache for Telegram update_id deduplication.
+ * Prevents redundant normalization, routing, attachment downloads,
+ * and runtime forwarding when Telegram retries a webhook on timeout.
+ */
+export class DedupCache {
+  private cache = new Map<number, CacheEntry>();
+  private readonly ttlMs: number;
+  private readonly maxSize: number;
+
+  constructor(ttlMs = 5 * 60_000, maxSize = 10_000) {
+    this.ttlMs = ttlMs;
+    this.maxSize = maxSize;
+  }
+
+  /** Returns the cached response body+status if the update_id was already seen. */
+  get(updateId: number): { body: string; status: number } | undefined {
+    const entry = this.cache.get(updateId);
+    if (!entry) return undefined;
+    if (Date.now() > entry.expiresAt) {
+      this.cache.delete(updateId);
+      return undefined;
+    }
+    return { body: entry.body, status: entry.status };
+  }
+
+  /**
+   * Checks whether this update_id is already reserved or cached.
+   * If not, immediately reserves it with a "processing" sentinel so that
+   * concurrent retries are blocked before the handler finishes.
+   * Returns true if a new reservation was created (caller should proceed),
+   * false if the update_id was already present (caller should short-circuit).
+   */
+  reserve(updateId: number): boolean {
+    const existing = this.cache.get(updateId);
+    if (existing && Date.now() <= existing.expiresAt) {
+      return false;
+    }
+    // Clean up expired entry if present
+    if (existing) this.cache.delete(updateId);
+    this.set(updateId, '{"ok":true}', 200);
+    this.cache.get(updateId)!.processing = true;
+    return true;
+  }
+
+  /** Remove a reserved entry so Telegram can retry. */
+  unreserve(updateId: number): void {
+    const entry = this.cache.get(updateId);
+    if (entry?.processing) {
+      this.cache.delete(updateId);
+    }
+  }
+
+  /** Store a response for the given update_id. */
+  set(updateId: number, body: string, status: number): void {
+    // Evict expired entries if we're at capacity
+    if (this.cache.size >= this.maxSize) {
+      this.evictExpired();
+    }
+    // If still at capacity after eviction, drop the oldest entry
+    if (this.cache.size >= this.maxSize) {
+      const oldest = this.cache.keys().next().value;
+      if (oldest !== undefined) {
+        this.cache.delete(oldest);
+      }
+    }
+
+    this.cache.set(updateId, {
+      body,
+      status,
+      expiresAt: Date.now() + this.ttlMs,
+    });
+  }
+
+  get size(): number {
+    return this.cache.size;
+  }
+
+  private evictExpired(): void {
+    const now = Date.now();
+    let evicted = 0;
+    for (const [key, entry] of this.cache) {
+      if (now > entry.expiresAt) {
+        this.cache.delete(key);
+        evicted++;
+      }
+    }
+    if (evicted > 0) {
+      log.debug({ evicted }, "Evicted expired dedup cache entries");
+    }
+  }
+}

package/src/handlers/handle-inbound.ts

@@ -0,0 +1,104 @@
+import type { GatewayConfig } from "../config.js";
+import { getLogger } from "../logger.js";
+import { resolveAssistant, isRejection } from "../routing/resolve-assistant.js";
+import { forwardToRuntime } from "../runtime/client.js";
+import type { RuntimeInboundResponse } from "../runtime/client.js";
+import type { GatewayInboundEventV1 } from "../types.js";
+
+const log = getLogger("handle-inbound");
+
+export type InboundResult = {
+  forwarded: boolean;
+  rejected: boolean;
+  runtimeResponse?: RuntimeInboundResponse;
+  rejectionReason?: string;
+};
+
+export type TransportMetadataOverrides = {
+  hints?: string[];
+  uxBrief?: string;
+};
+
+export type HandleInboundOptions = {
+  attachmentIds?: string[];
+  transportMetadata?: TransportMetadataOverrides;
+};
+
+function normalizeTransportHints(hints: string[] | undefined): string[] {
+  if (!hints || hints.length === 0) return [];
+  const seen = new Set<string>();
+  const normalized: string[] = [];
+  for (const raw of hints) {
+    const trimmed = raw.trim();
+    if (!trimmed || seen.has(trimmed)) continue;
+    seen.add(trimmed);
+    normalized.push(trimmed);
+  }
+  return normalized;
+}
+
+export async function handleInbound(
+  config: GatewayConfig,
+  event: Omit<GatewayInboundEventV1, "routing">,
+  options?: HandleInboundOptions,
+): Promise<InboundResult> {
+  const routing = resolveAssistant(
+    config,
+    event.message.externalChatId,
+    event.sender.externalUserId,
+  );
+
+  if (isRejection(routing)) {
+    log.info(
+      { externalChatId: event.message.externalChatId, reason: routing.reason },
+      "Inbound event rejected by routing",
+    );
+    return { forwarded: false, rejected: true, rejectionReason: routing.reason };
+  }
+
+  const displayName = event.sender.displayName || event.sender.username;
+  const transportHints = normalizeTransportHints(options?.transportMetadata?.hints);
+  const transportUxBrief = options?.transportMetadata?.uxBrief?.trim();
+
+  try {
+    const response = await forwardToRuntime(config, routing.assistantId, {
+      sourceChannel: event.sourceChannel,
+      externalChatId: event.message.externalChatId,
+      externalMessageId: event.message.externalMessageId,
+      content: event.message.content,
+      ...(event.message.isEdit ? { isEdit: true } : {}),
+      senderName: displayName,
+      senderExternalUserId: event.sender.externalUserId,
+      senderUsername: event.sender.username,
+      sourceMetadata: {
+        updateId: event.source.updateId,
+        messageId: event.source.messageId,
+        chatType: event.source.chatType,
+        languageCode: event.sender.languageCode,
+        isBot: event.sender.isBot,
+        ...(transportHints.length > 0 ? { hints: transportHints } : {}),
+        ...(transportUxBrief ? { uxBrief: transportUxBrief } : {}),
+      },
+      ...(options?.attachmentIds?.length ? { attachmentIds: options.attachmentIds } : {}),
+    });
+
+    log.info(
+      {
+        assistantId: routing.assistantId,
+        routeSource: routing.routeSource,
+        eventId: response.eventId,
+        duplicate: response.duplicate,
+        hasReply: !!response.assistantMessage,
+      },
+      "Inbound event forwarded to runtime",
+    );
+
+    return { forwarded: true, rejected: false, runtimeResponse: response };
+  } catch (err) {
+    log.error(
+      { err, assistantId: routing.assistantId },
+      "Failed to forward inbound event to runtime",
+    );
+    return { forwarded: false, rejected: false };
+  }
+}

package/src/http/auth/bearer.ts

@@ -0,0 +1,34 @@
+import { timingSafeEqual } from "crypto";
+
+export type BearerAuthResult =
+  | { authorized: true }
+  | { authorized: false; reason: string };
+
+export function validateBearerToken(
+  authorizationHeader: string | null,
+  expectedToken: string,
+): BearerAuthResult {
+  if (!authorizationHeader) {
+    return { authorized: false, reason: "Missing Authorization header" };
+  }
+
+  if (!authorizationHeader.slice(0, 7).toLowerCase().startsWith("bearer ")) {
+    return { authorized: false, reason: "Invalid authorization scheme" };
+  }
+
+  const token = authorizationHeader.slice(7);
+  if (!token) {
+    return { authorized: false, reason: "Empty bearer token" };
+  }
+
+  const a = Buffer.from(token);
+  const b = Buffer.from(expectedToken);
+  if (a.length !== b.length) {
+    return { authorized: false, reason: "Invalid bearer token" };
+  }
+  if (!timingSafeEqual(a, b)) {
+    return { authorized: false, reason: "Invalid bearer token" };
+  }
+
+  return { authorized: true };
+}