Merge pull request #108 from Contextable/codex/analyze-kotlin-sdk-vs-typescript-sdk

Codex/analyze kotlin sdk vs typescript sdk

Author: contextablemark

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

integrations/adk-middleware/python/README.md

@@ -247,6 +247,19 @@ add_adk_fastapi_endpoint(app, technical_agent_wrapper, path="/agents/technical")
 add_adk_fastapi_endpoint(app, creative_agent_wrapper, path="/agents/creative")
 ```
 
+## Railway Deployment
+
+Deploy the middleware as a managed FastAPI service using the included Railway manifest.
+
+1. Install the Railway CLI (`npm i -g @railway/cli`) and authenticate with `railway login`.
+2. From the repository root run `railway up` to create or update a service using `railway.toml`.
+3. Set `GOOGLE_API_KEY` or `GOOGLE_APPLICATION_CREDENTIALS` in the Railway dashboard so the ADK agent can call Gemini.
+4. (Optional) Tune behaviour with the environment variables documented in `ag_ui_adk/railway_app.py` such as `ADK_MODEL`, `ADK_APP_NAME`, and `ADK_API_PATH`.
+
+Railway builds from the provided `Dockerfile`, which installs the middleware and runs `uvicorn ag_ui_adk.railway_app:app`. The middleware endpoint is available at `https://<your-service>.railway.app/chat` (or the path set in `ADK_API_PATH`) with `/health` exposed for monitoring.
+
+> Note: A `Procfile` remains for local tooling compatibility, but Railway uses the Dockerfile as the authoritative start command.
+
 ## Tool Support
 
 The middleware provides complete bidirectional tool support, enabling AG-UI Protocol tools to execute within Google ADK agents. All tools supplied by the client are currently implemented as long-running tools that emit events to the client for execution and can be combined with backend tools provided by the agent to create a hybrid combined toolset.

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