Copilot SDK Driver Specification | GitHub Agentic Workflows
Skip to main content Copilot SDK Driver Specification Version : 1.0.3 Status : Draft Specification Latest Version : copilot-sdk-driver-specification Editor : GitHub Agentic Workflows Team Abstract Section titled “Abstract” This specification defines the normative behavior of a Copilot SDK driver that runs an agent session against a Copilot SDK endpoint and emits session telemetry. The specification is language agnostic and focuses on environment variable contracts, permission-checking policy, required logging behavior, and connection-token propagation between the harness-managed sidecar and the driver.
Non-normative examples use TypeScript. Conforming implementations provide deterministic permission enforcement, auditable diagnostics, and interoperable runtime behavior across host environments. Status of This Document Section titled “Status of This Document” This section describes the status of this document at the time of publication. This is a draft specification and may be updated, replaced, or made obsolete by other documents at any time.
This document is governed by the GitHub Agentic Workflows project specifications process. Table of Contents Section titled “Table of Contents” Introduction Conformance Driver Execution Model Configuration and Environment Variables Permission Checking Model Logging Requirements Error Handling and Exit Behavior Compliance Testing Appendices References Sync Notes Change Log 1. Introduction Section titled “1. Introduction” 1.1 Purpose Section titled “1.1 Purpose” The Copilot SDK driver provides a host-independent contract for starting a Copilot SDK client session, sending a prompt, handling tool permissions, and producing structured operational logs.
1.2 Scope Section titled “1.2 Scope” This specification covers: Driver configuration inputs and runtime environment variables Permission request evaluation and deny/allow behavior Required lifecycle and policy-denial logging Required error handling and process exit semantics This specification does NOT cover: Copilot model quality or response content guarantees Host workflow compiler internals SDK transport protocol internals beyond driver-facing inputs 1.3 Design Goals Section titled “1.3 Design Goals” A conforming implementation MUST: Remain language agnostic in externally visible behavior Provide explicit and testable permission decisions Produce consistent, audit-friendly logs for runtime and policy events Fail fast on missing required configuration in standalone mode 2.
Conformance Section titled “2. Conformance” 2.1 Conformance Classes Section titled “2.1 Conformance Classes” A conforming driver implementation satisfies all MUST, REQUIRED, and SHALL requirements in this specification. A partially conforming driver implementation satisfies all MUST requirements in Sections 4, 5, and 7 but MAY omit optional diagnostics in Section 6. 2.2 Requirements Notation Section titled “2.2 Requirements Notation” The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119 .
2.3 Compliance Levels Section titled “2.3 Compliance Levels” Implementations MUST support: Level 1 (Required) : Required environment variables, session startup, prompt dispatch, and exit behavior Level 2 (Standard) : Permission checking model and denial diagnostics Level 3 (Complete) : Full lifecycle logging and structured event serialization interoperability 3. Driver Execution Model Section titled “3. Driver Execution Model” 3.1 Runtime Mode Section titled “3.1 Runtime Mode” For extension integrations, a driver implementation MUST support standalone mode (executable entry point that reads configuration from environment variables).
Embedded callable APIs are out of scope for this specification. 3.2 Session Lifecycle Section titled “3.2 Session Lifecycle” A conforming implementation MUST execute the following sequence: Resolve runtime configuration. Start SDK client connection. Create a session. Register event handlers. Send prompt and await completion. Return success/failure result. Perform best-effort cleanup of stream/session/client resources.
3.3 Event Persistence Section titled “3.3 Event Persistence” A complete implementation (Level 3) SHOULD serialize non-ephemeral session events to a JSON Lines stream compatible with downstream timeline rendering. The built-in driver retains native event envelopes and payloads, including user messages, reasoning, errors, tool outcomes, and unknown non-ephemeral extensions. It also captures the ephemeral assistant.usage , assistant.message_delta , assistant.reasoning_delta , model.call_failure , and workflow lifecycle observations needed to recover accounting and interrupted conversations.
Other ephemeral events are not persisted. Canonical conversion happens in the Copilot session adapter; missing timestamps, tool outcomes, and metrics are not synthesized by the driver. Default summaries continue to omit user prompts. Bootstrap and collection retain independently parseable native observations from malformed JSONL and record an explicit collection warning. A usable partial native trace is not replayed together with fallback stdio.
When fallback is needed, exact identified copies are deduplicated within their observed session; conflicting payloads and independent retry or child observations remain available. 3.4 Harness Connection Token Flow Section titled “3.4 Harness Connection Token Flow” When SDK mode is enabled ( COPILOT_SDK_URI is set), the harness MUST generate a per-run COPILOT_CONNECTION_TOKEN and MUST pass the same token value to both: The harness-managed Copilot sidecar process The SDK driver subprocess environment The SDK driver MUST treat COPILOT_CONNECTION_TOKEN as a required input and MUST fail fast with non-zero exit when it is missing.
The harness MUST NOT propagate platform authentication secrets such as GITHUB_TOKEN , COPILOT_GITHUB_TOKEN , or GH_TOKEN into the SDK driver subprocess environment. Driver processes run in a secret-isolated environment and MUST NOT rely on or attempt to read platform authentication tokens. 3.5 Workflow Skill Registration Section titled “3.5 Workflow Skill Registration” The built-in driver explicitly supplies the staged workflow skill root /tmp/gh-aw/.github/skills through the SDK’s skillDirectories configuration when that directory exists, enabling skills without ambient configuration discovery.
This includes inline skills and installed frontmatter skills. Repository and home-directory skill roots are not added automatically. Missing staging directories produce an empty explicit list; a staged root that is a file or symbolic link fails session creation. This is a hard failure with exitCode: 1 and a session.error event, not a warning or silent skip. Skill registration does not grant additional shell permissions or change the tool-denial limit.
4. Configuration and Environment Variables Section titled “4. Configuration and Environment Variables” 4.1 Standalone Environment Variables Section titled “4.1 Standalone Environment Variables” In standalone mode, the implementation MUST enforce the following contract: Variable Required Description Default / Validation GH_AW_PROMPT Yes Path to prompt file MUST exist and be readable 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 Yes Model to use (e.g. gpt-4o , claude-sonnet-4 ) MUST be non-empty; implementations MUST fail fast when unset 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 GH_AW_MAX_
The rest of this page is on the live site.