@vellumai/assistant 0.12.3-staging.1 → 0.12.3-staging.2

package/src/calls/barge-in-guard.ts

@@ -55,6 +55,8 @@ export type BargeInGuardStep = "pending" | "reset" | "fired";
 export interface BargeInGuard {
   /** Speech accumulated in the current run. */
   readonly speechMs: number;
+  /** Whether this run has met the threshold, latched until the guard is replaced. */
+  readonly fired: boolean;
   /** Feed one classified chunk of `chunkMs` audio. */
   track(
     classification: BargeInChunkClassification,
@@ -82,6 +84,9 @@ export function createBargeInGuard(minSpeechMs: number): BargeInGuard {
   };
 
   return {
+    get fired() {
+      return fired;
+    },
     get speechMs() {
       return speechMs;
     },

package/src/calls/call-controller.ts

@@ -94,6 +94,11 @@ import {
   type FrontDoorLegCoordinator,
   type SpokenEscalationBridge,
 } from "./voice-leg-coordinator.js";
+import {
+  getVoiceMetricsAggregateFields,
+  VoiceMetricsCollector,
+  type VoiceMetricsSnapshot,
+} from "./voice-metrics.js";
 import { createProgressCadence } from "./voice-progress-cadence.js";
 import {
   CONVERSATION_BUSY_MESSAGE,
@@ -248,6 +253,23 @@ export class CallController {
   private readonly progressConfig: VoiceProgressConfig;
   /** Rotates the static narration fallback across turns. */
   private progressPhraseCounter = 0;
+  /** Per-turn latency marks for the call, shared with live voice. */
+  private readonly metrics: VoiceMetricsCollector;
+  /**
+   * The turn the collector currently has open, or null between turns. Every
+   * mark is guarded on this: the collector opens a turn for any mark that
+   * arrives without one, so an unguarded late callback would invent a phantom
+   * turn that never settles.
+   */
+  private metricsTurnId: string | null = null;
+  /**
+   * When the caller's utterance was transcribed, held until the turn it
+   * dispatches opens. The phone commits on the provider's utterance-boundary
+   * final, so this is the turn's speech-end anchor as well as its transcript
+   * mark; seeding it backdates the turn to the moment the caller stopped
+   * talking rather than the moment the controller got around to dispatching.
+   */
+  private pendingFinalTranscriptAtMs: number | null = null;
 
   constructor(
     callSessionId: string,
@@ -285,6 +307,11 @@ export class CallController {
     this.conversationId = session?.conversationId ?? callSessionId;
     this.skipDisclosure = session?.skipDisclosure ?? false;
 
+    this.metrics = new VoiceMetricsCollector({
+      sessionId: callSessionId,
+      conversationId: this.conversationId,
+    });
+
     this.startDurationTimer();
     this.resetSilenceTimer();
     registerCallController(callSessionId, this);
@@ -297,6 +324,14 @@ export class CallController {
     return this.state;
   }
 
+  /**
+   * The call's per-turn latency marks so far. Read-only: the collector is fed
+   * from this controller's own turn lifecycle.
+   */
+  getMetricsSnapshot(): VoiceMetricsSnapshot {
+    return this.metrics.getSnapshot();
+  }
+
   /**
    * Returns the question ID of the currently pending guardian consultation,
    * or null if no consultation is active. Used by answerCall to match
@@ -370,6 +405,10 @@ export class CallController {
    * consultation is pending — the consultation is tracked separately.
    */
   async handleCallerUtterance(transcript: string): Promise<void> {
+    // Stamped before the teardown waits below, which can run for hundreds of
+    // milliseconds: the caller stopped talking now, not once the prior turn
+    // finished dying.
+    this.pendingFinalTranscriptAtMs = Date.now();
     // If the caller speaks while an END_CALL teardown is pending (during the
     // drain wait or the listen window), this is a deferral — the caller is
     // re-engaging after we tried to hang up. Track it so we can cap repeats.
@@ -518,6 +557,7 @@ export class CallController {
       { callSessionId: this.callSessionId, state: this.state },
       "Barge-in accepted: interrupting the assistant's turn",
     );
+    this.markTurnMetric((turnId) => this.metrics.markBargeIn(turnId));
     onAccepted?.();
     this.handleInterrupt();
     return true;
@@ -532,6 +572,9 @@ export class CallController {
    * the transport's sustained-speech guard to vouch for the interruption.
    */
   handleInterrupt(): void {
+    // One cancelled turn: the interruption ends the turn here, whether or not
+    // anything picks the work up afterwards.
+    this.cancelMetricsTurn("interrupted");
     const wasSpeaking = this.state === "speaking";
     this.abortCurrentTurn();
     this.llmRunVersion++;
@@ -551,6 +594,7 @@ export class CallController {
    */
   destroy(): void {
     this.destroyed = true;
+    this.cancelMetricsTurn("call_ended");
     if (this.silenceTimer) {
       clearTimeout(this.silenceTimer);
     }
@@ -658,6 +702,7 @@ export class CallController {
     // Stamped before any pre-bridge work so the bridge's dispatch-timing log
     // attributes the whole turn, TTS provider resolution included.
     const launchedAtMs = Date.now();
+    this.openMetricsTurn(runVersion);
 
     // Clear silence timer while actively processing. The caller said
     // something (or a turn was triggered), so silence detection should
@@ -687,6 +732,10 @@ export class CallController {
       await this.handleTurnCompletion(outcome);
     } catch (err: unknown) {
       this.currentTurnHandle = null;
+      // Only this run's turn: a turn whose abort outlives the teardown wait
+      // rejects after its replacement has already opened, and settling by
+      // "whatever is open" would cancel the healthy turn's marks.
+      this.cancelMetricsTurnForRun(runVersion, "turn_error");
       // Aborted requests are expected (interruptions, rapid utterances)
       if (this.isExpectedAbortError(err) || runSignal.aborted) {
         log.debug(
@@ -1016,7 +1065,17 @@ export class CallController {
         transcriptSoFar: () => callerTranscript,
         language: () => this.resolveSynthesisLanguage(),
         deltaEpoch: () => deltaEpoch,
-        speak: speakFixedPhrase,
+        // Only the cadence's own phrases count as narration; the escalation
+        // bridge speaks through the same helper and is part of the answer.
+        speak: (text, language) => {
+          const spoken = speakFixedPhrase(text, language);
+          if (spoken) {
+            this.markTurnMetric((turnId) =>
+              this.metrics.markProgressSpoken(turnId),
+            );
+          }
+          return spoken;
+        },
       },
     });
     const settleTurn = (): void => {
@@ -1149,6 +1208,13 @@ export class CallController {
                   flushSafeText(fullResponseText);
                 },
                 abortLeg: () => legHandle?.abort(),
+                overruleLeg: () => {
+                  if (legHandle?.overrule) {
+                    legHandle.overrule();
+                  } else {
+                    legHandle?.abort();
+                  }
+                },
                 speakBridge: speakEscalationBridge,
                 startEscalatedLeg: (escalated) => {
                   const started = runVoiceLeg(escalated);
@@ -1179,6 +1245,9 @@ export class CallController {
           if (!this.isCurrentRun(runVersion) || coordinator?.handedOff) {
             return;
           }
+          this.markTurnMetric((turnId) =>
+            this.metrics.markFirstAssistantDelta(turnId),
+          );
           ingest(reasoningFilter.push(text));
         };
 
@@ -1197,6 +1266,15 @@ export class CallController {
           // A held "[..." tail that never completed a marker is real text,
           // released to both consumers before the leg settles.
           ingest(reasoningFilter.flush());
+          // An answer held for the escalation judge is spoken or overruled
+          // before the leg settles, so the turn awaits the right leg.
+          if (coordinator?.awaitingJudge === true) {
+            void coordinator.settled().then(() => {
+              coordinator.complete();
+              resolve();
+            });
+            return;
+          }
           coordinator?.complete();
           resolve();
         };
@@ -1205,6 +1283,11 @@ export class CallController {
           reject(new Error(message));
         };
 
+        // First-wins across the turn's two legs, so this is the front-door
+        // dispatch: the moment the caller's wait actually starts.
+        this.markTurnMetric((turnId) =>
+          this.metrics.markAssistantDispatch(turnId),
+        );
         startVoiceTurn({
           conversationId: this.conversationId,
           callSessionId: this.callSessionId,
@@ -1239,6 +1322,9 @@ export class CallController {
             legHandle = handle;
             if (this.isCurrentRun(runVersion) && !coordinator?.handedOff) {
               this.currentTurnHandle = handle;
+              if (coordinator !== null && handle.escalationJudgement) {
+                coordinator.attachEscalationJudge(handle.escalationJudgement);
+              }
             } else {
               // Superseded, or the front-door leg handed off before its
               // handle arrived: abort immediately.
@@ -1494,6 +1580,7 @@ export class CallController {
    * and normal idle transition.
    */
   private async handleTurnCompletion(outcome: VoiceTurnOutcome): Promise<void> {
+    this.completeMetricsTurn();
     const responseText = outcome.text;
 
     // Record the assistant response event, keyed to the conversation rows it
@@ -1923,6 +2010,10 @@ export class CallController {
     if (this.state === "processing") {
       this.state = "speaking";
     }
+    // Real outbound audio, not merely buffered tokens: on media-stream this
+    // fires from the transport's audio-start signal, which is the closest the
+    // daemon gets to the moment the caller hears the answer.
+    this.markTurnMetric((turnId) => this.metrics.markFirstTtsAudio(turnId));
   }
 
   /**
@@ -1947,6 +2038,110 @@ export class CallController {
     }
   }
 
+  /**
+   * Open the collector's turn for this run, seeded with the caller's
+   * transcript mark.
+   *
+   * A turn still open here was superseded by a rapid follow-up utterance
+   * (which aborts the old turn without going through the interrupt path), so
+   * it settles as cancelled and gets its line in the log before the new one
+   * starts.
+   */
+  private openMetricsTurn(runVersion: number): void {
+    this.cancelMetricsTurn("superseded");
+    const turnId = this.metricsTurnIdForRun(runVersion);
+    const finalTranscriptAtMs = this.pendingFinalTranscriptAtMs;
+    this.pendingFinalTranscriptAtMs = null;
+    this.metricsTurnId = turnId;
+    // The provider's utterance-boundary final is both the transcript and the
+    // moment the caller stopped speaking, so it anchors the round trip too;
+    // a phone turn has no separate VAD end or push-to-talk release to use.
+    this.metrics.startTurn(
+      turnId,
+      finalTranscriptAtMs !== null
+        ? { finalTranscriptAtMs, utteranceEndAtMs: finalTranscriptAtMs }
+        : {},
+    );
+  }
+
+  /**
+   * Run a mark against the call's open turn, if there is one.
+   *
+   * The collector opens a turn for any mark that arrives without one, so
+   * every phone mark is guarded: a delta from a superseded leg or a barge-in
+   * between turns must leave no trace rather than invent a turn that never
+   * settles.
+   */
+  private markTurnMetric(mark: (turnId: string) => void): void {
+    if (this.metricsTurnId === null) {
+      return;
+    }
+    mark(this.metricsTurnId);
+  }
+
+  private completeMetricsTurn(): void {
+    this.settleMetricsTurn("completed", (turnId) =>
+      this.metrics.completeTurn(turnId),
+    );
+  }
+
+  private cancelMetricsTurn(reason: string): void {
+    this.settleMetricsTurn(reason, (turnId) =>
+      this.metrics.cancelTurn(reason, turnId),
+    );
+  }
+
+  /** The turn id a given run's marks belong to. */
+  private metricsTurnIdForRun(runVersion: number): string {
+    return `${this.callSessionId}#${runVersion}`;
+  }
+
+  /**
+   * Cancel the open turn only if it is the one this run opened.
+   *
+   * Defensive: the abort listener resolves a superseded leg rather than
+   * rejecting it, and a genuine rejection is processed before the replacement
+   * turn opens, so no path today reaches the error handler holding a newer
+   * turn. Scoping the settle to its own run keeps that true by construction
+   * rather than by the ordering of two other code paths.
+   */
+  private cancelMetricsTurnForRun(runVersion: number, reason: string): void {
+    if (this.metricsTurnId !== this.metricsTurnIdForRun(runVersion)) {
+      return;
+    }
+    this.cancelMetricsTurn(reason);
+  }
+
+  /**
+   * Settle the open turn and log what it measured.
+   *
+   * Live voice streams a metrics frame to its client on every mark; a call
+   * has no client on the line, so the per-turn aggregate lands in the log
+   * instead. Cancelled turns are logged too: a turn the caller cut off still
+   * measured everything up to the interruption, and how long the assistant
+   * took before being cut off is the more interesting number of the two.
+   */
+  private settleMetricsTurn(
+    status: string,
+    settle: (turnId: string) => void,
+  ): void {
+    const turnId = this.metricsTurnId;
+    if (turnId === null) {
+      return;
+    }
+    this.metricsTurnId = null;
+    settle(turnId);
+    log.info(
+      {
+        callSessionId: this.callSessionId,
+        turnId,
+        status,
+        ...getVoiceMetricsAggregateFields(this.metrics.getSnapshot(), turnId),
+      },
+      "Phone call turn metrics",
+    );
+  }
+
   private isCurrentRun(runVersion: number): boolean {
     return runVersion === this.llmRunVersion;
   }

package/src/calls/call-domain.ts

@@ -299,6 +299,7 @@ export async function createInboundVoiceSession(
   const session = createCallSession({
     conversationId: voiceConversationId,
     provider: "twilio",
+    direction: "inbound",
     fromNumber,
     toNumber,
   });
@@ -438,6 +439,7 @@ export async function startCall(
     signal?.throwIfAborted();
 
     const session = createCallSession({
+      direction: "outbound",
       conversationId,
       provider: "twilio",
       fromNumber,
@@ -976,6 +978,7 @@ export async function startVerificationCall(
     });
 
     const session = createCallSession({
+      direction: "outbound",
       conversationId,
       provider: "twilio",
       fromNumber: identityResult.fromNumber,
@@ -1109,6 +1112,7 @@ export async function startInviteCall(
     });
 
     const session = createCallSession({
+      direction: "outbound",
       conversationId,
       provider: "twilio",
       fromNumber: identityResult.fromNumber,

package/src/calls/call-store.ts

@@ -1,6 +1,10 @@
-import { and, desc, eq, notInArray, or } from "drizzle-orm";
+import { and, desc, eq, like, notInArray, or } from "drizzle-orm";
 import { v4 as uuid } from "uuid";
 
+import {
+  recordPhoneCallEnded,
+  recordPhoneCallStarted,
+} from "../onboarding/onboarding-events-store.js";
 import { getDb } from "../persistence/db-connection.js";
 import { rawChanges, rawRun } from "../persistence/raw-query.js";
 import {
@@ -8,10 +12,16 @@ import {
   callPendingQuestions,
   callSessions,
 } from "../persistence/schema/index.js";
+import {
+  type PhoneCallDirection,
+  phoneCallEndScreen,
+  phoneCallSilenceReason,
+  phoneCallStartScreen,
+} from "../telemetry/phone-call-funnel.js";
 import { getLogger } from "../util/logger.js";
 import { cast, createRowMapper } from "../util/row-mapper.js";
 import { syncActiveCallLeaseFromSession } from "./active-call-lease.js";
-import { validateTransition } from "./call-state-machine.js";
+import { isTerminalState, validateTransition } from "./call-state-machine.js";
 import type {
   CallEvent,
   CallEventType,
@@ -85,6 +95,12 @@ export function createCallSession(opts: {
   provider: string;
   fromNumber: string;
   toNumber: string;
+  /**
+   * Which way the call is being placed, for the funnel stamp. Stated rather
+   * than derived: a verification or invite call carries no task and is still
+   * outbound, so task presence is not a direction.
+   */
+  direction: PhoneCallDirection;
   task?: string;
   callMode?: string;
   verificationSessionId?: string;
@@ -122,6 +138,14 @@ export function createCallSession(opts: {
     updatedAt: now,
   };
   db.insert(callSessions).values(row).run();
+  // The call is attempted the moment its row exists, which is before the
+  // provider dials: a call that never connects is exactly the one the funnel
+  // needs to count. An outbound attempt the ingress preflight rejects never
+  // reaches here; see `telemetry/phone-call-funnel.ts`.
+  recordPhoneCallStarted({
+    callSessionId: row.id,
+    screen: phoneCallStartScreen(opts.direction, row.callMode),
+  });
   return { ...row, skipDisclosure };
 }
 
@@ -224,6 +248,13 @@ export function updateCallSession(
     .where(eq(callSessions.id, id))
     .run();
 
+  // Terminal states are immutable and the validator above rejects any write
+  // that follows one, so the first terminal transition to get here is the only
+  // one: the ended event needs no separate once-only latch.
+  if (updates.status && isTerminalState(updates.status)) {
+    recordCallEndedEvent(id, updates.status);
+  }
+
   opts?.beforeLeaseSync?.();
 
   if (shouldSyncActiveLease) {
@@ -240,6 +271,60 @@ export function updateCallSession(
 
 // ── Recovery queries ─────────────────────────────────────────────────
 
+/**
+ * Whether the call's own event log holds an event of this type. Existence
+ * only: the row itself is never read.
+ */
+function hasCallEvent(
+  id: string,
+  eventType: CallEventType,
+  payloadContains?: string,
+): boolean {
+  const db = getDb();
+  const row = db
+    .select({ id: callEvents.id })
+    .from(callEvents)
+    .where(
+      and(
+        eq(callEvents.callSessionId, id),
+        eq(callEvents.eventType, eventType),
+        ...(payloadContains
+          ? [like(callEvents.payloadJson, `%${payloadContains}%`)]
+          : []),
+      ),
+    )
+    .limit(1)
+    .get();
+  return row !== undefined;
+}
+
+/**
+ * Emit the call's funnel end event, classifying a call that never took a
+ * caller turn by how far it got. Both signals come from the call's own event
+ * log: `call_connected` is written when the media stream opens, and
+ * `caller_spoke` when the caller is heard.
+ *
+ * `caller_spoke` carries two senses, though: a transcribed utterance
+ * (`transcript`) and a single DTMF digit (`dtmfDigit`). Only the first is a
+ * conversational turn, so the payload discriminates them. Splitting DTMF into
+ * an event type of its own would be the real fix, but that vocabulary is read
+ * by other consumers and is not this change's to alter.
+ */
+function recordCallEndedEvent(id: string, status: CallStatus): void {
+  const spoke = hasCallEvent(id, "caller_spoke", '"transcript"');
+  const silence = spoke
+    ? null
+    : phoneCallSilenceReason({
+        connected: hasCallEvent(id, "call_connected"),
+      });
+
+  recordPhoneCallEnded({
+    callSessionId: id,
+    screen: phoneCallEndScreen(status, silence),
+    outcome: status === "failed" ? "failed" : "completed",
+  });
+}
+
 /**
  * Returns all call sessions that are in a non-terminal state
  * (i.e. not completed, failed, or cancelled). Used during daemon startup

package/src/calls/guardian-action-sweep.ts

@@ -2,15 +2,17 @@
  * Guardian action expiry notices.
  *
  * Sends "this request has expired" notices to guardian delivery
- * destinations — vellum conversations get an assistant message, external
- * channels (telegram, slack) get a direct channel reply.
+ * destinations: vellum conversations get an assistant message, and external
+ * channels get a direct channel reply on the route
+ * `resolveDeliverCallbackUrlForChannel` names for the channel.
  */
 
 import { DELIVERY_STATUS } from "@vellumai/gateway-client";
 
+import { resolveDeliverCallbackUrlForChannel } from "../approvals/guardian-channel-delivery.js";
 import { addMessage } from "../persistence/conversation-crud.js";
 import { deliverChannelReply } from "../runtime/gateway-client.js";
-import { composeGuardianActionMessageGenerative } from "../runtime/guardian-action-message-composer.js";
+import { composeGuardianActionMessage } from "../runtime/guardian-action-message-composer.js";
 import { getLogger } from "../util/logger.js";
 
 const log = getLogger("guardian-action-sweep");
@@ -27,7 +29,12 @@ export interface ExpiryDeliveryInfo {
 /**
  * Send expiry notices to all delivery destinations for a guardian action
  * request. Handles both vellum/mac conversation messages and external channel
- * replies (telegram, slack).
+ * replies.
+ *
+ * A channel delivery's `destinationChatId` is the notification endpoint the
+ * card went to. On Discord that is the guardian's user snowflake, so the
+ * notice must take the `dm`-marked route that opens their DM; posted as a
+ * channel id it would address nothing.
  *
  * Deliveries must be captured *before* their status is changed to 'expired'
  * so the sent/pending filter still matches.
@@ -45,9 +52,8 @@ export async function sendGuardianExpiryNotices(
     }
 
     try {
-      const expiryText = await composeGuardianActionMessageGenerative({
+      const expiryText = composeGuardianActionMessage({
         scenario: "guardian_stale_expired",
-        channel: delivery.destinationChannel,
       });
 
       if (
@@ -69,8 +75,16 @@ export async function sendGuardianExpiryNotices(
           },
         );
       } else if (delivery.destinationChatId) {
-        // External channel — send expiry notice via direct delivery
-        const deliverUrl = `/deliver/${delivery.destinationChannel}`;
+        const deliverUrl = resolveDeliverCallbackUrlForChannel(
+          delivery.destinationChannel,
+        );
+        if (!deliverUrl) {
+          log.warn(
+            { deliveryId: delivery.id, channel: delivery.destinationChannel },
+            "No delivery route for guardian expiry notice channel",
+          );
+          continue;
+        }
         await deliverChannelReply(deliverUrl, {
           chatId: delivery.destinationChatId,
           text: expiryText,

package/src/calls/media-stream-audio-transcode.ts

@@ -68,9 +68,7 @@ function linearToMulaw(sample: number): number {
   // Determine segment
   const exponent = segmentSearch(sample);
   const mantissa = (sample >> (exponent + 3)) & 0x0f;
-  const mulawByte = ~(sign | (exponent << 4) | mantissa) & 0xff;
-
-  return mulawByte;
+  return ~(sign | (exponent << 4) | mantissa) & 0xff;
 }
 
 function segmentSearch(val: number): number {