Skip to content

Client SDKs: sessions.create opens a watched session - #2140

Merged
tschellenbach merged 5 commits into
mainfrom
feat/sessions-create-watches
Nov 19, 2026
Merged

tschellenbach merged 5 commits into
mainfrom
feat/sessions-create-watches

Conversation

@tschellenbach

Copy link
Copy Markdown
Member

How it works

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
Examples (android_assistant, swift_demo, swift_assistant) chat(...) + start() sessions.create(...)

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: 295 tests pass.
  • Live tests need a router URL and weren't run.

Made with Cursor

tschellenbach and others added 3 commits November 19, 2026 15:00
Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
@tschellenbach
tschellenbach marked this pull request as ready for review November 19, 2026 22:08
Co-authored-by: Cursor <cursoragent@cursor.com>
@coderabbitai

coderabbitai Bot commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

Explain Change →

Walkthrough

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.

Share

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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)

Review info

Run configuration

Commits

Reviewing files that changed from the base of the PR and between 8e9a001 and a9a05fb.

Files ignored due to path filters: 1

  • sdks/kotlin/core/src/main/kotlin/io/getstream/agents/android/core/generated/ErrorDetail.kt is excluded by !**/generated/**
Files selected for processing: 33

  • .claude/skills/sdk-swift/SKILL.md
  • examples/voice_agents/android_assistant/app/src/main/kotlin/io/getstream/agents/androidassistant/ChatViewModel.kt
  • examples/voice_agents/swift_assistant/app/SwiftAssistant/AgentChat.swift
  • examples/voice_agents/swift_assistant/app/SwiftAssistant/VoiceMode.swift
  • examples/voice_agents/swift_demo/app/SwiftDemo/AgentChat.swift
  • examples/voice_agents/swift_demo/app/SwiftDemo/ChatView.swift
  • examples/voice_agents/swift_demo/app/SwiftDemo/VoiceView.swift
  • sdks/dart/stream_agents/CHANGELOG.md
  • sdks/dart/stream_agents/README.md
  • sdks/dart/stream_agents/lib/src/core/agent_session.dart
  • sdks/dart/stream_agents/lib/src/core/convert.dart
  • sdks/dart/stream_agents/lib/src/core/models.dart
  • sdks/dart/stream_agents/lib/src/core/sessions.dart
  • sdks/dart/stream_agents/lib/src/core/stream_agents.dart
  • sdks/dart/stream_agents/test/core/client_test.dart
  • sdks/dart/stream_agents/test/core/live_test.dart
  • sdks/dart/stream_agents/test/core/posture_test.dart
  • sdks/kotlin/README.md
  • sdks/kotlin/core/src/main/kotlin/io/getstream/agents/android/core/AgentSession.kt
  • sdks/kotlin/core/src/main/kotlin/io/getstream/agents/android/core/Options.kt
  • sdks/kotlin/core/src/main/kotlin/io/getstream/agents/android/core/Sessions.kt
  • sdks/kotlin/core/src/main/kotlin/io/getstream/agents/android/core/StreamAgents.kt
  • sdks/kotlin/core/src/test/kotlin/io/getstream/agents/android/core/AgentSessionTest.kt
  • sdks/kotlin/core/src/test/kotlin/io/getstream/agents/android/core/LiveTest.kt
  • sdks/kotlin/core/src/test/kotlin/io/getstream/agents/android/core/PostureTest.kt
  • sdks/kotlin/core/src/test/kotlin/io/getstream/agents/android/core/StreamAgentsTest.kt
  • sdks/swift/README.md
  • sdks/swift/core/Sources/StreamAgents/AgentSession.swift
  • sdks/swift/core/Sources/StreamAgents/SessionSocket.swift
  • sdks/swift/core/Sources/StreamAgents/StreamAgents.swift
  • sdks/swift/core/Sources/StreamAgents/VoiceSession.swift
  • sdks/swift/core/Tests/StreamAgentsTests/LiveTests.swift
  • sdks/swift/core/Tests/StreamAgentsTests/SessionsTests.swift
Files with no reviewable changes: 2

  • examples/voice_agents/swift_assistant/app/SwiftAssistant/VoiceMode.swift
  • examples/voice_agents/swift_demo/app/SwiftDemo/VoiceView.swift

Included review availability: This review used your included allowance. Your plan provides up to 8 included reviews per hour; 7 remain after this review.

Co-authored-by: Cursor <cursoragent@cursor.com>
@tschellenbach
tschellenbach merged commit ebc1995 into main Nov 19, 2026
12 of 13 checks passed
@tschellenbach
tschellenbach deleted the feat/sessions-create-watches branch November 19, 2026 22:45
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant