@siuver/omp-debug-mode 0.1.4 → 0.1.6

package/src/state.ts

@@ -4,7 +4,14 @@ export const DEBUG_ENTRY = "com.omp.debug-mode.state";
 /** Custom message that carries the blackboard + methodology into the model. */
 export const DEBUG_CONTEXT_TYPE = "debug-mode-context";
 
-export type Phase = "idle" | "round" | "waiting" | "cleanup";
+/**
+ * Whose move it is, and nothing else. There is exactly one user stage: a turn
+ * the agent has handed back is the user's regardless of how well the agent
+ * closed the round, so command legality never depends on protocol compliance.
+ */
+export type Stage = "investigating" | "user_turn" | "cleaning_up";
+
+export type EvidenceMethod = "agent_inspection" | "runtime_probe" | "user_report" | "user_artifact";
 
 export interface Probe {
 	id: string;
@@ -12,8 +19,6 @@ export interface Probe {
 	round: number;
 }
 
-export type EvidenceMethod = "agent_inspection" | "runtime_probe" | "user_report" | "user_artifact";
-
 export interface EvidenceRequest {
 	/** Model-authored request identifier, unique within a plan. */
 	id: string;
@@ -27,7 +32,6 @@ export interface EvidenceRequest {
 	instructions: string[];
 	/** Expected file kind when method is user_artifact. */
 	artifactHint?: string;
-	round: number;
 }
 
 export interface EvidenceArtifact {
@@ -49,47 +53,186 @@ export interface EvidenceObservation {
 	addedAt: number;
 }
 
-export interface DebugState {
-	active: boolean;
-	phase: Phase;
-	problem: string;
-	round: number;
+/**
+ * How the agent handed the turn back. This is wording and guidance only: every
+ * mode is the same `user_turn` stage and allows the same commands, so a mode
+ * the agent got wrong can never make a legitimate command illegal.
+ */
+export type HandoffMode = "reproduce" | "capture" | "question" | "incomplete";
+
+/**
+ * One evidence round. Round membership is structural: everything scoped to a
+ * round lives here instead of being filtered out of a session-wide array by a
+ * mutable counter, so starting a round cannot forget to reset a field.
+ */
+export interface Round {
+	index: number;
 	runId: string | null;
+	/** Parsed `<evidence_plan>`; null until a valid plan arrives. */
+	plan: EvidenceRequest[] | null;
+	reproductionSteps: string[];
+	/** Ledger ids of probes introduced while this round was investigating. */
+	probeIds: string[];
+	/** Separate budgets: a probe nudge must not consume the closing one. */
+	nudges: { handoff: number; probes: number };
+	/**
+	 * A reminder went out and no tool call has landed since. One reminder per
+	 * round of visible progress: a model that answers every reminder with more
+	 * prose would otherwise spend the whole budget and delay the user by three
+	 * turns to reach the same handoff.
+	 */
+	awaitingProgress: boolean;
+	/** Set while the round sits with the user; null while the agent has the turn. */
+	handoff: HandoffMode | null;
+}
+
+export interface DebugSession {
+	stage: Stage;
+	problem: string;
+	debugDir: string | null;
+	/** Every round in order; the last entry is the current one. */
+	rounds: Round[];
+	/** Session-wide probe ledger; a probe outlives the round that created it. */
+	probes: Probe[];
 	/** Every run in creation order; the last entry is always the active run. */
 	runHistory: string[];
-	probes: Probe[];
-	debugDir: string | null;
 	logCounts: Record<string, number>;
-	hasRoundContent: boolean;
-	cleanupReady: boolean;
-	reproductionSteps: string[];
-	evidenceRequests: EvidenceRequest[];
-	evidenceArtifacts: EvidenceArtifact[];
-	evidenceObservations: EvidenceObservation[];
-	gateNudges: number;
+	artifacts: EvidenceArtifact[];
+	observations: EvidenceObservation[];
+	/** An assistant message landed during the current agent turn. */
+	turnProduced: boolean;
+	/** How often cleanup was sent back to finish removing probes. */
+	cleanupNudges: number;
 }
 
-export function freshState(): DebugState {
+/**
+ * `active` is the discriminant, so the cheap `if (!state.active) return` guard
+ * in hot handlers doubles as the type narrowing and there is no second source
+ * of truth for "is debug mode running".
+ */
+export type DebugState = { active: false } | ({ active: true } & DebugSession);
+
+export const INACTIVE: DebugState = { active: false };
+
+export function blankRound(index: number, runId: string | null): Round {
 	return {
-		active: false,
-		phase: "idle",
-		problem: "",
-		round: 0,
-		runId: null,
-		runHistory: [],
-		probes: [],
-		debugDir: null,
-		logCounts: {},
-		hasRoundContent: false,
-		cleanupReady: false,
+		index,
+		runId,
+		plan: null,
 		reproductionSteps: [],
-		gateNudges: 0,
-		evidenceRequests: [],
-		evidenceArtifacts: [],
-		evidenceObservations: [],
+		probeIds: [],
+		nudges: { handoff: 0, probes: 0 },
+		awaitingProgress: false,
+		handoff: null,
+	};
+}
+
+export function freshSession(problem: string, debugDir: string | null, runId: string | null): DebugSession {
+	return {
+		stage: "investigating",
+		problem,
+		debugDir,
+		rounds: [blankRound(1, runId)],
+		probes: [],
+		runHistory: runId ? [runId] : [],
+		logCounts: runId ? { [runId]: 0 } : {},
+		artifacts: [],
+		observations: [],
+		turnProduced: false,
+		cleanupNudges: 0,
+	};
+}
+
+export function currentRound(session: DebugSession): Round {
+	return session.rounds[session.rounds.length - 1] ?? blankRound(1, null);
+}
+
+export function activeRunId(session: DebugSession): string | null {
+	return currentRound(session).runId;
+}
+
+export function logFileFor(session: DebugSession, run: string | null = activeRunId(session)): string | null {
+	return resolveRunLogFile(session.debugDir, run, activeRunId(session));
+}
+
+/**
+ * Every probe the ledger still finds on disk, session-wide. Instrumentation
+ * deliberately outlives the round that installed it — the methodology keeps
+ * probes in place across a fix so the verification round can reuse them — so a
+ * round-scoped count would report "nothing instrumented" on exactly the rounds
+ * that are best instrumented.
+ */
+export function liveProbeCount(session: DebugSession): number {
+	return session.probes.length;
+}
+
+/** Probes this round introduced that are still in the ledger (i.e. still on disk). */
+export function roundProbeIds(session: DebugSession, round: Round = currentRound(session)): string[] {
+	return round.probeIds.filter(id => session.probes.some(probe => probe.id === id));
+}
+
+export function declaresRuntimeProbe(round: Round): boolean {
+	return (round.plan ?? []).some(request => request.method === "runtime_probe");
+}
+
+/** The plan asks the user to report or capture something themselves. */
+export function needsUserCapture(round: Round): boolean {
+	return (round.plan ?? []).some(
+		request => request.method === "user_report" || request.method === "user_artifact",
+	);
+}
+
+/** Requests whose method is satisfied by the agent alone, so they never gate on the user. */
+export function hasNonProbeEvidence(round: Round): boolean {
+	return (round.plan ?? []).some(request => request.method !== "runtime_probe");
+}
+
+/**
+ * Round requests that still need something from the user: a `user_artifact`
+ * request until a linked artifact exists, a `user_report` request until an
+ * observation names it. Agent-collected methods never create user work.
+ */
+export function pendingRequests(session: DebugSession, round: Round = currentRound(session)): EvidenceRequest[] {
+	return (round.plan ?? []).filter(request => {
+		if (request.method === "user_artifact") {
+			return !session.artifacts.some(artifact => artifact.requestId === request.id);
+		}
+		if (request.method === "user_report") {
+			return !session.observations.some(observation => observation.requestIds.includes(request.id));
+		}
+		return false;
+	});
+}
+
+/** Every request the session has ever declared, newest round last. */
+export function allRequests(session: DebugSession): EvidenceRequest[] {
+	return session.rounds.flatMap(round => round.plan ?? []);
+}
+
+/** Decoupled evidence projection so ledger formatting never depends on the state shape. */
+export interface EvidenceView {
+	requests: readonly EvidenceRequest[];
+	observations: readonly EvidenceObservation[];
+	artifacts: readonly EvidenceArtifact[];
+}
+
+export function evidenceView(session: DebugSession, round?: Round | null): EvidenceView {
+	return {
+		requests: round === undefined ? allRequests(session) : (round?.plan ?? []),
+		observations: session.observations,
+		artifacts: session.artifacts,
 	};
 }
 
+/** One-line evidence status used by messages, the gate and the UI. */
+export function evidenceSummary(session: DebugSession, round: Round = currentRound(session)): string {
+	const requests = round.plan ?? [];
+	if (requests.length === 0) return "no evidence requests this round";
+	const pending = pendingRequests(session, round);
+	const methods = requests.map(request => `${request.id}:${request.method}`).join(", ");
+	return `${requests.length} request(s) [${methods}], ${pending.length} pending user action(s), ${session.artifacts.length} artifact(s), ${session.observations.length} observation(s)`;
+}
+
 /** Order run ids by round number, then by the base36 creation stamp. */
 export function compareRunIds(a: string, b: string): number {
 	const parse = (id: string): [number, string] => {
@@ -144,88 +287,253 @@ export function resolveRun(
 	return { run: currentRun, note: null };
 }
 
-export function logFileFor(s: DebugState, run = s.runId): string | null {
-	return resolveRunLogFile(s.debugDir, run, s.runId);
-}
-
 /**
- * Keep only the newest copy of a custom-type injection. `before_agent_start`
- * re-injects a fresh blackboard every turn; `context` runs afterwards on the
- * combined history, so deleting every match would drop the copy that was just
- * added and the model would never see it.
+ * Leave the context holding exactly one, current copy of a custom-type
+ * injection: drop every stale copy and rewrite the survivor's content.
+ *
+ * Both halves are load-bearing. `before_agent_start` appends a fresh copy every
+ * prompt, so keeping all of them would grow the context without bound — but it
+ * does not fire at all when the host resumes the agent loop itself, so a turn
+ * started by a reminder or a nudge would otherwise read whatever the previous
+ * turn was told. Rewriting here, where the request is actually assembled, is
+ * the only point that no path into the model can skip.
+ *
+ * Returns null when the context already says the right thing, so an unchanged
+ * request is passed through untouched.
  */
-export function keepLatestCustomType<M extends { role?: string; customType?: string }>(
+export function syncCustomType<M extends { role?: string; customType?: string; content?: unknown }>(
 	messages: readonly M[],
 	customType: string,
-): M[] {
+	content: string | null,
+): M[] | null {
+	const isCopy = (message: M | undefined): boolean =>
+		message?.role === "custom" && message.customType === customType;
 	let last = -1;
+	let copies = 0;
+	for (let i = 0; i < messages.length; i++) {
+		if (!isCopy(messages[i])) continue;
+		last = i;
+		copies++;
+	}
+	if (last < 0) return null;
+	const rewrite = content !== null && messages[last]?.content !== content;
+	if (copies === 1 && !rewrite) return null;
+	const kept: M[] = [];
 	for (let i = 0; i < messages.length; i++) {
-		const message = messages[i];
-		if (message?.role === "custom" && message.customType === customType) last = i;
+		const message = messages[i] as M;
+		if (!isCopy(message)) {
+			kept.push(message);
+			continue;
+		}
+		if (i !== last) continue;
+		kept.push(rewrite ? ({ ...message, content } as M) : message);
 	}
-	if (last < 0) return [...messages];
-	return messages.filter((message, index) => !(message.role === "custom" && message.customType === customType && index !== last));
+	return kept;
 }
 
+const STAGES: readonly Stage[] = ["investigating", "user_turn", "cleaning_up"];
+const HANDOFF_MODES: readonly HandoffMode[] = ["reproduce", "capture", "question", "incomplete"];
+
+/** Pre-`user_turn` stage names and the handoff each one implied. */
+const LEGACY_STAGES: Readonly<Record<string, { stage: Stage; handoff: HandoffMode | null }>> = {
+	open: { stage: "user_turn", handoff: null },
+	awaiting_evidence: { stage: "user_turn", handoff: "reproduce" },
+};
+
+/** Pre-`handoff` reasons, mapped onto the mode that carries the same guidance. */
+const LEGACY_HANDOFFS: Readonly<Record<string, HandoffMode>> = {
+	awaiting_reply: "question",
+	probes_missing: "incomplete",
+	unclosed: "incomplete",
+};
+
+function asArray<T>(value: unknown): T[] {
+	return Array.isArray(value) ? (value as T[]) : [];
+}
 
-/** Replace the evidence requests that belong to one round. */
-export function replaceRoundEvidenceRequests(
-	state: DebugState,
-	round: number,
-	requests: EvidenceRequest[],
-): DebugState {
+function asRecord(value: unknown): Record<string, unknown> {
+	return typeof value === "object" && value !== null ? (value as Record<string, unknown>) : {};
+}
+
+function reviveHandoff(raw: unknown): HandoffMode | null {
+	if (typeof raw !== "string") return null;
+	if (HANDOFF_MODES.includes(raw as HandoffMode)) return raw as HandoffMode;
+	return LEGACY_HANDOFFS[raw] ?? null;
+}
+
+function reviveRound(raw: unknown, fallbackIndex: number): Round {
+	const record = asRecord(raw);
+	const nudges = asRecord(record.nudges);
 	return {
-		...state,
-		evidenceRequests: state.evidenceRequests.filter(request => request.round !== round).concat(requests),
+		index: typeof record.index === "number" ? record.index : fallbackIndex,
+		runId: typeof record.runId === "string" ? record.runId : null,
+		plan: Array.isArray(record.plan) ? (record.plan as EvidenceRequest[]) : null,
+		reproductionSteps: asArray<string>(record.reproductionSteps),
+		probeIds: asArray<string>(record.probeIds),
+		nudges: {
+			// `tags` is the pre-tool budget name, when prose was still a closure.
+			handoff: numberOr(nudges.handoff, numberOr(nudges.tags, 0)),
+			probes: numberOr(nudges.probes, 0),
+		},
+		// Never restored: no agent turn survives a restart, so nothing is pending.
+		awaitingProgress: false,
+		handoff: reviveHandoff(record.handoff ?? record.openReason),
 	};
 }
 
+function numberOr(value: unknown, fallback: number): number {
+	return typeof value === "number" ? value : fallback;
+}
+
 /**
- * Round requests that still need something from the user: a `user_artifact`
- * request until a linked artifact exists, a `user_report` request until an
- * observation names it. Agent-collected methods never create user work.
+ * Rebuild persisted state, tolerating the pre-`user_turn` stage names and the
+ * pre-`rounds` layout so a session that was mid-debug across an upgrade keeps
+ * working. Anything unrecognised — including a persisted `investigating`, since
+ * no agent turn survives a restore — resolves to `user_turn`, because the user
+ * must always be able to act on a restored investigation.
  */
-export function pendingEvidenceRequests(state: DebugState, round = state.round): EvidenceRequest[] {
-	return state.evidenceRequests.filter(request => {
-		if (request.round !== round) return false;
-		if (request.method === "user_artifact") {
-			return !state.evidenceArtifacts.some(artifact => artifact.requestId === request.id);
-		}
-		if (request.method === "user_report") {
-			return !state.evidenceObservations.some(observation => observation.requestIds.includes(request.id));
-		}
-		return false;
-	});
+export function reviveState(data: unknown): DebugState {
+	const record = asRecord(data);
+	if (record.active !== true) return INACTIVE;
+	const problem = typeof record.problem === "string" ? record.problem : "";
+	const debugDir = typeof record.debugDir === "string" ? record.debugDir : null;
+	const probes = asArray<Probe>(record.probes);
+	const logCounts = asRecord(record.logCounts) as Record<string, number>;
+	const restored = restoreStage(record);
+
+	const rounds = Array.isArray(record.rounds)
+		? record.rounds.map((round, i) => reviveRound(round, i + 1))
+		: [legacyRound(record, probes)];
+	const resolved = rounds.length > 0 ? rounds : [blankRound(1, null)];
+	const last = resolved[resolved.length - 1] as Round;
+	if (restored.stage === "user_turn" && last.handoff === null) {
+		resolved[resolved.length - 1] = { ...last, handoff: restored.handoff ?? "incomplete" };
+	}
+
+	return {
+		active: true,
+		stage: restored.stage,
+		problem,
+		debugDir,
+		rounds: resolved,
+		probes,
+		runHistory: asArray<string>(record.runHistory),
+		logCounts,
+		artifacts: asArray<EvidenceArtifact>(record.artifacts ?? record.evidenceArtifacts),
+		observations: asArray<EvidenceObservation>(record.observations ?? record.evidenceObservations),
+		turnProduced: false,
+		cleanupNudges: typeof record.cleanupNudges === "number" ? record.cleanupNudges : 0,
+	};
 }
 
-/** One-line evidence status used by messages, the gate and the UI. */
-export function evidenceSummary(state: DebugState, round = state.round): string {
-	const requests = state.evidenceRequests.filter(request => request.round === round);
-	if (requests.length === 0) return "no evidence requests this round";
-	const pending = pendingEvidenceRequests(state, round);
-	const methods = requests.map(request => `${request.id}:${request.method}`).join(", ");
-	return `${requests.length} request(s) [${methods}], ${pending.length} pending user action(s), ${state.evidenceArtifacts.length} artifact(s), ${state.evidenceObservations.length} observation(s)`;
+function restoreStage(record: Record<string, unknown>): { stage: Stage; handoff: HandoffMode | null } {
+	const raw = typeof record.stage === "string" ? record.stage : legacyPhase(record.phase);
+	const legacy = LEGACY_STAGES[raw];
+	if (legacy) return legacy;
+	// A persisted `investigating` cannot be resumed: no agent turn survives a
+	// restore, so honouring it would strand the user with every command refused.
+	if (raw !== "investigating" && STAGES.includes(raw as Stage)) return { stage: raw as Stage, handoff: null };
+	return { stage: "user_turn", handoff: null };
 }
 
-export function blackboard(s: DebugState, evidenceDescription = "(none)"): string {
-	const probes = s.probes.map(p => `${p.id} (${p.file}, round ${p.round})`).join("\n  ") || "(none)";
-	const counts = Object.entries(s.logCounts)
+/** Collapse the original `phase` field onto the stage name it became. */
+function legacyPhase(phase: unknown): string {
+	if (phase === "waiting") return "awaiting_evidence";
+	if (phase === "cleanup") return "cleaning_up";
+	return "open";
+}
+
+/** Collapse the pre-`rounds` fields into the single round they described. */
+function legacyRound(record: Record<string, unknown>, probes: readonly Probe[]): Round {
+	const index = typeof record.round === "number" && record.round > 0 ? record.round : 1;
+	const requests = asArray<EvidenceRequest & { round?: number }>(record.evidenceRequests).filter(
+		request => request.round === undefined || request.round === index,
+	);
+	return {
+		index,
+		runId: typeof record.runId === "string" ? record.runId : null,
+		plan: requests.length > 0 ? requests.map(({ round: _round, ...rest }) => rest) : null,
+		reproductionSteps: asArray<string>(record.reproductionSteps),
+		probeIds: probes.filter(probe => probe.round === index).map(probe => probe.id),
+		nudges: { handoff: numberOr(record.gateNudges, 0), probes: 0 },
+		awaitingProgress: false,
+		handoff: null,
+	};
+}
+
+/** The closing requirements of the current round, as observed facts. */
+export function roundFacts(session: DebugSession, round: Round = currentRound(session)): string {
+	const plan = round.plan ? `${round.plan.length} request(s)` : "MISSING";
+	const steps = round.reproductionSteps.length > 0 ? `${round.reproductionSteps.length} step(s)` : "MISSING";
+	return `evidence plan: ${plan}, reproduction steps: ${steps}, live probes: ${liveProbeCount(session)}`;
+}
+
+/**
+ * Whose turn it is and what closing the round still requires, stated to the
+ * model. The model drives these transitions, so leaving the stage out is what
+ * lets it announce a reproduction while the round is still its own.
+ */
+export function stageBriefing(session: DebugSession): string {
+	const round = currentRound(session);
+	const facts = `Round ${round.index} facts — ${roundFacts(session, round)}.`;
+	if (session.stage === "cleaning_up") {
+		return `Turn owner: AGENT (cleanup). Remove every probe, verify the ledger is empty, then summarize. ${facts}`;
+	}
+	if (session.stage === "user_turn") {
+		// Written to be true whichever way this turn started. The context is
+		// assembled before a user message is announced, so this text cannot know
+		// which case it is in — but the model can see its own transcript, so the
+		// test it is given is one it can actually apply.
+		//
+		// Three triggers land here, and only the first one is the user's: a reply,
+		// the request that follows the `hand_off_to_user` call in the same turn
+		// (a tool call never ends a turn, so this one is unavoidable), and a host
+		// continuation. The last two need the same answer, so they are described
+		// together rather than as a list of causes to match against.
+		return (
+			`Turn owner: USER. Round ${round.index} was handed back as "${round.handoff ?? "incomplete"}" and is NOT closed. ${facts} ` +
+			"The user has not run /debug-proceed. Check what started this turn before you do anything else. " +
+			"If a user message is part of it, the round is yours again: answer it, then call hand_off_to_user to " +
+			"re-close the round — never assume the earlier handoff still stands. " +
+			"If nothing in this turn came from the user, nothing has changed since the handoff: you are either " +
+			"finishing the turn in which you just called hand_off_to_user, or you were resumed by a reminder or " +
+			"another automatic continuation. Either way the user has not acted, no reproduction has run, and no new " +
+			"observation exists. Do not read logs, do not analyze, do not resume the plan. Write one short line " +
+			"addressed to the user — what to do now, and that /debug-proceed comes after they reproduce (or " +
+			"/debug-done if the bug is already fixed) — then end the turn. Never report " +
+			"that you were reminded and never restate this briefing back to them."
+		);
+	}
+	return (
+		`Turn owner: AGENT. Round ${round.index} is yours and you must close it before you stop. ${facts} ` +
+		"Close it by calling hand_off_to_user: that call is what moves the session into the user's hands. " +
+		"Prose telling the user to reproduce does not change the state, and a turn that stops without that call is " +
+		"sent straight back to you to make it."
+	);
+}
+
+export function blackboard(session: DebugSession, evidenceDescription = "(none)"): string {
+	const round = currentRound(session);
+	const probes = session.probes.map(p => `${p.id} (${p.file}, round ${p.round})`).join("\n  ") || "(none)";
+	const counts = Object.entries(session.logCounts)
 		.map(([run, n]) => `${run}: ${n}`)
 		.join(", ") || "(none yet)";
 	return `\
-[DEBUG MODE ACTIVE — round ${s.round}]
+[DEBUG MODE ACTIVE — round ${round.index} · stage ${session.stage}]
+
+${stageBriefing(session)}
 
 Problem under investigation:
-${s.problem}
+${session.problem}
 
 Deployed probes (ground truth, maintained by the extension):
   ${probes}
 
-Current run log file (absolute path): ${logFileFor(s) ?? "(not initialized)"}
+Current run log file (absolute path): ${logFileFor(session) ?? "(not initialized)"}
 Runtime probes MUST append JSONL directly to that exact file using the target environment's native file APIs.
 Console output such as Unity Debug.Log may supplement diagnostics but is never the runtime evidence for this workflow. Never ask the user to transcribe console output.
 Logs by run: ${counts}
-Current run id: ${s.runId ?? "(not started)"}
+Current run id: ${round.runId ?? "(not started)"}
 
 Evidence method priority (MINIMIZE USER INTERVENTION):
   1. agent_inspection — reuse existing logs/files and agent tools