release: sync copilot-sdk-cpp v0.3.0 from private

Re-pins the SDK to the official github/copilot-sdk@7a916f8 surface
(@github/copilot@1.0.83-0, wire protocol 3) and adds a schema-driven
codegen pipeline so future re-pins are mechanical.

Generated surface (tools/generate_protocol_types.py + schemas/official-baseline.json):
1,218 API definitions, 535 event definitions, 367 RPC methods, 133 event
variants. Regenerating is deterministic; `--check` guards it via the
codegen_check test.

New public surface:
- factory, canvas and extension APIs
- FFI transport (include/copilot/transport_ffi.hpp)
- request-handler bridge for llmInference streaming
- session.sandbox.getEnforcementStatus, session.factory.runFromTool/resumeFromTool
- gitHubToken.getToken via ClientOptions::github_token_provider; the runtime
  addresses the callback by an opaque registrationId exposed as
  Client::github_token_registration_id(), for installation as a token-provider
  AuthInfo. Enforces the schema's expiresIn >= 3601 minimum.

Event typing: all 133 generated wire types now resolve to a typed
SessionEventType. 52 previously fell through to Unknown with raw JSON --
11 new in this re-pin, 41 pre-existing. Note this makes SessionEventData a
132-alternative variant, which requires /bigobj on MSVC; it is applied as a
PUBLIC compile option so consumers inherit it.

Bug fixes:
- TcpTransport::connect no longer burns its full timeout on a refused address.
  getaddrinfo(AF_UNSPEC) commonly returns ::1 before 127.0.0.1, and on Windows
  a refused non-blocking connect is signalled through select()'s exceptfds,
  which was passed as nullptr. Now monitors exceptfds and budgets the timeout
  across the candidate list.
- Client::parse_cli_url no longer misreads "127.0.0.1:54321" as port 127.
  std::stoi stops at the first non-digit, so the bare-port branch matched any
  host:port whose first octet was a valid port number.

Validated: 464/464 tests pass, codegen check green. Authenticated E2E was not
run for this pin.

Author: 0xeb

CMakeLists.txt

@@ -1,5 +1,5 @@
 cmake_minimum_required(VERSION 3.20)
-project(copilot_sdk_cpp VERSION 0.2.0 LANGUAGES CXX)
+project(copilot_sdk_cpp VERSION 0.3.0 LANGUAGES CXX)
 
 # Enable folder organization in IDEs
 set_property(GLOBAL PROPERTY USE_FOLDERS ON)
@@ -18,6 +18,23 @@ option(COPILOT_BUILD_EXAMPLES "Build examples" ON)
 option(COPILOT_BUILD_SNAPSHOT_TESTS "Build snapshot conformance tests (requires upstream snapshots + Python)" OFF)
 option(COPILOT_WITH_FASTMCPP "Build in-process MCP examples with fastmcpp" OFF)
 
+# Protocol code generation
+find_package(Python3 COMPONENTS Interpreter QUIET)
+if(Python3_Interpreter_FOUND)
+    add_custom_target(copilot_codegen
+        COMMAND ${Python3_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/tools/generate_protocol_types.py
+        WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
+        COMMENT "Regenerating C++ protocol types from the official baseline"
+        VERBATIM
+    )
+    add_custom_target(copilot_codegen_check
+        COMMAND ${Python3_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/tools/generate_protocol_types.py --check
+        WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
+        COMMENT "Checking generated C++ protocol types"
+        VERBATIM
+    )
+endif()
+
 # Find dependencies
 find_package(nlohmann_json CONFIG QUIET)
 
@@ -55,23 +72,39 @@ add_library(copilot_sdk_cpp
     include/copilot/copilot.hpp
     include/copilot/types.hpp
     include/copilot/events.hpp
+    include/copilot/extension.hpp
+    include/copilot/factory.hpp
+    include/copilot/generated/api_types.hpp
+    include/copilot/generated/compatibility_types.hpp
+    include/copilot/generated/protocol_version.hpp
+    include/copilot/generated/schema_coverage.hpp
+    include/copilot/generated/schema_value.hpp
+    include/copilot/generated/session_events.hpp
     include/copilot/transport.hpp
     include/copilot/transport_stdio.hpp
     include/copilot/transport_tcp.hpp
+    include/copilot/transport_ffi.hpp
     include/copilot/jsonrpc.hpp
     include/copilot/process.hpp
+    include/copilot/request_handler.hpp
     include/copilot/client.hpp
+    include/copilot/canvas.hpp
     include/copilot/session.hpp
     include/copilot/rpc_methods.hpp
     include/copilot/rpc_types.hpp
     # Sources
     src/types.cpp
     src/events.cpp
+    src/extension.cpp
+    src/factory.cpp
     src/transport.cpp
+    src/transport_ffi.cpp
     src/jsonrpc.cpp
     src/process_win32.cpp
     src/process_posix.cpp
+    src/request_handler.cpp
     src/client.cpp
+    src/canvas.cpp
     src/session.cpp
 )
 add_library(copilot::copilot_sdk_cpp ALIAS copilot_sdk_cpp)
@@ -87,6 +120,8 @@ target_include_directories(copilot_sdk_cpp
 target_link_libraries(copilot_sdk_cpp
     PUBLIC
         nlohmann_json::nlohmann_json
+    PRIVATE
+        ${CMAKE_DL_LIBS}
 )
 
 # Platform-specific settings
@@ -96,6 +131,12 @@ if(WIN32)
     target_link_libraries(copilot_sdk_cpp PUBLIC ws2_32)
 endif()
 
+if(MSVC)
+    # SessionEventData is a std::variant with one alternative per event type; instantiating it
+    # exceeds the default COFF section limit. PUBLIC because consumers instantiate it too.
+    target_compile_options(copilot_sdk_cpp PUBLIC /bigobj)
+endif()
+
 # Set target properties
 set_target_properties(copilot_sdk_cpp PROPERTIES
     VERSION ${PROJECT_VERSION}

README.md

@@ -33,6 +33,49 @@ Snapshot conformance tests (optional):
 - Enable with `-DCOPILOT_BUILD_SNAPSHOT_TESTS=ON` and set `-DCOPILOT_SDK_CPP_SNAPSHOT_DIR=...` if auto-detection fails.
 - Run: `cmake --build build --target run_snapshot_tests --config Release`
 
+## Official protocol baseline and code generation
+
+`schemas/official-baseline.json` pins the official SDK commit, protocol version,
+schema hashes, and the complete generated surface: 1,203 API definitions, 494
+session-event definitions, 363 RPC methods, and 122 event variants. Generated
+wire-preserving types live under `include/copilot/generated/`; the existing
+handwritten public API remains the ergonomic layer.
+
+```sh
+# Regenerate from the committed baseline
+cmake --build build --target copilot_codegen
+
+# Fail if committed generated headers are stale
+cmake --build build --target copilot_codegen_check
+```
+
+To refresh from a checked-out official SDK and the matching CLI package schemas:
+
+```sh
+python tools/generate_protocol_types.py --refresh \
+  --official-sdk-root ../copilot-sdk \
+  --api-schema <path-to-api.schema.json> \
+  --session-events-schema <path-to-session-events.schema.json>
+```
+
+## Current public API surface
+
+`ClientOptions` supports SDK modes plus stdio, TCP, URI, and declared in-process
+runtime connections. Session create/resume requests expose the current official
+configuration fields while preserving the existing handwritten C++ API.
+`Session::invoke`/`invoke_typed` provide low-level access, with typed convenience
+wrappers for MCP, authentication, agents, skills, tasks, commands, history,
+usage, and remote-session operations.
+
+Advanced parity includes:
+
+- `RuntimeConnection::for_in_process()` using the official
+  `copilot_runtime_*` native ABI (`prebuilds/<platform>/runtime.node`).
+- `CopilotRequestHandler` and WebSocket handlers for streamed model-layer I/O.
+- Automatic MCP OAuth event handling and pending-request responses.
+- `create_canvas`, `define_factory`, `Session::factory()`, and `join_session`
+  helpers for canvas, factory, and extension consumers.
+
 ## Custom Tools
 
 Custom tools are provided when creating or resuming a session. The SDK auto-generates JSON schemas from C++ types.

cmake/copilot_sdk_cppConfig.cmake.in

@@ -1,11 +1,9 @@
 @PACKAGE_INIT@
 
-include(CMakeFindDependencyMacro)
-
 # If the consumer didn't provide nlohmann_json, try to find it. If it still isn't
 # available, fall back to the vendored headers installed with this package.
 if(NOT TARGET nlohmann_json::nlohmann_json)
-  find_dependency(nlohmann_json QUIET)
+  find_package(nlohmann_json CONFIG QUIET)
 endif()
 if(NOT TARGET nlohmann_json::nlohmann_json)
   add_library(nlohmann_json::nlohmann_json INTERFACE IMPORTED)

docs/validation-6e6eb55.md

@@ -0,0 +1,113 @@
+# Validation report: official SDK `6e6eb55`
+
+**Date:** 2026-08-24
+**Branch:** `sdk-parity/6e6eb55`
+**Official source:** `github/copilot-sdk` commit
+`6e6eb55f4d0f1ee222cfce3e64493781ef7c5be8`
+**Result:** **PASS — current-official parity validated on Windows x64**
+
+## Environment
+
+- Windows x64
+- Visual Studio 2022 / MSVC 19.44.35228
+- CMake 4.0
+- Python 3.13.15
+- SDK protocol version 3
+- Official schema package baseline `@github/copilot@1.0.81-6`
+- `copilot --version`: 1.0.81-8
+- Runtime reported by the connection handshake: 1.0.81-9, protocol 3
+
+No credentials, tokens, account names, or other authentication material were
+captured in this report.
+
+## Validation results
+
+| Area | Command / evidence | Result |
+|---|---|---|
+| Fresh configure | `cmake -S . -B build-validation-final -DCOPILOT_BUILD_TESTS=ON -DCOPILOT_BUILD_EXAMPLES=ON` | Pass |
+| Fresh Release build | `cmake --build build-validation-final --config Release` | Pass; library, all tests, and all examples compiled |
+| Full non-auth suite | `COPILOT_SDK_CPP_SKIP_E2E=1 ctest --test-dir build-validation-final -C Release --output-on-failure` | **494/494 passed**, 71 authenticated E2E tests intentionally skipped |
+| Code generation | CMake `copilot_codegen_check` plus direct `generate_protocol_types.py --check --official-sdk-root ...` | Pass: 1,203 API definitions, 494 event definitions, 363 RPC methods, 122 event variants |
+| Official-shape goldens | Generated/public/advanced parity test filters | **26/26 passed** |
+| FFI architecture loader | `FfiTransportTest.*` using a DLL exporting the official `copilot_runtime_*` ABI | **3/3 passed**, including blocked-read cancellation and missing-library errors |
+| Installed CMake package | Install to a clean prefix, configure/build/run an external `find_package(copilot_sdk_cpp CONFIG REQUIRED)` consumer | Pass after fixing the bundled `nlohmann_json` fallback |
+| Examples / consumer compilation | Fresh build compiled all repository examples; external consumer compiled generated, canvas, session, and runtime APIs | Pass |
+
+## Authenticated Copilot CLI validation
+
+The complete authenticated matrix was run with a per-test 120-second bound.
+The consolidated result was **69 passed, 2 intentionally skipped, 0 failed**
+across 71 scenarios. The two skips are the legacy foreground-session tests;
+their RPCs are absent from the official `6e6eb55` generated API.
+
+Validated live workflows include startup/shutdown, concurrent RPC, create and
+resume, tools and permissions, hooks, user input, elicitation registration,
+MCP and custom agents, attachments, streaming, compaction, model discovery,
+event parsing, lifecycle, status/auth, caching, and graceful/forced teardown.
+
+The validation run discovered and fixed:
+
+- ISO-8601 ping timestamp compatibility
+- fail-open preservation of evolved event payloads
+- protocol-v3 external-tool, permission, and user-input event handling
+- current `connect`/account status RPC usage
+- environment-dependent model selection in E2E tests
+- bounded process waits and client shutdown mutex deadlocks
+- resumable test cleanup
+- caller session-ID pre-registration/remapping
+- installed-package fallback when `nlohmann_json` is not separately installed
+- stdio reader shutdown after process termination
+- handler-enabled session creation with bounded E2E waits
+- protocol-v3 handler registration and payload compatibility
+
+### Root-cause resolution
+
+RPC tracing showed that handler-enabled `session.create` calls completed and
+returned valid responses. The apparent create hangs occurred during test
+cleanup: `JsonRpcClient::stop()` joined its stdio reader while
+`PipeTransport::close()` intentionally left the process-owned pipe handles
+open. A descendant runtime process could therefore keep `ReadFile` blocked.
+
+The fix adds `Process::close_pipes()` on Windows and POSIX and calls it after
+bounded process termination but before joining the JSON-RPC reader. A
+time-bounded process regression test and 30-second handler-create E2E bounds
+prevent recurrence. Hook, user-input, and elicitation-enabled creation all
+pass against the authenticated runtime.
+
+### Intentional skips
+
+1. `ForegroundSessionSetAndGet`
+2. `ForegroundSessionInitiallyEmpty`
+
+Both exercise legacy compatibility RPCs that do not exist in the official
+`6e6eb55` generated RPC surface.
+
+`tests/byok.env` was not present. This did not block authenticated testing;
+the installed Copilot CLI authentication was used instead.
+
+## Static analysis and sanitizers
+
+No static-analysis or sanitizer target is defined by this repository.
+`clang-tidy`, `cppcheck`, and `clang-cl` were not installed on this machine, so
+those optional checks were skipped. The fresh MSVC build completed without
+compiler warnings in the validation output.
+
+## Residual risks
+
+- The native FFI loader was validated against the exact ABI with a test DLL,
+  but not against a real packaged `runtime.node` in this run.
+- Linux, Linux-musl, and macOS builds were not executed; only Windows x64 was
+  compiled and tested.
+- Cloud-session creation and parent-process extension joining were compile/
+  golden tested but not exercised against a live host.
+- The local runtime was newer (`1.0.81-9`) than the official SDK schema package
+  baseline (`1.0.81-6`), although both negotiated protocol version 3.
+
+## Validation disposition
+
+The current-official surface is validated for the tested Windows x64
+environment. Build, generated protocol coverage, packaging, external
+consumption, non-auth tests, and all applicable authenticated E2E scenarios
+pass.
+
+Validation fixes are recorded in commits `38f8b5d` and `ebda3eb`.