feat(debug): add Debug Companion — AI-powered debugging for Gemini CLI

[SUNDRAM07]

Summary

This PR adds the Debug Companion — a production-grade, AI-powered debugging subsystem for Gemini CLI. It implements a proof-of-concept for Idea #7: Debug Companion, providing 9 debug tools, a full DAP (Debug Adapter Protocol) client, and 33 supporting modules spanning 7 architectural layers.

This is a Draft PR — it represents a proof-of-concept demonstrating the core architecture and capabilities. The remaining work (interactive /debug command, Ink TUI, integration tests with real debuggers) is planned for the GSoC period.

What does this PR do?

It enables Gemini CLI to debug programs by communicating with debug adapters (Node.js, Python, Go, Ruby) through the Debug Adapter Protocol. The LLM can launch debug sessions, set breakpoints, step through code, inspect variables, evaluate expressions, and analyze errors — all through natural language.

9 Debug Tools

Tool	Purpose
debug_launch	Start a debug session with auto-configured adapters
debug_attach	Attach to a running process
debug_set_breakpoint	Set line breakpoints with conditions and hit counts
debug_set_function_breakpoint	Set breakpoints on function names
debug_step	Step in/out/over/next with granular control
debug_evaluate	Evaluate expressions in debug context
debug_get_stacktrace	Retrieve enriched stack traces with source context
debug_get_variables	Inspect variables with scope filtering
debug_disconnect	Graceful session termination

Architecture: 33 Modules, 7 Layers

graph TB
    subgraph Protocol["Protocol Layer"]
        DAP["DAPClient — Wire Protocol + TCP"]
        SRC["SourceMapResolver"]
        REG["DebugAdapterRegistry"]
        CFG["DebugConfigPresets"]
    end

    subgraph Tools["Tool Layer — 9 Tools"]
        T["debug_launch / attach / breakpoint<br/>step / evaluate / stacktrace<br/>variables / disconnect / function_bp"]
    end

    subgraph Breakpoints["Breakpoint Layer"]
        BS["BreakpointStore"]
        SS["SmartSuggester — 4 strategies"]
        DB["DataBreakpointManager"]
        EB["ExceptionBreakpointManager"]
        BV["BreakpointValidator — Pre-validation"]
    end

    subgraph Analysis["Analysis Layer"]
        STA["StackTraceAnalyzer"]
        FIX["FixSuggestionEngine — 11 patterns"]
        KB["ErrorKnowledgeBase"]
        RCA["RootCauseAnalyzer"]
        EC["DebugErrorClassifier — 17 patterns"]
    end

    subgraph State["State Layer"]
        SM["SessionStateMachine — 8-state FSM"]
        SH["SessionHistory — Loop detection"]
        SER["SessionSerializer"]
        CSR["ConditionalStepRunner"]
    end

    subgraph Context["Context Layer"]
        CTX["DebugContextBuilder — Token-aware"]
        DP["DebugPrompt"]
        WM["WatchExpressionManager"]
        VDT["VariableDiffTracker"]
        TEL["TelemetryCollector"]
        PERF["PerformanceProfiler"]
    end

    subgraph Infra["Infrastructure Layer"]
        APM["AdapterProcessManager — 4 languages"]
        SAN["InputSanitizer"]
        PG["PolicyGuard"]
        TG["TestGenerator"]
        WO["WorkflowOrchestrator"]
        IFP["InlineFixPreview"]
    end

    Tools --> Protocol
    Tools --> Breakpoints
    Tools --> Analysis
    Tools --> State
    Context --> Tools
    Infra --> Protocol

Loading

Key Design Decisions

1. Protocol-first architecture: The DAPClient implements the full DAP wire protocol with TCP transport, Content-Length framing, and request/response correlation — the same protocol used by VS Code.

2. Pre-validation over post-failure: BreakpointValidator checks if a line is executable before sending to the adapter, preventing the common "breakpoint not verified" frustration.

3. LLM-optimized context: DebugContextBuilder creates priority-ranked, token-budget-aware context for the LLM, ensuring the most relevant debug information is always available regardless of context window limits.

4. Production resilience: DebugErrorClassifier transforms raw error strings into structured, actionable intelligence with 17 patterns across 8 categories — each with severity, recovery strategies, and retry logic.

5. Root cause analysis: RootCauseAnalyzer goes beyond "what crashed" to answer "why" — generating ranked hypotheses with confidence scores and concrete debugging next steps.

Testing

• 419 tests across 30 test files — all passing ✅
• TypeScript compilation: Clean, zero errors ✅
• Test coverage: Every module has a corresponding test file

Test Files  30 passed (30)
     Tests  419 passed (419)
  Duration  1.59s

What's Next (GSoC Timeline)

Phase	Work	Est. Weeks
1	/debug slash command & interactive debug mode	6-8
2	Debug Mode Ink TUI (variable panel, stack view, source preview)	4-6
3	Integration tests with real debuggers (Node.js, Python, Go)	3-4
4	Adapter auto-discovery & lifecycle management	3-4

Stats

Metric	Value
Lines of Code	16,467
Modules	33
Tools	9
Tests	419
Source Files	31
Test Files	30
Languages Supported	4 (Node.js, Python, Go, Ruby)
Error Patterns	17

Related to #20674

[gemini-cli]

Hi there! Thank you for your interest in contributing to Gemini CLI.

To ensure we maintain high code quality and focus on our prioritized roadmap, we have updated our contribution policy (see Discussion #17383).

We only guarantee review and consideration of pull requests for issues that are explicitly labeled as 'help wanted'. All other community pull requests are subject to closure after 14 days if they do not align with our current focus areas. For this reason, we strongly recommend that contributors only submit pull requests against issues explicitly labeled as 'help-wanted'.

This pull request is being closed as it has been open for 14 days without a 'help wanted' designation. We encourage you to find and contribute to existing 'help wanted' issues in our backlog! Thank you for your understanding and for being part of our community!