vellum 0.2.7 → 0.2.9

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,13 +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;
-  assistantId: string;
   conversationId: string;
   messageId: string | null;
   status: RunStatus;
   pendingConfirmation: PendingConfirmation | null;
+  pendingSecret: PendingSecret | null;
   inputTokens: number;
   outputTokens: number;
   estimatedCost: number;
@@ -64,13 +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,
-    assistantId: row.assistantId,
     conversationId: row.conversationId,
     messageId: row.messageId,
     status: row.status as RunStatus,
     pendingConfirmation,
+    pendingSecret,
     inputTokens: row.inputTokens,
     outputTokens: row.outputTokens,
     estimatedCost: row.estimatedCost,
@@ -94,11 +110,11 @@ export function createRun(
 
   const row = {
     id,
-    assistantId: 'self',
     conversationId,
     messageId: messageId ?? null,
     status: 'running' as const,
     pendingConfirmation: null,
+    pendingSecret: null,
     inputTokens: 0,
     outputTokens: 0,
     estimatedCost: 0,
@@ -147,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();
@@ -180,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

@@ -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,14 +204,14 @@ 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' }),
   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),
@@ -523,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

@@ -12,7 +12,7 @@ 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 { getWebhookBaseUrl } from '../calls/twilio-webhook-urls.js';
+import { getPublicBaseUrl } from '../inbound/public-ingress-urls.js';
 import type { RunOrchestrator } from './run-orchestrator.js';
 
 // Route handlers — grouped by domain
@@ -30,6 +30,7 @@ import {
   handleCreateRun,
   handleGetRun,
   handleRunDecision,
+  handleRunSecret,
   handleAddTrustRule,
 } from './routes/run-routes.js';
 import {
@@ -65,6 +66,8 @@ 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
 export type {
@@ -137,6 +140,103 @@ 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 a private/internal network address.
+ * Extracts the hostname from the Origin header and validates it against
+ * isPrivateAddress(), consistent with the isPrivateNetworkPeer check.
+ */
+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;
+    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;
+  }
+}
+
+/**
+ * Check if a hostname is a loopback address.
+ */
+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.
  *
@@ -186,7 +286,7 @@ async function validateTwilioWebhook(
   // used to compute the HMAC-SHA1 signature.
   let publicBaseUrl: string | undefined;
   try {
-    publicBaseUrl = getWebhookBaseUrl(loadConfig());
+    publicBaseUrl = getPublicBaseUrl(loadConfig());
   } catch {
     // No webhook base URL configured — fall back to using req.url as-is
   }
@@ -246,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,
@@ -289,7 +394,20 @@ export class RuntimeHttpServer {
       }, 30_000);
     }
 
-    log.info({ port: this.port, hostname: this.hostname, auth: !!this.bearerToken }, 'Runtime HTTP server listening');
+    // 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.actualPort, hostname: this.hostname, auth: !!this.bearerToken }, 'Runtime HTTP server listening');
   }
 
   async stop(): Promise<void> {
@@ -327,6 +445,18 @@ 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 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' && (!isPrivateNetworkPeer(server, req) || !isPrivateNetworkOrigin(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) {
@@ -356,6 +486,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;
@@ -519,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 });
@@ -529,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) {
@@ -551,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') {
@@ -628,6 +770,31 @@ 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 };
+        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) {
@@ -751,7 +918,7 @@ export class RuntimeHttpServer {
             chatId: externalChatId,
             text: rendered.text || undefined,
             attachments: replyAttachments.length > 0 ? replyAttachments : undefined,
-          });
+          }, this.bearerToken);
         }
         break;
       }

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

@@ -42,6 +42,7 @@ export async function handleDeleteConversation(req: Request): Promise<Response>
 export async function handleChannelInbound(
   req: Request,
   processMessage?: MessageProcessor,
+  bearerToken?: string,
 ): Promise<Response> {
   const body = await req.json() as {
     sourceChannel?: string;
@@ -229,6 +230,7 @@ export async function handleChannelInbound(
       metadataHints,
       metadataUxBrief,
       replyCallbackUrl,
+      bearerToken,
     });
   }
 
@@ -250,6 +252,7 @@ interface BackgroundProcessingParams {
   metadataHints: string[];
   metadataUxBrief?: string;
   replyCallbackUrl?: string;
+  bearerToken?: string;
 }
 
 function processChannelMessageInBackground(params: BackgroundProcessingParams): void {
@@ -264,6 +267,7 @@ function processChannelMessageInBackground(params: BackgroundProcessingParams):
     metadataHints,
     metadataUxBrief,
     replyCallbackUrl,
+    bearerToken,
   } = params;
 
   (async () => {
@@ -285,7 +289,7 @@ function processChannelMessageInBackground(params: BackgroundProcessingParams):
       channelDeliveryStore.markProcessed(eventId);
 
       if (replyCallbackUrl) {
-        await deliverReplyViaCallback(conversationId, externalChatId, replyCallbackUrl);
+        await deliverReplyViaCallback(conversationId, externalChatId, replyCallbackUrl, bearerToken);
       }
     } catch (err) {
       log.error({ err, conversationId }, 'Background channel message processing failed');
@@ -298,6 +302,7 @@ async function deliverReplyViaCallback(
   conversationId: string,
   externalChatId: string,
   callbackUrl: string,
+  bearerToken?: string,
 ): Promise<void> {
   const msgs = conversationStore.getMessages(conversationId);
   for (let i = msgs.length - 1; i >= 0; i--) {
@@ -320,7 +325,7 @@ async function deliverReplyViaCallback(
           chatId: externalChatId,
           text: rendered.text || undefined,
           attachments: replyAttachments.length > 0 ? replyAttachments : undefined,
-        });
+        }, bearerToken);
       }
       break;
     }

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

@@ -0,0 +1,79 @@
+/**
+ * Route handler for the assistant-events SSE endpoint.
+ *
+ * GET /v1/events?conversationKey=...
+ *
+ * Auth is enforced by RuntimeHttpServer before this handler is called.
+ * Subscribers receive all assistant events scoped to the given conversation.
+ */
+
+import { getOrCreateConversation } from '../../memory/conversation-key-store.js';
+import { assistantEventHub } from '../assistant-event-hub.js';
+import { formatSseFrame } from '../assistant-event.js';
+import type { AssistantEventSubscription } from '../assistant-event-hub.js';
+
+/**
+ * Stream assistant events as Server-Sent Events for a specific conversation.
+ *
+ * Query params:
+ *   conversationKey — required; scopes the stream to one conversation.
+ */
+export function handleSubscribeAssistantEvents(
+  req: Request,
+  url: URL,
+): Response {
+  const conversationKey = url.searchParams.get('conversationKey');
+  if (!conversationKey) {
+    return Response.json({ error: 'conversationKey is required' }, { status: 400 });
+  }
+
+  const mapping = getOrCreateConversation(conversationKey);
+  const encoder = new TextEncoder();
+  let sub: AssistantEventSubscription | null = null;
+
+  // Allow up to 16 queued frames before treating the consumer as stalled.
+  // This absorbs normal token-stream bursts without prematurely closing the
+  // connection, while still shedding genuinely slow clients.
+  const stream = new ReadableStream({
+    start(controller) {
+      // 'self' is the assistantId that RunOrchestrator assigns to all HTTP-run events
+      // (see buildAssistantEvent('self', ...) in run-orchestrator.ts). This endpoint
+      // is part of the HTTP runtime API, so only HTTP-run events are relevant here.
+      // IPC/daemon events use a different assistantId ('default') and reach desktop
+      // clients through a separate channel — they are intentionally excluded.
+      sub = assistantEventHub.subscribe(
+        { assistantId: 'self', sessionId: mapping.conversationId },
+        (event) => {
+          try {
+            // Shed stalled consumers: desiredSize <= 0 means the 16-event buffer
+            // is full and the client isn't draining it.
+            if (controller.desiredSize !== null && controller.desiredSize <= 0) {
+              sub?.dispose();
+              try { controller.close(); } catch { /* already closed */ }
+              return;
+            }
+            controller.enqueue(encoder.encode(formatSseFrame(event)));
+          } catch {
+            sub?.dispose();
+          }
+        },
+      );
+
+      req.signal.addEventListener('abort', () => {
+        sub?.dispose();
+        try { controller.close(); } catch { /* already closed */ }
+      }, { once: true });
+    },
+    cancel() {
+      sub?.dispose();
+    },
+  }, new CountQueuingStrategy({ highWaterMark: 16 }));
+
+  return new Response(stream, {
+    headers: {
+      'Content-Type': 'text/event-stream',
+      'Cache-Control': 'no-cache',
+      'Connection': 'keep-alive',
+    },
+  });
+}

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

@@ -88,6 +88,7 @@ export function handleGetRun(
     status: run.status,
     messageId: run.messageId,
     pendingConfirmation: run.pendingConfirmation,
+    pendingSecret: run.pendingSecret,
     error: run.error,
     createdAt: new Date(run.createdAt).toISOString(),
     updatedAt: new Date(run.updatedAt).toISOString(),
@@ -217,3 +218,45 @@ export async function handleAddTrustRule(
     return Response.json({ error: 'Failed to add trust rule' }, { status: 500 });
   }
 }
+
+export async function handleRunSecret(
+  runId: string,
+  req: Request,
+  runOrchestrator: RunOrchestrator,
+): Promise<Response> {
+  const run = runOrchestrator.getRun(runId);
+  if (!run) {
+    return Response.json({ error: 'Run not found' }, { status: 404 });
+  }
+
+  const body = await req.json() as {
+    value?: string;
+    delivery?: string;
+  };
+
+  const { value, delivery } = body;
+
+  if (delivery !== undefined && delivery !== 'store' && delivery !== 'transient_send') {
+    return Response.json(
+      { error: 'delivery must be "store" or "transient_send"' },
+      { status: 400 },
+    );
+  }
+
+  const result = runOrchestrator.submitSecret(
+    runId,
+    value,
+    delivery as 'store' | 'transient_send' | undefined,
+  );
+  if (result === 'run_not_found') {
+    return Response.json({ error: 'Run not found' }, { status: 404 });
+  }
+  if (result === 'no_pending_secret') {
+    return Response.json(
+      { error: 'No secret pending for this run' },
+      { status: 409 },
+    );
+  }
+
+  return Response.json({ accepted: true });
+}