@tanstack/ai-openrouter

Major Changes

• breaking

  TanStack AI 1.0.0. This release removes every API that was deprecated in 0.x. Read the upgrade guide before you upgrade: tanstack.com/ai/latest/docs/migration/v1

  • Removed all @deprecated exports, options, fields, and type aliases. Each one has a replacement that already shipped in 0.x.

  • Removed addToolApprovalResponse() from ChatClient and every chat hook. Resolve the bound tool-approval interrupt with resolveInterrupt instead. The devtools event tools:approval:responded is also removed.

  • Removed the old wire formats: the CUSTOM approval-requested and tool-input-available events, the [DONE] SSE line, the data copy of forwardedProps, pre-binding interrupt descriptors and their approval_required and client_tool_input reasons, and the STEP events that adapters sent next to REASONING_* events. Use a 1.0 client with a 1.0 server.

  • Removed the toolName alias from TOOL_CALL_START chunks. Read toolCallName instead.

  • threadId is now required on useChat and every other chat hook, ChatClient, the generation hooks and clients, chat(), summarize(), the generation functions, codeModeWithSnippets(), selectRelevantSnippets(), CompactionContext, and SummarizeInput. TanStack AI no longer makes a thread id for you. Pass a stable id for each conversation. createChatHook factory options no longer take threadId: pass it on each hook call. Octane generation hooks take threadId instead of id. @tanstack/ai-sandbox removes resolveDurableThreadId and DurableThreadIdRequiredError.

  • The published @tanstack/ai-octane/ui types are now strict. UI.Messages, UI.Message, UI.Part, and UI.Interrupts type their render children. ToolProps types part.input and part.output for the named tool. toolsComponents and interruptsComponents are required when the chat options declare tools or named interrupts. Code that relied on the old loose types can fail to compile.

  • A connection adapter's connect() and send() need the run context (with threadId) as their fourth argument. ChatClient and the generation clients pass it.

  • @tanstack/ai-sandbox: createToolBridgeCore(), startHostToolBridge(), a ToolBridgeProvisioner, and executeHostTool() take a required threadId. Bridged tools get it in their context.

  • @tanstack/ai-sandbox: the harness tool bridge and executeHostTool() refuse a tool with needsApproval. Before, the tool ran with no approval. Remove needsApproval, or run the tool with an HTTP adapter.

  • stream() and rpcStream() pass the AG-UI RunAgentInput for the run as the fourth factory argument, the same body the HTTP adapters send. Read it on the server with chatParamsFromRequestBody() or generationParamsFromBody(), so threadId, runId, and interrupt resume reach a server function. RunAgentInput is exported from @tanstack/ai/client.

  • A generation fetcher gets threadId and runId in its second argument, next to signal and headers. Pass them to the server generation call.

  • generationParamsFromBody() and generationParamsFromRequest() read the generation input from forwardedProps. A server that reads body.data gets undefined. Read body.forwardedProps instead. They also require threadId and runId and return them as strings, the same as chatParamsFromRequestBody() and the AG-UI RunAgentInput. A body that holds only the input is rejected.

  • Removed the readers for data saved in old 0.x formats (old Cloudflare run-log records, a bare UIMessage from client persistence, artifact records without blobKey).

  • Removed provider models that are shut down.

  • @tanstack/ai-react-ui, @tanstack/ai-solid-ui, and @tanstack/ai-vue-ui get no 1.0 release. Import from @tanstack/ai-react/ui, @tanstack/ai-solid/ui, or @tanstack/ai-vue/ui.

Minor Changes

• The TypeSafe, Ollaya, OpenRouter and Vercel Gateway evaluate adapters now set status on the error they throw for an error response. status is the HTTP status code, so you can tell a rate limit (429) from a bad key (401) without parsing the message. The message does not change.

  if (error instanceof Error && 'status' in error && error.status === 429) {
    // wait, then call decide() again
  }

Patch Changes

• Update model metadata from OpenRouter API

Minor Changes

• Structured output sends response_format: { type: "json_object" } for OpenRouter and Groq models that declare a response format without strict structured outputs. These models reject strict json_schema. In JSON mode the adapter adds the schema as a system prompt. await chat({ outputSchema }) checks the reply when the schema is a Standard Schema, such as Zod. Other models keep strict json_schema.

  modelOptions can set json_object for any model. On the OpenAI-base adapters (OpenAI, Grok, Groq and others), a json_object in modelOptions was replaced by strict json_schema. It is now sent as given, with the schema in a system prompt. In JSON mode, supportsCombinedToolsAndSchema() returns false. Tools and the schema then go out in separate requests, so the tool-calling turns do not get the schema prompt.

  OpenRouter catalog ids with a :variant, such as google/gemma-4-26b-a4b-it:free, now match their own catalog entry. Before, only the id without the variant was checked.

Patch Changes

• Keep the provider's raw tool argument string for replay.

  • Adapters now send the raw argument string as args on TOOL_CALL_END.

  • The tool call in the history keeps that exact string when it is the same JSON value as the parsed input, so the next request sends the provider's own bytes back (for example 1.50, or an id past Number.MAX_SAFE_INTEGER). When the parsed input differs, only the changed values are written again.

  • The TOOL_CALL_END that reaches the client carries the same string in metadata.tanstack.args, so the client history matches the server history. It no longer also carries metadata.tanstack.input: in-process chat() and StreamProcessor parse input from args. Run the client and the server on the same release: an older client ignores args, so it builds the tool input from the streamed deltas only, and a tool call with no deltas (for example an Anthropic server tool) gets no input.

  • History converters for Bedrock and the Gemini Interactions API send malformed tool arguments as {} instead of failing the request.

  • Gemini Interactions: the initial step.arguments snapshot goes out as a TOOL_CALL_ARGS delta only when no argument deltas follow, so the deltas always add up to the final arguments.

  • Malformed tool arguments are no longer turned into {} by an adapter. The tool gets a "Failed to parse tool arguments as JSON" error that the model can repair. Mistral still ends the run with an error on malformed arguments, as before.

Minor Changes

• Text adapters now set one stable code on RUN_ERROR when the input does not fit in the model's context window: code: 'context_overflow'. @tanstack/ai exports it as CONTEXT_OVERFLOW_CODE. The provider's own text stays in message.

  if (chunk.type === 'RUN_ERROR' && chunk.code === CONTEXT_OVERFLOW_CODE) {
    // shorten the messages, then call chat() again
  }

  These adapters set it: OpenAI and the other OpenAI-compatible adapters (from code: 'context_length_exceeded'), Anthropic, Gemini, Bedrock (Converse, Chat Completions, and Responses), OpenRouter, Grok, Cloudflare Workers AI, and BytePlus.

  Changes to code that reads the old values:

  • OpenAI-compatible adapters gave code: 'context_length_exceeded'. They now give 'context_overflow'. rawEvent still has the provider's code.

  • Anthropic, Grok, OpenRouter, and BytePlus gave the HTTP status or a general bad-request code for this error. Gemini and Bedrock Converse gave no code.

  • The Anthropic adapter now sends RUN_ERROR with this code when the model stops with stop_reason: 'model_context_window_exceeded'. Before, it sent RUN_FINISHED with finishReason: 'stop', so a cut-off answer looked complete.

• Add openrouterSignIn() at @tanstack/ai-openrouter/pkce: a local app, such as a CLI, signs the user in to OpenRouter in the browser and gets an API key, with no key to copy.

• Prompt caching is now on by default. Each chat() call asks the provider to cache the stable start of the request (system prompt, tools, and earlier messages), so repeated requests cost less and answer sooner.

  • New chat() option promptCache: 'none' | 'short' | 'long', or { retention, key }. The default is 'short'. The key is promptCache.key, else the threadId or conversationId that you give. A threadId that chat() makes up is never the key.

  • To turn it off, pass promptCache: 'none'. Do this for a large prompt that you send to Claude one time only, because Claude bills the cache write.

  • A middleware can change it for the next model call: onConfig gets config.promptCache and can return a new value.

  • Each adapter sends its own fields:

    • Claude on Anthropic, Bedrock Converse, and OpenRouter gets cache markers. 'long' asks for the 1-hour TTL.

    • OpenAI (Responses and Chat Completions) gets prompt_cache_key, and prompt_cache_retention or prompt_cache_options on 'long'.

    • Mistral gets prompt_cache_key, and usage now reports cache reads.

    • OpenRouter gets sessionId.

  • A manual cache_control, cachePoint, prompt_cache_key, or sessionId wins over the automatic value.

  • New types: PromptCacheRetention, PromptCacheOptions, and ResolvedPromptCache. Adapters read TextOptions.promptCache.

• Set reasoning with chat({ reasoning }) on both OpenRouter adapters.

  • The chat adapter sends reasoning.effort, and none for off. Its request has no budget field, so its types take no budgetTokens.

  • The Responses adapter sends reasoning.effort, summary: 'auto' when the summary is on, and maxTokens for budgetTokens.

  • Each model has its reasoning data in model-meta.ts. OpenRouterModelReasoningByName and OPENROUTER_MODEL_REASONING come from it.

  Breaking: reasoning is no longer in modelOptions, and ReasoningOptions is removed.

  // Before
  chat({
    adapter: openRouterText('openai/gpt-5.5'),
    messages,
    modelOptions: { reasoning: { enabled: false } },
  })
  
  // After
  chat({
    adapter: openRouterText('openai/gpt-5.5'),
    messages,
    reasoning: 'off',
  })

Patch Changes

• Fix three gaps in the OpenRouter Responses adapter (openRouterResponsesText):

  • Usage now has promptTokensDetails.cachedTokens when the response reports cached input tokens.

  • An output item that the OpenRouter SDK cannot parse (the SDK gives it as { type: 'UNKNOWN', isUnknown: true, raw }) is now read from its raw item, in the stream and in structuredOutput. Before this fix, that function call or message was lost.

  • The namespace of a function call is now kept in the tool call metadata and sent back when the call is replayed.

• chat({ retry }) now retries an OpenRouter provider error that arrives in the stream. OpenRouter can send status 200 before the provider fails. The error then comes as an error chunk that the SDK cannot retry. When the code of that chunk is in retryCodes (default ['5XX'], add '429' to retry a rate limit), the RUN_ERROR of the Chat Completions adapter now has retryAfterMs set to the initialInterval of retryConfig (default 500). chat() retries it only when the call streamed no output yet. An error after part of the answer is not retried. retryConfig: { strategy: 'none' } turns this off.

• Keep a schema property or a tool argument named __proto__. Before this fix, code that copied it with out[key] = value went to the __proto__ setter instead, so the key was lost.

  • @tanstack/ai-utils: transformNullsToUndefined and undoNullWidening keep the key.

  • @tanstack/openai-base: the strict schema and its null-widening map keep the key.

  • @tanstack/ai-mistral: the null-widening map keeps the key.

  • @tanstack/ai-openrouter: the Responses tool input normalizer keeps the key.

  • @tanstack/ai-gemini: the Interactions adapter keeps the key in tool parameters.

  • @tanstack/ai-bedrock: the Converse adapter puts the tool schemas and tool inputs back into the request body after the AWS SDK serializes it, because the SDK drops the key.

• Keep a conversation valid when the next request goes to a different model.

  • Each assistant message records metadata.tanstack.source ({ provider, api, model }), and responseId and the resolved model when the provider sends them. A failed or aborted answer gets stopReason: 'error' or 'aborted'. RUN_FINISHED has a new responseId field. TextAdapter has new optional provider and api fields.

  • When the next request goes to a different source, the adapter removes signatures and redacted thinking, turns readable thinking into text, and rewrites tool call IDs to the shape the target API accepts. Each call stays paired with its result.

  • Every request drops failed and aborted assistant batches and adds a No result provided result for an unanswered tool call. The saved history does not change.

  • RUN_FINISHED and RUN_ERROR metadata now merge onto the assistant messages of that model call in StreamProcessor.

  • Anthropic: the new allowEmptySignature option (default false) replays unsigned thinking from the same source, for gateways. The new provider option names a gateway.

  • Azure OpenAI reports the azure-openai-responses API.

  • Gemini, Mistral, and Bedrock Converse send same-source thinking back to the model, in block order.

  • withPersistence writes the source and the stop reason onto streaming snapshot rows.

  • Adapter authors get transformMessagesForReplay() and hashToolCallId() from @tanstack/ai/adapter-internals.

• Send chat({ toolChoice }) to each provider.

  • Anthropic and Bedrock Converse. Claude Fable 5.1, Mythos 5.1, Opus 5.5, and Sonnet 5.5 reject a forced tool, and every Claude model rejects one while thinking is on. On those, 'required' and a named tool fall back to auto.

  • Bedrock Converse has no none. 'none' sends no tool config. Bedrock refuses tool calls in the history without a tool config, so the history goes out as text.

  • Gemini maps the choice to functionCallingConfig (AUTO, NONE, ANY, and allowedFunctionNames). With only provider tools, such as Google Search, it sends no tool config.

  • OpenAI and Azure OpenAI (Responses), Grok, Mistral, and OpenRouter (Chat Completions and Responses) send their own tool_choice shape.

• Images in tool results now reach the model on Chat Completions and on OpenRouter Responses.

  • Chat Completions adapters (OpenAI and the adapters built on @tanstack/openai-base, and OpenRouter chat) send the tool text in the tool message and the images in one user message after the tool results. Before this fix, OpenAI sent the parts as a JSON string in the tool text, and OpenRouter dropped the images.

  • OpenRouter Responses sends the images as input_image parts of the function call output. Before this fix, it dropped them.

  • On Chat Completions, a result with only images gets the tool text (see attached image).

  • A model without image input gets no images. A result with only images then has the text (image omitted: this model has no image input). The OpenAI Responses adapter now uses this text too.

  • Other media (audio, video, documents) in a tool result with images is not sent on these adapters.

  • OpenRouter chat with automatic prompt caching on an anthropic/* model puts the cache marker on the tool result before that image message, because the image message has no text block.