From eb6bdd788f6b8de0bbc23f9f43ef3212a2e7f2a7 Mon Sep 17 00:00:00 2001 From: Vladimir Pavlov <43521651+MisterVVP@users.noreply.github.com> Date: Sat, 4 Jul 2026 22:48:55 +0300 Subject: [PATCH 1/2] Overhaul mdBook docs for v0.2.0 --- book/src/README.md | 44 ++++---- book/src/SUMMARY.md | 7 +- book/src/api-reference.md | 28 +++-- book/src/auth/overview.md | 41 ++++--- book/src/client/cancel-task.md | 30 ++--- book/src/client/discovery.md | 42 ++++--- book/src/client/get-task.md | 33 +++--- book/src/client/overview.md | 50 +++++---- book/src/client/sending-messages.md | 45 +++----- book/src/getting-started/installation.md | 105 ++++++------------ book/src/getting-started/quickstart.md | 60 +++++----- book/src/releases.md | 25 +++++ book/src/server/custom-executor.md | 39 +++---- book/src/server/interceptors.md | 24 ++++ book/src/server/json-rpc-server.md | 23 ++-- book/src/server/overview.md | 46 ++++---- book/src/server/push-notifications.md | 37 ++++++ book/src/server/rest-server.md | 26 ++--- book/src/streaming/overview.md | 32 +++--- book/src/transports/grpc.md | 36 +++++- book/src/transports/json-rpc.md | 24 ++-- book/src/transports/overview.md | 25 +++++ book/src/transports/rest.md | 26 ++--- .../17-google-sdk-readiness-checklist.md | 2 +- ...nformance-and-sdk-application-readiness.md | 2 +- ...9-windows-build-dependency-acceleration.md | 2 +- .../documentation/task-1-bootstrap-mdbook.md | 1 - docs/parity-a2a.md | 2 +- docs/sdk-readiness.md | 4 +- 29 files changed, 462 insertions(+), 399 deletions(-) create mode 100644 book/src/releases.md create mode 100644 book/src/server/interceptors.md create mode 100644 book/src/server/push-notifications.md create mode 100644 book/src/transports/overview.md diff --git a/book/src/README.md b/book/src/README.md index 4659b3a..0603569 100644 --- a/book/src/README.md +++ b/book/src/README.md @@ -1,32 +1,28 @@ # a2a-cpp C++20 Agent2Agent (A2A) SDK Documentation -Welcome to the **a2a-cpp** documentation for the C++20 Agent2Agent (A2A) SDK. +**a2a-cpp** is a C++20 SDK for building Agent2Agent (A2A) protocol clients and servers. The current documented release focuses on production-oriented protocol coverage: REST, JSON-RPC, and gRPC transports; Agent Card discovery; task lifecycle APIs; streaming; push notification configuration APIs; authentication metadata propagation; interceptors; CMake package exports; and vcpkg-oriented packaging. -Use this guide to: +## What is included -- install and build the SDK, -- build A2A clients and servers, -- select a transport (REST, JSON-RPC, or gRPC), and -- integrate streaming and authentication. +- Client API: `SendMessage`, `GetTask`, `ListTasks`, `CancelTask`, streaming send/subscribe, and task push-notification config lifecycle calls. +- Server API: executor-driven dispatch for REST, JSON-RPC, and gRPC transports. +- Discovery: public and extended Agent Card fetch plus preferred-interface resolution. +- Streaming: client observers, cancellable stream handles, and server stream sessions. +- Authentication hooks: client credential providers and server request metadata extraction. +- Operational extensions: client/server interceptors, required-extension validation, task stores, task history ordering, UUIDv7 task IDs, and optional PostgreSQL stores. +- Build integration: CMake 3.25+, C++20, installable CMake package exports, generated protobuf headers, and vcpkg overlay/public-registry preparation. -## Start here +## Recommended reading path -- New to the SDK? Begin with the [Quickstart: Build and Run a REST Client](getting-started/quickstart.md). -- Building a client workflow? Continue to [Send Messages with A2AClient](client/sending-messages.md). -- Implementing server-side execution? Read [Custom Executor Design and Implementation](server/custom-executor.md). -- Choosing a transport? Compare [REST Transport](transports/rest.md), [JSON-RPC Transport](transports/json-rpc.md), and [gRPC Transport](transports/grpc.md). -- Securing requests? Review [Authentication Overview](auth/overview.md). +1. [Installation and Build](getting-started/installation.md) for toolchain requirements and CMake options. +2. [Quickstart](getting-started/quickstart.md) for a copy/paste example flow. +3. [Client Overview](client/overview.md) or [Server Overview](server/overview.md), depending on your integration role. +4. [Transports](transports/rest.md), [Streaming](streaming/overview.md), and [Authentication](auth/overview.md) for runtime design decisions. +5. [API Reference](api-reference.md) when you need generated public-header details. -## SDK scope and capabilities +## Version and support notes -The SDK supports production-focused A2A capabilities including: - -- Agent card discovery and task lifecycle APIs, -- REST, JSON-RPC, and gRPC transport integrations, -- Streaming event consumption, -- Client credential providers and server auth metadata propagation, -- Build integration with CMake and vcpkg. - -## Examples - -Curated CMake consumer examples live in the repository [`examples/`](../../examples/) directory and cover FetchContent plus installed-package usage. +- See [Releases and Versions](releases.md) for current release details and versioning guidance. +- The SDK is C++20-only and exports CMake targets under the `a2a::` namespace. +- Package documentation describes vcpkg workflows only. +- Examples are deterministic and are intended to run without external services unless the example README says otherwise. diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md index cd30c9f..fb5d339 100644 --- a/book/src/SUMMARY.md +++ b/book/src/SUMMARY.md @@ -12,12 +12,15 @@ - [Custom Executor](server/custom-executor.md) - [REST Server](server/rest-server.md) - [JSON-RPC Server](server/json-rpc-server.md) -- [Transports](transports/rest.md) + - [Push Notifications](server/push-notifications.md) + - [Interceptors](server/interceptors.md) +- [Transports](transports/overview.md) + - [REST](transports/rest.md) - [JSON-RPC](transports/json-rpc.md) - [gRPC](transports/grpc.md) - [Streaming](streaming/overview.md) - [Authentication](auth/overview.md) +- [Releases and Versions](releases.md) - [Build](build/cmake.md) - [vcpkg](build/vcpkg.md) - - [Conan](build/conan.md) - [API Reference](api-reference.md) diff --git a/book/src/api-reference.md b/book/src/api-reference.md index 90436cb..506fc67 100644 --- a/book/src/api-reference.md +++ b/book/src/api-reference.md @@ -1,26 +1,24 @@ # API Reference -The C++ API reference is generated from public headers under `include/a2a/**` using Doxygen and is published with this documentation site. +The generated C++ API reference is built from public headers under `include/a2a/**`. -## Open the generated reference +## Generated reference -- [C++ API Reference (generated)](api/cpp/index.html) +When published with the documentation site, open: -## Coverage +- [C++ API Reference](api/cpp/index.html) -The generated API includes the public interfaces for: - -- Core primitives (`a2a::core`) -- Client APIs and transports (`a2a::client`) -- Server APIs and transports (`a2a::server`) -- Authentication-related client hooks (`a2a::client::auth`) - -## Local regeneration - -From the repository root: +## Generate locally ```bash ./scripts/generate_api_reference.sh ``` -By default this writes generated pages to `book-build/api/cpp`. +The script writes generated pages to `book-build/api/cpp`. + +## Public API areas + +- `a2a::core`: results, errors, protocol constants, JSON/protobuf helpers, Agent Card support, task state helpers, and versioning. +- `a2a::client`: `A2AClient`, transports, discovery, auth hooks, call options, interceptors, and streaming observers. +- `a2a::server`: executor, dispatcher, transports, interceptors, task stores, task lifecycle helpers, push notifications, and Agent Card serialization. +- `a2a::http`: shared outbound HTTP client abstraction used by default REST/JSON-RPC/discovery/push paths when libcurl is enabled. diff --git a/book/src/auth/overview.md b/book/src/auth/overview.md index 2fd8a86..e7b9dac 100644 --- a/book/src/auth/overview.md +++ b/book/src/auth/overview.md @@ -1,32 +1,31 @@ -# Authentication Overview for A2A Client and Server Flows +# Authentication and Authorization Hooks -Client-side authentication hooks are provided in `include/a2a/client/auth.h`. +The SDK provides hooks for carrying credentials and auth metadata. Your application remains responsible for credential storage, verification, authorization decisions, and audit policy. -For end-to-end request flow context, pair this guide with [Send Messages with A2AClient](../client/sending-messages.md), [Custom Executor Design and Implementation](../server/custom-executor.md), and transport docs for [REST](../transports/rest.md) or [JSON-RPC](../transports/json-rpc.md). +## Client credential providers -## Supported client auth patterns +`include/a2a/client/auth.h` includes providers for: -- **API key auth** via `ApiKeyCredentialProvider` -- **Bearer token auth** via `BearerTokenCredentialProvider` -- **Custom header auth** via `CustomHeaderCredentialProvider` -- **OAuth2 extension point** via `OAuth2BearerCredentialProvider` +- API key headers. +- Bearer token headers. +- Custom header credentials. +- OAuth2 bearer token extension points. -## Server-side metadata extraction +Use these with transport call options or request construction paths that support metadata injection. -Server request context metadata (`RequestContext::auth_metadata`) is populated from inbound auth headers in REST and JSON-RPC transports. Executor logic can use this metadata for authorization and auditing. +## Server metadata -## mTLS notes +REST, JSON-RPC, and gRPC server paths populate `RequestContext` with transport metadata. Executor or interceptor code can read this metadata to make authorization decisions. -mTLS is transport/runtime-termination dependent. If your deployment terminates TLS before the SDK boundary, propagate verified client identity metadata safely into request headers/context. If transport-native mTLS is enabled in your stack, ensure certificate validation, trust store rotation, and least-privilege identity mapping are documented and tested. +## Policy guidance -## Operational guidance +- Never hardcode secrets in source, examples, or tests. +- Validate credentials before trusting request metadata. +- Normalize auth failures so callers receive consistent protocol errors. +- Avoid logging raw credentials. +- Prefer short-lived tokens and managed secret storage. +- Document how TLS or mTLS identity is terminated and propagated into the SDK boundary. -- Do not hardcode secrets in source or test fixtures. -- Rotate keys/tokens and keep credential lifetimes bounded. -- Treat all inbound metadata as untrusted until validated against policy. -- Test auth success and failure paths end-to-end through transport integration tests. +## Example -## References - -- `tests/integration/rest_server_transport_integration_test.cpp` -- `README.md` +See `examples/apps/auth_policy_server/main.cpp` for an auth-policy shape. diff --git a/book/src/client/cancel-task.md b/book/src/client/cancel-task.md index f600a03..b01a5d3 100644 --- a/book/src/client/cancel-task.md +++ b/book/src/client/cancel-task.md @@ -1,27 +1,19 @@ # Cancel Task -`CancelTask` requests cancellation of in-flight work. +`A2AClient::CancelTask` asks the server to cancel in-flight work. -## When to use +## When to use cancellation -- User explicitly aborts an operation. -- Upstream deadline expires and work should stop. -- Supervising process needs to reclaim resources. +- A user aborts an operation. +- A deadline expires upstream. +- Supervising logic needs to reclaim compute or queue capacity. -## Happy path +## Semantics -1. Keep the task ID returned by `SendMessage`. -2. Issue `CancelTask` for that task ID. -3. Confirm task moves to a terminal canceled state via `GetTask` or stream events. +Cancellation is best-effort. A task can complete before the cancellation request is processed, and servers can reject cancellation for completed, unknown, or policy-protected tasks. -## Operational context +## Recommended behavior -- Cancellation is best-effort; completion may race with cancellation. -- Make cancellation idempotent in higher-level workflows. -- Document user-visible semantics (for example, whether partial outputs are retained). - -## Failure scenarios - -- Unknown task ID. -- Task already completed. -- Task cannot be canceled due to policy/executor constraints. +- Make higher-level cancellation idempotent. +- Return or display the latest task state after cancellation attempts. +- Preserve enough audit data to explain whether the task was canceled, completed, or rejected. diff --git a/book/src/client/discovery.md b/book/src/client/discovery.md index 7cab7d8..a12f190 100644 --- a/book/src/client/discovery.md +++ b/book/src/client/discovery.md @@ -1,25 +1,35 @@ -# Discovery +# Discovery and Agent Cards -Discovery resolves where and how to call an A2A agent. +Discovery resolves server capabilities before constructing a client transport. -## Happy path +## Public and extended cards -1. Use `DiscoveryClient` to fetch an `AgentCard`. -2. Use `AgentCardResolver` to select an endpoint and transport. -3. Use resolved endpoint metadata to construct your client transport. +`DiscoveryClient` supports: -## Operational context +- `Fetch(base_url)` for the standard Agent Card. +- `FetchExtendedAgentCard(base_url)` for the extended Agent Card endpoint. -- Cache discovery results where practical, with clear refresh strategy. -- Handle missing/partial card metadata defensively. -- Prefer explicit fallback order when multiple transports are available. +Fetched cards are cached for `kDefaultDiscoveryCacheTtl` (300 seconds) unless a different TTL is supplied. -## Failure scenarios +## Interface resolution -- Discovery endpoint unavailable. -- Invalid or incomplete `AgentCard`. -- Unsupported transport in discovered card. +`AgentCardResolver::SelectPreferredInterface(card, preferred)` selects a `ResolvedInterface` for one of: -## Example +- `PreferredTransport::kRest` +- `PreferredTransport::kJsonRpc` +- `PreferredTransport::kGrpc` -See `examples/apps/simple_client/main.cpp` for a minimal discovery flow. +The result includes the transport, URL, security requirements, and security schemes needed to configure a client. + +## Operational guidance + +- Validate and log the selected endpoint during startup. +- Prefer an explicit fallback order when cards advertise multiple transports. +- Treat discovery metadata as untrusted input until validated. +- Refresh cached cards after deployment or capability changes. + +## Related files + +- `include/a2a/client/discovery.h` +- `include/a2a/core/agent_card/agent_card_provider.h` +- `include/a2a/server/agent_card/agent_card_serializer.h` diff --git a/book/src/client/get-task.md b/book/src/client/get-task.md index ac1a8ed..9684698 100644 --- a/book/src/client/get-task.md +++ b/book/src/client/get-task.md @@ -1,26 +1,25 @@ -# Get Task +# Get Task and List Tasks -`GetTask` retrieves task state and associated outputs after a send operation. +`GetTask` retrieves a single task by ID. `ListTasks` returns a paginated list of tasks through the client abstraction and supported transports. -## When to use +## GetTask flow -- Polling task progress/state after `SendMessage`. -- Fetching final task payloads when streaming is not enabled. +1. Store the task ID from `SendMessage` or a stream event. +2. Build `lf::a2a::v1::GetTaskRequest`. +3. Call `A2AClient::GetTask`. +4. Interpret task status, artifacts, and history according to your application policy. -## Happy path +## ListTasks flow -1. Persist the returned task ID from `SendMessage`. -2. Call `GetTask` with that task ID. -3. Interpret status and outputs. +`a2a::client::ListTasksRequest` contains: -## Operational context +- `page_size` +- `page_token` -- Retry transient failures with bounded backoff. -- Enforce request deadlines to avoid hanging calls. -- Record task IDs in logs/telemetry for traceability. +The response includes task values plus `next_page_token`. -## Failure scenarios +## Operational guidance -- Unknown task ID. -- Task exists but has not produced outputs yet. -- Authorization mismatch for task visibility. +- Use bounded polling with backoff when not using streaming. +- Enforce authorization checks on server-side task visibility. +- Avoid exposing full task history to clients that do not need it. diff --git a/book/src/client/overview.md b/book/src/client/overview.md index 8c08436..3de4cd9 100644 --- a/book/src/client/overview.md +++ b/book/src/client/overview.md @@ -1,30 +1,38 @@ # Client Overview -Use `a2a::client::A2AClient` to interact with A2A servers over multiple transports. +Use `a2a::client::A2AClient` with a concrete `ClientTransport` to call A2A servers. -## Typical client flow +## Client capabilities -1. Discover an `AgentCard` with `DiscoveryClient`. -2. Resolve endpoint details with `AgentCardResolver`. -3. Construct a transport (`HttpJsonTransport` for REST, or `JsonRpcTransport` for JSON-RPC). -4. Create `A2AClient` with that transport. -5. Invoke operations such as: - - `SendMessage` - - `GetTask` - - `CancelTask` - - `SendStreamingMessage` - - `SubscribeTask` +- `SendMessage` +- `GetTask` +- `ListTasks` +- `CancelTask` +- `SendStreamingMessage` +- `SubscribeTask` +- `CreateTaskPushNotificationConfig` +- `GetTaskPushNotificationConfig` +- `ListTaskPushNotificationConfigs` +- `DeleteTaskPushNotificationConfig` +- Client interceptors via `ClientInterceptor` +- Per-call settings through `CallOptions` + +## Typical flow + +1. Fetch an Agent Card with `DiscoveryClient`. +2. Select an endpoint with `AgentCardResolver::SelectPreferredInterface`. +3. Construct `HttpJsonTransport`, `JsonRpcTransport`, or `GrpcTransport`. +4. Create `A2AClient` with the transport. +5. Invoke task, streaming, or push-notification APIs. +6. Call `Destroy()` during shutdown when you need transport cleanup. + +## Default outbound HTTP + +When libcurl is available and `A2A_ENABLE_LIBCURL=ON`, default constructors/factories can perform buffered outbound REST, JSON-RPC, and discovery calls. For tests, custom TLS policy, mTLS, retries, or embedded runtimes, inject your own requester/fetcher callbacks. ## Runnable examples +- `examples/apps/hello_agent/main.cpp` - `examples/apps/simple_client/main.cpp` -- `examples/apps/rest_server/main.cpp` -- `examples/apps/json_rpc_server/main.cpp` - `examples/apps/streaming_client/main.cpp` - -## Related chapters - -- [Sending Messages](sending-messages.md) -- [Discovery](discovery.md) -- [Get Task](get-task.md) -- [Cancel Task](cancel-task.md) +- `examples/apps/push_notifications/main.cpp` diff --git a/book/src/client/sending-messages.md b/book/src/client/sending-messages.md index 91a9e1b..5e3538b 100644 --- a/book/src/client/sending-messages.md +++ b/book/src/client/sending-messages.md @@ -1,38 +1,29 @@ -# Send Messages with A2AClient +# Sending Messages -This chapter covers the common happy path for sending a message request with `A2AClient`. +`A2AClient::SendMessage` starts or continues a task by sending a protobuf `lf::a2a::v1::SendMessageRequest` through the configured transport. -If you have not built and run examples yet, start with the [Quickstart](../getting-started/quickstart.md). +## Request construction guidance -## Happy path +- Set a stable `message.message_id` for idempotency and diagnostics. +- Let the server generate a task ID for new work unless you are intentionally continuing an existing task. +- Attach push-notification config only when the target Agent Card advertises support and your server policy allows it. +- Use `CallOptions` for per-call deadlines, metadata, or auth settings where supported by the transport. -1. Build or resolve the server endpoint. -2. Initialize a transport (REST or JSON-RPC). -3. Create an `A2AClient`. -4. Build the outgoing message payload. -5. Call `SendMessage`. -6. Inspect task/message response data. +## Response handling -## Operational guidance +The response can contain immediate task state and output data. Persist task identifiers in logs/telemetry so later `GetTask`, `CancelTask`, streaming subscription, or push-notification calls can be correlated. -- Validate endpoint configuration and protocol choice at startup. -- Prefer explicit timeouts at transport boundaries. -- Log request IDs/task IDs for diagnostics. -- Keep request construction deterministic in tests. +## Failure paths to test -## Failure paths to handle +- Network or HTTP/gRPC transport failure. +- Serialization or protocol validation failure. +- Auth policy rejection. +- Unsupported operation or required extension mismatch. +- Duplicate/retry behavior for repeated message IDs. -- Network transport errors. -- Protocol/serialization errors. -- Server-side execution errors. -- Auth failures (401/403 equivalents depending on transport mapping). +## Related pages -## See also - -- [Client Overview](overview.md) +- [Discovery](discovery.md) - [Get Task](get-task.md) - [Cancel Task](cancel-task.md) -- [Authentication Overview](../auth/overview.md) -- [Custom Executor Design and Implementation](../server/custom-executor.md) -- [REST Transport](../transports/rest.md) -- [JSON-RPC Transport](../transports/json-rpc.md) +- [Authentication](../auth/overview.md) diff --git a/book/src/getting-started/installation.md b/book/src/getting-started/installation.md index 7b036fe..7f2fc94 100644 --- a/book/src/getting-started/installation.md +++ b/book/src/getting-started/installation.md @@ -1,108 +1,73 @@ # Installation and Build -This page migrates and expands the previous `docs/build.md` guide into mdBook format. +This page reflects the current build surface for the latest documented release. ## Prerequisites -You need: +Install these tools before configuring the repository: -- **CMake 3.25+** -- **C++20 compiler** (Clang or GCC) -- **Protobuf** with `protoc` -- **gRPC C++** with `grpc_cpp_plugin` -- **clang-format** -- **clang-tidy** +- CMake 3.25 or newer. +- A C++20 compiler, tested primarily with GCC and Clang. +- Protobuf with `protoc`. +- gRPC C++ with `grpc_cpp_plugin`. +- `clang-format` and `clang-tidy` for contributor validation. +- Optional: Doxygen for API reference generation. +- Optional: libcurl for built-in outbound HTTP support. +- Optional: PostgreSQL client libraries when building PostgreSQL-backed stores. -## Configure +## Configure from source ```bash -cmake -S . -B build -DCMAKE_BUILD_TYPE=RelWithDebInfo -DCMAKE_EXPORT_COMPILE_COMMANDS=ON +cmake -S . -B build \ + -DCMAKE_BUILD_TYPE=RelWithDebInfo \ + -DCMAKE_EXPORT_COMPILE_COMMANDS=ON ``` -## Build +Useful options: -```bash -cmake --build build -``` +| Option | Default | Purpose | +|---|---:|---| +| `A2A_ENABLE_TESTING` | `ON` | Builds unit and integration tests. | +| `A2A_BUILD_EXAMPLES` | `ON` | Keeps the root project compatible with example-related CI messaging; curated examples are built as standalone consumers. | +| `A2A_BUILD_BENCHMARKS` | `OFF` | Builds the optional Google Benchmark suite. | +| `A2A_ENABLE_LIBCURL` | `ON` | Enables default buffered outbound HTTP when `CURL::libcurl` is found. | +| `A2A_ENABLE_POSTGRES_STORE` | `OFF` | Builds PostgreSQL task and push-notification stores. | -## Build examples +## Build and test ```bash -cmake -S examples/fetch_content_consumer -B build-example -DA2A_EXAMPLE_APP=hello_agent -cmake --build build-example --parallel -./build-example/a2a_example +cmake --build build --parallel +ctest --test-dir build --output-on-failure ``` -## Generate protobuf code only +Generate only protobuf outputs when needed: ```bash cmake --build build --target a2a_proto_codegen ``` -## Run tests - -```bash -ctest --test-dir build --output-on-failure -``` +Generated headers are written under `build/generated/a2a/v1/` and are installed with the SDK. -## Run formatting checks - -Use the CI-compatible formatting check command: +## Install CMake package artifacts ```bash -mapfile -t CPP_FILES < <(git ls-files '*.h' '*.hpp' '*.c' '*.cpp') -if [ "${#CPP_FILES[@]}" -gt 0 ]; then - clang-format --dry-run --Werror "${CPP_FILES[@]}" -fi +cmake --install build --prefix /tmp/a2a-cpp-install ``` -## Run clang-tidy - -```bash -./scripts/run_clang_tidy.sh build -``` +The install tree includes public headers, generated protobuf headers, libraries, and CMake package files under `lib/cmake/a2a_cpp`. -## Canonical local validation +## Contributor validation -Before opening or updating a PR, run: +For code changes, run the canonical validation script before opening or updating a PR: ```bash ./scripts/verify_changes.sh ``` -This runs format, build, tests, and lint in sequence. - -## Install package artifacts - -```bash -cmake --install build --prefix /tmp/a2a-cpp-install -``` - -This installs headers, generated protobuf headers, static libraries, and exported CMake package files under `lib/cmake/a2a_cpp`. +The script runs the same major local gates as CI: clang-format dry run, configure/build, tests, and clang-tidy. -## Coverage +For documentation-only mdBook changes, build the book: ```bash -python3 -m pip install --upgrade gcovr -./scripts/run_coverage.sh +mdbook build book ``` - -Coverage thresholds: - -- `src/core` line coverage >= 85% -- `src/client` line coverage >= 80% -- `src/server` line coverage >= 80% - -## Run all examples - -```bash -./scripts/run_examples.sh -``` - -## Notes on code generation and CI - -- Proto definitions are in `proto/a2a/v1/a2a.proto`. -- Generated outputs are written to `build/generated/a2a/v1/`. -- Code generation is wired through `a2a::proto_generated` and runs automatically when required. -- `.github/workflows/ci.yml` validates formatting, configure/build, clang-tidy, and tests. -- `.github/workflows/codeql.yml` runs CodeQL analysis for C/C++ on push, pull requests, and a weekly schedule. diff --git a/book/src/getting-started/quickstart.md b/book/src/getting-started/quickstart.md index c48b173..71abd58 100644 --- a/book/src/getting-started/quickstart.md +++ b/book/src/getting-started/quickstart.md @@ -1,56 +1,50 @@ -# Quickstart: Build and Run an A2A REST Client End-to-End +# Quickstart: Build and Run Examples -This quickstart gives a practical, copy/paste flow that goes from build to a runnable client example. +The fastest way to exercise the SDK is through the curated consumer examples. They build the example app sources the same way downstream applications consume the SDK. -Looking for the full docs map first? Start at the [Documentation Home](../README.md). - -## 1) Configure and build with examples - -```bash -cmake -S . -B build -DA2A_BUILD_EXAMPLES=ON -DCMAKE_BUILD_TYPE=RelWithDebInfo -cmake --build build -``` - -## 2) Run a minimal example +## 1. Run the smallest end-to-end example ```bash +cmake -S examples/fetch_content_consumer -B build-example \ + -DA2A_EXAMPLE_APP=hello_agent +cmake --build build-example --parallel ./build-example/a2a_example ``` -Expected behavior: the client performs a minimal REST workflow and exits successfully. +`hello_agent` creates a minimal in-process client/server flow and exits deterministically. -## 3) Try additional examples +## 2. Try transport-specific examples ```bash -./build-example/a2a_example -./build-example/a2a_example -./build-example/a2a_example -./build-example/a2a_example +./scripts/run_examples.sh rest_server json_rpc_server grpc_server ``` -## 4) Run quality gates locally +These examples cover server transport setup and deterministic request handling across REST, JSON-RPC, and gRPC. + +## 3. Try streaming, push, and auth examples ```bash -./scripts/verify_changes.sh +./scripts/run_examples.sh streaming_client streaming_server push_notifications auth_policy_server ``` -This command is the canonical contributor validation entrypoint and should pass before PR updates. +Use these when validating event streams, webhook configuration flows, or server-side auth metadata policy shapes. + +## 4. Consume an installed SDK package -## 5) Optional: run focused checks during iteration +After installing the SDK into a prefix, build the same app source with `find_package(a2a_cpp CONFIG REQUIRED)`: ```bash -ctest --test-dir build --output-on-failure -./scripts/run_clang_tidy.sh build +cmake -S examples/installed_package_consumer -B build-installed-example \ + -DCMAKE_PREFIX_PATH=/tmp/a2a-cpp-install \ + -DA2A_EXAMPLE_APP=hello_agent +cmake --build build-installed-example --parallel +./build-installed-example/a2a_example ``` -## Troubleshooting +## 5. Validate your local checkout -- If configure fails, confirm the required tools from [Installation](installation.md) are installed. -- If example binaries are missing, re-run CMake with `-DA2A_BUILD_EXAMPLES=ON`. -- If `clang-tidy` reports issues, fix touched code and re-run `./scripts/verify_changes.sh`. - -## Next steps +```bash +./scripts/verify_changes.sh +``` -- Continue with [Send Messages with A2AClient](../client/sending-messages.md). -- Review [REST Transport](../transports/rest.md) for endpoint and runtime guidance. -- Add auth headers safely using [Authentication Overview](../auth/overview.md). +For documentation-only edits, use `mdbook build book` instead of the full code validation flow. diff --git a/book/src/releases.md b/book/src/releases.md new file mode 100644 index 0000000..283b18d --- /dev/null +++ b/book/src/releases.md @@ -0,0 +1,25 @@ +# Releases and Versions + +This documentation is intended to stay version-aware without embedding a release number in every page title. + +## Current documented release + +The current documented release is **v0.2.0**. It includes: + +- REST, JSON-RPC, and gRPC client/server transport coverage. +- Agent Card discovery, including extended Agent Card support. +- Task lifecycle APIs including send, get, list, cancel, streaming send, and task subscription. +- Task push-notification configuration APIs and server-side delivery abstractions. +- Client and server interceptors. +- CMake package exports and vcpkg-oriented packaging support. + +## Versioning guidance + +- Pin CMake `FetchContent` integrations to a release tag such as `v0.2.0` or to a reviewed commit. +- Prefer `find_package(a2a_cpp CONFIG REQUIRED)` for installed SDK packages. +- Keep generated protobuf headers and linked SDK libraries from the same installed package or build tree. +- Review release notes before upgrading between minor versions. + +## Documentation policy + +Page titles and navigation should remain mostly version agnostic. Release-specific notes belong on this page or in clearly marked compatibility sections. diff --git a/book/src/server/custom-executor.md b/book/src/server/custom-executor.md index 514d416..61ab9b5 100644 --- a/book/src/server/custom-executor.md +++ b/book/src/server/custom-executor.md @@ -1,30 +1,27 @@ -# Custom Executor Design and Implementation +# Custom Executors -Implement `a2a::server::AgentExecutor` to provide server-side task and message behavior. +Implement `a2a::server::AgentExecutor` to define application behavior. -For a full user journey from build to request handling, see [Quickstart](../getting-started/quickstart.md) and [Send Messages with A2AClient](../client/sending-messages.md). +## Required methods -## Design guidance - -- Keep executor methods focused and deterministic. -- Validate request inputs at API boundaries. -- Return rich failures (structured status/errors according to project conventions). -- Avoid shared mutable state unless synchronization and threading expectations are explicit. +Executors implement task/message operations including: -## Threading and lifecycle +- `SendMessage` +- `SendStreamingMessage` +- `GetTask` +- `ListTasks` +- `CancelTask` -- Define whether your executor is single-threaded or concurrent. -- Ensure referenced resources outlive in-flight requests. -- Use RAII to manage external resources (files, sockets, handles). +Push-notification config methods have default `PushNotificationNotSupported` behavior and should be overridden only when the server actually supports them. -## Testing recommendations +## Request context -- Unit-test executor logic in isolation. -- Add integration tests through REST/JSON-RPC transport paths. -- Cover happy path, validation failures, and cancellation semantics. +Every executor method receives `RequestContext`. Use it for auth metadata, transport metadata, and request-scoped policy decisions. Treat metadata as untrusted until validated. -## Related pages +## Design guidance -- [REST Transport](../transports/rest.md) -- [JSON-RPC Transport](../transports/json-rpc.md) -- [Authentication Overview](../auth/overview.md) +- Keep executor methods small and deterministic. +- Validate inputs at the boundary. +- Return `a2a::core::Result` with structured errors. +- Avoid shared mutable state unless synchronized and documented. +- Unit-test executor behavior separately from transport mapping. diff --git a/book/src/server/interceptors.md b/book/src/server/interceptors.md new file mode 100644 index 0000000..86307d8 --- /dev/null +++ b/book/src/server/interceptors.md @@ -0,0 +1,24 @@ +# Server Interceptors + +Server interceptors let deployments attach cross-cutting behavior around dispatcher operations. + +## Common uses + +- Authorization and policy checks. +- Request/response telemetry. +- Audit logging. +- Metrics and latency measurement. +- Required extension enforcement in combination with transport validators. + +## Design guidance + +- Keep interceptors deterministic and low-latency. +- Avoid logging secrets or raw credential values. +- Use structured errors so transports can map failures consistently. +- Prefer composition: keep business behavior in `AgentExecutor` and cross-cutting behavior in interceptors. + +## Related APIs + +- `a2a::server::ServerInterceptor` +- `a2a::server::Dispatcher::AddInterceptor` +- `a2a::client::ClientInterceptor` for client-side call hooks diff --git a/book/src/server/json-rpc-server.md b/book/src/server/json-rpc-server.md index d70e0e9..8f8d299 100644 --- a/book/src/server/json-rpc-server.md +++ b/book/src/server/json-rpc-server.md @@ -2,22 +2,17 @@ `JsonRpcServerTransport` maps JSON-RPC 2.0 method calls to dispatcher operations. -## Use cases - -- Interop with systems already standardized on JSON-RPC. -- Environments where method-based routing is preferred to REST path routing. +## Responsibilities -## Operational guidance +- Validate the `jsonrpc`, `id`, `method`, and `params` envelope fields. +- Route supported A2A methods to the dispatcher. +- Return JSON-RPC error objects for invalid requests, unknown methods, and executor failures. +- Preserve request metadata for auth and audit policy. -- Validate `jsonrpc`, `id`, and `method` fields consistently. -- Return spec-consistent error objects for invalid requests and method failures. -- Preserve request metadata for auth/audit needs. - -## Authentication behavior +## Use cases -Authentication metadata from inbound headers can be extracted and made available to server execution context. +Use JSON-RPC when method-based routing is easier to integrate than resource-oriented REST paths or when another system already standardizes on JSON-RPC 2.0. -## Related chapters +## Example -- [Server Overview](overview.md) -- [Authentication Overview](../auth/overview.md) +See `examples/apps/json_rpc_server/main.cpp`. diff --git a/book/src/server/overview.md b/book/src/server/overview.md index 0e052cf..44f1e07 100644 --- a/book/src/server/overview.md +++ b/book/src/server/overview.md @@ -1,35 +1,27 @@ # Server Overview -Server integration starts by implementing executor logic and attaching it to a transport. +Server integrations implement `a2a::server::AgentExecutor` and route protocol requests through `Dispatcher` plus one or more transports. -## Core components +## Server capabilities -- `a2a::server::AgentExecutor`: your business logic entrypoint. -- `a2a::server::Dispatcher`: routes protocol operations to executor methods. -- Transport adapter: - - `RestServerTransport` for HTTP+JSON REST paths. - - `JsonRpcServerTransport` for JSON-RPC 2.0 method dispatch. +- REST server transport. +- JSON-RPC server transport. +- gRPC service transport. +- Public and extended Agent Card dispatch when a provider is installed. +- Required extension validation. +- Server interceptors. +- Streaming through `ServerStreamSession`. +- Task lifecycle helpers, in-memory task store, and optional PostgreSQL stores. +- Push-notification config CRUD and delivery service abstractions. -## Happy path +## Core flow -1. Implement a custom executor. -2. Build a `Dispatcher` with that executor. -3. Create REST or JSON-RPC transport. -4. Forward inbound requests to transport `Handle(...)`. +1. Implement an executor for task and message behavior. +2. Create a `Dispatcher` with the executor and optional Agent Card provider/interceptors. +3. Attach REST, JSON-RPC, or gRPC transport adapters. +4. Convert inbound framework requests into transport calls. +5. Return structured protocol errors instead of transport-specific ad hoc errors. -## Task ID generation +## Task IDs -- For new incoming messages where `message.taskId` is absent, the SDK service layer generates a server-side task id. -- The default generator is UUIDv7-based and emits ids like `task-0198f2d4-7c4a-7b21-9c02-dc6e7f2b8e91`. -- `message.messageId` is client-provided and is **not** used as a production task identifier. -- You can inject a custom task id strategy via `TaskLifecycleService` constructor if you require opaque/random ids or stricter privacy (UUIDv7 leaks approximate creation time). - -## Example - -See `examples/apps/rest_server/main.cpp` for a minimal in-process setup. - -## Push notifications - -Servers that advertise push support should compose `PushNotificationService` from a task store, a push-config store, and a delivery client. The executor should register inline configs from send-message requests, expose push-config CRUD methods, and call `NotifyTaskUpdated(task)` after task status changes. Propagate that `Result` back to the caller so failed webhook delivery is visible instead of silently ignored. - -`NotifyTaskUpdated` sends a `StreamResponse` status-update payload to each stored config. A delivery-client error, a populated `PushDeliveryResult::error_message`, or a non-2xx delivery status makes the service return an error. For production, prefer a custom delivery client that queues and retries notifications while preserving observability and webhook security controls. The focused sample is `examples/apps/push_notifications/main.cpp`; the reusable executor wiring is in `tests/support/example_support/example_support.h`. +When an incoming message does not carry `message.task_id`, the SDK service layer can generate server-side task IDs using UUIDv7. UUIDv7 is sortable and operationally useful, but it leaks approximate creation time. Inject a custom task ID generator if your deployment needs opaque identifiers. diff --git a/book/src/server/push-notifications.md b/book/src/server/push-notifications.md new file mode 100644 index 0000000..54bc393 --- /dev/null +++ b/book/src/server/push-notifications.md @@ -0,0 +1,37 @@ +# Push Notifications + +The SDK includes task push-notification configuration APIs and server-side delivery abstractions. + +## Client API surface + +`A2AClient` exposes: + +- `CreateTaskPushNotificationConfig` +- `GetTaskPushNotificationConfig` +- `ListTaskPushNotificationConfigs` +- `DeleteTaskPushNotificationConfig` + +Use these only when the target Agent Card and server policy indicate push-notification support. + +## Server components + +- `PushNotificationService` coordinates stored configs and delivery. +- `PushNotificationStore` persists webhook configs. +- `PushNotificationDeliveryClient` abstracts outbound delivery. +- `HttpPushNotificationDeliveryClient` provides a simple libcurl-backed synchronous delivery path when libcurl support is enabled. + +## Recommended executor flow + +1. Persist task state in your `TaskStore` or `TaskLifecycleService`. +2. Register inline configs from `SendMessageRequest` when present. +3. Call `NotifyTaskUpdated(task)` after status changes. +4. Propagate delivery failures instead of silently dropping them. +5. Override push-config CRUD executor methods only when push support is fully configured. + +## Production guidance + +For production, prefer a durable queued delivery client with retries, backoff, webhook URL validation, SSRF controls, credential protection, and delivery telemetry. Keep TLS policy at least as strong as the built-in delivery client, which requires TLS 1.2 or newer for HTTPS URLs. + +## Example + +See `examples/apps/push_notifications/main.cpp`. diff --git a/book/src/server/rest-server.md b/book/src/server/rest-server.md index 16d7187..d163835 100644 --- a/book/src/server/rest-server.md +++ b/book/src/server/rest-server.md @@ -1,24 +1,22 @@ # REST Server Transport -`RestServerTransport` adapts inbound HTTP+JSON requests into server dispatcher calls. +`RestServerTransport` maps HTTP+JSON requests onto dispatcher operations. -## Use cases +## Responsibilities -- Service deployments standardized on REST. -- Environments requiring straightforward HTTP middleware integration. +- Validate HTTP method, path, and content type. +- Parse JSON request bodies into protobuf messages. +- Populate `RequestContext`, including auth metadata. +- Serialize protocol responses and errors back to HTTP responses. -## Operational guidance +## Supported operation shape -- Validate method/path/content-type boundaries strictly. -- Propagate request metadata needed by executors (including auth headers). -- Define timeout and payload size policies explicitly. -- Log stable identifiers for correlation. +REST transport covers core task lifecycle operations, streaming-compatible endpoints where wired by the hosting environment, Agent Card routes, and push-notification config APIs exposed by the dispatcher/executor. -## Authentication behavior +## Hosting guidance -Inbound auth headers can be mapped into request context metadata and consumed by executor logic. +The SDK provides protocol mapping, not a full production web server framework. In production, place it behind an HTTP runtime that owns TLS, connection limits, request-size limits, access logs, and graceful shutdown. -## Related files +## Example -- `tests/integration/rest_server_transport_integration_test.cpp` -- `examples/apps/rest_server/main.cpp` +See `examples/apps/rest_server/main.cpp`. diff --git a/book/src/streaming/overview.md b/book/src/streaming/overview.md index 27d8931..895fd82 100644 --- a/book/src/streaming/overview.md +++ b/book/src/streaming/overview.md @@ -1,27 +1,29 @@ -# Streaming Overview +# Streaming -Streaming is available through: +Streaming is available through client APIs and server stream sessions. -- `A2AClient::SendStreamingMessage` -- `A2AClient::SubscribeTask` +## Client APIs -## Observer contract +- `A2AClient::SendStreamingMessage(request, observer, options)` +- `A2AClient::SubscribeTask(request, observer, options)` Implement `a2a::client::StreamObserver`: -- `OnEvent` for each `StreamResponse` -- `OnError` for transport/protocol failures -- `OnCompleted` on normal stream completion +- `OnEvent(const StreamResponse&)` for each event. +- `OnError(const core::Error&)` for transport or protocol failures. +- `OnCompleted()` when the stream finishes normally. -Use `StreamHandle` to cancel long-running streams. +Both calls return a `StreamHandle`. Call `Cancel()` to request cancellation and `IsActive()` to check handle state. -## Operational guidance +## Threading contract -- Handle event ordering explicitly in consumers. -- Make callback code thread-safe and non-blocking. -- Plan cancellation and shutdown semantics up front. +Observer callbacks run on transport-managed background threads. Keep observers alive until stream completion, cancellation, or handle destruction. Callback code should be thread-safe, fast, and non-blocking. -## Example and tests +## Server side + +Executors return `std::unique_ptr` from `SendStreamingMessage` and, optionally, `SubscribeTask`. A stream session publishes `StreamResponse` values until it returns an empty optional or an error. + +## Examples - `examples/apps/streaming_client/main.cpp` -- `tests/functional/examples_functional_test.cpp` +- `examples/apps/streaming_server/main.cpp` diff --git a/book/src/transports/grpc.md b/book/src/transports/grpc.md index 09f833e..796115d 100644 --- a/book/src/transports/grpc.md +++ b/book/src/transports/grpc.md @@ -1,5 +1,35 @@ -# Grpc +# gRPC Transport -> Placeholder page for Task 1 mdBook bootstrap. +gRPC support is first-class for client and server integrations. -Content for **Grpc** will be added in subsequent documentation tasks. +## Client side + +Use `a2a::client::GrpcTransport` with a resolved interface and either: + +- a `std::shared_ptr` for real gRPC calls, or +- a custom `GrpcTransport::RpcClient` for tests and embedded adapters. + +The transport supports unary task operations, streaming send, task subscription, and push-notification config lifecycle calls. + +## Server side + +`a2a::server::GrpcServerTransport` implements `lf::a2a::v1::A2AService::Service` and routes RPCs to the dispatcher. + +It supports: + +- `SendMessage` +- `SendStreamingMessage` +- `GetTask` +- `ListTasks` +- `CancelTask` +- `SubscribeToTask` +- Push-notification config RPCs +- `GetExtendedAgentCard` + +## Metadata and extensions + +The server transport recognizes A2A metadata such as `a2a-version` and can validate required extensions through `GrpcServerTransportOptions::required_extensions`. + +## Example + +See `examples/apps/grpc_server/main.cpp`. diff --git a/book/src/transports/json-rpc.md b/book/src/transports/json-rpc.md index bf54bec..65692ce 100644 --- a/book/src/transports/json-rpc.md +++ b/book/src/transports/json-rpc.md @@ -1,26 +1,18 @@ -# JSON-RPC Transport for A2A Clients and Servers +# JSON-RPC Transport -JSON-RPC transport supports method-based request dispatch aligned with JSON-RPC 2.0. - -If you are new to the SDK runtime flow, begin with the [Quickstart](../getting-started/quickstart.md). +JSON-RPC transport supports A2A method dispatch over JSON-RPC 2.0 envelopes. ## Client side -Use `JsonRpcTransport` with `A2AClient` for JSON-RPC integrations. +Use `JsonRpcTransport` with `A2AClient`. Default buffered outbound HTTP is available when libcurl is enabled and found; otherwise inject a requester. ## Server side -Use `JsonRpcServerTransport` to decode method calls and route them to dispatcher operations. +Use `JsonRpcServerTransport` to decode envelopes, dispatch operations, and encode JSON-RPC responses. ## Operational considerations -- Validate protocol envelope fields (`jsonrpc`, `id`, `method`). -- Return consistent JSON-RPC error structures. -- Preserve metadata needed for auth and auditing. - -## See also - -- [Send Messages with A2AClient](../client/sending-messages.md) -- [Custom Executor Design and Implementation](../server/custom-executor.md) -- [REST Transport](rest.md) -- [Authentication Overview](../auth/overview.md) +- Validate envelope fields strictly. +- Preserve client-provided request IDs in responses. +- Map structured SDK errors to consistent JSON-RPC error responses. +- Include auth metadata in `RequestContext` only after policy validation. diff --git a/book/src/transports/overview.md b/book/src/transports/overview.md new file mode 100644 index 0000000..76ef44f --- /dev/null +++ b/book/src/transports/overview.md @@ -0,0 +1,25 @@ +# Transports Overview + +The SDK separates protocol operations from transport adapters. Applications choose the transport that best matches their deployment boundary and interoperability needs. + +## Available transports + +- [REST](rest.md): HTTP+JSON resource-oriented integration for clients and servers. +- [JSON-RPC](json-rpc.md): JSON-RPC 2.0 method dispatch over HTTP-style request handling. +- [gRPC](grpc.md): protobuf/gRPC service integration with unary and streaming RPCs. + +## Choosing a transport + +- Choose REST when your platform already standardizes on HTTP routing, gateways, or resource-style APIs. +- Choose JSON-RPC when method-style dispatch is easier to interoperate with or proxy. +- Choose gRPC when you want protobuf-native contracts, gRPC streaming, or a service mesh that already supports gRPC well. + +## Shared operational concerns + +Regardless of transport, define these policies explicitly: + +- Authentication and authorization boundaries. +- Protocol version and required-extension handling. +- Request deadlines and payload limits. +- Retry and idempotency behavior. +- Telemetry, audit logs, and stable task/request identifiers. diff --git a/book/src/transports/rest.md b/book/src/transports/rest.md index b3c022a..4ca0098 100644 --- a/book/src/transports/rest.md +++ b/book/src/transports/rest.md @@ -1,27 +1,19 @@ -# REST Transport for A2A Clients and Servers +# REST Transport -The REST transport uses HTTP+JSON endpoints for A2A operations. - -Need a runnable baseline first? Start with the [Quickstart](../getting-started/quickstart.md). +REST is the HTTP+JSON transport path for clients and servers. ## Client side -Use `HttpJsonTransport` with `A2AClient` when your deployment or gateway standardizes on REST. +Use `HttpJsonTransport` with `A2AClient`. When libcurl is enabled and found, default outbound buffered HTTP can be used. Otherwise inject an `HttpRequester` implementation. ## Server side -Use `RestServerTransport` to map inbound HTTP requests to dispatcher/executor operations. +Use `RestServerTransport` to translate inbound framework requests into dispatcher calls. ## Operational considerations -- Ensure content-type and method validation is strict. -- Configure request deadlines/timeouts. -- Propagate auth metadata safely for policy checks. -- Log stable request/task identifiers. - -## See also - -- [Send Messages with A2AClient](../client/sending-messages.md) -- [Custom Executor Design and Implementation](../server/custom-executor.md) -- [JSON-RPC Transport](json-rpc.md) -- [Authentication Overview](../auth/overview.md) +- Enforce TLS and auth policy at your edge or hosting layer. +- Set explicit request deadlines and payload limits. +- Log stable task IDs and request IDs. +- Validate protocol version headers where required. +- Prefer injected requesters for custom retry, proxy, mTLS, or observability policy. diff --git a/docs/codex-mvp-tasks/development/17-google-sdk-readiness-checklist.md b/docs/codex-mvp-tasks/development/17-google-sdk-readiness-checklist.md index 9bf5505..e3e5ef4 100644 --- a/docs/codex-mvp-tasks/development/17-google-sdk-readiness-checklist.md +++ b/docs/codex-mvp-tasks/development/17-google-sdk-readiness-checklist.md @@ -20,7 +20,7 @@ From A2A community guidance and common SDK expectations: - Add explicit protocol conformance matrix against current A2A specification sections. - Add automated conformance tests (golden request/response and negative protocol cases). - Published package on standard registry - - Define and implement package publication path (vcpkg + Conan recommended for C++). + - Define and implement package publication path (vcpkg recommended for C++). - Add versioning/release policy and signed release artifacts. - Documentation quality - Add API reference generation (Doxygen or Sphinx+Breathe) and publish to GitHub Pages. diff --git a/docs/codex-mvp-tasks/development/18-spec-conformance-and-sdk-application-readiness.md b/docs/codex-mvp-tasks/development/18-spec-conformance-and-sdk-application-readiness.md index f950442..8379a05 100644 --- a/docs/codex-mvp-tasks/development/18-spec-conformance-and-sdk-application-readiness.md +++ b/docs/codex-mvp-tasks/development/18-spec-conformance-and-sdk-application-readiness.md @@ -22,7 +22,7 @@ Based on `https://a2a-protocol.org/latest/community/#the-future-is-interoperable - Add/maintain negative protocol tests (unsupported method, malformed params, version mismatch, auth requirement mismatch). - Add golden cross-SDK interop fixtures (a2a-go ↔ a2a-cpp and a2a-python ↔ a2a-cpp) for core RPCs and streaming events. - Standard registry publishing readiness - - Finalize package metadata and publication automation for at least one mainstream C++ registry (vcpkg and/or ConanCenter). + - Finalize package metadata and publication automation for at least one mainstream C++ registry (vcpkg). - Add reproducible source archive + signature/provenance generation in release workflow. - Validate install + smoke-test flow from published artifacts in CI. - Documentation completeness diff --git a/docs/codex-mvp-tasks/development/19-windows-build-dependency-acceleration.md b/docs/codex-mvp-tasks/development/19-windows-build-dependency-acceleration.md index a40a649..d97a73b 100644 --- a/docs/codex-mvp-tasks/development/19-windows-build-dependency-acceleration.md +++ b/docs/codex-mvp-tasks/development/19-windows-build-dependency-acceleration.md @@ -10,7 +10,7 @@ Reduce Windows CI build startup time (currently dominated by manifest dependency - Measure current Windows job timings broken down by checkout, tool bootstrap, dependency resolution, configure, build, and test stages. - Capture dependency graph and identify the highest-latency packages. - Caching and artifact reuse - - Add robust cache keys for package manager artifacts (vcpkg/Conan cache, build tree, compiler cache where applicable). + - Add robust cache keys for package manager artifacts (vcpkg cache, build tree, compiler cache where applicable). - Separate cache keys for lockfile/manifests vs source changes to maximize hit rate. - Add fallback behavior that avoids full cold reinstalls when partial cache is valid. - Build graph optimization diff --git a/docs/codex-mvp-tasks/documentation/task-1-bootstrap-mdbook.md b/docs/codex-mvp-tasks/documentation/task-1-bootstrap-mdbook.md index 9f03953..7dd2636 100644 --- a/docs/codex-mvp-tasks/documentation/task-1-bootstrap-mdbook.md +++ b/docs/codex-mvp-tasks/documentation/task-1-bootstrap-mdbook.md @@ -24,7 +24,6 @@ Create the mdBook skeleton and navigation so the docs site builds with placehold - `auth/overview.md` - `build/cmake.md` - `build/vcpkg.md` - - `build/conan.md` - `api-reference.md` - Keep root `README.md` concise and SEO-oriented. diff --git a/docs/parity-a2a.md b/docs/parity-a2a.md index 8c74a30..665750d 100644 --- a/docs/parity-a2a.md +++ b/docs/parity-a2a.md @@ -18,7 +18,7 @@ This matrix compares public `a2a-go` v2 and `a2a-python` SDK surfaces against cu | `GetExtendedAgentCard` API | Present | Present | Present as first-class API | ✅ parity | | Push-config lifecycle APIs (`ListTaskPushConfigs`, etc.) | Present | Present | Present across client transports | ✅ parity | | CLI workflow utility | Present (`cmd/a2a`) | Present (CLI package in repo) | Missing | ❌ gap | -| Standard package registry signal | Present (`go get`, pkg.go.dev indexed) | Present (`pip install a2a-sdk`, PyPI) | Partial (Conan + vcpkg workflow exists; public-registry proof still incomplete) | ⚠️ partial | +| Standard package registry signal | Present (`go get`, pkg.go.dev indexed) | Present (`pip install a2a-sdk`, PyPI) | Partial (vcpkg workflow exists; public-registry proof still incomplete) | ⚠️ partial | | Maintainer readiness signals (templates, governance cadence, support policy) | Present | Present | Partial | ⚠️ partial | ## Gap-to-task mitigation map diff --git a/docs/sdk-readiness.md b/docs/sdk-readiness.md index dc0ca49..1874421 100644 --- a/docs/sdk-readiness.md +++ b/docs/sdk-readiness.md @@ -3,7 +3,7 @@ ## Current status - ✅ Spec compliance: parity matrix + conformance tests tracked and partially implemented. -- ⚠️ Standard registry packaging: Conan (GitHub Packages) workflow and vcpkg public-registry submission workflow are added; repository secrets and port PR still required. +- ⚠️ Standard registry packaging: vcpkg public-registry submission workflow is added; repository secrets and port PR still required. - ✅ Documentation: build, quickstart, usage guides exist; API doc generation workflow added. - ✅ Tests with CI: Linux CI plus sanitizer/valgrind/coverage and examples smoke. - ✅ Apache 2.0 license: repository carries Apache-2.0 license. @@ -14,7 +14,7 @@ - Conformance tests: `tests/integration/*` and `tests/fixtures/*`. - Coverage gate: `.github/workflows/ci.yml` + `scripts/run_coverage.sh`. - Examples runnable matrix: `examples/README.md` + `scripts/run_examples.sh`. -- Packaging manifests: `conanfile.py`, `vcpkg.json`. +- Packaging manifest: `vcpkg.json`. - Packaging workflow docs: `docs/packaging.md`, `.github/workflows/release-packages.yml`. - Governance docs: `SECURITY.md`, `SUPPORT.md`, `.github/ISSUE_TEMPLATE/*`, `.github/pull_request_template.md`, `.github/CODEOWNERS`. From d5ed85c8b8f8918f21ac4aec4176da0689b847e5 Mon Sep 17 00:00:00 2001 From: Vladimir Pavlov <43521651+MisterVVP@users.noreply.github.com> Date: Sat, 4 Jul 2026 23:59:57 +0300 Subject: [PATCH 2/2] docs: expand and reorganize mdBook docs (transports, server features, releases, quickstart) ### Motivation - Expand the mdBook documentation from a bootstrap skeleton into a usable developer guide covering client/server APIs, transports, streaming, auth, and operational guidance. - Add missing conceptual pages (releases/versioning, transports overview, interceptors, push-notifications) and improve quickstart and installation guidance for contributors and consumers. - Align README/SUMMARY navigation and examples with the documented SDK surface so readers can find API and example usage easily. ### Description - Rewrote and expanded `book/src/README.md`, `SUMMARY.md`, and many client/server/transports/streaming/auth pages to provide concrete API lists, recommended flows, and operational guidance. - Added new pages: `book/src/releases.md`, `book/src/server/interceptors.md`, `book/src/server/push-notifications.md`, and `book/src/transports/overview.md` to document releases, server interceptor patterns, push-notification APIs, and transport selection guidance. - Improved developer workflows and examples in `getting-started/installation.md` and `getting-started/quickstart.md`, added clearer CMake usage, build/test commands, and install instructions, and updated API reference generation notes in `api-reference.md`. - Updated docs and parity/readiness files under `docs/` to reflect current packaging focus (vcpkg) and to tighten the SDK readiness/parity narratives. ### Testing - Built the docs site with `mdbook build book` to validate the generated book and navigation, and the build completed successfully. - No source code changes were made, so unit/integration test suites were unaffected by this documentation-only update. --- docs/codex-mvp-tasks/README.md | 20 +++++++++++++++++++ .../development/00-backlog-overview.md | 2 ++ .../01-repo-bootstrap-and-codegen.md | 2 ++ .../02-core-versioning-errors-protojson.md | 2 ++ .../development/03-agent-card-discovery.md | 2 ++ .../04-http-json-client-core-rpcs.md | 2 ++ .../development/05-sse-streaming-client.md | 2 ++ .../development/06-json-rpc-client.md | 2 ++ ...ver-core-executor-dispatcher-task-store.md | 2 ++ .../development/08-rest-server-transport.md | 2 ++ .../09-json-rpc-server-transport.md | 2 ++ .../development/10-auth-security-hooks.md | 2 ++ .../development/11-examples-interop-and-ci.md | 2 ++ .../12-parity-gap-analysis-vs-a2a-go.md | 2 ++ .../development/13-grpc-transport-parity.md | 2 ++ ...i-parity-extended-rpcs-and-interceptors.md | 2 ++ .../15-test-coverage-and-quality-gates.md | 2 ++ ...amples-expansion-and-local-runner-guide.md | 2 ++ .../17-google-sdk-readiness-checklist.md | 2 ++ ...nformance-and-sdk-application-readiness.md | 2 ++ ...9-windows-build-dependency-acceleration.md | 2 ++ .../20-cross-sdk-parity-vs-a2a-python.md | 2 ++ .../21-python-cross-sdk-interop-ci.md | 2 ++ .../22-python-cli-workflow-parity.md | 2 ++ docs/codex-mvp-tasks/documentation/README.md | 4 ++++ .../documentation/task-1-bootstrap-mdbook.md | 2 ++ .../task-2-migrate-expand-docs.md | 2 ++ .../task-3-github-pages-workflow.md | 2 ++ .../task-4-seo-release-hardening.md | 2 ++ ...k-5-generated-api-reference-publication.md | 2 ++ 30 files changed, 80 insertions(+) diff --git a/docs/codex-mvp-tasks/README.md b/docs/codex-mvp-tasks/README.md index 3685f27..1a12fae 100644 --- a/docs/codex-mvp-tasks/README.md +++ b/docs/codex-mvp-tasks/README.md @@ -2,6 +2,26 @@ This folder contains an ordered set of implementation tasks for building an **A2A SDK in C++** targeting **A2A protocol 1.0 only**. +## Current use and authority + +This folder is an internal planning/archive task pack for agents and maintainers. It is useful for understanding implementation intent, task sequencing, and historical acceptance criteria, but it is **not** the canonical source for current user-facing behavior. + +When a task file conflicts with current repository state, prefer these sources in order: + +1. Source code, tests, and CI workflows. +2. Current mdBook content under `book/src/**`. +3. Focused current docs under `docs/**` outside this task-pack folder. +4. These task files as historical planning context. + +Each task now carries status metadata near the title. Status values mean: + +- **Historical / completed**: the task described earlier implementation work and may be superseded by current source or docs. +- **Active follow-up**: the task still describes useful follow-up work or evidence collection. +- **Planned / decision needed**: the task is a future decision or parity item that should be revalidated before implementation. +- **Superseded**: the task contains assumptions known to be obsolete; keep it only for project history unless it is rewritten. + +Before using any task as implementation guidance, verify current state with source, tests, workflows, and mdBook docs. + ## Ground rules - Protocol target: **A2A 1.0** diff --git a/docs/codex-mvp-tasks/development/00-backlog-overview.md b/docs/codex-mvp-tasks/development/00-backlog-overview.md index 51dc7d5..e8b3c57 100644 --- a/docs/codex-mvp-tasks/development/00-backlog-overview.md +++ b/docs/codex-mvp-tasks/development/00-backlog-overview.md @@ -1,5 +1,7 @@ # A2A C++ SDK 1.0 — Backlog overview +> **Status:** Superseded historical overview. Several scope assumptions predate later gRPC, packaging, and readiness work; use it only for original backlog context. + ## Objective Build a production-usable **A2A 1.0** SDK in **C++20** with: diff --git a/docs/codex-mvp-tasks/development/01-repo-bootstrap-and-codegen.md b/docs/codex-mvp-tasks/development/01-repo-bootstrap-and-codegen.md index 42951e4..fa563ca 100644 --- a/docs/codex-mvp-tasks/development/01-repo-bootstrap-and-codegen.md +++ b/docs/codex-mvp-tasks/development/01-repo-bootstrap-and-codegen.md @@ -1,5 +1,7 @@ # Task 01 — Repository bootstrap, build system, and proto codegen +> **Status:** Historical / completed or superseded. Revalidate details against current source, tests, CI, and mdBook docs before using as implementation guidance. + ## Goal Create the initial repository skeleton for the A2A C++ SDK and establish a repeatable code-generation pipeline using the official A2A 1.0 protobuf definitions. diff --git a/docs/codex-mvp-tasks/development/02-core-versioning-errors-protojson.md b/docs/codex-mvp-tasks/development/02-core-versioning-errors-protojson.md index f0e31ad..c513bf4 100644 --- a/docs/codex-mvp-tasks/development/02-core-versioning-errors-protojson.md +++ b/docs/codex-mvp-tasks/development/02-core-versioning-errors-protojson.md @@ -1,5 +1,7 @@ # Task 02 — Core utilities: versioning, error model, and ProtoJSON helpers +> **Status:** Historical / completed or superseded. Revalidate details against current source, tests, CI, and mdBook docs before using as implementation guidance. + ## Goal Build the core shared layer used by both client and server: diff --git a/docs/codex-mvp-tasks/development/03-agent-card-discovery.md b/docs/codex-mvp-tasks/development/03-agent-card-discovery.md index 053cb15..2e95869 100644 --- a/docs/codex-mvp-tasks/development/03-agent-card-discovery.md +++ b/docs/codex-mvp-tasks/development/03-agent-card-discovery.md @@ -1,5 +1,7 @@ # Task 03 — Agent Card discovery and interface resolution +> **Status:** Historical / completed or superseded. Revalidate details against current source, tests, CI, and mdBook docs before using as implementation guidance. + ## Goal Implement A2A 1.0 discovery via `/.well-known/agent-card.json`, parse the returned Agent Card, validate required fields, and resolve the preferred interface for later client calls. diff --git a/docs/codex-mvp-tasks/development/04-http-json-client-core-rpcs.md b/docs/codex-mvp-tasks/development/04-http-json-client-core-rpcs.md index 5f582f7..8c7685f 100644 --- a/docs/codex-mvp-tasks/development/04-http-json-client-core-rpcs.md +++ b/docs/codex-mvp-tasks/development/04-http-json-client-core-rpcs.md @@ -1,5 +1,7 @@ # Task 04 — HTTP+JSON client for core A2A RPCs +> **Status:** Historical / completed or superseded. Revalidate details against current source, tests, CI, and mdBook docs before using as implementation guidance. + ## Goal Implement the first production-usable client transport: HTTP+JSON/REST for the core non-streaming A2A 1.0 operations. diff --git a/docs/codex-mvp-tasks/development/05-sse-streaming-client.md b/docs/codex-mvp-tasks/development/05-sse-streaming-client.md index 98c4040..7f03a76 100644 --- a/docs/codex-mvp-tasks/development/05-sse-streaming-client.md +++ b/docs/codex-mvp-tasks/development/05-sse-streaming-client.md @@ -1,5 +1,7 @@ # Task 05 — SSE streaming client for SendStreamingMessage and task subscription +> **Status:** Historical / completed or superseded. Revalidate details against current source, tests, CI, and mdBook docs before using as implementation guidance. + ## Goal Add streaming support over SSE for A2A 1.0 so the SDK can consume incremental responses from agents. diff --git a/docs/codex-mvp-tasks/development/06-json-rpc-client.md b/docs/codex-mvp-tasks/development/06-json-rpc-client.md index f8a3fbf..3653ec5 100644 --- a/docs/codex-mvp-tasks/development/06-json-rpc-client.md +++ b/docs/codex-mvp-tasks/development/06-json-rpc-client.md @@ -1,5 +1,7 @@ # Task 06 — JSON-RPC client transport +> **Status:** Historical / completed or superseded. Revalidate details against current source, tests, CI, and mdBook docs before using as implementation guidance. + ## Goal Implement JSON-RPC support for the same high-level A2A client API already exposed by the REST transport. diff --git a/docs/codex-mvp-tasks/development/07-server-core-executor-dispatcher-task-store.md b/docs/codex-mvp-tasks/development/07-server-core-executor-dispatcher-task-store.md index 0ed82d3..0bd9178 100644 --- a/docs/codex-mvp-tasks/development/07-server-core-executor-dispatcher-task-store.md +++ b/docs/codex-mvp-tasks/development/07-server-core-executor-dispatcher-task-store.md @@ -1,5 +1,7 @@ # Task 07 — Server core: executor interface, dispatcher, and task store +> **Status:** Historical / completed or superseded. Revalidate details against current source, tests, CI, and mdBook docs before using as implementation guidance. + ## Goal Create the transport-agnostic server core so users can implement an A2A agent once and expose it via multiple transports later. diff --git a/docs/codex-mvp-tasks/development/08-rest-server-transport.md b/docs/codex-mvp-tasks/development/08-rest-server-transport.md index de9434a..71b1fbe 100644 --- a/docs/codex-mvp-tasks/development/08-rest-server-transport.md +++ b/docs/codex-mvp-tasks/development/08-rest-server-transport.md @@ -1,5 +1,7 @@ # Task 08 — REST server transport and Agent Card publishing +> **Status:** Historical / completed or superseded. Revalidate details against current source, tests, CI, and mdBook docs before using as implementation guidance. + ## Goal Expose the server core over HTTP+JSON/REST, including discovery via the A2A 1.0 Agent Card. diff --git a/docs/codex-mvp-tasks/development/09-json-rpc-server-transport.md b/docs/codex-mvp-tasks/development/09-json-rpc-server-transport.md index a8cb21b..9acfe14 100644 --- a/docs/codex-mvp-tasks/development/09-json-rpc-server-transport.md +++ b/docs/codex-mvp-tasks/development/09-json-rpc-server-transport.md @@ -1,5 +1,7 @@ # Task 09 — JSON-RPC server transport +> **Status:** Historical / completed or superseded. Revalidate details against current source, tests, CI, and mdBook docs before using as implementation guidance. + ## Goal Expose the same server core over JSON-RPC so a single executor implementation can serve both REST and JSON-RPC clients. diff --git a/docs/codex-mvp-tasks/development/10-auth-security-hooks.md b/docs/codex-mvp-tasks/development/10-auth-security-hooks.md index b32a63f..6f3daf2 100644 --- a/docs/codex-mvp-tasks/development/10-auth-security-hooks.md +++ b/docs/codex-mvp-tasks/development/10-auth-security-hooks.md @@ -1,5 +1,7 @@ # Task 10 — Auth and security hooks +> **Status:** Historical / completed or superseded. Revalidate details against current source, tests, CI, and mdBook docs before using as implementation guidance. + ## Goal Add the auth abstraction layer and metadata handling needed for real-world SDK use without overbuilding every provider-specific flow. diff --git a/docs/codex-mvp-tasks/development/11-examples-interop-and-ci.md b/docs/codex-mvp-tasks/development/11-examples-interop-and-ci.md index fc71f92..a3dc3d7 100644 --- a/docs/codex-mvp-tasks/development/11-examples-interop-and-ci.md +++ b/docs/codex-mvp-tasks/development/11-examples-interop-and-ci.md @@ -1,5 +1,7 @@ # Task 11 — Examples, interoperability tests, packaging, and CI +> **Status:** Historical / completed or superseded. Revalidate details against current source, tests, CI, and mdBook docs before using as implementation guidance. + ## Goal Finish the first usable release by adding examples, end-to-end tests, packaging polish, and CI automation. diff --git a/docs/codex-mvp-tasks/development/12-parity-gap-analysis-vs-a2a-go.md b/docs/codex-mvp-tasks/development/12-parity-gap-analysis-vs-a2a-go.md index 12ff4c3..fd6436d 100644 --- a/docs/codex-mvp-tasks/development/12-parity-gap-analysis-vs-a2a-go.md +++ b/docs/codex-mvp-tasks/development/12-parity-gap-analysis-vs-a2a-go.md @@ -1,5 +1,7 @@ # Task 12 — A2A Go/Python parity gap analysis and roadmap alignment +> **Status:** Historical / completed or superseded. Revalidate details against current source, tests, CI, and mdBook docs before using as implementation guidance. + ## Goal Document feature gaps between the current C++ SDK MVP and the public `a2aproject/a2a-go` and `a2aproject/a2a-python` SDK surfaces, then convert those gaps into concrete, ordered implementation tasks. diff --git a/docs/codex-mvp-tasks/development/13-grpc-transport-parity.md b/docs/codex-mvp-tasks/development/13-grpc-transport-parity.md index b222ffb..53af3bb 100644 --- a/docs/codex-mvp-tasks/development/13-grpc-transport-parity.md +++ b/docs/codex-mvp-tasks/development/13-grpc-transport-parity.md @@ -1,5 +1,7 @@ # Task 13 — gRPC transport parity (client + server) +> **Status:** Historical / completed or superseded. Revalidate details against current source, tests, CI, and mdBook docs before using as implementation guidance. + ## Goal Add first-class gRPC transport support so the C++ SDK reaches transport-level parity with a2a-go's gRPC path. diff --git a/docs/codex-mvp-tasks/development/14-client-server-api-parity-extended-rpcs-and-interceptors.md b/docs/codex-mvp-tasks/development/14-client-server-api-parity-extended-rpcs-and-interceptors.md index 265a67d..1106231 100644 --- a/docs/codex-mvp-tasks/development/14-client-server-api-parity-extended-rpcs-and-interceptors.md +++ b/docs/codex-mvp-tasks/development/14-client-server-api-parity-extended-rpcs-and-interceptors.md @@ -1,5 +1,7 @@ # Task 14 — Extended RPC and interceptor parity with a2a-go +> **Status:** Historical / completed or superseded. Revalidate details against current source, tests, CI, and mdBook docs before using as implementation guidance. + ## Goal Close major API-surface gaps with a2a-go by adding missing protocol methods and interceptor/lifecycle extension points. diff --git a/docs/codex-mvp-tasks/development/15-test-coverage-and-quality-gates.md b/docs/codex-mvp-tasks/development/15-test-coverage-and-quality-gates.md index bb0f904..752be30 100644 --- a/docs/codex-mvp-tasks/development/15-test-coverage-and-quality-gates.md +++ b/docs/codex-mvp-tasks/development/15-test-coverage-and-quality-gates.md @@ -1,5 +1,7 @@ # Task 15 — Test coverage baselines and quality gate hardening +> **Status:** Historical / completed or superseded. Revalidate details against current source, tests, CI, and mdBook docs before using as implementation guidance. + ## Goal Establish measurable coverage baselines and enforce them in CI so regressions are blocked before release. diff --git a/docs/codex-mvp-tasks/development/16-examples-expansion-and-local-runner-guide.md b/docs/codex-mvp-tasks/development/16-examples-expansion-and-local-runner-guide.md index 4dc926b..0901869 100644 --- a/docs/codex-mvp-tasks/development/16-examples-expansion-and-local-runner-guide.md +++ b/docs/codex-mvp-tasks/development/16-examples-expansion-and-local-runner-guide.md @@ -1,5 +1,7 @@ # Task 16 — Examples expansion and local runnable scenarios +> **Status:** Historical / completed or superseded. Revalidate details against current source, tests, CI, and mdBook docs before using as implementation guidance. + ## Goal Expand SDK examples from minimal snippets into a practical runnable matrix that users can execute locally to validate end-to-end behavior. diff --git a/docs/codex-mvp-tasks/development/17-google-sdk-readiness-checklist.md b/docs/codex-mvp-tasks/development/17-google-sdk-readiness-checklist.md index e3e5ef4..a7acc4f 100644 --- a/docs/codex-mvp-tasks/development/17-google-sdk-readiness-checklist.md +++ b/docs/codex-mvp-tasks/development/17-google-sdk-readiness-checklist.md @@ -1,5 +1,7 @@ # Task 17 — Google ecosystem SDK-readiness checklist closure +> **Status:** Active follow-up. Use as readiness or operational planning context, but verify each evidence link against current repository state before claiming completion. + ## Goal Close remaining gaps against community expectations for production-quality SDKs before requesting inclusion/endorsement. diff --git a/docs/codex-mvp-tasks/development/18-spec-conformance-and-sdk-application-readiness.md b/docs/codex-mvp-tasks/development/18-spec-conformance-and-sdk-application-readiness.md index 8379a05..e0d61dc 100644 --- a/docs/codex-mvp-tasks/development/18-spec-conformance-and-sdk-application-readiness.md +++ b/docs/codex-mvp-tasks/development/18-spec-conformance-and-sdk-application-readiness.md @@ -1,5 +1,7 @@ # Task 18 — Spec conformance evidence and SDK application-readiness closure +> **Status:** Active follow-up. Use as readiness or operational planning context, but verify each evidence link against current repository state before claiming completion. + ## Goal Produce objective, auditable evidence that the C++ SDK satisfies community SDK requirements before submitting for official listing/review. diff --git a/docs/codex-mvp-tasks/development/19-windows-build-dependency-acceleration.md b/docs/codex-mvp-tasks/development/19-windows-build-dependency-acceleration.md index d97a73b..249a18c 100644 --- a/docs/codex-mvp-tasks/development/19-windows-build-dependency-acceleration.md +++ b/docs/codex-mvp-tasks/development/19-windows-build-dependency-acceleration.md @@ -1,5 +1,7 @@ # Task 19 — Windows dependency-install acceleration and CI latency reduction +> **Status:** Active follow-up. Use as readiness or operational planning context, but verify each evidence link against current repository state before claiming completion. + ## Goal Reduce Windows CI build startup time (currently dominated by manifest dependency installation) to improve developer feedback loops and release velocity. diff --git a/docs/codex-mvp-tasks/development/20-cross-sdk-parity-vs-a2a-python.md b/docs/codex-mvp-tasks/development/20-cross-sdk-parity-vs-a2a-python.md index 27bac5e..a00dba3 100644 --- a/docs/codex-mvp-tasks/development/20-cross-sdk-parity-vs-a2a-python.md +++ b/docs/codex-mvp-tasks/development/20-cross-sdk-parity-vs-a2a-python.md @@ -1,5 +1,7 @@ # Task 20 — Cross-SDK parity expansion vs a2a-python +> **Status:** Planned / decision needed. Treat as parity follow-up requiring fresh validation before implementation. + ## Goal Close remaining capability and ecosystem parity gaps between `a2a-cpp` and the public `a2aproject/a2a-python` SDK, while preserving C++-idiomatic APIs. diff --git a/docs/codex-mvp-tasks/development/21-python-cross-sdk-interop-ci.md b/docs/codex-mvp-tasks/development/21-python-cross-sdk-interop-ci.md index 94b7875..1f86cde 100644 --- a/docs/codex-mvp-tasks/development/21-python-cross-sdk-interop-ci.md +++ b/docs/codex-mvp-tasks/development/21-python-cross-sdk-interop-ci.md @@ -1,5 +1,7 @@ # Task 21 — Deterministic C++ ↔ Python interop CI scenario +> **Status:** Planned / decision needed. Treat as parity follow-up requiring fresh validation before implementation. + ## Goal Add an automated, deterministic CI scenario that validates A2A protocol interoperability between `a2a-cpp` and public `a2aproject/a2a-python` sample agent flows. diff --git a/docs/codex-mvp-tasks/development/22-python-cli-workflow-parity.md b/docs/codex-mvp-tasks/development/22-python-cli-workflow-parity.md index a19586a..4a66b9c 100644 --- a/docs/codex-mvp-tasks/development/22-python-cli-workflow-parity.md +++ b/docs/codex-mvp-tasks/development/22-python-cli-workflow-parity.md @@ -1,5 +1,7 @@ # Task 22 — Python CLI workflow parity decisions for C++ +> **Status:** Planned / decision needed. Treat as parity follow-up requiring fresh validation before implementation. + ## Goal Close the documented CLI-workflow parity gap versus `a2a-python` by deciding and implementing the C++ equivalent strategy (native CLI, helper scripts, or explicit non-goal with rationale). diff --git a/docs/codex-mvp-tasks/documentation/README.md b/docs/codex-mvp-tasks/documentation/README.md index c4d20e6..f1e1c47 100644 --- a/docs/codex-mvp-tasks/documentation/README.md +++ b/docs/codex-mvp-tasks/documentation/README.md @@ -2,6 +2,10 @@ This folder contains the documentation implementation plan for setting up and hardening docs with **mdBook + GitHub Pages**. +## Current use + +This documentation track is retained as implementation history and follow-up planning for the mdBook site. Current reader-facing documentation lives under `book/src/**`; use these task files only to understand why the docs site was created and what follow-up hardening remains. + ## Task order 1. [Task 1: Bootstrap mdBook Structure](task-1-bootstrap-mdbook.md) diff --git a/docs/codex-mvp-tasks/documentation/task-1-bootstrap-mdbook.md b/docs/codex-mvp-tasks/documentation/task-1-bootstrap-mdbook.md index 7dd2636..5446df9 100644 --- a/docs/codex-mvp-tasks/documentation/task-1-bootstrap-mdbook.md +++ b/docs/codex-mvp-tasks/documentation/task-1-bootstrap-mdbook.md @@ -1,5 +1,7 @@ # Task 1 — Bootstrap mdBook Structure +> **Status:** Historical / completed. The mdBook skeleton exists; keep this file as setup history. + ## Goal Create the mdBook skeleton and navigation so the docs site builds with placeholder content. diff --git a/docs/codex-mvp-tasks/documentation/task-2-migrate-expand-docs.md b/docs/codex-mvp-tasks/documentation/task-2-migrate-expand-docs.md index 7558a02..573b686 100644 --- a/docs/codex-mvp-tasks/documentation/task-2-migrate-expand-docs.md +++ b/docs/codex-mvp-tasks/documentation/task-2-migrate-expand-docs.md @@ -1,5 +1,7 @@ # Task 2 — Migrate and Expand Existing Docs +> **Status:** Historical / partially completed. Current mdBook pages have been expanded, but future doc work should use current `book/src/**` content as source of truth. + ## Goal Move and expand current documentation from `docs/` into `book/src/`, preserving useful content and improving depth. diff --git a/docs/codex-mvp-tasks/documentation/task-3-github-pages-workflow.md b/docs/codex-mvp-tasks/documentation/task-3-github-pages-workflow.md index 6528dcd..9503c08 100644 --- a/docs/codex-mvp-tasks/documentation/task-3-github-pages-workflow.md +++ b/docs/codex-mvp-tasks/documentation/task-3-github-pages-workflow.md @@ -1,5 +1,7 @@ # Task 3 — Add GitHub Pages Workflow +> **Status:** Active follow-up. Verify the current workflow state before using this task as implementation guidance. + ## Goal Automate docs build and deployment to GitHub Pages using GitHub Actions. diff --git a/docs/codex-mvp-tasks/documentation/task-4-seo-release-hardening.md b/docs/codex-mvp-tasks/documentation/task-4-seo-release-hardening.md index cff92fa..d5ea816 100644 --- a/docs/codex-mvp-tasks/documentation/task-4-seo-release-hardening.md +++ b/docs/codex-mvp-tasks/documentation/task-4-seo-release-hardening.md @@ -1,5 +1,7 @@ # Task 4 — SEO and Release Hardening +> **Status:** Active follow-up. Keep release and SEO guidance aligned with current mdBook and release process. + ## Goal Improve discoverability, navigation quality, and release-readiness for the first public docs release. diff --git a/docs/codex-mvp-tasks/documentation/task-5-generated-api-reference-publication.md b/docs/codex-mvp-tasks/documentation/task-5-generated-api-reference-publication.md index 1d0f5a6..153ff51 100644 --- a/docs/codex-mvp-tasks/documentation/task-5-generated-api-reference-publication.md +++ b/docs/codex-mvp-tasks/documentation/task-5-generated-api-reference-publication.md @@ -1,5 +1,7 @@ # Task 5 — Publish Generated C++ API Reference +> **Status:** Active follow-up. Verify generated API publication against current scripts and workflows before claiming completion. + ## Goal Replace the current API Reference placeholder page with a production-quality autogenerated C++ API reference pipeline and published output.