Proposal: Breakpoint management (set, unset, mute) via ACP

[bartvanhoutte]

Motivation

ACP currently has no way for an agent to manage breakpoints in the editor's debugger. As agents take on more autonomous debugging workflows — running code, observing failures, iterating on fixes — the ability to set, unset, and mute breakpoints becomes a natural and important capability.

The closest prior art is the Debug Adapter Protocol (DAP), which defines setBreakpoints, setFunctionBreakpoints, and setExceptionBreakpoints requests. Rather than reinventing that design, ACP could expose a lightweight breakpoint management surface that complements DAP (or delegates to it in editors that already host a DAP client).

---

Proposed capabilities

1. setBreakpoints (source breakpoints)

An agent sends a list of breakpoints for a single source file. Following DAP's semantics, this replaces the full set of breakpoints for that file (not incremental), so a simple adapter implementation can clear-and-reset.

Request (agent → client):

{
  "method": "setBreakpoints",
  "params": {
    "source": { "path": "/workspace/src/server.ts" },
    "breakpoints": [
      { "line": 42 },
      { "line": 87, "condition": "req.status === 500" },
      { "line": 120, "logMessage": "reached handler: {req.method}" },
      { "line": 55, "enabled": false }
    ]
  }
}

Key fields per breakpoint:

• line (required) — 1-based line number
• column (optional) — for inline breakpoints
• condition (optional) — expression that must be truthy to pause
• logMessage (optional) — log point: emit message instead of pausing (interpolated with {expr})
• enabled (optional, default true) — false means the breakpoint is registered but muted

Response (client → agent):

{
  "breakpoints": [
    { "id": 1, "verified": true,  "line": 42 },
    { "id": 2, "verified": true,  "line": 87 },
    { "id": 3, "verified": true,  "line": 120 },
    { "id": 4, "verified": false, "line": 55, "message": "Location not yet loaded" }
  ]
}

• verified: false indicates the editor could not confirm the breakpoint (e.g. source not yet compiled). The client should send a breakpointChanged notification when/if the state later resolves.

---

2. setFunctionBreakpoints

Break when a named function is entered, regardless of source location. Useful for agents that know a function name but are navigating unfamiliar code.

{
  "method": "setFunctionBreakpoints",
  "params": {
    "breakpoints": [
      { "name": "handleRequest" },
      { "name": "DatabasePool::connect", "condition": "retries > 3" }
    ]
  }
}

---

3. setExceptionBreakpoints

Control whether execution pauses on thrown or caught exceptions.

{
  "method": "setExceptionBreakpoints",
  "params": {
    "filters": ["uncaught"],
    "filterOptions": [
      { "filterId": "caught", "condition": "error instanceof TypeError" }
    ]
  }
}

Available filter IDs would be declared by the client in its capabilities during initialize.

---

4. breakpointChanged notification (client → agent)

An unsolicited notification the client sends when a breakpoint's state changes asynchronously (e.g. after hot-reload, source map resolution, or a recompile).

{
  "method": "breakpointChanged",
  "params": {
    "reason": "changed",
    "breakpoint": { "id": 4, "verified": true, "line": 55 }
  }
}

---

Design notes

• Muting vs. removing: A breakpoint with enabled: false is retained in the editor UI (typically shown greyed-out) but does not pause execution. This is distinct from removing it entirely. Passing an empty breakpoints array for a source clears all breakpoints for that file.
• Capability gating: Editors that don't support breakpoint management simply omit the relevant capability flags during initialize. Agents check capabilities before issuing these requests.
• DAP interoperability: Editors already running a DAP session can implement these ACP messages by forwarding to their existing DAP client, making adoption low-cost for editors like VS Code, Neovim, and Zed.
• Scope: This proposal intentionally omits data/watchpoint breakpoints and instruction-level breakpoints, which are lower-level than the typical agent use case and can be addressed in a follow-up.

---

Open questions

1. Should breakpoint IDs be assigned by the client (as in DAP) or by the agent?
2. Should setBreakpoints be per-file (replace semantics, as in DAP) or should there be separate addBreakpoint / removeBreakpoint messages with delta semantics?
3. Is there appetite to align this closely with DAP message shapes, or should ACP define its own simplified surface?

Happy to draft an RFD if there's interest.