docs: add session limits guidance

[szabta89]

Context

The Copilot runtime session-limits feature is now part of the SDK baseline through #1865, which updated the CLI/schema dependency and exposed sessionLimits on session create/resume options across SDKs.

Problem

SDK users can now set a max AI Credits budget, but the documentation does not explain how to configure it, which budget-related events applications can observe, or the current limitation around changing limits on an already-running session.

Solution

This PR is now a docs-only follow-up:

• Adds a session-limits feature guide with create/resume examples for TypeScript, Python, Go, .NET, Java, and Rust.
• Extends the streaming event reference with session.session_limits_changed, session.usage_checkpoint, session_limits_exhausted.requested, and session_limits_exhausted.completed.
• Links the new guide from the docs feature indexes.

Validation

The branch was rebuilt on current main with documentation-only changes, so no generated code or SDK test files are modified.

[Copilot]

Pull request overview

This PR adds session limits (AI credit budget) support across the SDKs (Node/TS, Python, Go, .NET, Java, Rust), updates schema-derived RPC/session-event types from @github/copilot@1.0.66, and documents/validates the new events and update/clear flows.

Changes:

• Expose sessionLimits on session create/resume plus per-session update/clear APIs (including explicit-null semantics where needed).
• Regenerate schema-derived RPC + session-event types (new/renamed session-limit events and related RPC surfaces).
• Add focused tests and docs for forwarding + update/clear behavior and new emitted events.

Show a summary per file

File	Description
scripts/codegen/go.ts	Adds Go codegen support for explicit-null companion field when clearing sessionLimits.
scripts/codegen/csharp.ts	Adds C# codegen support to distinguish omitted vs explicit-null sessionLimits in session.options.update.
rust/src/wire.rs	Forwards session_limits in create/resume wire payloads.
rust/src/types.rs	Introduces SessionLimitsConfig, wires it into SessionConfig/ResumeSessionConfig, and adds serialization tests.
rust/src/session.rs	Adds a session limits sub-API and payload builder/tests for session.options.update.
rust/src/generated/session_events.rs	Regenerates session events: rename to session.session_limits_changed, adds usage checkpoint + exhaustion events, etc.
rust/src/generated/rpc.rs	Regenerates RPC surface (includes completions namespace and handlePendingSessionLimitsExhausted).
rust/src/generated/api_types.rs	Regenerates API types + RPC method constants; updates limit-related types and docs.
rust/README.md	Documents Rust session limits usage and related events.
python/test_client.py	Adds tests for limits update/clear and create/resume forwarding/omission.
python/README.md	Documents Python session limits usage and related events.
python/copilot/session.py	Adds SessionLimitsConfig, wire conversion, and SessionLimitsApi.
python/copilot/client.py	Forwards session_limits on create/resume to sessionLimits wire payload.
python/copilot/init.py	Exports SessionLimitsApi and SessionLimitsConfig.
nodejs/test/e2e/session_limits.e2e.test.ts	Adds Node E2E coverage for set/clear emitting session.session_limits_changed.
nodejs/test/client.test.ts	Adds Node unit tests for update/clear RPC and create/resume forwarding.
nodejs/src/types.ts	Adds public Node types for session limits config + limits API.
nodejs/src/session.ts	Adds session.limits API and setSessionLimits() wrapper calling options.update.
nodejs/src/index.ts	Re-exports new public types alongside generated session events.
nodejs/src/generated/session-events.ts	Regenerates Node session-event types (limits/usage checkpoint/exhaustion, etc.).
nodejs/src/generated/rpc.ts	Regenerates Node RPC types + adds completions + handlePendingSessionLimitsExhausted.
nodejs/src/client.ts	Forwards sessionLimits during create/resume.
nodejs/README.md	Documents Node session limits usage and related events.
nodejs/package.json	Bumps @github/copilot dependency to ^1.0.66.
nodejs/package-lock.json	Updates lockfile to @github/copilot@1.0.66 artifacts and metadata.
java/src/test/java/com/github/copilot/SessionRequestBuilderTest.java	Adds Java tests for forwarding/omission + explicit-null serialization for limits update params.
java/src/test/java/com/github/copilot/SessionEventHandlingTest.java	Updates assistant message event construction for regenerated event schema.
java/src/test/java/com/github/copilot/generated/rpc/GeneratedRpcRecordsCoverageTest.java	Updates record construction for regenerated RPC record shapes.
java/src/main/java/com/github/copilot/SessionRequestBuilder.java	Forwards sessionLimits into create/resume request builders.
java/src/main/java/com/github/copilot/rpc/SessionLimitsConfig.java	Adds Java public config type for session limits (fluent setter + OptionalDouble getter).
java/src/main/java/com/github/copilot/rpc/SessionLimitsApi.java	Adds Java session limits API interface.
java/src/main/java/com/github/copilot/rpc/SessionConfig.java	Adds sessionLimits field + getter/setter to create-session config.
java/src/main/java/com/github/copilot/rpc/ResumeSessionRequest.java	Adds sessionLimits to resume request DTO.
java/src/main/java/com/github/copilot/rpc/ResumeSessionConfig.java	Adds sessionLimits field + getter/setter to resume-session config.
java/src/main/java/com/github/copilot/rpc/CreateSessionRequest.java	Adds sessionLimits to create request DTO.
java/src/main/java/com/github/copilot/CopilotSession.java	Implements SessionLimitsApi on the session and adds explicit-null update params record.
java/src/main/java/com/github/copilot/CopilotClient.java	Updates options update parameter ordering to match regenerated schema (session limits + excluded builtin agents).
java/src/generated/java/com/github/copilot/generated/SessionUsageCheckpointEvent.java	Adds generated session usage checkpoint event type.
java/src/generated/java/com/github/copilot/generated/SessionStartEvent.java	Regenerates start event to include sessionLimits instead of response limits.
java/src/generated/java/com/github/copilot/generated/SessionSessionLimitsChangedEvent.java	Regenerates limits-changed event name/payload.
java/src/generated/java/com/github/copilot/generated/SessionResumeEvent.java	Regenerates resume event to include sessionLimits instead of response limits.
java/src/generated/java/com/github/copilot/generated/SessionLimitsExhaustedResponseAction.java	Adds generated enum for session limit exhaustion responses.
java/src/generated/java/com/github/copilot/generated/SessionLimitsExhaustedResponse.java	Adds generated record for session limit exhaustion response payload.
java/src/generated/java/com/github/copilot/generated/SessionLimitsExhaustedRequestedEvent.java	Adds generated exhaustion requested event type.
java/src/generated/java/com/github/copilot/generated/SessionLimitsExhaustedCompletedEvent.java	Adds generated exhaustion completed event type.
java/src/generated/java/com/github/copilot/generated/SessionLimitsConfig.java	Renames/updates generated limits config type for events package.
java/src/generated/java/com/github/copilot/generated/SessionEvent.java	Updates session event union to include new/renamed limit-related events.
java/src/generated/java/com/github/copilot/generated/rpc/UISessionLimitsExhaustedResponseAction.java	Adds generated RPC enum for UI exhaustion response action.
java/src/generated/java/com/github/copilot/generated/rpc/UISessionLimitsExhaustedResponse.java	Adds generated RPC record for UI exhaustion response payload.
java/src/generated/java/com/github/copilot/generated/rpc/SessionUiHandlePendingSessionLimitsExhaustedResult.java	Adds generated RPC result type for handling pending exhaustion.
java/src/generated/java/com/github/copilot/generated/rpc/SessionUiHandlePendingSessionLimitsExhaustedParams.java	Adds generated RPC params for handling pending exhaustion.
java/src/generated/java/com/github/copilot/generated/rpc/SessionUiApi.java	Adds generated UI API method handlePendingSessionLimitsExhausted.
java/src/generated/java/com/github/copilot/generated/rpc/SessionRpc.java	Adds generated completions namespace accessor on session RPC.
java/src/generated/java/com/github/copilot/generated/rpc/SessionOptionsUpdateParams.java	Updates options update params to include sessionLimits and excluded builtin agents.
java/src/generated/java/com/github/copilot/generated/rpc/SessionMetadataSnapshotResult.java	Updates snapshot result to include sessionLimits instead of response limits.
java/src/generated/java/com/github/copilot/generated/rpc/SessionLimitsConfig.java	Renames/updates generated limits config type for RPC package.
java/src/generated/java/com/github/copilot/generated/rpc/SessionEventLogRegisterInterestParams.java	Updates docs/examples for event interest registration to include exhaustion event.
java/src/generated/java/com/github/copilot/generated/rpc/SessionCompletionsRequestResult.java	Adds generated RPC result for completions request.
java/src/generated/java/com/github/copilot/generated/rpc/SessionCompletionsRequestParams.java	Adds generated RPC params for completions request.
java/src/generated/java/com/github/copilot/generated/rpc/SessionCompletionsGetTriggerCharactersResult.java	Adds generated RPC result for completions trigger characters.
java/src/generated/java/com/github/copilot/generated/rpc/SessionCompletionsGetTriggerCharactersParams.java	Adds generated RPC params for completions trigger characters.
java/src/generated/java/com/github/copilot/generated/rpc/SessionCompletionsApi.java	Adds generated completions API namespace.
java/src/generated/java/com/github/copilot/generated/rpc/SessionCompletionItem.java	Adds generated completion item type.
java/src/generated/java/com/github/copilot/generated/rpc/ModelCapabilitiesSupports.java	Extends generated supports record (adaptive thinking).
java/src/generated/java/com/github/copilot/generated/rpc/ModelCapabilitiesOverrideSupports.java	Extends generated override supports record (adaptive thinking).
java/src/generated/java/com/github/copilot/generated/rpc/AdaptiveThinkingSupport.java	Adds generated adaptive thinking support enum.
java/src/generated/java/com/github/copilot/generated/AssistantMessageEvent.java	Extends assistant message event data (reasoning wire field).
java/scripts/codegen/package.json	Updates Java codegen dependency to @github/copilot@^1.0.66.
java/scripts/codegen/package-lock.json	Updates Java codegen lockfile to @github/copilot@1.0.66.
java/README.md	Documents Java session limits usage and related events.
go/zsession_events.go	Updates Go top-level session events re-exports for regenerated limit-related types.
go/types.go	Adds SessionLimits to create/resume configs and forwards it on requests; adds update request type.
go/session.go	Adds SetSessionLimits helper issuing session.options.update.
go/rpc/zsession_events.go	Regenerates Go RPC session events (new types + constants for limits/usage checkpoint/exhaustion).
go/rpc/zsession_encoding.go	Updates event decoding to include new limits-related events and remove old response-limits event.
go/rpc/zrpc.go	Regenerates Go RPC types (limits config, completions API, handlePendingSessionLimitsExhausted, etc.).
go/rpc/zrpc_encoding.go	Regenerates Go RPC JSON encoding/decoding to include new/renamed fields.
go/README.md	Documents Go session limits usage and related events.
go/client.go	Forwards SessionLimits in create/resume requests.
go/client_test.go	Adds Go tests for set/clear behavior and create/resume request JSON serialization.
dotnet/test/Unit/SerializationTests.cs	Adds .NET serialization tests for session limits set + omit behavior.
dotnet/test/Unit/CloneTests.cs	Ensures session config cloning copies SessionLimits.
dotnet/test/Unit/ClientSessionLifetimeTests.cs	Adds .NET tests for limits update/clear flows via high-level and generated RPC APIs.
dotnet/src/Types.cs	Adds ISessionLimitsApi + SessionLimits property on config base types.
dotnet/src/Session.cs	Implements Limits API and explicit-null request type + JSON context registration.
dotnet/src/Client.cs	Forwards SessionLimits into create/resume requests and registers type for serialization.
dotnet/README.md	Documents .NET session limits usage and related events.
docs/features/streaming-events.md	Documents new streaming events: usage checkpoint, session limits changed, and limits exhaustion requested/completed.

Review details

Files not reviewed (7)

• go/rpc/zrpc.go: Generated file
• go/rpc/zrpc_encoding.go: Generated file
• go/rpc/zsession_encoding.go: Generated file
• go/rpc/zsession_events.go: Generated file
• go/zsession_events.go: Generated file
• java/scripts/codegen/package-lock.json: Generated file
• nodejs/package-lock.json: Generated file

• Files reviewed: 45/92 changed files
• Comments generated: 2
• Review effort level: Low

[stephentoub]

Thanks, @szabta89. I left some comments on the .NET implementation, but they extend to all six. Essentially:

• This PR shouldn't be touching the autogenerated rpc and session event files
• The main contribution I think should be the additional properties on the session creation/resume options bags.
• I question whether we actually need new "high-level" surface area for this (e.g. session.Limits.SetLimitsAsync) or for modification intrasession can just rely on the RPC surface area (e.g. session.Rpc.Options.UpdateAsync).

[szabta89]

Thanks, @szabta89. I left some comments on the .NET implementation, but they extend to all six. Essentially:

* This PR shouldn't be touching the autogenerated rpc and session event files

* The main contribution I think should be the additional properties on the session creation/resume options bags.

* I question whether we actually need new "high-level" surface area for this (e.g. session.Limits.SetLimitsAsync) or for modification intrasession can just rely on the RPC surface area (e.g. session.Rpc.Options.UpdateAsync).

Thanks, I am gonna take a look at these. You mentioned a couple seemingly unrelated things ending up in this PR. They seem to be collateral schema-regeneration output from @github/copilot@1.0.66. What is the right approach to handle these? That schema includes session limits, but also other runtime schema additions such as the session.completions API and adaptive-thinking support. So these are unrelated to session limits semantically, but they came from the same schema refresh.

[github-actions]

Generated by SDK Consistency Review Agent for issue #1856 · sonnet46 2.6M

[stephentoub]

What is the right approach to handle these?

I'll get 1.0.66 imported now. (I thought I already did, but apparently not.)

[szabta89]

Update on this PR: I reset the branch onto current main after #1865 landed, so the previous generated-code and high-level API changes are no longer part of this diff. The PR is now intentionally scoped to a docs/tests follow-up only:

• Adds a session-limits feature guide with create/resume examples across SDKs.
• Documents the generated session-limit budget events in the streaming events reference.
• Adds focused Node and Go coverage for the generated budget event surface.

I resolved the old review threads because they were all attached to outdated code that was removed by the reset.

[github-actions]

Generated by SDK Consistency Review Agent for issue #1856 · sonnet46 3M

[github-actions]

Cross-SDK consistency review

Overall this PR is in good shape. The documentation guide covers all six SDKs with correct API examples, follows the docs style guide (sentence-case headings, consecutive <details> blocks, <!-- docs-validate: skip --> markers), and the streaming-events reference entries are consistent with the generated type shapes.

API examples verified ✅

Every language example was cross-checked against the actual implementation:

Language	SessionLimitsConfig field	Correct
TypeScript	sessionLimits: { maxAiCredits: 30 }	✅
Python	session_limits={"max_ai_credits": 30}	✅
Go	SessionLimits: &rpc.SessionLimitsConfig{ MaxAiCredits: copilot.Float64(30) }	✅
.NET	SessionLimits = new SessionLimitsConfig { MaxAiCredits = 30 }	✅
Java	setSessionLimits(new SessionLimitsConfig(30.0))	✅ (record with Double maxAiCredits)
Rust	SessionLimitsConfig { max_ai_credits: Some(30.0) }	✅

Minor consistency gap: unit test coverage

The PR adds focused event-type tests for Node.js (session-event-types.test.ts) and Go (session_event_serialization_test.go), which is great. However, the four new event types (session.session_limits_changed, session.usage_checkpoint, session_limits_exhausted.requested, session_limits_exhausted.completed) are not yet covered in the equivalent unit test files for the other four SDKs:

SDK	Test file	Has new event coverage?
Java	SessionEventDeserializationTest.java + GeneratedEventTypesCoverageTest.java	❌ not yet
.NET	SessionEventSerializationTests.cs	❌ not yet
Python	test_rpc_generated.py	❌ not yet
Rust	session_test.rs / api_types_test.rs	❌ not yet

This isn't blocking – the implementation is already validated through e2e tests for all SDKs – but the documented event surface would be more consistently backed by unit-level deserialization tests across all languages. Happy to see that tracked as a follow-up if preferred.

Generated by SDK Consistency Review Agent for issue #1856 · sonnet46 2.9M · ◷

[github-actions]

Generated by SDK Consistency Review Agent for issue #1856 · sonnet46 2.9M

[szabta89]

Removed the Node and Go test changes and rebuilt the branch on current main as a docs-only PR. The remaining diff is limited to the session-limits guide, docs index links, and streaming event reference updates.