@vellumai/assistant 0.8.6 → 0.8.7-dev.202606052118.34cd356

package/src/providers/gemini/client.ts

@@ -1,6 +1,10 @@
 import type * as genai from "@google/genai";
 import { ApiError, GoogleGenAI, ThinkingLevel } from "@google/genai";
 
+import {
+  THINKING_LEVELS,
+  type ThinkingLevel as ThinkingLevelName,
+} from "../../config/schemas/llm.js";
 import { isAbortReason } from "../../util/abort-reasons.js";
 import { ProviderError } from "../../util/errors.js";
 import { getLogger } from "../../util/logger.js";
@@ -12,12 +16,16 @@ import type {
   Provider,
   ProviderResponse,
   SendMessageOptions,
-  ToolDefinition,
 } from "../types.js";
 import {
   ContextOverflowError,
   extractOverflowTokensFromMessage,
 } from "../types.js";
+import {
+  base64ByteLength,
+  GEMINI_MAX_INLINE_AUDIO_BYTES,
+  normalizeGeminiAudioMime,
+} from "./inline-media.js";
 
 /**
  * Token/context-specific phrases that reliably indicate context-overflow
@@ -34,40 +42,100 @@ function isGemini3Model(model: string): boolean {
   return model.startsWith("gemini-3") || model.startsWith("models/gemini-3");
 }
 
-const THINKING_LEVEL_BY_NAME: Record<string, ThinkingLevel> = {
+const THINKING_LEVEL_BY_NAME: Record<ThinkingLevelName, ThinkingLevel> = {
   minimal: ThinkingLevel.MINIMAL,
   low: ThinkingLevel.LOW,
   medium: ThinkingLevel.MEDIUM,
   high: ThinkingLevel.HIGH,
 };
 
+/**
+ * Default thinking level for Gemini Pro models when the profile doesn't pin
+ * one. Pro rejects `"minimal"` and an absent level resolves to `"minimal"`
+ * upstream, so we pin Google's documented Pro default (`"high"`) — always a
+ * supported value.
+ */
+const GEMINI_PRO_DEFAULT_THINKING_LEVEL: ThinkingLevelName = "high";
+
+/**
+ * Gemini 3.x Pro family accepts only `low`/`medium`/`high` (no `"minimal"`) and
+ * cannot fully disable thinking. Matches `gemini-3.1-pro-preview`,
+ * `gemini-3.1-pro-preview-customtools`, and future `gemini-3*pro*`.
+ */
+function isGeminiProModel(model: string): boolean {
+  const normalized = model.startsWith("models/")
+    ? model.slice("models/".length)
+    : model;
+  return /^gemini-3.*pro/.test(normalized);
+}
+
+/**
+ * Lowest thinking level the model accepts. Pro's floor is `"low"`; every other
+ * thinking-capable Gemini model accepts `"minimal"`.
+ */
+function geminiThinkingFloor(model: string): ThinkingLevelName {
+  return isGeminiProModel(model) ? "low" : "minimal";
+}
+
+/**
+ * Raise `level` to `floor` when it sits below it, so we never send a level the
+ * model rejects (e.g. `"minimal"` to a Pro model).
+ */
+function clampThinkingLevelToFloor(
+  level: ThinkingLevelName,
+  floor: ThinkingLevelName,
+): ThinkingLevelName {
+  return THINKING_LEVELS.indexOf(level) < THINKING_LEVELS.indexOf(floor)
+    ? floor
+    : level;
+}
+
 /**
  * Translate the resolved wire-shape `thinking` config into Gemini's
- * `thinkingConfig`. Returns `undefined` when no thinking config was supplied,
- * which lets Google's per-model default apply (e.g. `gemini-3.5-flash`
- * defaults to dynamic medium-level thinking).
+ * `thinkingConfig`, guaranteeing the emitted `thinkingLevel` is one the model
+ * accepts. Returns `undefined` when nothing needs to be set, which lets
+ * Google's per-model default apply (e.g. `gemini-3.5-flash` defaults to
+ * dynamic medium-level thinking).
+ *
+ * - `enabled: false` maps to the model's floor — the most "off" state it
+ *   allows (`"minimal"` for most models, `"low"` for Pro, which can't disable
+ *   thinking).
+ * - An explicit `level` below the floor is raised to the floor.
+ * - When no `level` is pinned, Pro models get the documented default (`"high"`)
+ *   because an absent level resolves to the unsupported `"minimal"` upstream;
+ *   other models keep Google's per-model default by leaving the level unset.
  *
- * `enabled: false` maps to `thinkingLevel: MINIMAL` because Gemini 3.x cannot
- * fully disable thinking — `"minimal"` is the floor. `includeThoughts` is
- * gated on `streamThinking` so callers that opted out of streaming thoughts
- * don't pay for thought tokens in the response.
+ * `includeThoughts` is gated on `streamThinking` so callers that opted out of
+ * streaming thoughts don't pay for thought tokens in the response.
  */
 function buildThinkingConfig(
   thinking: Record<string, unknown> | undefined,
+  model: string,
 ): genai.ThinkingConfig | undefined {
   if (!thinking) return undefined;
+  const floor = geminiThinkingFloor(model);
+
   if (thinking.type === "disabled") {
     return {
-      thinkingLevel: ThinkingLevel.MINIMAL,
+      thinkingLevel: THINKING_LEVEL_BY_NAME[floor],
       includeThoughts: false,
     };
   }
   if (thinking.type !== "adaptive") return undefined;
 
   const result: genai.ThinkingConfig = {};
-  if (typeof thinking.level === "string") {
-    const mapped = THINKING_LEVEL_BY_NAME[thinking.level];
-    if (mapped) result.thinkingLevel = mapped;
+  if (
+    typeof thinking.level === "string" &&
+    thinking.level in THINKING_LEVEL_BY_NAME
+  ) {
+    const clamped = clampThinkingLevelToFloor(
+      thinking.level as ThinkingLevelName,
+      floor,
+    );
+    result.thinkingLevel = THINKING_LEVEL_BY_NAME[clamped];
+  } else if (isGeminiProModel(model)) {
+    result.thinkingLevel =
+      THINKING_LEVEL_BY_NAME[GEMINI_PRO_DEFAULT_THINKING_LEVEL];
   }
   if (typeof thinking.streamThinking === "boolean") {
     result.includeThoughts = thinking.streamThinking;
@@ -223,11 +291,9 @@ export class GeminiProvider implements Provider {
 
   async sendMessage(
     messages: Message[],
-    tools?: ToolDefinition[],
-    systemPrompt?: string,
     options?: SendMessageOptions,
   ): Promise<ProviderResponse> {
-    const { config, onEvent, signal } = options ?? {};
+    const { tools, systemPrompt, config, onEvent, signal } = options ?? {};
     const configObj = config as Record<string, unknown> | undefined;
     const maxTokens = configObj?.max_tokens as number | undefined;
     const modelOverride = configObj?.model as string | undefined;
@@ -238,6 +304,7 @@ export class GeminiProvider implements Provider {
     const thinkingConfig = geminiModelSupportsThinking(activeModel)
       ? buildThinkingConfig(
           configObj?.thinking as Record<string, unknown> | undefined,
+          activeModel,
         )
       : undefined;
 
@@ -296,6 +363,7 @@ export class GeminiProvider implements Provider {
       let finishReason = "unknown";
       let promptTokens = 0;
       let outputTokens = 0;
+      let cachedTokens = 0;
       let responseModel = activeModel;
 
       try {
@@ -343,6 +411,11 @@ export class GeminiProvider implements Provider {
           if (chunk.usageMetadata) {
             promptTokens = chunk.usageMetadata.promptTokenCount ?? 0;
             outputTokens = chunk.usageMetadata.candidatesTokenCount ?? 0;
+            // Gemini 2.5+/3.x cache a stable request prefix implicitly (on by
+            // default). promptTokenCount already includes these cached tokens,
+            // so cachedContentTokenCount is the read subset — surface it so the
+            // pricing layer applies the discounted cache-read rate.
+            cachedTokens = chunk.usageMetadata.cachedContentTokenCount ?? 0;
           }
 
           if (chunk.modelVersion) {
@@ -386,13 +459,18 @@ export class GeminiProvider implements Provider {
         usageMetadata: {
           promptTokenCount: promptTokens,
           candidatesTokenCount: outputTokens,
+          cachedContentTokenCount: cachedTokens,
         },
       };
 
       return {
         content,
         model: responseModel,
-        usage: { inputTokens: promptTokens, outputTokens },
+        usage: {
+          inputTokens: promptTokens,
+          outputTokens,
+          ...(cachedTokens > 0 ? { cacheReadInputTokens: cachedTokens } : {}),
+        },
         stopReason: finishReason,
         rawRequest,
         rawResponse,
@@ -456,7 +534,7 @@ export class GeminiProvider implements Provider {
 
     for (const msg of messages) {
       const role = msg.role === "assistant" ? "model" : "user";
-      const { parts, toolResultImageParts } = this.toGeminiParts(
+      const { parts, toolResultMediaParts } = this.toGeminiParts(
         msg.content,
         toolCallNames,
         model,
@@ -468,8 +546,8 @@ export class GeminiProvider implements Provider {
       // Gemini requires that a Content with functionResponse parts must not
       // contain non-functionResponse parts. Emit tool-result images in a
       // separate user Content entry.
-      if (toolResultImageParts.length > 0) {
-        result.push({ role: "user", parts: toolResultImageParts });
+      if (toolResultMediaParts.length > 0) {
+        result.push({ role: "user", parts: toolResultMediaParts });
       }
     }
 
@@ -482,9 +560,9 @@ export class GeminiProvider implements Provider {
     toolCallNames: Map<string, string>,
     model: string,
     role: "model" | "user",
-  ): { parts: genai.Part[]; toolResultImageParts: genai.Part[] } {
+  ): { parts: genai.Part[]; toolResultMediaParts: genai.Part[] } {
     const parts: genai.Part[] = [];
-    const toolResultImageParts: genai.Part[] = [];
+    const toolResultMediaParts: genai.Part[] = [];
 
     for (const block of blocks) {
       switch (block.type) {
@@ -499,14 +577,27 @@ export class GeminiProvider implements Provider {
             },
           });
           break;
-        case "file":
+        case "file": {
           if (this.supportsGeminiInlineFile(block.source.media_type)) {
-            parts.push({
-              inlineData: {
-                mimeType: block.source.media_type,
-                data: block.source.data,
-              },
-            });
+            // Normalize audio MIME onto Gemini's spelling (e.g. audio/mpeg →
+            // audio/mp3); PDFs pass through unchanged. Guard the 20 MB inline
+            // request limit for audio so an oversize clip degrades to a text
+            // note rather than 400ing the whole request.
+            const audioMime = normalizeGeminiAudioMime(block.source.media_type);
+            const rawBytes = base64ByteLength(block.source.data);
+            if (audioMime && rawBytes > GEMINI_MAX_INLINE_AUDIO_BYTES) {
+              const approxMb = Math.round(rawBytes / (1024 * 1024));
+              parts.push({
+                text: `[Audio file too large to send inline: ${block.source.filename} (${block.source.media_type}, ~${approxMb}MB). Gemini's inline request limit is 20MB; this file was omitted. Ask the user for a shorter clip.]`,
+              });
+            } else {
+              parts.push({
+                inlineData: {
+                  mimeType: audioMime ?? block.source.media_type,
+                  data: block.source.data,
+                },
+              });
+            }
           } else {
             const fallback = block.extracted_text?.trim()
               ? `[Attached file: ${block.source.filename} (${block.source.media_type})]\n${block.extracted_text}`
@@ -514,6 +605,7 @@ export class GeminiProvider implements Provider {
             parts.push({ text: fallback });
           }
           break;
+        }
         case "tool_use":
           {
             const functionCallPart: genai.Part = {
@@ -542,16 +634,39 @@ export class GeminiProvider implements Provider {
             if (extraText.length > 0) {
               outputText = outputText + "\n" + extraText.join("\n");
             }
-            // Collect images separately — Gemini rejects mixing inlineData
-            // with functionResponse in the same Content entry.
+            // Collect images and inline-able audio separately — Gemini rejects
+            // mixing inlineData with functionResponse in the same Content entry.
             for (const cb of block.contentBlocks) {
               if (cb.type === "image") {
-                toolResultImageParts.push({
+                toolResultMediaParts.push({
                   inlineData: {
                     mimeType: cb.source.media_type,
                     data: cb.source.data,
                   },
                 });
+              } else if (cb.type === "file") {
+                const audioMime = normalizeGeminiAudioMime(
+                  cb.source.media_type,
+                );
+                if (
+                  audioMime &&
+                  base64ByteLength(cb.source.data) <=
+                    GEMINI_MAX_INLINE_AUDIO_BYTES
+                ) {
+                  toolResultMediaParts.push({
+                    inlineData: { mimeType: audioMime, data: cb.source.data },
+                  });
+                } else if (audioMime) {
+                  // Oversize audio: note it in the functionResponse output
+                  // rather than a media part (a text part can't ride the
+                  // separate media Content, and inline audio would blow
+                  // Gemini's request-size limit).
+                  outputText =
+                    outputText +
+                    `\n[Audio too large to send inline: ${cb.source.filename}. Ask for a shorter clip.]`;
+                }
+                // Non-inline-able file sub-blocks (m4a/opus/pdf) are skipped
+                // here; the tool's text output already conveys the file.
               }
             }
           }
@@ -577,7 +692,7 @@ export class GeminiProvider implements Provider {
       this.addGemini3UnsignedToolCallFallback(parts, model);
     }
 
-    return { parts, toolResultImageParts };
+    return { parts, toolResultMediaParts };
   }
 
   private addGemini3UnsignedToolCallFallback(
@@ -601,6 +716,9 @@ export class GeminiProvider implements Provider {
   }
 
   private supportsGeminiInlineFile(mimeType: string): boolean {
-    return mimeType === "application/pdf";
+    return (
+      mimeType === "application/pdf" ||
+      normalizeGeminiAudioMime(mimeType) !== null
+    );
   }
 }

package/src/providers/gemini/inline-media.ts

@@ -0,0 +1,74 @@
+/**
+ * Shared source of truth for how Gemini ingests inline audio: which MIME types
+ * it accepts, how our stored MIME types normalize onto Gemini's spelling, the
+ * inline-request size ceiling, and the token cost.
+ *
+ * Imported by both the Gemini serializer (`client.ts`) and the token estimator
+ * (`context/token-estimator.ts`) so the two cannot drift — if they disagreed on
+ * which audio is sent inline, the context budgeter would mis-count what
+ * actually goes on the wire.
+ *
+ * Ref: https://ai.google.dev/gemini-api/docs/audio
+ *   - Inline-accepted audio: wav, mp3, aiff, aac, ogg, flac
+ *   - Inline request size limit: 20 MB total (prompt + system + inline files)
+ *   - Audio is billed at ~32 tokens/second
+ */
+
+/**
+ * Audio MIME types Gemini accepts as inline data, in Gemini's own spelling
+ * (the values we emit on the wire). Our upload allowlist stores mp3 as
+ * `audio/mpeg`; {@link normalizeGeminiAudioMime} maps that onto `audio/mp3`.
+ */
+export const GEMINI_INLINE_AUDIO_MIME_TYPES = new Set([
+  "audio/wav",
+  "audio/mp3",
+  "audio/aiff",
+  "audio/aac",
+  "audio/ogg",
+  "audio/flac",
+]);
+
+/**
+ * Map a stored attachment MIME type onto Gemini's inline-audio spelling, or
+ * `null` when Gemini cannot take it inline.
+ *
+ * m4a (`audio/x-m4a`, `audio/mp4`) and opus are intentionally unsupported:
+ * m4a bytes are an MP4 container, not raw AAC, so we must not relabel them as
+ * `audio/aac` — they fall through to a text placeholder instead.
+ */
+export function normalizeGeminiAudioMime(mimeType: string): string | null {
+  const normalized = mimeType.toLowerCase().split(";")[0]?.trim() ?? "";
+  const remapped = normalized === "audio/mpeg" ? "audio/mp3" : normalized;
+  return GEMINI_INLINE_AUDIO_MIME_TYPES.has(remapped) ? remapped : null;
+}
+
+/** Raw byte length backing a base64 string (4 base64 chars → 3 bytes). */
+export function base64ByteLength(base64Data: string): number {
+  return Math.floor((base64Data.length * 3) / 4);
+}
+
+/**
+ * Max raw bytes of audio we send inline to Gemini. Gemini's total inline
+ * request limit is 20 MB and base64 inflates payloads ~33%, so we cap raw
+ * audio at ~12 MB (≈16 MB encoded) to leave headroom for the prompt, system
+ * instruction, and conversation history. Larger files degrade to a text
+ * placeholder (the Gemini Files API is a future enhancement).
+ */
+export const GEMINI_MAX_INLINE_AUDIO_BYTES = 12 * 1024 * 1024;
+
+/**
+ * Gemini bills audio at ~32 tokens/second, NOT by payload size. We don't have
+ * the decoded duration at estimate time, so approximate it from byte size
+ * assuming ~128 kbps (~16 KB/s) typical compressed audio. This keeps the
+ * context budgeter within range instead of the ~170x over-count that treating
+ * the base64 payload as text produces. (Uncompressed WAV is under-counted, but
+ * the inline size guard caps it at {@link GEMINI_MAX_INLINE_AUDIO_BYTES}.)
+ */
+const GEMINI_AUDIO_TOKENS_PER_SECOND = 32;
+const APPROX_AUDIO_BYTES_PER_SECOND = 16_000;
+
+export function estimateGeminiAudioTokens(base64Data: string): number {
+  const approxSeconds =
+    base64ByteLength(base64Data) / APPROX_AUDIO_BYTES_PER_SECOND;
+  return Math.ceil(approxSeconds * GEMINI_AUDIO_TOKENS_PER_SECOND);
+}

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

@@ -1,6 +1,8 @@
 import { describe, expect, test } from "bun:test";
 
+import { isPlaceholderSentinelText } from "../../placeholder-sentinels.js";
 import {
+  EMPTY_ASSISTANT_TURN_PLACEHOLDER,
   OpenAIChatCompletionsProvider,
   type OpenAIChatCompletionsProviderOptions,
 } from "../chat-completions-provider.js";
@@ -74,8 +76,6 @@ async function runStream(
 }> {
   const response = await provider.sendMessage(
     [{ role: "user", content: [{ type: "text", text: "hi" }] }],
-    undefined,
-    undefined,
     {
       onEvent: (e) => {
         events.push(e as { type: string; thinking?: string; text?: string });
@@ -350,6 +350,116 @@ describe("OpenAIChatCompletionsProvider reasoning parsing", () => {
     expect(assistantMsg.reasoning_content).toBeUndefined();
   });
 
+  test("backfills placeholder content for a reasoning-only assistant turn when enabled", async () => {
+    const { provider, requests } = stubProvider(
+      [
+        {
+          choices: [{ delta: { content: "ok" }, finish_reason: "stop" }],
+          usage: { prompt_tokens: 2, completion_tokens: 1 },
+        },
+      ],
+      {
+        assistantReasoningField: "reasoning",
+        backfillEmptyAssistantContent: true,
+      },
+    );
+
+    await provider.sendMessage([
+      { role: "user", content: [{ type: "text", text: "question" }] },
+      {
+        role: "assistant",
+        content: [
+          {
+            type: "thinking",
+            thinking: "truncated chain of thought",
+            signature: "",
+          },
+        ],
+      },
+    ]);
+
+    const params = requests[0] as {
+      messages: Array<{
+        role: string;
+        content: string | null;
+        reasoning?: string;
+        tool_calls?: unknown;
+      }>;
+    };
+    const assistantMsg = params.messages.find((m) => m.role === "assistant")!;
+    // content or tool_calls must be set; reasoning alone does not satisfy it.
+    expect(assistantMsg.content).toBe(EMPTY_ASSISTANT_TURN_PLACEHOLDER);
+    expect(assistantMsg.tool_calls).toBeUndefined();
+    expect(assistantMsg.reasoning).toBe("truncated chain of thought");
+    // The placeholder is a recognized sentinel, so it is stripped from
+    // persisted/rendered history if a model echoes it back, and it carries no
+    // control characters that a strict OpenAI-compatible backend might reject.
+    expect(isPlaceholderSentinelText(EMPTY_ASSISTANT_TURN_PLACEHOLDER)).toBe(
+      true,
+    );
+    expect(EMPTY_ASSISTANT_TURN_PLACEHOLDER).not.toContain("\x00");
+  });
+
+  test("leaves reasoning-only assistant content null when backfill is disabled", async () => {
+    const { provider, requests } = stubProvider(
+      [
+        {
+          choices: [{ delta: { content: "ok" }, finish_reason: "stop" }],
+          usage: { prompt_tokens: 2, completion_tokens: 1 },
+        },
+      ],
+      { assistantReasoningField: "reasoning_content" },
+    );
+
+    await provider.sendMessage([
+      { role: "user", content: [{ type: "text", text: "question" }] },
+      {
+        role: "assistant",
+        content: [
+          {
+            type: "thinking",
+            thinking: "truncated chain of thought",
+            signature: "",
+          },
+        ],
+      },
+    ]);
+
+    const params = requests[0] as {
+      messages: Array<{ role: string; content: string | null }>;
+    };
+    const assistantMsg = params.messages.find((m) => m.role === "assistant")!;
+    // Backfill defaults off, so providers that tolerate null assistant content
+    // (e.g. OpenAI proper) are unaffected by the OpenRouter-specific guard.
+    expect(assistantMsg.content).toBeNull();
+  });
+
+  test("does not backfill content when tool calls are present", async () => {
+    const { provider, requests } = stubProvider([
+      {
+        choices: [{ delta: { content: "ok" }, finish_reason: "stop" }],
+        usage: { prompt_tokens: 2, completion_tokens: 1 },
+      },
+    ]);
+
+    await provider.sendMessage([
+      {
+        role: "assistant",
+        content: [
+          { type: "tool_use", id: "call_1", name: "search", input: { q: "x" } },
+        ],
+      },
+    ]);
+
+    const params = requests[0] as {
+      messages: Array<{ role: string; content: string | null }>;
+    };
+    // Tool-call-only assistant messages keep null content (preferred by
+    // Anthropic-proxy/Bedrock backends); the placeholder is only for the
+    // neither-content-nor-tool_calls case.
+    expect(params.messages[0].content).toBeNull();
+  });
+
   test("skips Anthropic-originated thinking blocks (with signatures)", async () => {
     const { provider, requests } = stubProvider(
       [

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

@@ -4,6 +4,7 @@ import { isAbortReason } from "../../util/abort-reasons.js";
 import { ProviderError } from "../../util/errors.js";
 import { extractRetryAfterMs } from "../../util/retry.js";
 import { escapeXmlAttr } from "../../util/xml.js";
+import { PLACEHOLDER_EMPTY_TURN } from "../placeholder-sentinels.js";
 import { createStreamTimeout } from "../stream-timeout.js";
 import type {
   ContentBlock,
@@ -11,7 +12,6 @@ import type {
   Provider,
   ProviderResponse,
   SendMessageOptions,
-  ToolDefinition,
 } from "../types.js";
 import {
   ContextOverflowError,
@@ -101,6 +101,26 @@ export function extractApiErrorDetail(
  *  OpenRouter's `error.metadata.raw` strings, which are typically <1KB. */
 const MAX_API_ERROR_DETAIL_CHARS = 2000;
 
+/**
+ * Fallback `content` for an assistant turn that has neither visible text nor
+ * tool calls (e.g. a reasoning-only turn truncated at the output-token limit).
+ *
+ * The OpenAI chat-completions schema requires an assistant message to carry
+ * `content` or `tool_calls`. OpenAI itself tolerates `content: null`/`""` here,
+ * but strict OpenAI-compatible backends do not: DeepSeek via OpenRouter rejects
+ * the request with `Invalid assistant message: content or tool_calls must be
+ * set`, and vLLM-style validators coerce empty-string content back to null and
+ * reject it the same way. The placeholder must therefore be a non-empty string.
+ *
+ * We reuse the shared empty-turn sentinel so that
+ * `isPlaceholderSentinelText`/`cleanAssistantContent` strip it from persisted
+ * and rendered history if a model ever echoes it back. The null-byte prefix is
+ * dropped because some OpenAI-compatible backends reject control characters in
+ * message content; the bare form is still recognized by
+ * `isPlaceholderSentinelText`.
+ */
+export const EMPTY_ASSISTANT_TURN_PLACEHOLDER = PLACEHOLDER_EMPTY_TURN.slice(1);
+
 /**
  * Read the first matching header from an SDK error's headers object,
  * tolerating both Map-like (`Headers.get()`) and plain-object shapes.
@@ -154,6 +174,13 @@ export interface OpenAIChatCompletionsProviderOptions {
    *  DeepSeek/Fireworks use `"reasoning_content"`; OpenRouter uses `"reasoning"`.
    *  When unset, thinking blocks are dropped from outbound assistant messages. */
   assistantReasoningField?: "reasoning" | "reasoning_content";
+  /** Backfill a non-empty placeholder for assistant turns that would otherwise
+   *  serialize with neither `content` nor `tool_calls` (e.g. reasoning-only
+   *  turns). Off by default; enabled for OpenRouter, whose downstream providers
+   *  (e.g. DeepSeek) reject such messages with `Invalid assistant message:
+   *  content or tool_calls must be set`. See {@link
+   *  EMPTY_ASSISTANT_TURN_PLACEHOLDER}. */
+  backfillEmptyAssistantContent?: boolean;
 }
 
 /** Wire-level reasoning_effort values. The OpenAI SDK type doesn't include
@@ -229,6 +256,7 @@ export class OpenAIChatCompletionsProvider implements Provider {
     | "reasoning"
     | "reasoning_content"
     | undefined;
+  private backfillEmptyAssistantContent: boolean;
 
   constructor(
     apiKey: string,
@@ -252,15 +280,15 @@ export class OpenAIChatCompletionsProvider implements Provider {
     this.requestHeaders = options.requestHeaders ?? {};
     this.parseThinkTags = options.parseThinkTags ?? false;
     this.assistantReasoningField = options.assistantReasoningField;
+    this.backfillEmptyAssistantContent =
+      options.backfillEmptyAssistantContent ?? false;
   }
 
   async sendMessage(
     messages: Message[],
-    tools?: ToolDefinition[],
-    systemPrompt?: string,
     options?: SendMessageOptions,
   ): Promise<ProviderResponse> {
-    const { config, onEvent, signal } = options ?? {};
+    const { tools, systemPrompt, config, onEvent, signal } = options ?? {};
     const configObj = config as Record<string, unknown> | undefined;
     const maxTokens = configObj?.max_tokens as number | undefined;
     const modelOverride = configObj?.model as string | undefined;
@@ -797,6 +825,19 @@ export class OpenAIChatCompletionsProvider implements Provider {
       result.tool_calls = toolCalls;
     }
 
+    // An assistant message must carry `content` or `tool_calls`. A turn with
+    // neither (e.g. reasoning-only) would serialize to null/empty content with
+    // no tool calls, which strict OpenAI-compatible backends reject. Reasoning
+    // lives in a separate field and does not satisfy this constraint. Scoped to
+    // providers that need it (OpenRouter) via `backfillEmptyAssistantContent`.
+    if (
+      this.backfillEmptyAssistantContent &&
+      !result.tool_calls &&
+      (result.content === null || result.content === "")
+    ) {
+      result.content = EMPTY_ASSISTANT_TURN_PLACEHOLDER;
+    }
+
     return result;
   }
 

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

@@ -12,7 +12,6 @@ import type {
   Provider,
   ProviderResponse,
   SendMessageOptions,
-  ToolDefinition,
 } from "../types.js";
 import { ContextOverflowError } from "../types.js";
 import { detectOpenAICompatibleContextOverflow } from "./chat-completions-provider.js";
@@ -160,11 +159,9 @@ export class OpenAIResponsesProvider implements Provider {
 
   async sendMessage(
     messages: Message[],
-    tools?: ToolDefinition[],
-    systemPrompt?: string,
     options?: SendMessageOptions,
   ): Promise<ProviderResponse> {
-    const { config, onEvent, signal } = options ?? {};
+    const { tools, systemPrompt, config, onEvent, signal } = options ?? {};
     const configObj = config as Record<string, unknown> | undefined;
     const maxTokens = configObj?.max_tokens as number | undefined;
     const modelOverride = configObj?.model as string | undefined;