Merge branch 'main' into chore/release-lg-py-0.0.18

Author: ranst91

.github/workflows/rust-lint-test.yml

@@ -0,0 +1,59 @@
+name: test
+
+on:
+  push:
+    branches: [ "main" ]
+    paths:
+      - "crates/**"
+      - ".github/workflows/rust.yml"
+      - "tests/**"
+      - "Cargo.toml"
+      - ".cargo/**"
+  pull_request:
+    branches: [ "main" ]
+    paths:
+      - "sdks/community/rust/crates/**"
+      - "sdks/community/rust/**/tests/**"
+      - "sdks/community/rust/Cargo.toml"
+      - "sdks/community/rust/.cargo/**"
+      - ".github/workflows/rust-lint-test.yml"
+
+defaults:
+  run:
+    working-directory: ./rust
+
+jobs:
+  rust:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ ubuntu-latest, macos-latest, windows-latest ]
+
+    name: Rust SDK Tests [${{ matrix.os }}]
+    runs-on: ${{ matrix.os }}
+
+    env:
+      CARGO_TERM_COLOR: always
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: Swatinem/rust-cache@v2
+
+      - name: Build
+        run: cargo build --verbose
+
+      - name: Check formatting
+        run: cargo fmt -- --check
+
+      - name: Check clippy
+        run: cargo clippy -- -D warnings
+
+      - name: Publish ag-ui-core dry-run
+        run: cargo publish -p ag-ui-core --dry-run
+
+      - name: Publish ag-ui-client dry-run
+        run: cargo publish -p ag-ui-client --dry-run
+
+      - name: Run tests
+        run: cargo test --verbose

.gitignore

@@ -5,6 +5,8 @@ mastra.db*
 **/.DS_Store
 
 test-results/
+
+**/target
 .turbo
 
 node_modules

docs/sdk/kotlin/client/overview.mdx

@@ -65,12 +65,17 @@ Real-time event streaming using Kotlin Flows:
 - Server-sent events (SSE) parsing
 - Automatic reconnection handling
 - Backpressure management
+- Automatic expansion of `TEXT_MESSAGE_CHUNK` / `TOOL_CALL_CHUNK` events into start/content/end triads
+- Thinking telemetry exposed through `AgentState.thinking`
 
 ### State Management
 Comprehensive state synchronization:
 - JSON Patch-based state updates
 - Automatic state validation
 - Error state handling
+- Tool call results surfaced as `ToolMessage` entries without additional wiring
+- Access to raw/custom protocol events via `AgentState.rawEvents` and `AgentState.customEvents`
+- Thinking streams exposed through `AgentState.thinking`
 
 ### Tool Integration
 Client-side tool execution framework:
@@ -108,6 +113,21 @@ agent.sendMessage("Hello!").collect { state ->
 }
 ```
 
+### Reading Thinking Telemetry
+
+```kotlin
+agent.sendMessage("Plan the next steps").collect { state ->
+    state.thinking?.let { thinking ->
+        if (thinking.isThinking) {
+            val thought = thinking.messages.lastOrNull().orEmpty()
+            println("🤔 Agent thinking: $thought")
+        } else if (thinking.messages.isNotEmpty()) {
+            println("💡 Agent finished thinking: ${thinking.messages.joinToString()}")
+        }
+    }
+}
+```
+
 ### Convenience Builders
 
 The SDK provides convenience builders for common configurations:
@@ -139,6 +159,12 @@ val chatAgent = StatefulAgUiAgent("https://api.example.com/agent") {
 chatAgent.chat("My name is Alice").collect { }
 chatAgent.chat("What's my name?").collect { state ->
     // Agent knows the name from previous message
+    state.customEvents?.forEach { custom ->
+        println("Custom event ${custom.name}: ${custom.value}")
+    }
+    state.rawEvents?.forEach { raw ->
+        println("Raw payload: ${raw.event}")
+    }
 }
 ```
 
@@ -170,4 +196,4 @@ val agent = AgUiAgent("https://api.example.com/agent") {
 - Initial state setup
 - State validation rules
 - Update strategies
-- Persistence options
+- Persistence options

docs/sdk/kotlin/overview.mdx

@@ -106,6 +106,13 @@ chatAgent.chat("What's my name?").collect { state ->
 }
 ```
 
+Chunked protocol events (`TEXT_MESSAGE_CHUNK`, `TOOL_CALL_CHUNK`) are automatically rewritten into
+their corresponding start/content/end sequences, so Kotlin clients see the same structured events
+as non-chunked streams.
+
+Thinking telemetry (`THINKING_*` events) is surfaced alongside normal messages, allowing UIs to indicate
+when an agent is reasoning internally before responding.
+
 ### Client-Side Tool Integration
 
 ```kotlin
@@ -172,4 +179,22 @@ println("Messages: ${currentState.messages.size}")
 agent.sendMessage("Hello").collect { state ->
     println("Updated state: ${state.messages.last()}")
 }
-```
+
+// RAW and CUSTOM protocol events are surfaced for inspection
+state.rawEvents?.forEach { raw ->
+    println("Raw event from ${raw.source ?: "unknown"}: ${raw.event}")
+}
+state.customEvents?.forEach { custom ->
+    println("Custom event ${custom.name}: ${custom.value}")
+}
+
+// Thinking telemetry stream
+state.thinking?.let { thinking ->
+    if (thinking.isThinking) {
+        val latest = thinking.messages.lastOrNull().orEmpty()
+        println("Agent is thinking: $latest")
+    } else if (thinking.messages.isNotEmpty()) {
+        println("Agent finished thinking: ${thinking.messages.joinToString()}")
+    }
+}
+```

docs/sdk/rust/client/agent-trait.mdx

@@ -0,0 +1,116 @@
+---
+title: "Agent"
+description: "Agent trait with core event handling"
+---
+
+# Agent trait
+
+The Agent trait defines the contract for connecting any execution backend to AG‑UI. Concrete implementations (like HttpAgent) stream core events that are handled by subscribers to maintain messages and state.
+
+```rust
+use ag_ui_client::Agent;
+```
+
+## Generics
+
+- StateT: the agent state type. Must implement ag_ui_client::core::AgentState (Serialize + Deserialize + Clone + Debug + Send + Sync).
+- FwdPropsT: forwarded properties type passed through to downstream systems. Must implement ag_ui_client::core::FwdProps.
+
+Defaults for both are serde_json::Value, which works well for quick starts.
+
+## Running
+
+The core trait method you implement is run, which returns an asynchronous stream of core events:
+
+```rust
+#[async_trait::async_trait]
+pub trait Agent<StateT = JsonValue, FwdPropsT = JsonValue>
+where
+    StateT: AgentState,
+    FwdPropsT: FwdProps,
+{
+    async fn run(
+        &self,
+        input: &RunAgentInput<StateT, FwdPropsT>,
+    ) -> Result<EventStream<'async_trait, StateT>, AgentError>;
+}
+```
+
+For most consumers, use the provided convenience wrapper run_agent which:
+
+- constructs an internal RunAgentInput from RunAgentParams
+- initializes an event handler with your subscribers
+- consumes the event stream and applies mutations
+- returns RunAgentResult with final result, new messages and new state
+
+```rust
+use ag_ui_client::{Agent};
+use ag_ui_client::agent::{RunAgentParams, RunAgentResult};
+
+let params = RunAgentParams::new().user("Hello!");
+let result: RunAgentResult<_> = my_agent.run_agent(&params, ()).await?;
+```
+
+## RunAgentParams
+
+A builder for run inputs. Supports typed state and forwarded props via new_typed.
+
+```rust
+use ag_ui_client::agent::RunAgentParams;
+use ag_ui_client::core::types::{Message, Tool, Context};
+
+// JSON state (default)
+let params = RunAgentParams::new()
+    .user("User message")
+    .add_tool(Tool::new("search".into(), "Search".into(), serde_json::json!({"type":"object"})))
+    .add_context(Context::new("trace_id".into(), "123".into()));
+
+// Strongly-typed state/forwarded props
+#[derive(serde::Serialize, serde::Deserialize, Clone, Debug, Default)]
+struct MyState { count: u32 }
+#[derive(serde::Serialize, serde::Deserialize, Clone, Debug, Default)]
+struct MyProps { tenant: String }
+
+let params_typed = RunAgentParams::<MyState, MyProps>::new_typed()
+    .with_state(MyState { count: 1 })
+    .with_forwarded_props(MyProps { tenant: "acme".into() })
+    .user("Go!");
+```
+
+Builder helpers include:
+
+- with_run_id(run_id)
+- add_tool(tool)
+- add_context(ctx)
+- with_forwarded_props(props)
+- with_state(state)
+- add_message(message)
+- user(content: impl Into<String>)
+
+## RunAgentResult
+
+Returned by run_agent:
+
+```rust
+pub struct RunAgentResult<StateT: AgentState> {
+    pub result: serde_json::Value,
+    pub new_messages: Vec<Message>,
+    pub new_state: StateT,
+}
+```
+
+## AgentStateMutation
+
+Subscriber methods may return AgentStateMutation to update messages and/or state and optionally stop propagation to later subscribers.
+
+```rust
+pub struct AgentStateMutation<StateT = JsonValue> {
+    pub messages: Option<Vec<Message>>,
+    pub state: Option<StateT>,
+    pub stop_propagation: bool,
+}
+```
+
+## Errors
+
+Most Agent operations return Result<_, AgentError> where AgentError = ag_ui_client::error::AgUiClientError. See the client error page for details. Common categories include configuration errors, HTTP transport/status errors (for HttpAgent), JSON errors, and subscriber errors.

docs/sdk/rust/client/http-agent.mdx

@@ -0,0 +1,90 @@
+---
+title: "HttpAgent"
+description: "HTTP-based Agent implementation for connecting to remote AI agents"
+---
+
+# HttpAgent
+
+The HttpAgent implements the Agent trait to provide HTTP-based connectivity to remote AI agents. It sends a POST request with a RunAgentInput payload and consumes a Server-Sent Events (SSE) stream of core events.
+
+```rust
+use ag_ui_client::HttpAgent
+```
+
+## Installation
+
+```bash
+cargo add ag-ui-client
+```
+
+## Creating an HttpAgent
+
+Use the builder to configure the base URL, headers, timeouts and optional Agent ID.
+
+```rust
+use ag_ui_client::HttpAgent;
+use reqwest::Url;
+
+let agent = HttpAgent::builder()
+    .with_url(Url::parse("https://api.example.com/v1/agent")?)
+    .with_bearer_token("your-api-key")?
+    .with_timeout(30)
+    .build()?;
+```
+
+Alternatively, pass a string URL and let the builder validate it:
+
+```rust
+let agent = HttpAgent::builder()
+    .with_url_str("https://api.example.com/v1/agent")?
+    .build()?;
+```
+
+## Configuration
+
+HttpAgent exposes a fluent builder with the following options:
+
+- `with_url(url: Url)` – Set the endpoint URL
+- `with_url_str(url: &str) -> Result<Self, AgentError>` – Parse and validate a string URL
+- `with_headers(headers: HeaderMap)` – Replace all headers
+- `with_header(name: &str, value: &str) -> Result<Self, AgentError>` – Add a single header
+- `with_header_typed(name: HeaderName, value: HeaderValue)` – Add a typed header
+- `with_bearer_token(token: &str) -> Result<Self, AgentError>` – Add Authorization: Bearer …
+- `with_http_client(client: reqwest::Client)` – Provide a custom reqwest client
+- `with_timeout(seconds: u64)` – Configure a request timeout on an internal client
+- `with_agent_id(agent_id: AgentId)` – Attach an optional AgentId reported via Agent::agent_id()
+
+Note: The builder enforces http/https schemes and returns an AgentError::Config for invalid inputs.
+
+## Running an agent over HTTP
+
+Use Agent::run_agent with your parameters (messages, tools, state, etc.). The HttpAgent takes care of sending the request and streaming events.
+
+```rust
+use ag_ui_client::{Agent, HttpAgent};
+use ag_ui_client::agent::RunAgentParams;
+use ag_ui_client::core::types::Message;
+
+let params = RunAgentParams::new()
+    .user("Tell me a short joke about Rust.");
+
+let result = agent.run_agent(&params, None).await?;
+println!("Final result: {}", result.result);
+println!("New messages: {}", result.new_messages.len());
+```
+
+## Errors
+
+HttpAgent surfaces a few structured error types through AgUiClientError (aliased as AgentError):
+
+- HttpTransport(reqwest::Error) – network and transport errors
+- HttpStatus { status, context } – non-success HTTP status with a snippet of the response body
+- Config { message } – invalid configuration inputs (e.g., malformed URL/header)
+
+Use AgUiClientError::is_retryable() to determine if an error can be retried (timeouts, 5xx, 429).
+
+## Implementation notes
+
+- Requests are sent as JSON with Content-Type: application/json; responses are handled as text/event-stream SSE.
+- The response stream is decoded into Event<StateT> items defined in ag-ui-core.
+- Agent::agent_id() returns the optional AgentId configured on the builder.