@vellumai/assistant 0.10.4 → 0.10.5-dev.202607022329.d89bf2f

package/src/calls/media-stream-server.ts

@@ -21,11 +21,18 @@
  * - WebSocket `open` -> extract callSessionId from upgrade params,
  *   create `MediaStreamCallSession`.
  * - Media stream `start` event -> capture streamSid/callSid, wire
- *   output adapter, create controller.
+ *   output adapter, run setup routing and hand the outcome to a
+ *   `CallSetupFlow` (deny, verification, invite redemption, name
+ *   capture / guardian wait, unverified caller, normal call). The
+ *   controller is created only once the flow completes with a
+ *   `proceed-*` result.
  * - Media stream `media` events -> forwarded to STT session for
  *   turn detection and transcription.
- * - STT `onTranscriptFinal` -> routed to controller's
+ * - STT `onTranscriptFinal` -> routed to the active setup flow's
+ *   `pushTranscriptFinal()`, else the controller's
  *   `handleCallerUtterance()`.
+ * - STT `onDtmf` -> routed to the active setup flow's
+ *   `pushDtmfDigit()` for code-collection sub-flows.
  * - STT `onSpeechStart` -> barge-in: clears outbound audio queue
  *   and interrupts the in-flight LLM turn via the controller.
  * - Media stream `stop` event / WebSocket close -> finalize call.
@@ -34,10 +41,22 @@
 import type { ServerWebSocket } from "bun";
 
 import { revokeScopedApprovalGrantsForContext } from "../approvals/scoped-approval-grants.js";
-import { toTrustContext } from "../runtime/actor-trust-resolver.js";
+import {
+  getGuardianDelivery,
+  getGuardianDeliveryFresh,
+  voiceGuardianDisplayName,
+} from "../contacts/guardian-delivery-reader.js";
+import { getAssistantName } from "../daemon/identity-helpers.js";
+import { addMessage } from "../persistence/conversation-crud.js";
+import { resolveGuardianName } from "../prompts/user-reference.js";
 import { getLogger } from "../util/logger.js";
 import { CallController } from "./call-controller.js";
-import { addPointerMessage, formatDuration } from "./call-pointer-messages.js";
+import {
+  formatDuration,
+  postPointerMessageSafe,
+} from "./call-pointer-messages.js";
+import { CallSetupFlow, type CallSetupFlowDeps } from "./call-setup-flow.js";
+import type { SetupFlowResult } from "./call-setup-flow-types.js";
 import { speakSystemPrompt } from "./call-speech-output.js";
 import {
   fireCallTranscriptNotifier,
@@ -64,6 +83,24 @@ import {
 import { routeSetup } from "./relay-setup-router.js";
 
 const log = getLogger("media-stream-server");
+const UUID_SHAPED_NAME =
+  /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
+
+/**
+ * Resolve the assistant's display name from identity configuration.
+ * Returns the trimmed name, or null when unavailable or UUID-shaped.
+ */
+function resolveAssistantLabel(): string | null {
+  try {
+    const trimmed = getAssistantName()?.trim();
+    if (!trimmed || UUID_SHAPED_NAME.test(trimmed)) {
+      return null;
+    }
+    return trimmed;
+  } catch {
+    return null;
+  }
+}
 
 // ---------------------------------------------------------------------------
 // Active sessions registry (keyed by callSessionId)
@@ -89,6 +126,15 @@ export class MediaStreamCallSession {
   private output: MediaStreamOutput;
   private sttSession: MediaStreamSttSession;
   private controller: CallController | null = null;
+  /**
+   * Active setup flow driving the pre-conversation phase (verification,
+   * invite redemption, name capture, guardian wait, deny). Non-null from
+   * setup routing until the flow completes; caller input routes into it
+   * instead of the controller while set.
+   */
+  private setupFlow: CallSetupFlow | null = null;
+  /** Guardian displayName primed from the gateway binding during setup. */
+  private primedGuardianDisplayName: string | undefined;
   private streamSid: string | null = null;
   private callSid: string | null = null;
   private disposed = false;
@@ -155,6 +201,13 @@ export class MediaStreamCallSession {
     return this.controller;
   }
 
+  /**
+   * Get the active setup flow (for test assertions).
+   */
+  getSetupFlow(): CallSetupFlow | null {
+    return this.setupFlow;
+  }
+
   /**
    * Resolves once the async setup routing started by the `start` frame has
    * settled. Test-only convenience — production code does not await this.
@@ -199,9 +252,24 @@ export class MediaStreamCallSession {
   handleTransportClosed(code?: number, reason?: string): void {
     if (this.disposed) return;
 
+    // Tear down an in-flight setup flow first: clears its timers and emits
+    // the guardian-wait callback handoff when the caller opted in.
+    const setupFlow = this.setupFlow;
+    this.setupFlow = null;
+    setupFlow?.dispose("transport_closed");
+
     const session = getCallSession(this.callSessionId);
     if (!session) return;
-    if (isTerminalState(session.status)) return;
+    if (isTerminalState(session.status)) {
+      // A hangup during a flow-terminal goodbye: dispose above swallowed the
+      // flow's pending complete(), so finalize + revoke grants here. Normal
+      // completion nulls setupFlow and hasFinalized() covers flow-side
+      // finalization, keeping this exactly-once.
+      if (setupFlow && !setupFlow.hasFinalized()) {
+        this.runFinalizationAndGrantCleanup(session);
+      }
+      return;
+    }
 
     const isNormalClose = code === 1000;
     const terminationReason = isNormalClose ? "normal_stop" : "premature_abort";
@@ -232,19 +300,14 @@ export class MediaStreamCallSession {
         const durationMs = session.startedAt
           ? Date.now() - session.startedAt
           : 0;
-        addPointerMessage(
+        postPointerMessageSafe(
           session.initiatedFromConversationId,
           "completed",
           session.toNumber,
           {
             duration: durationMs > 0 ? formatDuration(durationMs) : undefined,
           },
-        ).catch((err) => {
-          log.warn(
-            { conversationId: session.initiatedFromConversationId, err },
-            "Skipping pointer write — origin conversation may no longer exist",
-          );
-        });
+        );
       }
     } else {
       const detail =
@@ -261,39 +324,22 @@ export class MediaStreamCallSession {
       });
 
       if (session.initiatedFromConversationId) {
-        addPointerMessage(
+        postPointerMessageSafe(
           session.initiatedFromConversationId,
           "failed",
           session.toNumber,
           { reason: detail },
-        ).catch((err) => {
-          log.warn(
-            { conversationId: session.initiatedFromConversationId, err },
-            "Skipping pointer write — origin conversation may no longer exist",
-          );
-        });
+        );
       }
     }
 
-    // Revoke any scoped approval grants bound to this call session.
-    // Revoke by both callSessionId and conversationId because the
-    // guardian-approval-interception minting path sets callSessionId: null
-    // but always sets conversationId.
-    try {
-      revokeScopedApprovalGrantsForContext({
-        callSessionId: this.callSessionId,
-      });
-      revokeScopedApprovalGrantsForContext({
-        conversationId: session.conversationId,
-      });
-    } catch (err) {
-      log.warn(
-        { err, callSessionId: this.callSessionId },
-        "Failed to revoke scoped grants on media-stream transport close",
-      );
-    }
+    this.revokeScopedGrants(session.conversationId);
 
-    finalizeCall(this.callSessionId, session.conversationId);
+    // A setup flow that reached a flow-terminal path already ran
+    // finalizeCall — keep finalization exactly-once.
+    if (!setupFlow?.hasFinalized()) {
+      finalizeCall(this.callSessionId, session.conversationId);
+    }
   }
 
   /**
@@ -305,6 +351,9 @@ export class MediaStreamCallSession {
 
     this.sttSession.dispose();
 
+    this.setupFlow?.dispose("teardown");
+    this.setupFlow = null;
+
     if (this.controller) {
       this.controller.destroy();
       unregisterCallController(this.callSessionId);
@@ -365,11 +414,11 @@ export class MediaStreamCallSession {
     });
 
     // ── Setup-policy routing ────────────────────────────────────────
-    // Run the same routeSetup() that the ConversationRelay path uses
-    // to enforce ACL/deny/escalate, verification, and invite flows.
-    // The media-stream transport does not support interactive sub-flows
-    // (DTMF entry, name capture, guardian wait), so non-normal outcomes
-    // are rejected gracefully with a TTS message and session teardown.
+    // Run routeSetup() to enforce ACL/deny/escalate, verification, and
+    // invite flows. The resulting outcome is handed to a CallSetupFlow,
+    // which drives every interactive sub-flow (DTMF/spoken code entry,
+    // invite redemption, name capture, guardian wait) over this
+    // transport.
     const from = session?.fromNumber ?? "";
     const to = session?.toNumber ?? "";
 
@@ -377,41 +426,41 @@ export class MediaStreamCallSession {
     // (e.g. guardian_only) is enforced on this transport too — not just the
     // gateway webhook's no_one kill switch. The reader fails open to `null`
     // by contract, so a transport hiccup admits the caller.
-    const admissionPolicy = await getChannelAdmissionPolicy("phone");
+    //
+    // Concurrently, prime the guardian displayName used by setup-flow copy
+    // and warm the phone-channel guardian-delivery cache for routeSetup's
+    // SYNC resolveActorTrust fallback (gateway-side binding writes don't
+    // invalidate the daemon cache, so read fresh). All three are independent
+    // IPC reads on different cache keys.
+    const [admissionPolicy] = await Promise.all([
+      getChannelAdmissionPolicy("phone"),
+      this.primeGuardianDisplayName(),
+      getGuardianDeliveryFresh({ channelTypes: ["phone"] }),
+    ]);
 
     // The admission-policy read above yields the event loop; if Twilio closed
     // the WebSocket meanwhile, the close handler will have called destroy().
     // Abort setup so we don't create a controller or speak on a disposed
     // session.
-    if (this.disposed) {
-      log.info(
-        { callSessionId: this.callSessionId },
-        "Media-stream session disposed during admission read — aborting setup",
-      );
-      this.setupRouting = false;
+    if (this.abortIfDisposed("admission read")) {
       return;
     }
 
-    // Verdict-first caller trust so this transport enforces the same gateway
-    // ACL as ConversationRelay. routeSetup uses it when present and not
-    // resolutionFailed, else falls back to local resolution. The reader returns
-    // null on failure, keeping the local path on a gateway blip.
+    // Verdict-first caller trust so this transport enforces the gateway
+    // ACL. routeSetup uses it when present and not resolutionFailed, else
+    // falls back to local resolution. The reader returns null on failure,
+    // keeping the local path on a gateway blip.
     const isInbound = session?.initiatedFromConversationId == null;
     const otherPartyNumber = isInbound ? from : to;
     const verdict = await getPhoneCallerVerdict(otherPartyNumber);
 
     // The verdict read above yields the event loop; abort if the session was
     // disposed meanwhile, matching the admission-read guard above.
-    if (this.disposed) {
-      log.info(
-        { callSessionId: this.callSessionId },
-        "Media-stream session disposed during verdict read — aborting setup",
-      );
-      this.setupRouting = false;
+    if (this.abortIfDisposed("verdict read")) {
       return;
     }
 
-    const { outcome, resolved } = routeSetup({
+    const { outcome, resolved } = await routeSetup({
       callSessionId: this.callSessionId,
       session: session ?? null,
       from,
@@ -421,6 +470,12 @@ export class MediaStreamCallSession {
       verdict,
     });
 
+    // routeSetup can yield the event loop (gateway voice-invite read); abort
+    // if the session was disposed meanwhile, matching the guards above.
+    if (this.abortIfDisposed("setup routing")) {
+      return;
+    }
+
     log.info(
       {
         callSessionId: this.callSessionId,
@@ -431,141 +486,175 @@ export class MediaStreamCallSession {
       "Media stream session started",
     );
 
-    switch (outcome.action) {
-      case "normal_call": {
-        // Create the call controller only for normal calls. Deny and
-        // unsupported-flow paths speak a message via the output adapter
-        // directly and don't need a controller. Creating it eagerly
-        // would start duration/silence timers that leak when the
-        // session is torn down before destroy() runs.
-        const initialTrustContext = toTrustContext(
-          resolved.actorTrust,
-          resolved.otherPartyNumber,
-        );
-        this.controller = new CallController(
-          this.callSessionId,
-          this.output,
-          session?.task ?? null,
-          {
-            assistantId: resolved.assistantId,
-            trustContext: initialTrustContext,
-          },
-        );
-        registerCallController(this.callSessionId, this.controller);
+    const flow = new CallSetupFlow(
+      this.callSessionId,
+      this.output,
+      this.buildSetupFlowDeps(session),
+    );
+    this.setupFlow = flow;
+    // Routing/ACL cleared — the flow owns the setup phase from here, so
+    // transcripts and DTMF route into it until it completes.
+    this.setupRouting = false;
+    await flow.start(outcome, resolved);
+  }
 
-        // Routing/ACL cleared — leave the setup-pending window so subsequent
-        // transcripts and barge-in are handled normally.
-        this.setupRouting = false;
+  // ── Setup flow wiring ─────────────────────────────────────────────
 
-        // Fire the initial greeting.
-        this.controller.startInitialGreeting().catch((err) => {
-          log.error(
-            { err, callSessionId: this.callSessionId },
-            "Failed to start initial greeting on media-stream session",
-          );
-        });
-        return;
-      }
+  /**
+   * Abort a pending setup when the session was disposed across an await
+   * in {@link handleStart}: logs the stage and clears the setup-routing
+   * input gate. Returns true when setup must abort.
+   */
+  private abortIfDisposed(stage: string): boolean {
+    if (!this.disposed) {
+      return false;
+    }
+    log.info(
+      { callSessionId: this.callSessionId, stage },
+      "Media-stream session disposed during setup — aborting",
+    );
+    this.setupRouting = false;
+    return true;
+  }
 
-      case "deny":
-        // Deny — speak the denial message and tear down.
-        log.warn(
-          {
-            callSessionId: this.callSessionId,
-            reason: outcome.logReason,
-          },
-          "Media-stream setup denied by ACL policy",
-        );
-        recordCallEvent(this.callSessionId, "inbound_acl_denied", {
-          from,
-          trustClass: resolved.actorTrust.trustClass,
-        });
-        updateCallSession(this.callSessionId, {
-          status: "failed",
-          endedAt: Date.now(),
-          lastError: outcome.logReason,
-        });
-        // Run finalization now because handleTransportClosed will see
-        // terminal status and exit early when the WebSocket closes.
+  /**
+   * Real side-effect surface for the {@link CallSetupFlow}. Pure-logic
+   * deps (code validation, invite redemption, guardian notification,
+   * trust re-resolution, guardian wait construction) use the flow's
+   * real-implementation defaults.
+   */
+  private buildSetupFlowDeps(
+    session: ReturnType<typeof getCallSession>,
+  ): CallSetupFlowDeps {
+    return {
+      speakSystemPrompt: (text) => speakSystemPrompt(this.output, text),
+      updateCallSession,
+      recordCallEvent,
+      onComplete: (result) => this.handleSetupFlowResult(result, session),
+      getCallSession,
+      // Flow-terminal paths set a terminal session status, so the
+      // transport-close handler skips its cleanup — revoke scoped grants
+      // here alongside finalization.
+      finalizeCall: (callSessionId, conversationId) => {
+        this.revokeScopedGrants(conversationId);
+        finalizeCall(callSessionId, conversationId);
+      },
+      addMessage,
+      postPointerMessage: postPointerMessageSafe,
+      fireCallTranscriptNotifier,
+      resolveGuardianLabel: () =>
+        resolveGuardianName(this.primedGuardianDisplayName),
+      resolveAssistantLabel,
+    };
+  }
+
+  /**
+   * Continue the call once the setup flow reaches a terminal result:
+   * create + register the call controller and fire the matching opener
+   * for `proceed-*` variants, or complete finalization for `ended`
+   * (the flow already spoke its terminal copy, set terminal status,
+   * and scheduled its own delayed `endSession`).
+   */
+  private handleSetupFlowResult(
+    result: SetupFlowResult,
+    session: ReturnType<typeof getCallSession>,
+  ): void {
+    const flow = this.setupFlow;
+    this.setupFlow = null;
+
+    if (result.kind === "ended") {
+      // handleTransportClosed will see the terminal status and exit early
+      // when the WebSocket closes, so run cleanup inline — unless a
+      // flow-terminal path already finalized (grants revoked there too).
+      if (!flow?.hasFinalized()) {
         this.runFinalizationAndGrantCleanup(session);
-        void speakSystemPrompt(this.output, outcome.message).finally(() => {
-          setTimeout(() => this.output.endSession(outcome.logReason), 3000);
-        });
-        return;
-
-      default:
-        // All interactive sub-flows (verification, invite_redemption,
-        // name_capture, callee_verification, outbound_verification) are
-        // not supported on the media-stream transport. The TwiML preflight
-        // in twilio-routes.ts should have caught this and fallen back to
-        // ConversationRelay — reaching here indicates the preflight was
-        // bypassed or a new setup action was added without updating the
-        // preflight guard. Speak a generic apology and end the session
-        // rather than silently bypassing policy enforcement.
+      }
+      return;
+    }
+
+    const controller = new CallController(
+      this.callSessionId,
+      this.output,
+      session?.task ?? null,
+      {
+        assistantId: result.assistantId,
+        trustContext: result.trustContext,
+      },
+    );
+    this.controller = controller;
+    registerCallController(this.callSessionId, controller);
+
+    const opener =
+      result.kind === "proceed-post-verification-greeting"
+        ? controller.startPostVerificationGreeting()
+        : result.kind === "proceed-handoff-spoken"
+          ? Promise.resolve(controller.markNextCallerTurnAsOpeningAck())
+          : controller.startInitialGreeting();
+
+    const deferredTranscripts = result.deferredTranscripts ?? [];
+    void opener
+      .then(async () => {
+        // Replay transcripts buffered during mid-setup trust re-resolution,
+        // in order, so the caller's first utterance runs under the upgraded
+        // trust context.
+        for (const text of deferredTranscripts) {
+          await controller.handleCallerUtterance(text);
+        }
+      })
+      .catch((err) => {
         log.error(
-          {
-            callSessionId: this.callSessionId,
-            action: outcome.action,
-          },
-          "Media-stream transport received unsupported setup flow — preflight guard should have prevented this",
+          { err, callSessionId: this.callSessionId },
+          "Failed to start call flow after setup completion",
         );
-        recordCallEvent(this.callSessionId, "call_failed", {
-          reason: `Setup flow '${outcome.action}' not supported on media-stream transport (preflight guard bypass)`,
-          transport: "media-stream",
-        });
-        updateCallSession(this.callSessionId, {
-          status: "failed",
-          endedAt: Date.now(),
-          lastError: `Setup flow '${outcome.action}' not supported on media-stream transport — preflight guard should have prevented this`,
-        });
-        // Run finalization now because handleTransportClosed will see
-        // terminal status and exit early when the WebSocket closes.
-        this.runFinalizationAndGrantCleanup(session);
-        void speakSystemPrompt(
-          this.output,
-          "Sorry, this call requires additional verification that isn't available right now. Please try calling back. Goodbye.",
-        ).finally(() => {
-          setTimeout(
-            () =>
-              this.output.endSession(
-                `Unsupported setup flow: ${outcome.action} (preflight guard bypass)`,
-              ),
-            3000,
-          );
-        });
-        return;
-    }
+      });
   }
 
-  // ── Finalization helper for early-teardown paths ─────────────────
+  /**
+   * Prime the guardian displayName from the gateway binding so the
+   * synchronous setup-flow label path can read it without an IPC
+   * round-trip.
+   */
+  private async primeGuardianDisplayName(): Promise<void> {
+    const list = await getGuardianDelivery();
+    this.primedGuardianDisplayName = voiceGuardianDisplayName(list);
+  }
+
+  // ── Finalization helpers for early-teardown paths ─────────────────
 
   /**
-   * Run scoped-grant revocation and call finalization inline. Used by
-   * the deny and unsupported-flow branches which set terminal status
-   * before `endSession()`. When the WebSocket subsequently closes,
-   * {@link handleTransportClosed} sees the terminal status and exits
-   * early — so we must perform cleanup here to avoid leaking grants
-   * and skipping `finalizeCall()` side-effects.
+   * Revoke any scoped approval grants bound to this call session.
+   * Revoke by both callSessionId and conversationId because the
+   * guardian-approval-interception minting path sets callSessionId: null
+   * but always sets conversationId.
    */
-  private runFinalizationAndGrantCleanup(
-    session: ReturnType<typeof getCallSession>,
-  ): void {
+  private revokeScopedGrants(conversationId: string | undefined): void {
     try {
       revokeScopedApprovalGrantsForContext({
         callSessionId: this.callSessionId,
       });
-      if (session?.conversationId) {
-        revokeScopedApprovalGrantsForContext({
-          conversationId: session.conversationId,
-        });
+      if (conversationId) {
+        revokeScopedApprovalGrantsForContext({ conversationId });
       }
     } catch (err) {
       log.warn(
         { err, callSessionId: this.callSessionId },
-        "Failed to revoke scoped grants on early teardown path",
+        "Failed to revoke scoped grants for media-stream session",
       );
     }
+  }
 
+  /**
+   * Run scoped-grant revocation and call finalization inline. Used for
+   * setup-terminal paths which set terminal status before `endSession()`.
+   * When the WebSocket subsequently closes, {@link handleTransportClosed}
+   * sees the terminal status and exits early — so cleanup must happen
+   * here to avoid leaking grants and skipping `finalizeCall()`
+   * side-effects.
+   */
+  private runFinalizationAndGrantCleanup(
+    session: ReturnType<typeof getCallSession>,
+  ): void {
+    this.revokeScopedGrants(session?.conversationId);
     if (session?.conversationId) {
       finalizeCall(this.callSessionId, session.conversationId);
     }
@@ -581,12 +670,16 @@ export class MediaStreamCallSession {
     // handleBargeIn path so initial inbound audio frames do not cancel a
     // still-starting initial turn.
     //
-    // clearAudio runs BEFORE handleBargeIn so that the end-of-turn mark
-    // enqueued by handleInterrupt (called within handleBargeIn) is not
-    // wiped by the queue flush.
+    // clearAudio runs via the onAccepted hook so it only fires when the
+    // barge-in passes the speaking gate — an ignored barge-in (controller
+    // idle/processing) must not flush queued/in-flight TTS such as a
+    // buffered greeting. The hook runs before handleInterrupt so the
+    // end-of-turn mark it enqueues survives the queue flush.
     if (this.output && this.controller) {
-      this.output.clearAudio();
-      const accepted = this.controller.handleBargeIn();
+      const output = this.output;
+      const accepted = this.controller.handleBargeIn(() =>
+        output.clearAudio(),
+      );
       if (accepted) {
         this.bargeInAccepted++;
         log.info(
@@ -594,6 +687,11 @@ export class MediaStreamCallSession {
           "Media-stream barge-in accepted — cleared outbound audio",
         );
       } else {
+        // No turn to abort, but a completed turn's tail can still be
+        // playing from Twilio's buffer — flush only that buffer so the
+        // caller isn't talked over. Queued speech that hasn't reached
+        // Twilio yet (greeting, handoff prompt) is preserved.
+        output.clearBufferedAudio();
         this.bargeInIgnored++;
         log.debug(
           { callSessionId: this.callSessionId },
@@ -619,6 +717,23 @@ export class MediaStreamCallSession {
 
     this.transcriptFinalsProduced++;
 
+    // While a setup flow is active it owns caller speech (name capture,
+    // spoken code entry, guardian-wait utterances). Fire the transcript
+    // notifier for UI subscribers, then route into the flow.
+    if (this.setupFlow) {
+      const setupSession = getCallSession(this.callSessionId);
+      if (setupSession) {
+        fireCallTranscriptNotifier(
+          setupSession.conversationId,
+          this.callSessionId,
+          "caller",
+          text,
+        );
+      }
+      this.setupFlow.pushTranscriptFinal(text);
+      return;
+    }
+
     if (!this.controller) {
       log.warn(
         { callSessionId: this.callSessionId },
@@ -671,6 +786,10 @@ export class MediaStreamCallSession {
       dtmfDigit: digit,
       transport: "media-stream",
     });
+
+    // While a setup flow is active, digits feed its code-collection
+    // sub-flows (the flow itself records no per-digit events).
+    this.setupFlow?.pushDtmfDigit(digit);
   }
 
   private handleStreamStop(): void {