@vellumai/assistant 0.10.7 → 0.10.8-dev.202607102228.5945895

package/src/calls/call-setup-router.ts

@@ -1,19 +1,21 @@
 /**
  * Pure routing logic for the voice call setup phase.
  *
- * Given a setup context (call session, actor trust, voice config, ACL policy),
- * returns a discriminated union describing what the call session should do
- * next — without performing any side effects itself.
+ * Given a setup context (call session, gateway trust verdict, voice config,
+ * ACL policy), returns a discriminated union describing what the call session
+ * should do next — without performing any side effects itself.
+ *
+ * The gateway verdict is the sole caller-trust source. An unusable verdict
+ * (missing, `resolutionFailed`, or member-unresolvable) fails closed —
+ * matching the text path's posture: inbound calls are denied, outbound setup
+ * aborts.
  */
 
 import type { AdmissionPolicy, TrustVerdict } from "@vellumai/gateway-client";
 
 import { getPendingSession } from "../channels/gateway-verification-sessions.js";
 import { getConfig } from "../config/loader.js";
-import {
-  type ActorTrustContext,
-  resolveActorTrust,
-} from "../runtime/actor-trust-resolver.js";
+import type { ActorTrustContext } from "../runtime/actor-trust-resolver.js";
 import { DAEMON_INTERNAL_ASSISTANT_ID } from "../runtime/assistant-scope.js";
 import {
   type AdmissionPolicyResult,
@@ -21,11 +23,15 @@ import {
 } from "../runtime/routes/inbound-stages/admission-policy.js";
 import {
   actorTrustContextFromVerdict,
-  verdictMemberUnresolvable,
+  verdictUsability,
 } from "../runtime/trust-verdict-consumer.js";
 import { getLogger } from "../util/logger.js";
 import { getActiveVoiceInvite } from "./gateway-invite-reader.js";
 import type { CallSession } from "./types.js";
+import {
+  TRUST_UNAVAILABLE_DENY_MESSAGE,
+  unresolvedActorTrust,
+} from "./unresolved-caller-trust.js";
 
 const log = getLogger("call-setup-router");
 
@@ -44,9 +50,9 @@ interface SetupContext {
    */
   admissionPolicy?: AdmissionPolicy | null;
   /**
-   * Gateway-stamped caller trust verdict. When present and not
-   * `resolutionFailed`, the caller's trust is built from it; otherwise the
-   * router falls back to local resolution.
+   * Gateway-stamped caller trust verdict — the sole caller-trust source.
+   * A missing/failed/member-unresolvable verdict fails closed (inbound deny,
+   * outbound setup abort).
    */
   verdict?: TrustVerdict | null;
 }
@@ -122,32 +128,44 @@ export async function routeSetup(ctx: SetupContext): Promise<{
   const isInbound = ctx.session?.initiatedFromConversationId == null;
   const otherPartyNumber = isInbound ? ctx.from : ctx.to;
 
-  // Verdict-first: build caller trust from the gateway verdict when present.
-  // Voice falls back to local resolution on a missing/failed verdict so a
-  // gateway blip does not drop a known guardian's call — the deliberate
-  // difference from the fail-closed text path.
-  //
-  // A verdict that claims a member (contactId/channelId) but whose ACL can't be
-  // reassembled (malformed/mixed-version status·policy) also falls back to local
-  // resolution, so voice never trusts a member it cannot ACL-check. A real
-  // stranger verdict (no member identity) still takes the verdict path —
-  // memberRecord null is correct there.
-  const usable =
-    ctx.verdict &&
-    !ctx.verdict.resolutionFailed &&
-    !verdictMemberUnresolvable(ctx.verdict);
-  const actorTrust = usable
-    ? actorTrustContextFromVerdict(ctx.verdict!, {
-        sourceChannel: "phone",
-        conversationExternalId: otherPartyNumber,
-        actorDisplayName: undefined,
-      })
-    : resolveActorTrust({
+  // The gateway verdict is the sole caller-trust source; an unusable one
+  // fails closed, mirroring the text path's resolutionFailed deny
+  // (acl-enforcement.ts): inbound is denied with the unavailable copy and no
+  // stranger-lane side effects; outbound (guardian-initiated) aborts setup
+  // loudly via the transport's setup-failure teardown.
+  const usability = verdictUsability(ctx.verdict);
+  if (!usability.usable) {
+    const { reason } = usability;
+    if (!isInbound) {
+      throw new Error(
+        `Voice setup: caller trust verdict unavailable (${reason}) — aborting outbound setup`,
+      );
+    }
+    log.warn(
+      { callSessionId: ctx.callSessionId, from: ctx.from, reason },
+      "Inbound voice ACL: trust verdict unavailable — denying fail-closed",
+    );
+    return {
+      outcome: {
+        action: "deny",
+        message: TRUST_UNAVAILABLE_DENY_MESSAGE,
+        logReason: `Inbound voice ACL: trust verdict unavailable (${reason}) — fail-closed deny`,
+      },
+      resolved: {
         assistantId,
-        sourceChannel: "phone",
-        conversationExternalId: otherPartyNumber,
-        actorExternalId: otherPartyNumber || undefined,
-      });
+        isInbound,
+        otherPartyNumber,
+        actorTrust: unresolvedActorTrust(otherPartyNumber),
+      },
+    };
+  }
+
+  const { verdict } = usability;
+  const actorTrust = actorTrustContextFromVerdict(verdict, {
+    sourceChannel: "phone",
+    conversationExternalId: otherPartyNumber,
+    actorDisplayName: undefined,
+  });
 
   const resolved: SetupResolved = {
     assistantId,
@@ -233,14 +251,20 @@ export async function routeSetup(ctx: SetupContext): Promise<{
   // ── Inbound call ACL evaluation ─────────────────────────────────
   // Gateway read; throws on transport failure (control-plane posture —
   // setup fails loudly rather than mis-routing past a pending challenge).
-  const pendingChallenge = await getPendingSession("phone");
+  // Skipped when the verdict stamps `hasInterceptableVerificationSession:
+  // false` — the channel-scoped stamp is authoritative only as a negative
+  // (same rule as the text path); `true`/absent falls back to the read.
+  const pendingChallenge =
+    verdict.hasInterceptableVerificationSession === false
+      ? null
+      : await getPendingSession("phone");
 
   // An admission floor is "active" only when a policy applies and no pending
   // verification challenge is in flight. While active, the floor IS the access
   // decision: an admitted caller bypasses the legacy identity flows
   // (unverified_caller / name_capture) and connects directly. When inactive
-  // (null policy, flag off, exempt channel, reader failed open, or a pending
-  // challenge), those legacy flows are preserved unchanged.
+  // (null policy, flag off, exempt channel, or a pending challenge), those
+  // legacy flows are preserved unchanged.
   const floorActive = ctx.admissionPolicy != null && !pendingChallenge;
 
   // Inbound admission floor verdict; defaults to admitted when inactive.

package/src/calls/call-speech-output.ts

@@ -15,7 +15,7 @@
  *   via `sendPlayUrl()`.
  */
 
-import { getCatalogProvider, getTtsProvider } from "../tts/provider-catalog.js";
+import { getCatalogProvider } from "../tts/provider-catalog.js";
 import {
   type AudioStoreSink,
   createAudioStoreSink,
@@ -23,10 +23,12 @@ import {
 } from "../tts/synthesis-stream.js";
 import type { TtsProvider, TtsProviderId } from "../tts/types.js";
 import { getLogger } from "../util/logger.js";
+import type { CallAudioFormat } from "./audio-store.js";
 import type { CallTransport } from "./call-transport.js";
 import {
-  findPlayableTelephonyTtsFallback,
+  findPlayableTelephonyTtsFallbackProvider,
   resolveCallTtsProvider,
+  resolveSynthesisFormats,
 } from "./resolve-call-tts-provider.js";
 
 const log = getLogger("call-speech-output");
@@ -56,13 +58,13 @@ export async function speakSystemPrompt(
   text: string,
   signal?: AbortSignal,
 ): Promise<void> {
-  // When the transport requires WAV (media-stream), request WAV so
-  // the audio store entry contains PCM that audioBufferToFrames can
+  // When the transport requires PCM (media-stream), request PCM so
+  // the audio store entry contains raw PCM that audioBufferToFrames can
   // transcode to mu-law. Without this, compressed formats (mp3, opus)
   // are fetched by processFetchUrlItem and produce garbled audio.
   const { provider, useSynthesizedPath, audioFormat } =
     await resolveCallTtsProvider({
-      preferWav: relay.requiresWavAudio,
+      requiresPcmAudio: relay.requiresPcmAudio,
     });
 
   if (!useSynthesizedPath || !provider) {
@@ -83,14 +85,20 @@ export async function speakSystemPrompt(
  * Synthesize text via a streaming TTS provider and send the play URL
  * to the transport.
  *
- * On synthesis failure the behavior depends on the transport:
- * - WAV-requiring transports (media-stream) retry once with a playable
+ * A failure after the play URL has gone out (streaming provider died
+ * mid-stream) sends only the end-of-turn signal on every transport: the
+ * caller already heard the truncated prompt, and any fallback would
+ * re-speak it in full.
+ *
+ * On synthesis failure before any audio the behavior depends on the
+ * transport:
+ * - PCM-requiring transports (media-stream) retry once with a playable
  *   fallback provider — native token TTS cannot rescue the prompt there
  *   because text tokens are themselves synthesized via the same provider
  *   path. When no fallback exists (or the retry also fails), only an
  *   empty end-of-turn signal is sent so the transport transitions back
  *   to listening state.
- * - On non-WAV transports, providers with a native Twilio TTS fallback
+ * - On non-PCM transports, providers with a native Twilio TTS fallback
  *   (e.g. Fish Audio) fall back to `sendTextToken(text)` so the caller
  *   still hears the message; providers without one (e.g. Deepgram) log
  *   the error and send only the end-of-turn signal.
@@ -104,27 +112,20 @@ async function synthesizeAndPlay(
   relay: CallTransport,
   provider: TtsProvider,
   text: string,
-  format: "mp3" | "wav" | "opus",
+  format: CallAudioFormat,
   signal?: AbortSignal,
   isFallbackRetry = false,
 ): Promise<void> {
   let sink: AudioStoreSink | null = null;
+  let playUrlSent = false;
   try {
-    // When format is WAV (media-stream transport), request raw PCM from
-    // the provider so the audio bytes match the store's content-type.
-    // Without this, providers like Fish Audio still return mp3 and the
-    // downstream mu-law transcoder fails on the format mismatch.
-    const outputFormat = format === "wav" ? ("pcm" as const) : undefined;
-
-    // Use "pcm" as the store format when requesting PCM output so the
-    // audio store entry's content-type (audio/pcm) matches the raw PCM
-    // bytes providers return. Without this, the store says "audio/wav"
-    // but the bytes have no RIFF header, causing audioBufferToFrames to
-    // fall through to the wrong decode path.
-    const storeFormat = outputFormat ? "pcm" : format;
+    const { outputFormat, storeFormat } = resolveSynthesisFormats(format);
     sink = createAudioStoreSink({
       format: storeFormat,
-      onPlayUrl: (url) => relay.sendPlayUrl(url),
+      onPlayUrl: (url) => {
+        relay.sendPlayUrl(url);
+        playUrlSent = true;
+      },
     });
 
     const result = await synthesizeAndEmit({
@@ -177,17 +178,25 @@ async function synthesizeAndPlay(
         ? (err as Error & { code?: string }).code
         : undefined;
 
-    if (relay.requiresWavAudio) {
-      // WAV-requiring transport (media-stream): native token TTS routes
+    // The caller already heard the truncated prompt — any fallback would
+    // re-speak it in full (mirrors call-controller's failed-after-audio).
+    if (playUrlSent) {
+      log.warn(
+        { err, provider: provider.id, errName, errCode },
+        "System prompt TTS synthesis failed after audio started — skipping fallback to avoid re-speaking the prompt",
+      );
+      relay.sendTextToken("", true);
+      return;
+    }
+
+    if (relay.requiresPcmAudio) {
+      // PCM-requiring transport (media-stream): native token TTS routes
       // back through the same synthesis path, so retry once with a
       // playable fallback provider before degrading to end-of-turn only.
       if (!isFallbackRetry) {
-        const fallbackId = await findPlayableTelephonyTtsFallback(
-          provider.id as TtsProviderId,
+        const fallbackProvider = await findPlayableTelephonyTtsFallbackProvider(
+          provider.id,
         );
-        const fallbackProvider = fallbackId
-          ? lookupRegisteredProvider(fallbackId)
-          : null;
         if (fallbackProvider) {
           log.warn(
             {
@@ -213,7 +222,7 @@ async function synthesizeAndPlay(
       }
       log.error(
         { err, provider: provider.id, errName, errCode },
-        "System prompt TTS synthesis failed on WAV-requiring transport — sending end-of-turn only",
+        "System prompt TTS synthesis failed on PCM-requiring transport — sending end-of-turn only",
       );
       // Send the end-of-turn signal so the transport transitions from
       // "assistant speaking" to "caller speaking" state.
@@ -255,12 +264,3 @@ async function synthesizeAndPlay(
     sink?.finalize();
   }
 }
-
-/** Look up a registered provider, returning null instead of throwing. */
-function lookupRegisteredProvider(id: string): TtsProvider | null {
-  try {
-    return getTtsProvider(id);
-  } catch {
-    return null;
-  }
-}

package/src/calls/call-transport.ts

@@ -31,14 +31,15 @@ export interface CallTransport {
   endSession(reason?: string): void;
 
   /**
-   * When true, the transport requires WAV (PCM) audio for playback.
+   * When true, the transport synthesizes speech itself and requires raw
+   * PCM audio for playback.
    *
    * The media-stream transport sets this because its mu-law transcoder
-   * can only decode WAV (raw PCM) — compressed formats (mp3, opus)
-   * produce garbled audio. The call controller uses this to request
-   * WAV from TTS providers and the audio store.
+   * needs raw PCM — compressed formats (mp3, opus) produce garbled
+   * audio. The call controller uses this to request PCM from TTS
+   * providers and the audio store.
    */
-  readonly requiresWavAudio?: boolean;
+  readonly requiresPcmAudio?: boolean;
 
   /**
    * Arm a one-shot callback invoked when the transport sends the first
@@ -60,4 +61,15 @@ export interface CallTransport {
    * synthesis. Transports that don't buffer text may omit this.
    */
   discardPendingText?(): void;
+
+  /**
+   * Cancel queued and in-flight speech playback held by the transport,
+   * including any audio already buffered downstream (e.g. by Twilio).
+   *
+   * Called by the controller when it aborts an in-flight turn so speech
+   * the aborted turn queued for synthesis or playback never plays over
+   * the next turn. Transports that emit speech synchronously may omit
+   * this.
+   */
+  cancelPendingSpeech?(): void;
 }

package/src/calls/channel-admission-reader.ts

@@ -2,18 +2,24 @@
  * Gateway-backed channel admission policy reader.
  *
  * Reads a channel's resolved admission floor from the gateway via the
- * `get_channel_admission_policy` IPC route. Admission must never break call
- * setup, so this reader FAILS OPEN: any transport failure, malformed shape,
- * or thrown error resolves to `null` (= admit, no enforcement). A policy is
- * only returned when the gateway responds with `{ policy: <valid policy> }`.
+ * `get_channel_admission_policy` IPC route. The reader FAILS CLOSED,
+ * consistent with the text path: a gateway outage must not admit unvetted
+ * callers past the floor. Any transport failure, thrown error, or malformed
+ * shape resolves to `{ ok: false }` — the caller must DENY, not admit. A
+ * successful round-trip resolves to `{ ok: true, policy }`, where `policy:
+ * null` is the gateway's explicit "no enforcement configured" answer (still
+ * an admit) — distinct from an unreachable gateway.
+ *
+ * No production caller on the primary voice path — the combined trust-verdict
+ * read (`inbound-trust-reader.ts`) carries the policy; this reader is the
+ * version-skew fallback + standalone admission surface.
  *
  * Caches per channelType with a short TTL, mirroring the conversation
  * threshold cache in `../permissions/gateway-threshold-reader.ts`. Only the
  * result of a SUCCESSFUL gateway round-trip is cached (a valid policy, or an
- * explicit `{ policy: null }` "no enforcement" answer); a transport failure /
- * throw / malformed shape fails open to `null` WITHOUT caching, so a recovered
- * gateway is re-consulted on the next call setup rather than skipping the
- * admission floor for the rest of the TTL.
+ * explicit `{ policy: null }` "no enforcement" answer); a failure is NOT
+ * cached, so a recovered gateway is re-consulted on the next call setup
+ * rather than denying calls for the rest of the TTL.
  */
 
 import {
@@ -26,7 +32,7 @@ import { ipcCall } from "../ipc/gateway-client.js";
 
 const CACHE_TTL_MS = 5_000;
 
-// Short IPC timeout so admission fails open PROMPTLY: a gateway that accepts
+// Short IPC timeout so admission fails closed PROMPTLY: a gateway that accepts
 // the socket but stalls must never delay a live call handshake. 1s is generous
 // under normal conditions yet far below ipcCall's 5s default.
 const ADMISSION_IPC_TIMEOUT_MS = 1_000;
@@ -42,34 +48,38 @@ export function _clearCacheForTesting(): void {
 }
 
 /**
- * Outcome of a single gateway fetch. Only a SUCCESSFUL round-trip (a valid
- * policy, or an explicit `{ policy: null }` "no enforcement" answer) is
- * cacheable. A transport failure, thrown error, or malformed shape is NOT
- * cached so a recovered gateway is re-consulted on the next call setup.
+ * Result of an admission-policy read. `{ ok: false }` means the gateway was
+ * unreachable or answered with a malformed shape — the caller must deny.
+ * `{ ok: true, policy: null }` is the gateway's explicit "no enforcement
+ * configured" answer, which admits.
  */
-type FetchResult =
+export type AdmissionPolicyReadResult =
   | { ok: true; policy: AdmissionPolicy | null }
   | { ok: false };
 
 async function fetchAdmissionPolicy(
   channelType: ChannelId,
-): Promise<FetchResult> {
+): Promise<AdmissionPolicyReadResult> {
   try {
     // ipcCall() returns undefined on transport failure (socket not found,
     // timeout, parse error). That, a throw, or a malformed shape is a FAILURE:
-    // fail open without caching so the next setup re-attempts the IPC.
+    // fail closed without caching so the next setup re-attempts the IPC.
     const result = (await ipcCall(
       "get_channel_admission_policy",
       { channelType },
       ADMISSION_IPC_TIMEOUT_MS,
     )) as { policy?: unknown } | null | undefined;
 
-    if (result === undefined) return { ok: false };
+    if (result === undefined) {
+      return { ok: false };
+    }
     if (result && isAdmissionPolicy(result.policy)) {
       return { ok: true, policy: result.policy };
     }
     // Explicit "no enforcement" — the gateway successfully answered. Cacheable.
-    if (result && result.policy === null) return { ok: true, policy: null };
+    if (result && result.policy === null) {
+      return { ok: true, policy: null };
+    }
     // Anything else (missing/invalid policy field) is a malformed shape.
     return { ok: false };
   } catch {
@@ -78,27 +88,27 @@ async function fetchAdmissionPolicy(
 }
 
 /**
- * Resolve a channel's admission policy from the gateway, or `null` on any
- * failure / absence. `null` means admit with no enforcement.
+ * Resolve a channel's admission policy from the gateway.
  *
- * Always fails open to `null` on failure, but only caches the result of a
- * SUCCESSFUL gateway round-trip — a transient hiccup must not skip the
- * admission floor for the rest of the TTL.
+ * Fails closed: `{ ok: false }` on any transport failure / malformed shape,
+ * and the caller must deny. Only the result of a SUCCESSFUL gateway
+ * round-trip is cached — a transient hiccup must not deny (or admit) for the
+ * rest of the TTL.
  */
 export async function getChannelAdmissionPolicy(
   channelType: ChannelId,
-): Promise<AdmissionPolicy | null> {
+): Promise<AdmissionPolicyReadResult> {
   const cached = cache.get(channelType);
   if (cached && Date.now() - cached.timestamp < CACHE_TTL_MS) {
-    return cached.policy;
+    return { ok: true, policy: cached.policy };
   }
 
   const result = await fetchAdmissionPolicy(channelType);
   if (!result.ok) {
-    // Fail open WITHOUT caching so a recovered gateway is re-consulted next time.
-    return null;
+    // Never cached: a recovered gateway is re-consulted on the next setup.
+    return result;
   }
 
   cache.set(channelType, { policy: result.policy, timestamp: Date.now() });
-  return result.policy;
+  return result;
 }

package/src/calls/fish-audio-client.ts

@@ -1,15 +1,19 @@
 import type { FishAudioConfig } from "../config/schemas/fish-audio.js";
 import { credentialKey } from "../security/credential-key.js";
 import { getSecureKeyAsync } from "../security/secure-keys.js";
+import { consumeSynthesisResponse } from "../tts/stream-read.js";
 import { getLogger } from "../util/logger.js";
 
 const log = getLogger("fish-audio-client");
 
-/** Timeout waiting for the first chunk from Fish Audio (ms). */
-const FIRST_CHUNK_TIMEOUT_MS = 10_000;
-
-/** Timeout waiting between consecutive chunks (ms). */
-const IDLE_TIMEOUT_MS = 5_000;
+/**
+ * Config accepted by the synthesis client. Widens the user-facing format
+ * union with `"pcm"` (raw 16-bit LE, no container), which PCM-requesting
+ * callers substitute internally — it is not part of the config schema.
+ */
+export type FishAudioSynthesisConfig = Omit<FishAudioConfig, "format"> & {
+  format: FishAudioConfig["format"] | "pcm";
+};
 
 // ---------------------------------------------------------------------------
 // Fish Audio REST API (POST /v1/tts)
@@ -32,7 +36,7 @@ interface SynthesizeOptions {
  */
 export async function synthesizeWithFishAudio(
   text: string,
-  config: FishAudioConfig,
+  config: FishAudioSynthesisConfig,
   options?: SynthesizeOptions,
 ): Promise<Buffer> {
   const apiKey = await getSecureKeyAsync(
@@ -82,51 +86,19 @@ export async function synthesizeWithFishAudio(
     throw new Error(`Fish Audio API error (${response.status}): ${errorText}`);
   }
 
-  if (!response.body) {
-    throw new Error("Fish Audio API returned no body");
-  }
-
-  const chunks: Uint8Array[] = [];
-  const reader = response.body.getReader();
-  let isFirstChunk = true;
-
-  try {
-    while (true) {
-      const timeoutMs = isFirstChunk ? FIRST_CHUNK_TIMEOUT_MS : IDLE_TIMEOUT_MS;
-      let timerId: ReturnType<typeof setTimeout>;
-      const timeout = new Promise<never>((_, reject) => {
-        timerId = setTimeout(
-          () => reject(new Error(`Fish Audio read timed out after ${timeoutMs}ms`)),
-          timeoutMs,
-        );
-      });
-      let done: boolean;
-      let value: Uint8Array | undefined;
-      try {
-        ({ done, value } = await Promise.race([reader.read(), timeout]));
-      } finally {
-        clearTimeout(timerId!);
-      }
-      if (done) break;
-      if (value) {
-        isFirstChunk = false;
-        chunks.push(value);
-        options?.onChunk?.(value);
-      }
-    }
-  } catch (err) {
-    try { await reader.cancel(); } catch { /* Ignore cancellation errors */ }
-    throw err;
-  }
-
-  const totalLength = chunks.reduce((sum, c) => sum + c.byteLength, 0);
-  const merged = new Uint8Array(totalLength);
-  let offset = 0;
-  for (const chunk of chunks) {
-    merged.set(chunk, offset);
-    offset += chunk.byteLength;
-  }
+  const audio = await consumeSynthesisResponse(response, {
+    stream: true,
+    onChunk: options?.onChunk,
+    makeTimeoutError: (timeoutMs) =>
+      new Error(`Fish Audio read timed out after ${timeoutMs}ms`),
+    makeEmptyError: (kind) =>
+      new Error(
+        kind === "no-body"
+          ? "Fish Audio API returned no body"
+          : "Fish Audio API returned empty audio",
+      ),
+  });
 
-  log.debug({ bytes: totalLength }, "Fish Audio synthesis complete");
-  return Buffer.from(merged);
+  log.debug({ bytes: audio.byteLength }, "Fish Audio synthesis complete");
+  return audio;
 }

package/src/calls/gateway-invite-reader.ts

@@ -11,14 +11,21 @@
  * - Redemption fails CLOSED — any IPC failure is the generic
  *   `invalid_or_expired` outcome. There is no local fallback: the gateway
  *   row is the single lifecycle authority for voice invites.
+ *
+ * Deliberately NOT built on `channels/gateway-invites.ts` /
+ * `ipcCallPersistentValidated`: this is the hot call-setup path, so it uses
+ * one-shot `ipcCall` with explicit per-operation timeouts and the fail
+ * postures above instead of the persistent throw-fail-closed client the
+ * control-plane relays share.
  */
 
 import {
   type ActiveVoiceInvite,
-  ActiveVoiceInviteSchema,
-  InviteRedemptionOutcomeSchema,
+  GetActiveVoiceInviteIpcResponseSchema,
+  INVITES_IPC_METHODS,
+  type RedeemVoiceInviteIpcResponse,
+  RedeemVoiceInviteIpcResponseSchema,
 } from "@vellumai/gateway-client";
-import { z } from "zod";
 
 import { ipcCall } from "../ipc/gateway-client.js";
 
@@ -29,18 +36,7 @@ const DETECTION_IPC_TIMEOUT_MS = 2_000;
 // headroom — a timeout still fails closed.
 const REDEMPTION_IPC_TIMEOUT_MS = 10_000;
 
-const GetActiveVoiceInviteResponseSchema = z.object({
-  invite: ActiveVoiceInviteSchema.nullable(),
-});
-
-const RedeemVoiceInviteResponseSchema = z.discriminatedUnion("ok", [
-  z.object({ ok: z.literal(true), outcome: InviteRedemptionOutcomeSchema }),
-  z.object({ ok: z.literal(false), reason: z.literal("invalid_or_expired") }),
-]);
-
-export type GatewayVoiceRedemptionResult = z.infer<
-  typeof RedeemVoiceInviteResponseSchema
->;
+export type GatewayVoiceRedemptionResult = RedeemVoiceInviteIpcResponse;
 
 const REDEMPTION_FAILURE: GatewayVoiceRedemptionResult = {
   ok: false,
@@ -59,11 +55,11 @@ export async function getActiveVoiceInvite(
   }
   try {
     const result = await ipcCall(
-      "get_active_voice_invite",
+      INVITES_IPC_METHODS.getActiveVoiceInvite,
       { callerExternalUserId: fromNumber },
       DETECTION_IPC_TIMEOUT_MS,
     );
-    const parsed = GetActiveVoiceInviteResponseSchema.safeParse(result);
+    const parsed = GetActiveVoiceInviteIpcResponseSchema.safeParse(result);
     if (!parsed.success) {
       return null;
     }
@@ -83,11 +79,11 @@ export async function redeemVoiceInviteViaGateway(
 ): Promise<GatewayVoiceRedemptionResult> {
   try {
     const result = await ipcCall(
-      "redeem_voice_invite",
+      INVITES_IPC_METHODS.redeemVoiceInvite,
       { callerExternalUserId: fromNumber, code },
       REDEMPTION_IPC_TIMEOUT_MS,
     );
-    const parsed = RedeemVoiceInviteResponseSchema.safeParse(result);
+    const parsed = RedeemVoiceInviteIpcResponseSchema.safeParse(result);
     if (!parsed.success) {
       return REDEMPTION_FAILURE;
     }