{"owner":"github","repo":"copilot-sdk","hasSkills":true,"totalSkillsCount":3,"totalTokensCount":3970,"categories":["root-instruction"],"hasMcp":false,"mcpConfig":null,"found":["docs/AGENTS.md","java/AGENTS.md","rust/AGENTS.md"],"skills":{"docs/AGENTS.md":"# Copilot SDK docs style guide\n\nThis style guide applies to all documentation in the `docs/` directory. These docs are synced to `github/docs-internal` via a normalization pipeline, so they must follow the conventions below to be compatible with docs.github.com.\n\n## Headings\n\nUse **sentence case** for all headings. Capitalize only the first word and proper nouns.\n\n* `## Quick start: Microsoft Foundry` — not `## Quick Start: Microsoft Foundry`\n* `# Custom agents and sub-agent orchestration` — not `# Custom Agents & Sub-Agent Orchestration`\n\nUse `and` instead of `&` in headings.\n\nDo not use `**bold**` or `*italic*` markers inside headings. The heading level provides emphasis.\n\n### Proper nouns to always capitalize\n\n* Products/companies: GitHub, Copilot, Azure, OpenAI, Anthropic, Microsoft, Ollama, Slack, Foundry, Kubernetes, Docker\n* Languages/frameworks: TypeScript, JavaScript, Python, Java, Node.js, OpenTelemetry, Express\n* Platforms: macOS, Linux, Windows\n* Protocols/formats: OAuth, JSON-RPC, JSON, YAML, HTTP, TCP, SSE, REST\n* Acronyms: MCP, BYOK, MAF, SDK, CLI, API, HMAC, CI/CD, SaaS, ISV, FAQ, LLM, AI, EMU, ID, UI, PNG\n* Tools (keep canonical casing): npm, npx, stdio\n* Code identifiers in headings: SessionConfig, MessageOptions, TelemetryConfig, ProviderConfig, CopilotClient\n* Multi-word proper names: GitHub App, GitHub Actions, GitHub OAuth, Foundry Local, Managed Identity, Container Instances\n\n## Callouts\n\nUse GitHub-flavored alert syntax:\n\n```markdown\n> [!NOTE]\n> This is a note.\n\n> [!TIP]\n> This is a tip.\n\n> [!WARNING]\n> This is a warning.\n```\n\nNever use `> **Note:**` or `> **Tip:**` style callouts.\n\nWhen a callout applies to a specific language, put the qualifier as bold text in the body:\n\n```markdown\n> [!TIP]\n> **(Python / Go)** These SDKs use separate, per-event data types.\n```\n\n## Lists\n\n### Unordered lists\n\nUse `*` (asterisks) for unordered list markers, not `-` (hyphens).\n\n### Ordered lists\n\nUse `1.` for every item in ordered lists, not sequential numbering. This makes reordering easier.\n\n```markdown\n1. First step\n1. Second step\n1. Third step\n```\n\n### List item formatting\n\n* Capitalize the first letter of each list item.\n* Use periods only if the item is a complete sentence.\n* Introduce lists with a descriptive sentence, not vague phrases like \"the following\" in isolation.\n\n## Em dashes\n\nFor list items with a **label and description**, use a colon:\n\n```markdown\n* **Ephemeral**: not persisted to disk, not replayed on session resume\n```\n\nFor em dashes used mid-sentence, use no spaces:\n\n```markdown\nThe SDK is a transport layer—it sends your prompt to the CLI over JSON-RPC.\n```\n\n## Horizontal rules\n\nDo not use `---` as a horizontal rule to visually separate sections in the body of an article. Use headings to separate sections instead. This does not apply to YAML frontmatter delimiters.\n\n## Index.md files\n\nIn the docs pipeline, `index.md` files become YAML-only category pages. Rich content (prose, code samples, diagrams) must live in standalone files.\n\nIf you are writing a new section with substantive content, create a named file (for example, `choosing-a-setup-path.md`) rather than putting the content in `index.md`.\n\n## Code snippets\n\n* Only modify code block contents when necessary. From `<SDK_ROOT>`, run the\n  relevant `npm run docs:<language>` validator for Node.js, Python, Go, .NET,\n  or Java. Rust has no `docs:rust` facade; validate its API documentation with\n  `cd rust && DOCS_RS=1 cargo doc --no-deps --all-features` and follow\n  `rust/README.md`. Keep using `docs-validate: skip` or\n  `docs-validate: hidden` markers when appropriate.\n\n## Voice and tone\n\n* Use clear, simple language approachable for a wide range of readers.\n* Use active voice whenever possible.\n* Avoid idioms, slang, and region-specific phrases.\n* Avoid ambiguous modal verbs (\"may\", \"might\", \"should\", \"could\") when an action is required. Use definitive verbs instead.\n* Refer to people as \"people\" or \"users\", not \"customers.\"\n\n## Emphasis\n\n* Use **bold** for UI elements and for emphasis, sparingly (no more than five contiguous words).\n* Do not bold text that already has other formatting (for example, all-caps placeholders).\n\n## Word choice\n\n| Use | Avoid |\n|---|---|\n| terminal | shell |\n| sign in | log in, login |\n| sign up | signup |\n| email | e-mail |\n| press (a key) | hit, tap |\n| repository | repo |\n| administrator | admin |\n| for example | e.g. |\n| and similar | etc. |\n\n## What the pipeline handles\n\nAuthors do not need to worry about these — the normalization pipeline handles them automatically:\n\n* YAML frontmatter (added to files for docs.github.com)\n* Mermaid diagram → PNG conversion\n* Link rewriting for docs.github.com cross-references\n* Liquid variable substitution (product names)\n* `[AUTOTITLE]` link conversion\n\n## New article template\n\nWhen creating a new docs article, use this structure:\n\n```markdown\n# Article title in sentence case\n\nA one- or two-sentence intro explaining what the reader will learn or accomplish.\n\n## First section\n\nBody text here.\n\n## Second section\n\nBody text here.\n\n## Further reading\n\n* [Link text](./relative-path.md): short description\n```\n\n## Multi-language code examples\n\nWhen showing the same concept in multiple programming languages, use consecutive `<details>` blocks. The docs-internal normalization pipeline converts these into tabbed language switchers on docs.github.com.\n\n### Rules\n\n* **Only code inside `<details>` blocks.** Shared prose, headings, and explanations must go outside the blocks. Each block should contain only a code fence (and optionally a `<!-- docs-validate: skip -->` comment).\n* **Blocks must be consecutive.** No content (headings, paragraphs) between `<details>` blocks in the same group. Blank lines between blocks are fine.\n* **Use the exact `<summary>` format:** `<summary><strong>LANGUAGE</strong></summary>`. Supported labels: `.NET`, `Python`, `TypeScript`, `Go`, `Java`, `Rust`, `Node.js`, `Shell`.\n* **Need 2+ blocks to form a group.** A single `<details>` block won't be converted and renders as raw HTML on docs.github.com.\n* **Equal content across tabs.** Each tab should show the same concept in a different language. Language-specific extras should be a separate section outside the tabs.\n\n### Correct\n\nShared prose goes above the group, then each `<details>` block contains only code:\n\n```markdown\nInstall the SDK:\n\n<details open>\n<summary><strong>.NET</strong></summary>\n\n<!-- docs-validate: skip -->\n\n```bash\ndotnet add package GitHub.Copilot.SDK\n```\n\n</details>\n<details>\n<summary><strong>Python</strong></summary>\n\n<!-- docs-validate: skip -->\n\n```bash\npip install github-copilot-sdk\n```\n\n</details>\n```\n\n### Incorrect\n\nDo not put headings, prose, or multiple sections inside a `<details>` block:\n\n```markdown\n<details>\n<summary><strong>Python</strong></summary>\n\n### Prerequisites           ← breaks TOC/anchors\nInstall the packages:       ← prose belongs outside\n\n```bash\npip install github-copilot-sdk\n```\n\n### Basic usage             ← multiple sections in one tab\n```python\n[code]\n```\n\n</details>\n```\n","java/AGENTS.md":"<!-- Copyright (c) Microsoft Corporation. All rights reserved. -->\n\n# Java SDK\n\nThis directory is the Java SDK's Maven reactor. Paths and commands below are\nrelative to this directory, whether it is nested at `src/sdk/java` or exported\nas `java`. Keep API usage examples in [README.md](README.md), the\n[SDK documentation](../docs/getting-started.md), and public Javadoc rather than\nduplicating them in these contributor instructions.\n\n## Layout and compatibility\n\n- `sdk/src/main/java/` contains the handwritten client, session, and RPC APIs.\n  `sdk/src/test/java/` contains unit and integration tests.\n- `sdk/src/generated/java/` contains generated protocol and event types.\n- `copilot-native/` packages platform-specific runtime artifacts separately\n  from the pure-Java SDK.\n- Build with **JDK 25 or later**, as required by [sdk/pom.xml](sdk/pom.xml).\n  The base sources target Java 17; Java 25-specific implementations belong in\n  the existing `sdk/src/main/java25/` multi-release overlay. Do not raise the\n  base target or introduce newer APIs into the Java 17 sources.\n\n## API conventions\n\n- Preserve the `CompletableFuture`-based asynchronous API and fluent setters\n  on configuration classes. Preserve wire names and serialization behavior\n  when changing RPC types.\n- Use try-with-resources for `CopilotClient` and `CopilotSession`. Close event\n  and lifecycle subscriptions when no longer needed.\n- Use typed event handlers and the existing `ToolDefinition` and\n  `ToolInvocation` helpers rather than ad hoc wire payloads. Prefer\n  `getArgumentsAs()` for typed tool arguments.\n- Creating and resuming sessions requires a permission handler.\n  `PermissionHandler.APPROVE_ALL` is for scenarios that do not exercise\n  permission decisions; it cannot bypass managed-settings approval.\n- Handle exceptional future completion and `SessionErrorEvent`. Streaming\n  consumers must handle both incremental delta events and final messages.\n- Add Javadoc for public APIs and follow the existing four-space,\n  Spotless/Eclipse formatting. Checkstyle defines the Javadoc checks and\n  exclusions in `sdk/config/checkstyle/checkstyle.xml`.\n\n## Build, format, and test\n\nPrefer the checked-in Maven wrapper (`./mvnw`, or `.\\mvnw.cmd` on Windows).\nFollow [SDK setup](../CONTRIBUTING.md#developing-an-sdk) for the JDK and\nlayout-appropriate Node.js version. Tests use Node.js for the replay harness and\nruntime preparation tooling. Maven's `generate-test-resources` phase installs\ntheir dependencies from the SDK tree. In the runtime repository, prefer\n`npm --prefix <SDK_ROOT> run test:java`; it refreshes the selected schemas and\nJava projection and requests a current host CLI before running the tests.\nDirect Maven commands bypass those prerequisites and are appropriate after\npreparing the checkout, or in the standalone SDK repository.\n\n```bash\n./mvnw clean verify\n./mvnw -pl sdk spotless:apply\n./mvnw -pl sdk spotless:check checkstyle:check\n```\n\nRun `verify` without `-q` or piping through `grep` so failures remain visible.\n`verify` does not run Spotless: apply and check formatting separately for Java\nsource changes. Tests must exercise public APIs, not expose internals solely\nfor tests.\n\nAdd new Java E2E tests for Java SDK surface behavior, not shared runtime\nfunctionality; new SDK-accessible runtime E2Es belong in\n`../nodejs/test/e2e/`. For replay-backed Java integration tests, use the on-demand\n[`sdk-java-e2e-test` skill](../.github/skills/sdk-java-e2e-test/SKILL.md).\nIts snapshot workflow is not required for unrelated\nJava edits. For JDK 17 compatibility testing, run the JDK 25-built artifact on\nJDK 17 without recompiling it, following\n[Development Setup](README.md#development-setup).\n\n## Generated sources\n\nDo not edit `sdk/src/generated/java/` by hand. Update the generator in\n`scripts/codegen/java.ts` when needed. From `<SDK_ROOT>`, regenerate with the\nSDK facade so the runtime layout selects checked-out schemas and the standalone\nlayout selects its pinned release schemas:\n\n```bash\nnpm run generate:java\n```\n\nThe protocol constant `sdk/src/main/java/com/github/copilot/SdkProtocolVersion.java`\nis also generated, despite living outside `src/generated/`. Change the shared\n`<SDK_ROOT>/sdk-protocol-version.json` and run\n`npm --prefix <SDK_ROOT>/nodejs run update:protocol-version` to update all six SDKs.\n\nUse the SDK's selected schema inputs; do not update release-derived CLI pins\nas an incidental part of implementation work.\n","rust/AGENTS.md":"<!-- Copyright (c) Microsoft Corporation. All rights reserved. -->\n\n# Rust SDK\n\nThis directory contains the independent `github-copilot-sdk` crate. In\nstandalone SDK workflows, paths and Cargo commands below are relative to this\ndirectory, and this crate's own lockfile and toolchain apply. When nested at\n`src/sdk/rust`, the runtime CLI consumes the same checked-out sources through\nthe Bazel integration described under Development. The runtime's N-API\narchitecture does not otherwise govern this crate.\n\n## Public API and errors\n\n- Use the existing `Error` and `ErrorKind` in [src/errors.rs](src/errors.rs).\n  Extend that public error contract instead of adding parallel per-module error\n  types or returning `anyhow::Error` from library APIs.\n- Treat exported types, builders, and trait signatures as a consumer-facing\n  contract. Adding a required field to a public struct can break callers'\n  struct literals; preserve compatibility with existing construction patterns.\n- Document public APIs with rustdoc. Keep cross-language parity notes in\n  [README.md](README.md), rather than repeating comparisons to other SDKs on\n  individual symbols.\n\n## Extension points and session lifetime\n\n- Use the per-request traits in [src/handler.rs](src/handler.rs), such as\n  `PermissionHandler` with `SessionConfig::with_permission_handler`, and retain\n  their declared `Send + Sync + 'static` contracts.\n- Implement `SessionHooks` in [src/hooks.rs](src/hooks.rs) for lifecycle hooks.\n  Prefer its per-hook methods; `with_hooks` enables hooks on the session.\n- Implement `SystemMessageTransform` in [src/transforms.rs](src/transforms.rs)\n  with `section_ids` and `transform_section`, and register it through\n  `with_system_message_transform`.\n- Attach a `ToolHandler` to a `Tool` with `with_handler`, then register tools\n  with `with_tools`. The `derive` feature exposes `define_tool` and `schema_for`\n  for typed tool parameters. Use the current examples in\n  [src/tool.rs](src/tool.rs), not hand-built JSON wire payloads.\n- `EventSubscription` and `LifecycleSubscription` are streams; dropping a\n  subscription unsubscribes. `Session::cancellation_token` returns a child\n  token, so cancelling it must not cancel the parent session. Preserve these\n  ownership and cancellation semantics when changing event dispatch.\n- `ApproveAllHandler` is suitable for tests that do not exercise permission or\n  managed-settings behavior. It is not an override for managed approval.\n\n## Generated types\n\nDo not edit `src/generated/` by hand. The generator is\n`../scripts/codegen/rust.ts`. From `<SDK_ROOT>`, regenerate with the SDK facade\nso the runtime layout selects checked-out schemas and the standalone layout\nselects its pinned release schemas:\n\n```bash\nnpm run generate:rust\n```\n\nKeep handwritten consumer-facing types in `src/types.rs` when the wire types\ncannot express the public API, rather than patching generated output. Changes\nto release-derived CLI pins and schema inputs belong to the release process,\nnot incidental SDK implementation work.\n\n## Development\n\nIn the runtime repository, prefer `npm --prefix <SDK_ROOT> run test:rust`; it\nrefreshes the selected schemas and Rust projection and requests a current host\nCLI before running the tests. Direct Cargo commands bypass those prerequisites\nand the facade's environment applies only to its child process; it does not\npersist for later shell commands. The CLI consumes this crate through the\nsame-checkout `//src/sdk/rust:github-copilot-sdk-local-runtime` Bazel target,\nwith default features disabled. That `local-runtime` mode enables in-process\ntransport without SDK-managed acquisition because the CLI supplies its loaded\n`runtime.node`; `bundled-cli` takes precedence in all-feature builds.\n\nUse this crate's `rust-toolchain.toml`, `Cargo.toml`, and rustfmt configuration,\nnot the runtime workspace's. See [README.md#development](README.md#development)\nfor Node and replay-harness prerequisites. Cargo restores Rust dependencies.\nThe following direct Cargo commands are standalone SDK repository commands and\nuse its published/bundled acquisition semantics:\n\n```bash\ncargo check --all-features\ncargo test --features test-support\ncargo clippy --all-targets --all-features -- -D warnings\ncargo +nightly-2026-04-14 fmt --all -- --config-path .rustfmt.nightly.toml --check\n```\n\nFor changes to the CLI's SDK consumer path, run the repository's Bazel tests\nfrom the runtime root:\n\n```bash\npnpm bazel test //src/native/cli-runtime:cli-native-runtime_test //src/native/cli-runtime:runtime_sibling_resolution //src/native/cli-runtime:typed_sdk_call\n```\n\nDo not restore a repository-wide `COPILOT_SKIP_CLI_DOWNLOAD`. For focused\nsame-checkout compilation from this directory, use:\n\n```bash\ncargo check --no-default-features --features local-runtime\n```\n\nRun it with `COPILOT_SKIP_CLI_DOWNLOAD` unset. Tests that start the runtime must\nalso set `COPILOT_CLI_PATH` to the prepared same-checkout wrapper.\n\nKeep unit tests in external test-only modules: `foo.rs` declares\n`#[cfg(test)] mod tests;`, and its tests live in `foo/tests.rs`. Crate roots\nsuch as `lib.rs` use a sibling `tests.rs`; descriptive module names keep their\ncorresponding file names. Start each test-only file with `#![cfg(test)]`.\nKeep integration tests in `tests/`. Integration tests needing SDK test helpers\nuse the `test-support` feature because the library is compiled without\n`cfg(test)`.\n\nDefault features bundle the CLI; disabling them changes what must be provided\nexternally. For transport-specific E2E settings, bundled-runtime checks, and\nthe full platform matrix, follow the\n[Rust SDK workflow](../.github/workflows/sdk-rust.yml). A local unit test\nrun does not replace those checks.\n"},"files":{"docs/AGENTS.md":"# Copilot SDK docs style guide\n\nThis style guide applies to all documentation in the `docs/` directory. These docs are synced to `github/docs-internal` via a normalization pipeline, so they must follow the conventions below to be compatible with docs.github.com.\n\n## Headings\n\nUse **sentence case** for all headings. Capitalize only the first word and proper nouns.\n\n* `## Quick start: Microsoft Foundry` — not `## Quick Start: Microsoft Foundry`\n* `# Custom agents and sub-agent orchestration` — not `# Custom Agents & Sub-Agent Orchestration`\n\nUse `and` instead of `&` in headings.\n\nDo not use `**bold**` or `*italic*` markers inside headings. The heading level provides emphasis.\n\n### Proper nouns to always capitalize\n\n* Products/companies: GitHub, Copilot, Azure, OpenAI, Anthropic, Microsoft, Ollama, Slack, Foundry, Kubernetes, Docker\n* Languages/frameworks: TypeScript, JavaScript, Python, Java, Node.js, OpenTelemetry, Express\n* Platforms: macOS, Linux, Windows\n* Protocols/formats: OAuth, JSON-RPC, JSON, YAML, HTTP, TCP, SSE, REST\n* Acronyms: MCP, BYOK, MAF, SDK, CLI, API, HMAC, CI/CD, SaaS, ISV, FAQ, LLM, AI, EMU, ID, UI, PNG\n* Tools (keep canonical casing): npm, npx, stdio\n* Code identifiers in headings: SessionConfig, MessageOptions, TelemetryConfig, ProviderConfig, CopilotClient\n* Multi-word proper names: GitHub App, GitHub Actions, GitHub OAuth, Foundry Local, Managed Identity, Container Instances\n\n## Callouts\n\nUse GitHub-flavored alert syntax:\n\n```markdown\n> [!NOTE]\n> This is a note.\n\n> [!TIP]\n> This is a tip.\n\n> [!WARNING]\n> This is a warning.\n```\n\nNever use `> **Note:**` or `> **Tip:**` style callouts.\n\nWhen a callout applies to a specific language, put the qualifier as bold text in the body:\n\n```markdown\n> [!TIP]\n> **(Python / Go)** These SDKs use separate, per-event data types.\n```\n\n## Lists\n\n### Unordered lists\n\nUse `*` (asterisks) for unordered list markers, not `-` (hyphens).\n\n### Ordered lists\n\nUse `1.` for every item in ordered lists, not sequential numbering. This makes reordering easier.\n\n```markdown\n1. First step\n1. Second step\n1. Third step\n```\n\n### List item formatting\n\n* Capitalize the first letter of each list item.\n* Use periods only if the item is a complete sentence.\n* Introduce lists with a descriptive sentence, not vague phrases like \"the following\" in isolation.\n\n## Em dashes\n\nFor list items with a **label and description**, use a colon:\n\n```markdown\n* **Ephemeral**: not persisted to disk, not replayed on session resume\n```\n\nFor em dashes used mid-sentence, use no spaces:\n\n```markdown\nThe SDK is a transport layer—it sends your prompt to the CLI over JSON-RPC.\n```\n\n## Horizontal rules\n\nDo not use `---` as a horizontal rule to visually separate sections in the body of an article. Use headings to separate sections instead. This does not apply to YAML frontmatter delimiters.\n\n## Index.md files\n\nIn the docs pipeline, `index.md` files become YAML-only category pages. Rich content (prose, code samples, diagrams) must live in standalone files.\n\nIf you are writing a new section with substantive content, create a named file (for example, `choosing-a-setup-path.md`) rather than putting the content in `index.md`.\n\n## Code snippets\n\n* Only modify code block contents when necessary. From `<SDK_ROOT>`, run the\n  relevant `npm run docs:<language>` validator for Node.js, Python, Go, .NET,\n  or Java. Rust has no `docs:rust` facade; validate its API documentation with\n  `cd rust && DOCS_RS=1 cargo doc --no-deps --all-features` and follow\n  `rust/README.md`. Keep using `docs-validate: skip` or\n  `docs-validate: hidden` markers when appropriate.\n\n## Voice and tone\n\n* Use clear, simple language approachable for a wide range of readers.\n* Use active voice whenever possible.\n* Avoid idioms, slang, and region-specific phrases.\n* Avoid ambiguous modal verbs (\"may\", \"might\", \"should\", \"could\") when an action is required. Use definitive verbs instead.\n* Refer to people as \"people\" or \"users\", not \"customers.\"\n\n## Emphasis\n\n* Use **bold** for UI elements and for emphasis, sparingly (no more than five contiguous words).\n* Do not bold text that already has other formatting (for example, all-caps placeholders).\n\n## Word choice\n\n| Use | Avoid |\n|---|---|\n| terminal | shell |\n| sign in | log in, login |\n| sign up | signup |\n| email | e-mail |\n| press (a key) | hit, tap |\n| repository | repo |\n| administrator | admin |\n| for example | e.g. |\n| and similar | etc. |\n\n## What the pipeline handles\n\nAuthors do not need to worry about these — the normalization pipeline handles them automatically:\n\n* YAML frontmatter (added to files for docs.github.com)\n* Mermaid diagram → PNG conversion\n* Link rewriting for docs.github.com cross-references\n* Liquid variable substitution (product names)\n* `[AUTOTITLE]` link conversion\n\n## New article template\n\nWhen creating a new docs article, use this structure:\n\n```markdown\n# Article title in sentence case\n\nA one- or two-sentence intro explaining what the reader will learn or accomplish.\n\n## First section\n\nBody text here.\n\n## Second section\n\nBody text here.\n\n## Further reading\n\n* [Link text](./relative-path.md): short description\n```\n\n## Multi-language code examples\n\nWhen showing the same concept in multiple programming languages, use consecutive `<details>` blocks. The docs-internal normalization pipeline converts these into tabbed language switchers on docs.github.com.\n\n### Rules\n\n* **Only code inside `<details>` blocks.** Shared prose, headings, and explanations must go outside the blocks. Each block should contain only a code fence (and optionally a `<!-- docs-validate: skip -->` comment).\n* **Blocks must be consecutive.** No content (headings, paragraphs) between `<details>` blocks in the same group. Blank lines between blocks are fine.\n* **Use the exact `<summary>` format:** `<summary><strong>LANGUAGE</strong></summary>`. Supported labels: `.NET`, `Python`, `TypeScript`, `Go`, `Java`, `Rust`, `Node.js`, `Shell`.\n* **Need 2+ blocks to form a group.** A single `<details>` block won't be converted and renders as raw HTML on docs.github.com.\n* **Equal content across tabs.** Each tab should show the same concept in a different language. Language-specific extras should be a separate section outside the tabs.\n\n### Correct\n\nShared prose goes above the group, then each `<details>` block contains only code:\n\n```markdown\nInstall the SDK:\n\n<details open>\n<summary><strong>.NET</strong></summary>\n\n<!-- docs-validate: skip -->\n\n```bash\ndotnet add package GitHub.Copilot.SDK\n```\n\n</details>\n<details>\n<summary><strong>Python</strong></summary>\n\n<!-- docs-validate: skip -->\n\n```bash\npip install github-copilot-sdk\n```\n\n</details>\n```\n\n### Incorrect\n\nDo not put headings, prose, or multiple sections inside a `<details>` block:\n\n```markdown\n<details>\n<summary><strong>Python</strong></summary>\n\n### Prerequisites           ← breaks TOC/anchors\nInstall the packages:       ← prose belongs outside\n\n```bash\npip install github-copilot-sdk\n```\n\n### Basic usage             ← multiple sections in one tab\n```python\n[code]\n```\n\n</details>\n```\n","java/AGENTS.md":"<!-- Copyright (c) Microsoft Corporation. All rights reserved. -->\n\n# Java SDK\n\nThis directory is the Java SDK's Maven reactor. Paths and commands below are\nrelative to this directory, whether it is nested at `src/sdk/java` or exported\nas `java`. Keep API usage examples in [README.md](README.md), the\n[SDK documentation](../docs/getting-started.md), and public Javadoc rather than\nduplicating them in these contributor instructions.\n\n## Layout and compatibility\n\n- `sdk/src/main/java/` contains the handwritten client, session, and RPC APIs.\n  `sdk/src/test/java/` contains unit and integration tests.\n- `sdk/src/generated/java/` contains generated protocol and event types.\n- `copilot-native/` packages platform-specific runtime artifacts separately\n  from the pure-Java SDK.\n- Build with **JDK 25 or later**, as required by [sdk/pom.xml](sdk/pom.xml).\n  The base sources target Java 17; Java 25-specific implementations belong in\n  the existing `sdk/src/main/java25/` multi-release overlay. Do not raise the\n  base target or introduce newer APIs into the Java 17 sources.\n\n## API conventions\n\n- Preserve the `CompletableFuture`-based asynchronous API and fluent setters\n  on configuration classes. Preserve wire names and serialization behavior\n  when changing RPC types.\n- Use try-with-resources for `CopilotClient` and `CopilotSession`. Close event\n  and lifecycle subscriptions when no longer needed.\n- Use typed event handlers and the existing `ToolDefinition` and\n  `ToolInvocation` helpers rather than ad hoc wire payloads. Prefer\n  `getArgumentsAs()` for typed tool arguments.\n- Creating and resuming sessions requires a permission handler.\n  `PermissionHandler.APPROVE_ALL` is for scenarios that do not exercise\n  permission decisions; it cannot bypass managed-settings approval.\n- Handle exceptional future completion and `SessionErrorEvent`. Streaming\n  consumers must handle both incremental delta events and final messages.\n- Add Javadoc for public APIs and follow the existing four-space,\n  Spotless/Eclipse formatting. Checkstyle defines the Javadoc checks and\n  exclusions in `sdk/config/checkstyle/checkstyle.xml`.\n\n## Build, format, and test\n\nPrefer the checked-in Maven wrapper (`./mvnw`, or `.\\mvnw.cmd` on Windows).\nFollow [SDK setup](../CONTRIBUTING.md#developing-an-sdk) for the JDK and\nlayout-appropriate Node.js version. Tests use Node.js for the replay harness and\nruntime preparation tooling. Maven's `generate-test-resources` phase installs\ntheir dependencies from the SDK tree. In the runtime repository, prefer\n`npm --prefix <SDK_ROOT> run test:java`; it refreshes the selected schemas and\nJava projection and requests a current host CLI before running the tests.\nDirect Maven commands bypass those prerequisites and are appropriate after\npreparing the checkout, or in the standalone SDK repository.\n\n```bash\n./mvnw clean verify\n./mvnw -pl sdk spotless:apply\n./mvnw -pl sdk spotless:check checkstyle:check\n```\n\nRun `verify` without `-q` or piping through `grep` so failures remain visible.\n`verify` does not run Spotless: apply and check formatting separately for Java\nsource changes. Tests must exercise public APIs, not expose internals solely\nfor tests.\n\nAdd new Java E2E tests for Java SDK surface behavior, not shared runtime\nfunctionality; new SDK-accessible runtime E2Es belong in\n`../nodejs/test/e2e/`. For replay-backed Java integration tests, use the on-demand\n[`sdk-java-e2e-test` skill](../.github/skills/sdk-java-e2e-test/SKILL.md).\nIts snapshot workflow is not required for unrelated\nJava edits. For JDK 17 compatibility testing, run the JDK 25-built artifact on\nJDK 17 without recompiling it, following\n[Development Setup](README.md#development-setup).\n\n## Generated sources\n\nDo not edit `sdk/src/generated/java/` by hand. Update the generator in\n`scripts/codegen/java.ts` when needed. From `<SDK_ROOT>`, regenerate with the\nSDK facade so the runtime layout selects checked-out schemas and the standalone\nlayout selects its pinned release schemas:\n\n```bash\nnpm run generate:java\n```\n\nThe protocol constant `sdk/src/main/java/com/github/copilot/SdkProtocolVersion.java`\nis also generated, despite living outside `src/generated/`. Change the shared\n`<SDK_ROOT>/sdk-protocol-version.json` and run\n`npm --prefix <SDK_ROOT>/nodejs run update:protocol-version` to update all six SDKs.\n\nUse the SDK's selected schema inputs; do not update release-derived CLI pins\nas an incidental part of implementation work.\n","rust/AGENTS.md":"<!-- Copyright (c) Microsoft Corporation. All rights reserved. -->\n\n# Rust SDK\n\nThis directory contains the independent `github-copilot-sdk` crate. In\nstandalone SDK workflows, paths and Cargo commands below are relative to this\ndirectory, and this crate's own lockfile and toolchain apply. When nested at\n`src/sdk/rust`, the runtime CLI consumes the same checked-out sources through\nthe Bazel integration described under Development. The runtime's N-API\narchitecture does not otherwise govern this crate.\n\n## Public API and errors\n\n- Use the existing `Error` and `ErrorKind` in [src/errors.rs](src/errors.rs).\n  Extend that public error contract instead of adding parallel per-module error\n  types or returning `anyhow::Error` from library APIs.\n- Treat exported types, builders, and trait signatures as a consumer-facing\n  contract. Adding a required field to a public struct can break callers'\n  struct literals; preserve compatibility with existing construction patterns.\n- Document public APIs with rustdoc. Keep cross-language parity notes in\n  [README.md](README.md), rather than repeating comparisons to other SDKs on\n  individual symbols.\n\n## Extension points and session lifetime\n\n- Use the per-request traits in [src/handler.rs](src/handler.rs), such as\n  `PermissionHandler` with `SessionConfig::with_permission_handler`, and retain\n  their declared `Send + Sync + 'static` contracts.\n- Implement `SessionHooks` in [src/hooks.rs](src/hooks.rs) for lifecycle hooks.\n  Prefer its per-hook methods; `with_hooks` enables hooks on the session.\n- Implement `SystemMessageTransform` in [src/transforms.rs](src/transforms.rs)\n  with `section_ids` and `transform_section`, and register it through\n  `with_system_message_transform`.\n- Attach a `ToolHandler` to a `Tool` with `with_handler`, then register tools\n  with `with_tools`. The `derive` feature exposes `define_tool` and `schema_for`\n  for typed tool parameters. Use the current examples in\n  [src/tool.rs](src/tool.rs), not hand-built JSON wire payloads.\n- `EventSubscription` and `LifecycleSubscription` are streams; dropping a\n  subscription unsubscribes. `Session::cancellation_token` returns a child\n  token, so cancelling it must not cancel the parent session. Preserve these\n  ownership and cancellation semantics when changing event dispatch.\n- `ApproveAllHandler` is suitable for tests that do not exercise permission or\n  managed-settings behavior. It is not an override for managed approval.\n\n## Generated types\n\nDo not edit `src/generated/` by hand. The generator is\n`../scripts/codegen/rust.ts`. From `<SDK_ROOT>`, regenerate with the SDK facade\nso the runtime layout selects checked-out schemas and the standalone layout\nselects its pinned release schemas:\n\n```bash\nnpm run generate:rust\n```\n\nKeep handwritten consumer-facing types in `src/types.rs` when the wire types\ncannot express the public API, rather than patching generated output. Changes\nto release-derived CLI pins and schema inputs belong to the release process,\nnot incidental SDK implementation work.\n\n## Development\n\nIn the runtime repository, prefer `npm --prefix <SDK_ROOT> run test:rust`; it\nrefreshes the selected schemas and Rust projection and requests a current host\nCLI before running the tests. Direct Cargo commands bypass those prerequisites\nand the facade's environment applies only to its child process; it does not\npersist for later shell commands. The CLI consumes this crate through the\nsame-checkout `//src/sdk/rust:github-copilot-sdk-local-runtime` Bazel target,\nwith default features disabled. That `local-runtime` mode enables in-process\ntransport without SDK-managed acquisition because the CLI supplies its loaded\n`runtime.node`; `bundled-cli` takes precedence in all-feature builds.\n\nUse this crate's `rust-toolchain.toml`, `Cargo.toml`, and rustfmt configuration,\nnot the runtime workspace's. See [README.md#development](README.md#development)\nfor Node and replay-harness prerequisites. Cargo restores Rust dependencies.\nThe following direct Cargo commands are standalone SDK repository commands and\nuse its published/bundled acquisition semantics:\n\n```bash\ncargo check --all-features\ncargo test --features test-support\ncargo clippy --all-targets --all-features -- -D warnings\ncargo +nightly-2026-04-14 fmt --all -- --config-path .rustfmt.nightly.toml --check\n```\n\nFor changes to the CLI's SDK consumer path, run the repository's Bazel tests\nfrom the runtime root:\n\n```bash\npnpm bazel test //src/native/cli-runtime:cli-native-runtime_test //src/native/cli-runtime:runtime_sibling_resolution //src/native/cli-runtime:typed_sdk_call\n```\n\nDo not restore a repository-wide `COPILOT_SKIP_CLI_DOWNLOAD`. For focused\nsame-checkout compilation from this directory, use:\n\n```bash\ncargo check --no-default-features --features local-runtime\n```\n\nRun it with `COPILOT_SKIP_CLI_DOWNLOAD` unset. Tests that start the runtime must\nalso set `COPILOT_CLI_PATH` to the prepared same-checkout wrapper.\n\nKeep unit tests in external test-only modules: `foo.rs` declares\n`#[cfg(test)] mod tests;`, and its tests live in `foo/tests.rs`. Crate roots\nsuch as `lib.rs` use a sibling `tests.rs`; descriptive module names keep their\ncorresponding file names. Start each test-only file with `#![cfg(test)]`.\nKeep integration tests in `tests/`. Integration tests needing SDK test helpers\nuse the `test-support` feature because the library is compiled without\n`cfg(test)`.\n\nDefault features bundle the CLI; disabling them changes what must be provided\nexternally. For transport-specific E2E settings, bundled-runtime checks, and\nthe full platform matrix, follow the\n[Rust SDK workflow](../.github/workflows/sdk-rust.yml). A local unit test\nrun does not replace those checks.\n"},"items":[{"name":"AGENTS.md","path":"docs/AGENTS.md","rawUrl":"https://raw.githubusercontent.com/github/copilot-sdk/HEAD/docs/AGENTS.md","title":"docs - AI Agent Protocol & Instructions","category":"root-instruction","format":"markdown","content":"# Copilot SDK docs style guide\n\nThis style guide applies to all documentation in the `docs/` directory. These docs are synced to `github/docs-internal` via a normalization pipeline, so they must follow the conventions below to be compatible with docs.github.com.\n\n## Headings\n\nUse **sentence case** for all headings. Capitalize only the first word and proper nouns.\n\n* `## Quick start: Microsoft Foundry` — not `## Quick Start: Microsoft Foundry`\n* `# Custom agents and sub-agent orchestration` — not `# Custom Agents & Sub-Agent Orchestration`\n\nUse `and` instead of `&` in headings.\n\nDo not use `**bold**` or `*italic*` markers inside headings. The heading level provides emphasis.\n\n### Proper nouns to always capitalize\n\n* Products/companies: GitHub, Copilot, Azure, OpenAI, Anthropic, Microsoft, Ollama, Slack, Foundry, Kubernetes, Docker\n* Languages/frameworks: TypeScript, JavaScript, Python, Java, Node.js, OpenTelemetry, Express\n* Platforms: macOS, Linux, Windows\n* Protocols/formats: OAuth, JSON-RPC, JSON, YAML, HTTP, TCP, SSE, REST\n* Acronyms: MCP, BYOK, MAF, SDK, CLI, API, HMAC, CI/CD, SaaS, ISV, FAQ, LLM, AI, EMU, ID, UI, PNG\n* Tools (keep canonical casing): npm, npx, stdio\n* Code identifiers in headings: SessionConfig, MessageOptions, TelemetryConfig, ProviderConfig, CopilotClient\n* Multi-word proper names: GitHub App, GitHub Actions, GitHub OAuth, Foundry Local, Managed Identity, Container Instances\n\n## Callouts\n\nUse GitHub-flavored alert syntax:\n\n```markdown\n> [!NOTE]\n> This is a note.\n\n> [!TIP]\n> This is a tip.\n\n> [!WARNING]\n> This is a warning.\n```\n\nNever use `> **Note:**` or `> **Tip:**` style callouts.\n\nWhen a callout applies to a specific language, put the qualifier as bold text in the body:\n\n```markdown\n> [!TIP]\n> **(Python / Go)** These SDKs use separate, per-event data types.\n```\n\n## Lists\n\n### Unordered lists\n\nUse `*` (asterisks) for unordered list markers, not `-` (hyphens).\n\n### Ordered lists\n\nUse `1.` for every item in ordered lists, not sequential numbering. This makes reordering easier.\n\n```markdown\n1. First step\n1. Second step\n1. Third step\n```\n\n### List item formatting\n\n* Capitalize the first letter of each list item.\n* Use periods only if the item is a complete sentence.\n* Introduce lists with a descriptive sentence, not vague phrases like \"the following\" in isolation.\n\n## Em dashes\n\nFor list items with a **label and description**, use a colon:\n\n```markdown\n* **Ephemeral**: not persisted to disk, not replayed on session resume\n```\n\nFor em dashes used mid-sentence, use no spaces:\n\n```markdown\nThe SDK is a transport layer—it sends your prompt to the CLI over JSON-RPC.\n```\n\n## Horizontal rules\n\nDo not use `---` as a horizontal rule to visually separate sections in the body of an article. Use headings to separate sections instead. This does not apply to YAML frontmatter delimiters.\n\n## Index.md files\n\nIn the docs pipeline, `index.md` files become YAML-only category pages. Rich content (prose, code samples, diagrams) must live in standalone files.\n\nIf you are writing a new section with substantive content, create a named file (for example, `choosing-a-setup-path.md`) rather than putting the content in `index.md`.\n\n## Code snippets\n\n* Only modify code block contents when necessary. From `<SDK_ROOT>`, run the\n  relevant `npm run docs:<language>` validator for Node.js, Python, Go, .NET,\n  or Java. Rust has no `docs:rust` facade; validate its API documentation with\n  `cd rust && DOCS_RS=1 cargo doc --no-deps --all-features` and follow\n  `rust/README.md`. Keep using `docs-validate: skip` or\n  `docs-validate: hidden` markers when appropriate.\n\n## Voice and tone\n\n* Use clear, simple language approachable for a wide range of readers.\n* Use active voice whenever possible.\n* Avoid idioms, slang, and region-specific phrases.\n* Avoid ambiguous modal verbs (\"may\", \"might\", \"should\", \"could\") when an action is required. Use definitive verbs instead.\n* Refer to people as \"people\" or \"users\", not \"customers.\"\n\n## Emphasis\n\n* Use **bold** for UI elements and for emphasis, sparingly (no more than five contiguous words).\n* Do not bold text that already has other formatting (for example, all-caps placeholders).\n\n## Word choice\n\n| Use | Avoid |\n|---|---|\n| terminal | shell |\n| sign in | log in, login |\n| sign up | signup |\n| email | e-mail |\n| press (a key) | hit, tap |\n| repository | repo |\n| administrator | admin |\n| for example | e.g. |\n| and similar | etc. |\n\n## What the pipeline handles\n\nAuthors do not need to worry about these — the normalization pipeline handles them automatically:\n\n* YAML frontmatter (added to files for docs.github.com)\n* Mermaid diagram → PNG conversion\n* Link rewriting for docs.github.com cross-references\n* Liquid variable substitution (product names)\n* `[AUTOTITLE]` link conversion\n\n## New article template\n\nWhen creating a new docs article, use this structure:\n\n```markdown\n# Article title in sentence case\n\nA one- or two-sentence intro explaining what the reader will learn or accomplish.\n\n## First section\n\nBody text here.\n\n## Second section\n\nBody text here.\n\n## Further reading\n\n* [Link text](./relative-path.md): short description\n```\n\n## Multi-language code examples\n\nWhen showing the same concept in multiple programming languages, use consecutive `<details>` blocks. The docs-internal normalization pipeline converts these into tabbed language switchers on docs.github.com.\n\n### Rules\n\n* **Only code inside `<details>` blocks.** Shared prose, headings, and explanations must go outside the blocks. Each block should contain only a code fence (and optionally a `<!-- docs-validate: skip -->` comment).\n* **Blocks must be consecutive.** No content (headings, paragraphs) between `<details>` blocks in the same group. Blank lines between blocks are fine.\n* **Use the exact `<summary>` format:** `<summary><strong>LANGUAGE</strong></summary>`. Supported labels: `.NET`, `Python`, `TypeScript`, `Go`, `Java`, `Rust`, `Node.js`, `Shell`.\n* **Need 2+ blocks to form a group.** A single `<details>` block won't be converted and renders as raw HTML on docs.github.com.\n* **Equal content across tabs.** Each tab should show the same concept in a different language. Language-specific extras should be a separate section outside the tabs.\n\n### Correct\n\nShared prose goes above the group, then each `<details>` block contains only code:\n\n```markdown\nInstall the SDK:\n\n<details open>\n<summary><strong>.NET</strong></summary>\n\n<!-- docs-validate: skip -->\n\n```bash\ndotnet add package GitHub.Copilot.SDK\n```\n\n</details>\n<details>\n<summary><strong>Python</strong></summary>\n\n<!-- docs-validate: skip -->\n\n```bash\npip install github-copilot-sdk\n```\n\n</details>\n```\n\n### Incorrect\n\nDo not put headings, prose, or multiple sections inside a `<details>` block:\n\n```markdown\n<details>\n<summary><strong>Python</strong></summary>\n\n### Prerequisites           ← breaks TOC/anchors\nInstall the packages:       ← prose belongs outside\n\n```bash\npip install github-copilot-sdk\n```\n\n### Basic usage             ← multiple sections in one tab\n```python\n[code]\n```\n\n</details>\n```\n","isInternal":false,"tokens":1705,"sizeBytes":7081},{"name":"AGENTS.md","path":"java/AGENTS.md","rawUrl":"https://raw.githubusercontent.com/github/copilot-sdk/HEAD/java/AGENTS.md","title":"java - AI Agent Protocol & Instructions","category":"root-instruction","format":"markdown","content":"<!-- Copyright (c) Microsoft Corporation. All rights reserved. -->\n\n# Java SDK\n\nThis directory is the Java SDK's Maven reactor. Paths and commands below are\nrelative to this directory, whether it is nested at `src/sdk/java` or exported\nas `java`. Keep API usage examples in [README.md](README.md), the\n[SDK documentation](../docs/getting-started.md), and public Javadoc rather than\nduplicating them in these contributor instructions.\n\n## Layout and compatibility\n\n- `sdk/src/main/java/` contains the handwritten client, session, and RPC APIs.\n  `sdk/src/test/java/` contains unit and integration tests.\n- `sdk/src/generated/java/` contains generated protocol and event types.\n- `copilot-native/` packages platform-specific runtime artifacts separately\n  from the pure-Java SDK.\n- Build with **JDK 25 or later**, as required by [sdk/pom.xml](sdk/pom.xml).\n  The base sources target Java 17; Java 25-specific implementations belong in\n  the existing `sdk/src/main/java25/` multi-release overlay. Do not raise the\n  base target or introduce newer APIs into the Java 17 sources.\n\n## API conventions\n\n- Preserve the `CompletableFuture`-based asynchronous API and fluent setters\n  on configuration classes. Preserve wire names and serialization behavior\n  when changing RPC types.\n- Use try-with-resources for `CopilotClient` and `CopilotSession`. Close event\n  and lifecycle subscriptions when no longer needed.\n- Use typed event handlers and the existing `ToolDefinition` and\n  `ToolInvocation` helpers rather than ad hoc wire payloads. Prefer\n  `getArgumentsAs()` for typed tool arguments.\n- Creating and resuming sessions requires a permission handler.\n  `PermissionHandler.APPROVE_ALL` is for scenarios that do not exercise\n  permission decisions; it cannot bypass managed-settings approval.\n- Handle exceptional future completion and `SessionErrorEvent`. Streaming\n  consumers must handle both incremental delta events and final messages.\n- Add Javadoc for public APIs and follow the existing four-space,\n  Spotless/Eclipse formatting. Checkstyle defines the Javadoc checks and\n  exclusions in `sdk/config/checkstyle/checkstyle.xml`.\n\n## Build, format, and test\n\nPrefer the checked-in Maven wrapper (`./mvnw`, or `.\\mvnw.cmd` on Windows).\nFollow [SDK setup](../CONTRIBUTING.md#developing-an-sdk) for the JDK and\nlayout-appropriate Node.js version. Tests use Node.js for the replay harness and\nruntime preparation tooling. Maven's `generate-test-resources` phase installs\ntheir dependencies from the SDK tree. In the runtime repository, prefer\n`npm --prefix <SDK_ROOT> run test:java`; it refreshes the selected schemas and\nJava projection and requests a current host CLI before running the tests.\nDirect Maven commands bypass those prerequisites and are appropriate after\npreparing the checkout, or in the standalone SDK repository.\n\n```bash\n./mvnw clean verify\n./mvnw -pl sdk spotless:apply\n./mvnw -pl sdk spotless:check checkstyle:check\n```\n\nRun `verify` without `-q` or piping through `grep` so failures remain visible.\n`verify` does not run Spotless: apply and check formatting separately for Java\nsource changes. Tests must exercise public APIs, not expose internals solely\nfor tests.\n\nAdd new Java E2E tests for Java SDK surface behavior, not shared runtime\nfunctionality; new SDK-accessible runtime E2Es belong in\n`../nodejs/test/e2e/`. For replay-backed Java integration tests, use the on-demand\n[`sdk-java-e2e-test` skill](../.github/skills/sdk-java-e2e-test/SKILL.md).\nIts snapshot workflow is not required for unrelated\nJava edits. For JDK 17 compatibility testing, run the JDK 25-built artifact on\nJDK 17 without recompiling it, following\n[Development Setup](README.md#development-setup).\n\n## Generated sources\n\nDo not edit `sdk/src/generated/java/` by hand. Update the generator in\n`scripts/codegen/java.ts` when needed. From `<SDK_ROOT>`, regenerate with the\nSDK facade so the runtime layout selects checked-out schemas and the standalone\nlayout selects its pinned release schemas:\n\n```bash\nnpm run generate:java\n```\n\nThe protocol constant `sdk/src/main/java/com/github/copilot/SdkProtocolVersion.java`\nis also generated, despite living outside `src/generated/`. Change the shared\n`<SDK_ROOT>/sdk-protocol-version.json` and run\n`npm --prefix <SDK_ROOT>/nodejs run update:protocol-version` to update all six SDKs.\n\nUse the SDK's selected schema inputs; do not update release-derived CLI pins\nas an incidental part of implementation work.\n","isInternal":false,"tokens":1004,"sizeBytes":4450},{"name":"AGENTS.md","path":"rust/AGENTS.md","rawUrl":"https://raw.githubusercontent.com/github/copilot-sdk/HEAD/rust/AGENTS.md","title":"rust - AI Agent Protocol & Instructions","category":"root-instruction","format":"markdown","content":"<!-- Copyright (c) Microsoft Corporation. All rights reserved. -->\n\n# Rust SDK\n\nThis directory contains the independent `github-copilot-sdk` crate. In\nstandalone SDK workflows, paths and Cargo commands below are relative to this\ndirectory, and this crate's own lockfile and toolchain apply. When nested at\n`src/sdk/rust`, the runtime CLI consumes the same checked-out sources through\nthe Bazel integration described under Development. The runtime's N-API\narchitecture does not otherwise govern this crate.\n\n## Public API and errors\n\n- Use the existing `Error` and `ErrorKind` in [src/errors.rs](src/errors.rs).\n  Extend that public error contract instead of adding parallel per-module error\n  types or returning `anyhow::Error` from library APIs.\n- Treat exported types, builders, and trait signatures as a consumer-facing\n  contract. Adding a required field to a public struct can break callers'\n  struct literals; preserve compatibility with existing construction patterns.\n- Document public APIs with rustdoc. Keep cross-language parity notes in\n  [README.md](README.md), rather than repeating comparisons to other SDKs on\n  individual symbols.\n\n## Extension points and session lifetime\n\n- Use the per-request traits in [src/handler.rs](src/handler.rs), such as\n  `PermissionHandler` with `SessionConfig::with_permission_handler`, and retain\n  their declared `Send + Sync + 'static` contracts.\n- Implement `SessionHooks` in [src/hooks.rs](src/hooks.rs) for lifecycle hooks.\n  Prefer its per-hook methods; `with_hooks` enables hooks on the session.\n- Implement `SystemMessageTransform` in [src/transforms.rs](src/transforms.rs)\n  with `section_ids` and `transform_section`, and register it through\n  `with_system_message_transform`.\n- Attach a `ToolHandler` to a `Tool` with `with_handler`, then register tools\n  with `with_tools`. The `derive` feature exposes `define_tool` and `schema_for`\n  for typed tool parameters. Use the current examples in\n  [src/tool.rs](src/tool.rs), not hand-built JSON wire payloads.\n- `EventSubscription` and `LifecycleSubscription` are streams; dropping a\n  subscription unsubscribes. `Session::cancellation_token` returns a child\n  token, so cancelling it must not cancel the parent session. Preserve these\n  ownership and cancellation semantics when changing event dispatch.\n- `ApproveAllHandler` is suitable for tests that do not exercise permission or\n  managed-settings behavior. It is not an override for managed approval.\n\n## Generated types\n\nDo not edit `src/generated/` by hand. The generator is\n`../scripts/codegen/rust.ts`. From `<SDK_ROOT>`, regenerate with the SDK facade\nso the runtime layout selects checked-out schemas and the standalone layout\nselects its pinned release schemas:\n\n```bash\nnpm run generate:rust\n```\n\nKeep handwritten consumer-facing types in `src/types.rs` when the wire types\ncannot express the public API, rather than patching generated output. Changes\nto release-derived CLI pins and schema inputs belong to the release process,\nnot incidental SDK implementation work.\n\n## Development\n\nIn the runtime repository, prefer `npm --prefix <SDK_ROOT> run test:rust`; it\nrefreshes the selected schemas and Rust projection and requests a current host\nCLI before running the tests. Direct Cargo commands bypass those prerequisites\nand the facade's environment applies only to its child process; it does not\npersist for later shell commands. The CLI consumes this crate through the\nsame-checkout `//src/sdk/rust:github-copilot-sdk-local-runtime` Bazel target,\nwith default features disabled. That `local-runtime` mode enables in-process\ntransport without SDK-managed acquisition because the CLI supplies its loaded\n`runtime.node`; `bundled-cli` takes precedence in all-feature builds.\n\nUse this crate's `rust-toolchain.toml`, `Cargo.toml`, and rustfmt configuration,\nnot the runtime workspace's. See [README.md#development](README.md#development)\nfor Node and replay-harness prerequisites. Cargo restores Rust dependencies.\nThe following direct Cargo commands are standalone SDK repository commands and\nuse its published/bundled acquisition semantics:\n\n```bash\ncargo check --all-features\ncargo test --features test-support\ncargo clippy --all-targets --all-features -- -D warnings\ncargo +nightly-2026-04-14 fmt --all -- --config-path .rustfmt.nightly.toml --check\n```\n\nFor changes to the CLI's SDK consumer path, run the repository's Bazel tests\nfrom the runtime root:\n\n```bash\npnpm bazel test //src/native/cli-runtime:cli-native-runtime_test //src/native/cli-runtime:runtime_sibling_resolution //src/native/cli-runtime:typed_sdk_call\n```\n\nDo not restore a repository-wide `COPILOT_SKIP_CLI_DOWNLOAD`. For focused\nsame-checkout compilation from this directory, use:\n\n```bash\ncargo check --no-default-features --features local-runtime\n```\n\nRun it with `COPILOT_SKIP_CLI_DOWNLOAD` unset. Tests that start the runtime must\nalso set `COPILOT_CLI_PATH` to the prepared same-checkout wrapper.\n\nKeep unit tests in external test-only modules: `foo.rs` declares\n`#[cfg(test)] mod tests;`, and its tests live in `foo/tests.rs`. Crate roots\nsuch as `lib.rs` use a sibling `tests.rs`; descriptive module names keep their\ncorresponding file names. Start each test-only file with `#![cfg(test)]`.\nKeep integration tests in `tests/`. Integration tests needing SDK test helpers\nuse the `test-support` feature because the library is compiled without\n`cfg(test)`.\n\nDefault features bundle the CLI; disabling them changes what must be provided\nexternally. For transport-specific E2E settings, bundled-runtime checks, and\nthe full platform matrix, follow the\n[Rust SDK workflow](../.github/workflows/sdk-rust.yml). A local unit test\nrun does not replace those checks.\n","isInternal":false,"tokens":1261,"sizeBytes":5707}],"systemPromptSnippet":"<yakaai_skills repo=\"github/copilot-sdk\">\n<!-- File: docs/AGENTS.md (Tokens: ~1705 | Category: root-instruction) -->\n# Copilot SDK docs style guide\n\nThis style guide applies to all documentation in the `docs/` directory. These docs are synced to `github/docs-internal` via a normalization pipeline, so they must follow the conventions below to be compatible with docs.github.com.\n\n## Headings\n\nUse **sentence case** for all headings. Capitalize only the first word and proper nouns.\n\n* `## Quick start: Microsoft Foundry` — not `## Quick Start: Microsoft Foundry`\n* `# Custom agents and sub-agent orchestration` — not `# Custom Agents & Sub-Agent Orchestration`\n\nUse `and` instead of `&` in headings.\n\nDo not use `**bold**` or `*italic*` markers inside headings. The heading level provides emphasis.\n\n### Proper nouns to always capitalize\n\n* Products/companies: GitHub, Copilot, Azure, OpenAI, Anthropic, Microsoft, Ollama, Slack, Foundry, Kubernetes, Docker\n* Languages/frameworks: TypeScript, JavaScript, Python, Java, Node.js, OpenTelemetry, Express\n* Platforms: macOS, Linux, Windows\n* Protocols/formats: OAuth, JSON-RPC, JSON, YAML, HTTP, TCP, SSE, REST\n* Acronyms: MCP, BYOK, MAF, SDK, CLI, API, HMAC, CI/CD, SaaS, ISV, FAQ, LLM, AI, EMU, ID, UI, PNG\n* Tools (keep canonical casing): npm, npx, stdio\n* Code identifiers in headings: SessionConfig, MessageOptions, TelemetryConfig, ProviderConfig, CopilotClient\n* Multi-word proper names: GitHub App, GitHub Actions, GitHub OAuth, Foundry Local, Managed Identity, Container Instances\n\n## Callouts\n\nUse GitHub-flavored alert syntax:\n\n```markdown\n> [!NOTE]\n> This is a note.\n\n> [!TIP]\n> This is a tip.\n\n> [!WARNING]\n> This is a warning.\n```\n\nNever use `> **Note:**` or `> **Tip:**` style callouts.\n\nWhen a callout applies to a specific language, put the qualifier as bold text in the body:\n\n```markdown\n> [!TIP]\n> **(Python / Go)** These SDKs use separate, per-event data types.\n```\n\n## Lists\n\n### Unordered lists\n\nUse `*` (asterisks) for unordered list markers, not `-` (hyphens).\n\n### Ordered lists\n\nUse `1.` for every item in ordered lists, not sequential numbering. This makes reordering easier.\n\n```markdown\n1. First step\n1. Second step\n1. Third step\n```\n\n### List item formatting\n\n* Capitalize the first letter of each list item.\n* Use periods only if the item is a complete sentence.\n* Introduce lists with a descriptive sentence, not vague phrases like \"the following\" in isolation.\n\n## Em dashes\n\nFor list items with a **label and description**, use a colon:\n\n```markdown\n* **Ephemeral**: not persisted to disk, not replayed on session resume\n```\n\nFor em dashes used mid-sentence, use no spaces:\n\n```markdown\nThe SDK is a transport layer—it sends your prompt to the CLI over JSON-RPC.\n```\n\n## Horizontal rules\n\nDo not use `---` as a horizontal rule to visually separate sections in the body of an article. Use headings to separate sections instead. This does not apply to YAML frontmatter delimiters.\n\n## Index.md files\n\nIn the docs pipeline, `index.md` files become YAML-only category pages. Rich content (prose, code samples, diagrams) must live in standalone files.\n\nIf you are writing a new section with substantive content, create a named file (for example, `choosing-a-setup-path.md`) rather than putting the content in `index.md`.\n\n## Code snippets\n\n* Only modify code block contents when necessary. From `<SDK_ROOT>`, run the\n  relevant `npm run docs:<language>` validator for Node.js, Python, Go, .NET,\n  or Java. Rust has no `docs:rust` facade; validate its API documentation with\n  `cd rust && DOCS_RS=1 cargo doc --no-deps --all-features` and follow\n  `rust/README.md`. Keep using `docs-validate: skip` or\n  `docs-validate: hidden` markers when appropriate.\n\n## Voice and tone\n\n* Use clear, simple language approachable for a wide range of readers.\n* Use active voice whenever possible.\n* Avoid idioms, slang, and region-specific phrases.\n* Avoid ambiguous modal verbs (\"may\", \"might\", \"should\", \"could\") when an action is required. Use definitive verbs instead.\n* Refer to people as \"people\" or \"users\", not \"customers.\"\n\n## Emphasis\n\n* Use **bold** for UI elements and for emphasis, sparingly (no more than five contiguous words).\n* Do not bold text that already has other formatting (for example, all-caps placeholders).\n\n## Word choice\n\n| Use | Avoid |\n|---|---|\n| terminal | shell |\n| sign in | log in, login |\n| sign up | signup |\n| email | e-mail |\n| press (a key) | hit, tap |\n| repository | repo |\n| administrator | admin |\n| for example | e.g. |\n| and similar | etc. |\n\n## What the pipeline handles\n\nAuthors do not need to worry about these — the normalization pipeline handles them automatically:\n\n* YAML frontmatter (added to files for docs.github.com)\n* Mermaid diagram → PNG conversion\n* Link rewriting for docs.github.com cross-references\n* Liquid variable substitution (product names)\n* `[AUTOTITLE]` link conversion\n\n## New article template\n\nWhen creating a new docs article, use this structure:\n\n```markdown\n# Article title in sentence case\n\nA one- or two-sentence intro explaining what the reader will learn or accomplish.\n\n## First section\n\nBody text here.\n\n## Second section\n\nBody text here.\n\n## Further reading\n\n* [Link text](./relative-path.md): short description\n```\n\n## Multi-language code examples\n\nWhen showing the same concept in multiple programming languages, use consecutive `<details>` blocks. The docs-internal normalization pipeline converts these into tabbed language switchers on docs.github.com.\n\n### Rules\n\n* **Only code inside `<details>` blocks.** Shared prose, headings, and explanations must go outside the blocks. Each block should contain only a code fence (and optionally a `<!-- docs-validate: skip -->` comment).\n* **Blocks must be consecutive.** No content (headings, paragraphs) between `<details>` blocks in the same group. Blank lines between blocks are fine.\n* **Use the exact `<summary>` format:** `<summary><strong>LANGUAGE</strong></summary>`. Supported labels: `.NET`, `Python`, `TypeScript`, `Go`, `Java`, `Rust`, `Node.js`, `Shell`.\n* **Need 2+ blocks to form a group.** A single `<details>` block won't be converted and renders as raw HTML on docs.github.com.\n* **Equal content across tabs.** Each tab should show the same concept in a different language. Language-specific extras should be a separate section outside the tabs.\n\n### Correct\n\nShared prose goes above the group, then each `<details>` block contains only code:\n\n```markdown\nInstall the SDK:\n\n<details open>\n<summary><strong>.NET</strong></summary>\n\n<!-- docs-validate: skip -->\n\n```bash\ndotnet add package GitHub.Copilot.SDK\n```\n\n</details>\n<details>\n<summary><strong>Python</strong></summary>\n\n<!-- docs-validate: skip -->\n\n```bash\npip install github-copilot-sdk\n```\n\n</details>\n```\n\n### Incorrect\n\nDo not put headings, prose, or multiple sections inside a `<details>` block:\n\n```markdown\n<details>\n<summary><strong>Python</strong></summary>\n\n### Prerequisites           ← breaks TOC/anchors\nInstall the packages:       ← prose belongs outside\n\n```bash\npip install github-copilot-sdk\n```\n\n### Basic usage             ← multiple sections in one tab\n```python\n[code]\n```\n\n</details>\n```\n\n<!-- File: java/AGENTS.md (Tokens: ~1004 | Category: root-instruction) -->\n<!-- Copyright (c) Microsoft Corporation. All rights reserved. -->\n\n# Java SDK\n\nThis directory is the Java SDK's Maven reactor. Paths and commands below are\nrelative to this directory, whether it is nested at `src/sdk/java` or exported\nas `java`. Keep API usage examples in [README.md](README.md), the\n[SDK documentation](../docs/getting-started.md), and public Javadoc rather than\nduplicating them in these contributor instructions.\n\n## Layout and compatibility\n\n- `sdk/src/main/java/` contains the handwritten client, session, and RPC APIs.\n  `sdk/src/test/java/` contains unit and integration tests.\n- `sdk/src/generated/java/` contains generated protocol and event types.\n- `copilot-native/` packages platform-specific runtime artifacts separately\n  from the pure-Java SDK.\n- Build with **JDK 25 or later**, as required by [sdk/pom.xml](sdk/pom.xml).\n  The base sources target Java 17; Java 25-specific implementations belong in\n  the existing `sdk/src/main/java25/` multi-release overlay. Do not raise the\n  base target or introduce newer APIs into the Java 17 sources.\n\n## API conventions\n\n- Preserve the `CompletableFuture`-based asynchronous API and fluent setters\n  on configuration classes. Preserve wire names and serialization behavior\n  when changing RPC types.\n- Use try-with-resources for `CopilotClient` and `CopilotSession`. Close event\n  and lifecycle subscriptions when no longer needed.\n- Use typed event handlers and the existing `ToolDefinition` and\n  `ToolInvocation` helpers rather than ad hoc wire payloads. Prefer\n  `getArgumentsAs()` for typed tool arguments.\n- Creating and resuming sessions requires a permission handler.\n  `PermissionHandler.APPROVE_ALL` is for scenarios that do not exercise\n  permission decisions; it cannot bypass managed-settings approval.\n- Handle exceptional future completion and `SessionErrorEvent`. Streaming\n  consumers must handle both incremental delta events and final messages.\n- Add Javadoc for public APIs and follow the existing four-space,\n  Spotless/Eclipse formatting. Checkstyle defines the Javadoc checks and\n  exclusions in `sdk/config/checkstyle/checkstyle.xml`.\n\n## Build, format, and test\n\nPrefer the checked-in Maven wrapper (`./mvnw`, or `.\\mvnw.cmd` on Windows).\nFollow [SDK setup](../CONTRIBUTING.md#developing-an-sdk) for the JDK and\nlayout-appropriate Node.js version. Tests use Node.js for the replay harness and\nruntime preparation tooling. Maven's `generate-test-resources` phase installs\ntheir dependencies from the SDK tree. In the runtime repository, prefer\n`npm --prefix <SDK_ROOT> run test:java`; it refreshes the selected schemas and\nJava projection and requests a current host CLI before running the tests.\nDirect Maven commands bypass those prerequisites and are appropriate after\npreparing the checkout, or in the standalone SDK repository.\n\n```bash\n./mvnw clean verify\n./mvnw -pl sdk spotless:apply\n./mvnw -pl sdk spotless:check checkstyle:check\n```\n\nRun `verify` without `-q` or piping through `grep` so failures remain visible.\n`verify` does not run Spotless: apply and check formatting separately for Java\nsource changes. Tests must exercise public APIs, not expose internals solely\nfor tests.\n\nAdd new Java E2E tests for Java SDK surface behavior, not shared runtime\nfunctionality; new SDK-accessible runtime E2Es belong in\n`../nodejs/test/e2e/`. For replay-backed Java integration tests, use the on-demand\n[`sdk-java-e2e-test` skill](../.github/skills/sdk-java-e2e-test/SKILL.md).\nIts snapshot workflow is not required for unrelated\nJava edits. For JDK 17 compatibility testing, run the JDK 25-built artifact on\nJDK 17 without recompiling it, following\n[Development Setup](README.md#development-setup).\n\n## Generated sources\n\nDo not edit `sdk/src/generated/java/` by hand. Update the generator in\n`scripts/codegen/java.ts` when needed. From `<SDK_ROOT>`, regenerate with the\nSDK facade so the runtime layout selects checked-out schemas and the standalone\nlayout selects its pinned release schemas:\n\n```bash\nnpm run generate:java\n```\n\nThe protocol constant `sdk/src/main/java/com/github/copilot/SdkProtocolVersion.java`\nis also generated, despite living outside `src/generated/`. Change the shared\n`<SDK_ROOT>/sdk-protocol-version.json` and run\n`npm --prefix <SDK_ROOT>/nodejs run update:protocol-version` to update all six SDKs.\n\nUse the SDK's selected schema inputs; do not update release-derived CLI pins\nas an incidental part of implementation work.\n\n<!-- File: rust/AGENTS.md (Tokens: ~1261 | Category: root-instruction) -->\n<!-- Copyright (c) Microsoft Corporation. All rights reserved. -->\n\n# Rust SDK\n\nThis directory contains the independent `github-copilot-sdk` crate. In\nstandalone SDK workflows, paths and Cargo commands below are relative to this\ndirectory, and this crate's own lockfile and toolchain apply. When nested at\n`src/sdk/rust`, the runtime CLI consumes the same checked-out sources through\nthe Bazel integration described under Development. The runtime's N-API\narchitecture does not otherwise govern this crate.\n\n## Public API and errors\n\n- Use the existing `Error` and `ErrorKind` in [src/errors.rs](src/errors.rs).\n  Extend that public error contract instead of adding parallel per-module error\n  types or returning `anyhow::Error` from library APIs.\n- Treat exported types, builders, and trait signatures as a consumer-facing\n  contract. Adding a required field to a public struct can break callers'\n  struct literals; preserve compatibility with existing construction patterns.\n- Document public APIs with rustdoc. Keep cross-language parity notes in\n  [README.md](README.md), rather than repeating comparisons to other SDKs on\n  individual symbols.\n\n## Extension points and session lifetime\n\n- Use the per-request traits in [src/handler.rs](src/handler.rs), such as\n  `PermissionHandler` with `SessionConfig::with_permission_handler`, and retain\n  their declared `Send + Sync + 'static` contracts.\n- Implement `SessionHooks` in [src/hooks.rs](src/hooks.rs) for lifecycle hooks.\n  Prefer its per-hook methods; `with_hooks` enables hooks on the session.\n- Implement `SystemMessageTransform` in [src/transforms.rs](src/transforms.rs)\n  with `section_ids` and `transform_section`, and register it through\n  `with_system_message_transform`.\n- Attach a `ToolHandler` to a `Tool` with `with_handler`, then register tools\n  with `with_tools`. The `derive` feature exposes `define_tool` and `schema_for`\n  for typed tool parameters. Use the current examples in\n  [src/tool.rs](src/tool.rs), not hand-built JSON wire payloads.\n- `EventSubscription` and `LifecycleSubscription` are streams; dropping a\n  subscription unsubscribes. `Session::cancellation_token` returns a child\n  token, so cancelling it must not cancel the parent session. Preserve these\n  ownership and cancellation semantics when changing event dispatch.\n- `ApproveAllHandler` is suitable for tests that do not exercise permission or\n  managed-settings behavior. It is not an override for managed approval.\n\n## Generated types\n\nDo not edit `src/generated/` by hand. The generator is\n`../scripts/codegen/rust.ts`. From `<SDK_ROOT>`, regenerate with the SDK facade\nso the runtime layout selects checked-out schemas and the standalone layout\nselects its pinned release schemas:\n\n```bash\nnpm run generate:rust\n```\n\nKeep handwritten consumer-facing types in `src/types.rs` when the wire types\ncannot express the public API, rather than patching generated output. Changes\nto release-derived CLI pins and schema inputs belong to the release process,\nnot incidental SDK implementation work.\n\n## Development\n\nIn the runtime repository, prefer `npm --prefix <SDK_ROOT> run test:rust`; it\nrefreshes the selected schemas and Rust projection and requests a current host\nCLI before running the tests. Direct Cargo commands bypass those prerequisites\nand the facade's environment applies only to its child process; it does not\npersist for later shell commands. The CLI consumes this crate through the\nsame-checkout `//src/sdk/rust:github-copilot-sdk-local-runtime` Bazel target,\nwith default features disabled. That `local-runtime` mode enables in-process\ntransport without SDK-managed acquisition because the CLI supplies its loaded\n`runtime.node`; `bundled-cli` takes precedence in all-feature builds.\n\nUse this crate's `rust-toolchain.toml`, `Cargo.toml`, and rustfmt configuration,\nnot the runtime workspace's. See [README.md#development](README.md#development)\nfor Node and replay-harness prerequisites. Cargo restores Rust dependencies.\nThe following direct Cargo commands are standalone SDK repository commands and\nuse its published/bundled acquisition semantics:\n\n```bash\ncargo check --all-features\ncargo test --features test-support\ncargo clippy --all-targets --all-features -- -D warnings\ncargo +nightly-2026-04-14 fmt --all -- --config-path .rustfmt.nightly.toml --check\n```\n\nFor changes to the CLI's SDK consumer path, run the repository's Bazel tests\nfrom the runtime root:\n\n```bash\npnpm bazel test //src/native/cli-runtime:cli-native-runtime_test //src/native/cli-runtime:runtime_sibling_resolution //src/native/cli-runtime:typed_sdk_call\n```\n\nDo not restore a repository-wide `COPILOT_SKIP_CLI_DOWNLOAD`. For focused\nsame-checkout compilation from this directory, use:\n\n```bash\ncargo check --no-default-features --features local-runtime\n```\n\nRun it with `COPILOT_SKIP_CLI_DOWNLOAD` unset. Tests that start the runtime must\nalso set `COPILOT_CLI_PATH` to the prepared same-checkout wrapper.\n\nKeep unit tests in external test-only modules: `foo.rs` declares\n`#[cfg(test)] mod tests;`, and its tests live in `foo/tests.rs`. Crate roots\nsuch as `lib.rs` use a sibling `tests.rs`; descriptive module names keep their\ncorresponding file names. Start each test-only file with `#![cfg(test)]`.\nKeep integration tests in `tests/`. Integration tests needing SDK test helpers\nuse the `test-support` feature because the library is compiled without\n`cfg(test)`.\n\nDefault features bundle the CLI; disabling them changes what must be provided\nexternally. For transport-specific E2E settings, bundled-runtime checks, and\nthe full platform matrix, follow the\n[Rust SDK workflow](../.github/workflows/sdk-rust.yml). A local unit test\nrun does not replace those checks.\n</yakaai_skills>"}