Debugging & DAP
The LingXizhi kernel has a built-in DAP (Debug Adapter Protocol) client that communicates over stdio with any compatible debug adapter, bringing breakpoint debugging to the IDE and the AI. Debug data such as breakpoint locations and variable states also serves as input for the AI when locating problems.
How It Works
- The debug adapter launches as a subprocess and exchanges JSON messages over standard I/O in
Content-Lengthframes. - A background read loop continuously parses adapter output: responses are dispatched by request sequence number, events are queued for consumption, and waiting for a specific event (such as
stopped) is supported. - Every request carries a 15-second timeout, so the caller never hangs when the adapter stops responding.
- The
initializehandshake completes automatically after startup; the adapter process is reclaimed automatically when the session ends, and launches silently on Windows without popping up a console window. - The adapter's stderr is ignored by default, keeping diagnostic output from polluting the protocol stream.
Verified Debugging Capabilities
| Capability | Description |
|---|---|
| Breakpoint management | Set, list, and clear breakpoints by file and line number |
| Call stack | Get the full stack trace and frame IDs when the program pauses |
| Variable inspection | Expand the variable list of the current scope |
| Expression evaluation | Evaluate arbitrary expressions in the context of a given stack frame |
| Step / continue | next steps one line; continue runs to the next breakpoint or the end |
| Event notifications | Program stop, exit, and other events are queued in real time, ready to be awaited and consumed |
Debugging Flow
Set breakpoints: set breakpoints by line number in the target file; you can list or clear all breakpoints at any time.
Start a session: launch the debug adapter and run to a breakpoint; once the program pauses, inspect the call stack (stack trace).
Inspect variables: expand the variable list of the current scope, or use expression evaluation (evaluate) to compute any expression, such as x + y.
Step and continue: next steps one line; continue runs to the next breakpoint or until the program ends.
The kernel has completed end-to-end verification of the full "breakpoint → call stack → variables → evaluate → step → continue" flow with the Python debug adapter, covering scope resolution after a breakpoint hit (the complete chain from stack frame to scopes to the variable list). All breakpoints can be cleared in one go after the session ends.
Connecting a New Debug Adapter
Any debug adapter that implements the DAP protocol can be connected: simply provide the adapter's executable path and launch arguments, and the kernel will spawn it as a subprocess and complete the initialization handshake. Frame parsing, request dispatch, and event collection are all handled by the kernel — the IDE side needs no knowledge of protocol details. Other languages get the same capabilities described above by connecting their respective DAP adapters (such as the adapters for Node, Go, and Rust).
After connecting a new adapter, it is recommended to verify breakpoint hits and variable reads with a simple script before using it for daily debugging.
The debugging capabilities above are also exposed through the kernel API for IDE panels and AI tools to call — see Kernel API. Like the subprocesses in the integrated terminal, debug adapter processes are managed centrally by the kernel.
While debugging, you can paste variable states and call stacks at a breakpoint into AI Chat at any time, letting the model locate problems based on real runtime state.