You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Client SDKs: sessions.create opens a watched session - #2140
agent(name).sessions.create(options)
├─ watch = true (default)
│ ├─ POST /sessions, then open the socket, then return
│ │ -> the tools in options are answered from the first turn
│ └─ socket fails to open -> POST /sessions/{id}/stop, rethrow
└─ watch = false
└─ POST /sessions only, no socket
-> say / interrupt / decide / addTools throw a configuration error
-> close() stops the session over HTTP
chat(...) / voice(...) -> thin wrappers, socket waits for start()
Why
In JS, client.agent("support").sessions.create({ tools }) opens the session and answers its tools. In Kotlin, Swift and Dart the same call returned a session that nothing was watching, so the docs fell back to a different call on each platform (agents.agent("support").chat(location) in Kotlin, agents.chat(...) plus start() in Swift). Now all four work the same way, and the tool-calling docs show one shape (GetStream/getstream.io#1183).
Changes
Before
After
Kotlin Sessions.create
raw Session, no socket
AgentSession, watched, SessionOptions(watch = false) opts out
Swift Sessions.create
AgentSession, socket waits for start()
watched on return, options.watch = false opts out, honours startVoice
Dart Sessions.create
raw Session, no socket
Future<AgentSession>, watched, SessionOptions(watch: false) opts out
Breaking for callers of sessions.create: Kotlin and Dart return an AgentSession (session fields under .session), and a socket opens by default. To get the old behaviour, pass watch = false.
Validation
Change
Test that proves it
Watched sessions answer tools without start()
Swift aSessionOpenedAnswersItsToolsWithoutBeingStarted (fails if create skips the socket), Kotlin AgentSessionTest, Dart client_test.dart
watch = false opens no socket and says why
Swift aSessionOpenedUnwatchedHasNoSocketAndSaysWhatToDoInstead, Kotlin and Dart equivalents
A refused socket stops the session
Kotlin AgentSessionTest: socket answered 403, so the caller gets that 403 and the router receives POST /v1/agents/sessions/s1/stop
chat + start() still works
Swift aChatAnswersItsToolsOnceStarted
Kotlin: 220 tests, 0 failures (10 live tests skipped), release build OK.
Swift: 173 tests in 18 suites pass on the iOS simulator.
Dart, Kotlin, and Swift add a watch option to session creation. Watched sessions start following the session before creation returns. Unwatched sessions open without a socket or declared tools, and socket-dependent operations reject them; the SDKs provide HTTP response operations for turns. Session handles, chat and voice entry points, socket startup and closure, examples, and tests are updated to match these behaviors.
Merge Risk: Moderate · up to a9a05
Creating a watched session now opens the socket before returning. Cancelling during that wait can leave a live session on the router with no handle to stop it, and concurrent start calls on Swift sessions can misbehave. Fix the cancellation cleanup paths before merging; the remaining issues are minor.
- [ ] Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.
The reason will be displayed to describe this comment to others. Learn more.
Actionable comments posted: 7
Caution
Some comments are outside the diff and can’t be posted inline due to GitHub limitations.
⚠️ Outside diff range comments (2)
Major · Stop the created session when start() is cancelled. · Sessions.kt:75
sdks/kotlin/core/src/main/kotlin/io/getstream/agents/android/core/Sessions.kt:75 Major · Stability & Availability · Quick win
Stop the created session when start() is cancelled.
If the caller cancels sessions.create() after the POST succeeds and while session.start() waits for the socket, the CancellationException is not an AgentsException. The handler at line 75 does not run, so no close(created.id) request is sent. The session stays live in the router, and no AgentSession is returned, so the caller cannot stop it.
Run the stop for every failure of session.start(), including cancellation. Run it in NonCancellable, because the coroutine is already cancelled when the stop request starts. Then rethrow the original exception. Add the kotlinx.coroutines.NonCancellable and kotlinx.coroutines.withContext imports.
Suggested fix
- } catch (e: AgentsException) {
+ } catch (e: Throwable) {
// The session is live in the router even though nothing here can watch it, so it is
// stopped rather than left holding a call nobody is listening to.
- try {
- close(created.id)
- } catch (_: AgentsException) {
- // What the caller needs to hear is why it could not be watched.
- }
+ withContext(NonCancellable) {
+ try {
+ close(created.id)
+ } catch (_: AgentsException) {
+ // What the caller needs to hear is why it could not be watched.
+ }
+ }
throw e
Minor · Check watch mode before the approval lookup. · agent_session.dart:264-265
sdks/dart/stream_agents/lib/src/core/agent_session.dart:264-265 Minor · Functional Correctness · Quick win
Check watch mode before the approval lookup.
For watch: false, approvals remains empty. decide('c1', allowed: true) therefore returns before _held() and does not throw the promised StateError. Call _watched() before reading the approvals. Keep the existing no-op behavior for repeated decisions on watched sessions. (raw.githubusercontent.com)
Included review availability: This review used your included allowance. Your plan provides up to 8 included reviews per hour; 7 remain after this review.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
How it works
Why
In JS,
client.agent("support").sessions.create({ tools })opens the session and answers its tools. In Kotlin, Swift and Dart the same call returned a session that nothing was watching, so the docs fell back to a different call on each platform (agents.agent("support").chat(location)in Kotlin,agents.chat(...)plusstart()in Swift). Now all four work the same way, and the tool-calling docs show one shape (GetStream/getstream.io#1183).Changes
Sessions.createSession, no socketAgentSession, watched,SessionOptions(watch = false)opts outSessions.createAgentSession, socket waits forstart()options.watch = falseopts out, honoursstartVoiceSessions.createSession, no socketFuture<AgentSession>, watched,SessionOptions(watch: false)opts outandroid_assistant,swift_demo,swift_assistant)chat(...)+start()sessions.create(...)Breaking for callers of
sessions.create: Kotlin and Dart return anAgentSession(session fields under.session), and a socket opens by default. To get the old behaviour, passwatch = false.Validation
start()aSessionOpenedAnswersItsToolsWithoutBeingStarted(fails ifcreateskips the socket), KotlinAgentSessionTest, Dartclient_test.dartwatch = falseopens no socket and says whyaSessionOpenedUnwatchedHasNoSocketAndSaysWhatToDoInstead, Kotlin and Dart equivalentsAgentSessionTest: socket answered 403, so the caller gets that 403 and the router receivesPOST /v1/agents/sessions/s1/stopchat+start()still worksaChatAnswersItsToolsOnceStartedMade with Cursor