ci(cpp): cross-compile matrix + static binary packaging for C++ agents (#1094) (#1406)

## Why this matters

Before: the C++ agents in `cpp/` (health, wifi, process, vlm,
security-demo) had no distribution path — `build_cpp.yml` only compiled
and tested the library, so there was no self-contained binary anyone
could download and run, and no `dist/` artifact for the Agent Hub to
publish. After: every agent is built as a **static, cross-platform
binary** (no runtime DLL/`.so` dependency) and packaged with its
`gaia-agent.yaml` + checksum, on Windows, Linux, and macOS. This is the
packaging half of Agent Hub Phase 2B (issue #1094).

`build_agents.yml` adds the cross-compile matrix — win-x64 (MSVC),
linux-x64 (GCC), darwin-arm64 (Clang) — building with
`BUILD_SHARED_LIBS=OFF`, vcpkg `*-static` triplets, and the static MSVC
runtime. `cpp/packaging/package_agents.py` then emits `dist/<id>/` with
the renamed binary, the agent's manifest, and `checksums.sha256`. On a
`v*` tag a release job consolidates all platforms into one bundle;
actual R2/PyPI publishing is handled by other Agent Hub issues.

Windows-only agents (health/wifi/process) build on the win-x64 leg only;
security-demo and vlm are portable and prove the Linux/macOS legs.
Manifests validate against the `gaia-agent.yaml` parser from #1091.

**Isolated from the #1102 Python restructure** — touches only
`.github/workflows/`, `cpp/`, and a packaging script. No `src/gaia/`
changes.

Spec: `docs/spec/agent-hub-restructure.mdx` (Step 9 — CI/CD;
`cpp.binaries`/`static_linked`).

## Test plan

- [x] `python -c "import yaml;
yaml.safe_load(open('.github/workflows/build_agents.yml'))"` — workflow
is valid YAML
- [x] All five `cpp/agents/*/gaia-agent.yaml` parse via
`gaia.hub.manifest.parse` (cpp, static_linked, correct platforms)
- [x] `package_agents.py` smoke-tested with synthetic build trees for
win-x64 (5 agents) and linux-x64 (2 agents): correct `dist/<id>/`
layout, stale Debug copies skipped, checksums written, fails loudly on
missing binary
- [x] release-bundle merge logic tested locally — preserves all
platforms' binaries per agent and regenerates complete checksums (no
per-leg collision)
- [x] `python util/lint.py --black --isort` passes
- [ ] CI matrix green on all three legs (relies on the runners — no
local C++ toolchain available to smoke-build)

---------

Co-authored-by: Ovtcharov <kovtchar@amd.com>

Author: kovtcharov-amd

.github/workflows/build_agents.yml

@@ -0,0 +1,233 @@
+# Copyright(C) 2025-2026 Advanced Micro Devices, Inc. All rights reserved.
+# SPDX-License-Identifier: MIT
+
+# Cross-compile matrix + static-binary packaging for the native (C++) Agent Hub
+# agents in cpp/. Each matrix leg builds the C++ example agents with static
+# linking (BUILD_SHARED_LIBS=OFF + vcpkg *-static triplet + static MSVC runtime)
+# so the artifacts have no runtime DLL/.so dependency, then packages each agent
+# into dist/<id>/ (binary + gaia-agent.yaml + checksums.sha256) and uploads it.
+#
+# On a version tag (v*), a release job consolidates every platform's artifacts
+# into a single bundle for downstream publishing (R2 / PyPI are handled by other
+# Agent Hub issues — this workflow only produces and uploads the artifacts).
+#
+# Static triplets: Windows uses the built-in x64-windows-static; Linux/macOS use
+# the overlay triplets in cpp/triplets/ (no built-in *-static there).
+# Manifests + the packaging script: cpp/agents/, cpp/packaging/package_agents.py
+# Issue: https://github.com/amd/gaia/issues/1094
+
+name: Agent Binaries (C++)
+
+on:
+  push:
+    branches: [ main ]
+    tags: [ 'v*' ]
+    paths:
+      - 'cpp/**'
+      - '.github/workflows/build_agents.yml'
+  pull_request:
+    branches: [ main ]
+    types: [opened, synchronize, reopened, ready_for_review]
+    paths:
+      - 'cpp/**'
+      - '.github/workflows/build_agents.yml'
+  merge_group:
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Package (${{ matrix.platform }})
+    runs-on: ${{ matrix.os }}
+    if: github.event_name != 'pull_request' || github.event.pull_request.draft == false || contains(github.event.pull_request.labels.*.name, 'ready_for_ci')
+
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: windows-latest
+            platform: win-x64
+            triplet: x64-windows-static
+          - os: ubuntu-latest
+            platform: linux-x64
+            triplet: x64-linux-static
+          - os: macos-latest
+            platform: darwin-arm64
+            triplet: arm64-osx-static
+
+    env:
+      # vcpkg binary cache so static OpenSSL is built once and reused across runs.
+      VCPKG_DEFAULT_BINARY_CACHE: ${{ github.workspace }}/.vcpkg-cache
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: '3.12'
+
+      - name: Install packaging deps
+        run: python -m pip install --upgrade pyyaml
+
+      - name: Prepare vcpkg binary cache dir
+        shell: bash
+        run: mkdir -p "${VCPKG_DEFAULT_BINARY_CACHE}"
+
+      - name: Restore vcpkg binary cache
+        uses: actions/cache@v5
+        with:
+          path: ${{ github.workspace }}/.vcpkg-cache
+          key: vcpkg-${{ matrix.triplet }}-${{ hashFiles('cpp/vcpkg.json') }}
+          restore-keys: |
+            vcpkg-${{ matrix.triplet }}-
+
+      - name: Restore FetchContent cache
+        uses: actions/cache@v5
+        with:
+          path: cpp/build/_deps
+          key: fetchcontent-agents-${{ matrix.platform }}-${{ hashFiles('cpp/CMakeLists.txt') }}
+
+      - name: Install static OpenSSL via vcpkg (${{ matrix.triplet }})
+        shell: bash
+        run: |
+          set -euo pipefail
+          if [ -z "${VCPKG_INSTALLATION_ROOT:-}" ]; then
+            echo "::error::VCPKG_INSTALLATION_ROOT is not set on this runner"
+            exit 1
+          fi
+          # Linux/macOS have no built-in *-static triplet; cpp/triplets supplies
+          # them as overlays (Windows still uses its built-in x64-windows-static).
+          "${VCPKG_INSTALLATION_ROOT}/vcpkg" install "openssl:${{ matrix.triplet }}" \
+            --overlay-triplets="${GITHUB_WORKSPACE}/cpp/triplets"
+
+      - name: Configure CMake (static)
+        shell: bash
+        run: |
+          set -euo pipefail
+          cmake -B cpp/build -S cpp \
+            -DCMAKE_BUILD_TYPE=Release \
+            -DBUILD_SHARED_LIBS=OFF \
+            -DGAIA_BUILD_TESTS=OFF \
+            -DGAIA_BUILD_EXAMPLES=ON \
+            -DGAIA_BUILD_INTEGRATION_TESTS=OFF \
+            -DGAIA_BUILD_BENCHMARKS=OFF \
+            -DVCPKG_MANIFEST_MODE=OFF \
+            -DVCPKG_TARGET_TRIPLET=${{ matrix.triplet }} \
+            -DVCPKG_OVERLAY_TRIPLETS="${GITHUB_WORKSPACE}/cpp/triplets" \
+            -DCMAKE_TOOLCHAIN_FILE="${VCPKG_INSTALLATION_ROOT}/scripts/buildsystems/vcpkg.cmake"
+
+      - name: Build (Release)
+        run: cmake --build cpp/build --config Release --parallel
+
+      - name: Package agents for ${{ matrix.platform }}
+        run: >-
+          python cpp/packaging/package_agents.py
+          --platform ${{ matrix.platform }}
+          --build-dir cpp/build
+          --agents-dir cpp/agents
+          --out dist
+
+      - name: Show packaged artifacts
+        shell: bash
+        run: |
+          echo "=== dist/ (${{ matrix.platform }}) ==="
+          find dist -type f | sort
+          echo
+          echo "=== checksums ==="
+          find dist -name checksums.sha256 -exec cat {} +
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v7
+        with:
+          name: cpp-agents-${{ matrix.platform }}
+          path: dist/
+          if-no-files-found: error
+
+  # On a version tag, consolidate every platform's dist/ into one bundle so a
+  # downstream job (R2 / PyPI — other issues) has a single artifact to publish.
+  release-bundle:
+    name: Consolidate release bundle
+    runs-on: ubuntu-latest
+    needs: [build]
+    if: startsWith(github.ref, 'refs/tags/v')
+    permissions:
+      contents: read
+    steps:
+      - name: Download all platform artifacts
+        uses: actions/download-artifact@v8
+        with:
+          pattern: cpp-agents-*
+          path: artifacts
+
+      - name: Merge into release bundle
+        shell: bash
+        run: |
+          set -euo pipefail
+          mkdir -p bundle
+          # Each artifact is artifacts/cpp-agents-<platform>/<id>/...; merge by id
+          # so a single bundle/<id>/ holds every platform's binary + the manifest.
+          # The per-leg checksums.sha256 files collide (same path per id), so drop
+          # them here and regenerate complete per-agent + aggregate checksums from
+          # the merged binaries below.
+          for leg in artifacts/cpp-agents-*; do
+            [ -d "$leg" ] || continue
+            cp -r "$leg"/* bundle/
+          done
+          find bundle -name checksums.sha256 -delete
+
+          : > bundle/CHECKSUMS.sha256
+          for agent_dir in bundle/*/; do
+            [ -d "$agent_dir" ] || continue
+            ( cd "$agent_dir"
+              # Hash every shipped binary (everything except yaml/checksum files).
+              : > checksums.sha256
+              for f in *; do
+                case "$f" in
+                  *.yaml|*.sha256) continue ;;
+                esac
+                [ -f "$f" ] || continue
+                sha256sum "$f" >> checksums.sha256
+              done
+            )
+            agent_id="$(basename "$agent_dir")"
+            sed "s|\$| (${agent_id})|" "${agent_dir}checksums.sha256" >> bundle/CHECKSUMS.sha256
+          done
+
+          echo "=== release bundle ==="
+          find bundle -type f | sort
+          echo "=== aggregated checksums ==="
+          cat bundle/CHECKSUMS.sha256
+
+      - name: Upload release bundle
+        uses: actions/upload-artifact@v7
+        with:
+          name: gaia-cpp-agents-${{ github.ref_name }}
+          path: bundle/
+          if-no-files-found: error
+
+  agents-build-summary:
+    name: Agent Binaries Summary
+    runs-on: ubuntu-latest
+    needs: [build]
+    if: always() && !cancelled()
+    steps:
+      - name: Check results
+        run: |
+          echo "=== Agent Binaries (C++) Summary ==="
+          echo "Build/package matrix: ${{ needs.build.result }}"
+          if [[ "${{ needs.build.result }}" == "skipped" ]]; then
+            echo "Matrix skipped (draft PR — add 'ready_for_ci' label to run)"
+            exit 0
+          fi
+          if [[ "${{ needs.build.result }}" != "success" ]]; then
+            echo "One or more matrix legs failed"
+            exit 1
+          fi
+          echo "All platform legs packaged successfully"

cpp/CMakeLists.txt

@@ -3,6 +3,12 @@
 
 cmake_minimum_required(VERSION 3.14)
 
+# Select the MSVC runtime library via CMAKE_MSVC_RUNTIME_LIBRARY (the static-CRT
+# logic below). Must be set before project() to govern the runtime abstraction.
+if(POLICY CMP0091)
+    cmake_policy(SET CMP0091 NEW)
+endif()
+
 # Auto-detect or bootstrap vcpkg for optional OpenSSL support.
 # Must be included before project() so the toolchain is set in time.
 include(${CMAKE_CURRENT_LIST_DIR}/cmake/vcpkg-auto-setup.cmake)
@@ -18,6 +24,18 @@ if(MSVC)
     add_compile_options(/EHsc)
 endif()
 
+# ---------------------------------------------------------------------------
+# Static-binary packaging (Agent Hub, issue #1094)
+# ---------------------------------------------------------------------------
+# When building against a vcpkg *-static triplet (e.g. x64-windows-static), the
+# produced binaries must link the C runtime statically too — otherwise the .exe
+# still depends on the MSVC runtime DLLs and is not self-contained. Detect the
+# static triplet and switch the MSVC runtime to the static (/MT) variant.
+if(MSVC AND DEFINED VCPKG_TARGET_TRIPLET AND VCPKG_TARGET_TRIPLET MATCHES "-static$")
+    set(CMAKE_MSVC_RUNTIME_LIBRARY "MultiThreaded$<$<CONFIG:Debug>:Debug>")
+    message(STATUS "GAIA packaging: static MSVC runtime (/MT) for ${VCPKG_TARGET_TRIPLET}")
+endif()
+
 # ---------------------------------------------------------------------------
 # Options -- default ON when this is the top-level project, OFF as a sub-
 # project so consumers only get the library.

cpp/agents/README.md

@@ -0,0 +1,47 @@
+<!--
+Copyright(C) 2025-2026 Advanced Micro Devices, Inc. All rights reserved.
+SPDX-License-Identifier: MIT
+-->
+
+# C++ agent packaging manifests
+
+Each subdirectory here holds a `gaia-agent.yaml` packaging manifest for a native
+(C++) agent. The manifests are the contract between the C++ sources in
+[`../examples/`](../examples) and the Agent Hub: they declare identity, target
+platforms, and the packaged binary filename per platform.
+
+| id | source | platforms |
+|----|--------|-----------|
+| `health` | `examples/health_agent.cpp` | win-x64 |
+| `wifi` | `examples/wifi_agent.cpp` | win-x64 |
+| `process` | `examples/process_agent.cpp` | win-x64 |
+| `security-demo` | `examples/security_demo.cpp` | win-x64, linux-x64, darwin-arm64 |
+| `vlm` | `examples/vlm_agent.cpp` | win-x64, linux-x64, darwin-arm64 |
+
+`health`, `wifi`, and `process` use Windows-only APIs (`windows.h`, `psapi`,
+`netsh`/PowerShell), so they are built only on the `win-x64` matrix leg.
+`security-demo` and `vlm` are portable and prove the Linux and macOS legs.
+
+## How packaging works
+
+[`.github/workflows/build_agents.yml`](../../.github/workflows/build_agents.yml)
+builds the binaries with **static linking** (`BUILD_SHARED_LIBS=OFF`, vcpkg
+`*-static` triplets, static MSVC runtime) so the artifacts have no runtime
+DLL/`.so` dependency. Then [`packaging/package_agents.py`](../packaging/package_agents.py)
+produces, per agent:
+
+```
+dist/<id>/
+  <id>-<platform>[.exe]   # the binary, renamed to match cpp.binaries
+  gaia-agent.yaml          # this manifest
+  checksums.sha256         # SHA-256 of the binary
+```
+
+The packaged binary filename must match the `cpp.binaries.<platform>` value in
+the manifest — the packaging script fails loudly otherwise.
+
+## Mapping a manifest to its CMake target
+
+The manifest `id` maps to a CMake executable target via the `TARGET_BY_ID`
+table in [`packaging/package_agents.py`](../packaging/package_agents.py). When
+you add a new C++ agent, add an entry there and a matching manifest directory.

cpp/agents/health/gaia-agent.yaml

@@ -0,0 +1,40 @@
+# Copyright(C) 2025-2026 Advanced Micro Devices, Inc. All rights reserved.
+# SPDX-License-Identifier: MIT
+#
+# Packaging manifest for the native (C++) health agent. The binary is built
+# from cpp/examples/health_agent.cpp by .github/workflows/build_agents.yml and
+# packaged into dist/health/ by cpp/packaging/package_agents.py.
+id: health
+name: System Health
+version: 0.1.0
+description: "Diagnose a slow or unhealthy Windows system via the Windows MCP server."
+author: AMD
+license: MIT
+
+category: system
+tags: [health, system, diagnostics, mcp, windows]
+icon: heart-pulse
+
+language: cpp
+min_gaia_version: "0.18.0"
+models: [Qwen3-4B-Instruct-2507-GGUF]
+
+requirements:
+  min_memory_gb: 8
+  platforms: [win-x64]
+
+cpp:
+  static_linked: true
+  binaries:
+    win-x64: health-win-x64.exe
+
+permissions:
+  - process:read
+  - system:read
+
+interfaces:
+  tui: true
+  cli: false
+  pipe: false
+  api_server: false
+  mcp_server: false

cpp/agents/process/gaia-agent.yaml

@@ -0,0 +1,40 @@
+# Copyright(C) 2025-2026 Advanced Micro Devices, Inc. All rights reserved.
+# SPDX-License-Identifier: MIT
+#
+# Packaging manifest for the native (C++) process analyst agent. Built from
+# cpp/examples/process_agent.cpp by .github/workflows/build_agents.yml.
+id: process
+name: Process Analyst
+version: 0.1.0
+description: "PC narrator and process intelligence: detect anomalies, then act on labeled findings."
+author: AMD
+license: MIT
+
+category: system
+tags: [process, system, monitoring, windows]
+icon: activity
+
+language: cpp
+min_gaia_version: "0.18.0"
+models: [Qwen3-4B-Instruct-2507-GGUF]
+
+requirements:
+  min_memory_gb: 8
+  platforms: [win-x64]
+
+cpp:
+  static_linked: true
+  binaries:
+    win-x64: process-win-x64.exe
+
+permissions:
+  - process:read
+  - process:write
+  - system:read
+
+interfaces:
+  tui: true
+  cli: true
+  pipe: false
+  api_server: false
+  mcp_server: false