@hank-warren/pi-loop 0.6.0 → 0.8.0

package/src/decide.ts

@@ -9,7 +9,7 @@
  *   handler for a lost continuation or an external wait, not the pacemaker.
  *
  * Both share one precedence prefix: loop liveness → expiry → plan mode →
- * compaction → busy → wait → caps → act.
+ * compaction → busy → wait → the turn cap → act.
  *
  * A loop owns its own objective and reads no other extension's state: it ends
  * only through `loop_complete`, a cap, an expiry, or the user.
@@ -49,14 +49,14 @@ export type TickDecision =
 	| { action: "none"; reason: "loop-not-active" }
 	| { action: "expire"; reason: ExpiryReason }
 	| { action: "skip"; reason: SkipReason }
-	| { action: "stop"; reason: "max-iterations" | "max-automatic-turns" }
+	| { action: "stop"; reason: "max-turns" }
 	| { action: "poke"; reason: "objective-stalled" | "wait-elapsed" };
 
 export type ContinuationDecision =
 	| { action: "none"; reason: "loop-not-active" }
 	| { action: "expire"; reason: ExpiryReason }
 	| { action: "skip"; reason: SkipReason }
-	| { action: "stop"; reason: "max-iterations" | "max-automatic-turns" }
+	| { action: "stop"; reason: "max-turns" }
 	| { action: "continue"; reason: "settled-idle" };
 
 /** Shared prefix: everything that holds or ends a loop before caps matter. */
@@ -80,17 +80,14 @@ function decideCommonPrefix(
 }
 
 /**
- * Caps are checked in a fixed order so a loop that trips both reports the
- * wake cap first — it is the one the user configured with `--max`.
+ * The one cap, counting every turn the loop caused: continuations and pokes
+ * alike. A delivered-wake cap sat next to it until it was collapsed into
+ * this one — in a settle-paced loop the wake counter can stay at zero for the
+ * loop's whole life, so it was never the ceiling that held.
  */
-function decideCaps(
-	loop: LoopState,
-): { action: "stop"; reason: "max-iterations" | "max-automatic-turns" } | undefined {
-	if (loop.maxIterations !== null && loop.iteration >= loop.maxIterations) {
-		return { action: "stop", reason: "max-iterations" };
-	}
-	if (loop.maxAutomaticTurns !== null && loop.automaticTurns >= loop.maxAutomaticTurns) {
-		return { action: "stop", reason: "max-automatic-turns" };
+function decideCap(loop: LoopState): { action: "stop"; reason: "max-turns" } | undefined {
+	if (loop.maxTurns !== null && loop.automaticTurns >= loop.maxTurns) {
+		return { action: "stop", reason: "max-turns" };
 	}
 	return undefined;
 }
@@ -103,7 +100,7 @@ function decideCaps(
 export function decideContinuation(loop: LoopState, env: TickEnvironment): ContinuationDecision {
 	const prefix = decideCommonPrefix(loop, env);
 	if (prefix) return prefix;
-	const capped = decideCaps(loop);
+	const capped = decideCap(loop);
 	if (capped) return capped;
 	return { action: "continue", reason: "settled-idle" };
 }
@@ -111,10 +108,10 @@ export function decideContinuation(loop: LoopState, env: TickEnvironment): Conti
 export function decideTick(loop: LoopState, env: TickEnvironment): TickDecision {
 	const prefix = decideCommonPrefix(loop, env);
 	if (prefix) return prefix;
-	const capped = decideCaps(loop);
+	const capped = decideCap(loop);
 	if (capped) return capped;
 	// The prefix already let a still-waiting loop skip, so a wait surviving to
 	// here is one whose deadline has come due: this wake is the wake it asked
-	// for, and it counts against the wake cap like any other.
+	// for, and the turn it starts counts against the cap like any other.
 	return { action: "poke", reason: loop.waiting ? "wait-elapsed" : "objective-stalled" };
 }

package/src/index.ts

@@ -11,23 +11,18 @@ import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-c
 import { completeLoopArguments, parseLoopCommand } from "./command.js";
 import { registerLoopCompleteTool } from "./complete-tool.js";
 import { InlineInvocationState, registerInlineInvocation } from "./inline-invocation.js";
+import { registerLoopProgressTool } from "./progress-tool.js";
+import { registerLoopProposeTool } from "./propose-tool.js";
+import { LOOP_PLANNING_HINT } from "./planning.js";
 import { registerLoopStartTool } from "./start-tool.js";
 import { registerLoopWaitTool } from "./wait-tool.js";
 import { LoopController, type LoopControllerOptions } from "./loop.js";
-import { showLoopManager, showLoopSettings } from "./manager.js";
+import { showLoopApproval, showLoopManager, showLoopSettings } from "./manager.js";
 import { buildLoopObjectivePrompt } from "./objective.js";
 import { registerLoopMessageRendering } from "./render.js";
-import { completeScheduleArguments, parseScheduleCommand } from "./schedule/command.js";
-import { describeTask, listTasks, showScheduleManager } from "./schedule/manager.js";
-import { describeSchedule } from "./schedule/model.js";
-import { Scheduler } from "./schedule/runner.js";
 
 export default function loop(pi: ExtensionAPI, options: LoopControllerOptions = {}) {
 	const controller = new LoopController(pi, options);
-	const scheduler = new Scheduler(pi, {
-		...(options.agentDir === undefined ? {} : { agentDir: options.agentDir }),
-		...(options.now === undefined ? {} : { now: options.now }),
-	});
 	// Registered unconditionally and never toggled with loop state: tools are
 	// part of the cached request prefix, so mutating the tool set mid-session
 	// would invalidate the whole conversation cache. It refuses when no loop is
@@ -36,6 +31,8 @@ export default function loop(pi: ExtensionAPI, options: LoopControllerOptions =
 	// Registered on the same terms and for the same reason: the tool set is
 	// part of the cached prefix, so it never changes with loop state.
 	registerLoopWaitTool(pi, controller);
+	registerLoopProgressTool(pi, controller);
+	registerLoopProposeTool(pi, controller);
 	// Inline invocation: an `input` handler arms a one-turn system-prompt hint
 	// for a mid-prompt `/loop` token, `before_agent_start` appends it, and
 	// loop_start is the model-invoked start it points at — refused on any turn
@@ -54,9 +51,34 @@ export default function loop(pi: ExtensionAPI, options: LoopControllerOptions =
 		handler: async (args: string, ctx: ExtensionCommandContext) => {
 			const command = parseLoopCommand(args);
 			switch (command.kind) {
-				case "show":
-					await showLoopManager(controller, ctx);
+				case "show": {
+					// Bare /loop is the front door. With a loop running it is the
+					// manager, as before. With a draft awaiting approval it is the
+					// card. With neither it opens planning, which is what used to be
+					// a one-line "no loop in this session" dead end.
+					const running = controller.state && controller.state.status !== "stopped";
+					if (running) {
+						await showLoopManager(controller, ctx);
+						return;
+					}
+					if (controller.planning.proposal) {
+						await showLoopApproval(controller, ctx);
+						return;
+					}
+					if (controller.planning.active) {
+						ctx.ui.notify(
+							"Still planning: describe the objective, and the agent will put a loop up for approval.",
+							"info",
+						);
+						return;
+					}
+					controller.beginPlanning();
+					ctx.ui.notify(
+						"Loop planning. Describe what you want the loop to achieve and how you will know it is done; the agent drafts it and puts it up for approval. Nothing starts until you approve it.",
+						"info",
+					);
 					return;
+				}
 				case "status":
 					ctx.ui.notify(controller.statusLines(ctx).join("\n"), "info");
 					return;
@@ -101,83 +123,11 @@ export default function loop(pi: ExtensionAPI, options: LoopControllerOptions =
 		},
 	});
 
-	// The scheduler is user-typed only, exactly like /loop: the model gets no
-	// scheduling tools, because a model that can schedule its own future turns
-	// can schedule its way around every limit the loop imposes.
-	pi.registerCommand("schedule", {
-		description:
-			'Schedule prompts and headless runs: /schedule [every <dur>|at <time>|cron "<expr>"] [--run] <prompt>, or list/pause/resume/run/status/delete',
-		getArgumentCompletions: (prefix: string) => completeScheduleArguments(prefix),
-		handler: async (args: string, ctx: ExtensionCommandContext) => {
-			const command = parseScheduleCommand(args, { cwd: ctx.cwd });
-			switch (command.kind) {
-				case "show":
-					await showScheduleManager(scheduler, ctx);
-					return;
-				case "list":
-					ctx.ui.notify(listTasks(scheduler).join("\n"), "info");
-					return;
-				case "error":
-					ctx.ui.notify(command.message, "error");
-					return;
-				case "create": {
-					const { task, warning } = scheduler.create(command);
-					if (warning) {
-						ctx.ui.notify(`Scheduled task not persisted: ${warning}`, "warning");
-					}
-					if (command.clampedFrom !== undefined) {
-						ctx.ui.notify("Intervals below 1 minute are raised to the minimum.", "warning");
-					}
-					ctx.ui.notify(
-						[
-							`Scheduled "${task.name}" (${task.id}): ${describeSchedule(task.schedule)}.`,
-							task.task.kind === "run"
-								? `Runs headlessly in ${task.task.cwd}; wakes this session on ${task.task.wakeOn}.`
-								: "Injects a prompt into this session at an idle boundary; it dies with the session.",
-							`Runs: ${task.maxRuns === null ? "unlimited" : `at most ${task.maxRuns}`}; expires ${new Date(task.expiresAt).toLocaleDateString()}.`,
-						].join("\n"),
-						"info",
-					);
-					return;
-				}
-				default: {
-					const task = scheduler.find(command.id);
-					if (!task) {
-						ctx.ui.notify(
-							`No scheduled task matches ${command.id}. Run /schedule list to see them.`,
-							"error",
-						);
-						return;
-					}
-					if (command.kind === "status") {
-						ctx.ui.notify(describeTask(task).join("\n"), "info");
-						return;
-					}
-					if (command.kind === "pause" || command.kind === "resume") {
-						const status = command.kind === "pause" ? "paused" : "active";
-						scheduler.update({ ...task, status });
-						ctx.ui.notify(`Task "${task.name}" is now ${status}.`, "info");
-						return;
-					}
-					if (command.kind === "run") {
-						scheduler.fireNow(task);
-						ctx.ui.notify(`Running "${task.name}" now.`, "info");
-						return;
-					}
-					scheduler.remove(task.id);
-					ctx.ui.notify(`Deleted "${task.name}".`, "info");
-				}
-			}
-		},
-	});
-
 	pi.on("session_start", async (_event, ctx) => {
 		controller.onSessionStart(ctx);
-		scheduler.onSessionStart(ctx);
 	});
 	pi.on("session_shutdown", async () => {
 		controller.onSessionShutdown();
-		scheduler.onSessionShutdown();
 	});
 	// The pacemaker: agent_end records the intent to continue, agent_settled
 	// delivers it once Pi will accept a message.
@@ -189,12 +139,16 @@ export default function loop(pi: ExtensionAPI, options: LoopControllerOptions =
 	});
 	pi.on("agent_settled", async (_event, ctx) => {
 		controller.onAgentSettled(ctx);
-		scheduler.onAgentSettled(ctx);
 	});
 	// A loop carries its own objective and injects it as a byte-stable system
 	// append, which is what lets the poke and continuation messages stay
 	// pointer-sized.
 	pi.on("before_agent_start", (event) => {
+		// Planning precedes any loop, so its guidance is injected on the same hook
+		// and is mutually exclusive with the objective append below.
+		if (controller.planning.active) {
+			return { systemPrompt: `${event.systemPrompt}\n\n${LOOP_PLANNING_HINT}` };
+		}
 		const loop = controller.state;
 		if (!loop || loop.status !== "active") return;
 		const objectivePrompt = buildLoopObjectivePrompt(loop, controller.ledger);

package/src/interval.ts

@@ -54,6 +54,31 @@ export function formatDuration(ms: number): string {
 	return `${Math.round(ms / 1_000)}s`;
 }
 
+/**
+ * Render an elapsed span approximately, for display only.
+ *
+ * `formatDuration` renders the *canonical token* for a configured interval and
+ * only ever emits one unit on an exact multiple, so an arbitrary elapsed span
+ * falls through it to seconds — 2h12m comes back as "7920s". An age needs the
+ * opposite trade: two units at most, truncated, never exact.
+ */
+export function formatElapsed(ms: number): string {
+	const clamped = Math.max(0, ms);
+	if (clamped < UNIT_MS.m) return `${Math.floor(clamped / 1_000)}s`;
+	for (const [big, small] of [
+		["d", "h"],
+		["h", "m"],
+	] as const) {
+		const bigMs = UNIT_MS[big];
+		const smallMs = UNIT_MS[small];
+		if (bigMs === undefined || smallMs === undefined || clamped < bigMs) continue;
+		const whole = Math.floor(clamped / bigMs);
+		const rest = Math.floor((clamped % bigMs) / smallMs);
+		return rest > 0 ? `${whole}${big}${rest}${small}` : `${whole}${big}`;
+	}
+	return `${Math.floor(clamped / UNIT_MS.m)}m`;
+}
+
 /** Render a wall-clock time as HH:MM for the status widget. */
 export function formatClock(timestamp: number): string {
 	const date = new Date(timestamp);

package/src/ledger.ts

@@ -30,9 +30,9 @@ 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;
+/** Cap on a loop's criteria: an objective is a paragraph, not a backlog. */
+export const MAX_CRITERIA = 12;
+export const MAX_DESCRIPTION_LENGTH = 500;
 
 export interface LoopCriterion {
 	id: string;
@@ -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,15 +90,23 @@ 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 parts.slice(0, MAX_CRITERIA).map((description, index) => ({
+	return criteriaFromDescriptions(parts);
+}
+
+/**
+ * Number a list of descriptions into criteria.
+ *
+ * Shared by the deterministic split and by the criteria a model may propose
+ * at `loop_start`, so nothing downstream — the echo at start, the evidence
+ * gate, the immutability rule — can tell the two apart. The extension still
+ * writes every field but the description: ids are positional, `check` is
+ * empty (audit against authoritative state), and a criterion starts unmet.
+ */
+export function criteriaFromDescriptions(descriptions: readonly string[]): LoopCriterion[] {
+	return descriptions.slice(0, MAX_CRITERIA).map((description, index) => ({
 		id: `c${index + 1}`,
 		description: truncate(description),
 		check: "",
@@ -77,6 +114,46 @@ export function deriveCriteria(objective: string): LoopCriterion[] {
 	}));
 }
 
+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",
@@ -184,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;
@@ -213,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 } : {}),
 	};
 }