@vellumai/assistant 0.3.7 → 0.3.9

package/src/calls/call-domain.ts

@@ -19,7 +19,7 @@ import {
   expirePendingQuestions,
 } from './call-store.js';
 import { isTerminalState } from './call-state-machine.js';
-import { getCallOrchestrator, unregisterCallOrchestrator } from './call-state.js';
+import { getCallController, unregisterCallController } from './call-state.js';
 import { activeRelayConnections } from './relay-server.js';
 import { TwilioConversationRelayProvider } from './twilio-provider.js';
 import { getTwilioConfig } from './twilio-config.js';
@@ -402,7 +402,7 @@ export function getCallStatus(
 }
 
 /**
- * Cancel an active call. Cleans up relay connections and orchestrators.
+ * Cancel an active call. Cleans up relay connections and controllers.
  */
 export async function cancelCall(input: CancelCallInput): Promise<{ ok: true; session: CallSession } | CallError> {
   const { callSessionId, reason } = input;
@@ -436,11 +436,11 @@ export async function cancelCall(input: CancelCallInput): Promise<{ ok: true; se
     activeRelayConnections.delete(callSessionId);
   }
 
-  // Clean up orchestrator
-  const orchestrator = getCallOrchestrator(callSessionId);
-  if (orchestrator) {
-    orchestrator.destroy();
-    unregisterCallOrchestrator(callSessionId);
+  // Clean up controller
+  const controller = getCallController(callSessionId);
+  if (controller) {
+    controller.destroy();
+    unregisterCallController(callSessionId);
   }
 
   // Update session status
@@ -480,19 +480,19 @@ export async function answerCall(input: AnswerCallInput): Promise<{ ok: true; qu
     return { ok: false, error: 'No pending question found', status: 404 };
   }
 
-  const orchestrator = getCallOrchestrator(callSessionId);
-  if (!orchestrator) {
-    log.warn({ callSessionId }, 'answerCall: no active orchestrator for call session');
-    return { ok: false, error: 'No active orchestrator for this call', status: 409 };
+  const controller = getCallController(callSessionId);
+  if (!controller) {
+    log.warn({ callSessionId }, 'answerCall: no active controller for call session');
+    return { ok: false, error: 'No active controller for this call', status: 409 };
   }
 
-  const accepted = await orchestrator.handleUserAnswer(answer);
+  const accepted = await controller.handleUserAnswer(answer);
   if (!accepted) {
     log.warn(
       { callSessionId },
-      'answerCall: orchestrator rejected the answer (not in waiting_on_user state)',
+      'answerCall: controller rejected the answer (not in waiting_on_user state)',
     );
-    return { ok: false, error: 'Orchestrator is not waiting for an answer', status: 409 };
+    return { ok: false, error: 'Controller is not waiting for an answer', status: 409 };
   }
 
   answerPendingQuestion(question.id, answer);
@@ -501,9 +501,9 @@ export async function answerCall(input: AnswerCallInput): Promise<{ ok: true; qu
 }
 
 /**
- * Relay a user instruction to an active call's orchestrator.
+ * Relay a user instruction to an active call's controller.
  * Validates that the call is active and the instruction is non-empty
- * before injecting it into the orchestrator's conversation history.
+ * before injecting it into the controller's conversation.
  */
 export async function relayInstruction(input: RelayInstructionInput): Promise<{ ok: true } | CallError> {
   const { callSessionId, instructionText } = input;
@@ -521,14 +521,14 @@ export async function relayInstruction(input: RelayInstructionInput): Promise<{
     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 };
+  const controller = getCallController(callSessionId);
+  if (!controller) {
+    return { ok: false, error: 'No active controller for this call', status: 409 };
   }
 
-  await orchestrator.handleUserInstruction(instructionText);
+  await controller.handleUserInstruction(instructionText);
 
-  log.info({ callSessionId }, 'User instruction relayed to orchestrator');
+  log.info({ callSessionId }, 'User instruction relayed to controller');
 
   return { ok: true };
 }

package/src/calls/call-state.ts

@@ -1,12 +1,12 @@
 /**
- * Call session notifiers and orchestrator registry.
+ * Call session notifiers and controller registry.
  *
  * Follows the same notifier pattern as watch-state.ts: module-level Maps
  * with register/unregister/fire helpers keyed by conversationId.
  */
 
 import { getLogger } from '../util/logger.js';
-import type { CallOrchestrator } from './call-orchestrator.js';
+import type { CallController } from './call-controller.js';
 
 const log = getLogger('call-state');
 
@@ -69,19 +69,19 @@ export function fireCallCompletionNotifier(conversationId: string, callSessionId
   completionNotifiers.get(conversationId)?.(callSessionId);
 }
 
-// ── Active orchestrator registry ────────────────────────────────────
-const activeCallOrchestrators = new Map<string, CallOrchestrator>();
+// ── Active controller registry ──────────────────────────────────────
+const activeCallControllers = new Map<string, CallController>();
 
-export function registerCallOrchestrator(callSessionId: string, orchestrator: CallOrchestrator): void {
-  activeCallOrchestrators.set(callSessionId, orchestrator);
-  log.info({ callSessionId }, 'Call orchestrator registered');
+export function registerCallController(callSessionId: string, controller: CallController): void {
+  activeCallControllers.set(callSessionId, controller);
+  log.info({ callSessionId }, 'Call controller registered');
 }
 
-export function unregisterCallOrchestrator(callSessionId: string): void {
-  activeCallOrchestrators.delete(callSessionId);
-  log.info({ callSessionId }, 'Call orchestrator unregistered');
+export function unregisterCallController(callSessionId: string): void {
+  activeCallControllers.delete(callSessionId);
+  log.info({ callSessionId }, 'Call controller unregistered');
 }
 
-export function getCallOrchestrator(callSessionId: string): CallOrchestrator | undefined {
-  return activeCallOrchestrators.get(callSessionId);
+export function getCallController(callSessionId: string): CallController | undefined {
+  return activeCallControllers.get(callSessionId);
 }

package/src/calls/guardian-dispatch.ts

@@ -1,7 +1,7 @@
 /**
  * Guardian dispatch engine for cross-channel voice calls.
  *
- * When a call orchestrator detects ASK_GUARDIAN, this module:
+ * When a call controller detects ASK_GUARDIAN, this module:
  * 1. Creates a guardian_action_request
  * 2. Determines delivery destinations (telegram, sms, macos)
  * 3. Creates guardian_action_delivery rows for each destination
@@ -10,7 +10,9 @@
  */
 
 import { getLogger } from '../util/logger.js';
+import { getConfig } from '../config/loader.js';
 import { getGatewayInternalBaseUrl } from '../config/env.js';
+import { emitNotificationSignal } from '../notifications/emit-signal.js';
 import { getActiveBinding } from '../memory/channel-guardian-store.js';
 import {
   createGuardianActionRequest,
@@ -75,6 +77,39 @@ export async function dispatchGuardianQuestion(params: GuardianDispatchParams):
       'Created guardian action request',
     );
 
+    // Emit notification signal through the unified pipeline (fire-and-forget).
+    // The existing guardian dispatch logic below handles the actual delivery
+    // to specific channels (telegram, sms, macos), so this signal is
+    // supplementary — it lets the decision engine log and potentially route
+    // to additional channels in the future.
+    void emitNotificationSignal({
+      sourceEventName: 'guardian.question',
+      sourceChannel: 'voice',
+      sourceSessionId: callSessionId,
+      assistantId,
+      attentionHints: {
+        requiresAction: true,
+        urgency: 'high',
+        deadlineAt: expiresAt,
+        isAsyncBackground: false,
+        visibleInSourceNow: false,
+      },
+      contextPayload: {
+        requestId: request.id,
+        requestCode: request.requestCode,
+        callSessionId,
+        questionText: pendingQuestion.questionText,
+        pendingQuestionId: pendingQuestion.id,
+      },
+      dedupeKey: `guardian:${request.id}`,
+    });
+
+    // When the notification system is fully active (enabled + not shadow),
+    // it handles external channel delivery (Telegram, SMS) — skip the
+    // legacy dispatch for those channels to avoid duplicate alerts.
+    const notifConfig = getConfig().notifications;
+    const notificationsActive = notifConfig?.enabled === true && notifConfig.shadowMode !== true;
+
     // Determine delivery destinations
     const destinations: Array<{
       channel: string;
@@ -158,8 +193,13 @@ export async function dispatchGuardianQuestion(params: GuardianDispatchParams):
           destinationChatId: dest.chatId,
           destinationExternalUserId: dest.externalUserId,
         });
-        // External channel — POST to gateway
-        void deliverToExternalChannel(delivery.id, dest.channel, dest.chatId!, request.questionText, request.requestCode, assistantId, readHttpToken() ?? undefined);
+        // External channel — POST to gateway (skip when notification pipeline handles delivery)
+        if (!notificationsActive) {
+          void deliverToExternalChannel(delivery.id, dest.channel, dest.chatId!, request.questionText, request.requestCode, assistantId, readHttpToken() ?? undefined);
+        } else {
+          updateDeliveryStatus(delivery.id, 'sent');
+          log.info({ deliveryId: delivery.id, channel: dest.channel }, 'Skipping legacy external delivery — notification pipeline active');
+        }
       }
     }
   } catch (err) {

package/src/calls/relay-server.ts

@@ -17,7 +17,7 @@ import {
   recordCallEvent,
   expirePendingQuestions,
 } from './call-store.js';
-import { CallOrchestrator } from './call-orchestrator.js';
+import { CallController } from './call-controller.js';
 import { fireCallTranscriptNotifier, fireCallCompletionNotifier } from './call-state.js';
 import { addPointerMessage, formatDuration } from './call-pointer-messages.js';
 import { persistCallCompletionMessage } from './call-conversation-messages.js';
@@ -145,7 +145,7 @@ export class RelayConnection {
     speaker?: PromptSpeakerContext;
   }>;
   private abortController: AbortController;
-  private orchestrator: CallOrchestrator | null = null;
+  private controller: CallController | null = null;
   private speakerIdentityTracker: SpeakerIdentityTracker;
 
   // Verification state (outbound callee verification)
@@ -263,26 +263,26 @@ export class RelayConnection {
   }
 
   /**
-   * Set the orchestrator for this connection.
+   * Set the controller for this connection.
    */
-  setOrchestrator(orchestrator: CallOrchestrator): void {
-    this.orchestrator = orchestrator;
+  setController(controller: CallController): void {
+    this.controller = controller;
   }
 
   /**
-   * Get the orchestrator for this connection.
+   * Get the controller for this connection.
    */
-  getOrchestrator(): CallOrchestrator | null {
-    return this.orchestrator;
+  getController(): CallController | null {
+    return this.controller;
   }
 
   /**
    * Clean up resources on disconnect.
    */
   destroy(): void {
-    if (this.orchestrator) {
-      this.orchestrator.destroy();
-      this.orchestrator = null;
+    if (this.controller) {
+      this.controller.destroy();
+      this.controller = null;
     }
     this.abortController.abort();
     log.info({ callSessionId: this.callSessionId }, 'RelayConnection destroyed');
@@ -382,7 +382,7 @@ export class RelayConnection {
     const assistantId = normalizeAssistantId(session?.assistantId ?? 'self');
     const isInbound = session?.initiatedFromConversationId == null;
 
-    // Create and attach the LLM-driven orchestrator. For inbound voice,
+    // Create and attach the session-backed voice controller. For inbound voice,
     // seed guardian actor context from caller identity + active binding so
     // first-turn behavior matches channel ingress semantics.
     const initialGuardianContext = isInbound
@@ -397,12 +397,12 @@ export class RelayConnection {
       )
       : undefined;
 
-    const orchestrator = new CallOrchestrator(this.callSessionId, this, session?.task ?? null, {
+    const controller = new CallController(this.callSessionId, this, session?.task ?? null, {
       broadcast: globalBroadcast,
       assistantId,
       guardianContext: initialGuardianContext,
     });
-    this.setOrchestrator(orchestrator);
+    this.setController(controller);
 
     const config = getConfig();
     const verificationConfig = config.calls.verification;
@@ -416,10 +416,10 @@ export class RelayConnection {
       if (pendingChallenge) {
         this.startInboundGuardianVerification(assistantId, msg.from);
       } else {
-        this.startNormalCallFlow(orchestrator, true);
+        this.startNormalCallFlow(controller, true);
       }
     } else {
-      this.startNormalCallFlow(orchestrator, false);
+      this.startNormalCallFlow(controller, false);
     }
   }
 
@@ -469,13 +469,13 @@ export class RelayConnection {
   }
 
   /**
-   * Start normal call flow — fire the orchestrator greeting unless a
+   * Start normal call flow — fire the controller greeting unless a
    * static welcome greeting is configured.
    */
-  private startNormalCallFlow(orchestrator: CallOrchestrator, isInbound: boolean): void {
+  private startNormalCallFlow(controller: CallController, isInbound: boolean): void {
     const hasStaticGreeting = !!process.env.CALL_WELCOME_GREETING?.trim();
     if (!hasStaticGreeting) {
-      orchestrator.startInitialGreeting().catch((err) =>
+      controller.startInitialGreeting().catch((err) =>
         log.error({ err, callSessionId: this.callSessionId }, `Failed to start initial ${isInbound ? 'inbound' : 'outbound'} greeting`),
       );
     }
@@ -582,8 +582,8 @@ export class RelayConnection {
 
       // Proceed to normal call flow (use startNormalCallFlow to respect
       // the CALL_WELCOME_GREETING static greeting guard)
-      if (this.orchestrator) {
-        this.orchestrator.setGuardianContext(
+      if (this.controller) {
+        this.controller.setGuardianContext(
           toGuardianRuntimeContext(
             'voice',
             resolveGuardianContext({
@@ -594,7 +594,7 @@ export class RelayConnection {
             }),
           ),
         );
-        this.startNormalCallFlow(this.orchestrator, true);
+        this.startNormalCallFlow(this.controller, true);
       }
     } else {
       this.verificationAttempts++;
@@ -703,22 +703,17 @@ export class RelayConnection {
 
     const session = getCallSession(this.callSessionId);
     if (session) {
-      // Persist caller transcript to the voice conversation so it survives
-      // even when no live daemon Session is listening.
-      conversationStore.addMessage(
-        session.conversationId,
-        'user',
-        JSON.stringify([{ type: 'text', text: msg.voicePrompt }]),
-        { userMessageChannel: 'voice', assistantMessageChannel: 'voice' },
-      );
+      // User message persistence is handled by the session pipeline
+      // (RunOrchestrator.startRun -> session.persistUserMessage) so we only
+      // need to fire the transcript notifier for UI subscribers here.
       fireCallTranscriptNotifier(session.conversationId, this.callSessionId, 'caller', msg.voicePrompt);
     }
 
-    // Route to orchestrator for LLM-driven response
-    if (this.orchestrator) {
-      await this.orchestrator.handleCallerUtterance(msg.voicePrompt, speaker);
+    // Route to controller for session-backed response
+    if (this.controller) {
+      await this.controller.handleCallerUtterance(msg.voicePrompt, speaker);
     } else {
-      // Fallback if orchestrator not yet initialized
+      // Fallback if controller not yet initialized
       this.sendTextToken('I\'m still setting up. Please hold.', true);
     }
   }
@@ -733,9 +728,9 @@ export class RelayConnection {
     this.abortController.abort();
     this.abortController = new AbortController();
 
-    // Notify the orchestrator of the interruption
-    if (this.orchestrator) {
-      this.orchestrator.handleInterrupt();
+    // Notify the controller of the interruption
+    if (this.controller) {
+      this.controller.handleInterrupt();
     }
   }
 
@@ -780,8 +775,8 @@ export class RelayConnection {
           log.info({ callSessionId: this.callSessionId }, 'Callee verification succeeded');
 
           // Proceed to the normal call flow
-          if (this.orchestrator) {
-            this.orchestrator.startInitialGreeting().catch((err) =>
+          if (this.controller) {
+            this.controller.startInitialGreeting().catch((err) =>
               log.error({ err, callSessionId: this.callSessionId }, 'Failed to start initial outbound greeting after verification'),
             );
           }

package/src/calls/twilio-routes.ts

@@ -73,9 +73,9 @@ export function buildWelcomeGreeting(task: string | null, configuredGreeting?: s
   void task;
   const override = configuredGreeting?.trim();
   if (override) return override;
-  // The contextual first opener now comes from the call orchestrator's
-  // initial LLM turn. Keep Twilio's relay-level greeting empty by default
-  // so we don't speak a deterministic static line first.
+  // The contextual first opener now comes from the call controller's
+  // initial LLM turn via the session pipeline. Keep Twilio's relay-level
+  // greeting empty by default so we don't speak a deterministic static line first.
   return '';
 }
 

package/src/calls/voice-session-bridge.ts

@@ -0,0 +1,244 @@
+/**
+ * Bridge between voice relay and the daemon session/run pipeline.
+ *
+ * Provides a `startVoiceTurn()` function that wraps RunOrchestrator.startRun()
+ * with voice-specific defaults, translating agent-loop events into simple
+ * callbacks suitable for real-time TTS streaming.
+ *
+ * Dependency injection follows the same module-level setter pattern used by
+ * setRelayBroadcast in relay-server.ts: the daemon lifecycle injects the
+ * RunOrchestrator instance at startup via `setVoiceBridgeOrchestrator()`.
+ */
+
+import type { RunOrchestrator, VoiceRunEventSink } from '../runtime/run-orchestrator.js';
+import type { GuardianRuntimeContext } from '../daemon/session-runtime-assembly.js';
+import { getConfig } from '../config/loader.js';
+import { getLogger } from '../util/logger.js';
+
+/**
+ * Matches the exact `[CALL_OPENING]` marker that call-controller sends for
+ * the initial greeting turn. We replace it with a benign content string before
+ * persisting so the marker never appears in session history where it could
+ * retrigger opener behavior after a barge-in interruption.
+ */
+const CALL_OPENING_MARKER = '[CALL_OPENING]';
+
+
+const log = getLogger('voice-session-bridge');
+
+// ---------------------------------------------------------------------------
+// Module-level dependency injection
+// ---------------------------------------------------------------------------
+
+let orchestrator: RunOrchestrator | undefined;
+
+/**
+ * Inject the RunOrchestrator instance from daemon lifecycle.
+ * Must be called during daemon startup before any voice turns are executed.
+ */
+export function setVoiceBridgeOrchestrator(orch: RunOrchestrator): void {
+  orchestrator = orch;
+}
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface VoiceTurnOptions {
+  /** The conversation ID for this voice call's session. */
+  conversationId: string;
+  /** The transcribed caller utterance or synthetic marker. */
+  content: string;
+  /** Assistant scope for multi-assistant channels. */
+  assistantId?: string;
+  /** Guardian trust context for the caller. */
+  guardianContext?: GuardianRuntimeContext;
+  /** Whether this is an inbound call (no outbound task). */
+  isInbound: boolean;
+  /** The outbound call task, if any. */
+  task?: string | null;
+  /** Called for each streaming text token from the agent loop. */
+  onTextDelta: (text: string) => void;
+  /** Called when the agent loop completes a full response. */
+  onComplete: () => void;
+  /** Called when the agent loop encounters an error. */
+  onError: (message: string) => void;
+  /** Optional AbortSignal for external cancellation (e.g. barge-in). */
+  signal?: AbortSignal;
+}
+
+export interface VoiceTurnHandle {
+  /** The run ID for this turn. */
+  runId: string;
+  /** Abort the in-flight turn (e.g. for barge-in). */
+  abort: () => void;
+}
+
+// ---------------------------------------------------------------------------
+// Call-control protocol prompt builder
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the call-control protocol prompt injected into each voice turn.
+ *
+ * This contains the marker protocol rules that the model needs to emit
+ * control markers during voice calls. It intentionally omits the "You are
+ * on a live phone call" framing (the session system prompt already
+ * provides assistant identity) and guardian context (injected separately).
+ */
+function buildVoiceCallControlPrompt(opts: {
+  isInbound: boolean;
+  task?: string | null;
+}): string {
+  const config = getConfig();
+  const disclosureEnabled = config.calls?.disclosure?.enabled === true;
+  const disclosureText = config.calls?.disclosure?.text?.trim();
+  const disclosureRule = disclosureEnabled && disclosureText
+    ? `1. ${disclosureText}`
+    : '1. Begin the conversation naturally.';
+
+  const lines: string[] = ['<voice_call_control>'];
+
+  if (!opts.isInbound && opts.task) {
+    lines.push(`Task: ${opts.task}`);
+    lines.push('');
+  }
+
+  lines.push(
+    'CALL PROTOCOL RULES:',
+    '0. When introducing yourself, refer to yourself as an assistant. Avoid the phrase "AI assistant" unless directly asked.',
+    disclosureRule,
+    '2. Be concise — phone conversations should be brief and natural.',
+  );
+
+  if (opts.isInbound) {
+    lines.push(
+      '3. If the caller asks something you don\'t know or need to verify, include [ASK_GUARDIAN: your question here] in your response along with a hold message like "Let me check on that for you."',
+      '4. If information is provided preceded by [USER_ANSWERED: ...], use that answer naturally in the conversation.',
+      '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 caller indicates they are done or the conversation reaches a natural conclusion, include [END_CALL] in your response along with a polite goodbye.',
+    );
+  } else {
+    lines.push(
+      '3. If the callee asks something you don\'t know, include [ASK_GUARDIAN: 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. 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.',
+    );
+  }
+
+  lines.push(
+    '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.',
+  );
+
+  if (opts.isInbound) {
+    lines.push(
+      '10. If the latest user turn is [CALL_OPENING], greet the caller warmly and ask how you can help. Vary the wording; do not use a fixed template.',
+      '11. If the latest user turn includes [CALL_OPENING_ACK], treat it as the caller acknowledging your greeting and continue the conversation naturally.',
+    );
+  } else {
+    lines.push(
+      '10. If the latest user turn is [CALL_OPENING], generate a natural, context-specific opener: briefly introduce yourself once as an assistant, state why you are calling using the Task context, and ask a short permission/check-in question. Vary the wording; do not use a fixed template.',
+      '11. If the latest user turn includes [CALL_OPENING_ACK], treat it as the callee acknowledging your opener and continue the conversation naturally without re-introducing yourself or repeating the initial check-in question.',
+    );
+  }
+
+  lines.push(
+    '12. Do not repeat your introduction within the same call unless the callee explicitly asks who you are.',
+    '</voice_call_control>',
+  );
+
+  return lines.join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// startVoiceTurn
+// ---------------------------------------------------------------------------
+
+/**
+ * Execute a single voice turn through the daemon session pipeline.
+ *
+ * Wraps RunOrchestrator.startRun() with voice-specific defaults:
+ *   - sourceChannel: 'voice'
+ *   - eventSink wired to the provided callbacks
+ *   - abort propagated from the returned handle
+ *
+ * The caller (CallController via relay-server) can use the returned handle
+ * to cancel the turn on barge-in.
+ */
+export async function startVoiceTurn(opts: VoiceTurnOptions): Promise<VoiceTurnHandle> {
+  if (!orchestrator) {
+    throw new Error('Voice bridge not initialized — setVoiceBridgeOrchestrator() was not called');
+  }
+
+  const eventSink: VoiceRunEventSink = {
+    onTextDelta: opts.onTextDelta,
+    onMessageComplete: opts.onComplete,
+    onError: opts.onError,
+    onToolUse: (toolName, input) => {
+      log.debug({ toolName, input }, 'Voice turn tool_use event');
+    },
+  };
+
+  // Voice has no interactive permission/secret UI, so apply explicit
+  // per-role policies:
+  // - guardian: permission prompts auto-allow (parity with guardian chat)
+  // - everyone else (including unknown): fail-closed strict side-effects
+  //   with auto-deny confirmations.
+  const actorRole = opts.guardianContext?.actorRole;
+  const isGuardian = actorRole === 'guardian';
+  const forceStrictSideEffects = isGuardian ? undefined : true;
+
+  // Replace the [CALL_OPENING] marker with a neutral instruction before
+  // persisting. The marker must not appear as a user message in session
+  // history — after a barge-in interruption the next turn would replay
+  // the stale marker and potentially retrigger opener behavior.
+  const persistedContent = opts.content === CALL_OPENING_MARKER
+    ? '(call connected — deliver opening greeting)'
+    : opts.content;
+
+  // Build the call-control protocol prompt so the model knows how to emit
+  // control markers (ASK_GUARDIAN, END_CALL, CALL_OPENING, etc.).
+  const voiceCallControlPrompt = buildVoiceCallControlPrompt({
+    isInbound: opts.isInbound,
+    task: opts.task,
+  });
+
+  const { run, abort } = await orchestrator.startRun(
+    opts.conversationId,
+    persistedContent,
+    undefined, // no attachments for voice
+    {
+      sourceChannel: 'voice',
+      assistantId: opts.assistantId,
+      guardianContext: opts.guardianContext,
+      ...(forceStrictSideEffects ? { forceStrictSideEffects } : {}),
+      voiceAutoDenyConfirmations: !isGuardian,
+      voiceAutoAllowConfirmations: isGuardian,
+      voiceAutoResolveSecrets: true,
+      turnChannelContext: {
+        userMessageChannel: 'voice',
+        assistantMessageChannel: 'voice',
+      },
+      eventSink,
+      voiceCallControlPrompt,
+    },
+  );
+
+  // If the caller provided an external AbortSignal (e.g. from a
+  // RelayConnection's AbortController), wire it to the run's abort.
+  if (opts.signal) {
+    if (opts.signal.aborted) {
+      abort();
+    } else {
+      opts.signal.addEventListener('abort', () => abort(), { once: true });
+    }
+  }
+
+  return {
+    runId: run.id,
+    abort,
+  };
+}