@vellumai/assistant 0.12.0 → 0.12.1-dev.202609142113.d1590bc

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/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",
+  );
+}

package/src/providers/retry.ts

@@ -44,6 +44,7 @@ import {
   isAdaptiveThinkingUnsupportedModel,
 } from "./model-catalog.js";
 import { buildOpenCodeRequestHeaders } from "./opencode/client.js";
+import { sanitizeOutboundRequest } from "./outbound-request-sanitize.js";
 import { dispatchProviderResolvable } from "./provider-resolvability.js";
 import {
   isThinkingConfigAdaptive,
@@ -1142,8 +1143,9 @@ export class RetryProvider implements Provider {
 
   // Forward the optional token-counting endpoint so the capability survives
   // the wrapper chain (callers gate on its presence). Bound straight to the
-  // inner provider — count_tokens is a cheap separate endpoint and its caller
-  // already falls back on error, so it needs no retry wrapping.
+  // inner provider behind the same surrogate sanitizer as `sendMessage` —
+  // count_tokens is a cheap separate endpoint and its caller already falls
+  // back on error, so it needs no retry wrapping.
   // Deliberately not re-bound when a credential refresh swaps `inner`: every
   // outer wrapper snapshots this the same way at construction, so a re-bind
   // here would never reach callers. count_tokens on the pre-refresh credential
@@ -1188,7 +1190,18 @@ export class RetryProvider implements Provider {
     this.inner = inner;
     this.name = inner.name;
     if (inner.countInputTokens) {
-      this.countInputTokens = inner.countInputTokens.bind(inner);
+      const countInputTokens = inner.countInputTokens.bind(inner);
+      this.countInputTokens = (messages, systemPrompt, tools) => {
+        const clean = sanitizeOutboundRequest(this.name, {
+          messages,
+          options: { systemPrompt, tools },
+        });
+        return countInputTokens(
+          clean.messages,
+          clean.options?.systemPrompt ?? systemPrompt,
+          clean.options?.tools,
+        );
+      };
     }
   }
 
@@ -1262,6 +1275,14 @@ export class RetryProvider implements Provider {
     let credentialRefreshAttempted = false;
     let correctiveResendAttempted = false;
     let fallbackAttempted = false;
+
+    // Every attempt below, the backup route included, sends what this
+    // wrapper was handed, so an orphaned UTF-16 surrogate is stripped here
+    // once rather than rejected by the upstream parser on every resend.
+    ({ messages, options } = sanitizeOutboundRequest(this.name, {
+      messages,
+      options,
+    }));
     let messagesForAttempt = messages;
 
     const normalizedOptions = normalizeSendMessageOptions(this.name, options, {

package/src/providers/unparseable-tool-args.ts

@@ -12,6 +12,8 @@
  * an error tool result, so the model sees the failure and can retry, instead
  * of a tool executing with garbage input.
  */
+
+import { safeStringSlice } from "../util/unicode.js";
 const UNPARSEABLE_TOOL_ARGS_KEY = "_raw";
 
 /**
@@ -56,7 +58,9 @@ export function unparseableToolArgsMessage(
 ): string {
   const PREVIEW_LIMIT = 200;
   const preview =
-    raw.length > PREVIEW_LIMIT ? `${raw.slice(0, PREVIEW_LIMIT)}…` : raw;
+    raw.length > PREVIEW_LIMIT
+      ? `${safeStringSlice(raw, 0, PREVIEW_LIMIT)}…`
+      : raw;
   return (
     `Error: the arguments for "${toolName}" were not valid JSON — the argument stream was malformed or truncated, so the tool was NOT executed. ` +
     `Received: ${preview || "(empty)"}\n` +

package/src/runtime/AGENTS.md

@@ -12,6 +12,8 @@ The single HTTP send endpoint is `POST /v1/messages`. Key behaviors:
 
 Do NOT add new send endpoints. All message ingress should go through `POST /v1/messages` (HTTP).
 
+`POST /v1/channels/send` is not ingress: it is outbound delivery, the assistant posting text to a channel chat. It runs `sendChannelText` (`runtime/channel-send.ts`), the one send implementation for every channel whose transport declares proactive addressing (`ChannelTransport.addressFor`), and the messaging tool's channel branch runs the same function in-process, as the CLI's channel send door does over the route. A model-directed channel send goes through that function or it is not recorded; do not add a provider-side send for a channel that has a transport. The route names no sending turn: only the in-process tool call can claim a send landed in the turn's own chat, so everything sent through the route is recorded.
+
 **`interrupt-on-send`: a send may stop the running turn instead of queueing behind it.** With the flag on, a busy conversation is handed to `interruptRunningTurn` (`daemon/conversation-interrupt.ts`), which aborts the turn with `preempted_by_new_message`, waits for it to release the processing lock AND for its turn-boundary commit to finish, repairs the abandoned `tool_use` blocks with a persisted synthetic `tool_result`, and answers `released`. The route then falls through to the code an idle conversation already uses, so there is one turn dispatch rather than a second one for interrupts. The queue is not discarded: it may hold another actor's messages.
 
 **The handover runs off the response, not on it.** Fire-and-forget is not suspended for an interrupt. The eligibility decision is synchronous (`classifyInterruptEligibility`), so the route answers `202 { accepted, requestId }` the moment it accepts the message, then runs the abort, the release wait, the commit wait, the repair, the persist and the dispatch in a detached task. Holding the request would cost the abort budget (`ABORT_RELEASE_WAIT_MS`) plus the turn-boundary commit wait, long enough for a client to time out and retry a message the daemon is still placing. That 202 carries `messageId` as well as `requestId`, and they are the same value: a user turn persists its row under its `requestId` (`persistUserMessage` passes `id: requestId`), which is what lets the id be answered before the row exists. Both are required, not decorative: `postChatMessage` rejects an accepted, non-queued response without a string `messageId` and the client drops the optimistic row. Clients reconcile that row on `user_message_echo`. Two rules for anything added to that task: it must not be able to drop the message (every failure path falls back to `queueSend`, which never takes the enqueue's idle fast path, and a queue that refuses the fallback is reported to the sender as a `QUEUE_FULL` error keyed on the `requestId` the 202 carried, since the 429 itself reaches nobody), and a duplicate `clientMessageId` is answered from the existing row BEFORE the abort, since the insert's own dedup settles too late to un-abort a turn.
@@ -95,7 +97,7 @@ Host CU allows the assistant to proxy computer-use actions (screenshots, mouse/k
 
 - **Discovery**: Clients discover pending host CU requests via SSE events (`host_cu_request`) which include a `requestId`.
 - **Resolution**: Clients execute the CU action on the host and respond via:
-  - `POST /v1/host-cu-result` — `{ requestId, axTree?, axDiff?, screenshot?, screenshotWidthPx?, screenshotHeightPx?, screenWidthPt?, screenHeightPt?, executionResult?, executionError?, secondaryWindows?, userGuidance? }`
+  - `POST /v1/host-cu-result`: `{ requestId, axTree?, axDiff?, screenshot?, screenshotWidthPx?, screenshotHeightPx?, screenWidthPt?, screenHeightPt?, executionResult?, executionError?, secondaryWindows?, userGuidance?, timings? }`, where `timings` is optional per-phase helper timings in milliseconds
 - **Tracking**: Uses the same `pending-interactions` tracker as the other host proxy types, with `kind: "host_cu"`. Registration happens in `conversation-routes.ts` and the route handler is in `host-cu-routes.ts`.
 - **Conversation-agnostic observation**: `observeHostScreen()` in `host-observe.ts` issues a `computer_use_observe` request with no conversation, for callers outside an agent turn (`HostCuProxy` only exists inside one). It takes the initiating actor's principal id and reaches only that actor's own `host_cu` clients: `pickSameUserAutoResolve` picks the default target and `enforceSameActorOrErrorResult` gates an explicitly named one, both before the request is registered or broadcast. Its pending interaction carries no `conversationId`, so `host-cu-routes.ts` hands the raw observation fields straight to the waiting caller instead of routing through a conversation's CU proxy. On the desktop side the ordinary `host_cu` executor services the request.