yaze/docs/internal/plans/app-dev-agent-tools.md

App Development Agent Tools Specification

Document Version: 1.0 Date: 2025-11-22 Author: CLAUDE_AIINF Purpose: Define tools that enable AI agents to assist with yaze C++ development

Executive Summary

This document specifies new tools for the yaze AI agent system that enable agents to assist with C++ application development. These tools complement existing ROM manipulation and editor tools by providing build system interaction, code analysis, debugging assistance, and editor integration capabilities.

Tool Architecture Overview

Integration Points

• ToolDispatcher: Central routing via src/cli/service/agent/tool_dispatcher.cc
• CommandHandler Pattern: All tools inherit from resources::CommandHandler
• Output Formatting: JSON and text formats via resources::OutputFormatter
• Security Model: Sandboxed execution, project-restricted access
• Async Support: Long-running operations use background execution

Tool Specifications

1. Build System Tools

1.1 build_configure

Purpose: Configure CMake build with appropriate presets and options Priority: P0 (Critical for MVP)

Parameters:

struct BuildConfigureParams {
  std::string preset;        // e.g., "mac-dbg", "lin-ai", "win-rel"
  std::string build_dir;     // e.g., "build_ai" (default: "build")
  bool clean_build;          // Remove existing build directory first
  std::vector<std::string> options; // Additional CMake options
};

Returns:

{
  "status": "success",
  "preset": "mac-dbg",
  "build_directory": "/Users/scawful/Code/yaze/build_ai",
  "cmake_version": "3.28.0",
  "compiler": "AppleClang 15.0.0.15000100",
  "options_applied": ["YAZE_ENABLE_AI=ON", "YAZE_ENABLE_GRPC=ON"]
}

Implementation Approach:

• Execute cmake --preset <preset> via subprocess
• Parse CMakeCache.txt for configuration details
• Validate preset exists in CMakePresets.json
• Support parallel build directories for agent isolation

---

1.2 build_compile

Purpose: Trigger compilation of specific targets or entire project Priority: P0 (Critical for MVP)

Parameters:

struct BuildCompileParams {
  std::string build_dir;      // Build directory (default: "build")
  std::string target;          // Specific target or "all"
  int jobs;                    // Parallel jobs (default: CPU count)
  bool verbose;                // Show detailed compiler output
  bool continue_on_error;      // Continue building after errors
};

Returns:

{
  "status": "failed",
  "target": "yaze",
  "errors": [
    {
      "file": "src/app/editor/overworld_editor.cc",
      "line": 234,
      "column": 15,
      "severity": "error",
      "message": "use of undeclared identifier 'LoadGraphics'",
      "context": "  LoadGraphics();"
    }
  ],
  "warnings_count": 12,
  "build_time_seconds": 45.3,
  "artifacts": ["bin/yaze", "bin/z3ed"]
}

Implementation Approach:

• Execute cmake --build <dir> --target <target> -j<jobs>
• Parse compiler output with regex patterns for errors/warnings
• Track build timing and resource usage
• Support incremental builds and error recovery

---

1.3 build_test

Purpose: Execute test suites with filtering and result parsing Priority: P0 (Critical for MVP)

Parameters:

struct BuildTestParams {
  std::string build_dir;       // Build directory
  std::string suite;            // Test suite: "unit", "integration", "e2e", "all"
  std::string filter;           // Test name filter (gtest pattern)
  bool rom_dependent;           // Include ROM-dependent tests
  std::string rom_path;         // Path to ROM file (if rom_dependent)
  bool show_output;             // Display test output
};

Returns:

{
  "status": "failed",
  "suite": "unit",
  "tests_run": 156,
  "tests_passed": 154,
  "tests_failed": 2,
  "failures": [
    {
      "test_name": "SnesColorTest.ConvertRgbToSnes",
      "file": "test/unit/gfx/snes_color_test.cc",
      "line": 45,
      "failure_message": "Expected: 0x7FFF\n  Actual: 0x7FFE"
    }
  ],
  "execution_time_seconds": 12.4,
  "coverage_percent": 78.3
}

Implementation Approach:

• Execute ctest with appropriate labels and filters
• Parse test output XML (if available) or stdout
• Support test discovery and listing
• Handle timeouts and crashes gracefully

---

1.4 build_status

Purpose: Query current build system state and configuration Priority: P1 (Important for debugging)

Parameters:

struct BuildStatusParams {
  std::string build_dir;       // Build directory to inspect
  bool show_cache;              // Include CMakeCache variables
  bool show_targets;            // List available build targets
};

Returns:

{
  "configured": true,
  "preset": "mac-dbg",
  "last_build": "2025-11-22T10:30:00Z",
  "targets_available": ["yaze", "z3ed", "yaze_test", "format"],
  "configuration": {
    "CMAKE_BUILD_TYPE": "Debug",
    "YAZE_ENABLE_AI": "ON",
    "YAZE_ENABLE_GRPC": "ON"
  },
  "dirty_files": ["src/app/editor/overworld_editor.cc"],
  "build_dependencies_outdated": false
}

---

2. Code Analysis Tools

2.1 find_symbol

Purpose: Locate class, function, or variable definitions in codebase Priority: P0 (Critical for navigation)

Parameters:

struct FindSymbolParams {
  std::string symbol_name;     // Name to search for
  std::string symbol_type;     // "class", "function", "variable", "any"
  std::string scope;           // Directory scope (default: "src/")
  bool include_declarations;   // Include forward declarations
};

Returns:

{
  "symbol": "OverworldEditor",
  "type": "class",
  "locations": [
    {
      "file": "src/app/editor/overworld/overworld_editor.h",
      "line": 45,
      "kind": "definition",
      "context": "class OverworldEditor : public Editor {"
    },
    {
      "file": "src/app/editor/overworld/overworld_editor.cc",
      "line": 23,
      "kind": "implementation",
      "context": "OverworldEditor::OverworldEditor() {"
    }
  ],
  "base_classes": ["Editor"],
  "derived_classes": [],
  "namespace": "yaze::app::editor"
}

Implementation Approach:

• Use ctags/cscope database if available
• Fall back to intelligent grep patterns
• Parse include guards and namespace blocks
• Cache symbol database for performance

---

2.2 get_call_hierarchy

Purpose: Analyze function call relationships Priority: P1 (Important for refactoring)

Parameters:

struct CallHierarchyParams {
  std::string function_name;   // Function to analyze
  std::string direction;       // "callers", "callees", "both"
  int max_depth;                // Recursion depth (default: 3)
  bool include_virtual;         // Track virtual function calls
};

Returns:

{
  "function": "Rom::LoadFromFile",
  "callers": [
    {
      "function": "EditorManager::OpenRom",
      "file": "src/app/editor/editor_manager.cc",
      "line": 156,
      "call_sites": [{"line": 162, "context": "rom_->LoadFromFile(path)"}]
    }
  ],
  "callees": [
    {
      "function": "Rom::ReadAllGraphicsData",
      "file": "src/app/rom.cc",
      "line": 234,
      "is_virtual": false
    }
  ],
  "complexity_score": 12
}

---

2.3 get_class_members

Purpose: List all methods and fields of a class Priority: P1 (Important for understanding)

Parameters:

struct ClassMembersParams {
  std::string class_name;      // Class to analyze
  bool include_inherited;      // Include base class members
  bool include_private;        // Include private members
  std::string filter;          // Filter by member name pattern
};

Returns:

{
  "class": "OverworldEditor",
  "namespace": "yaze::app::editor",
  "members": {
    "methods": [
      {
        "name": "Update",
        "signature": "absl::Status Update() override",
        "visibility": "public",
        "is_virtual": true,
        "line": 67
      }
    ],
    "fields": [
      {
        "name": "current_map_",
        "type": "int",
        "visibility": "private",
        "line": 234,
        "has_getter": true,
        "has_setter": false
      }
    ]
  },
  "base_classes": ["Editor"],
  "total_methods": 42,
  "total_fields": 18
}

---

2.4 analyze_includes

Purpose: Show include dependency graph Priority: P2 (Useful for optimization)

Parameters:

struct AnalyzeIncludesParams {
  std::string file_path;       // File to analyze
  std::string direction;       // "includes", "included_by", "both"
  bool show_system;             // Include system headers
  int max_depth;                // Recursion depth
};

Returns:

{
  "file": "src/app/editor/overworld_editor.cc",
  "direct_includes": [
    {"file": "overworld_editor.h", "is_system": false},
    {"file": "app/rom.h", "is_system": false},
    {"file": <vector>", "is_system": true}
  ],
  "included_by": [
    "src/app/editor/editor_manager.cc"
  ],
  "include_depth": 3,
  "circular_dependencies": [],
  "suggestions": ["Consider forward declaration for 'Rom' class"]
}

---

3. Debug Tools

3.1 parse_crash_log

Purpose: Extract actionable information from crash dumps Priority: P0 (Critical for debugging)

Parameters:

struct ParseCrashLogParams {
  std::string log_path;        // Path to crash log or stdin
  std::string platform;        // "macos", "linux", "windows", "auto"
  bool symbolicate;            // Attempt to resolve symbols
};

Returns:

{
  "crash_type": "SIGSEGV",
  "crash_address": "0x00000000",
  "crashed_thread": 0,
  "stack_trace": [
    {
      "frame": 0,
      "address": "0x10234abcd",
      "symbol": "yaze::app::editor::OverworldEditor::RenderMap",
      "file": "src/app/editor/overworld_editor.cc",
      "line": 456,
      "is_user_code": true
    }
  ],
  "likely_cause": "Null pointer dereference in RenderMap",
  "suggested_fixes": [
    "Check if 'current_map_data_' is initialized before use",
    "Add null check at line 456"
  ],
  "similar_crashes": ["#1234 - Fixed in commit abc123"]
}

Implementation Approach:

• Parse platform-specific crash formats (lldb, gdb, Windows dumps)
• Symbolicate addresses using debug symbols
• Identify patterns (null deref, stack overflow, etc.)
• Search issue tracker for similar crashes

---

3.2 get_memory_profile

Purpose: Analyze memory usage and detect leaks Priority: P2 (Useful for optimization)

Parameters:

struct MemoryProfileParams {
  std::string process_name;    // Process to analyze or PID
  std::string profile_type;    // "snapshot", "leaks", "allocations"
  int duration_seconds;         // For allocation profiling
};

Returns:

{
  "total_memory_mb": 234.5,
  "heap_size_mb": 180.2,
  "largest_allocations": [
    {
      "size_mb": 45.6,
      "location": "gfx::Arena::LoadAllGraphics",
      "count": 223,
      "type": "gfx::Bitmap"
    }
  ],
  "potential_leaks": [
    {
      "size_bytes": 1024,
      "allocation_site": "CreateTempBuffer at editor.cc:123",
      "leak_confidence": 0.85
    }
  ],
  "memory_growth_rate_mb_per_min": 2.3
}

---

3.3 analyze_performance

Purpose: Profile performance hotspots Priority: P2 (Useful for optimization)

Parameters:

struct PerformanceAnalysisParams {
  std::string target;           // Binary or test to profile
  std::string scenario;         // Specific scenario to profile
  int duration_seconds;         // Profiling duration
  std::string metric;           // "cpu", "memory", "io", "all"
};

Returns:

{
  "hotspots": [
    {
      "function": "gfx::Bitmap::ApplyPalette",
      "cpu_percent": 23.4,
      "call_count": 1000000,
      "avg_duration_us": 12.3,
      "file": "src/app/gfx/bitmap.cc",
      "line": 234
    }
  ],
  "bottlenecks": [
    "Graphics rendering taking 65% of frame time",
    "Excessive allocations in tile loading"
  ],
  "optimization_suggestions": [
    "Cache palette conversions",
    "Use SIMD for pixel operations"
  ]
}

---

4. Editor Integration Tools

4.1 get_canvas_state

Purpose: Query current canvas/editor state for context Priority: P1 (Important for automation)

Parameters:

struct CanvasStateParams {
  std::string editor_type;     // "overworld", "dungeon", "graphics"
  bool include_selection;      // Include selected entities
  bool include_viewport;       // Include camera/zoom info
};

Returns:

{
  "editor": "overworld",
  "current_map": 0x00,
  "map_name": "Hyrule Field",
  "viewport": {
    "x": 0,
    "y": 0,
    "width": 512,
    "height": 512,
    "zoom": 2.0
  },
  "selection": {
    "type": "entrance",
    "id": 0x03,
    "position": {"x": 256, "y": 128}
  },
  "tool": "select",
  "modified": true,
  "undo_stack_size": 15
}

Implementation Approach:

• Query EditorManager for active editor
• Use Canvas automation API for state extraction
• Serialize entity selections and properties
• Include modification tracking

---

4.2 simulate_user_action

Purpose: Trigger UI actions programmatically Priority: P1 (Important for automation)

Parameters:

struct SimulateActionParams {
  std::string action_type;     // "click", "drag", "key", "menu"
  nlohmann::json parameters;   // Action-specific parameters
  std::string editor_context;  // Which editor to target
};

Returns:

{
  "action": "click",
  "target": "tile_palette",
  "position": {"x": 100, "y": 50},
  "result": "success",
  "new_selection": {
    "tile_id": 0x42,
    "tile_type": "grass"
  },
  "side_effects": ["Tool changed to 'paint'"]
}

---

4.3 capture_screenshot

Purpose: Capture editor visuals for verification or documentation Priority: P2 (Useful for testing)

Parameters:

struct ScreenshotParams {
  std::string output_path;     // Where to save screenshot
  std::string target;          // "full", "canvas", "window"
  std::string format;          // "png", "jpg", "bmp"
  bool include_ui;              // Include UI overlays
};

Returns:

{
  "status": "success",
  "file_path": "/tmp/screenshot_2025_11_22_103045.png",
  "dimensions": {"width": 1920, "height": 1080},
  "file_size_kb": 234,
  "metadata": {
    "editor": "overworld",
    "map_id": "0x00",
    "timestamp": "2025-11-22T10:30:45Z"
  }
}

---

Implementation Roadmap

Phase 1: MVP (Week 1)

Priority P0 tools only

1. build_compile - Essential for development iteration
2. build_test - Required for validation
3. find_symbol - Core navigation capability
4. parse_crash_log - Critical debugging tool

Phase 2: Enhanced (Week 2)

Priority P1 tools

1. build_configure - Build system management
2. build_status - State inspection
3. get_call_hierarchy - Code understanding
4. get_class_members - API exploration
5. get_canvas_state - Editor integration
6. simulate_user_action - Automation capability

Phase 3: Complete (Week 3)

Priority P2 tools

1. analyze_includes - Optimization support
2. get_memory_profile - Memory debugging
3. analyze_performance - Performance tuning
4. capture_screenshot - Visual verification

Integration with Existing Infrastructure

ToolDispatcher Integration

Add to tool_dispatcher.h:

enum class ToolCallType {
  // ... existing types ...

  // Build Tools
  kBuildConfigure,
  kBuildCompile,
  kBuildTest,
  kBuildStatus,

  // Code Analysis
  kCodeFindSymbol,
  kCodeGetCallHierarchy,
  kCodeGetClassMembers,
  kCodeAnalyzeIncludes,

  // Debug Tools
  kDebugParseCrashLog,
  kDebugGetMemoryProfile,
  kDebugAnalyzePerformance,

  // Editor Integration
  kEditorGetCanvasState,
  kEditorSimulateAction,
  kEditorCaptureScreenshot,
};

Handler Implementation Pattern

Each tool follows the CommandHandler pattern:

class BuildCompileCommandHandler : public resources::CommandHandler {
 public:
  std::string GetName() const override { return "build-compile"; }

  std::string GetUsage() const override {
    return "build-compile --build-dir <dir> [--target <name>] "
           "[--jobs <n>] [--verbose] [--format <json|text>]";
  }

 protected:
  absl::Status ValidateArgs(const resources::ArgumentParser& parser) override {
    // Validate required arguments
    return absl::OkStatus();
  }

  absl::Status Execute(Rom* rom, const resources::ArgumentParser& parser,
                      resources::OutputFormatter& formatter) override {
    // Implementation
    return absl::OkStatus();
  }

  bool RequiresLabels() const override { return false; }
};

Security Considerations

1. Build System Tools:

   • Restrict to project directory
   • Validate presets against CMakePresets.json
   • Sanitize compiler flags
   • Limit parallel jobs to prevent DoS

2. Code Analysis Tools:

   • Read-only operations only
   • Cache results to prevent excessive parsing
   • Timeout long-running analyses

3. Debug Tools:

   • Sanitize crash log paths
   • Limit profiling duration
   • Prevent access to system processes

4. Editor Integration:

   • Rate limit UI actions
   • Validate action parameters
   • Prevent infinite loops in automation

Testing Strategy

Unit Tests

• Mock subprocess execution for build tools
• Test error parsing with known compiler outputs
• Verify security restrictions (path traversal, etc.)

Integration Tests

• Test with real CMake builds (small test projects)
• Verify symbol finding with known codebase structure
• Test crash parsing with sample logs

End-to-End Tests

• Full development workflow automation
• Build → Test → Debug cycle
• Editor automation scenarios

Performance Considerations

1. Caching:

   • Symbol database caching (5-minute TTL)
   • Build status caching (invalidate on file changes)
   • Compiler error pattern cache

2. Async Operations:

   • Long builds run in background
   • Profiling operations are async
   • Support streaming output for progress

3. Resource Limits:

   • Max parallel build jobs = CPU count
   • Profiling duration cap = 5 minutes
   • Screenshot size limit = 10MB

Success Metrics

1. Developer Productivity:

   • Reduce build debugging time by 50%
   • Enable AI agents to fix 80% of simple compilation errors
   • Automate 60% of test failure investigations

2. Code Quality:

   • Increase test coverage by 20% through AI-generated tests
   • Identify 90% of memory leaks before release
   • Reduce performance regressions by 40%

3. Agent Capabilities:

   • Agents can complete full edit-compile-test cycles
   • Agents can diagnose and suggest fixes for crashes
   • Agents can navigate and understand codebase structure

Appendix A: Error Pattern Database

Common compilation error patterns for parsing:

# GCC/Clang error
^([^:]+):(\d+):(\d+):\s+(error|warning):\s+(.+)$

# MSVC error
^([^(]+)\((\d+)\):\s+(error|warning)\s+(\w+):\s+(.+)$

# Linker error
^(ld|link):\s+(error|warning):\s+(.+)$

Appendix B: Platform-Specific Considerations

macOS

• Use xcrun for toolchain discovery
• Parse .crash files from ~/Library/Logs/DiagnosticReports/
• Support both x86_64 and arm64 architectures

Linux

• Check for gcc/g++ and clang/clang++
• Parse core dumps with gdb
• Use perf for profiling when available

Windows

• Handle both MSVC and MinGW toolchains
• Parse .dmp files for crash analysis
• Use Windows Performance Toolkit for profiling

Appendix C: AI Agent Use Cases

Use Case 1: Compilation Error Resolution

Agent: I see you have a compilation error in overworld_editor.cc
Agent: Let me analyze the error...
[Executes: build_compile --verbose]
[Executes: find_symbol --symbol LoadGraphics]
Agent: The function LoadGraphics was renamed to LoadAreaGraphics in commit abc123
Agent: I'll update the call site...
[Modifies file]
[Executes: build_compile --target yaze]
Agent: Build successful! The error is resolved.

Use Case 2: Test Failure Investigation

Agent: The SnesColorTest is failing. Let me investigate...
[Executes: build_test --filter "*SnesColor*" --show-output]
[Executes: get_class_members --class SnesColor]
Agent: The test expects 0x7FFF but gets 0x7FFE
Agent: This is a rounding error in the conversion function
[Analyzes implementation]
Agent: The issue is at line 45 - we need to round instead of truncate

Use Case 3: Performance Optimization

Agent: Let me profile the slow rendering...
[Executes: analyze_performance --scenario "load_overworld"]
Agent: I found that ApplyPalette takes 23% of CPU time
[Executes: get_call_hierarchy --function ApplyPalette]
Agent: It's called 1M times per frame - that's excessive
Agent: I suggest caching the palette conversions...

Document History

• 2025-11-22: Initial specification (v1.0) - CLAUDE_AIINF