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

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

@@ -1,6 +1,11 @@
 import { describe, expect, test } from "bun:test";
 
-import { OpenAIChatCompletionsProvider } from "../chat-completions-provider.js";
+import { isPlaceholderSentinelText } from "../../placeholder-sentinels.js";
+import {
+  EMPTY_ASSISTANT_TURN_PLACEHOLDER,
+  OpenAIChatCompletionsProvider,
+  type OpenAIChatCompletionsProviderOptions,
+} from "../chat-completions-provider.js";
 
 type ReasoningDetail = {
   type?: string;
@@ -32,23 +37,35 @@ function makeStream(chunks: MockChunk[]): AsyncIterable<MockChunk> {
   };
 }
 
-function stubProvider(chunks: MockChunk[]): {
+function stubProvider(
+  chunks: MockChunk[],
+  options?: OpenAIChatCompletionsProviderOptions,
+): {
   provider: OpenAIChatCompletionsProvider;
   events: Array<{ type: string; thinking?: string; text?: string }>;
+  requests: unknown[];
 } {
-  const provider = new OpenAIChatCompletionsProvider("test-key", "test-model");
+  const provider = new OpenAIChatCompletionsProvider(
+    "test-key",
+    "test-model",
+    options,
+  );
+  const requests: unknown[] = [];
   // Swap the SDK client for a stub whose chat.completions.create returns our
   // canned async iterable.
   (provider as unknown as { client: unknown }).client = {
     chat: {
       completions: {
-        create: async () => makeStream(chunks),
+        create: async (params: unknown) => {
+          requests.push(params);
+          return makeStream(chunks);
+        },
       },
     },
   };
   const events: Array<{ type: string; thinking?: string; text?: string }> = [];
   (provider as unknown as { __events: typeof events }).__events = events;
-  return { provider, events };
+  return { provider, events, requests };
 }
 
 async function runStream(
@@ -59,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 });
@@ -232,4 +247,251 @@ describe("OpenAIChatCompletionsProvider reasoning parsing", () => {
     expect(deltas.map((d) => d.thinking)).toEqual(["it ", "worked", "!"]);
     expect(thinking).toBe("it worked!");
   });
+
+  test("round-trips prior assistant thinking as reasoning_content when field is set", async () => {
+    const { provider, requests } = stubProvider(
+      [
+        {
+          choices: [{ delta: { content: "continued" }, finish_reason: "stop" }],
+          usage: { prompt_tokens: 4, completion_tokens: 2 },
+        },
+      ],
+      { assistantReasoningField: "reasoning_content" },
+    );
+
+    await provider.sendMessage([
+      { role: "user", content: [{ type: "text", text: "first question" }] },
+      {
+        role: "assistant",
+        content: [
+          { type: "thinking", thinking: "hidden chain state", signature: "" },
+          { type: "text", text: "first answer" },
+        ],
+      },
+      { role: "user", content: [{ type: "text", text: "follow up" }] },
+    ]);
+
+    const params = requests[0] as {
+      messages: Array<{
+        role: string;
+        content: string | null;
+        reasoning_content?: string;
+      }>;
+    };
+    const assistantMsg = params.messages.find((m) => m.role === "assistant");
+    expect(assistantMsg).toEqual({
+      role: "assistant",
+      content: "first answer",
+      reasoning_content: "hidden chain state",
+    });
+  });
+
+  test("uses reasoning field for OpenRouter-style round-trip", async () => {
+    const { provider, requests } = stubProvider(
+      [
+        {
+          choices: [{ delta: { content: "ok" }, finish_reason: "stop" }],
+          usage: { prompt_tokens: 2, completion_tokens: 1 },
+        },
+      ],
+      { assistantReasoningField: "reasoning" },
+    );
+
+    await provider.sendMessage([
+      {
+        role: "assistant",
+        content: [
+          { type: "thinking", thinking: "visible summary", signature: "" },
+          { type: "text", text: "answer" },
+        ],
+      },
+    ]);
+
+    const params = requests[0] as {
+      messages: Array<{
+        role: string;
+        reasoning?: string;
+        reasoning_content?: string;
+      }>;
+    };
+    expect(params.messages[0].reasoning).toBe("visible summary");
+    expect(params.messages[0].reasoning_content).toBeUndefined();
+  });
+
+  test("drops thinking blocks when assistantReasoningField is unset", async () => {
+    const { provider, requests } = stubProvider([
+      {
+        choices: [{ delta: { content: "reply" }, finish_reason: "stop" }],
+        usage: { prompt_tokens: 2, completion_tokens: 1 },
+      },
+    ]);
+
+    await provider.sendMessage([
+      {
+        role: "assistant",
+        content: [
+          { type: "thinking", thinking: "should be dropped", signature: "" },
+          { type: "text", text: "visible" },
+        ],
+      },
+    ]);
+
+    const params = requests[0] as {
+      messages: Array<{
+        role: string;
+        content: string | null;
+        reasoning?: string;
+        reasoning_content?: string;
+      }>;
+    };
+    const assistantMsg = params.messages[0];
+    expect(assistantMsg.content).toBe("visible");
+    expect(assistantMsg.reasoning).toBeUndefined();
+    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(
+      [
+        {
+          choices: [{ delta: { content: "ok" }, finish_reason: "stop" }],
+          usage: { prompt_tokens: 2, completion_tokens: 1 },
+        },
+      ],
+      { assistantReasoningField: "reasoning_content" },
+    );
+
+    await provider.sendMessage([
+      {
+        role: "assistant",
+        content: [
+          {
+            type: "thinking",
+            thinking: "anthropic thinking",
+            signature: "sig-abc",
+          },
+          { type: "thinking", thinking: "deepseek thinking", signature: "" },
+          { type: "text", text: "answer" },
+        ],
+      },
+    ]);
+
+    const params = requests[0] as {
+      messages: Array<{
+        role: string;
+        reasoning_content?: string;
+      }>;
+    };
+    expect(params.messages[0].reasoning_content).toBe("deepseek thinking");
+  });
 });

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,
@@ -54,6 +54,101 @@ export function detectOpenAICompatibleContextOverflow(
   return extractOverflowTokensFromMessage(message);
 }
 
+/**
+ * Build the human-readable error string surfaced from an
+ * `OpenAI.APIError`. The SDK's `error.message` is typically a one-line
+ * summary like `"400 Provider returned error"` — useless when the
+ * upstream is OpenRouter (which wraps the real downstream error on
+ * `error.error.metadata.raw`) or any provider that returns nested
+ * structured details.
+ *
+ * Returns `{ detail, requestId }` where `detail` includes the JSON body
+ * (truncated) and `requestId` is the upstream correlation header when
+ * present. Callers fold these into the thrown `ProviderError` so log
+ * lines actually identify the failure without re-running the request.
+ *
+ * Exported for tests.
+ */
+export function extractApiErrorDetail(
+  error: InstanceType<typeof OpenAI.APIError>,
+): { detail: string; requestId: string | undefined } {
+  const body = (error as { error?: unknown }).error;
+  let detail = "";
+  if (body !== undefined && body !== null) {
+    try {
+      const serialized = typeof body === "string" ? body : JSON.stringify(body);
+      if (serialized && serialized !== "{}") {
+        detail =
+          serialized.length > MAX_API_ERROR_DETAIL_CHARS
+            ? `${serialized.slice(0, MAX_API_ERROR_DETAIL_CHARS)}…`
+            : serialized;
+      }
+    } catch {
+      // Body had a cycle or threw on toJSON — fall through with empty detail.
+    }
+  }
+  const requestId = readHeader(error.headers, [
+    "x-request-id",
+    "x-openrouter-request-id",
+    "openai-request-id",
+    "x-amzn-requestid",
+  ]);
+  return { detail, requestId };
+}
+
+/** Cap on the inline-rendered body to keep log lines readable while still
+ *  surfacing the meaningful upstream payload. Tuned to comfortably hold
+ *  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.
+ * Mirrors the shape-tolerance already in `extractRetryAfterMs`.
+ */
+function readHeader(
+  headers: unknown,
+  names: readonly string[],
+): string | undefined {
+  if (!headers) return undefined;
+  const getter =
+    typeof (headers as { get?: unknown }).get === "function"
+      ? (headers as { get(name: string): string | null }).get.bind(headers)
+      : undefined;
+  for (const name of names) {
+    let value: string | null | undefined;
+    if (getter) {
+      value = getter(name);
+    } else if (typeof headers === "object") {
+      const record = headers as Record<string, unknown>;
+      const raw = record[name] ?? record[name.toLowerCase()];
+      value = typeof raw === "string" ? raw : undefined;
+    }
+    if (typeof value === "string" && value.length > 0) return value;
+  }
+  return undefined;
+}
+
 export interface OpenAIChatCompletionsProviderOptions {
   baseURL?: string;
   providerName?: string;
@@ -75,6 +170,17 @@ export interface OpenAIChatCompletionsProviderOptions {
    *  blocks. MiniMax and similar providers embed reasoning inside XML-style
    *  tags in the regular content field rather than using `reasoning_content`. */
   parseThinkTags?: boolean;
+  /** Wire field used to replay prior assistant thinking on multi-turn requests.
+   *  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
@@ -146,6 +252,11 @@ export class OpenAIChatCompletionsProvider implements Provider {
   private maxReasoningEffort: "high" | "xhigh" | "max";
   private requestHeaders: Record<string, string>;
   private parseThinkTags: boolean;
+  private assistantReasoningField:
+    | "reasoning"
+    | "reasoning_content"
+    | undefined;
+  private backfillEmptyAssistantContent: boolean;
 
   constructor(
     apiKey: string,
@@ -168,15 +279,16 @@ export class OpenAIChatCompletionsProvider implements Provider {
     this.maxReasoningEffort = options.maxReasoningEffort ?? "xhigh";
     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;
@@ -524,18 +636,18 @@ export class OpenAIChatCompletionsProvider implements Provider {
           ? signal.reason
           : undefined;
       if (error instanceof OpenAI.APIError) {
+        const { detail, requestId } = extractApiErrorDetail(error);
+        const detailSuffix = detail ? ` ${detail}` : "";
+        const requestIdSuffix = requestId ? ` [request_id=${requestId}]` : "";
+        const formattedMessage = `${this.providerLabel} API error (${error.status}): ${error.message}${detailSuffix}${requestIdSuffix}`;
         const overflow = detectOpenAICompatibleContextOverflow(error);
         if (overflow) {
-          throw new ContextOverflowError(
-            `${this.providerLabel} API error (${error.status}): ${error.message}`,
-            this.name,
-            {
-              actualTokens: overflow.actualTokens,
-              maxTokens: overflow.maxTokens,
-              statusCode: error.status,
-              cause: error,
-            },
-          );
+          throw new ContextOverflowError(formattedMessage, this.name, {
+            actualTokens: overflow.actualTokens,
+            maxTokens: overflow.maxTokens,
+            statusCode: error.status,
+            cause: error,
+          });
         }
         const retryAfterMs = extractRetryAfterMs(error.headers);
         const errorOptions: {
@@ -546,7 +658,7 @@ export class OpenAIChatCompletionsProvider implements Provider {
           errorOptions.retryAfterMs = retryAfterMs;
         if (abortReason) errorOptions.abortReason = abortReason;
         throw new ProviderError(
-          `${this.providerLabel} API error (${error.status}): ${error.message}`,
+          formattedMessage,
           this.name,
           error.status,
           Object.keys(errorOptions).length > 0 ? errorOptions : undefined,
@@ -661,6 +773,7 @@ export class OpenAIChatCompletionsProvider implements Provider {
     msg: Message,
   ): OpenAI.Chat.Completions.ChatCompletionAssistantMessageParam {
     const textParts: string[] = [];
+    const reasoningParts: string[] = [];
     const toolCalls: OpenAI.Chat.Completions.ChatCompletionMessageToolCall[] =
       [];
 
@@ -669,6 +782,10 @@ export class OpenAIChatCompletionsProvider implements Provider {
         case "text":
           textParts.push(block.text);
           break;
+        case "thinking":
+          // Anthropic thinking blocks carry signatures — skip those.
+          if (!block.signature) reasoningParts.push(block.thinking);
+          break;
         case "tool_use":
           toolCalls.push({
             id: block.id,
@@ -685,7 +802,7 @@ export class OpenAIChatCompletionsProvider implements Provider {
         case "web_search_tool_result":
           textParts.push("[Web search results]");
           break;
-        // thinking, redacted_thinking, image — not applicable for OpenAI assistant messages
+        // redacted_thinking, image — not applicable for OpenAI assistant messages
       }
     }
 
@@ -695,10 +812,32 @@ export class OpenAIChatCompletionsProvider implements Provider {
         content: textParts.length > 0 ? textParts.join("") : null,
       };
 
+    if (reasoningParts.length > 0 && this.assistantReasoningField) {
+      (
+        result as OpenAI.Chat.Completions.ChatCompletionAssistantMessageParam & {
+          reasoning?: string;
+          reasoning_content?: string;
+        }
+      )[this.assistantReasoningField] = reasoningParts.join("");
+    }
+
     if (toolCalls.length > 0) {
       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/codex-models.ts

@@ -8,7 +8,9 @@
  * resolution of an "Any active OpenAI connection" profile.
  */
 export const CODEX_SUBSCRIPTION_MODEL_IDS: ReadonlySet<string> = new Set([
+  "gpt-5.5",
   "gpt-5.4",
+  "gpt-5.4-mini",
   "gpt-5.3-codex",
 ]);