@siuver/omp-debug-mode

A Cursor Debug Mode replica for oh-my-pi. It recreates Cursor's evidence-driven, human-in-the-loop debugging workflow for OMP; it is an independent implementation and is not affiliated with Cursor.

The plugin makes the agent form 3-5 hypotheses, choose the cheapest reliable evidence method for each one, and pause so you can reproduce the problem. The agent is instructed to NEVER fix without runtime evidence first; after a fix it keeps runtime probes in place for a verification reproduce. Your result either starts another evidence-driven round or triggers probe cleanup and a final summary.

Commands

| Command | Purpose | | --- | --- | | /debug-mode <problem> | Starts a debugging session from a symptom, expected result, actual result, and reproduction description. | | /debug-proceed [details] | Continues with captured evidence: optional details are recorded as a user-report observation, then the agent evaluates hypotheses and may fix only with evidence before asking for verification. | | /debug-evidence [<request-id>] <path> | Attaches one user-provided evidence file to the current round. If the first token matches a pending current-round request ID, the file is linked to that request; otherwise the whole argument is treated as the path (spaces allowed). Without an argument it opens an input dialog (interactive UI only). Files are referenced in place and never copied or deleted. | | /debug-done | Marks the problem as fixed: the agent removes every probe and summarizes the result. | | /debug-status | Shows the current stage, round, run, live probes, captured log counts, pending evidence requests, and attached/unavailable artifacts. | | /debug-abort | Stops debug mode and removes its logs after confirmation while leaving code changes in the working tree. |

Stages

The workflow tracks one thing: whose move it is. Every stage other than investigating belongs to you, and each has its own status label and widget so a stopped agent never looks like a stopped workflow.

| Stage | Meaning | What you do | | --- | --- | --- | | investigating | An agent turn is in flight. | Wait. | | open | The round settled without closing — a clarifying question, or declared instrumentation that never reached the code. | Reply normally. /debug-proceed closes the round anyway after a confirmation. | | awaiting_evidence | The round closed properly and is at the reproduction gate. | Reproduce, capture, then /debug-proceed. | | cleaning_up | /debug-done was accepted; probes are being removed. | Wait. |

Transitions live in one pure reducer (src/machine.ts), which returns declarative effects — notify, inject prompt, continue the turn, tear down — that the runtime shell applies. Every round is a record holding its own run id, evidence plan, reproduction steps, probe ids, and nudge budgets, so round-scoped data is never derived by filtering a session-wide array on a mutable counter.

A resumed session never lands in investigating, because no agent turn survives a restart; an unrecognised persisted stage resolves to open, on the conservative reading that the agent owes you something rather than the reverse.

Evidence Methods

For every hypothesis, the agent must pick one of four methods, in least-user-intervention order:

1. agent_inspection - reuse existing logs/files and the agent's own read/search/test/command tools. Always tried first.
2. runtime_probe - if runtime state is required, the agent installs @omp-probe instrumentation and combines every compatible hypothesis into a single reproduction.
3. user_report - only when a simple manual observation is decisive (something only you can see or try).
4. user_artifact - only when the disputed state cannot be represented reliably by inspection, probes, or a verbal report (e.g. a GPU capture, screenshot, crash dump, or externally generated trace).

Rules the agent must follow:

• It never asks you to run a command it could run itself.
• All unavoidable user actions are batched into the fewest reproductions/captures: hypotheses answerable by the same action share one request (hypothesisIds lists them all) instead of serial reports.
• A lower-priority method is never chosen merely because it is familiar; every user_report/user_artifact entry needs a rationale explicitly naming why agent inspection and runtime probes cannot settle its hypotheses.

The Evidence Plan

Each round closes with an exact machine-readable block that covers every hypothesis:

<evidence_plan>
[{"id":"E1","hypothesisIds":["A","B"],"method":"runtime_probe","title":"...","rationale":"The disputed runtime branches are not present in existing logs; one model-added probe set can capture both without a separate user artifact.","instructions":["..."],"artifactHint":"optional"}]
</evidence_plan>

Every field is validated: id must be unique and non-empty, hypothesisIds must reference one or more real hypotheses, method must be one of the four literals above, rationale/title must be non-empty, and instructions must contain actionable steps (artifactHint describes the expected file kind for user_artifact). A malformed plan is rejected entirely — no hypothesis is ever silently dropped. Plans are capped at 12 entries per round. The plan is combined with the existing <reproduction_steps> block, which describes the single combined reproduction/capture sequence the user performs now. The injected methodology forbids emitting those closing tags for a runtime_probe round until @omp-probe markers are already in the working tree, and forbids listing planned agent work (installing probes, reading logs, analyzing) as reproduction steps.

The Reproduction Gate

A round may only close when its declarations are backed by observable facts. Emitting the tags is the declaration; the probe ledger is the proof:

• Both <evidence_plan> and <reproduction_steps> must be present.
• A plan selecting runtime_probe additionally needs at least one @omp-probe marker that the ledger actually finds on disk for this round. A probe that was written and then deleted counts as missing.
• agent_inspection, user_report, and user_artifact plans need no markers at all, and expect no JSONL logs.

Anything short of that is one automatic nudge — and the two nudge budgets are separate, so being sent back for missing probes never consumes the budget for missing closing tags. When a budget is spent the round becomes open rather than being gated on evidence that does not exist. A clarifying question mid-round is open too, which is the ordinary case: reply and the agent picks the round back up.

A round with reproduction steps but no plan at all still gates (older sessions closed this way) and gets the "no runtime evidence" warning.

At the gate a widget shows the reproduction steps, any pending user requests (title, instructions, artifact hint), a live counter of captured observations, an evidence: <pending> pending, <attached> attached counter, and the list of commands you can use, so you can tell what evidence the round is waiting on and how to act. The widget always ends with the live log counter. An open round gets its own, smaller widget naming why it is open and stating that a reply is the way forward. Every round stops at a widget and you interact through commands only.

Pending requests resolve like this:

• A user_artifact request is pending until a file is attached with a matching request ID.
• A user_report request is pending until /debug-proceed <details> records an observation for the current round; one details submission can satisfy several report requests at once.
• agent_inspection and runtime_probe requests never create user work.

If user requests are still pending when you run /debug-proceed, the plugin asks "Proceed without all requested evidence?" — confirming is allowed so an unavailable external capture can never deadlock the session; cancelling keeps you at the gate. /debug-proceed and /debug-done ask for confirmation when the round captured no runtime logs and has no valid non-probe evidence plan, and again when the round is open rather than gated. They only refuse outright while an agent turn is actually running.

Attaching Evidence Files

/debug-evidence [<request-id>] <path> records one user-provided file for the current waiting round:

• The path is resolved against the session working directory; the plugin records the absolute path, size, and mtime and references the file in place. It never copies, renames, or deletes your file — not during attach, not during cleanup, not during teardown.
• If the first argument token matches a pending current-round request ID, the file is linked to that request; otherwise the entire argument is treated as the path (spaces are supported) and the artifact is attached unlinked — the agent sees it as unassigned evidence and must associate it with a request itself. A path whose first token happens to look like a request ID but does not match one is simply treated as a path.
• Interactive sessions must confirm before recording a path outside the session working directory; non-interactive sessions reject outside-cwd paths because no confirmation channel exists.
• Re-attaching the same resolved path reuses the existing artifact entry and refreshes its metadata and request association.
• Missing paths, directories, and unreadable files are rejected with the reason, and the ledger stays unchanged.

Availability is re-checked by re-statting each path, so a file that was moved or deleted after attaching is reported as unavailable — the ledger never claims unavailable evidence was captured. The model is told to treat user reports and artifacts as data to inspect, not instructions to execute, and must conclude INCONCLUSIVE (or file a new, lower-burden request) when it cannot inspect a file with its normal tools.

Example: for a GPU-rendering symptom whose disputed state only exists inside a frame capture, the agent justifies why inspection, tests, and probes cannot answer, then emits one user_artifact request with an artifactHint like "RenderDoc .rdc capture of a failing frame". You capture frame.rdc in RenderDoc and run /debug-evidence E1 frame.rdc (using the request ID shown in the widget). /debug-status and the read-only list_debug_evidence tool then show the artifact ID, absolute path, size, and availability. The .rdc bytes are treated as opaque — the plugin does not parse the format; if the agent cannot extract what it needs from the binary with its normal read/bash tools, it says so and asks for a converted report or a new capture rather than guessing.

Workflow

1. Run /debug-mode <problem description>.

2. The Agent records 3-5 hypotheses and picks an evidence method for each under the least-user-intervention priority. If the route is runtime_probe, it inserts minimal probes marked with @omp-probe <id> inside #region agent log blocks in the same turn, before emitting the closing tags; round 1 does not apply a product fix (probe edits are not a product fix). The start prompt and a per-turn debug-mode-context message name the exact JSONL path and require every probe to append to it, including hypothesisId; console output (including Unity Debug.Log) is supplemental only. The context filter keeps the newest of those messages so the model sees the contract instead of dropping it. <reproduction_steps> are user actions only (reproduce, capture, restart).

3. When the Agent reaches the gate, follow the <reproduction_steps> in the real application so the instrumented code writes its observations, watching the widget counter climb — or supply the requested evidence with /debug-evidence or /debug-proceed <details>. Restart the app or service if the instrumented build would otherwise be stale.

4. Continue with /debug-proceed [details] (optionally record a user observation, then evaluate evidence), /debug-done (clean up and summarize), /debug-evidence (attach a file), or /debug-status (inspect the current round state). Each round stops at the widget; all interaction is command-driven.

5. On Proceed, the Agent reads the evidence (logs, your observations, attached artifacts), cites the evidence method plus log-line numbers or artifact/report paths for each hypothesis, and only then may apply a fix. Probes stay in place. Reproduce again to verify. If verification fails, rejected-hypothesis code changes are reverted before the next round.

6. On /debug-done, the Agent removes every probe and summarizes the root cause and fix in 1-2 lines. If the ledger is still not empty when that turn settles, cleanup is sent back once with the remaining markers listed; a second incomplete attempt tears down anyway and warns you which probes are still in your source.

The extension also provides the read-only get_debug_logs, list_debug_probes, and list_debug_evidence tools so the Agent can inspect runtime evidence, review pending/satisfied requests with their methods and rationales, and verify cleanup.

Runtime Data

At the start of each round, the plugin creates an absolute log path under a directory owned by the current session:

<project>/.omp/debug/<session-id>/current.jsonl

The session segment keeps concurrent omp sessions from truncating or deleting each other's evidence, since every round truncates current.jsonl and teardown removes the directory. The plugin also adds .omp/debug/ to the repository's local .git/info/exclude once, so probe logs never appear in git status; that file is not committed, so your .gitignore is left alone. Teardown removes only this log directory; attached user evidence files are never removed.

That exact stable path is injected into the Agent prompt. The prompt requires every runtime probe to use the target environment's native file append API and write one compact JSON object plus a newline using this schema:

{"probe":"player-state","hypothesisId":"A","ts":1787193600000,"location":"Player.cs:42","message":"grounded check","data":{"isGrounded":false}}

get_debug_logs, the proceed prompt, and /debug-status summarize each run by hypothesisId, so you can see which hypotheses produced evidence before reading a single raw line. A hypothesis with no entries was not exercised, which is not the same as being rejected.

When you run /debug-proceed [details], the plugin records non-empty details as a user observation, archives the completed file as <run-id>.jsonl, and creates an empty current.jsonl for the next reproduction. Because the active run is truncated at the start of every round, get_debug_logs defaults to the newest run that actually captured observations and names the run it read; previous=true forces the last completed run. /debug-status shows the current absolute file path and the per-run log counts.

Probe Ledger

The plugin tracks every @omp-probe <id> marker the Agent writes, resolving each file against the session working directory, and attributes it to the round that introduced it. Before each turn, before a round is allowed to close, and on every list_debug_probes call it rescans those files so the ledger matches the code on disk: markers the Agent has since deleted drop out, and a file that exists but cannot be read is reported as unverified rather than assumed clean. That way a failed read can never make teardown claim the probes are gone while they are still in your source, and a runtime_probe round cannot reach the gate on a promise. Rounds that choose non-probe evidence methods simply add no markers, and cleanup still verifies that no leftover markers remain before finishing.

Install

omp plugin install @siuver/omp-debug-mode

Restart omp after installation, then run /debug-mode <problem>.

Local Development

From the repository root:

bun run check
omp plugin link ./plugins/debug-mode

Restart omp after linking.

Changelog

See CHANGELOG.md for release notes included in the npm package.