pi-harness-runtime 1.1.31 → 1.1.32

package/harness/langchain/checkpointer.test.ts

@@ -0,0 +1,269 @@
+/**
+ * FileCheckpointSaver tests — T9–T11 (wiki/auto-trigger-multi-agent.md §M5)
+ *
+ * Run:
+ *   bun test harness/langchain/checkpointer.test.ts
+ */
+
+import { describe, it } from "node:test";
+import assert from "node:assert";
+import { existsSync, mkdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+
+import {
+	FileCheckpointSaver,
+	createLoopCheckpointer,
+} from "./checkpointer.js";
+
+// ─── Fixtures ────────────────────────────────────────────────────────────────
+
+const ROOT = `/tmp/checkpointer-test-${randomUUID().slice(0, 8)}`;
+
+function freshSaver(): FileCheckpointSaver {
+	const saver = new FileCheckpointSaver({ root: ROOT });
+	saver.clearAll();
+	return saver;
+}
+
+const THREAD = "thread-abc123";
+const CONFIG = { configurable: { thread_id: THREAD } };
+const CONFIG_WITH_CPID = {
+	configurable: { thread_id: THREAD, checkpoint_id: "cp-001" },
+};
+
+// ─── T9: Basic put/get ──────────────────────────────────────────────────────
+
+describe("T9 — put and get basic checkpoint", () => {
+	it("stores and retrieves a checkpoint", async () => {
+		const saver = freshSaver();
+
+		const checkpoint = {
+			v: 4,
+			id: "cp-001",
+			ts: "2026-08-31T10:00:00.000Z",
+			channel_values: { plan: "do the thing", code: "" },
+			channel_versions: { plan: 1, code: 0 },
+			versions_seen: {},
+		};
+		const metadata = {
+			source: "input" as const,
+			step: -1,
+			parents: {},
+		};
+
+		const updatedConfig = await saver.put(CONFIG, checkpoint, metadata, {});
+		assert.equal(
+			updatedConfig.configurable?.checkpoint_id,
+			"cp-001",
+		);
+
+		// Retrieve it
+		const tuple = await saver.getTuple(CONFIG_WITH_CPID);
+		assert.ok(tuple, "should retrieve the checkpoint");
+		assert.equal(tuple?.checkpoint.id, "cp-001");
+		assert.equal(
+			(tuple?.checkpoint.channel_values as Record<string, unknown>)?.plan,
+			"do the thing",
+		);
+	});
+
+	it("get() returns the checkpoint", async () => {
+		const saver = freshSaver();
+		const cp = {
+			v: 4,
+			id: "cp-get",
+			ts: "2026-08-31T10:01:00.000Z",
+			channel_values: { plan: "test plan" },
+			channel_versions: {},
+			versions_seen: {},
+		};
+		await saver.put(CONFIG, cp, { source: "input", step: -1, parents: {} }, {});
+
+		const retrieved = await saver.get({
+			configurable: { thread_id: THREAD, checkpoint_id: "cp-get" },
+		});
+		assert.ok(retrieved, "should return the checkpoint");
+		assert.equal(retrieved?.id, "cp-get");
+	});
+});
+
+// ─── T10: Parent chain ──────────────────────────────────────────────────────
+
+describe("T10 — parent chain", () => {
+	it("stores and retrieves a parent chain (resume)", async () => {
+		const saver = freshSaver();
+
+		const root = {
+			v: 4,
+			id: "root",
+			ts: "2026-08-31T10:00:00.000Z",
+			channel_values: {},
+			channel_versions: {},
+			versions_seen: {},
+		};
+		const child = {
+			v: 4,
+			id: "child",
+			ts: "2026-08-31T10:01:00.000Z",
+			channel_values: { plan: "the plan" },
+			channel_versions: { plan: 1 },
+			versions_seen: {},
+		};
+
+		await saver.put(
+			CONFIG,
+			root,
+			{ source: "input", step: -1, parents: {} },
+			{},
+		);
+		await saver.put(
+			CONFIG,
+			child,
+			{ source: "loop", step: 0, parents: { "": "root" } },
+			{},
+		);
+
+		// Retrieve child and verify parent
+		const tuple = await saver.getTuple({
+			configurable: { thread_id: THREAD, checkpoint_id: "child" },
+		});
+		assert.ok(tuple);
+		assert.ok(tuple?.parentConfig);
+		assert.equal(
+			tuple?.parentConfig?.configurable?.checkpoint_id,
+			"root",
+		);
+
+		// getTuple without checkpoint_id returns the latest
+		const latest = await saver.getTuple(CONFIG);
+		assert.ok(latest);
+		assert.equal(latest?.checkpoint.id, "child");
+	});
+});
+
+// ─── T11: list + deleteThread ───────────────────────────────────────────────
+
+describe("T11 — list and deleteThread", () => {
+	it("lists checkpoints in reverse chronological order", async () => {
+		const saver = freshSaver();
+
+		for (let i = 0; i < 5; i++) {
+			const cp = {
+				v: 4,
+				id: `cp-${i}`,
+				ts: new Date(1000 + i * 1000).toISOString(),
+				channel_values: { step: i },
+				channel_versions: {},
+				versions_seen: {},
+			};
+			await saver.put(
+				CONFIG,
+				cp,
+				{ source: "loop", step: i, parents: {} },
+				{},
+			);
+		}
+
+		const all: string[] = [];
+		for await (const tuple of saver.list(CONFIG)) {
+			all.push(tuple.checkpoint.id);
+		}
+		assert.equal(all.length, 5);
+		// Newest first
+		assert.equal(all[0], "cp-4");
+		assert.equal(all[4], "cp-0");
+	});
+
+	it("limits list results", async () => {
+		const saver = freshSaver();
+		for (let i = 0; i < 3; i++) {
+			const cp = {
+				v: 4,
+				id: `limit-${i}`,
+				ts: new Date(2000 + i * 1000).toISOString(),
+				channel_values: {},
+				channel_versions: {},
+				versions_seen: {},
+			};
+			await saver.put(
+				CONFIG,
+				cp,
+				{ source: "loop", step: i, parents: {} },
+				{},
+			);
+		}
+
+		const limited: string[] = [];
+		for await (const tuple of saver.list(CONFIG, { limit: 2 })) {
+			limited.push(tuple.checkpoint.id);
+		}
+		assert.equal(limited.length, 2);
+	});
+
+	it("deleteThread removes all checkpoints for a thread", async () => {
+		const saver = freshSaver();
+
+		const cp = {
+			v: 4,
+			id: "delete-me",
+			ts: "2026-08-31T12:00:00.000Z",
+			channel_values: {},
+			channel_versions: {},
+			versions_seen: {},
+		};
+		await saver.put(
+			CONFIG,
+			cp,
+			{ source: "input", step: -1, parents: {} },
+			{},
+		);
+
+		assert.ok(await saver.getTuple(CONFIG), "checkpoint should exist");
+
+		await saver.deleteThread(THREAD);
+
+		assert.ok(
+			!(await saver.getTuple(CONFIG)),
+			"checkpoint should be gone after deleteThread",
+		);
+	});
+
+	it("toJSON returns a string (not the internal object)", async () => {
+		const saver = freshSaver();
+		const json = saver.toJSON();
+		assert.equal(typeof json, "string");
+		assert.ok(json.length > 0);
+	});
+
+	it("listThreads returns thread ids", async () => {
+		const saver = freshSaver();
+		const tid = `thread-${randomUUID().slice(0, 6)}`;
+		const cp = {
+			v: 4,
+			id: "cp-t",
+			ts: "2026-08-31T12:00:00.000Z",
+			channel_values: {},
+			channel_versions: {},
+			versions_seen: {},
+		};
+		await saver.put(
+			{ configurable: { thread_id: tid } },
+			cp,
+			{ source: "input", step: -1, parents: {} },
+			{},
+		);
+
+		const threads = saver.listThreads();
+		assert.ok(threads.includes(tid), `Expected ${tid} in ${JSON.stringify(threads)}`);
+	});
+});
+
+// ─── T12: createLoopCheckpointer factory ─────────────────────────────────────
+
+describe("T12 — createLoopCheckpointer factory", () => {
+	it("creates a saver with the correct root path", () => {
+		const saver = createLoopCheckpointer("/my/workspace");
+		assert.ok(saver instanceof FileCheckpointSaver);
+	});
+});

package/harness/langchain/checkpointer.ts

@@ -0,0 +1,343 @@
+/**
+ * File-based checkpointer — persists LangGraph StateGraph checkpoints to disk.
+ *
+ * Enables crash-safe loop resume: if the daemon dies mid-task, a new instance
+ * resumes from the last checkpoint instead of restarting from scratch.
+ *
+ * Storage layout:
+ *   <root>/
+ *   ├── <threadId>/
+ *   │   ├── index.jsonl      # one line per checkpoint (id, ts, parentId, step)
+ *   │   └── <checkpointId>.json  # full checkpoint + metadata + parentConfig
+ *
+ * Wiki: wiki/auto-trigger-multi-agent.md §M5
+ */
+
+import {
+	existsSync,
+	mkdirSync,
+	readFileSync,
+	readdirSync,
+	renameSync,
+	unlinkSync,
+	writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+
+import {
+	BaseCheckpointSaver,
+	Checkpoint,
+	CheckpointListOptions,
+	CheckpointMetadata,
+	CheckpointTuple,
+} from "@langchain/langgraph-checkpoint";
+import type { ChannelVersions } from "@langchain/langgraph-checkpoint";
+import type { RunnableConfig } from "@langchain/core/runnables";
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+/** Minimal JSON serializer compatible with SerializerProtocol. */
+const jsonSerializer = {
+	async dumpsTyped(data: unknown): Promise<[string, Uint8Array]> {
+		return ["application/json", new TextEncoder().encode(JSON.stringify(data))];
+	},
+	async loadsTyped(
+		_type: string,
+		data: Uint8Array | string,
+	): Promise<unknown> {
+		try {
+			const bytes: Uint8Array =
+				typeof data === "string" ? new TextEncoder().encode(data) : data;
+			return JSON.parse(new TextDecoder().decode(bytes));
+		} catch {
+			throw new Error("Failed to deserialize checkpoint data");
+		}
+	},
+} as const;
+
+// ─── Storage helpers ────────────────────────────────────────────────────────
+
+interface IndexEntry {
+	id: string;
+	ts: string;
+	parentId?: string;
+	step: number;
+}
+
+function threadDir(root: string, threadId: string): string {
+	return join(root, `thread-${threadId}`);
+}
+
+function checkpointPath(threadDir: string, checkpointId: string): string {
+	return join(threadDir, `${checkpointId}.json`);
+}
+
+function indexPath(threadDir: string): string {
+	return join(threadDir, "index.jsonl");
+}
+
+function ensureThreadDir(root: string, threadId: string): string {
+	const dir = threadDir(root, threadId);
+	if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+	return dir;
+}
+
+function readIndex(threadDir: string): IndexEntry[] {
+	const path = indexPath(threadDir);
+	if (!existsSync(path)) return [];
+	try {
+		return readFileSync(path, "utf8")
+			.split("\n")
+			.filter((l) => l.trim())
+			.map((l) => JSON.parse(l) as IndexEntry);
+	} catch {
+		return [];
+	}
+}
+
+function appendIndex(threadDir: string, entry: IndexEntry): void {
+	const path = indexPath(threadDir);
+	const line = JSON.stringify(entry) + "\n";
+	if (existsSync(path)) {
+		const fd = require("node:fs").openSync(path, "a");
+		require("node:fs").writeSync(fd, line);
+		require("node:fs").closeSync(fd);
+	} else {
+		writeFileSync(path, line, "utf8");
+	}
+}
+
+function atomicWrite(path: string, content: string): void {
+	const tmp = `${path}.tmp`;
+	writeFileSync(tmp, content, "utf8");
+	renameSync(tmp, path);
+}
+
+// ─── FileCheckpointSaver ──────────────────────────────────────────────────────
+
+/**
+ * File-based LangGraph checkpointer. Implements BaseCheckpointSaver so it can be
+ * passed directly to `buildWriteReviewLoop()` as the `checkpointer` option.
+ *
+ * Usage:
+ *   const saver = new FileCheckpointSaver({ root: "/tmp/checkpoints" });
+ *   const loop = buildWriteReviewLoop(deps, { checkpointer: saver });
+ *
+ * On daemon restart, pass the same root — checkpoints persist across restarts.
+ */
+export class FileCheckpointSaver extends BaseCheckpointSaver {
+private readonly root: string;
+
+constructor(opts: { root: string }) {
+super(jsonSerializer);
+this.root = opts.root;
+}
+
+	// ─── BaseCheckpointSaver ─────────────────────────────────────────────
+
+	async get(config: RunnableConfig): Promise<Checkpoint | undefined> {
+		const tuple = await this.getTuple(config);
+		return tuple?.checkpoint;
+	}
+
+	async getTuple(
+		config: RunnableConfig,
+	): Promise<CheckpointTuple | undefined> {
+		const threadId = String(config.configurable?.thread_id ?? "");
+		if (!threadId) return undefined;
+
+		const dir = threadDir(this.root, threadId);
+		if (!existsSync(dir)) return undefined;
+
+		const checkpointId = String(config.configurable?.checkpoint_id ?? "");
+		if (!checkpointId) {
+			const index = readIndex(dir);
+			if (index.length === 0) return undefined;
+			return this._loadCheckpoint(config, dir, index[index.length - 1].id);
+		}
+
+		return this._loadCheckpoint(config, dir, checkpointId);
+	}
+
+	private async _loadCheckpoint(
+		config: RunnableConfig,
+		dir: string,
+		checkpointId: string,
+	): Promise<CheckpointTuple | undefined> {
+		const path = checkpointPath(dir, checkpointId);
+		if (!existsSync(path)) return undefined;
+
+		try {
+			const raw = readFileSync(path);
+			const data = JSON.parse(
+				new TextDecoder().decode(raw),
+			) as {
+				checkpoint: Checkpoint;
+				metadata: CheckpointMetadata;
+				parentConfig?: RunnableConfig;
+			};
+
+			const index = readIndex(dir);
+			const entry = index.find((e) => e.id === checkpointId);
+			const parentId = entry?.parentId;
+
+			let parentConfig: RunnableConfig | undefined;
+			if (
+				parentId &&
+				existsSync(checkpointPath(dir, parentId))
+			) {
+				parentConfig = {
+					configurable: {
+						thread_id: config.configurable?.thread_id,
+						checkpoint_id: parentId,
+					},
+				};
+			}
+
+			return {
+				config,
+				checkpoint: data.checkpoint,
+				metadata: data.metadata,
+				parentConfig: parentConfig ?? data.parentConfig,
+			};
+		} catch {
+				return undefined;
+		}
+	}
+
+	async *list(
+		config: RunnableConfig,
+		options?: CheckpointListOptions,
+	): AsyncGenerator<CheckpointTuple> {
+		const threadId = String(config.configurable?.thread_id ?? "");
+		if (!threadId) return;
+
+		const dir = threadDir(this.root, threadId);
+		if (!existsSync(dir)) return;
+
+		const index = [...readIndex(dir)].sort((a, b) =>
+			b.ts.localeCompare(a.ts),
+		);
+
+		const limit = options?.limit ?? 100;
+		let count = 0;
+
+		for (const entry of index) {
+			if (count >= limit) break;
+			const tuple = await this._loadCheckpoint(config, dir, entry.id);
+			if (tuple) yield tuple;
+			count++;
+		}
+	}
+
+	async put(
+		config: RunnableConfig,
+		checkpoint: Checkpoint,
+		metadata: CheckpointMetadata,
+		_newVersions: ChannelVersions,
+	): Promise<RunnableConfig> {
+		const threadId = String(config.configurable?.thread_id ?? "");
+		if (!threadId) throw new Error("thread_id is required for checkpointing");
+
+		const dir = ensureThreadDir(this.root, threadId);
+		const parentId = (metadata.parents as Record<string, string | undefined>)?.[""];
+
+		const path = checkpointPath(dir, checkpoint.id);
+		atomicWrite(
+			path,
+			JSON.stringify({
+				checkpoint,
+				metadata,
+				parentConfig: parentId
+					? { configurable: { thread_id: threadId, checkpoint_id: parentId } }
+					: undefined,
+			}),
+		);
+
+		appendIndex(dir, {
+			id: checkpoint.id,
+			ts: checkpoint.ts,
+			parentId,
+			step: metadata.step,
+		});
+
+		return {
+			configurable: { ...config.configurable, checkpoint_id: checkpoint.id },
+		};
+	}
+
+	async putWrites(
+		_config: RunnableConfig,
+		_writes: [],
+		_taskId: string,
+	): Promise<void> {
+		// Pending writes stored inline in the checkpoint JSON — no separate file needed.
+	}
+
+	async deleteThread(threadId: string): Promise<void> {
+		const dir = threadDir(this.root, threadId);
+		if (!existsSync(dir)) return;
+
+		for (const file of readdirSync(dir)) {
+			try {
+				unlinkSync(join(dir, file));
+			} catch {
+				/* ignore */
+			}
+		}
+
+		try {
+			require("node:fs").rmdirSync(dir);
+		} catch {
+			/* ignore */
+		}
+	}
+
+	toJSON(): string {
+		return "FileCheckpointSaver";
+	}
+
+	// ─── Inherited defaults from BaseCheckpointSaver ───────────────────────
+
+	// getDeltaChannelHistory: uses the default implementation (walks getTuple chain)
+	// getNextVersion: uses the default integer implementation
+
+	// ─── Helpers ───────────────────────────────────────────────────────
+
+	/** List all known thread IDs with saved checkpoints. */
+	listThreads(): string[] {
+		if (!existsSync(this.root)) return [];
+		return readdirSync(this.root)
+			.filter((f) => f.startsWith("thread-"))
+			.map((f) => f.replace("thread-", ""));
+	}
+
+	/** Delete all checkpoints for all threads (cleanup). */
+	clearAll(): void {
+		if (!existsSync(this.root)) return;
+		for (const thread of readdirSync(this.root)) {
+			const fullPath = join(this.root, thread);
+			if (!existsSync(fullPath)) continue;
+			for (const file of readdirSync(fullPath)) {
+				try {
+					unlinkSync(join(fullPath, file));
+				} catch {
+					/* ignore */
+				}
+			}
+			try {
+				require("node:fs").rmdirSync(fullPath);
+			} catch {
+				/* ignore */
+			}
+		}
+	}
+}
+
+// ─── Factory ────────────────────────────────────────────────────────────────
+
+/** Build a FileCheckpointSaver wired to the daemon's workspace. */
+export function createLoopCheckpointer(workspace: string): FileCheckpointSaver {
+	const root = join(workspace, ".checkpoints");
+	return new FileCheckpointSaver({ root });
+}

package/harness/langchain/daemon.test.ts

@@ -351,3 +351,48 @@ describe("T7 — crash resilience", () => {
 		}
 	});
 });
+
+// ─── T13: Persistent checkpointer (M5) ──────────────────────────────────────
+
+describe("T13 — persistent checkpointer (M5)", () => {
+	it("loop checkpoints survive daemon stop and resume from last checkpoint", async () => {
+		cleanEvents();
+		// Use persistent checkpointer (true = use workspace root for checkpoints)
+		const daemon1 = new LoopDaemon(
+			testConfig({ sources: ["inbox"], checkpointer: true }),
+		);
+		daemon1.start();
+
+		const filename = `test-T13-${randomUUID().slice(0, 6)}.md`;
+		writeFileSync(join(WORKSPACE, filename), "Persistent checkpoint test", "utf8");
+
+		// Let the loop run for one iteration
+		await new Promise((r) => setTimeout(r, 500));
+		daemon1.stop();
+
+		// Verify checkpoints exist on disk
+		const { createLoopCheckpointer } = await import("./checkpointer.js");
+		const saver = createLoopCheckpointer(WORKSPACE);
+		const threads = saver.listThreads();
+		assert.ok(
+			threads.length > 0,
+			`Expected checkpoint threads, got: ${JSON.stringify(threads)}`,
+		);
+
+		// Resume with new daemon — should pick up from checkpoint
+		const daemon2 = new LoopDaemon(
+			testConfig({ sources: ["inbox"], checkpointer: true }),
+		);
+		daemon2.start();
+		try {
+			await waitForEvent("loop.finished", 15_000);
+			assert.ok(
+				countEvents("loop.finished") >= 1,
+				"Expected loop.finished after resume",
+			);
+		} finally {
+			daemon2.stop();
+			saver.clearAll();
+		}
+	});
+});