yaze/docs/internal/agents/archive/utility-tools/ai-modularity.md

AI & gRPC Modularity Blueprint

Date: November 16, 2025 – Author: GPT-5.1 Codex

1. Scope & Goals

• Make AI/gRPC features optional without scattering #ifdef guards.
• Ensure Windows builds succeed regardless of whether AI tooling is enabled.
• Provide a migration path toward relocatable dependencies (ext/) and cleaner preset defaults for macOS + custom tiling window manager workflows (sketchybar/yabai/skhd, Emacs/Spacemacs).

2. Current Touchpoints

Surface	Key Paths	Notes
Editor UI	src/app/editor/agent/**, app/gui/app/agent_chat_widget.cc, app/editor/agent/agent_chat_history_popup.cc	Widgets always compile when YAZE_ENABLE_GRPC=ON, but they include protobuf types directly.
Core Services	src/app/service/grpc_support.cmake, app/service/*.cc, app/test/test_recorder.cc	yaze_grpc_support bundles servers, generated protos, and even CLI code (cli/service/planning/tile16_proposal_generator.cc).
CLI / z3ed	src/cli/agent.cmake, src/cli/service/agent/*.cc, src/cli/service/ai/*.cc, src/cli/service/gui/*.cc	gRPC, Gemeni/Ollama (JSON + httplib/OpenSSL) all live in one static lib.
Build Flags	cmake/options.cmake, scattered #ifdef Z3ED_AI and #ifdef Z3ED_AI_AVAILABLE	Flags do not describe GUI vs CLI vs runtime needs, so every translation unit drags in gRPC headers once YAZE_ENABLE_GRPC=ON.
Tests & Automation	src/app/test/test_manager.cc, scripts/agent_test_suite.sh, .github/workflows/ci.yml	Tests assume AI features exist; Windows agents hit linker issues when that assumption breaks.

3. Coupling Pain Points

1. Single Monolithic yaze_agent – Links SDL, GUI, emulator, Abseil, yaml, nlohmann_json, httplib, OpenSSL, and gRPC simultaneously. No stubs exist when only CLI or GUI needs certain services (src/cli/agent.cmake).
2. Editor Hard Links – yaze_editor unconditionally links yaze_agent when YAZE_MINIMAL_BUILD is OFF, so even ROM-editing-only builds drag in AI dependencies (src/app/editor/editor_library.cmake).
3. Shared Proto Targets – yaze_grpc_support consumes CLI proto files, so editor-only builds still compile CLI automation code (src/app/service/grpc_support.cmake).
4. Preprocessor Guards – UI code mixes Z3ED_AI and Z3ED_AI_AVAILABLE; CLI code checks Z3ED_AI while build system only defines Z3ED_AI when YAZE_ENABLE_AI=ON. These mismatches cause dead code paths and missing symbols.

4. Windows Build Blockers

• Runtime library mismatch – yaml-cpp and other dependencies are built /MT while yaze_emu uses /MD, causing cascades of LNK2038 and _Lockit/libcpmt conflicts (logs/windows_ci_linker_error.log).
• OpenSSL duplication – yaze_agent links cpp-httplib with OpenSSL while gRPC pulls BoringSSL, leading to duplicate symbol errors (libssl.lib vs ssl.lib) in the same log.
• Missing native dialogs – FileDialogWrapper symbols fail to link when macOS-specific implementations are not excluded on Windows (also visible in the same log).
• Preset drift – win-ai enables GRPC/AI without guaranteeing vcpkg/clang-cl or ROM assets; win-dbg disables gRPC entirely so editor agents fail to compile because of unconditional includes.

5. Proposed Modularization

Proposed CMake Option	Purpose	Default	Notes
YAZE_BUILD_AGENT_UI	Compile ImGui agent widgets (editor).	ON for GUI presets, OFF elsewhere.	Controls app/editor/agent/** sources.
YAZE_ENABLE_REMOTE_AUTOMATION	Build/ship gRPC servers & automation bridges.	ON in *-ai presets.	Owns yaze_grpc_support + proto generation.
YAZE_ENABLE_AI_RUNTIME	Include AI runtime (Gemini/Ollama, CLI planners).	ON in CLI/AI presets.	Governs cli/service/ai/**.
YAZE_ENABLE_AGENT_CLI	Build z3ed with full agent features.	ON when CLI requested.	Allows z3ed to be disabled independently.

Implementation guidelines:

1. Split Targets
   • yaze_agent_core: command routing, ROM helpers, no AI.
   • yaze_agent_ai: depends on JSON + OpenSSL + remote automation.
   • yaze_agent_ui_bridge: tiny facade that editor links only when YAZE_BUILD_AGENT_UI=ON.
2. Proto Ownership
   • Keep proto generation under yaze_grpc_support, but do not add CLI sources to that target. Instead, expose headers/libs and let CLI link them conditionally.
3. Stub Providers
   • Provide header-compatible no-op classes (e.g., AgentChatWidgetBridge::Create() returning nullptr) when UI is disabled, removing the need for #ifdef in ImGui panels.
4. Dependency Injection
   • Replace #ifdef Z3ED_AI_AVAILABLE in agent_chat_widget.cc with an interface returned from AgentFeatures::MaybeCreateChatPanel().

6. Preset & Feature Matrix

Preset	GUI	CLI	GRPC	AI Runtime	Agent UI
mac-dbg	✅	✅	⚪	⚪	✅
mac-ai	✅	✅	✅	✅	✅
lin-dbg	✅	✅	⚪	⚪	✅
ci-windows	✅	✅	⚪	⚪	⚪ (core only)
ci-windows-ai (new nightly)	✅	✅	✅	✅	✅
win-dbg	✅	✅	⚪	⚪	✅
win-ai	✅	✅	✅	✅	✅

Legend: ✅ enabled, ⚪ disabled.

7. Migration Steps

1. Define Options in cmake/options.cmake and propagate via presets.
2. Restructure Libraries:
   • Move CLI AI/runtime code into yaze_agent_ai.
   • Add yaze_agent_stub for builds without AI.
   • Make yaze_editor link against stub/real target via generator expressions.
3. CMake Cleanup:
   • Limit yaze_grpc_support to gRPC-only code.
   • Guard JSON/OpenSSL includes behind YAZE_ENABLE_AI_RUNTIME.
4. Windows Hardening:
   • Force /MD everywhere and ensure yaml-cpp inherits CMAKE_MSVC_RUNTIME_LIBRARY.
   • Allow only one SSL provider based on feature set.
   • Add preset validation in scripts/verify-build-environment.ps1.
5. CI/CD Split:
   • Current .github/workflows/ci.yml runs GRPC on all platforms; adjust to run minimal Windows build plus nightly AI build to save time and reduce flakiness.
6. Docs + Scripts:
   • Update build guides to describe new options.
   • Document how macOS users can integrate headless builds with sketchybar/yabai/skhd (focus on CLI usage + automation).
7. External Dependencies:
   • Relocate submodules to ext/ and update scripts so the new layout is enforced before toggling feature flags.

8. Deliverables

• This blueprint (docs/internal/agents/ai-modularity.md).
• Updated CMake options, presets, and stubs.
• Hardened Windows build scripts/logging.
• CI/CD workflow split + release automation updates.
• Documentation refresh & dependency relocation.