C++ framework: docs, CI integration tests, health agent improvements

[kovtcharov]

Summary

Documentation

• Rename simple_agent to health_agent across all C++ guide pages
• Fix architecture diagram: replace clipboard/paste approach with file-write + Notepad open, add GPU check
• Fix Get-WmiObject to Get-CimInstance (correct PowerShell API)
• Add CleanConsole and test_tool_integration to project structure listing
• Update test suite description: six modules to eight
• Fix doc code snippets to match actual source (PipeCloser, isSafeShellArg, kDiagnosticMenu)
• Add shell injection prevention section to wifi-agent guide
• Clarify Lemonade Server as recommended/tested LLM backend
• Split multi-command code blocks for easy copy-paste
• Clean up C++ intro page (remove redundant LLM Backend and Integration sections)

CI/CD (build_cpp.yml)

• Add integration test suite on STX hardware: LLM + MCP + WiFi + Health tests
• Use Qwen3-4B-Instruct-2507-GGUF model (matches wifi and health agents)
• Add uvx verification step before test execution
• Fix MinGW portability: _dupenv_s guards, _WIN32 vs _MSC_VER, _putenv_s

Health Agent (health_agent.cpp)

• Simplify menu: option 1 is quick console-only summary (4 metrics, no Notepad), option 15 is full diagnostics + Notepad report
• Replace clipboard/paste with direct file-write + Start-Process notepad approach
• Use array-of-lines pattern with [Environment]::NewLine for proper newlines
• Increase context size to 32K for comprehensive diagnostics (12+ tool calls)
• Remove HTML report generation (unreliable with small LLMs)

Agent Core (agent.cpp)

• Fix loop detection false positive: compare both tool name AND arguments (was name-only, triggering on consecutive mcp_windows_Shell calls with different args)
• Reduce tool result truncation from 20K to 4K chars to prevent context overflow

New Files

• cpp/include/gaia/clean_console.h + cpp/src/clean_console.cpp — polished TUI with ANSI colors and word-wrap
• cpp/examples/health_agent.cpp — Windows system health agent using MCP
• cpp/tests/test_clean_console.cpp — CleanConsole unit tests
• cpp/tests/test_tool_integration.cpp — Tool registry integration tests
• cpp/tests/integration/test_integration_mcp.cpp — MCP connectivity tests
• cpp/tests/integration/test_integration_wifi.cpp — WiFi diagnostic tests
• cpp/tests/integration/test_integration_health.cpp — Health monitoring tests

Test plan

• All 6 cloud CI jobs pass (ubuntu + windows: mock tests, install test, shared lib)
• STX integration tests build and run (LLM + MCP + WiFi + Health)
• health_agent.exe option 1: quick console summary (no Notepad)
• health_agent.exe option 15: full diagnostics + Notepad report
• wifi_agent.exe full network diagnostic works
• Mock tests pass locally: gaia_tests.exe --gtest_color=yes
• Documentation renders correctly on Mintlify

[kovtcharov-amd]

@claude review this PR.

[github-actions]

Claude finished @kovtcharov-amd's task —— View job

---

PR Review: C++ Framework Updates

Overall Assessment: 🟢 Approved — This is a well-structured PR with comprehensive improvements to the C++ framework.

---

Summary

This PR delivers significant enhancements across three areas:

1. Documentation improvements — Renamed simple_agent to health_agent, fixed code snippets to match source, added shell injection prevention section
2. CI/CD enhancements — Added STX integration tests (LLM + MCP + WiFi + Health) with proper model selection
3. Health Agent rewrite — Simplified menu, direct file-write approach, improved reliability with small LLMs

---

Code Review Findings

🟢 Well-Done Sections

1. Loop Detection Fix (cpp/src/agent.cpp:507-521)
The loop detection now correctly compares both tool name AND arguments:

if (toolCallHistory[i].first != toolName ||
    toolCallHistory[i].second != toolArgs) {
    allSame = false;
    break;
}

This prevents false positives when consecutive mcp_windows_Shell calls have different arguments — a common pattern for health diagnostics.

2. Tool Result Truncation (cpp/src/agent.cpp:541-543)
Reduced from 20K to 4K characters to prevent context overflow. Good balance between preserving useful output and managing context limits for models like Qwen3-4B.

3. Shell Injection Prevention (cpp/examples/wifi_agent.cpp:87-96)
The isSafeShellArg() function properly rejects dangerous metacharacters:

if (c == ';' || c == '|' || c == '&' || c == '`' || c == '$'
    || c == '(' || c == ')' || c == '{' || c == '}' || c == '<'
    || c == '>' || c == '"' || c == '\n' || c == '\r') {
    return false;
}

4. CleanConsole Implementation (cpp/src/clean_console.cpp)

• Well-designed word-wrapping with ANSI color preservation
• Proper **bold** marker parsing for styled output
• Output preview truncation with line count indicators

5. CI Workflow (build_cpp.yml:267-294)
Good handling of PowerShell 5.1 stderr quirk with uv tool install:

$ErrorActionPreference = "SilentlyContinue"
uv tool install windows-mcp 2>$null
$installExit = $LASTEXITCODE
$ErrorActionPreference = "Stop"

6. MinGW Portability
Proper _dupenv_s guards with #ifdef _MSC_VER in test files, allowing MinGW builds.

---

🟡 Suggestions (Non-Blocking)

1. Context Size Hardcoded
In cpp/examples/health_agent.cpp:198, context size is hardcoded to 32K:

config.contextSize = 32768; // 32K needed for "Run ALL diagnostics"

Consider making this configurable or at least documenting why this value was chosen.

2. Test Integration Module Count
The documentation mentions "eight modules" in test suite description. Verify this matches the actual count in CMakeLists.txt:184-192 (currently lists 8 files: test_types, test_tool_registry, test_json_utils, test_agent, test_mcp_client, test_console, test_clean_console, test_tool_integration).

---

🟢 Test Coverage

The test_tool_integration.cpp file provides excellent coverage:

• WiFi agent tool registration and execution
• Input validation (safe vs unsafe hostnames)
• Health agent JSON parsing for all PowerShell outputs
• CleanConsole rendering pipeline
• Full diagnostic tool chains

The integration tests in test_integration_health.cpp properly skip on non-Windows platforms.

---

Files Reviewed

File	Status
.github/workflows/build_cpp.yml	✅ CI enhancements look good
cpp/src/agent.cpp	✅ Loop detection and truncation fixes
cpp/examples/health_agent.cpp	✅ Clean rewrite with proper MCP integration
cpp/examples/wifi_agent.cpp	✅ Shell injection prevention
cpp/include/gaia/clean_console.h	✅ Well-designed API
cpp/src/clean_console.cpp	✅ Proper ANSI handling
cpp/tests/test_tool_integration.cpp	✅ Comprehensive tests
cpp/tests/integration/test_integration_health.cpp	✅ Good LLM+MCP coverage
cpp/CMakeLists.txt	✅ Proper build structure
docs/guides/cpp/overview.mdx	✅ Clear architecture docs
docs/guides/cpp/wifi-agent.mdx	✅ Shell injection section added

---

Conclusion

This PR is ready to merge. The code is well-structured, properly tested, and the documentation accurately reflects the implementation changes.

---