vellum 0.2.12 → 0.2.14

package/src/calls/call-bridge.ts

@@ -1,11 +1,14 @@
 /**
- * Call-answer bridge: auto-consumes user replies in-thread as answers
- * to pending call questions, routing them to the live call orchestrator.
+ * Call message bridge: intercepts user messages in-thread and routes them
+ * to the live call orchestrator — either as answers to pending questions
+ * or as mid-call steering instructions.
  *
- * When a call has a pending question and the user sends a normal message
- * in the conversation thread, this bridge intercepts the message before
- * the agent loop, forwards the answer to the orchestrator, and returns
- * `{ handled: true }` so the caller can skip agent processing.
+ * Decision priority:
+ * 1. If a pending question exists → answer path (existing behavior).
+ * 2. If no pending question but an active call exists → instruction path.
+ *
+ * When the bridge consumes a message it returns `{ handled: true }` so
+ * the caller can skip agent processing.
  */
 
 import { getLogger } from '../util/logger.js';
@@ -17,6 +20,7 @@ import {
   getCallSession,
 } from './call-store.js';
 import { getCallOrchestrator } from './call-state.js';
+import { relayInstruction } from './call-domain.js';
 import * as conversationStore from '../memory/conversation-store.js';
 
 const log = getLogger('call-bridge');
@@ -24,18 +28,21 @@ const log = getLogger('call-bridge');
 export interface CallBridgeResult {
   handled: boolean;
   reason?: string;
+  /** User-facing text persisted in-thread by the bridge (success ack or failure notice). */
+  userFacingText?: string;
 }
 
 /**
- * Attempt to route a user message as an answer to a pending call question.
+ * Attempt to route a user message to an active call — as an answer to
+ * a pending question (priority) or as a mid-call steering instruction.
  *
  * @param conversationId - The conversation the message belongs to.
  * @param userText - The user's message text.
  * @param _userMessageId - The persisted message ID (reserved for future use).
- * @returns `{ handled: true }` if the answer was consumed by the call system,
+ * @returns `{ handled: true }` if the message was consumed by the call system,
  *          `{ handled: false, reason }` otherwise.
  */
-export async function tryHandlePendingCallAnswer(
+export async function tryRouteCallMessage(
   conversationId: string,
   userText: string,
   _userMessageId?: string,
@@ -46,18 +53,38 @@ export async function tryHandlePendingCallAnswer(
     return { handled: false, reason: 'no_active_call' };
   }
 
-  // 2. Check for a pending question
+  // 2. Check for a pending question — answer path takes priority
   const pendingQuestion = getPendingQuestion(callSession.id);
-  if (!pendingQuestion) {
-    return { handled: false, reason: 'no_pending_question' };
+  if (pendingQuestion) {
+    return handleAnswer(conversationId, callSession.id, pendingQuestion, userText);
+  }
+
+  // 3. No pending question — instruction path
+  return handleInstruction(conversationId, callSession.id, userText);
+}
+
+/** @deprecated Use `tryRouteCallMessage` instead. */
+export const tryHandlePendingCallAnswer = tryRouteCallMessage;
+
+// ── Answer path ─────────────────────────────────────────────────────
+
+async function handleAnswer(
+  conversationId: string,
+  callSessionId: string,
+  pendingQuestion: { id: string; questionText: string },
+  userText: string,
+): Promise<CallBridgeResult> {
+  // Empty text (e.g. attachment-only messages) should not be consumed as
+  // an answer — fall through to normal processing so attachments are handled.
+  if (!userText.trim()) {
+    return { handled: false, reason: 'empty_answer_text' };
   }
 
-  // 3. Check that the orchestrator is alive and waiting
-  const orchestrator = getCallOrchestrator(callSession.id);
+  const orchestrator = getCallOrchestrator(callSessionId);
   if (!orchestrator) {
     // The call may have ended between the question being asked and the
     // user replying. Persist a follow-up message so the user knows.
-    const freshSession = getCallSession(callSession.id);
+    const freshSession = getCallSession(callSessionId);
     const ended = freshSession && (freshSession.status === 'completed' || freshSession.status === 'failed');
     if (ended) {
       conversationStore.addMessage(
@@ -76,20 +103,66 @@ export async function tryHandlePendingCallAnswer(
     return { handled: false, reason: 'orchestrator_not_waiting' };
   }
 
-  // 4. Route the answer through the orchestrator
   const accepted = await orchestrator.handleUserAnswer(userText);
   if (!accepted) {
     return { handled: false, reason: 'orchestrator_rejected' };
   }
 
-  // 5. Persist the answered state
   answerPendingQuestion(pendingQuestion.id, userText);
-  recordCallEvent(callSession.id, 'user_answered', { answer: userText });
+  recordCallEvent(callSessionId, 'user_answered', { answer: userText });
 
   log.info(
-    { conversationId, callSessionId: callSession.id, questionId: pendingQuestion.id },
+    { conversationId, callSessionId, questionId: pendingQuestion.id },
     'User reply routed as call answer via bridge',
   );
 
   return { handled: true };
 }
+
+// ── Instruction path ────────────────────────────────────────────────
+
+async function handleInstruction(
+  conversationId: string,
+  callSessionId: string,
+  userText: string,
+): Promise<CallBridgeResult> {
+  // Empty text (e.g. attachment-only messages) should not be relayed —
+  // fall through to normal processing so attachments are handled.
+  if (!userText.trim()) {
+    return { handled: false, reason: 'empty_instruction_text' };
+  }
+
+  const result = await relayInstruction({ callSessionId, instructionText: userText });
+
+  if (!result.ok) {
+    log.warn(
+      { conversationId, callSessionId, error: result.error },
+      'Instruction relay failed via bridge',
+    );
+
+    const failureText = 'Failed to relay instruction to the active call.';
+    conversationStore.addMessage(
+      conversationId,
+      'assistant',
+      JSON.stringify([{ type: 'text', text: failureText }]),
+    );
+
+    // Consumed: caller should NOT fall through to the agent loop
+    return { handled: true, reason: 'instruction_relay_failed', userFacingText: failureText };
+  }
+
+  // Persist a concise acknowledgement so the user sees confirmation
+  const ackText = 'Instruction relayed to active call.';
+  conversationStore.addMessage(
+    conversationId,
+    'assistant',
+    JSON.stringify([{ type: 'text', text: ackText }]),
+  );
+
+  log.info(
+    { conversationId, callSessionId },
+    'User message routed as call instruction via bridge',
+  );
+
+  return { handled: true, userFacingText: ackText };
+}

package/src/calls/call-domain.ts

@@ -22,7 +22,10 @@ import { TwilioConversationRelayProvider } from './twilio-provider.js';
 import { getTwilioConfig } from './twilio-config.js';
 import { getTwilioVoiceWebhookUrl, getTwilioStatusCallbackUrl } from '../inbound/public-ingress-urls.js';
 import { loadConfig } from '../config/loader.js';
+import { getSecureKey } from '../security/secure-keys.js';
 import type { CallSession } from './types.js';
+import { VALID_CALLER_IDENTITY_MODES } from '../config/schema.js';
+import type { AssistantConfig } from '../config/types.js';
 
 const log = getLogger('call-domain');
 
@@ -34,6 +37,7 @@ export interface StartCallResult {
   ok: true;
   session: CallSession;
   callSid: string;
+  callerIdentityMode: 'assistant_number' | 'user_number';
 }
 
 export interface CallError {
@@ -47,6 +51,7 @@ export type StartCallInput = {
   task: string;
   context?: string;
   conversationId: string;
+  callerIdentityMode?: 'assistant_number' | 'user_number';
 };
 
 export type CancelCallInput = {
@@ -59,13 +64,118 @@ export type AnswerCallInput = {
   answer: string;
 };
 
+export type RelayInstructionInput = {
+  callSessionId: string;
+  instructionText: string;
+};
+
+// ── Caller identity resolution ───────────────────────────────────────
+
+export type CallerIdentitySource = 'per_call_override' | 'implicit_default' | 'user_config' | 'secure_key' | 'env_var';
+
+export type CallerIdentityResult =
+  | { ok: true; mode: 'assistant_number' | 'user_number'; fromNumber: string; source: CallerIdentitySource }
+  | { ok: false; error: string };
+
+/**
+ * Resolve which phone number to use as the caller ID for an outbound call.
+ *
+ * Policy: implicit calls (no explicit mode) always use `assistant_number`.
+ * `user_number` is only used when explicitly requested per call.
+ *
+ * - If `requestedMode` is provided and per-call overrides are allowed, use it.
+ * - If `requestedMode` is provided but overrides are disabled, return an error.
+ * - Otherwise, always use `assistant_number` (implicit default).
+ *
+ * For `assistant_number`: uses the Twilio phone number from `getTwilioConfig()`.
+ *   No eligibility check is performed — this is a fast path.
+ * For `user_number`: uses `config.calls.callerIdentity.userNumber` or the
+ *   secure key `credential:twilio:user_phone_number`, then validates that the
+ *   number is usable as an outbound caller ID via the Twilio API.
+ */
+export async function resolveCallerIdentity(
+  config: AssistantConfig,
+  requestedMode?: 'assistant_number' | 'user_number',
+): Promise<CallerIdentityResult> {
+  const identityConfig = config.calls.callerIdentity;
+  let mode: 'assistant_number' | 'user_number';
+  let source: CallerIdentitySource;
+
+  if (requestedMode != null) {
+    if (!(VALID_CALLER_IDENTITY_MODES as readonly string[]).includes(requestedMode)) {
+      return { ok: false, error: `Invalid callerIdentityMode: "${requestedMode}". Must be one of: ${VALID_CALLER_IDENTITY_MODES.join(', ')}` };
+    }
+    if (!identityConfig.allowPerCallOverride) {
+      log.warn({ requestedMode }, 'Caller identity override rejected — per-call override is disabled in configuration');
+      return { ok: false, error: 'Per-call caller identity override is disabled in configuration' };
+    }
+    mode = requestedMode;
+    source = 'per_call_override';
+  } else {
+    // Implicit calls always use assistant_number regardless of config
+    mode = 'assistant_number';
+    source = 'implicit_default';
+  }
+
+  if (mode === 'assistant_number') {
+    const twilioConfig = getTwilioConfig();
+    log.info({ mode, source, fromNumber: twilioConfig.phoneNumber }, 'Resolved caller identity');
+    return { ok: true, mode, fromNumber: twilioConfig.phoneNumber, source };
+  }
+
+  // user_number mode: resolve from config or secure key, tracking where the number came from
+  let userNumber = '';
+  let numberSource: CallerIdentitySource = source;
+
+  if (identityConfig.userNumber) {
+    userNumber = identityConfig.userNumber;
+    numberSource = 'user_config';
+  } else if (process.env.TWILIO_USER_PHONE_NUMBER) {
+    userNumber = process.env.TWILIO_USER_PHONE_NUMBER;
+    numberSource = 'env_var';
+  } else {
+    const secureKeyValue = getSecureKey('credential:twilio:user_phone_number');
+    if (secureKeyValue) {
+      userNumber = secureKeyValue;
+      numberSource = 'secure_key';
+    }
+  }
+
+  if (!userNumber) {
+    log.warn({ mode, source }, 'Caller identity resolution failed — no user phone number configured');
+    return {
+      ok: false,
+      error: 'user_number mode requires a user phone number. Set calls.callerIdentity.userNumber in config or store credential:twilio:user_phone_number via the credential_store tool.',
+    };
+  }
+
+  if (!E164_REGEX.test(userNumber)) {
+    log.warn({ mode, source: numberSource, userNumber }, 'User phone number is not in E.164 format');
+    return {
+      ok: false,
+      error: `User phone number "${userNumber}" is not in E.164 format (must start with + followed by digits, e.g. +14155551234). Check calls.callerIdentity.userNumber in config or credential:twilio:user_phone_number.`,
+    };
+  }
+
+  // Verify the user number is eligible as a caller ID with Twilio
+  const provider = new TwilioConversationRelayProvider();
+  const eligibility = await provider.checkCallerIdEligibility(userNumber);
+  if (!eligibility.eligible) {
+    log.warn({ mode, source: numberSource, userNumber, reason: eligibility.reason }, 'Caller ID eligibility check failed');
+    return { ok: false, error: eligibility.reason! };
+  }
+
+  log.info({ mode, source: numberSource, fromNumber: userNumber }, 'Resolved caller identity');
+  return { ok: true, mode, fromNumber: userNumber, source: numberSource };
+}
+
 // ── Domain operations ────────────────────────────────────────────────
 
 /**
  * Initiate a new outbound call.
  */
 export async function startCall(input: StartCallInput): Promise<StartCallResult | CallError> {
-  const { phoneNumber, task, context: callContext, conversationId } = input;
+  const { phoneNumber, task, context: callContext, conversationId, callerIdentityMode } = input;
 
   if (!phoneNumber || typeof phoneNumber !== 'string') {
     return { ok: false, error: 'phone_number is required and must be a string', status: 400 };
@@ -90,23 +200,31 @@ export async function startCall(input: StartCallInput): Promise<StartCallResult
   let sessionId: string | null = null;
 
   try {
-    const twilioConfig = getTwilioConfig();
     const ingressConfig = loadConfig();
     const provider = new TwilioConversationRelayProvider();
 
+    // Resolve which phone number to use as caller ID
+    const identityResult = await resolveCallerIdentity(ingressConfig, callerIdentityMode);
+    if (!identityResult.ok) {
+      return { ok: false, error: identityResult.error, status: 400 };
+    }
+    const fromNumber = identityResult.fromNumber;
+
     const session = createCallSession({
       conversationId,
       provider: 'twilio',
-      fromNumber: twilioConfig.phoneNumber,
+      fromNumber,
       toNumber: phoneNumber,
       task: callContext ? `${task}\n\nContext: ${callContext}` : task,
+      callerIdentityMode: identityResult.mode,
+      callerIdentitySource: identityResult.source,
     });
     sessionId = session.id;
 
-    log.info({ callSessionId: session.id, to: phoneNumber, task }, 'Initiating outbound call');
+    log.info({ callSessionId: session.id, to: phoneNumber, from: fromNumber, task }, 'Initiating outbound call');
 
     const { callSid } = await provider.initiateCall({
-      from: twilioConfig.phoneNumber,
+      from: fromNumber,
       to: phoneNumber,
       webhookUrl: getTwilioVoiceWebhookUrl(ingressConfig, session.id),
       statusCallbackUrl: getTwilioStatusCallbackUrl(ingressConfig),
@@ -120,6 +238,7 @@ export async function startCall(input: StartCallInput): Promise<StartCallResult
       ok: true,
       session: { ...session, providerCallSid: callSid },
       callSid,
+      callerIdentityMode: identityResult.mode,
     };
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
@@ -276,3 +395,36 @@ export async function answerCall(input: AnswerCallInput): Promise<{ ok: true; qu
 
   return { ok: true, questionId: question.id };
 }
+
+/**
+ * Relay a user instruction to an active call's orchestrator.
+ * Validates that the call is active and the instruction is non-empty
+ * before injecting it into the orchestrator's conversation history.
+ */
+export async function relayInstruction(input: RelayInstructionInput): Promise<{ ok: true } | CallError> {
+  const { callSessionId, instructionText } = input;
+
+  if (!instructionText || typeof instructionText !== 'string' || instructionText.trim().length === 0) {
+    return { ok: false, error: 'instructionText is required and must be a non-empty string', status: 400 };
+  }
+
+  const session = getCallSession(callSessionId);
+  if (!session) {
+    return { ok: false, error: `No call session found with ID ${callSessionId}`, status: 404 };
+  }
+
+  if (session.status === 'completed' || session.status === 'failed' || session.status === 'cancelled') {
+    return { ok: false, error: `Call session ${callSessionId} is not active (status: ${session.status})`, status: 409 };
+  }
+
+  const orchestrator = getCallOrchestrator(callSessionId);
+  if (!orchestrator) {
+    return { ok: false, error: 'No active orchestrator for this call', status: 409 };
+  }
+
+  await orchestrator.handleUserInstruction(instructionText);
+
+  log.info({ callSessionId }, 'User instruction relayed to orchestrator');
+
+  return { ok: true };
+}

package/src/calls/call-orchestrator.ts

@@ -41,6 +41,8 @@ export class CallOrchestrator {
   private consultationTimer: ReturnType<typeof setTimeout> | null = null;
   private durationEndTimer: ReturnType<typeof setTimeout> | null = null;
   private task: string | null;
+  /** Instructions queued while an LLM turn is in-flight or during waiting_on_user */
+  private pendingInstructions: string[] = [];
 
   constructor(callSessionId: string, relay: RelayConnection, task: string | null) {
     this.callSessionId = callSessionId;
@@ -101,8 +103,18 @@ export class CallOrchestrator {
     this.state = 'processing';
     updateCallSession(this.callSessionId, { status: 'in_progress' });
 
-    // Append the user's answer as a special message the model recognizes
-    this.conversationHistory.push({ role: 'user', content: `[USER_ANSWERED: ${answerText}]` });
+    // Merge any instructions that were queued during the waiting_on_user
+    // state into a single user message alongside the answer to avoid
+    // consecutive user-role messages (which violate Anthropic API
+    // role-alternation requirements).
+    const parts: string[] = [];
+    for (const instr of this.pendingInstructions) {
+      parts.push(`[USER_INSTRUCTION: ${instr}]`);
+    }
+    this.pendingInstructions = [];
+    parts.push(`[USER_ANSWERED: ${answerText}]`);
+
+    this.conversationHistory.push({ role: 'user', content: parts.join('\n') });
 
     // Fire-and-forget: unblock the caller so the HTTP response and answer
     // persistence happen immediately, before LLM streaming begins.
@@ -112,6 +124,46 @@ export class CallOrchestrator {
     return true;
   }
 
+  /**
+   * Inject a user instruction into the orchestrator's conversation history.
+   * The instruction is formatted as a dedicated marker that the system prompt
+   * tells the model to treat as high-priority steering input.
+   *
+   * When the LLM is actively processing or speaking, or when the orchestrator
+   * is waiting on a user answer, the instruction is queued and spliced into
+   * the conversation at the correct chronological position once the current
+   * turn completes. This prevents:
+   *  - History ordering corruption (instruction appearing before an in-flight
+   *    assistant response).
+   *  - Consecutive user-role messages (which violate Anthropic API
+   *    role-alternation requirements).
+   */
+  async handleUserInstruction(instructionText: string): Promise<void> {
+    recordCallEvent(this.callSessionId, 'user_instruction_relayed', { instruction: instructionText });
+
+    // Queue the instruction when it cannot be safely appended right now:
+    //  - processing/speaking: an LLM turn is in-flight; appending would
+    //    place the instruction before the assistant response in the array.
+    //  - waiting_on_user: the last message is an assistant turn; the next
+    //    message should be the user's answer. Queued instructions are merged
+    //    into that answer message by handleUserAnswer().
+    if (this.state === 'processing' || this.state === 'speaking' || this.state === 'waiting_on_user') {
+      this.pendingInstructions.push(instructionText);
+      return;
+    }
+
+    this.conversationHistory.push({
+      role: 'user',
+      content: `[USER_INSTRUCTION: ${instructionText}]`,
+    });
+
+    // Reset the silence timer so the instruction-triggered LLM turn
+    // doesn't race with a stale silence timeout.
+    this.resetSilenceTimer();
+
+    await this.runLlm();
+  }
+
   /**
    * Handle caller interrupting the assistant's speech.
    */
@@ -155,10 +207,11 @@ export class CallOrchestrator {
       '2. Be concise — phone conversations should be brief and natural.',
       '3. If the callee asks something you don\'t know, include [ASK_USER: your question here] in your response along with a hold message like "Let me check on that for you."',
       '4. If the callee provides information preceded by [USER_ANSWERED: ...], use that answer naturally in the conversation.',
-      '5. When the call\'s purpose is fulfilled, include [END_CALL] in your response along with a polite goodbye.',
-      '6. Do not make up information — ask the user if unsure.',
-      '7. Keep responses short — 1-3 sentences is ideal for phone conversation.',
-      '8. When caller text includes [SPEAKER id="..." label="..."], treat each speaker as a distinct person and personalize responses using that speaker\'s prior context in this call.',
+      '5. If you see [USER_INSTRUCTION: ...], treat it as a high-priority steering directive from your user. Follow the instruction immediately, adjusting your approach or response accordingly.',
+      '6. When the call\'s purpose is fulfilled, include [END_CALL] in your response along with a polite goodbye.',
+      '7. Do not make up information — ask the user if unsure.',
+      '8. Keep responses short — 1-3 sentences is ideal for phone conversation.',
+      '9. When caller text includes [SPEAKER id="..." label="..."], treat each speaker as a distinct person and personalize responses using that speaker\'s prior context in this call.',
     ]
       .filter(Boolean)
       .join('\n');
@@ -190,9 +243,11 @@ export class CallOrchestrator {
     try {
       this.state = 'speaking';
 
+      const callModel = getConfig().calls.model?.trim() || 'claude-sonnet-4-20250514';
+
       const stream = client.messages.stream(
         {
-          model: 'claude-sonnet-4-20250514',
+          model: callModel,
           max_tokens: 512,
           system: this.buildSystemPrompt(),
           messages: this.conversationHistory.map((m) => ({
@@ -324,6 +379,7 @@ export class CallOrchestrator {
             this.state = 'idle';
             updateCallSession(this.callSessionId, { status: 'in_progress' });
             expirePendingQuestions(this.callSessionId);
+            this.flushPendingInstructions();
           }
         }, getUserConsultationTimeoutMs());
         return;
@@ -349,8 +405,11 @@ export class CallOrchestrator {
         return;
       }
 
-      // Normal turn complete
+      // Normal turn complete — flush any instructions that arrived while
+      // the LLM was active. They are appended after the assistant response
+      // so chronological order is preserved, then a new LLM turn is started.
       this.state = 'idle';
+      this.flushPendingInstructions();
     } catch (err: unknown) {
       // Aborted requests are expected (interruptions, rapid utterances)
       if (err instanceof Error && err.name === 'AbortError') {
@@ -360,9 +419,38 @@ export class CallOrchestrator {
       log.error({ err, callSessionId: this.callSessionId }, 'LLM streaming error');
       this.relay.sendTextToken('I\'m sorry, I encountered a technical issue. Could you repeat that?', true);
       this.state = 'idle';
+      this.flushPendingInstructions();
     }
   }
 
+  /**
+   * Drain any instructions that were queued while the LLM was active.
+   * Each instruction is appended as a user message (now correctly after
+   * the assistant response) and a new LLM turn is kicked off to handle
+   * them. Batches all pending instructions into a single user message to
+   * avoid triggering multiple sequential LLM turns.
+   */
+  private flushPendingInstructions(): void {
+    if (this.pendingInstructions.length === 0) return;
+
+    const parts = this.pendingInstructions.map(
+      (instr) => `[USER_INSTRUCTION: ${instr}]`,
+    );
+    this.pendingInstructions = [];
+
+    this.conversationHistory.push({
+      role: 'user',
+      content: parts.join('\n'),
+    });
+
+    this.resetSilenceTimer();
+
+    // Fire-and-forget so we don't block the current turn's cleanup.
+    this.runLlm().catch((err) =>
+      log.error({ err, callSessionId: this.callSessionId }, 'runLlm failed after flushing queued instructions'),
+    );
+  }
+
   private startDurationTimer(): void {
     const maxDurationMs = getMaxCallDurationMs();
     const warningMs = maxDurationMs - 2 * 60 * 1000; // 2 minutes before max

package/src/calls/call-store.ts

@@ -20,6 +20,8 @@ function parseCallSession(row: typeof callSessions.$inferSelect): CallSession {
     toNumber: row.toNumber,
     task: row.task,
     status: row.status as CallSession['status'],
+    callerIdentityMode: row.callerIdentityMode,
+    callerIdentitySource: row.callerIdentitySource,
     startedAt: row.startedAt,
     endedAt: row.endedAt,
     lastError: row.lastError,
@@ -58,6 +60,8 @@ export function createCallSession(opts: {
   fromNumber: string;
   toNumber: string;
   task?: string;
+  callerIdentityMode?: string;
+  callerIdentitySource?: string;
 }): CallSession {
   const db = getDb();
   const now = Date.now();
@@ -70,6 +74,8 @@ export function createCallSession(opts: {
     toNumber: opts.toNumber,
     task: opts.task ?? null,
     status: 'initiated' as const,
+    callerIdentityMode: opts.callerIdentityMode ?? null,
+    callerIdentitySource: opts.callerIdentitySource ?? null,
     startedAt: null,
     endedAt: null,
     lastError: null,

package/src/calls/elevenlabs-client.ts

@@ -0,0 +1,97 @@
+import { getLogger } from '../util/logger.js';
+
+const log = getLogger('elevenlabs-client');
+
+export interface ElevenLabsRegisterCallRequest {
+  agent_id: string;
+  from_number: string;
+  to_number: string;
+  direction: 'outbound' | 'inbound';
+  conversation_initiation_client_data?: Record<string, unknown>;
+}
+
+export interface ElevenLabsRegisterCallResult {
+  twiml: string;
+}
+
+export interface ElevenLabsClientOptions {
+  apiBaseUrl: string;
+  apiKey: string;
+  timeoutMs: number;
+}
+
+export type ElevenLabsErrorCode = 'ELEVENLABS_TIMEOUT' | 'ELEVENLABS_HTTP_ERROR' | 'ELEVENLABS_INVALID_RESPONSE';
+
+export class ElevenLabsError extends Error {
+  code: ElevenLabsErrorCode;
+  statusCode?: number;
+
+  constructor(code: ElevenLabsErrorCode, message: string, statusCode?: number) {
+    super(message);
+    this.name = 'ElevenLabsError';
+    this.code = code;
+    this.statusCode = statusCode;
+  }
+}
+
+export class ElevenLabsClient {
+  private options: ElevenLabsClientOptions;
+
+  constructor(options: ElevenLabsClientOptions) {
+    this.options = options;
+  }
+
+  async registerCall(request: ElevenLabsRegisterCallRequest): Promise<ElevenLabsRegisterCallResult> {
+    const url = `${this.options.apiBaseUrl}/v1/convai/twilio/register-call`;
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), this.options.timeoutMs);
+
+    try {
+      log.info({ agent_id: request.agent_id, direction: request.direction }, 'Registering call with ElevenLabs');
+
+      const response = await fetch(url, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'xi-api-key': this.options.apiKey,
+        },
+        body: JSON.stringify(request),
+        signal: controller.signal,
+      });
+
+      if (!response.ok) {
+        throw new ElevenLabsError(
+          'ELEVENLABS_HTTP_ERROR',
+          `ElevenLabs register-call returned ${response.status}`,
+          response.status,
+        );
+      }
+
+      const body = await response.text();
+      if (!body || body.trim().length === 0) {
+        throw new ElevenLabsError(
+          'ELEVENLABS_INVALID_RESPONSE',
+          'ElevenLabs register-call returned empty response',
+        );
+      }
+
+      const lower = body.toLowerCase();
+      if (!lower.includes('<?xml') && !lower.includes('<response')) {
+        throw new ElevenLabsError(
+          'ELEVENLABS_INVALID_RESPONSE',
+          'Register-call response is not valid TwiML/XML',
+        );
+      }
+
+      return { twiml: body };
+    } catch (err) {
+      if (err instanceof ElevenLabsError) throw err;
+      if (err instanceof Error && err.name === 'AbortError') {
+        throw new ElevenLabsError('ELEVENLABS_TIMEOUT', `ElevenLabs register-call timed out after ${this.options.timeoutMs}ms`);
+      }
+      throw new ElevenLabsError('ELEVENLABS_HTTP_ERROR', `ElevenLabs register-call failed: ${err instanceof Error ? err.message : String(err)}`);
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+}