@vellumai/assistant 0.11.3-staging.2 → 0.11.3-staging.3

package/src/runtime/assistant-event-hub.ts

@@ -465,6 +465,29 @@ export class AssistantEventHub {
     return this.getClientById(clientId)?.actorPrincipalId;
   }
 
+  /**
+   * Whether the connection identified by `connectionId` is still an active
+   * client subscription that carries no `actorPrincipalId`.
+   *
+   * Drives the retrying SSE self-heal (`sse-actor-principal-heal.ts`): the loop
+   * re-checks before each attempt so it stops as soon as the connection closes,
+   * is replaced by a reconnect, or gets a principal from any path. Returns
+   * `false` for an unknown, inactive, or process-type connection.
+   */
+  needsActorPrincipalHeal(connectionId: string): boolean {
+    for (const entry of this.subscribers) {
+      if (entry.connectionId !== connectionId) {
+        continue;
+      }
+      return (
+        entry.active &&
+        entry.type === "client" &&
+        entry.actorPrincipalId == null
+      );
+    }
+    return false;
+  }
+
   /**
    * Fill a missing `actorPrincipalId` on a live client subscription.
    *

package/src/runtime/local-actor-identity.ts

@@ -11,6 +11,7 @@
 import { isHttpAuthDisabled } from "../config/env.js";
 import {
   getGuardianDelivery,
+  getGuardianDeliveryFresh,
   guardianForChannel,
   peekCachedGuardianDelivery,
 } from "../contacts/guardian-delivery-reader.js";
@@ -52,11 +53,19 @@ export function buildLocalAuthContext(conversationId: string): AuthContext {
  * Returns `undefined` when no vellum guardian binding exists (e.g. fresh
  * install before bootstrap, or the gateway is unreachable). Callers should
  * treat that case as "not yet available" and proceed without a principalId.
+ *
+ * `forceRefresh` bypasses the reader's TTL cache. A successful read that finds
+ * no binding is itself cached, and gateway-side binding writes do not
+ * invalidate the daemon's cache, so a caller that polls for a binding it
+ * expects to appear (the SSE actor-principal heal) must force the read or it
+ * re-reads the same empty answer until the TTL lapses.
  */
-export async function findLocalGuardianPrincipalId(): Promise<
-  string | undefined
-> {
-  const list = await getGuardianDelivery({ channelTypes: ["vellum"] });
+export async function findLocalGuardianPrincipalId(options?: {
+  forceRefresh?: boolean;
+}): Promise<string | undefined> {
+  const list = options?.forceRefresh
+    ? await getGuardianDeliveryFresh({ channelTypes: ["vellum"] })
+    : await getGuardianDelivery({ channelTypes: ["vellum"] });
   if (!list) {
     return undefined;
   }
@@ -136,15 +145,19 @@ export function findLocalGuardianPrincipalIdFromStore(): string | undefined {
  * `undefined` when dev-bypass is set but no guardian binding has been created
  * yet (e.g. fresh install before bootstrap); callers must treat this the
  * same as a missing principal.
+ *
+ * `forceRefresh` bypasses the guardian-delivery cache, for callers that poll
+ * for a binding they expect to appear. See {@link findLocalGuardianPrincipalId}.
  */
 export async function resolveActorPrincipalIdForLocalGuardian(
   rawHeader: string | undefined,
+  options?: { forceRefresh?: boolean },
 ): Promise<string | undefined> {
   if (rawHeader !== "dev-bypass" || !isHttpAuthDisabled()) {
     return rawHeader;
   }
 
-  const guardianPrincipalId = await findLocalGuardianPrincipalId();
+  const guardianPrincipalId = await findLocalGuardianPrincipalId(options);
   if (guardianPrincipalId) {
     return guardianPrincipalId;
   }

package/src/runtime/routes/__tests__/sse-actor-principal-heal.test.ts

@@ -0,0 +1,165 @@
+/**
+ * Tests for the retrying SSE actor-principal self-heal.
+ *
+ * The invariant they pin: a single empty or failed guardian lookup must not
+ * strand the subscription without a principal. The read goes over the gateway
+ * IPC and comes back empty both when the transport fails and when no binding
+ * exists yet, and a subscription that stays principal-less rejects every
+ * host-proxy result its client submits with "Submitting actor does not match
+ * the target client's actor for this request" until it reconnects.
+ */
+import { describe, expect, mock, test } from "bun:test";
+
+import { startActorPrincipalHeal } from "../sse-actor-principal-heal.js";
+
+/** All-zero schedule so the retries run without real wall-clock delay. */
+const NO_DELAYS = [0, 0, 0];
+
+/** Minimal hub double: `needs` flips to false once a principal is filled. */
+function fakeHub(options?: { needs?: boolean }) {
+  let needs = options?.needs ?? true;
+  const filled: string[] = [];
+  return {
+    filled,
+    setNeeds(value: boolean) {
+      needs = value;
+    },
+    needsActorPrincipalHeal: mock(() => needs),
+    fillClientActorPrincipalId: mock((_connectionId: string, id: string) => {
+      filled.push(id);
+      needs = false;
+    }),
+  };
+}
+
+/** Let the heal's async loop run to completion. */
+async function settle(): Promise<void> {
+  for (let i = 0; i < 10; i++) {
+    await new Promise((resolve) => setTimeout(resolve, 0));
+  }
+}
+
+describe("startActorPrincipalHeal", () => {
+  test("fills the principal on the first successful attempt", async () => {
+    const hub = fakeHub();
+    startActorPrincipalHeal({
+      hub,
+      connectionId: "conn-1",
+      resolve: () => Promise.resolve("guardian-real-id"),
+      delaysMs: NO_DELAYS,
+    });
+    await settle();
+
+    expect(hub.filled).toEqual(["guardian-real-id"]);
+    expect(hub.needsActorPrincipalHeal).toHaveBeenCalledTimes(1);
+  });
+
+  test("retries after a lookup that resolves undefined (gateway unreachable)", async () => {
+    const hub = fakeHub();
+    let calls = 0;
+    startActorPrincipalHeal({
+      hub,
+      connectionId: "conn-1",
+      resolve: () => {
+        calls++;
+        // Two failed reads, then the gateway comes up.
+        return Promise.resolve(calls < 3 ? undefined : "guardian-real-id");
+      },
+      delaysMs: NO_DELAYS,
+    });
+    await settle();
+
+    expect(calls).toBe(3);
+    expect(hub.filled).toEqual(["guardian-real-id"]);
+  });
+
+  test("retries after a lookup that rejects", async () => {
+    const hub = fakeHub();
+    let calls = 0;
+    startActorPrincipalHeal({
+      hub,
+      connectionId: "conn-1",
+      resolve: () => {
+        calls++;
+        return calls === 1
+          ? Promise.reject(new Error("ipc timeout"))
+          : Promise.resolve("guardian-real-id");
+      },
+      delaysMs: NO_DELAYS,
+    });
+    await settle();
+
+    expect(calls).toBe(2);
+    expect(hub.filled).toEqual(["guardian-real-id"]);
+  });
+
+  test("stops retrying once the connection no longer needs healing", async () => {
+    // Models a disconnect (or a reconnect that replaced this subscription)
+    // between attempts: the loop must not keep polling the gateway for a
+    // connection that is gone.
+    const hub = fakeHub();
+    let calls = 0;
+    startActorPrincipalHeal({
+      hub,
+      connectionId: "conn-1",
+      resolve: () => {
+        calls++;
+        hub.setNeeds(false);
+        return Promise.resolve(undefined);
+      },
+      delaysMs: NO_DELAYS,
+    });
+    await settle();
+
+    expect(calls).toBe(1);
+    expect(hub.filled).toEqual([]);
+  });
+
+  test("never starts a lookup when the connection is already healed or gone", async () => {
+    const hub = fakeHub({ needs: false });
+    const resolve = mock(() => Promise.resolve("guardian-real-id"));
+    startActorPrincipalHeal({
+      hub,
+      connectionId: "conn-1",
+      resolve,
+      delaysMs: NO_DELAYS,
+    });
+    await settle();
+
+    expect(resolve).toHaveBeenCalledTimes(0);
+    expect(hub.filled).toEqual([]);
+  });
+
+  test("gives up after the schedule is exhausted without filling", async () => {
+    const hub = fakeHub();
+    let calls = 0;
+    startActorPrincipalHeal({
+      hub,
+      connectionId: "conn-1",
+      resolve: () => {
+        calls++;
+        return Promise.resolve(undefined);
+      },
+      delaysMs: NO_DELAYS,
+    });
+    await settle();
+
+    expect(calls).toBe(NO_DELAYS.length);
+    expect(hub.filled).toEqual([]);
+  });
+
+  test("dispatches the first attempt synchronously", () => {
+    const hub = fakeHub();
+    const resolve = mock(() => Promise.resolve("guardian-real-id"));
+    startActorPrincipalHeal({
+      hub,
+      connectionId: "conn-1",
+      resolve,
+      delaysMs: NO_DELAYS,
+    });
+
+    // No await: the leading zero delay must not cost a macrotask, so a
+    // warm-cache heal lands before the stream delivers its first event.
+    expect(resolve).toHaveBeenCalledTimes(1);
+  });
+});

package/src/runtime/routes/__tests__/surface-action-routes.test.ts

@@ -59,6 +59,8 @@ let mockReResolve: { trustClass: string; sourceChannel: string } | null = null;
 mock.module("../../../contacts/guardian-delivery-reader.js", () => ({
   getGuardianDelivery: (_input?: { channelTypes?: string[] }) =>
     Promise.resolve(mockGuardianList),
+  getGuardianDeliveryFresh: (_input?: { channelTypes?: string[] }) =>
+    Promise.resolve(mockGuardianList),
   peekCachedGuardianDelivery: () => mockGuardianList ?? undefined,
   guardianForChannel: (
     list: Array<Record<string, unknown>>,

package/src/runtime/routes/events-routes.ts

@@ -52,6 +52,7 @@ import {
   ServiceUnavailableError,
 } from "./errors.js";
 import { parseBody } from "./parse-body.js";
+import { startActorPrincipalHeal } from "./sse-actor-principal-heal.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 
 const log = getLogger("events-routes");
@@ -455,28 +456,28 @@ export function handleSubscribeAssistantEvents(
     throw err;
   }
 
-  // Self-heal for dev-bypass connections: the sync resolution above reads
-  // only the guardian-delivery cache, which can be cold at connect time.
-  // Without this, the subscription would carry no principal for its whole
-  // lifetime and every host-proxy result would 403. Fire-and-forget so the
-  // stream is not delayed; keyed by connectionId so a reconnect race cannot
-  // patch the subscription that replaced this one.
+  // Self-heal for dev-bypass connections: the sync resolution above reads only
+  // the guardian-delivery cache, which can be cold at connect time, and a
+  // subscription that carries no principal for its lifetime 403s every
+  // host-proxy result it submits. The heal retries on a bounded backoff
+  // (`sse-actor-principal-heal.ts`), fire-and-forget so the stream is not
+  // delayed, keyed by connectionId so a reconnect race cannot patch the
+  // subscription that replaced this one. The lookup forces a fresh gateway read
+  // because a cached empty result outlives the retry schedule.
   if (
     clientId &&
     interfaceId &&
     actorPrincipalId == null &&
     rawActorPrincipalId?.trim() === "dev-bypass"
   ) {
-    void resolveActorPrincipalIdForLocalGuardian("dev-bypass")
-      .then((resolved) => {
-        if (resolved) {
-          hub.fillClientActorPrincipalId(sub.connectionId, resolved);
-        }
-      })
-      .catch(() => {
-        // Best-effort: an unreachable gateway leaves the record unhealed;
-        // the next reconnect retries.
-      });
+    startActorPrincipalHeal({
+      hub,
+      connectionId: sub.connectionId,
+      resolve: () =>
+        resolveActorPrincipalIdForLocalGuardian("dev-bypass", {
+          forceRefresh: true,
+        }),
+    });
   }
 
   const stream = new ReadableStream<Uint8Array>(

package/src/runtime/routes/sse-actor-principal-heal.ts

@@ -0,0 +1,113 @@
+/**
+ * Retrying self-heal for an SSE client subscription that registered without an
+ * actor principal.
+ *
+ * In `DISABLE_HTTP_AUTH` deployments the SSE subscribe path cannot await, so it
+ * resolves the dev-bypass actor principal from an IO-free peek at the
+ * guardian-delivery cache. A cold cache registers the subscription with
+ * `actorPrincipalId: undefined`, and every host-proxy result that client
+ * submits then fails the same-actor gate with `missing_target`: a 403 that only
+ * a fresh registration clears.
+ *
+ * The heal resolves the guardian asynchronously and patches the live hub
+ * record. Each attempt can come back empty, since the lookup goes over the
+ * gateway IPC and yields nothing both when the transport fails (unreachable
+ * gateway, its 2s timeout, a pod still starting) and when no guardian binding
+ * exists yet, so attempts repeat on a bounded backoff. The loop stops on the
+ * first success, when the connection is gone or already carries a principal, or
+ * when the schedule is exhausted.
+ *
+ * Callers must pass a cache-bypassing lookup: the guardian-delivery reader
+ * caches a successful empty result for minutes, which outlives the whole
+ * schedule, so a cached read would spend every attempt on the same stale
+ * answer.
+ */
+import { getLogger } from "../../util/logger.js";
+
+const log = getLogger("sse-actor-heal");
+
+/**
+ * The hub surface this module needs: a liveness check and the fill. Narrow by
+ * design so tests can drive the loop without a real hub.
+ */
+export interface ActorPrincipalHealHub {
+  needsActorPrincipalHeal(connectionId: string): boolean;
+  fillClientActorPrincipalId(
+    connectionId: string,
+    actorPrincipalId: string,
+  ): void;
+}
+
+/**
+ * Delay before each attempt, in milliseconds. The leading zero dispatches the
+ * first attempt inline with the subscribe; the rest back off to cover a gateway
+ * that is slow to come up, without holding a timer for the life of a long-lived
+ * stream. Total span is about 44s.
+ */
+export const ACTOR_PRINCIPAL_HEAL_DELAYS_MS: readonly number[] = [
+  0, 1_000, 3_000, 10_000, 30_000,
+];
+
+/**
+ * Start the retrying heal for `connectionId`. Fire-and-forget: never awaited by
+ * the route, never delays the stream.
+ *
+ * `resolve` performs the daemon's own server-side guardian lookup, bypassing
+ * the guardian-delivery cache. The value must never come from client input. It
+ * may resolve `undefined` (no binding yet, or the gateway is unreachable) or
+ * reject; both count as a failed attempt.
+ */
+export function startActorPrincipalHeal(args: {
+  hub: ActorPrincipalHealHub;
+  connectionId: string;
+  resolve: () => Promise<string | undefined>;
+  /** Override the backoff schedule. Tests pass all-zero delays. */
+  delaysMs?: readonly number[];
+}): void {
+  const { hub, connectionId, resolve } = args;
+  const delays = args.delaysMs ?? ACTOR_PRINCIPAL_HEAL_DELAYS_MS;
+
+  void (async () => {
+    for (let attempt = 0; attempt < delays.length; attempt++) {
+      const delayMs = delays[attempt] ?? 0;
+      if (delayMs > 0) {
+        await sleep(delayMs);
+      }
+
+      // Re-check every pass: the connection may have closed, been replaced by a
+      // reconnect, or been healed by another path since the last one.
+      if (!hub.needsActorPrincipalHeal(connectionId)) {
+        return;
+      }
+
+      let resolved: string | undefined;
+      try {
+        resolved = await resolve();
+      } catch {
+        resolved = undefined;
+      }
+      if (resolved) {
+        hub.fillClientActorPrincipalId(connectionId, resolved);
+        return;
+      }
+    }
+
+    // Log the give-up so a principal-less subscription is greppable next to the
+    // same-actor rejections it causes, rather than surfacing only as opaque
+    // 403s on the client.
+    if (hub.needsActorPrincipalHeal(connectionId)) {
+      log.warn(
+        { connectionId, attempts: delays.length },
+        "gave up healing missing actorPrincipalId for client subscription; host-proxy results from this connection are rejected until it reconnects",
+      );
+    }
+  })();
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => {
+    const timer = setTimeout(resolve, ms);
+    // Never hold the process (or a test runner) open on a pending backoff.
+    (timer as { unref?: () => void }).unref?.();
+  });
+}

package/src/stt/__tests__/language-metadata.test.ts

@@ -0,0 +1,85 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  dominantLanguageTag,
+  rankLanguages,
+  voteDominantLanguage,
+} from "../language-metadata.js";
+
+describe("voteDominantLanguage", () => {
+  test("only the dominance-ranked first entry votes", () => {
+    const tally = new Map<string, number>();
+    voteDominantLanguage(tally, ["en", "es"]);
+    expect(tally.get("en")).toBe(1);
+    expect(tally.has("es")).toBe(false);
+  });
+
+  test("regional variants count toward their base subtag", () => {
+    const tally = new Map<string, number>();
+    voteDominantLanguage(tally, ["pt-BR"]);
+    voteDominantLanguage(tally, ["pt"]);
+    expect(tally.get("pt")).toBe(2);
+  });
+
+  test("underscore-separated variants count toward their base subtag", () => {
+    const tally = new Map<string, number>();
+    voteDominantLanguage(tally, ["hi_IN"]);
+    expect(tally.get("hi")).toBe(1);
+  });
+
+  test("blank and absent tags cast no vote", () => {
+    const tally = new Map<string, number>();
+    voteDominantLanguage(tally, undefined);
+    voteDominantLanguage(tally, []);
+    voteDominantLanguage(tally, ["  "]);
+    expect(tally.size).toBe(0);
+  });
+});
+
+describe("dominantLanguageTag", () => {
+  test("most votes wins", () => {
+    const tally = new Map([
+      ["en", 1],
+      ["es", 3],
+    ]);
+    expect(dominantLanguageTag(tally)).toBe("es");
+  });
+
+  test("ties break by first insertion", () => {
+    const tally = new Map([
+      ["hi", 2],
+      ["en", 2],
+    ]);
+    expect(dominantLanguageTag(tally)).toBe("hi");
+  });
+
+  test("undefined for an empty tally", () => {
+    expect(dominantLanguageTag(new Map())).toBeUndefined();
+  });
+});
+
+describe("rankLanguages", () => {
+  test("returns empty array for empty input", () => {
+    expect(rankLanguages([])).toEqual([]);
+  });
+
+  test("ranks by frequency, most frequent first", () => {
+    expect(rankLanguages(["es", "en", "en", "en", "es"])).toEqual(["en", "es"]);
+  });
+
+  test("breaks ties by first appearance", () => {
+    expect(rankLanguages(["hi", "en", "en", "hi"])).toEqual(["hi", "en"]);
+  });
+
+  test("counts regional variants toward their base subtag", () => {
+    expect(rankLanguages(["en-US", "es", "en", "en-GB"])).toEqual(["en", "es"]);
+  });
+
+  test("skips blank tags", () => {
+    expect(rankLanguages(["", "  ", "ja"])).toEqual(["ja"]);
+  });
+
+  test("accepts any iterable", () => {
+    expect(rankLanguages(new Set(["fr", "de"]))).toEqual(["fr", "de"]);
+  });
+});

package/src/stt/language-metadata.ts

@@ -0,0 +1,65 @@
+/**
+ * Pure helpers for tallying and ranking detected-language tags emitted
+ * by streaming STT providers (e.g. Deepgram nova-3 `multi` per-word tags).
+ *
+ * Tag normalization is `baseLanguageSubtag` (util/language-subtag.ts);
+ * these helpers layer vote-counting on top of it so provider adapters and
+ * event consumers share one notion of a dominant language.
+ */
+
+import { baseLanguageSubtag } from "../util/language-subtag.js";
+
+/**
+ * Cast one vote into a language tally for a transcript chunk's dominant
+ * detected language. `languages` is dominance-ranked, so only the first
+ * entry votes: secondary tags at full weight would let a minority
+ * language outvote the dominant one. Blank and absent tags cast no vote;
+ * regional variants count toward their base subtag.
+ */
+export function voteDominantLanguage(
+  tally: Map<string, number>,
+  languages: readonly string[] | undefined,
+): void {
+  const dominant = baseLanguageSubtag(languages?.[0]);
+  if (dominant !== undefined) {
+    tally.set(dominant, (tally.get(dominant) ?? 0) + 1);
+  }
+}
+
+/**
+ * The dominant tag in a language tally: most votes wins, ties break by
+ * first insertion (Map iteration is insertion order). Undefined for an
+ * empty tally.
+ */
+export function dominantLanguageTag(
+  tally: ReadonlyMap<string, number>,
+): string | undefined {
+  let dominant: string | undefined;
+  let dominantCount = 0;
+  for (const [tag, count] of tally) {
+    if (count > dominantCount) {
+      dominant = tag;
+      dominantCount = count;
+    }
+  }
+  return dominant;
+}
+
+/**
+ * Tally normalized language tags and return them most-frequent-first.
+ * Ties are broken by first appearance in the input. Blank tags are
+ * skipped; regional variants count toward their base subtag.
+ */
+export function rankLanguages(tags: Iterable<string>): string[] {
+  // Map iteration order is insertion order, so a stable sort by count
+  // leaves tied tags in first-appearance order.
+  const counts = new Map<string, number>();
+  for (const tag of tags) {
+    const normalized = baseLanguageSubtag(tag);
+    if (normalized === undefined) {
+      continue;
+    }
+    counts.set(normalized, (counts.get(normalized) ?? 0) + 1);
+  }
+  return [...counts.entries()].sort((a, b) => b[1] - a[1]).map(([tag]) => tag);
+}

package/src/stt/types.ts

@@ -263,6 +263,14 @@ export interface SttStreamServerPartialEvent {
    * provider does not surface confidence on interim chunks.
    */
   readonly confidence?: number;
+  /**
+   * All detected languages of this chunk in dominance order (first entry
+   * dominant), already normalized to lowercase base subtags (e.g. "en",
+   * "hi") by the emitting adapter; consumers must not re-normalize. Only
+   * providers with code-switching metadata (currently Deepgram nova-3
+   * `multi`) populate this. Absence means "unknown", never English.
+   */
+  readonly languages?: readonly string[];
 }
 
 /**
@@ -279,6 +287,14 @@ export interface SttStreamServerFinalEvent {
    * provider does not surface confidence on this chunk.
    */
   readonly confidence?: number;
+  /**
+   * All detected languages of this chunk in dominance order (first entry
+   * dominant), already normalized to lowercase base subtags (e.g. "en",
+   * "hi") by the emitting adapter; consumers must not re-normalize. Only
+   * providers with code-switching metadata (currently Deepgram nova-3
+   * `multi`) populate this. Absence means "unknown", never English.
+   */
+  readonly languages?: readonly string[];
   /**
    * True when this final is the flush response to
    * {@link StreamingTranscriber.finalizeUtterance} — i.e. it commits audio