docs: add Copilot SDK support, driver configuration, and specification guidance (#36731)

* docs: add copilot sdk support section to engines reference

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

* docs: clarify gh-aw managed SDK timeout and log-level controls

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
Co-authored-by: Peli de Halleux <pelikhan@users.noreply.github.com>

Author: Copilot

docs/src/content/docs/reference/copilot-sdk-driver-specification.md

@@ -139,8 +139,8 @@ In standalone mode, the implementation MUST enforce the following contract:
 | `COPILOT_SDK_URI`             | Yes      | SDK endpoint URI                                          | MUST be non-empty                                                                                            |
 | `COPILOT_CONNECTION_TOKEN`    | Yes      | Per-run shared token generated by the harness in SDK mode | MUST be non-empty in the driver environment                                                                  |
 | `COPILOT_MODEL`               | No       | Model override                                            | OPTIONAL                                                                                                     |
-| `COPILOT_SDK_SEND_TIMEOUT_MS` | No       | Send timeout in milliseconds                              | Input SHOULD be a positive integer; default `600000`; implementations MUST fall back on invalid values       |
-| `COPILOT_SDK_LOG_LEVEL`       | No       | SDK client log level                                      | Valid values: `none`, `error`, `warning`, `info`, `debug`, `all`; invalid values MUST fall back to `warning` |
+| `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` |
 | `GITHUB_WORKSPACE`            | No       | Working directory hint                                    | SHOULD be used when present                                                                                  |
 
 ### 4.2 Connection Token Requirement
@@ -156,9 +156,17 @@ In SDK mode, a conforming implementation:
 
 ### 4.3 Timeout Environment Variable
 
-`COPILOT_SDK_SEND_TIMEOUT_MS` controls maximum send wait duration for prompt completion in standalone mode. Implementations MUST treat this value as milliseconds and MUST apply the default value (`600000`) when unset, non-numeric, or non-positive.
+`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.
+
+A conforming driver implementation MUST treat `COPILOT_SDK_SEND_TIMEOUT_MS` as milliseconds and MUST apply the default value (`600000`) when unset, non-numeric, or non-positive.
+
+### 4.4 Log-Level Environment Variable
+
+`COPILOT_SDK_LOG_LEVEL` is the host-provided SDK client log level control. A conforming driver implementation MUST use the provided value when it is one of `none`, `error`, `warning`, `info`, `debug`, or `all`; otherwise it MUST fall back to `warning`.
+
+### 4.5 TypeScript Example (Non-Normative)
 
 Prerequisite: install [`@github/copilot-sdk`](https://www.npmjs.com/package/@github/copilot-sdk) in the runtime where this example executes.
 

docs/src/content/docs/reference/engines.md

@@ -263,18 +263,71 @@ The value must be a bare filename — no directory separators, no `..`, and no s
 | Must start with `[A-Za-z0-9_]` | `harness.js` | `-harness.cjs` |
 | Must end with `.js`, `.cjs`, or `.mjs` | `wrapper.cjs` | `harness.sh` |
 
-### Copilot SDK Driver Override (`copilot-sdk-driver`)
+### Copilot SDK Support
 
-When `engine.copilot-sdk: true` is enabled, gh-aw runs a Node.js driver script (`copilot_sdk_driver.cjs`) under the harness. Use `engine.copilot-sdk-driver` to replace that built-in SDK driver with your own script filename.
+Enable `engine.copilot-sdk: true` to run Copilot in SDK mode.
+In this mode, the harness starts a local sidecar and runs the
+SDK driver process instead of the default CLI-only flow.
+
+Use `engine.copilot-sdk-driver` to replace the built-in
+`copilot_sdk_driver.cjs` implementation:
 
 ```yaml wrap
 engine:
   id: copilot
   copilot-sdk: true
-  copilot-sdk-driver: custom_copilot_sdk_driver.cjs
+  copilot-sdk-driver: custom-copilot-driver
 ```
 
-`copilot-sdk-driver` follows the same filename safety rules as `harness`: it must be a bare filename ending with `.js`, `.cjs`, or `.mjs` (no paths, no `..`, no shell metacharacters).
+`copilot-sdk-driver` must be a safe basename (no path
+separators, `..`, or shell metacharacters). It supports:
+
+- script filenames ending with `.js`, `.cjs`, `.mjs`,
+  `.py`, `.ts`, `.mts`, or `.rb`
+- bare command names without an extension (resolved from
+  `PATH`)
+
+See [Copilot SDK Driver Specification](/gh-aw/reference/copilot-sdk-driver-specification/)
+for the full driver contract.
+
+#### SDK driver environment variables
+
+The specification defines the driver environment contract.
+In SDK mode, gh-aw injects required runtime values:
+
+- `GH_AW_PROMPT`
+- `COPILOT_SDK_URI`
+- `COPILOT_CONNECTION_TOKEN`
+
+`COPILOT_MODEL` is optional and follows normal Copilot model
+configuration.
+
+For runtime controls, the driver should consume:
+
+- `COPILOT_SDK_SEND_TIMEOUT_MS`
+- `COPILOT_SDK_LOG_LEVEL`
+
+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.
+`COPILOT_SDK_LOG_LEVEL` is a host-provided driver control and
+should be honored when gh-aw passes it to the driver process.
+
+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
+```
 
 ### Bare Mode (`bare`)