[Kotlin] Major enhancements and refactoring

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()}")
+    }
+}
+```

sdks/community/kotlin/.gitignore

@@ -42,9 +42,10 @@ captures/
 *.perspectivev3
 **/*.xcworkspace/xcuserdata/
 **/*.xcodeproj/xcuserdata/
-*.xccheckout
-*.xcscmblueprint
-DerivedData/
+*.xccheckout
+*.xcscmblueprint
+*.xcsettings
+DerivedData/
 *.hmap
 *.ipa
 *.dSYM.zip
@@ -101,4 +102,4 @@ temp/
 *.rar
 
 # Virtual machine crash logs
-hs_err_pid*
+hs_err_pid*

sdks/community/kotlin/CHANGELOG.md

@@ -4,10 +4,23 @@
 - Smaller binary sizes due to better optimization
 - Improved coroutine performance with latest kotlinx.coroutines# Changelog
 
-All notable changes to ag-ui-4k will be documented in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+All notable changes to ag-ui-4k will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- Agent subscriber system for opt-in lifecycle and event interception.
+- Text message role fidelity in chunk transformation and state application.
+
+### Changed
+- Default apply pipeline now routes every event through subscribers before mutating state.
+- State application respects developer/system/user roles when constructing streaming messages.
+
+### Tests
+- Expanded chunk transformation and state application coverage for role propagation and subscriber behavior.
 
 ## [0.1.0] - 2025-06-14
 

sdks/community/kotlin/OVERVIEW.md

@@ -21,4 +21,9 @@ AG-UI Kotlin SDK follows the design patterns of the TypeScript SDK while leverag
 - **kotlin-client**: HTTP transport, state management, and high-level agent APIs  
 - **kotlin-tools**: Tool execution framework with registry and circuit breakers
 
-The SDK maintains conceptual parity with the TypeScript implementation while providing native Kotlin idioms like sealed classes, suspend functions, and Kotlin Flows for streaming responses.
+The SDK maintains conceptual parity with the TypeScript implementation while providing native Kotlin idioms like sealed classes, suspend functions, and Kotlin Flows for streaming responses.
+
+## Lifecycle subscribers and role fidelity
+
+- **AgentSubscriber hooks** – Agents now expose a subscription API so applications can observe run initialization, per-event delivery, and state mutations before the built-in handlers execute. This enables cross-cutting concerns like analytics, tracing, or custom persistence without forking the pipeline.
+- **Role-aware text streaming** – Text message events preserve their declared roles (developer, system, assistant, user) throughout chunk transformation and state application, ensuring downstream UI state mirrors the protocol payloads exactly.

sdks/community/kotlin/README.md

@@ -21,7 +21,7 @@ The comprehensive documentation covers:
 
 ```kotlin
 dependencies {
-    implementation("com.agui:kotlin-client:0.2.1")
+    implementation("com.agui:kotlin-client:0.2.3")
 }
 ```
 

sdks/community/kotlin/build.gradle.kts

@@ -1,8 +1,8 @@
 import org.jetbrains.kotlin.gradle.targets.js.dsl.ExperimentalWasmDsl
 
-plugins {
-    kotlin("multiplatform") version "2.1.21"
-    kotlin("plugin.serialization") version "2.1.21"
+plugins {
+    kotlin("multiplatform") version "2.2.20"
+    kotlin("plugin.serialization") version "2.2.20"
     id("com.android.library") version "8.2.2"
     id("io.gitlab.arturbosch.detekt") version "1.23.4"
     id("maven-publish")
@@ -34,8 +34,8 @@ kotlin {
                     freeCompilerArgs.add("-Xopt-in=kotlin.RequiresOptIn")
                     freeCompilerArgs.add("-Xopt-in=kotlinx.coroutines.ExperimentalCoroutinesApi")
                     freeCompilerArgs.add("-Xopt-in=kotlinx.serialization.ExperimentalSerializationApi")
-                    languageVersion.set(org.jetbrains.kotlin.gradle.dsl.KotlinVersion.KOTLIN_2_1)
-                    apiVersion.set(org.jetbrains.kotlin.gradle.dsl.KotlinVersion.KOTLIN_2_1)
+                    languageVersion.set(org.jetbrains.kotlin.gradle.dsl.KotlinVersion.KOTLIN_2_2)
+                    apiVersion.set(org.jetbrains.kotlin.gradle.dsl.KotlinVersion.KOTLIN_2_2)
                 }
             }
         }
@@ -226,4 +226,4 @@ tasks.withType<io.gitlab.arturbosch.detekt.Detekt>().configureEach {
         sarif.required.set(true)
         md.required.set(true)
     }
-}
+}