@siuver/omp-debug-mode 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.1.1 - 2026-08-20
+
+- Replaced the localhost HTTP collector with direct JSONL file appends from instrumented runtime code.
+- The injected prompt now supplies the exact absolute log file and explicitly forbids POST, sockets, and other network transports.
+- 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.
+
 ## 0.1.0 - 2026-08-20
 
 - Initial npm release of the Cursor Debug Mode replica for OMP.

package/README.md

@@ -17,20 +17,30 @@ The plugin makes the agent form hypotheses, add temporary runtime probes, attemp
 ## Workflow
 
 1. Run `/debug-mode <problem description>`.
-2. The agent investigates, records hypotheses, inserts minimal probes marked with `@omp-probe <id>`, and attempts a fix.
-3. When the agent stops, reproduce the issue in the real application.
-4. Run `/debug-done fixed` if the issue is resolved, or `/debug-done proceed` to analyze evidence and continue.
+2. The agent investigates, records hypotheses, inserts minimal probes marked with `@omp-probe <id>`, and attempts a fix. Each probe appends its runtime observation directly to the exact JSONL file provided in the injected prompt.
+3. When the agent stops, reproduce the issue in the real application so the instrumented code writes its observations.
+4. Run `/debug-done fixed` if the issue is resolved, or `/debug-done proceed` to make the agent read the completed run's JSONL file, analyze the evidence, and continue.
 5. On success, the agent removes all probes, verifies the probe ledger is empty, and summarizes the root cause and fix.
 
 The extension also provides the read-only `get_debug_logs` and `list_debug_probes` tools so the agent can inspect runtime evidence and verify cleanup.
 
 ## Runtime Data
 
-During an active session, the plugin starts a local HTTP server on `127.0.0.1:7842`. Instrumentation posts `{ "probe": "...", "data": ... }` to `/log`, and the plugin appends the entries to `<project>/.omp/debug/<run>.jsonl`.
+At the start of each round, the plugin creates an absolute log path:
 
-The server only listens on localhost. Debug data may still contain values captured from your application, so review probe payloads before reproducing sensitive workflows. Finishing or aborting debug mode removes the debug log directory. Applied fixes remain in the working tree for review.
+```text
+<project>/.omp/debug/current.jsonl
+```
+
+That exact stable path is injected into the Agent prompt. The prompt requires every runtime probe to use the target environment's native file append API and write one compact JSON object plus a newline using this schema:
+
+```json
+{"probe":"player-state","ts":1787193600000,"data":{"isGrounded":false}}
+```
+
+Probes append directly to `current.jsonl`; they must not overwrite it, and they should flush and close the file promptly rather than retaining an exclusive handle. The stable filename means probes retained across rounds continue writing to the correct place without being rewritten just to change a path. The mechanism does not use HTTP, localhost, sockets, or any other network transport, so environments such as the Unity Editor can use their normal filesystem APIs. The target process still needs permission to access the displayed absolute path.
 
-Debug state is recorded in the OMP session so an active workflow can resume after reopening the session. Port `7842` must be available for probes to report data.
+When you run `/debug-done proceed`, the plugin archives the completed file as `<run-id>.jsonl`, creates an empty `current.jsonl` for the next reproduction, and makes the Agent analyze the archived evidence through `get_debug_logs`. `/debug-status` shows the current absolute file path and log count.
 
 ## Install
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@siuver/omp-debug-mode",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "type": "module",
   "description": "A Cursor Debug Mode replica for evidence-driven, human-in-the-loop debugging in oh-my-pi.",
   "license": "MIT",

package/src/log-files.ts

@@ -0,0 +1,46 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+export const ACTIVE_LOG_FILE = "current.jsonl";
+
+export function resolveRunLogFile(
+	debugDir: string | null,
+	run: string | null,
+	activeRun: string | null,
+): string | null {
+	if (!debugDir || !run) return null;
+	return path.join(debugDir, run === activeRun ? ACTIVE_LOG_FILE : `${run}.jsonl`);
+}
+
+export function readJsonlLines(file: string | null): string[] {
+	if (!file) return [];
+	try {
+		return fs
+			.readFileSync(file, "utf8")
+			.split(/\r?\n/)
+			.filter(line => line.trim().length > 0);
+	} catch {
+		return [];
+	}
+}
+
+export function prepareRunLog(debugDir: string, previousRun: string | null): string {
+	const activeFile = path.join(debugDir, ACTIVE_LOG_FILE);
+	const archivedFile = previousRun ? path.join(debugDir, `${previousRun}.jsonl`) : null;
+
+	try {
+		if (archivedFile) {
+			if (fs.existsSync(activeFile)) fs.copyFileSync(activeFile, archivedFile);
+			else fs.writeFileSync(archivedFile, "", { flag: "a" });
+		}
+		fs.writeFileSync(activeFile, "", { flag: "w" });
+		return activeFile;
+	} catch (error) {
+		if (archivedFile) {
+			try {
+				fs.rmSync(archivedFile, { force: true });
+			} catch {}
+		}
+		throw error;
+	}
+}

package/src/main.ts

@@ -8,23 +8,20 @@
  *   → /debug-done fixed   → agent removes probes + summarizes → teardown (logs deleted)
  *   → /debug-done proceed → agent analyzes captured logs, re-instruments + fixes → loop
  *
- * Components:
- * - Local log server (Bun.serve, 127.0.0.1:7842) — probes POST {probe, data};
- *   logs append to <cwd>/.omp/debug/<run>.jsonl
+ * - Stable JSONL file at <cwd>/.omp/debug/current.jsonl — runtime probes append
+ *   observations directly with the target environment's native file APIs
  * - Probe ledger: tool_call interception on edit/write records @omp-probe ids;
  *   ground truth is rescanned from disk (checkLedger)
  * - Tools: get_debug_logs, list_debug_probes
  * - Commands: /debug-mode, /debug-status, /debug-done fixed|proceed, /debug-abort
  */
 import type { ExtensionAPI, ExtensionContext } from "@oh-my-pi/pi-coding-agent";
-import type { Server } from "bun";
-import type { WriteStream } from "node:fs";
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { ACTIVE_LOG_FILE, prepareRunLog, readJsonlLines, resolveRunLogFile } from "./log-files";
 
 const DEBUG_ENTRY = "com.omp.debug-mode.state";
 const PROBE_MARK = /@omp-probe\s+([A-Za-z0-9_-]+)/g;
-const DEFAULT_PORT = 7842;
 
 type Phase = "idle" | "round" | "waiting" | "cleanup";
 
@@ -47,12 +44,6 @@ interface DebugState {
 	cleanupReady: boolean;
 }
 
-interface LogEntry {
-	run: string;
-	probe: string;
-	ts: number;
-	data: unknown;
-}
 
 function freshState(): DebugState {
 	return {
@@ -76,6 +67,10 @@ function probeIdsIn(text: unknown): string[] {
 	return ids;
 }
 
+function logFileFor(s: DebugState, run = s.runId): string | null {
+	return resolveRunLogFile(s.debugDir, run, s.runId);
+}
+
 function blackboard(s: DebugState): string {
 	const probes = s.probes.map(p => `${p.id} (${p.file}, round ${p.round})`).join("\n  ") || "(none)";
 	const counts = Object.entries(s.logCounts)
@@ -90,7 +85,8 @@ ${s.problem}
 Deployed probes (ground truth, maintained by the extension):
   ${probes}
 
-Log endpoint for probes: POST JSON {probe, data} to http://127.0.0.1:${DEFAULT_PORT}/log
+Current run log file (absolute path): ${logFileFor(s) ?? "(not initialized)"}
+Runtime probes MUST append JSONL directly to that exact file using the target runtime's native file APIs.
 Probe code MUST carry the marker comment \`// @omp-probe <id>\` adjacent to it.
 Logs by run: ${counts}
 Current run id: ${s.runId ?? "(not started)"}`;
@@ -101,9 +97,14 @@ const METHODOLOGY = `\
 Each round consists of, in order:
 1. Restate hypotheses (mark each: pending / ruled-out / confirmed via runtime evidence).
 2. Update instrumentation: remove probes that yielded no information, add probes that
-   discriminate between remaining hypotheses. Each probe is one minimal statement sending
-   JSON via HTTP POST to the log endpoint, with the marker comment \`// @omp-probe <id>\`
-   adjacent (language-appropriate; keep the block small and easy to remove).
+   discriminate between remaining hypotheses. Each probe must use the target runtime's
+   native file append API to append exactly one compact JSON object plus a newline to the
+   exact absolute log file shown above. Use the schema {"probe":"<id>","ts":<epoch-ms>,
+   "data":<JSON-serializable-observation>}. Append; never overwrite or truncate. Open,
+   append, flush, and close promptly for each observation; do not retain an exclusive file
+   handle across the reproduction gate. Do not use HTTP, POST, localhost, sockets, or any
+   network transport. Escape the path correctly for the target language. Keep the marker
+   comment \`// @omp-probe <id>\` adjacent to the code.
 3. ATTEMPT A FIX for your leading hypothesis in the same round. Instrumentation without
    a fix is an incomplete round — the loop only advances when you fix something.
 4. End the round by writing concise reproduction steps for the user (exact commands or
@@ -115,80 +116,58 @@ tool that the ledger is empty, then summarize root cause and the final fix.`;
 export default function debugModeExtension(pi: ExtensionAPI) {
 	const z = pi.zod;
 	const state: DebugState = freshState();
-	let server: Server | null = null;
-	let logBuffer: LogEntry[] = [];
-	let pendingWrite: WriteStream | null = null;
 	let uiCtx: ExtensionContext | null = null;
 
-	// ============================== log server ==============================
+	// ============================== log files ==============================
 
-	function startServer(ctx: ExtensionContext, port: number): boolean {
-		if (server) return true;
-		const dir = path.join(ctx.cwd, ".omp", "debug");
+	function initializeLogDirectory(ctx: ExtensionContext): boolean {
+		const dir = path.resolve(ctx.cwd, ".omp", "debug");
 		try {
 			fs.mkdirSync(dir, { recursive: true });
-		} catch (err) {
-			pi.logger.error("debug-mode: cannot create log dir", { dir, err });
-			return false;
-		}
-		state.debugDir = dir;
-		logBuffer = [];
-		try {
-			server = Bun.serve({
-				port,
-				hostname: "127.0.0.1",
-				idleTimeout: 5,
-				async fetch(req) {
-					const url = new URL(req.url);
-					if (req.method === "POST" && url.pathname === "/log") {
-						try {
-							const body = (await req.json()) as { probe?: unknown; data?: unknown };
-							if (typeof body.probe !== "string") return new Response("bad probe", { status: 400 });
-							const entry: LogEntry = {
-								run: state.runId ?? "orphan",
-								probe: body.probe,
-								ts: Date.now(),
-								data: body.data ?? null,
-							};
-							logBuffer.push(entry);
-							state.logCounts[entry.run] = (state.logCounts[entry.run] ?? 0) + 1;
-							pendingWrite?.write(JSON.stringify(entry) + "\n");
-							refreshUi();
-							return new Response("ok");
-						} catch {
-							return new Response("bad json", { status: 400 });
-						}
-					}
-					if (req.method === "GET" && url.pathname === "/health") {
-						return new Response("ok");
-					}
-					return new Response("not found", { status: 404 });
-				},
-			});
+			state.debugDir = dir;
 			return true;
 		} catch (err) {
-			pi.logger.error("debug-mode: log server failed to start", { err });
-			server = null;
+			pi.logger.error("debug-mode: cannot create log dir", { dir, err });
+			state.debugDir = null;
 			return false;
 		}
 	}
 
-	function stopServer(): void {
-		pendingWrite?.end();
-		pendingWrite = null;
-		server?.stop(true);
-		server = null;
+	function readRunLines(run: string): string[] {
+		return readJsonlLines(logFileFor(state, run));
+	}
+
+	function refreshLogCounts(): void {
+		const runs = new Set(Object.keys(state.logCounts));
+		if (state.debugDir) {
+			try {
+				for (const file of fs.readdirSync(state.debugDir)) {
+					if (!file.endsWith(".jsonl")) continue;
+					if (file === ACTIVE_LOG_FILE) {
+						if (state.runId) runs.add(state.runId);
+					} else {
+						runs.add(file.replace(/\.jsonl$/, ""));
+					}
+				}
+			} catch {}
+		}
+		for (const run of runs) state.logCounts[run] = readRunLines(run).length;
 	}
 
-	function newRun(): string {
-		pendingWrite?.end();
-		pendingWrite = null;
+	function newRun(): string | null {
+		if (!state.debugDir) return null;
 		const run = `run${state.round}-${Date.now().toString(36)}`;
+		try {
+			prepareRunLog(state.debugDir, state.runId);
+		} catch (err) {
+			pi.logger.error("debug-mode: cannot initialize run log", {
+				file: path.join(state.debugDir, ACTIVE_LOG_FILE),
+				err,
+			});
+			return null;
+		}
 		state.runId = run;
 		state.logCounts[run] = 0;
-		if (state.debugDir) {
-			pendingWrite = fs.createWriteStream(path.join(state.debugDir, `${run}.jsonl`), { flags: "a" });
-		}
 		return run;
 	}
 
@@ -247,6 +226,7 @@ export default function debugModeExtension(pi: ExtensionAPI) {
 		ctx.ui.setStatus("debug-mode", ctx.ui.theme.fg("warning", label));
 		const lines: string[] = [];
 		if (state.phase === "waiting") {
+			refreshLogCounts();
 			const n = state.runId ? (state.logCounts[state.runId] ?? 0) : 0;
 			lines.push(ctx.ui.theme.fg("accent", "reproduce the bug, then: /debug-done fixed | proceed"));
 			lines.push(ctx.ui.theme.fg("dim", `run ${state.runId} — ${n} log entries`));
@@ -293,7 +273,7 @@ export default function debugModeExtension(pi: ExtensionAPI) {
 	pi.on("session_stop", async (_event, ctx) => {
 		if (!state.active) return;
 		if (state.phase === "cleanup") {
-			// cleanup turn settled → teardown (fixes kept, logs + server removed)
+			// Cleanup turn settled: keep fixes and remove the temporary logs.
 			if (state.cleanupReady) await teardown(ctx, true);
 			return;
 		}
@@ -324,6 +304,10 @@ export default function debugModeExtension(pi: ExtensionAPI) {
 	});
 
 	function startDebug(ctx: ExtensionContext, problem: string): void {
+		if (!initializeLogDirectory(ctx)) {
+			ctx.ui.notify("debug-mode: could not create the debug log directory; debug mode was not started", "error");
+			return;
+		}
 		state.active = true;
 		state.phase = "round";
 		state.problem = problem;
@@ -331,15 +315,16 @@ export default function debugModeExtension(pi: ExtensionAPI) {
 		state.probes = [];
 		state.logCounts = {};
 		state.hasRoundContent = false;
-		if (!startServer(ctx, DEFAULT_PORT)) {
-			ctx.ui.notify("debug-mode: log server failed to start; probes will have nowhere to report", "error");
+		if (!newRun()) {
+			Object.assign(state, freshState());
+			ctx.ui.notify("debug-mode: could not initialize the run log file; debug mode was not started", "error");
+			return;
 		}
-		newRun();
 		refreshUi();
 		pi.sendMessage(
 			{
 				customType: "debug-mode-start",
-				content: `Starting debug mode. Problem report:\n\n${problem}\n\nBegin round 1: explore, hypothesize, instrument, and attempt a fix. Then give reproduction steps and stop.`,
+				content: `Starting debug mode. Problem report:\n\n${problem}\n\nBegin round 1: explore, hypothesize, instrument with direct file writes, and attempt a fix. Then give reproduction steps and stop.`,
 				display: true,
 			},
 			{ triggerTurn: true },
@@ -355,6 +340,7 @@ export default function debugModeExtension(pi: ExtensionAPI) {
 			ctx.ui.notify(`debug-mode: not waiting for reproduction (phase: ${state.phase})`, "error");
 			return;
 		}
+		refreshLogCounts();
 		if (verdict === "fixed") {
 			state.phase = "cleanup";
 			state.cleanupReady = false;
@@ -375,10 +361,17 @@ export default function debugModeExtension(pi: ExtensionAPI) {
 		} else {
 			const run = state.runId ?? "(none)";
 			const n = state.logCounts[run] ?? 0;
+			const previousRound = state.round;
 			state.round += 1;
 			state.phase = "round";
 			state.hasRoundContent = false;
-			newRun();
+			if (!newRun()) {
+				state.round = previousRound;
+				state.phase = "waiting";
+				ctx.ui.notify("debug-mode: could not initialize the next run log file; staying at the reproduction gate", "error");
+				refreshUi();
+				return;
+			}
 			refreshUi();
 			pi.sendMessage(
 				{
@@ -386,7 +379,7 @@ export default function debugModeExtension(pi: ExtensionAPI) {
 					content:
 						`User chose PROCEED — the fix did not resolve it (run ${run} captured ${n} log entries).\n` +
 						(n === 0
-							? "No logs were captured: the probes may not have executed (wrong code path, not rebuilt, or server unreachable) — treat that as a signal.\n"
+							? "No logs were captured: the instrumented code path may not have executed, the build may be stale, the path may be wrong, or the file append may have failed — treat that as a signal.\n"
 							: "") +
 						"Read the logs with get_debug_logs, rule out / strengthen hypotheses, re-instrument, attempt the next fix, give reproduction steps, and stop.",
 					display: true,
@@ -404,9 +397,9 @@ export default function debugModeExtension(pi: ExtensionAPI) {
 				pi.logger.warn("debug-mode: failed to remove debug dir", { err });
 			}
 		}
-		stopServer();
 		const probesLeft = await checkLedger();
 		Object.assign(state, freshState());
+		pi.appendEntry(DEBUG_ENTRY, { ...state });
 		refreshUi();
 		if (probesLeft.length > 0) {
 			ctx.ui.notify(
@@ -463,12 +456,14 @@ export default function debugModeExtension(pi: ExtensionAPI) {
 				ctx.ui.notify("debug-mode: idle", "info");
 				return;
 			}
+			refreshLogCounts();
 			const alive = await checkLedger();
 			ctx.ui.notify(
 				`debug-mode: phase=${state.phase} round=${state.round} run=${state.runId}\n` +
 					`probes (ledger ${state.probes.length}, alive ${alive.length}):\n` +
 					(alive.map(p => `  ${p.id} — ${p.file}`).join("\n") || "  (none)") +
-					`\nlogs: ${Object.entries(state.logCounts).map(([r, n]) => `${r}=${n}`).join(", ") || "(none)"}`,
+					`\nlogs: ${Object.entries(state.logCounts).map(([r, n]) => `${r}=${n}`).join(", ") || "(none)"}` +
+					`\ncurrent log file: ${logFileFor(state) ?? "(not initialized)"}`,
 				"info",
 			);
 		},
@@ -480,7 +475,7 @@ export default function debugModeExtension(pi: ExtensionAPI) {
 		name: "get_debug_logs",
 		label: "Get Debug Logs",
 		description:
-			"Read logs captured by debug-mode probes. Each entry: {run, probe, ts, data}. Returns JSONL text. Call with previous=true to analyze the last completed reproduction run.",
+			"Read JSONL observations appended directly by debug-mode runtime probes. Each entry: {probe, ts, data}. Call with previous=true to analyze the last completed reproduction run.",
 		parameters: z.object({
 			run: z.string().optional().describe("Run id filter (default: current run)"),
 			probe: z.string().optional().describe("Probe id filter"),
@@ -488,33 +483,42 @@ export default function debugModeExtension(pi: ExtensionAPI) {
 		}),
 		approval: "read",
 		async execute(_toolCallId, params) {
+			refreshLogCounts();
 			const runs = Object.keys(state.logCounts);
 			let run = params.run;
-			if (!run && params.previous) run = runs[runs.length - 2];
-			if (!run) run = state.runId ?? undefined;
-			// disk is authoritative (survives resume); memory buffer is fallback
-			let text = "";
-			if (state.debugDir && run) {
-				try {
-					text = await Bun.file(path.join(state.debugDir, `${run}.jsonl`)).text();
-				} catch {
-					text = "";
+			if (!run && params.previous) {
+				run = runs[runs.length - 2];
+				if (!run) {
+					return {
+						content: [{ type: "text", text: "(no completed previous debug run is available)" }],
+						details: { run: null, file: null, count: 0 },
+					};
 				}
 			}
-			if (!text) {
-				text = logBuffer
-					.filter(e => (!run || e.run === run) && (!params.probe || e.probe === params.probe))
-					.map(e => JSON.stringify(e))
-					.join("\n");
+			if (!run) run = state.runId ?? undefined;
+
+			let lines = run ? readRunLines(run) : [];
+			if (params.probe) {
+				lines = lines.filter(line => {
+					try {
+						const entry = JSON.parse(line) as { probe?: unknown };
+						return entry.probe === params.probe;
+					} catch {
+						return false;
+					}
+				});
 			}
+			const text = lines.join("\n");
 			return {
 				content: [
 					{
 						type: "text",
-						text: text || "(no logs captured — probes did not report; wrong code path, stale build, or server unreachable)",
+						text:
+							text ||
+							"(no logs captured — the instrumented path may not have executed, the build may be stale, the path may be wrong, or the file append may have failed)",
 					},
 				],
-				details: { run: run ?? null, count: text.split("\n").filter(Boolean).length },
+				details: { run: run ?? null, file: run ? logFileFor(state, run) : null, count: lines.length },
 			};
 		},
 	});
@@ -553,29 +557,22 @@ export default function debugModeExtension(pi: ExtensionAPI) {
 			.pop() as { data?: DebugState } | undefined;
 		if (last?.data?.active) {
 			Object.assign(state, last.data);
-			if (state.debugDir && startServer(ctx, DEFAULT_PORT)) {
-				// replay disk logs for analysis continuity across resume
-				if (fs.existsSync(state.debugDir)) {
-					for (const f of fs.readdirSync(state.debugDir)) {
-						if (!f.endsWith(".jsonl")) continue;
-						const run = f.replace(/\.jsonl$/, "");
-						try {
-							const lines = (await Bun.file(path.join(state.debugDir!, f)).text()).split("\n").filter(Boolean);
-							state.logCounts[run] = lines.length;
-							for (const l of lines) {
-								try {
-									logBuffer.push(JSON.parse(l) as LogEntry);
-								} catch {}
-							}
-						} catch {}
+			if (!state.debugDir || !fs.existsSync(state.debugDir)) initializeLogDirectory(ctx);
+			const currentFile = logFileFor(state);
+			if (currentFile) {
+				try {
+					const legacyRunFile = state.debugDir && state.runId ? path.join(state.debugDir, `${state.runId}.jsonl`) : null;
+					if (!fs.existsSync(currentFile) && legacyRunFile && fs.existsSync(legacyRunFile)) {
+						fs.renameSync(legacyRunFile, currentFile);
 					}
-				}
-				if (state.runId) {
-					pendingWrite = fs.createWriteStream(path.join(state.debugDir, `${state.runId}.jsonl`), { flags: "a" });
+					fs.writeFileSync(currentFile, "", { flag: "a" });
+				} catch (err) {
+					pi.logger.error("debug-mode: cannot restore run log", { file: currentFile, err });
 				}
 			}
+			refreshLogCounts();
 			ctx.ui.notify(
-				`debug-mode resumed: phase=${state.phase} round=${state.round}. Use /debug-status, /debug-done fixed|proceed, or /debug-abort.`,
+				`debug-mode resumed: phase=${state.phase} round=${state.round}, log=${currentFile ?? "unavailable"}. Use /debug-status, /debug-done fixed|proceed, or /debug-abort.`,
 				"info",
 			);
 		}
@@ -586,9 +583,6 @@ export default function debugModeExtension(pi: ExtensionAPI) {
 		if (state.active) pi.appendEntry(DEBUG_ENTRY, { ...state });
 	});
 
-	pi.on("session_shutdown", async () => {
-		stopServer();
-	});
 
 	pi.setLabel("Debug Mode");
 }