agent-dbg 0.1.8 → 0.2.0

package/.claude/skills/agent-dbg/SKILL.md

@@ -1,26 +1,42 @@
 ---
 name: agent-dbg
 description: >
-  Debug Node.js/TypeScript/JavaScript applications using the agent-dbg CLI debugger.
+  Debug applications using the agent-dbg CLI debugger.
+  Supports Node.js (V8/CDP), Bun (WebKit/JSC), and native code via LLDB (DAP).
   Use when: (1) investigating runtime bugs by stepping through code, (2) inspecting
   variable values at specific execution points, (3) setting breakpoints and conditional
   breakpoints, (4) evaluating expressions in a paused context, (5) hot-patching code
-  without restarting, (6) debugging test failures by attaching to a running process,
-  (7) any task where understanding runtime behavior requires a debugger.
+  without restarting (JS/TS), (6) debugging test failures by attaching to a running process,
+  (7) debugging C/C++/Rust/Swift with LLDB, (8) any task where understanding runtime
+  behavior requires a debugger.
   Triggers: "debug this", "set a breakpoint", "step through", "inspect variables",
-  "why is this value wrong", "trace execution", "attach debugger", "runtime error".
+  "why is this value wrong", "trace execution", "attach debugger", "runtime error",
+  "segfault", "core dump".
 ---
 
 # agent-dbg Debugger
 
-`agent-dbg` is a CLI debugger for Node.js wrapping the V8 Inspector (CDP). It uses short `@refs` for all entities -- use them instead of long IDs.
+`agent-dbg` is a CLI debugger that supports **Node.js** (V8/CDP), **Bun** (WebKit/JSC), and **native code** (C/C++/Rust/Swift via LLDB/DAP). It uses short `@refs` for all entities -- use them instead of long IDs.
+
+## Supported Runtimes
+
+| Runtime | Language | Launch example |
+|---------|----------|----------------|
+| Node.js | JavaScript | `agent-dbg launch --brk node app.js` |
+| tsx / ts-node | TypeScript | `agent-dbg launch --brk tsx src/app.ts` |
+| Bun | JavaScript / TypeScript | `agent-dbg launch --brk bun app.ts` |
+| LLDB | C / C++ / Rust / Swift | `agent-dbg launch --brk --runtime lldb ./program` |
+
+The runtime is auto-detected from the launch command for JS runtimes. For native code, use `--runtime lldb`.
 
 ## Core Debug Loop
 
 ```bash
 # 1. Launch with breakpoint at first line
 agent-dbg launch --brk node app.js
-# Or attach to a running node process with the --inspect flag
+# Or: agent-dbg launch --brk bun app.ts
+# Or: agent-dbg launch --brk --runtime lldb ./my_program
+# Or attach to a running process with the --inspect flag
 agent-dbg attach 9229
 
 # 2. Set breakpoints at suspicious locations
@@ -35,10 +51,10 @@ agent-dbg state
 
 # 5. Drill into values
 agent-dbg props @v1              # expand object
-agent-dbg props @v1 --depth 3    # expand nested 3 levels
-agent-dbg eval "items.filter(x => x.active)"
+agent-dbg props @v1 --depth 3   # expand nested 3 levels
+agent-dbg eval "x + 1"
 
-# 6. Fix and verify
+# 6. Fix and verify (JS/TS only)
 agent-dbg set count 0            # change variable
 agent-dbg hotpatch src/utils.js  # live-edit (reads file from disk)
 agent-dbg continue               # verify fix
@@ -58,12 +74,24 @@ agent-dbg step over                               # advance one line
 agent-dbg state                                   # see new state
 ```
 
+### Native code debugging (C/C++/Rust)
+```bash
+agent-dbg launch --brk --runtime lldb ./my_program
+agent-dbg break main.c:42
+agent-dbg break-fn main                          # function breakpoint (DAP only)
+agent-dbg continue
+agent-dbg vars                                    # inspect locals
+agent-dbg eval "array[i]"                         # evaluate expression
+agent-dbg step into                               # step into function
+```
+
 ### Attach to running/test process
 ```bash
-# Start node with inspector
+# Start with inspector enabled
 node --inspect app.js
-# Or attach by PID
-agent-dbg attach 12345
+# Or: bun --inspect app.ts
+# Then attach
+agent-dbg attach 9229
 agent-dbg state
 ```
 
@@ -101,6 +129,7 @@ Refs `@v`/`@f` reset on each pause. `BP#`/`LP#` persist until removed.
 
 - `--json` -- machine-readable JSON output on any command
 - `--session NAME` -- target a specific session (default: "default")
+- `--runtime NAME` -- select debug adapter (e.g. `lldb` for native code)
 - `--generated` -- bypass source maps, show compiled JS (on state/source/stack)
 
 ## Command Reference
@@ -111,8 +140,9 @@ See [references/commands.md](references/commands.md) for full command details an
 
 - `agent-dbg state` after stepping always shows location + source + locals -- usually enough context
 - `agent-dbg state -c` for source only, `-v` for vars only, `-s` for stack only -- save tokens
-- `agent-dbg eval` supports `await` -- useful for async inspection
+- `agent-dbg eval` supports `await` -- useful for async inspection (JS/TS)
 - `agent-dbg blackbox "node_modules/**"` -- skip stepping into dependencies
-- `agent-dbg hotpatch file` reads the file from disk -- edit the file first, then hotpatch
+- `agent-dbg hotpatch file` reads the file from disk -- edit the file first, then hotpatch (JS/TS only)
+- `agent-dbg break-fn funcName` -- function breakpoints work with DAP runtimes (LLDB)
 - Execution commands (`continue`, `step`, `pause`, `run-to`) auto-return status
 - `agent-dbg stop` kills the debugged process and daemon

package/.claude/skills/agent-dbg/references/commands.md

@@ -14,6 +14,7 @@
 
 ```bash
 agent-dbg launch [--brk] <command...>     # Start + attach debugger (--brk pauses at first line)
+agent-dbg launch --brk --runtime lldb ./program  # Native debugging via LLDB (DAP)
 agent-dbg attach <pid|ws-url|port>        # Attach to running process
 agent-dbg stop                            # Kill process + daemon
 agent-dbg sessions [--cleanup]            # List active sessions
@@ -125,6 +126,8 @@ agent-dbg break-toggle all                # Disable/enable all
 agent-dbg breakable src/app.ts:10-50      # List valid breakpoint locations
 agent-dbg logpoint src/app.ts:20 "x=${x}" # Log without pausing
 agent-dbg logpoint src/app.ts:20 "x=${x}" --condition "x > 0"
+agent-dbg break-fn <name>                  # Function breakpoint (DAP runtimes only)
+agent-dbg break-fn main --condition "argc > 1"
 agent-dbg catch all                       # Pause on all exceptions
 agent-dbg catch uncaught                  # Pause on uncaught only
 agent-dbg catch none                      # Don't pause on exceptions
@@ -167,6 +170,7 @@ agent-dbg sourcemap --disable             # Disable resolution globally
 
 ```bash
 --session NAME                       # Target session (default: "default")
+--runtime NAME                       # Debug adapter: lldb, codelldb, etc. (for native debugging)
 --json                               # JSON output
 --color                              # Enable ANSI colors
 --help-agent                         # LLM-optimized reference card

package/README.md

@@ -1,16 +1,32 @@
 # agent-dbg
 
-Node.js debugger CLI built for AI agents. Fast, token-efficient, no fluff.
+Debugger CLI built for AI agents. Fast, token-efficient, no fluff.
 
 **Why?** Agents waste tokens on print-debugging. A real debugger gives precise state inspection in minimal output — variables, stack, breakpoints — all via short `@ref` handles.
 
+Inspired by Vercel's [agent-browser](https://github.com/vercel-labs/agent-browser) CLI — the same `@ref` concept, applied to debugging instead of browsing.
+
+## Supported Runtimes & Languages
+
+| Runtime | Language | Status | Protocol |
+|---------|----------|--------|----------|
+| Node.js | JavaScript | Supported | V8 Inspector (CDP) |
+| Node.js + tsx/ts-node | TypeScript | Supported | V8 Inspector (CDP) + Source Maps |
+| Bun | JavaScript / TypeScript | Supported | WebKit Inspector (JSC) |
+| LLDB | C / C++ / Rust / Swift | Supported | DAP (Debug Adapter Protocol) |
+| Deno | JavaScript / TypeScript | Planned | V8 Inspector (CDP) |
+| Python (debugpy) | Python | Planned | DAP |
+| Go (delve) | Go | Planned | DAP |
+
+agent-dbg auto-detects the runtime from the launch command and uses the appropriate protocol adapter. For native languages, use `--runtime lldb` to select the DAP adapter.
+
 ## Install
 
 Requires [Bun](https://bun.sh).
 
 ```bash
 bun install --global agent-dbg
-npx skills add theodo-group/agent-dbg # Install skills
+npx skills add theodo-group/agent-dbg # Install Claude Code skill
 ```
 
 ## Example
@@ -23,17 +39,17 @@ Paused at ./src/app.ts:0:1
 BP#1 set at src/app.ts:19
 
 > agent-dbg continue
-⏸ Paused at ./src/app.ts:19:21 (other)
+Paused at ./src/app.ts:19:21 (other)
 
 Source:
-   16│
-   17│const alice: Person = { name: "Alice", age: 30 };
-   18│const greeting: string = greet(alice);
- → 19│const sum: number = add(2, 3);
+   16|
+   17|const alice: Person = { name: "Alice", age: 30 };
+   18|const greeting: string = greet(alice);
+ > 19|const sum: number = add(2, 3);
                           ^
-   20│console.log(greeting);
-   21│console.log("Sum:", sum);
-   22│
+   20|console.log(greeting);
+   21|console.log("Sum:", sum);
+   22|
 
 Locals:
 @v1  greet     Function greet(person)
@@ -51,33 +67,30 @@ Breakpoints: 1 active
 ## Usage
 
 ```bash
+# Node.js
 agent-dbg launch --brk node app.js
-# Session "default" started (pid 12345)
-# Paused at app.js:1:1
 
-agent-dbg break src/handler.ts:42
-# BP#1 src/handler.ts:42
+# TypeScript (via tsx)
+agent-dbg launch --brk tsx src/app.ts
 
-agent-dbg continue
-# Paused at src/handler.ts:42:5 (breakpoint)
+# Bun
+agent-dbg launch --brk bun app.ts
 
-agent-dbg vars
-# @v1  x      42
-# @v2  name   "alice"
-# @v3  opts   {timeout: 3000}
+# C/C++ (via LLDB)
+agent-dbg launch --brk --runtime lldb ./my_program
 
-agent-dbg props @v3
-# @o1  timeout  3000
+# Attach to a running process (any runtime with --inspect)
+agent-dbg attach 9229
 
+# Debug loop
+agent-dbg break src/handler.ts:42
+agent-dbg continue
+agent-dbg vars
+agent-dbg props @v3
 agent-dbg eval "x + 1"
-# 43
-
 agent-dbg step over
-# Paused at src/handler.ts:43:5 (step)
-
 agent-dbg set @v1 100
-# @v1 changed to 100
-
+agent-dbg hotpatch src/handler.ts   # live-edit from disk (JS/TS only)
 agent-dbg stop
 ```
 
@@ -88,8 +101,31 @@ agent-dbg stop
 | Session | `launch`, `attach`, `stop`, `status`, `sessions` |
 | Execution | `continue`, `step [over\|into\|out]`, `pause`, `run-to`, `restart-frame` |
 | Inspection | `state`, `vars`, `stack`, `eval`, `props`, `source`, `scripts`, `search`, `console`, `exceptions` |
-| Breakpoints | `break`, `break-rm`, `break-ls`, `break-toggle`, `breakable`, `logpoint`, `catch` |
+| Breakpoints | `break`, `break-rm`, `break-ls`, `break-toggle`, `breakable`, `logpoint`, `catch`, `break-fn` (DAP only) |
 | Mutation | `set`, `set-return`, `hotpatch` |
 | Blackbox | `blackbox`, `blackbox-ls`, `blackbox-rm` |
 
 Run `agent-dbg --help` or `agent-dbg --help-agent` for the full reference.
+
+## Architecture
+
+```
+CLI (stateless)  -->  Unix socket IPC  -->  Daemon (per session)
+                                              |
+                                     DebugSession / DapSession
+                                       /                \
+                              CDP path (JS)          DAP path (native)
+                                 |                       |
+                           RuntimeAdapter            DapClient
+                            /         \            (stdin/stdout)
+                      NodeAdapter    BunAdapter         |
+                      (CDP/V8)    (WebKit/JSC)     lldb-dap / etc.
+                            \         /
+                          CdpClient (WebSocket)
+                                 |
+                          V8/JSC Inspector
+```
+
+The daemon manages two session types:
+- **DebugSession** (CDP) — for JavaScript runtimes (Node.js, Bun). Uses `RuntimeAdapter` to handle protocol differences between V8 and JSC.
+- **DapSession** (DAP) — for native debuggers (LLDB, etc.). Communicates with a debug adapter over stdin/stdout using the Debug Adapter Protocol.