[v4/p2-tool-calls] refactor!: tool calls follow the AI SDK

CHANGELOG.md

@@ -9,6 +9,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Breaking
 
+- Tool-call and tool-result types are unified, one per protocol layer
+  (`aimux-core`). A provider emits `tool::RawToolCall` (`input` is the raw
+  argument text) in `GenerateContent::ToolCall(..)` and
+  `StreamPart::ToolCall(..)`, and `tool::ToolResult` in the `ToolResult`
+  variants; these variants are newtype variants now. `StreamPart` is generic
+  over the tool-call type: a provider's `do_stream` yields `StreamPart`
+  (= `StreamPart<RawToolCall>`), `stream_text` and everything after it yield
+  `TextStreamPart` (= `StreamPart<ToolCall>`, parsed input with `invalid` /
+  `error`). `RawToolCall` moved from `parse_tool_call` to `tool`. Wire format:
+  enum variants keep their JSON shape; a provider-layer `StreamPart::ToolCall`
+  has a string `input` and no `invalid` / `error`; a
+  `GenerateContent::ToolCall` with a non-string `input` no longer
+  deserializes; the standalone `tool::ToolResult` gains a required
+  `tool_name` and optional `dynamic` / `provider_metadata`.
+
 - Removed the generated `ProviderName` type in every binding (Rust enum, TS
   const object, Go/Java/Kotlin consts, Swift enum, Dart consts, Python
   `Literal`) and `scripts/gen_provider_names.py`. Provider names are plain
@@ -41,6 +56,43 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Removed `NdjsonStream` / `NdjsonError`: nothing in the workspace used them
   and the AI SDK has no counterpart. `tokio` is now a dev-dependency only and
   the unused direct `serde` dependency is dropped.
+- `StreamingToolCallTracker`, `ToolCallStreamPart` and `TrackerError` are no
+  longer exported from `aimux-stream`; nothing in the workspace used them and
+  the AI SDK keeps the tracker in `@ai-sdk/provider-utils`, next to the
+  provider code that drives it. See `aimux-provider-utils` below.
+
+**Rust (aimux-provider-utils)**
+
+- Gains `StreamingToolCallTracker` (plus `StreamingToolCallDelta`,
+  `TypeValidation`, `TrackerError`, `StreamingToolCallArgumentState` and
+  `starts_with_structured_value`), a port of the current
+  `@ai-sdk/provider-utils` tracker. The previous `aimux-stream` version was
+  a port of an older, index-only tracker. Deltas are correlated by wire
+  `id`, `index` and function name (ambiguous deltas are dropped), ids are
+  de-duplicated with `-N` suffixes, blank function names are ignored, and
+  `finish` orders calls by index only when every call has one. It emits
+  `aimux_core::StreamPart` tool-input parts directly (`ToolInputStart` /
+  `ToolInputDelta` / `ToolInputEnd` / `ToolCall`); there is no separate
+  `ToolCallStreamPart` event type. `StreamingToolCallDelta` borrows from the
+  provider's wire type and flattens upstream's `function` object;
+  `process` and `finish` append to a caller-owned `Vec<StreamPart>`, and
+  `finish` consumes the tracker. The upstream `extractMetadata` /
+  `buildToolCallProviderMetadata` hooks are replaced by
+  `StreamingToolCallDelta::provider_metadata`, read from the delta that
+  starts a call. `TrackerError` converts into
+  `AiMuxError::InvalidResponseData`.
+
+**Rust (aimux-providers)**
+
+- The OpenAI chat-completions stream (`openai/model.rs`, which serves every
+  registry-backed provider) correlates `tool_calls` deltas with the tracker
+  instead of by `index` alone: deltas are matched by wire id, index and
+  function name; a continuation without an id follows its call; indices
+  reused across parallel calls stay distinct; ambiguous deltas are dropped;
+  a call whose delta carries no id gets a generated `tool-call` /
+  `tool-call-N` id instead of an empty string; a new call without a function
+  name ends the stream with `InvalidResponseData` (previously it started a
+  call with an empty name). `DeltaToolCall.index` is now `Option<usize>`.
 
 ## [0.5.0] - 2026-09-27
 

CONTRIBUTING.md

@@ -9,8 +9,8 @@ to set up a development environment, run the tests, and submit changes.
 aimux/
 ├── aimux-core/            # Core abstractions: LanguageModel / Provider / Message / StreamPart
 ├── aimux-providers/       # provider implementations + cassettes (counts: docs/api/providers.md)
-├── aimux-stream/          # SSE parsing, streamed tool-call tracking
-├── aimux-provider-utils/  # HTTP utilities: retry, backoff, error parsing, API-key loading
+├── aimux-stream/          # SSE parsing
+├── aimux-provider-utils/  # HTTP utilities: retry, backoff, error parsing, API-key loading, streamed tool-call tracking
 ├── aimux-ffi/             # C ABI (opaque handle + JSON + push callback) for non-native bindings
 ├── bindings/              # Node, Python, Swift, Kotlin, Flutter, Go, C — share one Rust core
 ├── rfc/                   # Design docs (RFCs)

README.md

@@ -98,8 +98,8 @@ middleware, and telemetry per request).
 aimux/
 ├── aimux-core            # Core abstractions: LanguageModel / Provider / Message / StreamPart
 ├── aimux-providers       # Provider implementations — registry-backed + typed (docs/api/providers.md)
-├── aimux-stream          # SSE parsing, streamed tool-call tracking
-├── aimux-provider-utils  # One-exchange HTTP helpers, response handlers, API-key loading
+├── aimux-stream          # SSE parsing
+├── aimux-provider-utils  # One-exchange HTTP helpers, response handlers, API-key loading, streamed tool-call tracking
 ├── aimux-ffi             # C ABI (opaque handles + JSON results + owned aimux_error_t *) for non-native bindings
 └── tools/                # aimux-cli (cache probe) · aimux-replay · aimux-web (console)
 ```
@@ -122,8 +122,8 @@ cargo add aimux-core aimux-providers
 |-------|-------------|-----------|
 | `aimux-core` | Core abstractions: `LanguageModel` / `Provider` / `Message` / `StreamPart` | [crates.io](https://crates.io/crates/aimux-core) |
 | `aimux-providers` | Provider implementations — [registry-backed + typed](docs/api/providers.md) | [crates.io](https://crates.io/crates/aimux-providers) |
-| `aimux-stream` | SSE parsing, streamed tool-call tracking | [crates.io](https://crates.io/crates/aimux-stream) |
-| `aimux-provider-utils` | One-exchange HTTP helpers and typed response handlers | [crates.io](https://crates.io/crates/aimux-provider-utils) |
+| `aimux-stream` | SSE parsing | [crates.io](https://crates.io/crates/aimux-stream) |
+| `aimux-provider-utils` | One-exchange HTTP helpers, typed response handlers, streamed tool-call tracking | [crates.io](https://crates.io/crates/aimux-provider-utils) |
 | `aimux-ffi` | C ABI for non-native bindings | [crates.io](https://crates.io/crates/aimux-ffi) |
 
 **Node.js**:

aimux-core/src/content.rs

@@ -104,11 +104,6 @@ pub enum ContentPart {
         /// need it to replay server tool calls on a later turn.
         #[serde(default, skip_serializing_if = "Option::is_none")]
         provider_executed: Option<bool>,
-        /// Provider-assigned thought signature (e.g. Google Gemini
-        /// `thoughtSignature`). Must be echoed back verbatim on the follow-up
-        /// turn when the tool result is sent.
-        #[serde(default, skip_serializing_if = "Option::is_none")]
-        thought_signature: Option<String>,
         /// Provider-specific options for this part (e.g.
         /// `anthropic.cacheControl`).
         #[serde(default, skip_serializing_if = "Option::is_none")]
@@ -167,7 +162,6 @@ impl ContentPart {
             tool_name: tool_name.into(),
             input,
             provider_executed: None,
-            thought_signature: None,
             provider_options: None,
         }
     }

aimux-core/src/generate.rs

@@ -21,24 +21,24 @@ use crate::language_model::LanguageModel;
 use crate::language_model_message::convert_to_language_model_prompt;
 use crate::message::{ModelMessage, ModelPrompt};
 use crate::options::{CallOptions, ResponseFormat, ToolChoice};
-use crate::parse_tool_call::{RawToolCall, ToolCallRepair, parse_tool_call};
+use crate::parse_tool_call::{ToolCallRepair, parse_tool_call};
 use crate::result::{
     FilePart, GenerateContent, GenerateResult, ReasoningPart, SourcePart, StreamResult,
     StreamTextResultAggregated,
 };
-use crate::stream_part::StreamPart;
+use crate::stream_part::{StreamPart, TextStreamPart};
 use crate::tool::Tool;
 use crate::types::{FinishReason, ReasoningEffort, Usage, Warning};
 use crate::{AbortSignal, retry, timeout};
 
 /// Matches the AI SDK's `isOutputChunk`: only chunks containing model output
 /// start or reset the first/chunk output timers.
-fn is_output_chunk(part: &StreamPart) -> bool {
+fn is_output_chunk<C>(part: &StreamPart<C>) -> bool {
     match part {
         StreamPart::TextDelta { delta, .. }
         | StreamPart::ReasoningDelta { delta, .. }
         | StreamPart::ToolInputDelta { delta, .. } => !delta.is_empty(),
-        StreamPart::ToolCall { .. } | StreamPart::File { .. } => true,
+        StreamPart::ToolCall(_) | StreamPart::File { .. } => true,
         _ => false,
     }
 }
@@ -107,6 +107,12 @@ impl GenerateTextOptions {
         self,
         prompt: crate::language_model_message::LanguageModelPrompt,
     ) -> CallOptions {
+        let tool_choice = self.tool_choice.or_else(|| {
+            self.tools
+                .as_ref()
+                .filter(|tools| !tools.is_empty())
+                .map(|_| ToolChoice::Auto)
+        });
         CallOptions {
             prompt,
             max_output_tokens: self.max_output_tokens,
@@ -119,7 +125,7 @@ impl GenerateTextOptions {
             response_format: self.response_format,
             seed: self.seed,
             tools: self.tools,
-            tool_choice: self.tool_choice.unwrap_or_default(),
+            tool_choice,
             headers: self.headers,
             provider_options: self.provider_options,
             reasoning: self.reasoning,
@@ -221,8 +227,8 @@ pub struct GenerateObjectResult {
 
 /// Result of `stream_text` (user-facing).
 pub struct StreamTextResult {
-    /// The stream of `StreamPart` items.
-    pub stream: Pin<Box<dyn Stream<Item = Result<StreamPart, AiMuxError>> + Send>>,
+    /// The stream of `TextStreamPart` items.
+    pub stream: Pin<Box<dyn Stream<Item = Result<TextStreamPart, AiMuxError>> + Send>>,
     /// The request body that was sent (for debugging / cache probing, RFC-0015).
     pub request_body: Option<serde_json::Value>,
     /// Response headers.
@@ -373,49 +379,11 @@ impl StreamTextResult {
                 StreamPart::ReasoningEnd {
                     provider_metadata, ..
                 } => rm.reasoning_end(provider_metadata),
-                StreamPart::ToolCall {
-                    tool_call_id,
-                    tool_name,
-                    input,
-                    provider_executed,
-                    dynamic,
-                    thought_signature,
-                    provider_metadata,
-                    invalid,
-                    error,
-                    ..
-                } => {
-                    let call = crate::tool::ToolCall {
-                        tool_call_id,
-                        tool_name,
-                        input,
-                        provider_executed,
-                        dynamic,
-                        thought_signature,
-                        provider_metadata,
-                        invalid,
-                        error,
-                    };
+                StreamPart::ToolCall(call) => {
                     rm.tool_call(&call);
                     tool_calls.push(call);
                 }
-                StreamPart::ToolResult {
-                    tool_call_id,
-                    tool_name,
-                    result,
-                    is_error,
-                    preliminary,
-                    dynamic,
-                    provider_metadata,
-                } => rm.tool_result(
-                    tool_call_id,
-                    tool_name,
-                    result,
-                    is_error,
-                    preliminary,
-                    dynamic,
-                    provider_metadata,
-                ),
+                StreamPart::ToolResult(result) => rm.tool_result(result),
                 StreamPart::Source {
                     id,
                     source_type,
@@ -656,26 +624,9 @@ pub async fn generate_text(
                 text.push_str(t);
                 rm.text(t, provider_metadata.as_ref());
             }
-            GenerateContent::ToolCall {
-                tool_call_id,
-                tool_name,
-                input,
-                provider_executed,
-                dynamic,
-                thought_signature,
-                provider_metadata,
-                ..
-            } => {
+            GenerateContent::ToolCall(call) => {
                 let parsed = parse_tool_call(
-                    RawToolCall {
-                        tool_call_id: tool_call_id.clone(),
-                        tool_name: tool_name.clone(),
-                        input: input.clone(),
-                        provider_executed: *provider_executed,
-                        dynamic: *dynamic,
-                        thought_signature: thought_signature.clone(),
-                        provider_metadata: provider_metadata.clone(),
-                    },
+                    call.clone(),
                     tools.as_deref(),
                     repair_tool_call.as_ref(),
                     &messages,
@@ -715,25 +666,7 @@ pub async fn generate_text(
             }
             // Provider-executed results stay in the assistant message so the
             // provider can replay its own server-tool transcript next turn.
-            GenerateContent::ToolResult {
-                tool_call_id,
-                tool_name,
-                result,
-                is_error,
-                preliminary,
-                dynamic,
-                provider_metadata,
-            } => {
-                rm.tool_result(
-                    tool_call_id.clone(),
-                    tool_name.clone(),
-                    result.clone(),
-                    *is_error,
-                    *preliminary,
-                    *dynamic,
-                    provider_metadata.clone(),
-                );
-            }
+            GenerateContent::ToolResult(result) => rm.tool_result(result.clone()),
         }
     }
 
@@ -1097,48 +1030,22 @@ pub async fn stream_text(
         })
     };
     let mut stream = stream;
-    let stream: Pin<Box<dyn Stream<Item = Result<StreamPart, AiMuxError>> + Send>> =
+    let stream: Pin<Box<dyn Stream<Item = Result<TextStreamPart, AiMuxError>> + Send>> =
         Box::pin(async_stream::stream! {
             while let Some(item) = stream.next().await {
                 match item {
-                    Ok(StreamPart::ToolCall {
-                        tool_call_id,
-                        tool_name,
-                        input,
-                        provider_executed,
-                        dynamic,
-                        thought_signature,
-                        provider_metadata,
-                        ..
-                    }) => {
+                    Ok(StreamPart::ToolCall(raw)) => {
                         let parsed = parse_tool_call(
-                            RawToolCall {
-                                tool_call_id,
-                                tool_name,
-                                input: crate::parse_tool_call::raw_tool_input(&input),
-                                provider_executed,
-                                dynamic,
-                                thought_signature,
-                                provider_metadata,
-                            },
+                            raw,
                             tools.as_deref(),
                             repair_tool_call.as_ref(),
                             &messages,
                             operation_instructions.as_deref(),
                         ).await;
-                        yield Ok(StreamPart::ToolCall {
-                            tool_call_id: parsed.tool_call_id,
-                            tool_name: parsed.tool_name,
-                            input: parsed.input,
-                            provider_executed: parsed.provider_executed,
-                            dynamic: parsed.dynamic,
-                            thought_signature: parsed.thought_signature,
-                            invalid: parsed.invalid,
-                            error: parsed.error,
-                            provider_metadata: parsed.provider_metadata,
-                        });
+                        yield Ok(StreamPart::ToolCall(parsed));
                     }
-                    item => yield item,
+                    Ok(part) => yield Ok(part.map_tool_call(|_| unreachable!("matched above"))),
+                    Err(error) => yield Err(error),
                 }
             }
         });
@@ -1749,23 +1656,23 @@ mod stream_aggregation_tests {
     use super::*;
     use crate::types::FinishReasonUnified;
 
-    fn result_from(parts: Vec<Result<StreamPart, AiMuxError>>) -> StreamTextResult {
+    fn result_from(parts: Vec<Result<TextStreamPart, AiMuxError>>) -> StreamTextResult {
         StreamTextResult {
             stream: Box::pin(futures::stream::iter(parts)),
             request_body: None,
             response_headers: None,
         }
     }
 
-    fn delta(text: &str) -> StreamPart {
+    fn delta(text: &str) -> TextStreamPart {
         StreamPart::TextDelta {
             id: "text-1".into(),
             delta: text.into(),
             provider_metadata: None,
         }
     }
 
-    fn finish() -> StreamPart {
+    fn finish() -> TextStreamPart {
         StreamPart::Finish {
             finish_reason: FinishReason {
                 unified: FinishReasonUnified::Stop,

aimux-core/src/lib.rs

@@ -96,9 +96,8 @@ pub mod prelude {
     };
     pub use crate::options::{CallOptions, ResponseFormat, ToolChoice};
     pub use crate::parse_tool_call::{
-        RawToolCall, ToolCallRepair, ToolCallRepairContext, ToolCallRepairReply,
-        apply_tool_call_repair, apply_tool_call_repair_to_result, tool_call_repair_context,
-        tool_call_repair_inputs,
+        ToolCallRepair, ToolCallRepairContext, ToolCallRepairReply, apply_tool_call_repair,
+        apply_tool_call_repair_to_result, tool_call_repair_context, tool_call_repair_inputs,
     };
     pub use crate::provider::Provider;
     pub use crate::reranking_model::{
@@ -120,8 +119,11 @@ pub mod prelude {
         SharedProviderOptions, SharedProviderReference, Size,
     };
     pub use crate::speech_model::{SpeechCallOptions, SpeechModel, SpeechResult, generate_speech};
-    pub use crate::stream_part::StreamPart;
-    pub use crate::tool::{FunctionTool, ProviderTool, Tool, ToolCall, ToolResult};
+    pub use crate::stream_part::{StreamPart, TextStreamPart};
+    pub use crate::tool::{
+        FunctionTool, FunctionToolInputExample, ProviderTool, RawToolCall, Tool, ToolCall,
+        ToolResult,
+    };
     pub use crate::transcription_model::{
         AudioChunk, InputAudioFormat, TranscriptionCallOptions, TranscriptionModel,
         TranscriptionResult, TranscriptionStreamOptions, TranscriptionStreamPart,