Initial commit: omp-debug DSH plugin (oh-my-pi port) with docs and tests

README.md

@@ -0,0 +1,63 @@
+# omp-debug
+
+[oh-my-pi](https://github.com/can1357/oh-my-pi)'s `debug` tool for the DeepSeek Harness (DSH). The agent drives a **real debugger** over the Debug Adapter Protocol: it sets breakpoints, launches or attaches, steps, inspects stack and variables, and evaluates expressions in the stopped frame. No more print debugging.
+
+| Adapter | Languages | Install |
+| --- | --- | --- |
+| `debugpy` | Python | `pip install --user debugpy` |
+| `node` (js-debug) | JavaScript / TypeScript (Node) | download `js-debug-dap-*.tar.gz` from [vscode-js-debug releases](https://github.com/microsoft/vscode-js-debug/releases) and extract to `~/.local/share/js-debug/` (or set `JS_DEBUG_DAP` to `dapDebugServer.js`) |
+| `lldb-dap` | C, C++, Rust, Swift | `apt install lldb` |
+| `gdb` | C, C++, Rust, Go, Fortran | `apt install gdb` (≥ 14, for `--interpreter=dap`) |
+| `dlv` | Go | `go install github.com/go-delve/delve/cmd/dlv@latest` |
+
+The adapter is picked from the program's extension (`.py` → debugpy, `.js/.ts` → node, `.go`/Go module → dlv, native binaries → lldb-dap then gdb), or forced with `adapter`. `debug {"action":"adapters"}` shows what's installed.
+
+## The `debug` tool
+
+Typical flow:
+
+```
+debug {"action":"set_breakpoint","file":"app.py","line":12}          # queued before launch
+debug {"action":"launch","program":"app.py","args":["--x"]}
+→ Stopped (breakpoint) thread 1 in handle at app.py:12 (frame 2)
+   11:    data = load(path)
+  →12:    return transform(data)
+debug {"action":"scopes"}                      # locals with values, [ref N] for nested
+debug {"action":"evaluate","expression":"len(data)"}
+debug {"action":"step_over"} / step_in / step_out / continue
+debug {"action":"terminate"}
+```
+
+| Action | Notes |
+| --- | --- |
+| `launch` | `program`, `args`, `cwd`, `env`, `stop_on_entry`, `adapter` |
+| `attach` | `pid`, or `host` + `port` (e.g. `python -m debugpy --listen 5678 app.py`) |
+| `set_breakpoint` / `remove_breakpoint` | `file` + `line`, or `function`; `condition`, `hit_condition`, `log_message` (logpoint). Can be set before launch |
+| `continue` / `step_over` / `step_in` / `step_out` / `pause` | Wait (up to `timeout`) for the next stop and show the location with source context and new program output |
+| `stack_trace`, `threads`, `scopes`, `variables` (`variable_ref`), `evaluate` (`expression`, `frame_id`, `context`) | Inspection |
+| `output` | Program stdout/stderr captured so far |
+| `disassemble`, `read_memory`, `modules`, `loaded_sources`, `custom_request` | Low-level / adapter-specific |
+| `sessions`, `adapters`, `terminate` | Management |
+
+There's one active session at a time. Child debug targets (e.g. js-debug's per-process sessions) are followed automatically.
+
+## Installation
+
+```bash
+dsh plugin --profile web add git+https://git.rizzy.dev/DSH-Plugins/omp-debug.git
+```
+
+Or in the Web UI, go to **Settings → Plugins → Install**. For development, use `link:` to a clone. Restart DSH afterwards.
+
+## Configuration
+
+```yaml
+- id: omp-debug
+  config:
+    stopWaitMs: 8000       # how long launch waits for the first stop
+    maxOutputChars: 8000   # program output shown per result
+```
+
+## Tests
+
+`npm test` runs live sessions against debugpy and js-debug when they're installed.