@vellumai/assistant 0.10.8 → 0.10.9-dev.202607152225.ec6fdbf

package/src/providers/speech-to-text/vellum-managed-realtime.ts

@@ -0,0 +1,309 @@
+/**
+ * Managed realtime STT through the gateway's speech relay
+ * (gateway → velay → Deepgram; velay contact is gateway-only).
+ *
+ * Composes {@link DeepgramRealtimeTranscriber} — both relay legs speak
+ * Deepgram's live wire protocol verbatim, so all frame handling (Results
+ * parsing, backpressure, finalize/flush serialization) is inherited, not
+ * duplicated. This wrapper owns what is relay-specific:
+ *
+ * - Dialing the gateway (`/v1/speech/stt/stream`, `?key=` carries a
+ *   daemon-minted service token, no `model` param — the model is pinned
+ *   server-side).
+ * - Surfacing `velay_error` control frames (velay's own, or synthesized
+ *   by the gateway for upstream failures) as categorized SttErrors
+ *   instead of generic socket failures.
+ * - Transparent re-dial on velay's 30-minute session cap: live-voice
+ *   reuses ONE streaming transcriber across utterance cycles (#37662), so
+ *   a normal conversation can outlive the cap. Velay settles the in-flight
+ *   utterance (trailing finals arrive before the close), then this wrapper
+ *   opens a fresh relay session and continues without surfacing an error.
+ */
+
+import {
+  type StreamingTranscriber,
+  SttError,
+  type SttStreamServerEvent,
+} from "../../stt/types.js";
+import { getLogger } from "../../util/logger.js";
+import { DeepgramRealtimeTranscriber } from "./deepgram-realtime.js";
+import {
+  mapVelayError,
+  probeVelayRejection,
+  type SpeechRelayConnection,
+  type VelayErrorInfo,
+} from "./vellum-speech-relay-connection.js";
+
+const log = getLogger("vellum-managed-realtime");
+
+const STT_STREAM_PATH = "/v1/speech/stt/stream";
+
+export interface VellumManagedRealtimeOptions {
+  /** Audio sample rate in Hz (default: 16000). */
+  sampleRate?: number;
+  /** BCP-47 language code, forwarded to the relay. */
+  language?: string;
+  /**
+   * Emit `final` events only at utterance boundaries (telephony mode).
+   * Note: velay's param allowlist has no `utterance_end_ms`, so boundaries
+   * come from Deepgram's endpointing (`speech_final`) alone.
+   */
+  utteranceBoundaryFinals?: boolean;
+}
+
+export class VellumManagedRealtimeTranscriber implements StreamingTranscriber {
+  readonly providerId = "vellum" as const;
+  readonly boundaryId = "daemon-streaming" as const;
+
+  private readonly connection: SpeechRelayConnection;
+  private readonly options: VellumManagedRealtimeOptions;
+
+  private onEvent: ((event: SttStreamServerEvent) => void) | null = null;
+  /** The current relay session; null while re-dialing after a session cap. */
+  private inner: DeepgramRealtimeTranscriber | null = null;
+  /**
+   * The most recent `velay_error` frame from the current session. Set just
+   * before velay closes the socket; consumed when the inner adapter turns
+   * that close into an error event.
+   */
+  private pendingRelayError: VelayErrorInfo | null = null;
+  /**
+   * Set when the current session hit velay's duration cap: the swap to a
+   * fresh session is deferred to the capped session's `closed` event so
+   * its close cleanup (withheld finals, outstanding finalizes) drains
+   * through first.
+   */
+  private redialOnClose = false;
+  private stopping = false;
+  private closedEmitted = false;
+
+  constructor(
+    connection: SpeechRelayConnection,
+    options: VellumManagedRealtimeOptions = {},
+  ) {
+    this.connection = connection;
+    this.options = options;
+  }
+
+  async start(onEvent: (event: SttStreamServerEvent) => void): Promise<void> {
+    if (this.onEvent) {
+      throw new Error("VellumManagedRealtimeTranscriber: start() called twice");
+    }
+    this.onEvent = onEvent;
+    try {
+      const inner = await this.dial();
+      if (this.stopping) {
+        // stop() raced the initial dial: it saw no inner to tear down and
+        // already emitted closed, so the freshly opened relay session must
+        // not be kept (a leaked session keeps velay metering).
+        inner.stop();
+        return;
+      }
+      this.inner = inner;
+    } catch (err) {
+      // A failed WebSocket upgrade exposes no HTTP details; replay the
+      // request as a plain GET to recover the relay's {code, detail}
+      // rejection (the gateway replays its whole gate on non-upgrade
+      // requests, including velay's own).
+      const rejection = await probeVelayRejection(this.probeUrl());
+      if (rejection) {
+        // Typed so the stream session preserves the mapped category —
+        // an auth/setup failure must not surface as a provider outage.
+        const mapped = mapVelayError(rejection);
+        throw new SttError(mapped.category, mapped.message);
+      }
+      throw err;
+    }
+  }
+
+  sendAudio(audio: Buffer, mimeType: string): void {
+    // ponytail: audio arriving during a session-cap re-dial (sub-second) is
+    // dropped, mirroring the inner adapter's backpressure-drop semantics;
+    // buffer-and-replay if the gap ever proves audible.
+    this.inner?.sendAudio(audio, mimeType);
+  }
+
+  finalizeUtterance(): void {
+    if (this.inner) {
+      this.inner.finalizeUtterance();
+      return;
+    }
+    // No live session (re-dialing or closed) — nothing is buffered
+    // provider-side, so the flush is trivially complete.
+    this.emit({ type: "finalized" });
+  }
+
+  stop(): void {
+    if (this.stopping) {
+      return;
+    }
+    this.stopping = true;
+    if (this.inner) {
+      this.inner.stop();
+      return;
+    }
+    // Mid-redial stop: there is no session to drain.
+    this.emitClosedOnce();
+  }
+
+  // ── Relay session management ─────────────────────────────────────────
+
+  private async dial(): Promise<DeepgramRealtimeTranscriber> {
+    this.pendingRelayError = null;
+    // Fresh per dial — a session-cap re-dial happens ~30 minutes in, long
+    // after any previously minted token expired.
+    const inner = new DeepgramRealtimeTranscriber(
+      this.connection.mintServiceToken(),
+      {
+        baseUrl: this.connection.wsBaseUrl,
+        path: STT_STREAM_PATH,
+        queryAuth: true,
+        omitModelParam: true,
+        sampleRate: this.options.sampleRate,
+        ...(this.options.language ? { language: this.options.language } : {}),
+        ...(this.options.utteranceBoundaryFinals
+          ? { utteranceBoundaryFinals: true }
+          : {}),
+        onUnhandledFrame: (frame) => this.handleRelayFrame(frame),
+      },
+    );
+    await inner.start((event) => this.handleInnerEvent(inner, event));
+    return inner;
+  }
+
+  private probeUrl(): string {
+    const key = encodeURIComponent(this.connection.mintServiceToken());
+    return `${this.connection.httpBaseUrl}${STT_STREAM_PATH}?key=${key}`;
+  }
+
+  private handleRelayFrame(frame: Record<string, unknown>): void {
+    if (frame.type !== "velay_error" || typeof frame.code !== "string") {
+      return;
+    }
+    this.pendingRelayError = {
+      code: frame.code,
+      ...(typeof frame.detail === "string" ? { detail: frame.detail } : {}),
+    };
+    log.info(
+      { code: frame.code, detail: frame.detail },
+      "Received velay_error frame on managed STT relay",
+    );
+  }
+
+  private handleInnerEvent(
+    source: DeepgramRealtimeTranscriber,
+    event: SttStreamServerEvent,
+  ): void {
+    // Events from a superseded session (the one replaced by a re-dial)
+    // must not leak through — its close/error was already accounted for.
+    if (source !== this.inner) {
+      return;
+    }
+
+    if (event.type === "error") {
+      const relayError = this.pendingRelayError;
+      if (relayError?.code === "session_duration_exceeded") {
+        // Velay's 30-minute cap, not a failure. Swallow the error but keep
+        // the capped session current: its close cleanup still flushes
+        // withheld boundary finals and settles outstanding finalizes, and
+        // those events must drain before the swap. The re-dial happens on
+        // its `closed` event.
+        this.redialOnClose = !this.stopping;
+        return;
+      }
+      if (relayError) {
+        const mapped = mapVelayError(relayError);
+        this.emit({
+          type: "error",
+          category: mapped.category,
+          message: mapped.message,
+        });
+        return;
+      }
+      this.emit(event);
+      return;
+    }
+
+    if (event.type === "closed") {
+      if (this.redialOnClose && !this.stopping) {
+        this.redialOnClose = false;
+        this.beginRedial();
+        return;
+      }
+      this.emitClosedOnce();
+      return;
+    }
+
+    this.emit(event);
+  }
+
+  /**
+   * Replace the capped session with a fresh one. Detached — audio sent
+   * during the swap is dropped (see {@link sendAudio}); a dial failure is
+   * a real error and ends the stream.
+   */
+  private beginRedial(): void {
+    log.info("Managed STT relay session hit velay's duration cap — re-dialing");
+    this.inner = null;
+    void (async () => {
+      try {
+        const inner = await this.dial();
+        if (this.stopping) {
+          inner.stop();
+          return;
+        }
+        this.inner = inner;
+        log.info("Managed STT relay re-dial complete — session continues");
+      } catch (err) {
+        if (this.stopping) {
+          return;
+        }
+        // Same diagnosis as start(): a rejected upgrade hides the relay's
+        // {code, detail} — mid-call credit exhaustion or a revoked
+        // connection must surface with its mapped message, not a generic
+        // transport error.
+        const rejection = await probeVelayRejection(this.probeUrl());
+        if (rejection) {
+          const mapped = mapVelayError(rejection);
+          this.emit({
+            type: "error",
+            category: mapped.category,
+            message: mapped.message,
+          });
+        } else {
+          this.emit({
+            type: "error",
+            category: "provider-error",
+            message: `Managed speech relay re-dial failed after the session cap: ${
+              err instanceof Error ? err.message : String(err)
+            }`,
+          });
+        }
+        this.emitClosedOnce();
+      }
+    })();
+  }
+
+  // ── Event emission ───────────────────────────────────────────────────
+
+  private emit(event: SttStreamServerEvent): void {
+    if (!this.onEvent || this.closedEmitted) {
+      return;
+    }
+    if (event.type === "closed") {
+      this.closedEmitted = true;
+    }
+    try {
+      this.onEvent(event);
+    } catch (err) {
+      log.warn(
+        { error: err },
+        "Listener error in vellum managed realtime adapter",
+      );
+    }
+  }
+
+  private emitClosedOnce(): void {
+    this.emit({ type: "closed" });
+  }
+}

package/src/providers/speech-to-text/vellum-managed.ts

@@ -0,0 +1,71 @@
+/**
+ * Vellum-managed batch STT: transcription through the platform's managed
+ * speech endpoint (Vellum-held Deepgram key, billed to Vellum credits). No
+ * provider API key exists on this machine — availability is the platform
+ * connection itself.
+ */
+
+import {
+  managedSpeechAvailable,
+  type ManagedSpeechResult,
+  managedSpeechTranscribe,
+} from "../../platform/managed-speech.js";
+import { SttError, type SttTranscribeResult } from "../../stt/types.js";
+
+type ManagedSpeechFailure = Extract<ManagedSpeechResult<never>, { ok: false }>;
+
+/**
+ * Whether managed speech can be used at all: a platform connection with a
+ * platform assistant ID. The credential-store lookup used for API-key
+ * providers does not apply to `vellum`.
+ */
+export async function vellumManagedSpeechAvailable(): Promise<boolean> {
+  return managedSpeechAvailable();
+}
+
+/**
+ * Map a managed-speech failure onto the normalized STT error categories.
+ *
+ * `insufficient_balance` gets a user-actionable message — the fix is topping
+ * up Vellum credits, not editing provider config.
+ */
+export function sttErrorFromManagedSpeech(
+  failure: ManagedSpeechFailure,
+): SttError {
+  if (failure.kind === "unavailable") {
+    return new SttError("auth", failure.message);
+  }
+  if (failure.code === "insufficient_balance") {
+    return new SttError(
+      "provider-error",
+      "Vellum credits are exhausted — add funds to your Vellum account to continue using managed transcription.",
+    );
+  }
+  switch (failure.status) {
+    case 401:
+    case 403:
+      return new SttError("auth", failure.message);
+    case 429:
+      return new SttError("rate-limit", failure.message);
+    case 413:
+      return new SttError("invalid-audio", failure.message);
+    default:
+      return new SttError("provider-error", failure.message);
+  }
+}
+
+/**
+ * Transcribe a complete audio buffer via the platform. Throws {@link SttError}
+ * on failure (already normalized — `normalizeSttError` passes it through).
+ */
+export async function vellumManagedTranscribe(
+  audio: Buffer,
+  mimeType: string,
+  signal?: AbortSignal,
+): Promise<SttTranscribeResult> {
+  const result = await managedSpeechTranscribe({ audio, mimeType, signal });
+  if (!result.ok) {
+    throw sttErrorFromManagedSpeech(result);
+  }
+  return { text: result.value.text };
+}

package/src/providers/speech-to-text/vellum-speech-relay-connection.ts

@@ -0,0 +1,174 @@
+/**
+ * Shared plumbing for dialing the GATEWAY's managed speech relay
+ * (`/v1/speech/{stt,tts}/stream`): connection resolution, and mapping the
+ * relay's error contract onto SttError categories.
+ *
+ * The daemon never dials velay itself — velay contact is gateway-only so
+ * deterministic policy stays in a process the agent cannot rewrite. The
+ * gateway route authenticates the daemon with a self-minted service JWT
+ * (both processes share the HMAC signing key), attaches the Vellum
+ * assistant API key on its own upstream leg to velay, and pipes Deepgram
+ * wire frames verbatim. The gateway mirrors velay's error contract:
+ * rejections are JSON `{code, detail}` bodies, and mid-session failures
+ * are one `velay_error` text frame followed by an abnormal close.
+ */
+
+import { getGatewayInternalBaseUrl } from "../../config/env.js";
+import { CURRENT_POLICY_EPOCH } from "../../runtime/auth/policy.js";
+import { mintToken } from "../../runtime/auth/token-service.js";
+import type { SttErrorCategory } from "../../stt/types.js";
+import { getLogger } from "../../util/logger.js";
+
+const log = getLogger("vellum-speech-relay");
+
+/**
+ * The principal the gateway's speech-relay route accepts. Must match
+ * DAEMON_SERVICE_SUB in gateway/src/http/routes/speech-relay-websocket.ts
+ * — the packages don't share auth constants.
+ */
+const DAEMON_SERVICE_SUB = "svc:daemon:self";
+
+/**
+ * Per-dial token TTL. Deliberately short: the gateway validates at
+ * upgrade time only, and every (re-)dial mints fresh — a session that
+ * outlives its token (velay caps at 30 minutes) is fine, but a re-dial
+ * must never reuse one.
+ */
+const RELAY_TOKEN_TTL_SECONDS = 300;
+
+export interface SpeechRelayConnection {
+  /** ws(s) origin of the gateway for the relay WebSocket dial. */
+  wsBaseUrl: string;
+  /** http(s) origin of the gateway for diagnostic (non-upgrade) probes. */
+  httpBaseUrl: string;
+  /**
+   * Mint a fresh daemon service token for one dial. Called per
+   * connection attempt so session-cap re-dials never present an expired
+   * token.
+   */
+  mintServiceToken: () => string;
+}
+
+/**
+ * Resolve everything needed to dial the gateway's speech relay, or null
+ * when the daemon cannot mint a service token (signing key unavailable) —
+ * the availability signal for the streaming resolver.
+ */
+export async function resolveSpeechRelayConnection(): Promise<SpeechRelayConnection | null> {
+  const mintServiceToken = () =>
+    mintToken({
+      aud: "vellum-gateway",
+      sub: DAEMON_SERVICE_SUB,
+      scope_profile: "gateway_service_v1",
+      policy_epoch: CURRENT_POLICY_EPOCH,
+      ttlSeconds: RELAY_TOKEN_TTL_SECONDS,
+    });
+  try {
+    // Fail here, not mid-dial, when the signing key is unavailable.
+    mintServiceToken();
+  } catch (err) {
+    log.warn(
+      { error: err instanceof Error ? err.message : String(err) },
+      "Managed speech relay unavailable: cannot mint a gateway service token",
+    );
+    return null;
+  }
+  const httpBaseUrl = getGatewayInternalBaseUrl().replace(/\/+$/, "");
+  return {
+    httpBaseUrl,
+    wsBaseUrl: httpBaseUrl.replace(/^http/, "ws"),
+    mintServiceToken,
+  };
+}
+
+/** The relay's error contract: HTTP reject bodies and velay_error frames. */
+export interface VelayErrorInfo {
+  code: string;
+  detail?: string;
+}
+
+/**
+ * Map a relay error code onto an SttError category and a user-actionable
+ * message. Codes are velay's contract plus the gateway route's own
+ * (`missing_platform_connection`, `invalid_token`) — unknown codes degrade
+ * to a provider error carrying the code for diagnosability.
+ */
+export function mapVelayError(error: VelayErrorInfo): {
+  category: SttErrorCategory;
+  message: string;
+} {
+  switch (error.code) {
+    case "invalid_key":
+      return {
+        category: "auth",
+        message:
+          "The Vellum speech relay rejected this assistant's API key — the assistant's platform environment may not match the relay it is dialing (set VELAY_BASE_URL on the gateway to the matching environment, e.g. https://velay-staging.vellum.ai for staging).",
+      };
+    case "missing_platform_connection":
+      return {
+        category: "auth",
+        message:
+          "Managed speech needs a working Vellum platform connection — reconnect with 'assistant platform connect'.",
+      };
+    case "invalid_token":
+      return {
+        category: "auth",
+        message:
+          "The assistant's managed-speech session was rejected by its gateway — the services may be out of sync; restart the assistant.",
+      };
+    case "insufficient_balance":
+      return {
+        category: "provider-error",
+        message:
+          "Managed speech is paused: your Vellum organization is out of credits. Top up credits to continue.",
+      };
+    case "provider_unreachable":
+    case "upstream_error":
+      return {
+        category: "provider-error",
+        message: `Managed speech relay could not reach the speech provider (${error.code}).`,
+      };
+    default:
+      return {
+        category: "provider-error",
+        message: `Managed speech relay error: ${error.code}${
+          error.detail ? ` — ${error.detail}` : ""
+        }`,
+      };
+  }
+}
+
+/**
+ * Diagnose a failed WebSocket dial by replaying the request as a plain
+ * HTTP GET. The gateway route runs its whole gate on non-upgrade requests
+ * (token, stored credential, then velay's own gate via an upstream probe),
+ * so a rejected upgrade reproduces as a JSON `{code, detail}` body; a
+ * request that passes everything returns a 426 whose body is ignored here
+ * (null → the original failure was transient/transport-level).
+ *
+ * The WebSocket API exposes no HTTP response details on a failed upgrade,
+ * so this probe is the only way to distinguish "bad connection state"
+ * from "gateway down".
+ */
+export async function probeVelayRejection(
+  httpUrl: string,
+): Promise<VelayErrorInfo | null> {
+  try {
+    const res = await fetch(httpUrl, {
+      signal: AbortSignal.timeout(5_000),
+    });
+    if (res.ok || res.status === 426) {
+      return null;
+    }
+    const body = (await res.json()) as { code?: unknown; detail?: unknown };
+    if (typeof body.code !== "string") {
+      return null;
+    }
+    return {
+      code: body.code,
+      ...(typeof body.detail === "string" ? { detail: body.detail } : {}),
+    };
+  } catch {
+    return null;
+  }
+}

package/src/providers/types.ts

@@ -215,7 +215,8 @@ export interface SendMessageConfig {
    * LLM call-site identifier. `RetryProvider` resolves
    * provider/model/maxTokens/effort/speed/verbosity/temperature/thinking/
    * contextWindow via `resolveCallSiteConfig(callSite, config.llm)`, falling
-   * back to `llm.default` when no callSite-specific entry is present.
+   * back to the shipped call-site defaults when no callSite-specific entry
+   * is present.
    */
   callSite?: LLMCallSite;
   /**
@@ -246,6 +247,18 @@ export interface SendMessageConfig {
    * stripped before any provider wire request.
    */
   selectionSeed?: string;
+  /**
+   * Per-conversation prompt-cache key for providers with explicit prompt
+   * caching (sent as the OpenAI `prompt_cache_key` request param). Set by
+   * `RetryProvider` from `selectionSeed` (the durable conversation id) for
+   * the `openai` and `openrouter` providers — GPT-5.6+ requires the key for
+   * reliable breakpoint matching, and OpenAI's ~15 req/min-per-key routing
+   * guidance is satisfied by per-conversation ids. A non-wire field for
+   * every other provider client (the Anthropic client strips it, covering
+   * OpenRouter's `anthropic/*` delegation); the request param is omitted
+   * when absent.
+   */
+  promptCacheKey?: string;
   /**
    * Internal per-request HTTP headers for managed-proxy usage attribution.
    * Provider clients may pass these through SDK request options only when the
@@ -421,11 +434,17 @@ export function extractOverflowTokensFromMessage(message: string): {
   maxTokens?: number;
 } {
   const match = message.match(/(\d[\d,]*)\s*(?:tokens?\s*)?[>≥]\s*(\d[\d,]*)/i);
-  if (!match) return {};
+  if (!match) {
+    return {};
+  }
   const actual = parseInt(match[1].replace(/,/g, ""), 10);
   const max = parseInt(match[2].replace(/,/g, ""), 10);
   const out: { actualTokens?: number; maxTokens?: number } = {};
-  if (!isNaN(actual) && actual > 0) out.actualTokens = actual;
-  if (!isNaN(max) && max > 0) out.maxTokens = max;
+  if (!isNaN(actual) && actual > 0) {
+    out.actualTokens = actual;
+  }
+  if (!isNaN(max) && max > 0) {
+    out.maxTokens = max;
+  }
   return out;
 }

package/src/providers/vellum-model-routing.test.ts

@@ -2,6 +2,7 @@ import { describe, expect, test } from "bun:test";
 
 import {
   formatVellumModel,
+  getManagedUpstream,
   MANAGED_ROUTABLE_PROVIDERS,
   parseVellumModel,
 } from "./vellum-model-routing.js";
@@ -38,6 +39,31 @@ describe("vellum-model-routing", () => {
     expect(parseVellumModel("/foo")).toBeNull(); // empty provider
   });
 
+  test("getManagedUpstream resolves a bare catalog id to its owner", () => {
+    expect(getManagedUpstream("claude-fable-5")).toBe("anthropic");
+  });
+
+  test("getManagedUpstream resolves a routing string by its prefix", () => {
+    expect(
+      getManagedUpstream("fireworks/accounts/fireworks/models/minimax-m3"),
+    ).toBe("fireworks");
+  });
+
+  test("getManagedUpstream returns null for non-managed owners", () => {
+    expect(getManagedUpstream("MiniMax-M3")).toBeNull(); // minimax, not managed
+    expect(getManagedUpstream("openrouter/whatever")).toBeNull();
+  });
+
+  test("getManagedUpstream returns null for unknown models", () => {
+    expect(getManagedUpstream("not-a-real-model")).toBeNull();
+    expect(getManagedUpstream("")).toBeNull();
+  });
+
+  test("getManagedUpstream rejects managed-prefixed strings whose model is not cataloged under that provider", () => {
+    expect(getManagedUpstream("anthropic/definitely-not-a-model")).toBeNull();
+    expect(getManagedUpstream("openai/accounts/foo/bar")).toBeNull();
+  });
+
   test("managed set matches the platform proxy table", () => {
     // Guards against drift if PLATFORM_PROVIDER_META changes.
     expect([...MANAGED_ROUTABLE_PROVIDERS].sort()).toEqual([

package/src/providers/vellum-model-routing.ts

@@ -14,6 +14,10 @@
  * codec — no I/O, no wiring — so it can be adopted incrementally.
  */
 
+import {
+  getCatalogProviderForModel,
+  isModelInCatalog,
+} from "./model-catalog.js";
 import { PLATFORM_PROVIDER_META } from "./platform-proxy/constants.js";
 
 /**
@@ -117,3 +121,29 @@ export function parseVellumModel(
   }
   return { provider, model };
 }
+
+/**
+ * Resolve the managed upstream provider for a model referenced by a
+ * `provider: "vellum"` profile. Such a profile carries no upstream of its own,
+ * so the model alone determines it: a `<provider>/<model>` routing string
+ * names the upstream directly, and a bare id resolves to its catalog owner.
+ * Returns null when the model has no managed-routable upstream (unknown id,
+ * or owned by a non-managed provider like openrouter).
+ *
+ * A decoded routing string must also name a real catalog model under its
+ * prefix: OpenRouter/Vercel native ids share the `<provider>/<model>` shape
+ * (e.g. `anthropic/…`), so an unvalidated prefix match could route an
+ * arbitrary non-managed id through the managed proxy.
+ */
+export function getManagedUpstream(model: string): string | null {
+  const route = parseVellumModel(model);
+  if (route) {
+    return isModelInCatalog(route.provider, route.model)
+      ? route.provider
+      : null;
+  }
+  const owner = getCatalogProviderForModel(model);
+  return owner !== undefined && MANAGED_ROUTABLE_PROVIDERS.has(owner)
+    ? owner
+    : null;
+}

package/src/runtime/AGENTS.md

@@ -154,7 +154,7 @@ All CDP-backed browser tools (`browser_navigate`, `browser_snapshot`, `browser_s
 Channel approval flows use `requestId` (not `runId`) as the primary identifier:
 
 - Telegram callback buttons encode `apr:<requestId>:<action>` in `callback_data`.
-- Guardian approval records in `canonicalGuardianRequests` (and their `canonicalGuardianDeliveries`) link via `requestId`.
+- Guardian approval records in the gateway-owned `guardian_requests` table (and their `guardian_request_deliveries`) link via `requestId`; the daemon reads/writes them through the `channels/gateway-guardian-requests.ts` client.
 - The conversational approval engine classifies user intent and resolves via `conversation.handleConfirmationResponse(requestId, decision)`.
 
 ### Channel verification: gateway-owned