docs: add Copilot SDK support, driver configuration, and specification guidance#36731
Merged
Conversation
Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
Copilot
AI
changed the title
docs: add Copilot SDK support guidance to engine reference
docs: add Copilot SDK support and driver configuration guidance
Jun 3, 2026
Copilot created this pull request from a session on behalf of
pelikhan
June 3, 2026 21:20
View session
pelikhan
reviewed
Jun 3, 2026
Comment on lines
+303
to
+322
| configuration. You can also set optional SDK tuning variables | ||
| in `engine.env`: | ||
|
|
||
| - `COPILOT_SDK_SEND_TIMEOUT_MS` | ||
| - `COPILOT_SDK_LOG_LEVEL` | ||
|
|
||
| Do not set `COPILOT_CONNECTION_TOKEN` manually. The harness | ||
| generates it per run and passes the same token to both the | ||
| sidecar and driver process. | ||
|
|
||
| ```yaml wrap | ||
| engine: | ||
| id: copilot | ||
| copilot-sdk: true | ||
| copilot-sdk-driver: my_driver.ts | ||
| model: gpt-5 | ||
| env: | ||
| COPILOT_SDK_SEND_TIMEOUT_MS: "900000" | ||
| COPILOT_SDK_LOG_LEVEL: info | ||
| ``` |
Collaborator
There was a problem hiding this comment.
@copilot the log-level and timeout-minutes variables are set by gh-aw and should be used by the driver to compare the file. Update the documentation and the specification using the W3C specwriter.
Contributor
Author
There was a problem hiding this comment.
Updated in 7fac799.
I clarified both the engine docs and the W3C-style SDK driver specification so the driver uses gh-aw-provided runtime controls:
- timeout behavior now explicitly ties to workflow
timeout-minutesvia host-injectedCOPILOT_SDK_SEND_TIMEOUT_MS(with the normative fallback behavior) - log level behavior now explicitly treats
COPILOT_SDK_LOG_LEVELas a host-provided control the driver must honor when valid
Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
Copilot
AI
changed the title
docs: add Copilot SDK support and driver configuration guidance
docs: add Copilot SDK support, driver configuration, and specification guidance
Jun 3, 2026
Contributor
There was a problem hiding this comment.
Pull request overview
This PR updates the Copilot engine documentation to describe SDK-mode execution, including how to enable SDK mode, configure/override the SDK driver, and reference the Copilot SDK driver’s normative environment-variable contract.
Changes:
- Adds a “Copilot SDK Support” section to the engine reference, including driver selection rules and YAML examples.
- Links engine configuration docs to the Copilot SDK Driver Specification as the normative contract.
- Clarifies the SDK driver’s timeout and log-level environment variables in the driver specification.
Show a summary per file
| File | Description |
|---|---|
| docs/src/content/docs/reference/engines.md | Documents SDK-mode enablement, multi-language/bare-command driver overrides, and required/optional SDK env vars. |
| docs/src/content/docs/reference/copilot-sdk-driver-specification.md | Refines the spec’s description of runtime controls (COPILOT_SDK_SEND_TIMEOUT_MS, COPILOT_SDK_LOG_LEVEL). |
Copilot's findings
Tip
Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Files reviewed: 2/2 changed files
- Comments generated: 3
Comment on lines
+310
to
+313
| In gh-aw, `COPILOT_SDK_SEND_TIMEOUT_MS` is usually injected | ||
| automatically from workflow `timeout-minutes` (via | ||
| `GH_AW_TIMEOUT_MINUTES`) with safety headroom. Override it in | ||
| `engine.env` only when you need a custom SDK send timeout. |
Comment on lines
+142
to
+143
| | `COPILOT_SDK_SEND_TIMEOUT_MS` | No | Send timeout in milliseconds | Input SHOULD be a positive integer; gh-aw typically sets this from workflow `timeout-minutes`; default `600000`; implementations MUST fall back on invalid values | | ||
| | `COPILOT_SDK_LOG_LEVEL` | No | SDK client log level | gh-aw may set this for driver runtime logging; valid values: `none`, `error`, `warning`, `info`, `debug`, `all`; invalid values MUST fall back to `warning` | |
Comment on lines
+159
to
+162
| `COPILOT_SDK_SEND_TIMEOUT_MS` controls maximum send wait duration for prompt completion in standalone mode. | ||
|
|
||
| ### 4.4 TypeScript Example (Non-Normative) | ||
| When gh-aw hosts the driver, it generally derives and injects this variable from workflow `timeout-minutes` (exposed to the harness as `GH_AW_TIMEOUT_MINUTES`) so SDK completion stays below the step timeout budget. | ||
|
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This updates the Copilot engine docs to explicitly cover Copilot SDK support and how to configure it end to end. It adds clear guidance for selecting an SDK driver, mapping specification-defined environment variables, and wiring the setup in workflow YAML.
What changed
reference/engines..js,.cjs,.mjs,.py,.ts,.mts,.rbPATHreference/copilot-sdk-driver-specificationto clarify host-provided runtime controls for timeout and log level.Configuration contract clarified
GH_AW_PROMPTCOPILOT_SDK_URICOPILOT_CONNECTION_TOKENCOPILOT_SDK_SEND_TIMEOUT_MSCOPILOT_SDK_LOG_LEVELCOPILOT_SDK_SEND_TIMEOUT_MSis typically injected from workflowtimeout-minutes(viaGH_AW_TIMEOUT_MINUTES) with headroomCOPILOT_SDK_LOG_LEVELis a host-provided control the driver should honorCOPILOT_CONNECTION_TOKENis harness-generated per run and should not be user-set.YAML examples added