pi-harness-runtime 1.1.136 → 1.1.138

package/packages/codex-watcher/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@pi-harness/codex-watcher",
+  "version": "1.1.138",
+  "description": "Watches Codex CLI sessions and emits visible messages for PING-PONG monitoring",
+  "type": "module",
+  "main": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/src/index.js",
+      "types": "./dist/src/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "bun test"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0"
+  },
+  "files": [
+    "dist"
+  ]
+}

package/packages/codex-watcher/src/index.ts

@@ -0,0 +1,244 @@
+/**
+ * Codex Session Watcher — Main API
+ *
+ * Watches the active Codex CLI session and emits visible messages (user + assistant)
+ * so the harness PING-PONG middleware can feed them to pi.dev.
+ *
+ * Usage:
+ *   import { startWatcher, getLatestSession, getVisibleMessages } from "@pi-harness/codex-watcher";
+ *
+ *   // One-shot: get latest messages from the current session
+ *   const session = getLatestSession();
+ *   const messages = await getVisibleMessages(session.rolloutPath, { fromOrdinal: 0 });
+ *
+ *   // Continuous: poll the active session and emit messages
+ *   const handle = startWatcher({
+ *     onMessages: (msgs) => console.log(msgs),
+ *   });
+ *   // later: handle.stop();
+ */
+
+import { existsSync, openSync, readFileSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { classifyMessage, parseNewMessages } from "./parser.js";
+import { getAllSessions, getLatestSession } from "./session.js";
+import type {
+	CodexMessage,
+	CodexSession,
+	WatcherHandle,
+	WatcherOptions,
+} from "./types.js";
+
+export type { CodexMessage, CodexSession, WatcherHandle, WatcherOptions };
+export { classifyMessage, getAllSessions, getLatestSession };
+
+// ---------------------------------------------------------------------------
+// One-shot API
+// ---------------------------------------------------------------------------
+
+/** Read all visible messages from a rollout file, starting from a given ordinal. */
+export async function getVisibleMessages(
+	rolloutPath: string,
+	options: { fromOrdinal?: number; limit?: number } = {},
+): Promise<CodexMessage[]> {
+	const { fromOrdinal = 0, limit } = options;
+	if (!existsSync(rolloutPath)) return [];
+
+	const content = readFileSync(rolloutPath, "utf8");
+	const lines = content.split("\n").filter((l: string) => l.trim());
+
+	let messages = parseNewMessages(lines, fromOrdinal);
+	if (limit) messages = messages.slice(-limit);
+
+	if (messages.length > 0) {
+		messages[messages.length - 1] = {
+			...messages[messages.length - 1],
+			isLatest: true,
+		};
+	}
+
+	return messages;
+}
+
+// ---------------------------------------------------------------------------
+// Streaming watcher API
+// ---------------------------------------------------------------------------
+
+/**
+ * Start watching the active Codex session and call `onMessages` whenever
+ * new visible messages appear in the rollout file.
+ *
+ * @returns WatcherHandle — call handle.stop() to stop watching
+ *
+ * The watcher:
+ * 1. Polls session_index.jsonl to detect active session changes
+ * 2. Tracks file position so it only reads new lines (no re-read of full file)
+ * 3. Calls onMessages with incremental messages each poll cycle
+ */
+export function startWatcher(options: WatcherOptions = {}): WatcherHandle {
+	const {
+		pollIntervalMs = 2000,
+		codexDir,
+		onMessages,
+		onSessionChange,
+	} = options;
+
+	const home = codexDir ?? join(homedir(), ".codex");
+	let stopped = false;
+	let currentFd: ReturnType<typeof openSync> | null = null;
+	let currentPath: string | null = null;
+	let currentOrdinal = 0;
+	let pollCount = 0;
+	const maxIdlePolls = options.maxIdlePolls ?? Infinity;
+
+	// Track last known session to detect changes
+	let lastSessionId: string | null = null;
+
+	function stop() {
+		stopped = true;
+		if (currentFd !== null) {
+			try {
+				const { closeSync } = require("node:fs") as typeof import("node:fs");
+				closeSync(currentFd);
+			} catch {
+				// ignore
+			}
+		}
+	}
+
+	function isRunning() {
+		return !stopped;
+	}
+
+	function latestSession() {
+		return getLatestSession(home);
+	}
+
+	function latestOrdinal() {
+		return currentOrdinal;
+	}
+
+	function openRollout(path: string) {
+		if (currentFd !== null && currentPath !== path) {
+			try {
+				const { closeSync } = require("node:fs") as typeof import("node:fs");
+				closeSync(currentFd);
+			} catch {
+				// ignore
+			}
+		}
+
+		// stat to get current size
+		const stat = statSync(path);
+		currentFd = openSync(path, "r");
+		currentPath = path;
+		currentOrdinal = 0;
+		return { fd: currentFd, size: stat.size };
+	}
+
+	function readNewLines(
+		fd: number,
+		knownSize: number,
+	): {
+		lines: string[];
+		newSize: number;
+	} {
+		const { readSync, fstatSync } =
+			require("node:fs") as typeof import("node:fs");
+		const stat = fstatSync(fd);
+		const newSize = stat.size;
+
+		if (newSize <= knownSize) {
+			return { lines: [], newSize: knownSize };
+		}
+
+		const buf = Buffer.alloc(newSize - knownSize);
+		const bytesRead = readSync(fd, buf, 0, buf.length, knownSize);
+		const text = buf.subarray(0, bytesRead).toString("utf8");
+		const lines = text.split("\n").filter((l) => l.trim());
+
+		return { lines, newSize };
+	}
+
+	async function poll() {
+		if (stopped) return;
+
+		try {
+			// Check for session change
+			const session = getLatestSession(home);
+			const sessionId = session?.id ?? null;
+
+			if (sessionId !== lastSessionId) {
+				// New session or session ended
+				if (session) {
+					// Open new rollout
+					openRollout(session.rolloutPath);
+					currentOrdinal = 0;
+					// Read all existing lines as "historical"
+					const existing = await getVisibleMessages(session.rolloutPath, {
+						fromOrdinal: 0,
+					});
+					if (existing.length > 0) {
+						currentOrdinal = existing[existing.length - 1].ordinal;
+					}
+					onSessionChange?.(session);
+				} else {
+					onSessionChange?.(null);
+				}
+				lastSessionId = sessionId;
+				pollCount = 0;
+			}
+
+			if (!session || !currentFd || currentPath !== session.rolloutPath) {
+				if (!stopped) {
+					await sleep(pollIntervalMs);
+					poll();
+				}
+				return;
+			}
+
+			const stat = statSync(session.rolloutPath);
+			const { lines } = readNewLines(currentFd, stat.size);
+
+			if (lines.length > 0) {
+				pollCount = 0;
+				const messages = parseNewMessages(lines, currentOrdinal);
+				if (messages.length > 0) {
+					currentOrdinal = messages[messages.length - 1].ordinal;
+					messages[messages.length - 1] = {
+						...messages[messages.length - 1],
+						isLatest: true,
+					};
+					onMessages?.(messages);
+				}
+			} else {
+				pollCount++;
+				if (pollCount > maxIdlePolls) {
+					stop();
+					return;
+				}
+			}
+		} catch (_err) {
+			// Session file may not exist yet; just wait
+		}
+
+		if (!stopped) {
+			await sleep(pollIntervalMs);
+			poll();
+		}
+	}
+
+	// Start polling
+	poll();
+
+	return { stop, isRunning, latestSession, latestOrdinal };
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function sleep(ms: number): Promise<void> {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/packages/codex-watcher/src/parser.ts

@@ -0,0 +1,210 @@
+/**
+ * Parser — extracts visible messages from Codex JSONL rollout lines.
+ *
+ * Safe subset (no developer/reasoning):
+ *   type == "response_item" && payload.role == "user"  → input_text content
+ *   type == "event_msg" && payload.type == "item_completed"
+ *     && payload.item.type == "AgentMessage"
+ *     && payload.item.content[].type == "Text"         → visible assistant text
+ */
+
+import type { CodexMessage } from "./types.js";
+
+// ---------------------------------------------------------------------------
+// Raw event shapes (from Codex rollout JSONL)
+// ---------------------------------------------------------------------------
+
+interface RawEvent {
+	ordinal: number;
+	timestamp: string;
+	type: string;
+	payload: unknown;
+}
+
+interface AgentMessageContent {
+	type: "Text";
+	text: string;
+}
+
+interface AgentMessageItem {
+	type: "AgentMessage";
+	content: AgentMessageContent[];
+}
+
+interface EventMsgPayload {
+	type: "item_completed";
+	item: AgentMessageItem;
+}
+
+interface ResponseItemPayload {
+	type: string;
+	role?: string;
+	content?: Array<{ type: string; text?: string }>;
+	phase?: string;
+}
+
+interface RawEventMsg extends RawEvent {
+	type: "event_msg";
+	payload: EventMsgPayload;
+}
+
+interface RawResponseItem extends RawEvent {
+	type: "response_item";
+	payload: ResponseItemPayload;
+}
+
+// ---------------------------------------------------------------------------
+// Parse a single JSONL line into a CodexMessage
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse a single JSONL line from a Codex rollout file.
+ * Returns null if the line is not a visible message or is malformed.
+ */
+export function parseRolloutLine(line: string): CodexMessage | null {
+	if (!line.trim()) return null;
+
+	let raw: RawEvent;
+	try {
+		raw = JSON.parse(line) as RawEvent;
+	} catch {
+		return null;
+	}
+
+	// Assistant: visible text from AgentMessage item_completed events
+	if (isEventMsg(raw)) {
+		const msg = parseAssistantMessage(raw);
+		if (msg) return msg;
+	}
+
+	// User: input_text from response_item events
+	if (isResponseItem(raw)) {
+		const msg = parseUserMessage(raw);
+		if (msg) return msg;
+	}
+
+	return null;
+}
+
+/**
+ * Parse all visible messages from a JSONL file.
+ * Reads from a given byte offset so callers can do incremental reads.
+ *
+ * @param lines    Lines to parse (typically newly read lines)
+ * @param latestOrdinal  The last ordinal already known (messages with ordinal ≤ this are skipped)
+ * @returns Messages with ordinal > latestOrdinal
+ */
+export function parseNewMessages(
+	lines: string[],
+	latestOrdinal = 0,
+): CodexMessage[] {
+	const messages: CodexMessage[] = [];
+	for (const line of lines) {
+		const msg = parseRolloutLine(line);
+		if (msg && msg.ordinal > latestOrdinal) {
+			messages.push(msg);
+		}
+	}
+	// Sort by ordinal (ascending) to preserve order
+	messages.sort((a, b) => a.ordinal - b.ordinal);
+	return messages;
+}
+
+// ---------------------------------------------------------------------------
+// Type guards
+// ---------------------------------------------------------------------------
+
+function isEventMsg(raw: RawEvent): raw is RawEventMsg {
+	return raw.type === "event_msg";
+}
+
+function isResponseItem(raw: RawEvent): raw is RawResponseItem {
+	return raw.type === "response_item";
+}
+
+// ---------------------------------------------------------------------------
+// Parse specific message types
+// ---------------------------------------------------------------------------
+
+function parseAssistantMessage(raw: RawEventMsg): CodexMessage | null {
+	const p = raw.payload as EventMsgPayload;
+	if (p.type !== "item_completed") return null;
+	if (p.item?.type !== "AgentMessage") return null;
+
+	// Collect all Text content blocks
+	const texts: string[] = [];
+	for (const content of p.item.content ?? []) {
+		if (content.type === "Text" && content.text) {
+			texts.push(content.text);
+		}
+	}
+
+	if (texts.length === 0) return null;
+
+	return {
+		ordinal: raw.ordinal,
+		timestamp: raw.timestamp,
+		role: "assistant",
+		text: texts.join("\n"),
+		isLatest: false,
+	};
+}
+
+function parseUserMessage(raw: RawResponseItem): CodexMessage | null {
+	const p = raw.payload;
+	if (p.type !== "message") return null;
+	if (p.role !== "user") return null;
+
+	const texts: string[] = [];
+	for (const content of p.content ?? []) {
+		if (content.type === "input_text" && content.text) {
+			texts.push(content.text);
+		}
+	}
+
+	if (texts.length === 0) return null;
+
+	return {
+		ordinal: raw.ordinal,
+		timestamp: raw.timestamp,
+		role: "user",
+		text: texts.join("\n"),
+		isLatest: false,
+	};
+}
+
+// ---------------------------------------------------------------------------
+// Text extraction utilities
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract code blocks from assistant message text.
+ * Useful for detecting "plan" vs "code" in the Codex output.
+ */
+export function extractCodeBlocks(text: string): string[] {
+	const blocks: string[] = [];
+	for (const match of text.matchAll(/```[\w]*\n?([\s\S]*?)```/g)) {
+		blocks.push(match[1]?.trim() ?? "");
+	}
+	return blocks;
+}
+
+/**
+ * Detect whether the message is a plan (markdown outline) vs code output.
+ * Returns "plan" if it looks like a planning document, "code" if mostly code,
+ * "mixed" if both, "unknown" otherwise.
+ */
+export function classifyMessage(
+	text: string,
+): "plan" | "code" | "mixed" | "unknown" {
+	const codeBlocks = extractCodeBlocks(text);
+	const codeCharCount = codeBlocks.join("").replace(/\s/g, "").length;
+	const nonCodeCharCount = text
+		.replace(/```[\s\S]*?```/g, "")
+		.replace(/\s/g, "").length;
+
+	if (codeCharCount === 0 && nonCodeCharCount > 0) return "plan";
+	if (nonCodeCharCount === 0 && codeCharCount > 0) return "code";
+	if (codeCharCount > 0 && nonCodeCharCount > 0) return "mixed";
+	return "unknown";
+}

package/packages/codex-watcher/src/session.ts

@@ -0,0 +1,151 @@
+/**
+ * Session discovery — reads ~/.codex/session_index.jsonl to find active sessions.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { CodexSession } from "./types.js";
+
+/** Find the most recently active Codex session. */
+export function getLatestSession(codexDir?: string): CodexSession | null {
+	const indexPath = getSessionIndexPath(codexDir);
+	if (!existsSync(indexPath)) return null;
+
+	let latest: SessionIndexEntry | null = null;
+
+	for (const line of readLines(indexPath)) {
+		const entry = parseSessionIndexLine(line);
+		if (!entry) continue;
+		if (!latest || entry.updated_at > latest.updated_at) {
+			latest = entry;
+		}
+	}
+
+	if (!latest) return null;
+
+	return {
+		id: latest.id,
+		threadName: latest.thread_name,
+		updatedAt: latest.updated_at,
+		rolloutPath: findRolloutPath(latest.id, codexDir),
+	};
+}
+
+/** Get all sessions sorted by most recent first. */
+export function getAllSessions(codexDir?: string): CodexSession[] {
+	const indexPath = getSessionIndexPath(codexDir);
+	if (!existsSync(indexPath)) return [];
+
+	const sessions: SessionIndexEntry[] = [];
+	for (const line of readLines(indexPath)) {
+		const entry = parseSessionIndexLine(line);
+		if (entry) sessions.push(entry);
+	}
+
+	return sessions
+		.sort((a, b) => b.updated_at.localeCompare(a.updated_at))
+		.map((e) => ({
+			id: e.id,
+			threadName: e.thread_name,
+			updatedAt: e.updated_at,
+			rolloutPath: findRolloutPath(e.id, codexDir),
+		}));
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+function getSessionIndexPath(codexDir?: string): string {
+	const home = codexDir ?? join(homedir(), ".codex");
+	return join(home, "session_index.jsonl");
+}
+
+function findRolloutPath(sessionId: string, codexDir?: string): string {
+	const home = codexDir ?? join(homedir(), ".codex");
+	const sessionsDir = join(home, "sessions");
+
+	// The rollout path follows: sessions/YYYY/MM/DD/rollout-YYYY-MM-DDTHH-MM-SS-<sessionId>.jsonl
+	// We need to find the file whose name ends with <sessionId>.jsonl
+	// Since there can be multiple sessions per day, iterate all files.
+	try {
+		const { readdirSync } = require("node:fs") as typeof import("node:fs");
+		for (const dirPath of walkDirs(sessionsDir)) {
+			for (const file of readdirSync(dirPath)) {
+				if (file.endsWith(`${sessionId}.jsonl`)) {
+					return join(dirPath, file);
+				}
+			}
+		}
+	} catch {
+		// walkSync may not be available on all Node versions; fall back to find
+	}
+	return findRolloutPathFallback(sessionId, sessionsDir);
+}
+
+function findRolloutPathFallback(
+	sessionId: string,
+	sessionsDir: string,
+): string {
+	const found = walkForSession(sessionsDir, sessionId);
+	return found ?? join(sessionsDir, "unknown", `${sessionId}.jsonl`);
+}
+
+/** Recursively walk all subdirectories, yielding each directory path. */
+function* walkDirs(dir: string): Generator<string> {
+	const { readdirSync, statSync } =
+		require("node:fs") as typeof import("node:fs");
+	for (const entry of readdirSync(dir)) {
+		const full = join(dir, entry);
+		const stat = statSync(full);
+		if (stat.isDirectory()) {
+			yield full;
+			yield* walkDirs(full);
+		}
+	}
+}
+
+/** Find the rollout file for a given session ID by walking directories. */
+function walkForSession(sessionsDir: string, sessionId: string): string | null {
+	const { readdirSync } = require("node:fs") as typeof import("node:fs");
+	for (const dirPath of walkDirs(sessionsDir)) {
+		for (const file of readdirSync(dirPath)) {
+			if (file.startsWith("rollout-") && file.endsWith(`${sessionId}.jsonl`)) {
+				return join(dirPath, file);
+			}
+		}
+	}
+	return null;
+}
+
+interface SessionIndexEntry {
+	id: string;
+	thread_name: string;
+	updated_at: string;
+}
+
+function parseSessionIndexLine(line: string): SessionIndexEntry | null {
+	try {
+		const obj = JSON.parse(line) as Record<string, unknown>;
+		if (typeof obj.id !== "string" || typeof obj.thread_name !== "string") {
+			return null;
+		}
+		return {
+			id: obj.id as string,
+			thread_name: obj.thread_name as string,
+			updated_at: String(obj.updated_at ?? ""),
+		};
+	} catch {
+		return null;
+	}
+}
+
+function readLines(filePath: string): string[] {
+	try {
+		const content = readFileSync(filePath, "utf8");
+		return content.split("\n").filter((l) => l.trim().length > 0);
+	} catch {
+		return [];
+	}
+}

package/packages/codex-watcher/src/types.ts

@@ -0,0 +1,67 @@
+/**
+ * Codex Session Watcher — types
+ *
+ * Watches ~/.codex/ for active Codex CLI sessions and parses visible
+ * communication between the user and Codex (Planner role in PING-PONG).
+ *
+ * Key file locations:
+ *   ~/.codex/session_index.jsonl          — session registry
+ *   ~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl  — session transcripts
+ *
+ * Visible message schema (safe subset — no developer/reasoning):
+ *   type == "event_msg" && payload.type == "item_completed"
+ *   && payload.item.type == "AgentMessage"
+ *   && payload.item.content[].type == "Text"
+ */
+
+export interface CodexSession {
+	/** Codex session ID (UUID) */
+	id: string;
+	/** Human-readable session name */
+	threadName: string;
+	/** ISO-8601 when session was last active */
+	updatedAt: string;
+	/** Absolute path to the rollout transcript file */
+	rolloutPath: string;
+}
+
+export interface CodexMessage {
+	/** Unique ordinal within the session (monotonically increasing) */
+	ordinal: number;
+	/** ISO-8601 timestamp */
+	timestamp: string;
+	/** Role: "user" (human) or "assistant" (Codex) */
+	role: "user" | "assistant";
+	/** Raw text content (markdown, code blocks, etc.) */
+	text: string;
+	/** Whether this message is the latest known message */
+	isLatest: boolean;
+}
+
+export interface CodexEvent {
+	/** Monotonically increasing ordinal within the session */
+	ordinal: number;
+	timestamp: string;
+	/** Raw JSON payload from the JSONL line */
+	raw: unknown;
+}
+
+export interface WatcherOptions {
+	/** How often to poll session_index.jsonl and active rollout file (ms). Default: 2000 */
+	pollIntervalMs?: number;
+	/** Absolute path to Codex home. Default: ~/.codex */
+	codexDir?: string;
+	/** Called with new visible messages each poll cycle */
+	onMessages?: (messages: CodexMessage[]) => void;
+	/** Called when a new session becomes active */
+	onSessionChange?: (session: CodexSession | null) => void;
+	/** Stop watching after N polls with no new lines. Default: Infinity */
+	maxIdlePolls?: number;
+}
+
+export interface WatcherHandle {
+	stop: () => void;
+	isRunning: () => boolean;
+	latestSession: () => CodexSession | null;
+	latestOrdinal: () => number;
+}