refactor(core)!: align public core types with the AI SDK V4 shapes

[cunninghamcard-bit]

What

Core public types in aimux-core take the AI SDK V4 provider and ai shapes: tool calls and results, output content, provider options and metadata, the provider prompt, and provider results. Base rfc-0036/integration; first of four (A to D), precedes B. Replaces #215, #216, #217 and #218, and takes over the range previously shown by #219.

Layers

Branch	PR	Content	Diff against its updated base
rfc-0036/tool-types	#215	One tool-call and one tool-result type per protocol layer	136 files, 1107 insertions(+), 25133 deletions(-)
rfc-0036/output-content-types	#216	One type each for source, generated file, reasoning output, response metadata	127 files, 3896 insertions(+), 22622 deletions(-)
rfc-0036/provider-options-types	#217	Provider options and metadata as namespace to JSON object	154 files, 1583 insertions(+), 7718 deletions(-)
rfc-0036/provider-prompt-types	#218	Provider prompt by role, one file part	93 files, 4177 insertions(+), 12601 deletions(-)
rfc-0036/provider-result-types	#219	Provider results carry request and response information	61 files, 986 insertions(+), 627 deletions(-)

Before and after

Area	Before	After	Upstream reference
Provider tool calls	Variants repeated fields; stream input mixed raw text and parsed JSON	RawToolCall with input: String in GenerateContent and StreamPart; compatibility decoder and raw_tool_input heuristic deleted	LanguageModelV4ToolCall
Call-layer tool calls	Separate raw-call definition and heuristics	ToolCall holds parsed Value (original string if parsing fails), invalid, error	TypedToolCall
Provider-executed results	Unused struct; repeated enum payloads	Shared ToolResult: required tool_name, optional dynamic, provider_metadata	LanguageModelV4ToolResult
Tool choice	Always supplied	CallOptions.tool_choice optional; generate_text, stream_text supply auto for a nonempty tool list	prepare-tool-choice.ts
Tool examples, args	Arbitrary JSON; nonobject args	FunctionTool.input_examples is { input: object }; ProviderTool.args is an object	LanguageModelV4FunctionTool, LanguageModelV4ProviderTool
Thought signatures	Signature fields; with_signature path	In provider metadata (output), provider options (input)	Google and Vertex modules
Sources	Inline fields; reduced SourcePart	Source URL/document union	LanguageModelV4Source
Generated files	Repeated fields	GeneratedFile with GeneratedFileData (data or URL; URL keeps original_url)	LanguageModelV4File, SharedV4FileDataUrl
Reasoning, content, usage	Text-only reasoning; no custom content, reasoning files, approval requests	ReasoningOutput keeps metadata; reasoning is text or ReasoningFileOutput; new content variants in provider content and streams; InputTokenUsage and OutputTokenUsage replace one usage type, raw usage is a JSON object	LanguageModelV4ReasoningFile, LanguageModelV4CustomContent, LanguageModelV4ToolApprovalRequest, LanguageModelV4Usage
Output conversions	Citations and thought output missing or misclassified	OpenAI Responses maps file, container-file, file-path citations to document sources; Google and Vertex map retrieved documents; Vertex emits inline files and thought text as file/reasoning output	Upstream provider modules
Provider options, metadata	Option<Value>; arbitrary JSON maps	SharedProviderOptions, SharedProviderMetadata = HashMap<String, JsonObject>; provider_namespace rejects non-objects	SharedV4ProviderOptions, SharedV4ProviderMetadata
Option fields	Reviewed paths passed invalid values or forwarded unknown keys	Schema-directed parsing in OpenAI chat and Responses, Groq, DeepSeek, Anthropic, xAI Responses, Cohere, Google, Mistral: invalid known fields error, unknown fields discarded; Cohere, Google, Mistral converters return errors	Upstream option schema modules
Cohere, Bedrock options	Invalid thinking defaulted to enabled; fractional budget dropped; only bedrock read	Invalid objects error; numeric tokenBudget kept; amazonBedrock first	cohereLanguageModelChatOptions, amazon-bedrock-chat-language-model.ts
Provider prompt	One struct with call-layer ContentPart for all roles	System (string), user, assistant, tool messages with own part unions and hyphenated tags; assistant adds reasoning-file, custom; tool adds tool-approval-response; one FilePart with tagged FileData	LanguageModelV4Message, LanguageModelV4FilePart
Tool result part	Free JSON result, error flags	Required tool_name; output is text, json, execution-denied, error-text, error-json or content (text, file, custom)	LanguageModelV4ToolResultOutput
Vendor prompt conversion	Inputs dropped or coerced	OpenAI non-object tool input becomes {}; DeepSeek resolves its references, Groq and Compatible reject them; Responses references become file IDs; Google tool content URLs become fileData; Bedrock emits S3 image locations; Cohere, Mistral, xAI, Vertex reject unsupported inputs	convert-to-* modules
Provider result	GenerateResultWire flattened request body, response headers	GenerateResult serializes directly with optional request: RequestInfo, response: ResponseInfo; StreamResponseInfo has optional headers	LanguageModelV4GenerateResult, LanguageModelV4StreamResult
Call result	No top-level request; flat raw path	GenerateTextResult.request, response (defaults for missing metadata); raw is GenerateResult without them; aggregation keeps request and last step's response	generate-text.ts, stream-text.ts
Stream chunks	TextStreamPart was the provider union	Distinct TextStreamPart; metadata in FinishStep.response; no output gives NoOutputGenerated	stream-text.ts, NoOutputGeneratedError
OpenAI Responses, Azure streaming	Returned request body had stream: true	Only the HTTP body has it	openai-responses-language-model.ts

TypeScript-only constraints (JSONSchema7, dotted IDs, NonNullable, URL, Date, numeric types, inner undefined in JSONObject) are not enforced upstream at runtime; Rust keeps Value, String, u32 and adds no checks.

Tests

• Deleted contract-tests/ (self-generated JSON, runner) and the 16 tests reading it; they recorded Rust's former output. CI, scripts and docs stop using them.
• Deleted hand-written tests that pin removed shapes, including invented-data tests in openai_output.rs and moa.rs.
• Restored and adapted: tool-choice cases from the upstream OpenAI, Groq, Mistral, Bedrock suites; tracker metadata, Google files and Bedrock message-conversion tests; Groq tool-argument and reasoning cases, Google model-path cases, Mistral strict-tool case.
• Migrated retained upstream ports and cassette replays; cassette_full_test.rs matches TextStreamPart; stream tests expect FinishStep then Finish; round-trip callers use generate_text_result_to_chat_completion. Hand-written end-to-end files remain.
• Older provider suites (some annotated as upstream ports) are deleted; no full coverage is claimed. DeepSeek request and Groq request-body cases return on B; bedrock_remaining_test.rs, anthropic_remaining_test.rs return in C. Cassettes and fixtures/ unchanged.

Not in this pull request

• Provider ToolChoice serializes auto, none, required as bare strings; upstream uses tagged objects. D does not name ToolChoice.
• Serde naming, optional-field encoding, required-nullable Node fields: covered by D. The call-layer ModelMessage tool-result shape: covered by D. D does not mention the TextStreamPart tool-result payload (still the provider ToolResult), a tool-error event for invalid calls, or the stream's Result error channel.
• A repaired call failing validation is still wrapped as a repair error; invalid-call fallback uses plain JSON parsing, not the secure parser. D rethrows a repair function's parse failure as is.
• Anthropic document citation sources, Bedrock response body and user-file media detection, OpenAI Responses approval-ID mapping, custom-tool async replay: covered by C.
• No namespace-constant migration or boundary script; no claim of exhaustive schema or per-vendor test parity. Other model families' result contracts need separate comparison.

Relation to the maintainer's design

Reference order: the pinned AI SDK source first; where it has no counterpart (C ABI, bindings, recording, code generation), the maintainer's RFCs 0039 (ops and bindings, #209), 0040 (provider construction and auth, #210), 0041 (replay governance, #211) and 0042 (V4 type boundaries, #212), which are Drafts that refine the #200 design doc docs/aisdk-architecture-alignment.md; that design doc only where those RFCs defer to it. Where an RFC restates upstream behaviour differently from the pinned source, upstream wins and the RFC gets an amendment request. The stack targets rfc-0036/integration; RFC-0039 §11 and RFC-0040 §7.2 require the whole closure to switch to master at once, so items marked "before master" must land on integration first. "Branch E" is the follow-up branch stacked on D, in progress.

• Crate split (before master). RFC-0040 §2 and RFC-0042 §1 place the V4 traits and types in aimux-provider, user ModelMessage and transport in aimux-provider-utils, factories and protocol code in aimux-providers, operations and registry in aimux, recording and replay in aimux-devtools; the docs: full-chain AI SDK alignment design and impact map #200 design doc §2.1 adds that no compatibility re-exports remain. This stack keeps all code in aimux-core (56 files, about 22,900 lines in its top two directory levels); behaviour is unaffected, and those dependency directions are not yet enforced by the compiler.
• Provider options and metadata (agrees). RFC-0042 §6.2: namespace → JSON object, unknown keys kept. This PR's SharedProviderOptions and SharedProviderMetadata have that shape.
• Other items are in the PRs they concern: the recording schema and descriptors in B; tool-call repair, the error JSON, code generation, the C ABI and Kotlin in D, with their implementation in branch E.

Verification

Gate on the head c16749d6: cargo fmt --check, cargo clippy --workspace --all-targets -D warnings, cargo doc with -D warnings, tests of core, provider-utils, providers, ffi, web, replay and cli: 2,364 passed, 0 failed, 8 ignored; Node and Python bindings cargo check; gen_ts_types.py --check; gen_providers_doc.py --check. Cassettes and fixtures/aisdk unchanged; contract-tests/fixtures/tool-call-repair.json and wire-format.json (fixtures generated by aimux itself) are deleted. Diff against the base: 330 files changed, 10710 insertions(+), 67662 deletions(-). After the restack onto the current master, only this head was tested; the intermediate layers were checked with fmt and clippy only.

Restacked head 5342962b. Restack (2026-10-09): merged master (#213, SSE) and the rewritten #204 tracker down the stack by merge, no history rewrite. This layer re-applies its V4 output change (StreamPart::ToolCall(RawToolCall { input: String, .. }), provider_namespace) to the rewritten tracker and updates the MIGRATION-NS.md note on tool-call metadata. Checked: cargo fmt --check, cargo clippy --workspace --all-targets -D warnings, tests of provider-utils and providers (103 test binaries, 0 failed). cargo doc, binding checks and the generator --check scripts were not rerun.

Not verified

No GitHub check runs were attached at the last refresh. Go, Java, Kotlin, Swift and Flutter were not compiled locally in that refresh; Node npm test and Python pytest were not run. Live vendor calls and unported upstream cases are outside validation.

🤖 Generated with Claude Code

[cunninghamcard-bit]

审批类型与 core 处理需要按最新职责边界收窄（核对 head c16749d6）。

本轮确认的范围调整：aimux 不承担审批运行时，也不定义统一的审批公共类型/语义；审批相关的定义、解释和处理由上层负责。这是对 #200 §0.4 原先“保留审批 variant”范围的收窄，不是否认 AI SDK 中存在这些类型。

本 PR 已实际引入：

• RawToolApprovalRequest / ToolApprovalRequestOutput，以及内容和流中的 ToolApprovalRequest variant。
• ToolApprovalResponsePart 与 ToolPart::ToolApprovalResponse。
• core 按 toolCallId 查找工具调用、构造审批输出；找不到时生成 ToolCallNotFoundForApproval，response_messages 也会重建审批消息。这已经包含审批专用处理，并非只保留未知数据。

请移除这套统一审批公共类型、专用错误及 core 关联/重建逻辑，连同相应导出和类型参数一起调整。调整时遵守已有的数据返回契约，不破坏已承诺的 raw/metadata 等通用行为。本评论不要求为审批新增原始输入透传、Raw 事件、回放或审批往返能力，也不将这些新能力作为删除审批专用类型的前置条件。

此范围调整需与 #220 的 provider 转换、#225 的 wire/绑定及设计文档同步。