@hank-warren/pi-loop 0.7.0 → 0.9.0

package/src/ledger.ts

@@ -44,8 +44,37 @@ export interface LoopCriterion {
 	 */
 	check: string;
 	passes: boolean;
+	/**
+	 * The citation given when `passes` was flipped, recorded by the extension
+	 * at flip time. Absent on a criterion still unmet, and on one flipped by a
+	 * hand-edit rather than through `loop_progress`.
+	 */
+	evidence?: string;
+	/** Epoch ms of the flip that recorded `evidence`. */
+	evidenceAt?: number;
 }
 
+/**
+ * The fixed headings of `PROGRESS.md`. The schema is the point: "update the
+ * ledger" means the same thing on every turn only while the sections are the
+ * same on every turn, so writes are section-scoped and a section that is not
+ * one of these is refused rather than created.
+ */
+export const PROGRESS_SECTIONS = [
+	"current status",
+	"completed",
+	"failed approaches and why",
+	"next actions",
+] as const;
+export type ProgressSection = (typeof PROGRESS_SECTIONS)[number];
+
+/** Cap on one ledger write: a progress note is a paragraph, not a transcript. */
+export const MAX_PROGRESS_TEXT_LENGTH = 4000;
+export const MAX_EVIDENCE_LENGTH = 4000;
+
+/** The template's placeholders, replaced rather than appended to on first write. */
+const PLACEHOLDERS = new Set(["not started.", "- (nothing yet)"]);
+
 export function loopLedgerDir(loopId: string, agentDir = getAgentDir()): string {
 	return join(agentDir, LEDGER_DIR_NAME, loopId);
 }
@@ -61,12 +90,7 @@ export function loopLedgerDir(loopId: string, agentDir = getAgentDir()): string
 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 bullets = collectBullets(trimmed);
 	const parts = bullets.length > 1 ? bullets : splitSentences(trimmed);
 	if (parts.length < 2) return [implicitCriterion(trimmed)];
 	return criteriaFromDescriptions(parts);
@@ -90,6 +114,46 @@ export function criteriaFromDescriptions(descriptions: readonly string[]): LoopC
 	}));
 }
 
+const BULLET_MARKER = /^([-*+]|\d+[.)])\s+/;
+
+/**
+ * Bullets, each folded back together with the lines it wrapped onto.
+ *
+ * A bullet longer than the terminal width is typed — or pasted — across
+ * several lines, and only the first carries the marker. Matching markers and
+ * discarding everything else silently truncated such a bullet at its first
+ * line, which is worse than mis-splitting it: the criterion still looked
+ * well-formed, so a requirement could vanish out of the gate with no signal.
+ * A non-blank line that starts no new bullet therefore continues the previous
+ * one. Text before the first bullet is still ignored (it is a preamble, not a
+ * requirement), and a blank line ends the bullet it follows so a trailing
+ * paragraph cannot be glued onto the last item.
+ */
+function collectBullets(text: string): string[] {
+	const bullets: string[] = [];
+	let open = false;
+	for (const raw of text.split(/\r?\n/)) {
+		const line = raw.trim();
+		if (!line) {
+			open = false;
+			continue;
+		}
+		if (BULLET_MARKER.test(line)) {
+			const body = line.replace(BULLET_MARKER, "").trim();
+			if (body) {
+				bullets.push(body);
+				open = true;
+			} else {
+				// A bare marker has no body to continue.
+				open = false;
+			}
+			continue;
+		}
+		if (open) bullets[bullets.length - 1] += ` ${line}`;
+	}
+	return bullets;
+}
+
 function implicitCriterion(objective: string): LoopCriterion {
 	return {
 		id: "c1",
@@ -197,6 +261,119 @@ export function progressTemplate(objective: string): string {
 	].join("\n");
 }
 
+/**
+ * Append to (or replace) one section of `PROGRESS.md`, leaving every other
+ * section byte-identical.
+ *
+ * This exists because the alternative the model reaches for otherwise is a
+ * whole-file overwrite, which takes out the objective line and the other
+ * three sections along with it. `createLedger` already refuses to overwrite
+ * this file for exactly that reason; the agent's write path has to honour the
+ * same rule or the protection is decorative.
+ *
+ * Returns the failure reason, or undefined on success.
+ */
+export function writeProgressSection(
+	paths: LedgerPaths,
+	section: ProgressSection,
+	text: string,
+): string | undefined {
+	const entry = text.trim();
+	if (!entry) return "the text to record was empty";
+	let contents: string;
+	try {
+		contents = readFileSync(paths.progress, "utf8");
+	} catch (error) {
+		return formatError(error);
+	}
+	const lines = contents.split(/\r?\n/);
+	const start = lines.findIndex((line) => headingText(line) === section);
+	if (start === -1) {
+		return `PROGRESS.md has no "## ${section}" section (it was renamed or removed by hand)`;
+	}
+	let end = start + 1;
+	while (end < lines.length && headingText(lines[end]) === undefined) end += 1;
+	const body = lines.slice(start + 1, end);
+	while (body.length > 0 && !body[0].trim()) body.shift();
+	while (body.length > 0 && !body[body.length - 1].trim()) body.pop();
+	const placeholder =
+		body.length === 1 && PLACEHOLDERS.has(body[0].trim().toLowerCase()) ? true : body.length === 0;
+	// Whether a write replaces or extends is a property of the section, not a
+	// choice: "current status" is a single current value and the other three are
+	// running lists. Deriving it keeps the decision out of the tool schema,
+	// where the model could get it wrong on a file nothing else can repair.
+	const next =
+		section === "current status" || placeholder
+			? entry.split("\n")
+			: [...body, "", ...entry.split("\n")];
+	const rebuilt = [...lines.slice(0, start + 1), "", ...next, "", ...lines.slice(end)];
+	try {
+		writeFileSync(paths.progress, `${rebuilt.join("\n").replace(/\n{3,}$/u, "\n")}`, "utf8");
+		return undefined;
+	} catch (error) {
+		return formatError(error);
+	}
+}
+
+function headingText(line: string | undefined): string | undefined {
+	const match = /^##\s+(.+?)\s*$/u.exec(line ?? "");
+	return match ? match[1].toLowerCase() : undefined;
+}
+
+export interface MarkCriterionResult {
+	ok: boolean;
+	message: string;
+	criteria?: LoopCriterion[];
+}
+
+/**
+ * Flip one criterion's `passes` and record the citation that justified it.
+ *
+ * The only mutation `criteria.json` accepts. Descriptions, ids, checks and the
+ * set of entries are rewritten by nothing here, so "a model may not rewrite
+ * its own acceptance criteria" stops being a rule in a skill file and becomes
+ * a property of the only available write path.
+ */
+export function markCriterion(
+	paths: LedgerPaths,
+	id: string,
+	evidence: string,
+	passes: boolean,
+	now: number,
+): MarkCriterionResult {
+	const criteria = readCriteria(paths);
+	if (!criteria) return { ok: false, message: "criteria.json is absent or unreadable" };
+	const target = criteria.find((criterion) => criterion.id === id);
+	if (!target) {
+		return {
+			ok: false,
+			message: `no criterion ${id}; this loop has ${criteria.map((c) => c.id).join(", ")}`,
+		};
+	}
+	const cited = evidence.trim();
+	if (passes && !cited) return { ok: false, message: "marking a criterion met requires evidence" };
+	const updated = criteria.map((criterion) =>
+		criterion.id === id
+			? {
+					...criterion,
+					passes,
+					...(passes ? { evidence: cited, evidenceAt: now } : {}),
+				}
+			: criterion,
+	);
+	try {
+		writeFileSync(paths.criteria, `${JSON.stringify(updated, null, 2)}\n`, "utf8");
+	} catch (error) {
+		return { ok: false, message: formatError(error) };
+	}
+	const met = updated.filter((criterion) => criterion.passes).length;
+	return {
+		ok: true,
+		message: `${id} marked ${passes ? "met" : "unmet"} (${met}/${updated.length} now passing)`,
+		criteria: updated,
+	};
+}
+
 /** Read the criteria back, fail-open: undefined when absent or unreadable. */
 export function readCriteria(paths: LedgerPaths): LoopCriterion[] | undefined {
 	let contents: string;
@@ -226,11 +403,15 @@ function normalizeCriterion(value: unknown): LoopCriterion | undefined {
 	const id = typeof record.id === "string" ? record.id.trim() : "";
 	const description = typeof record.description === "string" ? record.description.trim() : "";
 	if (!id || !description) return undefined;
+	const evidence = typeof record.evidence === "string" ? record.evidence.trim() : "";
+	const evidenceAt = record.evidenceAt;
 	return {
 		id,
 		description,
 		check: typeof record.check === "string" ? record.check : "",
 		passes: record.passes === true,
+		...(evidence ? { evidence } : {}),
+		...(typeof evidenceAt === "number" && Number.isSafeInteger(evidenceAt) ? { evidenceAt } : {}),
 	};
 }
 

package/src/loop-action-menus.ts

@@ -0,0 +1,129 @@
+/**
+ * The approval card's actions, as a menu.
+ *
+ * Presentation and choices are separate surfaces on purpose, the way
+ * pi-plan-mode splits `presentation.ts` from `plan-action-menus.ts`: the card
+ * is a durable artifact in the transcript that the user can scroll back to,
+ * and the menu is a transient dialog over it. A plain `ui.select` of label
+ * strings could not say what "start in a fresh session" means, and that is
+ * exactly the entry that needs explaining.
+ *
+ * The screen is built by a pure function so a test can assert what the menu
+ * offers without a terminal.
+ */
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { defineMenu, runMenu } from "@narumitw/pi-tui-kit";
+import type { ActionsScreen } from "@narumitw/pi-tui-kit";
+import { formatDuration } from "./interval.js";
+import type { LoopProposal } from "./planning.js";
+
+export type LoopApprovalAction =
+	| "start-here"
+	| "start-fresh"
+	| "change-cadence"
+	| "keep-editing"
+	| "cancel";
+
+type Screen = "approval";
+
+export interface LoopApprovalMenuOptions {
+	proposal: LoopProposal;
+	signal?: AbortSignal;
+	isCurrent?(): boolean;
+	startHere(): void | Promise<void>;
+	startFresh(signal: AbortSignal): void | Promise<void>;
+	changeCadence(): void | Promise<void>;
+	keepEditing(): void;
+	cancel(): void;
+}
+
+/**
+ * The approval screen. Pure and exported for tests: the set of actions on
+ * offer is the contract, and it is cheaper to pin here than through a TUI.
+ */
+export function loopApprovalScreen(
+	proposal: LoopProposal,
+): ActionsScreen<Screen, LoopApprovalAction> {
+	const criteria = `${proposal.criteria.length} ${proposal.criteria.length === 1 ? "criterion" : "criteria"}`;
+	return {
+		kind: "actions",
+		title: "Start this loop?",
+		lines: [
+			`${criteria} · fallback wake every ${formatDuration(proposal.intervalMs)} · turn cap ${proposal.maxTurns === null ? "unlimited" : proposal.maxTurns} · expires in ${formatDuration(proposal.expiresInMs)}`,
+			"The card above shows exactly what loop_complete will be held to.",
+		],
+		items: [
+			{
+				id: "start-here",
+				label: "Start loop here",
+				description: "Run it in this session, keeping the planning conversation.",
+				action: "start-here",
+			},
+			{
+				id: "start-fresh",
+				label: "Start loop in a fresh session",
+				description:
+					"Open a new session that runs the loop with only the objective — no planning history.",
+				action: "start-fresh",
+				busyLabel: "Starting the loop in a fresh session…",
+			},
+			{
+				id: "change-cadence",
+				label: "Change cadence…",
+				description: "Edit the fallback heartbeat before starting.",
+				action: "change-cadence",
+			},
+			{
+				id: "keep-editing",
+				label: "Keep editing",
+				description: "Go back to drafting; tell the agent what to change.",
+				action: "keep-editing",
+			},
+			{
+				id: "cancel",
+				label: "Cancel",
+				description: "Discard the draft. Nothing is started.",
+				action: "cancel",
+			},
+		],
+		hint: "close",
+	};
+}
+
+export async function showLoopApprovalMenu(
+	ctx: ExtensionContext,
+	options: LoopApprovalMenuOptions,
+) {
+	const menu = defineMenu<undefined, Screen, LoopApprovalAction, ExtensionContext>({
+		start: "approval",
+		screens: { approval: () => loopApprovalScreen(options.proposal) },
+		actions: {
+			"start-here": async () => {
+				await options.startHere();
+				return { kind: "close" };
+			},
+			"start-fresh": async ({ signal }) => {
+				await options.startFresh(signal);
+				return { kind: "close" };
+			},
+			"change-cadence": async () => {
+				await options.changeCadence();
+				return { kind: "close" };
+			},
+			"keep-editing": async () => {
+				options.keepEditing();
+				return { kind: "close" };
+			},
+			cancel: async () => {
+				options.cancel();
+				return { kind: "close" };
+			},
+		},
+	});
+	return runMenu(ctx, menu, {
+		getState: () => undefined,
+		...(options.signal ? { signal: options.signal } : {}),
+		...(options.isCurrent ? { isCurrent: options.isCurrent } : {}),
+	});
+}

package/src/loop-env.ts

@@ -0,0 +1,50 @@
+/**
+ * The loop-active environment contract.
+ *
+ * pi-loop publishes two variables into its own process environment while a
+ * loop is active, and removes them the moment it is not:
+ *
+ * - `PI_LOOP_ACTIVE=1` — an unattended loop is running in this session.
+ * - `PI_LOOP_ID=<id>` — the loop's id, so a reader can tell one loop from the
+ *   next without asking pi-loop anything.
+ *
+ * It exists for other extensions, and pi-auto-permissions is the first
+ * consumer: a modal permission prompt does not pause a loop, it deadlocks it,
+ * so a guardian that would have asked a human needs to know there is no human
+ * to ask. The mechanism is deliberately the one `pi-subagents` already
+ * established with `PI_SUBAGENT_CHILD=1` and `detectSubagentContext` reads —
+ * an environment variable, not a package dependency, not an import, not an
+ * RPC. Neither extension needs the other installed, in either direction, and
+ * a reader that never sees the variable behaves exactly as it does today.
+ *
+ * Both variables are set on the process, so they are visible to every
+ * extension in the session and inherited by anything it spawns. That is the
+ * point: a subagent launched by a looping session is running unattended for
+ * the same reason its parent is.
+ */
+
+import type { LoopState } from "./state.js";
+
+export const LOOP_ACTIVE_ENV = "PI_LOOP_ACTIVE";
+export const LOOP_ID_ENV = "PI_LOOP_ID";
+
+/**
+ * Publish (or withdraw) the loop-active signal for `loop`.
+ *
+ * Only an `active` loop publishes. A paused loop is not working unattended —
+ * the user paused it and is, by construction, present — and a stopped loop is
+ * not working at all, so both withdraw the signal rather than leaving a stale
+ * one behind for the rest of the session.
+ */
+export function publishLoopEnv(
+	loop: LoopState | undefined,
+	env: Record<string, string | undefined> = process.env,
+): void {
+	if (loop?.status === "active") {
+		env[LOOP_ACTIVE_ENV] = "1";
+		env[LOOP_ID_ENV] = loop.id;
+		return;
+	}
+	delete env[LOOP_ACTIVE_ENV];
+	delete env[LOOP_ID_ENV];
+}