Merge main to remove duplicate README churn

The Python README formatting now exists on main independently, so merge the updated base to keep it out of this PR's effective diff.

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

Author: Copilot

.github/copilot-instructions.md

@@ -24,7 +24,7 @@
   - Format all: `just format` | Lint all: `just lint` | Test all: `just test`
 - Per-language:
   - Node: `cd nodejs && npm ci` → `npm test` (Vitest), `npm run generate:session-types` to regenerate session-event types
-  - Python: `cd python && uv pip install -e ".[dev]"` → `uv run pytest` (E2E tests use the test harness)
+  - Python: `cd python && uv pip install -e . --group dev` → `uv run pytest` (E2E tests use the test harness)
   - Go: `cd go && go test ./...`
   - .NET: `cd dotnet && dotnet test test/GitHub.Copilot.SDK.Test.csproj`
   - **.NET testing note:** Never add `InternalsVisibleTo` to any project file when writing tests. Tests must only access public APIs.

.github/workflows/sdk-consistency-review.lock.yml

@@ -79,12 +79,19 @@ When a pull request modifies any SDK client code, review it to ensure:
 
 ## Review Process
 
-1. **Identify the changed SDK(s)**: Determine which language implementation(s) are modified in this PR
-2. **Analyze the changes**: Understand what feature/fix is being implemented
-3. **Cross-reference other SDKs**: Check if the equivalent functionality exists in other language implementations:
+1. **Get the authoritative PR delta**:
+   - Call `pull_request_read` with `method: get_files` for the PR, paginating until all changed files are retrieved
+   - Call `pull_request_read` with `method: get_diff` for the PR
+   - Treat these GitHub API responses as the only authoritative source of which changes belong to the PR, including when the PR head is a merge commit
+   - Base every claim about what the PR adds or modifies on the API diff; use the local checkout only for surrounding context and cross-SDK comparison
+   - Never infer the PR base from `HEAD^`, merge-parent ordering, recent commits, or local branch refs
+   - If the API file list or diff cannot be retrieved, call `missing_data` and stop; do not substitute an inferred local `git diff` range
+2. **Identify the changed SDK(s)**: Determine which language implementation(s) are modified in the authoritative PR delta
+3. **Analyze the changes**: Understand what feature/fix is being implemented from the authoritative PR delta
+4. **Cross-reference other SDKs**: Check if the equivalent functionality exists in other language implementations:
    - Read the corresponding files in other SDK directories
    - Compare method signatures, behavior, and documentation
-4. **Report findings**: If inconsistencies are found:
+5. **Report findings**: If inconsistencies are found:
    - Use `create-pull-request-review-comment` to add inline comments on specific lines where changes should be made
    - Use `add-comment` to provide a summary of cross-SDK consistency findings
    - Be specific about which SDKs need updates and what changes would bring them into alignment

.github/workflows/sdk-consistency-review.md

@@ -25,6 +25,7 @@
   "[go]": {
     "editor.defaultFormatter": "golang.go"
   },
+  "java.autobuild.enabled": false,
   "java.configuration.updateBuildConfiguration": "automatic",
   "java.compile.nullAnalysis.mode": "automatic"
 }

.vscode/settings.json

@@ -50,7 +50,7 @@ This is a multi-language SDK repository. Install the tools for the SDK(s) you pl
 
 1. Install [Python 3.8+](https://www.python.org/downloads/)
 1. Install [uv](https://github.com/astral-sh/uv)
-1. Install dependencies: `cd python && uv pip install -e ".[dev]"`
+1. Install dependencies: `cd python && uv pip install -e . --group dev`
 
 ### Go SDK
 

CONTRIBUTING.md

@@ -7,15 +7,15 @@ BYOK allows you to use the Copilot SDK with your own API keys from model provide
 | Provider | Type Value | Notes |
 |----------|------------|-------|
 | OpenAI | `"openai"` | OpenAI API and OpenAI-compatible endpoints |
-| Azure OpenAI / Azure AI Foundry | `"azure"` | Azure-hosted models |
+| Microsoft Foundry / Azure OpenAI | `"openai"` or `"azure"` | Use `"openai"` for `/openai/v1/`; use `"azure"` for native Azure endpoints |
 | Anthropic | `"anthropic"` | Claude models |
 | Ollama | `"openai"` | Local models via OpenAI-compatible API |
 | Microsoft Foundry Local | `"openai"` | Run AI models locally on your device via OpenAI-compatible API |
 | Other OpenAI-compatible | `"openai"` | vLLM, LiteLLM, etc. |
 
-## Quick start: Azure AI Foundry
+## Quick start: Microsoft Foundry
 
-Azure AI Foundry (formerly Azure OpenAI) is a common BYOK deployment target for enterprises. Here's a complete example:
+Microsoft Foundry is a common BYOK deployment target for enterprises. Here's a complete example:
 
 <details open>
 <summary><strong>Python</strong></summary>
@@ -260,9 +260,9 @@ provider: {
 }
 ```
 
-### Azure AI Foundry (OpenAI-compatible endpoint)
+### Microsoft Foundry (OpenAI-compatible endpoint)
 
-For Azure AI Foundry deployments with `/openai/v1/` endpoints, use `type: "openai"`:
+For Microsoft Foundry deployments with `/openai/v1/` endpoints, use `type: "openai"`:
 
 ```typescript
 provider: {
@@ -493,14 +493,6 @@ Results are cached after the first call, just like the default behavior. The han
 
 ## Limitations
 
-When using BYOK, be aware of these limitations:
-
-### Identity limitations
-
-BYOK authentication uses **static credentials only**.
-
-You must use an API key or static bearer token that you manage yourself.
-
 ### Feature limitations
 
 Some Copilot features may behave differently with BYOK:
@@ -514,9 +506,8 @@ Some Copilot features may behave differently with BYOK:
 
 | Provider | Limitations |
 |----------|-------------|
-| Azure AI Foundry | No Entra ID auth; must use API keys |
-| Ollama | No API key; local only; model support varies |
 | [Microsoft Foundry Local](https://foundrylocal.ai) | Local only; model availability depends on device hardware; no API key required |
+| Ollama | No API key; local only; model support varies |
 | OpenAI | Subject to OpenAI rate limits and quotas |
 
 ## Troubleshooting
@@ -571,7 +562,7 @@ provider: {
 }
 ```
 
-However, if your Azure AI Foundry deployment provides an OpenAI-compatible endpoint path (e.g., `/openai/v1/`), use `type: "openai"`:
+However, if your Microsoft Foundry deployment provides an OpenAI-compatible endpoint path (for example, `/openai/v1/`), use `type: "openai"`:
 
 <!-- docs-validate: hidden -->
 ```typescript
@@ -589,7 +580,7 @@ const session = await client.createSession({
 <!-- /docs-validate: hidden -->
 
 ```typescript
-// ✅ Correct: OpenAI-compatible Azure AI Foundry endpoint
+// ✅ Correct: OpenAI-compatible Microsoft Foundry endpoint
 provider: {
     type: "openai",
     baseUrl: "https://your-resource.openai.azure.com/openai/v1/",

docs/auth/byok.md

@@ -445,9 +445,9 @@ Sub-agent-originated session events share the parent session stream and include
 | Event | Emitted when | Data |
 |-------|-------------|------|
 | `subagent.selected` | Runtime selects an agent for the task | `agentName`, `agentDisplayName`, `tools` |
-| `subagent.started` | Sub-agent begins execution | `toolCallId`, `agentName`, `agentDisplayName`, `agentDescription` |
-| `subagent.completed` | Sub-agent finishes successfully | `toolCallId`, `agentName`, `agentDisplayName` |
-| `subagent.failed` | Sub-agent encounters an error | `toolCallId`, `agentName`, `agentDisplayName`, `error` |
+| `subagent.started` | Sub-agent begins execution | `toolCallId`, `agentName`, `agentDisplayName`, `agentDescription`, `model?` |
+| `subagent.completed` | Sub-agent finishes successfully | `toolCallId`, `agentName`, `agentDisplayName`, `model?`, `durationMs?`, `totalTokens?`, `totalToolCalls?` |
+| `subagent.failed` | Sub-agent encounters an error | `toolCallId`, `agentName`, `agentDisplayName`, `error`, `model?`, `durationMs?`, `totalTokens?`, `totalToolCalls?` |
 | `subagent.deselected` | Runtime switches away from the sub-agent |—|
 
 ### Subscribing to events
@@ -466,11 +466,15 @@ session.on((event) => {
 
         case "subagent.completed":
             console.log(`✅ Sub-agent completed: ${event.data.agentDisplayName}`);
+            if (event.data.durationMs !== undefined) console.log(`  Duration: ${event.data.durationMs}ms`);
+            if (event.data.totalTokens !== undefined) console.log(`  Tokens: ${event.data.totalTokens}`);
+            if (event.data.totalToolCalls !== undefined) console.log(`  Tool calls: ${event.data.totalToolCalls}`);
             break;
 
         case "subagent.failed":
             console.log(`❌ Sub-agent failed: ${event.data.agentDisplayName}`);
             console.log(`  Error: ${event.data.error}`);
+            if (event.data.durationMs !== undefined) console.log(`  Duration: ${event.data.durationMs}ms`);
             break;
 
         case "subagent.selected":

docs/features/custom-agents.md

@@ -176,7 +176,7 @@ Native typed bindings for fleet mode were verified in Node.js/TypeScript, Python
 Plan-mode UIs can start fleet deployment by returning the `autopilot_fleet` exit action. The generated session event types describe it as:
 
 ```typescript
-type PlanModeExitAction =
+type ExitPlanModeAction =
   | "exit_only"
   | "interactive"
   | "autopilot"

docs/features/fleet-mode.md

@@ -131,7 +131,7 @@ let limits = SessionLimitsConfig {
 
 let session = client
     .create_session(
-        SessionConfig::new()
+        SessionConfig::default()
             .approve_all_permissions()
             .with_session_limits(limits.clone()),
     )

docs/features/session-limits.md

@@ -443,12 +443,20 @@ Ephemeral. Token usage and cost information for an individual API call.
 | `model` | `string` | ✅ | Model identifier (e.g., `"gpt-5.4"`) |
 | `inputTokens` | `number` | | Input tokens consumed |
 | `outputTokens` | `number` | | Output tokens produced |
+| `reasoningTokens` | `number` | | Output tokens used for reasoning/chain-of-thought (subset of `outputTokens`) |
 | `cacheReadTokens` | `number` | | Tokens read from prompt cache |
 | `cacheWriteTokens` | `number` | | Tokens written to prompt cache |
+| `cacheExpiresAt` | `string` | | ISO 8601 timestamp when the prompt cache for this model call expires |
+| `contentFilterTriggered` | `boolean` | | Whether the response was blocked or truncated by content filtering (`finish_reason === 'content_filter'`) |
+| `finishReason` | `string` | | Model finish reason (e.g., `"stop"`, `"length"`, `"tool_calls"`, `"content_filter"`) |
 | `cost` | `number` | | Model multiplier cost for billing |
 | `duration` | `number` | | API call duration in milliseconds |
+| `timeToFirstTokenMs` | `number` | | Time from request dispatch to first token received (streaming latency) |
+| `interTokenLatencyMs` | `number` | | Average latency between consecutive tokens (streaming throughput) |
+| `reasoningEffort` | `string` | | Reasoning effort level used for this call (e.g., `"low"`, `"medium"`, `"high"`) |
 | `initiator` | `string` | | What triggered this call (e.g., `"sub-agent"`); absent for user-initiated |
 | `apiCallId` | `string` | | Completion ID from the provider (e.g., `chatcmpl-abc123`) |
+| `serviceRequestId` | `string` | | Copilot service request ID (`x-copilot-service-request-id`) for CAPI log correlation |
 | `apiEndpoint` | `"/chat/completions" \| "/v1/messages" \| "/responses" \| "ws:/responses"` | | API endpoint used for the model call; useful for observability and cost attribution. `ws:/responses` is the websocket variant of the responses API |
 | `providerCallId` | `string` | | GitHub request tracing ID (`x-github-request-id`) |
 | `parentToolCallId` | `string` | | Deprecated. Use envelope-level `agentId` for sub-agent attribution |
@@ -733,6 +741,7 @@ A custom agent was invoked as a sub-agent.
 | `agentName` | `string` | ✅ | Internal name of the sub-agent |
 | `agentDisplayName` | `string` | ✅ | Human-readable display name |
 | `agentDescription` | `string` | ✅ | Description of what the sub-agent does |
+| `model` | `string` | | Model the sub-agent will run with, when known at start |
 
 ### `subagent.completed`
 
@@ -743,6 +752,10 @@ A sub-agent finished successfully.
 | `toolCallId` | `string` | ✅ | Matches the corresponding `subagent.started` |
 | `agentName` | `string` | ✅ | Internal name |
 | `agentDisplayName` | `string` | ✅ | Display name |
+| `model` | `string` | | Model used by the sub-agent |
+| `durationMs` | `number` | | Wall-clock execution duration in milliseconds |
+| `totalTokens` | `number` | | Total input and output tokens consumed |
+| `totalToolCalls` | `number` | | Total tool calls made |
 
 ### `subagent.failed`
 
@@ -754,6 +767,10 @@ A sub-agent encountered an error.
 | `agentName` | `string` | ✅ | Internal name |
 | `agentDisplayName` | `string` | ✅ | Display name |
 | `error` | `string` | ✅ | Error message |
+| `model` | `string` | | Model selected for the sub-agent, when known |
+| `durationMs` | `number` | | Wall-clock execution duration in milliseconds |
+| `totalTokens` | `number` | | Total input and output tokens consumed before failure |
+| `totalToolCalls` | `number` | | Total tool calls made before failure |
 
 ### `subagent.selected`
 
@@ -958,9 +975,9 @@ This table lists key `data` payload fields. Common envelope fields are documente
 | `user_input.completed` | ✅ | User Input | `requestId` |
 | `elicitation.requested` | ✅ | User Input | `requestId`, `message`, `requestedSchema` |
 | `elicitation.completed` | ✅ | User Input | `requestId` |
-| `subagent.started` | | Sub-Agent | `toolCallId`, `agentName`, `agentDisplayName` |
-| `subagent.completed` | | Sub-Agent | `toolCallId`, `agentName`, `agentDisplayName` |
-| `subagent.failed` | | Sub-Agent | `toolCallId`, `agentName`, `error` |
+| `subagent.started` | | Sub-Agent | `toolCallId`, `agentName`, `agentDisplayName`, `model?` |
+| `subagent.completed` | | Sub-Agent | `toolCallId`, `agentName`, `agentDisplayName`, `model?`, `durationMs?`, `totalTokens?`, `totalToolCalls?` |
+| `subagent.failed` | | Sub-Agent | `toolCallId`, `agentName`, `error`, `model?`, `durationMs?`, `totalTokens?`, `totalToolCalls?` |
 | `subagent.selected` | | Sub-Agent | `agentName`, `agentDisplayName`, `tools` |
 | `subagent.deselected` | | Sub-Agent | *(empty)* |
 | `skill.invoked` | | Skill | `name`, `path`, `content`, `allowedTools?` |