@siuver/omp-debug-mode 0.1.5 → 0.1.7
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +82 -48
- package/README.md +88 -31
- package/package.json +41 -41
- package/src/debug-mode.ts +285 -92
- package/src/evidence.ts +325 -169
- package/src/gate.ts +115 -51
- package/src/log-files.ts +161 -115
- package/src/machine.ts +136 -49
- package/src/main.ts +24 -24
- package/src/methodology.ts +56 -15
- package/src/state.ts +191 -42
- package/src/tools.ts +195 -9
- package/src/ui.ts +145 -71
package/CHANGELOG.md
CHANGED
|
@@ -1,48 +1,82 @@
|
|
|
1
|
-
# Changelog
|
|
2
|
-
|
|
3
|
-
##
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
-
|
|
8
|
-
-
|
|
9
|
-
-
|
|
10
|
-
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
-
|
|
19
|
-
-
|
|
20
|
-
-
|
|
21
|
-
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
-
|
|
26
|
-
-
|
|
27
|
-
-
|
|
28
|
-
-
|
|
29
|
-
- Probe
|
|
30
|
-
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
-
|
|
35
|
-
-
|
|
36
|
-
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
-
|
|
42
|
-
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
-
|
|
47
|
-
-
|
|
48
|
-
-
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## 0.1.7 - 2026-09-09
|
|
4
|
+
|
|
5
|
+
- Added `/debug-clear`, which empties this round's `current.jsonl` without advancing. A botched reproduction can be thrown away and rerun on the same round; archived runs stay on disk. The live counter on `/debug-proceed` drops to zero, and a busy truncate is retried the same way as rotation.
|
|
6
|
+
- Cut the repetition out of the user-turn widgets, where one screen said `/debug-proceed` three times (call to action, the agent's closing step, the actions strip), the round number three times (footer plus both exit lines), and "nothing was captured" twice (the proceed line plus a `run <id> — 0 log entries` footer). The round number now lives only in the footer, the captured counts live only on the `/debug-proceed` line that acts on them — still climbing live while you reproduce — and the run id is gone from the widget entirely, since it is not something you type.
|
|
7
|
+
- The actions strip under the editor is a dim cheat-sheet headed `Tips:`, not a second headline. `/debug-proceed` no longer lights up when logs arrive (empty vs captured stays in the wording), the leftover-commands line stays dim, and `Reply in the editor` is gone: that exit is still legal, but listing it next to the editor restated what the cursor already is.
|
|
8
|
+
- The widget renumbers reproduction steps itself and drops any step naming `/debug-proceed` or `/debug-done`. The agent numbers its list about as often as it does not, and an unnumbered run of dim lines reads as one paragraph instead of a sequence — while the injected contract used to *require* a closing line naming the commands, which the model then also wrote in as a final numbered step the user cannot perform until every other step is done. The methodology, the start/proceed prompts, and the user-turn briefing now forbid naming either command in prose or in the steps, and ask for one short line saying what to do instead.
|
|
9
|
+
- Widget lines are clipped by terminal columns instead of character count. A CJK step counts one unit per character while occupying two columns, so a Chinese reproduction step passed the 90-character budget untouched at 180 columns wide and was wrapped or truncated by the host.
|
|
10
|
+
- Stopped spelling the `-` sentinel as `<request-id|->` under the editor: it renders as an arrow directly beneath three lines that use `→` to mean "and then this happens". The command's own completion already offers `-` as its first entry.
|
|
11
|
+
|
|
12
|
+
## 0.1.6 - 2026-08-31
|
|
13
|
+
|
|
14
|
+
- `/debug-proceed` now recreates a missing log directory, stops the live log watcher before rotating `current.jsonl`, retries a busy truncate, and reports the OS error instead of a bare "could not initialize the next run log file". A failed truncate no longer deletes the archive it just copied — that rollback destroyed the completed run when the instrumented app still had the file open.
|
|
15
|
+
- Merged the two user-facing stages into one. `open` and `awaiting_evidence` were the same turn with different wording, and telling them apart required judging how well the agent had closed the round, so `/debug-proceed` could be refused on a round the agent had already asked you to reproduce. There is now a single `user_turn` stage plus a `reproduce`/`capture`/`question`/`incomplete` handoff label that changes only the wording and never which command is legal. Persisted `open`, `awaiting_evidence`, and the old `openReason` values migrate onto the equivalent handoff.
|
|
16
|
+
- Added the `hand_off_to_user` Agent tool as the only way a round reaches the user, replacing inference from prose. It takes the handoff mode, the user's steps, and the evidence plan, validates them against the same rules as the `<evidence_plan>` tag, and rejects a bad call with the exact problem so the agent repairs it inside the same turn. The `<evidence_plan>`/`<reproduction_steps>` tags are still parsed for their contents and now share one validator with the tool, so both accept the same shape and reject with the same message.
|
|
17
|
+
- Prose no longer closes a round on its own, which is what made skipping the tool free. `<evidence_plan>`/`<reproduction_steps>` were accepted as an equivalent closure, so a turn that described a reproduction and stopped reached the user exactly like a proper tool call and was never corrected — and the injected contract advertised the tag form as a fallback that "may still be parsed". The tags are still read for their contents, but a settled turn that never called the tool is now sent back for the call, and the contract says so.
|
|
18
|
+
- Reshaped the sent-back reminder after the host's own plan-mode convergence prompt: a `<system-reminder>` block that names the round, asks for one of the three modes, and forbids answering in prose, instead of a paragraph that restated the whole evidence-method methodology the blackboard already injects every turn. A round that already wrote the values in prose is asked to pass those same values as arguments.
|
|
19
|
+
- Raised the closing reminder budget from one to three, matched by a progress guard: after a reminder, another one is only spent if the agent made a tool call in between, so a model that answers every reminder with more prose costs one extra turn rather than three. The persisted `nudges.tags` budget migrates onto `nudges.handoff`.
|
|
20
|
+
- Dropped the handoff tool from the `write` approval tier to `read`. The call touches no file and no command, only who owns the turn, and on the `write` tier an approval policy can put a prompt in front of the one action every round is required to end with — where a declined or interrupted prompt is indistinguishable from a model that never called it.
|
|
21
|
+
- Made the model see the state it drives: the `debug-mode-context` blackboard is injected on every prompt, including a reply on the user's turn, and states the stage, whose turn it is, how the round was handed back, and which closing requirements are still missing.
|
|
22
|
+
- A reply at a handoff is now a full round turn again. It moves the stage back to `investigating`, resets the nudge budgets, and absorbs whatever that turn produces, instead of silently discarding a revised plan or new reproduction steps.
|
|
23
|
+
- Fixed a host continuation being able to take the user's turn away. A turn that starts while the round is with the user is no longer read as a reply: only a user message landing in the transcript hands the round back. The host resumes the agent loop by itself for an incomplete-todo reminder, a plan-mode nudge or a queued-message drain, and every one of those started a turn that reset the stage to `investigating`, cleared the handoff, dropped the user-turn widget and stopped the log watcher — while the user was still out reproducing. Replying while the agent is still streaming still works, because a queued message is announced the same way a submitted one is.
|
|
24
|
+
- The injected blackboard is now re-rendered where the request is assembled, not only when a prompt is submitted. `before_agent_start` does not fire for a continuation, so a turn resumed by a reminder used to carry the previous turn's blackboard — which said the round was the agent's — directly under a reminder telling it to keep working. Combined with the item above, that is what made the agent analyze a reproduction the user had never run.
|
|
25
|
+
- Attributed the injected blackboard to the agent explicitly. A `before_agent_start` message otherwise inherits the attribution of the prompt it is answering, so on a real user turn this extension's own state dump was stamped user-authored — and models read that literally, reporting the stage back as a debug-mode message the user had sent and treating the injected closing contract as a fresh instruction from the user rather than as their own standing rules.
|
|
26
|
+
- Rewrote the user-turn briefing to be true whichever way the turn started, since the context is assembled before a user message is announced. It no longer asserts that the user replied; it tells the agent to check what started the turn, and that a turn with nothing from the user in it means no reproduction has run and must end without reading or analyzing anything.
|
|
27
|
+
- Made that briefing cover the request that follows the `hand_off_to_user` call, which is the one turn on the user's round that is neither a reply nor a foreign continuation. A tool call never ends a turn, so every handoff is followed by one more request, and describing the no-user-message case purely as reminders and automatic continuations meant the agent answered its own closing message with a report about having been reminded instead of telling the user what to do. Both cases now share one description, and the briefing asks for a short closing line addressed to the user rather than a restatement of the briefing.
|
|
28
|
+
- `get_debug_logs` now refuses while the round is with the user, stating that no reproduction has run rather than returning a stale or empty run. A genuine reply hands the round back before any tool can execute, so the only calls this blocks are the ones made on a turn the user never started.
|
|
29
|
+
- Probe liveness is counted session-wide instead of per round. Instrumentation deliberately outlives the round that installed it, so a verification round that reuses existing probes no longer gets nudged for having installed none.
|
|
30
|
+
- Debug commands no longer refuse because the stage looks wrong. They wait for the agent to go idle and then reclassify a round that never settled — the usual cause is an interrupted turn, which never reaches the settle hook and used to lock every command for the rest of the session.
|
|
31
|
+
- Rewrote the user-turn widget around the choice it is actually asking you to make: one line for the action that clears the round, then `Proceed → close round N, analyze <n> log entries, <n> artifacts` and `Reply → round N stays open, the run keeps recording`. The Proceed line becomes a warning while nothing has been captured, and the same commands are offered in every mode.
|
|
32
|
+
- Named the slash commands everywhere the user or the model is told what to do next. `Press Proceed/Mark as fixed` was leftover from the removed round-review menu; repeating that phrase made the agent tell you to press a key that does not exist, while the only real actions were `/debug-proceed` and `/debug-done`.
|
|
33
|
+
- Split the user-turn widget across the host's two slots. Context — the call to action, pending requests, and reproduction steps — stays above the editor. The three exits (`/debug-proceed`, reply in the editor, `/debug-done`), the remaining commands, and the live log counter sit below it, next to the prompt. Footer status is still the one-line `🐞 round N · reproduce` label.
|
|
34
|
+
- The four Agent tools (`hand_off_to_user` and the three read-only inspectors) stay `essential` once a debug session is running, but they are registered `defaultInactive` and only added to the active set when `/debug-mode` starts — or when a resumed session is already in debug mode. They are removed again on teardown. Registering them as essential at plugin load put `hand_off_to_user` in every ordinary session's schema, which is why the model called it without debug mode being on.
|
|
35
|
+
- The handoff tool and the three read-only tools are registered as essential, so a tool the injected contract orders by name is never hidden behind tool search.
|
|
36
|
+
- Fixed `/debug-evidence <request-id> <path>` resolving `<cwd>/<request-id> <path>` as a single path. The first token was only read as a request ID when it named a *currently pending* `user_artifact` request, and every other case silently fell back to treating the whole argument as a path, so the failure surfaced as a missing file rather than as an unrecognised ID. The first argument is now always a link selector: an evidence request ID from any round, or `-` for a file no request asked for. An unrecognised selector is reported as such with the known IDs listed, and the argument is parsed after the turn is claimed so the selector resolves against settled state.
|
|
37
|
+
- Added editor completion for `/debug-evidence`. Typing the command lists `-` plus every request ID with its method, title, and state (`pending`, `satisfied`, or the round it came from), this round's pending requests first; once the selector is settled the completion yields to the editor's own file-path completion.
|
|
38
|
+
|
|
39
|
+
## 0.1.5 - 2026-08-25
|
|
40
|
+
|
|
41
|
+
- Tightened the injected methodology, start prompt, and proceed prompt so a `runtime_probe` round must write `@omp-probe` instrumentation in the same turn before emitting closing tags, and `<reproduction_steps>` lists only user actions.
|
|
42
|
+
- Replaced the `idle`/`round`/`waiting`/`cleanup` phases plus the redundant `active` flag with a discriminated union over four stages named after whose turn it is: `investigating`, `open`, `awaiting_evidence`, and `cleaning_up`. A round that settles without closing is now the explicit `open` stage with its own status label, widget, and explanation instead of a silent stop that looked like the reproduction gate.
|
|
43
|
+
- Moved every transition into one pure reducer (`src/machine.ts`) that returns declarative effects (notify, prompt, continue, teardown) for the runtime shell to apply, so state changes no longer hand-reset a different subset of fields per call site and the run-creation failure path no longer needs a manual rollback.
|
|
44
|
+
- Made round-scoped data structural: each round record owns its run id, evidence plan, reproduction steps, probe ids, and per-reason nudge budgets, instead of being filtered out of session-wide arrays by a mutable round counter. Probe nudges and closing-tag nudges now have independent budgets.
|
|
45
|
+
- Closing a `runtime_probe` round now requires probes the ledger actually finds on disk, not just a plan that names the method; the ledger is reconciled before every settle, so instrumentation that was written and then deleted no longer reaches the gate.
|
|
46
|
+
- `/debug-proceed`, `/debug-done`, and `/debug-evidence` now work from an `open` round after a confirmation instead of failing with "not waiting for reproduction"; they only refuse while an agent turn is actually running.
|
|
47
|
+
- Cleanup that leaves markers behind is sent back once with the remaining probes listed before teardown gives up and warns, instead of tearing down on the first attempt regardless.
|
|
48
|
+
- Session restore now migrates the pre-`rounds` persisted layout, and an unknown or `investigating` stage resolves to `open` rather than dropping the user into a reproduction gate that was never opened.
|
|
49
|
+
|
|
50
|
+
## 0.1.4 - 2026-08-21
|
|
51
|
+
|
|
52
|
+
- Added least-user-intervention evidence planning: the agent chooses `agent_inspection`, `runtime_probe`, `user_report`, or `user_artifact` per hypothesis, must justify user-assisted methods, and batches compatible hypotheses into the fewest reproductions or captures.
|
|
53
|
+
- Added persisted evidence requests, user observations, and in-place artifact metadata plus the read-only `list_debug_evidence` tool. `/debug-evidence [<request-id>] <path>` links files to pending requests without copying or deleting them, and unavailable files remain explicitly unverified.
|
|
54
|
+
- Replaced the automatic round-review menu with a command-only gate widget. Removed `/debug-menu` and merged user-report submission into `/debug-proceed [details]`; users now continue with `/debug-proceed`, `/debug-evidence`, `/debug-done`, `/debug-abort`, and `/debug-status` while safety confirmations remain in place.
|
|
55
|
+
- Extended the reproduction gate, cleanup context, session restore, status output, tests, and documentation for mixed probe/report/artifact rounds, including opaque RenderDoc `.rdc` captures.
|
|
56
|
+
|
|
57
|
+
## 0.1.3 - 2026-08-20
|
|
58
|
+
|
|
59
|
+
- Aligned the injected methodology with Cursor Debug Mode: 3-5 hypotheses, instrument all of them, never fix without runtime logs, keep probes during the fix, and verify with a second reproduce. Round 1 is instrument-only.
|
|
60
|
+
- The methodology now actually reaches the model: the context filter keeps the newest `debug-mode-context` instead of stripping the injection, and the start prompt names the absolute log file and forbids console-only probes such as Unity `Debug.Log`. Cleanup turns get a cleanup-specific contract.
|
|
61
|
+
- The reproduction gate opens on the agent's `<reproduction_steps>` block. A clarifying question no longer strands you at the gate; an instrumented round that forgets the block is asked once to finish it, then gated anyway. The gate widget counts observations live while you reproduce.
|
|
62
|
+
- The Mark as fixed / Proceed / Add reproduction details / Abort menu opens automatically at the gate. `/debug-menu` reopens it; `/debug-proceed` continues with captured logs; `/debug-done` marks the problem fixed.
|
|
63
|
+
- Probe ledger and log reads are grounded in disk: markers are resolved against the session cwd, removal edits no longer re-register themselves, unreadable files are reported instead of assumed clean, and `get_debug_logs` defaults to the newest run that captured observations.
|
|
64
|
+
- Probe logs live under a per-session directory. `.omp/debug/` is added once to `.git/info/exclude`. Status, proceed, and `get_debug_logs` summarize hits by `hypothesisId`.
|
|
65
|
+
|
|
66
|
+
## 0.1.2 - 2026-08-20
|
|
67
|
+
|
|
68
|
+
- Added an interactive round-review menu with Mark as fixed, Proceed, Add reproduction details, and Abort actions.
|
|
69
|
+
- Added `/debug-review` to reopen the menu and `/debug-note <details>` to return to the editor, add user evidence, and continue the workflow.
|
|
70
|
+
- Kept `/debug-done fixed|proceed` as compatible shortcuts and added interactive confirmation for zero-log completion, zero-log progression, and abort.
|
|
71
|
+
|
|
72
|
+
## 0.1.1 - 2026-08-20
|
|
73
|
+
|
|
74
|
+
- Replaced the localhost HTTP collector with direct JSONL file appends from instrumented runtime code.
|
|
75
|
+
- The injected prompt now supplies the exact absolute log file and explicitly forbids POST, sockets, and other network transports.
|
|
76
|
+
- Updated log analysis, status reporting, and session resume to read JSONL directly; active probes use a stable `current.jsonl` path while completed rounds are archived by run id.
|
|
77
|
+
|
|
78
|
+
## 0.1.0 - 2026-08-20
|
|
79
|
+
|
|
80
|
+
- Initial npm release of the Cursor Debug Mode replica for OMP.
|
|
81
|
+
- Added iterative hypothesis, instrumentation, fix, and user-reproduction rounds.
|
|
82
|
+
- Added local probe logging, session resume, probe-ledger cleanup, debug commands, and evidence-reading tools.
|
package/README.md
CHANGED
|
@@ -10,25 +10,42 @@ The plugin makes the agent form 3-5 hypotheses, choose the cheapest reliable evi
|
|
|
10
10
|
| --- | --- |
|
|
11
11
|
| `/debug-mode <problem>` | Starts a debugging session from a symptom, expected result, actual result, and reproduction description. |
|
|
12
12
|
| `/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. |
|
|
13
|
-
| `/debug-evidence
|
|
13
|
+
| `/debug-evidence <request-id\|-> <path>` | Attaches one user-provided evidence file. The first argument always names what the file answers: an evidence request ID, or `-` for a file no request asked for. Typing the command lists the available selectors under the editor. Files are referenced in place and never copied or deleted. |
|
|
14
14
|
| `/debug-done` | Marks the problem as fixed: the agent removes every probe and summarizes the result. |
|
|
15
|
-
| `/debug-status` | Shows the current stage, round, run, live probes, captured log counts, pending evidence requests, and attached/unavailable artifacts. |
|
|
15
|
+
| `/debug-status` | Shows the current stage, round, run, how the round was handed back, live probes, captured log counts, pending evidence requests, and attached/unavailable artifacts. |
|
|
16
|
+
| `/debug-clear` | Empties the current run's `current.jsonl` so you can reproduce again on this round. Archived runs are left alone. |
|
|
16
17
|
| `/debug-abort` | Stops debug mode and removes its logs after confirmation while leaving code changes in the working tree. |
|
|
17
18
|
|
|
18
19
|
## Stages
|
|
19
20
|
|
|
20
|
-
The workflow tracks one thing: whose move it is.
|
|
21
|
+
The workflow tracks one thing: whose move it is. There are three stages, and exactly one of them is yours.
|
|
21
22
|
|
|
22
23
|
| Stage | Meaning | What you do |
|
|
23
24
|
| --- | --- | --- |
|
|
24
25
|
| `investigating` | An agent turn is in flight. | Wait. |
|
|
25
|
-
| `
|
|
26
|
-
| `awaiting_evidence` | The round closed properly and is at the reproduction gate. | Reproduce, capture, then `/debug-proceed`. |
|
|
26
|
+
| `user_turn` | The agent handed the round back. | Reproduce/capture and `/debug-proceed`, or just reply. |
|
|
27
27
|
| `cleaning_up` | `/debug-done` was accepted; probes are being removed. | Wait. |
|
|
28
28
|
|
|
29
|
+
Every settled agent turn ends in `user_turn`. How well the agent closed the round only changes the wording, never which commands are legal, so a handoff the agent mislabelled can never make `/debug-proceed` illegal:
|
|
30
|
+
|
|
31
|
+
| Handoff | Status label | Meaning |
|
|
32
|
+
| --- | --- | --- |
|
|
33
|
+
| `reproduce` | `round N · reproduce` | Run the app so the probes record. |
|
|
34
|
+
| `capture` | `round N · capture` | Only a report or a file is needed, no reproduction. |
|
|
35
|
+
| `question` | `round N · your reply` | The agent needs an answer before it can plan. |
|
|
36
|
+
| `incomplete` | `round N · needs input` | The round stopped without saying what to reproduce or capture. |
|
|
37
|
+
|
|
38
|
+
Replying instead of running `/debug-proceed` hands the round back to the agent: the stage returns to `investigating`, the reply is an ordinary turn, and anything that turn produces — a revised plan, new steps — is absorbed and re-closed. Nudge budgets and the reminder guard reset with it, so a round you replied to is still repairable.
|
|
39
|
+
|
|
40
|
+
Only your message does that. The host resumes the agent loop on its own for an incomplete-todo reminder, a plan-mode nudge or a queued-message drain, and each of those starts a turn while you are still out reproducing. Those turns leave the stage alone: your widget stays, the run keeps recording, and `get_debug_logs` refuses with "no reproduction has run" rather than handing back a stale run. The agent is told the same thing in its blackboard, which is re-rendered as the request is assembled precisely because those turns skip the prompt hook that normally injects it.
|
|
41
|
+
|
|
42
|
+
You will also see one short message from the agent right after the handoff notice. That is not a hidden turn of yours: a tool call never ends a turn, so calling `hand_off_to_user` always leaves the agent one more message to write, and it is told to spend it telling you what to do now rather than on reading anything.
|
|
43
|
+
|
|
29
44
|
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.
|
|
30
45
|
|
|
31
|
-
A resumed session never lands in `investigating`, because no agent turn survives a restart; an unrecognised persisted stage resolves to `
|
|
46
|
+
A resumed session never lands in `investigating`, because no agent turn survives a restart; an unrecognised persisted stage resolves to `user_turn`, on the conservative reading that the agent owes you something rather than the reverse.
|
|
47
|
+
|
|
48
|
+
Commands never refuse because the stage looks wrong. They wait for the agent to go idle first, and a round still sitting in `investigating` afterwards — the usual cause is an interrupted turn, which never reaches the settle hook — is reclassified as a handoff on the spot.
|
|
32
49
|
|
|
33
50
|
## Evidence Methods
|
|
34
51
|
|
|
@@ -45,31 +62,59 @@ Rules the agent must follow:
|
|
|
45
62
|
- 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.
|
|
46
63
|
- 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.
|
|
47
64
|
|
|
48
|
-
##
|
|
65
|
+
## Closing a Round
|
|
49
66
|
|
|
50
|
-
|
|
67
|
+
A round reaches you through one Agent tool call, not through prose. `hand_off_to_user` takes the handoff `mode` (`reproduce`, `capture`, or `question`), the numbered `steps` you perform now, and the evidence `plan`; that call is what renders your widget, makes `/debug-proceed` available, and records the plan. Announcing a reproduction in prose does not move the session, which is what used to leave a round "not closed" while you had already been told to act.
|
|
51
68
|
|
|
52
|
-
|
|
53
|
-
|
|
69
|
+
The tool validates its arguments and rejects a bad call with the exact problem — missing steps, a missing plan on the first round, an invalid plan entry — so the agent repairs it inside the same turn instead of stopping. It sits on the lowest approval tier, because a call that only changes whose turn it is should never wait behind a prompt.
|
|
70
|
+
|
|
71
|
+
A turn that settles without that call is sent back for it. The reminder is a `<system-reminder>` naming the round and the three modes, and a round that already wrote the steps or plan in prose is asked to pass those same values as arguments rather than to write anything new. Up to three reminders are available per round, but another one is only spent if the agent made a tool call since the last one, so a turn that answers a reminder with more prose costs one extra turn and then reaches you anyway — labelled from whatever its prose described, since reproduction steps you have already read are a work order whether or not the agent closed the round properly.
|
|
72
|
+
|
|
73
|
+
The plan is a JSON array covering every hypothesis:
|
|
74
|
+
|
|
75
|
+
```json
|
|
54
76
|
[{"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"}]
|
|
55
|
-
</evidence_plan>
|
|
56
77
|
```
|
|
57
78
|
|
|
58
|
-
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.
|
|
79
|
+
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.
|
|
59
80
|
|
|
60
|
-
|
|
81
|
+
The same array inside an `<evidence_plan>` block, followed by a `<reproduction_steps>` list, is still parsed for its contents so a plan described in prose is not lost; both paths share one validator, so they accept exactly the same shape and reject with exactly the same message. The tags never close a round, though — that is deliberate. While they did, describing a reproduction and stopping produced the same result as calling the tool, so there was nothing to learn from and nothing to correct.
|
|
61
82
|
|
|
62
|
-
|
|
83
|
+
### Probes must exist before the round closes
|
|
63
84
|
|
|
64
|
-
-
|
|
65
|
-
- 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.
|
|
66
|
-
- `agent_inspection`, `user_report`, and `user_artifact` plans need no markers at all, and expect no JSONL logs.
|
|
85
|
+
A plan that selects `runtime_probe` needs at least one `@omp-probe` marker the ledger actually finds on disk. Probe liveness is session-wide, because instrumentation deliberately outlives the round that installed it — the methodology keeps probes in place across a fix so the verification round can reuse them. A verification round that adds no new marker therefore closes normally; a round whose probes were written and then deleted does not.
|
|
67
86
|
|
|
68
|
-
Anything short of that is one automatic nudge
|
|
87
|
+
Anything short of that is one automatic nudge back into the same turn, and the two nudge budgets are separate, so being sent back for missing probes never consumes the budget for a missing closure. When the probe budget is spent the round is handed over as `incomplete` rather than being gated on evidence that does not exist. `agent_inspection`, `user_report`, and `user_artifact` plans need no markers at all and expect no JSONL logs.
|
|
69
88
|
|
|
70
|
-
|
|
89
|
+
### The user-turn widgets
|
|
71
90
|
|
|
72
|
-
|
|
91
|
+
Footer status stays a one-line label (`🐞 round N · reproduce`). The round itself uses two widgets, because the host caps each string-array widget at 10 lines and the commands need to sit next to the prompt:
|
|
92
|
+
|
|
93
|
+
**Above the editor** — what this round asked you to do:
|
|
94
|
+
|
|
95
|
+
```text
|
|
96
|
+
Reproduce the bug now.
|
|
97
|
+
↪ E1 Capture a frame: Capture the failing frame.
|
|
98
|
+
1. Restart the game.
|
|
99
|
+
2. Jump near the pit.
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
**Below the editor** — a dim cheat-sheet of the commands:
|
|
103
|
+
|
|
104
|
+
```text
|
|
105
|
+
Tips:
|
|
106
|
+
/debug-proceed → close this round, analyze 14 log entries, 1 artifact
|
|
107
|
+
/debug-done → bug is fixed: remove probes and summarize
|
|
108
|
+
/debug-evidence <request-id> <path> · /debug-clear · /debug-abort · /debug-status
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
Each fact appears once. The round number lives in the footer, so the exit lines say "this round"; the captured counts live on the `/debug-proceed` line, which is the only thing that acts on them, and they climb in place while you reproduce. The strip is all dim so it sits next to the prompt as a reminder rather than as a second headline — empty vs captured is in the wording (`close this round with nothing captured yet`), not the color. Replying in the editor is still a legal exit; it is just not listed here, because the editor is already where that line would have pointed.
|
|
112
|
+
|
|
113
|
+
Steps are renumbered by the widget, so an unnumbered list from the agent still reads as a sequence, and a step that names `/debug-proceed` or `/debug-done` is dropped: the commands belong under the editor, and the injected contract tells the agent not to write them into the steps in the first place. Lines are clipped by terminal columns rather than by character count, so a step written in Chinese or Japanese is not sent out at double width.
|
|
114
|
+
|
|
115
|
+
The same commands are offered in every mode, including `incomplete`. `/debug-evidence` also accepts `-` in place of a request ID for a file no request asked for; the command's own completion offers it. There is no Proceed/Mark as fixed button: type the slash command.
|
|
116
|
+
|
|
117
|
+
Every round stops at these widgets and you interact through commands only.
|
|
73
118
|
|
|
74
119
|
Pending requests resolve like this:
|
|
75
120
|
|
|
@@ -77,18 +122,28 @@ Pending requests resolve like this:
|
|
|
77
122
|
- 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.
|
|
78
123
|
- `agent_inspection` and `runtime_probe` requests never create user work.
|
|
79
124
|
|
|
80
|
-
If user requests are still pending when you run `/debug-proceed`, the plugin asks "
|
|
125
|
+
If user requests are still pending when you run `/debug-proceed`, the plugin asks "/debug-proceed without all requested evidence?" — confirming is allowed so an unavailable external capture can never deadlock the session; cancelling keeps you on the round. `/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 on a `question` or `incomplete` handoff, where continuing is a judgment call. They wait for the agent to go idle rather than refusing, so an interrupted turn cannot lock the session.
|
|
81
126
|
|
|
82
127
|
## Attaching Evidence Files
|
|
83
128
|
|
|
84
|
-
`/debug-evidence
|
|
129
|
+
`/debug-evidence <request-id|-> <path>` records one user-provided file. The first argument is always a link selector, never part of the path:
|
|
85
130
|
|
|
131
|
+
```text
|
|
132
|
+
/debug-evidence ⏎ lists the selectors under the editor
|
|
133
|
+
/debug-evidence E1 frame.rdc links the file to request E1
|
|
134
|
+
/debug-evidence - trace.log attaches a file no request asked for
|
|
135
|
+
/debug-evidence E1 ⏎ opens a path prompt for E1 (interactive UI only)
|
|
136
|
+
/debug-evidence frame.rdc rejected: names the unrecognised selector and lists the known IDs
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
Typing `/debug-evidence ` shows every selector under the editor with its method, title, and state — `pending`, `satisfied`, or the round it came from — with `-` offered first. Once the selector is settled the completion hands off to the editor's own file-path completion, so the path is completed normally.
|
|
140
|
+
|
|
141
|
+
- Any request ID the session has ever declared is a valid target, including one from an earlier round or one already satisfied, which is exactly what the attach path itself accepts. Selecting `-` attaches the artifact unlinked, and the agent sees it as unassigned evidence it must associate with a request itself.
|
|
142
|
+
- The path keeps its spaces: everything after the selector is the path.
|
|
86
143
|
- 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.
|
|
87
|
-
- 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.
|
|
88
|
-
A path whose first token happens to look like a request ID but does not match one is simply treated as a path.
|
|
89
144
|
- 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.
|
|
90
145
|
- Re-attaching the same resolved path reuses the existing artifact entry and refreshes its metadata and request association.
|
|
91
|
-
- Missing paths, directories, and unreadable files are rejected with the reason, and the ledger stays unchanged.
|
|
146
|
+
- Missing paths, directories, and unreadable files are rejected with the reason, and the ledger stays unchanged. An unrecognised selector is reported as an unrecognised request ID with the known IDs listed, never as a missing file.
|
|
92
147
|
|
|
93
148
|
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.
|
|
94
149
|
|
|
@@ -96,15 +151,17 @@ Example: for a GPU-rendering symptom whose disputed state only exists inside a f
|
|
|
96
151
|
|
|
97
152
|
## Workflow
|
|
98
153
|
1. Run `/debug-mode <problem description>`.
|
|
99
|
-
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
|
|
154
|
+
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 closing the round; 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. Steps are user actions only (reproduce, capture, restart).
|
|
100
155
|
|
|
101
|
-
3.
|
|
156
|
+
3. The Agent closes the round with `hand_off_to_user`, which is what puts the steps in your widget. Follow them in the real application so the instrumented code writes its observations, watching the count on the `/debug-proceed` line 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.
|
|
102
157
|
|
|
103
|
-
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.
|
|
158
|
+
4. Continue with `/debug-proceed [details]` (optionally record a user observation, then evaluate evidence), `/debug-clear` (empty this round's log and reproduce again), `/debug-done` (clean up and summarize), `/debug-evidence` (attach a file), or `/debug-status` (inspect the current round state). Replying normally instead hands the round back to the agent without closing it. Each round stops at the widget; all interaction is command-driven.
|
|
104
159
|
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.
|
|
105
160
|
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.
|
|
106
161
|
|
|
107
|
-
|
|
162
|
+
Every round the Agent runs sees the current stage, whose turn it is, and which closing requirements are still missing, so it never has to infer the state it is driving.
|
|
163
|
+
|
|
164
|
+
Besides `hand_off_to_user`, the extension 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. All four are `essential` while a debug session is running, so the injected contract can order them by name, but they are `defaultInactive` and are only added to the model's schema when `/debug-mode` starts (or a resumed session is already in debug mode). They leave the schema again on `/debug-done` or `/debug-abort`. An ordinary session does not see them.
|
|
108
165
|
|
|
109
166
|
## Runtime Data
|
|
110
167
|
|
|
@@ -124,11 +181,11 @@ That exact stable path is injected into the Agent prompt. The prompt requires ev
|
|
|
124
181
|
|
|
125
182
|
`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.
|
|
126
183
|
|
|
127
|
-
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.
|
|
184
|
+
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. If that rotation fails (typical on Windows while the instrumented app still has `current.jsonl` open), the round stays open, the archive is kept, and the error names the OS reason — close the app and retry. `/debug-clear` truncates `current.jsonl` in place without archiving or opening a new round, so a reproduction you want to throw away does not become the evidence for `/debug-proceed`. 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.
|
|
128
185
|
|
|
129
186
|
## Probe Ledger
|
|
130
187
|
|
|
131
|
-
The plugin tracks every `@omp-probe <id>` marker the Agent writes, resolving each file against the session working directory, and
|
|
188
|
+
The plugin tracks every `@omp-probe <id>` marker the Agent writes, resolving each file against the session working directory, and records which round 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 close on a promise. The closing check counts every live probe in the session, not just this round's, so reusing existing instrumentation for a verification round is not mistaken for having none. Rounds that choose non-probe evidence methods simply add no markers, and cleanup still verifies that no leftover markers remain before finishing.
|
|
132
189
|
|
|
133
190
|
## Install
|
|
134
191
|
|
package/package.json
CHANGED
|
@@ -1,41 +1,41 @@
|
|
|
1
|
-
{
|
|
2
|
-
"name": "@siuver/omp-debug-mode",
|
|
3
|
-
"version": "0.1.
|
|
4
|
-
"type": "module",
|
|
5
|
-
"description": "Evidence-driven, human-in-the-loop debugging with autonomous probes and user-assisted artifacts for oh-my-pi.",
|
|
6
|
-
"license": "MIT",
|
|
7
|
-
"homepage": "https://github.com/Siuver/blackhole/tree/master/plugins/debug-mode#readme",
|
|
8
|
-
"repository": {
|
|
9
|
-
"type": "git",
|
|
10
|
-
"url": "git+https://github.com/Siuver/blackhole.git",
|
|
11
|
-
"directory": "plugins/debug-mode"
|
|
12
|
-
},
|
|
13
|
-
"keywords": [
|
|
14
|
-
"omp",
|
|
15
|
-
"oh-my-pi",
|
|
16
|
-
"extension",
|
|
17
|
-
"debug",
|
|
18
|
-
"cursor",
|
|
19
|
-
"human-in-the-loop"
|
|
20
|
-
],
|
|
21
|
-
"exports": {
|
|
22
|
-
".": "./src/main.ts"
|
|
23
|
-
},
|
|
24
|
-
"files": [
|
|
25
|
-
"src",
|
|
26
|
-
"!src/**/*.test.ts",
|
|
27
|
-
"package.json",
|
|
28
|
-
"README.md",
|
|
29
|
-
"CHANGELOG.md"
|
|
30
|
-
],
|
|
31
|
-
"omp": {
|
|
32
|
-
"name": "debug-mode",
|
|
33
|
-
"description": "Evidence-driven debugging with least-user-intervention methods, runtime probes, and user artifacts.",
|
|
34
|
-
"extensions": [
|
|
35
|
-
"./src/main.ts"
|
|
36
|
-
]
|
|
37
|
-
},
|
|
38
|
-
"peerDependencies": {
|
|
39
|
-
"@oh-my-pi/pi-coding-agent": "*"
|
|
40
|
-
}
|
|
41
|
-
}
|
|
1
|
+
{
|
|
2
|
+
"name": "@siuver/omp-debug-mode",
|
|
3
|
+
"version": "0.1.7",
|
|
4
|
+
"type": "module",
|
|
5
|
+
"description": "Evidence-driven, human-in-the-loop debugging with autonomous probes and user-assisted artifacts for oh-my-pi.",
|
|
6
|
+
"license": "MIT",
|
|
7
|
+
"homepage": "https://github.com/Siuver/blackhole/tree/master/plugins/debug-mode#readme",
|
|
8
|
+
"repository": {
|
|
9
|
+
"type": "git",
|
|
10
|
+
"url": "git+https://github.com/Siuver/blackhole.git",
|
|
11
|
+
"directory": "plugins/debug-mode"
|
|
12
|
+
},
|
|
13
|
+
"keywords": [
|
|
14
|
+
"omp",
|
|
15
|
+
"oh-my-pi",
|
|
16
|
+
"extension",
|
|
17
|
+
"debug",
|
|
18
|
+
"cursor",
|
|
19
|
+
"human-in-the-loop"
|
|
20
|
+
],
|
|
21
|
+
"exports": {
|
|
22
|
+
".": "./src/main.ts"
|
|
23
|
+
},
|
|
24
|
+
"files": [
|
|
25
|
+
"src",
|
|
26
|
+
"!src/**/*.test.ts",
|
|
27
|
+
"package.json",
|
|
28
|
+
"README.md",
|
|
29
|
+
"CHANGELOG.md"
|
|
30
|
+
],
|
|
31
|
+
"omp": {
|
|
32
|
+
"name": "debug-mode",
|
|
33
|
+
"description": "Evidence-driven debugging with least-user-intervention methods, runtime probes, and user artifacts.",
|
|
34
|
+
"extensions": [
|
|
35
|
+
"./src/main.ts"
|
|
36
|
+
]
|
|
37
|
+
},
|
|
38
|
+
"peerDependencies": {
|
|
39
|
+
"@oh-my-pi/pi-coding-agent": "*"
|
|
40
|
+
}
|
|
41
|
+
}
|