@siuver/omp-debug-mode 0.1.5 → 0.1.6

package/src/machine.ts

@@ -1,5 +1,5 @@
 import { parseEvidencePlan } from "./evidence";
-import { decideGate, describeOpenReason } from "./gate";
+import { type GateFacts, MAX_HANDOFF_NUDGES, MAX_PROBE_NUDGES, decideGate, describeHandoff } from "./gate";
 import {
 	CLEANUP_NUDGE,
 	buildFixedMessage,
@@ -12,6 +12,8 @@ import {
 	type DebugState,
 	type EvidenceArtifact,
 	type EvidenceObservation,
+	type EvidenceRequest,
+	type HandoffMode,
 	type Probe,
 	type Round,
 	INACTIVE,
@@ -21,8 +23,10 @@ import {
 	declaresRuntimeProbe,
 	evidenceSummary,
 	freshSession,
-	liveProbeIds,
+	liveProbeCount,
+	needsUserCapture,
 	pendingRequests,
+	roundProbeIds,
 } from "./state";
 
 export const PROMPT_START = "debug-mode-start";
@@ -32,14 +36,25 @@ export const PROMPT_FIXED = "debug-mode-fixed";
 /** Artifact metadata gathered by the shell; the reducer only files it. */
 export type ArtifactCandidate = Omit<EvidenceArtifact, "id" | "addedAt" | "requestId">;
 
+/** No nudges left: used when there is no agent turn to send anything back to. */
+const SPENT_NUDGES = { handoff: MAX_HANDOFF_NUDGES, probes: MAX_PROBE_NUDGES };
+
 export type DebugEvent =
 	| { t: "start"; problem: string; debugDir: string; runId: string; logFile: string }
 	| { t: "turn_started" }
+	/** A user message landed in the transcript — the only thing that ends a user turn. */
+	| { t: "user_replied" }
 	| { t: "assistant_message"; text: string }
+	/** Any tool call: the progress signal the reminder guard waits for. */
+	| { t: "tool_used" }
 	| { t: "probes_found"; probes: Probe[] }
 	| { t: "ledger_synced"; probes: Probe[] }
 	| { t: "runs_observed"; runHistory: string[]; logCounts: Record<string, number> }
 	| { t: "turn_settled" }
+	/** An explicit `hand_off_to_user` call: intent the machine can trust. */
+	| { t: "handoff"; mode: HandoffMode; steps: string[]; plan: EvidenceRequest[] | null }
+	/** The user takes the turn back from a round that never settled. */
+	| { t: "reclaim" }
 	| { t: "proceed"; runId: string; logCount: number; hypotheses: string; details?: string; now: number }
 	| { t: "mark_fixed" }
 	| { t: "attach_artifact"; candidate: ArtifactCandidate; requestId: string | null; now: number }
@@ -94,18 +109,25 @@ export function reduce(state: DebugState, event: DebugEvent): Transition {
 
 	switch (event.t) {
 		case "turn_started":
-			// A reply to an open round hands the turn back to the agent. The
-			// reproduction gate deliberately survives ordinary conversation.
-			if (session.stage !== "open" && !session.turnProduced) return unchanged(session);
-			return unchanged({
-				...session,
-				stage: session.stage === "open" ? "investigating" : session.stage,
-				turnProduced: false,
-			});
+			// Deliberately stage-blind. A turn can start without the user doing
+			// anything — a todo reminder, a plan nudge or any other host
+			// continuation resumes the agent loop, which starts a turn while the
+			// round is still with the user. Reading "a turn began" as "the user
+			// replied" is what let those continuations take the user's turn away.
+			return session.turnProduced ? unchanged({ ...session, turnProduced: false }) : unchanged(session);
+
+		case "user_replied":
+			// A reply at a handoff hands the round back to the agent. Keeping the
+			// user stage through the turn would make the entire turn invisible to
+			// the machine and silently discard the plan and steps it produced.
+			return unchanged(session.stage === "user_turn" ? reopenRound(session) : session);
 
 		case "assistant_message":
 			return unchanged(absorbAssistantText(session, event.text));
 
+		case "tool_used":
+			return unchanged(clearNudgeWait(session));
+
 		case "probes_found": {
 			const fresh = event.probes.filter(probe => !session.probes.some(known => known.id === probe.id));
 			if (fresh.length === 0) return unchanged(session);
@@ -130,6 +152,12 @@ export function reduce(state: DebugState, event: DebugEvent): Transition {
 		case "turn_settled":
 			return settle(session);
 
+		case "handoff":
+			return applyHandoff(session, event);
+
+		case "reclaim":
+			return reclaim(session);
+
 		case "proceed":
 			return advance(session, event);
 
@@ -149,6 +177,31 @@ export function reduce(state: DebugState, event: DebugEvent): Transition {
 	}
 }
 
+/**
+ * Give the round back to the agent. Nudge budgets are per agent turn rather
+ * than per round: a round the user replied to must still be repairable, or one
+ * spent budget would silence every later turn in the same round.
+ */
+function reopenRound(session: ActiveState): ActiveState {
+	const round = currentRound(session);
+	return withRound(
+		{ ...session, stage: "investigating", turnProduced: false },
+		{ ...round, handoff: null, nudges: { handoff: 0, probes: 0 }, awaitingProgress: false },
+	);
+}
+
+/**
+ * Clear the reminder guard. A tool call means the agent acted on the reminder
+ * instead of restating itself, so the next settle may remind it again; a turn
+ * that only produces more prose keeps the guard set and is handed over.
+ */
+function clearNudgeWait(session: ActiveState): ActiveState {
+	if (session.stage !== "investigating") return session;
+	const round = currentRound(session);
+	if (!round.awaitingProgress) return session;
+	return withRound(session, { ...round, awaitingProgress: false });
+}
+
 /** Record the round artefacts a settled-but-not-yet-judged turn produced. */
 function absorbAssistantText(session: ActiveState, text: string): ActiveState {
 	const round = currentRound(session);
@@ -157,70 +210,104 @@ function absorbAssistantText(session: ActiveState, text: string): ActiveState {
 	const next: Round = {
 		...round,
 		reproductionSteps: steps.length > 0 ? steps : round.reproductionSteps,
-		plan: plan.found ? (plan.valid ? plan.requests : null) : round.plan,
+		// A later malformed block must never erase a plan that already validated:
+		// the round would lose evidence requests the user was already shown.
+		plan: plan.valid ? plan.requests : round.plan,
 	};
 	const roundChanged = next.reproductionSteps !== round.reproductionSteps || next.plan !== round.plan;
 	if (!roundChanged) return session.turnProduced ? session : { ...session, turnProduced: true };
 	return withRound({ ...session, turnProduced: true }, next);
 }
 
+function gateFacts(session: ActiveState, round: Round): GateFacts {
+	return {
+		round: round.index,
+		hasReproductionSteps: round.reproductionSteps.length > 0,
+		hasEvidencePlan: round.plan !== null,
+		declaresRuntimeProbe: declaresRuntimeProbe(round),
+		needsUserCapture: needsUserCapture(round),
+		liveProbes: liveProbeCount(session),
+		probesAddedThisRound: roundProbeIds(session, round).length,
+		nudges: round.nudges,
+		awaitingProgress: round.awaitingProgress,
+	};
+}
+
 function settle(session: ActiveState): Transition {
 	if (session.stage === "cleaning_up") return finishCleanup(session);
 	if (session.stage !== "investigating" || !session.turnProduced) return unchanged(session);
 
 	const round = currentRound(session);
-	const decision = decideGate({
-		hasReproductionSteps: round.reproductionSteps.length > 0,
-		hasEvidencePlan: round.plan !== null,
-		declaresRuntimeProbe: declaresRuntimeProbe(round),
-		liveProbes: liveProbeIds(session, round).length,
-		nudges: round.nudges,
-	});
+	const decision = decideGate(gateFacts(session, round));
 
 	if (decision.kind === "nudge") {
 		const nudges =
 			decision.budget === "probes"
 				? { ...round.nudges, probes: round.nudges.probes + 1 }
-				: { ...round.nudges, tags: round.nudges.tags + 1 };
+				: { ...round.nudges, handoff: round.nudges.handoff + 1 };
 		return {
-			state: withRound(session, { ...round, nudges }),
+			state: withRound(session, { ...round, nudges, awaitingProgress: true }),
 			effects: [{ kind: "continue", context: decision.context }],
 		};
 	}
 
-	if (decision.kind === "open") {
-		return {
-			state: withRound({ ...session, stage: "open" }, { ...round, openReason: decision.reason }),
-			effects: [
-				{
-					kind: "notify",
-					level: decision.reason === "awaiting_reply" ? "info" : "warning",
-					text: describeOpenReason(decision.reason, round.index),
-				},
-			],
-		};
-	}
+	return handOff(session, decision.mode, decision.missingPlan);
+}
 
-	const gated = withRound({ ...session, stage: "awaiting_evidence" }, { ...round, openReason: null });
-	return { state: gated, effects: [{ kind: "notify", ...gateNotice(gated, decision.missingPlan) }] };
+/**
+ * Move the round to the user. Every settled turn ends here: the mode only
+ * changes the wording, so a mode the agent misjudged can never make a command
+ * illegal. The notify text leads with the same sentence as the widget so the
+ * transcript and the widget cannot disagree about whose move it is.
+ */
+function handOff(session: ActiveState, mode: HandoffMode, missingPlan: boolean): Transition {
+	const round = currentRound(session);
+	const next = withRound({ ...session, stage: "user_turn" }, { ...round, handoff: mode });
+	const pending = pendingRequests(next);
+	const detail = pending.length > 0 ? ` Pending: ${pending.map(request => request.id).join(", ")}.` : "";
+	return {
+		state: next,
+		effects: [
+			{
+				kind: "notify",
+				level: mode === "incomplete" || missingPlan ? "warning" : "info",
+				text: `${describeHandoff(mode, round.index, missingPlan)}${detail}`,
+			},
+		],
+	};
 }
 
-function gateNotice(session: ActiveState, missingPlan: boolean): { level: "info" | "warning"; text: string } {
+/**
+ * An explicit handoff call. The tool has already validated its arguments, so
+ * this records the declared plan and steps and hands over without consulting
+ * the gate: the agent said what it wants, and guessing from its prose is the
+ * failure mode the tool exists to remove.
+ */
+function applyHandoff(session: ActiveState, event: Extract<DebugEvent, { t: "handoff" }>): Transition {
+	if (session.stage !== "investigating") return unchanged(session);
 	const round = currentRound(session);
-	if (missingPlan) {
-		return {
-			level: "warning",
-			text: `Debug round ${round.index} paused, but it added no probes and declared no evidence plan — this round cannot produce runtime evidence. Use /debug-proceed to ask for instrumentation.`,
-		};
-	}
-	const pending = pendingRequests(session, round);
-	if (pending.length > 0) {
-		return {
-			level: "info",
-			text: `Debug round ${round.index} paused. User evidence requested (${pending.length} pending: ${pending.map(r => r.id).join(", ")}) — attach via /debug-evidence <request-id> <path>, then press Proceed.`,
-		};
-	}
-	return { level: "info", text: `Debug round ${round.index} paused. Reproduce the bug, then press Proceed.` };
+	const updated: Round = {
+		...round,
+		plan: event.plan ?? round.plan,
+		reproductionSteps: event.steps.length > 0 ? event.steps : round.reproductionSteps,
+	};
+	const staged = withRound({ ...session, turnProduced: true }, updated);
+	const expectsPlan = event.mode !== "question";
+	return handOff(staged, event.mode, expectsPlan && updated.plan === null);
+}
+
+/**
+ * Classify a round whose turn never settled. An aborted turn never reaches
+ * `session_stop`, so without this the stage would stay `investigating` and
+ * every debug command would refuse for the rest of the session.
+ */
+function reclaim(session: ActiveState): Transition {
+	if (session.stage !== "investigating") return unchanged(session);
+	const round = currentRound(session);
+	// There is no turn left to continue, so no nudge is available.
+	const decision = decideGate({ ...gateFacts(session, round), nudges: SPENT_NUDGES });
+	if (decision.kind === "nudge") return handOff(session, "incomplete", round.plan === null);
+	return handOff(session, decision.mode, decision.missingPlan);
 }
 
 /** Cleanup may only finish once the ledger is actually empty. */

package/src/main.ts

@@ -1,24 +1,24 @@
-/**
- * Debug Mode Extension — Cursor-style human-in-the-loop debugging for omp.
- *
- * State machine (matches Cursor Debug Mode):
- *   IDLE → /debug-mode <problem>
- *   → agent writes 3-5 hypotheses and @omp-probe instrumentation (no product fix)
- *   → WAITING_REPRO: agent stops; user reproduces out-of-band
- *   → Proceed/add details → agent reads logs, evaluates hypotheses, fixes only
- *     with evidence, keeps probes, and asks for a verification reproduce → loop
- *   → Mark as fixed → agent removes probes + summarizes → teardown (logs deleted)
- *
- * - `state.ts` — persisted round state and the injected blackboard
- * - `probes.ts` — `@omp-probe` ledger and its on-disk ground truth
- * - `log-files.ts` — stable `<cwd>/.omp/debug/current.jsonl` and run archival
- * - `methodology.ts` — the Cursor Debug Mode prompt contract
- * - `debug-mode.ts` — state machine, commands, and lifecycle wiring
- */
-import type { ExtensionAPI } from "@oh-my-pi/pi-coding-agent";
-import { registerDebugMode } from "./debug-mode";
-
-export default function debugModeExtension(pi: ExtensionAPI) {
-	pi.setLabel("Debug Mode");
-	registerDebugMode(pi);
-}
+/**
+ * Debug Mode Extension — Cursor-style human-in-the-loop debugging for omp.
+ *
+ * State machine (matches Cursor Debug Mode):
+ *   IDLE → /debug-mode <problem>
+ *   → agent writes 3-5 hypotheses and @omp-probe instrumentation (no product fix)
+ *   → WAITING_REPRO: agent stops; user reproduces out-of-band
+ *   → /debug-proceed [details] → agent reads logs, evaluates hypotheses, fixes only
+ *     with evidence, keeps probes, and asks for a verification reproduce → loop
+ *   → /debug-done → agent removes probes + summarizes → teardown (logs deleted)
+ *
+ * - `state.ts` — persisted round state and the injected blackboard
+ * - `probes.ts` — `@omp-probe` ledger and its on-disk ground truth
+ * - `log-files.ts` — stable `<cwd>/.omp/debug/current.jsonl` and run archival
+ * - `methodology.ts` — the Cursor Debug Mode prompt contract
+ * - `debug-mode.ts` — state machine, commands, and lifecycle wiring
+ */
+import type { ExtensionAPI } from "@oh-my-pi/pi-coding-agent";
+import { registerDebugMode } from "./debug-mode";
+
+export default function debugModeExtension(pi: ExtensionAPI) {
+	pi.setLabel("Debug Mode");
+	registerDebugMode(pi);
+}

package/src/methodology.ts

@@ -1,7 +1,26 @@
-export const PROCEED_REMINDER = "Press Proceed/Mark as fixed when done.";
+export const PROCEED_REMINDER =
+	"When done, run /debug-proceed to analyze this round, or /debug-done if the bug is fixed.";
 
 export const EVIDENCE_PLAN_TAG = "evidence_plan";
 
+/** The Agent tool that ends an agent turn and hands the round to the user. */
+export const HANDOFF_TOOL = "hand_off_to_user";
+
+/**
+ * Stated wherever a round is closed. Prose cannot move the session: the model
+ * announcing a reproduction is not the same event as the session reaching the
+ * user, and conflating them is what leaves a round unclosed while the user has
+ * already been told to act.
+ */
+export const HANDOFF_RULE =
+	`Close every round by calling ${HANDOFF_TOOL} as your last action. Pass mode ("reproduce" when the user must run ` +
+	'the app, "capture" when they only supply a report or file, "question" when you need an answer before you can ' +
+	"plan), the evidence plan array, and the numbered steps the USER performs now. That tool call is the only thing " +
+	"that hands the session to the user, and it replies with exactly what to fix when an argument is wrong, so a " +
+	`rejected call is repaired in this turn. <${EVIDENCE_PLAN_TAG}> and <reproduction_steps> in prose are still read ` +
+	"for their contents, but they never close a round: a turn that stops without the tool call is sent straight back " +
+	"to you to make it.";
+
 /** The least-user-intervention evidence method ordering, verbatim for prompts. */
 export const MINIMIZE_USER_INTERVENTION =
 	"MINIMIZE USER INTERVENTION. Choose the cheapest reliable evidence method per hypothesis, in this exact order: " +
@@ -60,9 +79,10 @@ This is OMP Debug Mode. Follow the steps in order. Do not skip them.
    - The extension truncates the current log file at the start of each round.
      Do not delete, rename, or overwrite that file yourself.
 
-4. Close the round only after step 3 is done for any runtime_probe plan. Emit
-   exactly one <${EVIDENCE_PLAN_TAG}> block containing a
-   non-empty JSON array covering EVERY hypothesis:
+4. Close the round only after step 3 is done for any runtime_probe plan.
+   ${HANDOFF_RULE}
+   The plan is a non-empty JSON array covering EVERY hypothesis, in the same
+   shape accepted inside a legacy <${EVIDENCE_PLAN_TAG}> block:
    <${EVIDENCE_PLAN_TAG}>
    [{"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_TAG}>
@@ -70,18 +90,22 @@ This is OMP Debug Mode. Follow the steps in order. Do not skip them.
    Use artifactHint only for user_artifact (expected file kind). Give actionable
    numbered capture/report instructions in instructions.
 
-5. Ask the user to reproduce (or capture/report, per the plan). End your response
-   with a <reproduction_steps> numbered list (no header inside the tag) describing
-   the single combined reproduction/capture sequence the USER performs now, and
-   this exact sentence after the tag: "${PROCEED_REMINDER}"
+5. Ask the user to reproduce (or capture/report, per the plan). Pass the single
+   combined reproduction/capture sequence the USER performs now as the steps
+   argument of ${HANDOFF_TOOL} — the widget the user reads is built from that
+   call, not from your prose. A <reproduction_steps> numbered list (no header
+   inside the tag) followed by "${PROCEED_REMINDER}" is read as content but
+   closes nothing, so make the call even when you also wrote the prose.
    ${CLOSE_ROUND_RULES}
-   Never say "click". Never ask the user to reply "done". Remind them to restart
-   the app or service if the instrumented code would otherwise be stale.
+   Never say "click" or "press Proceed": those buttons do not exist. Name
+   /debug-proceed and /debug-done by those exact commands. Never ask the user to
+   reply "done". Remind them to restart the app or service if the instrumented
+   code would otherwise be stale.
    Then STOP. The user reproduces out-of-band.
    No logs may be expected for user_report/user_artifact plans: evaluate the
    requested user evidence instead of treating absent probes as a failed round.
 
-6. After Proceed: call list_debug_evidence, then read logs with get_debug_logs
+6. After /debug-proceed: call list_debug_evidence, then read logs with get_debug_logs
    (previous=true for the completed run). Evaluate EACH hypothesis as CONFIRMED,
    REJECTED, or INCONCLUSIVE citing the selected evidence method: hypothesis ID
    plus log-line numbers, a submitted observation, or an attached artifact/report
@@ -98,7 +122,7 @@ This is OMP Debug Mode. Follow the steps in order. Do not skip them.
 8. After a fix, ask the user to reproduce again. Compare before/after logs with
    cited entries. Do not claim success without that proof.
 
-9. If verification proves success and the user chooses Mark as fixed: remove
+9. If verification proves success and the user runs /debug-done: remove
    every probe, verify with list_debug_probes that the ledger is empty, then
    summarize the root cause and the final fix in 1-2 lines.
 
@@ -121,9 +145,12 @@ export function buildStartMessage(problem: string, logFile: string): string {
 		"Begin round 1: generate 3-5 precise hypotheses, decide an evidence method for each, and do NOT apply a product fix yet. " +
 		CLOSE_ROUND_RULES +
 		" " +
+		HANDOFF_RULE +
+		" " +
 		"Call list_debug_evidence whenever you need the request/observation/artifact ledger. " +
 		"Cite evidence as hypothesis ID plus log-line number or attached observation/artifact/report path. " +
-		`Then close with exactly one <${EVIDENCE_PLAN_TAG}> JSON block, then <reproduction_steps> and "${PROCEED_REMINDER}" then STOP.`
+		`Then close with ${HANDOFF_TOOL} — prose alone never closes a round, so make the call even if you also wrote ` +
+		`a <${EVIDENCE_PLAN_TAG}> block — tell the user "${PROCEED_REMINDER}" and STOP.`
 	);
 }
 
@@ -158,7 +185,9 @@ export function buildProceedMessage(args: {
 		"If a previous fix failed, first revert code changes from rejected hypotheses. " +
 		CLOSE_ROUND_RULES +
 		" " +
-		`Then end with <${EVIDENCE_PLAN_TAG}>, <reproduction_steps> and "${PROCEED_REMINDER}" then STOP.`
+		HANDOFF_RULE +
+		" " +
+		`Then end with ${HANDOFF_TOOL} — prose alone never closes a round — tell the user "${PROCEED_REMINDER}" and STOP.`
 	);
 }
 
@@ -174,7 +203,9 @@ The user confirmed the fix. Only two things remain:
    \`#region agent log\` wrapper, then call list_debug_probes and confirm the
    ledger is empty. Keep the proven fix; remove nothing else.
 2. Summarize in 1-2 lines: the root cause and the fix that is staying.
-Do not add probes, form new hypotheses, or ask for another reproduction.`;
+Do not add probes, form new hypotheses, or ask for another reproduction, and do
+not call ${HANDOFF_TOOL}: cleanup ends when the ledger is empty and you have
+summarized.`;
 
 /** Sent back into a cleanup turn that ended with probes still in the code. */
 export const CLEANUP_NUDGE =