oma-coding-agent 1.1.4

package/src/debug/remote-debugger.ts

@@ -0,0 +1,151 @@
+/**
+ * Bun JavaScriptCore remote inspector control.
+ *
+ * Wraps `bun:jsc`'s `startRemoteDebugger`, which exposes JavaScriptCore's
+ * built-in WebKit RemoteInspectorServer over a raw socket. The API is one-shot
+ * and rough around the edges (Bun documents it as untested, "may not be
+ * supported yet on macOS"):
+ *   - it returns `void` and has no stop handle, so we track the live endpoint
+ *     at module scope and make starting idempotent;
+ *   - it rejects port `0`, so "let the OS pick" is implemented by reserving a
+ *     free port via `node:net` and handing the concrete number to Bun;
+ *   - on macOS (Bun 1.3.x) it throws a spurious "port already in use" error
+ *     even when the server binds fine, so success is decided by a loopback
+ *     probe rather than by whether the call threw.
+ */
+
+import { startRemoteDebugger } from "bun:jsc";
+import * as net from "node:net";
+
+const DEFAULT_HOST = "127.0.0.1";
+/** How long to keep probing for the inspector socket before giving up. */
+const PROBE_DEADLINE_MS = 1000;
+const PROBE_INTERVAL_MS = 50;
+
+export interface RemoteDebuggerInfo {
+	host: string;
+	port: number;
+}
+
+let active: RemoteDebuggerInfo | null = null;
+/** In-flight start, shared so concurrent callers coalesce onto one launch. */
+let starting: Promise<RemoteDebuggerInfo> | null = null;
+
+/** Underlying starter signature; tests inject a disposable listener in its place. */
+export type RemoteDebuggerStarter = (host: string, port: number) => void;
+
+export interface StartRemoteDebuggerOptions {
+	/** Explicit port; when omitted a free port is reserved automatically. */
+	port?: number;
+	/** Override the JSC starter. Defaults to `bun:jsc`'s `startRemoteDebugger`. */
+	start?: RemoteDebuggerStarter;
+}
+
+/** The live inspector endpoint for this process, or `null` if not started. */
+export function getRemoteDebugger(): RemoteDebuggerInfo | null {
+	return active;
+}
+
+/** Reserve a free TCP port on `host` by binding to `0`, then releasing it. */
+async function reserveFreePort(host: string): Promise<number> {
+	const server = net.createServer();
+	const listening = Promise.withResolvers<number>();
+	server.once("error", listening.reject);
+	server.listen(0, host, () => {
+		const addr = server.address();
+		if (addr && typeof addr === "object") listening.resolve(addr.port);
+		else listening.reject(new Error("Failed to reserve a debugger port"));
+	});
+	try {
+		return await listening.promise;
+	} finally {
+		const closed = Promise.withResolvers<void>();
+		server.close(() => closed.resolve());
+		await closed.promise;
+	}
+}
+
+/** Resolve once `host:port` accepts a TCP connection (within one attempt). */
+function tryConnect(host: string, port: number, timeoutMs: number): Promise<boolean> {
+	const { promise, resolve } = Promise.withResolvers<boolean>();
+	const socket = net.createConnection({ host, port });
+	let settled = false;
+	const finish = (ok: boolean) => {
+		if (settled) return;
+		settled = true;
+		socket.destroy();
+		resolve(ok);
+	};
+	socket.setTimeout(timeoutMs);
+	socket.once("connect", () => finish(true));
+	socket.once("timeout", () => finish(false));
+	socket.once("error", () => finish(false));
+	return promise;
+}
+
+/** Poll the inspector socket until it accepts a connection or the deadline passes. */
+async function waitForListening(host: string, port: number): Promise<boolean> {
+	const deadline = Date.now() + PROBE_DEADLINE_MS;
+	do {
+		if (await tryConnect(host, port, PROBE_INTERVAL_MS)) return true;
+		await Bun.sleep(PROBE_INTERVAL_MS);
+	} while (Date.now() < deadline);
+	return false;
+}
+
+/**
+ * Start the JavaScriptCore remote inspector for this process and return its
+ * endpoint. Idempotent: the underlying API cannot be stopped or rebound, so a
+ * second call returns the existing endpoint instead of starting again. When
+ * `port` is omitted a free port is reserved automatically.
+ *
+ * Throws only when the socket never comes up; Bun's spurious bind error is
+ * swallowed and overridden by the loopback probe.
+ */
+export async function startRemoteDebuggerServer(options: StartRemoteDebuggerOptions = {}): Promise<RemoteDebuggerInfo> {
+	if (active) return active;
+	starting ??= launch(options);
+	try {
+		return await starting;
+	} finally {
+		starting = null;
+	}
+}
+
+async function launch({ port, start = startRemoteDebugger }: StartRemoteDebuggerOptions): Promise<RemoteDebuggerInfo> {
+	const host = DEFAULT_HOST;
+	const chosen = port ?? (await reserveFreePort(host));
+
+	// Something already on this port? Refuse up front: otherwise Bun throws a
+	// real bind error and our success probe would connect to that unrelated
+	// service, marking a bogus endpoint as the debugger.
+	if (await tryConnect(host, chosen, PROBE_INTERVAL_MS)) {
+		throw new Error(`Port ${host}:${chosen} is already in use; cannot start remote debugger there.`);
+	}
+
+	let thrown: unknown;
+	try {
+		start(host, chosen);
+	} catch (err) {
+		// Bun's startRemoteDebugger throws a spurious bind error even on success,
+		// so defer the verdict to the loopback probe below.
+		thrown = err;
+	}
+
+	if (await waitForListening(host, chosen)) {
+		active = { host, port: chosen };
+		return active;
+	}
+
+	throw thrown instanceof Error ? thrown : new Error(`Remote debugger socket never came up on ${host}:${chosen}`);
+}
+
+/**
+ * Test-only: forget the tracked endpoint so a fresh start can be exercised.
+ * Does not (and cannot) stop a real JSC inspector — callers in tests own the
+ * disposable listener they injected.
+ */
+export function __resetRemoteDebuggerForTests(): void {
+	active = null;
+	starting = null;
+}

package/src/debug/report-bundle.ts

@@ -0,0 +1,375 @@
+/**
+ * Debug report bundle creation.
+ *
+ * Creates a .tar.gz archive with session data, logs, system info, and optional profiling data.
+ */
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import type { WorkProfile } from "@oh-my-pi/pi-natives";
+import { APP_NAME, getLogPath, getLogsDir, getReportsDir, isEnoent } from "@oh-my-pi/pi-utils";
+import { writeArchive } from "../utils/zip";
+import type { CpuProfile, HeapSnapshot } from "./profiler";
+import { collectSystemInfo, sanitizeEnv } from "./system-info";
+
+/** Maximum number of log lines to load into memory at once. */
+const MAX_LOG_LINES = 5000;
+
+/** Maximum bytes to read from the tail of a log file (2 MB). */
+const MAX_LOG_BYTES = 2 * 1024 * 1024;
+/** Read last N lines from a file, reading at most `maxBytes` from the tail. */
+async function readLastLines(filePath: string, n: number, maxBytes = MAX_LOG_BYTES): Promise<string> {
+	try {
+		const file = Bun.file(filePath);
+		const size = file.size;
+		const start = Math.max(0, size - maxBytes);
+		const content = start > 0 ? await file.slice(start, size).text() : await file.text();
+		const lines = content.split("\n");
+		// If we sliced mid-file, drop the first (partial) line
+		if (start > 0 && lines.length > 0) {
+			lines.shift();
+		}
+		return lines.slice(-n).join("\n");
+	} catch (err) {
+		if (isEnoent(err)) return "";
+		throw err;
+	}
+}
+
+export interface ReportBundleOptions {
+	/** Session file path */
+	sessionFile: string | undefined;
+	/** Settings to include */
+	settings?: Record<string, unknown>;
+	/** CPU profile (for performance reports) */
+	cpuProfile?: CpuProfile;
+	/** Heap snapshot (for memory reports) */
+	heapSnapshot?: HeapSnapshot;
+	/** Work profile (for work scheduling reports) */
+	workProfile?: WorkProfile;
+	/** Raw provider SSE diagnostics captured by the session buffer */
+	rawSseText?: string;
+}
+
+export interface ReportBundleResult {
+	path: string;
+	files: string[];
+}
+
+export interface DebugLogSource {
+	getInitialText(): Promise<string>;
+	hasOlderLogs(): boolean;
+	loadOlderLogs(limitDays?: number): Promise<string>;
+}
+
+/**
+ * Create a debug report bundle.
+ *
+ * Bundle contents:
+ * - session.jsonl: Current session transcript
+ * - artifacts/: Session artifacts directory
+ * - subagents/: Subagent sessions + artifacts
+ * - logs.txt: Recent log entries
+ * - system.json: OS, arch, CPU, memory, versions
+ * - env.json: Sanitized environment variables
+ * - config.json: Resolved settings
+ * - profile.cpuprofile: CPU profile (performance report only)
+ * - raw-sse.txt: Recent raw provider SSE diagnostics (when captured)
+ * - profile.md: Markdown CPU profile (performance report only)
+ * - heap.heapsnapshot: Heap snapshot (memory report only)
+ * - work.folded: Work profile folded stacks (work report only)
+ * - work.md: Work profile summary (work report only)
+ * - work.svg: Work profile flamegraph (work report only)
+ */
+export async function createReportBundle(options: ReportBundleOptions): Promise<ReportBundleResult> {
+	const reportsDir = getReportsDir();
+	await fs.mkdir(reportsDir, { recursive: true });
+
+	const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
+	const outputPath = path.join(reportsDir, `omp-report-${timestamp}.tar.gz`);
+
+	const data: Record<string, string> = {};
+	const files: string[] = [];
+
+	// Collect system info
+	const systemInfo = await collectSystemInfo();
+	data["system.json"] = JSON.stringify(systemInfo, null, 2);
+	files.push("system.json");
+
+	// Sanitized environment
+	data["env.json"] = JSON.stringify(sanitizeEnv(Bun.env as Record<string, string>), null, 2);
+	files.push("env.json");
+
+	// Settings/config
+	if (options.settings) {
+		data["config.json"] = JSON.stringify(options.settings, null, 2);
+		files.push("config.json");
+	}
+
+	// Recent logs (last 1000 lines)
+	const logPath = getLogPath();
+	const logs = await readLastLines(logPath, 1000);
+	if (logs) {
+		data["logs.txt"] = logs;
+		files.push("logs.txt");
+	}
+
+	// Recent raw provider SSE diagnostics
+	if (options.rawSseText && options.rawSseText.trim().length > 0) {
+		data["raw-sse.txt"] = options.rawSseText;
+		files.push("raw-sse.txt");
+	}
+
+	// Session file
+	if (options.sessionFile) {
+		try {
+			const sessionContent = await Bun.file(options.sessionFile).text();
+			data["session.jsonl"] = sessionContent;
+			files.push("session.jsonl");
+		} catch {
+			// Session file might not exist yet
+		}
+
+		// Artifacts directory (same path without .jsonl)
+		const artifactsDir = options.sessionFile.slice(0, -6);
+		await addDirectoryToArchive(data, files, artifactsDir, "artifacts");
+
+		// Look for subagent sessions in the same directory
+		const sessionDir = path.dirname(options.sessionFile);
+		const sessionBasename = path.basename(options.sessionFile, ".jsonl");
+		await addSubagentSessions(data, files, sessionDir, sessionBasename);
+	}
+
+	// CPU profile
+	if (options.cpuProfile) {
+		data["profile.cpuprofile"] = options.cpuProfile.data;
+		files.push("profile.cpuprofile");
+		data["profile.md"] = options.cpuProfile.markdown;
+		files.push("profile.md");
+	}
+
+	// Heap snapshot
+	if (options.heapSnapshot) {
+		data["heap.heapsnapshot"] = options.heapSnapshot.data;
+		files.push("heap.heapsnapshot");
+	}
+
+	// Work profile
+	if (options.workProfile) {
+		data["work.folded"] = options.workProfile.folded;
+		files.push("work.folded");
+		data["work.md"] = options.workProfile.summary;
+		files.push("work.md");
+		if (options.workProfile.svg) {
+			data["work.svg"] = options.workProfile.svg;
+			files.push("work.svg");
+		}
+	}
+
+	// Write archive
+	await writeArchive(outputPath, "tar.gz", Object.entries(data));
+
+	return { path: outputPath, files };
+}
+
+/** Add all files from a directory to the archive */
+async function addDirectoryToArchive(
+	data: Record<string, string>,
+	files: string[],
+	dirPath: string,
+	archivePrefix: string,
+): Promise<void> {
+	try {
+		const entries = await fs.readdir(dirPath, { withFileTypes: true });
+		for (const entry of entries) {
+			if (!entry.isFile()) continue;
+			const filePath = path.join(dirPath, entry.name);
+			const archivePath = `${archivePrefix}/${entry.name}`;
+			try {
+				const content = await Bun.file(filePath).text();
+				data[archivePath] = content;
+				files.push(archivePath);
+			} catch {
+				// Skip files we can't read
+			}
+		}
+	} catch {
+		// Directory doesn't exist
+	}
+}
+
+/** Find and add subagent session files */
+async function addSubagentSessions(
+	data: Record<string, string>,
+	files: string[],
+	sessionDir: string,
+	parentBasename: string,
+): Promise<void> {
+	// Subagent sessions are named with task IDs in the same directory
+	// They follow the pattern: {timestamp}_{sessionId}.jsonl
+	// We look for any sessions created after the parent session
+	try {
+		const entries = await fs.readdir(sessionDir, { withFileTypes: true });
+		const sessionFiles = entries
+			.filter(e => e.isFile() && e.name.endsWith(".jsonl") && e.name !== `${parentBasename}.jsonl`)
+			.map(e => e.name);
+
+		// Limit to most recent 10 subagent sessions
+		const sortedFiles = sessionFiles.sort().slice(-10);
+
+		for (const filename of sortedFiles) {
+			const filePath = path.join(sessionDir, filename);
+			const archivePath = `subagents/${filename}`;
+			try {
+				const content = await Bun.file(filePath).text();
+				data[archivePath] = content;
+				files.push(archivePath);
+
+				// Also add artifacts for this subagent session
+				const artifactsDir = filePath.slice(0, -6);
+				await addDirectoryToArchive(data, files, artifactsDir, `subagents/${filename.slice(0, -6)}`);
+			} catch {
+				// Skip files we can't read
+			}
+		}
+	} catch {
+		// Directory doesn't exist
+	}
+}
+
+/** Get recent log entries for display (tail-limited to avoid OOM on large files). */
+export async function getLogText(): Promise<string> {
+	return readLastLines(getLogPath(), MAX_LOG_LINES);
+}
+
+const LOG_FILE_PATTERN = new RegExp(`^${APP_NAME}\\.(\\d{4}-\\d{2}-\\d{2})\\.log$`);
+
+export async function createDebugLogSource(): Promise<DebugLogSource> {
+	const logsDir = getLogsDir();
+	const todayPath = getLogPath();
+	const todayName = path.basename(todayPath);
+	let olderFiles: string[] = [];
+	try {
+		const entries = await fs.readdir(logsDir, { withFileTypes: true });
+		const datedFiles = entries
+			.filter(entry => entry.isFile())
+			.map(entry => {
+				const match = LOG_FILE_PATTERN.exec(entry.name);
+				return match ? { name: entry.name, date: match[1] } : undefined;
+			})
+			.filter((entry): entry is { name: string; date: string } => entry !== undefined)
+			.filter(entry => entry.name !== todayName)
+			.sort((a, b) => b.date.localeCompare(a.date));
+		olderFiles = datedFiles.map(entry => entry.name);
+	} catch {
+		olderFiles = [];
+	}
+
+	let cursor = 0;
+
+	const getInitialText = async (): Promise<string> => {
+		return readLastLines(todayPath, MAX_LOG_LINES);
+	};
+
+	const hasOlderLogs = (): boolean => cursor < olderFiles.length;
+
+	const loadOlderLogs = async (limitDays: number = 1): Promise<string> => {
+		if (!hasOlderLogs()) {
+			return "";
+		}
+		const count = Math.max(1, limitDays);
+		const slice = olderFiles.slice(cursor, cursor + count);
+		cursor += slice.length;
+		const chunks: string[] = [];
+		for (const filename of slice.reverse()) {
+			const filePath = path.join(logsDir, filename);
+			try {
+				const content = await readLastLines(filePath, MAX_LOG_LINES);
+				if (content.length > 0) {
+					chunks.push(content);
+				}
+			} catch (err) {
+				if (!isEnoent(err)) {
+					throw err;
+				}
+			}
+		}
+		return chunks.filter(chunk => chunk.length > 0).join("\n");
+	};
+
+	return {
+		getInitialText,
+		hasOlderLogs,
+		loadOlderLogs,
+	};
+}
+
+/** Calculate total size of artifact cache */
+export async function getArtifactCacheStats(
+	sessionsDir: string,
+): Promise<{ count: number; totalSize: number; oldestDate: Date | null }> {
+	let count = 0;
+	let totalSize = 0;
+	let oldestDate: Date | null = null;
+
+	try {
+		const sessions = await fs.readdir(sessionsDir, { withFileTypes: true });
+
+		for (const session of sessions) {
+			// Artifact directories don't have .jsonl extension
+			if (session.isDirectory()) {
+				const dirPath = path.join(sessionsDir, session.name);
+				try {
+					const stat = await fs.stat(dirPath);
+					const files = await fs.readdir(dirPath);
+					for (const file of files) {
+						const filePath = path.join(dirPath, file);
+						const fileStat = await fs.stat(filePath);
+						if (fileStat.isFile()) {
+							count++;
+							totalSize += fileStat.size;
+						}
+					}
+					if (!oldestDate || stat.mtime < oldestDate) {
+						oldestDate = stat.mtime;
+					}
+				} catch {
+					// Skip inaccessible directories
+				}
+			}
+		}
+	} catch {
+		// Directory doesn't exist
+	}
+
+	return { count, totalSize, oldestDate };
+}
+
+/** Clear artifact cache older than N days */
+export async function clearArtifactCache(sessionsDir: string, daysOld: number = 30): Promise<{ removed: number }> {
+	const cutoff = new Date();
+	cutoff.setDate(cutoff.getDate() - daysOld);
+	let removed = 0;
+
+	try {
+		const sessions = await fs.readdir(sessionsDir, { withFileTypes: true });
+
+		for (const session of sessions) {
+			if (session.isDirectory()) {
+				const dirPath = path.join(sessionsDir, session.name);
+				try {
+					const stat = await fs.stat(dirPath);
+					if (stat.mtime < cutoff) {
+						await fs.rm(dirPath, { recursive: true, force: true });
+						removed++;
+					}
+				} catch {
+					// Skip inaccessible directories
+				}
+			}
+		}
+	} catch {
+		// Directory doesn't exist
+	}
+
+	return { removed };
+}

package/src/debug/system-info.ts

@@ -0,0 +1,111 @@
+/**
+ * System information collection for debug reports.
+ */
+
+import * as os from "node:os";
+import { formatBytes, getProjectDir, VERSION } from "@oh-my-pi/pi-utils";
+
+export interface SystemInfo {
+	os: string;
+	arch: string;
+	cpu: string;
+	memory: {
+		total: number;
+		free: number;
+	};
+	versions: {
+		app: string;
+		bun: string;
+		node: string;
+	};
+	cwd: string;
+	shell: string;
+	terminal: string | undefined;
+}
+
+/** Map Darwin kernel major version to macOS marketing name. */
+function macosMarketingName(release: string): string | undefined {
+	const major = Number.parseInt(release.split(".")[0] ?? "", 10);
+	if (Number.isNaN(major)) return undefined;
+	const names: Record<number, string> = {
+		25: "Tahoe",
+		24: "Sequoia",
+		23: "Sonoma",
+		22: "Ventura",
+		21: "Monterey",
+		20: "Big Sur",
+	};
+	return names[major];
+}
+
+/** Collect system information */
+export async function collectSystemInfo(): Promise<SystemInfo> {
+	let cpuModel = "Unknown CPU";
+	try {
+		cpuModel = os.cpus()[0]?.model ?? cpuModel;
+	} catch {
+		// Keep debug report collection best-effort when CPU probing fails.
+	}
+
+	// Try to get shell from environment
+	const shell = Bun.env.SHELL ?? Bun.env.ComSpec ?? "unknown";
+	const terminal = Bun.env.TERM_PROGRAM ?? Bun.env.TERM ?? undefined;
+
+	let osStr = `${os.type()} ${os.release()} (${os.platform()})`;
+	if (os.platform() === "darwin") {
+		const name = macosMarketingName(os.release());
+		if (name) osStr = `${osStr} ${name}`;
+	}
+
+	return {
+		os: osStr,
+		arch: os.arch(),
+		cpu: cpuModel,
+		memory: {
+			total: os.totalmem(),
+			free: os.freemem(),
+		},
+		versions: {
+			app: VERSION,
+			bun: Bun.version,
+			node: process.version,
+		},
+		cwd: getProjectDir(),
+		shell,
+		terminal,
+	};
+}
+
+/** Format system info for display */
+export function formatSystemInfo(info: SystemInfo): string {
+	const lines = [
+		"System Information",
+		"━━━━━━━━━━━━━━━━━━",
+		`OS:      ${info.os}`,
+		`Arch:    ${info.arch}`,
+		`CPU:     ${info.cpu}`,
+		`Memory:  ${formatBytes(info.memory.total)} (${formatBytes(info.memory.free)} free)`,
+		`Bun:     ${info.versions.bun}`,
+		`App:     omp ${info.versions.app}`,
+		`Node:    ${info.versions.node} (compat)`,
+		`CWD:     ${info.cwd}`,
+		`Shell:   ${info.shell}`,
+	];
+	if (info.terminal) {
+		lines.push(`Terminal: ${info.terminal}`);
+	}
+	return lines.join("\n");
+}
+
+/** Sanitize environment variables by redacting sensitive values */
+export function sanitizeEnv(env: Record<string, string | undefined>): Record<string, string> {
+	const SENSITIVE_PATTERNS = [/key/i, /secret/i, /token/i, /pass/i, /auth/i, /credential/i, /api/i, /private/i];
+
+	const result: Record<string, string> = {};
+	for (const [k, v] of Object.entries(env)) {
+		if (v === undefined) continue;
+		const isSensitive = SENSITIVE_PATTERNS.some(p => p.test(k));
+		result[k] = isSensitive ? "[REDACTED]" : v;
+	}
+	return result;
+}