vellum 0.2.8 → 0.2.9

package/src/inbound/public-ingress-urls.ts

@@ -1,19 +1,33 @@
 /**
  * Centralized URL builders for all public-facing ingress endpoints.
  *
- * Resolves the canonical public base URL via a fallback chain:
- *   ingress.publicBaseUrl → calls.webhookBaseUrl → env TWILIO_WEBHOOK_BASE_URL
+ * ## Source-of-truth precedence
  *
- * Supersedes the per-domain URL helpers in calls/twilio-webhook-urls.ts.
+ * The canonical public base URL is resolved through a two-level chain:
+ *
+ *   1. **User Settings** (`config.ingress.publicBaseUrl`) — set via the
+ *      Settings UI or `config set ingress.publicBaseUrl`. This is the
+ *      primary source of truth. When the assistant spawns or restarts
+ *      the gateway, this value is forwarded as the `INGRESS_PUBLIC_BASE_URL`
+ *      environment variable so both processes agree on the same URL.
+ *
+ *   2. **Environment variable** (`INGRESS_PUBLIC_BASE_URL`) — serves as a
+ *      fallback for operational use (e.g. direct gateway-only deployments
+ *      without the assistant, or CI overrides). When the assistant is
+ *      managing the gateway, the env var is set automatically from (1).
+ *
+ * This chain ensures that:
+ *   - The assistant's outbound callback URLs (Twilio webhooks, OAuth
+ *     redirect URIs, etc.) match the gateway's inbound signature
+ *     reconstruction URL.
+ *   - Changing the URL in Settings propagates to the gateway on restart,
+ *     eliminating Twilio signature mismatch risk.
+ *
+ * All public-facing ingress URL construction is centralized here.
  */
 
-import { getLogger } from '../util/logger.js';
-
-const log = getLogger('public-ingress-urls');
-
 export interface IngressConfig {
   ingress?: { publicBaseUrl?: string };
-  calls?: { webhookBaseUrl?: string };
 }
 
 /**
@@ -24,10 +38,8 @@ function normalizeUrl(url: string): string {
 }
 
 /**
- * Resolve the canonical public base URL with a three-level fallback chain:
- *   1. ingress.publicBaseUrl (preferred)
- *   2. calls.webhookBaseUrl (backward compat)
- *   3. TWILIO_WEBHOOK_BASE_URL env var (legacy, deprecated)
+ * Resolve the canonical public base URL using the precedence chain
+ * documented at the top of this module.
  *
  * Throws if no source provides a non-empty value.
  */
@@ -38,28 +50,14 @@ export function getPublicBaseUrl(config: IngressConfig): string {
     if (normalized) return normalized;
   }
 
-  const callsValue = config.calls?.webhookBaseUrl;
-  if (callsValue) {
-    const normalized = normalizeUrl(callsValue);
-    if (normalized) {
-      log.warn(
-        'Using calls.webhookBaseUrl as public base URL — set ingress.publicBaseUrl instead.',
-      );
-      return normalized;
-    }
-  }
-
-  const envValue = process.env.TWILIO_WEBHOOK_BASE_URL;
-  if (envValue) {
-    log.warn(
-      'TWILIO_WEBHOOK_BASE_URL env var is deprecated — set ingress.publicBaseUrl in config instead.',
-    );
-    const normalized = normalizeUrl(envValue);
+  const ingressEnvValue = process.env.INGRESS_PUBLIC_BASE_URL;
+  if (ingressEnvValue) {
+    const normalized = normalizeUrl(ingressEnvValue);
     if (normalized) return normalized;
   }
 
   throw new Error(
-    'No public base URL configured. Set ingress.publicBaseUrl in config, calls.webhookBaseUrl, or TWILIO_WEBHOOK_BASE_URL env var.',
+    'No public base URL configured. Set ingress.publicBaseUrl in config or INGRESS_PUBLIC_BASE_URL env var.',
   );
 }
 
@@ -104,3 +102,11 @@ export function getOAuthCallbackUrl(config: IngressConfig): string {
   const base = getPublicBaseUrl(config);
   return `${base}/webhooks/oauth/callback`;
 }
+
+/**
+ * Build the Telegram webhook URL.
+ */
+export function getTelegramWebhookUrl(config: IngressConfig): string {
+  const base = getPublicBaseUrl(config);
+  return `${base}/webhooks/telegram`;
+}

package/src/memory/db.ts

@@ -241,6 +241,7 @@ export function initializeDb(): void {
       message_id TEXT REFERENCES messages(id) ON DELETE CASCADE,
       status TEXT NOT NULL DEFAULT 'running',
       pending_confirmation TEXT,
+      pending_secret TEXT,
       input_tokens INTEGER NOT NULL DEFAULT 0,
       output_tokens INTEGER NOT NULL DEFAULT 0,
       estimated_cost REAL NOT NULL DEFAULT 0,
@@ -250,6 +251,8 @@ export function initializeDb(): void {
     )
   `);
 
+  try { database.run(/*sql*/ `ALTER TABLE message_runs ADD COLUMN pending_secret TEXT`); } catch (e) { log.debug({ err: e }, 'ALTER TABLE message_runs ADD COLUMN pending_secret (likely already exists)'); }
+
   database.run(/*sql*/ `
     CREATE TABLE IF NOT EXISTS reminders (
       id TEXT PRIMARY KEY,
@@ -418,7 +421,6 @@ export function initializeDb(): void {
     CREATE TABLE IF NOT EXISTS llm_usage_events (
       id TEXT PRIMARY KEY,
       created_at INTEGER NOT NULL,
-      assistant_id TEXT,
       conversation_id TEXT,
       run_id TEXT,
       request_id TEXT,
@@ -548,6 +550,7 @@ export function initializeDb(): void {
   migrateMemoryItemsScopeSaltedFingerprints(database);
   migrateAssistantIdToSelf(database);
   migrateRemoveAssistantIdColumns(database);
+  migrateLlmUsageEventsDropAssistantId(database);
 
   // Indexes for query performance on large datasets
   database.run(/*sql*/ `CREATE INDEX IF NOT EXISTS idx_llm_request_logs_conv_created ON llm_request_logs(conversation_id, created_at)`);
@@ -610,7 +613,6 @@ export function initializeDb(): void {
   database.run(/*sql*/ `CREATE INDEX IF NOT EXISTS idx_accounts_status ON accounts(status)`);
 
   database.run(/*sql*/ `CREATE INDEX IF NOT EXISTS idx_llm_usage_events_created_at ON llm_usage_events(created_at)`);
-  database.run(/*sql*/ `CREATE INDEX IF NOT EXISTS idx_llm_usage_events_assistant_id ON llm_usage_events(assistant_id)`);
   database.run(/*sql*/ `CREATE INDEX IF NOT EXISTS idx_llm_usage_events_provider ON llm_usage_events(provider)`);
   database.run(/*sql*/ `CREATE INDEX IF NOT EXISTS idx_llm_usage_events_model ON llm_usage_events(model)`);
   database.run(/*sql*/ `CREATE INDEX IF NOT EXISTS idx_llm_usage_events_actor ON llm_usage_events(actor)`);
@@ -1438,19 +1440,22 @@ function migrateAssistantIdToSelf(database: ReturnType<typeof drizzle<typeof sch
 }
 
 /**
- * One-shot migration: rebuild the four tables that previously stored assistant_id
- * to remove that column now that all rows are keyed to the implicit single-tenant
- * identity ("self").
+ * One-shot migration: rebuild tables that previously stored assistant_id to remove
+ * that column now that all rows are keyed to the implicit single-tenant identity ("self").
  *
  * Must run AFTER migrateAssistantIdToSelf (which normalises all values to "self")
  * so there are no constraint violations when recreating the tables without the
  * assistant_id dimension.
  *
+ * Each table section is guarded by a DDL check so this is safe on fresh installs
+ * where the column was never created in the first place.
+ *
  * Tables rebuilt:
  *   - conversation_keys       UNIQUE (conversation_key)
  *   - attachments             no structural unique; content-dedup index updated
  *   - channel_inbound_events  UNIQUE (source_channel, external_chat_id, external_message_id)
  *   - message_runs            no unique constraint on assistant_id
+ *   - llm_usage_events        nullable column with no constraint
  */
 function migrateRemoveAssistantIdColumns(database: ReturnType<typeof drizzle<typeof schema>>): void {
   const raw = (database as unknown as { $client: Database }).$client;
@@ -1588,6 +1593,128 @@ function migrateRemoveAssistantIdColumns(database: ReturnType<typeof drizzle<typ
       raw.exec(/*sql*/ `ALTER TABLE message_runs_new RENAME TO message_runs`);
     }
 
+    // --- llm_usage_events ---
+    const lueDdl = raw.query(
+      `SELECT sql FROM sqlite_master WHERE type = 'table' AND name = 'llm_usage_events'`,
+    ).get() as { sql: string } | null;
+    if (lueDdl?.sql.includes('assistant_id')) {
+      raw.exec(/*sql*/ `
+        CREATE TABLE llm_usage_events_new (
+          id TEXT PRIMARY KEY,
+          created_at INTEGER NOT NULL,
+          conversation_id TEXT,
+          run_id TEXT,
+          request_id TEXT,
+          actor TEXT NOT NULL,
+          provider TEXT NOT NULL,
+          model TEXT NOT NULL,
+          input_tokens INTEGER NOT NULL,
+          output_tokens INTEGER NOT NULL,
+          cache_creation_input_tokens INTEGER,
+          cache_read_input_tokens INTEGER,
+          estimated_cost_usd REAL,
+          pricing_status TEXT NOT NULL,
+          metadata_json TEXT
+        )
+      `);
+      raw.exec(/*sql*/ `
+        INSERT INTO llm_usage_events_new (
+          id, created_at, conversation_id, run_id, request_id, actor, provider, model,
+          input_tokens, output_tokens, cache_creation_input_tokens, cache_read_input_tokens,
+          estimated_cost_usd, pricing_status, metadata_json
+        )
+        SELECT
+          id, created_at, conversation_id, run_id, request_id, actor, provider, model,
+          input_tokens, output_tokens, cache_creation_input_tokens, cache_read_input_tokens,
+          estimated_cost_usd, pricing_status, metadata_json
+        FROM llm_usage_events
+      `);
+      raw.exec(/*sql*/ `DROP TABLE llm_usage_events`);
+      raw.exec(/*sql*/ `ALTER TABLE llm_usage_events_new RENAME TO llm_usage_events`);
+    }
+
+    raw.query(
+      `INSERT OR IGNORE INTO memory_checkpoints (key, value, updated_at) VALUES (?, '1', ?)`,
+    ).run(checkpointKey, Date.now());
+
+    raw.exec('COMMIT');
+  } catch (e) {
+    try { raw.exec('ROLLBACK'); } catch { /* no active transaction */ }
+    throw e;
+  } finally {
+    raw.exec('PRAGMA foreign_keys = ON');
+  }
+}
+
+/**
+ * One-shot migration: rebuild llm_usage_events to drop the assistant_id column.
+ *
+ * This is a SEPARATE migration from migrateRemoveAssistantIdColumns so that installs
+ * where the 4-table version of that migration already ran (checkpoint already set)
+ * still get the llm_usage_events column removed. Without a separate checkpoint key,
+ * those installs would skip the llm_usage_events rebuild entirely.
+ *
+ * Safe on fresh installs (DDL guard exits early) and idempotent via checkpoint.
+ */
+function migrateLlmUsageEventsDropAssistantId(database: ReturnType<typeof drizzle<typeof schema>>): void {
+  const raw = (database as unknown as { $client: Database }).$client;
+  const checkpointKey = 'migration_remove_assistant_id_lue_v1';
+  const checkpoint = raw.query(
+    `SELECT 1 FROM memory_checkpoints WHERE key = ?`,
+  ).get(checkpointKey);
+  if (checkpoint) return;
+
+  // DDL guard: if the column was already removed (fresh install or migrateRemoveAssistantIdColumns
+  // ran with the llm_usage_events block), just record the checkpoint and exit.
+  const lueDdl = raw.query(
+    `SELECT sql FROM sqlite_master WHERE type = 'table' AND name = 'llm_usage_events'`,
+  ).get() as { sql: string } | null;
+
+  if (!lueDdl?.sql.includes('assistant_id')) {
+    raw.query(
+      `INSERT OR IGNORE INTO memory_checkpoints (key, value, updated_at) VALUES (?, '1', ?)`,
+    ).run(checkpointKey, Date.now());
+    return;
+  }
+
+  raw.exec('PRAGMA foreign_keys = OFF');
+  try {
+    raw.exec('BEGIN');
+
+    raw.exec(/*sql*/ `
+      CREATE TABLE llm_usage_events_new (
+        id TEXT PRIMARY KEY,
+        created_at INTEGER NOT NULL,
+        conversation_id TEXT,
+        run_id TEXT,
+        request_id TEXT,
+        actor TEXT NOT NULL,
+        provider TEXT NOT NULL,
+        model TEXT NOT NULL,
+        input_tokens INTEGER NOT NULL,
+        output_tokens INTEGER NOT NULL,
+        cache_creation_input_tokens INTEGER,
+        cache_read_input_tokens INTEGER,
+        estimated_cost_usd REAL,
+        pricing_status TEXT NOT NULL,
+        metadata_json TEXT
+      )
+    `);
+    raw.exec(/*sql*/ `
+      INSERT INTO llm_usage_events_new (
+        id, created_at, conversation_id, run_id, request_id, actor, provider, model,
+        input_tokens, output_tokens, cache_creation_input_tokens, cache_read_input_tokens,
+        estimated_cost_usd, pricing_status, metadata_json
+      )
+      SELECT
+        id, created_at, conversation_id, run_id, request_id, actor, provider, model,
+        input_tokens, output_tokens, cache_creation_input_tokens, cache_read_input_tokens,
+        estimated_cost_usd, pricing_status, metadata_json
+      FROM llm_usage_events
+    `);
+    raw.exec(/*sql*/ `DROP TABLE llm_usage_events`);
+    raw.exec(/*sql*/ `ALTER TABLE llm_usage_events_new RENAME TO llm_usage_events`);
+
     raw.query(
       `INSERT OR IGNORE INTO memory_checkpoints (key, value, updated_at) VALUES (?, '1', ?)`,
     ).run(checkpointKey, Date.now());

package/src/memory/llm-usage-store.ts

@@ -16,7 +16,6 @@ export function recordUsageEvent(input: UsageEventInput, pricing: PricingResult)
   db.insert(llmUsageEvents).values({
     id: event.id,
     createdAt: event.createdAt,
-    assistantId: 'self',
     conversationId: event.conversationId,
     runId: event.runId,
     requestId: event.requestId,

package/src/memory/runs-store.ts

@@ -3,6 +3,7 @@
  *
  * Runs track the lifecycle of an agent loop triggered by a user message:
  *   running → needs_confirmation → running → completed | failed
+ *   running → needs_secret       → running → completed | failed
  */
 
 import { eq, inArray } from 'drizzle-orm';
@@ -14,7 +15,7 @@ import { messageRuns } from './schema.js';
 // Types
 // ---------------------------------------------------------------------------
 
-export type RunStatus = 'running' | 'needs_confirmation' | 'completed' | 'failed';
+export type RunStatus = 'running' | 'needs_confirmation' | 'needs_secret' | 'completed' | 'failed';
 
 export interface PendingConfirmation {
   toolName: string;
@@ -34,12 +35,24 @@ export interface PendingConfirmation {
   persistentDecisionsAllowed?: boolean;
 }
 
+export interface PendingSecret {
+  requestId: string;
+  service: string;
+  field: string;
+  label: string;
+  description?: string;
+  placeholder?: string;
+  purpose?: string;
+  allowOneTimeSend?: boolean;
+}
+
 export interface Run {
   id: string;
   conversationId: string;
   messageId: string | null;
   status: RunStatus;
   pendingConfirmation: PendingConfirmation | null;
+  pendingSecret: PendingSecret | null;
   inputTokens: number;
   outputTokens: number;
   estimatedCost: number;
@@ -63,12 +76,17 @@ function rowToRun(row: typeof messageRuns.$inferSelect): Run {
   if (row.pendingConfirmation) {
     try { pendingConfirmation = JSON.parse(row.pendingConfirmation); } catch { /* malformed */ }
   }
+  let pendingSecret: PendingSecret | null = null;
+  if (row.pendingSecret) {
+    try { pendingSecret = JSON.parse(row.pendingSecret); } catch { /* malformed */ }
+  }
   return {
     id: row.id,
     conversationId: row.conversationId,
     messageId: row.messageId,
     status: row.status as RunStatus,
     pendingConfirmation,
+    pendingSecret,
     inputTokens: row.inputTokens,
     outputTokens: row.outputTokens,
     estimatedCost: row.estimatedCost,
@@ -96,6 +114,7 @@ export function createRun(
     messageId: messageId ?? null,
     status: 'running' as const,
     pendingConfirmation: null,
+    pendingSecret: null,
     inputTokens: 0,
     outputTokens: 0,
     estimatedCost: 0,
@@ -144,6 +163,35 @@ export function clearRunConfirmation(runId: string): void {
     .run();
 }
 
+export function setRunSecret(
+  runId: string,
+  secret: PendingSecret,
+): void {
+  const db = getDb();
+  const now = Date.now();
+  db.update(messageRuns)
+    .set({
+      status: 'needs_secret',
+      pendingSecret: JSON.stringify(secret),
+      updatedAt: now,
+    })
+    .where(eq(messageRuns.id, runId))
+    .run();
+}
+
+export function clearRunSecret(runId: string): void {
+  const db = getDb();
+  const now = Date.now();
+  db.update(messageRuns)
+    .set({
+      status: 'running',
+      pendingSecret: null,
+      updatedAt: now,
+    })
+    .where(eq(messageRuns.id, runId))
+    .run();
+}
+
 export function completeRun(runId: string, usage?: RunUsage): void {
   const db = getDb();
   const now = Date.now();
@@ -177,13 +225,13 @@ export function failRun(runId: string, error: string): void {
 /**
  * Mark all non-terminal runs as failed.
  * Called on startup to recover from daemon restarts that left runs
- * in running/needs_confirmation with no in-memory state to resolve them.
+ * in running/needs_confirmation/needs_secret with no in-memory state to resolve them.
  * Returns the number of rows affected.
  */
 export function failOrphanedRuns(): number {
   const db = getDb();
   const now = Date.now();
-  const activeStatuses = ['running', 'needs_confirmation'];
+  const activeStatuses = ['running', 'needs_confirmation', 'needs_secret'];
 
   // Count first so we can report how many were recovered.
   const active = db.select({ id: messageRuns.id })

package/src/memory/schema.ts

@@ -209,8 +209,9 @@ export const messageRuns = sqliteTable('message_runs', {
     .references(() => conversations.id, { onDelete: 'cascade' }),
   messageId: text('message_id')
     .references(() => messages.id, { onDelete: 'cascade' }),
-  status: text('status').notNull().default('running'),          // running | needs_confirmation | completed | failed
+  status: text('status').notNull().default('running'),          // running | needs_confirmation | needs_secret | completed | failed
   pendingConfirmation: text('pending_confirmation'),            // JSON when status=needs_confirmation
+  pendingSecret: text('pending_secret'),                        // JSON when status=needs_secret
   inputTokens: integer('input_tokens').notNull().default(0),
   outputTokens: integer('output_tokens').notNull().default(0),
   estimatedCost: real('estimated_cost').notNull().default(0),
@@ -519,7 +520,6 @@ export const llmRequestLogs = sqliteTable('llm_request_logs', {
 export const llmUsageEvents = sqliteTable('llm_usage_events', {
   id: text('id').primaryKey(),
   createdAt: integer('created_at').notNull(),
-  assistantId: text('assistant_id'),
   conversationId: text('conversation_id'),
   runId: text('run_id'),
   requestId: text('request_id'),

package/src/runtime/gateway-client.ts

@@ -15,10 +15,16 @@ export interface ChannelReplyPayload {
 export async function deliverChannelReply(
   callbackUrl: string,
   payload: ChannelReplyPayload,
+  bearerToken?: string,
 ): Promise<void> {
+  const headers: Record<string, string> = { 'Content-Type': 'application/json' };
+  if (bearerToken) {
+    headers['Authorization'] = `Bearer ${bearerToken}`;
+  }
+
   const response = await fetch(callbackUrl, {
     method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
+    headers,
     body: JSON.stringify(payload),
     signal: AbortSignal.timeout(DELIVERY_TIMEOUT_MS),
   });

package/src/runtime/http-server.ts

@@ -30,6 +30,7 @@ import {
   handleCreateRun,
   handleGetRun,
   handleRunDecision,
+  handleRunSecret,
   handleAddTrustRule,
 } from './routes/run-routes.js';
 import {
@@ -65,6 +66,7 @@ import {
 } from '../calls/twilio-routes.js';
 import { RelayConnection, activeRelayConnections } from '../calls/relay-server.js';
 import type { RelayWebSocketData } from '../calls/relay-server.js';
+import { handleSubscribeAssistantEvents } from './routes/events-routes.js';
 import { consumeCallback, consumeCallbackError } from '../security/oauth-callback-registry.js';
 
 // Re-export shared types so existing consumers don't need to update imports
@@ -145,16 +147,21 @@ const GATEWAY_SUBPATH_MAP: Record<string, string> = {
 const GATEWAY_ONLY_BLOCKED_SUBPATHS = new Set(['voice-webhook', 'status', 'connect-action']);
 
 /**
- * Check if a request origin is from localhost / loopback.
+ * Check if a request origin is from a private/internal network address.
+ * Extracts the hostname from the Origin header and validates it against
+ * isPrivateAddress(), consistent with the isPrivateNetworkPeer check.
  */
-function isLoopbackOrigin(req: Request): boolean {
+function isPrivateNetworkOrigin(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';
+    if (host === 'localhost') return true;
+    // URL.hostname wraps IPv6 addresses in brackets (e.g. "[::1]") — strip them
+    const rawHost = host.startsWith('[') && host.endsWith(']') ? host.slice(1, -1) : host;
+    return isPrivateAddress(rawHost);
   } catch {
     return false;
   }
@@ -167,6 +174,69 @@ function isLoopbackHost(hostname: string): boolean {
   return hostname === '127.0.0.1' || hostname === '::1' || hostname === 'localhost';
 }
 
+/**
+ * Check if the actual peer/remote address of a connection is from a
+ * private/internal network. Uses Bun's server.requestIP() to get the
+ * real peer address, which cannot be spoofed unlike the Origin header.
+ *
+ * Accepts loopback, RFC 1918 private IPv4, link-local, and RFC 4193
+ * unique-local IPv6 — including their IPv4-mapped IPv6 forms. This
+ * supports container/pod deployments (e.g. Kubernetes sidecars) where
+ * gateway and runtime communicate over pod-internal private IPs.
+ */
+function isPrivateNetworkPeer(server: { requestIP(req: Request): { address: string; family: string; port: number } | null }, req: Request): boolean {
+  const ip = server.requestIP(req);
+  if (!ip) return false;
+  return isPrivateAddress(ip.address);
+}
+
+/**
+ * @internal Exported for testing.
+ *
+ * Determine whether an IP address string belongs to a private/internal
+ * network range:
+ *   - Loopback: 127.0.0.0/8, ::1
+ *   - RFC 1918: 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16
+ *   - Link-local: 169.254.0.0/16
+ *   - IPv6 unique local: fc00::/7 (fc00::–fdff::)
+ *   - IPv4-mapped IPv6 variants of all of the above (::ffff:x.x.x.x)
+ */
+export function isPrivateAddress(addr: string): boolean {
+  // Handle IPv4-mapped IPv6 (e.g. ::ffff:10.0.0.1) — extract the IPv4 part
+  const v4Mapped = addr.match(/^::ffff:(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/i);
+  const normalized = v4Mapped ? v4Mapped[1] : addr;
+
+  // IPv4 checks
+  if (normalized.includes('.')) {
+    const parts = normalized.split('.').map(Number);
+    if (parts.length !== 4 || parts.some(p => isNaN(p) || p < 0 || p > 255)) return false;
+
+    // Loopback: 127.0.0.0/8
+    if (parts[0] === 127) return true;
+    // 10.0.0.0/8
+    if (parts[0] === 10) return true;
+    // 172.16.0.0/12 (172.16.x.x – 172.31.x.x)
+    if (parts[0] === 172 && parts[1] >= 16 && parts[1] <= 31) return true;
+    // 192.168.0.0/16
+    if (parts[0] === 192 && parts[1] === 168) return true;
+    // Link-local: 169.254.0.0/16
+    if (parts[0] === 169 && parts[1] === 254) return true;
+
+    return false;
+  }
+
+  // IPv6 checks
+  const lower = normalized.toLowerCase();
+  // Loopback
+  if (lower === '::1') return true;
+  // Unique local: fc00::/7 (fc00:: through fdff::)
+  if (lower.startsWith('fc') || lower.startsWith('fd')) return true;
+  // Link-local: fe80::/10
+  if (lower.startsWith('fe80')) return true;
+
+  return false;
+}
+
 /**
  * Validate a Twilio webhook request's X-Twilio-Signature header.
  *
@@ -276,6 +346,11 @@ export class RuntimeHttpServer {
     this.interfacesDir = options.interfacesDir ?? null;
   }
 
+  /** The port the server is actually listening on (resolved after start). */
+  get actualPort(): number {
+    return this.server?.port ?? this.port;
+  }
+
   async start(): Promise<void> {
     this.server = Bun.serve<RelayWebSocketData>({
       port: this.port,
@@ -332,7 +407,7 @@ export class RuntimeHttpServer {
       // 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');
+    log.info({ port: this.actualPort, hostname: this.hostname, auth: !!this.bearerToken }, 'Runtime HTTP server listening');
   }
 
   async stop(): Promise<void> {
@@ -370,9 +445,12 @@ 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
+      // In gateway_only mode, only allow relay connections from private network peers.
+      // Primary check: actual peer address (cannot be spoofed) — accepts loopback
+      // and RFC 1918/4193 private addresses to support container deployments.
+      // Secondary check: Origin header (defense in depth).
       const config = loadConfig();
-      if (config.ingress.mode === 'gateway_only' && !isLoopbackOrigin(req)) {
+      if (config.ingress.mode === 'gateway_only' && (!isPrivateNetworkPeer(server, req) || !isPrivateNetworkOrigin(req))) {
         return Response.json(
           { error: 'Direct relay access disabled in gateway-only mode', code: 'GATEWAY_ONLY' },
           { status: 403 },
@@ -580,8 +658,8 @@ export class RuntimeHttpServer {
         return await handleCreateRun(req, this.runOrchestrator);
       }
 
-      // Match runs/:runId, runs/:runId/decision, runs/:runId/trust-rule
-      const runsMatch = endpoint.match(/^runs\/([^/]+)(\/decision|\/trust-rule)?$/);
+      // Match runs/:runId, runs/:runId/decision, runs/:runId/trust-rule, runs/:runId/secret
+      const runsMatch = endpoint.match(/^runs\/([^/]+)(\/decision|\/trust-rule|\/secret)?$/);
       if (runsMatch) {
         if (!this.runOrchestrator) {
           return Response.json({ error: 'Run orchestration not configured' }, { status: 503 });
@@ -590,6 +668,9 @@ export class RuntimeHttpServer {
         if (runsMatch[2] === '/decision' && req.method === 'POST') {
           return await handleRunDecision(runId, req, this.runOrchestrator);
         }
+        if (runsMatch[2] === '/secret' && req.method === 'POST') {
+          return await handleRunSecret(runId, req, this.runOrchestrator);
+        }
         if (runsMatch[2] === '/trust-rule' && req.method === 'POST') {
           const run = this.runOrchestrator.getRun(runId);
           if (!run) {
@@ -612,7 +693,7 @@ export class RuntimeHttpServer {
       }
 
       if (endpoint === 'channels/inbound' && req.method === 'POST') {
-        return await handleChannelInbound(req, this.processMessage);
+        return await handleChannelInbound(req, this.processMessage, this.bearerToken);
       }
 
       if (endpoint === 'channels/delivery-ack' && req.method === 'POST') {
@@ -689,6 +770,10 @@ export class RuntimeHttpServer {
         return await handleConnectAction(fakeReq);
       }
 
+      if (endpoint === 'events' && req.method === 'GET') {
+        return handleSubscribeAssistantEvents(req, url);
+      }
+
       // ── 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 };
@@ -833,7 +918,7 @@ export class RuntimeHttpServer {
             chatId: externalChatId,
             text: rendered.text || undefined,
             attachments: replyAttachments.length > 0 ? replyAttachments : undefined,
-          });
+          }, this.bearerToken);
         }
         break;
       }