@tanstack/ai-bedrock

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.

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.

• 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 the three Bedrock APIs.

  • Chat Completions sends reasoning_effort. Responses sends reasoning.effort.

  • Converse sends thinking only for Claude: budget thinking in additionalModelRequestFields with the interleaved-thinking beta, and maxTokens grows past the budget. A model with effort levels gets adaptive thinking with output_config.effort. off sends nothing.

  • The reasoning data is in model-meta.ts, keyed by catalog id. BedrockModelReasoningByName and BEDROCK_MODEL_REASONING come from it.

  Breaking: reasoning_effort (Chat Completions) and reasoning (Responses) are no longer in modelOptions.

  // Before
  chat({
    adapter: bedrockText('openai.gpt-oss-120b-1:0', { api: 'chat' }),
    messages,
    modelOptions: { reasoning_effort: 'high' },
  })
  
  // After
  chat({
    adapter: bedrockText('openai.gpt-oss-120b-1:0', { api: 'chat' }),
    messages,
    reasoning: 'high',
  })

  Structured output sends no thinking, because Claude cannot think while a tool is forced.

Patch Changes

• The Bedrock text adapters (Converse, Chat Completions, and Responses) now set inputModalities from the model catalog. Before, it was always undefined. A known model gives the input kinds it reads, and an unknown model gives undefined.

  On the Responses API, this also means a text-only model such as openai.gpt-oss-120b-1:0 no longer gets image parts in a tool result, the same as other Responses adapters.

• The Bedrock Converse adapter now sends tool history as text when a chat request has no tools. Bedrock needs a toolConfig for toolUse and toolResult blocks, so before this fix such a request failed with a 400 error. The saved messages do not change.

• The Bedrock Converse adapter now sends an inline tool-result image as a Converse image block on Amazon Nova and Anthropic Claude 3 and 4. Other models, URL images, and unsupported image types still send only the text. A tool result with only an image does not get an empty text block.

• 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.

Minor Changes

• usage.promptTokens is now the total input on the Anthropic, Bedrock Converse, and Claude Code adapters. It is the uncached tokens plus the cache reads plus the cache writes. Before, it was the uncached tokens only. totalTokens now uses the new promptTokens. The cache parts stay in promptTokensDetails.cachedTokens and promptTokensDetails.cacheWriteTokens. Other adapters already report promptTokens this way.

  Breaking: if your code adds cachedTokens or cacheWriteTokens to promptTokens to get the total input, it now counts the cache two times. Use promptTokens as the total. To get the uncached tokens, subtract cachedTokens and cacheWriteTokens from promptTokens.

Patch Changes

• Add wrapFetch to chat(), to the middleware onConfig config, and to TextOptions. A wrapper gets the next fetch and gives back a new fetch. Use it to change the URL, the headers, the request, or the response of a model call. The new FetchWrapper type names the wrapper.

  The engine chains the chat() wrapper and the middleware wrappers into one function. A middleware wrapper runs inside the chat() wrapper and applies to one model call only.

  These text adapters send their requests through the wrapper: every adapter on @tanstack/openai-base (OpenAI, the OpenAI-compatible adapters, Grok, Groq, BytePlus, LLM Gateway, Lovable, Vercel AI Gateway, Cloudflare, and the Bedrock Chat Completions and Responses APIs), Anthropic, Mistral, Ollama, and OpenRouter. The wrapper wraps the fetch of the adapter config, not the global fetch. An Anthropic or Ollama adapter with an injected client ignores wrapFetch. In Cloudflare binding mode, the wrapper runs, but the binding does not send the URL or the headers. Without wrapFetch, the requests do not change.

Patch Changes

• Update the openai SDK dependency to ^7.30.0. openai 7 requires Node.js 22 or later.

Patch Changes

• Use the Bedrock API compatibility config's mantlePath on the Mantle endpoint so Gemma 4 hits /openai/v1 instead of a misleading 401. Other models stay on /v1.

Patch Changes

• Accept baseURL and defaultHeaders on every adapter's client config so one gateway config (Cloudflare AI Gateway, Vercel AI Gateway, a corporate proxy) can be spread into any adapter. The vendor-specific names (httpOptions, serverURL, host, baseUrl, headers) keep working. Bedrock's Converse adapter now applies defaultHeaders too.

Patch Changes

• Forward Bedrock Converse cache token counts to TokenUsage.

  cacheReadInputTokens and cacheWriteInputTokens from the Converse metadata.usage event now land on promptTokensDetails.cachedTokens and promptTokensDetails.cacheWriteTokens, in chatStream, structuredOutput, and structuredOutputStream. Bedrock's inputTokens counts only the uncached part of the input, so without these fields a cached request looked like a near-zero-input call. Both fields are omitted when Bedrock omits them.

Patch Changes

• forward usage from Converse structuredOutputStream()

  ConverseTextAdapter.structuredOutputStream() iterated the Converse event stream without a metadata branch, so the trailing usage event was ignored and RUN_FINISHED carried no token counts on the streaming structured-output path. The normal chat path (processConverseStream) and the non-stream structuredOutput() already handled it; this brings the third path in line.

Patch Changes

• Stop requiring Zod as a peer dependency when the adapters do not import it at runtime.

Minor Changes

• Add headless BYOK: defineByok in @tanstack/ai-client/byok, pass byok into chat and generation hooks, and read keys on the relay with getByokKey from @tanstack/ai/byok/server. Provider ids are open slugs (x-byok-<slug>). Each adapter exports a { id, label, env? } object (openaiByok, …); id is required. env is the env var name(s) for the relay — names only; the client never reads process.env. A wrong key surfaces as the provider's own 401 through the relay, so no client-side key check is needed. OpenRouter PKCE (@tanstack/ai-openrouter/pkce) saves the minted key under openrouterByok.id.

Patch Changes

• Timestamp native and fallback structured-output events when they are emitted so their lifecycle remains chronologically ordered.

Patch Changes

• populate StructuredOutputResult.usage from non-stream structuredOutput()

  Adapters that already returned tokens/cost on streaming structured paths were dropping response.usage on the non-stream structuredOutput() method. OpenRouter now forwards tokens and cost; openai-base, Mistral, and Bedrock Converse do the same for tokens so fallbackStructuredOutputStream and middleware can observe usage.

Minor Changes

• Add a multimodal embed() activity. A single primitive covers one input or a batch — input accepts a string, a text part, an image part, or a fused text+image item written as a nested Array<ContentPart> ([textPart, imagePart], the same shape chat messages use), one vector per item, with the accepted item types narrowed per model at compile time. Top-level dimensions requests Matryoshka output sizes where supported. Results carry embeddings: [{ vector, index }] plus usage when the provider reports it, and embed() participates in generation middleware, debug logging, OTel (gen_ai.operation.name: embeddings), and devtools events like every other activity.

  Provider adapters: openaiEmbedding (text-embedding-3-small/large), geminiEmbedding (gemini-embedding-001), mistralEmbedding (mistral-embed, codestral-embed), ollamaEmbedding (nomic-embed-text and any local model), bedrockEmbedding (Titan Text V2, Titan Multimodal G1 with fused text+image, Cohere Embed v3 on Bedrock), and @tanstack/ai-cohere's cohereEmbedding (embed-v4.0, multimodal text+image with required inputType).

Patch Changes

• publish internal dependency ranges as ^x.y.z instead of exact pins

  Internal dependencies on other TanStack AI packages used workspace:* in dependencies and peerDependencies. pnpm rewrites that to an exact version at publish time, so a released package asked for e.g. @tanstack/ai-utils@0.4.0 rather than ^0.4.0.

  Two consequences for consumers:

  • Duplicate copies. An exact pin cannot dedupe. Installing a newer @tanstack/ai alongside a package pinned to the previous patch produced two copies in the tree, which breaks instanceof checks and module-level state, and inflates bundles.

  • Unsatisfiable peers. An exactly pinned peerDependency conflicts the moment the internal package ships its next patch, forcing consumers into overrides or --legacy-peer-deps.

  These fields now use workspace:^, which publishes as ^x.y.z. Every package here is still 0.x, so ^0.43.1 resolves to 0.43.x only — patches dedupe cleanly and no breaking minor is ever pulled in.

  devDependencies deliberately keep workspace:*: they are never published, and * correctly means "always build against the local copy".