llmdbg/README.md

llmdbg

A scriptable, stateful debugger REPL with JavaScript as the interface language. Built from the spec in SPEC.md. This repo holds the v0.1–v0.8 implementation: enough to actually drive a debugged process from an agent harness with breakpoints, disassembly, symbol-aware (demangled) addresses, event listeners, and step-over.

The premise: existing debuggers optimise for humans at a terminal. An LLM agent is a different user — it wants terse output it can parse, lazy state access, and a scripting layer rich enough that "describe what you want to see each step" is the natural interface. The full motivation is in SPEC.md.

Status

Version	What landed
v0.1	Spawn, step, continue, basic state (pc/sp/regs/memory), persistent ctx, print(), JS prelude loaded via include_str!
v0.2	prev register snapshot before each resume; refactored register accessors
v0.3	ELF symbol parsing of main exe; sym(addr) / addr(name) / symbols(); addrstr / here prelude helpers
v0.4	INT3 software breakpoints with by-name/by-id ops; auto disarm-step-rearm; RIP rewind on hit
v0.5	x86-64 disassembly via iced-x86; read_mem_pristine() overlays original bytes through active INT3s; branch targets get symbolised
v0.6	state.stack; until(loc); finish(); show.{disasm,bp,regs} prelude helpers
v0.7	Event-listener system: addEventListener('step'|'breakpoint'|'signal'|'exit', ...), removeEventListener, clearListeners, listeners(); step/cont fire listeners per stop with {state, prev, stop_reason, ...} events; native steppers moved to __step_native/__cont_native
v0.8	Step-over: next(n) and trace(from, to, {over}). Rust: symbol demangling (addr("switch_to_scheduler") resolves by demangled path or unique last component; sym() returns demangled names), disasm records gain .len and .is_call. Prelude: state.insn, stackContains/stackDistance/region, watch(specs), fmt() (BigInt-safe), step(n, {summary})

Each vN corresponds to one git commit. See git log --oneline.

Not yet implemented

The spec calls for these; they're deliberately deferred:

• attach(pid) — only spawn works today.
• Hardware watchpoints. (The watchpoint event type exists in the listener registry but never fires until hardware watchpoints land.)
• Source-level debugging via DWARF (gimli).
• Multi-threaded targets; shared-library symbol resolution.
• Browser visualisation / DOM API.
• Conditional breakpoints. (Expressible as a guard inside a breakpoint listener — see the idiom below; native --condition support is still deferred.)
• Reverse execution.

A basic step(n, {summary}) batch-step mode landed in v0.8 (first/last/count instead of N listener fires); the SPEC's fuller "interesting events" summary is still open. Symbol demangling also landed in v0.8: addr("name") resolves by demangled path or unique last component, and sym() returns demangled names. The event-listener system landed in v0.7 — see the status table.

The complete "what not yet" list is in SPEC.md.

Build

Requires a Linux x86-64 host with ptrace permitted (no yama ptrace_scope restriction in the way) and a recent stable Rust toolchain (1.87+).

cargo build              # debug
cargo build --release    # ~3-5x faster

QuickJS builds via rquickjs-sys's pre-generated bindings; no libclang or bindgen needed on the supported platforms.

Run

The binary is a daemon. It reads JS scripts from stdin and writes results to stdout, with sentinels separating turns:

$ ./target/debug/llmdbg <<'EOF'
spawn("/tmp/testprog")
bp.set("main")
cont()
show.disasm(5)
---END---
EOF

Protocol:

• Read lines until a line containing exactly ---END---.
• Evaluate the accumulated buffer as one JS script in the persistent context.
• Print: any print() output, then the final expression's value (when not undefined), or error: ... if the eval threw.
• Print ---DONE--- and flush.
• Repeat.
• EOF on stdin exits cleanly. If a target is still alive, it gets SIGKILL'd.

Quick tour

A representative session against a small C program:

spawn("/tmp/testprog")
bp.set("main")
bp.set("add", "add_bp")
show.bp()
//   #1  0x55ca2862c1e8 (main)  hits=0  enabled
//   #2 "add_bp"  0x55ca2862c149 (add)  hits=0  enabled
---END---

cont()                                     // -> "breakpoint:1"
here()                                     // -> 0x55ca2862c1e8 (main)
show.disasm(5)
//   0x55ca2862c1e8  f30f1efa              endbr64
//   0x55ca2862c1ec  55                    push rbp
//   ...
---END---

cont()                                     // -> "breakpoint:2"
here()                                     // -> 0x55ca2862c149 (add)
show.regs(["rip","rdi","rsi"])             // (rdi, rsi are the first two args)
//   rip=0x55... rdi=0x5 rsi=0x1
---END---

step(5)
finish()                                   // -> "breakpoint:N", back at caller
state.registers.rax & 0xffffffffn          // -> 0x6 (the eax return value)
---END---

cont()                                     // -> "exited:0"
---END---

The native surface

Everything below is installed in the global scope by the Rust side. The JS prelude (src/prelude.js) adds the helpers listed at the bottom.

// Process control
spawn(path, ...args)         // -> { pid, status: "stopped_at_entry" }
step(n = 1)                  // -> stop-reason string
cont()                       // -> stop-reason string  (NOT `continue` — JS keyword)

// Stop reasons (returned as strings):
//   "step", "breakpoint:N", "signal:SIGSEGV", "exited:0", "killed:SIGKILL"

// Live state (each property re-reads via ptrace on access)
state.pc                     // -> BigInt
state.sp                     // -> BigInt
state.registers              // -> { rax, rbx, ..., r15, eflags } all BigInt
state.memory(addr)           // -> { u8(), u32(), u64(), i64(), bytes(n) }
state.disasm(n = 8)          // -> [{addr, bytes, text, target?, target_sym?}]
state.stack                  // -> { top, usable_base, guard_size }

// Snapshot before the most recent step/cont — same shape as state for regs.
// Throws if no step has happened yet.
prev.pc / prev.sp / prev.registers

// Symbols (main exe only; shared libs deferred)
sym(addr)                    // -> "name+0xN" | "name" | null
addr(name)                   // -> BigInt | null
symbols()                    // -> { count, load_base, path }
disasm(addr, n = 8)          // -> same shape as state.disasm

// Breakpoints (`breakpoint` and `bp` are the same object)
bp.set(addr_or_symbol, name?)  // -> id
bp.remove(id_or_name)
bp.list()                      // -> [{id, addr, name, hits, enabled}]

// User scratchpad (persistent across all evals)
ctx.something = whatever

Prelude (src/prelude.js)

Pure JS, loaded last so it can reference the natives. Edit it freely; it gets re-embedded into the binary on every cargo build via include_str!.

hex(v)              // -> "0x..." for Number or BigInt
unhex(s)            // -> BigInt (handles "0x", case, sign)
dump(label, v)      // -> print one terse "label\tvalue" line
repr(v)             // -> string form; hex for numerics, JSON for objects
addrstr(v)          // -> "0xN (sym+0xoff)" when sym is known, else "0xN"
here(label?)        // -> print addrstr(state.pc), optionally labelled

until(loc)          // one-shot bp at addr-or-symbol, cont, cleanup
finish()            // until([rbp+8]) — assumes frame pointer

next(n=1)           // step OVER calls (gdb `next`): bp at ret addr, cont
trace(from,to,opts) // run to `from`, step (opts.over → over calls) to `to`,
                    //   capturing per-step records. opts: {over, max, capture,
                    //   print, range:[lo,hi]}. -> {steps, reason, trace:[...]}
watch(specs)        // register a 'step' listener printing named exprs each
                    //   step; specs = {label: e => value}. -> handler
fmt(v)              // BigInt-safe stringify (never throws on nested BigInt)

state.insn          // disasm record at pc: {addr,bytes,len,text,is_call,...}
stackContains(addr) // is addr within [usable_base, top)?
stackDistance(addr) // top - addr (how deep into the stack)
region(addr)        // "stack" | "text:<sym>" | "0x.." — which mapping

show.disasm(n=8, [at])
show.bp()
show.regs([keys])

step(n, {summary:true})   // step n, print only first/last/count (no per-step
                          //   listeners) — for large N where you just want
                          //   the landing site

// Event listeners (v0.7). Handlers fire on each stop during step()/cont().
addEventListener(type, handler)   // type: 'step'|'breakpoint'|'signal'|'exit'
removeEventListener(type, handler)
clearListeners([type])            // drop one type, or all if omitted
listeners()                       // -> { step: n, breakpoint: n, ... } counts

Event listeners

The event object passed to each handler:

e.state          // live state (re-reads via ptrace), same as the `state` global
e.prev           // pre-resume snapshot, or null on the very first event
e.stop_reason    // "step" | "breakpoint:N" | "signal:SIGSEGV" | "exited:0" | ...
e.breakpoint_id  // number — only on 'breakpoint' events
e.signal         // string — only on 'signal' events
e.exit_code      // number — only on 'exit' events

step(n) single-steps one instruction at a time, firing listeners after each stop; cont() fires after the stop it lands on. When no listeners are registered, both take the native fast path and pay nothing. Handler exceptions are caught and printed, so one bad listener won't abort a long step loop. A worked example against smarm's context switch is in examples/smarm_ctx_switch.js.

Step-over (next) and trace (v0.8)

next(n) steps over calls: if the instruction at pc is a call, it sets a one-shot breakpoint at the return address (pc + insn.len), cont()s to it, and cleans up; otherwise it single-steps. A stepped-over call fires the step listener exactly once, so it reads as one logical step.

Caveat — calls that don't return to pc+len. A call that swaps rsp and rets into a different stack (the context-switch shims themselves, or a longjmp) never returns to the address right after the call. next does not hang on this: if the cont() lands on anything other than its own return breakpoint (a different bp, a signal, exit, or simply not coming back), it cleans up, dispatches the real event, and stops, returning that reason. The rule of thumb: use plain step() to walk through a switch shim instruction by instruction; use next() to skip the ordinary helper calls (TLS accessors etc.) that step() would dive into. examples/smarm_ctx_switch_next.js shows both, tracing a full switch_to_scheduler in 16 readable lines.

trace(from, to, {over, range, capture, print, max}) collapses the common "run to A, step (over calls) to B, log each step" pattern into one call. With range: [lo, hi] it stops when pc leaves a half-open address range — handy for "trace until we leave this shim" without knowing the exact exit address. It drives execution with the native steppers directly, so it neither fires nor depends on user listeners.

Conditional breakpoints (idiom, no new API)

A breakpoint listener is the guard. Inspect e.state and decide whether to act; to auto-resume until a condition holds, loop cont():

const myBp = bp.set("worker_loop");
function runUntilRdi(want) {
  while (true) {
    const r = cont();
    if (!r.startsWith("breakpoint:")) return r;     // signal/exit — stop
    if (state.registers.rdi === want) return r;     // condition met
    // else: fall through and cont() again
  }
}
runUntilRdi(0x10n);

BigInt ergonomics

All 64-bit values (state.pc, addr(...), anything address-sized) are BigInt. Two things bite:

• JSON.stringify throws on a raw BigInt. Use fmt() / repr() / dump(), which route BigInt through a "0x.." replacer, instead of JSON.stringify on any object that might hold addresses.
• Mixing BigInt with Number throws (pc + 8 is an error if pc is BigInt). Suffix literals with n (pc + 8n) or wrap with BigInt(...). The helpers that take addresses (stackContains, stackDistance, region, trace's range) coerce via BigInt(...) for you, so a Number offset is fine there.

Architecture

src/
├── main.rs        ─ stdin read loop, ---END--- framing, SIGKILL on exit
├── target.rs      ─ ptrace child management: spawn, step, cont, regs,
│                    process_vm_readv, breakpoint patching (read-byte+poke-byte
│                    via PEEKDATA/POKEDATA word RMW)
├── symbols.rs     ─ ELF parsing via `object`; PIE load-base from /proc/maps;
│                    StackRegion from /proc/maps
├── breakpoint.rs  ─ BreakpointSet storage (by id, by addr, by name)
├── disasm.rs      ─ thin wrapper around iced-x86 FastFormatter; emits records
│                    with branch_target for caller symbolisation
├── js.rs          ─ Runtime + Context + Rc<RefCell<Option<Target>>>;
│                    installs all native globals, then evals prelude.js
└── prelude.js     ─ embedded at compile time

A few decisions worth knowing

• BigInt for u64. A JS Number above 2⁵³ loses precision, which is exactly the range we live in. state.pc, addr(...), anything 64-bit goes in and out as BigInt. state.memory(addr).u8() and .u32() stay as Number.
• Lazy state. Every access to state.pc does a fresh PTRACE_GETREGS; every state.memory(...) does a fresh process_vm_readv. A script that touches three fields makes three syscalls, not 20. Worth it for scripts; the cache would just be a footgun once you have multi-threaded targets.
• continue() doesn't exist. continue is a reserved keyword in JS, so the natural name is a parse error. The spec's continue() is cont() here.
• Single QuickJS context for the daemon's lifetime. ctx (the JS scratchpad), registered listeners (when they land), and any user-defined helpers all persist. Only resets on daemon restart.
• Read-modify-write breakpoint patching. ptrace::write writes a full word. We ptrace::read first, modify byte 0, write the word back. The other seven bytes stay unchanged because we just read them.
• read_mem_pristine. Used by the disassembler so it sees the original byte, not 0xCC, at active breakpoints. Without this, a disasm over a bp'd function shows int3; ... at the first byte.
• PIE load base. Computed as mapping_base - mapping_file_offset of the first mapping of the executable in /proc/<pid>/maps. Earlier versions used the first executable mapping and dropped the file offset, which is wrong on toolchains that split read-only header pages.

Caveats

• Linux x86-64 only. No multi-arch, no other OSes.
• Single-threaded debuggees. A pthread'd binary will behave oddly the moment a non-main thread does anything.
• Symbols only cover the main executable. Shared-library functions (e.g. printf, malloc) resolve to null until ld.so awareness lands.
• finish() assumes a frame pointer (-fno-omit-frame-pointer, which is the default on most distros). It will throw if rbp == 0.
• The sandbox guard-page detection in state.stack.guard_size returns 0 on Linux configurations where the kernel handles guard implicitly without an anonymous ---p mapping below the stack. That's most modern setups.
• No attach(pid) yet — only spawn.

License

Personal experiment, no license declared. Treat as all-rights-reserved by the author until otherwise noted.