@hank-warren/pi-loop 0.4.0 → 0.5.0

package/src/ledger.ts

@@ -0,0 +1,230 @@
+/**
+ * The loop ledger: `~/.pi/agent/loop/<loop-id>/`.
+ *
+ * A multi-day loop cannot keep its state in the conversation — compaction is
+ * lossy by construction, and every summary of a summary drifts further from
+ * what actually happened. So the conversation stays the working memory and
+ * two files on disk become the record:
+ *
+ * - `criteria.json` — the completion criteria, written by the extension. JSON
+ *   deliberately, not Markdown: models rewrite prose they are asked to
+ *   maintain far more readily than they rewrite a structured file, and the
+ *   only edit this file may receive is flipping `passes`.
+ * - `PROGRESS.md` — the agent-maintained ledger, created here with a fixed
+ *   schema so "update the ledger" means the same thing on every turn.
+ *
+ * Keyed by **loop id**, not session id: session ids are not stably exposed to
+ * extensions, and one session can run several loops in sequence.
+ *
+ * Every operation here is best-effort. A read-only home directory, a full
+ * disk, or a file the user hand-edited into invalid JSON must degrade the
+ * loop to "no ledger", never break it: the ledger is an anchor for the model,
+ * not a dependency of the engine.
+ */
+
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
+export const LEDGER_DIR_NAME = "loop";
+export const CRITERIA_FILE = "criteria.json";
+export const PROGRESS_FILE = "PROGRESS.md";
+
+/** Cap on derived criteria: an objective is a paragraph, not a backlog. */
+const MAX_CRITERIA = 12;
+const MAX_DESCRIPTION_LENGTH = 500;
+
+export interface LoopCriterion {
+	id: string;
+	description: string;
+	/**
+	 * How the criterion is verified. Empty means "audit against authoritative
+	 * current state"; the extension writes this field and the model may not
+	 * change it.
+	 */
+	check: string;
+	passes: boolean;
+}
+
+export function loopLedgerDir(loopId: string, agentDir = getAgentDir()): string {
+	return join(agentDir, LEDGER_DIR_NAME, loopId);
+}
+
+/**
+ * Split an objective into checkable criteria.
+ *
+ * Deterministic and dumb on purpose: bullets first (a user who wrote a list
+ * meant a list), otherwise sentences. An objective with no separable parts
+ * yields the single implicit criterion, so `criteria.json` is never empty and
+ * `loop_complete` always has something concrete to answer for.
+ */
+export function deriveCriteria(objective: string): LoopCriterion[] {
+	const trimmed = objective.trim();
+	if (!trimmed) return [implicitCriterion(objective)];
+	const bullets = trimmed
+		.split(/\r?\n/)
+		.map((line) => line.trim())
+		.filter((line) => /^([-*+]|\d+[.)])\s+/.test(line))
+		.map((line) => line.replace(/^([-*+]|\d+[.)])\s+/, "").trim())
+		.filter(Boolean);
+	const parts = bullets.length > 1 ? bullets : splitSentences(trimmed);
+	if (parts.length < 2) return [implicitCriterion(trimmed)];
+	return parts.slice(0, MAX_CRITERIA).map((description, index) => ({
+		id: `c${index + 1}`,
+		description: truncate(description),
+		check: "",
+		passes: false,
+	}));
+}
+
+function implicitCriterion(objective: string): LoopCriterion {
+	return {
+		id: "c1",
+		description: truncate(objective.trim()) || "objective met as stated",
+		check: "",
+		passes: false,
+	};
+}
+
+/**
+ * Sentence split that survives how objectives are actually typed: mostly
+ * lowercase, occasionally with an abbreviation in the middle. Splitting on
+ * any letter after a full stop would turn "e.g. run the tests" into two
+ * criteria, so a fragment following a known abbreviation is merged back.
+ */
+const ABBREVIATION = /\b(?:e\.g|i\.e|etc|vs|cf|approx|no|fig|dr|mr|ms|mrs|st)\.$/iu;
+
+function splitSentences(text: string): string[] {
+	const parts = text
+		.split(/(?<=[.!?])\s+(?=[\p{L}\d])/u)
+		.map((sentence) => sentence.trim().replace(/\s+/gu, " "))
+		.filter((sentence) => sentence.length > 2);
+	const merged: string[] = [];
+	for (const part of parts) {
+		const previous = merged.at(-1);
+		if (previous !== undefined && ABBREVIATION.test(previous)) {
+			merged[merged.length - 1] = `${previous} ${part}`;
+			continue;
+		}
+		merged.push(part);
+	}
+	return merged;
+}
+
+function truncate(value: string): string {
+	const collapsed = value.replace(/\s+/gu, " ").trim();
+	return collapsed.length <= MAX_DESCRIPTION_LENGTH
+		? collapsed
+		: `${collapsed.slice(0, MAX_DESCRIPTION_LENGTH - 1)}…`;
+}
+
+export interface LedgerPaths {
+	dir: string;
+	criteria: string;
+	progress: string;
+}
+
+export function ledgerPaths(loopId: string, agentDir?: string): LedgerPaths {
+	const dir = loopLedgerDir(loopId, agentDir);
+	return { dir, criteria: join(dir, CRITERIA_FILE), progress: join(dir, PROGRESS_FILE) };
+}
+
+/**
+ * Create the ledger for a loop. Returns the failure reason, or undefined on
+ * success — the caller warns once and carries on either way.
+ *
+ * `criteria.json` is authoritative and overwritten on start (a new loop has
+ * new criteria). `PROGRESS.md` is only ever created, never overwritten: it is
+ * the agent's file, and a session restart must not erase days of ledger.
+ */
+export function createLedger(
+	paths: LedgerPaths,
+	objective: string,
+	criteria: LoopCriterion[],
+): string | undefined {
+	try {
+		mkdirSync(paths.dir, { recursive: true });
+		writeFileSync(paths.criteria, `${JSON.stringify(criteria, null, 2)}\n`, "utf8");
+		try {
+			writeFileSync(paths.progress, progressTemplate(objective), { encoding: "utf8", flag: "wx" });
+		} catch (error) {
+			// EEXIST is the normal case on restore: keep the existing ledger.
+			if (!isNodeError(error) || error.code !== "EEXIST") throw error;
+		}
+		return undefined;
+	} catch (error) {
+		return formatError(error);
+	}
+}
+
+export function progressTemplate(objective: string): string {
+	return [
+		"# Loop progress ledger",
+		"",
+		`Objective: ${objective.replace(/\s+/gu, " ").trim()}`,
+		"",
+		"Maintained by the agent. Keep these four sections; replace their contents.",
+		"",
+		"## Current status",
+		"",
+		"Not started.",
+		"",
+		"## Completed",
+		"",
+		"- (nothing yet)",
+		"",
+		"## Failed approaches and why",
+		"",
+		"- (nothing yet)",
+		"",
+		"## Next actions",
+		"",
+		"- (nothing yet)",
+		"",
+	].join("\n");
+}
+
+/** Read the criteria back, fail-open: undefined when absent or unreadable. */
+export function readCriteria(paths: LedgerPaths): LoopCriterion[] | undefined {
+	let contents: string;
+	try {
+		contents = readFileSync(paths.criteria, "utf8");
+	} catch {
+		return undefined;
+	}
+	try {
+		const parsed: unknown = JSON.parse(contents);
+		if (!Array.isArray(parsed)) return undefined;
+		const criteria: LoopCriterion[] = [];
+		for (const value of parsed) {
+			const criterion = normalizeCriterion(value);
+			if (!criterion) return undefined;
+			criteria.push(criterion);
+		}
+		return criteria.length > 0 ? criteria : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+function normalizeCriterion(value: unknown): LoopCriterion | undefined {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+	const record = value as Record<string, unknown>;
+	const id = typeof record.id === "string" ? record.id.trim() : "";
+	const description = typeof record.description === "string" ? record.description.trim() : "";
+	if (!id || !description) return undefined;
+	return {
+		id,
+		description,
+		check: typeof record.check === "string" ? record.check : "",
+		passes: record.passes === true,
+	};
+}
+
+function isNodeError(error: unknown): error is NodeJS.ErrnoException {
+	return error instanceof Error && "code" in error;
+}
+
+function formatError(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}