hkuds--cli-anything/lldb/agent-harness/LLDB.md

LLDB.md - LLDB Backend Notes for CLI-Anything

Why LLDB Python API

This harness follows the CLI-Anything principle:

Direct integration with actual software backends — full professional capabilities, zero compromises.

Using import lldb is the native backend integration route and avoids fragile text parsing from lldb -b -o ... subprocess output.

Integration Strategy

1. Try import lldb
2. On failure, run lldb -P to discover LLDB Python module directory
3. Prepend discovered path to sys.path
4. Retry import

This is implemented in utils/lldb_backend.py.

Session Lifecycle

• Initialize LLDB debugger (SBDebugger.Initialize, SBDebugger.Create)
• Keep one process-level session object during command/repl lifetime
• Use synchronous mode (SetAsync(False)) for deterministic command behavior
• Destroy debugger cleanly on session close

Data Model

All core operations return plain dictionaries:

• process info (pid, state, num_threads)
• stop info (reason, description, module, function, frame)
• frame info (function, file, line, address)
• breakpoints (id, locations, condition)
• expression result (type, value, summary, error)

This maps directly to --json output mode.

Current Limitations

• No advanced watchpoint support yet
• Memory search is a naive byte scan over fetched range
• Multi-target workflows are not implemented yet (single active target/session)