yaze/docs/internal/handoff/ai-api-phase2-handoff.md

AI API & Agentic Workflow Enhancement - Phase 2 Handoff

Date: 2025-11-20 Status: Phase 2 Implementation Complete Previous Plan: docs/internal/AI_API_ENHANCEMENT_HANDOFF.md

Overview

This handoff covers the completion of Phase 2, which focused on unifying the UI for model selection and implementing the initial HTTP API server foundation. The codebase is now ready for building and verifying the API endpoints.

Completed Work

1. UI Unification (src/app/editor/agent/agent_chat_widget.cc)

• Unified Model List: Replaced the separate Ollama/Gemini list logic with a single, unified list derived from ModelRegistry.
• Provider Badges: Models in the list now display their provider (e.g., [ollama], [gemini]).
• Contextual Configuration:
  • If an Ollama model is selected, the "Ollama Host" input is displayed.
  • If a Gemini model is selected, the "API Key" input is displayed.
• Favorites & Presets: Updated to work with the unified ModelInfo structure.

2. HTTP Server Implementation (src/cli/service/api/)

• HttpServer Class:
  • Wraps httplib::Server running in a background std::thread.
  • Exposed via Start(port) and Stop() methods.
  • Graceful shutdown handling.
• API Handlers:
  • GET /api/v1/health: Returns server status (JSON).
  • GET /api/v1/models: Returns list of available models from ModelRegistry.
• Integration:
  • Updated src/cli/agent.cmake to include http_server.cc, api_handlers.cc, and model_registry.cc.
  • Updated src/app/main.cc to accept --enable_api and --api_port flags.

Build & Test Instructions

1. Building

The project uses CMake. The new files are automatically included in the yaze_agent library via src/cli/agent.cmake.

# Generate build files (if not already done)
cmake -B build -G Ninja

# Build the main application
cmake --build build --target yaze_app

2. Testing the UI

1. Launch the editor:

   ./build/yaze_app --editor=Agent
   

2. Verify the Model Configuration panel:
   • You should see a single list of models.
   • Try searching for a model.
   • Select an Ollama model -> Verify "Host" input appears.
   • Select a Gemini model -> Verify "API Key" input appears.

3. Testing the API

1. Launch the editor with API enabled:

   ./build/yaze_app --enable_api --api_port=8080
   

   (Check logs for "Starting API server on port 8080")

2. Test Health Endpoint:

   curl -v http://localhost:8080/api/v1/health
   # Expected: {"status":"ok", "version":"1.0", ...}
   

3. Test Models Endpoint:

   curl -v http://localhost:8080/api/v1/models
   # Expected: {"models": [{"name": "...", "provider": "..."}], "count": ...}
   

Next Steps (Phase 3 & 4)

Phase 3: Tool Expansion

• FileSystemTool: Implement safe file read/write operations (src/cli/handlers/tools/filesystem_commands.h).
• BuildTool: Implement cmake/ninja triggers.
• Editor Integration: Inject editor state (open files, errors) into the agent context.

Phase 4: Structured Output

• Refactor ToolDispatcher to return JSON objects instead of capturing stdout strings.
• Update API to expose a /api/v1/chat endpoint that returns these structured responses.