release: copilot-sdk-cpp v0.4.2

- Update protocol and type coverage for Copilot CLI 1.0.102-1.
- Add structured responses, live tool updates, and skill providers.
- Add installation confirmation and extension launch callbacks.
- Expand session configuration, MCP authentication, and filesystem APIs.
- Improve request cancellation, response tracking, and runtime shutdown.

Author: 0xeb

.github/workflows/ci.yml

@@ -22,12 +22,10 @@ jobs:
         # Deliberately no -G: runner images rotate their Visual Studio version, and pinning
         # one ("Visual Studio 17 2022") breaks the Windows job the moment the image moves on.
         # CMake's per-platform default is correct on all three runners.
-        run: cmake -B build -DCMAKE_BUILD_TYPE=Release -DCOPILOT_BUILD_TESTS=ON
+        run: cmake -B build -DCMAKE_BUILD_TYPE=Release
 
       - name: Build
         run: cmake --build build --config Release
 
-      - name: Run Unit Tests
-        run: ctest --test-dir build -C Release -E "^E2ETest\." --output-on-failure
-        env:
-          COPILOT_SDK_CPP_SKIP_E2E: 1
+      - name: Check generated protocol catalog
+        run: cmake --build build --config Release --target copilot_codegen_check

CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 0.4.2
+
+- Update protocol coverage for Copilot CLI 1.0.102-1.
+- Add request-correlated and structured message waiting, live tool replacement,
+  skill providers, installation confirmation, and extension launch callbacks.
+- Expand session, agent, provider, MCP authentication, and binary filesystem APIs.
+- Fix hook error-object parsing, reentrant JSON-RPC callbacks, request cancellation,
+  session admission races, and runtime shutdown and process-tree cleanup.

CMakeLists.txt

@@ -1,5 +1,5 @@
 cmake_minimum_required(VERSION 3.20)
-project(copilot_sdk_cpp VERSION 0.4.1 LANGUAGES CXX)
+project(copilot_sdk_cpp VERSION 0.4.2 LANGUAGES CXX)
 
 # Enable folder organization in IDEs
 set_property(GLOBAL PROPERTY USE_FOLDERS ON)
@@ -13,9 +13,7 @@ set(CMAKE_CXX_STANDARD_REQUIRED ON)
 set(CMAKE_CXX_EXTENSIONS OFF)
 
 # Options
-option(COPILOT_BUILD_TESTS "Build tests" ON)
 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
@@ -73,7 +71,7 @@ add_library(copilot_sdk_cpp
     include/copilot/types.hpp
     include/copilot/events.hpp
     include/copilot/extension.hpp
-    include/copilot/factory.hpp
+    include/copilot/workflow.hpp
     include/copilot/generated/api_types.hpp
     include/copilot/generated/compatibility_types.hpp
     include/copilot/generated/protocol_version.hpp
@@ -96,7 +94,7 @@ add_library(copilot_sdk_cpp
     src/types.cpp
     src/events.cpp
     src/extension.cpp
-    src/factory.cpp
+    src/workflow.cpp
     src/transport.cpp
     src/transport_ffi.cpp
     src/jsonrpc.cpp
@@ -144,12 +142,6 @@ set_target_properties(copilot_sdk_cpp PROPERTIES
     FOLDER "Libraries"
 )
 
-# Tests
-if(COPILOT_BUILD_TESTS)
-    enable_testing()
-    add_subdirectory(tests)
-endif()
-
 # Examples
 if(COPILOT_BUILD_EXAMPLES)
     add_subdirectory(examples)

CONTRIBUTING.md

@@ -7,19 +7,20 @@ cmake -S . -B build
 cmake --build build --config Release
 ```
 
-## Tests
+## Validation
+
+Build the library and examples, then check the generated protocol catalog:
 
 ```sh
-ctest --test-dir build -C Release --output-on-failure
+cmake --build build --target copilot_codegen_check
 ```
 
-- E2E tests require the Copilot CLI (`copilot`) to be installed and authenticated.
-- Skip E2E tests in CI/non-interactive runs: set `COPILOT_SDK_CPP_SKIP_E2E=1`.
+The catalog check requires Python 3.
 
 ## Style
 
 - Format C++ with `.clang-format` (4 spaces, Allman braces):
-  - `clang-format -i src/*.cpp include/copilot/*.hpp examples/*.cpp tests/*.cpp`
+  - `clang-format -i src/*.cpp include/copilot/*.hpp examples/*.cpp`
 
 ## Pull Requests
 

README.md

@@ -6,6 +6,27 @@ C++ SDK for interacting with the Copilot CLI agent runtime (JSON-RPC over stdio
 [![C++20](https://img.shields.io/badge/C%2B%2B-20-blue)]()
 [![License](https://img.shields.io/badge/license-MIT-green)]()
 
+## Version 0.4.2
+
+Targets Copilot CLI 1.0.102-1 and SDK protocol version 3.
+
+- Correlate message waiters with the originating request, including sub-agent,
+  abort, and autopilot events; receive structured JSON with `response_schema`
+  and `send_and_wait_structured`.
+- Replace session tools at runtime with `Session::set_tools`; use tool namespaces
+  and per-invocation agent/request identifiers.
+- Supply session skill providers, installation confirmation handlers, and extension
+  launch providers. Handle MCP authentication token updates or runtime refresh.
+- Configure diagnostics, agent/hook directories, sandboxing, image generation,
+  transcript recovery, and the expanded provider/agent options.
+- Cancel incoming JSON-RPC requests and run request callbacks independently of the
+  reader. Retire session callbacks on teardown and shut down owned runtimes gracefully.
+- Use generated binary SessionFs request/result types and report partial writes
+  with `SessionFsError::write_changed`.
+
+Known limitations: experimental AHP hosting is not implemented. The in-process
+macOS UI-thread dispatcher is not provided.
+
 ## Build
 
 Requirements: CMake 3.20+ and a C++20 compiler.
@@ -15,29 +36,11 @@ cmake -S . -B build
 cmake --build build --config Release
 ```
 
-## Tests
-
-Unit tests:
-
-```sh
-ctest --test-dir build -C Release --output-on-failure
-```
-
-E2E tests (real Copilot CLI):
-- Require `copilot` to be installed and authenticated.
-- To disable E2E tests in CI/non-interactive runs, set `COPILOT_SDK_CPP_SKIP_E2E=1`.
-
-Snapshot conformance tests (optional):
-- Require Python 3 and the upstream `copilot-sdk` snapshots directory.
-- Install Python deps: `python -m pip install --user -r tests/snapshot_tests/requirements.txt`
-- 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
+schema hashes, and the complete generated surface: 1,899 API definitions, 679
+session-event definitions, 619 RPC methods, and 163 event variants. Generated
 wire-preserving types live under `include/copilot/generated/`; the existing
 handwritten public API remains the ergonomic layer.
 
@@ -73,8 +76,8 @@ Advanced parity includes:
   `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.
+- `create_canvas`, `define_workflow`, `Session::workflow()`, and `join_session`
+  helpers for canvas, workflow, and extension consumers.
 
 ## Custom Tools
 

include/copilot/cancellation.hpp

@@ -0,0 +1,127 @@
+// Copyright (c) 2025 Elias Bachaalany
+// SPDX-License-Identifier: MIT
+
+#pragma once
+
+#include <atomic>
+#include <cstdint>
+#include <functional>
+#include <map>
+#include <memory>
+#include <mutex>
+#include <vector>
+
+namespace copilot
+{
+
+namespace detail
+{
+
+struct CancellationState
+{
+    std::atomic<bool> cancelled{false};
+    std::mutex mutex;
+    uint64_t next_callback_id = 1;
+    std::map<uint64_t, std::function<void()>> callbacks;
+
+    void cancel()
+    {
+        std::map<uint64_t, std::function<void()>> to_run;
+        {
+            std::lock_guard<std::mutex> lock(mutex);
+            if (cancelled.exchange(true))
+                return;
+            to_run.swap(callbacks);
+        }
+        for (auto& [_, callback] : to_run)
+        {
+            try
+            {
+                callback();
+            }
+            catch (...)
+            {
+            }
+        }
+    }
+};
+
+} // namespace detail
+
+/// Observer side of a cancellation signal. A default-constructed token is never
+/// cancelled. Copies share state.
+class CancellationToken
+{
+  public:
+    CancellationToken() = default;
+
+    bool is_cancelled() const noexcept
+    {
+        return state_ && state_->cancelled.load();
+    }
+
+    /// Run `callback` once when the token is cancelled (immediately if it already
+    /// is). Returns an id for unregister(); 0 when the callback ran inline or the
+    /// token can never be cancelled.
+    uint64_t on_cancel(std::function<void()> callback) const
+    {
+        if (!state_)
+            return 0;
+        {
+            std::lock_guard<std::mutex> lock(state_->mutex);
+            if (!state_->cancelled.load())
+            {
+                const auto id = state_->next_callback_id++;
+                state_->callbacks.emplace(id, std::move(callback));
+                return id;
+            }
+        }
+        callback();
+        return 0;
+    }
+
+    void unregister(uint64_t id) const
+    {
+        if (!state_ || id == 0)
+            return;
+        std::lock_guard<std::mutex> lock(state_->mutex);
+        state_->callbacks.erase(id);
+    }
+
+  private:
+    friend class CancellationSource;
+    explicit CancellationToken(std::shared_ptr<detail::CancellationState> state)
+        : state_(std::move(state))
+    {
+    }
+
+    std::shared_ptr<detail::CancellationState> state_;
+};
+
+/// Owner side of a cancellation signal.
+class CancellationSource
+{
+  public:
+    CancellationSource() : state_(std::make_shared<detail::CancellationState>()) {}
+
+    CancellationToken token() const
+    {
+        return CancellationToken(state_);
+    }
+
+    /// Signal cancellation; callbacks run on the calling thread, once.
+    void cancel()
+    {
+        state_->cancel();
+    }
+
+    bool is_cancelled() const noexcept
+    {
+        return state_->cancelled.load();
+    }
+
+  private:
+    std::shared_ptr<detail::CancellationState> state_;
+};
+
+} // namespace copilot

include/copilot/canvas.hpp

@@ -18,7 +18,10 @@ class CanvasError : public std::runtime_error
     {
     }
 
-    const std::string& code() const noexcept { return code_; }
+    const std::string& code() const noexcept
+    {
+        return code_;
+    }
 
   private:
     std::string code_;
@@ -29,6 +32,8 @@ struct CanvasAction
     std::string name;
     std::optional<std::string> description;
     std::optional<json> input_schema;
+    /// Returned JSON becomes the invoke_canvas_action tool result. A ToolResultObject
+    /// shape with binaryResultsForLlm supplies images to the model.
     std::function<json(const json&)> handler;
 };
 
@@ -48,8 +53,14 @@ class Canvas
   public:
     explicit Canvas(CanvasOptions options);
 
-    const std::string& id() const noexcept { return id_; }
-    const json& declaration() const noexcept { return declaration_; }
+    const std::string& id() const noexcept
+    {
+        return id_;
+    }
+    const json& declaration() const noexcept
+    {
+        return declaration_;
+    }
     json handle_open(const json& request) const;
     void handle_close(const json& request) const;
     json handle_action(const std::string& action, const json& request) const;