diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
index db0fd0fec5..fff64bcdbe 100644
--- a/.devcontainer/devcontainer.json
+++ b/.devcontainer/devcontainer.json
@@ -3,7 +3,7 @@
{
"name": "Python 3",
// Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile
- "image": "mcr.microsoft.com/devcontainers/python:2-3.14-trixie",
+ "image": "mcr.microsoft.com/devcontainers/python:3-3.14-trixie",
"features": {
"ghcr.io/devcontainers/features/copilot-cli:1": {},
"ghcr.io/devcontainers/features/github-cli:1": {},
diff --git a/.github/agents/docs-maintenance.agent.md b/.github/agents/docs-maintenance.agent.md
index 9b97fecf4d..c5363e3699 100644
--- a/.github/agents/docs-maintenance.agent.md
+++ b/.github/agents/docs-maintenance.agent.md
@@ -122,7 +122,6 @@ Every major SDK feature should be documented. Core features include:
- Client initialization and configuration
- Connection modes (stdio vs TCP)
- Authentication options
-- Auto-start and auto-restart behavior
**Session Management:**
- Creating sessions
@@ -342,7 +341,7 @@ cat nodejs/src/types.ts | grep -A 10 "export interface ExportSessionOptions"
```
**Must match:**
-- `CopilotClient` constructor options: `cliPath`, `cliUrl`, `useStdio`, `port`, `logLevel`, `autoStart`, `autoRestart`, `env`, `githubToken`, `useLoggedInUser`
+- `CopilotClient` constructor options: `cliPath`, `cliUrl`, `useStdio`, `port`, `logLevel`, `autoStart`, `env`, `githubToken`, `useLoggedInUser`
- `createSession()` config: `model`, `tools`, `hooks`, `systemMessage`, `mcpServers`, `availableTools`, `excludedTools`, `streaming`, `reasoningEffort`, `provider`, `infiniteSessions`, `customAgents`, `workingDirectory`
- `CopilotSession` methods: `send()`, `sendAndWait()`, `getMessages()`, `disconnect()`, `abort()`, `on()`, `once()`, `off()`
- Hook names: `onPreToolUse`, `onPostToolUse`, `onUserPromptSubmitted`, `onSessionStart`, `onSessionEnd`, `onErrorOccurred`
@@ -360,7 +359,7 @@ cat python/copilot/types.py | grep -A 15 "class SessionHooks"
```
**Must match (snake_case):**
-- `CopilotClient` options: `cli_path`, `cli_url`, `use_stdio`, `port`, `log_level`, `auto_start`, `auto_restart`, `env`, `github_token`, `use_logged_in_user`
+- `CopilotClient` options: `cli_path`, `cli_url`, `use_stdio`, `port`, `log_level`, `auto_start`, `env`, `github_token`, `use_logged_in_user`
- `create_session()` config keys: `model`, `tools`, `hooks`, `system_message`, `mcp_servers`, `available_tools`, `excluded_tools`, `streaming`, `reasoning_effort`, `provider`, `infinite_sessions`, `custom_agents`, `working_directory`
- `CopilotSession` methods: `send()`, `send_and_wait()`, `get_messages()`, `disconnect()`, `abort()`, `export_session()`
- Hook names: `on_pre_tool_use`, `on_post_tool_use`, `on_user_prompt_submitted`, `on_session_start`, `on_session_end`, `on_error_occurred`
@@ -378,7 +377,7 @@ cat go/types.go | grep -A 15 "type SessionHooks struct"
```
**Must match (PascalCase for exported):**
-- `ClientOptions` fields: `CLIPath`, `CLIUrl`, `UseStdio`, `Port`, `LogLevel`, `AutoStart`, `AutoRestart`, `Env`, `GithubToken`, `UseLoggedInUser`
+- `ClientOptions` fields: `CLIPath`, `CLIUrl`, `UseStdio`, `Port`, `LogLevel`, `AutoStart`, `Env`, `GithubToken`, `UseLoggedInUser`
- `SessionConfig` fields: `Model`, `Tools`, `Hooks`, `SystemMessage`, `MCPServers`, `AvailableTools`, `ExcludedTools`, `Streaming`, `ReasoningEffort`, `Provider`, `InfiniteSessions`, `CustomAgents`, `WorkingDirectory`
- `Session` methods: `Send()`, `SendAndWait()`, `GetMessages()`, `Disconnect()`, `Abort()`, `ExportSession()`
- Hook fields: `OnPreToolUse`, `OnPostToolUse`, `OnUserPromptSubmitted`, `OnSessionStart`, `OnSessionEnd`, `OnErrorOccurred`
@@ -396,7 +395,7 @@ cat dotnet/src/Types.cs | grep -A 15 "public class SessionHooks"
```
**Must match (PascalCase):**
-- `CopilotClientOptions` properties: `CliPath`, `CliUrl`, `UseStdio`, `Port`, `LogLevel`, `AutoStart`, `AutoRestart`, `Environment`, `GithubToken`, `UseLoggedInUser`
+- `CopilotClientOptions` properties: `CliPath`, `CliUrl`, `UseStdio`, `Port`, `LogLevel`, `AutoStart`, `Environment`, `GithubToken`, `UseLoggedInUser`
- `SessionConfig` properties: `Model`, `Tools`, `Hooks`, `SystemMessage`, `McpServers`, `AvailableTools`, `ExcludedTools`, `Streaming`, `ReasoningEffort`, `Provider`, `InfiniteSessions`, `CustomAgents`, `WorkingDirectory`
- `CopilotSession` methods: `SendAsync()`, `SendAndWaitAsync()`, `GetMessagesAsync()`, `DisposeAsync()`, `AbortAsync()`, `ExportSessionAsync()`
- Hook properties: `OnPreToolUse`, `OnPostToolUse`, `OnUserPromptSubmitted`, `OnSessionStart`, `OnSessionEnd`, `OnErrorOccurred`
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index 7c362ab537..0133053997 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -25,6 +25,7 @@
- Python: `cd python && uv pip install -e ".[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.
## Testing & E2E tips ⚙️
diff --git a/.github/workflows/cross-repo-issue-analysis.lock.yml b/.github/workflows/cross-repo-issue-analysis.lock.yml
index c7cd9f4de5..05b2f23cb2 100644
--- a/.github/workflows/cross-repo-issue-analysis.lock.yml
+++ b/.github/workflows/cross-repo-issue-analysis.lock.yml
@@ -13,7 +13,7 @@
# \ /\ / (_) | | | | ( | | | | (_) \ V V /\__ \
# \/ \/ \___/|_| |_|\_\|_| |_|\___/ \_/\_/ |___/
#
-# This file was automatically generated by gh-aw (v0.50.5). DO NOT EDIT.
+# This file was automatically generated by gh-aw (v0.52.1). DO NOT EDIT.
#
# To update this file, edit the corresponding .md file and run:
# gh aw compile
@@ -21,9 +21,9 @@
#
# For more information: https://github.github.com/gh-aw/introduction/overview/
#
-# Analyzes copilot-sdk issues to determine if a fix is needed in copilot-agent-runtime, then opens a linked issue and suggested-fix PR there
+# Analyzes copilot-sdk issues to determine if a fix is needed in copilot-agent-runtime, then opens a linked issue there
#
-# gh-aw-metadata: {"schema_version":"v1","frontmatter_hash":"553bdce55a05e3f846f312d711680323ba79effef8a001bd23cb72c1c0459413","compiler_version":"v0.50.5"}
+# gh-aw-metadata: {"schema_version":"v1","frontmatter_hash":"bbe407b2d324d84d7c6653015841817713551b010318cee1ec12dd5c1c077977","compiler_version":"v0.52.1"}
name: "SDK Runtime Triage"
"on":
@@ -40,7 +40,7 @@ name: "SDK Runtime Triage"
permissions: {}
concurrency:
- group: "gh-aw-${{ github.workflow }}-${{ github.event.issue.number }}"
+ group: "gh-aw-${{ github.workflow }}-${{ github.event.issue.number || github.run_id }}"
run-name: "SDK Runtime Triage"
@@ -56,33 +56,50 @@ jobs:
body: ${{ steps.sanitized.outputs.body }}
comment_id: ""
comment_repo: ""
+ model: ${{ steps.generate_aw_info.outputs.model }}
secret_verification_result: ${{ steps.validate-secret.outputs.verification_result }}
text: ${{ steps.sanitized.outputs.text }}
title: ${{ steps.sanitized.outputs.title }}
steps:
- name: Setup Scripts
- uses: github/gh-aw/actions/setup@a7d371cc7e68f270ded0592942424548e05bf1c2 # v0.50.5
+ uses: github/gh-aw/actions/setup@a86e657586e4ac5f549a790628971ec02f6a4a8f # v0.52.1
with:
destination: /opt/gh-aw/actions
+ - name: Generate agentic run info
+ id: generate_aw_info
+ env:
+ GH_AW_INFO_ENGINE_ID: "copilot"
+ GH_AW_INFO_ENGINE_NAME: "GitHub Copilot CLI"
+ GH_AW_INFO_MODEL: ${{ vars.GH_AW_MODEL_AGENT_COPILOT || '' }}
+ GH_AW_INFO_VERSION: ""
+ GH_AW_INFO_AGENT_VERSION: "0.0.420"
+ GH_AW_INFO_CLI_VERSION: "v0.52.1"
+ GH_AW_INFO_WORKFLOW_NAME: "SDK Runtime Triage"
+ GH_AW_INFO_EXPERIMENTAL: "false"
+ GH_AW_INFO_SUPPORTS_TOOLS_ALLOWLIST: "true"
+ GH_AW_INFO_STAGED: "false"
+ GH_AW_INFO_ALLOWED_DOMAINS: '["defaults"]'
+ GH_AW_INFO_FIREWALL_ENABLED: "true"
+ GH_AW_INFO_AWF_VERSION: "v0.23.0"
+ GH_AW_INFO_AWMG_VERSION: ""
+ GH_AW_INFO_FIREWALL_TYPE: "squid"
+ uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8
+ with:
+ script: |
+ const { main } = require('/opt/gh-aw/actions/generate_aw_info.cjs');
+ await main(core, context);
- name: Validate COPILOT_GITHUB_TOKEN secret
id: validate-secret
run: /opt/gh-aw/actions/validate_multi_secret.sh COPILOT_GITHUB_TOKEN 'GitHub Copilot CLI' https://github.github.com/gh-aw/reference/engines/#github-copilot-default
env:
COPILOT_GITHUB_TOKEN: ${{ secrets.COPILOT_GITHUB_TOKEN }}
- - name: Validate context variables
- uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8
- with:
- script: |
- const { setupGlobals } = require('/opt/gh-aw/actions/setup_globals.cjs');
- setupGlobals(core, github, context, exec, io);
- const { main } = require('/opt/gh-aw/actions/validate_context_variables.cjs');
- await main();
- name: Checkout .github and .agents folders
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
with:
sparse-checkout: |
.github
.agents
+ sparse-checkout-cone-mode: true
fetch-depth: 1
persist-credentials: false
- name: Check workflow file timestamps
@@ -130,10 +147,7 @@ jobs:
cat "/opt/gh-aw/prompts/safe_outputs_prompt.md"
cat << 'GH_AW_PROMPT_EOF'
- Tools: create_issue, create_pull_request, add_labels, missing_tool, missing_data
- GH_AW_PROMPT_EOF
- cat "/opt/gh-aw/prompts/safe_outputs_create_pull_request.md"
- cat << 'GH_AW_PROMPT_EOF'
+ Tools: create_issue, add_labels, missing_tool, missing_data, noop
The following GitHub context information is available for this workflow:
@@ -231,12 +245,14 @@ jobs:
env:
GH_AW_PROMPT: /tmp/gh-aw/aw-prompts/prompt.txt
run: bash /opt/gh-aw/actions/print_prompt_summary.sh
- - name: Upload prompt artifact
+ - name: Upload activation artifact
if: success()
- uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6
+ uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
with:
- name: prompt
- path: /tmp/gh-aw/aw-prompts/prompt.txt
+ name: activation
+ path: |
+ /tmp/gh-aw/aw_info.json
+ /tmp/gh-aw/aw-prompts/prompt.txt
retention-days: 1
agent:
@@ -245,7 +261,6 @@ jobs:
permissions:
contents: read
issues: read
- pull-requests: read
env:
DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
GH_AW_ASSETS_ALLOWED_EXTS: ""
@@ -261,12 +276,13 @@ jobs:
detection_conclusion: ${{ steps.detection_conclusion.outputs.conclusion }}
detection_success: ${{ steps.detection_conclusion.outputs.success }}
has_patch: ${{ steps.collect_output.outputs.has_patch }}
- model: ${{ steps.generate_aw_info.outputs.model }}
+ inference_access_error: ${{ steps.detect-inference-error.outputs.inference_access_error || 'false' }}
+ model: ${{ needs.activation.outputs.model }}
output: ${{ steps.collect_output.outputs.output }}
output_types: ${{ steps.collect_output.outputs.output_types }}
steps:
- name: Setup Scripts
- uses: github/gh-aw/actions/setup@a7d371cc7e68f270ded0592942424548e05bf1c2 # v0.50.5
+ uses: github/gh-aw/actions/setup@a86e657586e4ac5f549a790628971ec02f6a4a8f # v0.52.1
with:
destination: /opt/gh-aw/actions
- name: Checkout repository
@@ -293,7 +309,7 @@ jobs:
- name: Checkout PR branch
id: checkout-pr
if: |
- github.event.pull_request
+ (github.event.pull_request) || (github.event.issue.pull_request)
uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8
env:
GH_TOKEN: ${{ secrets.RUNTIME_TRIAGE_TOKEN }}
@@ -304,52 +320,8 @@ jobs:
setupGlobals(core, github, context, exec, io);
const { main } = require('/opt/gh-aw/actions/checkout_pr_branch.cjs');
await main();
- - name: Generate agentic run info
- id: generate_aw_info
- uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8
- with:
- script: |
- const fs = require('fs');
-
- const awInfo = {
- engine_id: "copilot",
- engine_name: "GitHub Copilot CLI",
- model: process.env.GH_AW_MODEL_AGENT_COPILOT || "",
- version: "",
- agent_version: "0.0.418",
- cli_version: "v0.50.5",
- workflow_name: "SDK Runtime Triage",
- experimental: false,
- supports_tools_allowlist: true,
- run_id: context.runId,
- run_number: context.runNumber,
- run_attempt: process.env.GITHUB_RUN_ATTEMPT,
- repository: context.repo.owner + '/' + context.repo.repo,
- ref: context.ref,
- sha: context.sha,
- actor: context.actor,
- event_name: context.eventName,
- staged: false,
- allowed_domains: ["defaults"],
- firewall_enabled: true,
- awf_version: "v0.23.0",
- awmg_version: "v0.1.5",
- steps: {
- firewall: "squid"
- },
- created_at: new Date().toISOString()
- };
-
- // Write to /tmp/gh-aw directory to avoid inclusion in PR
- const tmpPath = '/tmp/gh-aw/aw_info.json';
- fs.writeFileSync(tmpPath, JSON.stringify(awInfo, null, 2));
- console.log('Generated aw_info.json at:', tmpPath);
- console.log(JSON.stringify(awInfo, null, 2));
-
- // Set model as output for reuse in other steps/jobs
- core.setOutput('model', awInfo.model);
- name: Install GitHub Copilot CLI
- run: /opt/gh-aw/actions/install_copilot_cli.sh 0.0.418
+ run: /opt/gh-aw/actions/install_copilot_cli.sh 0.0.420
- name: Install awf binary
run: bash /opt/gh-aw/actions/install_awf_binary.sh v0.23.0
- name: Determine automatic lockdown mode for GitHub MCP Server
@@ -364,14 +336,14 @@ jobs:
const determineAutomaticLockdown = require('/opt/gh-aw/actions/determine_automatic_lockdown.cjs');
await determineAutomaticLockdown(github, context, core);
- name: Download container images
- run: bash /opt/gh-aw/actions/download_docker_images.sh ghcr.io/github/gh-aw-firewall/agent:0.23.0 ghcr.io/github/gh-aw-firewall/api-proxy:0.23.0 ghcr.io/github/gh-aw-firewall/squid:0.23.0 ghcr.io/github/gh-aw-mcpg:v0.1.5 ghcr.io/github/github-mcp-server:v0.31.0 node:lts-alpine
+ run: bash /opt/gh-aw/actions/download_docker_images.sh ghcr.io/github/gh-aw-firewall/agent:0.23.0 ghcr.io/github/gh-aw-firewall/api-proxy:0.23.0 ghcr.io/github/gh-aw-firewall/squid:0.23.0 ghcr.io/github/gh-aw-mcpg:v0.1.7 ghcr.io/github/github-mcp-server:v0.31.0 node:lts-alpine
- name: Write Safe Outputs Config
run: |
mkdir -p /opt/gh-aw/safeoutputs
mkdir -p /tmp/gh-aw/safeoutputs
mkdir -p /tmp/gh-aw/mcp-logs/safeoutputs
cat > /opt/gh-aw/safeoutputs/config.json << 'GH_AW_SAFE_OUTPUTS_CONFIG_EOF'
- {"add_labels":{"allowed":["runtime","sdk-fix-only","needs-investigation"],"max":3,"target":"triggering"},"create_issue":{"max":1},"create_pull_request":{"max":1},"missing_data":{},"missing_tool":{},"noop":{"max":1}}
+ {"add_labels":{"allowed":["runtime","sdk-fix-only","needs-investigation"],"max":3,"target":"triggering"},"create_issue":{"max":1},"missing_data":{},"missing_tool":{},"noop":{"max":1}}
GH_AW_SAFE_OUTPUTS_CONFIG_EOF
cat > /opt/gh-aw/safeoutputs/tools.json << 'GH_AW_SAFE_OUTPUTS_TOOLS_EOF'
[
@@ -416,43 +388,6 @@ jobs:
},
"name": "create_issue"
},
- {
- "description": "Create a new GitHub pull request to propose code changes. Use this after making file edits to submit them for review and merging. The PR will be created from the current branch with your committed changes. For code review comments on an existing PR, use create_pull_request_review_comment instead. CONSTRAINTS: Maximum 1 pull request(s) can be created. Title will be prefixed with \"[copilot-sdk] \". Labels [upstream-from-sdk ai-suggested-fix] will be automatically added. PRs will be created as drafts.",
- "inputSchema": {
- "additionalProperties": false,
- "properties": {
- "body": {
- "description": "Detailed PR description in Markdown. Include what changes were made, why, testing notes, and any breaking changes. Do NOT repeat the title as a heading.",
- "type": "string"
- },
- "branch": {
- "description": "Source branch name containing the changes. If omitted, uses the current working branch.",
- "type": "string"
- },
- "draft": {
- "description": "Whether to create the PR as a draft. Draft PRs cannot be merged until marked as ready for review. Use mark_pull_request_as_ready_for_review to convert a draft PR. Default: true.",
- "type": "boolean"
- },
- "labels": {
- "description": "Labels to categorize the PR (e.g., 'enhancement', 'bugfix'). Labels must exist in the repository.",
- "items": {
- "type": "string"
- },
- "type": "array"
- },
- "title": {
- "description": "Concise PR title describing the changes. Follow repository conventions (e.g., conventional commits). The title appears as the main heading.",
- "type": "string"
- }
- },
- "required": [
- "title",
- "body"
- ],
- "type": "object"
- },
- "name": "create_pull_request"
- },
{
"description": "Add labels to an existing GitHub issue or pull request for categorization and filtering. Labels must already exist in the repository. For creating new issues with labels, use create_issue with the labels property instead. CONSTRAINTS: Maximum 3 label(s) can be added. Only these labels are allowed: [runtime sdk-fix-only needs-investigation]. Target: triggering.",
"inputSchema": {
@@ -599,42 +534,6 @@ jobs:
}
}
},
- "create_pull_request": {
- "defaultMax": 1,
- "fields": {
- "body": {
- "required": true,
- "type": "string",
- "sanitize": true,
- "maxLength": 65000
- },
- "branch": {
- "required": true,
- "type": "string",
- "sanitize": true,
- "maxLength": 256
- },
- "draft": {
- "type": "boolean"
- },
- "labels": {
- "type": "array",
- "itemType": "string",
- "itemSanitize": true,
- "itemMaxLength": 128
- },
- "repo": {
- "type": "string",
- "maxLength": 256
- },
- "title": {
- "required": true,
- "type": "string",
- "sanitize": true,
- "maxLength": 128
- }
- }
- },
"missing_data": {
"defaultMax": 20,
"fields": {
@@ -752,10 +651,11 @@ jobs:
export MCP_GATEWAY_API_KEY
export MCP_GATEWAY_PAYLOAD_DIR="/tmp/gh-aw/mcp-payloads"
mkdir -p "${MCP_GATEWAY_PAYLOAD_DIR}"
+ export MCP_GATEWAY_PAYLOAD_SIZE_THRESHOLD="524288"
export DEBUG="*"
export GH_AW_ENGINE="copilot"
- export MCP_GATEWAY_DOCKER_COMMAND='docker run -i --rm --network host -v /var/run/docker.sock:/var/run/docker.sock -e MCP_GATEWAY_PORT -e MCP_GATEWAY_DOMAIN -e MCP_GATEWAY_API_KEY -e MCP_GATEWAY_PAYLOAD_DIR -e DEBUG -e MCP_GATEWAY_LOG_DIR -e GH_AW_MCP_LOG_DIR -e GH_AW_SAFE_OUTPUTS -e GH_AW_SAFE_OUTPUTS_CONFIG_PATH -e GH_AW_SAFE_OUTPUTS_TOOLS_PATH -e GH_AW_ASSETS_BRANCH -e GH_AW_ASSETS_MAX_SIZE_KB -e GH_AW_ASSETS_ALLOWED_EXTS -e DEFAULT_BRANCH -e GITHUB_MCP_SERVER_TOKEN -e GITHUB_MCP_LOCKDOWN -e GITHUB_REPOSITORY -e GITHUB_SERVER_URL -e GITHUB_SHA -e GITHUB_WORKSPACE -e GITHUB_TOKEN -e GITHUB_RUN_ID -e GITHUB_RUN_NUMBER -e GITHUB_RUN_ATTEMPT -e GITHUB_JOB -e GITHUB_ACTION -e GITHUB_EVENT_NAME -e GITHUB_EVENT_PATH -e GITHUB_ACTOR -e GITHUB_ACTOR_ID -e GITHUB_TRIGGERING_ACTOR -e GITHUB_WORKFLOW -e GITHUB_WORKFLOW_REF -e GITHUB_WORKFLOW_SHA -e GITHUB_REF -e GITHUB_REF_NAME -e GITHUB_REF_TYPE -e GITHUB_HEAD_REF -e GITHUB_BASE_REF -e GH_AW_SAFE_OUTPUTS_PORT -e GH_AW_SAFE_OUTPUTS_API_KEY -v /tmp/gh-aw/mcp-payloads:/tmp/gh-aw/mcp-payloads:rw -v /opt:/opt:ro -v /tmp:/tmp:rw -v '"${GITHUB_WORKSPACE}"':'"${GITHUB_WORKSPACE}"':rw ghcr.io/github/gh-aw-mcpg:v0.1.5'
+ export MCP_GATEWAY_DOCKER_COMMAND='docker run -i --rm --network host -v /var/run/docker.sock:/var/run/docker.sock -e MCP_GATEWAY_PORT -e MCP_GATEWAY_DOMAIN -e MCP_GATEWAY_API_KEY -e MCP_GATEWAY_PAYLOAD_DIR -e MCP_GATEWAY_PAYLOAD_SIZE_THRESHOLD -e DEBUG -e MCP_GATEWAY_LOG_DIR -e GH_AW_MCP_LOG_DIR -e GH_AW_SAFE_OUTPUTS -e GH_AW_SAFE_OUTPUTS_CONFIG_PATH -e GH_AW_SAFE_OUTPUTS_TOOLS_PATH -e GH_AW_ASSETS_BRANCH -e GH_AW_ASSETS_MAX_SIZE_KB -e GH_AW_ASSETS_ALLOWED_EXTS -e DEFAULT_BRANCH -e GITHUB_MCP_SERVER_TOKEN -e GITHUB_MCP_LOCKDOWN -e GITHUB_REPOSITORY -e GITHUB_SERVER_URL -e GITHUB_SHA -e GITHUB_WORKSPACE -e GITHUB_TOKEN -e GITHUB_RUN_ID -e GITHUB_RUN_NUMBER -e GITHUB_RUN_ATTEMPT -e GITHUB_JOB -e GITHUB_ACTION -e GITHUB_EVENT_NAME -e GITHUB_EVENT_PATH -e GITHUB_ACTOR -e GITHUB_ACTOR_ID -e GITHUB_TRIGGERING_ACTOR -e GITHUB_WORKFLOW -e GITHUB_WORKFLOW_REF -e GITHUB_WORKFLOW_SHA -e GITHUB_REF -e GITHUB_REF_NAME -e GITHUB_REF_TYPE -e GITHUB_HEAD_REF -e GITHUB_BASE_REF -e GH_AW_SAFE_OUTPUTS_PORT -e GH_AW_SAFE_OUTPUTS_API_KEY -v /tmp/gh-aw/mcp-payloads:/tmp/gh-aw/mcp-payloads:rw -v /opt:/opt:ro -v /tmp:/tmp:rw -v '"${GITHUB_WORKSPACE}"':'"${GITHUB_WORKSPACE}"':rw ghcr.io/github/gh-aw-mcpg:v0.1.7'
mkdir -p /home/runner/.copilot
cat << GH_AW_MCP_CONFIG_EOF | bash /opt/gh-aw/actions/start_mcp_gateway.sh
@@ -787,17 +687,11 @@ jobs:
}
}
GH_AW_MCP_CONFIG_EOF
- - name: Generate workflow overview
- uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8
- with:
- script: |
- const { generateWorkflowOverview } = require('/opt/gh-aw/actions/generate_workflow_overview.cjs');
- await generateWorkflowOverview(core);
- - name: Download prompt artifact
- uses: actions/download-artifact@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v6
+ - name: Download activation artifact
+ uses: actions/download-artifact@70fc10c6e5e1ce46ad2ea6f2b72d43f7d47b13c3 # v8.0.0
with:
- name: prompt
- path: /tmp/gh-aw/aw-prompts
+ name: activation
+ path: /tmp/gh-aw
- name: Clean git credentials
run: bash /opt/gh-aw/actions/clean_git_credentials.sh
- name: Execute GitHub Copilot CLI
@@ -810,14 +704,6 @@ jobs:
# --allow-tool shell(date)
# --allow-tool shell(echo)
# --allow-tool shell(find:*)
- # --allow-tool shell(git add:*)
- # --allow-tool shell(git branch:*)
- # --allow-tool shell(git checkout:*)
- # --allow-tool shell(git commit:*)
- # --allow-tool shell(git merge:*)
- # --allow-tool shell(git rm:*)
- # --allow-tool shell(git status)
- # --allow-tool shell(git switch:*)
# --allow-tool shell(grep)
# --allow-tool shell(grep:*)
# --allow-tool shell(head)
@@ -838,7 +724,7 @@ jobs:
set -o pipefail
# shellcheck disable=SC1003
sudo -E awf --env-all --container-workdir "${GITHUB_WORKSPACE}" --allow-domains "api.business.githubcopilot.com,api.enterprise.githubcopilot.com,api.github.com,api.githubcopilot.com,api.individual.githubcopilot.com,api.snapcraft.io,archive.ubuntu.com,azure.archive.ubuntu.com,crl.geotrust.com,crl.globalsign.com,crl.identrust.com,crl.sectigo.com,crl.thawte.com,crl.usertrust.com,crl.verisign.com,crl3.digicert.com,crl4.digicert.com,crls.ssl.com,github.com,host.docker.internal,json-schema.org,json.schemastore.org,keyserver.ubuntu.com,ocsp.digicert.com,ocsp.geotrust.com,ocsp.globalsign.com,ocsp.identrust.com,ocsp.sectigo.com,ocsp.ssl.com,ocsp.thawte.com,ocsp.usertrust.com,ocsp.verisign.com,packagecloud.io,packages.cloud.google.com,packages.microsoft.com,ppa.launchpad.net,raw.githubusercontent.com,registry.npmjs.org,s.symcb.com,s.symcd.com,security.ubuntu.com,telemetry.enterprise.githubcopilot.com,ts-crl.ws.symantec.com,ts-ocsp.ws.symantec.com" --log-level info --proxy-logs-dir /tmp/gh-aw/sandbox/firewall/logs --enable-host-access --image-tag 0.23.0 --skip-pull --enable-api-proxy \
- -- /bin/bash -c '/usr/local/bin/copilot --add-dir /tmp/gh-aw/ --log-level all --log-dir /tmp/gh-aw/sandbox/agent/logs/ --add-dir "${GITHUB_WORKSPACE}" --disable-builtin-mcps --allow-tool github --allow-tool safeoutputs --allow-tool '\''shell(cat)'\'' --allow-tool '\''shell(cat:*)'\'' --allow-tool '\''shell(date)'\'' --allow-tool '\''shell(echo)'\'' --allow-tool '\''shell(find:*)'\'' --allow-tool '\''shell(git add:*)'\'' --allow-tool '\''shell(git branch:*)'\'' --allow-tool '\''shell(git checkout:*)'\'' --allow-tool '\''shell(git commit:*)'\'' --allow-tool '\''shell(git merge:*)'\'' --allow-tool '\''shell(git rm:*)'\'' --allow-tool '\''shell(git status)'\'' --allow-tool '\''shell(git switch:*)'\'' --allow-tool '\''shell(grep)'\'' --allow-tool '\''shell(grep:*)'\'' --allow-tool '\''shell(head)'\'' --allow-tool '\''shell(head:*)'\'' --allow-tool '\''shell(ls)'\'' --allow-tool '\''shell(ls:*)'\'' --allow-tool '\''shell(pwd)'\'' --allow-tool '\''shell(sort)'\'' --allow-tool '\''shell(tail)'\'' --allow-tool '\''shell(tail:*)'\'' --allow-tool '\''shell(uniq)'\'' --allow-tool '\''shell(wc)'\'' --allow-tool '\''shell(wc:*)'\'' --allow-tool '\''shell(yq)'\'' --allow-tool write --allow-all-paths --prompt "$(cat /tmp/gh-aw/aw-prompts/prompt.txt)"${GH_AW_MODEL_AGENT_COPILOT:+ --model "$GH_AW_MODEL_AGENT_COPILOT"}' 2>&1 | tee -a /tmp/gh-aw/agent-stdio.log
+ -- /bin/bash -c '/usr/local/bin/copilot --add-dir /tmp/gh-aw/ --log-level all --log-dir /tmp/gh-aw/sandbox/agent/logs/ --add-dir "${GITHUB_WORKSPACE}" --disable-builtin-mcps --allow-tool github --allow-tool safeoutputs --allow-tool '\''shell(cat)'\'' --allow-tool '\''shell(cat:*)'\'' --allow-tool '\''shell(date)'\'' --allow-tool '\''shell(echo)'\'' --allow-tool '\''shell(find:*)'\'' --allow-tool '\''shell(grep)'\'' --allow-tool '\''shell(grep:*)'\'' --allow-tool '\''shell(head)'\'' --allow-tool '\''shell(head:*)'\'' --allow-tool '\''shell(ls)'\'' --allow-tool '\''shell(ls:*)'\'' --allow-tool '\''shell(pwd)'\'' --allow-tool '\''shell(sort)'\'' --allow-tool '\''shell(tail)'\'' --allow-tool '\''shell(tail:*)'\'' --allow-tool '\''shell(uniq)'\'' --allow-tool '\''shell(wc)'\'' --allow-tool '\''shell(wc:*)'\'' --allow-tool '\''shell(yq)'\'' --allow-tool write --allow-all-paths --prompt "$(cat /tmp/gh-aw/aw-prompts/prompt.txt)"${GH_AW_MODEL_AGENT_COPILOT:+ --model "$GH_AW_MODEL_AGENT_COPILOT"}' 2>&1 | tee -a /tmp/gh-aw/agent-stdio.log
env:
COPILOT_AGENT_RUNNER_TYPE: STANDALONE
COPILOT_GITHUB_TOKEN: ${{ secrets.COPILOT_GITHUB_TOKEN }}
@@ -854,6 +740,11 @@ jobs:
GITHUB_STEP_SUMMARY: ${{ env.GITHUB_STEP_SUMMARY }}
GITHUB_WORKSPACE: ${{ github.workspace }}
XDG_CONFIG_HOME: /home/runner
+ - name: Detect inference access error
+ id: detect-inference-error
+ if: always()
+ continue-on-error: true
+ run: bash /opt/gh-aw/actions/detect_inference_access_error.sh
- name: Configure Git credentials
env:
REPO_NAME: ${{ github.repository }}
@@ -909,7 +800,7 @@ jobs:
SECRET_RUNTIME_TRIAGE_TOKEN: ${{ secrets.RUNTIME_TRIAGE_TOKEN }}
- name: Upload Safe Outputs
if: always()
- uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6
+ uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
with:
name: safe-output
path: ${{ env.GH_AW_SAFE_OUTPUTS }}
@@ -932,13 +823,13 @@ jobs:
await main();
- name: Upload sanitized agent output
if: always() && env.GH_AW_AGENT_OUTPUT
- uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6
+ uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
with:
name: agent-output
path: ${{ env.GH_AW_AGENT_OUTPUT }}
if-no-files-found: warn
- name: Upload engine output files
- uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6
+ uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
with:
name: agent_outputs
path: |
@@ -983,17 +874,15 @@ jobs:
- name: Upload agent artifacts
if: always()
continue-on-error: true
- uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6
+ uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
with:
name: agent-artifacts
path: |
/tmp/gh-aw/aw-prompts/prompt.txt
- /tmp/gh-aw/aw_info.json
/tmp/gh-aw/mcp-logs/
/tmp/gh-aw/sandbox/firewall/logs/
/tmp/gh-aw/agent-stdio.log
/tmp/gh-aw/agent/
- /tmp/gh-aw/aw-*.patch
if-no-files-found: ignore
# --- Threat Detection (inline) ---
- name: Check if detection needed
@@ -1032,7 +921,7 @@ jobs:
uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8
env:
WORKFLOW_NAME: "SDK Runtime Triage"
- WORKFLOW_DESCRIPTION: "Analyzes copilot-sdk issues to determine if a fix is needed in copilot-agent-runtime, then opens a linked issue and suggested-fix PR there"
+ WORKFLOW_DESCRIPTION: "Analyzes copilot-sdk issues to determine if a fix is needed in copilot-agent-runtime, then opens a linked issue there"
HAS_PATCH: ${{ steps.collect_output.outputs.has_patch }}
with:
script: |
@@ -1086,7 +975,7 @@ jobs:
await main();
- name: Upload threat detection log
if: always() && steps.detection_guard.outputs.run_detection == 'true'
- uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6
+ uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
with:
name: threat-detection.log
path: /tmp/gh-aw/threat-detection/detection.log
@@ -1120,7 +1009,7 @@ jobs:
if: (always()) && (needs.agent.result != 'skipped')
runs-on: ubuntu-slim
permissions:
- contents: write
+ contents: read
issues: write
pull-requests: write
outputs:
@@ -1129,12 +1018,12 @@ jobs:
total_count: ${{ steps.missing_tool.outputs.total_count }}
steps:
- name: Setup Scripts
- uses: github/gh-aw/actions/setup@a7d371cc7e68f270ded0592942424548e05bf1c2 # v0.50.5
+ uses: github/gh-aw/actions/setup@a86e657586e4ac5f549a790628971ec02f6a4a8f # v0.52.1
with:
destination: /opt/gh-aw/actions
- name: Download agent output artifact
continue-on-error: true
- uses: actions/download-artifact@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v6
+ uses: actions/download-artifact@70fc10c6e5e1ce46ad2ea6f2b72d43f7d47b13c3 # v8.0.0
with:
name: agent-output
path: /tmp/gh-aw/safeoutputs/
@@ -1181,9 +1070,9 @@ jobs:
GH_AW_WORKFLOW_ID: "cross-repo-issue-analysis"
GH_AW_SECRET_VERIFICATION_RESULT: ${{ needs.activation.outputs.secret_verification_result }}
GH_AW_CHECKOUT_PR_SUCCESS: ${{ needs.agent.outputs.checkout_pr_success }}
- GH_AW_CODE_PUSH_FAILURE_ERRORS: ${{ needs.safe_outputs.outputs.code_push_failure_errors }}
- GH_AW_CODE_PUSH_FAILURE_COUNT: ${{ needs.safe_outputs.outputs.code_push_failure_count }}
+ GH_AW_INFERENCE_ACCESS_ERROR: ${{ needs.agent.outputs.inference_access_error }}
GH_AW_GROUP_REPORTS: "false"
+ GH_AW_TIMEOUT_MINUTES: "20"
with:
github-token: ${{ secrets.RUNTIME_TRIAGE_TOKEN }}
script: |
@@ -1208,20 +1097,6 @@ jobs:
setupGlobals(core, github, context, exec, io);
const { main } = require('/opt/gh-aw/actions/handle_noop_message.cjs');
await main();
- - name: Handle Create Pull Request Error
- id: handle_create_pr_error
- uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8
- env:
- GH_AW_AGENT_OUTPUT: ${{ env.GH_AW_AGENT_OUTPUT }}
- GH_AW_WORKFLOW_NAME: "SDK Runtime Triage"
- GH_AW_RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
- with:
- github-token: ${{ secrets.RUNTIME_TRIAGE_TOKEN }}
- script: |
- const { setupGlobals } = require('/opt/gh-aw/actions/setup_globals.cjs');
- setupGlobals(core, github, context, exec, io);
- const { main } = require('/opt/gh-aw/actions/handle_create_pr_error.cjs');
- await main();
pre_activation:
if: github.event_name == 'workflow_dispatch' || github.event.label.name == 'runtime triage'
@@ -1231,7 +1106,7 @@ jobs:
matched_command: ''
steps:
- name: Setup Scripts
- uses: github/gh-aw/actions/setup@a7d371cc7e68f270ded0592942424548e05bf1c2 # v0.50.5
+ uses: github/gh-aw/actions/setup@a86e657586e4ac5f549a790628971ec02f6a4a8f # v0.52.1
with:
destination: /opt/gh-aw/actions
- name: Check team membership for workflow
@@ -1248,17 +1123,16 @@ jobs:
await main();
safe_outputs:
- needs:
- - activation
- - agent
+ needs: agent
if: ((!cancelled()) && (needs.agent.result != 'skipped')) && (needs.agent.outputs.detection_success == 'true')
runs-on: ubuntu-slim
permissions:
- contents: write
+ contents: read
issues: write
pull-requests: write
timeout-minutes: 15
env:
+ GH_AW_CALLER_WORKFLOW_ID: "${{ github.repository }}/cross-repo-issue-analysis"
GH_AW_ENGINE_ID: "copilot"
GH_AW_WORKFLOW_ID: "cross-repo-issue-analysis"
GH_AW_WORKFLOW_NAME: "SDK Runtime Triage"
@@ -1267,16 +1141,18 @@ jobs:
code_push_failure_errors: ${{ steps.process_safe_outputs.outputs.code_push_failure_errors }}
create_discussion_error_count: ${{ steps.process_safe_outputs.outputs.create_discussion_error_count }}
create_discussion_errors: ${{ steps.process_safe_outputs.outputs.create_discussion_errors }}
+ created_issue_number: ${{ steps.process_safe_outputs.outputs.created_issue_number }}
+ created_issue_url: ${{ steps.process_safe_outputs.outputs.created_issue_url }}
process_safe_outputs_processed_count: ${{ steps.process_safe_outputs.outputs.processed_count }}
process_safe_outputs_temporary_id_map: ${{ steps.process_safe_outputs.outputs.temporary_id_map }}
steps:
- name: Setup Scripts
- uses: github/gh-aw/actions/setup@a7d371cc7e68f270ded0592942424548e05bf1c2 # v0.50.5
+ uses: github/gh-aw/actions/setup@a86e657586e4ac5f549a790628971ec02f6a4a8f # v0.52.1
with:
destination: /opt/gh-aw/actions
- name: Download agent output artifact
continue-on-error: true
- uses: actions/download-artifact@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v6
+ uses: actions/download-artifact@70fc10c6e5e1ce46ad2ea6f2b72d43f7d47b13c3 # v8.0.0
with:
name: agent-output
path: /tmp/gh-aw/safeoutputs/
@@ -1285,42 +1161,15 @@ jobs:
mkdir -p /tmp/gh-aw/safeoutputs/
find "/tmp/gh-aw/safeoutputs/" -type f -print
echo "GH_AW_AGENT_OUTPUT=/tmp/gh-aw/safeoutputs/agent_output.json" >> "$GITHUB_ENV"
- - name: Download patch artifact
- continue-on-error: true
- uses: actions/download-artifact@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v6
- with:
- name: agent-artifacts
- path: /tmp/gh-aw/
- - name: Checkout repository
- if: ((!cancelled()) && (needs.agent.result != 'skipped')) && (contains(needs.agent.outputs.output_types, 'create_pull_request'))
- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
- with:
- repository: github/copilot-agent-runtime
- ref: ${{ github.base_ref || github.ref_name }}
- token: ${{ secrets.RUNTIME_TRIAGE_TOKEN }}
- persist-credentials: false
- fetch-depth: 1
- - name: Configure Git credentials
- if: ((!cancelled()) && (needs.agent.result != 'skipped')) && (contains(needs.agent.outputs.output_types, 'create_pull_request'))
- env:
- REPO_NAME: "github/copilot-agent-runtime"
- SERVER_URL: ${{ github.server_url }}
- GIT_TOKEN: ${{ secrets.RUNTIME_TRIAGE_TOKEN }}
- run: |
- git config --global user.email "github-actions[bot]@users.noreply.github.com"
- git config --global user.name "github-actions[bot]"
- git config --global am.keepcr true
- # Re-authenticate git with GitHub token
- SERVER_URL_STRIPPED="${SERVER_URL#https://}"
- git remote set-url origin "https://x-access-token:${GIT_TOKEN}@${SERVER_URL_STRIPPED}/${REPO_NAME}.git"
- echo "Git configured with standard GitHub Actions identity"
- name: Process Safe Outputs
id: process_safe_outputs
uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8
env:
GH_AW_AGENT_OUTPUT: ${{ env.GH_AW_AGENT_OUTPUT }}
- GH_AW_SAFE_OUTPUTS_HANDLER_CONFIG: "{\"add_labels\":{\"allowed\":[\"runtime\",\"sdk-fix-only\",\"needs-investigation\"],\"max\":3,\"target\":\"triggering\"},\"create_issue\":{\"labels\":[\"upstream-from-sdk\",\"ai-triaged\"],\"max\":1,\"target-repo\":\"github/copilot-agent-runtime\",\"title_prefix\":\"[copilot-sdk] \"},\"create_pull_request\":{\"base_branch\":\"${{ github.base_ref || github.ref_name }}\",\"draft\":true,\"labels\":[\"upstream-from-sdk\",\"ai-suggested-fix\"],\"max\":1,\"max_patch_size\":1024,\"target-repo\":\"github/copilot-agent-runtime\",\"title_prefix\":\"[copilot-sdk] \"},\"missing_data\":{},\"missing_tool\":{}}"
- GH_AW_CI_TRIGGER_TOKEN: ${{ secrets.GH_AW_CI_TRIGGER_TOKEN }}
+ GH_AW_ALLOWED_DOMAINS: "api.business.githubcopilot.com,api.enterprise.githubcopilot.com,api.github.com,api.githubcopilot.com,api.individual.githubcopilot.com,api.snapcraft.io,archive.ubuntu.com,azure.archive.ubuntu.com,crl.geotrust.com,crl.globalsign.com,crl.identrust.com,crl.sectigo.com,crl.thawte.com,crl.usertrust.com,crl.verisign.com,crl3.digicert.com,crl4.digicert.com,crls.ssl.com,github.com,host.docker.internal,json-schema.org,json.schemastore.org,keyserver.ubuntu.com,ocsp.digicert.com,ocsp.geotrust.com,ocsp.globalsign.com,ocsp.identrust.com,ocsp.sectigo.com,ocsp.ssl.com,ocsp.thawte.com,ocsp.usertrust.com,ocsp.verisign.com,packagecloud.io,packages.cloud.google.com,packages.microsoft.com,ppa.launchpad.net,raw.githubusercontent.com,registry.npmjs.org,s.symcb.com,s.symcd.com,security.ubuntu.com,telemetry.enterprise.githubcopilot.com,ts-crl.ws.symantec.com,ts-ocsp.ws.symantec.com"
+ GITHUB_SERVER_URL: ${{ github.server_url }}
+ GITHUB_API_URL: ${{ github.api_url }}
+ GH_AW_SAFE_OUTPUTS_HANDLER_CONFIG: "{\"add_labels\":{\"allowed\":[\"runtime\",\"sdk-fix-only\",\"needs-investigation\"],\"max\":3,\"target\":\"triggering\"},\"create_issue\":{\"labels\":[\"upstream-from-sdk\",\"ai-triaged\"],\"max\":1,\"target-repo\":\"github/copilot-agent-runtime\",\"title_prefix\":\"[copilot-sdk] \"},\"missing_data\":{},\"missing_tool\":{}}"
with:
github-token: ${{ secrets.RUNTIME_TRIAGE_TOKEN }}
script: |
@@ -1330,7 +1179,7 @@ jobs:
await main();
- name: Upload safe output items manifest
if: always()
- uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6
+ uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
with:
name: safe-output-items
path: /tmp/safe-output-items.jsonl
diff --git a/.github/workflows/cross-repo-issue-analysis.md b/.github/workflows/cross-repo-issue-analysis.md
index 8a0218427a..61b19f4913 100644
--- a/.github/workflows/cross-repo-issue-analysis.md
+++ b/.github/workflows/cross-repo-issue-analysis.md
@@ -1,5 +1,5 @@
---
-description: Analyzes copilot-sdk issues to determine if a fix is needed in copilot-agent-runtime, then opens a linked issue and suggested-fix PR there
+description: Analyzes copilot-sdk issues to determine if a fix is needed in copilot-agent-runtime, then opens a linked issue there
on:
issues:
types: [labeled]
@@ -13,7 +13,6 @@ if: "github.event_name == 'workflow_dispatch' || github.event.label.name == 'run
permissions:
contents: read
issues: read
- pull-requests: read
steps:
- name: Clone copilot-agent-runtime
run: git clone --depth 1 https://x-access-token:${{ secrets.RUNTIME_TRIAGE_TOKEN }}@github.com/github/copilot-agent-runtime.git ${{ github.workspace }}/copilot-agent-runtime
@@ -21,7 +20,6 @@ tools:
github:
toolsets: [default]
github-token: ${{ secrets.RUNTIME_TRIAGE_TOKEN }}
- edit:
bash:
- "grep:*"
- "find:*"
@@ -42,12 +40,6 @@ safe-outputs:
labels: [upstream-from-sdk, ai-triaged]
target-repo: "github/copilot-agent-runtime"
max: 1
- create-pull-request:
- title-prefix: "[copilot-sdk] "
- labels: [upstream-from-sdk, ai-suggested-fix]
- draft: true
- target-repo: "github/copilot-agent-runtime"
-
timeout-minutes: 20
---
@@ -106,10 +98,6 @@ Classify the issue into one of these categories:
- References the original SDK issue (e.g., `github/copilot-sdk#123`)
- Includes the specific files and code paths involved
- Suggests a fix approach
- - Create a draft PR in `github/copilot-agent-runtime` with a suggested fix:
- - Make the minimal, targeted code changes needed
- - Include a clear PR description linking back to both issues
- - If you're uncertain about the fix, still create the PR as a starting point for discussion
3. **Needs-investigation**: You cannot confidently determine the root cause. Label the issue `needs-investigation`.
@@ -117,7 +105,6 @@ Classify the issue into one of these categories:
1. **Be thorough but focused**: Read enough code to be confident in your analysis, but don't read every file in both repos
2. **Err on the side of creating the runtime issue**: If there's a reasonable chance the fix is in the runtime, create the issue. False positives are better than missed upstream bugs.
-3. **Make actionable PRs**: Even if the fix isn't perfect, a draft PR with a concrete starting point is more useful than just an issue description
-4. **Link everything**: Always cross-reference between the SDK issue, runtime issue, and runtime PR so maintainers can follow the trail
-5. **Be specific**: When describing the root cause, point to specific files, functions, and line numbers in both repos
-6. **Don't duplicate**: Before creating a runtime issue, search existing open issues in `github/copilot-agent-runtime` to avoid duplicates. If a related issue exists, reference it instead of creating a new one.
+3. **Link everything**: Always cross-reference between the SDK issue and runtime issue so maintainers can follow the trail
+4. **Be specific**: When describing the root cause, point to specific files, functions, and line numbers in both repos
+5. **Don't duplicate**: Before creating a runtime issue, search existing open issues in `github/copilot-agent-runtime` to avoid duplicates. If a related issue exists, reference it instead of creating a new one.
diff --git a/.github/workflows/nodejs-sdk-tests.yml b/.github/workflows/nodejs-sdk-tests.yml
index 9e978a22fa..9dec016675 100644
--- a/.github/workflows/nodejs-sdk-tests.yml
+++ b/.github/workflows/nodejs-sdk-tests.yml
@@ -62,6 +62,9 @@ jobs:
- name: Typecheck SDK
run: npm run typecheck
+ - name: Build SDK
+ run: npm run build
+
- name: Install test harness dependencies
working-directory: ./test/harness
run: npm ci --ignore-scripts
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 5abbfefc43..ac5712aa58 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,78 @@ All notable changes to the Copilot SDK are documented in this file.
This changelog is automatically generated by an AI agent when stable releases are published.
See [GitHub Releases](https://github.com/github/copilot-sdk/releases) for the full list.
+## [v0.1.32](https://github.com/github/copilot-sdk/releases/tag/v0.1.32) (2026-03-07)
+
+### Feature: backward compatibility with v2 CLI servers
+
+SDK applications written against the v3 API now also work when connected to a v2 CLI server, with no code changes required. The SDK detects the server's protocol version and automatically adapts v2 `tool.call` and `permission.request` messages into the same user-facing handlers used by v3. ([#706](https://github.com/github/copilot-sdk/pull/706))
+
+```ts
+const session = await client.createSession({
+ tools: [myTool], // unchanged — works with v2 and v3 servers
+ onPermissionRequest: approveAll,
+});
+```
+
+```cs
+var session = await client.CreateSessionAsync(new SessionConfig {
+ Tools = [myTool], // unchanged — works with v2 and v3 servers
+ OnPermissionRequest = approveAll,
+});
+```
+
+## [v0.1.31](https://github.com/github/copilot-sdk/releases/tag/v0.1.31) (2026-03-07)
+
+### Feature: multi-client tool and permission broadcasts (protocol v3)
+
+The SDK now uses protocol version 3, where the runtime broadcasts `external_tool.requested` and `permission.requested` as session events to all connected clients. This enables multi-client architectures where different clients contribute different tools, or where multiple clients observe the same permission prompts — if one client approves, all clients see the result. Your existing tool and permission handler code is unchanged. ([#686](https://github.com/github/copilot-sdk/pull/686))
+
+```ts
+// Two clients each register different tools; the agent can use both
+const session1 = await client1.createSession({
+ tools: [defineTool("search", { handler: doSearch })],
+ onPermissionRequest: approveAll,
+});
+const session2 = await client2.resumeSession(session1.id, {
+ tools: [defineTool("analyze", { handler: doAnalyze })],
+ onPermissionRequest: approveAll,
+});
+```
+
+```cs
+var session1 = await client1.CreateSessionAsync(new SessionConfig {
+ Tools = [AIFunctionFactory.Create(DoSearch, "search")],
+ OnPermissionRequest = PermissionHandlers.ApproveAll,
+});
+var session2 = await client2.ResumeSessionAsync(session1.Id, new ResumeSessionConfig {
+ Tools = [AIFunctionFactory.Create(DoAnalyze, "analyze")],
+ OnPermissionRequest = PermissionHandlers.ApproveAll,
+});
+```
+
+### Feature: strongly-typed `PermissionRequestResultKind` for .NET and Go
+
+Rather than comparing `result.Kind` against undiscoverable magic strings like `"approved"` or `"denied-interactively-by-user"`, .NET and Go now provide typed constants. Node and Python already had typed unions for this; this brings full parity. ([#631](https://github.com/github/copilot-sdk/pull/631))
+
+```cs
+session.OnPermissionCompleted += (e) => {
+ if (e.Result.Kind == PermissionRequestResultKind.Approved) { /* ... */ }
+ if (e.Result.Kind == PermissionRequestResultKind.DeniedInteractivelyByUser) { /* ... */ }
+};
+```
+
+```go
+// Go: PermissionKindApproved, PermissionKindDeniedByRules,
+// PermissionKindDeniedCouldNotRequestFromUser, PermissionKindDeniedInteractivelyByUser
+if result.Kind == copilot.PermissionKindApproved { /* ... */ }
+```
+
+### Other changes
+
+- feature: **[Python]** **[Go]** add `get_last_session_id()` / `GetLastSessionID()` for SDK-wide parity (was already available in Node and .NET) ([#671](https://github.com/github/copilot-sdk/pull/671))
+- improvement: **[Python]** add `timeout` parameter to generated RPC methods, allowing callers to override the default 30s timeout for long-running operations ([#681](https://github.com/github/copilot-sdk/pull/681))
+- bugfix: **[Go]** `PermissionRequest` fields are now properly typed (`ToolName`, `Diff`, `Path`, etc.) instead of a generic `Extra map[string]any` catch-all ([#685](https://github.com/github/copilot-sdk/pull/685))
+
## [v0.1.30](https://github.com/github/copilot-sdk/releases/tag/v0.1.30) (2026-03-03)
### Feature: support overriding built-in tools
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 4650ee04e3..7dbe1b4923 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,60 +1,71 @@
-## Contributing
+# Contributing
-[fork]: https://github.com/github/copilot-sdk/fork
-[pr]: https://github.com/github/copilot-sdk/compare
+Thanks for your interest in contributing!
-Hi there! We're thrilled that you'd like to contribute to this project. Your help is essential for keeping it great.
+This repository contains the Copilot SDK, a set of multi-language SDKs (Node/TypeScript, Python, Go, .NET) for building applications with the GitHub Copilot agent, maintained by the GitHub Copilot team.
Contributions to this project are [released](https://help.github.com/articles/github-terms-of-service/#6-contributions-under-repository-license) to the public under the [project's open source license](LICENSE).
Please note that this project is released with a [Contributor Code of Conduct](CODE_OF_CONDUCT.md). By participating in this project you agree to abide by its terms.
-## What kinds of contributions we're looking for
+## Before You Submit a PR
-We'd love your help with:
+**Please discuss any feature work with us before writing code.**
- * Fixing any bugs in the existing feature set
- * Making the SDKs more idiomatic and nice to use for each supported language
- * Improving documentation
+The team already has a committed product roadmap, and features must be maintained in sync across all supported languages. Pull requests that introduce features not previously aligned with the team are unlikely to be accepted, regardless of their quality or scope.
-If you have ideas for entirely new features, please post an issue or start a discussion. We're very open to new features but need to make sure they align with the direction of the underlying Copilot CLI and can be maintained in sync across all our supported languages.
+If you submit a PR, **be sure to link to an associated issue describing the bug or agreed feature**. No PRs without context :)
-Currently **we are not looking to add SDKs for other languages**. If you want to create a Copilot SDK for another language, we'd love to hear from you, and we may offer to link to your SDK from our repo. However we do not plan to add further language-specific SDKs to this repo in the short term, since we need to retain our maintenance capacity for moving forwards quickly with the existing language set. So, for any other languages, please consider running your own external project.
+## What We're Looking For
-## Prerequisites for running and testing code
+We welcome:
+
+- Bug fixes with clear reproduction steps
+- Improvements to documentation
+- Making the SDKs more idiomatic and nice to use for each supported language
+- Bug reports and feature suggestions on [our issue tracker](https://github.com/github/copilot-sdk/issues) — especially for bugs with repro steps
+
+We are generally **not** looking for:
+
+- New features, capabilities, or UX changes that haven't been discussed and agreed with the team
+- Refactors or architectural changes
+- Integrations with external tools or services
+- Additional documentation
+- **SDKs for other languages** — if you want to create a Copilot SDK for another language, we'd love to hear from you and may offer to link to your SDK from our repo. However we do not plan to add further language-specific SDKs to this repo in the short term, since we need to retain our maintenance capacity for moving forwards quickly with the existing language set. For other languages, please consider running your own external project.
+
+## Prerequisites for Running and Testing Code
This is a multi-language SDK repository. Install the tools for the SDK(s) you plan to work on:
### All SDKs
-1. (Optional) Install [just](https://github.com/casey/just) command runner for convenience
+
+1. The end-to-end tests across all languages use a shared test harness written in Node.js. Before running tests in any language, `cd test/harness && npm ci`.
### Node.js/TypeScript SDK
+
1. Install [Node.js](https://nodejs.org/) (v18+)
1. Install dependencies: `cd nodejs && npm ci`
### Python SDK
+
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]"`
### Go SDK
+
1. Install [Go 1.24+](https://go.dev/doc/install)
1. Install [golangci-lint](https://golangci-lint.run/welcome/install/#local-installation)
1. Install dependencies: `cd go && go mod download`
### .NET SDK
+
1. Install [.NET 8.0+](https://dotnet.microsoft.com/download)
-1. Install [Node.js](https://nodejs.org/) (v18+) (the .NET tests depend on a TypeScript-based test harness)
-1. Install npm dependencies (from the repository root):
- ```bash
- cd nodejs && npm ci
- cd test/harness && npm ci
- ```
1. Install .NET dependencies: `cd dotnet && dotnet restore`
-## Submitting a pull request
+## Submitting a Pull Request
-1. [Fork][fork] and clone the repository
+1. Fork and clone the repository
1. Install dependencies for the SDK(s) you're modifying (see above)
1. Make sure the tests pass on your machine (see commands below)
1. Make sure linter passes on your machine (see commands below)
@@ -63,29 +74,7 @@ This is a multi-language SDK repository. Install the tools for the SDK(s) you pl
1. Push to your fork and [submit a pull request][pr]
1. Pat yourself on the back and wait for your pull request to be reviewed and merged.
-### Running tests and linters
-
-If you installed `just`, you can use it to run tests and linters across all SDKs or for specific languages:
-
-```bash
-# All SDKs
-just test # Run all tests
-just lint # Run all linters
-just format # Format all code
-
-# Individual SDKs
-just test-nodejs # Node.js tests
-just test-python # Python tests
-just test-go # Go tests
-just test-dotnet # .NET tests
-
-just lint-nodejs # Node.js linting
-just lint-python # Python linting
-just lint-go # Go linting
-just lint-dotnet # .NET linting
-```
-
-Or run commands directly in each SDK directory:
+### Running Tests and Linters
```bash
# Node.js
diff --git a/README.md b/README.md
index be9b4694b6..65a2339c85 100644
--- a/README.md
+++ b/README.md
@@ -8,7 +8,7 @@
Agents for every app.
-Embed Copilot's agentic workflows in your application—now available in Technical preview as a programmable SDK for Python, TypeScript, Go, and .NET.
+Embed Copilot's agentic workflows in your application—now available in Technical preview as a programmable SDK for Python, TypeScript, Go, .NET, and Java.
The GitHub Copilot SDK exposes the same engine behind Copilot CLI: a production-tested agent runtime you can invoke programmatically. No need to build your own orchestration—you define agent behavior, Copilot handles planning, tool invocation, file edits, and more.
@@ -20,6 +20,7 @@ The GitHub Copilot SDK exposes the same engine behind Copilot CLI: a production-
| **Python** | [`python/`](./python/) | [Cookbook](https://github.com/github/awesome-copilot/blob/main/cookbook/copilot-sdk/python/README.md) | `pip install github-copilot-sdk` |
| **Go** | [`go/`](./go/) | [Cookbook](https://github.com/github/awesome-copilot/blob/main/cookbook/copilot-sdk/go/README.md) | `go get github.com/github/copilot-sdk/go` |
| **.NET** | [`dotnet/`](./dotnet/) | [Cookbook](https://github.com/github/awesome-copilot/blob/main/cookbook/copilot-sdk/dotnet/README.md) | `dotnet add package GitHub.Copilot.SDK` |
+| **Java** | [`github/copilot-sdk-java`](https://github.com/github/copilot-sdk-java) | WIP | Maven coordinates
`com.github:copilot-sdk-java`
See instructions for [Maven](https://github.com/github/copilot-sdk-java?tab=readme-ov-file#maven) and [Gradle](https://github.com/github/copilot-sdk-java?tab=readme-ov-file#gradle) |
See the individual SDK READMEs for installation, usage examples, and API reference.
@@ -91,7 +92,14 @@ Yes, the GitHub Copilot SDK allows you to define custom agents, skills, and tool
### Are there instructions for Copilot to speed up development with the SDK?
-Yes, check out the custom instructions at [`github/awesome-copilot`](https://github.com/github/awesome-copilot/blob/main/collections/copilot-sdk.md).
+Yes, check out the custom instructions for each SDK:
+
+- **[Node.js / TypeScript](https://github.com/github/awesome-copilot/blob/main/instructions/copilot-sdk-nodejs.instructions.md)**
+- **[Python](https://github.com/github/awesome-copilot/blob/main/instructions/copilot-sdk-python.instructions.md)**
+- **[.NET](https://github.com/github/awesome-copilot/blob/main/instructions/copilot-sdk-csharp.instructions.md)**
+- **[Go](https://github.com/github/awesome-copilot/blob/main/instructions/copilot-sdk-go.instructions.md)**
+- **[Java](https://github.com/github/copilot-sdk-java/blob/main/instructions/copilot-sdk-java.instructions.md)**
+
### What models are supported?
@@ -107,8 +115,12 @@ Please use the [GitHub Issues](https://github.com/github/copilot-sdk/issues) pag
## Quick Links
+- **[Documentation](./docs/index.md)** – Full documentation index
- **[Getting Started](./docs/getting-started.md)** – Tutorial to get up and running
+- **[Setup Guides](./docs/setup/index.md)** – Architecture, deployment, and scaling
- **[Authentication](./docs/auth/index.md)** – GitHub OAuth, BYOK, and more
+- **[Features](./docs/features/index.md)** – Hooks, custom agents, MCP, skills, and more
+- **[Troubleshooting](./docs/troubleshooting/debugging.md)** – Common issues and solutions
- **[Cookbook](https://github.com/github/awesome-copilot/blob/main/cookbook/copilot-sdk)** – Practical recipes for common tasks across all languages
- **[More Resources](https://github.com/github/awesome-copilot/blob/main/collections/copilot-sdk.md)** – Additional examples, tutorials, and community resources
@@ -118,12 +130,10 @@ Please use the [GitHub Issues](https://github.com/github/copilot-sdk/issues) pag
| SDK | Location |
| --------------| ----------------------------------------------------------------- |
-| **Java** | [copilot-community-sdk/copilot-sdk-java][sdk-java] |
| **Rust** | [copilot-community-sdk/copilot-sdk-rust][sdk-rust] |
| **Clojure** | [copilot-community-sdk/copilot-sdk-clojure][sdk-clojure] |
| **C++** | [0xeb/copilot-sdk-cpp][sdk-cpp] |
-[sdk-java]: https://github.com/copilot-community-sdk/copilot-sdk-java
[sdk-rust]: https://github.com/copilot-community-sdk/copilot-sdk-rust
[sdk-cpp]: https://github.com/0xeb/copilot-sdk-cpp
[sdk-clojure]: https://github.com/copilot-community-sdk/copilot-sdk-clojure
diff --git a/assets/copilot.png b/assets/copilot.png
new file mode 100644
index 0000000000..e71958c947
Binary files /dev/null and b/assets/copilot.png differ
diff --git a/docs/auth/byok.md b/docs/auth/byok.md
index ca7861c160..8d96502802 100644
--- a/docs/auth/byok.md
+++ b/docs/auth/byok.md
@@ -23,7 +23,7 @@ Azure AI Foundry (formerly Azure OpenAI) is a common BYOK deployment target for
```python
import asyncio
import os
-from copilot import CopilotClient
+from copilot import CopilotClient, PermissionHandler
FOUNDRY_MODEL_URL = "https://your-resource.openai.azure.com/openai/v1/"
# Set FOUNDRY_API_KEY environment variable
@@ -32,14 +32,11 @@ async def main():
client = CopilotClient()
await client.start()
- session = await client.create_session({
- "model": "gpt-5.2-codex", # Your deployment name
- "provider": {
- "type": "openai",
- "base_url": FOUNDRY_MODEL_URL,
- "wire_api": "responses", # Use "completions" for older models
- "api_key": os.environ["FOUNDRY_API_KEY"],
- },
+ session = await client.create_session(on_permission_request=PermissionHandler.approve_all, model="gpt-5.2-codex", provider={
+ "type": "openai",
+ "base_url": FOUNDRY_MODEL_URL,
+ "wire_api": "responses", # Use "completions" for older models
+ "api_key": os.environ["FOUNDRY_API_KEY"],
})
done = asyncio.Event()
@@ -306,6 +303,116 @@ provider: {
> **Note:** The `bearerToken` option accepts a **static token string** only. The SDK does not refresh this token automatically. If your token expires, requests will fail and you'll need to create a new session with a fresh token.
+## Custom Model Listing
+
+When using BYOK, the CLI server may not know which models your provider supports. You can supply a custom `onListModels` handler at the client level so that `client.listModels()` returns your provider's models in the standard `ModelInfo` format. This lets downstream consumers discover available models without querying the CLI.
+
+
+Node.js / TypeScript
+
+```typescript
+import { CopilotClient } from "@github/copilot-sdk";
+import type { ModelInfo } from "@github/copilot-sdk";
+
+const client = new CopilotClient({
+ onListModels: () => [
+ {
+ id: "my-custom-model",
+ name: "My Custom Model",
+ capabilities: {
+ supports: { vision: false, reasoningEffort: false },
+ limits: { max_context_window_tokens: 128000 },
+ },
+ },
+ ],
+});
+```
+
+
+
+
+Python
+
+```python
+from copilot import CopilotClient
+from copilot.types import ModelInfo, ModelCapabilities, ModelSupports, ModelLimits
+
+client = CopilotClient({
+ "on_list_models": lambda: [
+ ModelInfo(
+ id="my-custom-model",
+ name="My Custom Model",
+ capabilities=ModelCapabilities(
+ supports=ModelSupports(vision=False, reasoning_effort=False),
+ limits=ModelLimits(max_context_window_tokens=128000),
+ ),
+ )
+ ],
+})
+```
+
+
+
+
+Go
+
+```go
+package main
+
+import (
+ "context"
+ copilot "github.com/github/copilot-sdk/go"
+)
+
+func main() {
+ client := copilot.NewClient(&copilot.ClientOptions{
+ OnListModels: func(ctx context.Context) ([]copilot.ModelInfo, error) {
+ return []copilot.ModelInfo{
+ {
+ ID: "my-custom-model",
+ Name: "My Custom Model",
+ Capabilities: copilot.ModelCapabilities{
+ Supports: copilot.ModelSupports{Vision: false, ReasoningEffort: false},
+ Limits: copilot.ModelLimits{MaxContextWindowTokens: 128000},
+ },
+ },
+ }, nil
+ },
+ })
+ _ = client
+}
+```
+
+
+
+
+.NET
+
+```csharp
+using GitHub.Copilot.SDK;
+
+var client = new CopilotClient(new CopilotClientOptions
+{
+ OnListModels = (ct) => Task.FromResult(new List
+ {
+ new()
+ {
+ Id = "my-custom-model",
+ Name = "My Custom Model",
+ Capabilities = new ModelCapabilities
+ {
+ Supports = new ModelSupports { Vision = false, ReasoningEffort = false },
+ Limits = new ModelLimits { MaxContextWindowTokens = 128000 }
+ }
+ }
+ })
+});
+```
+
+
+
+Results are cached after the first call, just like the default behavior. The handler completely replaces the CLI's `models.list` RPC — no fallback to the server occurs.
+
## Limitations
When using BYOK, be aware of these limitations:
@@ -363,7 +470,21 @@ const session = await client.createSession({
For Azure OpenAI endpoints (`*.openai.azure.com`), use the correct type:
-
+
+```typescript
+import { CopilotClient } from "@github/copilot-sdk";
+
+const client = new CopilotClient();
+const session = await client.createSession({
+ model: "gpt-4.1",
+ provider: {
+ type: "azure",
+ baseUrl: "https://my-resource.openai.azure.com",
+ },
+});
+```
+
+
```typescript
// ❌ Wrong: Using "openai" type with native Azure endpoint
provider: {
@@ -380,7 +501,21 @@ provider: {
However, if your Azure AI Foundry deployment provides an OpenAI-compatible endpoint path (e.g., `/openai/v1/`), use `type: "openai"`:
-
+
+```typescript
+import { CopilotClient } from "@github/copilot-sdk";
+
+const client = new CopilotClient();
+const session = await client.createSession({
+ model: "gpt-4.1",
+ provider: {
+ type: "openai",
+ baseUrl: "https://your-resource.openai.azure.com/openai/v1/",
+ },
+});
+```
+
+
```typescript
// ✅ Correct: OpenAI-compatible Azure AI Foundry endpoint
provider: {
diff --git a/docs/auth/index.md b/docs/auth/index.md
index 9fc65fe28b..2f36d8b21d 100644
--- a/docs/auth/index.md
+++ b/docs/auth/index.md
@@ -50,7 +50,20 @@ await client.start()
Go
-
+
+```go
+package main
+
+import copilot "github.com/github/copilot-sdk/go"
+
+func main() {
+ // Default: uses logged-in user credentials
+ client := copilot.NewClient(nil)
+ _ = client
+}
+```
+
+
```go
import copilot "github.com/github/copilot-sdk/go"
@@ -120,7 +133,23 @@ await client.start()
Go
-
+
+```go
+package main
+
+import copilot "github.com/github/copilot-sdk/go"
+
+func main() {
+ userAccessToken := "token"
+ client := copilot.NewClient(&copilot.ClientOptions{
+ GitHubToken: userAccessToken,
+ UseLoggedInUser: copilot.Bool(false),
+ })
+ _ = client
+}
+```
+
+
```go
import copilot "github.com/github/copilot-sdk/go"
@@ -135,7 +164,19 @@ client := copilot.NewClient(&copilot.ClientOptions{
.NET
-
+
+```csharp
+using GitHub.Copilot.SDK;
+
+var userAccessToken = "token";
+await using var client = new CopilotClient(new CopilotClientOptions
+{
+ GithubToken = userAccessToken,
+ UseLoggedInUser = false,
+});
+```
+
+
```csharp
using GitHub.Copilot.SDK;
@@ -254,7 +295,16 @@ const client = new CopilotClient({
Python
-
+
+```python
+from copilot import CopilotClient
+
+client = CopilotClient({
+ "use_logged_in_user": False,
+})
+```
+
+
```python
client = CopilotClient({
"use_logged_in_user": False, # Only use explicit tokens
@@ -266,7 +316,21 @@ client = CopilotClient({
Go
-
+
+```go
+package main
+
+import copilot "github.com/github/copilot-sdk/go"
+
+func main() {
+ client := copilot.NewClient(&copilot.ClientOptions{
+ UseLoggedInUser: copilot.Bool(false),
+ })
+ _ = client
+}
+```
+
+
```go
client := copilot.NewClient(&copilot.ClientOptions{
UseLoggedInUser: copilot.Bool(false), // Only use explicit tokens
@@ -291,4 +355,4 @@ await using var client = new CopilotClient(new CopilotClientOptions
- [BYOK Documentation](./byok.md) - Learn how to use your own API keys
- [Getting Started Guide](../getting-started.md) - Build your first Copilot-powered app
-- [MCP Servers](../mcp) - Connect to external tools
+- [MCP Servers](../features/mcp.md) - Connect to external tools
diff --git a/docs/guides/custom-agents.md b/docs/features/custom-agents.md
similarity index 76%
rename from docs/guides/custom-agents.md
rename to docs/features/custom-agents.md
index 16f7a37a0c..47712d9cf0 100644
--- a/docs/guides/custom-agents.md
+++ b/docs/features/custom-agents.md
@@ -65,13 +65,15 @@ const session = await client.createSession({
```python
from copilot import CopilotClient
+from copilot.types import PermissionRequestResult
client = CopilotClient()
await client.start()
-session = await client.create_session({
- "model": "gpt-4.1",
- "custom_agents": [
+session = await client.create_session(
+ on_permission_request=lambda req, inv: PermissionRequestResult(kind="approved"),
+ model="gpt-4.1",
+ custom_agents=[
{
"name": "researcher",
"display_name": "Research Agent",
@@ -87,8 +89,7 @@ session = await client.create_session({
"prompt": "You are a code editor. Make minimal, surgical changes to files as requested.",
},
],
- "on_permission_request": lambda req: {"kind": "approved"},
-})
+)
```
@@ -96,7 +97,47 @@ session = await client.create_session({
Go
-
+
+```go
+package main
+
+import (
+ "context"
+ copilot "github.com/github/copilot-sdk/go"
+)
+
+func main() {
+ ctx := context.Background()
+ client := copilot.NewClient(nil)
+ client.Start(ctx)
+
+ session, _ := client.CreateSession(ctx, &copilot.SessionConfig{
+ Model: "gpt-4.1",
+ CustomAgents: []copilot.CustomAgentConfig{
+ {
+ Name: "researcher",
+ DisplayName: "Research Agent",
+ Description: "Explores codebases and answers questions using read-only tools",
+ Tools: []string{"grep", "glob", "view"},
+ Prompt: "You are a research assistant. Analyze code and answer questions. Do not modify any files.",
+ },
+ {
+ Name: "editor",
+ DisplayName: "Editor Agent",
+ Description: "Makes targeted code changes",
+ Tools: []string{"view", "edit", "bash"},
+ Prompt: "You are a code editor. Make minimal, surgical changes to files as requested.",
+ },
+ },
+ OnPermissionRequest: func(req copilot.PermissionRequest, inv copilot.PermissionInvocation) (copilot.PermissionRequestResult, error) {
+ return copilot.PermissionRequestResult{Kind: copilot.PermissionRequestResultKindApproved}, nil
+ },
+ })
+ _ = session
+}
+```
+
+
```go
ctx := context.Background()
client := copilot.NewClient(nil)
@@ -178,6 +219,103 @@ await using var session = await client.CreateSessionAsync(new SessionConfig
> **Tip:** A good `description` helps the runtime match user intent to the right agent. Be specific about the agent's expertise and capabilities.
+In addition to per-agent configuration above, you can set `agent` on the **session config** itself to pre-select which custom agent is active when the session starts. See [Selecting an Agent at Session Creation](#selecting-an-agent-at-session-creation) below.
+
+| Session Config Property | Type | Description |
+|-------------------------|------|-------------|
+| `agent` | `string` | Name of the custom agent to pre-select at session creation. Must match a `name` in `customAgents`. |
+
+## Selecting an Agent at Session Creation
+
+You can pass `agent` in the session config to pre-select which custom agent should be active when the session starts. The value must match the `name` of one of the agents defined in `customAgents`.
+
+This is equivalent to calling `session.rpc.agent.select()` after creation, but avoids the extra API call and ensures the agent is active from the very first prompt.
+
+
+Node.js / TypeScript
+
+
+```typescript
+const session = await client.createSession({
+ customAgents: [
+ {
+ name: "researcher",
+ prompt: "You are a research assistant. Analyze code and answer questions.",
+ },
+ {
+ name: "editor",
+ prompt: "You are a code editor. Make minimal, surgical changes.",
+ },
+ ],
+ agent: "researcher", // Pre-select the researcher agent
+});
+```
+
+
+
+
+Python
+
+
+```python
+session = await client.create_session(
+ on_permission_request=PermissionHandler.approve_all,
+ custom_agents=[
+ {
+ "name": "researcher",
+ "prompt": "You are a research assistant. Analyze code and answer questions.",
+ },
+ {
+ "name": "editor",
+ "prompt": "You are a code editor. Make minimal, surgical changes.",
+ },
+ ],
+ agent="researcher", # Pre-select the researcher agent
+)
+```
+
+
+
+
+Go
+
+
+```go
+session, _ := client.CreateSession(ctx, &copilot.SessionConfig{
+ CustomAgents: []copilot.CustomAgentConfig{
+ {
+ Name: "researcher",
+ Prompt: "You are a research assistant. Analyze code and answer questions.",
+ },
+ {
+ Name: "editor",
+ Prompt: "You are a code editor. Make minimal, surgical changes.",
+ },
+ },
+ Agent: "researcher", // Pre-select the researcher agent
+})
+```
+
+
+
+
+.NET
+
+
+```csharp
+var session = await client.CreateSessionAsync(new SessionConfig
+{
+ CustomAgents = new List
+ {
+ new() { Name = "researcher", Prompt = "You are a research assistant. Analyze code and answer questions." },
+ new() { Name = "editor", Prompt = "You are a code editor. Make minimal, surgical changes." },
+ },
+ Agent = "researcher", // Pre-select the researcher agent
+});
+```
+
+
+
## How Sub-Agent Delegation Works
When you send a prompt to a session with custom agents, the runtime evaluates whether to delegate to a sub-agent:
@@ -286,7 +424,51 @@ response = await session.send_and_wait({
Go
-
+
+```go
+package main
+
+import (
+ "context"
+ "fmt"
+ copilot "github.com/github/copilot-sdk/go"
+)
+
+func main() {
+ ctx := context.Background()
+ client := copilot.NewClient(nil)
+ client.Start(ctx)
+
+ session, _ := client.CreateSession(ctx, &copilot.SessionConfig{
+ Model: "gpt-4.1",
+ OnPermissionRequest: func(req copilot.PermissionRequest, inv copilot.PermissionInvocation) (copilot.PermissionRequestResult, error) {
+ return copilot.PermissionRequestResult{Kind: copilot.PermissionRequestResultKindApproved}, nil
+ },
+ })
+
+ session.On(func(event copilot.SessionEvent) {
+ switch event.Type {
+ case "subagent.started":
+ fmt.Printf("▶ Sub-agent started: %s\n", *event.Data.AgentDisplayName)
+ fmt.Printf(" Description: %s\n", *event.Data.AgentDescription)
+ fmt.Printf(" Tool call ID: %s\n", *event.Data.ToolCallID)
+ case "subagent.completed":
+ fmt.Printf("✅ Sub-agent completed: %s\n", *event.Data.AgentDisplayName)
+ case "subagent.failed":
+ fmt.Printf("❌ Sub-agent failed: %s — %v\n", *event.Data.AgentDisplayName, event.Data.Error)
+ case "subagent.selected":
+ fmt.Printf("🎯 Agent selected: %s\n", *event.Data.AgentDisplayName)
+ }
+ })
+
+ _, err := session.SendAndWait(ctx, copilot.MessageOptions{
+ Prompt: "Research how authentication works in this codebase",
+ })
+ _ = err
+}
+```
+
+
```go
session.On(func(event copilot.SessionEvent) {
switch event.Type {
diff --git a/docs/features/hooks.md b/docs/features/hooks.md
new file mode 100644
index 0000000000..1a01c5f1a4
--- /dev/null
+++ b/docs/features/hooks.md
@@ -0,0 +1,988 @@
+# Working with Hooks
+
+Hooks let you plug custom logic into every stage of a Copilot session — from the moment it starts, through each user prompt and tool call, to the moment it ends. This guide walks through practical use cases so you can ship permissions, auditing, notifications, and more without modifying the core agent behavior.
+
+## Overview
+
+A hook is a callback you register once when creating a session. The SDK invokes it at a well-defined point in the conversation lifecycle, passes contextual input, and optionally accepts output that modifies the session's behavior.
+
+```mermaid
+flowchart LR
+ A[Session starts] -->|onSessionStart| B[User sends prompt]
+ B -->|onUserPromptSubmitted| C[Agent picks a tool]
+ C -->|onPreToolUse| D[Tool executes]
+ D -->|onPostToolUse| E{More work?}
+ E -->|yes| C
+ E -->|no| F[Session ends]
+ F -->|onSessionEnd| G((Done))
+ C -.->|error| H[onErrorOccurred]
+ D -.->|error| H
+```
+
+| Hook | When it fires | What you can do |
+|------|---------------|-----------------|
+| [`onSessionStart`](../hooks/session-lifecycle.md#session-start) | Session begins (new or resumed) | Inject context, load preferences |
+| [`onUserPromptSubmitted`](../hooks/user-prompt-submitted.md) | User sends a message | Rewrite prompts, add context, filter input |
+| [`onPreToolUse`](../hooks/pre-tool-use.md) | Before a tool executes | Allow / deny / modify the call |
+| [`onPostToolUse`](../hooks/post-tool-use.md) | After a tool returns | Transform results, redact secrets, audit |
+| [`onSessionEnd`](../hooks/session-lifecycle.md#session-end) | Session ends | Clean up, record metrics |
+| [`onErrorOccurred`](../hooks/error-handling.md) | An error is raised | Custom logging, retry logic, alerts |
+
+All hooks are **optional** — register only the ones you need. Returning `null` (or the language equivalent) from any hook tells the SDK to continue with default behavior.
+
+## Registering Hooks
+
+Pass a `hooks` object when you create (or resume) a session. Every example below follows this pattern.
+
+
+Node.js / TypeScript
+
+```typescript
+import { CopilotClient } from "@github/copilot-sdk";
+
+const client = new CopilotClient();
+await client.start();
+
+const session = await client.createSession({
+ hooks: {
+ onSessionStart: async (input, invocation) => { /* ... */ },
+ onPreToolUse: async (input, invocation) => { /* ... */ },
+ onPostToolUse: async (input, invocation) => { /* ... */ },
+ // ... add only the hooks you need
+ },
+ onPermissionRequest: async () => ({ kind: "approved" }),
+});
+```
+
+
+
+
+Python
+
+```python
+from copilot import CopilotClient
+
+client = CopilotClient()
+await client.start()
+
+session = await client.create_session(
+ on_permission_request=lambda req, inv: {"kind": "approved"},
+ hooks={
+ "on_session_start": on_session_start,
+ "on_pre_tool_use": on_pre_tool_use,
+ "on_post_tool_use": on_post_tool_use,
+ # ... add only the hooks you need
+ },
+)
+```
+
+
+
+
+Go
+
+
+```go
+package main
+
+import (
+ "context"
+ copilot "github.com/github/copilot-sdk/go"
+)
+
+func onSessionStart(input copilot.SessionStartHookInput, inv copilot.HookInvocation) (*copilot.SessionStartHookOutput, error) {
+ return nil, nil
+}
+
+func onPreToolUse(input copilot.PreToolUseHookInput, inv copilot.HookInvocation) (*copilot.PreToolUseHookOutput, error) {
+ return nil, nil
+}
+
+func onPostToolUse(input copilot.PostToolUseHookInput, inv copilot.HookInvocation) (*copilot.PostToolUseHookOutput, error) {
+ return nil, nil
+}
+
+func main() {
+ ctx := context.Background()
+ client := copilot.NewClient(nil)
+
+ session, err := client.CreateSession(ctx, &copilot.SessionConfig{
+ Hooks: &copilot.SessionHooks{
+ OnSessionStart: onSessionStart,
+ OnPreToolUse: onPreToolUse,
+ OnPostToolUse: onPostToolUse,
+ },
+ OnPermissionRequest: func(req copilot.PermissionRequest, inv copilot.PermissionInvocation) (copilot.PermissionRequestResult, error) {
+ return copilot.PermissionRequestResult{Kind: "approved"}, nil
+ },
+ })
+ _ = session
+ _ = err
+}
+```
+
+
+```go
+client := copilot.NewClient(nil)
+
+session, err := client.CreateSession(ctx, &copilot.SessionConfig{
+ Hooks: &copilot.SessionHooks{
+ OnSessionStart: onSessionStart,
+ OnPreToolUse: onPreToolUse,
+ OnPostToolUse: onPostToolUse,
+ // ... add only the hooks you need
+ },
+ OnPermissionRequest: func(req copilot.PermissionRequest, inv copilot.PermissionInvocation) (copilot.PermissionRequestResult, error) {
+ return copilot.PermissionRequestResult{Kind: "approved"}, nil
+ },
+})
+```
+
+
+
+
+.NET
+
+
+```csharp
+using GitHub.Copilot.SDK;
+
+public static class HooksExample
+{
+ static Task onSessionStart(SessionStartHookInput input, HookInvocation invocation) =>
+ Task.FromResult(null);
+ static Task onPreToolUse(PreToolUseHookInput input, HookInvocation invocation) =>
+ Task.FromResult(null);
+ static Task onPostToolUse(PostToolUseHookInput input, HookInvocation invocation) =>
+ Task.FromResult(null);
+
+ public static async Task Main()
+ {
+ var client = new CopilotClient();
+
+ var session = await client.CreateSessionAsync(new SessionConfig
+ {
+ Hooks = new SessionHooks
+ {
+ OnSessionStart = onSessionStart,
+ OnPreToolUse = onPreToolUse,
+ OnPostToolUse = onPostToolUse,
+ },
+ OnPermissionRequest = (req, inv) =>
+ Task.FromResult(new PermissionRequestResult { Kind = PermissionRequestResultKind.Approved }),
+ });
+ }
+}
+```
+
+
+```csharp
+var client = new CopilotClient();
+
+var session = await client.CreateSessionAsync(new SessionConfig
+{
+ Hooks = new SessionHooks
+ {
+ OnSessionStart = onSessionStart,
+ OnPreToolUse = onPreToolUse,
+ OnPostToolUse = onPostToolUse,
+ // ... add only the hooks you need
+ },
+ OnPermissionRequest = (req, inv) =>
+ Task.FromResult(new PermissionRequestResult { Kind = PermissionRequestResultKind.Approved }),
+});
+```
+
+
+
+> **Tip:** Every hook handler receives an `invocation` parameter containing the `sessionId`, which is useful for correlating logs and maintaining per-session state.
+
+---
+
+## Use Case: Permission Control
+
+Use `onPreToolUse` to build a permission layer that decides which tools the agent may run, what arguments are allowed, and whether the user should be prompted before execution.
+
+### Allow-list a safe set of tools
+
+
+Node.js / TypeScript
+
+```typescript
+const READ_ONLY_TOOLS = ["read_file", "glob", "grep", "view"];
+
+const session = await client.createSession({
+ hooks: {
+ onPreToolUse: async (input) => {
+ if (!READ_ONLY_TOOLS.includes(input.toolName)) {
+ return {
+ permissionDecision: "deny",
+ permissionDecisionReason:
+ `Only read-only tools are allowed. "${input.toolName}" was blocked.`,
+ };
+ }
+ return { permissionDecision: "allow" };
+ },
+ },
+ onPermissionRequest: async () => ({ kind: "approved" }),
+});
+```
+
+
+
+
+Python
+
+```python
+READ_ONLY_TOOLS = ["read_file", "glob", "grep", "view"]
+
+async def on_pre_tool_use(input_data, invocation):
+ if input_data["toolName"] not in READ_ONLY_TOOLS:
+ return {
+ "permissionDecision": "deny",
+ "permissionDecisionReason":
+ f'Only read-only tools are allowed. "{input_data["toolName"]}" was blocked.',
+ }
+ return {"permissionDecision": "allow"}
+
+session = await client.create_session(
+ on_permission_request=lambda req, inv: {"kind": "approved"},
+ hooks={"on_pre_tool_use": on_pre_tool_use},
+)
+```
+
+
+
+
+Go
+
+
+```go
+package main
+
+import (
+ "context"
+ "fmt"
+ copilot "github.com/github/copilot-sdk/go"
+)
+
+func main() {
+ ctx := context.Background()
+ client := copilot.NewClient(nil)
+
+ readOnlyTools := map[string]bool{"read_file": true, "glob": true, "grep": true, "view": true}
+
+ session, _ := client.CreateSession(ctx, &copilot.SessionConfig{
+ Hooks: &copilot.SessionHooks{
+ OnPreToolUse: func(input copilot.PreToolUseHookInput, inv copilot.HookInvocation) (*copilot.PreToolUseHookOutput, error) {
+ if !readOnlyTools[input.ToolName] {
+ return &copilot.PreToolUseHookOutput{
+ PermissionDecision: "deny",
+ PermissionDecisionReason: fmt.Sprintf("Only read-only tools are allowed. %q was blocked.", input.ToolName),
+ }, nil
+ }
+ return &copilot.PreToolUseHookOutput{PermissionDecision: "allow"}, nil
+ },
+ },
+ OnPermissionRequest: func(req copilot.PermissionRequest, inv copilot.PermissionInvocation) (copilot.PermissionRequestResult, error) {
+ return copilot.PermissionRequestResult{Kind: copilot.PermissionRequestResultKindApproved}, nil
+ },
+ })
+ _ = session
+}
+```
+
+
+```go
+readOnlyTools := map[string]bool{"read_file": true, "glob": true, "grep": true, "view": true}
+
+session, _ := client.CreateSession(ctx, &copilot.SessionConfig{
+ Hooks: &copilot.SessionHooks{
+ OnPreToolUse: func(input copilot.PreToolUseHookInput, inv copilot.HookInvocation) (*copilot.PreToolUseHookOutput, error) {
+ if !readOnlyTools[input.ToolName] {
+ return &copilot.PreToolUseHookOutput{
+ PermissionDecision: "deny",
+ PermissionDecisionReason: fmt.Sprintf("Only read-only tools are allowed. %q was blocked.", input.ToolName),
+ }, nil
+ }
+ return &copilot.PreToolUseHookOutput{PermissionDecision: "allow"}, nil
+ },
+ },
+})
+```
+
+
+
+
+.NET
+
+
+```csharp
+using GitHub.Copilot.SDK;
+
+public static class PermissionControlExample
+{
+ public static async Task Main()
+ {
+ await using var client = new CopilotClient();
+
+ var readOnlyTools = new HashSet { "read_file", "glob", "grep", "view" };
+
+ var session = await client.CreateSessionAsync(new SessionConfig
+ {
+ Hooks = new SessionHooks
+ {
+ OnPreToolUse = (input, invocation) =>
+ {
+ if (!readOnlyTools.Contains(input.ToolName))
+ {
+ return Task.FromResult(new PreToolUseHookOutput
+ {
+ PermissionDecision = "deny",
+ PermissionDecisionReason = $"Only read-only tools are allowed. \"{input.ToolName}\" was blocked.",
+ });
+ }
+ return Task.FromResult(
+ new PreToolUseHookOutput { PermissionDecision = "allow" });
+ },
+ },
+ OnPermissionRequest = (req, inv) =>
+ Task.FromResult(new PermissionRequestResult { Kind = PermissionRequestResultKind.Approved }),
+ });
+ }
+}
+```
+
+
+```csharp
+var readOnlyTools = new HashSet { "read_file", "glob", "grep", "view" };
+
+var session = await client.CreateSessionAsync(new SessionConfig
+{
+ Hooks = new SessionHooks
+ {
+ OnPreToolUse = (input, invocation) =>
+ {
+ if (!readOnlyTools.Contains(input.ToolName))
+ {
+ return Task.FromResult(new PreToolUseHookOutput
+ {
+ PermissionDecision = "deny",
+ PermissionDecisionReason = $"Only read-only tools are allowed. \"{input.ToolName}\" was blocked.",
+ });
+ }
+ return Task.FromResult(
+ new PreToolUseHookOutput { PermissionDecision = "allow" });
+ },
+ },
+});
+```
+
+
+
+### Restrict file access to specific directories
+
+```typescript
+const ALLOWED_DIRS = ["/home/user/projects", "/tmp"];
+
+const session = await client.createSession({
+ hooks: {
+ onPreToolUse: async (input) => {
+ if (["read_file", "write_file", "edit"].includes(input.toolName)) {
+ const filePath = (input.toolArgs as { path: string }).path;
+ const allowed = ALLOWED_DIRS.some((dir) => filePath.startsWith(dir));
+
+ if (!allowed) {
+ return {
+ permissionDecision: "deny",
+ permissionDecisionReason:
+ `Access to "${filePath}" is outside the allowed directories.`,
+ };
+ }
+ }
+ return { permissionDecision: "allow" };
+ },
+ },
+ onPermissionRequest: async () => ({ kind: "approved" }),
+});
+```
+
+### Ask the user before destructive operations
+
+```typescript
+const DESTRUCTIVE_TOOLS = ["delete_file", "shell", "bash"];
+
+const session = await client.createSession({
+ hooks: {
+ onPreToolUse: async (input) => {
+ if (DESTRUCTIVE_TOOLS.includes(input.toolName)) {
+ return { permissionDecision: "ask" };
+ }
+ return { permissionDecision: "allow" };
+ },
+ },
+ onPermissionRequest: async () => ({ kind: "approved" }),
+});
+```
+
+Returning `"ask"` delegates the decision to the user at runtime — useful for destructive actions where you want a human in the loop.
+
+---
+
+## Use Case: Auditing & Compliance
+
+Combine `onPreToolUse`, `onPostToolUse`, and the session lifecycle hooks to build a complete audit trail that records every action the agent takes.
+
+### Structured audit log
+
+
+Node.js / TypeScript
+
+```typescript
+interface AuditEntry {
+ timestamp: number;
+ sessionId: string;
+ event: string;
+ toolName?: string;
+ toolArgs?: unknown;
+ toolResult?: unknown;
+ prompt?: string;
+}
+
+const auditLog: AuditEntry[] = [];
+
+const session = await client.createSession({
+ hooks: {
+ onSessionStart: async (input, invocation) => {
+ auditLog.push({
+ timestamp: input.timestamp,
+ sessionId: invocation.sessionId,
+ event: "session_start",
+ });
+ return null;
+ },
+ onUserPromptSubmitted: async (input, invocation) => {
+ auditLog.push({
+ timestamp: input.timestamp,
+ sessionId: invocation.sessionId,
+ event: "user_prompt",
+ prompt: input.prompt,
+ });
+ return null;
+ },
+ onPreToolUse: async (input, invocation) => {
+ auditLog.push({
+ timestamp: input.timestamp,
+ sessionId: invocation.sessionId,
+ event: "tool_call",
+ toolName: input.toolName,
+ toolArgs: input.toolArgs,
+ });
+ return { permissionDecision: "allow" };
+ },
+ onPostToolUse: async (input, invocation) => {
+ auditLog.push({
+ timestamp: input.timestamp,
+ sessionId: invocation.sessionId,
+ event: "tool_result",
+ toolName: input.toolName,
+ toolResult: input.toolResult,
+ });
+ return null;
+ },
+ onSessionEnd: async (input, invocation) => {
+ auditLog.push({
+ timestamp: input.timestamp,
+ sessionId: invocation.sessionId,
+ event: "session_end",
+ });
+
+ // Persist the log — swap this with your own storage backend
+ await fs.promises.writeFile(
+ `audit-${invocation.sessionId}.json`,
+ JSON.stringify(auditLog, null, 2),
+ );
+ return null;
+ },
+ },
+ onPermissionRequest: async () => ({ kind: "approved" }),
+});
+```
+
+
+
+
+Python
+
+
+```python
+import json, aiofiles
+
+audit_log = []
+
+async def on_session_start(input_data, invocation):
+ audit_log.append({
+ "timestamp": input_data["timestamp"],
+ "session_id": invocation["session_id"],
+ "event": "session_start",
+ })
+ return None
+
+async def on_user_prompt_submitted(input_data, invocation):
+ audit_log.append({
+ "timestamp": input_data["timestamp"],
+ "session_id": invocation["session_id"],
+ "event": "user_prompt",
+ "prompt": input_data["prompt"],
+ })
+ return None
+
+async def on_pre_tool_use(input_data, invocation):
+ audit_log.append({
+ "timestamp": input_data["timestamp"],
+ "session_id": invocation["session_id"],
+ "event": "tool_call",
+ "tool_name": input_data["toolName"],
+ "tool_args": input_data["toolArgs"],
+ })
+ return {"permissionDecision": "allow"}
+
+async def on_post_tool_use(input_data, invocation):
+ audit_log.append({
+ "timestamp": input_data["timestamp"],
+ "session_id": invocation["session_id"],
+ "event": "tool_result",
+ "tool_name": input_data["toolName"],
+ "tool_result": input_data["toolResult"],
+ })
+ return None
+
+async def on_session_end(input_data, invocation):
+ audit_log.append({
+ "timestamp": input_data["timestamp"],
+ "session_id": invocation["session_id"],
+ "event": "session_end",
+ })
+ async with aiofiles.open(f"audit-{invocation['session_id']}.json", "w") as f:
+ await f.write(json.dumps(audit_log, indent=2))
+ return None
+
+session = await client.create_session(
+ on_permission_request=lambda req, inv: {"kind": "approved"},
+ hooks={
+ "on_session_start": on_session_start,
+ "on_user_prompt_submitted": on_user_prompt_submitted,
+ "on_pre_tool_use": on_pre_tool_use,
+ "on_post_tool_use": on_post_tool_use,
+ "on_session_end": on_session_end,
+ },
+)
+```
+
+
+
+### Redact secrets from tool results
+
+```typescript
+const SECRET_PATTERNS = [
+ /(?:api[_-]?key|token|secret|password)\s*[:=]\s*["']?[\w\-\.]+["']?/gi,
+];
+
+const session = await client.createSession({
+ hooks: {
+ onPostToolUse: async (input) => {
+ if (typeof input.toolResult !== "string") return null;
+
+ let redacted = input.toolResult;
+ for (const pattern of SECRET_PATTERNS) {
+ redacted = redacted.replace(pattern, "[REDACTED]");
+ }
+
+ return redacted !== input.toolResult
+ ? { modifiedResult: redacted }
+ : null;
+ },
+ },
+ onPermissionRequest: async () => ({ kind: "approved" }),
+});
+```
+
+---
+
+## Use Case: Notifications & Sounds
+
+Hooks fire in your application's process, so you can trigger any side-effect — desktop notifications, sounds, Slack messages, or webhook calls.
+
+### Desktop notification on session events
+
+
+Node.js / TypeScript
+
+```typescript
+import notifier from "node-notifier"; // npm install node-notifier
+
+const session = await client.createSession({
+ hooks: {
+ onSessionEnd: async (input, invocation) => {
+ notifier.notify({
+ title: "Copilot Session Complete",
+ message: `Session ${invocation.sessionId.slice(0, 8)} finished (${input.reason}).`,
+ });
+ return null;
+ },
+ onErrorOccurred: async (input) => {
+ notifier.notify({
+ title: "Copilot Error",
+ message: input.error.slice(0, 200),
+ });
+ return null;
+ },
+ },
+ onPermissionRequest: async () => ({ kind: "approved" }),
+});
+```
+
+
+
+
+Python
+
+```python
+import subprocess
+
+async def on_session_end(input_data, invocation):
+ sid = invocation["session_id"][:8]
+ reason = input_data["reason"]
+ subprocess.Popen([
+ "notify-send", "Copilot Session Complete",
+ f"Session {sid} finished ({reason}).",
+ ])
+ return None
+
+async def on_error_occurred(input_data, invocation):
+ subprocess.Popen([
+ "notify-send", "Copilot Error",
+ input_data["error"][:200],
+ ])
+ return None
+
+session = await client.create_session(
+ on_permission_request=lambda req, inv: {"kind": "approved"},
+ hooks={
+ "on_session_end": on_session_end,
+ "on_error_occurred": on_error_occurred,
+ },
+)
+```
+
+
+
+### Play a sound when a tool finishes
+
+```typescript
+import { exec } from "node:child_process";
+
+const session = await client.createSession({
+ hooks: {
+ onPostToolUse: async (input) => {
+ // macOS: play a system sound after every tool call
+ exec("afplay /System/Library/Sounds/Pop.aiff");
+ return null;
+ },
+ onErrorOccurred: async () => {
+ exec("afplay /System/Library/Sounds/Basso.aiff");
+ return null;
+ },
+ },
+ onPermissionRequest: async () => ({ kind: "approved" }),
+});
+```
+
+### Post to Slack on errors
+
+```typescript
+const SLACK_WEBHOOK_URL = process.env.SLACK_WEBHOOK_URL!;
+
+const session = await client.createSession({
+ hooks: {
+ onErrorOccurred: async (input, invocation) => {
+ if (!input.recoverable) {
+ await fetch(SLACK_WEBHOOK_URL, {
+ method: "POST",
+ headers: { "Content-Type": "application/json" },
+ body: JSON.stringify({
+ text: `🚨 Unrecoverable error in session \`${invocation.sessionId.slice(0, 8)}\`:\n\`\`\`${input.error}\`\`\``,
+ }),
+ });
+ }
+ return null;
+ },
+ },
+ onPermissionRequest: async () => ({ kind: "approved" }),
+});
+```
+
+---
+
+## Use Case: Prompt Enrichment
+
+Use `onSessionStart` and `onUserPromptSubmitted` to automatically inject context so users don't have to repeat themselves.
+
+### Inject project metadata at session start
+
+```typescript
+const session = await client.createSession({
+ hooks: {
+ onSessionStart: async (input) => {
+ const pkg = JSON.parse(
+ await fs.promises.readFile("package.json", "utf-8"),
+ );
+ return {
+ additionalContext: [
+ `Project: ${pkg.name} v${pkg.version}`,
+ `Node: ${process.version}`,
+ `CWD: ${input.cwd}`,
+ ].join("\n"),
+ };
+ },
+ },
+ onPermissionRequest: async () => ({ kind: "approved" }),
+});
+```
+
+### Expand shorthand commands in prompts
+
+```typescript
+const SHORTCUTS: Record = {
+ "/fix": "Find and fix all errors in the current file",
+ "/test": "Write comprehensive unit tests for this code",
+ "/explain": "Explain this code in detail",
+ "/refactor": "Refactor this code to improve readability",
+};
+
+const session = await client.createSession({
+ hooks: {
+ onUserPromptSubmitted: async (input) => {
+ for (const [shortcut, expansion] of Object.entries(SHORTCUTS)) {
+ if (input.prompt.startsWith(shortcut)) {
+ const rest = input.prompt.slice(shortcut.length).trim();
+ return { modifiedPrompt: rest ? `${expansion}: ${rest}` : expansion };
+ }
+ }
+ return null;
+ },
+ },
+ onPermissionRequest: async () => ({ kind: "approved" }),
+});
+```
+
+---
+
+## Use Case: Error Handling & Recovery
+
+The `onErrorOccurred` hook gives you a chance to react to failures — whether that means retrying, notifying a human, or gracefully shutting down.
+
+### Retry transient model errors
+
+```typescript
+const session = await client.createSession({
+ hooks: {
+ onErrorOccurred: async (input) => {
+ if (input.errorContext === "model_call" && input.recoverable) {
+ return {
+ errorHandling: "retry",
+ retryCount: 3,
+ userNotification: "Temporary model issue — retrying…",
+ };
+ }
+ return null;
+ },
+ },
+ onPermissionRequest: async () => ({ kind: "approved" }),
+});
+```
+
+### Friendly error messages
+
+```typescript
+const FRIENDLY_MESSAGES: Record = {
+ model_call: "The AI model is temporarily unavailable. Please try again.",
+ tool_execution: "A tool encountered an error. Check inputs and try again.",
+ system: "A system error occurred. Please try again later.",
+};
+
+const session = await client.createSession({
+ hooks: {
+ onErrorOccurred: async (input) => {
+ return {
+ userNotification: FRIENDLY_MESSAGES[input.errorContext] ?? input.error,
+ };
+ },
+ },
+ onPermissionRequest: async () => ({ kind: "approved" }),
+});
+```
+
+---
+
+## Use Case: Session Metrics
+
+Track how long sessions run, how many tools are invoked, and why sessions end — useful for dashboards and cost monitoring.
+
+
+Node.js / TypeScript
+
+```typescript
+const metrics = new Map();
+
+const session = await client.createSession({
+ hooks: {
+ onSessionStart: async (input, invocation) => {
+ metrics.set(invocation.sessionId, {
+ start: input.timestamp,
+ toolCalls: 0,
+ prompts: 0,
+ });
+ return null;
+ },
+ onUserPromptSubmitted: async (_input, invocation) => {
+ metrics.get(invocation.sessionId)!.prompts++;
+ return null;
+ },
+ onPreToolUse: async (_input, invocation) => {
+ metrics.get(invocation.sessionId)!.toolCalls++;
+ return { permissionDecision: "allow" };
+ },
+ onSessionEnd: async (input, invocation) => {
+ const m = metrics.get(invocation.sessionId)!;
+ const durationSec = (input.timestamp - m.start) / 1000;
+
+ console.log(
+ `Session ${invocation.sessionId.slice(0, 8)}: ` +
+ `${durationSec.toFixed(1)}s, ${m.prompts} prompts, ` +
+ `${m.toolCalls} tool calls, ended: ${input.reason}`,
+ );
+
+ metrics.delete(invocation.sessionId);
+ return null;
+ },
+ },
+ onPermissionRequest: async () => ({ kind: "approved" }),
+});
+```
+
+
+
+
+Python
+
+```python
+session_metrics = {}
+
+async def on_session_start(input_data, invocation):
+ session_metrics[invocation["session_id"]] = {
+ "start": input_data["timestamp"],
+ "tool_calls": 0,
+ "prompts": 0,
+ }
+ return None
+
+async def on_user_prompt_submitted(input_data, invocation):
+ session_metrics[invocation["session_id"]]["prompts"] += 1
+ return None
+
+async def on_pre_tool_use(input_data, invocation):
+ session_metrics[invocation["session_id"]]["tool_calls"] += 1
+ return {"permissionDecision": "allow"}
+
+async def on_session_end(input_data, invocation):
+ m = session_metrics.pop(invocation["session_id"])
+ duration = (input_data["timestamp"] - m["start"]) / 1000
+ sid = invocation["session_id"][:8]
+ print(
+ f"Session {sid}: {duration:.1f}s, {m['prompts']} prompts, "
+ f"{m['tool_calls']} tool calls, ended: {input_data['reason']}"
+ )
+ return None
+
+session = await client.create_session(
+ on_permission_request=lambda req, inv: {"kind": "approved"},
+ hooks={
+ "on_session_start": on_session_start,
+ "on_user_prompt_submitted": on_user_prompt_submitted,
+ "on_pre_tool_use": on_pre_tool_use,
+ "on_session_end": on_session_end,
+ },
+)
+```
+
+
+
+---
+
+## Combining Hooks
+
+Hooks compose naturally. A single `hooks` object can handle permissions **and** auditing **and** notifications — each hook does its own job.
+
+```typescript
+const session = await client.createSession({
+ hooks: {
+ onSessionStart: async (input) => {
+ console.log(`[audit] session started in ${input.cwd}`);
+ return { additionalContext: "Project uses TypeScript and Vitest." };
+ },
+ onPreToolUse: async (input) => {
+ console.log(`[audit] tool requested: ${input.toolName}`);
+ if (input.toolName === "shell") {
+ return { permissionDecision: "ask" };
+ }
+ return { permissionDecision: "allow" };
+ },
+ onPostToolUse: async (input) => {
+ console.log(`[audit] tool completed: ${input.toolName}`);
+ return null;
+ },
+ onErrorOccurred: async (input) => {
+ console.error(`[alert] ${input.errorContext}: ${input.error}`);
+ return null;
+ },
+ onSessionEnd: async (input, invocation) => {
+ console.log(`[audit] session ${invocation.sessionId.slice(0, 8)} ended: ${input.reason}`);
+ return null;
+ },
+ },
+ onPermissionRequest: async () => ({ kind: "approved" }),
+});
+```
+
+## Best Practices
+
+1. **Keep hooks fast.** Every hook runs inline — slow hooks delay the conversation. Offload heavy work (database writes, HTTP calls) to a background queue when possible.
+
+2. **Return `null` when you have nothing to change.** This tells the SDK to proceed with defaults and avoids unnecessary object allocation.
+
+3. **Be explicit with permission decisions.** Returning `{ permissionDecision: "allow" }` is clearer than returning `null`, even though both allow the tool.
+
+4. **Don't swallow critical errors.** It's fine to suppress recoverable tool errors, but always log or alert on unrecoverable ones.
+
+5. **Use `additionalContext` instead of `modifiedPrompt` when possible.** Appending context preserves the user's original intent while still guiding the model.
+
+6. **Scope state by session ID.** If you track per-session data, key it on `invocation.sessionId` and clean up in `onSessionEnd`.
+
+## Reference
+
+For full type definitions, input/output field tables, and additional examples for every hook, see the API reference:
+
+- [Hooks Overview](../hooks/index.md)
+- [Pre-Tool Use](../hooks/pre-tool-use.md)
+- [Post-Tool Use](../hooks/post-tool-use.md)
+- [User Prompt Submitted](../hooks/user-prompt-submitted.md)
+- [Session Lifecycle](../hooks/session-lifecycle.md)
+- [Error Handling](../hooks/error-handling.md)
+
+## See Also
+
+- [Getting Started](../getting-started.md)
+- [Custom Agents & Sub-Agent Orchestration](./custom-agents.md)
+- [Streaming Session Events](./streaming-events.md)
+- [Debugging Guide](../troubleshooting/debugging.md)
diff --git a/docs/features/image-input.md b/docs/features/image-input.md
new file mode 100644
index 0000000000..8295b83d71
--- /dev/null
+++ b/docs/features/image-input.md
@@ -0,0 +1,480 @@
+# Image Input
+
+Send images to Copilot sessions as attachments. There are two ways to attach images:
+
+- **File attachment** (`type: "file"`) — provide an absolute path; the runtime reads the file from disk, converts it to base64, and sends it to the LLM.
+- **Blob attachment** (`type: "blob"`) — provide base64-encoded data directly; useful when the image is already in memory (e.g., screenshots, generated images, or data from an API).
+
+## Overview
+
+```mermaid
+sequenceDiagram
+ participant App as Your App
+ participant SDK as SDK Session
+ participant RT as Copilot Runtime
+ participant LLM as Vision Model
+
+ App->>SDK: send({ prompt, attachments: [{ type: "file", path }] })
+ SDK->>RT: JSON-RPC with file attachment
+ RT->>RT: Read file from disk
+ RT->>RT: Detect image, convert to base64
+ RT->>RT: Resize if needed (model-specific limits)
+ RT->>LLM: image_url content block (base64)
+ LLM-->>RT: Response referencing the image
+ RT-->>SDK: assistant.message events
+ SDK-->>App: event stream
+```
+
+| Concept | Description |
+|---------|-------------|
+| **File attachment** | An attachment with `type: "file"` and an absolute `path` to an image on disk |
+| **Blob attachment** | An attachment with `type: "blob"`, base64-encoded `data`, and a `mimeType` — no disk I/O needed |
+| **Automatic encoding** | For file attachments, the runtime reads the image and converts it to base64 automatically |
+| **Auto-resize** | The runtime automatically resizes or quality-reduces images that exceed model-specific limits |
+| **Vision capability** | The model must have `capabilities.supports.vision = true` to process images |
+
+## Quick Start — File Attachment
+
+Attach an image file to any message using the file attachment type. The path must be an absolute path to an image on disk.
+
+
+Node.js / TypeScript
+
+```typescript
+import { CopilotClient } from "@github/copilot-sdk";
+
+const client = new CopilotClient();
+await client.start();
+
+const session = await client.createSession({
+ model: "gpt-4.1",
+ onPermissionRequest: async () => ({ kind: "approved" }),
+});
+
+await session.send({
+ prompt: "Describe what you see in this image",
+ attachments: [
+ {
+ type: "file",
+ path: "/absolute/path/to/screenshot.png",
+ },
+ ],
+});
+```
+
+
+
+
+Python
+
+```python
+from copilot import CopilotClient
+from copilot.types import PermissionRequestResult
+
+client = CopilotClient()
+await client.start()
+
+session = await client.create_session(
+ on_permission_request=lambda req, inv: PermissionRequestResult(kind="approved"),
+ model="gpt-4.1",
+)
+
+await session.send(
+ "Describe what you see in this image",
+ attachments=[
+ {
+ "type": "file",
+ "path": "/absolute/path/to/screenshot.png",
+ },
+ ],
+)
+```
+
+
+
+
+Go
+
+
+```go
+package main
+
+import (
+ "context"
+ copilot "github.com/github/copilot-sdk/go"
+)
+
+func main() {
+ ctx := context.Background()
+ client := copilot.NewClient(nil)
+ client.Start(ctx)
+
+ session, _ := client.CreateSession(ctx, &copilot.SessionConfig{
+ Model: "gpt-4.1",
+ OnPermissionRequest: func(req copilot.PermissionRequest, inv copilot.PermissionInvocation) (copilot.PermissionRequestResult, error) {
+ return copilot.PermissionRequestResult{Kind: copilot.PermissionRequestResultKindApproved}, nil
+ },
+ })
+
+ path := "/absolute/path/to/screenshot.png"
+ session.Send(ctx, copilot.MessageOptions{
+ Prompt: "Describe what you see in this image",
+ Attachments: []copilot.Attachment{
+ {
+ Type: copilot.AttachmentTypeFile,
+ Path: &path,
+ },
+ },
+ })
+}
+```
+
+
+```go
+ctx := context.Background()
+client := copilot.NewClient(nil)
+client.Start(ctx)
+
+session, _ := client.CreateSession(ctx, &copilot.SessionConfig{
+ Model: "gpt-4.1",
+ OnPermissionRequest: func(req copilot.PermissionRequest, inv copilot.PermissionInvocation) (copilot.PermissionRequestResult, error) {
+ return copilot.PermissionRequestResult{Kind: copilot.PermissionRequestResultKindApproved}, nil
+ },
+})
+
+path := "/absolute/path/to/screenshot.png"
+session.Send(ctx, copilot.MessageOptions{
+ Prompt: "Describe what you see in this image",
+ Attachments: []copilot.Attachment{
+ {
+ Type: copilot.AttachmentTypeFile,
+ Path: &path,
+ },
+ },
+})
+```
+
+
+
+
+.NET
+
+
+```csharp
+using GitHub.Copilot.SDK;
+
+public static class ImageInputExample
+{
+ public static async Task Main()
+ {
+ await using var client = new CopilotClient();
+ await using var session = await client.CreateSessionAsync(new SessionConfig
+ {
+ Model = "gpt-4.1",
+ OnPermissionRequest = (req, inv) =>
+ Task.FromResult(new PermissionRequestResult { Kind = PermissionRequestResultKind.Approved }),
+ });
+
+ await session.SendAsync(new MessageOptions
+ {
+ Prompt = "Describe what you see in this image",
+ Attachments = new List
+ {
+ new UserMessageDataAttachmentsItemFile
+ {
+ Path = "/absolute/path/to/screenshot.png",
+ DisplayName = "screenshot.png",
+ },
+ },
+ });
+ }
+}
+```
+
+
+```csharp
+using GitHub.Copilot.SDK;
+
+await using var client = new CopilotClient();
+await using var session = await client.CreateSessionAsync(new SessionConfig
+{
+ Model = "gpt-4.1",
+ OnPermissionRequest = (req, inv) =>
+ Task.FromResult(new PermissionRequestResult { Kind = PermissionRequestResultKind.Approved }),
+});
+
+await session.SendAsync(new MessageOptions
+{
+ Prompt = "Describe what you see in this image",
+ Attachments = new List
+ {
+ new UserMessageDataAttachmentsItemFile
+ {
+ Path = "/absolute/path/to/screenshot.png",
+ DisplayName = "screenshot.png",
+ },
+ },
+});
+```
+
+
+
+## Quick Start — Blob Attachment
+
+When you already have image data in memory (e.g., a screenshot captured by your app, or an image fetched from an API), use a blob attachment to send it directly without writing to disk.
+
+
+Node.js / TypeScript
+
+```typescript
+import { CopilotClient } from "@github/copilot-sdk";
+
+const client = new CopilotClient();
+await client.start();
+
+const session = await client.createSession({
+ model: "gpt-4.1",
+ onPermissionRequest: async () => ({ kind: "approved" }),
+});
+
+const base64ImageData = "..."; // your base64-encoded image
+await session.send({
+ prompt: "Describe what you see in this image",
+ attachments: [
+ {
+ type: "blob",
+ data: base64ImageData,
+ mimeType: "image/png",
+ displayName: "screenshot.png",
+ },
+ ],
+});
+```
+
+
+
+
+Python
+
+```python
+from copilot import CopilotClient
+from copilot.types import PermissionRequestResult
+
+client = CopilotClient()
+await client.start()
+
+session = await client.create_session({
+ "model": "gpt-4.1",
+ "on_permission_request": lambda req, inv: PermissionRequestResult(kind="approved"),
+})
+
+base64_image_data = "..." # your base64-encoded image
+await session.send(
+ "Describe what you see in this image",
+ attachments=[
+ {
+ "type": "blob",
+ "data": base64_image_data,
+ "mimeType": "image/png",
+ "displayName": "screenshot.png",
+ },
+ ],
+)
+```
+
+
+
+
+Go
+
+
+```go
+package main
+
+import (
+ "context"
+ copilot "github.com/github/copilot-sdk/go"
+)
+
+func main() {
+ ctx := context.Background()
+ client := copilot.NewClient(nil)
+ client.Start(ctx)
+
+ session, _ := client.CreateSession(ctx, &copilot.SessionConfig{
+ Model: "gpt-4.1",
+ OnPermissionRequest: func(req copilot.PermissionRequest, inv copilot.PermissionInvocation) (copilot.PermissionRequestResult, error) {
+ return copilot.PermissionRequestResult{Kind: copilot.PermissionRequestResultKindApproved}, nil
+ },
+ })
+
+ base64ImageData := "..."
+ mimeType := "image/png"
+ displayName := "screenshot.png"
+ session.Send(ctx, copilot.MessageOptions{
+ Prompt: "Describe what you see in this image",
+ Attachments: []copilot.Attachment{
+ {
+ Type: copilot.AttachmentTypeBlob,
+ Data: &base64ImageData,
+ MIMEType: &mimeType,
+ DisplayName: &displayName,
+ },
+ },
+ })
+}
+```
+
+
+```go
+mimeType := "image/png"
+displayName := "screenshot.png"
+session.Send(ctx, copilot.MessageOptions{
+ Prompt: "Describe what you see in this image",
+ Attachments: []copilot.Attachment{
+ {
+ Type: copilot.AttachmentTypeBlob,
+ Data: &base64ImageData, // base64-encoded string
+ MIMEType: &mimeType,
+ DisplayName: &displayName,
+ },
+ },
+})
+```
+
+
+
+
+.NET
+
+
+```csharp
+using GitHub.Copilot.SDK;
+
+public static class BlobAttachmentExample
+{
+ public static async Task Main()
+ {
+ await using var client = new CopilotClient();
+ await using var session = await client.CreateSessionAsync(new SessionConfig
+ {
+ Model = "gpt-4.1",
+ OnPermissionRequest = (req, inv) =>
+ Task.FromResult(new PermissionRequestResult { Kind = PermissionRequestResultKind.Approved }),
+ });
+
+ var base64ImageData = "...";
+ await session.SendAsync(new MessageOptions
+ {
+ Prompt = "Describe what you see in this image",
+ Attachments = new List
+ {
+ new UserMessageDataAttachmentsItemBlob
+ {
+ Data = base64ImageData,
+ MimeType = "image/png",
+ DisplayName = "screenshot.png",
+ },
+ },
+ });
+ }
+}
+```
+
+
+```csharp
+await session.SendAsync(new MessageOptions
+{
+ Prompt = "Describe what you see in this image",
+ Attachments = new List
+ {
+ new UserMessageDataAttachmentsItemBlob
+ {
+ Data = base64ImageData,
+ MimeType = "image/png",
+ DisplayName = "screenshot.png",
+ },
+ },
+});
+```
+
+
+
+## Supported Formats
+
+Supported image formats include JPG, PNG, GIF, and other common image types. For file attachments, the runtime reads the image from disk and converts it as needed. For blob attachments, you provide the base64 data and MIME type directly. Use PNG or JPEG for best results, as these are the most widely supported formats.
+
+The model's `capabilities.limits.vision.supported_media_types` field lists the exact MIME types it accepts.
+
+## Automatic Processing
+
+The runtime automatically processes images to fit within the model's constraints. No manual resizing is required.
+
+- Images that exceed the model's dimension or size limits are automatically resized (preserving aspect ratio) or quality-reduced.
+- If an image cannot be brought within limits after processing, it is skipped and not sent to the LLM.
+- The model's `capabilities.limits.vision.max_prompt_image_size` field indicates the maximum image size in bytes.
+
+You can check these limits at runtime via the model capabilities object. For the best experience, use reasonably-sized PNG or JPEG images.
+
+## Vision Model Capabilities
+
+Not all models support vision. Check the model's capabilities before sending images.
+
+### Capability fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `capabilities.supports.vision` | `boolean` | Whether the model can process image inputs |
+| `capabilities.limits.vision.supported_media_types` | `string[]` | MIME types the model accepts (e.g., `["image/png", "image/jpeg"]`) |
+| `capabilities.limits.vision.max_prompt_images` | `number` | Maximum number of images per prompt |
+| `capabilities.limits.vision.max_prompt_image_size` | `number` | Maximum image size in bytes |
+
+### Vision limits type
+
+
+```typescript
+interface VisionCapabilities {
+ vision?: {
+ supported_media_types: string[];
+ max_prompt_images: number;
+ max_prompt_image_size: number; // bytes
+ };
+}
+```
+
+```typescript
+vision?: {
+ supported_media_types: string[];
+ max_prompt_images: number;
+ max_prompt_image_size: number; // bytes
+};
+```
+
+## Receiving Image Results
+
+When tools return images (e.g., screenshots or generated charts), the result contains `"image"` content blocks with base64-encoded data.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `type` | `"image"` | Content block type discriminator |
+| `data` | `string` | Base64-encoded image data |
+| `mimeType` | `string` | MIME type (e.g., `"image/png"`) |
+
+These image blocks appear in `tool.execution_complete` event results. See the [Streaming Events](./streaming-events.md) guide for the full event lifecycle.
+
+## Tips & Limitations
+
+| Tip | Details |
+|-----|---------|
+| **Use PNG or JPEG directly** | Avoids conversion overhead — these are sent to the LLM as-is |
+| **Keep images reasonably sized** | Large images may be quality-reduced, which can lose important details |
+| **Use absolute paths for file attachments** | The runtime reads files from disk; relative paths may not resolve correctly |
+| **Use blob attachments for in-memory data** | When you already have base64 data (e.g., screenshots, API responses), blob avoids unnecessary disk I/O |
+| **Check vision support first** | Sending images to a non-vision model wastes tokens without visual understanding |
+| **Multiple images are supported** | Attach several attachments in one message, up to the model's `max_prompt_images` limit |
+| **SVG is not supported** | SVG files are text-based and excluded from image processing |
+
+## See Also
+
+- [Streaming Events](./streaming-events.md) — event lifecycle including tool result content blocks
+- [Steering & Queueing](./steering-and-queueing.md) — sending follow-up messages with attachments
diff --git a/docs/features/index.md b/docs/features/index.md
new file mode 100644
index 0000000000..3eb63a799a
--- /dev/null
+++ b/docs/features/index.md
@@ -0,0 +1,25 @@
+# Features
+
+These guides cover the capabilities you can add to your Copilot SDK application. Each guide includes examples in all supported languages (TypeScript, Python, Go, and .NET).
+
+> **New to the SDK?** Start with the [Getting Started tutorial](../getting-started.md) first, then come back here to add more capabilities.
+
+## Guides
+
+| Feature | Description |
+|---|---|
+| [Hooks](./hooks.md) | Intercept and customize session behavior — control tool execution, transform results, handle errors |
+| [Custom Agents](./custom-agents.md) | Define specialized sub-agents with scoped tools and instructions |
+| [MCP Servers](./mcp.md) | Integrate Model Context Protocol servers for external tool access |
+| [Skills](./skills.md) | Load reusable prompt modules from directories |
+| [Image Input](./image-input.md) | Send images to sessions as attachments |
+| [Streaming Events](./streaming-events.md) | Subscribe to real-time session events (40+ event types) |
+| [Steering & Queueing](./steering-and-queueing.md) | Control message delivery — immediate steering vs. sequential queueing |
+| [Session Persistence](./session-persistence.md) | Resume sessions across restarts, manage session storage |
+
+## Related
+
+- [Hooks Reference](../hooks/index.md) — detailed API reference for each hook type
+- [Integrations](../integrations/microsoft-agent-framework.md) — use the SDK with other platforms (MAF, etc.)
+- [Troubleshooting](../troubleshooting/debugging.md) — when things don't work as expected
+- [Compatibility](../troubleshooting/compatibility.md) — SDK vs CLI feature matrix
diff --git a/docs/mcp/overview.md b/docs/features/mcp.md
similarity index 89%
rename from docs/mcp/overview.md
rename to docs/features/mcp.md
index 5ad8b1df39..62465c0bd7 100644
--- a/docs/mcp/overview.md
+++ b/docs/features/mcp.md
@@ -59,32 +59,29 @@ const session = await client.createSession({
```python
import asyncio
-from copilot import CopilotClient
+from copilot import CopilotClient, PermissionHandler
async def main():
client = CopilotClient()
await client.start()
- session = await client.create_session({
- "model": "gpt-5",
- "mcp_servers": {
- # Local MCP server (stdio)
- "my-local-server": {
- "type": "local",
- "command": "python",
- "args": ["./mcp_server.py"],
- "env": {"DEBUG": "true"},
- "cwd": "./servers",
- "tools": ["*"],
- "timeout": 30000,
- },
- # Remote MCP server (HTTP)
- "github": {
- "type": "http",
- "url": "https://api.githubcopilot.com/mcp/",
- "headers": {"Authorization": "Bearer ${TOKEN}"},
- "tools": ["*"],
- },
+ session = await client.create_session(on_permission_request=PermissionHandler.approve_all, model="gpt-5", mcp_servers={
+ # Local MCP server (stdio)
+ "my-local-server": {
+ "type": "local",
+ "command": "python",
+ "args": ["./mcp_server.py"],
+ "env": {"DEBUG": "true"},
+ "cwd": "./servers",
+ "tools": ["*"],
+ "timeout": 30000,
+ },
+ # Remote MCP server (HTTP)
+ "github": {
+ "type": "http",
+ "url": "https://api.githubcopilot.com/mcp/",
+ "headers": {"Authorization": "Bearer ${TOKEN}"},
+ "tools": ["*"],
},
})
@@ -258,7 +255,7 @@ directories for different applications.
| "Timeout" errors | Increase the `timeout` value or check server performance |
| Tools work but aren't called | Ensure your prompt clearly requires the tool's functionality |
-For detailed debugging guidance, see the **[MCP Debugging Guide](./debugging.md)**.
+For detailed debugging guidance, see the **[MCP Debugging Guide](../troubleshooting/mcp-debugging.md)**.
## Related Resources
@@ -266,10 +263,10 @@ For detailed debugging guidance, see the **[MCP Debugging Guide](./debugging.md)
- [MCP Servers Directory](https://github.com/modelcontextprotocol/servers) - Community MCP servers
- [GitHub MCP Server](https://github.com/github/github-mcp-server) - Official GitHub MCP server
- [Getting Started Guide](../getting-started.md) - SDK basics and custom tools
-- [General Debugging Guide](../debugging.md) - SDK-wide debugging
+- [General Debugging Guide](.../troubleshooting/mcp-debugging.md) - SDK-wide debugging
## See Also
-- [MCP Debugging Guide](./debugging.md) - Detailed MCP troubleshooting
+- [MCP Debugging Guide](../troubleshooting/mcp-debugging.md) - Detailed MCP troubleshooting
- [Issue #9](https://github.com/github/copilot-sdk/issues/9) - Original MCP tools usage question
- [Issue #36](https://github.com/github/copilot-sdk/issues/36) - MCP documentation tracking issue
diff --git a/docs/guides/session-persistence.md b/docs/features/session-persistence.md
similarity index 87%
rename from docs/guides/session-persistence.md
rename to docs/features/session-persistence.md
index e2b736c1b5..3b0e9f69b9 100644
--- a/docs/guides/session-persistence.md
+++ b/docs/features/session-persistence.md
@@ -46,16 +46,13 @@ await session.sendAndWait({ prompt: "Analyze my codebase" });
### Python
```python
-from copilot import CopilotClient
+from copilot import CopilotClient, PermissionHandler
client = CopilotClient()
await client.start()
# Create a session with a meaningful ID
-session = await client.create_session({
- "session_id": "user-123-task-456",
- "model": "gpt-5.2-codex",
-})
+session = await client.create_session(on_permission_request=PermissionHandler.approve_all, model="gpt-5.2-codex", session_id="user-123-task-456")
# Do some work...
await session.send_and_wait({"prompt": "Analyze my codebase"})
@@ -65,7 +62,33 @@ await session.send_and_wait({"prompt": "Analyze my codebase"})
### Go
-
+
+```go
+package main
+
+import (
+ "context"
+ copilot "github.com/github/copilot-sdk/go"
+)
+
+func main() {
+ ctx := context.Background()
+ client := copilot.NewClient(nil)
+
+ session, _ := client.CreateSession(ctx, &copilot.SessionConfig{
+ SessionID: "user-123-task-456",
+ Model: "gpt-5.2-codex",
+ OnPermissionRequest: func(req copilot.PermissionRequest, inv copilot.PermissionInvocation) (copilot.PermissionRequestResult, error) {
+ return copilot.PermissionRequestResult{Kind: copilot.PermissionRequestResultKindApproved}, nil
+ },
+ })
+
+ session.SendAndWait(ctx, copilot.MessageOptions{Prompt: "Analyze my codebase"})
+ _ = session
+}
+```
+
+
```go
ctx := context.Background()
client := copilot.NewClient(nil)
@@ -134,7 +157,7 @@ await session.sendAndWait({ prompt: "What did we discuss earlier?" });
```python
# Resume from a different client instance (or after restart)
-session = await client.resume_session("user-123-task-456")
+session = await client.resume_session("user-123-task-456", on_permission_request=PermissionHandler.approve_all)
# Continue where you left off
await session.send_and_wait({"prompt": "What did we discuss earlier?"})
@@ -142,7 +165,27 @@ await session.send_and_wait({"prompt": "What did we discuss earlier?"})
### Go
-
+
+```go
+package main
+
+import (
+ "context"
+ copilot "github.com/github/copilot-sdk/go"
+)
+
+func main() {
+ ctx := context.Background()
+ client := copilot.NewClient(nil)
+
+ session, _ := client.ResumeSession(ctx, "user-123-task-456", nil)
+
+ session.SendAndWait(ctx, copilot.MessageOptions{Prompt: "What did we discuss earlier?"})
+ _ = session
+}
+```
+
+
```go
ctx := context.Background()
@@ -155,7 +198,28 @@ session.SendAndWait(ctx, copilot.MessageOptions{Prompt: "What did we discuss ear
### C# (.NET)
-
+
+```csharp
+using GitHub.Copilot.SDK;
+
+public static class ResumeSessionExample
+{
+ public static async Task Main()
+ {
+ await using var client = new CopilotClient();
+
+ var session = await client.ResumeSessionAsync("user-123-task-456", new ResumeSessionConfig
+ {
+ OnPermissionRequest = (req, inv) =>
+ Task.FromResult(new PermissionRequestResult { Kind = PermissionRequestResultKind.Approved }),
+ });
+
+ await session.SendAndWaitAsync(new MessageOptions { Prompt = "What did we discuss earlier?" });
+ }
+}
+```
+
+
```csharp
// Resume from a different client instance (or after restart)
var session = await client.ResumeSessionAsync("user-123-task-456");
@@ -181,6 +245,7 @@ When resuming a session, you can optionally reconfigure many settings. This is u
| `configDir` | Override configuration directory |
| `mcpServers` | Configure MCP servers |
| `customAgents` | Configure custom agents |
+| `agent` | Pre-select a custom agent by name |
| `skillDirectories` | Directories to load skills from |
| `disabledSkills` | Skills to disable |
| `infiniteSessions` | Configure infinite session behavior |
@@ -494,7 +559,7 @@ const session = await client.createSession({
});
```
-> **Note:** Thresholds are context utilization ratios (0.0-1.0), not absolute token counts. See the [Compatibility Guide](../compatibility.md) for details.
+> **Note:** Thresholds are context utilization ratios (0.0-1.0), not absolute token counts. See the [Compatibility Guide](../troubleshooting/compatibility.md) for details.
## Limitations & Considerations
@@ -554,6 +619,6 @@ await withSessionLock("user-123-task-456", async () => {
## Next Steps
-- [Hooks Overview](../hooks/overview.md) - Customize session behavior with hooks
-- [Compatibility Guide](../compatibility.md) - SDK vs CLI feature comparison
-- [Debugging Guide](../debugging.md) - Troubleshoot session issues
+- [Hooks Overview](../hooks/index.md) - Customize session behavior with hooks
+- [Compatibility Guide](../troubleshooting/compatibility.md) - SDK vs CLI feature comparison
+- [Debugging Guide](../troubleshooting/debugging.md) - Troubleshoot session issues
diff --git a/docs/guides/skills.md b/docs/features/skills.md
similarity index 82%
rename from docs/guides/skills.md
rename to docs/features/skills.md
index 5e085e3b29..466c637ffe 100644
--- a/docs/guides/skills.md
+++ b/docs/features/skills.md
@@ -43,19 +43,20 @@ await session.sendAndWait({ prompt: "Review this code for security issues" });
```python
from copilot import CopilotClient
+from copilot.types import PermissionRequestResult
async def main():
client = CopilotClient()
await client.start()
- session = await client.create_session({
- "model": "gpt-4.1",
- "skill_directories": [
+ session = await client.create_session(
+ on_permission_request=lambda req, inv: {"kind": "approved"},
+ model="gpt-4.1",
+ skill_directories=[
"./skills/code-review",
"./skills/documentation",
],
- "on_permission_request": lambda req: {"kind": "approved"},
- })
+ )
# Copilot now has access to skills in those directories
await session.send_and_wait({"prompt": "Review this code for security issues"})
@@ -159,10 +160,13 @@ const session = await client.createSession({
Python
```python
-session = await client.create_session({
- "skill_directories": ["./skills"],
- "disabled_skills": ["experimental-feature", "deprecated-tool"],
-})
+from copilot import PermissionHandler
+
+session = await client.create_session(
+ on_permission_request=PermissionHandler.approve_all,
+ skill_directories=["./skills"],
+ disabled_skills=["experimental-feature", "deprecated-tool"],
+)
```
@@ -170,7 +174,31 @@ session = await client.create_session({
Go
-
+
+```go
+package main
+
+import (
+ "context"
+ copilot "github.com/github/copilot-sdk/go"
+)
+
+func main() {
+ ctx := context.Background()
+ client := copilot.NewClient(nil)
+
+ session, _ := client.CreateSession(ctx, &copilot.SessionConfig{
+ SkillDirectories: []string{"./skills"},
+ DisabledSkills: []string{"experimental-feature", "deprecated-tool"},
+ OnPermissionRequest: func(req copilot.PermissionRequest, inv copilot.PermissionInvocation) (copilot.PermissionRequestResult, error) {
+ return copilot.PermissionRequestResult{Kind: copilot.PermissionRequestResultKindApproved}, nil
+ },
+ })
+ _ = session
+}
+```
+
+
```go
session, _ := client.CreateSession(context.Background(), &copilot.SessionConfig{
SkillDirectories: []string{"./skills"},
@@ -183,7 +211,28 @@ session, _ := client.CreateSession(context.Background(), &copilot.SessionConfig{
.NET
-
+
+```csharp
+using GitHub.Copilot.SDK;
+
+public static class SkillsExample
+{
+ public static async Task Main()
+ {
+ await using var client = new CopilotClient();
+
+ var session = await client.CreateSessionAsync(new SessionConfig
+ {
+ SkillDirectories = new List { "./skills" },
+ DisabledSkills = new List { "experimental-feature", "deprecated-tool" },
+ OnPermissionRequest = (req, inv) =>
+ Task.FromResult(new PermissionRequestResult { Kind = PermissionRequestResultKind.Approved }),
+ });
+ }
+}
+```
+
+
```csharp
var session = await client.CreateSessionAsync(new SessionConfig
{
@@ -319,4 +368,4 @@ If multiple skills provide conflicting instructions:
- [Custom Agents](../getting-started.md#create-custom-agents) - Define specialized AI personas
- [Custom Tools](../getting-started.md#step-4-add-a-custom-tool) - Build your own tools
-- [MCP Servers](../mcp/overview.md) - Connect external tool providers
+- [MCP Servers](./mcp.md) - Connect external tool providers
diff --git a/docs/features/steering-and-queueing.md b/docs/features/steering-and-queueing.md
new file mode 100644
index 0000000000..7da349e1c2
--- /dev/null
+++ b/docs/features/steering-and-queueing.md
@@ -0,0 +1,579 @@
+# Steering & Queueing
+
+Two interaction patterns let users send messages while the agent is already working: **steering** redirects the agent mid-turn, and **queueing** buffers messages for sequential processing after the current turn completes.
+
+## Overview
+
+When a session is actively processing a turn, incoming messages can be delivered in one of two modes via the `mode` field on `MessageOptions`:
+
+| Mode | Behavior | Use case |
+|------|----------|----------|
+| `"immediate"` (steering) | Injected into the **current** LLM turn | "Actually, don't create that file — use a different approach" |
+| `"enqueue"` (queueing) | Queued and processed **after** the current turn finishes | "After this, also fix the tests" |
+
+```mermaid
+sequenceDiagram
+ participant U as User
+ participant S as Session
+ participant LLM as Agent
+
+ U->>S: send({ prompt: "Refactor auth" })
+ S->>LLM: Turn starts
+
+ Note over U,LLM: Agent is busy...
+
+ U->>S: send({ prompt: "Use JWT instead", mode: "immediate" })
+ S-->>LLM: Injected into current turn (steering)
+
+ U->>S: send({ prompt: "Then update the docs", mode: "enqueue" })
+ S-->>S: Queued for next turn
+
+ LLM->>S: Turn completes (incorporates steering)
+ S->>LLM: Processes queued message
+ LLM->>S: Turn completes
+```
+
+## Steering (Immediate Mode)
+
+Steering sends a message that is injected directly into the agent's current turn. The agent sees the message in real time and adjusts its response accordingly — useful for course-correcting without aborting the turn.
+
+
+Node.js / TypeScript
+
+```typescript
+import { CopilotClient } from "@github/copilot-sdk";
+
+const client = new CopilotClient();
+await client.start();
+
+const session = await client.createSession({
+ model: "gpt-4.1",
+ onPermissionRequest: async () => ({ kind: "approved" }),
+});
+
+// Start a long-running task
+const msgId = await session.send({
+ prompt: "Refactor the authentication module to use sessions",
+});
+
+// While the agent is working, steer it
+await session.send({
+ prompt: "Actually, use JWT tokens instead of sessions",
+ mode: "immediate",
+});
+```
+
+
+
+
+Python
+
+```python
+from copilot import CopilotClient
+from copilot.types import PermissionRequestResult
+
+async def main():
+ client = CopilotClient()
+ await client.start()
+
+ session = await client.create_session(
+ on_permission_request=lambda req, inv: PermissionRequestResult(kind="approved"),
+ model="gpt-4.1",
+ )
+
+ # Start a long-running task
+ msg_id = await session.send({
+ "prompt": "Refactor the authentication module to use sessions",
+ })
+
+ # While the agent is working, steer it
+ await session.send({
+ "prompt": "Actually, use JWT tokens instead of sessions",
+ "mode": "immediate",
+ })
+
+ await client.stop()
+```
+
+
+
+
+Go
+
+```go
+package main
+
+import (
+ "context"
+ "log"
+ copilot "github.com/github/copilot-sdk/go"
+)
+
+func main() {
+ ctx := context.Background()
+ client := copilot.NewClient(nil)
+ if err := client.Start(ctx); err != nil {
+ log.Fatal(err)
+ }
+ defer client.Stop()
+
+ session, err := client.CreateSession(ctx, &copilot.SessionConfig{
+ Model: "gpt-4.1",
+ OnPermissionRequest: func(req copilot.PermissionRequest, inv copilot.PermissionInvocation) (copilot.PermissionRequestResult, error) {
+ return copilot.PermissionRequestResult{Kind: copilot.PermissionRequestResultKindApproved}, nil
+ },
+ })
+ if err != nil {
+ log.Fatal(err)
+ }
+
+ // Start a long-running task
+ _, err = session.Send(ctx, copilot.MessageOptions{
+ Prompt: "Refactor the authentication module to use sessions",
+ })
+ if err != nil {
+ log.Fatal(err)
+ }
+
+ // While the agent is working, steer it
+ _, err = session.Send(ctx, copilot.MessageOptions{
+ Prompt: "Actually, use JWT tokens instead of sessions",
+ Mode: "immediate",
+ })
+ if err != nil {
+ log.Fatal(err)
+ }
+}
+```
+
+
+
+
+.NET
+
+```csharp
+using GitHub.Copilot.SDK;
+
+await using var client = new CopilotClient();
+await using var session = await client.CreateSessionAsync(new SessionConfig
+{
+ Model = "gpt-4.1",
+ OnPermissionRequest = (req, inv) =>
+ Task.FromResult(new PermissionRequestResult { Kind = PermissionRequestResultKind.Approved }),
+});
+
+// Start a long-running task
+var msgId = await session.SendAsync(new MessageOptions
+{
+ Prompt = "Refactor the authentication module to use sessions"
+});
+
+// While the agent is working, steer it
+await session.SendAsync(new MessageOptions
+{
+ Prompt = "Actually, use JWT tokens instead of sessions",
+ Mode = "immediate"
+});
+```
+
+
+
+### How Steering Works Internally
+
+1. The message is added to the runtime's `ImmediatePromptProcessor` queue
+2. Before the next LLM request within the current turn, the processor injects the message into the conversation
+3. The agent sees the steering message as a new user message and adjusts its response
+4. If the turn completes before the steering message is processed, it is automatically moved to the regular queue for the next turn
+
+> **Note:** Steering messages are best-effort within the current turn. If the agent has already committed to a tool call, the steering takes effect after that call completes but still within the same turn.
+
+## Queueing (Enqueue Mode)
+
+Queueing buffers messages to be processed sequentially after the current turn finishes. Each queued message starts its own full turn. This is the default mode — if you omit `mode`, the SDK uses `"enqueue"`.
+
+
+Node.js / TypeScript
+
+```typescript
+import { CopilotClient } from "@github/copilot-sdk";
+
+const client = new CopilotClient();
+await client.start();
+
+const session = await client.createSession({
+ model: "gpt-4.1",
+ onPermissionRequest: async () => ({ kind: "approved" }),
+});
+
+// Send an initial task
+await session.send({ prompt: "Set up the project structure" });
+
+// Queue follow-up tasks while the agent is busy
+await session.send({
+ prompt: "Add unit tests for the auth module",
+ mode: "enqueue",
+});
+
+await session.send({
+ prompt: "Update the README with setup instructions",
+ mode: "enqueue",
+});
+
+// Messages are processed in FIFO order after each turn completes
+```
+
+
+
+
+Python
+
+```python
+from copilot import CopilotClient
+from copilot.types import PermissionRequestResult
+
+async def main():
+ client = CopilotClient()
+ await client.start()
+
+ session = await client.create_session(
+ on_permission_request=lambda req, inv: PermissionRequestResult(kind="approved"),
+ model="gpt-4.1",
+ )
+
+ # Send an initial task
+ await session.send({"prompt": "Set up the project structure"})
+
+ # Queue follow-up tasks while the agent is busy
+ await session.send({
+ "prompt": "Add unit tests for the auth module",
+ "mode": "enqueue",
+ })
+
+ await session.send({
+ "prompt": "Update the README with setup instructions",
+ "mode": "enqueue",
+ })
+
+ # Messages are processed in FIFO order after each turn completes
+ await client.stop()
+```
+
+
+
+
+Go
+
+
+```go
+package main
+
+import (
+ "context"
+ copilot "github.com/github/copilot-sdk/go"
+)
+
+func main() {
+ ctx := context.Background()
+ client := copilot.NewClient(nil)
+ client.Start(ctx)
+
+ session, _ := client.CreateSession(ctx, &copilot.SessionConfig{
+ Model: "gpt-4.1",
+ OnPermissionRequest: func(req copilot.PermissionRequest, inv copilot.PermissionInvocation) (copilot.PermissionRequestResult, error) {
+ return copilot.PermissionRequestResult{Kind: copilot.PermissionRequestResultKindApproved}, nil
+ },
+ })
+
+ session.Send(ctx, copilot.MessageOptions{
+ Prompt: "Set up the project structure",
+ })
+
+ session.Send(ctx, copilot.MessageOptions{
+ Prompt: "Add unit tests for the auth module",
+ Mode: "enqueue",
+ })
+
+ session.Send(ctx, copilot.MessageOptions{
+ Prompt: "Update the README with setup instructions",
+ Mode: "enqueue",
+ })
+}
+```
+
+
+```go
+// Send an initial task
+session.Send(ctx, copilot.MessageOptions{
+ Prompt: "Set up the project structure",
+})
+
+// Queue follow-up tasks while the agent is busy
+session.Send(ctx, copilot.MessageOptions{
+ Prompt: "Add unit tests for the auth module",
+ Mode: "enqueue",
+})
+
+session.Send(ctx, copilot.MessageOptions{
+ Prompt: "Update the README with setup instructions",
+ Mode: "enqueue",
+})
+
+// Messages are processed in FIFO order after each turn completes
+```
+
+
+
+
+.NET
+
+
+```csharp
+using GitHub.Copilot.SDK;
+
+public static class QueueingExample
+{
+ public static async Task Main()
+ {
+ await using var client = new CopilotClient();
+ await using var session = await client.CreateSessionAsync(new SessionConfig
+ {
+ Model = "gpt-4.1",
+ OnPermissionRequest = (req, inv) =>
+ Task.FromResult(new PermissionRequestResult { Kind = PermissionRequestResultKind.Approved }),
+ });
+
+ await session.SendAsync(new MessageOptions
+ {
+ Prompt = "Set up the project structure"
+ });
+
+ await session.SendAsync(new MessageOptions
+ {
+ Prompt = "Add unit tests for the auth module",
+ Mode = "enqueue"
+ });
+
+ await session.SendAsync(new MessageOptions
+ {
+ Prompt = "Update the README with setup instructions",
+ Mode = "enqueue"
+ });
+ }
+}
+```
+
+
+```csharp
+// Send an initial task
+await session.SendAsync(new MessageOptions
+{
+ Prompt = "Set up the project structure"
+});
+
+// Queue follow-up tasks while the agent is busy
+await session.SendAsync(new MessageOptions
+{
+ Prompt = "Add unit tests for the auth module",
+ Mode = "enqueue"
+});
+
+await session.SendAsync(new MessageOptions
+{
+ Prompt = "Update the README with setup instructions",
+ Mode = "enqueue"
+});
+
+// Messages are processed in FIFO order after each turn completes
+```
+
+
+
+### How Queueing Works Internally
+
+1. The message is added to the session's `itemQueue` as a `QueuedItem`
+2. When the current turn completes and the session becomes idle, `processQueuedItems()` runs
+3. Items are dequeued in FIFO order — each message triggers a full agentic turn
+4. If a steering message was pending when the turn ended, it is moved to the front of the queue
+5. Processing continues until the queue is empty, then the session emits an idle event
+
+## Combining Steering and Queueing
+
+You can use both patterns together in a single session. Steering affects the current turn while queued messages wait for their own turns:
+
+
+Node.js / TypeScript
+
+```typescript
+const session = await client.createSession({
+ model: "gpt-4.1",
+ onPermissionRequest: async () => ({ kind: "approved" }),
+});
+
+// Start a task
+await session.send({ prompt: "Refactor the database layer" });
+
+// Steer the current work
+await session.send({
+ prompt: "Make sure to keep backwards compatibility with the v1 API",
+ mode: "immediate",
+});
+
+// Queue a follow-up for after this turn
+await session.send({
+ prompt: "Now add migration scripts for the schema changes",
+ mode: "enqueue",
+});
+```
+
+
+
+
+Python
+
+```python
+session = await client.create_session(
+ on_permission_request=lambda req, inv: PermissionRequestResult(kind="approved"),
+ model="gpt-4.1",
+)
+
+# Start a task
+await session.send({"prompt": "Refactor the database layer"})
+
+# Steer the current work
+await session.send({
+ "prompt": "Make sure to keep backwards compatibility with the v1 API",
+ "mode": "immediate",
+})
+
+# Queue a follow-up for after this turn
+await session.send({
+ "prompt": "Now add migration scripts for the schema changes",
+ "mode": "enqueue",
+})
+```
+
+
+
+## Choosing Between Steering and Queueing
+
+| Scenario | Pattern | Why |
+|----------|---------|-----|
+| Agent is going down the wrong path | **Steering** | Redirects the current turn without losing progress |
+| You thought of something the agent should also do | **Queueing** | Doesn't disrupt current work; runs next |
+| Agent is about to make a mistake | **Steering** | Intervenes before the mistake is committed |
+| You want to chain multiple tasks | **Queueing** | FIFO ordering ensures predictable execution |
+| You want to add context to the current task | **Steering** | Agent incorporates it into its current reasoning |
+| You want to batch unrelated requests | **Queueing** | Each gets its own full turn with clean context |
+
+## Building a UI with Steering & Queueing
+
+Here's a pattern for building an interactive UI that supports both modes:
+
+```typescript
+import { CopilotClient, CopilotSession } from "@github/copilot-sdk";
+
+interface PendingMessage {
+ prompt: string;
+ mode: "immediate" | "enqueue";
+ sentAt: Date;
+}
+
+class InteractiveChat {
+ private session: CopilotSession;
+ private isProcessing = false;
+ private pendingMessages: PendingMessage[] = [];
+
+ constructor(session: CopilotSession) {
+ this.session = session;
+
+ session.on((event) => {
+ if (event.type === "session.idle") {
+ this.isProcessing = false;
+ this.onIdle();
+ }
+ if (event.type === "assistant.message") {
+ this.renderMessage(event);
+ }
+ });
+ }
+
+ async sendMessage(prompt: string): Promise {
+ if (!this.isProcessing) {
+ this.isProcessing = true;
+ await this.session.send({ prompt });
+ return;
+ }
+
+ // Session is busy — let the user choose how to deliver
+ // Your UI would present this choice (e.g., buttons, keyboard shortcuts)
+ }
+
+ async steer(prompt: string): Promise {
+ this.pendingMessages.push({
+ prompt,
+ mode: "immediate",
+ sentAt: new Date(),
+ });
+ await this.session.send({ prompt, mode: "immediate" });
+ }
+
+ async enqueue(prompt: string): Promise {
+ this.pendingMessages.push({
+ prompt,
+ mode: "enqueue",
+ sentAt: new Date(),
+ });
+ await this.session.send({ prompt, mode: "enqueue" });
+ }
+
+ private onIdle(): void {
+ this.pendingMessages = [];
+ // Update UI to show session is ready for new input
+ }
+
+ private renderMessage(event: unknown): void {
+ // Render assistant message in your UI
+ }
+}
+```
+
+## API Reference
+
+### MessageOptions
+
+| Language | Field | Type | Default | Description |
+|----------|-------|------|---------|-------------|
+| Node.js | `mode` | `"enqueue" \| "immediate"` | `"enqueue"` | Message delivery mode |
+| Python | `mode` | `Literal["enqueue", "immediate"]` | `"enqueue"` | Message delivery mode |
+| Go | `Mode` | `string` | `"enqueue"` | Message delivery mode |
+| .NET | `Mode` | `string?` | `"enqueue"` | Message delivery mode |
+
+### Delivery Modes
+
+| Mode | Effect | During active turn | During idle |
+|------|--------|-------------------|-------------|
+| `"enqueue"` | Queue for next turn | Waits in FIFO queue | Starts a new turn immediately |
+| `"immediate"` | Inject into current turn | Injected before next LLM call | Starts a new turn immediately |
+
+> **Note:** When the session is idle (not processing), both modes behave identically — the message starts a new turn immediately.
+
+## Best Practices
+
+1. **Default to queueing** — Use `"enqueue"` (or omit `mode`) for most messages. It's predictable and doesn't risk disrupting in-progress work.
+
+2. **Reserve steering for corrections** — Use `"immediate"` when the agent is actively doing the wrong thing and you need to redirect it before it goes further.
+
+3. **Keep steering messages concise** — The agent needs to quickly understand the course correction. Long, complex steering messages may confuse the current context.
+
+4. **Don't over-steer** — Multiple rapid steering messages can degrade turn quality. If you need to change direction significantly, consider aborting the turn and starting fresh.
+
+5. **Show queue state in your UI** — Display the number of queued messages so users know what's pending. Listen for idle events to clear the display.
+
+6. **Handle the steering-to-queue fallback** — If a steering message arrives after the turn completes, it's automatically moved to the queue. Design your UI to reflect this transition.
+
+## See Also
+
+- [Getting Started](../getting-started.md) — Set up a session and send messages
+- [Custom Agents](./custom-agents.md) — Define specialized agents with scoped tools
+- [Session Hooks](../hooks/index.md) — React to session lifecycle events
+- [Session Persistence](./session-persistence.md) — Resume sessions across restarts
diff --git a/docs/features/streaming-events.md b/docs/features/streaming-events.md
new file mode 100644
index 0000000000..d03ed95fa7
--- /dev/null
+++ b/docs/features/streaming-events.md
@@ -0,0 +1,791 @@
+# Streaming Session Events
+
+Every action the Copilot agent takes — thinking, writing code, running tools — is emitted as a **session event** you can subscribe to. This guide is a field-level reference for each event type so you know exactly what data to expect without reading the SDK source.
+
+## Overview
+
+When `streaming: true` is set on a session, the SDK emits **ephemeral** events in real time (deltas, progress updates) alongside **persisted** events (complete messages, tool results). All events share a common envelope and carry a `data` payload whose shape depends on the event `type`.
+
+```mermaid
+sequenceDiagram
+ participant App as Your App
+ participant SDK as SDK Session
+ participant Agent as Copilot Agent
+
+ App->>SDK: send({ prompt })
+ SDK->>Agent: JSON-RPC
+
+ Agent-->>SDK: assistant.turn_start
+ SDK-->>App: event
+
+ loop Streaming response
+ Agent-->>SDK: assistant.message_delta (ephemeral)
+ SDK-->>App: event
+ end
+
+ Agent-->>SDK: assistant.message
+ SDK-->>App: event
+
+ loop Tool execution
+ Agent-->>SDK: tool.execution_start
+ SDK-->>App: event
+ Agent-->>SDK: tool.execution_complete
+ SDK-->>App: event
+ end
+
+ Agent-->>SDK: assistant.turn_end
+ SDK-->>App: event
+
+ Agent-->>SDK: session.idle (ephemeral)
+ SDK-->>App: event
+```
+
+| Concept | Description |
+|---------|-------------|
+| **Ephemeral event** | Transient; streamed in real time but **not** persisted to the session log. Not replayed on session resume. |
+| **Persisted event** | Saved to the session event log on disk. Replayed when resuming a session. |
+| **Delta event** | An ephemeral streaming chunk (text or reasoning). Accumulate deltas to build the complete content. |
+| **`parentId` chain** | Each event's `parentId` points to the previous event, forming a linked list you can walk. |
+
+## Event Envelope
+
+Every session event, regardless of type, includes these fields:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | `string` (UUID v4) | Unique event identifier |
+| `timestamp` | `string` (ISO 8601) | When the event was created |
+| `parentId` | `string \| null` | ID of the previous event in the chain; `null` for the first event |
+| `ephemeral` | `boolean?` | `true` for transient events; absent or `false` for persisted events |
+| `type` | `string` | Event type discriminator (see tables below) |
+| `data` | `object` | Event-specific payload |
+
+## Subscribing to Events
+
+
+Node.js / TypeScript
+
+```typescript
+// All events
+session.on((event) => {
+ console.log(event.type, event.data);
+});
+
+// Specific event type — data is narrowed automatically
+session.on("assistant.message_delta", (event) => {
+ process.stdout.write(event.data.deltaContent);
+});
+```
+
+
+
+
+Python
+
+
+```python
+from copilot import CopilotClient
+from copilot.generated.session_events import SessionEventType
+
+client = CopilotClient()
+
+session = None # assume session is created elsewhere
+
+def handle(event):
+ if event.type == SessionEventType.ASSISTANT_MESSAGE_DELTA:
+ print(event.data.delta_content, end="", flush=True)
+
+# session.on(handle)
+```
+
+
+```python
+from copilot.generated.session_events import SessionEventType
+
+def handle(event):
+ if event.type == SessionEventType.ASSISTANT_MESSAGE_DELTA:
+ print(event.data.delta_content, end="", flush=True)
+
+session.on(handle)
+```
+
+
+
+
+Go
+
+
+```go
+package main
+
+import (
+ "context"
+ "fmt"
+ copilot "github.com/github/copilot-sdk/go"
+)
+
+func main() {
+ ctx := context.Background()
+ client := copilot.NewClient(nil)
+
+ session, _ := client.CreateSession(ctx, &copilot.SessionConfig{
+ Model: "gpt-4.1",
+ Streaming: true,
+ OnPermissionRequest: func(req copilot.PermissionRequest, inv copilot.PermissionInvocation) (copilot.PermissionRequestResult, error) {
+ return copilot.PermissionRequestResult{Kind: copilot.PermissionRequestResultKindApproved}, nil
+ },
+ })
+
+ session.On(func(event copilot.SessionEvent) {
+ if event.Type == "assistant.message_delta" {
+ fmt.Print(*event.Data.DeltaContent)
+ }
+ })
+ _ = session
+}
+```
+
+
+```go
+session.On(func(event copilot.SessionEvent) {
+ if event.Type == "assistant.message_delta" {
+ fmt.Print(*event.Data.DeltaContent)
+ }
+})
+```
+
+
+
+
+.NET
+
+
+```csharp
+using GitHub.Copilot.SDK;
+
+public static class StreamingEventsExample
+{
+ public static async Task Example(CopilotSession session)
+ {
+ session.On(evt =>
+ {
+ if (evt is AssistantMessageDeltaEvent delta)
+ {
+ Console.Write(delta.Data.DeltaContent);
+ }
+ });
+ }
+}
+```
+
+
+```csharp
+session.On(evt =>
+{
+ if (evt is AssistantMessageDeltaEvent delta)
+ {
+ Console.Write(delta.Data.DeltaContent);
+ }
+});
+```
+
+
+
+> **Tip (Python / Go):** These SDKs use a single `Data` class/struct with all possible fields as optional/nullable. Only the fields listed in the tables below are populated for each event type — the rest will be `None` / `nil`.
+>
+> **Tip (.NET):** The .NET SDK uses separate, strongly-typed data classes per event (e.g., `AssistantMessageDeltaData`), so only the relevant fields exist on each type.
+>
+> **Tip (TypeScript):** The TypeScript SDK uses a discriminated union — when you match on `event.type`, the `data` payload is automatically narrowed to the correct shape.
+
+---
+
+## Assistant Events
+
+These events track the agent's response lifecycle — from turn start through streaming chunks to the final message.
+
+### `assistant.turn_start`
+
+Emitted when the agent begins processing a turn.
+
+| Data Field | Type | Required | Description |
+|------------|------|----------|-------------|
+| `turnId` | `string` | ✅ | Turn identifier (typically a stringified turn number) |
+| `interactionId` | `string` | | CAPI interaction ID for telemetry correlation |
+
+### `assistant.intent`
+
+Ephemeral. Short description of what the agent is currently doing, updated as it works.
+
+| Data Field | Type | Required | Description |
+|------------|------|----------|-------------|
+| `intent` | `string` | ✅ | Human-readable intent (e.g., "Exploring codebase") |
+
+### `assistant.reasoning`
+
+Complete extended thinking block from the model. Emitted after reasoning is finished.
+
+| Data Field | Type | Required | Description |
+|------------|------|----------|-------------|
+| `reasoningId` | `string` | ✅ | Unique identifier for this reasoning block |
+| `content` | `string` | ✅ | The complete extended thinking text |
+
+### `assistant.reasoning_delta`
+
+Ephemeral. Incremental chunk of the model's extended thinking, streamed in real time.
+
+| Data Field | Type | Required | Description |
+|------------|------|----------|-------------|
+| `reasoningId` | `string` | ✅ | Matches the corresponding `assistant.reasoning` event |
+| `deltaContent` | `string` | ✅ | Text chunk to append to reasoning content |
+
+### `assistant.message`
+
+The assistant's complete response for this LLM call. May include tool invocation requests.
+
+| Data Field | Type | Required | Description |
+|------------|------|----------|-------------|
+| `messageId` | `string` | ✅ | Unique identifier for this message |
+| `content` | `string` | ✅ | The assistant's text response |
+| `toolRequests` | `ToolRequest[]` | | Tool calls the assistant wants to make (see below) |
+| `reasoningOpaque` | `string` | | Encrypted extended thinking (Anthropic models); session-bound |
+| `reasoningText` | `string` | | Readable reasoning text from extended thinking |
+| `encryptedContent` | `string` | | Encrypted reasoning content (OpenAI models); session-bound |
+| `phase` | `string` | | Generation phase (e.g., `"thinking"` vs `"response"`) |
+| `outputTokens` | `number` | | Actual output token count from the API response |
+| `interactionId` | `string` | | CAPI interaction ID for telemetry |
+| `parentToolCallId` | `string` | | Set when this message originates from a sub-agent |
+
+**`ToolRequest` fields:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `toolCallId` | `string` | ✅ | Unique ID for this tool call |
+| `name` | `string` | ✅ | Tool name (e.g., `"bash"`, `"edit"`, `"grep"`) |
+| `arguments` | `object` | | Parsed arguments for the tool |
+| `type` | `"function" \| "custom"` | | Call type; defaults to `"function"` when absent |
+
+### `assistant.message_delta`
+
+Ephemeral. Incremental chunk of the assistant's text response, streamed in real time.
+
+| Data Field | Type | Required | Description |
+|------------|------|----------|-------------|
+| `messageId` | `string` | ✅ | Matches the corresponding `assistant.message` event |
+| `deltaContent` | `string` | ✅ | Text chunk to append to the message |
+| `parentToolCallId` | `string` | | Set when originating from a sub-agent |
+
+### `assistant.turn_end`
+
+Emitted when the agent finishes a turn (all tool executions complete, final response delivered).
+
+| Data Field | Type | Required | Description |
+|------------|------|----------|-------------|
+| `turnId` | `string` | ✅ | Matches the corresponding `assistant.turn_start` event |
+
+### `assistant.usage`
+
+Ephemeral. Token usage and cost information for an individual API call.
+
+| Data Field | Type | Required | Description |
+|------------|------|----------|-------------|
+| `model` | `string` | ✅ | Model identifier (e.g., `"gpt-4.1"`) |
+| `inputTokens` | `number` | | Input tokens consumed |
+| `outputTokens` | `number` | | Output tokens produced |
+| `cacheReadTokens` | `number` | | Tokens read from prompt cache |
+| `cacheWriteTokens` | `number` | | Tokens written to prompt cache |
+| `cost` | `number` | | Model multiplier cost for billing |
+| `duration` | `number` | | API call duration in milliseconds |
+| `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`) |
+| `providerCallId` | `string` | | GitHub request tracing ID (`x-github-request-id`) |
+| `parentToolCallId` | `string` | | Set when usage originates from a sub-agent |
+| `quotaSnapshots` | `Record` | | Per-quota resource usage, keyed by quota identifier |
+| `copilotUsage` | `CopilotUsage` | | Itemized token cost breakdown from the API |
+
+### `assistant.streaming_delta`
+
+Ephemeral. Low-level network progress indicator — total bytes received from the streaming API response.
+
+| Data Field | Type | Required | Description |
+|------------|------|----------|-------------|
+| `totalResponseSizeBytes` | `number` | ✅ | Cumulative bytes received so far |
+
+---
+
+## Tool Execution Events
+
+These events track the full lifecycle of each tool invocation — from the model requesting a tool call through execution to completion.
+
+### `tool.execution_start`
+
+Emitted when a tool begins executing.
+
+| Data Field | Type | Required | Description |
+|------------|------|----------|-------------|
+| `toolCallId` | `string` | ✅ | Unique identifier for this tool call |
+| `toolName` | `string` | ✅ | Name of the tool (e.g., `"bash"`, `"edit"`, `"grep"`) |
+| `arguments` | `object` | | Parsed arguments passed to the tool |
+| `mcpServerName` | `string` | | MCP server name, when the tool is provided by an MCP server |
+| `mcpToolName` | `string` | | Original tool name on the MCP server |
+| `parentToolCallId` | `string` | | Set when invoked by a sub-agent |
+
+### `tool.execution_partial_result`
+
+Ephemeral. Incremental output from a running tool (e.g., streaming bash output).
+
+| Data Field | Type | Required | Description |
+|------------|------|----------|-------------|
+| `toolCallId` | `string` | ✅ | Matches the corresponding `tool.execution_start` |
+| `partialOutput` | `string` | ✅ | Incremental output chunk |
+
+### `tool.execution_progress`
+
+Ephemeral. Human-readable progress status from a running tool (e.g., MCP server progress notifications).
+
+| Data Field | Type | Required | Description |
+|------------|------|----------|-------------|
+| `toolCallId` | `string` | ✅ | Matches the corresponding `tool.execution_start` |
+| `progressMessage` | `string` | ✅ | Progress status message |
+
+### `tool.execution_complete`
+
+Emitted when a tool finishes executing — successfully or with an error.
+
+| Data Field | Type | Required | Description |
+|------------|------|----------|-------------|
+| `toolCallId` | `string` | ✅ | Matches the corresponding `tool.execution_start` |
+| `success` | `boolean` | ✅ | Whether execution succeeded |
+| `model` | `string` | | Model that generated this tool call |
+| `interactionId` | `string` | | CAPI interaction ID |
+| `isUserRequested` | `boolean` | | `true` when the user explicitly requested this tool call |
+| `result` | `Result` | | Present on success (see below) |
+| `error` | `{ message, code? }` | | Present on failure |
+| `toolTelemetry` | `object` | | Tool-specific telemetry (e.g., CodeQL check counts) |
+| `parentToolCallId` | `string` | | Set when invoked by a sub-agent |
+
+**`Result` fields:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `content` | `string` | ✅ | Concise result sent to the LLM (may be truncated for token efficiency) |
+| `detailedContent` | `string` | | Full result for display, preserving complete content like diffs |
+| `contents` | `ContentBlock[]` | | Structured content blocks (text, terminal, image, audio, resource) |
+
+### `tool.user_requested`
+
+Emitted when the user explicitly requests a tool invocation (rather than the model choosing to call one).
+
+| Data Field | Type | Required | Description |
+|------------|------|----------|-------------|
+| `toolCallId` | `string` | ✅ | Unique identifier for this tool call |
+| `toolName` | `string` | ✅ | Name of the tool the user wants to invoke |
+| `arguments` | `object` | | Arguments for the invocation |
+
+---
+
+## Session Lifecycle Events
+
+### `session.idle`
+
+Ephemeral. The agent has finished all processing and is ready for the next message. This is the signal that a turn is fully complete.
+
+| Data Field | Type | Required | Description |
+|------------|------|----------|-------------|
+| `backgroundTasks` | `BackgroundTasks` | | Background agents/shells still running when the agent became idle |
+
+### `session.error`
+
+An error occurred during session processing.
+
+| Data Field | Type | Required | Description |
+|------------|------|----------|-------------|
+| `errorType` | `string` | ✅ | Error category (e.g., `"authentication"`, `"quota"`, `"rate_limit"`) |
+| `message` | `string` | ✅ | Human-readable error message |
+| `stack` | `string` | | Error stack trace |
+| `statusCode` | `number` | | HTTP status code from the upstream request |
+| `providerCallId` | `string` | | GitHub request tracing ID for server-side log correlation |
+
+### `session.compaction_start`
+
+Context window compaction has begun. **Data payload is empty (`{}`)**.
+
+### `session.compaction_complete`
+
+Context window compaction finished.
+
+| Data Field | Type | Required | Description |
+|------------|------|----------|-------------|
+| `success` | `boolean` | ✅ | Whether compaction succeeded |
+| `error` | `string` | | Error message if compaction failed |
+| `preCompactionTokens` | `number` | | Tokens before compaction |
+| `postCompactionTokens` | `number` | | Tokens after compaction |
+| `preCompactionMessagesLength` | `number` | | Message count before compaction |
+| `messagesRemoved` | `number` | | Messages removed |
+| `tokensRemoved` | `number` | | Tokens removed |
+| `summaryContent` | `string` | | LLM-generated summary of compacted history |
+| `checkpointNumber` | `number` | | Checkpoint snapshot number created for recovery |
+| `checkpointPath` | `string` | | File path where the checkpoint was stored |
+| `compactionTokensUsed` | `{ input, output, cachedInput }` | | Token usage for the compaction LLM call |
+| `requestId` | `string` | | GitHub request tracing ID for the compaction call |
+
+### `session.title_changed`
+
+Ephemeral. The session's auto-generated title was updated.
+
+| Data Field | Type | Required | Description |
+|------------|------|----------|-------------|
+| `title` | `string` | ✅ | New session title |
+
+### `session.context_changed`
+
+The session's working directory or repository context changed.
+
+| Data Field | Type | Required | Description |
+|------------|------|----------|-------------|
+| `cwd` | `string` | ✅ | Current working directory |
+| `gitRoot` | `string` | | Git repository root |
+| `repository` | `string` | | Repository in `"owner/name"` format |
+| `branch` | `string` | | Current git branch |
+
+### `session.usage_info`
+
+Ephemeral. Context window utilization snapshot.
+
+| Data Field | Type | Required | Description |
+|------------|------|----------|-------------|
+| `tokenLimit` | `number` | ✅ | Maximum tokens for the model's context window |
+| `currentTokens` | `number` | ✅ | Current tokens in the context window |
+| `messagesLength` | `number` | ✅ | Current message count in the conversation |
+
+### `session.task_complete`
+
+The agent has completed its assigned task.
+
+| Data Field | Type | Required | Description |
+|------------|------|----------|-------------|
+| `summary` | `string` | | Summary of the completed task |
+
+### `session.shutdown`
+
+The session has ended.
+
+| Data Field | Type | Required | Description |
+|------------|------|----------|-------------|
+| `shutdownType` | `"routine" \| "error"` | ✅ | Normal shutdown or crash |
+| `errorReason` | `string` | | Error description when `shutdownType` is `"error"` |
+| `totalPremiumRequests` | `number` | ✅ | Total premium API requests used |
+| `totalApiDurationMs` | `number` | ✅ | Cumulative API call time in milliseconds |
+| `sessionStartTime` | `number` | ✅ | Unix timestamp (ms) when the session started |
+| `codeChanges` | `{ linesAdded, linesRemoved, filesModified }` | ✅ | Aggregate code change metrics |
+| `modelMetrics` | `Record` | ✅ | Per-model usage breakdown |
+| `currentModel` | `string` | | Model selected at shutdown time |
+
+---
+
+## Permission & User Input Events
+
+These events are emitted when the agent needs approval or input from the user before continuing.
+
+### `permission.requested`
+
+Ephemeral. The agent needs permission to perform an action (run a command, write a file, etc.).
+
+| Data Field | Type | Required | Description |
+|------------|------|----------|-------------|
+| `requestId` | `string` | ✅ | Use this to respond via `session.respondToPermission()` |
+| `permissionRequest` | `PermissionRequest` | ✅ | Details of the permission being requested |
+
+The `permissionRequest` is a discriminated union on `kind`:
+
+| `kind` | Key Fields | Description |
+|--------|------------|-------------|
+| `"shell"` | `fullCommandText`, `intention`, `commands[]`, `possiblePaths[]` | Execute a shell command |
+| `"write"` | `fileName`, `diff`, `intention`, `newFileContents?` | Write/modify a file |
+| `"read"` | `path`, `intention` | Read a file or directory |
+| `"mcp"` | `serverName`, `toolName`, `toolTitle`, `args?`, `readOnly` | Call an MCP tool |
+| `"url"` | `url`, `intention` | Fetch a URL |
+| `"memory"` | `subject`, `fact`, `citations` | Store a memory |
+| `"custom-tool"` | `toolName`, `toolDescription`, `args?` | Call a custom tool |
+
+All `kind` variants also include an optional `toolCallId` linking back to the tool call that triggered the request.
+
+### `permission.completed`
+
+Ephemeral. A permission request was resolved.
+
+| Data Field | Type | Required | Description |
+|------------|------|----------|-------------|
+| `requestId` | `string` | ✅ | Matches the corresponding `permission.requested` |
+| `result.kind` | `string` | ✅ | One of: `"approved"`, `"denied-by-rules"`, `"denied-interactively-by-user"`, `"denied-no-approval-rule-and-could-not-request-from-user"`, `"denied-by-content-exclusion-policy"` |
+
+### `user_input.requested`
+
+Ephemeral. The agent is asking the user a question.
+
+| Data Field | Type | Required | Description |
+|------------|------|----------|-------------|
+| `requestId` | `string` | ✅ | Use this to respond via `session.respondToUserInput()` |
+| `question` | `string` | ✅ | The question to present to the user |
+| `choices` | `string[]` | | Predefined choices for the user |
+| `allowFreeform` | `boolean` | | Whether free-form text input is allowed |
+
+### `user_input.completed`
+
+Ephemeral. A user input request was resolved.
+
+| Data Field | Type | Required | Description |
+|------------|------|----------|-------------|
+| `requestId` | `string` | ✅ | Matches the corresponding `user_input.requested` |
+
+### `elicitation.requested`
+
+Ephemeral. The agent needs structured form input from the user (MCP elicitation protocol).
+
+| Data Field | Type | Required | Description |
+|------------|------|----------|-------------|
+| `requestId` | `string` | ✅ | Use this to respond via `session.respondToElicitation()` |
+| `message` | `string` | ✅ | Description of what information is needed |
+| `mode` | `"form"` | | Elicitation mode (currently only `"form"`) |
+| `requestedSchema` | `{ type: "object", properties, required? }` | ✅ | JSON Schema describing the form fields |
+
+### `elicitation.completed`
+
+Ephemeral. An elicitation request was resolved.
+
+| Data Field | Type | Required | Description |
+|------------|------|----------|-------------|
+| `requestId` | `string` | ✅ | Matches the corresponding `elicitation.requested` |
+
+---
+
+## Sub-Agent & Skill Events
+
+### `subagent.started`
+
+A custom agent was invoked as a sub-agent.
+
+| Data Field | Type | Required | Description |
+|------------|------|----------|-------------|
+| `toolCallId` | `string` | ✅ | Parent tool call that spawned this 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 |
+
+### `subagent.completed`
+
+A sub-agent finished successfully.
+
+| Data Field | Type | Required | Description |
+|------------|------|----------|-------------|
+| `toolCallId` | `string` | ✅ | Matches the corresponding `subagent.started` |
+| `agentName` | `string` | ✅ | Internal name |
+| `agentDisplayName` | `string` | ✅ | Display name |
+
+### `subagent.failed`
+
+A sub-agent encountered an error.
+
+| Data Field | Type | Required | Description |
+|------------|------|----------|-------------|
+| `toolCallId` | `string` | ✅ | Matches the corresponding `subagent.started` |
+| `agentName` | `string` | ✅ | Internal name |
+| `agentDisplayName` | `string` | ✅ | Display name |
+| `error` | `string` | ✅ | Error message |
+
+### `subagent.selected`
+
+A custom agent was selected (inferred) to handle the current request.
+
+| Data Field | Type | Required | Description |
+|------------|------|----------|-------------|
+| `agentName` | `string` | ✅ | Internal name of the selected agent |
+| `agentDisplayName` | `string` | ✅ | Display name |
+| `tools` | `string[] \| null` | ✅ | Tool names available to this agent; `null` for all tools |
+
+### `subagent.deselected`
+
+A custom agent was deselected, returning to the default agent. **Data payload is empty (`{}`)**.
+
+### `skill.invoked`
+
+A skill was activated for the current conversation.
+
+| Data Field | Type | Required | Description |
+|------------|------|----------|-------------|
+| `name` | `string` | ✅ | Skill name |
+| `path` | `string` | ✅ | File path to the SKILL.md definition |
+| `content` | `string` | ✅ | Full skill content injected into the conversation |
+| `allowedTools` | `string[]` | | Tools auto-approved while this skill is active |
+| `pluginName` | `string` | | Plugin the skill originated from |
+| `pluginVersion` | `string` | | Plugin version |
+
+---
+
+## Other Events
+
+### `abort`
+
+The current turn was aborted.
+
+| Data Field | Type | Required | Description |
+|------------|------|----------|-------------|
+| `reason` | `string` | ✅ | Why the turn was aborted (e.g., `"user initiated"`) |
+
+### `user.message`
+
+The user sent a message. Recorded for the session timeline.
+
+| Data Field | Type | Required | Description |
+|------------|------|----------|-------------|
+| `content` | `string` | ✅ | The user's message text |
+| `transformedContent` | `string` | | Transformed version after preprocessing |
+| `attachments` | `Attachment[]` | | File, directory, selection, blob, or GitHub reference attachments |
+| `source` | `string` | | Message source identifier |
+| `agentMode` | `string` | | Agent mode: `"interactive"`, `"plan"`, `"autopilot"`, or `"shell"` |
+| `interactionId` | `string` | | CAPI interaction ID |
+
+### `system.message`
+
+A system or developer prompt was injected into the conversation.
+
+| Data Field | Type | Required | Description |
+|------------|------|----------|-------------|
+| `content` | `string` | ✅ | The prompt text |
+| `role` | `"system" \| "developer"` | ✅ | Message role |
+| `name` | `string` | | Source identifier |
+| `metadata` | `{ promptVersion?, variables? }` | | Prompt template metadata |
+
+### `external_tool.requested`
+
+Ephemeral. The agent wants to invoke an external tool (one provided by the SDK consumer).
+
+| Data Field | Type | Required | Description |
+|------------|------|----------|-------------|
+| `requestId` | `string` | ✅ | Use this to respond via `session.respondToExternalTool()` |
+| `sessionId` | `string` | ✅ | Session this request belongs to |
+| `toolCallId` | `string` | ✅ | Tool call ID for this invocation |
+| `toolName` | `string` | ✅ | Name of the external tool |
+| `arguments` | `object` | | Arguments for the tool |
+
+### `external_tool.completed`
+
+Ephemeral. An external tool request was resolved.
+
+| Data Field | Type | Required | Description |
+|------------|------|----------|-------------|
+| `requestId` | `string` | ✅ | Matches the corresponding `external_tool.requested` |
+
+### `exit_plan_mode.requested`
+
+Ephemeral. The agent has created a plan and wants to exit plan mode.
+
+| Data Field | Type | Required | Description |
+|------------|------|----------|-------------|
+| `requestId` | `string` | ✅ | Use this to respond via `session.respondToExitPlanMode()` |
+| `summary` | `string` | ✅ | Summary of the plan |
+| `planContent` | `string` | ✅ | Full plan file content |
+| `actions` | `string[]` | ✅ | Available user actions (e.g., approve, edit, reject) |
+| `recommendedAction` | `string` | ✅ | Suggested action |
+
+### `exit_plan_mode.completed`
+
+Ephemeral. An exit plan mode request was resolved.
+
+| Data Field | Type | Required | Description |
+|------------|------|----------|-------------|
+| `requestId` | `string` | ✅ | Matches the corresponding `exit_plan_mode.requested` |
+
+### `command.queued`
+
+Ephemeral. A slash command was queued for execution.
+
+| Data Field | Type | Required | Description |
+|------------|------|----------|-------------|
+| `requestId` | `string` | ✅ | Use this to respond via `session.respondToQueuedCommand()` |
+| `command` | `string` | ✅ | The slash command text (e.g., `/help`, `/clear`) |
+
+### `command.completed`
+
+Ephemeral. A queued command was resolved.
+
+| Data Field | Type | Required | Description |
+|------------|------|----------|-------------|
+| `requestId` | `string` | ✅ | Matches the corresponding `command.queued` |
+
+---
+
+## Quick Reference: Agentic Turn Flow
+
+A typical agentic turn emits events in this order:
+
+```
+assistant.turn_start → Turn begins
+├── assistant.intent → What the agent plans to do (ephemeral)
+├── assistant.reasoning_delta → Streaming thinking chunks (ephemeral, repeated)
+├── assistant.reasoning → Complete thinking block
+├── assistant.message_delta → Streaming response chunks (ephemeral, repeated)
+├── assistant.message → Complete response (may include toolRequests)
+├── assistant.usage → Token usage for this API call (ephemeral)
+│
+├── [If tools were requested:]
+│ ├── permission.requested → Needs user approval (ephemeral)
+│ ├── permission.completed → Approval result (ephemeral)
+│ ├── tool.execution_start → Tool begins
+│ ├── tool.execution_partial_result → Streaming tool output (ephemeral, repeated)
+│ ├── tool.execution_progress → Progress updates (ephemeral, repeated)
+│ ├── tool.execution_complete → Tool finished
+│ │
+│ └── [Agent loops: more reasoning → message → tool calls...]
+│
+assistant.turn_end → Turn complete
+session.idle → Ready for next message (ephemeral)
+```
+
+## All Event Types at a Glance
+
+| Event Type | Ephemeral | Category | Key Data Fields |
+|------------|-----------|----------|-----------------|
+| `assistant.turn_start` | | Assistant | `turnId`, `interactionId?` |
+| `assistant.intent` | ✅ | Assistant | `intent` |
+| `assistant.reasoning` | | Assistant | `reasoningId`, `content` |
+| `assistant.reasoning_delta` | ✅ | Assistant | `reasoningId`, `deltaContent` |
+| `assistant.streaming_delta` | ✅ | Assistant | `totalResponseSizeBytes` |
+| `assistant.message` | | Assistant | `messageId`, `content`, `toolRequests?`, `outputTokens?`, `phase?` |
+| `assistant.message_delta` | ✅ | Assistant | `messageId`, `deltaContent`, `parentToolCallId?` |
+| `assistant.turn_end` | | Assistant | `turnId` |
+| `assistant.usage` | ✅ | Assistant | `model`, `inputTokens?`, `outputTokens?`, `cost?`, `duration?` |
+| `tool.user_requested` | | Tool | `toolCallId`, `toolName`, `arguments?` |
+| `tool.execution_start` | | Tool | `toolCallId`, `toolName`, `arguments?`, `mcpServerName?` |
+| `tool.execution_partial_result` | ✅ | Tool | `toolCallId`, `partialOutput` |
+| `tool.execution_progress` | ✅ | Tool | `toolCallId`, `progressMessage` |
+| `tool.execution_complete` | | Tool | `toolCallId`, `success`, `result?`, `error?` |
+| `session.idle` | ✅ | Session | `backgroundTasks?` |
+| `session.error` | | Session | `errorType`, `message`, `statusCode?` |
+| `session.compaction_start` | | Session | *(empty)* |
+| `session.compaction_complete` | | Session | `success`, `preCompactionTokens?`, `summaryContent?` |
+| `session.title_changed` | ✅ | Session | `title` |
+| `session.context_changed` | | Session | `cwd`, `gitRoot?`, `repository?`, `branch?` |
+| `session.usage_info` | ✅ | Session | `tokenLimit`, `currentTokens`, `messagesLength` |
+| `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` |
+| `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.selected` | | Sub-Agent | `agentName`, `agentDisplayName`, `tools` |
+| `subagent.deselected` | | Sub-Agent | *(empty)* |
+| `skill.invoked` | | Skill | `name`, `path`, `content`, `allowedTools?` |
+| `abort` | | Control | `reason` |
+| `user.message` | | User | `content`, `attachments?`, `agentMode?` |
+| `system.message` | | System | `content`, `role` |
+| `external_tool.requested` | ✅ | External Tool | `requestId`, `toolName`, `arguments?` |
+| `external_tool.completed` | ✅ | External Tool | `requestId` |
+| `command.queued` | ✅ | Command | `requestId`, `command` |
+| `command.completed` | ✅ | Command | `requestId` |
+| `exit_plan_mode.requested` | ✅ | Plan Mode | `requestId`, `summary`, `planContent`, `actions` |
+| `exit_plan_mode.completed` | ✅ | Plan Mode | `requestId` |
diff --git a/docs/getting-started.md b/docs/getting-started.md
index 05bbde8dc6..9d4189f561 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -129,15 +129,16 @@ Create `main.py`:
```python
import asyncio
-from copilot import CopilotClient
+from copilot import CopilotClient, PermissionHandler
async def main():
client = CopilotClient()
await client.start()
- session = await client.create_session({"model": "gpt-4.1"})
+ session = await client.create_session(on_permission_request=PermissionHandler.approve_all, model="gpt-4.1")
response = await session.send_and_wait({"prompt": "What is 2 + 2?"})
+ response = await session.send_and_wait({"prompt": "What is 2 + 2?"})
print(response.data.content)
await client.stop()
@@ -274,17 +275,14 @@ Update `main.py`:
```python
import asyncio
import sys
-from copilot import CopilotClient
+from copilot import CopilotClient, PermissionHandler
from copilot.generated.session_events import SessionEventType
async def main():
client = CopilotClient()
await client.start()
- session = await client.create_session({
- "model": "gpt-4.1",
- "streaming": True,
- })
+ session = await client.create_session(on_permission_request=PermissionHandler.approve_all, model="gpt-4.1", streaming=True)
# Listen for response chunks
def handle_event(event):
@@ -433,7 +431,7 @@ from copilot.generated.session_events import SessionEvent, SessionEventType
client = CopilotClient()
-session = client.create_session({"on_permission_request": lambda req, inv: {"kind": "approved"}})
+session = client.create_session(on_permission_request=lambda req, inv: {"kind": "approved"})
# Subscribe to all events
unsubscribe = session.on(lambda event: print(f"Event: {event.type}"))
@@ -653,7 +651,7 @@ Update `main.py`:
import asyncio
import random
import sys
-from copilot import CopilotClient
+from copilot import CopilotClient, PermissionHandler
from copilot.tools import define_tool
from copilot.generated.session_events import SessionEventType
from pydantic import BaseModel, Field
@@ -676,11 +674,7 @@ async def main():
client = CopilotClient()
await client.start()
- session = await client.create_session({
- "model": "gpt-4.1",
- "streaming": True,
- "tools": [get_weather],
- })
+ session = await client.create_session(on_permission_request=PermissionHandler.approve_all, model="gpt-4.1", streaming=True, tools=[get_weather])
def handle_event(event):
if event.type == SessionEventType.ASSISTANT_MESSAGE_DELTA:
@@ -925,7 +919,7 @@ Create `weather_assistant.py`:
import asyncio
import random
import sys
-from copilot import CopilotClient
+from copilot import CopilotClient, PermissionHandler
from copilot.tools import define_tool
from copilot.generated.session_events import SessionEventType
from pydantic import BaseModel, Field
@@ -945,11 +939,7 @@ async def main():
client = CopilotClient()
await client.start()
- session = await client.create_session({
- "model": "gpt-4.1",
- "streaming": True,
- "tools": [get_weather],
- })
+ session = await client.create_session(on_permission_request=PermissionHandler.approve_all, model="gpt-4.1", streaming=True, tools=[get_weather])
def handle_event(event):
if event.type == SessionEventType.ASSISTANT_MESSAGE_DELTA:
@@ -1224,7 +1214,7 @@ const session = await client.createSession({
});
```
-📖 **[Full MCP documentation →](./mcp/overview.md)** - Learn about local vs remote servers, all configuration options, and troubleshooting.
+📖 **[Full MCP documentation →](./features/mcp.md)** - Learn about local vs remote servers, all configuration options, and troubleshooting.
### Create Custom Agents
@@ -1241,9 +1231,11 @@ const session = await client.createSession({
});
```
+> **Tip:** You can also set `agent: "pr-reviewer"` in the session config to pre-select this agent from the start. See the [Custom Agents guide](./guides/custom-agents.md#selecting-an-agent-at-session-creation) for details.
+
### Customize the System Message
-Control the AI's behavior and personality:
+Control the AI's behavior and personality by appending instructions:
```typescript
const session = await client.createSession({
@@ -1253,6 +1245,28 @@ const session = await client.createSession({
});
```
+For more fine-grained control, use `mode: "customize"` to override individual sections of the system prompt while preserving the rest:
+
+```typescript
+const session = await client.createSession({
+ systemMessage: {
+ mode: "customize",
+ sections: {
+ tone: { action: "replace", content: "Respond in a warm, professional tone. Be thorough in explanations." },
+ code_change_rules: { action: "remove" },
+ guidelines: { action: "append", content: "\n* Always cite data sources" },
+ },
+ content: "Focus on financial analysis and reporting.",
+ },
+});
+```
+
+Available section IDs: `identity`, `tone`, `tool_efficiency`, `environment_context`, `code_change_rules`, `guidelines`, `safety`, `tool_instructions`, `custom_instructions`, `last_instructions`.
+
+Each override supports four actions: `replace`, `remove`, `append`, and `prepend`. Unknown section IDs are handled gracefully — content is appended to additional instructions and a warning is emitted; `remove` on unknown sections is silently ignored.
+
+See the language-specific SDK READMEs for examples in [TypeScript](../nodejs/README.md), [Python](../python/README.md), [Go](../go/README.md), and [C#](../dotnet/README.md).
+
---
## Connecting to an External CLI Server
@@ -1306,7 +1320,7 @@ client = CopilotClient({
await client.start()
# Use the client normally
-session = await client.create_session({"on_permission_request": PermissionHandler.approve_all})
+session = await client.create_session(on_permission_request=PermissionHandler.approve_all)
# ...
```
@@ -1393,6 +1407,119 @@ await using var session = await client.CreateSessionAsync(new()
---
+## Telemetry & Observability
+
+The Copilot SDK supports [OpenTelemetry](https://opentelemetry.io/) for distributed tracing. Provide a `telemetry` configuration to the client to enable trace export from the CLI process and automatic [W3C Trace Context](https://www.w3.org/TR/trace-context/) propagation between the SDK and CLI.
+
+### Enabling Telemetry
+
+Pass a `telemetry` (or `Telemetry`) config when creating the client. This is the opt-in — no separate "enabled" flag is needed.
+
+
+Node.js / TypeScript
+
+
+```typescript
+import { CopilotClient } from "@github/copilot-sdk";
+
+const client = new CopilotClient({
+ telemetry: {
+ otlpEndpoint: "http://localhost:4318",
+ },
+});
+```
+
+Optional peer dependency: `@opentelemetry/api`
+
+
+
+
+Python
+
+
+```python
+from copilot import CopilotClient, SubprocessConfig
+
+client = CopilotClient(SubprocessConfig(
+ telemetry={
+ "otlp_endpoint": "http://localhost:4318",
+ },
+))
+```
+
+Install with telemetry extras: `pip install copilot-sdk[telemetry]` (provides `opentelemetry-api`)
+
+
+
+
+Go
+
+
+```go
+client, err := copilot.NewClient(copilot.ClientOptions{
+ Telemetry: &copilot.TelemetryConfig{
+ OTLPEndpoint: "http://localhost:4318",
+ },
+})
+```
+
+Dependency: `go.opentelemetry.io/otel`
+
+
+
+
+.NET
+
+
+```csharp
+var client = new CopilotClient(new CopilotClientOptions
+{
+ Telemetry = new TelemetryConfig
+ {
+ OtlpEndpoint = "http://localhost:4318",
+ },
+});
+```
+
+No extra dependencies — uses built-in `System.Diagnostics.Activity`.
+
+
+
+### TelemetryConfig Options
+
+| Option | Node.js | Python | Go | .NET | Description |
+|---|---|---|---|---|---|
+| OTLP endpoint | `otlpEndpoint` | `otlp_endpoint` | `OTLPEndpoint` | `OtlpEndpoint` | OTLP HTTP endpoint URL |
+| File path | `filePath` | `file_path` | `FilePath` | `FilePath` | File path for JSON-lines trace output |
+| Exporter type | `exporterType` | `exporter_type` | `ExporterType` | `ExporterType` | `"otlp-http"` or `"file"` |
+| Source name | `sourceName` | `source_name` | `SourceName` | `SourceName` | Instrumentation scope name |
+| Capture content | `captureContent` | `capture_content` | `CaptureContent` | `CaptureContent` | Whether to capture message content |
+
+### File Export
+
+To write traces to a local file instead of an OTLP endpoint:
+
+
+```typescript
+const client = new CopilotClient({
+ telemetry: {
+ filePath: "./traces.jsonl",
+ exporterType: "file",
+ },
+});
+```
+
+### Trace Context Propagation
+
+Trace context is propagated automatically — no manual instrumentation is needed:
+
+- **SDK → CLI**: `traceparent` and `tracestate` headers from the current span/activity are included in `session.create`, `session.resume`, and `session.send` RPC calls.
+- **CLI → SDK**: When the CLI invokes tool handlers, the trace context from the CLI's span is propagated so your tool code runs under the correct parent span.
+
+📖 **[OpenTelemetry Instrumentation Guide →](./observability/opentelemetry.md)** — TelemetryConfig options, trace context propagation, and per-language dependencies.
+
+---
+
## Learn More
- [Authentication Guide](./auth/index.md) - GitHub OAuth, environment variables, and BYOK
@@ -1401,9 +1528,10 @@ await using var session = await client.CreateSessionAsync(new()
- [Python SDK Reference](../python/README.md)
- [Go SDK Reference](../go/README.md)
- [.NET SDK Reference](../dotnet/README.md)
-- [Using MCP Servers](./mcp) - Integrate external tools via Model Context Protocol
+- [Using MCP Servers](./features/mcp.md) - Integrate external tools via Model Context Protocol
- [GitHub MCP Server Documentation](https://github.com/github/github-mcp-server)
- [MCP Servers Directory](https://github.com/modelcontextprotocol/servers) - Explore more MCP servers
+- [OpenTelemetry Instrumentation](./observability/opentelemetry.md) - TelemetryConfig, trace context propagation, and per-language dependencies
---
diff --git a/docs/guides/setup/byok.md b/docs/guides/setup/byok.md
deleted file mode 100644
index 5b8b8a460c..0000000000
--- a/docs/guides/setup/byok.md
+++ /dev/null
@@ -1,360 +0,0 @@
-# BYOK (Bring Your Own Key) Setup
-
-Use your own model provider API keys instead of GitHub Copilot authentication. You control the identity layer, the model provider, and the billing — the SDK provides the agent runtime.
-
-**Best for:** Apps where users don't have GitHub accounts, enterprise deployments with existing model provider contracts, apps needing full control over identity and billing.
-
-## How It Works
-
-With BYOK, the SDK uses the Copilot CLI as an agent runtime only — it doesn't call GitHub's Copilot API. Instead, model requests go directly to your configured provider (OpenAI, Azure AI Foundry, Anthropic, etc.).
-
-```mermaid
-flowchart LR
- subgraph App["Your Application"]
- SDK["SDK Client"]
- IdP["Your Identity
Provider"]
- end
-
- subgraph CLI["Copilot CLI"]
- Runtime["Agent Runtime"]
- end
-
- subgraph Provider["Your Model Provider"]
- API["OpenAI / Azure /
Anthropic / Ollama"]
- end
-
- IdP -.->|"authenticates
users"| SDK
- SDK --> Runtime
- Runtime -- "API key" --> API
-
- style App fill:#0d1117,stroke:#58a6ff,color:#c9d1d9
- style CLI fill:#0d1117,stroke:#3fb950,color:#c9d1d9
- style Provider fill:#161b22,stroke:#f0883e,color:#c9d1d9
-```
-
-**Key characteristics:**
-- No GitHub Copilot subscription needed
-- No GitHub account needed for end users
-- You manage authentication and identity yourself
-- Model requests go to your provider, billed to your account
-- Full agent runtime capabilities (tools, sessions, streaming) still work
-
-## Architecture: GitHub Auth vs. BYOK
-
-```mermaid
-flowchart TB
- subgraph GitHub["GitHub Auth Path"]
- direction LR
- G1["User"] --> G2["GitHub OAuth"]
- G2 --> G3["SDK + CLI"]
- G3 --> G4["☁️ Copilot API"]
- end
-
- subgraph BYOK["BYOK Path"]
- direction LR
- B1["User"] --> B2["Your Auth"]
- B2 --> B3["SDK + CLI"]
- B3 --> B4["☁️ Your Provider"]
- end
-
- style GitHub fill:#161b22,stroke:#8b949e,color:#c9d1d9
- style BYOK fill:#0d1117,stroke:#3fb950,color:#c9d1d9
-```
-
-## Quick Start
-
-
-Node.js / TypeScript
-
-```typescript
-import { CopilotClient } from "@github/copilot-sdk";
-
-const client = new CopilotClient();
-
-const session = await client.createSession({
- model: "gpt-4.1",
- provider: {
- type: "openai",
- baseUrl: "https://api.openai.com/v1",
- apiKey: process.env.OPENAI_API_KEY,
- },
-});
-
-const response = await session.sendAndWait({ prompt: "Hello!" });
-console.log(response?.data.content);
-
-await client.stop();
-```
-
-
-
-
-Python
-
-```python
-import os
-from copilot import CopilotClient
-
-client = CopilotClient()
-await client.start()
-
-session = await client.create_session({
- "model": "gpt-4.1",
- "provider": {
- "type": "openai",
- "base_url": "https://api.openai.com/v1",
- "api_key": os.environ["OPENAI_API_KEY"],
- },
-})
-
-response = await session.send_and_wait({"prompt": "Hello!"})
-print(response.data.content)
-
-await client.stop()
-```
-
-
-
-
-Go
-
-
-```go
-client := copilot.NewClient(nil)
-client.Start(ctx)
-defer client.Stop()
-
-session, _ := client.CreateSession(ctx, &copilot.SessionConfig{
- Model: "gpt-4.1",
- Provider: &copilot.ProviderConfig{
- Type: "openai",
- BaseURL: "https://api.openai.com/v1",
- APIKey: os.Getenv("OPENAI_API_KEY"),
- },
-})
-
-response, _ := session.SendAndWait(ctx, copilot.MessageOptions{Prompt: "Hello!"})
-fmt.Println(*response.Data.Content)
-```
-
-
-
-
-.NET
-
-```csharp
-await using var client = new CopilotClient();
-await using var session = await client.CreateSessionAsync(new SessionConfig
-{
- Model = "gpt-4.1",
- Provider = new ProviderConfig
- {
- Type = "openai",
- BaseUrl = "https://api.openai.com/v1",
- ApiKey = Environment.GetEnvironmentVariable("OPENAI_API_KEY"),
- },
-});
-
-var response = await session.SendAndWaitAsync(
- new MessageOptions { Prompt = "Hello!" });
-Console.WriteLine(response?.Data.Content);
-```
-
-
-
-## Provider Configurations
-
-### OpenAI
-
-```typescript
-provider: {
- type: "openai",
- baseUrl: "https://api.openai.com/v1",
- apiKey: process.env.OPENAI_API_KEY,
-}
-```
-
-### Azure AI Foundry
-
-```typescript
-provider: {
- type: "openai",
- baseUrl: "https://your-resource.openai.azure.com/openai/v1/",
- apiKey: process.env.FOUNDRY_API_KEY,
- wireApi: "responses", // For GPT-5 series models
-}
-```
-
-### Azure OpenAI (Native)
-
-```typescript
-provider: {
- type: "azure",
- baseUrl: "https://your-resource.openai.azure.com",
- apiKey: process.env.AZURE_OPENAI_KEY,
- azure: { apiVersion: "2024-10-21" },
-}
-```
-
-### Anthropic
-
-```typescript
-provider: {
- type: "anthropic",
- baseUrl: "https://api.anthropic.com",
- apiKey: process.env.ANTHROPIC_API_KEY,
-}
-```
-
-### Ollama (Local)
-
-```typescript
-provider: {
- type: "openai",
- baseUrl: "http://localhost:11434/v1",
- // No API key needed for local Ollama
-}
-```
-
-## Managing Identity Yourself
-
-With BYOK, you're responsible for authentication. Here are common patterns:
-
-### Pattern 1: Your Own Identity Provider
-
-```mermaid
-sequenceDiagram
- participant User
- participant App as Your App
- participant IdP as Your Identity Provider
- participant SDK as SDK + CLI
- participant LLM as Model Provider
-
- User->>App: Login
- App->>IdP: Authenticate user
- IdP-->>App: User identity + permissions
-
- App->>App: Look up API key for user's tier
- App->>SDK: Create session (with provider config)
- SDK->>LLM: Model request (your API key)
- LLM-->>SDK: Response
- SDK-->>App: Result
- App-->>User: Display
-```
-
-```typescript
-// Your app handles auth, then creates sessions with your API key
-app.post("/chat", authMiddleware, async (req, res) => {
- const user = req.user; // From your auth middleware
-
- // Use your API key — not the user's
- const session = await getOrCreateSession(user.id, {
- model: getModelForTier(user.tier), // "gpt-4.1" for pro, etc.
- provider: {
- type: "openai",
- baseUrl: "https://api.openai.com/v1",
- apiKey: process.env.OPENAI_API_KEY, // Your key, your billing
- },
- });
-
- const response = await session.sendAndWait({ prompt: req.body.message });
- res.json({ content: response?.data.content });
-});
-```
-
-### Pattern 2: Per-Customer API Keys
-
-For B2B apps where each customer brings their own model provider keys:
-
-```mermaid
-flowchart TB
- subgraph Customers
- C1["Customer A
(OpenAI key)"]
- C2["Customer B
(Azure key)"]
- C3["Customer C
(Anthropic key)"]
- end
-
- subgraph App["Your App"]
- Router["Request Router"]
- KS["Key Store
(encrypted)"]
- end
-
- C1 --> Router
- C2 --> Router
- C3 --> Router
-
- Router --> KS
- KS --> SDK1["SDK → OpenAI"]
- KS --> SDK2["SDK → Azure"]
- KS --> SDK3["SDK → Anthropic"]
-
- style App fill:#0d1117,stroke:#58a6ff,color:#c9d1d9
-```
-
-```typescript
-async function createSessionForCustomer(customerId: string) {
- const config = await keyStore.getProviderConfig(customerId);
-
- return client.createSession({
- sessionId: `customer-${customerId}-${Date.now()}`,
- model: config.model,
- provider: {
- type: config.providerType,
- baseUrl: config.baseUrl,
- apiKey: config.apiKey,
- },
- });
-}
-```
-
-## Session Persistence with BYOK
-
-When resuming BYOK sessions, you **must** re-provide the provider configuration. API keys are never persisted to disk for security.
-
-```typescript
-// Create session
-const session = await client.createSession({
- sessionId: "task-123",
- model: "gpt-4.1",
- provider: {
- type: "openai",
- baseUrl: "https://api.openai.com/v1",
- apiKey: process.env.OPENAI_API_KEY,
- },
-});
-
-// Resume later — must re-provide provider config
-const resumed = await client.resumeSession("task-123", {
- provider: {
- type: "openai",
- baseUrl: "https://api.openai.com/v1",
- apiKey: process.env.OPENAI_API_KEY, // Required again
- },
-});
-```
-
-## Limitations
-
-| Limitation | Details |
-|------------|---------|
-| **Static credentials only** | API keys or bearer tokens — no native Entra ID, OIDC, or managed identity support. See [Azure Managed Identity workaround](./azure-managed-identity.md) for using `DefaultAzureCredential` with short-lived tokens. |
-| **No auto-refresh** | If a bearer token expires, you must create a new session |
-| **Your billing** | All model usage is billed to your provider account |
-| **Model availability** | Limited to what your provider offers |
-| **Keys not persisted** | Must re-provide on session resume |
-
-For the full BYOK reference, see the **[BYOK documentation](../../auth/byok.md)**.
-
-## When to Move On
-
-| Need | Next Guide |
-|------|-----------|
-| Run the SDK on a server | [Backend Services](./backend-services.md) |
-| Multiple users with GitHub accounts | [GitHub OAuth](./github-oauth.md) |
-| Handle many concurrent users | [Scaling & Multi-Tenancy](./scaling.md) |
-
-## Next Steps
-
-- **[BYOK reference](../../auth/byok.md)** — Full provider config details and troubleshooting
-- **[Backend Services](./backend-services.md)** — Deploy the SDK server-side
-- **[Scaling & Multi-Tenancy](./scaling.md)** — Serve many customers at scale
diff --git a/docs/hooks/error-handling.md b/docs/hooks/error-handling.md
index 0f705868df..a67906ac94 100644
--- a/docs/hooks/error-handling.md
+++ b/docs/hooks/error-handling.md
@@ -12,7 +12,15 @@ The `onErrorOccurred` hook is called when errors occur during session execution.
Node.js / TypeScript
-
+
+```ts
+import type { ErrorOccurredHookInput, HookInvocation, ErrorOccurredHookOutput } from "@github/copilot-sdk";
+type ErrorOccurredHandler = (
+ input: ErrorOccurredHookInput,
+ invocation: HookInvocation
+) => Promise;
+```
+
```typescript
type ErrorOccurredHandler = (
input: ErrorOccurredHookInput,
@@ -25,7 +33,17 @@ type ErrorOccurredHandler = (
Python
-
+
+```python
+from copilot.types import ErrorOccurredHookInput, HookInvocation, ErrorOccurredHookOutput
+from typing import Callable, Awaitable
+
+ErrorOccurredHandler = Callable[
+ [ErrorOccurredHookInput, HookInvocation],
+ Awaitable[ErrorOccurredHookOutput | None]
+]
+```
+
```python
ErrorOccurredHandler = Callable[
[ErrorOccurredHookInput, HookInvocation],
@@ -38,7 +56,20 @@ ErrorOccurredHandler = Callable[
Go
-
+
+```go
+package main
+
+import copilot "github.com/github/copilot-sdk/go"
+
+type ErrorOccurredHandler func(
+ input copilot.ErrorOccurredHookInput,
+ invocation copilot.HookInvocation,
+) (*copilot.ErrorOccurredHookOutput, error)
+
+func main() {}
+```
+
```go
type ErrorOccurredHandler func(
input ErrorOccurredHookInput,
@@ -51,7 +82,15 @@ type ErrorOccurredHandler func(
.NET
-
+
+```csharp
+using GitHub.Copilot.SDK;
+
+public delegate Task ErrorOccurredHandler(
+ ErrorOccurredHookInput input,
+ HookInvocation invocation);
+```
+
```csharp
public delegate Task ErrorOccurredHandler(
ErrorOccurredHookInput input,
@@ -107,15 +146,15 @@ const session = await client.createSession({
Python
```python
+from copilot import PermissionHandler
+
async def on_error_occurred(input_data, invocation):
print(f"[{invocation['session_id']}] Error: {input_data['error']}")
print(f" Context: {input_data['errorContext']}")
print(f" Recoverable: {input_data['recoverable']}")
return None
-session = await client.create_session({
- "hooks": {"on_error_occurred": on_error_occurred}
-})
+session = await client.create_session(on_permission_request=PermissionHandler.approve_all, hooks={"on_error_occurred": on_error_occurred})
```
@@ -123,7 +162,33 @@ session = await client.create_session({
Go
-
+
+```go
+package main
+
+import (
+ "context"
+ "fmt"
+ copilot "github.com/github/copilot-sdk/go"
+)
+
+func main() {
+ client := copilot.NewClient(nil)
+ session, _ := client.CreateSession(context.Background(), &copilot.SessionConfig{
+ OnPermissionRequest: copilot.PermissionHandler.ApproveAll,
+ Hooks: &copilot.SessionHooks{
+ OnErrorOccurred: func(input copilot.ErrorOccurredHookInput, inv copilot.HookInvocation) (*copilot.ErrorOccurredHookOutput, error) {
+ fmt.Printf("[%s] Error: %s\n", inv.SessionID, input.Error)
+ fmt.Printf(" Context: %s\n", input.ErrorContext)
+ fmt.Printf(" Recoverable: %v\n", input.Recoverable)
+ return nil, nil
+ },
+ },
+ })
+ _ = session
+}
+```
+
```go
session, _ := client.CreateSession(context.Background(), &copilot.SessionConfig{
Hooks: &copilot.SessionHooks{
@@ -142,7 +207,32 @@ session, _ := client.CreateSession(context.Background(), &copilot.SessionConfig{
.NET
-
+
+```csharp
+using GitHub.Copilot.SDK;
+
+public static class ErrorHandlingExample
+{
+ public static async Task Main()
+ {
+ await using var client = new CopilotClient();
+ var session = await client.CreateSessionAsync(new SessionConfig
+ {
+ Hooks = new SessionHooks
+ {
+ OnErrorOccurred = (input, invocation) =>
+ {
+ Console.Error.WriteLine($"[{invocation.SessionId}] Error: {input.Error}");
+ Console.Error.WriteLine($" Context: {input.ErrorContext}");
+ Console.Error.WriteLine($" Recoverable: {input.Recoverable}");
+ return Task.FromResult(null);
+ },
+ },
+ });
+ }
+}
+```
+
```csharp
var session = await client.CreateSessionAsync(new SessionConfig
{
@@ -381,6 +471,6 @@ const session = await client.createSession({
## See Also
-- [Hooks Overview](./overview.md)
+- [Hooks Overview](./index.md)
- [Session Lifecycle Hooks](./session-lifecycle.md)
-- [Debugging Guide](../debugging.md)
+- [Debugging Guide](../troubleshooting/debugging.md)
diff --git a/docs/hooks/overview.md b/docs/hooks/index.md
similarity index 96%
rename from docs/hooks/overview.md
rename to docs/hooks/index.md
index a51ef04640..d83b11b2f9 100644
--- a/docs/hooks/overview.md
+++ b/docs/hooks/index.md
@@ -53,7 +53,7 @@ const session = await client.createSession({
Python
```python
-from copilot import CopilotClient
+from copilot import CopilotClient, PermissionHandler
async def main():
client = CopilotClient()
@@ -70,13 +70,11 @@ async def main():
async def on_session_start(input_data, invocation):
return {"additionalContext": "User prefers concise answers."}
- session = await client.create_session({
- "hooks": {
+ session = await client.create_session(on_permission_request=PermissionHandler.approve_all, hooks={
"on_pre_tool_use": on_pre_tool_use,
"on_post_tool_use": on_post_tool_use,
"on_session_start": on_session_start,
- }
- })
+ })
```
@@ -233,4 +231,4 @@ const session = await client.createSession({
- [Getting Started Guide](../getting-started.md)
- [Custom Tools](../getting-started.md#step-4-add-a-custom-tool)
-- [Debugging Guide](../debugging.md)
+- [Debugging Guide](../troubleshooting/debugging.md)
diff --git a/docs/hooks/post-tool-use.md b/docs/hooks/post-tool-use.md
index 0021e20a0d..029e9eb2f7 100644
--- a/docs/hooks/post-tool-use.md
+++ b/docs/hooks/post-tool-use.md
@@ -12,7 +12,15 @@ The `onPostToolUse` hook is called **after** a tool executes. Use it to:
Node.js / TypeScript
-
+
+```ts
+import type { PostToolUseHookInput, HookInvocation, PostToolUseHookOutput } from "@github/copilot-sdk";
+type PostToolUseHandler = (
+ input: PostToolUseHookInput,
+ invocation: HookInvocation
+) => Promise;
+```
+
```typescript
type PostToolUseHandler = (
input: PostToolUseHookInput,
@@ -25,7 +33,17 @@ type PostToolUseHandler = (
Python
-
+
+```python
+from copilot.types import PostToolUseHookInput, HookInvocation, PostToolUseHookOutput
+from typing import Callable, Awaitable
+
+PostToolUseHandler = Callable[
+ [PostToolUseHookInput, HookInvocation],
+ Awaitable[PostToolUseHookOutput | None]
+]
+```
+
```python
PostToolUseHandler = Callable[
[PostToolUseHookInput, HookInvocation],
@@ -38,7 +56,20 @@ PostToolUseHandler = Callable[
Go
-
+
+```go
+package main
+
+import copilot "github.com/github/copilot-sdk/go"
+
+type PostToolUseHandler func(
+ input copilot.PostToolUseHookInput,
+ invocation copilot.HookInvocation,
+) (*copilot.PostToolUseHookOutput, error)
+
+func main() {}
+```
+
```go
type PostToolUseHandler func(
input PostToolUseHookInput,
@@ -51,7 +82,15 @@ type PostToolUseHandler func(
.NET
-
+
+```csharp
+using GitHub.Copilot.SDK;
+
+public delegate Task PostToolUseHandler(
+ PostToolUseHookInput input,
+ HookInvocation invocation);
+```
+
```csharp
public delegate Task PostToolUseHandler(
PostToolUseHookInput input,
@@ -106,15 +145,15 @@ const session = await client.createSession({
Python
```python
+from copilot import PermissionHandler
+
async def on_post_tool_use(input_data, invocation):
print(f"[{invocation['session_id']}] Tool: {input_data['toolName']}")
print(f" Args: {input_data['toolArgs']}")
print(f" Result: {input_data['toolResult']}")
return None # Pass through unchanged
-session = await client.create_session({
- "hooks": {"on_post_tool_use": on_post_tool_use}
-})
+session = await client.create_session(on_permission_request=PermissionHandler.approve_all, hooks={"on_post_tool_use": on_post_tool_use})
```
@@ -122,7 +161,33 @@ session = await client.create_session({
Go
-
+
+```go
+package main
+
+import (
+ "context"
+ "fmt"
+ copilot "github.com/github/copilot-sdk/go"
+)
+
+func main() {
+ client := copilot.NewClient(nil)
+ session, _ := client.CreateSession(context.Background(), &copilot.SessionConfig{
+ OnPermissionRequest: copilot.PermissionHandler.ApproveAll,
+ Hooks: &copilot.SessionHooks{
+ OnPostToolUse: func(input copilot.PostToolUseHookInput, inv copilot.HookInvocation) (*copilot.PostToolUseHookOutput, error) {
+ fmt.Printf("[%s] Tool: %s\n", inv.SessionID, input.ToolName)
+ fmt.Printf(" Args: %v\n", input.ToolArgs)
+ fmt.Printf(" Result: %v\n", input.ToolResult)
+ return nil, nil
+ },
+ },
+ })
+ _ = session
+}
+```
+
```go
session, _ := client.CreateSession(context.Background(), &copilot.SessionConfig{
Hooks: &copilot.SessionHooks{
@@ -141,7 +206,32 @@ session, _ := client.CreateSession(context.Background(), &copilot.SessionConfig{
.NET
-
+
+```csharp
+using GitHub.Copilot.SDK;
+
+public static class PostToolUseExample
+{
+ public static async Task Main()
+ {
+ await using var client = new CopilotClient();
+ var session = await client.CreateSessionAsync(new SessionConfig
+ {
+ Hooks = new SessionHooks
+ {
+ OnPostToolUse = (input, invocation) =>
+ {
+ Console.WriteLine($"[{invocation.SessionId}] Tool: {input.ToolName}");
+ Console.WriteLine($" Args: {input.ToolArgs}");
+ Console.WriteLine($" Result: {input.ToolResult}");
+ return Task.FromResult(null);
+ },
+ },
+ });
+ }
+}
+```
+
```csharp
var session = await client.CreateSessionAsync(new SessionConfig
{
@@ -338,6 +428,6 @@ const session = await client.createSession({
## See Also
-- [Hooks Overview](./overview.md)
+- [Hooks Overview](./index.md)
- [Pre-Tool Use Hook](./pre-tool-use.md)
- [Error Handling Hook](./error-handling.md)
diff --git a/docs/hooks/pre-tool-use.md b/docs/hooks/pre-tool-use.md
index ac12df4fab..e1bb974951 100644
--- a/docs/hooks/pre-tool-use.md
+++ b/docs/hooks/pre-tool-use.md
@@ -12,7 +12,15 @@ The `onPreToolUse` hook is called **before** a tool executes. Use it to:
Node.js / TypeScript
-
+
+```ts
+import type { PreToolUseHookInput, HookInvocation, PreToolUseHookOutput } from "@github/copilot-sdk";
+type PreToolUseHandler = (
+ input: PreToolUseHookInput,
+ invocation: HookInvocation
+) => Promise;
+```
+
```typescript
type PreToolUseHandler = (
input: PreToolUseHookInput,
@@ -25,7 +33,17 @@ type PreToolUseHandler = (
Python
-
+
+```python
+from copilot.types import PreToolUseHookInput, HookInvocation, PreToolUseHookOutput
+from typing import Callable, Awaitable
+
+PreToolUseHandler = Callable[
+ [PreToolUseHookInput, HookInvocation],
+ Awaitable[PreToolUseHookOutput | None]
+]
+```
+
```python
PreToolUseHandler = Callable[
[PreToolUseHookInput, HookInvocation],
@@ -38,7 +56,20 @@ PreToolUseHandler = Callable[
Go
-
+
+```go
+package main
+
+import copilot "github.com/github/copilot-sdk/go"
+
+type PreToolUseHandler func(
+ input copilot.PreToolUseHookInput,
+ invocation copilot.HookInvocation,
+) (*copilot.PreToolUseHookOutput, error)
+
+func main() {}
+```
+
```go
type PreToolUseHandler func(
input PreToolUseHookInput,
@@ -51,7 +82,15 @@ type PreToolUseHandler func(
.NET
-
+
+```csharp
+using GitHub.Copilot.SDK;
+
+public delegate Task PreToolUseHandler(
+ PreToolUseHookInput input,
+ HookInvocation invocation);
+```
+
```csharp
public delegate Task PreToolUseHandler(
PreToolUseHookInput input,
@@ -114,14 +153,14 @@ const session = await client.createSession({
Python
```python
+from copilot import PermissionHandler
+
async def on_pre_tool_use(input_data, invocation):
print(f"[{invocation['session_id']}] Calling {input_data['toolName']}")
print(f" Args: {input_data['toolArgs']}")
return {"permissionDecision": "allow"}
-session = await client.create_session({
- "hooks": {"on_pre_tool_use": on_pre_tool_use}
-})
+session = await client.create_session(on_permission_request=PermissionHandler.approve_all, hooks={"on_pre_tool_use": on_pre_tool_use})
```
@@ -129,7 +168,34 @@ session = await client.create_session({
Go
-
+
+```go
+package main
+
+import (
+ "context"
+ "fmt"
+ copilot "github.com/github/copilot-sdk/go"
+)
+
+func main() {
+ client := copilot.NewClient(nil)
+ session, _ := client.CreateSession(context.Background(), &copilot.SessionConfig{
+ OnPermissionRequest: copilot.PermissionHandler.ApproveAll,
+ Hooks: &copilot.SessionHooks{
+ OnPreToolUse: func(input copilot.PreToolUseHookInput, inv copilot.HookInvocation) (*copilot.PreToolUseHookOutput, error) {
+ fmt.Printf("[%s] Calling %s\n", inv.SessionID, input.ToolName)
+ fmt.Printf(" Args: %v\n", input.ToolArgs)
+ return &copilot.PreToolUseHookOutput{
+ PermissionDecision: "allow",
+ }, nil
+ },
+ },
+ })
+ _ = session
+}
+```
+
```go
session, _ := client.CreateSession(context.Background(), &copilot.SessionConfig{
Hooks: &copilot.SessionHooks{
@@ -149,7 +215,33 @@ session, _ := client.CreateSession(context.Background(), &copilot.SessionConfig{
.NET
-
+
+```csharp
+using GitHub.Copilot.SDK;
+
+public static class PreToolUseExample
+{
+ public static async Task Main()
+ {
+ await using var client = new CopilotClient();
+ var session = await client.CreateSessionAsync(new SessionConfig
+ {
+ Hooks = new SessionHooks
+ {
+ OnPreToolUse = (input, invocation) =>
+ {
+ Console.WriteLine($"[{invocation.SessionId}] Calling {input.ToolName}");
+ Console.WriteLine($" Args: {input.ToolArgs}");
+ return Task.FromResult(
+ new PreToolUseHookOutput { PermissionDecision = "allow" }
+ );
+ },
+ },
+ });
+ }
+}
+```
+
```csharp
var session = await client.CreateSessionAsync(new SessionConfig
{
@@ -294,6 +386,6 @@ const session = await client.createSession({
## See Also
-- [Hooks Overview](./overview.md)
+- [Hooks Overview](./index.md)
- [Post-Tool Use Hook](./post-tool-use.md)
-- [Debugging Guide](../debugging.md)
+- [Debugging Guide](../troubleshooting/debugging.md)
diff --git a/docs/hooks/session-lifecycle.md b/docs/hooks/session-lifecycle.md
index 74f4666f45..4efd33ccc0 100644
--- a/docs/hooks/session-lifecycle.md
+++ b/docs/hooks/session-lifecycle.md
@@ -16,7 +16,15 @@ The `onSessionStart` hook is called when a session begins (new or resumed).
Node.js / TypeScript
-
+
+```ts
+import type { SessionStartHookInput, HookInvocation, SessionStartHookOutput } from "@github/copilot-sdk";
+type SessionStartHandler = (
+ input: SessionStartHookInput,
+ invocation: HookInvocation
+) => Promise;
+```
+
```typescript
type SessionStartHandler = (
input: SessionStartHookInput,
@@ -29,7 +37,17 @@ type SessionStartHandler = (
Python
-
+
+```python
+from copilot.types import SessionStartHookInput, HookInvocation, SessionStartHookOutput
+from typing import Callable, Awaitable
+
+SessionStartHandler = Callable[
+ [SessionStartHookInput, HookInvocation],
+ Awaitable[SessionStartHookOutput | None]
+]
+```
+
```python
SessionStartHandler = Callable[
[SessionStartHookInput, HookInvocation],
@@ -42,7 +60,20 @@ SessionStartHandler = Callable[
Go
-
+
+```go
+package main
+
+import copilot "github.com/github/copilot-sdk/go"
+
+type SessionStartHandler func(
+ input copilot.SessionStartHookInput,
+ invocation copilot.HookInvocation,
+) (*copilot.SessionStartHookOutput, error)
+
+func main() {}
+```
+
```go
type SessionStartHandler func(
input SessionStartHookInput,
@@ -55,7 +86,15 @@ type SessionStartHandler func(
.NET
-
+
+```csharp
+using GitHub.Copilot.SDK;
+
+public delegate Task SessionStartHandler(
+ SessionStartHookInput input,
+ HookInvocation invocation);
+```
+
```csharp
public delegate Task SessionStartHandler(
SessionStartHookInput input,
@@ -113,6 +152,8 @@ Package manager: ${projectInfo.packageManager}
Python
```python
+from copilot import PermissionHandler
+
async def on_session_start(input_data, invocation):
print(f"Session {invocation['session_id']} started ({input_data['source']})")
@@ -126,9 +167,7 @@ Package manager: {project_info['packageManager']}
""".strip()
}
-session = await client.create_session({
- "hooks": {"on_session_start": on_session_start}
-})
+session = await client.create_session(on_permission_request=PermissionHandler.approve_all, hooks={"on_session_start": on_session_start})
```
@@ -208,7 +247,17 @@ type SessionEndHandler = (
Python
-
+
+```python
+from copilot.types import SessionEndHookInput, HookInvocation
+from typing import Callable, Awaitable
+
+SessionEndHandler = Callable[
+ [SessionEndHookInput, HookInvocation],
+ Awaitable[None]
+]
+```
+
```python
SessionEndHandler = Callable[
[SessionEndHookInput, HookInvocation],
@@ -221,7 +270,20 @@ SessionEndHandler = Callable[
Go
-
+
+```go
+package main
+
+import copilot "github.com/github/copilot-sdk/go"
+
+type SessionEndHandler func(
+ input copilot.SessionEndHookInput,
+ invocation copilot.HookInvocation,
+) error
+
+func main() {}
+```
+
```go
type SessionEndHandler func(
input SessionEndHookInput,
@@ -309,6 +371,8 @@ const session = await client.createSession({
Python
```python
+from copilot import PermissionHandler
+
session_start_times = {}
async def on_session_start(input_data, invocation):
@@ -328,12 +392,10 @@ async def on_session_end(input_data, invocation):
session_start_times.pop(invocation["session_id"], None)
return None
-session = await client.create_session({
- "hooks": {
+session = await client.create_session(on_permission_request=PermissionHandler.approve_all, hooks={
"on_session_start": on_session_start,
"on_session_end": on_session_end,
- }
-})
+ })
```
@@ -442,6 +504,6 @@ Session Summary:
## See Also
-- [Hooks Overview](./overview.md)
+- [Hooks Overview](./index.md)
- [Error Handling Hook](./error-handling.md)
-- [Debugging Guide](../debugging.md)
+- [Debugging Guide](../troubleshooting/debugging.md)
diff --git a/docs/hooks/user-prompt-submitted.md b/docs/hooks/user-prompt-submitted.md
index 3205b95cd4..2aca7f1cec 100644
--- a/docs/hooks/user-prompt-submitted.md
+++ b/docs/hooks/user-prompt-submitted.md
@@ -12,7 +12,15 @@ The `onUserPromptSubmitted` hook is called when a user submits a message. Use it
Node.js / TypeScript
-
+
+```ts
+import type { UserPromptSubmittedHookInput, HookInvocation, UserPromptSubmittedHookOutput } from "@github/copilot-sdk";
+type UserPromptSubmittedHandler = (
+ input: UserPromptSubmittedHookInput,
+ invocation: HookInvocation
+) => Promise;
+```
+
```typescript
type UserPromptSubmittedHandler = (
input: UserPromptSubmittedHookInput,
@@ -25,7 +33,17 @@ type UserPromptSubmittedHandler = (
Python
-
+
+```python
+from copilot.types import UserPromptSubmittedHookInput, HookInvocation, UserPromptSubmittedHookOutput
+from typing import Callable, Awaitable
+
+UserPromptSubmittedHandler = Callable[
+ [UserPromptSubmittedHookInput, HookInvocation],
+ Awaitable[UserPromptSubmittedHookOutput | None]
+]
+```
+
```python
UserPromptSubmittedHandler = Callable[
[UserPromptSubmittedHookInput, HookInvocation],
@@ -38,7 +56,20 @@ UserPromptSubmittedHandler = Callable[
Go
-
+
+```go
+package main
+
+import copilot "github.com/github/copilot-sdk/go"
+
+type UserPromptSubmittedHandler func(
+ input copilot.UserPromptSubmittedHookInput,
+ invocation copilot.HookInvocation,
+) (*copilot.UserPromptSubmittedHookOutput, error)
+
+func main() {}
+```
+
```go
type UserPromptSubmittedHandler func(
input UserPromptSubmittedHookInput,
@@ -51,7 +82,15 @@ type UserPromptSubmittedHandler func(
.NET
-
+
+```csharp
+using GitHub.Copilot.SDK;
+
+public delegate Task UserPromptSubmittedHandler(
+ UserPromptSubmittedHookInput input,
+ HookInvocation invocation);
+```
+
```csharp
public delegate Task UserPromptSubmittedHandler(
UserPromptSubmittedHookInput input,
@@ -102,13 +141,13 @@ const session = await client.createSession({
Python
```python
+from copilot import PermissionHandler
+
async def on_user_prompt_submitted(input_data, invocation):
print(f"[{invocation['session_id']}] User: {input_data['prompt']}")
return None
-session = await client.create_session({
- "hooks": {"on_user_prompt_submitted": on_user_prompt_submitted}
-})
+session = await client.create_session(on_permission_request=PermissionHandler.approve_all, hooks={"on_user_prompt_submitted": on_user_prompt_submitted})
```
@@ -116,7 +155,31 @@ session = await client.create_session({
Go
-
+
+```go
+package main
+
+import (
+ "context"
+ "fmt"
+ copilot "github.com/github/copilot-sdk/go"
+)
+
+func main() {
+ client := copilot.NewClient(nil)
+ session, _ := client.CreateSession(context.Background(), &copilot.SessionConfig{
+ OnPermissionRequest: copilot.PermissionHandler.ApproveAll,
+ Hooks: &copilot.SessionHooks{
+ OnUserPromptSubmitted: func(input copilot.UserPromptSubmittedHookInput, inv copilot.HookInvocation) (*copilot.UserPromptSubmittedHookOutput, error) {
+ fmt.Printf("[%s] User: %s\n", inv.SessionID, input.Prompt)
+ return nil, nil
+ },
+ },
+ })
+ _ = session
+}
+```
+
```go
session, _ := client.CreateSession(context.Background(), &copilot.SessionConfig{
Hooks: &copilot.SessionHooks{
@@ -133,7 +196,30 @@ session, _ := client.CreateSession(context.Background(), &copilot.SessionConfig{
.NET
-
+
+```csharp
+using GitHub.Copilot.SDK;
+
+public static class UserPromptSubmittedExample
+{
+ public static async Task Main()
+ {
+ await using var client = new CopilotClient();
+ var session = await client.CreateSessionAsync(new SessionConfig
+ {
+ Hooks = new SessionHooks
+ {
+ OnUserPromptSubmitted = (input, invocation) =>
+ {
+ Console.WriteLine($"[{invocation.SessionId}] User: {input.Prompt}");
+ return Task.FromResult(null);
+ },
+ },
+ });
+ }
+}
+```
+
```csharp
var session = await client.CreateSessionAsync(new SessionConfig
{
@@ -360,6 +446,6 @@ const session = await client.createSession({
## See Also
-- [Hooks Overview](./overview.md)
+- [Hooks Overview](./index.md)
- [Session Lifecycle Hooks](./session-lifecycle.md)
- [Pre-Tool Use Hook](./pre-tool-use.md)
diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 0000000000..04ef99bd88
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,76 @@
+# GitHub Copilot SDK Documentation
+
+Welcome to the GitHub Copilot SDK docs. Whether you're building your first Copilot-powered app or deploying to production, you'll find what you need here.
+
+## Where to Start
+
+| I want to... | Go to |
+|---|---|
+| **Build my first app** | [Getting Started](./getting-started.md) — end-to-end tutorial with streaming & custom tools |
+| **Set up for production** | [Setup Guides](./setup/index.md) — architecture, deployment patterns, scaling |
+| **Configure authentication** | [Authentication](./auth/index.md) — GitHub OAuth, environment variables, BYOK |
+| **Add features to my app** | [Features](./features/index.md) — hooks, custom agents, MCP, skills, and more |
+| **Debug an issue** | [Troubleshooting](./troubleshooting/debugging.md) — common problems and solutions |
+
+## Documentation Map
+
+### [Getting Started](./getting-started.md)
+
+Step-by-step tutorial that takes you from zero to a working Copilot app with streaming responses and custom tools.
+
+### [Setup](./setup/index.md)
+
+How to configure and deploy the SDK for your use case.
+
+- [Local CLI](./setup/local-cli.md) — simplest path, uses your signed-in CLI
+- [Bundled CLI](./setup/bundled-cli.md) — ship the CLI with your app
+- [Backend Services](./setup/backend-services.md) — server-side with headless CLI over TCP
+- [GitHub OAuth](./setup/github-oauth.md) — implement the OAuth flow
+- [Azure Managed Identity](./setup/azure-managed-identity.md) — BYOK with Azure AI Foundry
+- [Scaling & Multi-Tenancy](./setup/scaling.md) — horizontal scaling, isolation patterns
+
+### [Authentication](./auth/index.md)
+
+Configuring how users and services authenticate with Copilot.
+
+- [Authentication Overview](./auth/index.md) — methods, priority order, and examples
+- [Bring Your Own Key (BYOK)](./auth/byok.md) — use your own API keys from OpenAI, Azure, Anthropic, and more
+
+### [Features](./features/index.md)
+
+Guides for building with the SDK's capabilities.
+
+- [Hooks](./features/hooks.md) — intercept and customize session behavior
+- [Custom Agents](./features/custom-agents.md) — define specialized sub-agents
+- [MCP Servers](./features/mcp.md) — integrate Model Context Protocol servers
+- [Skills](./features/skills.md) — load reusable prompt modules
+- [Image Input](./features/image-input.md) — send images as attachments
+- [Streaming Events](./features/streaming-events.md) — real-time event reference
+- [Steering & Queueing](./features/steering-and-queueing.md) — message delivery modes
+- [Session Persistence](./features/session-persistence.md) — resume sessions across restarts
+
+### [Hooks Reference](./hooks/index.md)
+
+Detailed API reference for each session hook.
+
+- [Pre-Tool Use](./hooks/pre-tool-use.md) — approve, deny, or modify tool calls
+- [Post-Tool Use](./hooks/post-tool-use.md) — transform tool results
+- [User Prompt Submitted](./hooks/user-prompt-submitted.md) — modify or filter user messages
+- [Session Lifecycle](./hooks/session-lifecycle.md) — session start and end
+- [Error Handling](./hooks/error-handling.md) — custom error handling
+
+### [Troubleshooting](./troubleshooting/debugging.md)
+
+- [Debugging Guide](./troubleshooting/debugging.md) — common issues and solutions
+- [MCP Debugging](./troubleshooting/mcp-debugging.md) — MCP-specific troubleshooting
+- [Compatibility](./troubleshooting/compatibility.md) — SDK vs CLI feature matrix
+
+### [Observability](./observability/opentelemetry.md)
+
+- [OpenTelemetry Instrumentation](./observability/opentelemetry.md) — built-in TelemetryConfig and trace context propagation
+
+### [Integrations](./integrations/microsoft-agent-framework.md)
+
+Guides for using the SDK with other platforms and frameworks.
+
+- [Microsoft Agent Framework](./integrations/microsoft-agent-framework.md) — MAF multi-agent workflows
diff --git a/docs/integrations/microsoft-agent-framework.md b/docs/integrations/microsoft-agent-framework.md
new file mode 100644
index 0000000000..8e794759b7
--- /dev/null
+++ b/docs/integrations/microsoft-agent-framework.md
@@ -0,0 +1,456 @@
+# Microsoft Agent Framework Integration
+
+Use the Copilot SDK as an agent provider inside the [Microsoft Agent Framework](https://devblogs.microsoft.com/semantic-kernel/build-ai-agents-with-github-copilot-sdk-and-microsoft-agent-framework/) (MAF) to compose multi-agent workflows alongside Azure OpenAI, Anthropic, and other providers.
+
+## Overview
+
+The Microsoft Agent Framework is the unified successor to Semantic Kernel and AutoGen. It provides a standard interface for building, orchestrating, and deploying AI agents. Dedicated integration packages let you wrap a Copilot SDK client as a first-class MAF agent — interchangeable with any other agent provider in the framework.
+
+| Concept | Description |
+|---------|-------------|
+| **Microsoft Agent Framework** | Open-source framework for single- and multi-agent orchestration in .NET and Python |
+| **Agent provider** | A backend that powers an agent (Copilot, Azure OpenAI, Anthropic, etc.) |
+| **Orchestrator** | A MAF component that coordinates agents in sequential, concurrent, or handoff workflows |
+| **A2A protocol** | Agent-to-Agent communication standard supported by the framework |
+
+> **Note:** MAF integration packages are available for **.NET** and **Python**. For TypeScript and Go, use the Copilot SDK directly — the standard SDK APIs already provide tool calling, streaming, and custom agents.
+
+## Prerequisites
+
+Before you begin, ensure you have:
+
+- A working [Copilot SDK setup](../getting-started.md) in your language of choice
+- A GitHub Copilot subscription (Individual, Business, or Enterprise)
+- The Copilot CLI installed or available via the SDK's bundled CLI
+
+## Installation
+
+Install the Copilot SDK alongside the MAF integration package for your language:
+
+
+.NET
+
+```shell
+dotnet add package GitHub.Copilot.SDK
+dotnet add package Microsoft.Agents.AI.GitHub.Copilot --prerelease
+```
+
+
+
+
+Python
+
+```shell
+pip install copilot-sdk agent-framework-github-copilot
+```
+
+
+
+## Basic Usage
+
+Wrap the Copilot SDK client as a MAF agent with a single method call. The resulting agent conforms to the framework's standard interface and can be used anywhere a MAF agent is expected.
+
+
+.NET
+
+
+```csharp
+using GitHub.Copilot.SDK;
+using Microsoft.Agents.AI;
+
+await using var copilotClient = new CopilotClient();
+await copilotClient.StartAsync();
+
+// Wrap as a MAF agent
+AIAgent agent = copilotClient.AsAIAgent();
+
+// Use the standard MAF interface
+string response = await agent.RunAsync("Explain how dependency injection works in ASP.NET Core");
+Console.WriteLine(response);
+```
+
+
+
+
+Python
+
+
+```python
+from agent_framework.github import GitHubCopilotAgent
+
+async def main():
+ agent = GitHubCopilotAgent(
+ default_options={
+ "instructions": "You are a helpful coding assistant.",
+ }
+ )
+
+ async with agent:
+ result = await agent.run("Explain how dependency injection works in FastAPI")
+ print(result)
+```
+
+
+
+## Adding Custom Tools
+
+Extend your Copilot agent with custom function tools. Tools defined through the standard Copilot SDK are automatically available when the agent runs inside MAF.
+
+
+.NET
+
+
+```csharp
+using GitHub.Copilot.SDK;
+using Microsoft.Extensions.AI;
+using Microsoft.Agents.AI;
+
+// Define a custom tool
+AIFunction weatherTool = AIFunctionFactory.Create(
+ (string location) => $"The weather in {location} is sunny with a high of 25°C.",
+ "GetWeather",
+ "Get the current weather for a given location."
+);
+
+await using var copilotClient = new CopilotClient();
+await copilotClient.StartAsync();
+
+// Create agent with tools
+AIAgent agent = copilotClient.AsAIAgent(new AIAgentOptions
+{
+ Tools = new[] { weatherTool },
+});
+
+string response = await agent.RunAsync("What's the weather like in Seattle?");
+Console.WriteLine(response);
+```
+
+
+
+
+Python
+
+
+```python
+from agent_framework.github import GitHubCopilotAgent
+
+def get_weather(location: str) -> str:
+ """Get the current weather for a given location."""
+ return f"The weather in {location} is sunny with a high of 25°C."
+
+async def main():
+ agent = GitHubCopilotAgent(
+ default_options={
+ "instructions": "You are a helpful assistant with access to weather data.",
+ },
+ tools=[get_weather],
+ )
+
+ async with agent:
+ result = await agent.run("What's the weather like in Seattle?")
+ print(result)
+```
+
+
+
+You can also use Copilot SDK's native tool definition alongside MAF tools:
+
+
+Node.js / TypeScript (standalone SDK)
+
+```typescript
+import { CopilotClient, DefineTool } from "@github/copilot-sdk";
+
+const getWeather = DefineTool({
+ name: "GetWeather",
+ description: "Get the current weather for a given location.",
+ parameters: { location: { type: "string", description: "City name" } },
+ execute: async ({ location }) => `The weather in ${location} is sunny, 25°C.`,
+});
+
+const client = new CopilotClient();
+const session = await client.createSession({
+ model: "gpt-4.1",
+ tools: [getWeather],
+ onPermissionRequest: async () => ({ kind: "approved" }),
+});
+
+await session.sendAndWait({ prompt: "What's the weather like in Seattle?" });
+```
+
+
+
+## Multi-Agent Workflows
+
+The primary benefit of MAF integration is composing Copilot alongside other agent providers in orchestrated workflows. Use the framework's built-in orchestrators to create pipelines where different agents handle different steps.
+
+### Sequential Workflow
+
+Run agents one after another, passing output from one to the next:
+
+
+.NET
+
+
+```csharp
+using GitHub.Copilot.SDK;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Orchestration;
+
+await using var copilotClient = new CopilotClient();
+await copilotClient.StartAsync();
+
+// Copilot agent for code review
+AIAgent reviewer = copilotClient.AsAIAgent(new AIAgentOptions
+{
+ Instructions = "You review code for bugs, security issues, and best practices. Be thorough.",
+});
+
+// Azure OpenAI agent for generating documentation
+AIAgent documentor = AIAgent.FromOpenAI(new OpenAIAgentOptions
+{
+ Model = "gpt-4.1",
+ Instructions = "You write clear, concise documentation for code changes.",
+});
+
+// Compose in a sequential pipeline
+var pipeline = new SequentialOrchestrator(new[] { reviewer, documentor });
+
+string result = await pipeline.RunAsync(
+ "Review and document this pull request: added retry logic to the HTTP client"
+);
+Console.WriteLine(result);
+```
+
+
+
+
+Python
+
+
+```python
+from agent_framework.github import GitHubCopilotAgent
+from agent_framework.openai import OpenAIAgent
+from agent_framework.orchestration import SequentialOrchestrator
+
+async def main():
+ # Copilot agent for code review
+ reviewer = GitHubCopilotAgent(
+ default_options={
+ "instructions": "You review code for bugs, security issues, and best practices.",
+ }
+ )
+
+ # OpenAI agent for documentation
+ documentor = OpenAIAgent(
+ model="gpt-4.1",
+ instructions="You write clear, concise documentation for code changes.",
+ )
+
+ # Compose in a sequential pipeline
+ pipeline = SequentialOrchestrator(agents=[reviewer, documentor])
+
+ async with pipeline:
+ result = await pipeline.run(
+ "Review and document this PR: added retry logic to the HTTP client"
+ )
+ print(result)
+```
+
+
+
+### Concurrent Workflow
+
+Run multiple agents in parallel and aggregate their results:
+
+
+.NET
+
+
+```csharp
+using GitHub.Copilot.SDK;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Orchestration;
+
+await using var copilotClient = new CopilotClient();
+await copilotClient.StartAsync();
+
+AIAgent securityReviewer = copilotClient.AsAIAgent(new AIAgentOptions
+{
+ Instructions = "Focus exclusively on security vulnerabilities and risks.",
+});
+
+AIAgent performanceReviewer = copilotClient.AsAIAgent(new AIAgentOptions
+{
+ Instructions = "Focus exclusively on performance bottlenecks and optimization opportunities.",
+});
+
+// Run both reviews concurrently
+var concurrent = new ConcurrentOrchestrator(new[] { securityReviewer, performanceReviewer });
+
+string combinedResult = await concurrent.RunAsync(
+ "Analyze this database query module for issues"
+);
+Console.WriteLine(combinedResult);
+```
+
+
+
+## Streaming Responses
+
+When building interactive applications, stream agent responses to show real-time output. The MAF integration preserves the Copilot SDK's streaming capabilities.
+
+
+.NET
+
+
+```csharp
+using GitHub.Copilot.SDK;
+using Microsoft.Agents.AI;
+
+await using var copilotClient = new CopilotClient();
+await copilotClient.StartAsync();
+
+AIAgent agent = copilotClient.AsAIAgent(new AIAgentOptions
+{
+ Streaming = true,
+});
+
+await foreach (var chunk in agent.RunStreamingAsync("Write a quicksort implementation in C#"))
+{
+ Console.Write(chunk);
+}
+Console.WriteLine();
+```
+
+
+
+
+Python
+
+
+```python
+from agent_framework.github import GitHubCopilotAgent
+
+async def main():
+ agent = GitHubCopilotAgent(
+ default_options={"streaming": True}
+ )
+
+ async with agent:
+ async for chunk in agent.run_streaming("Write a quicksort in Python"):
+ print(chunk, end="", flush=True)
+ print()
+```
+
+
+
+You can also stream directly through the Copilot SDK without MAF:
+
+
+Node.js / TypeScript (standalone SDK)
+
+```typescript
+import { CopilotClient } from "@github/copilot-sdk";
+
+const client = new CopilotClient();
+const session = await client.createSession({
+ model: "gpt-4.1",
+ streaming: true,
+ onPermissionRequest: async () => ({ kind: "approved" }),
+});
+
+session.on("assistant.message_delta", (event) => {
+ process.stdout.write(event.data.delta ?? "");
+});
+
+await session.sendAndWait({ prompt: "Write a quicksort implementation in TypeScript" });
+```
+
+
+
+## Configuration Reference
+
+### MAF Agent Options
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `Instructions` / `instructions` | `string` | System prompt for the agent |
+| `Tools` / `tools` | `AIFunction[]` / `list` | Custom function tools available to the agent |
+| `Streaming` / `streaming` | `bool` | Enable streaming responses |
+| `Model` / `model` | `string` | Override the default model |
+
+### Copilot SDK Options (Passed Through)
+
+All standard [SessionConfig](../getting-started.md) options are still available when creating the underlying Copilot client. The MAF wrapper delegates to the SDK under the hood:
+
+| SDK Feature | MAF Support |
+|-------------|-------------|
+| Custom tools (`DefineTool` / `AIFunctionFactory`) | ✅ Merged with MAF tools |
+| MCP servers | ✅ Configured on the SDK client |
+| Custom agents / sub-agents | ✅ Available within the Copilot agent |
+| Infinite sessions | ✅ Configured on the SDK client |
+| Model selection | ✅ Overridable per agent or per call |
+| Streaming | ✅ Full delta event support |
+
+## Best Practices
+
+### Choose the right level of integration
+
+Use the MAF wrapper when you need to compose Copilot with other providers in orchestrated workflows. If your application only uses Copilot, the standalone SDK is simpler and gives you full control:
+
+```typescript
+// Standalone SDK — full control, simpler setup
+import { CopilotClient } from "@github/copilot-sdk";
+
+const client = new CopilotClient();
+const session = await client.createSession({
+ model: "gpt-4.1",
+ onPermissionRequest: async () => ({ kind: "approved" }),
+});
+const response = await session.sendAndWait({ prompt: "Explain this code" });
+```
+
+### Keep agents focused
+
+When building multi-agent workflows, give each agent a specific role with clear instructions. Avoid overlapping responsibilities:
+
+```typescript
+// ❌ Too vague — overlapping roles
+const agents = [
+ { instructions: "Help with code" },
+ { instructions: "Assist with programming" },
+];
+
+// ✅ Focused — clear separation of concerns
+const agents = [
+ { instructions: "Review code for security vulnerabilities. Flag SQL injection, XSS, and auth issues." },
+ { instructions: "Optimize code performance. Focus on algorithmic complexity and memory usage." },
+];
+```
+
+### Handle errors at the orchestration level
+
+Wrap agent calls in error handling, especially in multi-agent workflows where one agent's failure shouldn't block the entire pipeline:
+
+
+```csharp
+try
+{
+ string result = await pipeline.RunAsync("Analyze this module");
+ Console.WriteLine(result);
+}
+catch (AgentException ex)
+{
+ Console.Error.WriteLine($"Agent {ex.AgentName} failed: {ex.Message}");
+ // Fall back to single-agent mode or retry
+}
+```
+
+## See Also
+
+- [Getting Started](../getting-started.md) — initial Copilot SDK setup
+- [Custom Agents](../features/custom-agents.md) — define specialized sub-agents within the SDK
+- [Custom Skills](../features/skills.md) — reusable prompt modules
+- [Microsoft Agent Framework documentation](https://learn.microsoft.com/en-us/agent-framework/agents/providers/github-copilot) — official MAF docs for the Copilot provider
+- [Blog: Build AI Agents with GitHub Copilot SDK and Microsoft Agent Framework](https://devblogs.microsoft.com/semantic-kernel/build-ai-agents-with-github-copilot-sdk-and-microsoft-agent-framework/)
diff --git a/docs/observability/opentelemetry.md b/docs/observability/opentelemetry.md
new file mode 100644
index 0000000000..b59e61a4cd
--- /dev/null
+++ b/docs/observability/opentelemetry.md
@@ -0,0 +1,158 @@
+# OpenTelemetry Instrumentation for Copilot SDK
+
+This guide shows how to add OpenTelemetry tracing to your Copilot SDK applications.
+
+## Built-in Telemetry Support
+
+The SDK has built-in support for configuring OpenTelemetry on the CLI process and propagating W3C Trace Context between the SDK and CLI. Provide a `TelemetryConfig` when creating the client to opt in:
+
+
+Node.js / TypeScript
+
+
+```typescript
+import { CopilotClient } from "@github/copilot-sdk";
+
+const client = new CopilotClient({
+ telemetry: {
+ otlpEndpoint: "http://localhost:4318",
+ },
+});
+```
+
+
+
+
+Python
+
+
+```python
+from copilot import CopilotClient, SubprocessConfig
+
+client = CopilotClient(SubprocessConfig(
+ telemetry={
+ "otlp_endpoint": "http://localhost:4318",
+ },
+))
+```
+
+
+
+
+Go
+
+
+```go
+client, err := copilot.NewClient(copilot.ClientOptions{
+ Telemetry: &copilot.TelemetryConfig{
+ OTLPEndpoint: "http://localhost:4318",
+ },
+})
+```
+
+
+
+
+.NET
+
+
+```csharp
+var client = new CopilotClient(new CopilotClientOptions
+{
+ Telemetry = new TelemetryConfig
+ {
+ OtlpEndpoint = "http://localhost:4318",
+ },
+});
+```
+
+
+
+### TelemetryConfig Options
+
+| Option | Node.js | Python | Go | .NET | Description |
+|---|---|---|---|---|---|
+| OTLP endpoint | `otlpEndpoint` | `otlp_endpoint` | `OTLPEndpoint` | `OtlpEndpoint` | OTLP HTTP endpoint URL |
+| File path | `filePath` | `file_path` | `FilePath` | `FilePath` | File path for JSON-lines trace output |
+| Exporter type | `exporterType` | `exporter_type` | `ExporterType` | `ExporterType` | `"otlp-http"` or `"file"` |
+| Source name | `sourceName` | `source_name` | `SourceName` | `SourceName` | Instrumentation scope name |
+| Capture content | `captureContent` | `capture_content` | `CaptureContent` | `CaptureContent` | Whether to capture message content |
+
+### Trace Context Propagation
+
+> **Most users don't need this.** The `TelemetryConfig` above is all you need to collect traces from the CLI. The trace context propagation described in this section is an **advanced feature** for applications that create their own OpenTelemetry spans and want them to appear in the **same distributed trace** as the CLI's spans.
+
+The SDK can propagate W3C Trace Context (`traceparent`/`tracestate`) on JSON-RPC payloads so that your application's spans and the CLI's spans are linked in one distributed trace. This is useful when, for example, you want to see a "handle tool call" span in your app nested inside the CLI's "execute tool" span, or show the SDK call as a child of your request-handling span.
+
+#### SDK → CLI (outbound)
+
+For **Node.js**, provide an `onGetTraceContext` callback on the client options. This is only needed if your application already uses `@opentelemetry/api` and you want to link your spans with the CLI's spans. The SDK calls this callback before `session.create`, `session.resume`, and `session.send` RPCs:
+
+
+```typescript
+import { CopilotClient } from "@github/copilot-sdk";
+import { propagation, context } from "@opentelemetry/api";
+
+const client = new CopilotClient({
+ telemetry: { otlpEndpoint: "http://localhost:4318" },
+ onGetTraceContext: () => {
+ const carrier: Record = {};
+ propagation.inject(context.active(), carrier);
+ return carrier; // { traceparent: "00-...", tracestate: "..." }
+ },
+});
+```
+
+For **Python**, **Go**, and **.NET**, trace context injection is automatic when the respective OpenTelemetry/Activity API is configured — no callback is needed.
+
+#### CLI → SDK (inbound)
+
+When the CLI invokes a tool handler, the `traceparent` and `tracestate` from the CLI's span are available in all languages:
+
+- **Go**: The `ToolInvocation.TraceContext` field is a `context.Context` with the trace already restored — use it directly as the parent for your spans.
+- **Python**: Trace context is automatically restored around the handler via `trace_context()` — child spans are parented to the CLI's span automatically.
+- **.NET**: Trace context is automatically restored via `RestoreTraceContext()` — child `Activity` instances are parented to the CLI's span automatically.
+- **Node.js**: Since the SDK has no OpenTelemetry dependency, `traceparent` and `tracestate` are passed as raw strings on the `ToolInvocation` object. Restore the context manually if needed:
+
+
+```typescript
+import { propagation, context, trace } from "@opentelemetry/api";
+
+session.registerTool(myTool, async (args, invocation) => {
+ // Restore the CLI's trace context as the active context
+ const carrier = {
+ traceparent: invocation.traceparent,
+ tracestate: invocation.tracestate,
+ };
+ const parentCtx = propagation.extract(context.active(), carrier);
+
+ // Create a child span under the CLI's span
+ const tracer = trace.getTracer("my-app");
+ return context.with(parentCtx, () =>
+ tracer.startActiveSpan("my-tool", async (span) => {
+ try {
+ const result = await doWork(args);
+ return result;
+ } finally {
+ span.end();
+ }
+ })
+ );
+});
+```
+
+### Per-Language Dependencies
+
+| Language | Dependency | Notes |
+|---|---|---|
+| Node.js | — | No dependency; provide `onGetTraceContext` callback for outbound propagation |
+| Python | `opentelemetry-api` | Install with `pip install copilot-sdk[telemetry]` |
+| Go | `go.opentelemetry.io/otel` | Required dependency |
+| .NET | — | Uses built-in `System.Diagnostics.Activity` |
+
+## References
+
+- [OpenTelemetry GenAI Semantic Conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/)
+- [OpenTelemetry MCP Semantic Conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/mcp/)
+- [OpenTelemetry Python SDK](https://opentelemetry.io/docs/instrumentation/python/)
+- [Copilot SDK Documentation](https://github.com/github/copilot-sdk)
diff --git a/docs/opentelemetry-instrumentation.md b/docs/opentelemetry-instrumentation.md
deleted file mode 100644
index f0e1b2556c..0000000000
--- a/docs/opentelemetry-instrumentation.md
+++ /dev/null
@@ -1,570 +0,0 @@
-# OpenTelemetry Instrumentation for Copilot SDK
-
-This guide shows how to add OpenTelemetry tracing to your Copilot SDK applications using GenAI semantic conventions.
-
-## Overview
-
-The Copilot SDK emits session events as your agent processes requests. You can instrument your application to convert these events into OpenTelemetry spans and attributes following the [OpenTelemetry GenAI Semantic Conventions v1.34.0](https://opentelemetry.io/docs/specs/semconv/gen-ai/).
-
-## Installation
-
-```bash
-pip install opentelemetry-sdk opentelemetry-api
-```
-
-For exporting to observability backends:
-
-```bash
-# Console output
-pip install opentelemetry-sdk
-
-# Azure Monitor
-pip install azure-monitor-opentelemetry
-
-# OTLP (Jaeger, Prometheus, etc.)
-pip install opentelemetry-exporter-otlp
-```
-
-## Basic Setup
-
-### 1. Initialize OpenTelemetry
-
-```python
-from opentelemetry import trace
-from opentelemetry.sdk.trace import TracerProvider
-from opentelemetry.sdk.trace.export import SimpleSpanProcessor, ConsoleSpanExporter
-
-# Setup tracer provider
-tracer_provider = TracerProvider()
-trace.set_tracer_provider(tracer_provider)
-
-# Add exporter (console example)
-span_exporter = ConsoleSpanExporter()
-tracer_provider.add_span_processor(SimpleSpanProcessor(span_exporter))
-
-# Get a tracer
-tracer = trace.get_tracer(__name__)
-```
-
-### 2. Create Spans Around Agent Operations
-
-```python
-from copilot import CopilotClient, PermissionHandler
-from copilot.generated.session_events import SessionEventType
-from opentelemetry import trace, context
-from opentelemetry.trace import SpanKind
-
-# Initialize client and start the CLI server
-client = CopilotClient()
-await client.start()
-
-tracer = trace.get_tracer(__name__)
-
-# Create a span for the agent invocation
-span_attrs = {
- "gen_ai.operation.name": "invoke_agent",
- "gen_ai.provider.name": "github.copilot",
- "gen_ai.agent.name": "my-agent",
- "gen_ai.request.model": "gpt-5",
-}
-
-span = tracer.start_span(
- name="invoke_agent my-agent",
- kind=SpanKind.CLIENT,
- attributes=span_attrs
-)
-token = context.attach(trace.set_span_in_context(span))
-
-try:
- # Create a session (model is set here, not on the client)
- session = await client.create_session({
- "model": "gpt-5",
- "on_permission_request": PermissionHandler.approve_all,
- })
-
- # Subscribe to events via callback
- def handle_event(event):
- if event.type == SessionEventType.ASSISTANT_USAGE:
- if event.data.model:
- span.set_attribute("gen_ai.response.model", event.data.model)
-
- unsubscribe = session.on(handle_event)
-
- # Send a message (returns a message ID)
- await session.send({"prompt": "Hello, world!"})
-
- # Or send and wait for the session to become idle
- response = await session.send_and_wait({"prompt": "Hello, world!"})
-finally:
- context.detach(token)
- span.end()
- await client.stop()
-```
-
-## Copilot SDK Event to GenAI Attribute Mapping
-
-The Copilot SDK emits `SessionEventType` events during agent execution. Subscribe to these events using `session.on(handler)`, which returns an unsubscribe function. Here's how to map these events to GenAI semantic convention attributes:
-
-### Core Session Events
-
-| SessionEventType | GenAI Attributes | Description |
-|------------------|------------------|-------------|
-| `SESSION_START` | - | Session initialization (mark span start) |
-| `SESSION_IDLE` | - | Session completed (mark span end) |
-| `SESSION_ERROR` | `error.type`, `error.message` | Error occurred |
-
-### Assistant Events
-
-| SessionEventType | GenAI Attributes | Description |
-|------------------|------------------|-------------|
-| `ASSISTANT_TURN_START` | - | Assistant begins processing |
-| `ASSISTANT_TURN_END` | - | Assistant finished processing |
-| `ASSISTANT_MESSAGE` | `gen_ai.output.messages` (event) | Final assistant message with complete content |
-| `ASSISTANT_MESSAGE_DELTA` | - | Streaming message chunk (optional to trace) |
-| `ASSISTANT_USAGE` | `gen_ai.usage.input_tokens`
`gen_ai.usage.output_tokens`
`gen_ai.response.model` | Token usage and model information |
-| `ASSISTANT_REASONING` | - | Reasoning content (optional to trace) |
-| `ASSISTANT_INTENT` | - | Assistant's understood intent |
-
-### Tool Execution Events
-
-| SessionEventType | GenAI Attributes / Span | Description |
-|------------------|-------------------------|-------------|
-| `TOOL_EXECUTION_START` | Create child span:
- `gen_ai.tool.name`
- `gen_ai.tool.call.id`
- `gen_ai.operation.name`: `execute_tool`
- `gen_ai.tool.call.arguments` (opt-in) | Tool execution begins |
-| `TOOL_EXECUTION_COMPLETE` | On child span:
- `gen_ai.tool.call.result` (opt-in)
- `error.type` (if failed)
End child span | Tool execution finished |
-| `TOOL_EXECUTION_PARTIAL_RESULT` | - | Streaming tool result |
-
-### Model and Context Events
-
-| SessionEventType | GenAI Attributes | Description |
-|------------------|------------------|-------------|
-| `SESSION_MODEL_CHANGE` | `gen_ai.request.model` | Model changed during session |
-| `SESSION_CONTEXT_CHANGED` | - | Context window modified |
-| `SESSION_TRUNCATION` | - | Context truncated |
-
-## Detailed Event Mapping Examples
-
-### ASSISTANT_USAGE Event
-
-When you receive an `ASSISTANT_USAGE` event, extract token usage:
-
-```python
-from copilot.generated.session_events import SessionEventType
-
-def handle_usage(event):
- if event.type == SessionEventType.ASSISTANT_USAGE:
- data = event.data
- if data.model:
- span.set_attribute("gen_ai.response.model", data.model)
- if data.input_tokens is not None:
- span.set_attribute("gen_ai.usage.input_tokens", int(data.input_tokens))
- if data.output_tokens is not None:
- span.set_attribute("gen_ai.usage.output_tokens", int(data.output_tokens))
-
-unsubscribe = session.on(handle_usage)
-await session.send({"prompt": "Hello"})
-```
-
-**Event Data Structure:**
-
-```python
-@dataclass
-class Usage:
- input_tokens: float
- output_tokens: float
- cache_read_tokens: float
- cache_write_tokens: float
-```
-
-**Maps to GenAI Attributes:**
-- `input_tokens` → `gen_ai.usage.input_tokens`
-- `output_tokens` → `gen_ai.usage.output_tokens`
-- Response model → `gen_ai.response.model`
-
-### TOOL_EXECUTION_START / COMPLETE Events
-
-Create child spans for each tool execution:
-
-```python
-from opentelemetry.trace import SpanKind
-import json
-
-# Dictionary to track active tool spans
-tool_spans = {}
-
-def handle_tool_events(event):
- data = event.data
-
- if event.type == SessionEventType.TOOL_EXECUTION_START and data:
- call_id = data.tool_call_id or str(uuid.uuid4())
- tool_name = data.tool_name or "unknown"
-
- tool_attrs = {
- "gen_ai.tool.name": tool_name,
- "gen_ai.operation.name": "execute_tool",
- }
-
- if call_id:
- tool_attrs["gen_ai.tool.call.id"] = call_id
-
- # Optional: include tool arguments (may contain sensitive data)
- if data.arguments is not None:
- try:
- tool_attrs["gen_ai.tool.call.arguments"] = json.dumps(data.arguments)
- except Exception:
- tool_attrs["gen_ai.tool.call.arguments"] = str(data.arguments)
-
- tool_span = tracer.start_span(
- name=f"execute_tool {tool_name}",
- kind=SpanKind.CLIENT,
- attributes=tool_attrs
- )
- tool_token = context.attach(trace.set_span_in_context(tool_span))
- tool_spans[call_id] = (tool_span, tool_token)
-
- elif event.type == SessionEventType.TOOL_EXECUTION_COMPLETE and data:
- call_id = data.tool_call_id
- entry = tool_spans.pop(call_id, None) if call_id else None
-
- if entry:
- tool_span, tool_token = entry
-
- # Optional: include tool result (may contain sensitive data)
- if data.result is not None:
- try:
- result_str = json.dumps(data.result)
- except Exception:
- result_str = str(data.result)
- # Truncate to 512 chars to avoid huge spans
- tool_span.set_attribute("gen_ai.tool.call.result", result_str[:512])
-
- # Mark as error if tool failed
- if hasattr(data, "success") and data.success is False:
- tool_span.set_attribute("error.type", "tool_error")
-
- context.detach(tool_token)
- tool_span.end()
-
-unsubscribe = session.on(handle_tool_events)
-await session.send({"prompt": "What's the weather?"})
-```
-
-**Tool Event Data:**
-- `tool_call_id` → `gen_ai.tool.call.id`
-- `tool_name` → `gen_ai.tool.name`
-- `arguments` → `gen_ai.tool.call.arguments` (opt-in)
-- `result` → `gen_ai.tool.call.result` (opt-in)
-
-### ASSISTANT_MESSAGE Event
-
-Capture the final message as a span event:
-
-```python
-def handle_message(event):
- if event.type == SessionEventType.ASSISTANT_MESSAGE and event.data:
- if event.data.content:
- # Add as a span event (opt-in for content recording)
- span.add_event(
- "gen_ai.output.messages",
- attributes={
- "gen_ai.event.content": json.dumps({
- "role": "assistant",
- "content": event.data.content
- })
- }
- )
-
-unsubscribe = session.on(handle_message)
-await session.send({"prompt": "Tell me a joke"})
-```
-
-## Complete Example
-
-```python
-import asyncio
-import json
-import uuid
-from copilot import CopilotClient, PermissionHandler
-from copilot.generated.session_events import SessionEventType
-from opentelemetry import trace, context
-from opentelemetry.trace import SpanKind
-from opentelemetry.sdk.trace import TracerProvider
-from opentelemetry.sdk.trace.export import SimpleSpanProcessor, ConsoleSpanExporter
-
-# Setup OpenTelemetry
-tracer_provider = TracerProvider()
-trace.set_tracer_provider(tracer_provider)
-tracer_provider.add_span_processor(SimpleSpanProcessor(ConsoleSpanExporter()))
-tracer = trace.get_tracer(__name__)
-
-async def invoke_agent(prompt: str):
- """Invoke agent with full OpenTelemetry instrumentation."""
-
- # Create main span
- span_attrs = {
- "gen_ai.operation.name": "invoke_agent",
- "gen_ai.provider.name": "github.copilot",
- "gen_ai.agent.name": "example-agent",
- "gen_ai.request.model": "gpt-5",
- }
-
- span = tracer.start_span(
- name="invoke_agent example-agent",
- kind=SpanKind.CLIENT,
- attributes=span_attrs
- )
- token = context.attach(trace.set_span_in_context(span))
- tool_spans = {}
-
- try:
- client = CopilotClient()
- await client.start()
-
- session = await client.create_session({
- "model": "gpt-5",
- "on_permission_request": PermissionHandler.approve_all,
- })
-
- # Subscribe to events via callback
- def handle_event(event):
- data = event.data
-
- # Handle usage events
- if event.type == SessionEventType.ASSISTANT_USAGE and data:
- if data.model:
- span.set_attribute("gen_ai.response.model", data.model)
- if data.input_tokens is not None:
- span.set_attribute("gen_ai.usage.input_tokens", int(data.input_tokens))
- if data.output_tokens is not None:
- span.set_attribute("gen_ai.usage.output_tokens", int(data.output_tokens))
-
- # Handle tool execution
- elif event.type == SessionEventType.TOOL_EXECUTION_START and data:
- call_id = data.tool_call_id or str(uuid.uuid4())
- tool_name = data.tool_name or "unknown"
-
- tool_attrs = {
- "gen_ai.tool.name": tool_name,
- "gen_ai.operation.name": "execute_tool",
- "gen_ai.tool.call.id": call_id,
- }
-
- tool_span = tracer.start_span(
- name=f"execute_tool {tool_name}",
- kind=SpanKind.CLIENT,
- attributes=tool_attrs
- )
- tool_token = context.attach(trace.set_span_in_context(tool_span))
- tool_spans[call_id] = (tool_span, tool_token)
-
- elif event.type == SessionEventType.TOOL_EXECUTION_COMPLETE and data:
- call_id = data.tool_call_id
- entry = tool_spans.pop(call_id, None) if call_id else None
- if entry:
- tool_span, tool_token = entry
- context.detach(tool_token)
- tool_span.end()
-
- # Capture final message
- elif event.type == SessionEventType.ASSISTANT_MESSAGE and data:
- if data.content:
- print(f"Assistant: {data.content}")
-
- unsubscribe = session.on(handle_event)
-
- # Send message and wait for completion
- response = await session.send_and_wait({"prompt": prompt})
-
- span.set_attribute("gen_ai.response.finish_reasons", ["stop"])
- unsubscribe()
-
- except Exception as e:
- span.set_attribute("error.type", type(e).__name__)
- raise
- finally:
- # Clean up any unclosed tool spans
- for call_id, (tool_span, tool_token) in tool_spans.items():
- tool_span.set_attribute("error.type", "stream_aborted")
- context.detach(tool_token)
- tool_span.end()
-
- context.detach(token)
- span.end()
- await client.stop()
-
-# Run
-asyncio.run(invoke_agent("What's 2+2?"))
-```
-
-## Required Span Attributes
-
-According to OpenTelemetry GenAI semantic conventions, these attributes are **required** for agent invocation spans:
-
-| Attribute | Description | Example |
-|-----------|-------------|---------|
-| `gen_ai.operation.name` | Operation type | `invoke_agent`, `chat`, `execute_tool` |
-| `gen_ai.provider.name` | Provider identifier | `github.copilot` |
-| `gen_ai.request.model` | Model used for request | `gpt-5`, `gpt-4.1` |
-
-## Recommended Span Attributes
-
-These attributes are **recommended** for better observability:
-
-| Attribute | Description |
-|-----------|-------------|
-| `gen_ai.agent.id` | Unique agent identifier |
-| `gen_ai.agent.name` | Human-readable agent name |
-| `gen_ai.response.model` | Actual model used in response |
-| `gen_ai.usage.input_tokens` | Input tokens consumed |
-| `gen_ai.usage.output_tokens` | Output tokens generated |
-| `gen_ai.response.finish_reasons` | Completion reasons (e.g., `["stop"]`) |
-
-## Content Recording
-
-Recording message content and tool arguments/results is **optional** and should be opt-in since it may contain sensitive data.
-
-### Environment Variable Control
-
-```bash
-# Enable content recording
-export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true
-```
-
-### Checking at Runtime
-
-
-```python
-import os
-
-def should_record_content():
- return os.getenv("OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT", "false").lower() == "true"
-
-# Only add content if enabled
-if should_record_content() and event.data.content:
- span.add_event("gen_ai.output.messages", ...)
-```
-
-## MCP (Model Context Protocol) Tool Conventions
-
-For MCP-based tools, add these additional attributes following the [OpenTelemetry MCP semantic conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/mcp/):
-
-
-```python
-tool_attrs = {
- # Required
- "mcp.method.name": "tools/call",
-
- # Recommended
- "mcp.server.name": data.mcp_server_name,
- "mcp.session.id": session.session_id,
-
- # GenAI attributes
- "gen_ai.tool.name": data.mcp_tool_name,
- "gen_ai.operation.name": "execute_tool",
- "network.transport": "pipe", # Copilot SDK uses stdio
-}
-```
-
-## Span Naming Conventions
-
-Follow these patterns for span names:
-
-| Operation | Span Name Pattern | Example |
-|-----------|-------------------|---------|
-| Agent invocation | `invoke_agent {agent_name}` | `invoke_agent weather-bot` |
-| Chat | `chat` | `chat` |
-| Tool execution | `execute_tool {tool_name}` | `execute_tool fetch_weather` |
-| MCP tool | `tools/call {tool_name}` | `tools/call read_file` |
-
-## Metrics
-
-You can also export metrics for token usage and operation duration:
-
-```python
-from opentelemetry import metrics
-from opentelemetry.sdk.metrics import MeterProvider
-from opentelemetry.sdk.metrics.export import ConsoleMetricExporter, PeriodicExportingMetricReader
-
-# Setup metrics
-reader = PeriodicExportingMetricReader(ConsoleMetricExporter())
-provider = MeterProvider(metric_readers=[reader])
-metrics.set_meter_provider(provider)
-
-meter = metrics.get_meter(__name__)
-
-# Create metrics
-operation_duration = meter.create_histogram(
- name="gen_ai.client.operation.duration",
- description="Duration of GenAI operations",
- unit="ms"
-)
-
-token_usage = meter.create_counter(
- name="gen_ai.client.token.usage",
- description="Token usage count"
-)
-
-# Record metrics
-operation_duration.record(123.45, attributes={
- "gen_ai.operation.name": "invoke_agent",
- "gen_ai.request.model": "gpt-5",
-})
-
-token_usage.add(150, attributes={
- "gen_ai.token.type": "input",
- "gen_ai.operation.name": "invoke_agent",
-})
-```
-
-## Azure Monitor Integration
-
-For production observability with Azure Monitor:
-
-```python
-from azure.monitor.opentelemetry import configure_azure_monitor
-
-# Enable Azure Monitor
-connection_string = "InstrumentationKey=..."
-configure_azure_monitor(connection_string=connection_string)
-
-# Your instrumented code here
-```
-
-View traces in the Azure Portal under your Application Insights resource → Tracing.
-
-## Best Practices
-
-1. **Always close spans**: Use try/finally blocks to ensure spans are ended even on errors
-2. **Set error attributes**: On exceptions, set `error.type` and optionally `error.message`
-3. **Use child spans for tools**: Create separate spans for each tool execution
-4. **Opt-in for content**: Only record message content and tool arguments when explicitly enabled
-5. **Truncate large values**: Limit tool results and arguments to reasonable sizes (e.g., 512 chars)
-6. **Set finish reasons**: Always set `gen_ai.response.finish_reasons` when the operation completes successfully
-7. **Include model info**: Capture both request and response model names
-
-## Troubleshooting
-
-### No spans appearing
-
-1. Verify tracer provider is set: `trace.set_tracer_provider(provider)`
-2. Add a span processor: `provider.add_span_processor(SimpleSpanProcessor(exporter))`
-3. Ensure spans are ended: Check for missing `span.end()` calls
-
-### Tool spans not showing as children
-
-Make sure to attach the tool span to the parent context:
-
-```python
-tool_token = context.attach(trace.set_span_in_context(tool_span))
-```
-
-### Context warnings in async code
-
-You may see "Failed to detach context" warnings in async streaming code. These are expected and don't affect tracing correctness.
-
-## References
-
-- [OpenTelemetry GenAI Semantic Conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/)
-- [OpenTelemetry MCP Semantic Conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/mcp/)
-- [OpenTelemetry Python SDK](https://opentelemetry.io/docs/instrumentation/python/)
-- [GenAI Semantic Conventions v1.34.0](https://opentelemetry.io/schemas/1.34.0)
-- [Copilot SDK Documentation](https://github.com/github/copilot-sdk)
diff --git a/docs/guides/setup/azure-managed-identity.md b/docs/setup/azure-managed-identity.md
similarity index 82%
rename from docs/guides/setup/azure-managed-identity.md
rename to docs/setup/azure-managed-identity.md
index 9ad1ddb157..40d87c5ba1 100644
--- a/docs/guides/setup/azure-managed-identity.md
+++ b/docs/setup/azure-managed-identity.md
@@ -1,6 +1,6 @@
# Azure Managed Identity with BYOK
-The Copilot SDK's [BYOK mode](./byok.md) accepts static API keys, but Azure deployments often use **Managed Identity** (Entra ID) instead of long-lived keys. Since the SDK doesn't natively support Entra ID authentication, you can use a short-lived bearer token via the `bearer_token` provider config field.
+The Copilot SDK's [BYOK mode](../auth/byok.md) accepts static API keys, but Azure deployments often use **Managed Identity** (Entra ID) instead of long-lived keys. Since the SDK doesn't natively support Entra ID authentication, you can use a short-lived bearer token via the `bearer_token` provider config field.
This guide shows how to use `DefaultAzureCredential` from the [Azure Identity](https://learn.microsoft.com/python/api/azure-identity/azure.identity.defaultazurecredential) library to authenticate with Azure AI Foundry models through the Copilot SDK.
@@ -42,7 +42,7 @@ import asyncio
import os
from azure.identity import DefaultAzureCredential
-from copilot import CopilotClient, ProviderConfig, SessionConfig
+from copilot import CopilotClient, PermissionHandler
COGNITIVE_SERVICES_SCOPE = "https://cognitiveservices.azure.com/.default"
@@ -58,15 +58,14 @@ async def main():
await client.start()
session = await client.create_session(
- SessionConfig(
- model="gpt-4.1",
- provider=ProviderConfig(
- type="openai",
- base_url=f"{foundry_url.rstrip('/')}/openai/v1/",
- bearer_token=token, # Short-lived bearer token
- wire_api="responses",
- ),
- )
+ on_permission_request=PermissionHandler.approve_all,
+ model="gpt-4.1",
+ provider={
+ "type": "openai",
+ "base_url": f"{foundry_url.rstrip('/')}/openai/v1/",
+ "bearer_token": token, # Short-lived bearer token
+ "wire_api": "responses",
+ },
)
response = await session.send_and_wait({"prompt": "Hello from Managed Identity!"})
@@ -84,7 +83,7 @@ Bearer tokens expire (typically after ~1 hour). For servers or long-running agen
```python
from azure.identity import DefaultAzureCredential
-from copilot import CopilotClient, ProviderConfig, SessionConfig
+from copilot import CopilotClient, PermissionHandler
COGNITIVE_SERVICES_SCOPE = "https://cognitiveservices.azure.com/.default"
@@ -98,24 +97,21 @@ class ManagedIdentityCopilotAgent:
self.credential = DefaultAzureCredential()
self.client = CopilotClient()
- def _get_session_config(self) -> SessionConfig:
- """Build a SessionConfig with a fresh bearer token."""
+ def _get_provider_config(self) -> dict:
+ """Build a provider config dict with a fresh bearer token."""
token = self.credential.get_token(COGNITIVE_SERVICES_SCOPE).token
- return SessionConfig(
- model=self.model,
- provider=ProviderConfig(
- type="openai",
- base_url=f"{self.foundry_url}/openai/v1/",
- bearer_token=token,
- wire_api="responses",
- ),
- )
+ return {
+ "type": "openai",
+ "base_url": f"{self.foundry_url}/openai/v1/",
+ "bearer_token": token,
+ "wire_api": "responses",
+ }
async def chat(self, prompt: str) -> str:
"""Send a prompt and return the response text."""
# Fresh token for each session
- config = self._get_session_config()
- session = await self.client.create_session(config)
+ provider = self._get_provider_config()
+ session = await self.client.create_session(on_permission_request=PermissionHandler.approve_all, model=self.model, provider=provider)
response = await session.send_and_wait({"prompt": prompt})
await session.disconnect()
@@ -207,11 +203,11 @@ See the [DefaultAzureCredential documentation](https://learn.microsoft.com/pytho
| Azure-hosted app with Managed Identity | ✅ Use this pattern |
| App with existing Azure AD service principal | ✅ Use this pattern |
| Local development with `az login` | ✅ Use this pattern |
-| Non-Azure environment with static API key | Use [standard BYOK](./byok.md) |
+| Non-Azure environment with static API key | Use [standard BYOK](../auth/byok.md) |
| GitHub Copilot subscription available | Use [GitHub OAuth](./github-oauth.md) |
## See Also
-- [BYOK Setup Guide](./byok.md) — Static API key configuration
+- [BYOK Setup Guide](../auth/byok.md) — Static API key configuration
- [Backend Services](./backend-services.md) — Server-side deployment
- [Azure Identity documentation](https://learn.microsoft.com/python/api/overview/azure/identity-readme)
diff --git a/docs/guides/setup/backend-services.md b/docs/setup/backend-services.md
similarity index 86%
rename from docs/guides/setup/backend-services.md
rename to docs/setup/backend-services.md
index e0d0975dbf..735adf4ff3 100644
--- a/docs/guides/setup/backend-services.md
+++ b/docs/setup/backend-services.md
@@ -111,17 +111,14 @@ res.json({ content: response?.data.content });
Python
```python
-from copilot import CopilotClient
+from copilot import CopilotClient, PermissionHandler
client = CopilotClient({
"cli_url": "localhost:4321",
})
await client.start()
-session = await client.create_session({
- "session_id": f"user-{user_id}-{int(time.time())}",
- "model": "gpt-4.1",
-})
+session = await client.create_session(on_permission_request=PermissionHandler.approve_all, model="gpt-4.1", session_id=f"user-{user_id}-{int(time.time())}")
response = await session.send_and_wait({"prompt": message})
```
@@ -131,7 +128,39 @@ response = await session.send_and_wait({"prompt": message})
Go
-
+
+```go
+package main
+
+import (
+ "context"
+ "fmt"
+ "time"
+ copilot "github.com/github/copilot-sdk/go"
+)
+
+func main() {
+ ctx := context.Background()
+ userID := "user1"
+ message := "Hello"
+
+ client := copilot.NewClient(&copilot.ClientOptions{
+ CLIUrl: "localhost:4321",
+ })
+ client.Start(ctx)
+ defer client.Stop()
+
+ session, _ := client.CreateSession(ctx, &copilot.SessionConfig{
+ SessionID: fmt.Sprintf("user-%s-%d", userID, time.Now().Unix()),
+ Model: "gpt-4.1",
+ })
+
+ response, _ := session.SendAndWait(ctx, copilot.MessageOptions{Prompt: message})
+ _ = response
+}
+```
+
+
```go
client := copilot.NewClient(&copilot.ClientOptions{
CLIUrl:"localhost:4321",
@@ -152,7 +181,30 @@ response, _ := session.SendAndWait(ctx, copilot.MessageOptions{Prompt: message})
.NET
-
+
+```csharp
+using GitHub.Copilot.SDK;
+
+var userId = "user1";
+var message = "Hello";
+
+var client = new CopilotClient(new CopilotClientOptions
+{
+ CliUrl = "localhost:4321",
+ UseStdio = false,
+});
+
+await using var session = await client.CreateSessionAsync(new SessionConfig
+{
+ SessionId = $"user-{userId}-{DateTimeOffset.UtcNow.ToUnixTimeSeconds()}",
+ Model = "gpt-4.1",
+});
+
+var response = await session.SendAndWaitAsync(
+ new MessageOptions { Prompt = message });
+```
+
+
```csharp
var client = new CopilotClient(new CopilotClientOptions
{
@@ -225,7 +277,7 @@ app.post("/chat", authMiddleware, async (req, res) => {
### BYOK (No GitHub Auth)
-Use your own API keys for the model provider. See [BYOK](./byok.md) for details.
+Use your own API keys for the model provider. See [BYOK](../auth/byok.md) for details.
```typescript
const client = new CopilotClient({
@@ -423,10 +475,10 @@ setInterval(() => cleanupSessions(24 * 60 * 60 * 1000), 60 * 60 * 1000);
|------|-----------|
| Multiple CLI servers / high availability | [Scaling & Multi-Tenancy](./scaling.md) |
| GitHub account auth for users | [GitHub OAuth](./github-oauth.md) |
-| Your own model keys | [BYOK](./byok.md) |
+| Your own model keys | [BYOK](../auth/byok.md) |
## Next Steps
- **[Scaling & Multi-Tenancy](./scaling.md)** — Handle more users, add redundancy
-- **[Session Persistence](../session-persistence.md)** — Resume sessions across restarts
+- **[Session Persistence](../features/session-persistence.md)** — Resume sessions across restarts
- **[GitHub OAuth](./github-oauth.md)** — Add user authentication
diff --git a/docs/guides/setup/bundled-cli.md b/docs/setup/bundled-cli.md
similarity index 88%
rename from docs/guides/setup/bundled-cli.md
rename to docs/setup/bundled-cli.md
index 6daf57b56e..cdfe6df812 100644
--- a/docs/guides/setup/bundled-cli.md
+++ b/docs/setup/bundled-cli.md
@@ -85,7 +85,7 @@ await client.stop();
Python
```python
-from copilot import CopilotClient
+from copilot import CopilotClient, PermissionHandler
from pathlib import Path
client = CopilotClient({
@@ -93,7 +93,7 @@ client = CopilotClient({
})
await client.start()
-session = await client.create_session({"model": "gpt-4.1"})
+session = await client.create_session(on_permission_request=PermissionHandler.approve_all, model="gpt-4.1")
response = await session.send_and_wait({"prompt": "Hello!"})
print(response.data.content)
@@ -105,7 +105,35 @@ await client.stop()
Go
-
+
+```go
+package main
+
+import (
+ "context"
+ "fmt"
+ "log"
+ copilot "github.com/github/copilot-sdk/go"
+)
+
+func main() {
+ ctx := context.Background()
+
+ client := copilot.NewClient(&copilot.ClientOptions{
+ CLIPath: "./vendor/copilot",
+ })
+ if err := client.Start(ctx); err != nil {
+ log.Fatal(err)
+ }
+ defer client.Stop()
+
+ session, _ := client.CreateSession(ctx, &copilot.SessionConfig{Model: "gpt-4.1"})
+ response, _ := session.SendAndWait(ctx, copilot.MessageOptions{Prompt: "Hello!"})
+ fmt.Println(*response.Data.Content)
+}
+```
+
+
```go
client := copilot.NewClient(&copilot.ClientOptions{
CLIPath:"./vendor/copilot",
@@ -203,7 +231,7 @@ const session = await client.createSession({
});
```
-See the **[BYOK guide](./byok.md)** for full details.
+See the **[BYOK guide](../auth/byok.md)** for full details.
## Session Management
@@ -318,10 +346,10 @@ const client = new CopilotClient({
|------|-----------|
| Users signing in with GitHub accounts | [GitHub OAuth](./github-oauth.md) |
| Run on a server instead of user machines | [Backend Services](./backend-services.md) |
-| Use your own model keys | [BYOK](./byok.md) |
+| Use your own model keys | [BYOK](../auth/byok.md) |
## Next Steps
-- **[BYOK guide](./byok.md)** — Use your own model provider keys
-- **[Session Persistence](../session-persistence.md)** — Advanced session management
-- **[Getting Started tutorial](../../getting-started.md)** — Build a complete app
+- **[BYOK guide](../auth/byok.md)** — Use your own model provider keys
+- **[Session Persistence](../features/session-persistence.md)** — Advanced session management
+- **[Getting Started tutorial](../getting-started.md)** — Build a complete app
diff --git a/docs/guides/setup/github-oauth.md b/docs/setup/github-oauth.md
similarity index 86%
rename from docs/guides/setup/github-oauth.md
rename to docs/setup/github-oauth.md
index 07251c8fbe..81d2b25a27 100644
--- a/docs/guides/setup/github-oauth.md
+++ b/docs/setup/github-oauth.md
@@ -145,7 +145,7 @@ const response = await session.sendAndWait({ prompt: "Hello!" });
Python
```python
-from copilot import CopilotClient
+from copilot import CopilotClient, PermissionHandler
def create_client_for_user(user_token: str) -> CopilotClient:
return CopilotClient({
@@ -157,10 +157,7 @@ def create_client_for_user(user_token: str) -> CopilotClient:
client = create_client_for_user("gho_user_access_token")
await client.start()
-session = await client.create_session({
- "session_id": f"user-{user_id}-session",
- "model": "gpt-4.1",
-})
+session = await client.create_session(on_permission_request=PermissionHandler.approve_all, model="gpt-4.1", session_id=f"user-{user_id}-session")
response = await session.send_and_wait({"prompt": "Hello!"})
```
@@ -170,7 +167,41 @@ response = await session.send_and_wait({"prompt": "Hello!"})
Go
-
+
+```go
+package main
+
+import (
+ "context"
+ "fmt"
+ copilot "github.com/github/copilot-sdk/go"
+)
+
+func createClientForUser(userToken string) *copilot.Client {
+ return copilot.NewClient(&copilot.ClientOptions{
+ GitHubToken: userToken,
+ UseLoggedInUser: copilot.Bool(false),
+ })
+}
+
+func main() {
+ ctx := context.Background()
+ userID := "user1"
+
+ client := createClientForUser("gho_user_access_token")
+ client.Start(ctx)
+ defer client.Stop()
+
+ session, _ := client.CreateSession(ctx, &copilot.SessionConfig{
+ SessionID: fmt.Sprintf("user-%s-session", userID),
+ Model: "gpt-4.1",
+ })
+ response, _ := session.SendAndWait(ctx, copilot.MessageOptions{Prompt: "Hello!"})
+ _ = response
+}
+```
+
+
```go
func createClientForUser(userToken string) *copilot.Client {
return copilot.NewClient(&copilot.ClientOptions{
@@ -196,7 +227,31 @@ response, _ := session.SendAndWait(ctx, copilot.MessageOptions{Prompt: "Hello!"}
.NET
-
+
+```csharp
+using GitHub.Copilot.SDK;
+
+CopilotClient CreateClientForUser(string userToken) =>
+ new CopilotClient(new CopilotClientOptions
+ {
+ GithubToken = userToken,
+ UseLoggedInUser = false,
+ });
+
+var userId = "user1";
+
+await using var client = CreateClientForUser("gho_user_access_token");
+await using var session = await client.CreateSessionAsync(new SessionConfig
+{
+ SessionId = $"user-{userId}-session",
+ Model = "gpt-4.1",
+});
+
+var response = await session.SendAndWaitAsync(
+ new MessageOptions { Prompt = "Hello!" });
+```
+
+
```csharp
CopilotClient CreateClientForUser(string userToken) =>
new CopilotClient(new CopilotClientOptions
@@ -374,12 +429,12 @@ For a lighter resource footprint, you can run a single external CLI server and p
| Need | Next Guide |
|------|-----------|
-| Users without GitHub accounts | [BYOK](./byok.md) |
+| Users without GitHub accounts | [BYOK](../auth/byok.md) |
| Run the SDK on servers | [Backend Services](./backend-services.md) |
| Handle many concurrent users | [Scaling & Multi-Tenancy](./scaling.md) |
## Next Steps
-- **[Authentication docs](../../auth/index.md)** — Full auth method reference
+- **[Authentication docs](../auth/index.md)** — Full auth method reference
- **[Backend Services](./backend-services.md)** — Run the SDK server-side
- **[Scaling & Multi-Tenancy](./scaling.md)** — Handle many users at scale
diff --git a/docs/guides/setup/index.md b/docs/setup/index.md
similarity index 94%
rename from docs/guides/setup/index.md
rename to docs/setup/index.md
index 2613fe29df..268e266882 100644
--- a/docs/guides/setup/index.md
+++ b/docs/setup/index.md
@@ -58,7 +58,7 @@ You're building a product for customers. You need to handle authentication for y
**Start with:**
1. **[GitHub OAuth](./github-oauth.md)** — Let customers sign in with GitHub
-2. **[BYOK](./byok.md)** — Manage identity yourself with your own model keys
+2. **[BYOK](../auth/byok.md)** — Manage identity yourself with your own model keys
3. **[Backend Services](./backend-services.md)** — Power your product from server-side code
**For production:**
@@ -74,7 +74,7 @@ You're embedding Copilot into a platform — APIs, developer tools, or infrastru
**Depending on your auth model:**
3. **[GitHub OAuth](./github-oauth.md)** — For GitHub-authenticated users
-4. **[BYOK](./byok.md)** — For self-managed identity and model access
+4. **[BYOK](../auth/byok.md)** — For self-managed identity and model access
## Decision Matrix
@@ -85,7 +85,7 @@ Use this table to find the right guides based on what you need to do:
| Simplest possible setup | [Local CLI](./local-cli.md) |
| Ship a standalone app with Copilot | [Bundled CLI](./bundled-cli.md) |
| Users sign in with GitHub | [GitHub OAuth](./github-oauth.md) |
-| Use your own model keys (OpenAI, Azure, etc.) | [BYOK](./byok.md) |
+| Use your own model keys (OpenAI, Azure, etc.) | [BYOK](../auth/byok.md) |
| Azure BYOK with Managed Identity (no API keys) | [Azure Managed Identity](./azure-managed-identity.md) |
| Run the SDK on a server | [Backend Services](./backend-services.md) |
| Serve multiple users / scale horizontally | [Scaling & Multi-Tenancy](./scaling.md) |
@@ -136,7 +136,7 @@ All guides assume you have:
- Go: `go get github.com/github/copilot-sdk/go`
- .NET: `dotnet add package GitHub.Copilot.SDK`
-If you're brand new, start with the **[Getting Started tutorial](../../getting-started.md)** first, then come back here for production configuration.
+If you're brand new, start with the **[Getting Started tutorial](../getting-started.md)** first, then come back here for production configuration.
## Next Steps
diff --git a/docs/guides/setup/local-cli.md b/docs/setup/local-cli.md
similarity index 82%
rename from docs/guides/setup/local-cli.md
rename to docs/setup/local-cli.md
index a5fa906b89..bb95a4d38c 100644
--- a/docs/guides/setup/local-cli.md
+++ b/docs/setup/local-cli.md
@@ -51,12 +51,12 @@ await client.stop();
Python
```python
-from copilot import CopilotClient
+from copilot import CopilotClient, PermissionHandler
client = CopilotClient()
await client.start()
-session = await client.create_session({"model": "gpt-4.1"})
+session = await client.create_session(on_permission_request=PermissionHandler.approve_all, model="gpt-4.1")
response = await session.send_and_wait({"prompt": "Hello!"})
print(response.data.content)
@@ -68,7 +68,33 @@ await client.stop()
Go
-
+
+```go
+package main
+
+import (
+ "context"
+ "fmt"
+ "log"
+ copilot "github.com/github/copilot-sdk/go"
+)
+
+func main() {
+ ctx := context.Background()
+
+ client := copilot.NewClient(nil)
+ if err := client.Start(ctx); err != nil {
+ log.Fatal(err)
+ }
+ defer client.Stop()
+
+ session, _ := client.CreateSession(ctx, &copilot.SessionConfig{Model: "gpt-4.1"})
+ response, _ := session.SendAndWait(ctx, copilot.MessageOptions{Prompt: "Hello!"})
+ fmt.Println(*response.Data.Content)
+}
+```
+
+
```go
client := copilot.NewClient(nil)
if err := client.Start(ctx); err != nil {
@@ -140,14 +166,11 @@ const client = new CopilotClient({
// Set log level for debugging
logLevel: "debug",
- // Pass extra CLI arguments
- cliArgs: ["--disable-telemetry"],
+ // Pass extra CLI arguments (example: set a custom log directory)
+ cliArgs: ["--log-dir=/tmp/copilot-logs"],
// Set working directory
cwd: "/path/to/project",
-
- // Auto-restart CLI if it crashes (default: true)
- autoRestart: true,
});
```
@@ -199,10 +222,10 @@ If you need any of these, it's time to pick a more advanced setup:
| Ship your app to others | [Bundled CLI](./bundled-cli.md) |
| Multiple users signing in | [GitHub OAuth](./github-oauth.md) |
| Run on a server | [Backend Services](./backend-services.md) |
-| Use your own model keys | [BYOK](./byok.md) |
+| Use your own model keys | [BYOK](../auth/byok.md) |
## Next Steps
-- **[Getting Started tutorial](../../getting-started.md)** — Build a complete interactive app
-- **[Authentication docs](../../auth/index.md)** — All auth methods in detail
-- **[Session Persistence](../session-persistence.md)** — Advanced session management
+- **[Getting Started tutorial](../getting-started.md)** — Build a complete interactive app
+- **[Authentication docs](../auth/index.md)** — All auth methods in detail
+- **[Session Persistence](../features/session-persistence.md)** — Advanced session management
diff --git a/docs/guides/setup/scaling.md b/docs/setup/scaling.md
similarity index 99%
rename from docs/guides/setup/scaling.md
rename to docs/setup/scaling.md
index 974276e5e1..325d9244dd 100644
--- a/docs/guides/setup/scaling.md
+++ b/docs/setup/scaling.md
@@ -629,7 +629,7 @@ flowchart TB
## Next Steps
-- **[Session Persistence](../session-persistence.md)** — Deep dive on resumable sessions
+- **[Session Persistence](../features/session-persistence.md)** — Deep dive on resumable sessions
- **[Backend Services](./backend-services.md)** — Core server-side setup
- **[GitHub OAuth](./github-oauth.md)** — Multi-user authentication
-- **[BYOK](./byok.md)** — Use your own model provider
+- **[BYOK](../auth/byok.md)** — Use your own model provider
diff --git a/docs/compatibility.md b/docs/troubleshooting/compatibility.md
similarity index 51%
rename from docs/compatibility.md
rename to docs/troubleshooting/compatibility.md
index bfd17915b5..1a322b88c2 100644
--- a/docs/compatibility.md
+++ b/docs/troubleshooting/compatibility.md
@@ -20,9 +20,15 @@ The Copilot SDK communicates with the CLI via JSON-RPC protocol. Features must b
| Delete session | `deleteSession()` | Remove from storage |
| List sessions | `listSessions()` | All stored sessions |
| Get last session | `getLastSessionId()` | For quick resume |
+| Get foreground session | `getForegroundSessionId()` | Multi-session coordination |
+| Set foreground session | `setForegroundSessionId()` | Multi-session coordination |
| **Messaging** | | |
| Send message | `send()` | With attachments |
| Send and wait | `sendAndWait()` | Blocks until complete |
+| Steering (immediate mode) | `send({ mode: "immediate" })` | Inject mid-turn without aborting |
+| Queueing (enqueue mode) | `send({ mode: "enqueue" })` | Buffer for sequential processing (default) |
+| File attachments | `send({ attachments: [{ type: "file", path }] })` | Images auto-encoded and resized |
+| Directory attachments | `send({ attachments: [{ type: "directory", path }] })` | Attach directory context |
| Get history | `getMessages()` | All session events |
| Abort | `abort()` | Cancel in-flight request |
| **Tools** | | |
@@ -31,12 +37,28 @@ The Copilot SDK communicates with the CLI via JSON-RPC protocol. Features must b
| Tool result modification | `onPostToolUse` hook | Transform results |
| Available/excluded tools | `availableTools`, `excludedTools` config | Filter tools |
| **Models** | | |
-| List models | `listModels()` | With capabilities |
-| Set model | `model` in session config | Per-session |
+| List models | `listModels()` | With capabilities, billing, policy |
+| Set model (at creation) | `model` in session config | Per-session |
+| Switch model (mid-session) | `session.setModel()` | Also via `session.rpc.model.switchTo()` |
+| Get current model | `session.rpc.model.getCurrent()` | Query active model |
| Reasoning effort | `reasoningEffort` config | For supported models |
+| **Agent Mode** | | |
+| Get current mode | `session.rpc.mode.get()` | Returns current mode |
+| Set mode | `session.rpc.mode.set()` | Switch between modes |
+| **Plan Management** | | |
+| Read plan | `session.rpc.plan.read()` | Get plan.md content and path |
+| Update plan | `session.rpc.plan.update()` | Write plan.md content |
+| Delete plan | `session.rpc.plan.delete()` | Remove plan.md |
+| **Workspace Files** | | |
+| List workspace files | `session.rpc.workspace.listFiles()` | Files in session workspace |
+| Read workspace file | `session.rpc.workspace.readFile()` | Read file content |
+| Create workspace file | `session.rpc.workspace.createFile()` | Create file in workspace |
| **Authentication** | | |
| Get auth status | `getAuthStatus()` | Check login state |
| Use token | `githubToken` option | Programmatic auth |
+| **Connectivity** | | |
+| Ping | `client.ping()` | Health check with server timestamp |
+| Get server status | `client.getStatus()` | Protocol version and server info |
| **MCP Servers** | | |
| Local/stdio servers | `mcpServers` config | Spawn processes |
| Remote HTTP/SSE | `mcpServers` config | Connect to services |
@@ -44,19 +66,27 @@ The Copilot SDK communicates with the CLI via JSON-RPC protocol. Features must b
| Pre-tool use | `onPreToolUse` | Permission, modify args |
| Post-tool use | `onPostToolUse` | Modify results |
| User prompt | `onUserPromptSubmitted` | Modify prompts |
-| Session start/end | `onSessionStart`, `onSessionEnd` | Lifecycle |
+| Session start/end | `onSessionStart`, `onSessionEnd` | Lifecycle with source/reason |
| Error handling | `onErrorOccurred` | Custom handling |
| **Events** | | |
| All session events | `on()`, `once()` | 40+ event types |
| Streaming | `streaming: true` | Delta events |
-| **Advanced** | | |
-| Custom agents | `customAgents` config | Load agent definitions |
+| **Session Config** | | |
+| Custom agents | `customAgents` config | Define specialized agents |
| System message | `systemMessage` config | Append or replace |
| Custom provider | `provider` config | BYOK support |
| Infinite sessions | `infiniteSessions` config | Auto-compaction |
| Permission handler | `onPermissionRequest` | Approve/deny requests |
| User input handler | `onUserInputRequest` | Handle ask_user |
| Skills | `skillDirectories` config | Custom skills |
+| Disabled skills | `disabledSkills` config | Disable specific skills |
+| Config directory | `configDir` config | Override default config location |
+| Client name | `clientName` config | Identify app in User-Agent |
+| Working directory | `workingDirectory` config | Set session cwd |
+| **Experimental** | | |
+| Agent management | `session.rpc.agent.*` | List, select, deselect, get current agent |
+| Fleet mode | `session.rpc.fleet.start()` | Parallel sub-agent execution |
+| Manual compaction | `session.rpc.compaction.compact()` | Trigger compaction on demand |
### ❌ Not Available in SDK (CLI-Only)
@@ -66,20 +96,32 @@ The Copilot SDK communicates with the CLI via JSON-RPC protocol. Features must b
| Export to file | `--share`, `/share` | Not in protocol |
| Export to gist | `--share-gist`, `/share gist` | Not in protocol |
| **Interactive UI** | | |
-| Slash commands | `/help`, `/clear`, etc. | TUI-only |
+| Slash commands | `/help`, `/clear`, `/exit`, etc. | TUI-only |
| Agent picker dialog | `/agent` | Interactive UI |
| Diff mode dialog | `/diff` | Interactive UI |
| Feedback dialog | `/feedback` | Interactive UI |
| Theme picker | `/theme` | Terminal UI |
+| Model picker | `/model` | Interactive UI (use SDK `setModel()` instead) |
+| Copy to clipboard | `/copy` | Terminal-specific |
+| Context management | `/context` | Interactive UI |
+| **Research & History** | | |
+| Deep research | `/research` | TUI workflow with web search |
+| Session history tools | `/chronicle` | Standup, tips, improve, reindex |
| **Terminal Features** | | |
| Color output | `--no-color` | Terminal-specific |
| Screen reader mode | `--screen-reader` | Accessibility |
| Rich diff rendering | `--plain-diff` | Terminal rendering |
| Startup banner | `--banner` | Visual element |
+| Streamer mode | `/streamer-mode` | TUI display mode |
+| Alternate screen buffer | `--alt-screen`, `--no-alt-screen` | Terminal rendering |
+| Mouse support | `--mouse`, `--no-mouse` | Terminal input |
| **Path/Permission Shortcuts** | | |
| Allow all paths | `--allow-all-paths` | Use permission handler |
| Allow all URLs | `--allow-all-urls` | Use permission handler |
-| YOLO mode | `--yolo` | Use permission handler |
+| Allow all permissions | `--yolo`, `--allow-all`, `/allow-all` | Use permission handler |
+| Granular tool permissions | `--allow-tool`, `--deny-tool` | Use `onPreToolUse` hook |
+| URL access control | `--allow-url`, `--deny-url` | Use permission handler |
+| Reset allowed tools | `/reset-allowed-tools` | TUI command |
| **Directory Management** | | |
| Add directory | `/add-dir`, `--add-dir` | Configure in session |
| List directories | `/list-dirs` | TUI command |
@@ -93,8 +135,13 @@ The Copilot SDK communicates with the CLI via JSON-RPC protocol. Features must b
| User info | `/user` | TUI command |
| **Session Operations** | | |
| Clear conversation | `/clear` | TUI-only |
-| Compact context | `/compact` | Use `infiniteSessions` config |
-| Plan view | `/plan` | TUI-only |
+| Plan view | `/plan` | TUI-only (use SDK `session.rpc.plan.*` instead) |
+| Session management | `/session`, `/resume`, `/rename` | TUI workflow |
+| Fleet mode (interactive) | `/fleet` | TUI-only (use SDK `session.rpc.fleet.start()` instead) |
+| **Skills Management** | | |
+| Manage skills | `/skills` | Interactive UI |
+| **Task Management** | | |
+| View background tasks | `/tasks` | TUI command |
| **Usage & Stats** | | |
| Token usage | `/usage` | Subscribe to usage events |
| **Code Review** | | |
@@ -103,8 +150,20 @@ The Copilot SDK communicates with the CLI via JSON-RPC protocol. Features must b
| Delegate to PR | `/delegate` | TUI workflow |
| **Terminal Setup** | | |
| Shell integration | `/terminal-setup` | Shell-specific |
-| **Experimental** | | |
-| Toggle experimental | `/experimental` | Runtime flag |
+| **Development** | | |
+| Toggle experimental | `/experimental`, `--experimental` | Runtime flag |
+| Custom instructions control | `--no-custom-instructions` | CLI flag |
+| Diagnose session | `/diagnose` | TUI command |
+| View/manage instructions | `/instructions` | TUI command |
+| Collect debug logs | `/collect-debug-logs` | Diagnostic tool |
+| Reindex workspace | `/reindex` | TUI command |
+| IDE integration | `/ide` | IDE-specific workflow |
+| **Non-interactive Mode** | | |
+| Prompt mode | `-p`, `--prompt` | Single-shot execution |
+| Interactive prompt | `-i`, `--interactive` | Auto-execute then interactive |
+| Silent output | `-s`, `--silent` | Script-friendly |
+| Continue session | `--continue` | Resume most recent |
+| Agent selection | `--agent ` | CLI flag |
## Workarounds
@@ -150,9 +209,10 @@ session.on("assistant.usage", (event) => {
### Context Compaction
-Instead of `/compact`, configure automatic compaction:
+Instead of `/compact`, configure automatic compaction or trigger it manually:
```typescript
+// Automatic compaction via config
const session = await client.createSession({
infiniteSessions: {
enabled: true,
@@ -160,10 +220,44 @@ const session = await client.createSession({
bufferExhaustionThreshold: 0.95, // Block and compact at 95% context utilization
},
});
+
+// Manual compaction (experimental)
+const result = await session.rpc.compaction.compact();
+console.log(`Removed ${result.tokensRemoved} tokens, ${result.messagesRemoved} messages`);
```
> **Note:** Thresholds are context utilization ratios (0.0-1.0), not absolute token counts.
+### Plan Management
+
+Read and write session plans programmatically:
+
+```typescript
+// Read the current plan
+const plan = await session.rpc.plan.read();
+if (plan.exists) {
+ console.log(plan.content);
+}
+
+// Update the plan
+await session.rpc.plan.update({ content: "# My Plan\n- Step 1\n- Step 2" });
+
+// Delete the plan
+await session.rpc.plan.delete();
+```
+
+### Message Steering
+
+Inject a message into the current LLM turn without aborting:
+
+```typescript
+// Steer the agent mid-turn
+await session.send({ prompt: "Focus on error handling first", mode: "immediate" });
+
+// Default: enqueue for next turn
+await session.send({ prompt: "Next, add tests" });
+```
+
## Protocol Limitations
The SDK can only access features exposed through the CLI's JSON-RPC protocol. If you need a CLI feature that's not available:
@@ -174,15 +268,23 @@ The SDK can only access features exposed through the CLI's JSON-RPC protocol. If
## Version Compatibility
-| SDK Version | CLI Version | Protocol Version |
-|-------------|-------------|------------------|
-| Check `package.json` | `copilot --version` | `getStatus().protocolVersion` |
+| SDK Protocol Range | CLI Protocol Version | Compatibility |
+|--------------------|---------------------|---------------|
+| v2–v3 | v3 | Full support |
+| v2–v3 | v2 | Supported with automatic v2 adapters |
+
+The SDK negotiates protocol versions with the CLI at startup. The SDK supports protocol versions 2 through 3. When connecting to a v2 CLI server, the SDK automatically adapts `tool.call` and `permission.request` messages to the v3 event model — no code changes required.
+
+Check versions at runtime:
-The SDK and CLI must have compatible protocol versions. The SDK will log warnings if versions are mismatched.
+```typescript
+const status = await client.getStatus();
+console.log("Protocol version:", status.protocolVersion);
+```
## See Also
-- [Getting Started Guide](./getting-started.md)
-- [Hooks Documentation](./hooks/overview.md)
-- [MCP Servers Guide](./mcp/overview.md)
+- [Getting Started Guide](../getting-started.md)
+- [Hooks Documentation](../hooks/index.md)
+- [MCP Servers Guide](../features/mcp.md)
- [Debugging Guide](./debugging.md)
diff --git a/docs/debugging.md b/docs/troubleshooting/debugging.md
similarity index 92%
rename from docs/debugging.md
rename to docs/troubleshooting/debugging.md
index bf953b2ffd..146d3fd5aa 100644
--- a/docs/debugging.md
+++ b/docs/troubleshooting/debugging.md
@@ -44,7 +44,21 @@ client = CopilotClient({"log_level": "debug"})
Go
-
+
+```go
+package main
+
+import copilot "github.com/github/copilot-sdk/go"
+
+func main() {
+ client := copilot.NewClient(&copilot.ClientOptions{
+ LogLevel: "debug",
+ })
+ _ = client
+}
+```
+
+
```go
import copilot "github.com/github/copilot-sdk/go"
@@ -59,6 +73,7 @@ client := copilot.NewClient(&copilot.ClientOptions{
.NET
+
```csharp
using GitHub.Copilot.SDK;
using Microsoft.Extensions.Logging;
@@ -110,7 +125,18 @@ const client = new CopilotClient({
Go
-
+
+```go
+package main
+
+func main() {
+ // The Go SDK does not currently support passing extra CLI arguments.
+ // For custom log directories, run the CLI manually with --log-dir
+ // and connect via CLIUrl option.
+}
+```
+
+
```go
// The Go SDK does not currently support passing extra CLI arguments.
// For custom log directories, run the CLI manually with --log-dir
@@ -271,14 +297,7 @@ var client = new CopilotClient(new CopilotClientOptions
copilot --server --stdio
```
-2. Enable auto-restart (enabled by default):
- ```typescript
- const client = new CopilotClient({
- autoRestart: true,
- });
- ```
-
-3. Check for port conflicts if using TCP mode:
+2. Check for port conflicts if using TCP mode:
```typescript
const client = new CopilotClient({
useStdio: false,
@@ -290,7 +309,7 @@ var client = new CopilotClient(new CopilotClientOptions
## MCP Server Debugging
-MCP (Model Context Protocol) servers can be tricky to debug. For comprehensive MCP debugging guidance, see the dedicated **[MCP Debugging Guide](./mcp/debugging.md)**.
+MCP (Model Context Protocol) servers can be tricky to debug. For comprehensive MCP debugging guidance, see the dedicated **[MCP Debugging Guide](./mcp-debugging.md)**.
### Quick MCP Checklist
@@ -308,7 +327,7 @@ Before integrating with the SDK, verify your MCP server works:
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | /path/to/your/mcp-server
```
-See [MCP Debugging Guide](./mcp/debugging.md) for detailed troubleshooting.
+See [MCP Debugging Guide](./mcp-debugging.md) for detailed troubleshooting.
---
@@ -493,7 +512,7 @@ If you're still stuck:
## See Also
-- [Getting Started Guide](./getting-started.md)
-- [MCP Overview](./mcp/overview.md) - MCP configuration and setup
-- [MCP Debugging Guide](./mcp/debugging.md) - Detailed MCP troubleshooting
+- [Getting Started Guide](../getting-started.md)
+- [MCP Overview](../features/mcp.md) - MCP configuration and setup
+- [MCP Debugging Guide](./mcp-debugging.md) - Detailed MCP troubleshooting
- [API Reference](https://github.com/github/copilot-sdk)
diff --git a/docs/mcp/debugging.md b/docs/troubleshooting/mcp-debugging.md
similarity index 82%
rename from docs/mcp/debugging.md
rename to docs/troubleshooting/mcp-debugging.md
index 5ca51d1e3b..30e05fd3e9 100644
--- a/docs/mcp/debugging.md
+++ b/docs/troubleshooting/mcp-debugging.md
@@ -242,7 +242,37 @@ cd /expected/working/dir
#### .NET Console Apps / Tools
-
+
+```csharp
+using GitHub.Copilot.SDK;
+
+public static class McpDotnetConfigExample
+{
+ public static void Main()
+ {
+ var servers = new Dictionary
+ {
+ ["my-dotnet-server"] = new McpLocalServerConfig
+ {
+ Type = "local",
+ Command = @"C:\Tools\MyServer\MyServer.exe",
+ Args = new List(),
+ Cwd = @"C:\Tools\MyServer",
+ Tools = new List { "*" },
+ },
+ ["my-dotnet-tool"] = new McpLocalServerConfig
+ {
+ Type = "local",
+ Command = "dotnet",
+ Args = new List { @"C:\Tools\MyTool\MyTool.dll" },
+ Cwd = @"C:\Tools\MyTool",
+ Tools = new List { "*" },
+ }
+ };
+ }
+}
+```
+
```csharp
// Correct configuration for .NET exe
["my-dotnet-server"] = new McpLocalServerConfig
@@ -267,7 +297,28 @@ cd /expected/working/dir
#### NPX Commands
-
+
+```csharp
+using GitHub.Copilot.SDK;
+
+public static class McpNpxConfigExample
+{
+ public static void Main()
+ {
+ var servers = new Dictionary
+ {
+ ["filesystem"] = new McpLocalServerConfig
+ {
+ Type = "local",
+ Command = "cmd",
+ Args = new List { "/c", "npx", "-y", "@modelcontextprotocol/server-filesystem", "C:\\allowed\\path" },
+ Tools = new List { "*" },
+ }
+ };
+ }
+}
+```
+
```csharp
// Windows needs cmd /c for npx
["filesystem"] = new McpLocalServerConfig
@@ -304,7 +355,19 @@ xattr -d com.apple.quarantine /path/to/mcp-server
#### Homebrew Paths
-
+
+```typescript
+import { MCPLocalServerConfig } from "@github/copilot-sdk";
+
+const mcpServers: Record = {
+ "my-server": {
+ command: "/opt/homebrew/bin/node",
+ args: ["/path/to/server.js"],
+ tools: ["*"],
+ },
+};
+```
+
```typescript
// GUI apps may not have /opt/homebrew in PATH
mcpServers: {
@@ -410,6 +473,6 @@ When opening an issue or asking for help, collect:
## See Also
-- [MCP Overview](./overview.md) - Configuration and setup
-- [General Debugging Guide](../debugging.md) - SDK-wide debugging
+- [MCP Overview](../features/mcp.md) - Configuration and setup
+- [General Debugging Guide](./debugging.md) - SDK-wide debugging
- [MCP Specification](https://modelcontextprotocol.io/) - Official protocol docs
diff --git a/dotnet/README.md b/dotnet/README.md
index bdb3e8dab4..cab1cf068c 100644
--- a/dotnet/README.md
+++ b/dotnet/README.md
@@ -28,10 +28,11 @@ using GitHub.Copilot.SDK;
await using var client = new CopilotClient();
await client.StartAsync();
-// Create a session
+// Create a session (OnPermissionRequest is required)
await using var session = await client.CreateSessionAsync(new SessionConfig
{
- Model = "gpt-5"
+ Model = "gpt-5",
+ OnPermissionRequest = PermissionHandler.ApproveAll,
});
// Wait for response using session.idle event
@@ -73,12 +74,12 @@ new CopilotClient(CopilotClientOptions? options = null)
- `UseStdio` - Use stdio transport instead of TCP (default: true)
- `LogLevel` - Log level (default: "info")
- `AutoStart` - Auto-start server (default: true)
-- `AutoRestart` - Auto-restart on crash (default: true)
- `Cwd` - Working directory for the CLI process
- `Environment` - Environment variables to pass to the CLI process
- `Logger` - `ILogger` instance for SDK logging
- `GitHubToken` - GitHub token for authentication. When provided, takes priority over other auth methods.
- `UseLoggedInUser` - Whether to use logged-in user for authentication (default: true, but false when `GitHubToken` is provided). Cannot be used with `CliUrl`.
+- `Telemetry` - OpenTelemetry configuration for the CLI process. Providing this enables telemetry — no separate flag needed. See [Telemetry](#telemetry) below.
#### Methods
@@ -110,6 +111,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)
+- `OnPermissionRequest` - **Required.** Handler called before each tool execution to approve or deny it. 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.
@@ -117,6 +119,10 @@ Create a new conversation session.
Resume an existing session. Returns the session with `WorkspacePath` populated if infinite sessions were enabled.
+**ResumeSessionConfig:**
+
+- `OnPermissionRequest` - **Required.** Handler called before each tool execution to approve or deny it. See [Permission Handling](#permission-handling) section.
+
##### `PingAsync(string? message = null): Task`
Ping the server to check connectivity.
@@ -265,18 +271,33 @@ session.On(evt =>
## Image Support
-The SDK supports image attachments via the `Attachments` parameter. You can attach images by providing their file path:
+The SDK supports image attachments via the `Attachments` parameter. You can attach images by providing their file path, or by passing base64-encoded data directly using a blob attachment:
```csharp
+// File attachment — runtime reads from disk
await session.SendAsync(new MessageOptions
{
Prompt = "What's in this image?",
Attachments = new List
{
- new UserMessageDataAttachmentsItem
+ new UserMessageDataAttachmentsItemFile
{
- Type = UserMessageDataAttachmentsItemType.File,
- Path = "/path/to/image.jpg"
+ Path = "/path/to/image.jpg",
+ DisplayName = "image.jpg",
+ }
+ }
+});
+
+// Blob attachment — provide base64 data directly
+await session.SendAsync(new MessageOptions
+{
+ Prompt = "What's in this image?",
+ Attachments = new List
+ {
+ new UserMessageDataAttachmentsItemBlob
+ {
+ Data = base64ImageData,
+ MimeType = "image/png",
}
}
});
@@ -449,6 +470,24 @@ var session = await client.CreateSessionAsync(new SessionConfig
});
```
+#### Skipping Permission Prompts
+
+Set `skip_permission` in the tool's `AdditionalProperties` to allow it to execute without triggering a permission prompt:
+
+```csharp
+var safeLookup = AIFunctionFactory.Create(
+ async ([Description("Lookup ID")] string id) => {
+ // your logic
+ },
+ "safe_lookup",
+ "A read-only lookup that needs no confirmation",
+ new AIFunctionFactoryOptions
+ {
+ AdditionalProperties = new ReadOnlyDictionary(
+ new Dictionary { ["skip_permission"] = true })
+ });
+```
+
### System Message Customization
Control the system prompt using `SystemMessage` in session config:
@@ -470,6 +509,34 @@ var session = await client.CreateSessionAsync(new SessionConfig
});
```
+#### Customize Mode
+
+Use `Mode = SystemMessageMode.Customize` to selectively override individual sections of the prompt while preserving the rest:
+
+```csharp
+var session = await client.CreateSessionAsync(new SessionConfig
+{
+ Model = "gpt-5",
+ SystemMessage = new SystemMessageConfig
+ {
+ Mode = SystemMessageMode.Customize,
+ Sections = new Dictionary
+ {
+ [SystemPromptSections.Tone] = new() { Action = SectionOverrideAction.Replace, Content = "Respond in a warm, professional tone. Be thorough in explanations." },
+ [SystemPromptSections.CodeChangeRules] = new() { Action = SectionOverrideAction.Remove },
+ [SystemPromptSections.Guidelines] = new() { Action = SectionOverrideAction.Append, Content = "\n* Always cite data sources" },
+ },
+ Content = "Focus on financial analysis and reporting."
+ }
+});
+```
+
+Available section IDs are defined as constants on `SystemPromptSections`: `Identity`, `Tone`, `ToolEfficiency`, `EnvironmentContext`, `CodeChangeRules`, `Guidelines`, `Safety`, `ToolInstructions`, `CustomInstructions`, `LastInstructions`.
+
+Each section override supports four actions: `Replace`, `Remove`, `Append`, and `Prepend`. Unknown section IDs are handled gracefully: content is appended to additional instructions, and `Remove` overrides are silently ignored.
+
+#### Replace Mode
+
For full control (removes all guardrails), use `Mode = SystemMessageMode.Replace`:
```csharp
@@ -529,6 +596,110 @@ var session = await client.CreateSessionAsync(new SessionConfig
});
```
+## Telemetry
+
+The SDK supports OpenTelemetry for distributed tracing. Provide a `Telemetry` config to enable trace export and automatic W3C Trace Context propagation.
+
+```csharp
+var client = new CopilotClient(new CopilotClientOptions
+{
+ Telemetry = new TelemetryConfig
+ {
+ OtlpEndpoint = "http://localhost:4318",
+ },
+});
+```
+
+**TelemetryConfig properties:**
+
+- `OtlpEndpoint` - OTLP HTTP endpoint URL
+- `FilePath` - File path for JSON-lines trace output
+- `ExporterType` - `"otlp-http"` or `"file"`
+- `SourceName` - Instrumentation scope name
+- `CaptureContent` - Whether to capture message content
+
+Trace context (`traceparent`/`tracestate`) is automatically propagated between the SDK and CLI on `CreateSessionAsync`, `ResumeSessionAsync`, and `SendAsync` calls, and inbound when the CLI invokes tool handlers.
+
+No extra dependencies — uses built-in `System.Diagnostics.Activity`.
+
+## Permission Handling
+
+An `OnPermissionRequest` handler is **required** whenever you create or resume a session. The handler is called before the agent executes each tool (file writes, shell commands, custom tools, etc.) and must return a decision.
+
+### Approve All (simplest)
+
+Use the built-in `PermissionHandler.ApproveAll` helper to allow every tool call without any checks:
+
+```csharp
+using GitHub.Copilot.SDK;
+
+var session = await client.CreateSessionAsync(new SessionConfig
+{
+ Model = "gpt-5",
+ OnPermissionRequest = PermissionHandler.ApproveAll,
+});
+```
+
+### Custom Permission Handler
+
+Provide your own `PermissionRequestHandler` delegate to inspect each request and apply custom logic:
+
+```csharp
+var session = await client.CreateSessionAsync(new SessionConfig
+{
+ Model = "gpt-5",
+ OnPermissionRequest = async (request, invocation) =>
+ {
+ // request.Kind — string discriminator for the type of operation being requested:
+ // "shell" — executing a shell command
+ // "write" — writing or editing a file
+ // "read" — reading a file
+ // "mcp" — calling an MCP tool
+ // "custom_tool" — calling one of your registered tools
+ // "url" — fetching a URL
+ // "memory" — accessing or modifying assistant memory
+ // "hook" — invoking a registered hook
+ // request.ToolCallId — the tool call that triggered this request
+ // request.ToolName — name of the tool (for custom-tool / mcp)
+ // request.FileName — file being written (for write)
+ // request.FullCommandText — full shell command text (for shell)
+
+ if (request.Kind == "shell")
+ {
+ // Deny shell commands
+ return new PermissionRequestResult { Kind = PermissionRequestResultKind.DeniedInteractivelyByUser };
+ }
+
+ return new PermissionRequestResult { Kind = PermissionRequestResultKind.Approved };
+ }
+});
+```
+
+### Permission Result Kinds
+
+| Value | Meaning |
+|-------|---------|
+| `PermissionRequestResultKind.Approved` | Allow the tool to run |
+| `PermissionRequestResultKind.DeniedInteractivelyByUser` | User explicitly denied the request |
+| `PermissionRequestResultKind.DeniedCouldNotRequestFromUser` | No approval rule matched and user could not be asked |
+| `PermissionRequestResultKind.DeniedByRules` | Denied by a policy rule |
+| `PermissionRequestResultKind.NoResult` | Leave the permission request unanswered (the SDK returns without calling the RPC). Not allowed for protocol v2 permission requests (will be rejected). |
+
+### Resuming Sessions
+
+Pass `OnPermissionRequest` when resuming a session too — it is required:
+
+```csharp
+var session = await client.ResumeSessionAsync("session-id", new ResumeSessionConfig
+{
+ OnPermissionRequest = PermissionHandler.ApproveAll,
+});
+```
+
+### Per-Tool Skip Permission
+
+To let a specific custom tool bypass the permission prompt entirely, set `skip_permission = true` in the tool's `AdditionalProperties`. See [Skipping Permission Prompts](#skipping-permission-prompts) under Tools.
+
## User Input Requests
Enable the agent to ask questions to the user using the `ask_user` tool by providing an `OnUserInputRequest` handler:
diff --git a/dotnet/src/Client.cs b/dotnet/src/Client.cs
index 8cad6b0489..99c0eff003 100644
--- a/dotnet/src/Client.cs
+++ b/dotnet/src/Client.cs
@@ -14,6 +14,7 @@
using System.Text;
using System.Text.Json;
using System.Text.Json.Serialization;
+using System.Text.Json.Serialization.Metadata;
using System.Text.RegularExpressions;
using GitHub.Copilot.SDK.Rpc;
using System.Globalization;
@@ -54,6 +55,9 @@ namespace GitHub.Copilot.SDK;
///
public sealed partial class CopilotClient : IDisposable, IAsyncDisposable
{
+ internal const string NoResultPermissionV2ErrorMessage =
+ "Permission handlers cannot return 'no-result' when connected to a protocol v2 server.";
+
///
/// Minimum protocol version this SDK can communicate with.
///
@@ -63,6 +67,7 @@ public sealed partial class CopilotClient : IDisposable, IAsyncDisposable
private readonly CopilotClientOptions _options;
private readonly ILogger _logger;
private Task? _connectionTask;
+ private volatile bool _disconnected;
private bool _disposed;
private readonly int? _optionsPort;
private readonly string? _optionsHost;
@@ -70,6 +75,7 @@ public sealed partial class CopilotClient : IDisposable, IAsyncDisposable
private int? _negotiatedProtocolVersion;
private List? _modelsCache;
private readonly SemaphoreSlim _modelsCacheLock = new(1, 1);
+ private readonly Func>>? _onListModels;
private readonly List> _lifecycleHandlers = [];
private readonly Dictionary>> _typedLifecycleHandlers = [];
private readonly object _lifecycleHandlersLock = new();
@@ -136,6 +142,7 @@ public CopilotClient(CopilotClientOptions? options = null)
}
_logger = _options.Logger ?? NullLogger.Instance;
+ _onListModels = _options.OnListModels;
// Parse CliUrl if provided
if (!string.IsNullOrEmpty(_options.CliUrl))
@@ -197,6 +204,7 @@ public Task StartAsync(CancellationToken cancellationToken = default)
async Task StartCoreAsync(CancellationToken ct)
{
_logger.LogDebug("Starting Copilot client");
+ _disconnected = false;
Task result;
@@ -357,6 +365,44 @@ private async Task CleanupConnectionAsync(List? errors)
}
}
+ private static (SystemMessageConfig? wireConfig, Dictionary>>? callbacks) ExtractTransformCallbacks(SystemMessageConfig? systemMessage)
+ {
+ if (systemMessage?.Mode != SystemMessageMode.Customize || systemMessage.Sections == null)
+ {
+ return (systemMessage, null);
+ }
+
+ var callbacks = new Dictionary>>();
+ var wireSections = new Dictionary();
+
+ foreach (var (sectionId, sectionOverride) in systemMessage.Sections)
+ {
+ if (sectionOverride.Transform != null)
+ {
+ callbacks[sectionId] = sectionOverride.Transform;
+ wireSections[sectionId] = new SectionOverride { Action = SectionOverrideAction.Transform };
+ }
+ else
+ {
+ wireSections[sectionId] = sectionOverride;
+ }
+ }
+
+ if (callbacks.Count == 0)
+ {
+ return (systemMessage, null);
+ }
+
+ var wireConfig = new SystemMessageConfig
+ {
+ Mode = systemMessage.Mode,
+ Content = systemMessage.Content,
+ Sections = wireSections
+ };
+
+ return (wireConfig, callbacks);
+ }
+
///
/// Creates a new Copilot session with the specified configuration.
///
@@ -401,33 +447,13 @@ public async Task CreateSessionAsync(SessionConfig config, Cance
config.Hooks.OnSessionEnd != null ||
config.Hooks.OnErrorOccurred != null);
- var request = new CreateSessionRequest(
- config.Model,
- config.SessionId,
- config.ClientName,
- config.ReasoningEffort,
- config.Tools?.Select(ToolDefinition.FromAIFunction).ToList(),
- config.SystemMessage,
- config.AvailableTools,
- config.ExcludedTools,
- config.Provider,
- (bool?)true,
- config.OnUserInputRequest != null ? true : null,
- hasHooks ? true : null,
- config.WorkingDirectory,
- config.Streaming is true ? true : null,
- config.McpServers,
- "direct",
- config.CustomAgents,
- config.ConfigDir,
- config.SkillDirectories,
- config.DisabledSkills,
- config.InfiniteSessions);
-
- var response = await InvokeRpcAsync(
- connection.Rpc, "session.create", [request], cancellationToken);
-
- var session = new CopilotSession(response.SessionId, connection.Rpc, response.WorkspacePath);
+ var (wireSystemMessage, transformCallbacks) = ExtractTransformCallbacks(config.SystemMessage);
+
+ var sessionId = config.SessionId ?? Guid.NewGuid().ToString();
+
+ // Create and register the session before issuing the RPC so that
+ // events emitted by the CLI (e.g. session.start) are not dropped.
+ var session = new CopilotSession(sessionId, connection.Rpc, _logger);
session.RegisterTools(config.Tools ?? []);
session.RegisterPermissionHandler(config.OnPermissionRequest);
if (config.OnUserInputRequest != null)
@@ -438,10 +464,55 @@ public async Task CreateSessionAsync(SessionConfig config, Cance
{
session.RegisterHooks(config.Hooks);
}
+ if (transformCallbacks != null)
+ {
+ session.RegisterTransformCallbacks(transformCallbacks);
+ }
+ if (config.OnEvent != null)
+ {
+ session.On(config.OnEvent);
+ }
+ _sessions[sessionId] = session;
- if (!_sessions.TryAdd(response.SessionId, session))
+ try
+ {
+ var (traceparent, tracestate) = TelemetryHelpers.GetTraceContext();
+
+ var request = new CreateSessionRequest(
+ config.Model,
+ sessionId,
+ config.ClientName,
+ config.ReasoningEffort,
+ config.Tools?.Select(ToolDefinition.FromAIFunction).ToList(),
+ wireSystemMessage,
+ config.AvailableTools,
+ config.ExcludedTools,
+ config.Provider,
+ (bool?)true,
+ config.OnUserInputRequest != null ? true : null,
+ hasHooks ? true : null,
+ config.WorkingDirectory,
+ config.Streaming is true ? true : null,
+ config.McpServers,
+ "direct",
+ config.CustomAgents,
+ config.Agent,
+ config.ConfigDir,
+ config.SkillDirectories,
+ config.DisabledSkills,
+ config.InfiniteSessions,
+ traceparent,
+ tracestate);
+
+ var response = await InvokeRpcAsync(
+ connection.Rpc, "session.create", [request], cancellationToken);
+
+ session.WorkspacePath = response.WorkspacePath;
+ }
+ catch
{
- throw new InvalidOperationException($"Session {response.SessionId} already exists");
+ _sessions.TryRemove(sessionId, out _);
+ throw;
}
return session;
@@ -492,34 +563,11 @@ public async Task ResumeSessionAsync(string sessionId, ResumeSes
config.Hooks.OnSessionEnd != null ||
config.Hooks.OnErrorOccurred != null);
- var request = new ResumeSessionRequest(
- sessionId,
- config.ClientName,
- config.Model,
- config.ReasoningEffort,
- config.Tools?.Select(ToolDefinition.FromAIFunction).ToList(),
- config.SystemMessage,
- config.AvailableTools,
- config.ExcludedTools,
- config.Provider,
- (bool?)true,
- config.OnUserInputRequest != null ? true : null,
- hasHooks ? true : null,
- config.WorkingDirectory,
- config.ConfigDir,
- config.DisableResume is true ? true : null,
- config.Streaming is true ? true : null,
- config.McpServers,
- "direct",
- config.CustomAgents,
- config.SkillDirectories,
- config.DisabledSkills,
- config.InfiniteSessions);
-
- var response = await InvokeRpcAsync(
- connection.Rpc, "session.resume", [request], cancellationToken);
-
- var session = new CopilotSession(response.SessionId, connection.Rpc, response.WorkspacePath);
+ var (wireSystemMessage, transformCallbacks) = ExtractTransformCallbacks(config.SystemMessage);
+
+ // Create and register the session before issuing the RPC so that
+ // events emitted by the CLI (e.g. session.start) are not dropped.
+ var session = new CopilotSession(sessionId, connection.Rpc, _logger);
session.RegisterTools(config.Tools ?? []);
session.RegisterPermissionHandler(config.OnPermissionRequest);
if (config.OnUserInputRequest != null)
@@ -530,9 +578,58 @@ public async Task ResumeSessionAsync(string sessionId, ResumeSes
{
session.RegisterHooks(config.Hooks);
}
+ if (transformCallbacks != null)
+ {
+ session.RegisterTransformCallbacks(transformCallbacks);
+ }
+ if (config.OnEvent != null)
+ {
+ session.On(config.OnEvent);
+ }
+ _sessions[sessionId] = session;
+
+ try
+ {
+ var (traceparent, tracestate) = TelemetryHelpers.GetTraceContext();
+
+ var request = new ResumeSessionRequest(
+ sessionId,
+ config.ClientName,
+ config.Model,
+ config.ReasoningEffort,
+ config.Tools?.Select(ToolDefinition.FromAIFunction).ToList(),
+ wireSystemMessage,
+ config.AvailableTools,
+ config.ExcludedTools,
+ config.Provider,
+ (bool?)true,
+ config.OnUserInputRequest != null ? true : null,
+ hasHooks ? true : null,
+ config.WorkingDirectory,
+ config.ConfigDir,
+ config.DisableResume is true ? true : null,
+ config.Streaming is true ? true : null,
+ config.McpServers,
+ "direct",
+ config.CustomAgents,
+ config.Agent,
+ config.SkillDirectories,
+ config.DisabledSkills,
+ config.InfiniteSessions,
+ traceparent,
+ tracestate);
+
+ var response = await InvokeRpcAsync(
+ connection.Rpc, "session.resume", [request], cancellationToken);
+
+ session.WorkspacePath = response.WorkspacePath;
+ }
+ catch
+ {
+ _sessions.TryRemove(sessionId, out _);
+ throw;
+ }
- // Replace any existing session entry to ensure new config (like permission handler) is used
- _sessions[response.SessionId] = session;
return session;
}
@@ -557,6 +654,7 @@ public ConnectionState State
if (_connectionTask == null) return ConnectionState.Disconnected;
if (_connectionTask.IsFaulted) return ConnectionState.Error;
if (!_connectionTask.IsCompleted) return ConnectionState.Connecting;
+ if (_disconnected) return ConnectionState.Disconnected;
return ConnectionState.Connected;
}
}
@@ -622,9 +720,6 @@ public async Task GetAuthStatusAsync(CancellationToken ca
/// Thrown when the client is not connected or not authenticated.
public async Task> ListModelsAsync(CancellationToken cancellationToken = default)
{
- var connection = await EnsureConnectedAsync(cancellationToken);
-
- // Use semaphore for async locking to prevent race condition with concurrent calls
await _modelsCacheLock.WaitAsync(cancellationToken);
try
{
@@ -634,14 +729,26 @@ public async Task> ListModelsAsync(CancellationToken cancellatio
return [.. _modelsCache]; // Return a copy to prevent cache mutation
}
- // Cache miss - fetch from backend while holding lock
- var response = await InvokeRpcAsync(
- connection.Rpc, "models.list", [], cancellationToken);
+ List models;
+ if (_onListModels is not null)
+ {
+ // Use custom handler instead of CLI RPC
+ models = await _onListModels(cancellationToken);
+ }
+ else
+ {
+ var connection = await EnsureConnectedAsync(cancellationToken);
+
+ // Cache miss - fetch from backend while holding lock
+ var response = await InvokeRpcAsync(
+ connection.Rpc, "models.list", [], cancellationToken);
+ models = response.Models;
+ }
- // Update cache before releasing lock
- _modelsCache = response.Models;
+ // Update cache before releasing lock (copy to prevent external mutation)
+ _modelsCache = [.. models];
- return [.. response.Models]; // Return a copy to prevent cache mutation
+ return [.. models]; // Return a copy to prevent cache mutation
}
finally
{
@@ -1022,6 +1129,17 @@ private async Task VerifyProtocolVersionAsync(Connection connection, Cancellatio
startInfo.Environment["COPILOT_SDK_AUTH_TOKEN"] = options.GitHubToken;
}
+ // Set telemetry environment variables if configured
+ if (options.Telemetry is { } telemetry)
+ {
+ startInfo.Environment["COPILOT_OTEL_ENABLED"] = "true";
+ if (telemetry.OtlpEndpoint is not null) startInfo.Environment["OTEL_EXPORTER_OTLP_ENDPOINT"] = telemetry.OtlpEndpoint;
+ if (telemetry.FilePath is not null) startInfo.Environment["COPILOT_OTEL_FILE_EXPORTER_PATH"] = telemetry.FilePath;
+ if (telemetry.ExporterType is not null) startInfo.Environment["COPILOT_OTEL_EXPORTER_TYPE"] = telemetry.ExporterType;
+ if (telemetry.SourceName is not null) startInfo.Environment["COPILOT_OTEL_SOURCE_NAME"] = telemetry.SourceName;
+ if (telemetry.CaptureContent is { } capture) startInfo.Environment["OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT"] = capture ? "true" : "false";
+ }
+
var cliProcess = new Process { StartInfo = startInfo };
cliProcess.Start();
@@ -1154,8 +1272,12 @@ private async Task ConnectToServerAsync(Process? cliProcess, string?
rpc.AddLocalRpcMethod("permission.request", handler.OnPermissionRequestV2);
rpc.AddLocalRpcMethod("userInput.request", handler.OnUserInputRequest);
rpc.AddLocalRpcMethod("hooks.invoke", handler.OnHooksInvoke);
+ rpc.AddLocalRpcMethod("systemMessage.transform", handler.OnSystemMessageTransform);
rpc.StartListening();
+ // Transition state to Disconnected if the JSON-RPC connection drops
+ _ = rpc.Completion.ContinueWith(_ => _disconnected = true, TaskScheduler.Default);
+
_rpc = new ServerRpc(rpc);
return new Connection(rpc, cliProcess, tcpClient, networkStream, stderrBuffer);
@@ -1184,6 +1306,12 @@ private static JsonSerializerOptions CreateSerializerOptions()
options.TypeInfoResolverChain.Add(SessionEventsJsonContext.Default);
options.TypeInfoResolverChain.Add(SDK.Rpc.RpcJsonContext.Default);
+ // StreamJsonRpc's RequestId needs serialization when CancellationToken fires during
+ // JSON-RPC operations. Its built-in converter (RequestIdSTJsonConverter) is internal,
+ // and [JsonSerializable] can't source-gen for it (SYSLIB1220), so we provide our own
+ // AOT-safe resolver + converter.
+ options.TypeInfoResolverChain.Add(new RequestIdTypeInfoResolver());
+
options.MakeReadOnly();
return options;
@@ -1273,13 +1401,23 @@ public async Task OnHooksInvoke(string sessionId, string ho
return new HooksInvokeResponse(output);
}
+ public async Task OnSystemMessageTransform(string sessionId, JsonElement sections)
+ {
+ var session = client.GetSession(sessionId) ?? throw new ArgumentException($"Unknown session {sessionId}");
+ return await session.HandleSystemMessageTransformAsync(sections);
+ }
+
// Protocol v2 backward-compatibility adapters
public async Task OnToolCallV2(string sessionId,
string toolCallId,
string toolName,
- object? arguments)
+ object? arguments,
+ string? traceparent = null,
+ string? tracestate = null)
{
+ using var _ = TelemetryHelpers.RestoreTraceContext(traceparent, tracestate);
+
var session = client.GetSession(sessionId) ?? throw new ArgumentException($"Unknown session {sessionId}");
if (session.GetTool(toolName) is not { } tool)
{
@@ -1352,8 +1490,16 @@ public async Task OnPermissionRequestV2(string sess
try
{
var result = await session.HandlePermissionRequestAsync(permissionRequest);
+ if (result.Kind == new PermissionRequestResultKind("no-result"))
+ {
+ throw new InvalidOperationException(NoResultPermissionV2ErrorMessage);
+ }
return new PermissionRequestResponseV2(result);
}
+ catch (InvalidOperationException ex) when (ex.Message == NoResultPermissionV2ErrorMessage)
+ {
+ throw;
+ }
catch (Exception)
{
return new PermissionRequestResponseV2(new PermissionRequestResult
@@ -1407,22 +1553,28 @@ internal record CreateSessionRequest(
Dictionary? McpServers,
string? EnvValueMode,
List? CustomAgents,
+ string? Agent,
string? ConfigDir,
List? SkillDirectories,
List? DisabledSkills,
- InfiniteSessionConfig? InfiniteSessions);
+ InfiniteSessionConfig? InfiniteSessions,
+ string? Traceparent = null,
+ string? Tracestate = null);
internal record ToolDefinition(
string Name,
string? Description,
JsonElement Parameters, /* JSON schema */
- bool? OverridesBuiltInTool = null)
+ bool? OverridesBuiltInTool = null,
+ bool? SkipPermission = null)
{
public static ToolDefinition FromAIFunction(AIFunction function)
{
var overrides = function.AdditionalProperties.TryGetValue("is_override", out var val) && val is true;
+ var skipPerm = function.AdditionalProperties.TryGetValue("skip_permission", out var skipVal) && skipVal is true;
return new ToolDefinition(function.Name, function.Description, function.JsonSchema,
- overrides ? true : null);
+ overrides ? true : null,
+ skipPerm ? true : null);
}
}
@@ -1450,9 +1602,12 @@ internal record ResumeSessionRequest(
Dictionary? McpServers,
string? EnvValueMode,
List? CustomAgents,
+ string? Agent,
List? SkillDirectories,
List? DisabledSkills,
- InfiniteSessionConfig? InfiniteSessions);
+ InfiniteSessionConfig? InfiniteSessions,
+ string? Traceparent = null,
+ string? Tracestate = null);
internal record ResumeSessionResponse(
string SessionId,
@@ -1587,6 +1742,7 @@ private static LogLevel MapLevel(TraceEventType eventType)
[JsonSerializable(typeof(ResumeSessionResponse))]
[JsonSerializable(typeof(SessionMetadata))]
[JsonSerializable(typeof(SystemMessageConfig))]
+ [JsonSerializable(typeof(SystemMessageTransformRpcResponse))]
[JsonSerializable(typeof(ToolCallResponseV2))]
[JsonSerializable(typeof(ToolDefinition))]
[JsonSerializable(typeof(ToolResultAIContent))]
@@ -1596,6 +1752,50 @@ private static LogLevel MapLevel(TraceEventType eventType)
[JsonSerializable(typeof(UserInputResponse))]
internal partial class ClientJsonContext : JsonSerializerContext;
+ ///
+ /// AOT-safe type info resolver for .
+ /// StreamJsonRpc's own RequestIdSTJsonConverter is internal (SYSLIB1220/CS0122),
+ /// so we provide our own converter and wire it through
+ /// to stay fully AOT/trimming-compatible.
+ ///
+ private sealed class RequestIdTypeInfoResolver : IJsonTypeInfoResolver
+ {
+ public JsonTypeInfo? GetTypeInfo(Type type, JsonSerializerOptions options)
+ {
+ if (type == typeof(RequestId))
+ return JsonMetadataServices.CreateValueInfo(options, new RequestIdJsonConverter());
+ return null;
+ }
+ }
+
+ private sealed class RequestIdJsonConverter : JsonConverter
+ {
+ public override RequestId Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
+ {
+ return reader.TokenType switch
+ {
+ JsonTokenType.Number => reader.TryGetInt64(out long val)
+ ? new RequestId(val)
+ : new RequestId(reader.HasValueSequence
+ ? Encoding.UTF8.GetString(reader.ValueSequence)
+ : Encoding.UTF8.GetString(reader.ValueSpan)),
+ JsonTokenType.String => new RequestId(reader.GetString()!),
+ JsonTokenType.Null => RequestId.Null,
+ _ => throw new JsonException($"Unexpected token type for RequestId: {reader.TokenType}"),
+ };
+ }
+
+ public override void Write(Utf8JsonWriter writer, RequestId value, JsonSerializerOptions options)
+ {
+ if (value.Number.HasValue)
+ writer.WriteNumberValue(value.Number.Value);
+ else if (value.String is not null)
+ writer.WriteStringValue(value.String);
+ else
+ writer.WriteNullValue();
+ }
+ }
+
[GeneratedRegex(@"listening on port ([0-9]+)", RegexOptions.IgnoreCase)]
private static partial Regex ListeningOnPortRegex();
}
diff --git a/dotnet/src/Generated/Rpc.cs b/dotnet/src/Generated/Rpc.cs
index 85e55e4b80..fabe4817ed 100644
--- a/dotnet/src/Generated/Rpc.cs
+++ b/dotnet/src/Generated/Rpc.cs
@@ -5,220 +5,293 @@
// AUTO-GENERATED FILE - DO NOT EDIT
// Generated from: api.schema.json
-// Generated code does not have XML doc comments; suppress CS1591 to avoid warnings.
-#pragma warning disable CS1591
-
+using System.Diagnostics.CodeAnalysis;
using System.Text.Json;
using System.Text.Json.Serialization;
using StreamJsonRpc;
namespace GitHub.Copilot.SDK.Rpc;
+/// Diagnostic IDs for the Copilot SDK.
+internal static class Diagnostics
+{
+ /// Indicates an experimental API that may change or be removed.
+ internal const string Experimental = "GHCP001";
+}
+
+/// RPC data type for Ping operations.
public class PingResult
{
- /// Echoed message (or default greeting)
+ /// Echoed message (or default greeting).
[JsonPropertyName("message")]
public string Message { get; set; } = string.Empty;
- /// Server timestamp in milliseconds
+ /// Server timestamp in milliseconds.
[JsonPropertyName("timestamp")]
public double Timestamp { get; set; }
- /// Server protocol version number
+ /// Server protocol version number.
[JsonPropertyName("protocolVersion")]
public double ProtocolVersion { get; set; }
}
+/// RPC data type for Ping operations.
internal class PingRequest
{
+ /// Optional message to echo back.
[JsonPropertyName("message")]
public string? Message { get; set; }
}
+/// Feature flags indicating what the model supports.
public class ModelCapabilitiesSupports
{
+ /// Whether this model supports vision/image input.
[JsonPropertyName("vision")]
public bool? Vision { get; set; }
- /// Whether this model supports reasoning effort configuration
+ /// Whether this model supports reasoning effort configuration.
[JsonPropertyName("reasoningEffort")]
public bool? ReasoningEffort { get; set; }
}
+/// Token limits for prompts, outputs, and context window.
public class ModelCapabilitiesLimits
{
+ /// Maximum number of prompt/input tokens.
[JsonPropertyName("max_prompt_tokens")]
public double? MaxPromptTokens { get; set; }
+ /// Maximum number of output/completion tokens.
[JsonPropertyName("max_output_tokens")]
public double? MaxOutputTokens { get; set; }
+ /// Maximum total context window size in tokens.
[JsonPropertyName("max_context_window_tokens")]
public double MaxContextWindowTokens { get; set; }
}
-/// Model capabilities and limits
+/// Model capabilities and limits.
public class ModelCapabilities
{
+ /// Feature flags indicating what the model supports.
[JsonPropertyName("supports")]
- public ModelCapabilitiesSupports Supports { get; set; } = new();
+ public ModelCapabilitiesSupports Supports { get => field ??= new(); set; }
+ /// Token limits for prompts, outputs, and context window.
[JsonPropertyName("limits")]
- public ModelCapabilitiesLimits Limits { get; set; } = new();
+ public ModelCapabilitiesLimits Limits { get => field ??= new(); set; }
}
-/// Policy state (if applicable)
+/// Policy state (if applicable).
public class ModelPolicy
{
+ /// Current policy state for this model.
[JsonPropertyName("state")]
public string State { get; set; } = string.Empty;
+ /// Usage terms or conditions for this model.
[JsonPropertyName("terms")]
public string Terms { get; set; } = string.Empty;
}
-/// Billing information
+/// Billing information.
public class ModelBilling
{
+ /// Billing cost multiplier relative to the base rate.
[JsonPropertyName("multiplier")]
public double Multiplier { get; set; }
}
+/// RPC data type for Model operations.
public class Model
{
- /// Model identifier (e.g., "claude-sonnet-4.5")
+ /// Model identifier (e.g., "claude-sonnet-4.5").
[JsonPropertyName("id")]
public string Id { get; set; } = string.Empty;
- /// Display name
+ /// Display name.
[JsonPropertyName("name")]
public string Name { get; set; } = string.Empty;
- /// Model capabilities and limits
+ /// Model capabilities and limits.
[JsonPropertyName("capabilities")]
- public ModelCapabilities Capabilities { get; set; } = new();
+ public ModelCapabilities Capabilities { get => field ??= new(); set; }
- /// Policy state (if applicable)
+ /// Policy state (if applicable).
[JsonPropertyName("policy")]
public ModelPolicy? Policy { get; set; }
- /// Billing information
+ /// Billing information.
[JsonPropertyName("billing")]
public ModelBilling? Billing { get; set; }
- /// Supported reasoning effort levels (only present if model supports reasoning effort)
+ /// Supported reasoning effort levels (only present if model supports reasoning effort).
[JsonPropertyName("supportedReasoningEfforts")]
public List? SupportedReasoningEfforts { get; set; }
- /// Default reasoning effort level (only present if model supports reasoning effort)
+ /// Default reasoning effort level (only present if model supports reasoning effort).
[JsonPropertyName("defaultReasoningEffort")]
public string? DefaultReasoningEffort { get; set; }
}
+/// RPC data type for ModelsList operations.
public class ModelsListResult
{
- /// List of available models with full metadata
+ /// List of available models with full metadata.
[JsonPropertyName("models")]
- public List Models { get; set; } = [];
+ public List Models { get => field ??= []; set; }
}
+/// RPC data type for Tool operations.
public class Tool
{
- /// Tool identifier (e.g., "bash", "grep", "str_replace_editor")
+ /// Tool identifier (e.g., "bash", "grep", "str_replace_editor").
[JsonPropertyName("name")]
public string Name { get; set; } = string.Empty;
- /// Optional namespaced name for declarative filtering (e.g., "playwright/navigate" for MCP tools)
+ /// Optional namespaced name for declarative filtering (e.g., "playwright/navigate" for MCP tools).
[JsonPropertyName("namespacedName")]
public string? NamespacedName { get; set; }
- /// Description of what the tool does
+ /// Description of what the tool does.
[JsonPropertyName("description")]
public string Description { get; set; } = string.Empty;
- /// JSON Schema for the tool's input parameters
+ /// JSON Schema for the tool's input parameters.
[JsonPropertyName("parameters")]
public Dictionary? Parameters { get; set; }
- /// Optional instructions for how to use this tool effectively
+ /// Optional instructions for how to use this tool effectively.
[JsonPropertyName("instructions")]
public string? Instructions { get; set; }
}
+/// RPC data type for ToolsList operations.
public class ToolsListResult
{
- /// List of available built-in tools with metadata
+ /// List of available built-in tools with metadata.
[JsonPropertyName("tools")]
- public List Tools { get; set; } = [];
+ public List Tools { get => field ??= []; set; }
}
+/// RPC data type for ToolsList operations.
internal class ToolsListRequest
{
+ /// Optional model ID — when provided, the returned tool list reflects model-specific overrides.
[JsonPropertyName("model")]
public string? Model { get; set; }
}
+/// RPC data type for AccountGetQuotaResultQuotaSnapshotsValue operations.
public class AccountGetQuotaResultQuotaSnapshotsValue
{
- /// Number of requests included in the entitlement
+ /// Number of requests included in the entitlement.
[JsonPropertyName("entitlementRequests")]
public double EntitlementRequests { get; set; }
- /// Number of requests used so far this period
+ /// Number of requests used so far this period.
[JsonPropertyName("usedRequests")]
public double UsedRequests { get; set; }
- /// Percentage of entitlement remaining
+ /// Percentage of entitlement remaining.
[JsonPropertyName("remainingPercentage")]
public double RemainingPercentage { get; set; }
- /// Number of overage requests made this period
+ /// Number of overage requests made this period.
[JsonPropertyName("overage")]
public double Overage { get; set; }
- /// Whether pay-per-request usage is allowed when quota is exhausted
+ /// Whether pay-per-request usage is allowed when quota is exhausted.
[JsonPropertyName("overageAllowedWithExhaustedQuota")]
public bool OverageAllowedWithExhaustedQuota { get; set; }
- /// Date when the quota resets (ISO 8601)
+ /// Date when the quota resets (ISO 8601).
[JsonPropertyName("resetDate")]
public string? ResetDate { get; set; }
}
+/// RPC data type for AccountGetQuota operations.
public class AccountGetQuotaResult
{
- /// Quota snapshots keyed by type (e.g., chat, completions, premium_interactions)
+ /// Quota snapshots keyed by type (e.g., chat, completions, premium_interactions).
[JsonPropertyName("quotaSnapshots")]
- public Dictionary QuotaSnapshots { get; set; } = [];
+ public Dictionary QuotaSnapshots { get => field ??= []; set; }
+}
+
+/// RPC data type for SessionLog operations.
+public class SessionLogResult
+{
+ /// The unique identifier of the emitted session event.
+ [JsonPropertyName("eventId")]
+ public Guid EventId { get; set; }
+}
+
+/// RPC data type for SessionLog operations.
+internal class SessionLogRequest
+{
+ /// Target session identifier.
+ [JsonPropertyName("sessionId")]
+ public string SessionId { get; set; } = string.Empty;
+
+ /// Human-readable message.
+ [JsonPropertyName("message")]
+ public string Message { get; set; } = string.Empty;
+
+ /// Log severity level. Determines how the message is displayed in the timeline. Defaults to "info".
+ [JsonPropertyName("level")]
+ public SessionLogRequestLevel? Level { get; set; }
+
+ /// When true, the message is transient and not persisted to the session event log on disk.
+ [JsonPropertyName("ephemeral")]
+ public bool? Ephemeral { get; set; }
+
+ /// Optional URL the user can open in their browser for more details.
+ [JsonPropertyName("url")]
+ public string? Url { get; set; }
}
+/// RPC data type for SessionModelGetCurrent operations.
public class SessionModelGetCurrentResult
{
+ /// Currently active model identifier.
[JsonPropertyName("modelId")]
public string? ModelId { get; set; }
}
+/// RPC data type for SessionModelGetCurrent operations.
internal class SessionModelGetCurrentRequest
{
+ /// Target session identifier.
[JsonPropertyName("sessionId")]
public string SessionId { get; set; } = string.Empty;
}
+/// RPC data type for SessionModelSwitchTo operations.
public class SessionModelSwitchToResult
{
+ /// Currently active model identifier after the switch.
[JsonPropertyName("modelId")]
public string? ModelId { get; set; }
}
+/// RPC data type for SessionModelSwitchTo operations.
internal class SessionModelSwitchToRequest
{
+ /// Target session identifier.
[JsonPropertyName("sessionId")]
public string SessionId { get; set; } = string.Empty;
+ /// Model identifier to switch to.
[JsonPropertyName("modelId")]
public string ModelId { get; set; } = string.Empty;
+
+ /// Reasoning effort level to use for the model.
+ [JsonPropertyName("reasoningEffort")]
+ public string? ReasoningEffort { get; set; }
}
+/// RPC data type for SessionModeGet operations.
public class SessionModeGetResult
{
/// The current agent mode.
@@ -226,12 +299,15 @@ public class SessionModeGetResult
public SessionModeGetResultMode Mode { get; set; }
}
+/// RPC data type for SessionModeGet operations.
internal class SessionModeGetRequest
{
+ /// Target session identifier.
[JsonPropertyName("sessionId")]
public string SessionId { get; set; } = string.Empty;
}
+/// RPC data type for SessionModeSet operations.
public class SessionModeSetResult
{
/// The agent mode after switching.
@@ -239,291 +315,930 @@ public class SessionModeSetResult
public SessionModeGetResultMode Mode { get; set; }
}
+/// RPC data type for SessionModeSet operations.
internal class SessionModeSetRequest
{
+ /// Target session identifier.
[JsonPropertyName("sessionId")]
public string SessionId { get; set; } = string.Empty;
+ /// The mode to switch to. Valid values: "interactive", "plan", "autopilot".
[JsonPropertyName("mode")]
public SessionModeGetResultMode Mode { get; set; }
}
+/// RPC data type for SessionPlanRead operations.
public class SessionPlanReadResult
{
- /// Whether the plan file exists in the workspace
+ /// Whether the plan file exists in the workspace.
[JsonPropertyName("exists")]
public bool Exists { get; set; }
- /// The content of the plan file, or null if it does not exist
+ /// The content of the plan file, or null if it does not exist.
[JsonPropertyName("content")]
public string? Content { get; set; }
- /// Absolute file path of the plan file, or null if workspace is not enabled
+ /// Absolute file path of the plan file, or null if workspace is not enabled.
[JsonPropertyName("path")]
public string? Path { get; set; }
}
+/// RPC data type for SessionPlanRead operations.
internal class SessionPlanReadRequest
{
+ /// Target session identifier.
[JsonPropertyName("sessionId")]
public string SessionId { get; set; } = string.Empty;
}
+/// RPC data type for SessionPlanUpdate operations.
public class SessionPlanUpdateResult
{
}
+/// RPC data type for SessionPlanUpdate operations.
internal class SessionPlanUpdateRequest
{
+ /// Target session identifier.
[JsonPropertyName("sessionId")]
public string SessionId { get; set; } = string.Empty;
+ /// The new content for the plan file.
[JsonPropertyName("content")]
public string Content { get; set; } = string.Empty;
}
+/// RPC data type for SessionPlanDelete operations.
public class SessionPlanDeleteResult
{
}
+/// RPC data type for SessionPlanDelete operations.
internal class SessionPlanDeleteRequest
{
+ /// Target session identifier.
[JsonPropertyName("sessionId")]
public string SessionId { get; set; } = string.Empty;
}
+/// RPC data type for SessionWorkspaceListFiles operations.
public class SessionWorkspaceListFilesResult
{
- /// Relative file paths in the workspace files directory
+ /// Relative file paths in the workspace files directory.
[JsonPropertyName("files")]
- public List Files { get; set; } = [];
+ public List Files { get => field ??= []; set; }
}
+/// RPC data type for SessionWorkspaceListFiles operations.
internal class SessionWorkspaceListFilesRequest
{
+ /// Target session identifier.
[JsonPropertyName("sessionId")]
public string SessionId { get; set; } = string.Empty;
}
+/// RPC data type for SessionWorkspaceReadFile operations.
public class SessionWorkspaceReadFileResult
{
- /// File content as a UTF-8 string
+ /// File content as a UTF-8 string.
[JsonPropertyName("content")]
public string Content { get; set; } = string.Empty;
}
+/// RPC data type for SessionWorkspaceReadFile operations.
internal class SessionWorkspaceReadFileRequest
{
+ /// Target session identifier.
[JsonPropertyName("sessionId")]
public string SessionId { get; set; } = string.Empty;
+ /// Relative path within the workspace files directory.
[JsonPropertyName("path")]
public string Path { get; set; } = string.Empty;
}
+/// RPC data type for SessionWorkspaceCreateFile operations.
public class SessionWorkspaceCreateFileResult
{
}
+/// RPC data type for SessionWorkspaceCreateFile operations.
internal class SessionWorkspaceCreateFileRequest
{
+ /// Target session identifier.
[JsonPropertyName("sessionId")]
public string SessionId { get; set; } = string.Empty;
+ /// Relative path within the workspace files directory.
[JsonPropertyName("path")]
public string Path { get; set; } = string.Empty;
+ /// File content to write as a UTF-8 string.
[JsonPropertyName("content")]
public string Content { get; set; } = string.Empty;
}
+/// RPC data type for SessionFleetStart operations.
+[Experimental(Diagnostics.Experimental)]
public class SessionFleetStartResult
{
- /// Whether fleet mode was successfully activated
+ /// Whether fleet mode was successfully activated.
[JsonPropertyName("started")]
public bool Started { get; set; }
}
+/// RPC data type for SessionFleetStart operations.
+[Experimental(Diagnostics.Experimental)]
internal class SessionFleetStartRequest
{
+ /// Target session identifier.
[JsonPropertyName("sessionId")]
public string SessionId { get; set; } = string.Empty;
+ /// Optional user prompt to combine with fleet instructions.
[JsonPropertyName("prompt")]
public string? Prompt { get; set; }
}
+/// RPC data type for Agent operations.
public class Agent
{
- /// Unique identifier of the custom agent
+ /// Unique identifier of the custom agent.
[JsonPropertyName("name")]
public string Name { get; set; } = string.Empty;
- /// Human-readable display name
+ /// Human-readable display name.
[JsonPropertyName("displayName")]
public string DisplayName { get; set; } = string.Empty;
- /// Description of the agent's purpose
+ /// Description of the agent's purpose.
[JsonPropertyName("description")]
public string Description { get; set; } = string.Empty;
}
+/// RPC data type for SessionAgentList operations.
+[Experimental(Diagnostics.Experimental)]
public class SessionAgentListResult
{
- /// Available custom agents
+ /// Available custom agents.
[JsonPropertyName("agents")]
- public List Agents { get; set; } = [];
+ public List Agents { get => field ??= []; set; }
}
+/// RPC data type for SessionAgentList operations.
+[Experimental(Diagnostics.Experimental)]
internal class SessionAgentListRequest
{
+ /// Target session identifier.
[JsonPropertyName("sessionId")]
public string SessionId { get; set; } = string.Empty;
}
+/// RPC data type for SessionAgentGetCurrentResultAgent operations.
public class SessionAgentGetCurrentResultAgent
{
- /// Unique identifier of the custom agent
+ /// Unique identifier of the custom agent.
[JsonPropertyName("name")]
public string Name { get; set; } = string.Empty;
- /// Human-readable display name
+ /// Human-readable display name.
[JsonPropertyName("displayName")]
public string DisplayName { get; set; } = string.Empty;
- /// Description of the agent's purpose
+ /// Description of the agent's purpose.
[JsonPropertyName("description")]
public string Description { get; set; } = string.Empty;
}
+/// RPC data type for SessionAgentGetCurrent operations.
+[Experimental(Diagnostics.Experimental)]
public class SessionAgentGetCurrentResult
{
- /// Currently selected custom agent, or null if using the default agent
+ /// Currently selected custom agent, or null if using the default agent.
[JsonPropertyName("agent")]
public SessionAgentGetCurrentResultAgent? Agent { get; set; }
}
+/// RPC data type for SessionAgentGetCurrent operations.
+[Experimental(Diagnostics.Experimental)]
internal class SessionAgentGetCurrentRequest
{
+ /// Target session identifier.
[JsonPropertyName("sessionId")]
public string SessionId { get; set; } = string.Empty;
}
-/// The newly selected custom agent
+/// The newly selected custom agent.
public class SessionAgentSelectResultAgent
{
- /// Unique identifier of the custom agent
+ /// Unique identifier of the custom agent.
[JsonPropertyName("name")]
public string Name { get; set; } = string.Empty;
- /// Human-readable display name
+ /// Human-readable display name.
[JsonPropertyName("displayName")]
public string DisplayName { get; set; } = string.Empty;
- /// Description of the agent's purpose
+ /// Description of the agent's purpose.
[JsonPropertyName("description")]
public string Description { get; set; } = string.Empty;
}
+/// RPC data type for SessionAgentSelect operations.
+[Experimental(Diagnostics.Experimental)]
public class SessionAgentSelectResult
{
- /// The newly selected custom agent
+ /// The newly selected custom agent.
[JsonPropertyName("agent")]
- public SessionAgentSelectResultAgent Agent { get; set; } = new();
+ public SessionAgentSelectResultAgent Agent { get => field ??= new(); set; }
}
+/// RPC data type for SessionAgentSelect operations.
+[Experimental(Diagnostics.Experimental)]
internal class SessionAgentSelectRequest
{
+ /// Target session identifier.
[JsonPropertyName("sessionId")]
public string SessionId { get; set; } = string.Empty;
+ /// Name of the custom agent to select.
[JsonPropertyName("name")]
public string Name { get; set; } = string.Empty;
}
+/// RPC data type for SessionAgentDeselect operations.
+[Experimental(Diagnostics.Experimental)]
public class SessionAgentDeselectResult
{
}
+/// RPC data type for SessionAgentDeselect operations.
+[Experimental(Diagnostics.Experimental)]
internal class SessionAgentDeselectRequest
{
+ /// Target session identifier.
+ [JsonPropertyName("sessionId")]
+ public string SessionId { get; set; } = string.Empty;
+}
+
+/// RPC data type for SessionAgentReload operations.
+[Experimental(Diagnostics.Experimental)]
+public class SessionAgentReloadResult
+{
+ /// Reloaded custom agents.
+ [JsonPropertyName("agents")]
+ public List Agents { get => field ??= []; set; }
+}
+
+/// RPC data type for SessionAgentReload operations.
+[Experimental(Diagnostics.Experimental)]
+internal class SessionAgentReloadRequest
+{
+ /// Target session identifier.
+ [JsonPropertyName("sessionId")]
+ public string SessionId { get; set; } = string.Empty;
+}
+
+/// RPC data type for Skill operations.
+public class Skill
+{
+ /// Unique identifier for the skill.
+ [JsonPropertyName("name")]
+ public string Name { get; set; } = string.Empty;
+
+ /// Description of what the skill does.
+ [JsonPropertyName("description")]
+ public string Description { get; set; } = string.Empty;
+
+ /// Source location type (e.g., project, personal, plugin).
+ [JsonPropertyName("source")]
+ public string Source { get; set; } = string.Empty;
+
+ /// Whether the skill can be invoked by the user as a slash command.
+ [JsonPropertyName("userInvocable")]
+ public bool UserInvocable { get; set; }
+
+ /// Whether the skill is currently enabled.
+ [JsonPropertyName("enabled")]
+ public bool Enabled { get; set; }
+
+ /// Absolute path to the skill file.
+ [JsonPropertyName("path")]
+ public string? Path { get; set; }
+}
+
+/// RPC data type for SessionSkillsList operations.
+[Experimental(Diagnostics.Experimental)]
+public class SessionSkillsListResult
+{
+ /// Available skills.
+ [JsonPropertyName("skills")]
+ public List Skills { get => field ??= []; set; }
+}
+
+/// RPC data type for SessionSkillsList operations.
+[Experimental(Diagnostics.Experimental)]
+internal class SessionSkillsListRequest
+{
+ /// Target session identifier.
[JsonPropertyName("sessionId")]
public string SessionId { get; set; } = string.Empty;
}
+/// RPC data type for SessionSkillsEnable operations.
+[Experimental(Diagnostics.Experimental)]
+public class SessionSkillsEnableResult
+{
+}
+
+/// RPC data type for SessionSkillsEnable operations.
+[Experimental(Diagnostics.Experimental)]
+internal class SessionSkillsEnableRequest
+{
+ /// Target session identifier.
+ [JsonPropertyName("sessionId")]
+ public string SessionId { get; set; } = string.Empty;
+
+ /// Name of the skill to enable.
+ [JsonPropertyName("name")]
+ public string Name { get; set; } = string.Empty;
+}
+
+/// RPC data type for SessionSkillsDisable operations.
+[Experimental(Diagnostics.Experimental)]
+public class SessionSkillsDisableResult
+{
+}
+
+/// RPC data type for SessionSkillsDisable operations.
+[Experimental(Diagnostics.Experimental)]
+internal class SessionSkillsDisableRequest
+{
+ /// Target session identifier.
+ [JsonPropertyName("sessionId")]
+ public string SessionId { get; set; } = string.Empty;
+
+ /// Name of the skill to disable.
+ [JsonPropertyName("name")]
+ public string Name { get; set; } = string.Empty;
+}
+
+/// RPC data type for SessionSkillsReload operations.
+[Experimental(Diagnostics.Experimental)]
+public class SessionSkillsReloadResult
+{
+}
+
+/// RPC data type for SessionSkillsReload operations.
+[Experimental(Diagnostics.Experimental)]
+internal class SessionSkillsReloadRequest
+{
+ /// Target session identifier.
+ [JsonPropertyName("sessionId")]
+ public string SessionId { get; set; } = string.Empty;
+}
+
+/// RPC data type for Server operations.
+public class Server
+{
+ /// Server name (config key).
+ [JsonPropertyName("name")]
+ public string Name { get; set; } = string.Empty;
+
+ /// Connection status: connected, failed, pending, disabled, or not_configured.
+ [JsonPropertyName("status")]
+ public ServerStatus Status { get; set; }
+
+ /// Configuration source: user, workspace, plugin, or builtin.
+ [JsonPropertyName("source")]
+ public string? Source { get; set; }
+
+ /// Error message if the server failed to connect.
+ [JsonPropertyName("error")]
+ public string? Error { get; set; }
+}
+
+/// RPC data type for SessionMcpList operations.
+[Experimental(Diagnostics.Experimental)]
+public class SessionMcpListResult
+{
+ /// Configured MCP servers.
+ [JsonPropertyName("servers")]
+ public List Servers { get => field ??= []; set; }
+}
+
+/// RPC data type for SessionMcpList operations.
+[Experimental(Diagnostics.Experimental)]
+internal class SessionMcpListRequest
+{
+ /// Target session identifier.
+ [JsonPropertyName("sessionId")]
+ public string SessionId { get; set; } = string.Empty;
+}
+
+/// RPC data type for SessionMcpEnable operations.
+[Experimental(Diagnostics.Experimental)]
+public class SessionMcpEnableResult
+{
+}
+
+/// RPC data type for SessionMcpEnable operations.
+[Experimental(Diagnostics.Experimental)]
+internal class SessionMcpEnableRequest
+{
+ /// Target session identifier.
+ [JsonPropertyName("sessionId")]
+ public string SessionId { get; set; } = string.Empty;
+
+ /// Name of the MCP server to enable.
+ [JsonPropertyName("serverName")]
+ public string ServerName { get; set; } = string.Empty;
+}
+
+/// RPC data type for SessionMcpDisable operations.
+[Experimental(Diagnostics.Experimental)]
+public class SessionMcpDisableResult
+{
+}
+
+/// RPC data type for SessionMcpDisable operations.
+[Experimental(Diagnostics.Experimental)]
+internal class SessionMcpDisableRequest
+{
+ /// Target session identifier.
+ [JsonPropertyName("sessionId")]
+ public string SessionId { get; set; } = string.Empty;
+
+ /// Name of the MCP server to disable.
+ [JsonPropertyName("serverName")]
+ public string ServerName { get; set; } = string.Empty;
+}
+
+/// RPC data type for SessionMcpReload operations.
+[Experimental(Diagnostics.Experimental)]
+public class SessionMcpReloadResult
+{
+}
+
+/// RPC data type for SessionMcpReload operations.
+[Experimental(Diagnostics.Experimental)]
+internal class SessionMcpReloadRequest
+{
+ /// Target session identifier.
+ [JsonPropertyName("sessionId")]
+ public string SessionId { get; set; } = string.Empty;
+}
+
+/// RPC data type for Plugin operations.
+public class Plugin
+{
+ /// Plugin name.
+ [JsonPropertyName("name")]
+ public string Name { get; set; } = string.Empty;
+
+ /// Marketplace the plugin came from.
+ [JsonPropertyName("marketplace")]
+ public string Marketplace { get; set; } = string.Empty;
+
+ /// Installed version.
+ [JsonPropertyName("version")]
+ public string? Version { get; set; }
+
+ /// Whether the plugin is currently enabled.
+ [JsonPropertyName("enabled")]
+ public bool Enabled { get; set; }
+}
+
+/// RPC data type for SessionPluginsList operations.
+[Experimental(Diagnostics.Experimental)]
+public class SessionPluginsListResult
+{
+ /// Installed plugins.
+ [JsonPropertyName("plugins")]
+ public List Plugins { get => field ??= []; set; }
+}
+
+/// RPC data type for SessionPluginsList operations.
+[Experimental(Diagnostics.Experimental)]
+internal class SessionPluginsListRequest
+{
+ /// Target session identifier.
+ [JsonPropertyName("sessionId")]
+ public string SessionId { get; set; } = string.Empty;
+}
+
+/// RPC data type for Extension operations.
+public class Extension
+{
+ /// Source-qualified ID (e.g., 'project:my-ext', 'user:auth-helper').
+ [JsonPropertyName("id")]
+ public string Id { get; set; } = string.Empty;
+
+ /// Extension name (directory name).
+ [JsonPropertyName("name")]
+ public string Name { get; set; } = string.Empty;
+
+ /// Discovery source: project (.github/extensions/) or user (~/.copilot/extensions/).
+ [JsonPropertyName("source")]
+ public ExtensionSource Source { get; set; }
+
+ /// Current status: running, disabled, failed, or starting.
+ [JsonPropertyName("status")]
+ public ExtensionStatus Status { get; set; }
+
+ /// Process ID if the extension is running.
+ [JsonPropertyName("pid")]
+ public double? Pid { get; set; }
+}
+
+/// RPC data type for SessionExtensionsList operations.
+[Experimental(Diagnostics.Experimental)]
+public class SessionExtensionsListResult
+{
+ /// Discovered extensions and their current status.
+ [JsonPropertyName("extensions")]
+ public List Extensions { get => field ??= []; set; }
+}
+
+/// RPC data type for SessionExtensionsList operations.
+[Experimental(Diagnostics.Experimental)]
+internal class SessionExtensionsListRequest
+{
+ /// Target session identifier.
+ [JsonPropertyName("sessionId")]
+ public string SessionId { get; set; } = string.Empty;
+}
+
+/// RPC data type for SessionExtensionsEnable operations.
+[Experimental(Diagnostics.Experimental)]
+public class SessionExtensionsEnableResult
+{
+}
+
+/// RPC data type for SessionExtensionsEnable operations.
+[Experimental(Diagnostics.Experimental)]
+internal class SessionExtensionsEnableRequest
+{
+ /// Target session identifier.
+ [JsonPropertyName("sessionId")]
+ public string SessionId { get; set; } = string.Empty;
+
+ /// Source-qualified extension ID to enable.
+ [JsonPropertyName("id")]
+ public string Id { get; set; } = string.Empty;
+}
+
+/// RPC data type for SessionExtensionsDisable operations.
+[Experimental(Diagnostics.Experimental)]
+public class SessionExtensionsDisableResult
+{
+}
+
+/// RPC data type for SessionExtensionsDisable operations.
+[Experimental(Diagnostics.Experimental)]
+internal class SessionExtensionsDisableRequest
+{
+ /// Target session identifier.
+ [JsonPropertyName("sessionId")]
+ public string SessionId { get; set; } = string.Empty;
+
+ /// Source-qualified extension ID to disable.
+ [JsonPropertyName("id")]
+ public string Id { get; set; } = string.Empty;
+}
+
+/// RPC data type for SessionExtensionsReload operations.
+[Experimental(Diagnostics.Experimental)]
+public class SessionExtensionsReloadResult
+{
+}
+
+/// RPC data type for SessionExtensionsReload operations.
+[Experimental(Diagnostics.Experimental)]
+internal class SessionExtensionsReloadRequest
+{
+ /// Target session identifier.
+ [JsonPropertyName("sessionId")]
+ public string SessionId { get; set; } = string.Empty;
+}
+
+/// RPC data type for SessionCompactionCompact operations.
+[Experimental(Diagnostics.Experimental)]
public class SessionCompactionCompactResult
{
- /// Whether compaction completed successfully
+ /// Whether compaction completed successfully.
[JsonPropertyName("success")]
public bool Success { get; set; }
- /// Number of tokens freed by compaction
+ /// Number of tokens freed by compaction.
[JsonPropertyName("tokensRemoved")]
public double TokensRemoved { get; set; }
- /// Number of messages removed during compaction
+ /// Number of messages removed during compaction.
[JsonPropertyName("messagesRemoved")]
public double MessagesRemoved { get; set; }
}
+/// RPC data type for SessionCompactionCompact operations.
+[Experimental(Diagnostics.Experimental)]
internal class SessionCompactionCompactRequest
{
+ /// Target session identifier.
[JsonPropertyName("sessionId")]
public string SessionId { get; set; } = string.Empty;
}
+/// RPC data type for SessionToolsHandlePendingToolCall operations.
public class SessionToolsHandlePendingToolCallResult
{
+ /// Whether the tool call result was handled successfully.
[JsonPropertyName("success")]
public bool Success { get; set; }
}
+/// RPC data type for SessionToolsHandlePendingToolCall operations.
internal class SessionToolsHandlePendingToolCallRequest
{
+ /// Target session identifier.
[JsonPropertyName("sessionId")]
public string SessionId { get; set; } = string.Empty;
+ /// Gets or sets the requestId value.
[JsonPropertyName("requestId")]
public string RequestId { get; set; } = string.Empty;
+ /// Gets or sets the result value.
[JsonPropertyName("result")]
public object? Result { get; set; }
+ /// Gets or sets the error value.
[JsonPropertyName("error")]
public string? Error { get; set; }
}
+/// RPC data type for SessionCommandsHandlePendingCommand operations.
+public class SessionCommandsHandlePendingCommandResult
+{
+ /// Gets or sets the success value.
+ [JsonPropertyName("success")]
+ public bool Success { get; set; }
+}
+
+/// RPC data type for SessionCommandsHandlePendingCommand operations.
+internal class SessionCommandsHandlePendingCommandRequest
+{
+ /// Target session identifier.
+ [JsonPropertyName("sessionId")]
+ public string SessionId { get; set; } = string.Empty;
+
+ /// Request ID from the command invocation event.
+ [JsonPropertyName("requestId")]
+ public string RequestId { get; set; } = string.Empty;
+
+ /// Error message if the command handler failed.
+ [JsonPropertyName("error")]
+ public string? Error { get; set; }
+}
+
+/// RPC data type for SessionUiElicitation operations.
+public class SessionUiElicitationResult
+{
+ /// The user's response: accept (submitted), decline (rejected), or cancel (dismissed).
+ [JsonPropertyName("action")]
+ public SessionUiElicitationResultAction Action { get; set; }
+
+ /// The form values submitted by the user (present when action is 'accept').
+ [JsonPropertyName("content")]
+ public Dictionary? Content { get; set; }
+}
+
+/// JSON Schema describing the form fields to present to the user.
+public class SessionUiElicitationRequestRequestedSchema
+{
+ /// Schema type indicator (always 'object').
+ [JsonPropertyName("type")]
+ public string Type { get; set; } = string.Empty;
+
+ /// Form field definitions, keyed by field name.
+ [JsonPropertyName("properties")]
+ public Dictionary Properties { get => field ??= []; set; }
+
+ /// List of required field names.
+ [JsonPropertyName("required")]
+ public List? Required { get; set; }
+}
+
+/// RPC data type for SessionUiElicitation operations.
+internal class SessionUiElicitationRequest
+{
+ /// Target session identifier.
+ [JsonPropertyName("sessionId")]
+ public string SessionId { get; set; } = string.Empty;
+
+ /// Message describing what information is needed from the user.
+ [JsonPropertyName("message")]
+ public string Message { get; set; } = string.Empty;
+
+ /// JSON Schema describing the form fields to present to the user.
+ [JsonPropertyName("requestedSchema")]
+ public SessionUiElicitationRequestRequestedSchema RequestedSchema { get => field ??= new(); set; }
+}
+
+/// RPC data type for SessionPermissionsHandlePendingPermissionRequest operations.
public class SessionPermissionsHandlePendingPermissionRequestResult
{
+ /// Whether the permission request was handled successfully.
[JsonPropertyName("success")]
public bool Success { get; set; }
}
+/// RPC data type for SessionPermissionsHandlePendingPermissionRequest operations.
internal class SessionPermissionsHandlePendingPermissionRequestRequest
{
+ /// Target session identifier.
[JsonPropertyName("sessionId")]
public string SessionId { get; set; } = string.Empty;
+ /// Gets or sets the requestId value.
[JsonPropertyName("requestId")]
public string RequestId { get; set; } = string.Empty;
+ /// Gets or sets the result value.
[JsonPropertyName("result")]
public object Result { get; set; } = null!;
}
+/// RPC data type for SessionShellExec operations.
+public class SessionShellExecResult
+{
+ /// Unique identifier for tracking streamed output.
+ [JsonPropertyName("processId")]
+ public string ProcessId { get; set; } = string.Empty;
+}
+
+/// RPC data type for SessionShellExec operations.
+internal class SessionShellExecRequest
+{
+ /// Target session identifier.
+ [JsonPropertyName("sessionId")]
+ public string SessionId { get; set; } = string.Empty;
+
+ /// Shell command to execute.
+ [JsonPropertyName("command")]
+ public string Command { get; set; } = string.Empty;
+
+ /// Working directory (defaults to session working directory).
+ [JsonPropertyName("cwd")]
+ public string? Cwd { get; set; }
+
+ /// Timeout in milliseconds (default: 30000).
+ [JsonPropertyName("timeout")]
+ public double? Timeout { get; set; }
+}
+
+/// RPC data type for SessionShellKill operations.
+public class SessionShellKillResult
+{
+ /// Whether the signal was sent successfully.
+ [JsonPropertyName("killed")]
+ public bool Killed { get; set; }
+}
+
+/// RPC data type for SessionShellKill operations.
+internal class SessionShellKillRequest
+{
+ /// Target session identifier.
+ [JsonPropertyName("sessionId")]
+ public string SessionId { get; set; } = string.Empty;
+
+ /// Process identifier returned by shell.exec.
+ [JsonPropertyName("processId")]
+ public string ProcessId { get; set; } = string.Empty;
+
+ /// Signal to send (default: SIGTERM).
+ [JsonPropertyName("signal")]
+ public SessionShellKillRequestSignal? Signal { get; set; }
+}
+
+/// Log severity level. Determines how the message is displayed in the timeline. Defaults to "info".
+[JsonConverter(typeof(JsonStringEnumConverter))]
+public enum SessionLogRequestLevel
+{
+ /// The info variant.
+ [JsonStringEnumMemberName("info")]
+ Info,
+ /// The warning variant.
+ [JsonStringEnumMemberName("warning")]
+ Warning,
+ /// The error variant.
+ [JsonStringEnumMemberName("error")]
+ Error,
+}
+
+
+/// The current agent mode.
[JsonConverter(typeof(JsonStringEnumConverter))]
public enum SessionModeGetResultMode
{
+ /// The interactive variant.
[JsonStringEnumMemberName("interactive")]
Interactive,
+ /// The plan variant.
[JsonStringEnumMemberName("plan")]
Plan,
+ /// The autopilot variant.
[JsonStringEnumMemberName("autopilot")]
Autopilot,
}
-/// Typed server-scoped RPC methods (no session required).
+/// Connection status: connected, failed, pending, disabled, or not_configured.
+[JsonConverter(typeof(JsonStringEnumConverter))]
+public enum ServerStatus
+{
+ /// The connected variant.
+ [JsonStringEnumMemberName("connected")]
+ Connected,
+ /// The failed variant.
+ [JsonStringEnumMemberName("failed")]
+ Failed,
+ /// The pending variant.
+ [JsonStringEnumMemberName("pending")]
+ Pending,
+ /// The disabled variant.
+ [JsonStringEnumMemberName("disabled")]
+ Disabled,
+ /// The not_configured variant.
+ [JsonStringEnumMemberName("not_configured")]
+ NotConfigured,
+}
+
+
+/// Discovery source: project (.github/extensions/) or user (~/.copilot/extensions/).
+[JsonConverter(typeof(JsonStringEnumConverter))]
+public enum ExtensionSource
+{
+ /// The project variant.
+ [JsonStringEnumMemberName("project")]
+ Project,
+ /// The user variant.
+ [JsonStringEnumMemberName("user")]
+ User,
+}
+
+
+/// Current status: running, disabled, failed, or starting.
+[JsonConverter(typeof(JsonStringEnumConverter))]
+public enum ExtensionStatus
+{
+ /// The running variant.
+ [JsonStringEnumMemberName("running")]
+ Running,
+ /// The disabled variant.
+ [JsonStringEnumMemberName("disabled")]
+ Disabled,
+ /// The failed variant.
+ [JsonStringEnumMemberName("failed")]
+ Failed,
+ /// The starting variant.
+ [JsonStringEnumMemberName("starting")]
+ Starting,
+}
+
+
+/// The user's response: accept (submitted), decline (rejected), or cancel (dismissed).
+[JsonConverter(typeof(JsonStringEnumConverter))]
+public enum SessionUiElicitationResultAction
+{
+ /// The accept variant.
+ [JsonStringEnumMemberName("accept")]
+ Accept,
+ /// The decline variant.
+ [JsonStringEnumMemberName("decline")]
+ Decline,
+ /// The cancel variant.
+ [JsonStringEnumMemberName("cancel")]
+ Cancel,
+}
+
+
+/// Signal to send (default: SIGTERM).
+[JsonConverter(typeof(JsonStringEnumConverter))]
+public enum SessionShellKillRequestSignal
+{
+ /// The SIGTERM variant.
+ [JsonStringEnumMemberName("SIGTERM")]
+ SIGTERM,
+ /// The SIGKILL variant.
+ [JsonStringEnumMemberName("SIGKILL")]
+ SIGKILL,
+ /// The SIGINT variant.
+ [JsonStringEnumMemberName("SIGINT")]
+ SIGINT,
+}
+
+
+/// Provides server-scoped RPC methods (no session required).
public class ServerRpc
{
private readonly JsonRpc _rpc;
@@ -553,7 +1268,7 @@ public async Task PingAsync(string? message = null, CancellationToke
public ServerAccountApi Account { get; }
}
-/// Server-scoped Models APIs.
+/// Provides server-scoped Models APIs.
public class ServerModelsApi
{
private readonly JsonRpc _rpc;
@@ -570,7 +1285,7 @@ public async Task ListAsync(CancellationToken cancellationToke
}
}
-/// Server-scoped Tools APIs.
+/// Provides server-scoped Tools APIs.
public class ServerToolsApi
{
private readonly JsonRpc _rpc;
@@ -588,7 +1303,7 @@ public async Task ListAsync(string? model = null, CancellationT
}
}
-/// Server-scoped Account APIs.
+/// Provides server-scoped Account APIs.
public class ServerAccountApi
{
private readonly JsonRpc _rpc;
@@ -605,7 +1320,7 @@ public async Task GetQuotaAsync(CancellationToken cancell
}
}
-/// Typed session-scoped RPC methods.
+/// Provides typed session-scoped RPC methods.
public class SessionRpc
{
private readonly JsonRpc _rpc;
@@ -621,30 +1336,75 @@ internal SessionRpc(JsonRpc rpc, string sessionId)
Workspace = new WorkspaceApi(rpc, sessionId);
Fleet = new FleetApi(rpc, sessionId);
Agent = new AgentApi(rpc, sessionId);
+ Skills = new SkillsApi(rpc, sessionId);
+ Mcp = new McpApi(rpc, sessionId);
+ Plugins = new PluginsApi(rpc, sessionId);
+ Extensions = new ExtensionsApi(rpc, sessionId);
Compaction = new CompactionApi(rpc, sessionId);
Tools = new ToolsApi(rpc, sessionId);
+ Commands = new CommandsApi(rpc, sessionId);
+ Ui = new UiApi(rpc, sessionId);
Permissions = new PermissionsApi(rpc, sessionId);
+ Shell = new ShellApi(rpc, sessionId);
}
+ /// Model APIs.
public ModelApi Model { get; }
+ /// Mode APIs.
public ModeApi Mode { get; }
+ /// Plan APIs.
public PlanApi Plan { get; }
+ /// Workspace APIs.
public WorkspaceApi Workspace { get; }
+ /// Fleet APIs.
public FleetApi Fleet { get; }
+ /// Agent APIs.
public AgentApi Agent { get; }
+ /// Skills APIs.
+ public SkillsApi Skills { get; }
+
+ /// Mcp APIs.
+ public McpApi Mcp { get; }
+
+ /// Plugins APIs.
+ public PluginsApi Plugins { get; }
+
+ /// Extensions APIs.
+ public ExtensionsApi Extensions { get; }
+
+ /// Compaction APIs.
public CompactionApi Compaction { get; }
+ /// Tools APIs.
public ToolsApi Tools { get; }
+ /// Commands APIs.
+ public CommandsApi Commands { get; }
+
+ /// Ui APIs.
+ public UiApi Ui { get; }
+
+ /// Permissions APIs.
public PermissionsApi Permissions { get; }
+
+ /// Shell APIs.
+ public ShellApi Shell { get; }
+
+ /// Calls "session.log".
+ public async Task LogAsync(string message, SessionLogRequestLevel? level = null, bool? ephemeral = null, string? url = null, CancellationToken cancellationToken = default)
+ {
+ var request = new SessionLogRequest { SessionId = _sessionId, Message = message, Level = level, Ephemeral = ephemeral, Url = url };
+ return await CopilotClient.InvokeRpcAsync(_rpc, "session.log", [request], cancellationToken);
+ }
}
+/// Provides session-scoped Model APIs.
public class ModelApi
{
private readonly JsonRpc _rpc;
@@ -664,13 +1424,14 @@ public async Task GetCurrentAsync(CancellationToke
}
/// Calls "session.model.switchTo".
- public async Task SwitchToAsync(string modelId, CancellationToken cancellationToken = default)
+ public async Task SwitchToAsync(string modelId, string? reasoningEffort = null, CancellationToken cancellationToken = default)
{
- var request = new SessionModelSwitchToRequest { SessionId = _sessionId, ModelId = modelId };
+ var request = new SessionModelSwitchToRequest { SessionId = _sessionId, ModelId = modelId, ReasoningEffort = reasoningEffort };
return await CopilotClient.InvokeRpcAsync(_rpc, "session.model.switchTo", [request], cancellationToken);
}
}
+/// Provides session-scoped Mode APIs.
public class ModeApi
{
private readonly JsonRpc _rpc;
@@ -697,6 +1458,7 @@ public async Task SetAsync(SessionModeGetResultMode mode,
}
}
+/// Provides session-scoped Plan APIs.
public class PlanApi
{
private readonly JsonRpc _rpc;
@@ -730,6 +1492,7 @@ public async Task DeleteAsync(CancellationToken cancell
}
}
+/// Provides session-scoped Workspace APIs.
public class WorkspaceApi
{
private readonly JsonRpc _rpc;
@@ -763,6 +1526,8 @@ public async Task CreateFileAsync(string path,
}
}
+/// Provides session-scoped Fleet APIs.
+[Experimental(Diagnostics.Experimental)]
public class FleetApi
{
private readonly JsonRpc _rpc;
@@ -775,13 +1540,15 @@ internal FleetApi(JsonRpc rpc, string sessionId)
}
/// Calls "session.fleet.start".
- public async Task StartAsync(string? prompt, CancellationToken cancellationToken = default)
+ public async Task StartAsync(string? prompt = null, CancellationToken cancellationToken = default)
{
var request = new SessionFleetStartRequest { SessionId = _sessionId, Prompt = prompt };
return await CopilotClient.InvokeRpcAsync(_rpc, "session.fleet.start", [request], cancellationToken);
}
}
+/// Provides session-scoped Agent APIs.
+[Experimental(Diagnostics.Experimental)]
public class AgentApi
{
private readonly JsonRpc _rpc;
@@ -820,8 +1587,164 @@ public async Task DeselectAsync(CancellationToken ca
var request = new SessionAgentDeselectRequest { SessionId = _sessionId };
return await CopilotClient.InvokeRpcAsync(_rpc, "session.agent.deselect", [request], cancellationToken);
}
+
+ /// Calls "session.agent.reload".
+ public async Task ReloadAsync(CancellationToken cancellationToken = default)
+ {
+ var request = new SessionAgentReloadRequest { SessionId = _sessionId };
+ return await CopilotClient.InvokeRpcAsync(_rpc, "session.agent.reload", [request], cancellationToken);
+ }
+}
+
+/// Provides session-scoped Skills APIs.
+[Experimental(Diagnostics.Experimental)]
+public class SkillsApi
+{
+ private readonly JsonRpc _rpc;
+ private readonly string _sessionId;
+
+ internal SkillsApi(JsonRpc rpc, string sessionId)
+ {
+ _rpc = rpc;
+ _sessionId = sessionId;
+ }
+
+ /// Calls "session.skills.list".
+ public async Task ListAsync(CancellationToken cancellationToken = default)
+ {
+ var request = new SessionSkillsListRequest { SessionId = _sessionId };
+ return await CopilotClient.InvokeRpcAsync(_rpc, "session.skills.list", [request], cancellationToken);
+ }
+
+ /// Calls "session.skills.enable".
+ public async Task EnableAsync(string name, CancellationToken cancellationToken = default)
+ {
+ var request = new SessionSkillsEnableRequest { SessionId = _sessionId, Name = name };
+ return await CopilotClient.InvokeRpcAsync(_rpc, "session.skills.enable", [request], cancellationToken);
+ }
+
+ /// Calls "session.skills.disable".
+ public async Task DisableAsync(string name, CancellationToken cancellationToken = default)
+ {
+ var request = new SessionSkillsDisableRequest { SessionId = _sessionId, Name = name };
+ return await CopilotClient.InvokeRpcAsync(_rpc, "session.skills.disable", [request], cancellationToken);
+ }
+
+ /// Calls "session.skills.reload".
+ public async Task ReloadAsync(CancellationToken cancellationToken = default)
+ {
+ var request = new SessionSkillsReloadRequest { SessionId = _sessionId };
+ return await CopilotClient.InvokeRpcAsync(_rpc, "session.skills.reload", [request], cancellationToken);
+ }
+}
+
+/// Provides session-scoped Mcp APIs.
+[Experimental(Diagnostics.Experimental)]
+public class McpApi
+{
+ private readonly JsonRpc _rpc;
+ private readonly string _sessionId;
+
+ internal McpApi(JsonRpc rpc, string sessionId)
+ {
+ _rpc = rpc;
+ _sessionId = sessionId;
+ }
+
+ /// Calls "session.mcp.list".
+ public async Task ListAsync(CancellationToken cancellationToken = default)
+ {
+ var request = new SessionMcpListRequest { SessionId = _sessionId };
+ return await CopilotClient.InvokeRpcAsync(_rpc, "session.mcp.list", [request], cancellationToken);
+ }
+
+ /// Calls "session.mcp.enable".
+ public async Task EnableAsync(string serverName, CancellationToken cancellationToken = default)
+ {
+ var request = new SessionMcpEnableRequest { SessionId = _sessionId, ServerName = serverName };
+ return await CopilotClient.InvokeRpcAsync(_rpc, "session.mcp.enable", [request], cancellationToken);
+ }
+
+ /// Calls "session.mcp.disable".
+ public async Task DisableAsync(string serverName, CancellationToken cancellationToken = default)
+ {
+ var request = new SessionMcpDisableRequest { SessionId = _sessionId, ServerName = serverName };
+ return await CopilotClient.InvokeRpcAsync(_rpc, "session.mcp.disable", [request], cancellationToken);
+ }
+
+ /// Calls "session.mcp.reload".
+ public async Task ReloadAsync(CancellationToken cancellationToken = default)
+ {
+ var request = new SessionMcpReloadRequest { SessionId = _sessionId };
+ return await CopilotClient.InvokeRpcAsync(_rpc, "session.mcp.reload", [request], cancellationToken);
+ }
}
+/// Provides session-scoped Plugins APIs.
+[Experimental(Diagnostics.Experimental)]
+public class PluginsApi
+{
+ private readonly JsonRpc _rpc;
+ private readonly string _sessionId;
+
+ internal PluginsApi(JsonRpc rpc, string sessionId)
+ {
+ _rpc = rpc;
+ _sessionId = sessionId;
+ }
+
+ /// Calls "session.plugins.list".
+ public async Task ListAsync(CancellationToken cancellationToken = default)
+ {
+ var request = new SessionPluginsListRequest { SessionId = _sessionId };
+ return await CopilotClient.InvokeRpcAsync(_rpc, "session.plugins.list", [request], cancellationToken);
+ }
+}
+
+/// Provides session-scoped Extensions APIs.
+[Experimental(Diagnostics.Experimental)]
+public class ExtensionsApi
+{
+ private readonly JsonRpc _rpc;
+ private readonly string _sessionId;
+
+ internal ExtensionsApi(JsonRpc rpc, string sessionId)
+ {
+ _rpc = rpc;
+ _sessionId = sessionId;
+ }
+
+ /// Calls "session.extensions.list".
+ public async Task ListAsync(CancellationToken cancellationToken = default)
+ {
+ var request = new SessionExtensionsListRequest { SessionId = _sessionId };
+ return await CopilotClient.InvokeRpcAsync(_rpc, "session.extensions.list", [request], cancellationToken);
+ }
+
+ /// Calls "session.extensions.enable".
+ public async Task EnableAsync(string id, CancellationToken cancellationToken = default)
+ {
+ var request = new SessionExtensionsEnableRequest { SessionId = _sessionId, Id = id };
+ return await CopilotClient.InvokeRpcAsync(_rpc, "session.extensions.enable", [request], cancellationToken);
+ }
+
+ /// Calls "session.extensions.disable".
+ public async Task DisableAsync(string id, CancellationToken cancellationToken = default)
+ {
+ var request = new SessionExtensionsDisableRequest { SessionId = _sessionId, Id = id };
+ return await CopilotClient.InvokeRpcAsync(_rpc, "session.extensions.disable", [request], cancellationToken);
+ }
+
+ /// Calls "session.extensions.reload".
+ public async Task ReloadAsync(CancellationToken cancellationToken = default)
+ {
+ var request = new SessionExtensionsReloadRequest { SessionId = _sessionId };
+ return await CopilotClient.InvokeRpcAsync(_rpc, "session.extensions.reload", [request], cancellationToken);
+ }
+}
+
+/// Provides session-scoped Compaction APIs.
+[Experimental(Diagnostics.Experimental)]
public class CompactionApi
{
private readonly JsonRpc _rpc;
@@ -841,6 +1764,7 @@ public async Task CompactAsync(CancellationToken
}
}
+/// Provides session-scoped Tools APIs.
public class ToolsApi
{
private readonly JsonRpc _rpc;
@@ -853,13 +1777,54 @@ internal ToolsApi(JsonRpc rpc, string sessionId)
}
/// Calls "session.tools.handlePendingToolCall".
- public async Task HandlePendingToolCallAsync(string requestId, object? result, string? error, CancellationToken cancellationToken = default)
+ public async Task HandlePendingToolCallAsync(string requestId, object? result = null, string? error = null, CancellationToken cancellationToken = default)
{
var request = new SessionToolsHandlePendingToolCallRequest { SessionId = _sessionId, RequestId = requestId, Result = result, Error = error };
return await CopilotClient.InvokeRpcAsync(_rpc, "session.tools.handlePendingToolCall", [request], cancellationToken);
}
}
+/// Provides session-scoped Commands APIs.
+public class CommandsApi
+{
+ private readonly JsonRpc _rpc;
+ private readonly string _sessionId;
+
+ internal CommandsApi(JsonRpc rpc, string sessionId)
+ {
+ _rpc = rpc;
+ _sessionId = sessionId;
+ }
+
+ /// Calls "session.commands.handlePendingCommand".
+ public async Task HandlePendingCommandAsync(string requestId, string? error = null, CancellationToken cancellationToken = default)
+ {
+ var request = new SessionCommandsHandlePendingCommandRequest { SessionId = _sessionId, RequestId = requestId, Error = error };
+ return await CopilotClient.InvokeRpcAsync(_rpc, "session.commands.handlePendingCommand", [request], cancellationToken);
+ }
+}
+
+/// Provides session-scoped Ui APIs.
+public class UiApi
+{
+ private readonly JsonRpc _rpc;
+ private readonly string _sessionId;
+
+ internal UiApi(JsonRpc rpc, string sessionId)
+ {
+ _rpc = rpc;
+ _sessionId = sessionId;
+ }
+
+ /// Calls "session.ui.elicitation".
+ public async Task ElicitationAsync(string message, SessionUiElicitationRequestRequestedSchema requestedSchema, CancellationToken cancellationToken = default)
+ {
+ var request = new SessionUiElicitationRequest { SessionId = _sessionId, Message = message, RequestedSchema = requestedSchema };
+ return await CopilotClient.InvokeRpcAsync(_rpc, "session.ui.elicitation", [request], cancellationToken);
+ }
+}
+
+/// Provides session-scoped Permissions APIs.
public class PermissionsApi
{
private readonly JsonRpc _rpc;
@@ -879,6 +1844,33 @@ public async Task Handle
}
}
+/// Provides session-scoped Shell APIs.
+public class ShellApi
+{
+ private readonly JsonRpc _rpc;
+ private readonly string _sessionId;
+
+ internal ShellApi(JsonRpc rpc, string sessionId)
+ {
+ _rpc = rpc;
+ _sessionId = sessionId;
+ }
+
+ /// Calls "session.shell.exec".
+ public async Task ExecAsync(string command, string? cwd = null, double? timeout = null, CancellationToken cancellationToken = default)
+ {
+ var request = new SessionShellExecRequest { SessionId = _sessionId, Command = command, Cwd = cwd, Timeout = timeout };
+ return await CopilotClient.InvokeRpcAsync(_rpc, "session.shell.exec", [request], cancellationToken);
+ }
+
+ /// Calls "session.shell.kill".
+ public async Task KillAsync(string processId, SessionShellKillRequestSignal? signal = null, CancellationToken cancellationToken = default)
+ {
+ var request = new SessionShellKillRequest { SessionId = _sessionId, ProcessId = processId, Signal = signal };
+ return await CopilotClient.InvokeRpcAsync(_rpc, "session.shell.kill", [request], cancellationToken);
+ }
+}
+
[JsonSourceGenerationOptions(
JsonSerializerDefaults.Web,
AllowOutOfOrderMetadataProperties = true,
@@ -886,6 +1878,7 @@ public async Task Handle
[JsonSerializable(typeof(AccountGetQuotaResult))]
[JsonSerializable(typeof(AccountGetQuotaResultQuotaSnapshotsValue))]
[JsonSerializable(typeof(Agent))]
+[JsonSerializable(typeof(Extension))]
[JsonSerializable(typeof(Model))]
[JsonSerializable(typeof(ModelBilling))]
[JsonSerializable(typeof(ModelCapabilities))]
@@ -895,6 +1888,8 @@ public async Task Handle
[JsonSerializable(typeof(ModelsListResult))]
[JsonSerializable(typeof(PingRequest))]
[JsonSerializable(typeof(PingResult))]
+[JsonSerializable(typeof(Plugin))]
+[JsonSerializable(typeof(Server))]
[JsonSerializable(typeof(SessionAgentDeselectRequest))]
[JsonSerializable(typeof(SessionAgentDeselectResult))]
[JsonSerializable(typeof(SessionAgentGetCurrentRequest))]
@@ -902,13 +1897,35 @@ public async Task Handle
[JsonSerializable(typeof(SessionAgentGetCurrentResultAgent))]
[JsonSerializable(typeof(SessionAgentListRequest))]
[JsonSerializable(typeof(SessionAgentListResult))]
+[JsonSerializable(typeof(SessionAgentReloadRequest))]
+[JsonSerializable(typeof(SessionAgentReloadResult))]
[JsonSerializable(typeof(SessionAgentSelectRequest))]
[JsonSerializable(typeof(SessionAgentSelectResult))]
[JsonSerializable(typeof(SessionAgentSelectResultAgent))]
+[JsonSerializable(typeof(SessionCommandsHandlePendingCommandRequest))]
+[JsonSerializable(typeof(SessionCommandsHandlePendingCommandResult))]
[JsonSerializable(typeof(SessionCompactionCompactRequest))]
[JsonSerializable(typeof(SessionCompactionCompactResult))]
+[JsonSerializable(typeof(SessionExtensionsDisableRequest))]
+[JsonSerializable(typeof(SessionExtensionsDisableResult))]
+[JsonSerializable(typeof(SessionExtensionsEnableRequest))]
+[JsonSerializable(typeof(SessionExtensionsEnableResult))]
+[JsonSerializable(typeof(SessionExtensionsListRequest))]
+[JsonSerializable(typeof(SessionExtensionsListResult))]
+[JsonSerializable(typeof(SessionExtensionsReloadRequest))]
+[JsonSerializable(typeof(SessionExtensionsReloadResult))]
[JsonSerializable(typeof(SessionFleetStartRequest))]
[JsonSerializable(typeof(SessionFleetStartResult))]
+[JsonSerializable(typeof(SessionLogRequest))]
+[JsonSerializable(typeof(SessionLogResult))]
+[JsonSerializable(typeof(SessionMcpDisableRequest))]
+[JsonSerializable(typeof(SessionMcpDisableResult))]
+[JsonSerializable(typeof(SessionMcpEnableRequest))]
+[JsonSerializable(typeof(SessionMcpEnableResult))]
+[JsonSerializable(typeof(SessionMcpListRequest))]
+[JsonSerializable(typeof(SessionMcpListResult))]
+[JsonSerializable(typeof(SessionMcpReloadRequest))]
+[JsonSerializable(typeof(SessionMcpReloadResult))]
[JsonSerializable(typeof(SessionModeGetRequest))]
[JsonSerializable(typeof(SessionModeGetResult))]
[JsonSerializable(typeof(SessionModeSetRequest))]
@@ -925,14 +1942,32 @@ public async Task Handle
[JsonSerializable(typeof(SessionPlanReadResult))]
[JsonSerializable(typeof(SessionPlanUpdateRequest))]
[JsonSerializable(typeof(SessionPlanUpdateResult))]
+[JsonSerializable(typeof(SessionPluginsListRequest))]
+[JsonSerializable(typeof(SessionPluginsListResult))]
+[JsonSerializable(typeof(SessionShellExecRequest))]
+[JsonSerializable(typeof(SessionShellExecResult))]
+[JsonSerializable(typeof(SessionShellKillRequest))]
+[JsonSerializable(typeof(SessionShellKillResult))]
+[JsonSerializable(typeof(SessionSkillsDisableRequest))]
+[JsonSerializable(typeof(SessionSkillsDisableResult))]
+[JsonSerializable(typeof(SessionSkillsEnableRequest))]
+[JsonSerializable(typeof(SessionSkillsEnableResult))]
+[JsonSerializable(typeof(SessionSkillsListRequest))]
+[JsonSerializable(typeof(SessionSkillsListResult))]
+[JsonSerializable(typeof(SessionSkillsReloadRequest))]
+[JsonSerializable(typeof(SessionSkillsReloadResult))]
[JsonSerializable(typeof(SessionToolsHandlePendingToolCallRequest))]
[JsonSerializable(typeof(SessionToolsHandlePendingToolCallResult))]
+[JsonSerializable(typeof(SessionUiElicitationRequest))]
+[JsonSerializable(typeof(SessionUiElicitationRequestRequestedSchema))]
+[JsonSerializable(typeof(SessionUiElicitationResult))]
[JsonSerializable(typeof(SessionWorkspaceCreateFileRequest))]
[JsonSerializable(typeof(SessionWorkspaceCreateFileResult))]
[JsonSerializable(typeof(SessionWorkspaceListFilesRequest))]
[JsonSerializable(typeof(SessionWorkspaceListFilesResult))]
[JsonSerializable(typeof(SessionWorkspaceReadFileRequest))]
[JsonSerializable(typeof(SessionWorkspaceReadFileResult))]
+[JsonSerializable(typeof(Skill))]
[JsonSerializable(typeof(Tool))]
[JsonSerializable(typeof(ToolsListRequest))]
[JsonSerializable(typeof(ToolsListResult))]
diff --git a/dotnet/src/Generated/SessionEvents.cs b/dotnet/src/Generated/SessionEvents.cs
index c497038c6a..d5ef13d530 100644
--- a/dotnet/src/Generated/SessionEvents.cs
+++ b/dotnet/src/Generated/SessionEvents.cs
@@ -5,20 +5,19 @@
// AUTO-GENERATED FILE - DO NOT EDIT
// Generated from: session-events.schema.json
-// Generated code does not have XML doc comments; suppress CS1591 to avoid warnings.
-#pragma warning disable CS1591
-
+using System.Diagnostics;
using System.Text.Json;
using System.Text.Json.Serialization;
namespace GitHub.Copilot.SDK;
///
-/// Base class for all session events with polymorphic JSON serialization.
+/// Provides the base class from which all session events derive.
///
+[DebuggerDisplay("{DebuggerDisplay,nq}")]
[JsonPolymorphic(
TypeDiscriminatorPropertyName = "type",
- UnknownDerivedTypeHandling = JsonUnknownDerivedTypeHandling.FailSerialization)]
+ IgnoreUnrecognizedTypeDiscriminators = true)]
[JsonDerivedType(typeof(AbortEvent), "abort")]
[JsonDerivedType(typeof(AssistantIntentEvent), "assistant.intent")]
[JsonDerivedType(typeof(AssistantMessageEvent), "assistant.message")]
@@ -30,7 +29,9 @@ namespace GitHub.Copilot.SDK;
[JsonDerivedType(typeof(AssistantTurnStartEvent), "assistant.turn_start")]
[JsonDerivedType(typeof(AssistantUsageEvent), "assistant.usage")]
[JsonDerivedType(typeof(CommandCompletedEvent), "command.completed")]
+[JsonDerivedType(typeof(CommandExecuteEvent), "command.execute")]
[JsonDerivedType(typeof(CommandQueuedEvent), "command.queued")]
+[JsonDerivedType(typeof(CommandsChangedEvent), "commands.changed")]
[JsonDerivedType(typeof(ElicitationCompletedEvent), "elicitation.completed")]
[JsonDerivedType(typeof(ElicitationRequestedEvent), "elicitation.requested")]
[JsonDerivedType(typeof(ExitPlanModeCompletedEvent), "exit_plan_mode.completed")]
@@ -39,25 +40,33 @@ namespace GitHub.Copilot.SDK;
[JsonDerivedType(typeof(ExternalToolRequestedEvent), "external_tool.requested")]
[JsonDerivedType(typeof(HookEndEvent), "hook.end")]
[JsonDerivedType(typeof(HookStartEvent), "hook.start")]
+[JsonDerivedType(typeof(McpOauthCompletedEvent), "mcp.oauth_completed")]
+[JsonDerivedType(typeof(McpOauthRequiredEvent), "mcp.oauth_required")]
[JsonDerivedType(typeof(PendingMessagesModifiedEvent), "pending_messages.modified")]
[JsonDerivedType(typeof(PermissionCompletedEvent), "permission.completed")]
[JsonDerivedType(typeof(PermissionRequestedEvent), "permission.requested")]
+[JsonDerivedType(typeof(SessionBackgroundTasksChangedEvent), "session.background_tasks_changed")]
[JsonDerivedType(typeof(SessionCompactionCompleteEvent), "session.compaction_complete")]
[JsonDerivedType(typeof(SessionCompactionStartEvent), "session.compaction_start")]
[JsonDerivedType(typeof(SessionContextChangedEvent), "session.context_changed")]
[JsonDerivedType(typeof(SessionErrorEvent), "session.error")]
+[JsonDerivedType(typeof(SessionExtensionsLoadedEvent), "session.extensions_loaded")]
[JsonDerivedType(typeof(SessionHandoffEvent), "session.handoff")]
[JsonDerivedType(typeof(SessionIdleEvent), "session.idle")]
[JsonDerivedType(typeof(SessionInfoEvent), "session.info")]
+[JsonDerivedType(typeof(SessionMcpServerStatusChangedEvent), "session.mcp_server_status_changed")]
+[JsonDerivedType(typeof(SessionMcpServersLoadedEvent), "session.mcp_servers_loaded")]
[JsonDerivedType(typeof(SessionModeChangedEvent), "session.mode_changed")]
[JsonDerivedType(typeof(SessionModelChangeEvent), "session.model_change")]
[JsonDerivedType(typeof(SessionPlanChangedEvent), "session.plan_changed")]
[JsonDerivedType(typeof(SessionResumeEvent), "session.resume")]
[JsonDerivedType(typeof(SessionShutdownEvent), "session.shutdown")]
+[JsonDerivedType(typeof(SessionSkillsLoadedEvent), "session.skills_loaded")]
[JsonDerivedType(typeof(SessionSnapshotRewindEvent), "session.snapshot_rewind")]
[JsonDerivedType(typeof(SessionStartEvent), "session.start")]
[JsonDerivedType(typeof(SessionTaskCompleteEvent), "session.task_complete")]
[JsonDerivedType(typeof(SessionTitleChangedEvent), "session.title_changed")]
+[JsonDerivedType(typeof(SessionToolsUpdatedEvent), "session.tools_updated")]
[JsonDerivedType(typeof(SessionTruncationEvent), "session.truncation")]
[JsonDerivedType(typeof(SessionUsageInfoEvent), "session.usage_info")]
[JsonDerivedType(typeof(SessionWarningEvent), "session.warning")]
@@ -69,6 +78,7 @@ namespace GitHub.Copilot.SDK;
[JsonDerivedType(typeof(SubagentSelectedEvent), "subagent.selected")]
[JsonDerivedType(typeof(SubagentStartedEvent), "subagent.started")]
[JsonDerivedType(typeof(SystemMessageEvent), "system.message")]
+[JsonDerivedType(typeof(SystemNotificationEvent), "system.notification")]
[JsonDerivedType(typeof(ToolExecutionCompleteEvent), "tool.execution_complete")]
[JsonDerivedType(typeof(ToolExecutionPartialResultEvent), "tool.execution_partial_result")]
[JsonDerivedType(typeof(ToolExecutionProgressEvent), "tool.execution_progress")]
@@ -77,17 +87,21 @@ namespace GitHub.Copilot.SDK;
[JsonDerivedType(typeof(UserInputCompletedEvent), "user_input.completed")]
[JsonDerivedType(typeof(UserInputRequestedEvent), "user_input.requested")]
[JsonDerivedType(typeof(UserMessageEvent), "user.message")]
-public abstract partial class SessionEvent
+public partial class SessionEvent
{
+ /// Unique event identifier (UUID v4), generated when the event is emitted.
[JsonPropertyName("id")]
public Guid Id { get; set; }
+ /// ISO 8601 timestamp when the event was created.
[JsonPropertyName("timestamp")]
public DateTimeOffset Timestamp { get; set; }
+ /// ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
[JsonPropertyName("parentId")]
public Guid? ParentId { get; set; }
+ /// When true, the event is transient and not persisted to the session event log on disk.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("ephemeral")]
public bool? Ephemeral { get; set; }
@@ -96,1780 +110,2655 @@ public abstract partial class SessionEvent
/// The event type discriminator.
///
[JsonIgnore]
- public abstract string Type { get; }
+ public virtual string Type => "unknown";
+ /// Deserializes a JSON string into a .
public static SessionEvent FromJson(string json) =>
JsonSerializer.Deserialize(json, SessionEventsJsonContext.Default.SessionEvent)!;
+ /// Serializes this event to a JSON string.
public string ToJson() =>
JsonSerializer.Serialize(this, SessionEventsJsonContext.Default.SessionEvent);
+
+ [DebuggerBrowsable(DebuggerBrowsableState.Never)]
+ private string DebuggerDisplay => ToJson();
}
-///
-/// Event: session.start
-///
+/// Session initialization metadata including context and configuration.
+/// Represents the session.start event.
public partial class SessionStartEvent : SessionEvent
{
+ ///
[JsonIgnore]
public override string Type => "session.start";
+ /// The session.start event payload.
[JsonPropertyName("data")]
public required SessionStartData Data { get; set; }
}
-///
-/// Event: session.resume
-///
+/// Session resume metadata including current context and event count.
+/// Represents the session.resume event.
public partial class SessionResumeEvent : SessionEvent
{
+ ///
[JsonIgnore]
public override string Type => "session.resume";
+ /// The session.resume event payload.
[JsonPropertyName("data")]
public required SessionResumeData Data { get; set; }
}
-///
-/// Event: session.error
-///
+/// Error details for timeline display including message and optional diagnostic information.
+/// Represents the session.error event.
public partial class SessionErrorEvent : SessionEvent
{
+ ///
[JsonIgnore]
public override string Type => "session.error";
+ /// The session.error event payload.
[JsonPropertyName("data")]
public required SessionErrorData Data { get; set; }
}
-///
-/// Event: session.idle
-///
+/// Payload indicating the agent is idle; includes any background tasks still in flight.
+/// Represents the session.idle event.
public partial class SessionIdleEvent : SessionEvent
{
+ ///
[JsonIgnore]
public override string Type => "session.idle";
+ /// The session.idle event payload.
[JsonPropertyName("data")]
public required SessionIdleData Data { get; set; }
}
-///
-/// Event: session.title_changed
-///
+/// Session title change payload containing the new display title.
+/// Represents the session.title_changed event.
public partial class SessionTitleChangedEvent : SessionEvent
{
+ ///
[JsonIgnore]
public override string Type => "session.title_changed";
+ /// The session.title_changed event payload.
[JsonPropertyName("data")]
public required SessionTitleChangedData Data { get; set; }
}
-///
-/// Event: session.info
-///
+/// Informational message for timeline display with categorization.
+/// Represents the session.info event.
public partial class SessionInfoEvent : SessionEvent
{
+ ///
[JsonIgnore]
public override string Type => "session.info";
+ /// The session.info event payload.
[JsonPropertyName("data")]
public required SessionInfoData Data { get; set; }
}
-///
-/// Event: session.warning
-///
+/// Warning message for timeline display with categorization.
+/// Represents the session.warning event.
public partial class SessionWarningEvent : SessionEvent
{
+ ///
[JsonIgnore]
public override string Type => "session.warning";
+ /// The session.warning event payload.
[JsonPropertyName("data")]
public required SessionWarningData Data { get; set; }
}
-///
-/// Event: session.model_change
-///
+/// Model change details including previous and new model identifiers.
+/// Represents the session.model_change event.
public partial class SessionModelChangeEvent : SessionEvent
{
+ ///
[JsonIgnore]
public override string Type => "session.model_change";
+ /// The session.model_change event payload.
[JsonPropertyName("data")]
public required SessionModelChangeData Data { get; set; }
}
-///
-/// Event: session.mode_changed
-///
+/// Agent mode change details including previous and new modes.
+/// Represents the session.mode_changed event.
public partial class SessionModeChangedEvent : SessionEvent
{
+ ///
[JsonIgnore]
public override string Type => "session.mode_changed";
+ /// The session.mode_changed event payload.
[JsonPropertyName("data")]
public required SessionModeChangedData Data { get; set; }
}
-///
-/// Event: session.plan_changed
-///
+/// Plan file operation details indicating what changed.
+/// Represents the session.plan_changed event.
public partial class SessionPlanChangedEvent : SessionEvent
{
+ ///
[JsonIgnore]
public override string Type => "session.plan_changed";
+ /// The session.plan_changed event payload.
[JsonPropertyName("data")]
public required SessionPlanChangedData Data { get; set; }
}
-///
-/// Event: session.workspace_file_changed
-///
+/// Workspace file change details including path and operation type.
+/// Represents the session.workspace_file_changed event.
public partial class SessionWorkspaceFileChangedEvent : SessionEvent
{
+ ///
[JsonIgnore]
public override string Type => "session.workspace_file_changed";
+ /// The session.workspace_file_changed event payload.
[JsonPropertyName("data")]
public required SessionWorkspaceFileChangedData Data { get; set; }
}
-///
-/// Event: session.handoff
-///
+/// Session handoff metadata including source, context, and repository information.
+/// Represents the session.handoff event.
public partial class SessionHandoffEvent : SessionEvent
{
+ ///
[JsonIgnore]
public override string Type => "session.handoff";
+ /// The session.handoff event payload.
[JsonPropertyName("data")]
public required SessionHandoffData Data { get; set; }
}
-///
-/// Event: session.truncation
-///
+/// Conversation truncation statistics including token counts and removed content metrics.
+/// Represents the session.truncation event.
public partial class SessionTruncationEvent : SessionEvent
{
+ ///
[JsonIgnore]
public override string Type => "session.truncation";
+ /// The session.truncation event payload.
[JsonPropertyName("data")]
public required SessionTruncationData Data { get; set; }
}
-///
-/// Event: session.snapshot_rewind
-///
+/// Session rewind details including target event and count of removed events.
+/// Represents the session.snapshot_rewind event.
public partial class SessionSnapshotRewindEvent : SessionEvent
{
+ ///
[JsonIgnore]
public override string Type => "session.snapshot_rewind";
+ /// The session.snapshot_rewind event payload.
[JsonPropertyName("data")]
public required SessionSnapshotRewindData Data { get; set; }
}
-///
-/// Event: session.shutdown
-///
+/// Session termination metrics including usage statistics, code changes, and shutdown reason.
+/// Represents the session.shutdown event.
public partial class SessionShutdownEvent : SessionEvent
{
+ ///
[JsonIgnore]
public override string Type => "session.shutdown";
+ /// The session.shutdown event payload.
[JsonPropertyName("data")]
public required SessionShutdownData Data { get; set; }
}
-///
-/// Event: session.context_changed
-///
+/// Updated working directory and git context after the change.
+/// Represents the session.context_changed event.
public partial class SessionContextChangedEvent : SessionEvent
{
+ ///
[JsonIgnore]
public override string Type => "session.context_changed";
+ /// The session.context_changed event payload.
[JsonPropertyName("data")]
public required SessionContextChangedData Data { get; set; }
}
-///
-/// Event: session.usage_info
-///
+/// Current context window usage statistics including token and message counts.
+/// Represents the session.usage_info event.
public partial class SessionUsageInfoEvent : SessionEvent
{
+ ///
[JsonIgnore]
public override string Type => "session.usage_info";
+ /// The session.usage_info event payload.
[JsonPropertyName("data")]
public required SessionUsageInfoData Data { get; set; }
}
-///
-/// Event: session.compaction_start
-///
+/// Context window breakdown at the start of LLM-powered conversation compaction.
+/// Represents the session.compaction_start event.
public partial class SessionCompactionStartEvent : SessionEvent
{
+ ///
[JsonIgnore]
public override string Type => "session.compaction_start";
+ /// The session.compaction_start event payload.
[JsonPropertyName("data")]
public required SessionCompactionStartData Data { get; set; }
}
-///
-/// Event: session.compaction_complete
-///
+/// Conversation compaction results including success status, metrics, and optional error details.
+/// Represents the session.compaction_complete event.
public partial class SessionCompactionCompleteEvent : SessionEvent
{
+ ///
[JsonIgnore]
public override string Type => "session.compaction_complete";
+ /// The session.compaction_complete event payload.
[JsonPropertyName("data")]
public required SessionCompactionCompleteData Data { get; set; }
}
-///
-/// Event: session.task_complete
-///
+/// Task completion notification with summary from the agent.
+/// Represents the session.task_complete event.
public partial class SessionTaskCompleteEvent : SessionEvent
{
+ ///
[JsonIgnore]
public override string Type => "session.task_complete";
+ /// The session.task_complete event payload.
[JsonPropertyName("data")]
public required SessionTaskCompleteData Data { get; set; }
}
-///
-/// Event: user.message
-///
+/// Represents the user.message event.
public partial class UserMessageEvent : SessionEvent
{
+ ///
[JsonIgnore]
public override string Type => "user.message";
+ /// The user.message event payload.
[JsonPropertyName("data")]
public required UserMessageData Data { get; set; }
}
-///
-/// Event: pending_messages.modified
-///
+/// Empty payload; the event signals that the pending message queue has changed.
+/// Represents the pending_messages.modified event.
public partial class PendingMessagesModifiedEvent : SessionEvent
{
+ ///
[JsonIgnore]
public override string Type => "pending_messages.modified";
+ /// The pending_messages.modified event payload.
[JsonPropertyName("data")]
public required PendingMessagesModifiedData Data { get; set; }
}
-///
-/// Event: assistant.turn_start
-///
+/// Turn initialization metadata including identifier and interaction tracking.
+/// Represents the assistant.turn_start event.
public partial class AssistantTurnStartEvent : SessionEvent
{
+ ///
[JsonIgnore]
public override string Type => "assistant.turn_start";
+ /// The assistant.turn_start event payload.
[JsonPropertyName("data")]
public required AssistantTurnStartData Data { get; set; }
}
-///
-/// Event: assistant.intent
-///
+/// Agent intent description for current activity or plan.
+/// Represents the assistant.intent event.
public partial class AssistantIntentEvent : SessionEvent
{
+ ///
[JsonIgnore]
public override string Type => "assistant.intent";
+ /// The assistant.intent event payload.
[JsonPropertyName("data")]
public required AssistantIntentData Data { get; set; }
}
-///
-/// Event: assistant.reasoning
-///
+/// Assistant reasoning content for timeline display with complete thinking text.
+/// Represents the assistant.reasoning event.
public partial class AssistantReasoningEvent : SessionEvent
{
+ ///
[JsonIgnore]
public override string Type => "assistant.reasoning";
+ /// The assistant.reasoning event payload.
[JsonPropertyName("data")]
public required AssistantReasoningData Data { get; set; }
}
-///
-/// Event: assistant.reasoning_delta
-///
+/// Streaming reasoning delta for incremental extended thinking updates.
+/// Represents the assistant.reasoning_delta event.
public partial class AssistantReasoningDeltaEvent : SessionEvent
{
+ ///
[JsonIgnore]
public override string Type => "assistant.reasoning_delta";
+ /// The assistant.reasoning_delta event payload.
[JsonPropertyName("data")]
public required AssistantReasoningDeltaData Data { get; set; }
}
-///
-/// Event: assistant.streaming_delta
-///
+/// Streaming response progress with cumulative byte count.
+/// Represents the assistant.streaming_delta event.
public partial class AssistantStreamingDeltaEvent : SessionEvent
{
+ ///
[JsonIgnore]
public override string Type => "assistant.streaming_delta";
+ /// The assistant.streaming_delta event payload.
[JsonPropertyName("data")]
public required AssistantStreamingDeltaData Data { get; set; }
}
-///
-/// Event: assistant.message
-///
+/// Assistant response containing text content, optional tool requests, and interaction metadata.
+/// Represents the assistant.message event.
public partial class AssistantMessageEvent : SessionEvent
{
+ ///
[JsonIgnore]
public override string Type => "assistant.message";
+ /// The assistant.message event payload.
[JsonPropertyName("data")]
public required AssistantMessageData Data { get; set; }
}
-///
-/// Event: assistant.message_delta
-///
+/// Streaming assistant message delta for incremental response updates.
+/// Represents the assistant.message_delta event.
public partial class AssistantMessageDeltaEvent : SessionEvent
{
+ ///
[JsonIgnore]
public override string Type => "assistant.message_delta";
+ /// The assistant.message_delta event payload.
[JsonPropertyName("data")]
public required AssistantMessageDeltaData Data { get; set; }
}
-///
-/// Event: assistant.turn_end
-///
+/// Turn completion metadata including the turn identifier.
+/// Represents the assistant.turn_end event.
public partial class AssistantTurnEndEvent : SessionEvent
{
+ ///
[JsonIgnore]
public override string Type => "assistant.turn_end";
+ /// The assistant.turn_end event payload.
[JsonPropertyName("data")]
public required AssistantTurnEndData Data { get; set; }
}
-///
-/// Event: assistant.usage
-///
+/// LLM API call usage metrics including tokens, costs, quotas, and billing information.
+/// Represents the assistant.usage event.
public partial class AssistantUsageEvent : SessionEvent
{
+ ///
[JsonIgnore]
public override string Type => "assistant.usage";
+ /// The assistant.usage event payload.
[JsonPropertyName("data")]
public required AssistantUsageData Data { get; set; }
}
-///
-/// Event: abort
-///
+/// Turn abort information including the reason for termination.
+/// Represents the abort event.
public partial class AbortEvent : SessionEvent
{
+ ///
[JsonIgnore]
public override string Type => "abort";
+ /// The abort event payload.
[JsonPropertyName("data")]
public required AbortData Data { get; set; }
}
-///
-/// Event: tool.user_requested
-///
+/// User-initiated tool invocation request with tool name and arguments.
+/// Represents the tool.user_requested event.
public partial class ToolUserRequestedEvent : SessionEvent
{
+ ///
[JsonIgnore]
public override string Type => "tool.user_requested";
+ /// The tool.user_requested event payload.
[JsonPropertyName("data")]
public required ToolUserRequestedData Data { get; set; }
}
-///
-/// Event: tool.execution_start
-///
+/// Tool execution startup details including MCP server information when applicable.
+/// Represents the tool.execution_start event.
public partial class ToolExecutionStartEvent : SessionEvent
{
+ ///
[JsonIgnore]
public override string Type => "tool.execution_start";
+ /// The tool.execution_start event payload.
[JsonPropertyName("data")]
public required ToolExecutionStartData Data { get; set; }
}
-///
-/// Event: tool.execution_partial_result
-///
+/// Streaming tool execution output for incremental result display.
+/// Represents the tool.execution_partial_result event.
public partial class ToolExecutionPartialResultEvent : SessionEvent
{
+ ///
[JsonIgnore]
public override string Type => "tool.execution_partial_result";
+ /// The tool.execution_partial_result event payload.
[JsonPropertyName("data")]
public required ToolExecutionPartialResultData Data { get; set; }
}
-///
-/// Event: tool.execution_progress
-///
+/// Tool execution progress notification with status message.
+/// Represents the tool.execution_progress event.
public partial class ToolExecutionProgressEvent : SessionEvent
{
+ ///
[JsonIgnore]
public override string Type => "tool.execution_progress";
+ /// The tool.execution_progress event payload.
[JsonPropertyName("data")]
public required ToolExecutionProgressData Data { get; set; }
}
-///
-/// Event: tool.execution_complete
-///
+/// Tool execution completion results including success status, detailed output, and error information.
+/// Represents the tool.execution_complete event.
public partial class ToolExecutionCompleteEvent : SessionEvent
{
+ ///
[JsonIgnore]
public override string Type => "tool.execution_complete";
+ /// The tool.execution_complete event payload.
[JsonPropertyName("data")]
public required ToolExecutionCompleteData Data { get; set; }
}
-///
-/// Event: skill.invoked
-///
+/// Skill invocation details including content, allowed tools, and plugin metadata.
+/// Represents the skill.invoked event.
public partial class SkillInvokedEvent : SessionEvent
{
+ ///
[JsonIgnore]
public override string Type => "skill.invoked";
+ /// The skill.invoked event payload.
[JsonPropertyName("data")]
public required SkillInvokedData Data { get; set; }
}
-///
-/// Event: subagent.started
-///
+/// Sub-agent startup details including parent tool call and agent information.
+/// Represents the subagent.started event.
public partial class SubagentStartedEvent : SessionEvent
{
+ ///
[JsonIgnore]
public override string Type => "subagent.started";
+ /// The subagent.started event payload.
[JsonPropertyName("data")]
public required SubagentStartedData Data { get; set; }
}
-///
-/// Event: subagent.completed
-///
+/// Sub-agent completion details for successful execution.
+/// Represents the subagent.completed event.
public partial class SubagentCompletedEvent : SessionEvent
{
+ ///
[JsonIgnore]
public override string Type => "subagent.completed";
+ /// The subagent.completed event payload.
[JsonPropertyName("data")]
public required SubagentCompletedData Data { get; set; }
}
-///
-/// Event: subagent.failed
-///
+/// Sub-agent failure details including error message and agent information.
+/// Represents the subagent.failed event.
public partial class SubagentFailedEvent : SessionEvent
{
+ ///
[JsonIgnore]
public override string Type => "subagent.failed";
+ /// The subagent.failed event payload.
[JsonPropertyName("data")]
public required SubagentFailedData Data { get; set; }
}
-///
-/// Event: subagent.selected
-///
+/// Custom agent selection details including name and available tools.
+/// Represents the subagent.selected event.
public partial class SubagentSelectedEvent : SessionEvent
{
+ ///
[JsonIgnore]
public override string Type => "subagent.selected";
+ /// The subagent.selected event payload.
[JsonPropertyName("data")]
public required SubagentSelectedData Data { get; set; }
}
-///
-/// Event: subagent.deselected
-///
+/// Empty payload; the event signals that the custom agent was deselected, returning to the default agent.
+/// Represents the subagent.deselected event.
public partial class SubagentDeselectedEvent : SessionEvent
{
+ ///
[JsonIgnore]
public override string Type => "subagent.deselected";
+ /// The subagent.deselected event payload.
[JsonPropertyName("data")]
public required SubagentDeselectedData Data { get; set; }
}
-///
-/// Event: hook.start
-///
+/// Hook invocation start details including type and input data.
+/// Represents the hook.start event.
public partial class HookStartEvent : SessionEvent
{
+ ///
[JsonIgnore]
public override string Type => "hook.start";
+ /// The hook.start event payload.
[JsonPropertyName("data")]
public required HookStartData Data { get; set; }
}
-///
-/// Event: hook.end
-///
+/// Hook invocation completion details including output, success status, and error information.
+/// Represents the hook.end event.
public partial class HookEndEvent : SessionEvent
{
+ ///
[JsonIgnore]
public override string Type => "hook.end";
+ /// The hook.end event payload.
[JsonPropertyName("data")]
public required HookEndData Data { get; set; }
}
-///
-/// Event: system.message
-///
+/// System or developer message content with role and optional template metadata.
+/// Represents the system.message event.
public partial class SystemMessageEvent : SessionEvent
{
+ ///
[JsonIgnore]
public override string Type => "system.message";
+ /// The system.message event payload.
[JsonPropertyName("data")]
public required SystemMessageData Data { get; set; }
}
-///
-/// Event: permission.requested
-///
+/// System-generated notification for runtime events like background task completion.
+/// Represents the system.notification event.
+public partial class SystemNotificationEvent : SessionEvent
+{
+ ///
+ [JsonIgnore]
+ public override string Type => "system.notification";
+
+ /// The system.notification event payload.
+ [JsonPropertyName("data")]
+ public required SystemNotificationData Data { get; set; }
+}
+
+/// Permission request notification requiring client approval with request details.
+/// Represents the permission.requested event.
public partial class PermissionRequestedEvent : SessionEvent
{
+ ///
[JsonIgnore]
public override string Type => "permission.requested";
+ /// The permission.requested event payload.
[JsonPropertyName("data")]
public required PermissionRequestedData Data { get; set; }
}
-///
-/// Event: permission.completed
-///
+/// Permission request completion notification signaling UI dismissal.
+/// Represents the permission.completed event.
public partial class PermissionCompletedEvent : SessionEvent
{
+ ///
[JsonIgnore]
public override string Type => "permission.completed";
+ /// The permission.completed event payload.
[JsonPropertyName("data")]
public required PermissionCompletedData Data { get; set; }
}
-///
-/// Event: user_input.requested
-///
+/// User input request notification with question and optional predefined choices.
+/// Represents the user_input.requested event.
public partial class UserInputRequestedEvent : SessionEvent
{
+ ///
[JsonIgnore]
public override string Type => "user_input.requested";
+ /// The user_input.requested event payload.
[JsonPropertyName("data")]
public required UserInputRequestedData Data { get; set; }
}
-///
-/// Event: user_input.completed
-///
+/// User input request completion notification signaling UI dismissal.
+/// Represents the user_input.completed event.
public partial class UserInputCompletedEvent : SessionEvent
{
+ ///
[JsonIgnore]
public override string Type => "user_input.completed";
+ /// The user_input.completed event payload.
[JsonPropertyName("data")]
public required UserInputCompletedData Data { get; set; }
}
-///
-/// Event: elicitation.requested
-///
+/// Elicitation request; may be form-based (structured input) or URL-based (browser redirect).
+/// Represents the elicitation.requested event.
public partial class ElicitationRequestedEvent : SessionEvent
{
+ ///
[JsonIgnore]
public override string Type => "elicitation.requested";
+ /// The elicitation.requested event payload.
[JsonPropertyName("data")]
public required ElicitationRequestedData Data { get; set; }
}
-///
-/// Event: elicitation.completed
-///
+/// Elicitation request completion notification signaling UI dismissal.
+/// Represents the elicitation.completed event.
public partial class ElicitationCompletedEvent : SessionEvent
{
+ ///
[JsonIgnore]
public override string Type => "elicitation.completed";
+ /// The elicitation.completed event payload.
[JsonPropertyName("data")]
public required ElicitationCompletedData Data { get; set; }
}
-///
-/// Event: external_tool.requested
-///
+/// OAuth authentication request for an MCP server.
+/// Represents the mcp.oauth_required event.
+public partial class McpOauthRequiredEvent : SessionEvent
+{
+ ///
+ [JsonIgnore]
+ public override string Type => "mcp.oauth_required";
+
+ /// The mcp.oauth_required event payload.
+ [JsonPropertyName("data")]
+ public required McpOauthRequiredData Data { get; set; }
+}
+
+/// MCP OAuth request completion notification.
+/// Represents the mcp.oauth_completed event.
+public partial class McpOauthCompletedEvent : SessionEvent
+{
+ ///
+ [JsonIgnore]
+ public override string Type => "mcp.oauth_completed";
+
+ /// The mcp.oauth_completed event payload.
+ [JsonPropertyName("data")]
+ public required McpOauthCompletedData Data { get; set; }
+}
+
+/// External tool invocation request for client-side tool execution.
+/// Represents the external_tool.requested event.
public partial class ExternalToolRequestedEvent : SessionEvent
{
+ ///
[JsonIgnore]
public override string Type => "external_tool.requested";
+ /// The external_tool.requested event payload.
[JsonPropertyName("data")]
public required ExternalToolRequestedData Data { get; set; }
}
-///
-/// Event: external_tool.completed
-///
+/// External tool completion notification signaling UI dismissal.
+/// Represents the external_tool.completed event.
public partial class ExternalToolCompletedEvent : SessionEvent
{
+ ///
[JsonIgnore]
public override string Type => "external_tool.completed";
+ /// The external_tool.completed event payload.
[JsonPropertyName("data")]
public required ExternalToolCompletedData Data { get; set; }
}
-///
-/// Event: command.queued
-///
+/// Queued slash command dispatch request for client execution.
+/// Represents the command.queued event.
public partial class CommandQueuedEvent : SessionEvent
{
+ ///
[JsonIgnore]
public override string Type => "command.queued";
+ /// The command.queued event payload.
[JsonPropertyName("data")]
public required CommandQueuedData Data { get; set; }
}
-///
-/// Event: command.completed
-///
+/// Registered command dispatch request routed to the owning client.
+/// Represents the command.execute event.
+public partial class CommandExecuteEvent : SessionEvent
+{
+ ///
+ [JsonIgnore]
+ public override string Type => "command.execute";
+
+ /// The command.execute event payload.
+ [JsonPropertyName("data")]
+ public required CommandExecuteData Data { get; set; }
+}
+
+/// Queued command completion notification signaling UI dismissal.
+/// Represents the command.completed event.
public partial class CommandCompletedEvent : SessionEvent
{
+ ///
[JsonIgnore]
public override string Type => "command.completed";
+ /// The command.completed event payload.
[JsonPropertyName("data")]
public required CommandCompletedData Data { get; set; }
}
-///
-/// Event: exit_plan_mode.requested
-///
+/// SDK command registration change notification.
+/// Represents the commands.changed event.
+public partial class CommandsChangedEvent : SessionEvent
+{
+ ///
+ [JsonIgnore]
+ public override string Type => "commands.changed";
+
+ /// The commands.changed event payload.
+ [JsonPropertyName("data")]
+ public required CommandsChangedData Data { get; set; }
+}
+
+/// Plan approval request with plan content and available user actions.
+/// Represents the exit_plan_mode.requested event.
public partial class ExitPlanModeRequestedEvent : SessionEvent
{
+ ///
[JsonIgnore]
public override string Type => "exit_plan_mode.requested";
+ /// The exit_plan_mode.requested event payload.
[JsonPropertyName("data")]
public required ExitPlanModeRequestedData Data { get; set; }
}
-///
-/// Event: exit_plan_mode.completed
-///
+/// Plan mode exit completion notification signaling UI dismissal.
+/// Represents the exit_plan_mode.completed event.
public partial class ExitPlanModeCompletedEvent : SessionEvent
{
+ ///
[JsonIgnore]
public override string Type => "exit_plan_mode.completed";
+ /// The exit_plan_mode.completed event payload.
[JsonPropertyName("data")]
public required ExitPlanModeCompletedData Data { get; set; }
}
+/// Represents the session.tools_updated event.
+public partial class SessionToolsUpdatedEvent : SessionEvent
+{
+ ///
+ [JsonIgnore]
+ public override string Type => "session.tools_updated";
+
+ /// The session.tools_updated event payload.
+ [JsonPropertyName("data")]
+ public required SessionToolsUpdatedData Data { get; set; }
+}
+
+/// Represents the session.background_tasks_changed event.
+public partial class SessionBackgroundTasksChangedEvent : SessionEvent
+{
+ ///
+ [JsonIgnore]
+ public override string Type => "session.background_tasks_changed";
+
+ /// The session.background_tasks_changed event payload.
+ [JsonPropertyName("data")]
+ public required SessionBackgroundTasksChangedData Data { get; set; }
+}
+
+/// Represents the session.skills_loaded event.
+public partial class SessionSkillsLoadedEvent : SessionEvent
+{
+ ///
+ [JsonIgnore]
+ public override string Type => "session.skills_loaded";
+
+ /// The session.skills_loaded event payload.
+ [JsonPropertyName("data")]
+ public required SessionSkillsLoadedData Data { get; set; }
+}
+
+/// Represents the session.mcp_servers_loaded event.
+public partial class SessionMcpServersLoadedEvent : SessionEvent
+{
+ ///
+ [JsonIgnore]
+ public override string Type => "session.mcp_servers_loaded";
+
+ /// The session.mcp_servers_loaded event payload.
+ [JsonPropertyName("data")]
+ public required SessionMcpServersLoadedData Data { get; set; }
+}
+
+/// Represents the session.mcp_server_status_changed event.
+public partial class SessionMcpServerStatusChangedEvent : SessionEvent
+{
+ ///
+ [JsonIgnore]
+ public override string Type => "session.mcp_server_status_changed";
+
+ /// The session.mcp_server_status_changed event payload.
+ [JsonPropertyName("data")]
+ public required SessionMcpServerStatusChangedData Data { get; set; }
+}
+
+/// Represents the session.extensions_loaded event.
+public partial class SessionExtensionsLoadedEvent : SessionEvent
+{
+ ///
+ [JsonIgnore]
+ public override string Type => "session.extensions_loaded";
+
+ /// The session.extensions_loaded event payload.
+ [JsonPropertyName("data")]
+ public required SessionExtensionsLoadedData Data { get; set; }
+}
+
+/// Session initialization metadata including context and configuration.
public partial class SessionStartData
{
+ /// Unique identifier for the session.
[JsonPropertyName("sessionId")]
public required string SessionId { get; set; }
+ /// Schema version number for the session event format.
[JsonPropertyName("version")]
public required double Version { get; set; }
+ /// Identifier of the software producing the events (e.g., "copilot-agent").
[JsonPropertyName("producer")]
public required string Producer { get; set; }
+ /// Version string of the Copilot application.
[JsonPropertyName("copilotVersion")]
public required string CopilotVersion { get; set; }
+ /// ISO 8601 timestamp when the session was created.
[JsonPropertyName("startTime")]
public required DateTimeOffset StartTime { get; set; }
+ /// Model selected at session creation time, if any.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("selectedModel")]
public string? SelectedModel { get; set; }
+ /// Reasoning effort level used for model calls, if applicable (e.g. "low", "medium", "high", "xhigh").
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ [JsonPropertyName("reasoningEffort")]
+ public string? ReasoningEffort { get; set; }
+
+ /// Working directory and git context at session start.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("context")]
public SessionStartDataContext? Context { get; set; }
+
+ /// Whether the session was already in use by another client at start time.
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ [JsonPropertyName("alreadyInUse")]
+ public bool? AlreadyInUse { get; set; }
}
+/// Session resume metadata including current context and event count.
public partial class SessionResumeData
{
+ /// ISO 8601 timestamp when the session was resumed.
[JsonPropertyName("resumeTime")]
public required DateTimeOffset ResumeTime { get; set; }
+ /// Total number of persisted events in the session at the time of resume.
[JsonPropertyName("eventCount")]
public required double EventCount { get; set; }
+ /// Model currently selected at resume time.
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ [JsonPropertyName("selectedModel")]
+ public string? SelectedModel { get; set; }
+
+ /// Reasoning effort level used for model calls, if applicable (e.g. "low", "medium", "high", "xhigh").
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ [JsonPropertyName("reasoningEffort")]
+ public string? ReasoningEffort { get; set; }
+
+ /// Updated working directory and git context at resume time.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("context")]
public SessionResumeDataContext? Context { get; set; }
+
+ /// Whether the session was already in use by another client at resume time.
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ [JsonPropertyName("alreadyInUse")]
+ public bool? AlreadyInUse { get; set; }
}
+/// Error details for timeline display including message and optional diagnostic information.
public partial class SessionErrorData
{
+ /// Category of error (e.g., "authentication", "authorization", "quota", "rate_limit", "query").
[JsonPropertyName("errorType")]
public required string ErrorType { get; set; }
+ /// Human-readable error message.
[JsonPropertyName("message")]
public required string Message { get; set; }
+ /// Error stack trace, when available.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("stack")]
public string? Stack { get; set; }
+ /// HTTP status code from the upstream request, if applicable.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("statusCode")]
public double? StatusCode { get; set; }
+ /// GitHub request tracing ID (x-github-request-id header) for correlating with server-side logs.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("providerCallId")]
public string? ProviderCallId { get; set; }
+
+ /// Optional URL associated with this error that the user can open in a browser.
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ [JsonPropertyName("url")]
+ public string? Url { get; set; }
}
+/// Payload indicating the agent is idle; includes any background tasks still in flight.
public partial class SessionIdleData
{
+ /// Background tasks still running when the agent became idle.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("backgroundTasks")]
public SessionIdleDataBackgroundTasks? BackgroundTasks { get; set; }
}
+/// Session title change payload containing the new display title.
public partial class SessionTitleChangedData
{
+ /// The new display title for the session.
[JsonPropertyName("title")]
public required string Title { get; set; }
}
+/// Informational message for timeline display with categorization.
public partial class SessionInfoData
{
+ /// Category of informational message (e.g., "notification", "timing", "context_window", "mcp", "snapshot", "configuration", "authentication", "model").
[JsonPropertyName("infoType")]
public required string InfoType { get; set; }
+ /// Human-readable informational message for display in the timeline.
[JsonPropertyName("message")]
public required string Message { get; set; }
+
+ /// Optional URL associated with this message that the user can open in a browser.
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ [JsonPropertyName("url")]
+ public string? Url { get; set; }
}
+/// Warning message for timeline display with categorization.
public partial class SessionWarningData
{
+ /// Category of warning (e.g., "subscription", "policy", "mcp").
[JsonPropertyName("warningType")]
public required string WarningType { get; set; }
+ /// Human-readable warning message for display in the timeline.
[JsonPropertyName("message")]
public required string Message { get; set; }
+
+ /// Optional URL associated with this warning that the user can open in a browser.
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ [JsonPropertyName("url")]
+ public string? Url { get; set; }
}
+/// Model change details including previous and new model identifiers.
public partial class SessionModelChangeData
{
+ /// Model that was previously selected, if any.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("previousModel")]
public string? PreviousModel { get; set; }
+ /// Newly selected model identifier.
[JsonPropertyName("newModel")]
public required string NewModel { get; set; }
+
+ /// Reasoning effort level before the model change, if applicable.
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ [JsonPropertyName("previousReasoningEffort")]
+ public string? PreviousReasoningEffort { get; set; }
+
+ /// Reasoning effort level after the model change, if applicable.
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ [JsonPropertyName("reasoningEffort")]
+ public string? ReasoningEffort { get; set; }
}
+/// Agent mode change details including previous and new modes.
public partial class SessionModeChangedData
{
+ /// Agent mode before the change (e.g., "interactive", "plan", "autopilot").
[JsonPropertyName("previousMode")]
public required string PreviousMode { get; set; }
+ /// Agent mode after the change (e.g., "interactive", "plan", "autopilot").
[JsonPropertyName("newMode")]
public required string NewMode { get; set; }
}
+/// Plan file operation details indicating what changed.
public partial class SessionPlanChangedData
{
+ /// The type of operation performed on the plan file.
[JsonPropertyName("operation")]
public required SessionPlanChangedDataOperation Operation { get; set; }
}
+/// Workspace file change details including path and operation type.
public partial class SessionWorkspaceFileChangedData
{
+ /// Relative path within the session workspace files directory.
[JsonPropertyName("path")]
public required string Path { get; set; }
+ /// Whether the file was newly created or updated.
[JsonPropertyName("operation")]
public required SessionWorkspaceFileChangedDataOperation Operation { get; set; }
}
+/// Session handoff metadata including source, context, and repository information.
public partial class SessionHandoffData
{
+ /// ISO 8601 timestamp when the handoff occurred.
[JsonPropertyName("handoffTime")]
public required DateTimeOffset HandoffTime { get; set; }
+ /// Origin type of the session being handed off.
[JsonPropertyName("sourceType")]
public required SessionHandoffDataSourceType SourceType { get; set; }
+ /// Repository context for the handed-off session.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("repository")]
public SessionHandoffDataRepository? Repository { get; set; }
+ /// Additional context information for the handoff.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("context")]
public string? Context { get; set; }
+ /// Summary of the work done in the source session.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("summary")]
public string? Summary { get; set; }
+ /// Session ID of the remote session being handed off.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("remoteSessionId")]
public string? RemoteSessionId { get; set; }
+
+ /// GitHub host URL for the source session (e.g., https://github.com or https://tenant.ghe.com).
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ [JsonPropertyName("host")]
+ public string? Host { get; set; }
}
+/// Conversation truncation statistics including token counts and removed content metrics.
public partial class SessionTruncationData
{
+ /// Maximum token count for the model's context window.
[JsonPropertyName("tokenLimit")]
public required double TokenLimit { get; set; }
+ /// Total tokens in conversation messages before truncation.
[JsonPropertyName("preTruncationTokensInMessages")]
public required double PreTruncationTokensInMessages { get; set; }
+ /// Number of conversation messages before truncation.
[JsonPropertyName("preTruncationMessagesLength")]
public required double PreTruncationMessagesLength { get; set; }
+ /// Total tokens in conversation messages after truncation.
[JsonPropertyName("postTruncationTokensInMessages")]
public required double PostTruncationTokensInMessages { get; set; }
+ /// Number of conversation messages after truncation.
[JsonPropertyName("postTruncationMessagesLength")]
public required double PostTruncationMessagesLength { get; set; }
+ /// Number of tokens removed by truncation.
[JsonPropertyName("tokensRemovedDuringTruncation")]
public required double TokensRemovedDuringTruncation { get; set; }
+ /// Number of messages removed by truncation.
[JsonPropertyName("messagesRemovedDuringTruncation")]
public required double MessagesRemovedDuringTruncation { get; set; }
+ /// Identifier of the component that performed truncation (e.g., "BasicTruncator").
[JsonPropertyName("performedBy")]
public required string PerformedBy { get; set; }
}
+/// Session rewind details including target event and count of removed events.
public partial class SessionSnapshotRewindData
{
+ /// Event ID that was rewound to; all events after this one were removed.
[JsonPropertyName("upToEventId")]
public required string UpToEventId { get; set; }
+ /// Number of events that were removed by the rewind.
[JsonPropertyName("eventsRemoved")]
public required double EventsRemoved { get; set; }
}
+/// Session termination metrics including usage statistics, code changes, and shutdown reason.
public partial class SessionShutdownData
{
+ /// Whether the session ended normally ("routine") or due to a crash/fatal error ("error").
[JsonPropertyName("shutdownType")]
public required SessionShutdownDataShutdownType ShutdownType { get; set; }
+ /// Error description when shutdownType is "error".
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("errorReason")]
public string? ErrorReason { get; set; }
+ /// Total number of premium API requests used during the session.
[JsonPropertyName("totalPremiumRequests")]
public required double TotalPremiumRequests { get; set; }
+ /// Cumulative time spent in API calls during the session, in milliseconds.
[JsonPropertyName("totalApiDurationMs")]
public required double TotalApiDurationMs { get; set; }
+ /// Unix timestamp (milliseconds) when the session started.
[JsonPropertyName("sessionStartTime")]
public required double SessionStartTime { get; set; }
+ /// Aggregate code change metrics for the session.
[JsonPropertyName("codeChanges")]
public required SessionShutdownDataCodeChanges CodeChanges { get; set; }
+ /// Per-model usage breakdown, keyed by model identifier.
[JsonPropertyName("modelMetrics")]
public required Dictionary ModelMetrics { get; set; }
+ /// Model that was selected at the time of shutdown.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("currentModel")]
public string? CurrentModel { get; set; }
+
+ /// Total tokens in context window at shutdown.
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ [JsonPropertyName("currentTokens")]
+ public double? CurrentTokens { get; set; }
+
+ /// System message token count at shutdown.
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ [JsonPropertyName("systemTokens")]
+ public double? SystemTokens { get; set; }
+
+ /// Non-system message token count at shutdown.
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ [JsonPropertyName("conversationTokens")]
+ public double? ConversationTokens { get; set; }
+
+ /// Tool definitions token count at shutdown.
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ [JsonPropertyName("toolDefinitionsTokens")]
+ public double? ToolDefinitionsTokens { get; set; }
}
+/// Updated working directory and git context after the change.
public partial class SessionContextChangedData
{
+ /// Current working directory path.
[JsonPropertyName("cwd")]
public required string Cwd { get; set; }
+ /// Root directory of the git repository, resolved via git rev-parse.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("gitRoot")]
public string? GitRoot { get; set; }
+ /// Repository identifier derived from the git remote URL ("owner/name" for GitHub, "org/project/repo" for Azure DevOps).
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("repository")]
public string? Repository { get; set; }
+ /// Hosting platform type of the repository (github or ado).
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ [JsonPropertyName("hostType")]
+ public SessionStartDataContextHostType? HostType { get; set; }
+
+ /// Current git branch name.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("branch")]
public string? Branch { get; set; }
+
+ /// Head commit of current git branch at session start time.
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ [JsonPropertyName("headCommit")]
+ public string? HeadCommit { get; set; }
+
+ /// Base commit of current git branch at session start time.
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ [JsonPropertyName("baseCommit")]
+ public string? BaseCommit { get; set; }
}
+/// Current context window usage statistics including token and message counts.
public partial class SessionUsageInfoData
{
+ /// Maximum token count for the model's context window.
[JsonPropertyName("tokenLimit")]
public required double TokenLimit { get; set; }
+ /// Current number of tokens in the context window.
[JsonPropertyName("currentTokens")]
public required double CurrentTokens { get; set; }
+ /// Current number of messages in the conversation.
[JsonPropertyName("messagesLength")]
public required double MessagesLength { get; set; }
+
+ /// Token count from system message(s).
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ [JsonPropertyName("systemTokens")]
+ public double? SystemTokens { get; set; }
+
+ /// Token count from non-system messages (user, assistant, tool).
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ [JsonPropertyName("conversationTokens")]
+ public double? ConversationTokens { get; set; }
+
+ /// Token count from tool definitions.
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ [JsonPropertyName("toolDefinitionsTokens")]
+ public double? ToolDefinitionsTokens { get; set; }
+
+ /// Whether this is the first usage_info event emitted in this session.
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ [JsonPropertyName("isInitial")]
+ public bool? IsInitial { get; set; }
}
+/// Context window breakdown at the start of LLM-powered conversation compaction.
public partial class SessionCompactionStartData
{
+ /// Token count from system message(s) at compaction start.
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ [JsonPropertyName("systemTokens")]
+ public double? SystemTokens { get; set; }
+
+ /// Token count from non-system messages (user, assistant, tool) at compaction start.
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ [JsonPropertyName("conversationTokens")]
+ public double? ConversationTokens { get; set; }
+
+ /// Token count from tool definitions at compaction start.
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ [JsonPropertyName("toolDefinitionsTokens")]
+ public double? ToolDefinitionsTokens { get; set; }
}
+/// Conversation compaction results including success status, metrics, and optional error details.
public partial class SessionCompactionCompleteData
{
+ /// Whether compaction completed successfully.
[JsonPropertyName("success")]
public required bool Success { get; set; }
+ /// Error message if compaction failed.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("error")]
public string? Error { get; set; }
+ /// Total tokens in conversation before compaction.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("preCompactionTokens")]
public double? PreCompactionTokens { get; set; }
+ /// Total tokens in conversation after compaction.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("postCompactionTokens")]
public double? PostCompactionTokens { get; set; }
+ /// Number of messages before compaction.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("preCompactionMessagesLength")]
public double? PreCompactionMessagesLength { get; set; }
+ /// Number of messages removed during compaction.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("messagesRemoved")]
public double? MessagesRemoved { get; set; }
+ /// Number of tokens removed during compaction.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("tokensRemoved")]
public double? TokensRemoved { get; set; }
+ /// LLM-generated summary of the compacted conversation history.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("summaryContent")]
public string? SummaryContent { get; set; }
+ /// Checkpoint snapshot number created for recovery.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("checkpointNumber")]
public double? CheckpointNumber { get; set; }
+ /// File path where the checkpoint was stored.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("checkpointPath")]
public string? CheckpointPath { get; set; }
+ /// Token usage breakdown for the compaction LLM call.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("compactionTokensUsed")]
public SessionCompactionCompleteDataCompactionTokensUsed? CompactionTokensUsed { get; set; }
+ /// GitHub request tracing ID (x-github-request-id header) for the compaction LLM call.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("requestId")]
public string? RequestId { get; set; }
+
+ /// Token count from system message(s) after compaction.
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ [JsonPropertyName("systemTokens")]
+ public double? SystemTokens { get; set; }
+
+ /// Token count from non-system messages (user, assistant, tool) after compaction.
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ [JsonPropertyName("conversationTokens")]
+ public double? ConversationTokens { get; set; }
+
+ /// Token count from tool definitions after compaction.
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ [JsonPropertyName("toolDefinitionsTokens")]
+ public double? ToolDefinitionsTokens { get; set; }
}
+/// Task completion notification with summary from the agent.
public partial class SessionTaskCompleteData
{
+ /// Summary of the completed task, provided by the agent.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("summary")]
public string? Summary { get; set; }
+
+ /// Whether the tool call succeeded. False when validation failed (e.g., invalid arguments).
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ [JsonPropertyName("success")]
+ public bool? Success { get; set; }
}
+/// Event payload for .
public partial class UserMessageData
{
+ /// The user's message text as displayed in the timeline.
[JsonPropertyName("content")]
public required string Content { get; set; }
+ /// Transformed version of the message sent to the model, with XML wrapping, timestamps, and other augmentations for prompt caching.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("transformedContent")]
public string? TransformedContent { get; set; }
+ /// Files, selections, or GitHub references attached to the message.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("attachments")]
public UserMessageDataAttachmentsItem[]? Attachments { get; set; }
+ /// Origin of this message, used for timeline filtering (e.g., "skill-pdf" for skill-injected messages that should be hidden from the user).
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("source")]
public string? Source { get; set; }
+ /// The agent mode that was active when this message was sent.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("agentMode")]
public UserMessageDataAgentMode? AgentMode { get; set; }
+ /// CAPI interaction ID for correlating this user message with its turn.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("interactionId")]
public string? InteractionId { get; set; }
}
+/// Empty payload; the event signals that the pending message queue has changed.
public partial class PendingMessagesModifiedData
{
}
+/// Turn initialization metadata including identifier and interaction tracking.
public partial class AssistantTurnStartData
{
+ /// Identifier for this turn within the agentic loop, typically a stringified turn number.
[JsonPropertyName("turnId")]
public required string TurnId { get; set; }
+ /// CAPI interaction ID for correlating this turn with upstream telemetry.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("interactionId")]
public string? InteractionId { get; set; }
}
+/// Agent intent description for current activity or plan.
public partial class AssistantIntentData
{
+ /// Short description of what the agent is currently doing or planning to do.
[JsonPropertyName("intent")]
public required string Intent { get; set; }
}
+/// Assistant reasoning content for timeline display with complete thinking text.
public partial class AssistantReasoningData
{
+ /// Unique identifier for this reasoning block.
[JsonPropertyName("reasoningId")]
public required string ReasoningId { get; set; }
+ /// The complete extended thinking text from the model.
[JsonPropertyName("content")]
public required string Content { get; set; }
}
+/// Streaming reasoning delta for incremental extended thinking updates.
public partial class AssistantReasoningDeltaData
{
+ /// Reasoning block ID this delta belongs to, matching the corresponding assistant.reasoning event.
[JsonPropertyName("reasoningId")]
public required string ReasoningId { get; set; }
+ /// Incremental text chunk to append to the reasoning content.
[JsonPropertyName("deltaContent")]
public required string DeltaContent { get; set; }
}
+/// Streaming response progress with cumulative byte count.
public partial class AssistantStreamingDeltaData
{
+ /// Cumulative total bytes received from the streaming response so far.
[JsonPropertyName("totalResponseSizeBytes")]
public required double TotalResponseSizeBytes { get; set; }
}
+/// Assistant response containing text content, optional tool requests, and interaction metadata.
public partial class AssistantMessageData
{
+ /// Unique identifier for this assistant message.
[JsonPropertyName("messageId")]
public required string MessageId { get; set; }
+ /// The assistant's text response content.
[JsonPropertyName("content")]
public required string Content { get; set; }
+ /// Tool invocations requested by the assistant in this message.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("toolRequests")]
public AssistantMessageDataToolRequestsItem[]? ToolRequests { get; set; }
+ /// Opaque/encrypted extended thinking data from Anthropic models. Session-bound and stripped on resume.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("reasoningOpaque")]
public string? ReasoningOpaque { get; set; }
+ /// Readable reasoning text from the model's extended thinking.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("reasoningText")]
public string? ReasoningText { get; set; }
+ /// Encrypted reasoning content from OpenAI models. Session-bound and stripped on resume.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("encryptedContent")]
public string? EncryptedContent { get; set; }
+ /// Generation phase for phased-output models (e.g., thinking vs. response phases).
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("phase")]
public string? Phase { get; set; }
+ /// Actual output token count from the API response (completion_tokens), used for accurate token accounting.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("outputTokens")]
public double? OutputTokens { get; set; }
+ /// CAPI interaction ID for correlating this message with upstream telemetry.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("interactionId")]
public string? InteractionId { get; set; }
+ /// Tool call ID of the parent tool invocation when this event originates from a sub-agent.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("parentToolCallId")]
public string? ParentToolCallId { get; set; }
}
+/// Streaming assistant message delta for incremental response updates.
public partial class AssistantMessageDeltaData
{
+ /// Message ID this delta belongs to, matching the corresponding assistant.message event.
[JsonPropertyName("messageId")]
public required string MessageId { get; set; }
+ /// Incremental text chunk to append to the message content.
[JsonPropertyName("deltaContent")]
public required string DeltaContent { get; set; }
+ /// Tool call ID of the parent tool invocation when this event originates from a sub-agent.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("parentToolCallId")]
public string? ParentToolCallId { get; set; }
}
+/// Turn completion metadata including the turn identifier.
public partial class AssistantTurnEndData
{
+ /// Identifier of the turn that has ended, matching the corresponding assistant.turn_start event.
[JsonPropertyName("turnId")]
public required string TurnId { get; set; }
}
+/// LLM API call usage metrics including tokens, costs, quotas, and billing information.
public partial class AssistantUsageData
{
+ /// Model identifier used for this API call.
[JsonPropertyName("model")]
public required string Model { get; set; }
+ /// Number of input tokens consumed.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("inputTokens")]
public double? InputTokens { get; set; }
+ /// Number of output tokens produced.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("outputTokens")]
public double? OutputTokens { get; set; }
+ /// Number of tokens read from prompt cache.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("cacheReadTokens")]
public double? CacheReadTokens { get; set; }
+ /// Number of tokens written to prompt cache.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("cacheWriteTokens")]
public double? CacheWriteTokens { get; set; }
+ /// Model multiplier cost for billing purposes.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("cost")]
public double? Cost { get; set; }
+ /// Duration of the API call in milliseconds.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("duration")]
public double? Duration { get; set; }
+ /// What initiated this API call (e.g., "sub-agent"); absent for user-initiated calls.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("initiator")]
public string? Initiator { get; set; }
+ /// Completion ID from the model provider (e.g., chatcmpl-abc123).
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("apiCallId")]
public string? ApiCallId { get; set; }
+ /// GitHub request tracing ID (x-github-request-id header) for server-side log correlation.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("providerCallId")]
public string? ProviderCallId { get; set; }
+ /// Parent tool call ID when this usage originates from a sub-agent.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("parentToolCallId")]
public string? ParentToolCallId { get; set; }
+ /// Per-quota resource usage snapshots, keyed by quota identifier.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("quotaSnapshots")]
public Dictionary? QuotaSnapshots { get; set; }
+ /// Per-request cost and usage data from the CAPI copilot_usage response field.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("copilotUsage")]
public AssistantUsageDataCopilotUsage? CopilotUsage { get; set; }
+
+ /// Reasoning effort level used for model calls, if applicable (e.g. "low", "medium", "high", "xhigh").
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ [JsonPropertyName("reasoningEffort")]
+ public string? ReasoningEffort { get; set; }
}
+/// Turn abort information including the reason for termination.
public partial class AbortData
{
+ /// Reason the current turn was aborted (e.g., "user initiated").
[JsonPropertyName("reason")]
public required string Reason { get; set; }
}
+/// User-initiated tool invocation request with tool name and arguments.
public partial class ToolUserRequestedData
{
+ /// Unique identifier for this tool call.
[JsonPropertyName("toolCallId")]
public required string ToolCallId { get; set; }
+ /// Name of the tool the user wants to invoke.
[JsonPropertyName("toolName")]
public required string ToolName { get; set; }
+ /// Arguments for the tool invocation.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("arguments")]
public object? Arguments { get; set; }
}
+/// Tool execution startup details including MCP server information when applicable.
public partial class ToolExecutionStartData
{
+ /// Unique identifier for this tool call.
[JsonPropertyName("toolCallId")]
public required string ToolCallId { get; set; }
+ /// Name of the tool being executed.
[JsonPropertyName("toolName")]
public required string ToolName { get; set; }
+ /// Arguments passed to the tool.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("arguments")]
public object? Arguments { get; set; }
+ /// Name of the MCP server hosting this tool, when the tool is an MCP tool.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("mcpServerName")]
public string? McpServerName { get; set; }
+ /// Original tool name on the MCP server, when the tool is an MCP tool.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("mcpToolName")]
public string? McpToolName { get; set; }
+ /// Tool call ID of the parent tool invocation when this event originates from a sub-agent.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("parentToolCallId")]
public string? ParentToolCallId { get; set; }
}
+/// Streaming tool execution output for incremental result display.
public partial class ToolExecutionPartialResultData
{
+ /// Tool call ID this partial result belongs to.
[JsonPropertyName("toolCallId")]
public required string ToolCallId { get; set; }
+ /// Incremental output chunk from the running tool.
[JsonPropertyName("partialOutput")]
public required string PartialOutput { get; set; }
}
+/// Tool execution progress notification with status message.
public partial class ToolExecutionProgressData
{
+ /// Tool call ID this progress notification belongs to.
[JsonPropertyName("toolCallId")]
public required string ToolCallId { get; set; }
+ /// Human-readable progress status message (e.g., from an MCP server).
[JsonPropertyName("progressMessage")]
public required string ProgressMessage { get; set; }
}
+/// Tool execution completion results including success status, detailed output, and error information.
public partial class ToolExecutionCompleteData
{
+ /// Unique identifier for the completed tool call.
[JsonPropertyName("toolCallId")]
public required string ToolCallId { get; set; }
+ /// Whether the tool execution completed successfully.
[JsonPropertyName("success")]
public required bool Success { get; set; }
+ /// Model identifier that generated this tool call.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("model")]
public string? Model { get; set; }
+ /// CAPI interaction ID for correlating this tool execution with upstream telemetry.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("interactionId")]
public string? InteractionId { get; set; }
+ /// Whether this tool call was explicitly requested by the user rather than the assistant.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("isUserRequested")]
public bool? IsUserRequested { get; set; }
+ /// Tool execution result on success.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("result")]
public ToolExecutionCompleteDataResult? Result { get; set; }
+ /// Error details when the tool execution failed.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("error")]
public ToolExecutionCompleteDataError? Error { get; set; }
+ /// Tool-specific telemetry data (e.g., CodeQL check counts, grep match counts).
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("toolTelemetry")]
public Dictionary? ToolTelemetry { get; set; }
+ /// Tool call ID of the parent tool invocation when this event originates from a sub-agent.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("parentToolCallId")]
public string? ParentToolCallId { get; set; }
}
+/// Skill invocation details including content, allowed tools, and plugin metadata.
public partial class SkillInvokedData
{
+ /// Name of the invoked skill.
[JsonPropertyName("name")]
public required string Name { get; set; }
+ /// File path to the SKILL.md definition.
[JsonPropertyName("path")]
public required string Path { get; set; }
+ /// Full content of the skill file, injected into the conversation for the model.
[JsonPropertyName("content")]
public required string Content { get; set; }
+ /// Tool names that should be auto-approved when this skill is active.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("allowedTools")]
public string[]? AllowedTools { get; set; }
+ /// Name of the plugin this skill originated from, when applicable.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("pluginName")]
public string? PluginName { get; set; }
+ /// Version of the plugin this skill originated from, when applicable.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("pluginVersion")]
public string? PluginVersion { get; set; }
}
+/// Sub-agent startup details including parent tool call and agent information.
public partial class SubagentStartedData
{
+ /// Tool call ID of the parent tool invocation that spawned this sub-agent.
[JsonPropertyName("toolCallId")]
public required string ToolCallId { get; set; }
+ /// Internal name of the sub-agent.
[JsonPropertyName("agentName")]
public required string AgentName { get; set; }
+ /// Human-readable display name of the sub-agent.
[JsonPropertyName("agentDisplayName")]
public required string AgentDisplayName { get; set; }
+ /// Description of what the sub-agent does.
[JsonPropertyName("agentDescription")]
public required string AgentDescription { get; set; }
}
+/// Sub-agent completion details for successful execution.
public partial class SubagentCompletedData
{
+ /// Tool call ID of the parent tool invocation that spawned this sub-agent.
[JsonPropertyName("toolCallId")]
public required string ToolCallId { get; set; }
+ /// Internal name of the sub-agent.
[JsonPropertyName("agentName")]
public required string AgentName { get; set; }
+ /// Human-readable display name of the sub-agent.
[JsonPropertyName("agentDisplayName")]
public required string AgentDisplayName { get; set; }
}
+/// Sub-agent failure details including error message and agent information.
public partial class SubagentFailedData
{
+ /// Tool call ID of the parent tool invocation that spawned this sub-agent.
[JsonPropertyName("toolCallId")]
public required string ToolCallId { get; set; }
+ /// Internal name of the sub-agent.
[JsonPropertyName("agentName")]
public required string AgentName { get; set; }
+ /// Human-readable display name of the sub-agent.
[JsonPropertyName("agentDisplayName")]
public required string AgentDisplayName { get; set; }
+ /// Error message describing why the sub-agent failed.
[JsonPropertyName("error")]
public required string Error { get; set; }
}
+/// Custom agent selection details including name and available tools.
public partial class SubagentSelectedData
{
+ /// Internal name of the selected custom agent.
[JsonPropertyName("agentName")]
public required string AgentName { get; set; }
+ /// Human-readable display name of the selected custom agent.
[JsonPropertyName("agentDisplayName")]
public required string AgentDisplayName { get; set; }
+ /// List of tool names available to this agent, or null for all tools.
[JsonPropertyName("tools")]
public string[]? Tools { get; set; }
}
+/// Empty payload; the event signals that the custom agent was deselected, returning to the default agent.
public partial class SubagentDeselectedData
{
}
+/// Hook invocation start details including type and input data.
public partial class HookStartData
{
+ /// Unique identifier for this hook invocation.
[JsonPropertyName("hookInvocationId")]
public required string HookInvocationId { get; set; }
+ /// Type of hook being invoked (e.g., "preToolUse", "postToolUse", "sessionStart").
[JsonPropertyName("hookType")]
public required string HookType { get; set; }
+ /// Input data passed to the hook.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("input")]
public object? Input { get; set; }
}
+/// Hook invocation completion details including output, success status, and error information.
public partial class HookEndData
{
+ /// Identifier matching the corresponding hook.start event.
[JsonPropertyName("hookInvocationId")]
public required string HookInvocationId { get; set; }
+ /// Type of hook that was invoked (e.g., "preToolUse", "postToolUse", "sessionStart").
[JsonPropertyName("hookType")]
public required string HookType { get; set; }
+ /// Output data produced by the hook.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("output")]
public object? Output { get; set; }
+ /// Whether the hook completed successfully.
[JsonPropertyName("success")]
public required bool Success { get; set; }
+ /// Error details when the hook failed.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("error")]
public HookEndDataError? Error { get; set; }
}
+/// System or developer message content with role and optional template metadata.
public partial class SystemMessageData
{
+ /// The system or developer prompt text.
[JsonPropertyName("content")]
public required string Content { get; set; }
+ /// Message role: "system" for system prompts, "developer" for developer-injected instructions.
[JsonPropertyName("role")]
public required SystemMessageDataRole Role { get; set; }
+ /// Optional name identifier for the message source.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("name")]
public string? Name { get; set; }
+ /// Metadata about the prompt template and its construction.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("metadata")]
public SystemMessageDataMetadata? Metadata { get; set; }
}
-public partial class PermissionRequestedData
+/// System-generated notification for runtime events like background task completion.
+public partial class SystemNotificationData
{
- [JsonPropertyName("requestId")]
- public required string RequestId { get; set; }
+ /// The notification text, typically wrapped in <system_notification> XML tags.
+ [JsonPropertyName("content")]
+ public required string Content { get; set; }
- [JsonPropertyName("permissionRequest")]
- public required object PermissionRequest { get; set; }
+ /// Structured metadata identifying what triggered this notification.
+ [JsonPropertyName("kind")]
+ public required SystemNotificationDataKind Kind { get; set; }
+}
+
+/// Permission request notification requiring client approval with request details.
+public partial class PermissionRequestedData
+{
+ /// Unique identifier for this permission request; used to respond via session.respondToPermission().
+ [JsonPropertyName("requestId")]
+ public required string RequestId { get; set; }
+
+ /// Details of the permission being requested.
+ [JsonPropertyName("permissionRequest")]
+ public required PermissionRequest PermissionRequest { get; set; }
}
+/// Permission request completion notification signaling UI dismissal.
public partial class PermissionCompletedData
{
+ /// Request ID of the resolved permission request; clients should dismiss any UI for this request.
[JsonPropertyName("requestId")]
public required string RequestId { get; set; }
+ /// The result of the permission request.
[JsonPropertyName("result")]
public required PermissionCompletedDataResult Result { get; set; }
}
+/// User input request notification with question and optional predefined choices.
public partial class UserInputRequestedData
{
+ /// Unique identifier for this input request; used to respond via session.respondToUserInput().
[JsonPropertyName("requestId")]
public required string RequestId { get; set; }
+ /// The question or prompt to present to the user.
[JsonPropertyName("question")]
public required string Question { get; set; }
+ /// Predefined choices for the user to select from, if applicable.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("choices")]
public string[]? Choices { get; set; }
+ /// Whether the user can provide a free-form text response in addition to predefined choices.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("allowFreeform")]
public bool? AllowFreeform { get; set; }
+
+ /// The LLM-assigned tool call ID that triggered this request; used by remote UIs to correlate responses.
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ [JsonPropertyName("toolCallId")]
+ public string? ToolCallId { get; set; }
}
+/// User input request completion notification signaling UI dismissal.
public partial class UserInputCompletedData
{
+ /// Request ID of the resolved user input request; clients should dismiss any UI for this request.
[JsonPropertyName("requestId")]
public required string RequestId { get; set; }
}
+/// Elicitation request; may be form-based (structured input) or URL-based (browser redirect).
public partial class ElicitationRequestedData
{
+ /// Unique identifier for this elicitation request; used to respond via session.respondToElicitation().
[JsonPropertyName("requestId")]
public required string RequestId { get; set; }
+ /// Tool call ID from the LLM completion; used to correlate with CompletionChunk.toolCall.id for remote UIs.
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ [JsonPropertyName("toolCallId")]
+ public string? ToolCallId { get; set; }
+
+ /// The source that initiated the request (MCP server name, or absent for agent-initiated).
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ [JsonPropertyName("elicitationSource")]
+ public string? ElicitationSource { get; set; }
+
+ /// Message describing what information is needed from the user.
[JsonPropertyName("message")]
public required string Message { get; set; }
+ /// Elicitation mode; "form" for structured input, "url" for browser-based. Defaults to "form" when absent.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("mode")]
- public string? Mode { get; set; }
+ public ElicitationRequestedDataMode? Mode { get; set; }
+ /// JSON Schema describing the form fields to present to the user (form mode only).
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("requestedSchema")]
- public required ElicitationRequestedDataRequestedSchema RequestedSchema { get; set; }
+ public ElicitationRequestedDataRequestedSchema? RequestedSchema { get; set; }
+
+ /// URL to open in the user's browser (url mode only).
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ [JsonPropertyName("url")]
+ public string? Url { get; set; }
}
+/// Elicitation request completion notification signaling UI dismissal.
public partial class ElicitationCompletedData
{
+ /// Request ID of the resolved elicitation request; clients should dismiss any UI for this request.
[JsonPropertyName("requestId")]
public required string RequestId { get; set; }
}
+/// OAuth authentication request for an MCP server.
+public partial class McpOauthRequiredData
+{
+ /// Unique identifier for this OAuth request; used to respond via session.respondToMcpOAuth().
+ [JsonPropertyName("requestId")]
+ public required string RequestId { get; set; }
+
+ /// Display name of the MCP server that requires OAuth.
+ [JsonPropertyName("serverName")]
+ public required string ServerName { get; set; }
+
+ /// URL of the MCP server that requires OAuth.
+ [JsonPropertyName("serverUrl")]
+ public required string ServerUrl { get; set; }
+
+ /// Static OAuth client configuration, if the server specifies one.
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ [JsonPropertyName("staticClientConfig")]
+ public McpOauthRequiredDataStaticClientConfig? StaticClientConfig { get; set; }
+}
+
+/// MCP OAuth request completion notification.
+public partial class McpOauthCompletedData
+{
+ /// Request ID of the resolved OAuth request.
+ [JsonPropertyName("requestId")]
+ public required string RequestId { get; set; }
+}
+
+/// External tool invocation request for client-side tool execution.
public partial class ExternalToolRequestedData
{
+ /// Unique identifier for this request; used to respond via session.respondToExternalTool().
[JsonPropertyName("requestId")]
public required string RequestId { get; set; }
+ /// Session ID that this external tool request belongs to.
[JsonPropertyName("sessionId")]
public required string SessionId { get; set; }
+ /// Tool call ID assigned to this external tool invocation.
[JsonPropertyName("toolCallId")]
public required string ToolCallId { get; set; }
+ /// Name of the external tool to invoke.
[JsonPropertyName("toolName")]
public required string ToolName { get; set; }
+ /// Arguments to pass to the external tool.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("arguments")]
public object? Arguments { get; set; }
+
+ /// W3C Trace Context traceparent header for the execute_tool span.
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ [JsonPropertyName("traceparent")]
+ public string? Traceparent { get; set; }
+
+ /// W3C Trace Context tracestate header for the execute_tool span.
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ [JsonPropertyName("tracestate")]
+ public string? Tracestate { get; set; }
}
+/// External tool completion notification signaling UI dismissal.
public partial class ExternalToolCompletedData
{
+ /// Request ID of the resolved external tool request; clients should dismiss any UI for this request.
[JsonPropertyName("requestId")]
public required string RequestId { get; set; }
}
+/// Queued slash command dispatch request for client execution.
public partial class CommandQueuedData
{
+ /// Unique identifier for this request; used to respond via session.respondToQueuedCommand().
[JsonPropertyName("requestId")]
public required string RequestId { get; set; }
+ /// The slash command text to be executed (e.g., /help, /clear).
[JsonPropertyName("command")]
public required string Command { get; set; }
}
+/// Registered command dispatch request routed to the owning client.
+public partial class CommandExecuteData
+{
+ /// Unique identifier; used to respond via session.commands.handlePendingCommand().
+ [JsonPropertyName("requestId")]
+ public required string RequestId { get; set; }
+
+ /// The full command text (e.g., /deploy production).
+ [JsonPropertyName("command")]
+ public required string Command { get; set; }
+
+ /// Command name without leading /.
+ [JsonPropertyName("commandName")]
+ public required string CommandName { get; set; }
+
+ /// Raw argument string after the command name.
+ [JsonPropertyName("args")]
+ public required string Args { get; set; }
+}
+
+/// Queued command completion notification signaling UI dismissal.
public partial class CommandCompletedData
{
+ /// Request ID of the resolved command request; clients should dismiss any UI for this request.
[JsonPropertyName("requestId")]
public required string RequestId { get; set; }
}
+/// SDK command registration change notification.
+public partial class CommandsChangedData
+{
+ /// Current list of registered SDK commands.
+ [JsonPropertyName("commands")]
+ public required CommandsChangedDataCommandsItem[] Commands { get; set; }
+}
+
+/// Plan approval request with plan content and available user actions.
public partial class ExitPlanModeRequestedData
{
+ /// Unique identifier for this request; used to respond via session.respondToExitPlanMode().
[JsonPropertyName("requestId")]
public required string RequestId { get; set; }
+ /// Summary of the plan that was created.
[JsonPropertyName("summary")]
public required string Summary { get; set; }
+ /// Full content of the plan file.
[JsonPropertyName("planContent")]
public required string PlanContent { get; set; }
+ /// Available actions the user can take (e.g., approve, edit, reject).
[JsonPropertyName("actions")]
public required string[] Actions { get; set; }
+ /// The recommended action for the user to take.
[JsonPropertyName("recommendedAction")]
public required string RecommendedAction { get; set; }
}
+/// Plan mode exit completion notification signaling UI dismissal.
public partial class ExitPlanModeCompletedData
{
+ /// Request ID of the resolved exit plan mode request; clients should dismiss any UI for this request.
[JsonPropertyName("requestId")]
public required string RequestId { get; set; }
}
+/// Event payload for .
+public partial class SessionToolsUpdatedData
+{
+ /// Gets or sets the model value.
+ [JsonPropertyName("model")]
+ public required string Model { get; set; }
+}
+
+/// Event payload for .
+public partial class SessionBackgroundTasksChangedData
+{
+}
+
+/// Event payload for .
+public partial class SessionSkillsLoadedData
+{
+ /// Array of resolved skill metadata.
+ [JsonPropertyName("skills")]
+ public required SessionSkillsLoadedDataSkillsItem[] Skills { get; set; }
+}
+
+/// Event payload for .
+public partial class SessionMcpServersLoadedData
+{
+ /// Array of MCP server status summaries.
+ [JsonPropertyName("servers")]
+ public required SessionMcpServersLoadedDataServersItem[] Servers { get; set; }
+}
+
+/// Event payload for .
+public partial class SessionMcpServerStatusChangedData
+{
+ /// Name of the MCP server whose status changed.
+ [JsonPropertyName("serverName")]
+ public required string ServerName { get; set; }
+
+ /// New connection status: connected, failed, pending, disabled, or not_configured.
+ [JsonPropertyName("status")]
+ public required SessionMcpServersLoadedDataServersItemStatus Status { get; set; }
+}
+
+/// Event payload for .
+public partial class SessionExtensionsLoadedData
+{
+ /// Array of discovered extensions and their status.
+ [JsonPropertyName("extensions")]
+ public required SessionExtensionsLoadedDataExtensionsItem[] Extensions { get; set; }
+}
+
+/// Working directory and git context at session start.
+/// Nested data type for SessionStartDataContext.
public partial class SessionStartDataContext
{
+ /// Current working directory path.
[JsonPropertyName("cwd")]
public required string Cwd { get; set; }
+ /// Root directory of the git repository, resolved via git rev-parse.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("gitRoot")]
public string? GitRoot { get; set; }
+ /// Repository identifier derived from the git remote URL ("owner/name" for GitHub, "org/project/repo" for Azure DevOps).
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("repository")]
public string? Repository { get; set; }
+ /// Hosting platform type of the repository (github or ado).
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ [JsonPropertyName("hostType")]
+ public SessionStartDataContextHostType? HostType { get; set; }
+
+ /// Current git branch name.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("branch")]
public string? Branch { get; set; }
+
+ /// Head commit of current git branch at session start time.
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ [JsonPropertyName("headCommit")]
+ public string? HeadCommit { get; set; }
+
+ /// Base commit of current git branch at session start time.
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ [JsonPropertyName("baseCommit")]
+ public string? BaseCommit { get; set; }
}
+/// Updated working directory and git context at resume time.
+/// Nested data type for SessionResumeDataContext.
public partial class SessionResumeDataContext
{
+ /// Current working directory path.
[JsonPropertyName("cwd")]
public required string Cwd { get; set; }
+ /// Root directory of the git repository, resolved via git rev-parse.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("gitRoot")]
public string? GitRoot { get; set; }
+ /// Repository identifier derived from the git remote URL ("owner/name" for GitHub, "org/project/repo" for Azure DevOps).
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("repository")]
public string? Repository { get; set; }
+ /// Hosting platform type of the repository (github or ado).
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ [JsonPropertyName("hostType")]
+ public SessionStartDataContextHostType? HostType { get; set; }
+
+ /// Current git branch name.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("branch")]
public string? Branch { get; set; }
+
+ /// Head commit of current git branch at session start time.
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ [JsonPropertyName("headCommit")]
+ public string? HeadCommit { get; set; }
+
+ /// Base commit of current git branch at session start time.
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ [JsonPropertyName("baseCommit")]
+ public string? BaseCommit { get; set; }
}
+/// A background agent task.
+/// Nested data type for SessionIdleDataBackgroundTasksAgentsItem.
public partial class SessionIdleDataBackgroundTasksAgentsItem
{
+ /// Unique identifier of the background agent.
[JsonPropertyName("agentId")]
public required string AgentId { get; set; }
+ /// Type of the background agent.
[JsonPropertyName("agentType")]
public required string AgentType { get; set; }
+ /// Human-readable description of the agent task.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("description")]
public string? Description { get; set; }
}
+/// A background shell command.
+/// Nested data type for SessionIdleDataBackgroundTasksShellsItem.
public partial class SessionIdleDataBackgroundTasksShellsItem
{
+ /// Unique identifier of the background shell.
[JsonPropertyName("shellId")]
public required string ShellId { get; set; }
+ /// Human-readable description of the shell command.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("description")]
public string? Description { get; set; }
}
+/// Background tasks still running when the agent became idle.
+/// Nested data type for SessionIdleDataBackgroundTasks.
public partial class SessionIdleDataBackgroundTasks
{
+ /// Currently running background agents.
[JsonPropertyName("agents")]
public required SessionIdleDataBackgroundTasksAgentsItem[] Agents { get; set; }
+ /// Currently running background shell commands.
[JsonPropertyName("shells")]
public required SessionIdleDataBackgroundTasksShellsItem[] Shells { get; set; }
}
+/// Repository context for the handed-off session.
+/// Nested data type for SessionHandoffDataRepository.
public partial class SessionHandoffDataRepository
{
+ /// Repository owner (user or organization).
[JsonPropertyName("owner")]
public required string Owner { get; set; }
+ /// Repository name.
[JsonPropertyName("name")]
public required string Name { get; set; }
+ /// Git branch name, if applicable.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("branch")]
public string? Branch { get; set; }
}
+/// Aggregate code change metrics for the session.
+/// Nested data type for SessionShutdownDataCodeChanges.
public partial class SessionShutdownDataCodeChanges
{
+ /// Total number of lines added during the session.
[JsonPropertyName("linesAdded")]
public required double LinesAdded { get; set; }
+ /// Total number of lines removed during the session.
[JsonPropertyName("linesRemoved")]
public required double LinesRemoved { get; set; }
+ /// List of file paths that were modified during the session.
[JsonPropertyName("filesModified")]
public required string[] FilesModified { get; set; }
}
+/// Token usage breakdown for the compaction LLM call.
+/// Nested data type for SessionCompactionCompleteDataCompactionTokensUsed.
public partial class SessionCompactionCompleteDataCompactionTokensUsed
{
+ /// Input tokens consumed by the compaction LLM call.
[JsonPropertyName("input")]
public required double Input { get; set; }
+ /// Output tokens produced by the compaction LLM call.
[JsonPropertyName("output")]
public required double Output { get; set; }
+ /// Cached input tokens reused in the compaction LLM call.
[JsonPropertyName("cachedInput")]
public required double CachedInput { get; set; }
}
+/// Optional line range to scope the attachment to a specific section of the file.
+/// Nested data type for UserMessageDataAttachmentsItemFileLineRange.
public partial class UserMessageDataAttachmentsItemFileLineRange
{
+ /// Start line number (1-based).
[JsonPropertyName("start")]
public required double Start { get; set; }
+ /// End line number (1-based, inclusive).
[JsonPropertyName("end")]
public required double End { get; set; }
}
+/// File attachment.
+/// The file variant of .
public partial class UserMessageDataAttachmentsItemFile : UserMessageDataAttachmentsItem
{
+ ///
[JsonIgnore]
public override string Type => "file";
+ /// Absolute file path.
[JsonPropertyName("path")]
public required string Path { get; set; }
+ /// User-facing display name for the attachment.
[JsonPropertyName("displayName")]
public required string DisplayName { get; set; }
+ /// Optional line range to scope the attachment to a specific section of the file.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("lineRange")]
public UserMessageDataAttachmentsItemFileLineRange? LineRange { get; set; }
}
-public partial class UserMessageDataAttachmentsItemDirectoryLineRange
-{
- [JsonPropertyName("start")]
- public required double Start { get; set; }
-
- [JsonPropertyName("end")]
- public required double End { get; set; }
-}
-
+/// Directory attachment.
+/// The directory variant of .
public partial class UserMessageDataAttachmentsItemDirectory : UserMessageDataAttachmentsItem
{
+ ///
[JsonIgnore]
public override string Type => "directory";
+ /// Absolute directory path.
[JsonPropertyName("path")]
public required string Path { get; set; }
+ /// User-facing display name for the attachment.
[JsonPropertyName("displayName")]
public required string DisplayName { get; set; }
-
- [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
- [JsonPropertyName("lineRange")]
- public UserMessageDataAttachmentsItemDirectoryLineRange? LineRange { get; set; }
}
+/// Start position of the selection.
+/// Nested data type for UserMessageDataAttachmentsItemSelectionSelectionStart.
public partial class UserMessageDataAttachmentsItemSelectionSelectionStart
{
+ /// Start line number (0-based).
[JsonPropertyName("line")]
public required double Line { get; set; }
+ /// Start character offset within the line (0-based).
[JsonPropertyName("character")]
public required double Character { get; set; }
}
+/// End position of the selection.
+/// Nested data type for UserMessageDataAttachmentsItemSelectionSelectionEnd.
public partial class UserMessageDataAttachmentsItemSelectionSelectionEnd
{
+ /// End line number (0-based).
[JsonPropertyName("line")]
public required double Line { get; set; }
+ /// End character offset within the line (0-based).
[JsonPropertyName("character")]
public required double Character { get; set; }
}
+/// Position range of the selection within the file.
+/// Nested data type for UserMessageDataAttachmentsItemSelectionSelection.
public partial class UserMessageDataAttachmentsItemSelectionSelection
{
+ /// Start position of the selection.
[JsonPropertyName("start")]
public required UserMessageDataAttachmentsItemSelectionSelectionStart Start { get; set; }
+ /// End position of the selection.
[JsonPropertyName("end")]
public required UserMessageDataAttachmentsItemSelectionSelectionEnd End { get; set; }
}
+/// Code selection attachment from an editor.
+/// The selection variant of .
public partial class UserMessageDataAttachmentsItemSelection : UserMessageDataAttachmentsItem
{
+ ///
[JsonIgnore]
public override string Type => "selection";
+ /// Absolute path to the file containing the selection.
[JsonPropertyName("filePath")]
public required string FilePath { get; set; }
+ /// User-facing display name for the selection.
[JsonPropertyName("displayName")]
public required string DisplayName { get; set; }
+ /// The selected text content.
[JsonPropertyName("text")]
public required string Text { get; set; }
+ /// Position range of the selection within the file.
[JsonPropertyName("selection")]
public required UserMessageDataAttachmentsItemSelectionSelection Selection { get; set; }
}
+/// GitHub issue, pull request, or discussion reference.
+/// The github_reference variant of .
public partial class UserMessageDataAttachmentsItemGithubReference : UserMessageDataAttachmentsItem
{
+ ///
[JsonIgnore]
public override string Type => "github_reference";
+ /// Issue, pull request, or discussion number.
[JsonPropertyName("number")]
public required double Number { get; set; }
+ /// Title of the referenced item.
[JsonPropertyName("title")]
public required string Title { get; set; }
+ /// Type of GitHub reference.
[JsonPropertyName("referenceType")]
public required UserMessageDataAttachmentsItemGithubReferenceReferenceType ReferenceType { get; set; }
+ /// Current state of the referenced item (e.g., open, closed, merged).
[JsonPropertyName("state")]
public required string State { get; set; }
+ /// URL to the referenced item on GitHub.
[JsonPropertyName("url")]
public required string Url { get; set; }
}
+/// Blob attachment with inline base64-encoded data.
+/// The blob variant of .
+public partial class UserMessageDataAttachmentsItemBlob : UserMessageDataAttachmentsItem
+{
+ ///
+ [JsonIgnore]
+ public override string Type => "blob";
+
+ /// Base64-encoded content.
+ [JsonPropertyName("data")]
+ public required string Data { get; set; }
+
+ /// MIME type of the inline data.
+ [JsonPropertyName("mimeType")]
+ public required string MimeType { get; set; }
+
+ /// User-facing display name for the attachment.
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ [JsonPropertyName("displayName")]
+ public string? DisplayName { get; set; }
+}
+
+/// A user message attachment — a file, directory, code selection, blob, or GitHub reference.
+/// Polymorphic base type discriminated by type.
[JsonPolymorphic(
TypeDiscriminatorPropertyName = "type",
UnknownDerivedTypeHandling = JsonUnknownDerivedTypeHandling.FallBackToBaseType)]
@@ -1877,163 +2766,233 @@ public partial class UserMessageDataAttachmentsItemGithubReference : UserMessage
[JsonDerivedType(typeof(UserMessageDataAttachmentsItemDirectory), "directory")]
[JsonDerivedType(typeof(UserMessageDataAttachmentsItemSelection), "selection")]
[JsonDerivedType(typeof(UserMessageDataAttachmentsItemGithubReference), "github_reference")]
+[JsonDerivedType(typeof(UserMessageDataAttachmentsItemBlob), "blob")]
public partial class UserMessageDataAttachmentsItem
{
+ /// The type discriminator.
[JsonPropertyName("type")]
public virtual string Type { get; set; } = string.Empty;
}
+/// A tool invocation request from the assistant.
+/// Nested data type for AssistantMessageDataToolRequestsItem.
public partial class AssistantMessageDataToolRequestsItem
{
+ /// Unique identifier for this tool call.
[JsonPropertyName("toolCallId")]
public required string ToolCallId { get; set; }
+ /// Name of the tool being invoked.
[JsonPropertyName("name")]
public required string Name { get; set; }
+ /// Arguments to pass to the tool, format depends on the tool.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("arguments")]
public object? Arguments { get; set; }
+ /// Tool call type: "function" for standard tool calls, "custom" for grammar-based tool calls. Defaults to "function" when absent.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("type")]
public AssistantMessageDataToolRequestsItemType? Type { get; set; }
+
+ /// Human-readable display title for the tool.
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ [JsonPropertyName("toolTitle")]
+ public string? ToolTitle { get; set; }
+
+ /// Resolved intention summary describing what this specific call does.
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ [JsonPropertyName("intentionSummary")]
+ public string? IntentionSummary { get; set; }
}
+/// Token usage detail for a single billing category.
+/// Nested data type for AssistantUsageDataCopilotUsageTokenDetailsItem.
public partial class AssistantUsageDataCopilotUsageTokenDetailsItem
{
+ /// Number of tokens in this billing batch.
[JsonPropertyName("batchSize")]
public required double BatchSize { get; set; }
+ /// Cost per batch of tokens.
[JsonPropertyName("costPerBatch")]
public required double CostPerBatch { get; set; }
+ /// Total token count for this entry.
[JsonPropertyName("tokenCount")]
public required double TokenCount { get; set; }
+ /// Token category (e.g., "input", "output").
[JsonPropertyName("tokenType")]
public required string TokenType { get; set; }
}
+/// Per-request cost and usage data from the CAPI copilot_usage response field.
+/// Nested data type for AssistantUsageDataCopilotUsage.
public partial class AssistantUsageDataCopilotUsage
{
+ /// Itemized token usage breakdown.
[JsonPropertyName("tokenDetails")]
public required AssistantUsageDataCopilotUsageTokenDetailsItem[] TokenDetails { get; set; }
+ /// Total cost in nano-AIU (AI Units) for this request.
[JsonPropertyName("totalNanoAiu")]
public required double TotalNanoAiu { get; set; }
}
+/// Plain text content block.
+/// The text variant of .
public partial class ToolExecutionCompleteDataResultContentsItemText : ToolExecutionCompleteDataResultContentsItem
{
+ ///
[JsonIgnore]
public override string Type => "text";
+ /// The text content.
[JsonPropertyName("text")]
public required string Text { get; set; }
}
+/// Terminal/shell output content block with optional exit code and working directory.
+/// The terminal variant of .
public partial class ToolExecutionCompleteDataResultContentsItemTerminal : ToolExecutionCompleteDataResultContentsItem
{
+ ///
[JsonIgnore]
public override string Type => "terminal";
+ /// Terminal/shell output text.
[JsonPropertyName("text")]
public required string Text { get; set; }
+ /// Process exit code, if the command has completed.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("exitCode")]
public double? ExitCode { get; set; }
+ /// Working directory where the command was executed.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("cwd")]
public string? Cwd { get; set; }
}
+/// Image content block with base64-encoded data.
+/// The image variant of .
public partial class ToolExecutionCompleteDataResultContentsItemImage : ToolExecutionCompleteDataResultContentsItem
{
+ ///
[JsonIgnore]
public override string Type => "image";
+ /// Base64-encoded image data.
[JsonPropertyName("data")]
public required string Data { get; set; }
+ /// MIME type of the image (e.g., image/png, image/jpeg).
[JsonPropertyName("mimeType")]
public required string MimeType { get; set; }
}
+/// Audio content block with base64-encoded data.
+/// The audio variant of .
public partial class ToolExecutionCompleteDataResultContentsItemAudio : ToolExecutionCompleteDataResultContentsItem
{
+ ///
[JsonIgnore]
public override string Type => "audio";
+ /// Base64-encoded audio data.
[JsonPropertyName("data")]
public required string Data { get; set; }
+ /// MIME type of the audio (e.g., audio/wav, audio/mpeg).
[JsonPropertyName("mimeType")]
public required string MimeType { get; set; }
}
+/// Icon image for a resource.
+/// Nested data type for ToolExecutionCompleteDataResultContentsItemResourceLinkIconsItem.
public partial class ToolExecutionCompleteDataResultContentsItemResourceLinkIconsItem
{
+ /// URL or path to the icon image.
[JsonPropertyName("src")]
public required string Src { get; set; }
+ /// MIME type of the icon image.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("mimeType")]
public string? MimeType { get; set; }
+ /// Available icon sizes (e.g., ['16x16', '32x32']).
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("sizes")]
public string[]? Sizes { get; set; }
+ /// Theme variant this icon is intended for.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("theme")]
public ToolExecutionCompleteDataResultContentsItemResourceLinkIconsItemTheme? Theme { get; set; }
}
+/// Resource link content block referencing an external resource.
+/// The resource_link variant of .
public partial class ToolExecutionCompleteDataResultContentsItemResourceLink : ToolExecutionCompleteDataResultContentsItem
{
+ ///
[JsonIgnore]
public override string Type => "resource_link";
+ /// Icons associated with this resource.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("icons")]
public ToolExecutionCompleteDataResultContentsItemResourceLinkIconsItem[]? Icons { get; set; }
+ /// Resource name identifier.
[JsonPropertyName("name")]
public required string Name { get; set; }
+ /// Human-readable display title for the resource.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("title")]
public string? Title { get; set; }
+ /// URI identifying the resource.
[JsonPropertyName("uri")]
public required string Uri { get; set; }
+ /// Human-readable description of the resource.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("description")]
public string? Description { get; set; }
+ /// MIME type of the resource content.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("mimeType")]
public string? MimeType { get; set; }
+ /// Size of the resource in bytes.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("size")]
public double? Size { get; set; }
}
+/// Embedded resource content block with inline text or binary data.
+/// The resource variant of .
public partial class ToolExecutionCompleteDataResultContentsItemResource : ToolExecutionCompleteDataResultContentsItem
{
+ ///
[JsonIgnore]
public override string Type => "resource";
+ /// The embedded resource contents, either text or base64-encoded binary.
[JsonPropertyName("resource")]
public required object Resource { get; set; }
}
+/// A content block within a tool result, which may be text, terminal output, image, audio, or a resource.
+/// Polymorphic base type discriminated by type.
[JsonPolymorphic(
TypeDiscriminatorPropertyName = "type",
UnknownDerivedTypeHandling = JsonUnknownDerivedTypeHandling.FallBackToBaseType)]
@@ -2045,179 +3004,813 @@ public partial class ToolExecutionCompleteDataResultContentsItemResource : ToolE
[JsonDerivedType(typeof(ToolExecutionCompleteDataResultContentsItemResource), "resource")]
public partial class ToolExecutionCompleteDataResultContentsItem
{
+ /// The type discriminator.
[JsonPropertyName("type")]
public virtual string Type { get; set; } = string.Empty;
}
+/// Tool execution result on success.
+/// Nested data type for ToolExecutionCompleteDataResult.
public partial class ToolExecutionCompleteDataResult
{
+ /// Concise tool result text sent to the LLM for chat completion, potentially truncated for token efficiency.
[JsonPropertyName("content")]
public required string Content { get; set; }
+ /// Full detailed tool result for UI/timeline display, preserving complete content such as diffs. Falls back to content when absent.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("detailedContent")]
public string? DetailedContent { get; set; }
+ /// Structured content blocks (text, images, audio, resources) returned by the tool in their native format.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("contents")]
public ToolExecutionCompleteDataResultContentsItem[]? Contents { get; set; }
}
+/// Error details when the tool execution failed.
+/// Nested data type for ToolExecutionCompleteDataError.
public partial class ToolExecutionCompleteDataError
{
+ /// Human-readable error message.
[JsonPropertyName("message")]
public required string Message { get; set; }
+ /// Machine-readable error code.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("code")]
public string? Code { get; set; }
}
+/// Error details when the hook failed.
+/// Nested data type for HookEndDataError.
public partial class HookEndDataError
{
+ /// Human-readable error message.
[JsonPropertyName("message")]
public required string Message { get; set; }
+ /// Error stack trace, when available.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("stack")]
public string? Stack { get; set; }
}
+/// Metadata about the prompt template and its construction.
+/// Nested data type for SystemMessageDataMetadata.
public partial class SystemMessageDataMetadata
{
+ /// Version identifier of the prompt template used.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("promptVersion")]
public string? PromptVersion { get; set; }
+ /// Template variables used when constructing the prompt.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("variables")]
public Dictionary? Variables { get; set; }
}
+/// The agent_completed variant of .
+public partial class SystemNotificationDataKindAgentCompleted : SystemNotificationDataKind
+{
+ ///
+ [JsonIgnore]
+ public override string Type => "agent_completed";
+
+ /// Unique identifier of the background agent.
+ [JsonPropertyName("agentId")]
+ public required string AgentId { get; set; }
+
+ /// Type of the agent (e.g., explore, task, general-purpose).
+ [JsonPropertyName("agentType")]
+ public required string AgentType { get; set; }
+
+ /// Whether the agent completed successfully or failed.
+ [JsonPropertyName("status")]
+ public required SystemNotificationDataKindAgentCompletedStatus Status { get; set; }
+
+ /// Human-readable description of the agent task.
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ [JsonPropertyName("description")]
+ public string? Description { get; set; }
+
+ /// The full prompt given to the background agent.
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ [JsonPropertyName("prompt")]
+ public string? Prompt { get; set; }
+}
+
+/// The agent_idle variant of .
+public partial class SystemNotificationDataKindAgentIdle : SystemNotificationDataKind
+{
+ ///
+ [JsonIgnore]
+ public override string Type => "agent_idle";
+
+ /// Unique identifier of the background agent.
+ [JsonPropertyName("agentId")]
+ public required string AgentId { get; set; }
+
+ /// Type of the agent (e.g., explore, task, general-purpose).
+ [JsonPropertyName("agentType")]
+ public required string AgentType { get; set; }
+
+ /// Human-readable description of the agent task.
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ [JsonPropertyName("description")]
+ public string? Description { get; set; }
+}
+
+/// The shell_completed variant of .
+public partial class SystemNotificationDataKindShellCompleted : SystemNotificationDataKind
+{
+ ///
+ [JsonIgnore]
+ public override string Type => "shell_completed";
+
+ /// Unique identifier of the shell session.
+ [JsonPropertyName("shellId")]
+ public required string ShellId { get; set; }
+
+ /// Exit code of the shell command, if available.
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ [JsonPropertyName("exitCode")]
+ public double? ExitCode { get; set; }
+
+ /// Human-readable description of the command.
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ [JsonPropertyName("description")]
+ public string? Description { get; set; }
+}
+
+/// The shell_detached_completed variant of .
+public partial class SystemNotificationDataKindShellDetachedCompleted : SystemNotificationDataKind
+{
+ ///
+ [JsonIgnore]
+ public override string Type => "shell_detached_completed";
+
+ /// Unique identifier of the detached shell session.
+ [JsonPropertyName("shellId")]
+ public required string ShellId { get; set; }
+
+ /// Human-readable description of the command.
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ [JsonPropertyName("description")]
+ public string? Description { get; set; }
+}
+
+/// Structured metadata identifying what triggered this notification.
+/// Polymorphic base type discriminated by type.
+[JsonPolymorphic(
+ TypeDiscriminatorPropertyName = "type",
+ UnknownDerivedTypeHandling = JsonUnknownDerivedTypeHandling.FallBackToBaseType)]
+[JsonDerivedType(typeof(SystemNotificationDataKindAgentCompleted), "agent_completed")]
+[JsonDerivedType(typeof(SystemNotificationDataKindAgentIdle), "agent_idle")]
+[JsonDerivedType(typeof(SystemNotificationDataKindShellCompleted), "shell_completed")]
+[JsonDerivedType(typeof(SystemNotificationDataKindShellDetachedCompleted), "shell_detached_completed")]
+public partial class SystemNotificationDataKind
+{
+ /// The type discriminator.
+ [JsonPropertyName("type")]
+ public virtual string Type { get; set; } = string.Empty;
+}
+
+
+/// Nested data type for PermissionRequestShellCommandsItem.
+public partial class PermissionRequestShellCommandsItem
+{
+ /// Command identifier (e.g., executable name).
+ [JsonPropertyName("identifier")]
+ public required string Identifier { get; set; }
+
+ /// Whether this command is read-only (no side effects).
+ [JsonPropertyName("readOnly")]
+ public required bool ReadOnly { get; set; }
+}
+
+/// Nested data type for PermissionRequestShellPossibleUrlsItem.
+public partial class PermissionRequestShellPossibleUrlsItem
+{
+ /// URL that may be accessed by the command.
+ [JsonPropertyName("url")]
+ public required string Url { get; set; }
+}
+
+/// Shell command permission request.
+/// The shell variant of .
+public partial class PermissionRequestShell : PermissionRequest
+{
+ ///
+ [JsonIgnore]
+ public override string Kind => "shell";
+
+ /// Tool call ID that triggered this permission request.
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ [JsonPropertyName("toolCallId")]
+ public string? ToolCallId { get; set; }
+
+ /// The complete shell command text to be executed.
+ [JsonPropertyName("fullCommandText")]
+ public required string FullCommandText { get; set; }
+
+ /// Human-readable description of what the command intends to do.
+ [JsonPropertyName("intention")]
+ public required string Intention { get; set; }
+
+ /// Parsed command identifiers found in the command text.
+ [JsonPropertyName("commands")]
+ public required PermissionRequestShellCommandsItem[] Commands { get; set; }
+
+ /// File paths that may be read or written by the command.
+ [JsonPropertyName("possiblePaths")]
+ public required string[] PossiblePaths { get; set; }
+
+ /// URLs that may be accessed by the command.
+ [JsonPropertyName("possibleUrls")]
+ public required PermissionRequestShellPossibleUrlsItem[] PossibleUrls { get; set; }
+
+ /// Whether the command includes a file write redirection (e.g., > or >>).
+ [JsonPropertyName("hasWriteFileRedirection")]
+ public required bool HasWriteFileRedirection { get; set; }
+
+ /// Whether the UI can offer session-wide approval for this command pattern.
+ [JsonPropertyName("canOfferSessionApproval")]
+ public required bool CanOfferSessionApproval { get; set; }
+
+ /// Optional warning message about risks of running this command.
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ [JsonPropertyName("warning")]
+ public string? Warning { get; set; }
+}
+
+/// File write permission request.
+/// The write variant of .
+public partial class PermissionRequestWrite : PermissionRequest
+{
+ ///
+ [JsonIgnore]
+ public override string Kind => "write";
+
+ /// Tool call ID that triggered this permission request.
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ [JsonPropertyName("toolCallId")]
+ public string? ToolCallId { get; set; }
+
+ /// Human-readable description of the intended file change.
+ [JsonPropertyName("intention")]
+ public required string Intention { get; set; }
+
+ /// Path of the file being written to.
+ [JsonPropertyName("fileName")]
+ public required string FileName { get; set; }
+
+ /// Unified diff showing the proposed changes.
+ [JsonPropertyName("diff")]
+ public required string Diff { get; set; }
+
+ /// Complete new file contents for newly created files.
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ [JsonPropertyName("newFileContents")]
+ public string? NewFileContents { get; set; }
+}
+
+/// File or directory read permission request.
+/// The read variant of .
+public partial class PermissionRequestRead : PermissionRequest
+{
+ ///
+ [JsonIgnore]
+ public override string Kind => "read";
+
+ /// Tool call ID that triggered this permission request.
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ [JsonPropertyName("toolCallId")]
+ public string? ToolCallId { get; set; }
+
+ /// Human-readable description of why the file is being read.
+ [JsonPropertyName("intention")]
+ public required string Intention { get; set; }
+
+ /// Path of the file or directory being read.
+ [JsonPropertyName("path")]
+ public required string Path { get; set; }
+}
+
+/// MCP tool invocation permission request.
+/// The mcp variant of .
+public partial class PermissionRequestMcp : PermissionRequest
+{
+ ///
+ [JsonIgnore]
+ public override string Kind => "mcp";
+
+ /// Tool call ID that triggered this permission request.
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ [JsonPropertyName("toolCallId")]
+ public string? ToolCallId { get; set; }
+
+ /// Name of the MCP server providing the tool.
+ [JsonPropertyName("serverName")]
+ public required string ServerName { get; set; }
+
+ /// Internal name of the MCP tool.
+ [JsonPropertyName("toolName")]
+ public required string ToolName { get; set; }
+
+ /// Human-readable title of the MCP tool.
+ [JsonPropertyName("toolTitle")]
+ public required string ToolTitle { get; set; }
+
+ /// Arguments to pass to the MCP tool.
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ [JsonPropertyName("args")]
+ public object? Args { get; set; }
+
+ /// Whether this MCP tool is read-only (no side effects).
+ [JsonPropertyName("readOnly")]
+ public required bool ReadOnly { get; set; }
+}
+
+/// URL access permission request.
+/// The url variant of .
+public partial class PermissionRequestUrl : PermissionRequest
+{
+ ///
+ [JsonIgnore]
+ public override string Kind => "url";
+
+ /// Tool call ID that triggered this permission request.
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ [JsonPropertyName("toolCallId")]
+ public string? ToolCallId { get; set; }
+
+ /// Human-readable description of why the URL is being accessed.
+ [JsonPropertyName("intention")]
+ public required string Intention { get; set; }
+
+ /// URL to be fetched.
+ [JsonPropertyName("url")]
+ public required string Url { get; set; }
+}
+
+/// Memory storage permission request.
+/// The memory variant of .
+public partial class PermissionRequestMemory : PermissionRequest
+{
+ ///
+ [JsonIgnore]
+ public override string Kind => "memory";
+
+ /// Tool call ID that triggered this permission request.
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ [JsonPropertyName("toolCallId")]
+ public string? ToolCallId { get; set; }
+
+ /// Topic or subject of the memory being stored.
+ [JsonPropertyName("subject")]
+ public required string Subject { get; set; }
+
+ /// The fact or convention being stored.
+ [JsonPropertyName("fact")]
+ public required string Fact { get; set; }
+
+ /// Source references for the stored fact.
+ [JsonPropertyName("citations")]
+ public required string Citations { get; set; }
+}
+
+/// Custom tool invocation permission request.
+/// The custom-tool variant of .
+public partial class PermissionRequestCustomTool : PermissionRequest
+{
+ ///
+ [JsonIgnore]
+ public override string Kind => "custom-tool";
+
+ /// Tool call ID that triggered this permission request.
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ [JsonPropertyName("toolCallId")]
+ public string? ToolCallId { get; set; }
+
+ /// Name of the custom tool.
+ [JsonPropertyName("toolName")]
+ public required string ToolName { get; set; }
+
+ /// Description of what the custom tool does.
+ [JsonPropertyName("toolDescription")]
+ public required string ToolDescription { get; set; }
+
+ /// Arguments to pass to the custom tool.
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ [JsonPropertyName("args")]
+ public object? Args { get; set; }
+}
+
+/// Hook confirmation permission request.
+/// The hook variant of .
+public partial class PermissionRequestHook : PermissionRequest
+{
+ ///
+ [JsonIgnore]
+ public override string Kind => "hook";
+
+ /// Tool call ID that triggered this permission request.
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ [JsonPropertyName("toolCallId")]
+ public string? ToolCallId { get; set; }
+
+ /// Name of the tool the hook is gating.
+ [JsonPropertyName("toolName")]
+ public required string ToolName { get; set; }
+
+ /// Arguments of the tool call being gated.
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ [JsonPropertyName("toolArgs")]
+ public object? ToolArgs { get; set; }
+
+ /// Optional message from the hook explaining why confirmation is needed.
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ [JsonPropertyName("hookMessage")]
+ public string? HookMessage { get; set; }
+}
+
+/// Details of the permission being requested.
+/// Polymorphic base type discriminated by kind.
+[JsonPolymorphic(
+ TypeDiscriminatorPropertyName = "kind",
+ UnknownDerivedTypeHandling = JsonUnknownDerivedTypeHandling.FallBackToBaseType)]
+[JsonDerivedType(typeof(PermissionRequestShell), "shell")]
+[JsonDerivedType(typeof(PermissionRequestWrite), "write")]
+[JsonDerivedType(typeof(PermissionRequestRead), "read")]
+[JsonDerivedType(typeof(PermissionRequestMcp), "mcp")]
+[JsonDerivedType(typeof(PermissionRequestUrl), "url")]
+[JsonDerivedType(typeof(PermissionRequestMemory), "memory")]
+[JsonDerivedType(typeof(PermissionRequestCustomTool), "custom-tool")]
+[JsonDerivedType(typeof(PermissionRequestHook), "hook")]
+public partial class PermissionRequest
+{
+ /// The type discriminator.
+ [JsonPropertyName("kind")]
+ public virtual string Kind { get; set; } = string.Empty;
+}
+
+
+/// The result of the permission request.
+/// Nested data type for PermissionCompletedDataResult.
public partial class PermissionCompletedDataResult
{
+ /// The outcome of the permission request.
[JsonPropertyName("kind")]
public required PermissionCompletedDataResultKind Kind { get; set; }
}
+/// JSON Schema describing the form fields to present to the user (form mode only).
+/// Nested data type for ElicitationRequestedDataRequestedSchema.
public partial class ElicitationRequestedDataRequestedSchema
{
+ /// Schema type indicator (always 'object').
[JsonPropertyName("type")]
public required string Type { get; set; }
+ /// Form field definitions, keyed by field name.
[JsonPropertyName("properties")]
public required Dictionary Properties { get; set; }
+ /// List of required field names.
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
[JsonPropertyName("required")]
public string[]? Required { get; set; }
}
+/// Static OAuth client configuration, if the server specifies one.
+/// Nested data type for McpOauthRequiredDataStaticClientConfig.
+public partial class McpOauthRequiredDataStaticClientConfig
+{
+ /// OAuth client ID for the server.
+ [JsonPropertyName("clientId")]
+ public required string ClientId { get; set; }
+
+ /// Whether this is a public OAuth client.
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ [JsonPropertyName("publicClient")]
+ public bool? PublicClient { get; set; }
+}
+
+/// Nested data type for CommandsChangedDataCommandsItem.
+public partial class CommandsChangedDataCommandsItem
+{
+ /// Gets or sets the name value.
+ [JsonPropertyName("name")]
+ public required string Name { get; set; }
+
+ /// Gets or sets the description value.
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ [JsonPropertyName("description")]
+ public string? Description { get; set; }
+}
+
+/// Nested data type for SessionSkillsLoadedDataSkillsItem.
+public partial class SessionSkillsLoadedDataSkillsItem
+{
+ /// Unique identifier for the skill.
+ [JsonPropertyName("name")]
+ public required string Name { get; set; }
+
+ /// Description of what the skill does.
+ [JsonPropertyName("description")]
+ public required string Description { get; set; }
+
+ /// Source location type of the skill (e.g., project, personal, plugin).
+ [JsonPropertyName("source")]
+ public required string Source { get; set; }
+
+ /// Whether the skill can be invoked by the user as a slash command.
+ [JsonPropertyName("userInvocable")]
+ public required bool UserInvocable { get; set; }
+
+ /// Whether the skill is currently enabled.
+ [JsonPropertyName("enabled")]
+ public required bool Enabled { get; set; }
+
+ /// Absolute path to the skill file, if available.
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ [JsonPropertyName("path")]
+ public string? Path { get; set; }
+}
+
+/// Nested data type for SessionMcpServersLoadedDataServersItem.
+public partial class SessionMcpServersLoadedDataServersItem
+{
+ /// Server name (config key).
+ [JsonPropertyName("name")]
+ public required string Name { get; set; }
+
+ /// Connection status: connected, failed, pending, disabled, or not_configured.
+ [JsonPropertyName("status")]
+ public required SessionMcpServersLoadedDataServersItemStatus Status { get; set; }
+
+ /// Configuration source: user, workspace, plugin, or builtin.
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ [JsonPropertyName("source")]
+ public string? Source { get; set; }
+
+ /// Error message if the server failed to connect.
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ [JsonPropertyName("error")]
+ public string? Error { get; set; }
+}
+
+/// Nested data type for SessionExtensionsLoadedDataExtensionsItem.
+public partial class SessionExtensionsLoadedDataExtensionsItem
+{
+ /// Source-qualified extension ID (e.g., 'project:my-ext', 'user:auth-helper').
+ [JsonPropertyName("id")]
+ public required string Id { get; set; }
+
+ /// Extension name (directory name).
+ [JsonPropertyName("name")]
+ public required string Name { get; set; }
+
+ /// Discovery source.
+ [JsonPropertyName("source")]
+ public required SessionExtensionsLoadedDataExtensionsItemSource Source { get; set; }
+
+ /// Current status: running, disabled, failed, or starting.
+ [JsonPropertyName("status")]
+ public required SessionExtensionsLoadedDataExtensionsItemStatus Status { get; set; }
+}
+
+/// Hosting platform type of the repository (github or ado).
+[JsonConverter(typeof(JsonStringEnumConverter))]
+public enum SessionStartDataContextHostType
+{
+ /// The github variant.
+ [JsonStringEnumMemberName("github")]
+ Github,
+ /// The ado variant.
+ [JsonStringEnumMemberName("ado")]
+ Ado,
+}
+
+/// The type of operation performed on the plan file.
[JsonConverter(typeof(JsonStringEnumConverter))]
public enum SessionPlanChangedDataOperation
{
+ /// The create variant.
[JsonStringEnumMemberName("create")]
Create,
+ /// The update variant.
[JsonStringEnumMemberName("update")]
Update,
+ /// The delete variant.
[JsonStringEnumMemberName("delete")]
Delete,
}
+/// Whether the file was newly created or updated.
[JsonConverter(typeof(JsonStringEnumConverter))]
public enum SessionWorkspaceFileChangedDataOperation
{
+ /// The create variant.
[JsonStringEnumMemberName("create")]
Create,
+ /// The update variant.
[JsonStringEnumMemberName("update")]
Update,
}
+/// Origin type of the session being handed off.
[JsonConverter(typeof(JsonStringEnumConverter))]
public enum SessionHandoffDataSourceType
{
+ /// The remote variant.
[JsonStringEnumMemberName("remote")]
Remote,
+ /// The local variant.
[JsonStringEnumMemberName("local")]
Local,
}
+/// Whether the session ended normally ("routine") or due to a crash/fatal error ("error").
[JsonConverter(typeof(JsonStringEnumConverter))]
public enum SessionShutdownDataShutdownType
{
+ /// The routine variant.
[JsonStringEnumMemberName("routine")]
Routine,
+ /// The error variant.
[JsonStringEnumMemberName("error")]
Error,
}
+/// Type of GitHub reference.
[JsonConverter(typeof(JsonStringEnumConverter))]
public enum UserMessageDataAttachmentsItemGithubReferenceReferenceType
{
+ /// The issue variant.
[JsonStringEnumMemberName("issue")]
Issue,
+ /// The pr variant.
[JsonStringEnumMemberName("pr")]
Pr,
+ /// The discussion variant.
[JsonStringEnumMemberName("discussion")]
Discussion,
}
+/// The agent mode that was active when this message was sent.
[JsonConverter(typeof(JsonStringEnumConverter))]
public enum UserMessageDataAgentMode
{
+ /// The interactive variant.
[JsonStringEnumMemberName("interactive")]
Interactive,
+ /// The plan variant.
[JsonStringEnumMemberName("plan")]
Plan,
+ /// The autopilot variant.
[JsonStringEnumMemberName("autopilot")]
Autopilot,
+ /// The shell variant.
[JsonStringEnumMemberName("shell")]
Shell,
}
+/// Tool call type: "function" for standard tool calls, "custom" for grammar-based tool calls. Defaults to "function" when absent.
[JsonConverter(typeof(JsonStringEnumConverter))]
public enum AssistantMessageDataToolRequestsItemType
{
+ /// The function variant.
[JsonStringEnumMemberName("function")]
Function,
+ /// The custom variant.
[JsonStringEnumMemberName("custom")]
Custom,
}
+/// Theme variant this icon is intended for.
[JsonConverter(typeof(JsonStringEnumConverter))]
public enum ToolExecutionCompleteDataResultContentsItemResourceLinkIconsItemTheme
{
+ /// The light variant.
[JsonStringEnumMemberName("light")]
Light,
+ /// The dark variant.
[JsonStringEnumMemberName("dark")]
Dark,
}
+/// Message role: "system" for system prompts, "developer" for developer-injected instructions.
[JsonConverter(typeof(JsonStringEnumConverter))]
public enum SystemMessageDataRole
{
+ /// The system variant.
[JsonStringEnumMemberName("system")]
System,
+ /// The developer variant.
[JsonStringEnumMemberName("developer")]
Developer,
}
+/// Whether the agent completed successfully or failed.
+[JsonConverter(typeof(JsonStringEnumConverter))]
+public enum SystemNotificationDataKindAgentCompletedStatus
+{
+ /// The completed variant.
+ [JsonStringEnumMemberName("completed")]
+ Completed,
+ /// The failed variant.
+ [JsonStringEnumMemberName("failed")]
+ Failed,
+}
+
+/// The outcome of the permission request.
[JsonConverter(typeof(JsonStringEnumConverter))]
public enum PermissionCompletedDataResultKind
{
+ /// The approved variant.
[JsonStringEnumMemberName("approved")]
Approved,
+ /// The denied-by-rules variant.
[JsonStringEnumMemberName("denied-by-rules")]
DeniedByRules,
+ /// The denied-no-approval-rule-and-could-not-request-from-user variant.
[JsonStringEnumMemberName("denied-no-approval-rule-and-could-not-request-from-user")]
DeniedNoApprovalRuleAndCouldNotRequestFromUser,
+ /// The denied-interactively-by-user variant.
[JsonStringEnumMemberName("denied-interactively-by-user")]
DeniedInteractivelyByUser,
+ /// The denied-by-content-exclusion-policy variant.
[JsonStringEnumMemberName("denied-by-content-exclusion-policy")]
DeniedByContentExclusionPolicy,
}
+/// Elicitation mode; "form" for structured input, "url" for browser-based. Defaults to "form" when absent.
+[JsonConverter(typeof(JsonStringEnumConverter))]
+public enum ElicitationRequestedDataMode
+{
+ /// The form variant.
+ [JsonStringEnumMemberName("form")]
+ Form,
+ /// The url variant.
+ [JsonStringEnumMemberName("url")]
+ Url,
+}
+
+/// Connection status: connected, failed, pending, disabled, or not_configured.
+[JsonConverter(typeof(JsonStringEnumConverter))]
+public enum SessionMcpServersLoadedDataServersItemStatus
+{
+ /// The connected variant.
+ [JsonStringEnumMemberName("connected")]
+ Connected,
+ /// The failed variant.
+ [JsonStringEnumMemberName("failed")]
+ Failed,
+ /// The pending variant.
+ [JsonStringEnumMemberName("pending")]
+ Pending,
+ /// The disabled variant.
+ [JsonStringEnumMemberName("disabled")]
+ Disabled,
+ /// The not_configured variant.
+ [JsonStringEnumMemberName("not_configured")]
+ NotConfigured,
+}
+
+/// Discovery source.
+[JsonConverter(typeof(JsonStringEnumConverter))]
+public enum SessionExtensionsLoadedDataExtensionsItemSource
+{
+ /// The project variant.
+ [JsonStringEnumMemberName("project")]
+ Project,
+ /// The user variant.
+ [JsonStringEnumMemberName("user")]
+ User,
+}
+
+/// Current status: running, disabled, failed, or starting.
+[JsonConverter(typeof(JsonStringEnumConverter))]
+public enum SessionExtensionsLoadedDataExtensionsItemStatus
+{
+ /// The running variant.
+ [JsonStringEnumMemberName("running")]
+ Running,
+ /// The disabled variant.
+ [JsonStringEnumMemberName("disabled")]
+ Disabled,
+ /// The failed variant.
+ [JsonStringEnumMemberName("failed")]
+ Failed,
+ /// The starting variant.
+ [JsonStringEnumMemberName("starting")]
+ Starting,
+}
+
[JsonSourceGenerationOptions(
JsonSerializerDefaults.Web,
AllowOutOfOrderMetadataProperties = true,
@@ -2248,8 +3841,13 @@ public enum PermissionCompletedDataResultKind
[JsonSerializable(typeof(AssistantUsageEvent))]
[JsonSerializable(typeof(CommandCompletedData))]
[JsonSerializable(typeof(CommandCompletedEvent))]
+[JsonSerializable(typeof(CommandExecuteData))]
+[JsonSerializable(typeof(CommandExecuteEvent))]
[JsonSerializable(typeof(CommandQueuedData))]
[JsonSerializable(typeof(CommandQueuedEvent))]
+[JsonSerializable(typeof(CommandsChangedData))]
+[JsonSerializable(typeof(CommandsChangedDataCommandsItem))]
+[JsonSerializable(typeof(CommandsChangedEvent))]
[JsonSerializable(typeof(ElicitationCompletedData))]
[JsonSerializable(typeof(ElicitationCompletedEvent))]
[JsonSerializable(typeof(ElicitationRequestedData))]
@@ -2268,13 +3866,31 @@ public enum PermissionCompletedDataResultKind
[JsonSerializable(typeof(HookEndEvent))]
[JsonSerializable(typeof(HookStartData))]
[JsonSerializable(typeof(HookStartEvent))]
+[JsonSerializable(typeof(McpOauthCompletedData))]
+[JsonSerializable(typeof(McpOauthCompletedEvent))]
+[JsonSerializable(typeof(McpOauthRequiredData))]
+[JsonSerializable(typeof(McpOauthRequiredDataStaticClientConfig))]
+[JsonSerializable(typeof(McpOauthRequiredEvent))]
[JsonSerializable(typeof(PendingMessagesModifiedData))]
[JsonSerializable(typeof(PendingMessagesModifiedEvent))]
[JsonSerializable(typeof(PermissionCompletedData))]
[JsonSerializable(typeof(PermissionCompletedDataResult))]
[JsonSerializable(typeof(PermissionCompletedEvent))]
+[JsonSerializable(typeof(PermissionRequest))]
+[JsonSerializable(typeof(PermissionRequestCustomTool))]
+[JsonSerializable(typeof(PermissionRequestHook))]
+[JsonSerializable(typeof(PermissionRequestMcp))]
+[JsonSerializable(typeof(PermissionRequestMemory))]
+[JsonSerializable(typeof(PermissionRequestRead))]
+[JsonSerializable(typeof(PermissionRequestShell))]
+[JsonSerializable(typeof(PermissionRequestShellCommandsItem))]
+[JsonSerializable(typeof(PermissionRequestShellPossibleUrlsItem))]
+[JsonSerializable(typeof(PermissionRequestUrl))]
+[JsonSerializable(typeof(PermissionRequestWrite))]
[JsonSerializable(typeof(PermissionRequestedData))]
[JsonSerializable(typeof(PermissionRequestedEvent))]
+[JsonSerializable(typeof(SessionBackgroundTasksChangedData))]
+[JsonSerializable(typeof(SessionBackgroundTasksChangedEvent))]
[JsonSerializable(typeof(SessionCompactionCompleteData))]
[JsonSerializable(typeof(SessionCompactionCompleteDataCompactionTokensUsed))]
[JsonSerializable(typeof(SessionCompactionCompleteEvent))]
@@ -2285,6 +3901,9 @@ public enum PermissionCompletedDataResultKind
[JsonSerializable(typeof(SessionErrorData))]
[JsonSerializable(typeof(SessionErrorEvent))]
[JsonSerializable(typeof(SessionEvent))]
+[JsonSerializable(typeof(SessionExtensionsLoadedData))]
+[JsonSerializable(typeof(SessionExtensionsLoadedDataExtensionsItem))]
+[JsonSerializable(typeof(SessionExtensionsLoadedEvent))]
[JsonSerializable(typeof(SessionHandoffData))]
[JsonSerializable(typeof(SessionHandoffDataRepository))]
[JsonSerializable(typeof(SessionHandoffEvent))]
@@ -2295,6 +3914,11 @@ public enum PermissionCompletedDataResultKind
[JsonSerializable(typeof(SessionIdleEvent))]
[JsonSerializable(typeof(SessionInfoData))]
[JsonSerializable(typeof(SessionInfoEvent))]
+[JsonSerializable(typeof(SessionMcpServerStatusChangedData))]
+[JsonSerializable(typeof(SessionMcpServerStatusChangedEvent))]
+[JsonSerializable(typeof(SessionMcpServersLoadedData))]
+[JsonSerializable(typeof(SessionMcpServersLoadedDataServersItem))]
+[JsonSerializable(typeof(SessionMcpServersLoadedEvent))]
[JsonSerializable(typeof(SessionModeChangedData))]
[JsonSerializable(typeof(SessionModeChangedEvent))]
[JsonSerializable(typeof(SessionModelChangeData))]
@@ -2307,6 +3931,9 @@ public enum PermissionCompletedDataResultKind
[JsonSerializable(typeof(SessionShutdownData))]
[JsonSerializable(typeof(SessionShutdownDataCodeChanges))]
[JsonSerializable(typeof(SessionShutdownEvent))]
+[JsonSerializable(typeof(SessionSkillsLoadedData))]
+[JsonSerializable(typeof(SessionSkillsLoadedDataSkillsItem))]
+[JsonSerializable(typeof(SessionSkillsLoadedEvent))]
[JsonSerializable(typeof(SessionSnapshotRewindData))]
[JsonSerializable(typeof(SessionSnapshotRewindEvent))]
[JsonSerializable(typeof(SessionStartData))]
@@ -2316,6 +3943,8 @@ public enum PermissionCompletedDataResultKind
[JsonSerializable(typeof(SessionTaskCompleteEvent))]
[JsonSerializable(typeof(SessionTitleChangedData))]
[JsonSerializable(typeof(SessionTitleChangedEvent))]
+[JsonSerializable(typeof(SessionToolsUpdatedData))]
+[JsonSerializable(typeof(SessionToolsUpdatedEvent))]
[JsonSerializable(typeof(SessionTruncationData))]
[JsonSerializable(typeof(SessionTruncationEvent))]
[JsonSerializable(typeof(SessionUsageInfoData))]
@@ -2339,6 +3968,13 @@ public enum PermissionCompletedDataResultKind
[JsonSerializable(typeof(SystemMessageData))]
[JsonSerializable(typeof(SystemMessageDataMetadata))]
[JsonSerializable(typeof(SystemMessageEvent))]
+[JsonSerializable(typeof(SystemNotificationData))]
+[JsonSerializable(typeof(SystemNotificationDataKind))]
+[JsonSerializable(typeof(SystemNotificationDataKindAgentCompleted))]
+[JsonSerializable(typeof(SystemNotificationDataKindAgentIdle))]
+[JsonSerializable(typeof(SystemNotificationDataKindShellCompleted))]
+[JsonSerializable(typeof(SystemNotificationDataKindShellDetachedCompleted))]
+[JsonSerializable(typeof(SystemNotificationEvent))]
[JsonSerializable(typeof(ToolExecutionCompleteData))]
[JsonSerializable(typeof(ToolExecutionCompleteDataError))]
[JsonSerializable(typeof(ToolExecutionCompleteDataResult))]
@@ -2365,8 +4001,8 @@ public enum PermissionCompletedDataResultKind
[JsonSerializable(typeof(UserInputRequestedEvent))]
[JsonSerializable(typeof(UserMessageData))]
[JsonSerializable(typeof(UserMessageDataAttachmentsItem))]
+[JsonSerializable(typeof(UserMessageDataAttachmentsItemBlob))]
[JsonSerializable(typeof(UserMessageDataAttachmentsItemDirectory))]
-[JsonSerializable(typeof(UserMessageDataAttachmentsItemDirectoryLineRange))]
[JsonSerializable(typeof(UserMessageDataAttachmentsItemFile))]
[JsonSerializable(typeof(UserMessageDataAttachmentsItemFileLineRange))]
[JsonSerializable(typeof(UserMessageDataAttachmentsItemGithubReference))]
@@ -2375,4 +4011,5 @@ public enum PermissionCompletedDataResultKind
[JsonSerializable(typeof(UserMessageDataAttachmentsItemSelectionSelectionEnd))]
[JsonSerializable(typeof(UserMessageDataAttachmentsItemSelectionSelectionStart))]
[JsonSerializable(typeof(UserMessageEvent))]
+[JsonSerializable(typeof(JsonElement))]
internal partial class SessionEventsJsonContext : JsonSerializerContext;
\ No newline at end of file
diff --git a/dotnet/src/GitHub.Copilot.SDK.csproj b/dotnet/src/GitHub.Copilot.SDK.csproj
index 8ae53ca74c..38eb0cf3aa 100644
--- a/dotnet/src/GitHub.Copilot.SDK.csproj
+++ b/dotnet/src/GitHub.Copilot.SDK.csproj
@@ -11,6 +11,7 @@
https://github.com/github/copilot-sdk
README.md
https://github.com/github/copilot-sdk
+ copilot.png
github;copilot;sdk;jsonrpc;agent
true
true
@@ -19,12 +20,17 @@
true
+
+ $(NoWarn);GHCP001
+
+
true
+
diff --git a/dotnet/src/SdkProtocolVersion.cs b/dotnet/src/SdkProtocolVersion.cs
index f3d8f04c5a..889af460bb 100644
--- a/dotnet/src/SdkProtocolVersion.cs
+++ b/dotnet/src/SdkProtocolVersion.cs
@@ -16,8 +16,5 @@ internal static class SdkProtocolVersion
///
/// Gets the SDK protocol version.
///
- public static int GetVersion()
- {
- return Version;
- }
+ public static int GetVersion() => Version;
}
diff --git a/dotnet/src/Session.cs b/dotnet/src/Session.cs
index 397eae0fa2..675a3e0c0d 100644
--- a/dotnet/src/Session.cs
+++ b/dotnet/src/Session.cs
@@ -2,12 +2,15 @@
* Copyright (c) Microsoft Corporation. All rights reserved.
*--------------------------------------------------------------------------------------------*/
+using GitHub.Copilot.SDK.Rpc;
using Microsoft.Extensions.AI;
+using Microsoft.Extensions.Logging;
using StreamJsonRpc;
+using System.Collections.Immutable;
using System.Text.Json;
using System.Text.Json.Nodes;
using System.Text.Json.Serialization;
-using GitHub.Copilot.SDK.Rpc;
+using System.Threading.Channels;
namespace GitHub.Copilot.SDK;
@@ -52,22 +55,29 @@ namespace GitHub.Copilot.SDK;
///
public sealed partial class CopilotSession : IAsyncDisposable
{
- ///
- /// Multicast delegate used as a thread-safe, insertion-ordered handler list.
- /// The compiler-generated add/remove accessors use a lock-free CAS loop over the backing field.
- /// Dispatch reads the field once (inherent snapshot, no allocation).
- /// Expected handler count is small (typically 1–3), so Delegate.Combine/Remove cost is negligible.
- ///
- private event SessionEventHandler? EventHandlers;
private readonly Dictionary _toolHandlers = [];
private readonly JsonRpc _rpc;
+ private readonly ILogger _logger;
+
private volatile PermissionRequestHandler? _permissionHandler;
private volatile UserInputHandler? _userInputHandler;
+ private ImmutableArray _eventHandlers = ImmutableArray.Empty;
+
private SessionHooks? _hooks;
private readonly SemaphoreSlim _hooksLock = new(1, 1);
+ private Dictionary>>? _transformCallbacks;
+ private readonly SemaphoreSlim _transformCallbacksLock = new(1, 1);
private SessionRpc? _sessionRpc;
private int _isDisposed;
+ ///
+ /// Channel that serializes event dispatch. enqueues;
+ /// a single background consumer () dequeues and
+ /// invokes handlers one at a time, preserving arrival order.
+ ///
+ private readonly Channel _eventChannel = Channel.CreateUnbounded(
+ new() { SingleReader = true });
+
///
/// Gets the unique identifier for this session.
///
@@ -86,22 +96,27 @@ public sealed partial class CopilotSession : IAsyncDisposable
/// The path to the workspace containing checkpoints/, plan.md, and files/ subdirectories,
/// or null if infinite sessions are disabled.
///
- public string? WorkspacePath { get; }
+ public string? WorkspacePath { get; internal set; }
///
/// Initializes a new instance of the class.
///
/// The unique identifier for this session.
/// The JSON-RPC connection to the Copilot CLI.
+ /// Logger for diagnostics.
/// The workspace path if infinite sessions are enabled.
///
/// This constructor is internal. Use to create sessions.
///
- internal CopilotSession(string sessionId, JsonRpc rpc, string? workspacePath = null)
+ internal CopilotSession(string sessionId, JsonRpc rpc, ILogger logger, string? workspacePath = null)
{
SessionId = sessionId;
_rpc = rpc;
+ _logger = logger;
WorkspacePath = workspacePath;
+
+ // Start the asynchronous processing loop.
+ _ = ProcessEventsAsync();
}
private Task InvokeRpcAsync(string method, object?[]? args, CancellationToken cancellationToken)
@@ -139,12 +154,16 @@ private Task InvokeRpcAsync(string method, object?[]? args, CancellationTo
///
public async Task SendAsync(MessageOptions options, CancellationToken cancellationToken = default)
{
+ var (traceparent, tracestate) = TelemetryHelpers.GetTraceContext();
+
var request = new SendMessageRequest
{
SessionId = SessionId,
Prompt = options.Prompt,
Attachments = options.Attachments,
- Mode = options.Mode
+ Mode = options.Mode,
+ Traceparent = traceparent,
+ Tracestate = tracestate
};
var response = await InvokeRpcAsync(
@@ -186,7 +205,7 @@ public async Task SendAsync(MessageOptions options, CancellationToken ca
CancellationToken cancellationToken = default)
{
var effectiveTimeout = timeout ?? TimeSpan.FromSeconds(60);
- var tcs = new TaskCompletionSource();
+ var tcs = new TaskCompletionSource(TaskCreationOptions.RunContinuationsAsynchronously);
AssistantMessageEvent? lastAssistantMessage = null;
void Handler(SessionEvent evt)
@@ -236,7 +255,9 @@ void Handler(SessionEvent evt)
/// Multiple handlers can be registered and will all receive events.
///
///
- /// Handler exceptions are allowed to propagate so they are not lost.
+ /// Handlers are invoked serially in event-arrival order on a background thread.
+ /// A handler will never be called concurrently with itself or with other handlers
+ /// on the same session.
///
///
///
@@ -259,27 +280,53 @@ void Handler(SessionEvent evt)
///
public IDisposable On(SessionEventHandler handler)
{
- EventHandlers += handler;
- return new ActionDisposable(() => EventHandlers -= handler);
+ ImmutableInterlocked.Update(ref _eventHandlers, array => array.Add(handler));
+ return new ActionDisposable(() => ImmutableInterlocked.Update(ref _eventHandlers, array => array.Remove(handler)));
}
///
- /// Dispatches an event to all registered handlers.
+ /// Enqueues an event for serial dispatch to all registered handlers.
///
/// The session event to dispatch.
///
- /// This method is internal. Handler exceptions are allowed to propagate so they are not lost.
- /// Broadcast request events (external_tool.requested, permission.requested) are handled
- /// internally before being forwarded to user handlers.
+ /// This method is non-blocking. Broadcast request events (external_tool.requested,
+ /// permission.requested) are fired concurrently so that a stalled handler does not
+ /// block event delivery. The event is then placed into an in-memory channel and
+ /// processed by a single background consumer (),
+ /// which guarantees user handlers see events one at a time, in order.
///
internal void DispatchEvent(SessionEvent sessionEvent)
{
- // Handle broadcast request events (protocol v3) before dispatching to user handlers.
- // Fire-and-forget: the response is sent asynchronously via RPC.
- HandleBroadcastEventAsync(sessionEvent);
+ // Fire broadcast work concurrently (fire-and-forget with error logging).
+ // This is done outside the channel so broadcast handlers don't block the
+ // consumer loop — important when a secondary client's handler intentionally
+ // never completes (multi-client permission scenario).
+ _ = HandleBroadcastEventAsync(sessionEvent);
+
+ // Queue the event for serial processing by user handlers.
+ _eventChannel.Writer.TryWrite(sessionEvent);
+ }
- // Reading the field once gives us a snapshot; delegates are immutable.
- EventHandlers?.Invoke(sessionEvent);
+ ///
+ /// Single-reader consumer loop that processes events from the channel.
+ /// Ensures user event handlers are invoked serially and in FIFO order.
+ ///
+ private async Task ProcessEventsAsync()
+ {
+ await foreach (var sessionEvent in _eventChannel.Reader.ReadAllAsync())
+ {
+ foreach (var handler in _eventHandlers)
+ {
+ try
+ {
+ handler(sessionEvent);
+ }
+ catch (Exception ex)
+ {
+ LogEventHandlerError(ex);
+ }
+ }
+ }
}
///
@@ -339,7 +386,7 @@ internal async Task HandlePermissionRequestAsync(JsonEl
};
}
- var request = JsonSerializer.Deserialize(permissionRequestData.GetRawText(), SessionJsonContext.Default.PermissionRequest)
+ var request = JsonSerializer.Deserialize(permissionRequestData.GetRawText(), SessionEventsJsonContext.Default.PermissionRequest)
?? throw new InvalidOperationException("Failed to deserialize permission request");
var invocation = new PermissionInvocation
@@ -355,37 +402,45 @@ internal async Task HandlePermissionRequestAsync(JsonEl
/// Implements the protocol v3 broadcast model where tool calls and permission requests
/// are broadcast as session events to all clients.
///
- private async void HandleBroadcastEventAsync(SessionEvent sessionEvent)
+ private async Task HandleBroadcastEventAsync(SessionEvent sessionEvent)
{
- switch (sessionEvent)
+ try
{
- case ExternalToolRequestedEvent toolEvent:
- {
- var data = toolEvent.Data;
- if (string.IsNullOrEmpty(data.RequestId) || string.IsNullOrEmpty(data.ToolName))
- return;
-
- var tool = GetTool(data.ToolName);
- if (tool is null)
- return; // This client doesn't handle this tool; another client will.
-
- await ExecuteToolAndRespondAsync(data.RequestId, data.ToolName, data.ToolCallId, data.Arguments, tool);
- break;
- }
-
- case PermissionRequestedEvent permEvent:
- {
- var data = permEvent.Data;
- if (string.IsNullOrEmpty(data.RequestId) || data.PermissionRequest is null)
- return;
-
- var handler = _permissionHandler;
- if (handler is null)
- return; // This client doesn't handle permissions; another client will.
-
- await ExecutePermissionAndRespondAsync(data.RequestId, data.PermissionRequest, handler);
- break;
- }
+ switch (sessionEvent)
+ {
+ case ExternalToolRequestedEvent toolEvent:
+ {
+ var data = toolEvent.Data;
+ if (string.IsNullOrEmpty(data.RequestId) || string.IsNullOrEmpty(data.ToolName))
+ return;
+
+ var tool = GetTool(data.ToolName);
+ if (tool is null)
+ return; // This client doesn't handle this tool; another client will.
+
+ using (TelemetryHelpers.RestoreTraceContext(data.Traceparent, data.Tracestate))
+ await ExecuteToolAndRespondAsync(data.RequestId, data.ToolName, data.ToolCallId, data.Arguments, tool);
+ break;
+ }
+
+ case PermissionRequestedEvent permEvent:
+ {
+ var data = permEvent.Data;
+ if (string.IsNullOrEmpty(data.RequestId) || data.PermissionRequest is null)
+ return;
+
+ var handler = _permissionHandler;
+ if (handler is null)
+ return; // This client doesn't handle permissions; another client will.
+
+ await ExecutePermissionAndRespondAsync(data.RequestId, data.PermissionRequest, handler);
+ break;
+ }
+ }
+ }
+ catch (Exception ex) when (ex is not OperationCanceledException)
+ {
+ LogBroadcastHandlerError(ex);
}
}
@@ -457,27 +512,20 @@ private async Task ExecuteToolAndRespondAsync(string requestId, string toolName,
///
/// Executes a permission handler and sends the result back via the HandlePendingPermissionRequest RPC.
///
- private async Task ExecutePermissionAndRespondAsync(string requestId, object permissionRequestData, PermissionRequestHandler handler)
+ private async Task ExecutePermissionAndRespondAsync(string requestId, PermissionRequest permissionRequest, PermissionRequestHandler handler)
{
try
{
- // PermissionRequestedData.PermissionRequest is typed as `object` in generated code,
- // but StreamJsonRpc deserializes it as a JsonElement.
- if (permissionRequestData is not JsonElement permJsonElement)
- {
- throw new InvalidOperationException(
- $"Permission request data must be a {nameof(JsonElement)}; received {permissionRequestData.GetType().Name}");
- }
-
- var request = JsonSerializer.Deserialize(permJsonElement.GetRawText(), SessionJsonContext.Default.PermissionRequest)
- ?? throw new InvalidOperationException("Failed to deserialize permission request");
-
var invocation = new PermissionInvocation
{
SessionId = SessionId
};
- var result = await handler(request, invocation);
+ var result = await handler(permissionRequest, invocation);
+ if (result.Kind == new PermissionRequestResultKind("no-result"))
+ {
+ return;
+ }
await Rpc.Permissions.HandlePendingPermissionRequestAsync(requestId, result);
}
catch (Exception)
@@ -607,6 +655,72 @@ internal void RegisterHooks(SessionHooks hooks)
};
}
+ ///
+ /// Registers transform callbacks for system message sections.
+ ///
+ /// The transform callbacks keyed by section identifier.
+ internal void RegisterTransformCallbacks(Dictionary>>? callbacks)
+ {
+ _transformCallbacksLock.Wait();
+ try
+ {
+ _transformCallbacks = callbacks;
+ }
+ finally
+ {
+ _transformCallbacksLock.Release();
+ }
+ }
+
+ ///
+ /// Handles a systemMessage.transform RPC call from the Copilot CLI.
+ ///
+ /// The raw JSON element containing sections to transform.
+ /// A task that resolves with the transformed sections.
+ internal async Task HandleSystemMessageTransformAsync(JsonElement sections)
+ {
+ Dictionary>>? callbacks;
+ await _transformCallbacksLock.WaitAsync();
+ try
+ {
+ callbacks = _transformCallbacks;
+ }
+ finally
+ {
+ _transformCallbacksLock.Release();
+ }
+
+ var parsed = JsonSerializer.Deserialize(
+ sections.GetRawText(),
+ SessionJsonContext.Default.DictionaryStringSystemMessageTransformSection) ?? new();
+
+ var result = new Dictionary();
+ foreach (var (sectionId, data) in parsed)
+ {
+ Func>? callback = null;
+ callbacks?.TryGetValue(sectionId, out callback);
+
+ if (callback != null)
+ {
+ try
+ {
+ var transformed = await callback(data.Content ?? "");
+ result[sectionId] = new SystemMessageTransformSection { Content = transformed };
+ }
+ catch
+ {
+ result[sectionId] = new SystemMessageTransformSection { Content = data.Content ?? "" };
+ }
+ }
+ else
+ {
+ result[sectionId] = new SystemMessageTransformSection { Content = data.Content ?? "" };
+ }
+ }
+
+ return new SystemMessageTransformRpcResponse { Sections = result };
+ }
+
///
/// Gets the complete list of messages and events in the session.
///
@@ -674,15 +788,48 @@ await InvokeRpcAsync