dap-protocol-guide

DAP Protocol Guide for AIDB

This skill provides comprehensive guidance for working with the Debug Adapter Protocol (DAP) in AIDB. Use this when implementing features that interact with debug adapters, analyzing DAP message flows, or troubleshooting protocol-level issues.

Overview

The Debug Adapter Protocol (DAP) is a standardized protocol for communication between development tools and debug adapters. AIDB provides a fully-typed, authoritative implementation in src/aidb/dap/protocol/.

For system-wide DAP architecture, see docs/developer-guide/overview.md which includes:

• Complete data flow diagrams
• DAP client layer details
• Integration with adapters and session management

Key Principles

1. Always use existing protocol types - Don't create dictionaries manually
2. Follow established patterns - Check adapter implementations before creating new request sequences
3. Handle errors properly - DAP has specific error response patterns
4. Respect initialization sequence - Initialize → Launch/Attach → ConfigurationDone
5. Consider language differences - Python, JavaScript, and Java adapters have different behaviors

Authoritative Source

src/aidb/dap/protocol/ is THE authoritative reference for all DAP types and messages.

This package contains:

• types.py - DAP data types (Breakpoint, StackFrame, Variable, etc.)
• requests.py - All request message classes
• responses.py - All response message classes
• events.py - All event message classes
• bodies.py - Request arguments and response bodies
• base.py - Base classes (Request, Response, Event, ProtocolMessage)

Quick Reference

Common DAP Operations

# Import protocol types
from aidb.dap.protocol import (
    InitializeRequest,
    LaunchRequest,
    SetBreakpointsRequest,
    StackTraceRequest,
    ScopesRequest,
    VariablesRequest,
    ContinueRequest,
)
from aidb.dap.protocol.types import Source, SourceBreakpoint
from aidb.dap.protocol.bodies import (
    InitializeRequestArguments,
    LaunchRequestArguments,
    SetBreakpointsArguments,
    StackTraceArguments,
)

# Get next sequence number
seq = await client.get_next_seq()

# Build a request
request = SetBreakpointsRequest(
    seq=seq,
    arguments=SetBreakpointsArguments(
        source=Source(path="/path/to/file.py"),
        breakpoints=[
            SourceBreakpoint(line=10, condition="x > 5")
        ]
    )
)

# Send request and await response
response = await client.send_request(request)