Skip to content

Commit 621d955

Browse files
docs-botgithub-actions[bot]sunbryeCopilot
authored
Sync Copilot SDK docs (auto-generated) (#62025)
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: sunbrye <sunbrye@github.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
1 parent d5ab360 commit 621d955

7 files changed

Lines changed: 243 additions & 17 deletions

File tree

‎assets/images/help/copilot/copilot-sdk/features-agent-loop-diagram-1.png‎

-12 Bytes
Loading

‎assets/images/help/copilot/copilot-sdk/features-agent-loop-diagram-2.png‎

-17 Bytes
Loading

‎content/copilot/how-tos/copilot-sdk/features/hooks.md‎

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1028,16 +1028,16 @@ const session = await client.createSession({
10281028

10291029
For full type definitions, input/output field tables, and additional examples for every hook, see the API reference:
10301030

1031-
- [AUTOTITLE](/copilot/how-tos/copilot-sdk/hooks/hooks-overview)
1032-
- [AUTOTITLE](/copilot/how-tos/copilot-sdk/hooks/pre-tool-use)
1033-
- [AUTOTITLE](/copilot/how-tos/copilot-sdk/hooks/post-tool-use)
1034-
- [AUTOTITLE](/copilot/how-tos/copilot-sdk/hooks/user-prompt-submitted)
1035-
- [AUTOTITLE](/copilot/how-tos/copilot-sdk/hooks/session-lifecycle)
1036-
- [AUTOTITLE](/copilot/how-tos/copilot-sdk/hooks/error-handling)
1031+
* [AUTOTITLE](/copilot/how-tos/copilot-sdk/hooks/hooks-overview)
1032+
* [AUTOTITLE](/copilot/how-tos/copilot-sdk/hooks/pre-tool-use)
1033+
* [AUTOTITLE](/copilot/how-tos/copilot-sdk/hooks/post-tool-use)
1034+
* [AUTOTITLE](/copilot/how-tos/copilot-sdk/hooks/user-prompt-submitted)
1035+
* [AUTOTITLE](/copilot/how-tos/copilot-sdk/hooks/session-lifecycle)
1036+
* [AUTOTITLE](/copilot/how-tos/copilot-sdk/hooks/error-handling)
10371037

10381038
## See also
10391039

1040-
- [AUTOTITLE](/copilot/how-tos/copilot-sdk/getting-started)
1041-
- [AUTOTITLE](/copilot/how-tos/copilot-sdk/features/custom-agents)
1042-
- [AUTOTITLE](/copilot/how-tos/copilot-sdk/features/streaming-events)
1043-
- [AUTOTITLE](/copilot/how-tos/copilot-sdk/troubleshooting/debugging)
1040+
* [AUTOTITLE](/copilot/how-tos/copilot-sdk/getting-started)
1041+
* [AUTOTITLE](/copilot/how-tos/copilot-sdk/features/custom-agents)
1042+
* [AUTOTITLE](/copilot/how-tos/copilot-sdk/features/streaming-events)
1043+
* [AUTOTITLE](/copilot/how-tos/copilot-sdk/troubleshooting/debugging)

‎content/copilot/how-tos/copilot-sdk/features/index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@ children:
2020
- /mcp
2121
- /plugin-directories
2222
- /remote-sessions
23+
- /session-limits
2324
- /session-persistence
2425
- /skills
2526
- /steering-and-queueing

‎content/copilot/how-tos/copilot-sdk/features/session-limits.md‎

Lines changed: 182 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,182 @@
1+
---
2+
title: Session limits
3+
shortTitle: Session limits
4+
intro: >-
5+
Session limits let an application set an AI Credits budget for a Copilot
6+
session. Use `sessionLimits` when creating or resuming a session to set a soft
7+
cap for the current accounting window.
8+
versions:
9+
fpt: '*'
10+
ghec: '*'
11+
contentType: how-tos
12+
---
13+
14+
<!-- markdownlint-disable GHD046 GHD005 -->
15+
<!-- Suppressed: GHD046 (outdated release terminology), GHD005 (hardcoded data variable) -->
16+
17+
## Configure a session limit
18+
19+
Set `maxAiCredits` to the AI Credits soft cap for the session's current accounting window. Usage is checked after model calls return, so one response can exceed the configured value before the runtime blocks the next model call. The SDK forwards this value to the Copilot CLI when it creates or resumes the session.
20+
21+
{% codetabs %}
22+
{% codetab typescript %}
23+
24+
<!-- docs-validate: skip -->
25+
26+
```typescript
27+
const session = await client.createSession({
28+
onPermissionRequest: approveAll,
29+
sessionLimits: {
30+
maxAiCredits: 30,
31+
},
32+
});
33+
34+
const resumed = await client.resumeSession(session.sessionId, {
35+
onPermissionRequest: approveAll,
36+
sessionLimits: {
37+
maxAiCredits: 30,
38+
},
39+
});
40+
```
41+
42+
{% endcodetab %}
43+
{% codetab python %}
44+
45+
<!-- docs-validate: skip -->
46+
47+
```python
48+
session = await client.create_session(
49+
on_permission_request=PermissionHandler.approve_all,
50+
session_limits={
51+
"max_ai_credits": 30,
52+
},
53+
)
54+
55+
resumed = await client.resume_session(
56+
session.session_id,
57+
on_permission_request=PermissionHandler.approve_all,
58+
session_limits={
59+
"max_ai_credits": 30,
60+
},
61+
)
62+
```
63+
64+
{% endcodetab %}
65+
{% codetab go %}
66+
67+
<!-- docs-validate: skip -->
68+
69+
```golang
70+
session, err := client.CreateSession(ctx, &copilot.SessionConfig{
71+
OnPermissionRequest: copilot.PermissionHandler.ApproveAll,
72+
SessionLimits: &rpc.SessionLimitsConfig{
73+
MaxAiCredits: copilot.Float64(30),
74+
},
75+
})
76+
77+
resumed, err := client.ResumeSession(ctx, session.SessionID, &copilot.ResumeSessionConfig{
78+
OnPermissionRequest: copilot.PermissionHandler.ApproveAll,
79+
SessionLimits: &rpc.SessionLimitsConfig{
80+
MaxAiCredits: copilot.Float64(30),
81+
},
82+
})
83+
```
84+
85+
{% endcodetab %}
86+
{% codetab dotnet %}
87+
88+
<!-- docs-validate: skip -->
89+
90+
```csharp
91+
var session = await client.CreateSessionAsync(new SessionConfig
92+
{
93+
OnPermissionRequest = PermissionHandler.ApproveAll,
94+
SessionLimits = new SessionLimitsConfig
95+
{
96+
MaxAiCredits = 30,
97+
},
98+
});
99+
100+
var resumed = await client.ResumeSessionAsync(session.SessionId, new ResumeSessionConfig
101+
{
102+
OnPermissionRequest = PermissionHandler.ApproveAll,
103+
SessionLimits = new SessionLimitsConfig
104+
{
105+
MaxAiCredits = 30,
106+
},
107+
});
108+
```
109+
110+
{% endcodetab %}
111+
{% codetab java %}
112+
113+
<!-- docs-validate: skip -->
114+
115+
```java
116+
CopilotSession session = client
117+
.createSession(new SessionConfig()
118+
.setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
119+
.setSessionLimits(new SessionLimitsConfig(30.0)))
120+
.get();
121+
122+
CopilotSession resumed = client
123+
.resumeSession(session.getSessionId(), new ResumeSessionConfig()
124+
.setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
125+
.setSessionLimits(new SessionLimitsConfig(30.0)))
126+
.get();
127+
```
128+
129+
{% endcodetab %}
130+
{% codetab rust %}
131+
132+
<!-- docs-validate: skip -->
133+
134+
```rust
135+
let limits = SessionLimitsConfig {
136+
max_ai_credits: Some(30.0),
137+
};
138+
139+
let session = client
140+
.create_session(
141+
SessionConfig::new()
142+
.approve_all_permissions()
143+
.with_session_limits(limits.clone()),
144+
)
145+
.await?;
146+
147+
let resumed = client
148+
.resume_session(
149+
ResumeSessionConfig::new(session.id().clone())
150+
.approve_all_permissions()
151+
.with_session_limits(limits),
152+
)
153+
.await?;
154+
```
155+
156+
{% endcodetab %}
157+
{% endcodetabs %}
158+
159+
## Observe budget events
160+
161+
Applications can subscribe to session events to update UI when the soft cap changes or the session reaches the exhausted-budget flow.
162+
163+
| Event type | When it is emitted | Important fields |
164+
|---|---|---|
165+
| `session.session_limits_changed` | Active session limits changed. A `null` `sessionLimits` value means no limits are active. | `sessionLimits.maxAiCredits?` |
166+
| `session.usage_checkpoint` | The runtime records durable aggregate usage for resume and accounting. | `totalNanoAiu`, `totalPremiumRequests?` |
167+
| `session_limits_exhausted.requested` | The session reached the exhausted-budget flow and needs a user decision before continuing. | `requestId`, `maxAiCredits`, `usedAiCredits` |
168+
| `session_limits_exhausted.completed` | The exhausted-limit prompt was resolved. | `requestId`, `response.action`, `response.additionalAiCredits?`, `response.maxAiCredits?` |
169+
170+
Use the generated event types for the SDK language you are using. For example, TypeScript narrows by `event.type`:
171+
172+
```typescript
173+
session.on((event) => {
174+
if (event.type === "session_limits_exhausted.requested") {
175+
showBudgetDialog({
176+
requestId: event.data.requestId,
177+
maxAiCredits: event.data.maxAiCredits,
178+
usedAiCredits: event.data.usedAiCredits,
179+
});
180+
}
181+
});
182+
```

‎content/copilot/how-tos/copilot-sdk/features/streaming-events.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -443,6 +443,24 @@ Ephemeral. Context window utilization snapshot.
443443
| `currentTokens` | `number` | ✅ | Current tokens in the context window |
444444
| `messagesLength` | `number` | ✅ | Current message count in the conversation |
445445

446+
### `session.session_limits_changed`
447+
448+
Session limits changed for the current accounting window. A `null` `sessionLimits` value means no limits are active.
449+
450+
| Data Field | Type | Required | Description |
451+
|------------|------|----------|-------------|
452+
| `sessionLimits` | `SessionLimitsConfig \| null` | ✅ | Current session limits, or `null` when no limits are active |
453+
| `sessionLimits.maxAiCredits` | `number` | | Maximum AI Credits allowed across the session's current accounting window |
454+
455+
### `session.usage_checkpoint`
456+
457+
Durable aggregate usage checkpoint used to reconstruct accounting when a session is resumed.
458+
459+
| Data Field | Type | Required | Description |
460+
|------------|------|----------|-------------|
461+
| `totalNanoAiu` | `number` | ✅ | Session-wide accumulated nano-AI units cost at checkpoint time |
462+
| `totalPremiumRequests` | `number` | | Total number of premium API requests used at checkpoint time |
463+
446464
### `session.task_complete`
447465

448466
The agent has completed its assigned task.
@@ -692,6 +710,27 @@ Ephemeral. A queued command was resolved.
692710
|------------|------|----------|-------------|
693711
| `requestId` | `string` | ✅ | Matches the corresponding `command.queued` |
694712

713+
### `session_limits_exhausted.requested`
714+
715+
Ephemeral. The current session budget was exhausted and the runtime needs a user decision before continuing.
716+
717+
| Data Field | Type | Required | Description |
718+
|------------|------|----------|-------------|
719+
| `requestId` | `string` | ✅ | Use this ID when responding to the pending exhausted-limit request |
720+
| `maxAiCredits` | `number` | ✅ | Configured max AI Credits for the current accounting window |
721+
| `usedAiCredits` | `number` | ✅ | AI Credits already consumed in the current accounting window |
722+
723+
### `session_limits_exhausted.completed`
724+
725+
Ephemeral. A pending exhausted-limit request was resolved.
726+
727+
| Data Field | Type | Required | Description |
728+
|------------|------|----------|-------------|
729+
| `requestId` | `string` | ✅ | Matches the corresponding `session_limits_exhausted.requested` event |
730+
| `response.action` | `"add" \| "set" \| "unset" \| "cancel"` | ✅ | Action selected for the exhausted-limit request |
731+
| `response.additionalAiCredits` | `number` | | AI Credits to add to the current max when `response.action` is `"add"` |
732+
| `response.maxAiCredits` | `number` | | New absolute max AI Credits when `response.action` is `"set"` |
733+
695734
## Quick reference: agentic turn flow
696735

697736
A typical agentic turn emits events in this order:
@@ -744,6 +783,8 @@ session.idle → Ready for next message (ephemeral)
744783
| `session.title_changed` | ✅ | Session | `title` |
745784
| `session.context_changed` | | Session | `cwd`, `gitRoot?`, `repository?`, `branch?` |
746785
| `session.usage_info` | ✅ | Session | `tokenLimit`, `currentTokens`, `messagesLength` |
786+
| `session.session_limits_changed` | | Session | `sessionLimits` |
787+
| `session.usage_checkpoint` | | Session | `totalNanoAiu`, `totalPremiumRequests?` |
747788
| `session.task_complete` | | Session | `summary?` |
748789
| `session.shutdown` | | Session | `shutdownType`, `codeChanges`, `modelMetrics` |
749790
| `permission.requested` | ✅ | Permission | `requestId`, `permissionRequest` |
@@ -765,5 +806,7 @@ session.idle → Ready for next message (ephemeral)
765806
| `external_tool.completed` | ✅ | External Tool | `requestId` |
766807
| `command.queued` | ✅ | Command | `requestId`, `command` |
767808
| `command.completed` | ✅ | Command | `requestId` |
809+
| `session_limits_exhausted.requested` | ✅ | Session | `requestId`, `maxAiCredits`, `usedAiCredits` |
810+
| `session_limits_exhausted.completed` | ✅ | Session | `requestId`, `response.action` |
768811
| `exit_plan_mode.requested` | ✅ | Plan Mode | `requestId`, `summary`, `planContent`, `actions` |
769812
| `exit_plan_mode.completed` | ✅ | Plan Mode | `requestId` |

‎content/copilot/how-tos/copilot-sdk/hooks/post-tool-use.md‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -15,10 +15,10 @@ contentType: how-tos
1515
<!-- markdownlint-disable GHD046 GHD005 -->
1616
<!-- Suppressed: GHD046 (outdated release terminology), GHD005 (hardcoded data variable) -->
1717

18-
- Transform or filter tool results
19-
- Log tool execution for auditing
20-
- Add context based on results
21-
- Suppress results from the conversation
18+
* Transform or filter tool results
19+
* Log tool execution for auditing
20+
* Add context based on results
21+
* Suppress results from the conversation
2222

2323
> **Failure variant** — `onPostToolUse` only fires for successful tool executions. To observe **failed** tool calls, register `onPostToolUseFailure` (`on_post_tool_use_failure` in Python, `OnPostToolUseFailure` in Go/.NET, `on_post_tool_use_failure` in Rust). The handler receives `{ sessionId, toolName, toolArgs, error, timestamp, workingDirectory }` — the `error` field is a string extracted from the tool's failure result — and may return `{ additionalContext: string }` to inject extra guidance for the model (e.g. retry hints). See the [AUTOTITLE](/copilot/how-tos/copilot-sdk/hooks/hooks-overview) for the full list.
2424
> <a id="failure-variant"></a>
@@ -488,6 +488,6 @@ const session = await client.createSession({
488488

489489
## See also
490490

491-
- [AUTOTITLE](/copilot/how-tos/copilot-sdk/hooks)
492-
- [AUTOTITLE](/copilot/how-tos/copilot-sdk/hooks/pre-tool-use)
493-
- [AUTOTITLE](/copilot/how-tos/copilot-sdk/hooks/error-handling)
491+
* [AUTOTITLE](/copilot/how-tos/copilot-sdk/hooks)
492+
* [AUTOTITLE](/copilot/how-tos/copilot-sdk/hooks/pre-tool-use)
493+
* [AUTOTITLE](/copilot/how-tos/copilot-sdk/hooks/error-handling)

0 commit comments

Comments
 (0)