@vellumai/assistant 0.12.1 → 0.12.2-staging.2

package/src/providers/openai/google-thought-signature.ts

@@ -0,0 +1,320 @@
+import {
+  isGemini3Model,
+  unsignedThoughtSignatureFallback,
+} from "../gemini-thought-signature.js";
+import type { Message, ToolUseContent } from "../types.js";
+
+export type GoogleToolCallExtraContent = {
+  extra_content?: {
+    google?: {
+      thought_signature?: string;
+    };
+  };
+};
+
+export type GoogleThoughtSignatureRetryKind =
+  | "missing-thought-signature"
+  | "unknown-extra-content";
+
+function asNonEmptyString(value: unknown): string | undefined {
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+function googleObjectThoughtSignature(google: unknown): string | undefined {
+  if (google === null || typeof google !== "object") {
+    return undefined;
+  }
+  const record = google as Record<string, unknown>;
+  return (
+    asNonEmptyString(record.thought_signature) ??
+    asNonEmptyString(record.thoughtSignature)
+  );
+}
+
+/**
+ * Gemini's OpenAI-compatible wire format puts the thought signature on
+ * `tool_calls[].extra_content.google.thought_signature`.
+ */
+export function googleThoughtSignatureFromUnknown(
+  value: unknown,
+): string | undefined {
+  if (value === null || typeof value !== "object") {
+    return undefined;
+  }
+  const extra = (value as { extra_content?: unknown }).extra_content;
+  if (extra === null || typeof extra !== "object") {
+    return undefined;
+  }
+  return googleObjectThoughtSignature((extra as { google?: unknown }).google);
+}
+
+export function toolUseMetadataFromChatCompletionsDelta(
+  delta: unknown,
+): ToolUseContent["providerMetadata"] | undefined {
+  const thoughtSignature = googleThoughtSignatureFromUnknown(delta);
+  if (!thoughtSignature) {
+    return undefined;
+  }
+  return { gemini: { thoughtSignature } };
+}
+
+export function thoughtSignatureFromToolUseMetadata(
+  metadata: ToolUseContent["providerMetadata"] | undefined,
+): string | undefined {
+  return metadata?.gemini?.thoughtSignature;
+}
+
+export function attachGoogleThoughtSignature<T extends object>(
+  toolCall: T,
+  thoughtSignature: string | undefined,
+): T & GoogleToolCallExtraContent {
+  if (!thoughtSignature) {
+    return toolCall;
+  }
+  return {
+    ...toolCall,
+    extra_content: {
+      google: { thought_signature: thoughtSignature },
+    },
+  };
+}
+
+/**
+ * Attach Gemini extra_content only when the destination model is Gemini 3.x.
+ * Non-Gemini Chat Completions endpoints never see the vendor field on the
+ * first request. Remapped model ids that still require a signature recover
+ * via {@link backfillGoogleThoughtSignatures} after a 4xx.
+ */
+export function attachGoogleThoughtSignatureIfNeeded<T extends object>(
+  toolCall: T,
+  thoughtSignature: string | undefined,
+  model: string,
+): T & GoogleToolCallExtraContent {
+  if (!isGemini3Model(model)) {
+    return toolCall;
+  }
+  return attachGoogleThoughtSignature(toolCall, thoughtSignature);
+}
+
+function stampUnsignedGoogleThoughtSignature(
+  toolCalls: GoogleToolCallExtraContent[],
+  options?: { model?: string },
+): boolean {
+  const fallback = unsignedThoughtSignatureFallback(
+    toolCalls.map((tc) => googleThoughtSignatureFromUnknown(tc)),
+    options,
+  );
+  if (!fallback) {
+    return false;
+  }
+  const target = toolCalls[fallback.index];
+  if (!target) {
+    return false;
+  }
+  target.extra_content = {
+    google: { thought_signature: fallback.signature },
+  };
+  return true;
+}
+
+function stampCapturedGoogleThoughtSignatures(
+  toolCalls: Array<GoogleToolCallExtraContent & { id?: unknown }>,
+  capturedByCallId: ReadonlyMap<string, string>,
+): boolean {
+  let added = false;
+  for (const tc of toolCalls) {
+    if (typeof tc.id !== "string") {
+      continue;
+    }
+    const captured = capturedByCallId.get(tc.id);
+    if (!captured || googleThoughtSignatureFromUnknown(tc)) {
+      continue;
+    }
+    tc.extra_content = {
+      google: { thought_signature: captured },
+    };
+    added = true;
+  }
+  return added;
+}
+
+/**
+ * Gemini 3.x validates the first function call of each step. When none of the
+ * serialized tool_calls carry a captured signature, attach the documented dummy
+ * so unsigned history (or a non-capturing earlier turn) does not 400.
+ */
+export function applyGemini3UnsignedToolCallFallback(
+  toolCalls: GoogleToolCallExtraContent[],
+  model: string,
+): void {
+  stampUnsignedGoogleThoughtSignature(toolCalls, { model });
+}
+
+function paramsMessages(params: unknown): unknown[] | undefined {
+  const messages = (params as { messages?: unknown }).messages;
+  return Array.isArray(messages) ? messages : undefined;
+}
+
+function assistantToolCalls(
+  msg: unknown,
+): Array<GoogleToolCallExtraContent & { id?: unknown }> | undefined {
+  if (msg === null || typeof msg !== "object") {
+    return undefined;
+  }
+  const record = msg as { role?: unknown; tool_calls?: unknown };
+  if (record.role !== "assistant" || !Array.isArray(record.tool_calls)) {
+    return undefined;
+  }
+  return record.tool_calls as Array<
+    GoogleToolCallExtraContent & { id?: unknown }
+  >;
+}
+
+export function messagesCarryGoogleThoughtSignature(params: unknown): boolean {
+  const messages = paramsMessages(params);
+  if (!messages) {
+    return false;
+  }
+  return messages.some((msg) => {
+    const toolCalls = assistantToolCalls(msg);
+    return toolCalls?.some((tc) => googleThoughtSignatureFromUnknown(tc));
+  });
+}
+
+export function assistantToolCallsNeedThoughtSignatureBackfill(
+  params: unknown,
+): boolean {
+  const messages = paramsMessages(params);
+  if (!messages) {
+    return false;
+  }
+  return messages.some((msg) => {
+    const toolCalls = assistantToolCalls(msg);
+    if (!toolCalls || toolCalls.length === 0) {
+      return false;
+    }
+    return !toolCalls.some((tc) => googleThoughtSignatureFromUnknown(tc));
+  });
+}
+
+export function stripGoogleThoughtSignatures(params: unknown): boolean {
+  const messages = paramsMessages(params);
+  if (!messages) {
+    return false;
+  }
+  let stripped = false;
+  for (const msg of messages) {
+    const toolCalls = assistantToolCalls(msg);
+    if (!toolCalls) {
+      continue;
+    }
+    for (const tc of toolCalls) {
+      if (tc.extra_content !== undefined) {
+        delete tc.extra_content;
+        stripped = true;
+      }
+    }
+  }
+  return stripped;
+}
+
+export function geminiThoughtSignaturesByToolCallId(
+  messages: ReadonlyArray<Message>,
+): Map<string, string> {
+  const out = new Map<string, string>();
+  for (const msg of messages) {
+    if (msg.role !== "assistant") {
+      continue;
+    }
+    for (const block of msg.content) {
+      if (block.type !== "tool_use") {
+        continue;
+      }
+      const signature = block.providerMetadata?.gemini?.thoughtSignature;
+      if (signature) {
+        out.set(block.id, signature);
+      }
+    }
+  }
+  return out;
+}
+
+export function backfillGoogleThoughtSignatures(
+  params: unknown,
+  capturedByCallId?: ReadonlyMap<string, string>,
+): boolean {
+  const messages = paramsMessages(params);
+  if (!messages) {
+    return false;
+  }
+  let added = false;
+  for (const msg of messages) {
+    const toolCalls = assistantToolCalls(msg);
+    if (!toolCalls || toolCalls.length === 0) {
+      continue;
+    }
+    if (
+      capturedByCallId &&
+      stampCapturedGoogleThoughtSignatures(toolCalls, capturedByCallId)
+    ) {
+      added = true;
+    }
+    if (stampUnsignedGoogleThoughtSignature(toolCalls)) {
+      added = true;
+    }
+  }
+  return added;
+}
+
+export function backfillUnsignedGoogleThoughtSignatures(
+  params: unknown,
+): boolean {
+  return backfillGoogleThoughtSignatures(params);
+}
+
+const UNKNOWN_EXTRA_CONTENT_REJECTION =
+  /unknown|unexpected|unrecognized|additional propert|extra (?:field|property)|not (?:a )?valid|invalid (?:argument|parameter|field|property)/i;
+
+export function classifyGoogleThoughtSignatureRetry(
+  params: unknown,
+  options: {
+    isClientError: boolean;
+    haystack: string;
+    capturedByCallId?: ReadonlyMap<string, string>;
+  },
+): {
+  kind: GoogleThoughtSignatureRetryKind;
+  message: string;
+  apply: () => void;
+} | null {
+  if (!options.isClientError) {
+    return null;
+  }
+  if (
+    assistantToolCallsNeedThoughtSignatureBackfill(params) &&
+    /thought[_\s-]?signature/i.test(options.haystack)
+  ) {
+    return {
+      kind: "missing-thought-signature",
+      message:
+        "Upstream requires thought signature round-trip; retrying with signatures on unsigned tool_calls",
+      apply: () => {
+        backfillGoogleThoughtSignatures(params, options.capturedByCallId);
+      },
+    };
+  }
+  if (
+    messagesCarryGoogleThoughtSignature(params) &&
+    /extra_content/i.test(options.haystack) &&
+    UNKNOWN_EXTRA_CONTENT_REJECTION.test(options.haystack)
+  ) {
+    return {
+      kind: "unknown-extra-content",
+      message: "Upstream rejected tool_call extra_content; retrying without it",
+      apply: () => {
+        stripGoogleThoughtSignatures(params);
+      },
+    };
+  }
+  return null;
+}

package/src/providers/opencode/client.test.ts

@@ -1,4 +1,9 @@
-import { describe, expect, test } from "bun:test";
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+let mockDeviceId: string | null = null;
+mock.module("../../util/device-id.js", () => ({
+  getExistingDeviceId: () => mockDeviceId,
+}));
 
 import {
   EMPTY_ASSISTANT_TURN_PLACEHOLDER,
@@ -11,7 +16,9 @@ import {
   OPENCODE_SESSION_HEADER,
   OPENCODE_ZEN_BASE_URL,
   OpenCodeProvider,
+  resetOpenCodeFallbackSessionForTests,
   resolveOpenCodeBaseURL,
+  resolveOpenCodeRequestHeaders,
 } from "./client.js";
 
 describe("resolveOpenCodeBaseURL", () => {
@@ -72,15 +79,44 @@ describe("buildOpenCodeRequestHeaders", () => {
   });
 
   test("sets only the ids that are present", () => {
-    expect(
-      buildOpenCodeRequestHeaders({ conversationId: "conv-xyz" }),
-    ).toEqual({ [OPENCODE_SESSION_HEADER]: "conv-xyz" });
+    expect(buildOpenCodeRequestHeaders({ conversationId: "conv-xyz" })).toEqual(
+      { [OPENCODE_SESSION_HEADER]: "conv-xyz" },
+    );
     expect(buildOpenCodeRequestHeaders({ requestId: "req-123" })).toEqual({
       [OPENCODE_REQUEST_HEADER]: "req-123",
     });
   });
 });
 
+describe("resolveOpenCodeRequestHeaders", () => {
+  beforeEach(() => {
+    mockDeviceId = null;
+    resetOpenCodeFallbackSessionForTests();
+  });
+
+  test("uses the conversation id over the device id", () => {
+    mockDeviceId = "dev-123";
+    const headers = resolveOpenCodeRequestHeaders("conv-xyz");
+    expect(headers[OPENCODE_SESSION_HEADER]).toBe("conv-xyz");
+    expect(headers[OPENCODE_REQUEST_HEADER]).toMatch(/\S/);
+    expect(resolveOpenCodeRequestHeaders()[OPENCODE_SESSION_HEADER]).toBe(
+      "dev-123",
+    );
+  });
+
+  test("mints one process-stable session when there is no device id", () => {
+    const first = resolveOpenCodeRequestHeaders();
+    expect(first[OPENCODE_SESSION_HEADER]).toMatch(/\S/);
+    expect(first).not.toHaveProperty("session_id");
+    // Pinned: a device.json created later in the process does not move
+    // background traffic onto a second session.
+    mockDeviceId = "dev-123";
+    expect(resolveOpenCodeRequestHeaders()[OPENCODE_SESSION_HEADER]).toBe(
+      first[OPENCODE_SESSION_HEADER]!,
+    );
+  });
+});
+
 describe("OpenCodeProvider", () => {
   test("uses OpenAI chat-completions with reasoning-compatible knobs", () => {
     const provider = new OpenCodeProvider("sk-test", "mimo-v2.5-free");
@@ -137,6 +173,39 @@ describe("OpenCodeProvider", () => {
     expect(options.headers).not.toHaveProperty("session_id");
   });
 
+  test("stamps session and request headers on a configless call", async () => {
+    const provider = new OpenCodeProvider("sk-test", "mimo-v2.5-free");
+    const seen: Array<{ options: unknown }> = [];
+    (provider as unknown as { client: unknown }).client = {
+      chat: {
+        completions: {
+          create: async (_params: unknown, options: unknown) => {
+            seen.push({ options });
+            return {
+              async *[Symbol.asyncIterator]() {
+                yield {
+                  choices: [
+                    { delta: { content: "ok" }, finish_reason: "stop" },
+                  ],
+                  usage: { prompt_tokens: 2, completion_tokens: 1 },
+                };
+              },
+            };
+          },
+        },
+      },
+    };
+
+    await provider.sendMessage([
+      { role: "user", content: [{ type: "text", text: "question" }] },
+    ]);
+
+    const options = seen[0]!.options as { headers?: Record<string, string> };
+    expect(options.headers?.[OPENCODE_SESSION_HEADER]).toMatch(/\S/);
+    expect(options.headers?.[OPENCODE_REQUEST_HEADER]).toMatch(/\S/);
+    expect(options.headers).not.toHaveProperty("session_id");
+  });
+
   test("backfills placeholder content after an aborted empty assistant turn", async () => {
     const provider = new OpenCodeProvider("sk-test", "mimo-v2.5-free");
     const requests: unknown[] = [];

package/src/providers/opencode/client.ts

@@ -1,4 +1,12 @@
+import { randomUUID } from "node:crypto";
+
+import { getExistingDeviceId } from "../../util/device-id.js";
 import { OpenAIChatCompletionsProvider } from "../openai/chat-completions-provider.js";
+import type {
+  Message,
+  ProviderResponse,
+  SendMessageOptions,
+} from "../types.js";
 
 export const OPENCODE_ZEN_BASE_URL = "https://opencode.ai/zen/v1";
 export const OPENCODE_GO_BASE_URL = "https://opencode.ai/zen/go/v1";
@@ -27,9 +35,8 @@ export function resolveOpenCodeBaseURL(configuredBaseURL?: string): string {
  * request ids only when they exist. Never sets `session_id` (zen/go
  * returns 500 when that header is present).
  *
- * `conversationId` wins for the session header; `fallbackSessionId` (a
- * stable per-device ID supplied by the caller) covers non-conversation
- * background calls so they still identify a session to zen/go.
+ * `conversationId` wins for the session header; `fallbackSessionId` covers
+ * non-conversation calls so they still identify a session to zen/go.
  */
 export function buildOpenCodeRequestHeaders(opts: {
   conversationId?: string;
@@ -48,6 +55,33 @@ export function buildOpenCodeRequestHeaders(opts: {
   return headers;
 }
 
+let fallbackSessionId: string | undefined;
+
+/** @internal */
+export function resetOpenCodeFallbackSessionForTests(): void {
+  fallbackSessionId = undefined;
+}
+
+/**
+ * Headers for one outgoing OpenCode request. The session header is never
+ * omitted, because zen/go rejects requests without `x-opencode-session`:
+ * `conversationId` when the call has one, otherwise a fallback resolved
+ * once per process (the stable per-device ID if device.json exists at that
+ * point, else a fresh UUID) and pinned, so non-conversation traffic stays on
+ * one session even if device.json is created later. Transport metadata
+ * only; nothing here enters the request body.
+ */
+export function resolveOpenCodeRequestHeaders(
+  conversationId?: string,
+): Record<string, string> {
+  fallbackSessionId ??= getExistingDeviceId() ?? randomUUID();
+  return buildOpenCodeRequestHeaders({
+    conversationId,
+    fallbackSessionId,
+    requestId: randomUUID(),
+  });
+}
+
 export class OpenCodeProvider extends OpenAIChatCompletionsProvider {
   constructor(
     apiKey: string,
@@ -63,4 +97,27 @@ export class OpenCodeProvider extends OpenAIChatCompletionsProvider {
       omitToolChoiceWhenReasoning: true,
     });
   }
+
+  /**
+   * Transport-level backstop so a call that reaches this provider without
+   * going through `RetryProvider` (or with no config at all) still carries
+   * the session and request headers zen/go requires. Headers the caller
+   * already resolved (conversation-derived) win.
+   */
+  override async sendMessage(
+    messages: Message[],
+    options?: SendMessageOptions,
+  ): Promise<ProviderResponse> {
+    const config = options?.config ?? {};
+    return super.sendMessage(messages, {
+      ...options,
+      config: {
+        ...config,
+        requestHeaders: {
+          ...resolveOpenCodeRequestHeaders(),
+          ...config.requestHeaders,
+        },
+      },
+    });
+  }
 }

package/src/providers/openrouter/client.ts

@@ -36,6 +36,19 @@ const OPENROUTER_APP_ATTRIBUTION_HEADERS = {
 
 const OPENROUTER_MODEL_EFFORT_CEILINGS = modelEffortCeilings("openrouter");
 
+const OPENROUTER_MAX_COMPLETION_TOKENS_ONLY = /gpt-5\.[12]-(?:codex|chat)/;
+
+/** Output-token-limit wire key for an OpenRouter model id. Most endpoints
+ *  advertise `max_tokens`; GPT-5.1/5.2 Codex and Chat advertise only
+ *  `max_completion_tokens`. Exported for tests. */
+export function openRouterOutputTokenLimitField(
+  model: string,
+): "max_completion_tokens" | "max_tokens" {
+  return OPENROUTER_MAX_COMPLETION_TOKENS_ONLY.test(model)
+    ? "max_completion_tokens"
+    : "max_tokens";
+}
+
 /**
  * Extract the normalized `openrouter.only` list from a per-call config. Returns
  * an empty array when the field is absent, empty, or contains no usable string
@@ -143,6 +156,7 @@ export class OpenRouterProvider extends OpenAIChatCompletionsProvider {
       streamTimeoutMs: options.streamTimeoutMs,
       requestHeaders: OPENROUTER_APP_ATTRIBUTION_HEADERS,
       assistantReasoningField: "reasoning",
+      outputTokenLimitField: "max_tokens",
     });
     this.openRouterApiKey = apiKey;
     this.resolvedBaseURL = baseURL;
@@ -250,6 +264,12 @@ export class OpenRouterProvider extends OpenAIChatCompletionsProvider {
     );
   }
 
+  protected override resolveOutputTokenLimitField(
+    model: string,
+  ): "max_completion_tokens" | "max_tokens" {
+    return openRouterOutputTokenLimitField(model);
+  }
+
   private resolveEffectiveModel(options?: SendMessageOptions): string {
     const config = options?.config as Record<string, unknown> | undefined;
     const override =

package/src/providers/outbound-request-sanitize.ts

@@ -0,0 +1,96 @@
+/**
+ * Outbound-request Unicode guard for every provider adapter.
+ *
+ * JavaScript strings are UTF-16, and any `.slice()` on a code-unit boundary
+ * can orphan half of a surrogate pair. `JSON.stringify` emits the orphan as a
+ * `\udXXX` escape, which strict API parsers reject with a 400 before the model
+ * runs (Anthropic: "no low surrogate in string"; OpenAI: `invalid_json`).
+ * `RetryProvider` sanitizes the caller's messages and options once at entry,
+ * so every attempt, corrective resend, credential refresh, and backup route
+ * sends a clean payload, and sanitizes token-count requests the same way.
+ * Nothing beneath the wrapper truncates text, so this is the one place the
+ * invariant is enforced.
+ *
+ * The replacement is lossy (U+FFFD), so the warning names the block types
+ * involved: the durable fix for any offender is a surrogate-safe slice at the
+ * truncation site (`safeStringSlice` in `util/unicode.ts`).
+ */
+
+import { getLogger } from "../util/logger.js";
+import { stripOrphanedSurrogatesDeep } from "../util/unicode.js";
+import type { Message, SendMessageOptions } from "./types.js";
+
+const log = getLogger("outbound-request-sanitize");
+
+/** Rate-limit the warning so a poisoned conversation cannot flood the log. */
+const ORPHAN_WARNING_THROTTLE_MS = 60_000;
+let lastOrphanWarningMs = 0;
+
+export interface OutboundRequest {
+  messages: Message[];
+  options: SendMessageOptions | undefined;
+}
+
+/**
+ * Fields that hold provider-bound base64 (an inline media source's payload,
+ * a redacted-thinking blob) are ASCII by construction and can run to over a
+ * hundred megabytes, so scanning them is pure event-loop cost.
+ */
+function isBase64Payload(
+  key: string,
+  parent: Record<string, unknown>,
+): boolean {
+  return (
+    key === "data" &&
+    (parent.type === "base64" || parent.type === "redacted_thinking")
+  );
+}
+
+/**
+ * Replace every orphaned UTF-16 surrogate in the request's messages and
+ * options with U+FFFD. Returns the same references when nothing needed
+ * fixing, so the happy path allocates nothing.
+ */
+export function sanitizeOutboundRequest(
+  providerName: string,
+  request: OutboundRequest,
+): OutboundRequest {
+  const sanitized = stripOrphanedSurrogatesDeep(request, {
+    skipKey: isBase64Payload,
+  });
+  if (!sanitized.changed) {
+    return request;
+  }
+  logOrphanedSurrogateWarning(
+    providerName,
+    sanitized.fixedStringCount,
+    request.messages,
+  );
+  return sanitized.value;
+}
+
+function logOrphanedSurrogateWarning(
+  providerName: string,
+  fixedStringCount: number,
+  messages: Message[],
+): void {
+  const now = Date.now();
+  if (now - lastOrphanWarningMs < ORPHAN_WARNING_THROTTLE_MS) {
+    return;
+  }
+  lastOrphanWarningMs = now;
+  const blockTypes = new Set<string>();
+  for (const msg of messages) {
+    for (const block of msg.content) {
+      blockTypes.add(block.type);
+    }
+  }
+  log.warn(
+    {
+      provider: providerName,
+      fixedStringCount,
+      blockTypes: Array.from(blockTypes),
+    },
+    "stripped orphaned UTF-16 surrogates from an outbound LLM request; an upstream truncation is not surrogate-aware",
+  );
+}