@vellumai/assistant 0.10.4 → 0.10.5-dev.202607022248.91fa053

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

@@ -17,68 +17,6 @@ import type {
   TelephonySttMode,
 } from "../../stt/types.js";
 
-// ---------------------------------------------------------------------------
-// Telephony routing metadata
-// ---------------------------------------------------------------------------
-
-/**
- * Strategy kind for telephony call setup.
- *
- * Determines how the telephony routing resolver (`telephony-stt-routing.ts`)
- * wires the STT provider into a Twilio call:
- *
- * - `"conversation-relay-native"` — the provider is natively supported by
- *   Twilio ConversationRelay. TwiML includes `transcriptionProvider` /
- *   `speechModel` attributes and Twilio handles audio ingestion.
- * - `"media-stream-custom"` — the provider is not natively supported by
- *   Twilio. A `<Stream>` media-stream is opened and the daemon transcribes
- *   audio server-side via the provider's batch API.
- */
-type TelephonyStrategyKind =
-  | "conversation-relay-native"
-  | "media-stream-custom";
-
-/**
- * Twilio-native ConversationRelay provider name.
- *
- * These are the values Twilio accepts in the `transcriptionProvider` TwiML
- * attribute on `<ConversationRelay>`.
- */
-export type TwilioNativeProvider = "Deepgram" | "Google";
-
-/**
- * Twilio-native mapping details for providers routed through
- * ConversationRelay. Only present when `strategyKind` is
- * `"conversation-relay-native"`.
- */
-interface TwilioNativeMapping {
-  /** Twilio-native provider name for the TwiML `transcriptionProvider` attribute. */
-  readonly provider: TwilioNativeProvider;
-  /**
-   * Default ASR speech model identifier, or `undefined` to use the
-   * provider's default model. Individual providers override as needed
-   * (e.g. Deepgram defaults to `"nova-3"`).
-   */
-  readonly defaultSpeechModel: string | undefined;
-}
-
-/**
- * Telephony routing metadata — the single source of truth for how a
- * provider is wired into Twilio call setup.
- *
- * The telephony routing resolver reads these fields from the catalog
- * instead of maintaining its own hardcoded maps.
- */
-interface TelephonyRouting {
-  /** Which Twilio call-setup strategy this provider uses. */
-  readonly strategyKind: TelephonyStrategyKind;
-  /**
-   * Twilio-native mapping details. Present when `strategyKind` is
-   * `"conversation-relay-native"`, absent for `"media-stream-custom"`.
-   */
-  readonly twilioNativeMapping?: TwilioNativeMapping;
-}
-
 // ---------------------------------------------------------------------------
 // Client display metadata
 // ---------------------------------------------------------------------------
@@ -161,13 +99,6 @@ interface SttProviderEntry {
    */
   readonly supportsDiarization: boolean;
 
-  /**
-   * Telephony routing metadata — describes how this provider is wired
-   * into Twilio call setup. This is the single source of truth for
-   * strategy selection and Twilio-native mapping details.
-   */
-  readonly telephonyRouting: TelephonyRouting;
-
   /** Guide for obtaining API credentials from this provider. */
   readonly credentialsGuide?: SttCredentialsGuide;
 }
@@ -206,13 +137,6 @@ const CATALOG: ReadonlyMap<SttProviderId, SttProviderEntry> = new Map<
       telephonyMode: "realtime-ws",
       conversationStreamingMode: "realtime-ws",
       supportsDiarization: true,
-      telephonyRouting: {
-        strategyKind: "conversation-relay-native",
-        twilioNativeMapping: {
-          provider: "Deepgram",
-          defaultSpeechModel: "nova-3",
-        },
-      },
       credentialsGuide: {
         description:
           "Sign in to the Deepgram console, navigate to API Keys, and create a new key.",
@@ -239,13 +163,6 @@ const CATALOG: ReadonlyMap<SttProviderId, SttProviderEntry> = new Map<
       telephonyMode: "batch-only",
       conversationStreamingMode: "realtime-ws",
       supportsDiarization: false,
-      telephonyRouting: {
-        strategyKind: "conversation-relay-native",
-        twilioNativeMapping: {
-          provider: "Google",
-          defaultSpeechModel: undefined,
-        },
-      },
       credentialsGuide: {
         description:
           "Visit Google AI Studio, sign in with your Google account, and create an API key.",
@@ -271,9 +188,6 @@ const CATALOG: ReadonlyMap<SttProviderId, SttProviderEntry> = new Map<
       telephonyMode: "batch-only",
       conversationStreamingMode: "incremental-batch",
       supportsDiarization: false,
-      telephonyRouting: {
-        strategyKind: "media-stream-custom",
-      },
       credentialsGuide: {
         description:
           "Log in to the OpenAI platform, go to API Keys, and generate a new secret key.",
@@ -299,9 +213,6 @@ const CATALOG: ReadonlyMap<SttProviderId, SttProviderEntry> = new Map<
       telephonyMode: "batch-only",
       conversationStreamingMode: "realtime-ws",
       supportsDiarization: true,
-      telephonyRouting: {
-        strategyKind: "media-stream-custom",
-      },
       credentialsGuide: {
         description:
           "Sign in to the xAI console, navigate to API Keys, and create a new key.",

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

@@ -260,6 +260,17 @@ export interface ResolveStreamingTranscriberOptions {
    * See {@link DiarizePreference} for semantics.
    */
   diarize?: DiarizePreference;
+  /**
+   * Emit `final` events only at utterance boundaries. Supported only by
+   * providers whose catalog `telephonyMode` is `"realtime-ws"` (Deepgram,
+   * where it also enables `utterance_end_ms` endpointing). All other
+   * providers resolve to `null` so the caller falls back to per-turn
+   * batch transcription — e.g. openai-whisper fires `final` only from
+   * `stop()` (end-of-stream, not end-of-utterance) and xAI emits a
+   * `final` per committed segment. Used by telephony call ingestion.
+   * Default: false.
+   */
+  utteranceBoundaryFinals?: boolean;
 }
 
 /**
@@ -277,6 +288,8 @@ export interface ResolveStreamingTranscriberOptions {
  * - No credentials are configured for the resolved provider.
  * - No streaming adapter exists for the configured provider.
  * - `diarize` is `"required"` but the configured provider cannot diarize.
+ * - `utteranceBoundaryFinals` is set but the configured provider's catalog
+ *   `telephonyMode` is not `"realtime-ws"`.
  */
 export async function resolveStreamingTranscriber(
   options: ResolveStreamingTranscriberOptions = {},
@@ -298,6 +311,26 @@ export async function resolveStreamingTranscriber(
     return null;
   }
 
+  // Boundary-requiring callers (telephony) can only stream on providers
+  // whose catalog telephonyMode is "realtime-ws" (Deepgram gates finals on
+  // utterance boundaries). Everything else fires `final` either only from
+  // stop() — end-of-stream, not end-of-utterance (openai-whisper) — or per
+  // committed segment (xAI), so streaming would yield no replies until
+  // hangup, or mid-sentence replies. Resolve to null so the caller falls
+  // back to per-turn batch transcription.
+  if (options.utteranceBoundaryFinals) {
+    const telephonyMode = getProviderEntry(
+      provider as SttProviderId,
+    )?.telephonyMode;
+    if (telephonyMode !== "realtime-ws") {
+      log.warn(
+        { providerId: provider, telephonyMode },
+        "utterance-boundary finals requested but the configured STT provider has no realtime telephony streaming — falling back to batch transcription",
+      );
+      return null;
+    }
+  }
+
   // Resolve diarization capability against the catalog. For `"required"`
   // callers, bail early (with a warning) when the configured provider can't
   // diarize so the caller can surface a clear error to the user.
@@ -323,9 +356,18 @@ export async function resolveStreamingTranscriber(
   return createStreamingTranscriber(apiKey, provider as SttProviderId, {
     sampleRate: options.sampleRate,
     diarize: enableDiarization,
+    utteranceBoundaryFinals: options.utteranceBoundaryFinals ?? false,
   });
 }
 
+/**
+ * Deepgram `utterance_end_ms` used when utterance-boundary finals are
+ * requested. Deepgram requires >= 1000 ms; this is the pause length after
+ * which an `UtteranceEnd` frame confirms the utterance is complete even
+ * when `speech_final` endpointing never fired (e.g. background noise).
+ */
+const UTTERANCE_BOUNDARY_END_MS = 1_000;
+
 /**
  * Options forwarded to individual streaming adapter constructors.
  */
@@ -338,6 +380,13 @@ interface CreateStreamingTranscriberOptions {
    * support.
    */
   diarize?: boolean;
+  /**
+   * Whether `final` events should be gated on utterance boundaries.
+   * Only forwarded to Deepgram; the resolver never sets this for
+   * providers without realtime telephony streaming (they resolve to
+   * `null` instead).
+   */
+  utteranceBoundaryFinals?: boolean;
 }
 
 /**
@@ -361,6 +410,12 @@ async function createStreamingTranscriber(
       return new DeepgramRealtimeTranscriber(apiKey, {
         sampleRate: options.sampleRate,
         ...(options.diarize ? { diarize: true } : {}),
+        ...(options.utteranceBoundaryFinals
+          ? {
+              utteranceBoundaryFinals: true,
+              utteranceEndMs: UTTERANCE_BOUNDARY_END_MS,
+            }
+          : {}),
       });
     }
     case "google-gemini": {

package/src/providers/tool-progress-events.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, test } from "bun:test";
+
+import { createToolProgressEmitter } from "./tool-progress-events.js";
+import type { ProviderEvent } from "./types.js";
+
+describe("createToolProgressEmitter", () => {
+  test("flushes the latest throttled argument progress after activity pauses", async () => {
+    const events: ProviderEvent[] = [];
+    const progress = createToolProgressEmitter((event) => events.push(event));
+
+    progress.emitInputJsonDelta("call-1", "app_create", '{"a":1}');
+    progress.emitInputJsonDelta("call-1", "app_create", '{"a":12}');
+
+    expect(events).toEqual([
+      {
+        type: "tool_use_preview_start",
+        toolUseId: "call-1",
+        toolName: "app_create",
+      },
+      {
+        type: "input_json_delta",
+        toolUseId: "call-1",
+        toolName: "app_create",
+        accumulatedJson: '{"a":1}',
+      },
+    ]);
+
+    await Bun.sleep(180);
+
+    expect(events).toEqual([
+      {
+        type: "tool_use_preview_start",
+        toolUseId: "call-1",
+        toolName: "app_create",
+      },
+      {
+        type: "input_json_delta",
+        toolUseId: "call-1",
+        toolName: "app_create",
+        accumulatedJson: '{"a":1}',
+      },
+      {
+        type: "input_json_delta",
+        toolUseId: "call-1",
+        toolName: "app_create",
+        accumulatedJson: '{"a":12}',
+      },
+    ]);
+  });
+});

package/src/providers/tool-progress-events.ts

@@ -0,0 +1,99 @@
+import type { ProviderEvent } from "./types.js";
+
+const INPUT_JSON_DELTA_EMIT_INTERVAL_MS = 150;
+
+export function createToolProgressEmitter(
+  onEvent: ((event: ProviderEvent) => void) | undefined,
+): {
+  emitPreviewStart: (toolUseId: string, toolName: string) => void;
+  emitInputJsonDelta: (
+    toolUseId: string,
+    toolName: string,
+    accumulatedJson: string,
+    opts?: { force?: boolean },
+  ) => void;
+} {
+  const previewedToolUseIds = new Set<string>();
+  const lastInputEmitByToolUseId = new Map<
+    string,
+    { emittedAt: number; accumulatedJson: string }
+  >();
+  const pendingInputEmitByToolUseId = new Map<
+    string,
+    {
+      timeout: ReturnType<typeof setTimeout>;
+      toolName: string;
+      accumulatedJson: string;
+    }
+  >();
+
+  const emitPreviewStart = (toolUseId: string, toolName: string): void => {
+    if (!onEvent || !toolUseId || !toolName) return;
+    if (previewedToolUseIds.has(toolUseId)) return;
+    previewedToolUseIds.add(toolUseId);
+    onEvent({ type: "tool_use_preview_start", toolUseId, toolName });
+  };
+
+  const emitInputJsonDelta = (
+    toolUseId: string,
+    toolName: string,
+    accumulatedJson: string,
+    opts?: { force?: boolean },
+  ): void => {
+    if (!onEvent || !toolUseId || !toolName || !accumulatedJson) return;
+    emitPreviewStart(toolUseId, toolName);
+
+    const last = lastInputEmitByToolUseId.get(toolUseId);
+    if (last?.accumulatedJson === accumulatedJson) return;
+
+    const now = Date.now();
+    if (
+      !opts?.force &&
+      last &&
+      now - last.emittedAt < INPUT_JSON_DELTA_EMIT_INTERVAL_MS
+    ) {
+      const pending = pendingInputEmitByToolUseId.get(toolUseId);
+      if (pending) {
+        pending.toolName = toolName;
+        pending.accumulatedJson = accumulatedJson;
+        return;
+      }
+      const delay = INPUT_JSON_DELTA_EMIT_INTERVAL_MS - (now - last.emittedAt);
+      const timeout = setTimeout(() => {
+        const latest = pendingInputEmitByToolUseId.get(toolUseId);
+        if (!latest) return;
+        pendingInputEmitByToolUseId.delete(toolUseId);
+        lastInputEmitByToolUseId.set(toolUseId, {
+          emittedAt: Date.now(),
+          accumulatedJson: latest.accumulatedJson,
+        });
+        onEvent({
+          type: "input_json_delta",
+          toolName: latest.toolName,
+          toolUseId,
+          accumulatedJson: latest.accumulatedJson,
+        });
+      }, delay);
+      timeout.unref?.();
+      pendingInputEmitByToolUseId.set(toolUseId, {
+        timeout,
+        toolName,
+        accumulatedJson,
+      });
+      return;
+    }
+
+    const pending = pendingInputEmitByToolUseId.get(toolUseId);
+    if (pending) {
+      clearTimeout(pending.timeout);
+      pendingInputEmitByToolUseId.delete(toolUseId);
+    }
+    lastInputEmitByToolUseId.set(toolUseId, {
+      emittedAt: now,
+      accumulatedJson,
+    });
+    onEvent({ type: "input_json_delta", toolName, toolUseId, accumulatedJson });
+  };
+
+  return { emitPreviewStart, emitInputJsonDelta };
+}

package/src/providers/types.ts

@@ -1,4 +1,4 @@
-import type { ToolDefinition } from "@vellumai/skill-host-contracts";
+import type { ToolDefinition } from "../tools/tool-types.js";
 export type { ToolDefinition };
 
 import type { LLMCallSite } from "../config/schemas/llm.js";

package/src/runtime/AGENTS.md

@@ -163,15 +163,16 @@ Verification SESSION state (pending sessions, codes, resend, rate-limit) is assi
 
 The verified outcome is written in-process by the gateway: the HTTP guardian-attest handler calls `ContactStore.markChannelVerified` directly (verifiedVia "manual"), and the inbound code-match path (`gateway/src/verification/text-verification.ts`) writes via `upsertVerifiedContactChannel` / `createGuardianBinding` (verifiedVia "challenge"). The revoke/downgrade outcome is relayed from the daemon via `ipcCallPersistent("mark_channel_revoked", …)` to `ContactStore.markChannelRevoked`.
 
-The `mark_channel_verified` IPC method exists as the daemon/CLI relay surface (symmetric with `mark_channel_revoked`) but has no caller: the trusted-contact CLI path sends codes only, and the outcome arrives via the inbound code-match path.
-
 ## Rate Limiting & Diagnostics
 
-All `/v1/*` endpoints share a per-client-IP sliding-window rate limiter (`middleware/rate-limiter.ts`):
+Most `/v1/*` endpoints share a per-client-IP sliding-window rate limiter (`middleware/rate-limiter.ts`):
 
-- **Authenticated**: 300 requests/minute
+- **Authenticated (loopback)**: 1200 requests/minute — desktop app, CLI, anything on the daemon's own host (`127.0.0.0/8`, `::1`). A cold sidebar load at thousands of conversations legitimately bursts far beyond the remote budget.
+- **Authenticated (remote)**: 300 requests/minute — proxied non-loopback clients, keyed by the forwarded client IP.
 - **Unauthenticated**: 20 requests/minute
 
+**Exempt endpoints** (`isRateLimitExemptEndpoint`): the SSE stream (`events`) and liveness/readiness probes (`health`, `healthz`, `readyz`) bypass the per-minute limiter entirely. The stream is one long-lived connection, not a burst of requests, and 429-ing it drops the stream — which drives a client reconnect + full re-bootstrap loop that generates far more load than the limiter saves. Liveness probes must always answer or the client treats the assistant as down and reconnects harder. The events route still enforces auth downstream, and stream memory is bounded by SSE backpressure shedding + subscriber caps.
+
 When the limit is exceeded, the limiter returns 429 and logs a structured warning (module: `rate-limiter`) with the denied endpoint and a breakdown of which endpoints consumed the budget in the current window. This makes it easy to identify whether the cause is rapid conversation switching, polling, or unexpected request volume.
 
 Logs rotate daily into `$VELLUM_WORKSPACE_DIR/data/logs/assistant-YYYY-MM-DD.log` (or into the directory configured via `logFile.dir`). To watch rate limit events in real time:

package/src/runtime/__tests__/agent-wake.test.ts

@@ -87,6 +87,13 @@ interface WakeConversationProbe {
    * persistent `setTrustContext`) and restores the prior value in its finally.
    */
   turnTrustContextSets: Array<{ ctx: unknown; order: number }>;
+  /**
+   * `setTrustContext` writes to the persistent `conversation.trustContext`,
+   * in order. A trust-carrying wake's resolver leaves its trust here; the
+   * wake must put the prior value back so it doesn't linger for a later
+   * no-trust wake.
+   */
+  trustContextSets: unknown[];
   /**
    * Every assignment to `conversation.wakePersonaOverride`, in order. A
    * wake that applies an override records `[override, undefined]` — the
@@ -340,6 +347,10 @@ import type {
   AgentLoopRunResult,
 } from "../../agent/loop.js";
 import type { Conversation } from "../../daemon/conversation.js";
+import {
+  deleteConversation,
+  setConversation,
+} from "../../daemon/conversation-registry.js";
 import { ContextOverflowError, type Message } from "../../providers/types.js";
 import {
   __resetWakeChainForTests,
@@ -387,6 +398,8 @@ function makeWakeConversation(options: {
    * (always under the mocked 200k window).
    */
   estimatedInputTokens?: number;
+  /** Seed for the conversation's resting `trustContext`. */
+  initialTrustContext?: unknown;
 }): WakeConversation {
   const conversationId = options.conversationId ?? "conv-test";
   const probe: WakeConversationProbe = {
@@ -401,6 +414,7 @@ function makeWakeConversation(options: {
     processingDuringDrain: [],
     allowedToolSnapshots: [],
     turnTrustContextSets: [],
+    trustContextSets: [],
     personaOverrideSets: [],
     persistedAtEachEmit: [],
     maybeCompactOrders: [],
@@ -413,6 +427,7 @@ function makeWakeConversation(options: {
   let activeAllowedTools = options.initialAllowedTools;
   let wakePersonaOverride: unknown;
   let currentTurnTrustContext: unknown;
+  let persistentTrustContext: unknown = options.initialTrustContext;
   const snapshotAllowedTools = (): string[] | undefined =>
     activeAllowedTools ? [...activeAllowedTools].sort() : undefined;
 
@@ -526,7 +541,14 @@ function makeWakeConversation(options: {
     },
     getTurnChannelContext: () => null,
     getTurnInterfaceContext: () => null,
-    trustContext: undefined,
+    get trustContext() {
+      return persistentTrustContext;
+    },
+    // Mirrors Conversation.setTrustContext (coerces null → undefined).
+    setTrustContext(ctx: unknown) {
+      persistentTrustContext = ctx ?? undefined;
+      probe.trustContextSets.push(ctx);
+    },
     buildCurrentSystemPrompt: () => "mock-system-prompt",
     modelOverride: undefined,
     ...(drainQueue ? { drainQueue } : {}),
@@ -1535,6 +1557,141 @@ describe("wakeAgentForOpportunity", () => {
     expect(conversation.currentTurnTrustContext).toBeUndefined();
   });
 
+  // ── Persistent-trust restore ────────────────────────────────────────
+  // The resolver leaves the wake's trust on the conversation. The wake must
+  // put the prior resting value back, or a later no-trust wake inherits it
+  // through tool setup's `currentTurnTrustContext ?? trustContext` fallback.
+
+  const GUARDIAN_TRUST = {
+    sourceChannel: "vellum",
+    trustClass: "guardian",
+  } as const;
+
+  // The wake reads the prior trust from the live registry, so a test that
+  // wants to exercise the restore registers its double there and simulates
+  // the resolver's write by setting the trust in resolveTarget.
+  const withRegisteredConversation = async (
+    conversation: WakeConversation,
+    run: () => Promise<unknown>,
+  ): Promise<void> => {
+    setConversation(conversation.conversationId, conversation as Conversation);
+    try {
+      await run();
+    } finally {
+      deleteConversation(conversation.conversationId);
+    }
+  };
+
+  test("restores the conversation's prior trust once the wake ends", async () => {
+    const priorTrust = {
+      sourceChannel: "slack",
+      trustClass: "trusted_contact",
+    } as const;
+    const conversation = makeWakeConversation({
+      conversationId: "conv-trust-restore",
+      initialTrustContext: priorTrust,
+    });
+
+    await withRegisteredConversation(conversation, () =>
+      wakeAgentForOpportunity(
+        {
+          conversationId: "conv-trust-restore",
+          hint: "x",
+          source: "t",
+          trustContext: GUARDIAN_TRUST,
+        },
+        {
+          resolveTarget: async () => {
+            conversation.setTrustContext(GUARDIAN_TRUST);
+            return conversation;
+          },
+        },
+      ),
+    );
+
+    // Resolver installs guardian, wake restores the prior value.
+    expect(conversation.trustContextSets).toEqual([GUARDIAN_TRUST, priorTrust]);
+    expect(conversation.trustContext).toEqual(priorTrust);
+  });
+
+  test("restores the prior trust even when the agent loop throws", async () => {
+    const conversation = makeWakeConversation({
+      conversationId: "conv-trust-restore-throw",
+      runImpl: async () => {
+        throw new Error("boom");
+      },
+    });
+
+    await withRegisteredConversation(conversation, () =>
+      wakeAgentForOpportunity(
+        {
+          conversationId: "conv-trust-restore-throw",
+          hint: "x",
+          source: "t",
+          trustContext: GUARDIAN_TRUST,
+        },
+        {
+          resolveTarget: async () => {
+            conversation.setTrustContext(GUARDIAN_TRUST);
+            return conversation;
+          },
+        },
+      ),
+    );
+
+    // Nothing was resting before the wake, so it goes back to unset.
+    expect(conversation.trustContext).toBeUndefined();
+  });
+
+  test("leaves a trust that was re-set mid-run alone (identity guard)", async () => {
+    const replaced = {
+      sourceChannel: "vellum",
+      trustClass: "unknown",
+    } as const;
+    const conversation = makeWakeConversation({
+      conversationId: "conv-trust-guard",
+      runImpl: async (input) => {
+        conversation.setTrustContext(replaced);
+        return runResult(input);
+      },
+    });
+
+    await withRegisteredConversation(conversation, () =>
+      wakeAgentForOpportunity(
+        {
+          conversationId: "conv-trust-guard",
+          hint: "x",
+          source: "t",
+          trustContext: GUARDIAN_TRUST,
+        },
+        {
+          resolveTarget: async () => {
+            conversation.setTrustContext(GUARDIAN_TRUST);
+            return conversation;
+          },
+        },
+      ),
+    );
+
+    // The wake sees a different reference than it installed, so it doesn't
+    // restore: two writes (resolver install, mid-run replacement), no third.
+    expect(conversation.trustContext).toEqual(replaced);
+    expect(conversation.trustContextSets).toHaveLength(2);
+  });
+
+  test("never touches the persistent trust when the wake carries none", async () => {
+    const conversation = makeWakeConversation({
+      conversationId: "conv-trust-none",
+    });
+
+    await wakeAgentForOpportunity(
+      { conversationId: "conv-trust-none", hint: "x", source: "t" },
+      { resolveTarget: async () => conversation },
+    );
+
+    expect(conversation.trustContextSets).toHaveLength(0);
+  });
+
   test("two concurrent wakes on the same conversation are serialized", async () => {
     // Build a target whose agentLoop.run resolves only when we signal.
     const gate1 = Promise.withResolvers<void>();

package/src/runtime/__tests__/channel-verification-service.test.ts

@@ -73,7 +73,7 @@ describe("getGuardianBinding", () => {
     expect(binding?.verifiedVia).toBe("verified");
   });
 
-  test("falls back to empty strings for absent optional delivery fields", async () => {
+  test("a missing principal surfaces as null (unresolved), never an empty string", async () => {
     mockGuardianList = [
       {
         channelType: "telegram",
@@ -85,7 +85,7 @@ describe("getGuardianBinding", () => {
 
     const binding = await getGuardianBinding("asst-1", "telegram");
 
-    expect(binding?.guardianPrincipalId).toBe("");
+    expect(binding?.guardianPrincipalId).toBeNull();
     expect(binding?.guardianDeliveryChatId).toBe("");
     expect(binding?.verifiedAt).toBe(0);
   });