dap-protocol-guide

name	dap-protocol-guide
description	Comprehensive guide for working with Debug Adapter Protocol in AIDB
version	1.0.0
tags	["dap","protocol","debugging","requests","responses"]

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)

Client Constants

Always use constants from src/aidb/dap/client/constants.py:

from aidb.dap.client.constants import (
    CommandType,
    EventType,
    StopReason,
)

# Check event type
if event.event == EventType.STOPPED.value:
    # Handle stopped event
    pass

# Check stop reason
if stopped_body.reason == StopReason.BREAKPOINT.value:
    # Handle breakpoint
    pass

Protocol Flow Overview

Standard Initialization Sequence

Client → Initialize Request
       ← Initialize Response (capabilities)
       ← Initialized Event
Client → SetBreakpoints (optional, multiple)
Client → SetExceptionBreakpoints (optional)
Client → ConfigurationDone Request
       ← ConfigurationDone Response
Client → Launch/Attach Request
       ← Launch/Attach Response
       [Debug session active]

Introspection Flow

       ← Stopped Event
Client → Threads Request
       ← Threads Response
Client → StackTrace Request (threadId)
       ← StackTrace Response (stackFrames)
Client → Scopes Request (frameId)
       ← Scopes Response (scopes)
Client → Variables Request (variablesReference)
       ← Variables Response (variables)

Execution Control

Client → Continue/Next/StepIn/StepOut Request
       ← Response (acknowledgement)
       ← Stopped Event (when execution stops again)

Resource Files

This skill is organized into focused resource files, each under 500 lines:

Core Protocol Operations

• initialization-sequence.md

  • Initialize request/response
  • Attach vs Launch differences
  • Configuration done sequence
  • Language-specific initialization parameters

• breakpoint-operations.md

  • Setting source breakpoints
  • Conditional breakpoints
  • Hit conditions and log points
  • Breakpoint verification
  • Language-specific breakpoint quirks

• stack-inspection.md

  • Stack trace requests
  • Frame ID handling
  • Scope requests
  • Source references
  • Language-specific stack frame differences

• variable-evaluation.md

  • Variables request
  • Variables reference tracking
  • Evaluate request
  • Expression contexts
  • Language-specific variable representations

Patterns & Best Practices

Language-Specific Differences

Python (debugpy)

• Uses launch or attach request types
• justMyCode controls whether to step into library code
• Variable inspection is straightforward
• Stack frames include Python-specific metadata
• Supports showReturnValue option

JavaScript/TypeScript (vscode-js-debug)

• Uses child sessions for subprocess debugging
• Source maps for TypeScript
• Async stack traces supported
• console option controls console API redirection
• Runtime executable can be node, npm, yarn, pnpm

Java (java-debug-server)

• Requires classpath or module path configuration
• May use Eclipse JDT LS for code intelligence
• Main class specification required
• Can auto-compile .java files
• Supports JVM arguments (vmargs)

Code Reuse Checklist

Before writing new DAP code, check these locations:

1. Protocol Types: src/aidb/dap/protocol/types.py

   • Breakpoint, StackFrame, Variable, Source, Thread, Scope, etc.

2. Request/Response Classes: src/aidb/dap/protocol/requests.py, responses.py

   • All request and response types fully typed

3. Event Classes: src/aidb/dap/protocol/events.py

   • StoppedEvent, ThreadEvent, BreakpointEvent, etc.

4. Client Constants: src/aidb/dap/client/constants.py

   • CommandType, EventType, StopReason enums

5. Adapter Implementations:

   • Python: src/aidb/adapters/lang/python/python.py
   • JavaScript: src/aidb/adapters/lang/javascript/javascript.py
   • Java: src/aidb/adapters/lang/java/java.py

6. Session Management: src/aidb/session/

   • connector.py - Connection sequences
   • session_breakpoints.py - Breakpoint management
   • child_manager.py - Child session patterns

Common Pitfalls

1. Wrong Sequence Number

# ❌ Bad: reusing or hardcoding seq
request = InitializeRequest(seq=1, arguments=args)

# ✅ Good: always get fresh seq
seq = await client.get_next_seq()
request = InitializeRequest(seq=seq, arguments=args)

2. Missing Required Fields

# ❌ Bad: missing required fields
breakpoint = SourceBreakpoint(line=10)  # Error if other required fields

# ✅ Good: use protocol types correctly
from aidb.dap.protocol.types import SourceBreakpoint
breakpoint = SourceBreakpoint(line=10)  # All defaults handled

3. Ignoring Initialization Sequence

# ❌ Bad: launching before configuration
await client.connect()
await client.send_request(LaunchRequest(...))  # Will fail

# ✅ Good: follow proper sequence
await client.connect()
await client.send_request(InitializeRequest(...))
# Wait for initialized event
await client.send_request(SetBreakpointsRequest(...))
await client.send_request(ConfigurationDoneRequest(...))
await client.send_request(LaunchRequest(...))

4. Not Handling Language Differences

# ❌ Bad: assuming all adapters work the same
launch_config = {"program": "/path/to/file"}

# ✅ Good: use language-specific configuration
# Note: Launch arguments are implementation-specific dicts, not typed objects
# Adapters provide get_launch_configuration() that returns language-specific config

from aidb_common.constants import Language

if language == Language.PYTHON:
    # Python adapter provides debugpy-specific configuration
    launch_config = adapter.get_launch_configuration()
    # Typically includes: program, justMyCode, console, etc.
elif language == Language.JAVASCRIPT:
    # JavaScript adapter provides vscode-js-debug configuration
    launch_config = adapter.get_launch_configuration()
    # Typically includes: program, runtimeExecutable, console, etc.
elif language == Language.JAVA:
    # Java adapter provides java-debug-server configuration
    launch_config = adapter.get_launch_configuration()
    # Typically includes: mainClass, classpath, vmArgs, etc.

5. Creating Dictionaries Instead of Using Protocol Types

# ❌ Bad: manual dictionary construction
source = {"path": "/path/to/file.py"}  # Type unsafe, error prone

# ✅ Good: use protocol types
from aidb.dap.protocol.types import Source
source = Source(path="/path/to/file.py")  # Type safe, IDE support

When to Use This Skill

Invoke this skill ONLY when working directly with:

1. DAP Protocol Types - Creating/modifying protocol message classes in src/aidb/dap/protocol/
2. DAP Client - Implementing DAP client message handling in src/aidb/dap/client/
3. Protocol Specification - Understanding DAP spec, message flows, sequence numbers
4. Protocol-Level Debugging - Issues with DAP message encoding/decoding/parsing

DO NOT use for:

• Adapter implementation (use adapter-development skill instead)
• Breakpoint logic in adapters (use adapter-development skill)
• Session management (use adapter-development skill)
• General debugging questions (use adapter-development skill)

Rule of thumb: If you're working in src/aidb/dap/protocol/ or src/aidb/dap/client/, use this skill. Otherwise, use adapter-development.

Related Skills

When working with DAP protocol, you may also need:

• adapter-development - Adapters implement language-specific DAP patterns
• mcp-tools-development - MCP tools use DAP types for all debugging operations
• testing-strategy - Framework tests validate DAP flows end-to-end

Related Documentation

Internal Documentation:

• Architecture: docs/developer-guide/overview.md - Overall system architecture with DAP layer details
• Adapter Base: src/aidb/adapters/base/ - Base adapter classes
• Session Management: src/aidb/session/ - Session lifecycle
• Testing: src/tests/aidb/ - Example usage patterns

External References:

• DAP Specification: Microsoft DAP Spec - Official protocol specification

Verifying This Skill

To verify the code examples in this skill are current and accurate, check these files:

• Protocol definitions: src/aidb/dap/protocol/ - Authoritative source for all types
• Client implementation: src/aidb/dap/client/client.py - Client methods and signatures
• Real initialization flows: src/aidb/session/connector.py - Production initialization sequences
• Real breakpoint handling: src/aidb/session/session_breakpoints.py - Production breakpoint patterns
• Framework tests: Working examples of complete flows:
  • Python: src/tests/frameworks/python/pytest/e2e/test_pytest_debugging.py
  • JavaScript: src/tests/frameworks/javascript/jest/e2e/test_jest_debugging.py
  • Java: src/tests/frameworks/java/junit/e2e/test_junit_debugging.py

Example: Complete Debugging Flow

Note: This is a conceptual example showing the typical request sequence. For working examples, see the framework tests listed in "Verifying This Skill" above.

from aidb.dap.protocol import (
    InitializeRequest,
    LaunchRequest,
    SetBreakpointsRequest,
    ConfigurationDoneRequest,
    ContinueRequest,
    StackTraceRequest,
    ScopesRequest,
    VariablesRequest,
)
from aidb.dap.protocol.types import Source, SourceBreakpoint
from aidb.dap.protocol.bodies import (
    InitializeRequestArguments,
    SetBreakpointsArguments,
    StackTraceArguments,
    ScopesArguments,
    VariablesArguments,
    ContinueArguments,
)

# 1. Initialize
seq = await client.get_next_seq()
init_response = await client.send_request(
    InitializeRequest(
        seq=seq,
        arguments=InitializeRequestArguments(
            clientID="aidb",
            adapterID="python",
            linesStartAt1=True,
            columnsStartAt1=True,
        )
    )
)

# 2. Wait for initialized event
await client.wait_for_event("initialized")

# 3. Set breakpoints
seq = await client.get_next_seq()
bp_response = await client.send_request(
    SetBreakpointsRequest(
        seq=seq,
        arguments=SetBreakpointsArguments(
            source=Source(path="/path/to/file.py"),
            breakpoints=[SourceBreakpoint(line=10)]
        )
    )
)

# 4. Configuration done
seq = await client.get_next_seq()
await client.send_request(ConfigurationDoneRequest(seq=seq))

# 5. Launch
seq = await client.get_next_seq()
launch_response = await client.send_request(
    LaunchRequest(seq=seq, arguments=launch_args)
)

# 6. Wait for stopped event
await client.wait_for_event(EventType.STOPPED.value)
thread_id = client.state.current_thread_id

# 7. Get stack trace
seq = await client.get_next_seq()
stack_response = await client.send_request(
    StackTraceRequest(
        seq=seq,
        arguments=StackTraceArguments(threadId=thread_id)
    )
)
frame_id = stack_response.body.stackFrames[0].id

# 8. Get scopes
seq = await client.get_next_seq()
scopes_response = await client.send_request(
    ScopesRequest(
        seq=seq,
        arguments=ScopesArguments(frameId=frame_id)
    )
)
vars_ref = scopes_response.body.scopes[0].variablesReference

# 9. Get variables
seq = await client.get_next_seq()
vars_response = await client.send_request(
    VariablesRequest(
        seq=seq,
        arguments=VariablesArguments(variablesReference=vars_ref)
    )
)

# 10. Continue execution
seq = await client.get_next_seq()
await client.send_request(
    ContinueRequest(
        seq=seq,
        arguments=ContinueArguments(threadId=thread_id)
    )
)

Summary

This skill provides comprehensive DAP protocol guidance for AIDB development. Always:

1. Use protocol types from src/aidb/dap/protocol/
2. Check adapter implementations for patterns
3. Follow initialization sequences
4. Handle language-specific differences
5. Use constants from client/constants.py
6. Refer to resource files for detailed guidance

For deep dives into specific operations, see the resource files listed above.