@vellumai/assistant 0.4.23 → 0.4.25

package/src/__tests__/session-runtime-assembly.test.ts

@@ -44,6 +44,14 @@ describe("resolveChannelCapabilities", () => {
     expect(caps.supportsVoiceInput).toBe(true);
   });
 
+  test("vellum channel with vellum interface supports dynamic UI", () => {
+    const caps = resolveChannelCapabilities("vellum", "vellum");
+    expect(caps.channel).toBe("vellum");
+    expect(caps.dashboardCapable).toBe(false);
+    expect(caps.supportsDynamicUi).toBe(true);
+    expect(caps.supportsVoiceInput).toBe(false);
+  });
+
   test("defaults to vellum for null source channel", () => {
     const caps = resolveChannelCapabilities(null);
     expect(caps.channel).toBe("vellum");
@@ -407,6 +415,24 @@ describe("trust-gating via channel capabilities", () => {
     expect(injected).toContain("Present information as well-formatted text");
     expect(injected).toContain("desktop app");
   });
+
+  test("vellum web interface allows dynamic UI but constrains dashboard references", () => {
+    const caps = resolveChannelCapabilities("vellum", "vellum");
+    const message: Message = {
+      role: "user",
+      content: [{ type: "text", text: "Show me a form" }],
+    };
+
+    const result = injectChannelCapabilityContext(message, caps);
+    const injected = (result.content[0] as { type: "text"; text: string }).text;
+
+    expect(injected).toContain("CHANNEL CONSTRAINTS");
+    expect(injected).toContain("Do NOT reference the dashboard UI");
+    expect(injected).not.toContain("Do NOT use ui_show");
+    expect(injected).not.toContain("Present information as well-formatted text");
+    expect(injected).toContain("supports_dynamic_ui: true");
+    expect(injected).toContain("dashboard_capable: false");
+  });
 });
 
 // ---------------------------------------------------------------------------
@@ -994,12 +1020,12 @@ describe("sanitizePttActivationKey", () => {
     expect(sanitizePttActivationKey("none")).toBe("none");
   });
 
-  test('returns "unknown" for invalid keys', () => {
-    expect(sanitizePttActivationKey("malicious\nprompt injection")).toBe(
-      "unknown",
-    );
-    expect(sanitizePttActivationKey("arbitrary_value")).toBe("unknown");
-    expect(sanitizePttActivationKey("")).toBe("unknown");
+  test("returns undefined for invalid keys", () => {
+    expect(
+      sanitizePttActivationKey("malicious\nprompt injection"),
+    ).toBeUndefined();
+    expect(sanitizePttActivationKey("arbitrary_value")).toBeUndefined();
+    expect(sanitizePttActivationKey("")).toBeUndefined();
   });
 });
 
@@ -1015,11 +1041,11 @@ describe("resolveChannelCapabilities with PTT metadata", () => {
     expect(caps.pttActivationKey).toBe("fn");
   });
 
-  test("sanitizes invalid pttActivationKey to unknown", () => {
+  test("sanitizes invalid pttActivationKey to undefined", () => {
     const caps = resolveChannelCapabilities("macos", "macos", {
       pttActivationKey: "evil\nprompt",
     });
-    expect(caps.pttActivationKey).toBe("unknown");
+    expect(caps.pttActivationKey).toBeUndefined();
   });
 
   test("passes through microphonePermissionGranted", () => {

package/src/__tests__/system-prompt.test.ts

@@ -75,9 +75,15 @@ const {
   buildPhoneCallsRoutingSection,
 } = await import("../config/system-prompt.js");
 
-/** Strip the Configuration and Skills sections so base-prompt tests stay focused. */
+/** Strip the Configuration, Skills, and hardcoded preamble sections so base-prompt tests stay focused. */
 function basePrompt(result: string): string {
   let s = result;
+  // Strip the hardcoded em-dash instruction preamble
+  const emDashLine =
+    "IMPORTANT: Never use em dashes (\u2014) in your messages. Use commas, periods, or just start a new sentence instead.";
+  if (s.startsWith(emDashLine)) {
+    s = s.slice(emDashLine.length).replace(/^\n\n/, "");
+  }
   for (const heading of [
     "## Configuration",
     "## Skills Catalog",

package/src/__tests__/trusted-contact-approval-notifier.test.ts

@@ -120,8 +120,14 @@ mock.module("../config/env.js", () => ({
   getGatewayInternalBaseUrl: () => "http://localhost:3000",
 }));
 
+// ── User reference mock ──
+mock.module("../config/user-reference.js", () => ({
+  resolveUserReference: () => "my human",
+}));
+
 // Import module under test AFTER mocks are set up
 import type { ChannelId } from "../channels/types.js";
+import { resolveUserReference } from "../config/user-reference.js";
 import type { GuardianContext } from "../runtime/guardian-context-resolver.js";
 
 // We need to test the private functions by importing the module.
@@ -220,9 +226,7 @@ async function simulateNotifierPoll(params: {
     }
   }
 
-  const waitingText = guardianName
-    ? `Waiting for ${guardianName}'s approval...`
-    : "Waiting for your guardian's approval...";
+  const waitingText = `Waiting for ${guardianName ?? resolveUserReference()}'s approval...`;
 
   try {
     await deliverChannelReply(
@@ -330,7 +334,7 @@ describe("trusted-contact pending-approval notifier", () => {
     );
   });
 
-  test("uses generic phrasing when no guardian name is available", async () => {
+  test("falls back to user reference when no guardian name is available", async () => {
     mockPendingApprovals = [
       {
         requestId: "req-3",
@@ -359,11 +363,11 @@ describe("trusted-contact pending-approval notifier", () => {
 
     expect(deliveredReplies).toHaveLength(1);
     expect(deliveredReplies[0].payload.text).toBe(
-      "Waiting for your guardian's approval...",
+      "Waiting for my human's approval...",
     );
   });
 
-  test("uses generic phrasing when no guardian binding exists", async () => {
+  test("falls back to user reference when no guardian binding exists", async () => {
     mockPendingApprovals = [
       {
         requestId: "req-4",
@@ -388,7 +392,7 @@ describe("trusted-contact pending-approval notifier", () => {
 
     expect(deliveredReplies).toHaveLength(1);
     expect(deliveredReplies[0].payload.text).toBe(
-      "Waiting for your guardian's approval...",
+      "Waiting for my human's approval...",
     );
   });
 
@@ -736,7 +740,7 @@ describe("trusted-contact pending-approval notifier", () => {
     expect(deliveredReplies).toHaveLength(1);
     // Falls back to generic phrasing
     expect(deliveredReplies[0].payload.text).toBe(
-      "Waiting for your guardian's approval...",
+      "Waiting for my human's approval...",
     );
   });
 });

package/src/__tests__/twilio-routes-twiml.test.ts

@@ -46,7 +46,7 @@ describe("generateTwiML with voice quality profile", () => {
     expect(twiml).toContain('voice="voice123-turbo_v2_5-1_0.5_0.75"');
   });
 
-  test("voice attribute reflects configured voice for twilio_standard mode", () => {
+  test("voice attribute reflects configured Google voice", () => {
     const twiml = generateTwiML(callSessionId, relayUrl, welcomeGreeting, {
       language: "en-US",
       transcriptionProvider: "Deepgram",
@@ -57,7 +57,7 @@ describe("generateTwiML with voice quality profile", () => {
     expect(twiml).toContain('voice="Google.en-US-Journey-O"');
   });
 
-  test("voice attribute reflects configured voice for twilio_elevenlabs_tts mode", () => {
+  test("voice attribute reflects configured ElevenLabs voice", () => {
     const twiml = generateTwiML(callSessionId, relayUrl, welcomeGreeting, {
       language: "en-US",
       transcriptionProvider: "Deepgram",

package/src/__tests__/twilio-routes.test.ts

@@ -60,13 +60,12 @@ const mockConfigObj = {
   memory: { enabled: false },
   rateLimit: { maxRequestsPerMinute: 0, maxTokensPerSession: 0 },
   secretDetection: { enabled: false },
+  elevenlabs: { voiceId: "21m00Tcm4TlvDq8ikWAM" },
   calls: {
     voice: {
-      mode: "twilio_standard",
       language: "en-US",
       transcriptionProvider: "Deepgram",
-      fallbackToStandardOnError: true,
-      elevenlabs: { voiceId: "" },
+      elevenlabs: {},
     },
   },
 };

package/src/__tests__/voice-quality.test.ts

@@ -8,7 +8,6 @@ mock.module("../config/loader.js", () => ({
 
 import {
   buildElevenLabsVoiceSpec,
-  isVoiceProfileValid,
   resolveVoiceQualityProfile,
 } from "../calls/voice-quality.js";
 
@@ -62,176 +61,66 @@ describe("buildElevenLabsVoiceSpec", () => {
 });
 
 describe("resolveVoiceQualityProfile", () => {
-  test("returns standard profile for twilio_standard mode", () => {
+  test("always returns ElevenLabs ttsProvider", () => {
     mockConfig = {
+      elevenlabs: { voiceId: "21m00Tcm4TlvDq8ikWAM" },
       calls: {
         voice: {
-          mode: "twilio_standard",
           language: "en-US",
-          transcriptionProvider: "Google",
-          fallbackToStandardOnError: false,
-          elevenlabs: {},
-        },
-      },
-    };
-    const profile = resolveVoiceQualityProfile();
-    expect(profile.mode).toBe("twilio_standard");
-    expect(profile.ttsProvider).toBe("Google");
-    expect(profile.voice).toBe("Google.en-US-Journey-O");
-    expect(profile.validationErrors).toHaveLength(0);
-  });
-
-  test("returns elevenlabs profile for twilio_elevenlabs_tts mode", () => {
-    mockConfig = {
-      calls: {
-        voice: {
-          mode: "twilio_elevenlabs_tts",
-          language: "en-US",
-          transcriptionProvider: "Google",
-          fallbackToStandardOnError: false,
-          elevenlabs: { voiceId: "elvoice1" },
+          transcriptionProvider: "Deepgram",
         },
       },
     };
     const profile = resolveVoiceQualityProfile();
-    expect(profile.mode).toBe("twilio_elevenlabs_tts");
     expect(profile.ttsProvider).toBe("ElevenLabs");
-    expect(profile.voice).toBe("elvoice1");
-    expect(profile.validationErrors).toHaveLength(0);
-  });
-
-  test("falls back to standard when voiceId missing and fallback enabled", () => {
-    mockConfig = {
-      calls: {
-        voice: {
-          mode: "twilio_elevenlabs_tts",
-          language: "en-US",
-          transcriptionProvider: "Google",
-          fallbackToStandardOnError: true,
-          elevenlabs: { voiceId: "" },
-        },
-      },
-    };
-    const profile = resolveVoiceQualityProfile();
-    expect(profile.mode).toBe("twilio_standard");
-    expect(profile.validationErrors.length).toBeGreaterThan(0);
-    expect(profile.validationErrors[0]).toContain("falling back");
-  });
-
-  test("returns validation error when voiceId missing and fallback disabled", () => {
-    mockConfig = {
-      calls: {
-        voice: {
-          mode: "twilio_elevenlabs_tts",
-          language: "en-US",
-          transcriptionProvider: "Google",
-          fallbackToStandardOnError: false,
-          elevenlabs: { voiceId: "" },
-        },
-      },
-    };
-    const profile = resolveVoiceQualityProfile();
-    expect(profile.mode).toBe("twilio_elevenlabs_tts");
-    expect(profile.validationErrors.length).toBeGreaterThan(0);
-    expect(profile.validationErrors[0]).toContain("voiceId is required");
   });
 
-  test("returns elevenlabs_agent profile with agentId", () => {
+  test("voice ID comes from elevenlabs.voiceId", () => {
     mockConfig = {
+      elevenlabs: { voiceId: "custom-voice-123" },
       calls: {
         voice: {
-          mode: "elevenlabs_agent",
           language: "en-US",
-          transcriptionProvider: "Google",
-          fallbackToStandardOnError: false,
-          elevenlabs: { voiceId: "voice1", agentId: "agent123" },
+          transcriptionProvider: "Deepgram",
         },
       },
     };
     const profile = resolveVoiceQualityProfile();
-    expect(profile.mode).toBe("elevenlabs_agent");
-    expect(profile.agentId).toBe("agent123");
-    expect(profile.validationErrors).toHaveLength(0);
+    expect(profile.voice).toBe("custom-voice-123");
   });
 
-  test("falls back to standard when agentId missing and fallback enabled", () => {
+  test("uses language from calls.voice config", () => {
     mockConfig = {
+      elevenlabs: { voiceId: "abc" },
       calls: {
         voice: {
-          mode: "elevenlabs_agent",
-          language: "en-US",
+          language: "es-MX",
           transcriptionProvider: "Google",
-          fallbackToStandardOnError: true,
-          elevenlabs: { voiceId: "voice1", agentId: "" },
         },
       },
     };
     const profile = resolveVoiceQualityProfile();
-    expect(profile.mode).toBe("twilio_standard");
-    expect(profile.validationErrors[0]).toContain("falling back");
+    expect(profile.language).toBe("es-MX");
+    expect(profile.transcriptionProvider).toBe("Google");
   });
 
-  test("returns validation error when agentId missing and fallback disabled", () => {
+  test("builds voice spec with model and tuning params", () => {
     mockConfig = {
-      calls: {
-        voice: {
-          mode: "elevenlabs_agent",
-          language: "en-US",
-          transcriptionProvider: "Google",
-          fallbackToStandardOnError: false,
-          elevenlabs: { voiceId: "voice1", agentId: "" },
-        },
+      elevenlabs: {
+        voiceId: "voice1",
+        voiceModelId: "turbo_v2_5",
+        speed: 0.9,
+        stability: 0.8,
+        similarityBoost: 0.9,
       },
-    };
-    const profile = resolveVoiceQualityProfile();
-    expect(profile.mode).toBe("elevenlabs_agent");
-    expect(profile.validationErrors.length).toBeGreaterThan(0);
-    expect(profile.validationErrors[0]).toContain("agentId is required");
-  });
-
-  test("returns standard profile for unknown mode", () => {
-    mockConfig = {
       calls: {
         voice: {
-          mode: "unknown_mode",
           language: "en-US",
-          transcriptionProvider: "Google",
-          fallbackToStandardOnError: false,
-          elevenlabs: {},
+          transcriptionProvider: "Deepgram",
         },
       },
     };
     const profile = resolveVoiceQualityProfile();
-    expect(profile.mode).toBe("twilio_standard");
-  });
-});
-
-describe("isVoiceProfileValid", () => {
-  test("returns true for profile with no errors", () => {
-    expect(
-      isVoiceProfileValid({
-        mode: "twilio_standard",
-        language: "en-US",
-        transcriptionProvider: "Google",
-        ttsProvider: "Google",
-        voice: "Google.en-US-Journey-O",
-        fallbackToStandardOnError: false,
-        validationErrors: [],
-      }),
-    ).toBe(true);
-  });
-
-  test("returns false for profile with errors", () => {
-    expect(
-      isVoiceProfileValid({
-        mode: "twilio_elevenlabs_tts",
-        language: "en-US",
-        transcriptionProvider: "Google",
-        ttsProvider: "ElevenLabs",
-        voice: "",
-        fallbackToStandardOnError: false,
-        validationErrors: ["voiceId is required"],
-      }),
-    ).toBe(false);
+    expect(profile.voice).toBe("voice1-turbo_v2_5-0.9_0.8_0.9");
   });
 });

package/src/calls/relay-server.ts

@@ -11,6 +11,7 @@ import { randomInt } from 'node:crypto';
 import type { ServerWebSocket } from 'bun';
 
 import { getConfig } from '../config/loader.js';
+import { resolveUserReference } from '../config/user-reference.js';
 import { getAssistantName } from '../daemon/identity-helpers.js';
 import { getCanonicalGuardianRequest } from '../memory/canonical-guardian-store.js';
 import { listActiveBindingsByAssistant } from '../memory/channel-guardian-store.js';
@@ -1214,10 +1215,14 @@ export class RelayConnection {
 
     updateCallSession(this.callSessionId, { status: 'waiting_on_user' });
 
-    // Start the heartbeat timer for periodic progress updates
-    this.accessRequestWaitStartedAt = Date.now();
+    // Start the heartbeat timer for periodic progress updates.
+    // Delay the first heartbeat by the estimated TTS playback duration so
+    // the initial hold message finishes before any heartbeat fires.
     this.heartbeatSequence = 0;
-    this.scheduleNextHeartbeat();
+    this.accessRequestHeartbeatTimer = setTimeout(() => {
+      this.accessRequestWaitStartedAt = Date.now();
+      this.scheduleNextHeartbeat();
+    }, getTtsPlaybackDelayMs());
 
     // Poll the canonical request status
     this.accessRequestPollTimer = setInterval(() => {
@@ -1658,7 +1663,7 @@ export class RelayConnection {
   /**
    * Resolve a human-readable guardian label for voice wait copy.
    * Prefers displayName from the guardian binding metadata, falls back
-   * to @username, then "my guardian".
+   * to @username, then the user's preferred name from USER.md.
    */
   private resolveGuardianLabel(): string {
     const assistantId = this.accessRequestAssistantId ?? DAEMON_INTERNAL_ASSISTANT_ID;
@@ -1690,7 +1695,8 @@ export class RelayConnection {
         // ignore malformed metadata
       }
     }
-    return 'my guardian';
+
+    return resolveUserReference();
   }
 
   /**

package/src/calls/twilio-routes.ts

@@ -29,7 +29,7 @@ import {
 } from './call-store.js';
 import { getTwilioConfig } from './twilio-config.js';
 import type { CallStatus } from './types.js';
-import { isVoiceProfileValid,resolveVoiceQualityProfile } from './voice-quality.js';
+import { resolveVoiceQualityProfile } from './voice-quality.js';
 
 const log = getLogger('twilio-routes');
 
@@ -144,7 +144,7 @@ function mapTwilioStatus(twilioStatus: string): CallStatus | null {
  * Receives the initial voice webhook when Twilio connects the call.
  * Returns TwiML XML that tells Twilio to open a ConversationRelay WebSocket.
  *
- * Supports two modes:
+ * Supports two flows:
  * - **Outbound** (callSessionId present in query): uses the existing session
  * - **Inbound** (callSessionId absent): creates or reuses a session keyed
  *   by the Twilio CallSid. Uses daemon internal scope for assistant identity.
@@ -214,43 +214,9 @@ function buildVoiceWebhookTwiml(
   task: string | null,
   guardianVerificationSessionId?: string | null,
 ): Response {
-  let profile = resolveVoiceQualityProfile(loadConfig());
+  const profile = resolveVoiceQualityProfile(loadConfig());
 
-  log.info({ callSessionId, mode: profile.mode, ttsProvider: profile.ttsProvider, voice: profile.voice }, 'Voice quality profile resolved');
-
-  if (profile.validationErrors.length > 0) {
-    log.warn({ callSessionId, errors: profile.validationErrors }, 'Voice quality profile has validation warnings');
-  }
-
-  // WS-A: Enforce strict fallback semantics — reject invalid profiles when fallback is disabled
-  if (!isVoiceProfileValid(profile)) {
-    if (!profile.fallbackToStandardOnError) {
-      const errorMsg = `Voice quality configuration error: ${profile.validationErrors.join('; ')}`;
-      log.error({ callSessionId, errors: profile.validationErrors }, errorMsg);
-      return new Response(errorMsg, { status: 500 });
-    }
-    // Fallback is enabled — profile already resolved to standard; log explicitly
-    log.info({ callSessionId }, 'Profile invalid with fallback enabled; proceeding with standard mode');
-  }
-
-  // WS-B: Guard elevenlabs_agent until consultation bridge exists.
-  // This fires BEFORE any ElevenLabs API calls, blocking the entire mode.
-  if (profile.mode === 'elevenlabs_agent') {
-    if (!profile.fallbackToStandardOnError) {
-      const msg = 'elevenlabs_agent mode is restricted: consultation bridging (waiting_on_user) is not yet supported. Set calls.voice.fallbackToStandardOnError=true to fall back to standard mode.';
-      log.error({ callSessionId }, msg);
-      return new Response(msg, { status: 501 });
-    }
-    log.warn({ callSessionId }, 'elevenlabs_agent mode is restricted/experimental — consultation bridging is not yet supported; falling back to standard ConversationRelay TwiML');
-    const standardConfig = loadConfig();
-    profile = resolveVoiceQualityProfile({
-      ...standardConfig,
-      calls: {
-        ...standardConfig.calls,
-        voice: { ...standardConfig.calls.voice, mode: 'twilio_standard' },
-      },
-    });
-  }
+  log.info({ callSessionId, ttsProvider: profile.ttsProvider, voice: profile.voice }, 'Voice quality profile resolved');
 
   const twilioConfig = getTwilioConfig();
   let relayUrl: string;

package/src/calls/voice-quality.ts

@@ -1,14 +1,10 @@
 import { loadConfig } from '../config/loader.js';
 
 export interface VoiceQualityProfile {
-  mode: 'twilio_standard' | 'twilio_elevenlabs_tts' | 'elevenlabs_agent';
   language: string;
   transcriptionProvider: string;
   ttsProvider: string;
   voice: string;
-  agentId?: string;
-  fallbackToStandardOnError: boolean;
-  validationErrors: string[];
 }
 
 /**
@@ -45,70 +41,18 @@ export function buildElevenLabsVoiceSpec(config: {
 
 /**
  * Resolve the effective voice quality profile from config.
- * Returns a profile with all resolved values ready for use by TwiML generation
- * and call orchestration.
+ *
+ * Always uses ElevenLabs TTS via Twilio ConversationRelay.
+ * The voice ID comes from the shared `elevenlabs.voiceId` config
+ * (defaults to Rachel — 21m00Tcm4TlvDq8ikWAM).
  */
 export function resolveVoiceQualityProfile(config?: ReturnType<typeof loadConfig>): VoiceQualityProfile {
   const cfg = config ?? loadConfig();
   const voice = cfg.calls.voice;
-  const errors: string[] = [];
-
-  // Default/standard profile
-  const standardProfile: VoiceQualityProfile = {
-    mode: 'twilio_standard',
+  return {
     language: voice.language,
     transcriptionProvider: voice.transcriptionProvider,
-    ttsProvider: 'Google',
-    voice: 'Google.en-US-Journey-O',
-    fallbackToStandardOnError: voice.fallbackToStandardOnError,
-    validationErrors: [],
+    ttsProvider: 'ElevenLabs',
+    voice: buildElevenLabsVoiceSpec(cfg.elevenlabs),
   };
-
-  if (voice.mode === 'twilio_standard') {
-    return standardProfile;
-  }
-
-  if (voice.mode === 'twilio_elevenlabs_tts') {
-    if (!voice.elevenlabs.voiceId && !voice.fallbackToStandardOnError) {
-      errors.push('calls.voice.elevenlabs.voiceId is required for twilio_elevenlabs_tts mode when fallback is disabled');
-    }
-    if (!voice.elevenlabs.voiceId && voice.fallbackToStandardOnError) {
-      return { ...standardProfile, validationErrors: ['calls.voice.elevenlabs.voiceId is empty; falling back to twilio_standard'] };
-    }
-    return {
-      mode: 'twilio_elevenlabs_tts',
-      language: voice.language,
-      transcriptionProvider: voice.transcriptionProvider,
-      ttsProvider: 'ElevenLabs',
-      voice: buildElevenLabsVoiceSpec(voice.elevenlabs),
-      fallbackToStandardOnError: voice.fallbackToStandardOnError,
-      validationErrors: errors,
-    };
-  }
-
-  if (voice.mode === 'elevenlabs_agent') {
-    if (!voice.elevenlabs.agentId && !voice.fallbackToStandardOnError) {
-      errors.push('calls.voice.elevenlabs.agentId is required for elevenlabs_agent mode when fallback is disabled');
-    }
-    if (!voice.elevenlabs.agentId && voice.fallbackToStandardOnError) {
-      return { ...standardProfile, validationErrors: ['calls.voice.elevenlabs.agentId is empty; falling back to twilio_standard'] };
-    }
-    return {
-      mode: 'elevenlabs_agent',
-      language: voice.language,
-      transcriptionProvider: voice.transcriptionProvider,
-      ttsProvider: 'ElevenLabs',
-      voice: buildElevenLabsVoiceSpec(voice.elevenlabs),
-      agentId: voice.elevenlabs.agentId,
-      fallbackToStandardOnError: voice.fallbackToStandardOnError,
-      validationErrors: errors,
-    };
-  }
-
-  return standardProfile;
-}
-
-/** Returns false when the profile has any validation errors. */
-export function isVoiceProfileValid(profile: VoiceQualityProfile): boolean {
-  return profile.validationErrors.length === 0;
 }