Add explicit session reset APIs

[redsun82]

Summary

Adds explicit reset(config) support across the SDKs. This captures the SDK-owned lifecycle part of the TUI /clear behavior, while keeping host-owned state like UI cleanup, workspace bindings, session trees, and refs in the embedding app.

Terminology

This uses reset rather than clear on the SDK API because clear is a TUI verb: it includes clearing the visible transcript and other host-owned UI state. In the SDK, that part has to stay with the embedding app.

The SDK method owns the runtime lifecycle piece instead: clear queued work, tear down the current runtime session, and create a fresh session from explicit config. reset(config) names that more precisely, and avoids implying that the SDK can or should clear app-owned state like tabs, refs, session trees, drafts, or rendered messages.

clear(config) would also be a bit confusing, I think: the config argument is not describing what to clear, it is describing the replacement session to create after the old runtime session has been abandoned.

Changes

• Adds reset APIs across Node, Python, Go, .NET, Rust, and Java.
• Clears pending queue work, tears down the old runtime session, and creates a fresh session from caller-supplied config.
• Returns the previous session ID plus the fresh session so hosts can update their own session mappings.
• Ignores caller-provided session IDs on reset so replacement sessions always get a fresh identity.
• Documents that if reset fails after teardown starts, callers should treat the old session handle as unusable.
• Adds focused tests for reset sequencing, stale-session rejection, config cloning, and concurrent reset guards.

Validation

• Node: npm ci, npm run typecheck, npm run format:check, npx vitest run test/client.test.ts
• Python: uv run ruff check ., uv run ruff format --check .
• Go: go test .
• Rust: cargo +nightly-2026-04-14 fmt --check, cargo check, cargo test reset_rejects_inactive_session_handle
• Java: mvn -Denforcer.skip=true test -Dtest=ConfigCloneTest
• .NET: dotnet build src/GitHub.Copilot.SDK.csproj --no-restore
• git --no-pager diff --check

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Adds a cross-SDK “session reset” capability that tears down the current runtime session and creates a fresh one from explicit configuration, including guardrails for stale handles and concurrent resets.

Changes:

• Introduces reset/ResetAsync/Reset APIs and ResetSessionResult types across Rust, Python, Node.js, Java, Go, and .NET.
• Adds client-side tracking for session registrations and “reset in progress” state to reject stale handles and concurrent resets.
• Updates docs and compatibility matrix to describe reset behavior and /clear lifecycle parity.

Show a summary per file

File	Description
rust/src/session.rs	Adds session registration IDs and implements Session::reset with a result type and a Rust unit test.
rust/src/lib.rs	Tracks session registrations/reset-in-progress state in Client, and updates register/unregister APIs.
rust/src/errors.rs	Adds SessionErrorKind::ResetInProgress and display formatting.
rust/README.md	Documents Rust session reset usage and expectations for host UI cleanup.
python/copilot/session.py	Adds CopilotSession.reset, lifecycle cleanup helpers, and switches model capability helpers to a new module.
python/copilot/client.py	Refactors model capability override types into a dedicated module; adds client-side reset book-keeping.
python/copilot/_reset.py	Introduces Python ResetSessionResult dataclass.
python/copilot/_model_capabilities.py	New module containing model capability override dataclasses and serialization helper.
python/copilot/init.py	Re-exports ResetSessionResult.
python/README.md	Documents Python session reset usage.
nodejs/test/client.test.ts	Adds tests for reset behavior, config handling, and concurrency rejection.
nodejs/src/types.ts	Adds ResetSessionResult TS interface.
nodejs/src/session.ts	Adds session.reset, detach/cleanup logic, and enhanced disconnect behavior.
nodejs/src/index.ts	Exports ResetSessionResult.
nodejs/src/client.ts	Implements reset orchestration and concurrent-reset rejection; adds session forget helper.
nodejs/README.md	Documents Node.js session reset usage.
java/src/test/java/com/github/copilot/ConfigCloneTest.java	Adds test to ensure reset can clear sessionId without mutating the original config.
java/src/main/java/com/github/copilot/ResetSessionResult.java	Adds Java ResetSessionResult record.
java/src/main/java/com/github/copilot/CopilotSession.java	Adds resetAsync and refactors destruction paths to support reset vs close semantics.
java/src/main/java/com/github/copilot/CopilotClient.java	Adds reset coordination with concurrent-reset rejection and session unregister support.
java/README.md	Documents Java session reset usage.
go/types.go	Adds Go ResetResult type.
go/session.go	Adds Session.Reset and unregister-on-disconnect through parent client.
go/client.go	Adds reset orchestration and concurrent-reset rejection; session forget helper.
go/README.md	Documents Go session reset usage.
dotnet/src/Types.cs	Adds .NET ResetSessionResult record type.
dotnet/src/Session.cs	Adds ResetAsync and reset-specific destroy path with local-state clearing.
dotnet/src/JsonRpc.cs	Avoids warning-log formatting work when warning level is disabled.
dotnet/src/Client.cs	Implements reset orchestration and concurrent-reset tracking cleanup.
dotnet/README.md	Documents .NET session reset usage.
docs/troubleshooting/compatibility.md	Adds reset to feature matrix and clarifies /clear lifecycle guidance.

Copilot's findings

Comments suppressed due to low confidence (1)

rust/src/session.rs:1

• The new reset coordination logic adds important concurrency semantics (ResetInProgress gating + begin_session_reset/end_session_reset), but the Rust tests added here only cover the inactive-handle rejection. Add a unit test that starts one reset() and, while it is paused between steps (e.g., after queue clear, before disconnect completes), asserts that a second reset() returns ResetInProgress, and also assert that end_session_reset is executed on error paths (so subsequent resets are not permanently blocked).

• Files reviewed: 31/31 changed files
• Comments generated: 3

[SteveSandersonMS]

@redsun82 Can you clarify if there's some part of the logic here that needs to be done inside the SDK as opposed to being done by client apps?

I would have thought client apps are already able to destroy a session and then create a new one with equivalent config. What extra thing do we get from having ResetSessionAsync as an SDK feature?

I'm asking because this is quite an opinionated flow - it's not at all obvious that "reset" should actually mean "destroy and get a different instance". From the name alone I think people would expect "reset" to mutate the session in some way that resets it (so you end up with the same session object, same session ID), not to create a whole new session with a new ID.

So I'm wondering if we could avoid this risk of confusion by keeping this logic inside the apps that need it, rather than making it a general SDK feature.