@vellumai/assistant 0.11.2 → 0.11.3-staging.2

package/src/providers/inference/connection-availability.ts

@@ -1,36 +1,61 @@
 /**
  * Shared availability computation for a (provider, connection) pair: whether
  * the connection exists, carries a usable credential, and can actually serve
- * the provider. The status is reported, never enforced — a dangling or
+ * the provider.
+ *
+ * On read paths the status is reported, not enforced — a dangling or
  * uncredentialed connection is a valid persisted state that surfaces an
- * explainable error at dispatch time.
+ * explainable error at dispatch time. The dedicated inference-profile write
+ * routes (create / update / set-active / conversation-scoped pin) are the
+ * exception: they refuse to persist a selection that provably cannot dispatch,
+ * because those writes are what a chat turn resolves through. Generic
+ * `config set` writes and dispatch itself stay report-only.
  *
  * Consumed by the default-provider status route (`llm.defaultProvider`) and
- * the inference-profile list route (per-profile `provider_connection`) so the
- * two never drift.
+ * the inference-profile routes (per-profile availability) so the two never
+ * drift.
  */
 
 import { getDb } from "../../persistence/db-connection.js";
 import { credentialKey } from "../../security/credential-key.js";
 import { getSecureKeyResultAsync } from "../../security/secure-keys.js";
+import {
+  describeSubscriptionModelIncompatibility,
+  isConnectionCompatibleWithModel,
+} from "../connection-model-compat.js";
 import { PROVIDER_CATALOG } from "../model-catalog.js";
 import { resolveManagedProxyContext } from "../platform-proxy/context.js";
+import {
+  ConnectionResolutionError,
+  resolveRoutingIdentity,
+} from "../routing-identity.js";
 import {
   isVellumManagedConnection,
   MANAGED_ROUTABLE_PROVIDERS,
   VELLUM_MANAGED_CONNECTION_NAME,
   VELLUM_MANAGED_PROVIDER,
 } from "../vellum-model-routing.js";
-import { getConnection } from "./connections.js";
+import { ROUTING_IDENTITY_PROVIDERS } from "./auth.js";
+import { getConnection, listConnections } from "./connections.js";
+
+/**
+ * Every availability verdict, in one place. Route schemas build their zod
+ * enums from this rather than restating it, so a new status reaches the wire
+ * for every surface at once instead of drifting between them.
+ */
+export const CONNECTION_AVAILABILITY_STATUSES = [
+  "ok",
+  "incomplete",
+  "missing_connection",
+  "missing_credential",
+  "provider_mismatch",
+  "unsupported_auth",
+  "vellum_unauthenticated",
+  "unknown",
+] as const;
 
 export type ConnectionAvailabilityStatus =
-  | "ok"
-  | "missing_connection"
-  | "missing_credential"
-  | "provider_mismatch"
-  | "unsupported_auth"
-  | "vellum_unauthenticated"
-  | "unknown";
+  (typeof CONNECTION_AVAILABILITY_STATUSES)[number];
 
 export interface ConnectionAvailability {
   status: ConnectionAvailabilityStatus;
@@ -204,3 +229,130 @@ export async function computeConnectionAvailability(
     }
   }
 }
+
+/**
+ * Statuses that mean a profile provably cannot serve a request. `unknown` is
+ * excluded on purpose: it means the credential store could not be reached, not
+ * that the credential is absent, and treating a CES outage as a broken profile
+ * would block writes that are actually fine.
+ */
+const UNAVAILABLE_STATUSES: ReadonlySet<ConnectionAvailabilityStatus> = new Set(
+  [
+    // A profile with no provider and model of its own is skipped by the
+    // resolver on every turn, so it provably cannot serve a request. It
+    // belongs here for the same reason the connection failures do: pinning
+    // one silently runs a different profile than the user selected.
+    "incomplete",
+    "missing_connection",
+    "missing_credential",
+    "provider_mismatch",
+    "unsupported_auth",
+    "vellum_unauthenticated",
+  ],
+);
+
+/** Whether an availability verdict means dispatch would provably fail. */
+export function isUnavailable(
+  availability: ConnectionAvailability | null,
+): boolean {
+  return availability !== null && UNAVAILABLE_STATUSES.has(availability.status);
+}
+
+/**
+ * Availability of a whole effective profile entry, judged the way dispatch
+ * judges it:
+ *
+ *   - routing identities (`vellum`, `chatgpt`) resolve to their canonical row
+ *     and derived upstream;
+ *   - a pinned `provider_connection` is judged directly;
+ *   - a provider with no pinned connection is judged against the connection
+ *     dispatch would auto-resolve (an active, model-compatible row for that
+ *     provider) — with no such row, the profile cannot serve requests.
+ *
+ * Returns null when there is nothing to judge: a mix carries no provider or
+ * model of its own, because the resolver expands it to a seeded arm and
+ * judges that arm instead.
+ */
+export async function computeProfileAvailability(
+  entry: Record<string, unknown>,
+): Promise<ConnectionAvailability | null> {
+  const provider = entry.provider;
+  const model = typeof entry.model === "string" ? entry.model : undefined;
+
+  // A rung only wins if its profile carries BOTH a provider and a model (see
+  // `usableEntry` in config/llm-resolver.ts); one without them is skipped as
+  // "incomplete" and the call site quietly resolves elsewhere. Report that so
+  // clients can show it rather than presenting the profile as healthy.
+  if (typeof provider !== "string" || model === undefined) {
+    if (entry.mix != null) {
+      return null;
+    }
+    const missing =
+      typeof provider !== "string"
+        ? model === undefined
+          ? "a provider and a model"
+          : "a provider"
+        : "a model";
+    // Which profile a call site falls back to depends on the call site (its
+    // shipped intent, then the balanced anchor), so this names the effect
+    // without claiming a destination it cannot know.
+    return {
+      status: "incomplete",
+      message: `Missing ${missing}, so actions using it fall back to another profile.`,
+    };
+  }
+
+  // Routing-identity profiles carry no provider_connection. A model the
+  // identity cannot route reports as a mismatch rather than throwing —
+  // availability annotates, it must not fail the profiles read.
+  if (ROUTING_IDENTITY_PROVIDERS.has(provider)) {
+    try {
+      const identity = resolveRoutingIdentity(provider, model);
+      if (!identity) {
+        return null;
+      }
+      return await computeConnectionAvailability(
+        identity.expectedProvider,
+        identity.connectionName,
+      );
+    } catch (err) {
+      return {
+        status: "provider_mismatch",
+        message:
+          err instanceof ConnectionResolutionError
+            ? err.message
+            : `Model "${model ?? "<unset>"}" cannot be routed by provider "${provider}".`,
+      };
+    }
+  }
+
+  const pinned = entry.provider_connection;
+  if (typeof pinned === "string") {
+    return computeConnectionAvailability(provider, pinned);
+  }
+
+  // Mirror the dispatch-time auto-resolve (`resolveConfiguredProvider`): with
+  // no pinned connection, the first active model-compatible row for the
+  // provider serves the request, and none means dispatch returns no provider.
+  let candidates;
+  try {
+    candidates = listConnections(getDb(), { provider });
+  } catch {
+    return {
+      status: "unknown",
+      message: `Connections for provider "${provider}" could not be looked up. Try again shortly.`,
+    };
+  }
+  const active = candidates.find((candidate) =>
+    isConnectionCompatibleWithModel(candidate, model),
+  );
+  if (active) {
+    return computeConnectionAvailability(provider, active.name);
+  }
+  return {
+    status: "missing_connection",
+    message:
+      describeSubscriptionModelIncompatibility(candidates, model) ??
+      `Provider "${provider}" is a valid provider id, but no ${provider} connection/API key is configured, so this profile cannot serve requests.`,
+  };
+}

package/src/providers/inference/connections.ts

@@ -163,6 +163,14 @@ export type CreateConnectionInput = {
 
 export type UpdateConnectionInput = {
   auth: Auth;
+  /**
+   * Optional provider correction. The HTTP PATCH route never passes this
+   * (provider is immutable there); it exists for owners of well-known rows
+   * to keep the provider truthful when they rewrite the auth, e.g. the
+   * ChatGPT sign-in flow stamping "openai" on the subscription row so a
+   * claiming row with a different provider cannot strand the fresh token.
+   */
+  provider?: string;
   label?: string | null;
   baseUrl?: string | null;
   models?: ConnectionModel[] | null;
@@ -178,6 +186,7 @@ export type ConnectionCreateError =
 export type ConnectionUpdateError =
   | { code: "not_found" }
   | { code: "invalid_auth" }
+  | { code: "invalid_provider"; provider: string }
   | { code: "base_url_required" }
   | { code: "models_required" };
 
@@ -278,12 +287,23 @@ export function updateConnection(
     return { ok: false, error: { code: "invalid_auth" } };
   }
 
+  if (
+    input.provider !== undefined &&
+    !VALID_CONNECTION_PROVIDERS.includes(input.provider as never)
+  ) {
+    return {
+      ok: false,
+      error: { code: "invalid_provider", provider: input.provider },
+    };
+  }
+  const nextProvider = input.provider ?? existing.provider;
+
   const nextBaseUrl =
     input.baseUrl !== undefined ? input.baseUrl : existing.baseUrl;
   const nextModels =
     input.models !== undefined ? input.models : existing.models;
 
-  if (PROVIDERS_REQUIRING_BASE_URL_AND_MODELS.has(existing.provider)) {
+  if (PROVIDERS_REQUIRING_BASE_URL_AND_MODELS.has(nextProvider)) {
     if (!nextBaseUrl) {
       return { ok: false, error: { code: "base_url_required" } };
     }
@@ -296,10 +316,14 @@ export function updateConnection(
   const setClause: {
     auth: string;
     updatedAt: number;
+    provider?: string;
     label?: string | null;
     baseUrl?: string | null;
     models?: string | null;
   } = { auth: JSON.stringify(auth), updatedAt: now };
+  if (input.provider !== undefined) {
+    setClause.provider = input.provider;
+  }
   if (input.label !== undefined) {
     setClause.label = input.label;
   }

package/src/providers/media-resolve.ts

@@ -96,7 +96,7 @@ export function resolveMediaSourceData(
   return { data: bytes.toString("base64"), media_type: source.media_type };
 }
 
-function resolveImageBlock(block: ImageContent): ContentBlock {
+async function resolveImageBlock(block: ImageContent): Promise<ContentBlock> {
   if (block.source.type === "base64") {
     return block;
   }
@@ -113,7 +113,7 @@ function resolveImageBlock(block: ImageContent): ContentBlock {
   }
   // Apply the same transport optimization the inline-base64 path used, so a
   // reloaded (reference) turn sends the model the same bytes a live turn would.
-  const { data, mediaType } = optimizeImageForTransport(
+  const { data, mediaType } = await optimizeImageForTransport(
     bytes.toString("base64"),
     block.source.media_type,
   );
@@ -161,7 +161,7 @@ function resolveFileBlock(block: FileContent): ContentBlock {
   };
 }
 
-function resolveBlock(block: ContentBlock): ContentBlock {
+async function resolveBlock(block: ContentBlock): Promise<ContentBlock> {
   switch (block.type) {
     case "image":
       return resolveImageBlock(block);
@@ -172,7 +172,10 @@ function resolveBlock(block: ContentBlock): ContentBlock {
       if (!block.contentBlocks?.length) {
         return block;
       }
-      return { ...block, contentBlocks: block.contentBlocks.map(resolveBlock) };
+      return {
+        ...block,
+        contentBlocks: await Promise.all(block.contentBlocks.map(resolveBlock)),
+      };
     }
     default:
       return block;
@@ -197,11 +200,18 @@ function contentHasReference(content: ContentBlock[]): boolean {
  * (same object reference) so the common all-base64 live turn does no allocation
  * or disk I/O.
  */
-export function resolveMediaReferences(messages: Message[]): Message[] {
-  return messages.map((message) => {
-    if (!contentHasReference(message.content)) {
-      return message;
-    }
-    return { ...message, content: message.content.map(resolveBlock) };
-  });
+export function resolveMediaReferences(
+  messages: Message[],
+): Promise<Message[]> {
+  return Promise.all(
+    messages.map(async (message) => {
+      if (!contentHasReference(message.content)) {
+        return message;
+      }
+      return {
+        ...message,
+        content: await Promise.all(message.content.map(resolveBlock)),
+      };
+    }),
+  );
 }

package/src/providers/model-catalog.ts

@@ -2233,6 +2233,21 @@ export function getCatalogProviderForModel(
     ?.id;
 }
 
+/**
+ * Human-readable display name for a model id, from the first catalog entry
+ * that serves it (a model carries the same display name under every provider
+ * that offers it). Undefined for uncataloged ids.
+ */
+export function getModelDisplayName(modelId: string): string | undefined {
+  for (const provider of PROVIDER_CATALOG) {
+    const match = provider.models.find((m) => m.id === modelId);
+    if (match) {
+      return match.displayName;
+    }
+  }
+  return undefined;
+}
+
 /**
  * Whether the given model only supports adaptive (always-on) thinking, driven
  * by the `adaptiveThinkingOnly` capability in the catalog. Matches the model ID

package/src/providers/openai/chat-completions-provider.ts

@@ -383,7 +383,7 @@ export class OpenAIChatCompletionsProvider implements Provider {
     const coercedObjectKeys = new Map<string, string[]>();
 
     try {
-      const openaiMessages = this.toOpenAIMessages(
+      const openaiMessages = await this.toOpenAIMessages(
         messages,
         systemPrompt,
         modelSupportsAudioInput(modelOverride ?? this.model),
@@ -940,14 +940,14 @@ export class OpenAIChatCompletionsProvider implements Provider {
   }
 
   /** Convert neutral messages + system prompt to OpenAI message format. */
-  private toOpenAIMessages(
+  private async toOpenAIMessages(
     messages: Message[],
     systemPrompt?: string,
     audioInputEnabled = false,
-  ): OpenAI.Chat.Completions.ChatCompletionMessageParam[] {
+  ): Promise<OpenAI.Chat.Completions.ChatCompletionMessageParam[]> {
     // Swap any persisted attachment references back to inline base64 before
     // serializing, so the block transforms below can read `source.data`.
-    messages = resolveMediaReferences(messages);
+    messages = await resolveMediaReferences(messages);
     const result: OpenAI.Chat.Completions.ChatCompletionMessageParam[] = [];
 
     if (systemPrompt) {

package/src/providers/openai/responses-provider.ts

@@ -231,8 +231,6 @@ export class OpenAIResponsesProvider implements Provider {
     const usageAttributionHeaders = configObj?.usageAttributionHeaders as
       | Record<string, string>
       | undefined;
-    const mutableLatestUserMessage =
-      configObj?.mutableLatestUserMessage === true;
     const disableCache = configObj?.disableCache === true;
     const disableTurnStartCache = configObj?.disableTurnStartCache === true;
     const promptCacheKey =
@@ -244,7 +242,7 @@ export class OpenAIResponsesProvider implements Provider {
     try {
       const effectiveModel = modelOverride ?? this.model;
       recordProviderRequestDiagnostics({ model_id: effectiveModel });
-      const input = this.toResponsesInput(messages);
+      const input = await this.toResponsesInput(messages);
 
       const params: Record<string, unknown> = {
         model: effectiveModel,
@@ -273,8 +271,8 @@ export class OpenAIResponsesProvider implements Provider {
 
       // Explicit prompt-cache mode (GPT-5.6+ semantics, direct API only).
       // Explicit mode disables the implicit latest-message breakpoint — under
-      // implicit mode a volatile latest user message (mutableLatestUserMessage)
-      // makes every cached entry end at content that never recurs: zero reads
+      // implicit mode a volatile latest user message makes every cached entry
+      // end at content that never recurs across turns: zero reads
       // plus a full-prompt 1.25x write per turn. With explicit markers we
       // choose the stable boundaries ourselves. Under `disableCache` we still
       // send explicit mode but stamp no markers: a request with no explicit
@@ -288,10 +286,7 @@ export class OpenAIResponsesProvider implements Provider {
       ) {
         params.prompt_cache_options = { mode: "explicit" };
         if (!disableCache) {
-          this.applyPromptCacheBreakpoints(input, {
-            mutableLatestUserMessage,
-            disableTurnStartCache,
-          });
+          this.applyPromptCacheBreakpoints(input, { disableTurnStartCache });
         }
       }
 
@@ -753,10 +748,10 @@ export class OpenAIResponsesProvider implements Provider {
    *
    * System prompt is NOT included here — it goes into the `instructions` param.
    */
-  private toResponsesInput(messages: Message[]): unknown[] {
+  private async toResponsesInput(messages: Message[]): Promise<unknown[]> {
     // Swap any persisted attachment references back to inline base64 before
     // serializing, so the block transforms below can read `source.data`.
-    messages = resolveMediaReferences(messages);
+    messages = await resolveMediaReferences(messages);
     const result: unknown[] = [];
 
     // `call_id`s emitted as `function_call` items earlier in this request.
@@ -788,8 +783,11 @@ export class OpenAIResponsesProvider implements Provider {
    * historical user-message boundaries makes the newest still-matching one
    * the read point; in the volatile-latest-message flow that is typically
    * the previous turn's user message once it re-renders without its
-   * injected block. Marking the volatile latest item itself prepays its
-   * write so in-turn tool-loop iterations read it back. The ladder is
+   * injected block. Every markable item is marked, including a volatile
+   * latest user message that is the only one on a first turn: a volatile
+   * message is still fixed within its own turn, so marking it prepays one
+   * write that every in-turn tool-loop iteration reads back, and cross-turn
+   * the ladder re-marks whichever boundaries recur. The ladder is
    * cost-safe: OpenAI writes at most the latest four unmatched marked
    * boundaries per request and considers up to the latest 50 markers for
    * reads. All breakpoints share the fixed 30m TTL (no `ttl` field is
@@ -811,7 +809,7 @@ export class OpenAIResponsesProvider implements Provider {
    */
   private applyPromptCacheBreakpoints(
     input: unknown[],
-    opts: { mutableLatestUserMessage: boolean; disableTurnStartCache: boolean },
+    opts: { disableTurnStartCache: boolean },
   ): void {
     const items = input as ResponsesMessageItem[];
 
@@ -866,17 +864,6 @@ export class OpenAIResponsesProvider implements Provider {
       return;
     }
 
-    // A volatile latest user message with no prior user message to anchor
-    // on: every marker would be a write whose prefix never recurs across
-    // turns — skip caching entirely for this request.
-    if (
-      opts.mutableLatestUserMessage &&
-      candidates.length === 1 &&
-      candidates[0] === items.length - 1
-    ) {
-      return;
-    }
-
     for (const idx of candidates) {
       // `disableTurnStartCache` suppresses the marker on the turn-start
       // (newest user) item — one-shot call sites whose prompts never

package/src/providers/registry.ts

@@ -17,7 +17,10 @@ import {
 // Per-connection provider cache (mix-and-match support)
 // ---------------------------------------------------------------------------
 import type { ProviderConnection } from "./inference/auth.js";
-import { ROUTING_IDENTITY_PROVIDERS } from "./inference/auth.js";
+import {
+  effectiveConnectionAuth,
+  ROUTING_IDENTITY_PROVIDERS,
+} from "./inference/auth.js";
 import { resolveAuth } from "./inference/resolve-auth.js";
 import { isModelInCatalog, PROVIDER_CATALOG } from "./model-catalog.js";
 import { getProviderDefaultModel } from "./model-intents.js";
@@ -333,9 +336,11 @@ export async function resolveProviderFromConnection(
   // re-read from the store below, so a key rotated since the entry was cached
   // is picked up here rather than served stale forever.
 
-  const authResult = await resolveAuth(connection.auth, effectiveProvider, {
-    baseUrl: connection.baseUrl,
-  });
+  const authResult = await resolveAuth(
+    effectiveConnectionAuth(connection),
+    effectiveProvider,
+    { baseUrl: connection.baseUrl },
+  );
   if (!authResult.ok) {
     const err = authResult.error;
     if (err.code === "not_implemented") {

package/src/providers/retry.ts

@@ -4,6 +4,7 @@ import {
   resolveUsageAttribution,
   sanitizeUsageMetadataValue,
 } from "../usage/attribution.js";
+import { resolveSubagentAttribution } from "../usage/subagent-attribution.js";
 import {
   type ProviderCredentialSource,
   ProviderError,
@@ -49,6 +50,12 @@ const USAGE_ATTRIBUTION_HEADER_NAMES = {
   resolvedProvider: "X-Vellum-Resolved-Provider",
   resolvedModel: "X-Vellum-Resolved-Model",
   resolvedMixArm: "X-Vellum-Resolved-Mix-Arm",
+  // Delegated-work attribution. Every subagent variety shares
+  // `llm_call_site = "subagentSpawn"`, so on the authoritative billing path
+  // these two orthogonal dimensions are the only way to tell an advisor
+  // consult from a fork from a regular spawn.
+  subagentRole: "X-Vellum-Subagent-Role",
+  subagentSpawnMode: "X-Vellum-Subagent-Spawn-Mode",
 } as const;
 
 /** Providers whose transports consume `promptCacheKey` (OpenAI Responses
@@ -422,6 +429,10 @@ function normalizeSendMessageOptions(
     // downstream as a wire-format field.
     delete nextConfig.callSite;
     if (normalizeOptions.forwardUsageAttributionHeaders === true) {
+      // Read from the conversation row rather than the live SubagentManager:
+      // the row is durable and the lookup is a memoized primary-key read that
+      // can never throw, so billing attribution cannot destabilize dispatch.
+      const subagent = resolveSubagentAttribution(config.conversationId);
       const usageAttributionHeaders = buildUsageAttributionHeaders({
         callSite: attribution.callSite,
         appliedProfile: attribution.appliedProfile,
@@ -429,6 +440,8 @@ function normalizeSendMessageOptions(
         resolvedProvider: attribution.resolvedProvider,
         resolvedModel: attribution.resolvedModel,
         resolvedMixArm: attribution.resolvedMixArm,
+        subagentRole: subagent.subagentRole,
+        subagentSpawnMode: subagent.subagentSpawnMode,
       });
       if (Object.keys(usageAttributionHeaders).length > 0) {
         nextConfig.usageAttributionHeaders = usageAttributionHeaders;
@@ -769,6 +782,8 @@ function buildUsageAttributionHeaders(input: {
   resolvedProvider: string;
   resolvedModel: string;
   resolvedMixArm: string | null;
+  subagentRole: string | null;
+  subagentSpawnMode: string | null;
 }): Record<string, string> {
   const headers: Record<string, string> = {};
   addSanitizedHeader(
@@ -803,6 +818,16 @@ function buildUsageAttributionHeaders(input: {
     USAGE_ATTRIBUTION_HEADER_NAMES.resolvedMixArm,
     input.resolvedMixArm,
   );
+  addSanitizedHeader(
+    headers,
+    USAGE_ATTRIBUTION_HEADER_NAMES.subagentRole,
+    input.subagentRole,
+  );
+  addSanitizedHeader(
+    headers,
+    USAGE_ATTRIBUTION_HEADER_NAMES.subagentSpawnMode,
+    input.subagentSpawnMode,
+  );
   return headers;
 }