[GSoC 2026] Idea #7 — Debug Companion: Proof-of-Concept & Architecture Discussion

[SUNDRAM07]

Hi everyone, I'm Sundaram Mahajan (Sundram07).

I've been contributing to Gemini CLI for the past few weeks and I'm deeply interested in Idea #7: Terminal-Integrated Debugging Companion via DAP (issue #20674). I've built a comprehensive proof-of-concept implementation to explore the architectural requirements and would love to start a discussion about the design.

Proof-of-Concept & My Progress

I've implemented a functional DAP (Debug Adapter Protocol) subsystem in Draft PR #22472. This is currently exploratory work to validate the feasibility of agentic debugging.

Current Stats:

• Lines of Code: 16,467
• Tests: 419 passed ✅
• Modules: 33 spanning 7 architectural layers
• Debug Tools: 9 integrated tools (debug_launch, debug_step, debug_get_stacktrace, etc.)

Architecture Diagram

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

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

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

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

    subgraph Context["Context Layer"]
        CTX["DebugContextBuilder — Token-aware"]
        VDT["VariableDiffTracker"]
    end

    subgraph Infra["Infrastructure Layer"]
        APM["AdapterProcessManager — 4 languages"]
        PG["PolicyGuard"]
        SAN["InputSanitizer"]
    end

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

Loading

Key Technical Explorations

In building this PoC, I've focused on several "hard" problems that I think are central to the GSoC project:

1. LLM-Optimized Context: Raw DAP data is too verbose. I've built a DebugContextBuilder that priority-ranks state (stack, variables, source) to feed the LLM exactly what it needs within its token budget.
2. Pre-validation Logic: I implemented a BreakpointValidator that checks if a line is executable before sending it to the adapter, reducing "unverified breakpoint" errors.
3. Session Lifecycle: A robust 8-state Finite State Machine (FSM) manages the transition from Idle → Running → Stopped → Stepping to ensure session stability.
4. Security & Guard Rails: Every debug operation (especially evaluate) passes through a PolicyGuard and InputSanitizer to prevent injection or unauthorized code execution.

My Contributions to Gemini CLI

I've been an active contributor over the last period to build trust and understanding of the codebase:

• #20954 — fix(core): platform-aware command separator
• #20862 — fix(cli): emit STREAM_JSON for AgentExecutionBlocked
• #20699 — fix(policy): reject unknown policy fields (security)
• #20454 — fix: add JSON output for AgentExecutionStopped
• #20004 — fix: trap SIGHUP for WSL2
• #19935 — fix(core): parse callCommand with shell-quote
• Note: I recently consolidated my open PRs (closing fix: handle STREAM_JSON output format in validateNonInteractiveAuth #20185) to stay within contributor limits.

Design Questions for Mentors

1. Tool State Management: Should the debug session state live within the tool instance or be managed by a higher-level DebugSessionManager in the agent loop?
2. Unified Policy Engine: Should debug risk classification be integrated directly into the core PolicyEngine, or remain as a specialized DebugPolicyGuard?
3. Transport Choice: My PoC uses TCP/IP for adapter communication. Would a stdio transport be preferred for better portability without port management?

I'm incredibly excited about the potential of a "Debug Companion". Looking forward to hearing your thoughts and feedback!

Thanks,
Sundaram Mahajan (Sundram07)