Drive rdbg from an autonomous agent.

What rdbg gives an agent

• A persistent JSON pipe to a daemon driving a target via the Win32 Debugging API. Win64 (rdbgd64.exe) and Win32 (rdbgd32.exe) ship in parallel; the bridge auto-switches per launch based on the target's PE machine type.
• Commands to launch, set breakpoints (SW + HW), step, read memory and registers, and inspect Delphi objects — full RTTI walk including extended-RTTI public/private/protected, record fields, dyn-arrays, strings.
• Async events drained via the events tool: paused, breakpoint_hit, exception, debug_output, exit_process, create_process, load_dll. Every drain response includes idle_since_last_event_ms so you can tell "still chewing" from "wire is silent because something broke" without sending a probe RPC.
• Multi-conn daemon, multi-session: paused sessions outlive client disconnects (zombies). status + bind_session let an agent adopt a session left by another client; release_session hands one back. interrupt mid-runs a target into a paused, reason:"interrupt" event for inspection without killing it; detach leaves the target running.
• HWND enumeration + input injection — list_windows, post_message, send_keys, set_text_field (cross-process WM_SETTEXT, no focus-loss races), click_at, send_input (raw HID), capture_window, screenshot_desktop (auto-downscales for 4K) — so an agent can drive a VCL UI without a human at the keyboard. VCL discovery: get_main_form, find_vcl_for_hwnd, enumerate_vcl_tree.
• Input-spy mode — the inverse of input injection. spy action:"start" turns on a low-level recorder that emits an {"event":"input", ...} for every mouse/keyboard event the user performs against the debuggee, tagged with the VCL component path (Form1.pnlBottom.btnOK). A human reproduces a bug once; the agent persists the JSONL and replays it on every iteration. See R5c — Bug-reproduction handoff.
• Caller-frame inspection — get_registers frame_idx=N walks via the .pdata/.xdata unwinder on Win64 (FPO_DATA on Win32) to expose the up-stack frame's CONTEXT, with a valid_registers bitmask listing which slots are real (volatiles are never preserved). Step Over pre-arms a temp BP for direct/indirect/tail-call shapes, surfaced as prearmed_kind on the response.
• DLL symbols beyond the launched exe — frame addresses inside kernel32, ntdll, etc. resolve to module!Symbol+offset via Microsoft public PDBs auto-fetched on first use; set_breakpoint accepts the same module!symbol form (e.g. kernelbase!RaiseException).
• Static-analysis surface via 13 lsp_* tools backed by Embarcadero's DelphiLSP.exe. Go-to-definition / hover / completion / workspace-symbol-search / diagnostics — capability-gated per Delphi version. Useful before launching the debugger, or to find the symbol you want to break on without grepping.

This is enough for an agent to find the suspected handler with LSP, set a BP there, reproduce a bug by driving the UI, and inspect the in-process Delphi state at the moment things go wrong — without ever rebuilding the target.

Connecting

The daemon (rdbgd64.exe for Win64 targets, rdbgd32.exe for Win32) runs on the Windows host where your debuggee lives. The agent talks to it from anywhere over TCP — locally, across an SSH tunnel, or via the bundled MCP bridge.

# On the Windows host, start the daemon listening.
rdbgd64.exe --listen 127.0.0.1:5902

# From the agent's host: open a JSON-pipe REPL. Each line of stdout
# is one wire response or event; each line of stdin is one request.
# EOF on stdin sends `shutdown` and closes the daemon cleanly.
rdbgc.exe repl 127.0.0.1:5902

Mental model: pause-loop semantics

Every interaction the agent has is mediated by pause state:

RUNNING  ── exception/BP/launch ──▶  PAUSED  ── continue/step ──▶  RUNNING
                                       │
                            other commands here

While paused, the agent can call any inspection method and the continue / step_* / run_to / detach methods.

While running, the wire only returns event messages until the next pause. Sending an inspection method while running gets you either error: target_running or — depending on the method — silence until the next event.

Draining async events

Async daemon notifications (create_process, paused, breakpoint_hit, exception, debug_output, exit_process, load_dll, ...) are queued by the bridge and exposed via the events tool, which has no daemon round-trip — it just returns whatever's in the bridge's local buffer. Pattern:

// Pause-blocking wait: poll until something interesting arrives.
{"method":"events","params":{"timeout_ms":5000,"filter":["paused","exception","exit_process"]}}

// Non-blocking peek: timeout_ms:0 returns immediately with whatever's queued.
{"method":"events","params":{"timeout_ms":0}}

Every response carries idle_since_last_event_ms — how long the bridge has been receiving nothing from the daemon. This is the difference between "target is genuinely idle, waiting on a UI action you should drive" (large value) and "wire is silent because something broke" (also large, but you can probe with hello to disambiguate). Without this, agents would have to issue probe RPCs to tell the two states apart.

The fastest way to confirm liveness without consuming an event: send {"method":"hello"}. It's a no-op that confirms the daemon is alive and reports current pause state.

LSP companion surface

Since v0.19.33 the bridge also exposes a static-analysis surface backed by Embarcadero's DelphiLSP.exe: 13 lsp_* tools (lsp_definition, lsp_hover, lsp_completion, lsp_workspace_symbol, ...). These are paused-state independent — they query the source tree, not the running target — so an agent can navigate code before launching the debugger or while the target is in any state. Use them to find the symbol you want to break on (lsp_workspace_symbol → pick → lsp_definition → set_breakpoint source+line) instead of grepping. Capability-gated per Delphi version — absent capabilities surface as a structured error_reason on the first call.

Method cheat-sheet

The full reference is in docs/protocol.md; this is the agent-relevant slice.

UI methods accept either params.hwnd (raw hex) or params.target (caption / class name lookup). They post into the target's window queue while the daemon is paused; messages drain on the next continue. LSP methods are paused-state independent — the LSP child operates on source files, not the running target, so static-analysis queries work whether or not a debug session is live.

Recipes

Operational patterns from least to most agent-driven. Each one is self-contained — mix and match for your scenario.

// What's running that looks debuggable?
{"method":"list_processes","params":{"has_map_only":true}}
// response carries [{pid, name, exe_path, map_path?,
//                    source_dir?, dpr_path?}]

// Attach by name (first match)
{"method":"attach","params":{"name":"my-service.exe"}}
// or by exact PID
{"method":"attach","params":{"pid":1234}}

{"method":"hello"}
{"method":"launch","params":{"exe":"C:/builds/.../app.exe"}}
{"method":"continue"}

{"method":"launch","params":{"exe":"..."}}
{"method":"set_breakpoint",
 "params":{"source":"MainForm.pas","line":248}}
{"method":"continue"}

{"method":"get_self"}                       // capture Self ptr
{"method":"inspect_object",
 "params":{"address":"<self-from-above>","max_depth":2}}
{"method":"get_registers"}

{"method":"inspect_locals"}
→ {"ok":true,"frame_idx":0,"function_symbol":"MainForm.TForm1.btnSaveClick",
     "auto_walked_frames":0,"version_warning":null,
     "locals":[
       {"name":"Self",  "location":"reg",  "reg_id":0, ...},
       {"name":"Sender","location":"reg",  "reg_id":1, ...}
     ]}

{"method":"launch","params":{"exe":"..."}}
{"method":"continue"}                  // past loader BP into the message loop

// Find the form HWND.
{"method":"list_windows"}
// Response carries [{hwnd, class, title, rect, parent_hwnd}, ...].
// Pick the form by class:"TFormMain" or title:"My App".

// Set a BP at the click handler.
{"method":"set_breakpoint",
 "params":{"source":"MainForm.pas","line":248}}

// Drive the UI. PostMessage queues even when target is paused -
// fine here, target is running.
{"method":"send_keys",
 "params":{"hwnd":"<edit-hwnd>","text":"42"}}
{"method":"click_at",
 "params":{"hwnd":"<button-hwnd>","x":50,"y":15,
           "target":"OK"}}

// (a) Find and close the dialog.
{"method":"list_windows"}
// Match class:"TMessageForm" or title:"Confirm".
{"method":"post_message",
 "params":{"hwnd":"<dialog-hwnd>","msg":16,"wparam":0,"lparam":0}}
// 16 = WM_CLOSE. Cleanest, runs the dialog's normal close path.

// (b) Press Esc inside the dialog (cancels via VCL default-cancel).
{"method":"send_keys",
 "params":{"hwnd":"<dialog-hwnd>","text":""}}

// (c) Press Enter (default-affirm).
{"method":"send_keys",
 "params":{"hwnd":"<dialog-hwnd>","text":"\n"}}

# pseudocode the agent runs around the wire
hwnd_form = list_windows() | grep "TFormWizard"
for step in [
    {"field": "name",  "value": "Test User",  "next_button": "Next"},
    {"field": "email", "value": "a@b.c",      "next_button": "Next"},
    {"field": "tier",  "value": "premium",    "next_button": "Finish"},
]:
    hwnd_field = list_windows() | filter title==step.field   # or by tab order
    send_keys(hwnd_field, step.value)
    sleep(0.2)  # let the message pump catch up
    click_at(target=step.next_button)
    wait_for_event("breakpoint_hit" or "paused")
    inspect_self()

# After R3 has driven inputtest to "hello\nclick OK",
# agent paused at the BP in the click handler.
resp = repl.send({"method":"capture_window",
                  "params":{"target":"TFormInputtest"}})
# resp.result has bytes_base64 (a PNG of the form pixels).
import base64, pathlib
png = base64.b64decode(resp["result"]["bytes_base64"]
                       .replace("\\/", "/"))   # un-escape JSON
pathlib.Path("/tmp/inputtest-after-click.png").write_bytes(png)

for attempt in range(50):
    daemon = spawn_daemon()
    repl = open_repl(daemon)
    repl.send({"method":"launch","params":{"exe":"..."}})
    repl.send({"method":"continue"})

    # Drive the suspected reproducer.
    repl.send(*recipe_R3_steps)

    while event := repl.read_event(timeout=10):
        if event.kind == "exception":
            # Crash reproduced. Stop the loop, save state.
            inspect_chain = repl.send({"method":"inspect_object",
                "params":{"address":event["exception_object"],"max_depth":3}})
            save_artifact(attempt, event, inspect_chain)
            return
        if event.kind == "exit_process":
            # Clean exit this round; restart.
            break

{"method":"status"}
// → {"sessions":[{"session_id":3,"pid":1234,"owner":"none",
//                  "state":"paused","last_pause":{...}}, ...]}

{"method":"bind_session","params":{"session_id":3}}
// → returns last_pause snapshot so you know reason / pid / tid /
//   the source line the target stopped at; the session is now
//   yours and inspect / step / continue all work normally.

{"method":"lsp_open_project","params":{"project":"C:/myapp/MyApp.dproj"}}
// → autogen .delphilsp.json if needed, spawn DelphiLSP, advertise caps

{"method":"lsp_workspace_symbol","params":{"query":"SubmitClick"}}
// → [{name:"TFormMain.SubmitClick", file:"MainForm.pas", line:142, ...}]

{"method":"lsp_definition","params":{"file":"MainForm.pas","line":142,"column":10}}
// → confirms the body's source location (vs. forward declaration)

{"method":"set_breakpoint","params":{"source":"MainForm.pas","line":144}}
// → BP set; combine with R3 (drive UI) to fire it

State inspection patterns

Find the Delphi object behind a HWND

list_windows returns the TWinControl's HWND but not its Delphi object pointer — post_message is fire-and-forget and doesn't return values. To bridge HWND → Self pointer:

1. Set a BP at a method on the form (anything that runs early — often the click handler line is fine).
2. Use click_at / send_keys to fire the handler.
3. At the BP, get_self returns the form pointer (RCX on entry to a Delphi method holds Self).

Once you have the form pointer, inspect_object walks the full class chain + published-field/property values cross-process.

Read a property's live value

inspect_object decodes field-backed properties cross-process by default. For method-backed properties (like TForm.Caption, TEdit.Text, TStrings.Count) pass eval_method_props:true — the daemon hijacks the paused thread, calls the getter on a 64 KB scratch stack, captures the return register, then restores. Per-prop failures surface error_reason; for AVs you also get target_exception_code, target_exception_addr, target_exception_data_addr, and target_exception_op ("read" / "write" / "execute") so you can tell which pointer was bad without parsing EXCEPTION_RECORD. Set eval_timeout_ms (default 1000) to bound a misbehaving getter.

Resolve a path expression in one shot

For targeted reads, evaluate takes a Pascal-style path: {expr:"Self.Caption"}, {expr:"Form.Edit1.Text"}, or {expr:"0x<hex>.ComponentCount"}. Returns the same per-prop wire shape inspect_object emits, so the same renderers work. The root is either Self (resolved via get_self's heuristics on the paused frame) or a literal hex pointer. Each .ident step walks fields and properties — method-backed getters dispatch through the same cross-process RPC as inspect_object eval_method_props:true. v1 doesn't support indexing (Components[0]), arithmetic, type casts, method calls with args, or locals; those fail with parseable error_reason values.

Frame symbolization may be approximate

Stack frames inside the launched exe carry an optional approximate: true field. When set, the daemon couldn't confidently attribute the RIP to a specific source line — either (a) the RIP is in a procedure whose debug info was elided (Delphi CE Starter has been observed to drop line records and public symbols for certain procs entirely; the linker can place such a procedure between two procs that do have debug info, and the resolver picks the wrong neighbour); or (b) the RIP is legitimately past the last documented line of an extending procedure (epilogue, linker padding). The source, line, symbol, offset fields are all still populated as best-effort breadcrumbs — the flag tells the consumer to treat them as "near here, roughly" rather than as authoritative citations. Cross-check with the call-stack structure (which symbol is calling which) before drawing conclusions from an approximate frame.

Multi-thread targets

list_threads shows every tid the daemon has tracked. The is_paused_thread flag marks the one whose context the other methods default to; pass an explicit tid parameter to get_registers to inspect a different thread.

Error and timeout patterns

"method not valid while paused"

Method dispatch failed because pause/run state didn't match. Check the last event you saw: if it was paused / breakpoint_hit / target_breakpoint / exception you're paused; if create_process followed by no pause and the target is consuming time, you're running. Fix by either continue-ing or waiting for the next pause event.

Hung pipe

The daemon is generally honest about debugging state, but a target that's deadlocked won't give you events. Always wrap reads in a wall-clock timeout (the wire-scenarios harness uses python3 ... communicate(timeout=N)). On timeout: kill the SSH process group, kill the daemon explicitly via taskkill /F /IM rdbgd64.exe /T, kill known target binaries.

HWND staleness

Window handles from list_windows are valid "for now". A target that closes and reopens a form gets a new HWND. Re-enumerate after major events (form-create / form-destroy in the target, mode-switching in the UI). Don't cache HWNDs across continue calls.

Rate-limiting

PostMessage doesn't wait for the message pump. Sending dozens of events in quick succession can flood the target's queue and lose WM_MOUSEMOVE coalescing. Pace at ~50–100ms between distinct UI actions; tighter for keystroke sequences.

End-to-end worked example

Goal: a user reports that clicking Submit in inputtest.exe with an empty Email field crashes the app. Reproduce, capture stack + exception object, write up findings.

# Spawn a daemon on the Windows host.
rdbgd64.exe --listen 127.0.0.1:5902

# Drive a session from the agent's host (here, over SSH).
cat <<'EOF' | ssh windows-host "rdbgc.exe repl 127.0.0.1:5902"
{"method":"hello"}
{"method":"launch","params":{"exe":"C:/path/to/inputtest.exe"}}
{"method":"continue"}
EOF

Stream comes back:

{"id":1,"result":{"daemon":"rdbgd64","protocol":"1"}}
{"event":"create_process","pid":1234,"tid":5678,"image_base":"0x400000",...}
{"event":"paused","reason":"initial_loader_breakpoint",...}
{"id":2,"result":{"exit_code":0}}    // launch ack-ish
{"id":3,"result":{"ok":true}}         // continue ack
{"event":"debug_output","text":"inputtest started\n"}
... target running ...

Now the form is up. Drive it:

{"method":"list_windows"}
// pick form: class TFormInputtest, hwnd 0x00050aa6
// pick edit: parent matches form, class TEdit, title ""
// pick button: parent matches form, class TButton, title "Submit"

{"method":"send_keys","params":{"hwnd":"<edit>","text":""}}
// (no-op; edit was empty already, but explicit clears would go here)

{"method":"click_at","params":{"target":"Submit"}}

If the bug fires, the stream emits an exception event:

{"event":"exception","kind":"delphi","class":"EAccessViolation",
 "exception_object":"0x1A2B3C40","frames":[
   {"idx":0,"rip":"0x...","source":"InputtestMain.pas","line":52,
    "symbol":"InputtestMain.TFormInputtest.SubmitClick","offset":17},
   ...]}
{"event":"paused","reason":"exception",...}

Capture state at the pause:

{"method":"inspect_object",
 "params":{"address":"0x1A2B3C40","max_depth":3}}
{"method":"get_self"}
{"method":"inspect_object",
 "params":{"address":"<self-from-above>","max_depth":2}}
{"method":"get_registers"}

Then either fix it (set_rip past the AV to keep the session going), or report and shutdown:

{"method":"shutdown"}

Write the findings: stack at fault, the form's FEmail field value (likely ''), and the suspected guard (if FEmail = '' then is missing in TFormInputtest.SubmitClick). Recommend the fix. Optionally cycle through R6 to confirm the bug is deterministic.

Tips for autonomous loops

• Always send hello first. Confirms daemon liveness and the cost is negligible. bridge_config too if you need to know which daemon is connected.
• Drain events after every state-changing call (continue, step_*, run_to, interrupt). The synchronous response is just the ack; the real outcome lands as one or more events. Use filter:["paused","exception","exit_process"] to ignore log-class events.
• Trust idle_since_last_event_ms over wall-clock waits. A high value means "target genuinely idle" (waiting for input you should drive) or "wire is silent because something broke" — disambiguate with hello.
• Check status on reconnect. If a previous agent left a paused session, it'll show in sessions[] with owner:"none". bind_session adopts it and you skip a full launch cycle.
• Keep wire requests idempotent where possible. set_breakpoint on an already-set BP returns the existing bp_id; safe to retry.
• Save the response stream verbatim. Future-you (or another agent) reading the artifact will care more about the literal JSON than your interpretation of it.
• For caller-frame inspection, check valid_registers in the get_registers frame_idx>0 response before reading volatile slots — volatile GPRs (RAX/RCX/RDX/R8-R11) and XMM0-5 are never preserved by the ABI, so their values at the up-stack frame are meaningless.
• Distinguish value_kind:"method" from "unreadable". The first means "we know what it is, can't read it without executing" (use eval_method_props:true); the second means "something went wrong reading memory."
• For UI driving, log every HWND you discover with its class + title. The "Why didn't my click do anything?" debugging is almost always "you posted to the wrong HWND" or "HWND got reused after a form recreate." Prefer set_text_field over send_keys for text inputs — instant, no focus-loss races.
• Open the LSP project once per session. First call to lsp_open_project (or any lsp_* with a project arg) spawns DelphiLSP and autogens .delphilsp.json if needed; later calls reuse the warm child until idle reap (5 min default).

See also