@hank-warren/pi-loop 0.8.0 → 1.0.0

package/src/manager.ts

@@ -1,10 +1,16 @@
 /**
- * Bare-/loop manager and /loop settings, built on Pi's native dialog
- * primitives (ui.select / ui.input / ui.confirm). Non-TUI modes get status
- * notifications instead of menus.
+ * The `/loop` surfaces, wired to the controller: the manager for a live loop,
+ * the approval card's actions, and the settings editor.
+ *
+ * The top-level menus are tui-kit screens (see `loop-manager-menu.ts` and
+ * `loop-launch-menu.ts`), so the family renders the same way pi-plan-mode
+ * does. The settings editor keeps its `ui.select`/`ui.input` internals: it is
+ * a value editor, not a navigation surface, and rewriting it would change
+ * nothing a user can see. Non-TUI modes get status notifications instead of
+ * menus, exactly as before.
  */
 
-import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import type { ExtensionCommandContext, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { formatDuration, parseInterval } from "./interval.js";
 import type { LoopController } from "./loop.js";
 import {
@@ -14,134 +20,144 @@ import {
 	saveLoopSettings,
 } from "./settings.js";
 import { parseDuration } from "./interval.js";
-import { renderProposalCard } from "./planning.js";
+import type { LoopStartArguments } from "./command.js";
+import { startLoopInFreshSession } from "./fresh-launch.js";
+import { showLoopApprovalMenu } from "./loop-action-menus.js";
+import { type LoopManagerView, showLoopManagerMenu } from "./loop-manager-menu.js";
+import { showLoopLaunchMenu, showLoopPlanningMenu } from "./loop-launch-menu.js";
+import type { LoopProposal } from "./planning.js";
+import { loopWidgetLine } from "./widget.js";
 
-export async function showLoopManager(
+/** The launch menu: no loop, no draft, nothing planning. */
+export async function showLoopLaunch(
 	controller: LoopController,
 	ctx: ExtensionCommandContext,
+	startPlanning: () => void,
 ): Promise<void> {
 	if (ctx.mode !== "tui") {
-		notifyStatus(controller, ctx);
+		ctx.ui.notify(
+			"No loop in this session. The interactive /loop menu is unavailable in print and JSON modes.",
+			"info",
+		);
 		return;
 	}
-	for (;;) {
-		const loop = controller.state;
-		const options: string[] = ["Status"];
-		if (loop?.status === "active") options.push("Pause", "Edit focus", "Edit interval", "Stop");
-		else if (loop?.status === "paused") options.push("Resume", "Edit focus", "Edit interval", "Stop");
-		else options.push("Start a loop…");
-		options.push("Settings");
-		const choice = await ctx.ui.select(`Pi Loop${loop ? ` · ${loop.status}` : ""}`, options);
-		if (choice === undefined) return;
-		switch (choice) {
-			case "Status":
-				notifyStatus(controller, ctx);
-				break;
-			case "Pause":
-				controller.pauseLoop(ctx);
-				break;
-			case "Resume":
-				controller.resumeLoop(ctx);
-				break;
-			case "Stop":
-				controller.stopLoop(ctx);
-				break;
-			case "Start a loop…":
-				await startFromMenu(controller, ctx);
-				break;
-			case "Edit focus":
-				await editPrompt(controller, ctx);
-				break;
-			case "Edit interval":
-				await editInterval(controller, ctx);
-				break;
-			case "Settings":
-				await showLoopSettings(controller, ctx);
-				break;
-			default:
-				return;
-		}
-	}
-}
-
-function notifyStatus(controller: LoopController, ctx: ExtensionCommandContext): void {
-	ctx.ui.notify(controller.statusLines(ctx).join("\n"), "info");
+	await showLoopLaunchMenu(ctx, {
+		startPlanning,
+		settings: async () => {
+			await showLoopSettings(controller, ctx);
+		},
+	});
 }
 
-async function startFromMenu(
+/** The planning menu: a drafting conversation is open with no draft yet. */
+export async function showLoopPlanning(
 	controller: LoopController,
 	ctx: ExtensionCommandContext,
+	options: { requestProposal: () => void },
 ): Promise<void> {
-	const intervalText = await ctx.ui.input("Wake interval (e.g. 5m, 2h)", "5m");
-	if (intervalText === undefined) return;
-	const interval = parseInterval(intervalText.trim() || "5m");
-	if (!interval) {
-		ctx.ui.notify(`Invalid interval: ${intervalText}. Use <number><unit>, e.g. 5m.`, "error");
+	if (ctx.mode !== "tui") {
+		ctx.ui.notify(
+			"Loop planning is open: describe the objective, and the agent will put a loop up for approval.",
+			"info",
+		);
 		return;
 	}
-	// The loop owns its objective, so the text is required — asking for it here
-	// is what replaces the old dead-end refusal.
-	const promptText = await ctx.ui.input(
-		"Objective, including how the loop knows it is done",
-		"e.g. get CI green on main, verified by a passing run",
-	);
-	if (promptText === undefined) return;
-	const prompt = promptText.trim();
-	if (!prompt) {
-		ctx.ui.notify("A loop needs an objective, so no loop was started.", "warning");
+	await showLoopPlanningMenu(ctx, {
+		requestProposal: options.requestProposal,
+		cancelPlanning: () => {
+			controller.endPlanning();
+			ctx.ui.notify("Loop planning cancelled. Nothing was started.", "info");
+		},
+		settings: async () => {
+			await showLoopSettings(controller, ctx);
+		},
+	});
+}
+
+export async function showLoopManager(
+	controller: LoopController,
+	ctx: ExtensionCommandContext,
+): Promise<void> {
+	if (ctx.mode !== "tui") {
+		notifyStatus(controller, ctx);
 		return;
 	}
-	const result = controller.startLoop(ctx, {
-		kind: "start",
-		requestedMs: interval.requestedMs,
-		intervalMs: interval.effectiveMs,
-		clamped: interval.clamped,
-		...(prompt ? { prompt } : {}),
+	await showLoopManagerMenu(ctx, {
+		getView: () => managerView(controller, ctx),
+		pause: () => controller.pauseLoop(ctx),
+		resume: () => controller.resumeLoop(ctx),
+		stop: () => controller.stopLoop(ctx),
+		settings: async () => {
+			await showLoopSettings(controller, ctx);
+		},
+		setFocus: (value) => setFocus(controller, ctx, value),
+		setCadence: (value) => setCadence(controller, ctx, value),
 	});
-	if (!result.ok) ctx.ui.notify(result.message, "error");
 }
 
-async function editPrompt(controller: LoopController, ctx: ExtensionCommandContext): Promise<void> {
+/** The live loop as the manager needs it, or undefined once it has stopped. */
+function managerView(
+	controller: LoopController,
+	ctx: ExtensionContext,
+): LoopManagerView | undefined {
 	const loop = controller.state;
-	if (!loop || loop.status === "stopped") return;
-	const next = await ctx.ui.input(
-		"Loop focus (optional, restated on every loop message)",
-		loop.prompt ?? "",
-	);
-	if (next === undefined) return;
-	const prompt = next.trim();
+	if (!loop || loop.status === "stopped") return undefined;
+	const view = controller.widgetView();
+	return {
+		status: loop.status,
+		headline: view ? loopWidgetLine(view) : `loop ${loop.status}`,
+		statusLines: controller.statusLines(ctx),
+		...(loop.prompt ? { focus: loop.prompt } : {}),
+		interval: formatDuration(loop.intervalMs),
+	};
+}
+
+function notifyStatus(controller: LoopController, ctx: ExtensionCommandContext): void {
+	ctx.ui.notify(controller.statusLines(ctx).join("\n"), "info");
+}
+
+/** An empty value clears the focus; anything else replaces it. */
+function setFocus(
+	controller: LoopController,
+	ctx: ExtensionCommandContext,
+	value: string,
+): boolean {
+	const loop = controller.state;
+	if (!loop || loop.status === "stopped") return false;
+	const prompt = value.trim();
 	if (prompt) controller.state = { ...loop, prompt };
 	else {
 		const { prompt: _dropped, ...rest } = loop;
 		controller.state = rest;
 	}
 	controller.persist();
-	ctx.ui.notify("Loop focus updated.", "info");
+	controller.updateWidget();
+	ctx.ui.notify(prompt ? "Loop focus updated." : "Loop focus cleared.", "info");
+	return true;
 }
 
-async function editInterval(
+function setCadence(
 	controller: LoopController,
 	ctx: ExtensionCommandContext,
-): Promise<void> {
+	value: string,
+): boolean {
 	const loop = controller.state;
-	if (!loop || loop.status === "stopped") return;
-	const next = await ctx.ui.input("Wake interval (e.g. 5m, 2h)", formatDuration(loop.intervalMs));
-	if (next === undefined) return;
-	const interval = parseInterval(next.trim());
+	if (!loop || loop.status === "stopped") return false;
+	const interval = parseInterval(value.trim());
 	if (!interval) {
-		ctx.ui.notify(`Invalid interval: ${next}. Use <number><unit>, e.g. 5m.`, "error");
-		return;
+		ctx.ui.notify(`Invalid interval: ${value}. Use <number><unit>, e.g. 5m.`, "error");
+		return false;
 	}
 	controller.state = { ...loop, intervalMs: interval.effectiveMs };
 	controller.persist();
-	if (loop.status === "active") {
-		// Re-arm on the new cadence from now.
-		controller.resumeAfterEdit();
-	}
+	// Re-arm on the new cadence from now.
+	if (loop.status === "active") controller.resumeAfterEdit();
+	else controller.updateWidget();
 	ctx.ui.notify(
 		`Loop interval set to ${formatDuration(interval.effectiveMs)}${interval.clamped ? " (clamped to the minimum)" : ""}.`,
 		"info",
 	);
+	return true;
 }
 
 export async function showLoopSettings(
@@ -166,7 +182,8 @@ export async function showLoopSettings(
 		const next = structuredClone(s);
 		if (index === 0) {
 			// Unlimited is a first-class choice, not a magic word typed into a free
-			// text box: it is only reachable by discovery otherwise.
+			// text box: it is only reachable by discovery otherwise. It is also the
+			// default, so this editor is where a user opts *into* a budget.
 			const cap = await editCap(ctx, "Max loop turns", "no turn cap", s.maxTurns);
 			if (cap === undefined) continue;
 			next.maxTurns = cap === "unlimited" ? null : cap;
@@ -214,8 +231,7 @@ export async function showLoopSettings(
 /**
  * One cap editor for every cap. Unlimited is a first-class choice, not a
  * magic word typed into a free text box: it is only reachable by discovery
- * otherwise. The typed word still works, so the /loop --max vocabulary and
- * muscle memory keep working.
+ * otherwise. The typed word still works too.
  */
 async function editCap(
 	ctx: ExtensionCommandContext,
@@ -272,11 +288,11 @@ function applySettings(
  * The approval card and its actions.
  *
  * This is where a planned loop starts, and the approval is what authorises it.
- * `loop_start`'s gate exists because a loop is self-continuing and must never
- * begin on model initiative; an explicit choice here, on a card showing the
- * objective, the derived criteria, the cadence and the caps, is stronger
- * evidence of intent than a typed token, so it starts the loop directly rather
- * than routing back through a tool the model could reach on its own.
+ * A loop is self-continuing and must never begin on model initiative; an
+ * explicit choice here, on a card showing the objective, the derived criteria,
+ * the ground rules, the cadence and the caps, is the strongest evidence of
+ * intent there is — stronger than any token the model could also emit — so it
+ * starts the loop directly rather than routing back through a tool.
  */
 export async function showLoopApproval(
 	controller: LoopController,
@@ -284,59 +300,109 @@ export async function showLoopApproval(
 ): Promise<void> {
 	const proposal = controller.planning.proposal;
 	if (!proposal) return;
-	ctx.ui.notify(renderProposalCard(proposal).join("\n"), "info");
+	// The card is an artifact, emitted once per draft; the menu below is the
+	// dialog over it. A draft proposed by loop_propose already has its card, so
+	// this only renders one when the user reached the approval some other way.
+	controller.showProposalCard(ctx);
 	if (ctx.mode !== "tui") {
-		ctx.ui.notify(
-			"Approve it from a TUI session, or start it directly with /loop <interval> <objective>.",
-			"info",
-		);
+		ctx.ui.notify("Approve it from a TUI session; a loop cannot be started headless.", "info");
 		return;
 	}
-	const choice = await ctx.ui.select("Start this loop?", [
-		"Start loop",
-		"Change cadence",
-		"Keep editing",
-		"Cancel",
-	]);
-	switch (choice) {
-		case "Start loop": {
-			const result = controller.startLoop(ctx, {
-				kind: "start",
-				requestedMs: proposal.intervalMs,
-				intervalMs: proposal.intervalMs,
-				clamped: false,
-				maxTurns: proposal.maxTurns,
-				expiresInMs: proposal.expiresInMs,
-				prompt: proposal.objective,
-			});
+	await showLoopApprovalMenu(ctx, {
+		proposal,
+		startHere: () => {
+			const result = controller.startLoop(ctx, startArgumentsFor(proposal));
 			if (result.ok) controller.endPlanning();
 			else ctx.ui.notify(result.message, "error");
-			return;
-		}
-		case "Change cadence": {
-			const text = await ctx.ui.input(
-				"Fallback heartbeat (e.g. 30m). The loop advances whenever the session settles.",
-				formatDuration(proposal.intervalMs),
-			);
-			if (text === undefined) return;
-			const interval = parseInterval(text.trim());
-			if (!interval) {
-				ctx.ui.notify(`Invalid interval: ${text}. Use <number><unit>, e.g. 30m.`, "error");
-				return;
-			}
-			controller.propose(proposal.objective, {
-				intervalMs: interval.effectiveMs,
-				maxTurns: proposal.maxTurns,
-				expiresInMs: proposal.expiresInMs,
-			});
-			await showLoopApproval(controller, ctx);
-			return;
-		}
-		case "Keep editing":
+		},
+		startFresh: async () => {
+			await startApprovedLoopFresh(controller, ctx, proposal);
+		},
+		changeCadence: async () => {
+			await changeCadence(controller, ctx, proposal);
+		},
+		keepEditing: () => {
 			ctx.ui.notify("Still planning. Tell the agent what to change.", "info");
-			return;
-		default:
+		},
+		cancel: () => {
 			controller.endPlanning();
 			ctx.ui.notify("Loop planning cancelled. Nothing was started.", "info");
+		},
+	});
+}
+
+/** The approved draft, as the arguments both start paths take. */
+function startArgumentsFor(proposal: LoopProposal): LoopStartArguments {
+	return {
+		kind: "start",
+		requestedMs: proposal.intervalMs,
+		intervalMs: proposal.intervalMs,
+		clamped: false,
+		maxTurns: proposal.maxTurns,
+		expiresInMs: proposal.expiresInMs,
+		prompt: proposal.objective,
+		// The approved constraints cross with the objective; they are part of what
+		// the user said yes to.
+		...(proposal.groundRules ? { groundRules: proposal.groundRules } : {}),
+	};
+}
+
+/**
+ * Build the loop here, install it over there. The build/install split is what
+ * makes this possible at all: the state has to exist before `newSession` so
+ * its `setup` can append it, and it must not be installed in this session or
+ * the planning session would start working the objective it is handing away.
+ */
+async function startApprovedLoopFresh(
+	controller: LoopController,
+	ctx: ExtensionCommandContext,
+	proposal: LoopProposal,
+): Promise<void> {
+	const built = controller.buildLoop(startArgumentsFor(proposal));
+	if (!built.ok) {
+		ctx.ui.notify(built.message, "error");
+		return;
+	}
+	const result = await startLoopInFreshSession(ctx, {
+		built: built.built,
+		prepareLedger: () => controller.prepareLedgerFor(built.built),
+	});
+	switch (result.kind) {
+		case "started":
+		case "partial":
+			// The draft has been handed off either way: the planning session must
+			// not keep offering to start it a second time.
+			controller.endPlanning();
+			return;
+		case "cancelled":
+			return;
+		default:
+			ctx.ui.notify(result.detail, "error");
 	}
 }
+
+async function changeCadence(
+	controller: LoopController,
+	ctx: ExtensionCommandContext,
+	proposal: LoopProposal,
+): Promise<void> {
+	const text = await ctx.ui.input(
+		"Fallback heartbeat (e.g. 30m). The loop advances whenever the session settles.",
+		formatDuration(proposal.intervalMs),
+	);
+	if (text === undefined) return;
+	const interval = parseInterval(text.trim());
+	if (!interval) {
+		ctx.ui.notify(`Invalid interval: ${text}. Use <number><unit>, e.g. 30m.`, "error");
+		return;
+	}
+	// A new draft, so it gets a new card: the cadence on the old one is no
+	// longer what would start.
+	controller.propose(proposal.objective, {
+		intervalMs: interval.effectiveMs,
+		maxTurns: proposal.maxTurns,
+		expiresInMs: proposal.expiresInMs,
+		...(proposal.groundRules ? { groundRules: proposal.groundRules } : {}),
+	});
+	await showLoopApproval(controller, ctx);
+}

package/src/messages.ts

@@ -20,7 +20,7 @@ export type ContinuationKind = "kickoff" | "continue" | "reanchor";
  * counter against the delivered-wake cap; that cap is gone, collapsed into
  * the single loop-turn cap, and pairing a wake number with a turn cap would
  * have been a number that reads as a budget and is not one. The cap is shown
- * to the *user*, in the widget and `/loop status`, which is who it is for.
+ * to the *user*, in the widget and the /loop status screen, which is who it is for.
  */
 function formatWakeOrdinal(loop: LoopState): string {
 	return `${loop.iteration + 1}`;

package/src/objective.ts

@@ -32,6 +32,7 @@ export function buildLoopObjectivePrompt(
 		"<loop_objective>",
 		escapeXmlText(loop.objective),
 		"</loop_objective>",
+		...groundRuleLines(loop),
 		`<loop_id>\n${escapeXmlText(loop.id)}\n</loop_id>`,
 		"This loop_id is only the loop_complete tool's stale-loop guard, not part of the objective.",
 		"",
@@ -52,7 +53,19 @@ export function buildLoopObjectivePrompt(
 		"- You are running unattended. A prompt that blocks on a human — a permission approval, a clarifying question, any tool that waits for an answer — does not pause this loop, it deadlocks it: the session stays busy, so no continuation fires, no wake lands, and no cap trips. Nothing ends the loop until it expires. Plan to work without prompting.",
 		"- Decide rather than ask. Take the reversible option, record the decision and the reasoning behind it in the ledger, and keep going. A decision written down is worth more than a question nobody is there to answer.",
 		"- When you genuinely need a human, call loop_wait: it is the only way to ask that does not deadlock the session. Put the options in the ledger first, so the answer can be one word.",
-		"- Never reshape a command to get past a permission prompt. A blocked command means stop and ask through loop_wait, never find another way around it.",
+		// The old wording forbade reshaping a blocked command outright, and a
+		// permission guardian that blocks with a stated concern depends on exactly
+		// that: its block is an instruction to fix the named problem. Both cannot
+		// stand, and "never reshape" is the one that was wrong — it made every
+		// block terminal, including the ones that named a one-word fix. The line
+		// that matters is not whether the command changes but what the change is
+		// aimed at: satisfying the concern, or getting around the gate that raised
+		// it. So the prohibition is stated against the aim, and the number of
+		// attempts is bounded so that "revise to address it" cannot decay into
+		// "retry until it passes".
+		"- Never reshape a command to get around a permission gate. Splitting it up, obfuscating it, routing it through another tool, or retrying variations until one is allowed are all the same move, and it is forbidden however the loop is going.",
+		"- A block that states a concern is different: it names something to fix, and fixing exactly that is legitimate. Revise only to satisfy the stated concern, and only while the block says rounds remain against it. When they run out, the block will say so — stop revising and call loop_wait.",
+		"- A block that states no concern, or one you cannot address without widening what the command does, is already final. Do not spend the rounds; call loop_wait.",
 		"- Prefer the undoable. Nobody is watching to catch a bad call, so when two paths are close, take the one that is cheap to reverse.",
 		...(ledger ? ledgerRules(ledger) : []),
 		`${focus}`,
@@ -61,6 +74,30 @@ export function buildLoopObjectivePrompt(
 		.trimEnd();
 }
 
+/**
+ * The approved ground rules, as a block the model cannot mistake for the
+ * objective.
+ *
+ * They sit next to the objective rather than inside it because they are a
+ * different kind of thing: the objective is what the loop is trying to reach
+ * and what `loop_complete` answers for, while these bound how it may get
+ * there. Folding them into the objective would make them criteria, and a
+ * constraint that has to be "met" is a constraint nobody can satisfy.
+ *
+ * Approved by the user on the card, so unlike the objective they are not
+ * merely task data to consider — they outrank the loop's own judgement about
+ * what is expedient at 3am on turn 200.
+ */
+function groundRuleLines(loop: LoopState): string[] {
+	if (!loop.groundRules || loop.groundRules.length === 0) return [];
+	return [
+		"",
+		"Ground rules (hard constraints, never violate):",
+		...loop.groundRules.map((rule) => `- ${escapeXmlText(rule)}`),
+		"The user approved these with the objective. They bound how the work may be done, they are never satisfied or completed, and no amount of progress justifies breaking one. If the only way forward violates a ground rule, stop and call loop_wait.",
+	];
+}
+
 /**
  * The ledger contract. Stable per loop (the path is derived from the loop
  * id), so it keeps the append byte-identical across turns.