vellum 0.2.13 → 0.2.14

package/src/permissions/workspace-policy.ts

@@ -0,0 +1,114 @@
+import { resolve, normalize, dirname, basename } from 'node:path';
+import { realpathSync } from 'node:fs';
+
+/**
+ * Resolve a path to its canonical form. When the target itself doesn't
+ * exist (e.g. a new file being written), walk up to the nearest existing
+ * ancestor and append the remaining segments so that symlinks in parent
+ * directories (like macOS `/var` -> `/private/var`) are still resolved.
+ */
+function canonicalize(p: string): string {
+  const abs = resolve(p);
+  try {
+    return realpathSync(abs);
+  } catch {
+    // Walk upward until we find an existing ancestor.
+    const name = basename(abs);
+    const parent = dirname(abs);
+    if (parent === abs) {
+      // Reached filesystem root — nothing left to resolve.
+      return normalize(abs);
+    }
+    return `${canonicalize(parent)}/${name}`;
+  }
+}
+
+/**
+ * Resolve a file path to its canonical form (resolving symlinks and
+ * normalizing segments like `.` and `..`), then check whether it falls
+ * within the given workspace root.
+ */
+export function isPathWithinWorkspaceRoot(filePath: string, workspaceRoot: string): boolean {
+  if (!filePath || !workspaceRoot) return false;
+
+  const canonicalPath = canonicalize(filePath);
+  const canonicalRoot = canonicalize(workspaceRoot);
+
+  // Ensure the root ends with a separator so `/workspace-extra` doesn't
+  // match `/workspace`.
+  const rootPrefix = canonicalRoot.endsWith('/') ? canonicalRoot : `${canonicalRoot}/`;
+
+  return canonicalPath === canonicalRoot || canonicalPath.startsWith(rootPrefix);
+}
+
+// ── Tool-name sets for invocation classification ──────────────────────
+
+/** File-path tools whose workspace-scoped-ness depends on the file_path input. */
+const PATH_SCOPED_TOOLS = new Set([
+  'file_read',
+  'file_write',
+  'file_edit',
+]);
+
+/** Network-accessing tools — never workspace-scoped. */
+const NETWORK_TOOLS = new Set([
+  'web_search',
+  'web_fetch',
+  'browser_navigate',
+  'browser_click',
+  'browser_type',
+  'browser_scroll',
+  'browser_screenshot',
+  'browser_close',
+  'network_request',
+]);
+
+/** Host-level tools — operate outside the sandbox, never workspace-scoped. */
+const HOST_TOOLS = new Set([
+  'host_file_read',
+  'host_file_write',
+  'host_file_edit',
+  'host_bash',
+]);
+
+/** Safe local-only tools that are always workspace-scoped. */
+const ALWAYS_SCOPED_TOOLS = new Set([
+  'skill_load',
+  'view_image',
+  'memory_search',
+  'ui_update',
+  'ui_dismiss',
+]);
+
+/**
+ * Determine whether a tool invocation only affects resources within the
+ * workspace root. This is a conservative classification — unknown tools
+ * default to NOT workspace-scoped.
+ */
+export function isWorkspaceScopedInvocation(
+  toolName: string,
+  toolInput: Record<string, unknown>,
+  workspaceRoot: string,
+): boolean {
+  if (ALWAYS_SCOPED_TOOLS.has(toolName)) return true;
+  if (NETWORK_TOOLS.has(toolName)) return false;
+  if (HOST_TOOLS.has(toolName)) return false;
+
+  if (PATH_SCOPED_TOOLS.has(toolName)) {
+    const rawPath = typeof toolInput.file_path === 'string'
+      ? toolInput.file_path
+      : typeof toolInput.path === 'string'
+        ? toolInput.path
+        : '';
+    // Resolve relative paths against workspaceRoot (not process.cwd())
+    const filePath = rawPath !== '' && !rawPath.startsWith('/') ? resolve(workspaceRoot, rawPath) : rawPath;
+    return filePath !== '' && isPathWithinWorkspaceRoot(filePath, workspaceRoot);
+  }
+
+  // Bash is generally workspace-scoped when sandbox isolation is active —
+  // the caller handles network mode checks separately.
+  if (toolName === 'bash') return true;
+
+  // Unknown tool — conservative default.
+  return false;
+}

package/src/providers/retry.ts

@@ -1,46 +1,21 @@
 import type { Provider, ProviderResponse, SendMessageOptions, Message, ToolDefinition } from './types.js';
 import { ProviderError } from '../util/errors.js';
 import { getLogger, isDebug } from '../util/logger.js';
+import {
+  computeRetryDelay,
+  isRetryableNetworkError,
+  sleep,
+  DEFAULT_MAX_RETRIES,
+  DEFAULT_BASE_DELAY_MS,
+} from '../util/retry.js';
 
 const log = getLogger('retry');
 
-const MAX_RETRIES = 3;
-const BASE_DELAY_MS = 1000;
-
 function isRetryableError(error: unknown): boolean {
-  // Check ProviderError.statusCode for retryable HTTP status codes
   if (error instanceof ProviderError && error.statusCode !== undefined) {
     if (error.statusCode === 429 || error.statusCode >= 500) return true;
   }
-
-  // Check for network errors (direct or wrapped in cause chain)
-  if (error instanceof Error) {
-    const code = (error as NodeJS.ErrnoException).code;
-    if (code === 'ECONNRESET' || code === 'ECONNREFUSED' || code === 'ETIMEDOUT' || code === 'EPIPE') {
-      return true;
-    }
-
-    if (error.cause instanceof Error) {
-      const causeCode = (error.cause as NodeJS.ErrnoException).code;
-      if (causeCode === 'ECONNRESET' || causeCode === 'ECONNREFUSED' || causeCode === 'ETIMEDOUT' || causeCode === 'EPIPE') {
-        return true;
-      }
-    }
-  }
-
-  return false;
-}
-
-function getRetryDelay(attempt: number): number {
-  // Equal jitter: guaranteed floor of cap/2 plus random in [0, cap/2].
-  // Prevents retry storms while ensuring retries never collapse to 0ms.
-  const cap = BASE_DELAY_MS * Math.pow(2, attempt);
-  const half = cap / 2;
-  return half + Math.random() * half;
-}
-
-function sleep(ms: number): Promise<void> {
-  return new Promise((resolve) => setTimeout(resolve, ms));
+  return isRetryableNetworkError(error);
 }
 
 export class RetryProvider implements Provider {
@@ -67,7 +42,7 @@ export class RetryProvider implements Provider {
       }, 'Provider sendMessage start');
     }
 
-    for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+    for (let attempt = 0; attempt <= DEFAULT_MAX_RETRIES; attempt++) {
       try {
         const start = Date.now();
         const result = await this.inner.sendMessage(messages, tools, systemPrompt, options);
@@ -85,14 +60,14 @@ export class RetryProvider implements Provider {
       } catch (error) {
         lastError = error;
 
-        if (attempt < MAX_RETRIES && isRetryableError(error)) {
-          const delay = getRetryDelay(attempt);
+        if (attempt < DEFAULT_MAX_RETRIES && isRetryableError(error)) {
+          const delay = computeRetryDelay(attempt, DEFAULT_BASE_DELAY_MS);
           const errorType = error instanceof ProviderError && error.statusCode === 429
             ? 'rate_limit'
             : error instanceof ProviderError && error.statusCode !== undefined && error.statusCode >= 500
               ? `server_error_${error.statusCode}`
               : 'network_error';
-          log.warn({ attempt: attempt + 1, maxRetries: MAX_RETRIES, delay, errorType, provider: this.name }, 'Retrying after transient error');
+          log.warn({ attempt: attempt + 1, maxRetries: DEFAULT_MAX_RETRIES, delay, errorType, provider: this.name }, 'Retrying after transient error');
           await sleep(delay);
           continue;
         }

package/src/runtime/assistant-event-hub.ts

@@ -33,6 +33,8 @@ interface SubscriberEntry {
   filter: AssistantEventFilter;
   callback: AssistantEventCallback;
   active: boolean;
+  /** Called by the hub when this entry is evicted to make room for a new subscriber. */
+  onEvict?: () => void;
 }
 
 /**
@@ -42,18 +44,48 @@ interface SubscriberEntry {
  * events that match their `assistantId` (and optionally `sessionId`).
  *
  * The hub is intentionally simple: synchronous fanout, no buffering, no
- * backpressure. Slow-consumer protection is added in PR 7.
+ * backpressure. Slow-consumer protection lives in the SSE route (PR 7).
  */
 export class AssistantEventHub {
   private readonly subscribers = new Set<SubscriberEntry>();
+  private readonly maxSubscribers: number;
+
+  constructor(options?: { maxSubscribers?: number }) {
+    this.maxSubscribers = options?.maxSubscribers ?? Infinity;
+  }
 
   /**
    * Register a subscriber that will be called for each matching event.
    *
+   * When the subscriber cap (`maxSubscribers`) has been reached, the **oldest**
+   * subscriber is evicted to make room: its `onEvict` callback is invoked (so
+   * it can close its SSE stream) and its entry is removed from the hub.
+   *
+   * The only case that throws is when `maxSubscribers` is 0 — there is nothing
+   * to evict and no room to add.
+   *
+   * @param options.onEvict  Called if this subscriber is later evicted by a newer one.
    * @returns A subscription handle. Call `dispose()` to unsubscribe.
    */
-  subscribe(filter: AssistantEventFilter, callback: AssistantEventCallback): AssistantEventSubscription {
-    const entry: SubscriberEntry = { filter, callback, active: true };
+  subscribe(
+    filter: AssistantEventFilter,
+    callback: AssistantEventCallback,
+    options?: { onEvict?: () => void },
+  ): AssistantEventSubscription {
+    if (this.subscribers.size >= this.maxSubscribers) {
+      // Evict the oldest subscriber (Sets maintain insertion order).
+      const [oldest] = this.subscribers;
+      if (!oldest) {
+        // maxSubscribers is 0 — nothing to evict, nothing to add.
+        throw new RangeError(
+          `AssistantEventHub: subscriber cap reached (${this.maxSubscribers})`,
+        );
+      }
+      oldest.active = false;
+      this.subscribers.delete(oldest);
+      try { oldest.onEvict?.(); } catch { /* ignore eviction callback errors */ }
+    }
+    const entry: SubscriberEntry = { filter, callback, active: true, onEvict: options?.onEvict };
     this.subscribers.add(entry);
 
     return {
@@ -108,6 +140,11 @@ export class AssistantEventHub {
   subscriberCount(): number {
     return this.subscribers.size;
   }
+
+  /** Returns true if the hub can accept a subscriber without evicting anyone. */
+  hasCapacity(): boolean {
+    return this.subscribers.size < this.maxSubscribers;
+  }
 }
 
 // ── Process-level singleton ───────────────────────────────────────────────────
@@ -117,4 +154,4 @@ export class AssistantEventHub {
  *
  * Import and use this in daemon send paths (PR 3) and the SSE route (PR 5).
  */
-export const assistantEventHub = new AssistantEventHub();
+export const assistantEventHub = new AssistantEventHub({ maxSubscribers: 100 });

package/src/runtime/channel-approval-parser.ts

@@ -0,0 +1,60 @@
+/**
+ * Channel-agnostic plain-text approval decision parser.
+ *
+ * Parses inbound user text to determine whether it matches an approval,
+ * rejection, or "approve always" intent. This module is transport-agnostic
+ * and can be used by any channel adapter (Telegram, SMS, etc.).
+ */
+
+import type { ApprovalAction, ApprovalDecisionResult } from './channel-approval-types.js';
+
+// ---------------------------------------------------------------------------
+// Phrase → action mapping
+// ---------------------------------------------------------------------------
+
+const APPROVE_ONCE_PHRASES = ['yes', 'approve', 'allow', 'go ahead'];
+const APPROVE_ALWAYS_PHRASES = ['always', 'approve always', 'allow always'];
+const REJECT_PHRASES = ['no', 'reject', 'deny', 'cancel'];
+
+/**
+ * Build a Map from lowercased phrase to action. "Approve always" phrases
+ * are checked first (longest-match-wins) because "approve" is a prefix
+ * of "approve always".
+ */
+function buildPhraseMap(): Map<string, ApprovalAction> {
+  const map = new Map<string, ApprovalAction>();
+
+  // Insert longer phrases first so iteration order does not matter —
+  // we match on exact equality after normalising, not prefix matching.
+  for (const phrase of APPROVE_ALWAYS_PHRASES) {
+    map.set(phrase, 'approve_always');
+  }
+  for (const phrase of APPROVE_ONCE_PHRASES) {
+    map.set(phrase, 'approve_once');
+  }
+  for (const phrase of REJECT_PHRASES) {
+    map.set(phrase, 'reject');
+  }
+  return map;
+}
+
+const PHRASE_MAP = buildPhraseMap();
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse a plain-text message into an approval decision.
+ *
+ * Returns a structured `ApprovalDecisionResult` if the text matches one
+ * of the known intent phrases, or `null` if it does not match.
+ *
+ * Matching is case-insensitive with leading/trailing whitespace trimmed.
+ */
+export function parseApprovalDecision(text: string): ApprovalDecisionResult | null {
+  const normalised = text.trim().toLowerCase();
+  const action = PHRASE_MAP.get(normalised);
+  if (!action) return null;
+  return { action, source: 'plain_text' };
+}

package/src/runtime/channel-approval-types.ts

@@ -0,0 +1,71 @@
+/**
+ * Channel-agnostic approval flow types.
+ *
+ * These types model the approval prompt/decision lifecycle for tool-use
+ * confirmations surfaced through external channels (Telegram, SMS, etc.).
+ * They are intentionally decoupled from any specific channel so that the
+ * same approval flow can be reused across transports.
+ */
+
+// ---------------------------------------------------------------------------
+// Approval actions
+// ---------------------------------------------------------------------------
+
+/** The set of actions a user can take on an approval prompt. */
+export type ApprovalAction = 'approve_once' | 'approve_always' | 'reject';
+
+/** An action presented to the user as a tappable button or text option. */
+export interface ApprovalActionOption {
+  id: ApprovalAction;
+  label: string;
+}
+
+/** Default action options presented to users across all channels. */
+export const DEFAULT_APPROVAL_ACTIONS: readonly ApprovalActionOption[] = [
+  { id: 'approve_once', label: 'Approve once' },
+  { id: 'approve_always', label: 'Approve always' },
+  { id: 'reject', label: 'Reject' },
+] as const;
+
+// ---------------------------------------------------------------------------
+// Approval prompt
+// ---------------------------------------------------------------------------
+
+/** The approval prompt model sent to users via a channel. */
+export interface ChannelApprovalPrompt {
+  /** Human-readable description of what is being approved. */
+  promptText: string;
+  /** Available actions the user can take. */
+  actions: ApprovalActionOption[];
+  /** Instruction text for channels that only support plain text (no buttons). */
+  plainTextFallback: string;
+}
+
+// ---------------------------------------------------------------------------
+// Approval UI metadata (gateway callback payload)
+// ---------------------------------------------------------------------------
+
+/**
+ * Metadata attached to gateway callback payloads so the channel adapter
+ * can render approval UI and route the user's decision back to the
+ * correct pending run.
+ */
+export interface ApprovalUIMetadata {
+  runId: string;
+  requestId: string;
+  actions: ApprovalActionOption[];
+  plainTextFallback: string;
+}
+
+// ---------------------------------------------------------------------------
+// Decision result
+// ---------------------------------------------------------------------------
+
+/** How the user communicated their decision. */
+export type ApprovalDecisionSource = 'telegram_button' | 'plain_text';
+
+/** The structured result of a user's approval decision. */
+export interface ApprovalDecisionResult {
+  action: ApprovalAction;
+  source: ApprovalDecisionSource;
+}

package/src/runtime/channel-approvals.ts

@@ -0,0 +1,145 @@
+/**
+ * Channel-agnostic approval orchestration module.
+ *
+ * Bridges the gap between external channel adapters (Telegram, SMS, etc.)
+ * and the internal run orchestrator / permission system:
+ *
+ *   1. Detect pending confirmations for a conversation
+ *   2. Build human-readable approval prompts with action buttons
+ *   3. Consume user decisions and apply them to the underlying run
+ *   4. Build reminder prompts when non-decision messages arrive
+ */
+
+import { getPendingConfirmationsByConversation, getRun } from '../memory/runs-store.js';
+import type { PendingRunInfo } from '../memory/runs-store.js';
+import { addRule } from '../permissions/trust-store.js';
+import type { RunOrchestrator } from './run-orchestrator.js';
+import { DEFAULT_APPROVAL_ACTIONS } from './channel-approval-types.js';
+import type {
+  ChannelApprovalPrompt,
+  ApprovalUIMetadata,
+  ApprovalDecisionResult,
+} from './channel-approval-types.js';
+
+// ---------------------------------------------------------------------------
+// 1. Detect pending confirmations and build prompt
+// ---------------------------------------------------------------------------
+
+/**
+ * Check whether a conversation has a pending tool-use confirmation and,
+ * if so, build a human-readable approval prompt.
+ *
+ * Returns `null` when there is nothing waiting for approval.
+ */
+export function getChannelApprovalPrompt(
+  conversationId: string,
+): ChannelApprovalPrompt | null {
+  const pending = getPendingConfirmationsByConversation(conversationId);
+  if (pending.length === 0) return null;
+
+  // Use the first pending run — channel UIs show one prompt at a time.
+  const info = pending[0];
+  return buildPromptFromRunInfo(info);
+}
+
+/**
+ * Internal helper: turn a PendingRunInfo into a ChannelApprovalPrompt.
+ */
+function buildPromptFromRunInfo(info: PendingRunInfo): ChannelApprovalPrompt {
+  const promptText = `The assistant wants to use the tool "${info.toolName}". Do you want to allow this?`;
+  const actions = [...DEFAULT_APPROVAL_ACTIONS];
+  const plainTextFallback =
+    `${promptText}\n\nReply "yes" to approve once, "always" to approve always, or "no" to reject.`;
+
+  return { promptText, actions, plainTextFallback };
+}
+
+// ---------------------------------------------------------------------------
+// 2. Build gateway-facing UI metadata
+// ---------------------------------------------------------------------------
+
+/**
+ * Convert a prompt + run info into the `ApprovalUIMetadata` payload that
+ * gateway adapters use to render buttons and route decisions back.
+ */
+export function buildApprovalUIMetadata(
+  prompt: ChannelApprovalPrompt,
+  runInfo: PendingRunInfo,
+): ApprovalUIMetadata {
+  return {
+    runId: runInfo.runId,
+    requestId: runInfo.requestId,
+    actions: prompt.actions,
+    plainTextFallback: prompt.plainTextFallback,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// 3. Consume a user decision and apply it to the run
+// ---------------------------------------------------------------------------
+
+export interface HandleDecisionResult {
+  applied: boolean;
+  runId?: string;
+}
+
+/**
+ * Find the pending run for a conversation, map the user's decision to the
+ * permission system's vocabulary, and apply it.
+ *
+ * For `approve_always`, a trust rule is persisted using the first allowlist
+ * option and first scope option from the pending confirmation (narrow
+ * default). The current invocation is also approved.
+ */
+export function handleChannelDecision(
+  conversationId: string,
+  decision: ApprovalDecisionResult,
+  orchestrator: RunOrchestrator,
+): HandleDecisionResult {
+  const pending = getPendingConfirmationsByConversation(conversationId);
+  if (pending.length === 0) return { applied: false };
+
+  const info = pending[0];
+
+  if (decision.action === 'approve_always') {
+    // Persist a trust rule so future invocations of this tool are auto-approved.
+    const run = getRun(info.runId);
+    const confirmation = run?.pendingConfirmation;
+    if (confirmation) {
+      const pattern = confirmation.allowlistOptions?.[0]?.pattern ?? '**';
+      const scope = confirmation.scopeOptions?.[0]?.scope ?? 'everywhere';
+      addRule(confirmation.toolName, pattern, scope, 'allow', 100, {
+        executionTarget: confirmation.executionTarget,
+      });
+    }
+  }
+
+  // Map channel-level action to the permission system's UserDecision type.
+  const userDecision = decision.action === 'reject' ? 'deny' as const : 'allow' as const;
+  const result = orchestrator.submitDecision(info.runId, userDecision);
+
+  return {
+    applied: result === 'applied',
+    runId: info.runId,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// 4. Reminder prompt for non-decision messages
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a reminder prompt when the user sends a non-decision message while
+ * an approval is pending. Reuses the original actions and fallback text
+ * but prefixes the prompt text with a reminder.
+ */
+export function buildReminderPrompt(
+  pendingPrompt: ChannelApprovalPrompt,
+): ChannelApprovalPrompt {
+  const reminderPrefix = "I'm still waiting for your decision on the previous request.";
+  return {
+    promptText: `${reminderPrefix}\n\n${pendingPrompt.promptText}`,
+    actions: pendingPrompt.actions,
+    plainTextFallback: `${reminderPrefix}\n\n${pendingPrompt.plainTextFallback}`,
+  };
+}

package/src/runtime/gateway-client.ts

@@ -1,5 +1,6 @@
 import { getLogger } from '../util/logger.js';
 import type { RuntimeAttachmentMetadata } from './http-types.js';
+import type { ApprovalUIMetadata } from './channel-approval-types.js';
 
 const log = getLogger('gateway-client');
 
@@ -10,6 +11,7 @@ export interface ChannelReplyPayload {
   text?: string;
   assistantId?: string;
   attachments?: RuntimeAttachmentMetadata[];
+  approval?: ApprovalUIMetadata;
 }
 
 export async function deliverChannelReply(
@@ -40,3 +42,17 @@ export async function deliverChannelReply(
 
   log.info({ chatId: payload.chatId, callbackUrl }, 'Channel reply delivered');
 }
+
+/**
+ * Deliver an approval prompt (text + inline keyboard metadata) to the
+ * gateway so it can render the approval UI in the channel.
+ */
+export async function deliverApprovalPrompt(
+  callbackUrl: string,
+  chatId: string,
+  text: string,
+  approval: ApprovalUIMetadata,
+  bearerToken?: string,
+): Promise<void> {
+  await deliverChannelReply(callbackUrl, { chatId, text, approval }, bearerToken);
+}

package/src/runtime/http-server.ts

@@ -44,6 +44,7 @@ import {
 } from './routes/channel-routes.js';
 import * as channelDeliveryStore from '../memory/channel-delivery-store.js';
 import * as conversationStore from '../memory/conversation-store.js';
+import * as externalConversationStore from '../memory/external-conversation-store.js';
 import * as attachmentsStore from '../memory/attachments-store.js';
 import { renderHistoryContent } from '../daemon/handlers.js';
 import { deliverChannelReply } from './gateway-client.js';
@@ -60,6 +61,7 @@ import {
   handleGetCallStatus,
   handleCancelCall,
   handleAnswerCall,
+  handleInstructionCall,
 } from './routes/call-routes.js';
 import {
   handleVoiceWebhook,
@@ -616,13 +618,28 @@ export class RuntimeHttpServer {
       if (endpoint === 'conversations' && req.method === 'GET') {
         const limit = Number(url.searchParams.get('limit') ?? 50);
         const conversations = conversationStore.listConversations(limit);
+        const bindings = externalConversationStore.getBindingsForConversations(
+          conversations.map((c) => c.id),
+        );
         return Response.json({
-          sessions: conversations.map((c) => ({
-            id: c.id,
-            title: c.title ?? 'Untitled',
-            updatedAt: c.updatedAt,
-            threadType: c.threadType === 'private' ? 'private' : 'standard',
-          })),
+          sessions: conversations.map((c) => {
+            const binding = bindings.get(c.id);
+            return {
+              id: c.id,
+              title: c.title ?? 'Untitled',
+              updatedAt: c.updatedAt,
+              threadType: c.threadType === 'private' ? 'private' : 'standard',
+              ...(binding ? {
+                channelBinding: {
+                  sourceChannel: binding.sourceChannel,
+                  externalChatId: binding.externalChatId,
+                  externalUserId: binding.externalUserId,
+                  displayName: binding.displayName,
+                  username: binding.username,
+                },
+              } : {}),
+            };
+          }),
         });
       }
 
@@ -700,7 +717,7 @@ export class RuntimeHttpServer {
       }
 
       if (endpoint === 'channels/inbound' && req.method === 'POST') {
-        return await handleChannelInbound(req, this.processMessage, this.bearerToken);
+        return await handleChannelInbound(req, this.processMessage, this.bearerToken, this.runOrchestrator);
       }
 
       if (endpoint === 'channels/delivery-ack' && req.method === 'POST') {
@@ -720,8 +737,8 @@ export class RuntimeHttpServer {
         return await handleStartCall(req);
       }
 
-      // Match calls/:callSessionId and calls/:callSessionId/cancel, calls/:callSessionId/answer
-      const callsMatch = endpoint.match(/^calls\/([^/]+?)(\/cancel|\/answer)?$/);
+      // Match calls/:callSessionId and calls/:callSessionId/cancel, calls/:callSessionId/answer, calls/:callSessionId/instruction
+      const callsMatch = endpoint.match(/^calls\/([^/]+?)(\/cancel|\/answer|\/instruction)?$/);
       if (callsMatch) {
         const callSessionId = callsMatch[1];
         // Skip known sub-paths that are handled elsewhere (twilio, relay)
@@ -732,6 +749,9 @@ export class RuntimeHttpServer {
           if (callsMatch[2] === '/answer' && req.method === 'POST') {
             return await handleAnswerCall(req, callSessionId);
           }
+          if (callsMatch[2] === '/instruction' && req.method === 'POST') {
+            return await handleInstructionCall(req, callSessionId);
+          }
           if (!callsMatch[2] && req.method === 'GET') {
             return handleGetCallStatus(callSessionId);
           }