Gregor Martynus

feat(video): externalize polling control and webhook support for generateVideo (#12515) - Adds optional `doStart`/`doStatus` methods to the experimental `VideoModelV4` spec, enabling a two-phase async model where the SDK core orchestrates polling or webhook-based completion instead of each provider implementing its own polling loop. - Adds `poll` and `webhook` parameters to `experimental_generateVideo` for user-controlled polling intervals/timeouts and webhook-based completion. - Adds optional `handleWebhookOption` to `VideoModelV4` so a provider can signal native webhook support. The SDK only invokes the user's webhook factory when the model implements it; otherwise it falls back to polling. - Replaces `doGenerate` with `doStart`/`doStatus` in the first-party models implementing `VideoModelV4` (FAL, Alibaba, KlingAI, Replicate, xAI, Google, and Google Vertex). The gateway video model remains a `doGenerate` passthrough. - Makes `doGenerate` optional on `VideoModelV4`. Third-party providers implementing only `doGenerate` continue to work unchanged, and the SDK falls back to it when no async flow is selected. - Constrains operation handles to `JSONValue`, making the provider-owned task reference serializable and suitable for future persistence and gateway support. Towards https://github.com/vercel/ai/issues/12381. ## Architecture ``` User calls: generateVideo({ model, prompt, poll?, webhook? }) ↓ Core function: Chooses flow based on model capabilities and user options ↓ ┌───────────┴───────────────┐ │ │ [Legacy / fallback] [Start/Status flow] │ (poll or webhook provided, │ or doGenerate missing) │ │ model.doGenerate(options) model.doStart(options) ↓ ↓ Provider owns polling returns { operation } ↓ ┌───────────┴────────────┐ │ │ [native webhook] [polling] │ │ await notification SDK core loop │ │ model.doStatus(op) model.doStatus(op) └───────────┬────────────┘ ↓ return result ``` The SDK core owns the polling lifecycle. Providers only implement single-shot `doStart` (submit) and `doStatus` (check once). The polling interval and timeout are controlled by the user. ## Review decisions - **`poll` and `webhook` are intentionally composable.** When a model supports native webhooks, `poll.timeoutMs` limits the webhook wait. When it does not, the same polling configuration controls the automatic fallback. This behavior is documented and covered by tests. ([discussion](https://github.com/vercel/ai/pull/12515#discussion_r2821429102)) - **The first iteration uses fixed polling intervals and timeouts.** Exponential backoff and `onAttempt` were removed to keep the API small; aligning polling with shared retry/backoff primitives can be revisited separately. ([discussion](https://github.com/vercel/ai/pull/12515#discussion_r2821435402)) - **Operation handles are JSON-serializable.** `operation` is typed as `JSONValue` instead of `unknown`, while remaining opaque to core. ([discussion](https://github.com/vercel/ai/pull/12515#discussion_r2843221880)) - **Shared cross-modality operation types are deferred.** The current types remain video-specific until another modality implements the same lifecycle, avoiding a premature provider-spec abstraction. ([discussion](https://github.com/vercel/ai/pull/12515#discussion_r2843151286)) - **Replicate's server-side `wait` remains provider-specific.** It affects how long Replicate holds the submission request open, while top-level `poll` controls the SDK's provider-neutral status lifecycle. It can be added through Replicate provider options independently if needed. ([discussion](https://github.com/vercel/ai/pull/12515#discussion_r2843203139)) ## Verification - [x] Tests added and updated - [x] Documentation added and updated - [x] Patch changeset added - [x] TypeScript, lint/format, and code consistency checks pass locally ## Future work - Expose async operations as a first-class API: start an operation, persist its handle, and resume or query it later. ([discussion](https://github.com/vercel/ai/pull/12515#discussion_r2843215786)) - Generalize operation types after another model modality implements the same lifecycle. - Add AI Gateway transport for the JSON-serializable start/status operation flow. - Explore a multi-notification webhook receiver if providers need intermediate status events rather than a single completion notification. ## Related issue https://github.com/vercel/ai/issues/12381 --------- Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Co-authored-by: josh <144584931+dancer@users.noreply.github.com> Co-authored-by: vercel-ai-sdk[bot] <225926702+vercel-ai-sdk[bot]@users.noreply.github.com> Co-authored-by: mat lenhard <mclenhard@gmail.com> Co-authored-by: Rohan Taneja <47066511+R-Taneja@users.noreply.github.com> Co-authored-by: Felix Arntz <felix.arntz@vercel.com> Co-authored-by: Walter Korman <shaper@vercel.com> Co-authored-by: Nico Albanese <49612682+nicoalbanese@users.noreply.github.com> Co-authored-by: Cursor <cursoragent@cursor.com>

feat(provider/perplexity)!: migrate to Agent API (#18991) ## Background `@ai-sdk/perplexity` language generation still uses Sonar Chat Completions, which Perplexity supports only until September 27, 2026. This PR moves language generation to the Agent API as an intentional major-version change, exposing presets, direct models, native tools, typed output, and usage/cost data. ## Breaking changes - All language generation and streaming requests use `/v1/agent`; custom `baseURL` proxies must route that path. - Legacy Sonar model IDs are not aliases. Applications must select an Agent API preset or direct model ID. - Sonar provider options are not translated or deprecated at runtime. Applications must use Agent API options and native tools. - Sonar PDF and video inputs and image/video results have no Agent API equivalent. The migration note describes alternatives. - Raw responses and streams use typed Agent output and SSE events. Provider metadata, usage/cost data, and source identifiers can differ. The embeddings API is unchanged. Remaining on `@ai-sdk/perplexity` v4 does not preserve language generation after the Sonar shutdown. ## Implementation - Convert prompts, structured output, reasoning settings, and AI SDK function tools to Agent API requests, including tool-call continuations and image input. - Expose search/fetch results and citation annotations as sources, preserving search result IDs and emitting each URL once while streaming. - Parse native output by item type so finance and other native tool results do not fail web-search validation. Native traces remain available in raw response bodies and raw stream chunks. - Handle reasoning streams, incomplete terminal states, failed HTTP 200 responses, malformed responses, and terminal output that contains text missing from deltas. - Expose usage, cost, native-tool invocation counts, and source metadata. - Add examples, recorded JSON/SSE fixtures, regression tests, and a [v4 Sonar to v5 Agent API migration note](https://github.com/vercel/ai/blob/codex/perplexity-agent-api-18988/content/providers/01-ai-sdk-providers/70-perplexity.mdx#migrating-from-v4-sonar-to-v5-agent-api). The migration note gives manual model starting points and option moves; presets can change models, tools, cost, latency, and output. It also clarifies that `store: false` prevents later retrieval but does not disable persistence or continuation. ## Verification - Perplexity provider tests: **51 passed in Node.js and 51 passed in Edge**. - **8 live Agent API E2E tests passed**: grounded generation and streaming, a direct model, structured output, generation and streaming function-call continuations, inline image input, and invalid-model errors. - Captured real web-search JSON and SSE fixtures with the `fast` preset. - Perplexity and dependent package builds passed. - `pnpm type-check:full` passed, including examples. - `pnpm check` and `git diff --check` passed. Live finance validation is limited by the test account's zero data retention policy: the API rejects `finance_search` with HTTP 400 because it is a file-capable tool. Finance output parsing has regression coverage using the documented response shape, and generation/streaming examples are provided for an account that supports the tool. ## Scope Agent background submit/poll/reconnect/cancel and generated-file downloads are lifecycle operations outside `LanguageModelV4` and are not included. Search/fetch sources and client function calls map to AI SDK parts; other native tool traces remain in raw output. ## Checklist - [x] All commits are signed - [x] Tests and live fixtures have been added / updated - [x] Examples and documentation have been added / updated - [x] A major changeset and patch changesets for review fixes are included - [x] Breaking changes and migration steps are documented - [x] I have reviewed my own code Fixes #18988

docs: refresh model defaults across docs and examples (#21416) ## Background Generic docs and examples still selected older or retired models. Refresh their defaults using the live AI Gateway catalog and provider capability definitions, while retaining models required by the feature being demonstrated. ## Summary - Update language, embedding, reranking, image, speech, and video defaults across 166 content files, 919 example files, and 18 package READMEs. Current choices include GPT-6, Claude Sonnet 5 / Opus 5.5, Gemini 3.8 Flash / 3.1 Pro, and Grok 4.7. - Update two interactive docs preview components, including current labels and the mapping from Gateway's `spacexai` IDs to the `@ai-sdk/xai` provider. - Preserve model-specific guides, sampling and logprob examples, versioned tools, thinking budgets, transparent images, transcription timestamps, Azure deployment names, and compatibility coverage. Retain third-party/harness IDs where replacements could not be verified. - Keep routing choices distinct and synchronize model names with explanatory text. Published package implementations, dependencies, migration guides, fixtures, and snapshots are unchanged; no release changeset is needed. ## Validation - Changed-file formatting and lint pass; `git diff --check` passes. - `pnpm validate:docs` passes for 534 MDX files. - `pnpm --filter ai-sdk-docs validate:site` passes, including all nine tests, TypeScript, and production generation of 3,072 pages. - All 16 newly selected Gateway IDs match its live catalog. Static checks of 2,395 source files and documentation blocks find no collapsed routing branches or duplicate model choices; the preview parser correctly maps current Grok IDs. - `pnpm type-check:full` reports six existing Nuxt runtime-config typing errors. The same diagnostics were reproduced against the original Nuxt source. - Live inference calls were not run. ## Checklist - [x] All commits are signed (PRs with unsigned commits cannot be merged) - [ ] Tests have been added / updated (for bug fixes / features) - [x] Documentation has been added / updated (for bug fixes / features) - [ ] A _patch_ changeset for relevant packages has been added (for bug fixes / features - run `pnpm changeset` in the project root) - [x] I have reviewed this pull request (self-review)

fix(openai): expand Responses API parallel tool call wrappers (#19098) ## Background Azure OpenAI gpt-5.4 can intermittently return its internal parallel dispatch wrapper as a Responses API function call named parallel. Generic tool validation treats that wrapper as an unavailable user tool, so its valid nested calls are discarded. ## Changes - recognize the wrapper only when parallel is not a declared client tool - require the reported tool_uses shape and verify every nested recipient against declared function tools - expand valid nested calls into ordinary SDK tool calls for generate and stream paths - preserve existing behavior for declared parallel tools, malformed payloads, and unavailable nested tools - add recorded-response fixtures plus focused helper coverage ## Testing - pnpm --filter @ai-sdk/openai test - pnpm check - pnpm type-check:full ## End-to-end validation A live Azure deployment is unavailable, so validation uses non-streaming and streaming fixtures derived from the trusted production payload reported in the issue. Fixes #19067

feat: add experimental evaluation models and shared adapter to openai, google, anthropic (#20858) ## Summary Add `openai.evaluationModel(modelId)` for experimental Choice, Score, and Boolean evaluation through the Responses API. Add the shared `Experimental_EvaluationLanguageModel` adapter at `@ai-sdk/provider-utils/experimental-evaluation` for OpenAI, Anthropic, and Google. Boolean answers contain a model-generated estimate of P(true), validated to be finite and within `[0, 1]`. The returned `probability` stays numeric: `0` means false, `1` means true, and application code chooses its decision threshold: ```ts const requestsRefund = result.answers.requestsRefund.probability >= 0.5; ``` These are prompted estimates without a calibration guarantee. Choice and Score answers omit probability distributions. All questions share one generation. The adapter preserves exact Choice labels, validates fractional Score bounds, and supports Boolean questions with or without true/false criteria. Missing or extra answers, invalid probabilities, refusals, and incomplete generation fail the whole call. Provider configuration, options, cancellation, usage, warnings, response data, and provider metadata are preserved; core owns retries. The portable schema uses required enum/number fields and `additionalProperties: false`. Bounds are described in the prompt and checked locally because Anthropic rejects numeric schema bounds. A dedicated entry point keeps Workflow serialization hooks at module scope while excluding evaluation code from ordinary provider-utils imports. Includes core/provider documentation, a mixed-question example demonstrating thresholding, and patch changesets. ## Validation - Regression tests cover mixed question types, probabilities `0`, `0.5`, `1`, and fractional values, structured/absent Boolean criteria, invalid probabilities, complete-answer validation, and metadata forwarding. - Live `experimental_evaluate` example with `gpt-5.6-luna` returned Choice, Score, Boolean probability, and usage. This verifies API compatibility, not calibration. - Full provider-utils, OpenAI, Anthropic, and Google package suites passed in Node and Edge on the updated stack. - Core evaluation runtime and type tests passed in Node and Edge. - Full workspace `pnpm type-check:full`, formatting/lint, provider consistency, and all bundle-size checks passed. Part of #20846. Merge order: this PR → #20859 (Anthropic) → #20863 (Google).

feat(provider/anthropic): add Claude Opus 5.5 support (#21286) ## Background Claude Opus 5.5 (`claude-opus-5-5`) rejects several request shapes that `@ai-sdk/anthropic` previously sent unconditionally: `thinking: { type: 'disabled' }` and budget-based thinking, forced `tool_choice` (`required` or a named tool), and the older `computer_*` tool types. Without these changes, common SDK usage 400s against the new model. ## Summary - Add the `claude-opus-5-5` model ID to `@ai-sdk/anthropic` and `anthropic/claude-opus-5.5` to `@ai-sdk/gateway`. - Models that always use adaptive thinking (`claude-opus-5-5`, `claude-fable-5`, `claude-fable-5-1`) no longer receive disabled or budget-based thinking. The provider drops the unsupported setting, maps `reasoning: 'none'` to `effort: 'low'`, and emits a warning. - Models that reject forced tool use (`claude-opus-5-5`, `claude-fable-5-1`) fall back to `auto` tool choice for `required` and named tool choices, and to native structured outputs when `structuredOutputMode: 'jsonTool'` is requested, each with a warning. - Add the `computerToolset_20260801` computer use tool (`computer_toolset_20260801`), required for computer use on `claude-opus-5-5`. Member calls are mapped to `action` and `toolset_name` round-trips through tool results. - Use the documented `mid-conversation-output-config-2026-07-01` beta header for per-message effort. - Docs and examples for the new model and tool. ## End-to-End Verification Ran the new examples under `examples/ai-functions/src` against the Anthropic API with `claude-opus-5-5`: - `generate-text/anthropic/claude-opus-5-5.ts` (default adaptive thinking) - `generate-text/anthropic/claude-opus-5-5-low-effort.ts` (`reasoning: 'none'` mapped to low effort with warning) - `stream-text/anthropic/claude-opus-5-5-thinking-updates.ts` (per-message effort beta) - `stream-text/anthropic/computer-toolset.ts` (`computer_toolset_20260801` round-trip) Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>

feat(ai): add experimental evaluation model registry support (#20875) ## Background Evaluation models could only be passed as instances, so applications could not use custom aliases, registered providers, or their configured default provider to resolve evaluation model IDs. This implements Phase 5 of #20846. ## Summary - Add `customProvider({ evaluationModels })` and `registry.evaluationModel('provider:model')`, preserving alias inference, fallback receivers, and experimental methods on legacy providers. - Allow string IDs in `experimental_evaluate` only when `AI_SDK_DEFAULT_PROVIDER` explicitly supports evaluation. Missing capabilities use `NoSuchModelError` with `modelType: 'evaluationModel'`; no implicit Gateway requests or model substitution. - Keep `ProviderV4`, `Provider`, and `ProviderRegistryProvider` unchanged. Export `Experimental_EvaluationProviderRegistry` for applications that name the extended registry type. - Document resolution, optional distributions, native TypeSafe confidence, caller-owned thresholds, and unsupported functionality. Add runnable registry/routing and default-provider examples, plus patch changesets for `ai` and `@ai-sdk/provider`. The existing merged Boolean and default-reasoning behavior is preserved. Generative-provider Boolean answers remain prompted P(true) estimates, distinct from native TypeSafe probabilities. ## End-to-End Verification Ran the public TypeSafe registry/routing example and OpenAI custom-default-provider example with live credentials; both resolved the alias and routed the billing request successfully. Also ran the basic TypeSafe, OpenAI, Anthropic, and Google examples, validating complete typed answers and token usage. These are integration checks, not assertions of identical model judgments. ## Validation - Affected registry, model-resolution, and evaluation tests pass in Node and Edge, including type tests. - Root `pnpm type-check:full`, `pnpm check`, and `pnpm konsistent` pass. - Affected package/dependency builds pass. - All bundle checks pass: Node 518.29 KiB, browser 506.65 KiB; named `generateText` and `tool` checks also pass. ## Checklist - [x] All commits are signed (PRs with unsigned commits cannot be merged) - [x] Tests have been added / updated (for bug fixes / features) - [x] Documentation has been added / updated (for bug fixes / features) - [x] A _patch_ changeset for relevant packages has been added (for bug fixes / features - run `pnpm changeset` in the project root) - [x] I have reviewed this pull request (self-review) ## Related Issues Implements Phase 5 of #20846.

fix(ai,mcp): preserve prototype-named tools and provider metadata (#21648) ## Background Tools, provider IDs, and provider metadata named `__proto__` can change lookup object prototypes instead of becoming own properties. Inherited names such as `constructor` can also resolve as unregistered providers or crash image metadata aggregation. ## Summary Use null-prototype maps for MCP tools and the provider registry. Merge embedding, image, and video metadata with own-property reads and writes, including per-image metadata, while retaining plain objects in returned metadata. Add regressions for prototype-named keys and patch changesets for `ai` and `@ai-sdk/mcp`. Validation: the added regressions exposed failures in all five reported areas before the fix. The affected AI SDK suites pass 234 tests in each of Node and Edge; the MCP client suite passes 89 in each. `pnpm check` and `pnpm type-check:full` pass. ## Contributor Credit Reported by @trmxvibs in #18187. Related proposed fix: #20005. ## End-to-End Verification Ran a standalone local reproduction through embedding, image, and video generation, provider lookup, and MCP tool discovery/execution using synthetic models and an in-memory MCP transport. `__proto__` survives enumeration and execution, returned metadata retains its ordinary prototype, and provider members do not become registered providers. No live provider credentials are required. ## Checklist - [x] All commits are signed (PRs with unsigned commits cannot be merged) - [x] Tests have been added / updated (for bug fixes / features) - [ ] Documentation has been added / updated (for bug fixes / features) - [x] A _patch_ changeset for relevant packages has been added (for bug fixes / features - run `pnpm changeset` in the project root) - [x] I have reviewed this pull request (self-review) ## Related Issues Addresses finding 1 of #18187. The other findings are tracked separately.

feat(ai): add experimental evaluation API and model spec (#20848) ## Background Applications need typed evaluations of shared state without forcing every model through text generation. This implements Phase 2 of #20846 and provides the foundation for the TypeSafe provider in #20851 (`@ai-sdk/typesafe-ai`, using `TYPESAFE_AI_API_KEY`). Merge this PR first. ## Summary - Add `experimental_evaluate({ model, state, questions })` for Choice, Score, and Boolean questions, with inferred question IDs and Choice options. - Add an isolated `Experimental_EvaluationModelV4` spec with advertised question capabilities. Stable `ProviderV4` is unchanged. - Validate structured JSON inputs, complete answer maps, probability distributions, weighted scores, and required Boolean P(true). Unsupported types fail the whole call before provider I/O with `Experimental_EvaluationUnsupportedQuestionTypeError`. - Reuse retries, cancellation, warnings, usage, and provider metadata; add the experimental mock model, docs, and a runnable example. Model instances are supported here. Registry/string resolution and adapters for existing providers remain separate phases. Probability distributions are optional for Choice and Score, never synthesized. Distribution sums and weighted means use an absolute tolerance of 1e-6 plus the accumulated half-unit error for provider-declared decimal precision. Native verification found a TypeSafe score of 0.97 with displayed probabilities whose mean is 0.98; `result.rounding` lets core accept that rounding without rewriting either value. ## End-to-End Verification Built the published provider and core entry points and ran `examples/ai-functions/src/evaluate/mock/basic.ts` through the public `ai` and `ai/test` exports. Native TypeSafe verification belongs to the next PR. Additional validation: evaluation and error tests in Node and Edge, type-inference tests, `pnpm type-check:full`, and `pnpm check`. ## Checklist - [x] All commits are signed (PRs with unsigned commits cannot be merged) - [x] Tests have been added / updated (for bug fixes / features) - [x] Documentation has been added / updated (for bug fixes / features) - [x] A _patch_ changeset for relevant packages has been added (for bug fixes / features - run `pnpm changeset` in the project root) - [x] I have reviewed this pull request (self-review) ## Related Issues Implements Phase 2 of #20846; does not close the issue.

fix(gateway): preserve structured AI Gateway failure details in nested API call errors (#18760) ## Summary - serialize structured AI Gateway failed-response payloads before constructing nested API call errors - cover all Gateway request paths on main, including realtime client-secret and async video handlers - add a regression assertion that the nested APICallError preserves Gateway failure details ## Testing - pnpm --filter @ai-sdk/gateway test - pnpm --filter @ai-sdk/gateway type-check - pnpm check - pnpm type-check:full ## Related Issues Related to #15872. Forward-port of #18737.