feat: add session limits support

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Author: szabta89

docs/features/streaming-events.md

@@ -472,6 +472,29 @@ Ephemeral. Context window utilization snapshot.
 | `currentTokens` | `number` | ✅ | Current tokens in the context window |
 | `messagesLength` | `number` | ✅ | Current message count in the conversation |
 
+### `session.usage_checkpoint`
+
+Durable usage checkpoint for reconstructing aggregate session accounting on resume.
+
+| Data Field | Type | Required | Description |
+|------------|------|----------|-------------|
+| `totalNanoAiu` | `number` | ✅ | Session-wide accumulated nano-AI units cost at checkpoint time |
+| `totalPremiumRequests` | `number` | | Total premium API requests used at checkpoint time |
+
+### `session.session_limits_changed`
+
+Emitted when session limits are set, changed, or cleared.
+
+| Data Field | Type | Required | Description |
+|------------|------|----------|-------------|
+| `sessionLimits` | `SessionLimitsConfig \| null` | ✅ | Current session limits, or `null` when no limits are active |
+
+**`SessionLimitsConfig` fields:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `maxAiCredits` | `number` | | Maximum AI Credits allowed across the session's current accounting window |
+
 ### `session.task_complete`
 
 The agent has completed its assigned task.
@@ -550,6 +573,33 @@ Ephemeral. A user input request was resolved.
 |------------|------|----------|-------------|
 | `requestId` | `string` | ✅ | Matches the corresponding `user_input.requested` |
 
+### `session_limits_exhausted.requested`
+
+Ephemeral. The session's AI Credits budget is exhausted and the runtime needs a decision before continuing the blocked model request.
+
+| Data Field | Type | Required | Description |
+|------------|------|----------|-------------|
+| `requestId` | `string` | ✅ | Use this to respond via `session.ui.handlePendingSessionLimitsExhausted()` |
+| `maxAiCredits` | `number` | ✅ | Configured max AI Credits for the current accounting window |
+| `usedAiCredits` | `number` | ✅ | AI Credits already consumed in the current accounting window |
+
+### `session_limits_exhausted.completed`
+
+Ephemeral. A session limit exhaustion request was resolved.
+
+| Data Field | Type | Required | Description |
+|------------|------|----------|-------------|
+| `requestId` | `string` | ✅ | Matches the corresponding `session_limits_exhausted.requested` |
+| `response` | `SessionLimitsExhaustedResponse` | ✅ | User-selected action for the exhausted limit |
+
+**`SessionLimitsExhaustedResponse` fields:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `action` | `"add" \| "set" \| "unset" \| "cancel"` | ✅ | How to handle the exhausted session limit |
+| `additionalAiCredits` | `number` | | AI Credits to add to the current max when `action` is `"add"` |
+| `maxAiCredits` | `number` | | New absolute max AI Credits when `action` is `"set"` |
+
 ### `elicitation.requested`
 
 Ephemeral. The agent needs structured form input from the user (MCP elicitation protocol).
@@ -773,12 +823,16 @@ session.idle                  → Ready for next message (ephemeral)
 | `session.title_changed` | ✅ | Session | `title` |
 | `session.context_changed` | | Session | `cwd`, `gitRoot?`, `repository?`, `branch?` |
 | `session.usage_info` | ✅ | Session | `tokenLimit`, `currentTokens`, `messagesLength` |
+| `session.usage_checkpoint` | | Session | `totalNanoAiu`, `totalPremiumRequests?` |
+| `session.session_limits_changed` | | Session | `sessionLimits` |
 | `session.task_complete` | | Session | `summary?` |
 | `session.shutdown` | | Session | `shutdownType`, `codeChanges`, `modelMetrics` |
 | `permission.requested` | ✅ | Permission | `requestId`, `permissionRequest` |
 | `permission.completed` | ✅ | Permission | `requestId`, `result.kind` |
 | `user_input.requested` | ✅ | User Input | `requestId`, `question`, `choices?` |
 | `user_input.completed` | ✅ | User Input | `requestId` |
+| `session_limits_exhausted.requested` | ✅ | User Input | `requestId`, `maxAiCredits`, `usedAiCredits` |
+| `session_limits_exhausted.completed` | ✅ | User Input | `requestId`, `response` |
 | `elicitation.requested` | ✅ | User Input | `requestId`, `message`, `requestedSchema` |
 | `elicitation.completed` | ✅ | User Input | `requestId` |
 | `subagent.started` | | Sub-Agent | `toolCallId`, `agentName`, `agentDisplayName` |

dotnet/README.md

@@ -125,6 +125,7 @@ Create a new conversation session.
 - `Provider` - Custom API provider configuration (BYOK)
 - `Streaming` - Enable streaming of response chunks (default: false)
 - `InfiniteSessions` - Configure automatic context compaction (see below)
+- `SessionLimits` - Configure an AI credit budget for the session (see below)
 - `OnPermissionRequest` - Optional handler called before each tool execution to approve or deny it. When omitted, permission requests are emitted as events and left pending for manual resolution. Use `PermissionHandler.ApproveAll` to allow everything, or provide a custom function for fine-grained control. See [Permission Handling](#permission-handling) section.
 - `OnUserInputRequest` - Handler for user input requests from the agent (enables ask_user tool). See [User Input Requests](#user-input-requests) section.
 - `Hooks` - Hook handlers for session lifecycle events. See [Session Hooks](#session-hooks) section.
@@ -136,6 +137,7 @@ Resume an existing session. Returns the session with `WorkspacePath` populated i
 **ResumeSessionConfig:**
 
 - `OnPermissionRequest` - Optional handler called before each tool execution to approve or deny it. See [Permission Handling](#permission-handling) section.
+- `SessionLimits` - Configure an AI credit budget for the resumed session.
 
 ##### `PingAsync(string? message = null): Task<PingResponse>`
 
@@ -431,6 +433,23 @@ var session = await client.CreateSessionAsync(new SessionConfig
 
 When `Memory` is left unset, no memory configuration is sent and the runtime default applies. In the default `CopilotClientMode.CopilotCli` the SDK leaves `Memory` unset so the runtime applies its own default, while `CopilotClientMode.Empty` defaults `Memory` to disabled unless you set it explicitly.
 
+## Session Limits
+
+Set an AI credit budget when creating or resuming a session, then update it later through the session limits API. Pass `null` to clear the current limit.
+
+```csharp
+var session = await client.CreateSessionAsync(new SessionConfig
+{
+    Model = "gpt-5",
+    SessionLimits = new SessionLimitsConfig { MaxAiCredits = 10 }
+});
+
+await session.Limits.SetLimitsAsync(new SessionLimitsConfig { MaxAiCredits = 20 });
+await session.Limits.SetLimitsAsync(null);
+```
+
+The runtime emits limit-related events such as `SessionUsageCheckpointEvent`, `SessionSessionLimitsChangedEvent`, `SessionLimitsExhaustedRequestedEvent`, and `SessionLimitsExhaustedCompletedEvent`.
+
 ## Advanced Usage
 
 ### Manual Server Control

dotnet/src/Client.cs

@@ -1026,6 +1026,7 @@ public async Task<CopilotSession> CreateSessionAsync(SessionConfig config, Cance
                 PluginDirectories: config.PluginDirectories,
                 LargeOutput: config.LargeOutput,
                 Memory: config.Memory,
+                SessionLimits: config.SessionLimits,
                 Canvases: config.Canvases,
                 RequestCanvasRenderer: config.RequestCanvasRenderer,
                 RequestExtensions: config.RequestExtensions,
@@ -1236,6 +1237,7 @@ public async Task<CopilotSession> ResumeSessionAsync(string sessionId, ResumeSes
                 PluginDirectories: config.PluginDirectories,
                 LargeOutput: config.LargeOutput,
                 Memory: config.Memory,
+                SessionLimits: config.SessionLimits,
                 Canvases: config.Canvases,
                 RequestCanvasRenderer: config.RequestCanvasRenderer,
                 RequestExtensions: config.RequestExtensions,
@@ -2477,6 +2479,7 @@ internal record CreateSessionRequest(
         IList<string>? PluginDirectories = null,
         LargeToolOutputConfig? LargeOutput = null,
         MemoryConfiguration? Memory = null,
+        SessionLimitsConfig? SessionLimits = null,
 #pragma warning disable GHCP001
         IList<CanvasDeclaration>? Canvases = null,
         bool? RequestCanvasRenderer = null,
@@ -2572,6 +2575,7 @@ internal record ResumeSessionRequest(
         IList<string>? PluginDirectories = null,
         LargeToolOutputConfig? LargeOutput = null,
         MemoryConfiguration? Memory = null,
+        SessionLimitsConfig? SessionLimits = null,
 #pragma warning disable GHCP001
         IList<CanvasDeclaration>? Canvases = null,
         bool? RequestCanvasRenderer = null,
@@ -2658,6 +2662,7 @@ internal record HooksInvokeResponse(
     [JsonSerializable(typeof(ModelCapabilitiesOverride))]
     [JsonSerializable(typeof(ProviderConfig))]
     [JsonSerializable(typeof(CapiSessionOptions))]
+    [JsonSerializable(typeof(SessionLimitsConfig))]
     [JsonSerializable(typeof(NamedProviderConfig))]
     [JsonSerializable(typeof(ProviderModelConfig))]
     [JsonSerializable(typeof(ResumeSessionRequest))]