@vellumai/assistant 0.11.10 → 0.11.11-staging.1

package/src/providers/openai/__tests__/chat-completions-provider-xml-salvage.test.ts

@@ -0,0 +1,291 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  OpenAIChatCompletionsProvider,
+  type OpenAIChatCompletionsProviderOptions,
+} from "../chat-completions-provider.js";
+
+type MockChunkDelta = {
+  content?: string | null;
+  tool_calls?: Array<{
+    index: number;
+    id?: string;
+    function?: { name?: string; arguments?: string };
+  }>;
+};
+
+type MockChunk = {
+  choices: Array<{ delta: MockChunkDelta; finish_reason?: string | null }>;
+  usage?: { prompt_tokens: number; completion_tokens: number };
+};
+
+const BASH_TOOL = {
+  name: "bash",
+  description: "Run a shell command",
+  input_schema: {
+    type: "object",
+    properties: {
+      command: { type: "string" },
+      activity: { type: "string" },
+      timeout_seconds: { type: "number" },
+    },
+  },
+};
+
+const INVOKE_XML = `<invoke name="bash">
+<parameter name="command">cd /workspace/example && git status</parameter>
+<parameter name="activity">Checking live repo state</parameter>
+<parameter name="timeout_seconds">60</parameter>
+</invoke>`;
+
+function makeStream(chunks: MockChunk[]): AsyncIterable<MockChunk> {
+  return {
+    async *[Symbol.asyncIterator]() {
+      for (const c of chunks) {
+        yield c;
+      }
+    },
+  };
+}
+
+function stubProvider(
+  chunks: MockChunk[],
+  options?: OpenAIChatCompletionsProviderOptions,
+  model = "test-model",
+): {
+  provider: OpenAIChatCompletionsProvider;
+  events: Array<{ type: string; text?: string }>;
+} {
+  const provider = new OpenAIChatCompletionsProvider("test-key", model, options);
+  (provider as unknown as { client: unknown }).client = {
+    chat: {
+      completions: {
+        create: async () => makeStream(chunks),
+      },
+    },
+  };
+  return { provider, events: [] };
+}
+
+function contentChunks(parts: string[], finishReason = "stop"): MockChunk[] {
+  return [
+    ...parts.map((content) => ({
+      choices: [{ delta: { content } }],
+    })),
+    {
+      choices: [{ delta: {}, finish_reason: finishReason }],
+      usage: { prompt_tokens: 1, completion_tokens: 2 },
+    },
+  ];
+}
+
+describe("OpenAIChatCompletionsProvider XML tool-call salvage", () => {
+  test("converts streamed invoke XML into a tool_use block and holds it back from text_delta", async () => {
+    const { provider, events } = stubProvider(
+      contentChunks([
+        "Let me actually run the check.\n\n",
+        "<inv",
+        `oke name="bash">\n`,
+        `<parameter name="command">cd /workspace/example && git status</parameter>\n`,
+        `<parameter name="activity">Checking live repo state</parameter>\n`,
+        `<parameter name="timeout_seconds">60</parameter>\n`,
+        "</invoke>",
+      ]),
+      { salvageXmlToolCalls: true },
+    );
+
+    const response = await provider.sendMessage(
+      [{ role: "user", content: [{ type: "text", text: "check the repo" }] }],
+      {
+        tools: [BASH_TOOL],
+        onEvent: (e) => {
+          events.push(e as { type: string; text?: string });
+        },
+      },
+    );
+
+    const textDeltas = events
+      .filter((e) => e.type === "text_delta")
+      .map((e) => e.text ?? "")
+      .join("");
+    expect(textDeltas).toBe("Let me actually run the check.\n\n");
+    expect(textDeltas).not.toContain("<invoke");
+    expect(textDeltas).not.toContain("<inv");
+
+    const textBlock = response.content.find((b) => b.type === "text") as
+      | { type: "text"; text: string }
+      | undefined;
+    expect(textBlock?.text).toBe("Let me actually run the check.");
+
+    const toolUse = response.content.filter((b) => b.type === "tool_use");
+    expect(toolUse).toEqual([
+      {
+        type: "tool_use",
+        id: expect.stringMatching(/^call_/),
+        name: "bash",
+        input: {
+          command: "cd /workspace/example && git status",
+          activity: "Checking live repo state",
+          timeout_seconds: 60,
+        },
+      },
+    ]);
+    expect(response.stopReason).toBe("tool_calls");
+  });
+
+  test("salvages invoke XML when parseThinkTags is enabled", async () => {
+    const { provider } = stubProvider(
+      contentChunks([`Okay.\n${INVOKE_XML}`]),
+      { parseThinkTags: true, salvageXmlToolCalls: true },
+    );
+
+    const response = await provider.sendMessage(
+      [{ role: "user", content: [{ type: "text", text: "hi" }] }],
+      { tools: [BASH_TOOL] },
+    );
+
+    expect(response.content.some((b) => b.type === "tool_use")).toBe(true);
+    const textBlock = response.content.find((b) => b.type === "text") as
+      | { type: "text"; text: string }
+      | undefined;
+    expect(textBlock?.text).toBe("Okay.");
+  });
+
+  test("leaves XML as text when native tool_calls are already present", async () => {
+    const { provider } = stubProvider(
+      [
+      { choices: [{ delta: { content: `${INVOKE_XML}\n` } }] },
+      {
+        choices: [
+          {
+            delta: {
+              tool_calls: [
+                {
+                  index: 0,
+                  id: "call_native",
+                  function: {
+                    name: "bash",
+                    arguments: '{"command":"pwd"}',
+                  },
+                },
+              ],
+            },
+          },
+        ],
+      },
+      {
+        choices: [{ delta: {}, finish_reason: "tool_calls" }],
+        usage: { prompt_tokens: 1, completion_tokens: 2 },
+      },
+      ],
+      { salvageXmlToolCalls: true },
+    );
+
+    const response = await provider.sendMessage(
+      [{ role: "user", content: [{ type: "text", text: "hi" }] }],
+      { tools: [BASH_TOOL] },
+    );
+
+    const toolUse = response.content.filter((b) => b.type === "tool_use");
+    expect(toolUse).toHaveLength(1);
+    expect(toolUse[0]).toMatchObject({
+      id: "call_native",
+      name: "bash",
+      input: { command: "pwd" },
+    });
+    const textBlock = response.content.find((b) => b.type === "text") as
+      | { type: "text"; text: string }
+      | undefined;
+    expect(textBlock?.text).toContain("<invoke");
+  });
+
+  test("leaves XML as text when no tools were offered", async () => {
+    const { provider, events } = stubProvider(contentChunks([INVOKE_XML]));
+
+    const response = await provider.sendMessage(
+      [{ role: "user", content: [{ type: "text", text: "hi" }] }],
+      {
+        onEvent: (e) => {
+          events.push(e as { type: string; text?: string });
+        },
+      },
+    );
+
+    expect(response.content.some((b) => b.type === "tool_use")).toBe(false);
+    expect(
+      events
+        .filter((e) => e.type === "text_delta")
+        .map((e) => e.text ?? "")
+        .join(""),
+    ).toContain("<invoke");
+  });
+
+  test("leaves XML as text when tool_choice is none", async () => {
+    const { provider } = stubProvider(contentChunks([INVOKE_XML]), {
+      salvageXmlToolCalls: true,
+    });
+
+    const response = await provider.sendMessage(
+      [{ role: "user", content: [{ type: "text", text: "hi" }] }],
+      {
+        tools: [BASH_TOOL],
+        config: { tool_choice: { type: "none" } },
+      },
+    );
+
+    expect(response.content.some((b) => b.type === "tool_use")).toBe(false);
+    const textBlock = response.content.find((b) => b.type === "text") as
+      | { type: "text"; text: string }
+      | undefined;
+    expect(textBlock?.text).toContain("<invoke");
+  });
+
+  test("leaves XML as text on non-DeepSeek models unless salvage is opted in", async () => {
+    const { provider } = stubProvider(contentChunks([INVOKE_XML]));
+
+    const response = await provider.sendMessage(
+      [{ role: "user", content: [{ type: "text", text: "hi" }] }],
+      { tools: [BASH_TOOL] },
+    );
+
+    expect(response.content.some((b) => b.type === "tool_use")).toBe(false);
+    const textBlock = response.content.find((b) => b.type === "text") as
+      | { type: "text"; text: string }
+      | undefined;
+    expect(textBlock?.text).toContain("<invoke");
+  });
+
+  test("salvages by default when the model id is DeepSeek", async () => {
+    const { provider } = stubProvider(
+      contentChunks([INVOKE_XML]),
+      undefined,
+      "accounts/fireworks/models/deepseek-v4-flash-0731",
+    );
+
+    const response = await provider.sendMessage(
+      [{ role: "user", content: [{ type: "text", text: "hi" }] }],
+      { tools: [BASH_TOOL] },
+    );
+
+    expect(response.content.some((b) => b.type === "tool_use")).toBe(true);
+  });
+
+  test("does not salvage DeepSeek when salvageXmlToolCalls is false", async () => {
+    const { provider } = stubProvider(
+      contentChunks([INVOKE_XML]),
+      { salvageXmlToolCalls: false },
+      "accounts/fireworks/models/deepseek-v4-flash-0731",
+    );
+
+    const response = await provider.sendMessage(
+      [{ role: "user", content: [{ type: "text", text: "hi" }] }],
+      { tools: [BASH_TOOL] },
+    );
+
+    expect(response.content.some((b) => b.type === "tool_use")).toBe(false);
+    const textBlock = response.content.find((b) => b.type === "text") as
+      | { type: "text"; text: string }
+      | undefined;
+    expect(textBlock?.text).toContain("<invoke");
+  });
+});

package/src/providers/openai/api-error-normalization.ts

@@ -5,6 +5,8 @@ import {
   DAILY_LIMIT_PATTERNS,
   INSUFFICIENT_CREDITS_PATTERNS,
   isChatTemplateFailureError,
+  MODEL_NOT_FOUND_PATTERNS,
+  UNSUPPORTED_MODEL_ID_PATTERNS,
   VISION_NOT_SUPPORTED_PATTERNS,
 } from "../../util/provider-error-patterns.js";
 
@@ -52,8 +54,8 @@ export function normalizedErrorText(n: NormalizedOpenAIAPIError): string {
 
 /**
  * Map an OpenAI-compatible error to a semantic {@link ProviderErrorReason}.
- * Order matters — the model-restriction check precedes the generic 401/403
- * credential branch, and billing precedes credentials.
+ * Order matters: model restriction and model-not-found precede the generic
+ * 401/403 credential branch, and billing precedes credentials.
  */
 export function deriveReason(
   n: NormalizedOpenAIAPIError,
@@ -72,12 +74,25 @@ export function deriveReason(
   }
 
   if (
-    /model .*(?:not found|does not exist)/i.test(haystack) ||
+    MODEL_NOT_FOUND_PATTERNS.some((re) => re.test(haystack)) ||
     /model_not_found/i.test(`${n.apiErrorCode ?? ""} ${n.apiErrorType ?? ""}`)
   ) {
     return "model_not_found";
   }
 
+  // OpenCode's unsupported-model payload uses type=ModelError on a 401.
+  // Gate on 4xx so a 5xx that happens to carry that type stays server_error
+  // (retryable) instead of model_not_found (not retryable, fallback-eligible).
+  if (
+    status !== undefined &&
+    status >= 400 &&
+    status < 500 &&
+    (UNSUPPORTED_MODEL_ID_PATTERNS.some((re) => re.test(haystack)) ||
+      /ModelError/i.test(`${n.apiErrorCode ?? ""} ${n.apiErrorType ?? ""}`))
+  ) {
+    return "model_not_found";
+  }
+
   if (VISION_NOT_SUPPORTED_PATTERNS.some((re) => re.test(haystack))) {
     return "vision_unsupported";
   }

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

@@ -1,3 +1,5 @@
+import { randomUUID } from "node:crypto";
+
 import OpenAI from "openai";
 
 import { SYSTEM_PROMPT_CACHE_BOUNDARY } from "../../prompts/cache-boundary.js";
@@ -9,12 +11,12 @@ import { extractRetryAfterMs } from "../../util/retry.js";
 import { partialTagSuffix as sharedPartialTagSuffix } from "../../util/think-tag-stream.js";
 import { clampProviderString } from "../content-block-size.js";
 import { fileBlockToProviderText } from "../file-block-text.js";
+import { requestSupportsInlineAudio } from "../inline-audio-support.js";
 import {
   base64Source,
   mediaSourceByteLength,
   resolveMediaReferences,
 } from "../media-resolve.js";
-import { modelSupportsAudioInput } from "../model-catalog.js";
 import { PLACEHOLDER_EMPTY_TURN } from "../placeholder-sentinels.js";
 import { recordProviderRequestDiagnostics } from "../request-diagnostics.js";
 import { createStreamTimeout } from "../stream-timeout.js";
@@ -34,6 +36,11 @@ import {
   isUnparseableToolArgs,
   wrapUnparseableToolArgs,
 } from "../unparseable-tool-args.js";
+import {
+  salvageXmlToolCalls,
+  shouldSalvageXmlToolCalls,
+  splitXmlToolCallHoldback,
+} from "../xml-tool-call-salvage.js";
 import {
   captureRawErrorBodyFetch,
   formatNormalizedOpenAIAPIError,
@@ -177,6 +184,12 @@ export interface OpenAIChatCompletionsProviderOptions {
    *  with minimax-m3 on Fireworks). Off by default; scalars/arrays unaffected.
    *  See {@link coerceObjectParamsToJsonString}. */
   coerceObjectArgsToJsonString?: boolean;
+  /**
+   * Convert complete `<invoke>` XML in assistant text into `tool_use` blocks.
+   * Defaults to on for DeepSeek model ids and off otherwise. Set explicitly to
+   * override the model-id default.
+   */
+  salvageXmlToolCalls?: boolean;
   /** Drop `tool_choice` when thinking/reasoning is on the wire. Strict
    *  OpenAI-compatible reasoning upstreams (DeepSeek thinking mode) reject any
    *  explicit `tool_choice` with `Thinking mode does not support this
@@ -692,8 +705,11 @@ export class OpenAIChatCompletionsProvider implements Provider {
   private requestHeaders: Record<string, string>;
   private parseThinkTags: boolean;
   private assistantReasoningField:
-    "reasoning" | "reasoning_content" | undefined;
+    | "reasoning"
+    | "reasoning_content"
+    | undefined;
   private coerceObjectArgsToJsonString: boolean;
+  private salvageXmlToolCalls: boolean;
   private omitToolChoiceWhenReasoning: boolean;
 
   constructor(
@@ -722,6 +738,8 @@ export class OpenAIChatCompletionsProvider implements Provider {
     this.assistantReasoningField = options.assistantReasoningField;
     this.coerceObjectArgsToJsonString =
       options.coerceObjectArgsToJsonString ?? false;
+    this.salvageXmlToolCalls =
+      options.salvageXmlToolCalls ?? shouldSalvageXmlToolCalls(model);
     this.omitToolChoiceWhenReasoning =
       options.omitToolChoiceWhenReasoning ?? false;
   }
@@ -740,12 +758,15 @@ export class OpenAIChatCompletionsProvider implements Provider {
     const modelOverride = configObj?.model as string | undefined;
     const effort = configObj?.effort as string | undefined;
     const logitBias = configObj?.logit_bias as
-      Record<string, number> | undefined;
+      | Record<string, number>
+      | undefined;
     const topP = configObj?.top_p as number | undefined;
     const usageAttributionHeaders = configObj?.usageAttributionHeaders as
-      Record<string, string> | undefined;
+      | Record<string, string>
+      | undefined;
     const perRequestHeaders = configObj?.requestHeaders as
-      Record<string, string> | undefined;
+      | Record<string, string>
+      | undefined;
 
     // Per-tool keys whose object schemas were rewritten to JSON strings for the
     // wire, to be decoded back on the response. Empty unless
@@ -756,7 +777,7 @@ export class OpenAIChatCompletionsProvider implements Provider {
       const openaiMessages = await this.toOpenAIMessages(
         messages,
         systemPrompt,
-        modelSupportsAudioInput(modelOverride ?? this.model),
+        requestSupportsInlineAudio(modelOverride ?? this.model),
       );
 
       recordProviderRequestDiagnostics({
@@ -812,6 +833,9 @@ export class OpenAIChatCompletionsProvider implements Provider {
         ) as OpenAI.Chat.Completions.ChatCompletionCreateParams["reasoning_effort"];
       }
 
+      const offeredToolNames = new Set((tools ?? []).map((t) => t.name));
+      let xmlToolCallSalvageEnabled = false;
+
       if (tools && tools.length > 0) {
         params.tools = tools.map((t) => {
           let parameters = t.input_schema as OpenAI.FunctionParameters;
@@ -844,6 +868,8 @@ export class OpenAIChatCompletionsProvider implements Provider {
         // receive them; the generic openai-compatible adapter drops every
         // explicit value in thinking mode via `omitToolChoiceWhenReasoning`.
         const toolChoice = mapNeutralToolChoice(configObj?.tool_choice);
+        xmlToolCallSalvageEnabled =
+          this.salvageXmlToolCalls && toolChoice !== "none";
         if (toolChoice !== undefined) {
           const thinkingOn = isThinkingEnabledOnWire(params);
           const skipAutoDefault = thinkingOn && toolChoice === "auto";
@@ -862,6 +888,33 @@ export class OpenAIChatCompletionsProvider implements Provider {
       let reasoningText = "";
       let insideThinkBlock = false;
       let pendingContent = "";
+      let xmlHeld = "";
+
+      const emitVisibleText = (delta: string): void => {
+        if (!delta) {
+          return;
+        }
+        if (!xmlToolCallSalvageEnabled) {
+          contentText += delta;
+          onEvent?.({ type: "text_delta", text: delta });
+          return;
+        }
+        const split = splitXmlToolCallHoldback(xmlHeld + delta);
+        xmlHeld = split.held;
+        if (split.visible) {
+          contentText += split.visible;
+          onEvent?.({ type: "text_delta", text: split.visible });
+        }
+      };
+
+      const flushHeldXmlAsText = (): void => {
+        if (!xmlHeld) {
+          return;
+        }
+        contentText += xmlHeld;
+        onEvent?.({ type: "text_delta", text: xmlHeld });
+        xmlHeld = "";
+      };
 
       const flushPendingContent = (final: boolean): void => {
         while (pendingContent.length > 0) {
@@ -896,8 +949,7 @@ export class OpenAIChatCompletionsProvider implements Provider {
             if (openIdx >= 0) {
               const text = pendingContent.substring(0, openIdx);
               if (text) {
-                contentText += text;
-                onEvent?.({ type: "text_delta", text });
+                emitVisibleText(text);
               }
               insideThinkBlock = true;
               pendingContent = pendingContent.substring(
@@ -909,9 +961,7 @@ export class OpenAIChatCompletionsProvider implements Provider {
                 : partialTagSuffix(pendingContent, "<think>");
               const safeLen = pendingContent.length - partial;
               if (safeLen > 0) {
-                const t = pendingContent.substring(0, safeLen);
-                contentText += t;
-                onEvent?.({ type: "text_delta", text: t });
+                emitVisibleText(pendingContent.substring(0, safeLen));
               }
               pendingContent =
                 partial > 0 ? pendingContent.substring(safeLen) : "";
@@ -940,6 +990,10 @@ export class OpenAIChatCompletionsProvider implements Provider {
           ...(usageAttributionHeaders ?? {}),
           ...(perRequestHeaders ?? {}),
         };
+        const extraBody = this.buildRequestExtraBody(options);
+        if (extraBody) {
+          Object.assign(params, extraBody);
+        }
         const createStream = () =>
           this.client.chat.completions.create(params, {
             signal: timeoutSignal,
@@ -1020,8 +1074,7 @@ export class OpenAIChatCompletionsProvider implements Provider {
                 pendingContent += choice.delta.content;
                 flushPendingContent(false);
               } else {
-                contentText += choice.delta.content;
-                onEvent?.({ type: "text_delta", text: choice.delta.content });
+                emitVisibleText(choice.delta.content);
               }
             }
 
@@ -1142,6 +1195,42 @@ export class OpenAIChatCompletionsProvider implements Provider {
         flushPendingContent(true);
       }
 
+      // DeepSeek (and any caller that sets salvageXmlToolCalls) may emit
+      // `<invoke>` XML as assistant text instead of native `tool_calls`.
+      // Convert complete offered-tool invokes into tool_use blocks so the
+      // agent loop can execute them. Native tool_calls win.
+      if (xmlToolCallSalvageEnabled && toolCallMap.size === 0) {
+        const salvaged = salvageXmlToolCalls(
+          contentText + xmlHeld,
+          offeredToolNames,
+        );
+        if (salvaged) {
+          contentText = salvaged.text;
+          xmlHeld = "";
+          log.info(
+            {
+              salvagedToolCount: salvaged.calls.length,
+              salvagedToolNames: salvaged.calls.map((call) => call.name),
+            },
+            "Converted XML-formatted assistant text into native tool calls",
+          );
+          for (const [index, call] of salvaged.calls.entries()) {
+            toolCallMap.set(index, {
+              id: `call_${randomUUID()}`,
+              name: call.name,
+              args: JSON.stringify(call.input),
+            });
+          }
+          if (finishReason === "stop" || finishReason === "unknown") {
+            finishReason = "tool_calls";
+          }
+        } else {
+          flushHeldXmlAsText();
+        }
+      } else {
+        flushHeldXmlAsText();
+      }
+
       // Build content blocks
       const finalReasoning = this.parseThinkTags
         ? reasoningText.trim()
@@ -1362,6 +1451,17 @@ export class OpenAIChatCompletionsProvider implements Provider {
     return this.extraCreateParams;
   }
 
+  /**
+   * Fields merged onto the `chat.completions.create` params object. The
+   * OpenAI Node SDK sends unknown body fields as-is, so hosted-Qwen
+   * `directions` reach the runtime proxy on the JSON body.
+   */
+  protected buildRequestExtraBody(
+    _options?: SendMessageOptions,
+  ): Record<string, unknown> | undefined {
+    return undefined;
+  }
+
   /**
    * Per-request reasoning_effort ceiling. Defaults to the provider-wide
    * `maxReasoningEffort` from constructor options. Subclasses (e.g. Fireworks)

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

@@ -47,7 +47,7 @@ export interface OpenAIResponsesProviderOptions {
   streamTimeoutMs?: number;
   useNativeWebSearch?: boolean;
   /** When true, target the Codex subscription endpoint and strip fields it
-   *  rejects (`max_output_tokens`). */
+   *  rejects (`max_output_tokens`, `prompt_cache_options`, breakpoints). */
   codexSubscription?: boolean;
   /** Static HTTP headers sent with every request (e.g. OpenRouter app
    *  attribution). Merged under any per-request attribution headers. */
@@ -309,13 +309,13 @@ export class OpenAIResponsesProvider implements Provider {
 
       // A per-conversation prompt-cache key gives OpenAI's cache router a
       // stable affinity key so a conversation's requests land on the same
-      // cache shard. Every model on the direct API receives it — both
+      // cache shard. Every Responses model receives it, including the Codex
+      // subscription endpoint: the key is a supported routing field there
+      // (the official Codex client defaults it from thread identity). Both
       // breakpoint-capable models (which additionally opt into explicit mode
-      // below) and implicit-mode models, which carry no explicit breakpoints
-      // yet still gain prefix-cache routing affinity from a stable key. The
-      // Codex subscription endpoint rejects extra params, so it is skipped
-      // there.
-      if (!this.codexSubscription && promptCacheKey) {
+      // below) and implicit-mode models, which carry no explicit breakpoints,
+      // still gain prefix-cache routing affinity from a stable key.
+      if (promptCacheKey) {
         params.prompt_cache_key = promptCacheKey;
       }
 
@@ -329,7 +329,9 @@ export class OpenAIResponsesProvider implements Provider {
       // breakpoints neither uses the cache nor incurs cache-write charges,
       // which is exactly the opt-out `disableCache` wants (omitting the param
       // would re-enable implicit mode). The Codex subscription endpoint
-      // rejects extra params, so these params are skipped entirely there.
+      // rejects `prompt_cache_options` and block-level breakpoints, so those
+      // stay off there. Codex runs in implicit prefix-cache mode and relies
+      // on `prompt_cache_key` above for routing affinity.
       if (
         !this.codexSubscription &&
         PROMPT_CACHE_BREAKPOINT_MODEL_IDS.has(effectiveModel)

package/src/providers/provider-secret-catalog.ts

@@ -2,7 +2,7 @@
  * Canonical source for API-key-addressable providers.
  *
  * This module composes the full set of providers that store API keys in
- * secure storage (the `api_key` secret type) from four sources:
+ * secure storage (the `api_key` secret type) from five sources:
  *
  * 1. **LLM providers** -- derived from `PROVIDER_CATALOG`
  *    (`model-catalog.ts`). Adding a provider to the catalog automatically
@@ -15,6 +15,8 @@
  * 4. **TTS catalog providers** -- dynamically derived from the canonical
  *    TTS provider catalog by selecting entries whose secret requirements
  *    use the bare-name (non-credential) storage convention.
+ * 5. **Embedding-only providers** -- currently `custom`, the
+ *    OpenAI-compatible memory embeddings endpoint.
  *
  * Consumers that need the set of valid API-key provider names should
  * import {@link API_KEY_PROVIDERS} from this module rather than
@@ -116,6 +118,13 @@ function catalogApiKeyNames(): string[] {
     );
 }
 
+/**
+ * Embedding-only API-key names. `custom` is the OpenAI-compatible memory
+ * embeddings provider and is not an LLM catalog entry, so it is declared
+ * here rather than in `PROVIDER_CATALOG`.
+ */
+const EMBEDDING_API_KEY_PROVIDERS: readonly string[] = ["custom"];
+
 // ---------------------------------------------------------------------------
 // Unified export
 // ---------------------------------------------------------------------------
@@ -148,6 +157,7 @@ export const API_KEY_PROVIDERS: readonly string[] = (() => {
     ...LLM_AND_SEARCH_API_KEY_PROVIDERS,
     ...sttApiKeyProviderNames(),
     ...catalogApiKeyNames(),
+    ...EMBEDDING_API_KEY_PROVIDERS,
   ]) {
     if (!seen.has(name)) {
       seen.add(name);