@vellumai/assistant 0.11.3 → 0.11.4-staging.2

package/src/providers/speech-to-text/provider-catalog.ts

@@ -14,6 +14,7 @@ import type {
   ConversationStreamingMode,
   SttBoundaryId,
   SttProviderId,
+  SttTurnDetectionMode,
   TelephonySttMode,
 } from "../../stt/types.js";
 import { baseLanguageSubtag } from "../../util/language-subtag.js";
@@ -87,6 +88,14 @@ interface SttProviderEntry {
    */
   readonly conversationStreamingMode: ConversationStreamingMode;
 
+  /**
+   * Whether the provider decides end-of-turn itself, in-band with the audio
+   * it transcribes, or leaves the boundary to the session's local silence
+   * timer. A live-voice session reads this to decide whether to arm its
+   * provider turn-end path; it never names a provider directly.
+   */
+  readonly turnDetection: SttTurnDetectionMode;
+
   /**
    * Whether the provider can attribute transcribed speech to distinct
    * speakers (speaker diarization). When `true`, callers may opt in to
@@ -105,8 +114,9 @@ interface SttProviderEntry {
    *
    * - `"manual"`: the provider accepts an explicit language parameter and
    *   defaults to English when omitted; a language picker is meaningful.
-   * - `"auto"`: the provider detects language natively and accepts no
-   *   language parameter; a picker would be a no-op, so clients must hide it.
+   * - `"auto"`: the provider takes no language parameter, either because it
+   *   detects the language natively or because its model is monolingual; a
+   *   picker would be a no-op, so clients must hide it.
    */
   readonly languageSelection: "manual" | "auto";
 
@@ -118,6 +128,17 @@ interface SttProviderEntry {
 // Catalog data
 // ---------------------------------------------------------------------------
 
+/**
+ * Shared by every provider that authenticates against a Deepgram account.
+ * The key is the same one, so the instructions must not drift apart.
+ */
+const DEEPGRAM_CREDENTIALS_GUIDE: SttCredentialsGuide = {
+  description:
+    "Sign in to the Deepgram console, navigate to API Keys, and create a new key.",
+  url: "https://console.deepgram.com/",
+  linkLabel: "Open Deepgram Console",
+};
+
 /**
  * Provider catalog entries, keyed by provider ID.
  *
@@ -147,14 +168,41 @@ const CATALOG: ReadonlyMap<SttProviderId, SttProviderEntry> = new Map<
       ]),
       telephonyMode: "realtime-ws",
       conversationStreamingMode: "realtime-ws",
+      turnDetection: "none",
       supportsDiarization: true,
       languageSelection: "manual",
-      credentialsGuide: {
-        description:
-          "Sign in to the Deepgram console, navigate to API Keys, and create a new key.",
-        url: "https://console.deepgram.com/",
-        linkLabel: "Open Deepgram Console",
-      },
+      credentialsGuide: DEEPGRAM_CREDENTIALS_GUIDE,
+    },
+  ],
+  [
+    "deepgram-flux",
+    {
+      id: "deepgram-flux",
+      displayName: "Deepgram Flux",
+      subtitle:
+        "Conversational speech-to-text with model-native turn detection. Uses your Deepgram API key.",
+      setupMode: "api-key",
+      setupHint:
+        "Enter your Deepgram API key. Flux shares the same key as Deepgram.",
+      // Shared with the `deepgram` provider: Flux is a model on the same
+      // account, not a separate credential.
+      credentialProvider: "deepgram",
+      // Streaming only: Flux has no batch endpoint.
+      supportedBoundaries: new Set<SttBoundaryId>(["daemon-streaming"]),
+      // Telephony is out of scope for the spike. Nothing reroutes a call to
+      // another provider, so a Flux-configured assistant does not transcribe
+      // calls at all.
+      telephonyMode: "none",
+      conversationStreamingMode: "realtime-ws",
+      // Flux emits turn lifecycle events on its transcript stream and numbers
+      // them, so a live-voice session may let them commit the turn.
+      turnDetection: "provider",
+      supportsDiarization: false,
+      // "no picker", not native detection: the Flux model is English-only and
+      // takes no language parameter, so audio in another language transcribes
+      // as English rather than being detected.
+      languageSelection: "auto",
+      credentialsGuide: DEEPGRAM_CREDENTIALS_GUIDE,
     },
   ],
   [
@@ -174,6 +222,7 @@ const CATALOG: ReadonlyMap<SttProviderId, SttProviderEntry> = new Map<
       ]),
       telephonyMode: "batch-only",
       conversationStreamingMode: "realtime-ws",
+      turnDetection: "none",
       supportsDiarization: false,
       languageSelection: "auto",
       credentialsGuide: {
@@ -200,6 +249,7 @@ const CATALOG: ReadonlyMap<SttProviderId, SttProviderEntry> = new Map<
       ]),
       telephonyMode: "batch-only",
       conversationStreamingMode: "incremental-batch",
+      turnDetection: "none",
       supportsDiarization: false,
       languageSelection: "auto",
       credentialsGuide: {
@@ -226,6 +276,7 @@ const CATALOG: ReadonlyMap<SttProviderId, SttProviderEntry> = new Map<
       ]),
       telephonyMode: "realtime-ws",
       conversationStreamingMode: "realtime-ws",
+      turnDetection: "none",
       supportsDiarization: false,
       // The relay dials Deepgram nova-3 server-side, which takes an explicit
       // language parameter.
@@ -248,6 +299,7 @@ const CATALOG: ReadonlyMap<SttProviderId, SttProviderEntry> = new Map<
       ]),
       telephonyMode: "batch-only",
       conversationStreamingMode: "realtime-ws",
+      turnDetection: "none",
       supportsDiarization: true,
       languageSelection: "manual",
       credentialsGuide: {
@@ -342,6 +394,32 @@ export function supportsBoundary(
   return CATALOG.get(id)?.supportedBoundaries.has(boundary) ?? false;
 }
 
+/**
+ * Message explaining why a provider cannot serve the `daemon-batch` boundary.
+ *
+ * Streaming-only providers are selected through the same
+ * `services.stt.provider` key as batch-capable ones, so a batch caller that
+ * reports only "nothing is configured" points the operator at the wrong
+ * problem. This names the provider and, where one exists, the batch-capable
+ * provider on the same credential, so acting on it needs no catalog reading.
+ */
+export function batchBoundaryGapReason(id: SttProviderId): string {
+  const entry = CATALOG.get(id);
+  const label = entry?.displayName ?? id;
+  const alternative = entry
+    ? [...CATALOG.values()].find(
+        (candidate) =>
+          candidate.id !== entry.id &&
+          candidate.credentialProvider === entry.credentialProvider &&
+          candidate.supportedBoundaries.has("daemon-batch"),
+      )
+    : undefined;
+  const remedy = alternative
+    ? `Batch transcription requires the ${alternative.id} provider: set services.stt.provider to "${alternative.id}".`
+    : "Set services.stt.provider to a provider that supports batch transcription.";
+  return `${label} is streaming-only. ${remedy}`;
+}
+
 /**
  * Check whether a provider supports speaker diarization.
  *
@@ -353,6 +431,19 @@ export function supportsDiarization(id: SttProviderId): boolean {
   return CATALOG.get(id)?.supportsDiarization ?? false;
 }
 
+/**
+ * Check whether a provider decides end-of-turn itself.
+ *
+ * Returns `false` for unknown provider IDs, which keeps an unrecognized
+ * provider on the local silence boundary rather than waiting for turn events
+ * that will never arrive. A live-voice session reads this instead of naming a
+ * provider, so a new turn-detecting provider is a catalog entry rather than a
+ * session change.
+ */
+export function supportsProviderTurnDetection(id: SttProviderId): boolean {
+  return CATALOG.get(id)?.turnDetection === "provider";
+}
+
 /**
  * Return all canonical provider IDs in deterministic (insertion) order.
  */

package/src/providers/speech-to-text/resolve.ts

@@ -6,8 +6,10 @@ import type {
   StreamingTranscriber,
   SttProviderId,
 } from "../../stt/types.js";
+import { SttError } from "../../stt/types.js";
 import { getLogger } from "../../util/logger.js";
 import {
+  batchBoundaryGapReason,
   getCredentialProvider,
   getProviderEntry,
   supportsBoundary,
@@ -88,8 +90,13 @@ export function effectiveSttLanguage(
  *
  * Returns `null` when:
  * - The configured provider is not in the catalog.
- * - The configured provider doesn't support the `daemon-batch` boundary.
  * - No credentials are configured for the resolved provider.
+ *
+ * Throws an {@link SttError} when the configured provider is in the catalog
+ * but has no `daemon-batch` boundary. That is a configuration mismatch the
+ * resolver can name, and returning `null` for it would reach the user as the
+ * "no speech-to-text provider is configured" copy every caller pairs with
+ * `null`, which is the opposite of what happened.
  */
 export async function resolveBatchTranscriber(): Promise<BatchTranscriber | null> {
   // Snapshot the stt config once, before any await, so a concurrent config
@@ -111,7 +118,9 @@ export async function resolveBatchTranscriber(): Promise<BatchTranscriber | null
 
   // Verify the provider supports the daemon-batch boundary.
   if (!supportsBoundary(provider as SttProviderId, "daemon-batch")) {
-    return null;
+    const reason = batchBoundaryGapReason(provider as SttProviderId);
+    log.warn({ providerId: provider }, reason);
+    throw new SttError("provider-error", reason, { userFacing: true });
   }
 
   if (provider === "vellum") {
@@ -632,6 +641,20 @@ async function createStreamingTranscriber(
           : {}),
       });
     }
+    case "deepgram-flux": {
+      // Flux is streaming-only and dials Deepgram's /v2/listen conversational
+      // endpoint. Turn-detection tuning comes from `liveVoice.flux`, which
+      // the adapter reads itself, so only the transport-level sample rate is
+      // passed here. No language is forwarded: the spike pins the
+      // English-only `flux-general-en`, and `language_hint` means nothing to
+      // a monolingual model. Diarization is off in the catalog, so a
+      // `"required"` caller never reaches this case.
+      const { DeepgramFluxRealtimeTranscriber } =
+        await import("./deepgram-flux-realtime.js");
+      return new DeepgramFluxRealtimeTranscriber(apiKey, {
+        sampleRate: options.sampleRate,
+      });
+    }
     default: {
       const _exhaustive: never = providerId;
       return null;

package/src/routes/worker.ts

@@ -25,6 +25,11 @@ import type { IpcEnvelope } from "@vellumai/ipc-server-utils";
 import { IpcFrameReader, writeMessage } from "@vellumai/ipc-server-utils";
 
 import { disableStreamSeqStamping } from "../runtime/assistant-stream-state.js";
+import {
+  evictRouteSourceTree,
+  importRouteModule,
+  sourceRootForHandler,
+} from "../runtime/routes/user-route-import.js";
 import { getLogger } from "../util/logger.js";
 import {
   ensureProcDir,
@@ -43,6 +48,9 @@ import {
 
 const log = getLogger("route-host");
 
+/** Last entry-file mtime imported in this process, keyed by handler path. */
+const lastHandlerMtime = new Map<string, number>();
+
 const socketPath = getProcSocketPath(ROUTE_HOST_PROC_NAME);
 const pidPath = getProcPidPath(ROUTE_HOST_PROC_NAME);
 
@@ -110,11 +118,15 @@ async function handleInvoke(
   params: RouteInvokeParams,
   body: Uint8Array | undefined,
 ): Promise<void> {
-  // Each worker has its own module cache; cache-bust per mtime so an edited
-  // handler is re-imported.
-  const mod = (await import(
-    `${params.filePath}?t=${params.mtimeMs}`
-  )) as Record<string, unknown>;
+  // Each worker has its own module cache. When the entry file's mtime
+  // moves, evict the whole source tree so a new handler cannot bind to a
+  // stale helper, then re-import.
+  const lastMtime = lastHandlerMtime.get(params.filePath);
+  if (lastMtime !== params.mtimeMs) {
+    evictRouteSourceTree(sourceRootForHandler(params.filePath));
+    lastHandlerMtime.set(params.filePath, params.mtimeMs);
+  }
+  const mod = await importRouteModule(params.filePath);
 
   const handler = mod[params.method];
   if (typeof handler !== "function") {

package/src/runtime/access-request-helper.ts

@@ -29,6 +29,7 @@ import { buildVellumCardAffinity } from "../notifications/vellum-card-affinity.j
 import { IntegrityError } from "../util/errors.js";
 import { getLogger } from "../util/logger.js";
 import { resolveAnchoredGuardian } from "./anchored-guardian.js";
+import { DAEMON_INTERNAL_ASSISTANT_ID } from "./assistant-scope.js";
 import { CHALLENGE_TTL_MS } from "./channel-verification-service.js";
 import {
   type AccessRequestTrigger,
@@ -46,7 +47,6 @@ const log = getLogger("access-request-helper");
 export type { AccessRequestTrigger } from "./introduction-policy.js";
 
 export interface AccessRequestParams {
-  canonicalAssistantId: string;
   sourceChannel: ChannelId;
   conversationExternalId: string;
   actorExternalId?: string;
@@ -93,15 +93,18 @@ export type AccessRequestResult =
 // ---------------------------------------------------------------------------
 
 /**
- * Assistant-scoped conversation id for an actor's access requests. Stable key
- * that dedupes pending prompts for the same (assistant, channel, actor).
+ * Conversation id for an actor's access requests. Stable key that dedupes
+ * pending prompts for the same (channel, actor).
+ *
+ * The `self` segment is part of a persisted id format: guardian request rows
+ * carry these ids, so the shape is fixed even though the daemon scopes all its
+ * storage to the one assistant (`DAEMON_INTERNAL_ASSISTANT_ID`).
  */
 export function accessRequestConversationId(
-  canonicalAssistantId: string,
   sourceChannel: string,
   actorExternalId: string,
 ): string {
-  return `access-req-${canonicalAssistantId}-${sourceChannel}-${actorExternalId}`;
+  return `access-req-${DAEMON_INTERNAL_ASSISTANT_ID}-${sourceChannel}-${actorExternalId}`;
 }
 
 /**
@@ -126,7 +129,6 @@ export function accessRequestConversationId(
  * fail-closed.
  */
 export async function isApprovalHandshakeInProgress(params: {
-  canonicalAssistantId: string;
   sourceChannel: string;
   actorExternalId: string;
 }): Promise<boolean> {
@@ -134,7 +136,6 @@ export async function isApprovalHandshakeInProgress(params: {
     return false;
   }
   const conversationId = accessRequestConversationId(
-    params.canonicalAssistantId,
     params.sourceChannel,
     params.actorExternalId,
   );
@@ -171,7 +172,6 @@ export async function notifyGuardianOfAccessRequest(
   params: AccessRequestParams,
 ): Promise<AccessRequestResult> {
   const {
-    canonicalAssistantId,
     sourceChannel,
     conversationExternalId,
     actorExternalId,
@@ -219,7 +219,6 @@ export async function notifyGuardianOfAccessRequest(
   // from assistant A could be returned for assistant B, allowing the caller
   // to piggyback on A's guardian approval.
   const conversationId = accessRequestConversationId(
-    canonicalAssistantId,
     sourceChannel,
     actorExternalId,
   );
@@ -270,7 +269,6 @@ export async function notifyGuardianOfAccessRequest(
   // re-prompting is allowed again.
   if (
     await isApprovalHandshakeInProgress({
-      canonicalAssistantId,
       sourceChannel,
       actorExternalId,
     })
@@ -283,7 +281,7 @@ export async function notifyGuardianOfAccessRequest(
   }
 
   const senderIdentifier = actorDisplayName || actorUsername || actorExternalId;
-  const requestId = `access-req-${canonicalAssistantId}-${sourceChannel}-${actorExternalId}-${Date.now()}`;
+  const requestId = `access-req-${DAEMON_INTERNAL_ASSISTANT_ID}-${sourceChannel}-${actorExternalId}-${Date.now()}`;
 
   // Access requests are decisionable: without a bound principal nobody could
   // ever decide them (mirrors the gateway create's integrity guard).
@@ -461,7 +459,6 @@ export async function maybeNotifyGuardianOfAdmittedContact(
   }
 
   const conversationId = accessRequestConversationId(
-    params.canonicalAssistantId,
     params.sourceChannel,
     params.actorExternalId,
   );

package/src/runtime/agent-wake.ts

@@ -718,9 +718,9 @@ export async function wakeAgentForOpportunity(
   return runWakeSingleFlight(conversationId, async () => {
     // Snapshot the conversation's resting trust before the resolver runs, so
     // it can be restored after. The resolver leaves the wake's trust on the
-    // conversation, and a following no-trust wake would otherwise read it via
-    // tool setup's `currentTurnTrustContext ?? trustContext` fallback. Null
-    // when the conversation isn't resident yet (a fresh hydrate or a fork).
+    // conversation, and a following no-trust wake would otherwise pick it up
+    // from the resting trust its consumers fall back to. Null when the
+    // conversation isn't resident yet (a fresh hydrate or a fork).
     let priorPersistentTrust: TrustContext | null = null;
     if (opts.trustContext) {
       const { findConversation } =

package/src/runtime/pre-first-message-gate.ts

@@ -55,9 +55,13 @@ export function hasReceivedUserMessage(): boolean {
   try {
     const row = rawGet<{ one: number }>(
       "preFirstMsg:hasReceivedUserMessage",
+      // Finalized user-role rows only: the grouped tool-result row is a
+      // user-role row reserved unfinalized mid-turn, and this gate must not
+      // read tool plumbing as "the user has messaged this assistant".
       `SELECT 1 AS one FROM messages m
        JOIN conversations c ON m.conversation_id = c.id
        WHERE m.role = 'user'
+         AND m.finalized = 1
          AND c.conversation_type = 'standard'
        LIMIT 1`,
     );

package/src/runtime/routes/__tests__/acp-claude-auth-routes.test.ts

@@ -47,7 +47,7 @@ mock.module("../../../security/oauth2.js", () => ({
 }));
 
 const actualClaudeOauth = await import("../../../acp/acp-claude-oauth.js");
-const { CLAUDE_MANUAL_REDIRECT_URI } = actualClaudeOauth;
+const { CLAUDE_MANUAL_REDIRECT_URI, CLAUDE_OAUTH_CONFIG } = actualClaudeOauth;
 const storeAcpClaudeTokenMock = mock(async (_token: string) => {});
 // The connect-status route reads token presence; mock it so the route test
 // doesn't reach real secure storage.
@@ -125,7 +125,7 @@ function deferredFlow(state: string): {
     reject = rej;
   });
   prepareOAuth2FlowMock.mockImplementationOnce(async () => ({
-    authorizeUrl: `https://claude.ai/oauth/authorize?state=${state}`,
+    authorizeUrl: `${CLAUDE_OAUTH_CONFIG.authorizeUrl}?state=${state}`,
     state,
     completion,
   }));
@@ -153,7 +153,7 @@ describe("acp_claude_auth_start", () => {
 
     const url = new URL(result.authorize_url);
     expect(`${url.origin}${url.pathname}`).toBe(
-      "https://claude.ai/oauth/authorize",
+      CLAUDE_OAUTH_CONFIG.authorizeUrl,
     );
     expect(url.searchParams.get("client_id")).toBe(CLAUDE_CLIENT_ID);
     expect(url.searchParams.get("code_challenge_method")).toBe("S256");
@@ -161,6 +161,11 @@ describe("acp_claude_auth_start", () => {
     const redirectUri = url.searchParams.get("redirect_uri") ?? "";
     expect(redirectUri).toMatch(/^http:\/\/localhost:\d+\/callback$/);
 
+    // The loopback flow performs a REAL redirect to the localhost callback;
+    // `code=true` (render the code on the page) belongs to the manual flow
+    // only and must not leak into this URL.
+    expect(url.searchParams.get("code")).toBeNull();
+
     expect(result.state).toBeTruthy();
     expect(url.searchParams.get("state")).toBe(result.state);
 
@@ -284,7 +289,7 @@ describe("acp_claude_auth_start (cloud/manual)", () => {
     expect(result.mode).toBe("manual");
     const url = new URL(result.authorize_url);
     expect(`${url.origin}${url.pathname}`).toBe(
-      "https://claude.ai/oauth/authorize",
+      CLAUDE_OAUTH_CONFIG.authorizeUrl,
     );
     expect(url.searchParams.get("redirect_uri")).toBe(
       CLAUDE_MANUAL_REDIRECT_URI,
@@ -292,6 +297,9 @@ describe("acp_claude_auth_start (cloud/manual)", () => {
     expect(url.searchParams.get("client_id")).toBe(CLAUDE_CLIENT_ID);
     expect(url.searchParams.get("code_challenge_method")).toBe("S256");
     expect(url.searchParams.get("state")).toBe(result.state);
+    // Manual flow requires `code=true` so the callback page renders the
+    // `code#state` string to paste back.
+    expect(url.searchParams.get("code")).toBe("true");
 
     // The manual path must not bind a loopback.
     expect(prepareOAuth2FlowMock).not.toHaveBeenCalled();