@hank-warren/pi-loop 0.9.0 → 1.1.0

package/src/command.ts

@@ -1,23 +1,39 @@
 /**
- * Deterministic /loop argument parsing. Grammar:
+ * The whole `/loop` grammar, which is now two cases:
  *
- *   /loop                                    -> show (manager TUI / status)
- *   /loop status|pause|resume|stop|settings  -> subcommand
- *   /loop [flags] <interval> [flags] [prompt...]
+ *   /loop          -> the menu (context-sensitive: launch, planning, approval, manager)
+ *   /loop <text>   -> open planning and send <text> as the first drafting message
  *
- * Flags (`--max N`, `--compact-at X`, `--expires 3d`) may appear on either
- * side of the interval; the interval is the first non-flag token, and
- * everything after the trailing flags (raw, newlines preserved) is the
- * prompt. Accepting them on both sides is not politeness: when they were
- * positional, `/loop 5m --max 3 fix the tests` silently folded the flag into
- * the objective and applied the default instead.
+ * Everything else that used to live here — a typed start (`/loop 5m fix CI`),
+ * its flags, and the `status|pause|resume|stop|settings` subcommands — is
+ * gone. A loop's objective becomes its acceptance gate, and a command line is
+ * the worst place to author one: the flags were invisible, the interval was
+ * mandatory for no reason a user could see, and the criteria were frozen
+ * before anyone had seen them. Planning plus an approval card replaces all of
+ * it, and the menu carries the lifecycle actions the subcommands used to.
+ *
+ * Consequence worth stating plainly: `/loop status` is no longer a
+ * subcommand, so it seeds planning with the word "status". That is the price
+ * of having exactly one way in, and the menu is one keystroke away.
  */
 
-import { parseDuration, parseInterval } from "./interval.js";
+export type LoopCommand =
+	/** Bare `/loop`: open whichever menu the current state calls for. */
+	| { kind: "menu" }
+	/** `/loop <text>`: enter planning and send the text as the first message. */
+	| { kind: "seed"; text: string };
 
-export const LOOP_SUBCOMMANDS = ["status", "pause", "resume", "stop", "settings"] as const;
-export type LoopSubcommand = (typeof LOOP_SUBCOMMANDS)[number];
+export function parseLoopCommand(args: string): LoopCommand {
+	const trimmed = args.trim();
+	return trimmed ? { kind: "seed", text: trimmed } : { kind: "menu" };
+}
 
+/**
+ * The arguments a loop is built from.
+ *
+ * Only two callers construct these now — the approval card's start actions —
+ * so the shape is the approved draft, not a parsed command line.
+ */
 export interface LoopStartArguments {
 	kind: "start";
 	requestedMs: number;
@@ -31,180 +47,10 @@ export interface LoopStartArguments {
 	expiresInMs?: number;
 	prompt?: string;
 	/**
-	 * Completion criteria proposed at `loop_start`, replacing the deterministic
-	 * split of the objective. Only the tool sets this: a typed `/loop` always
-	 * splits, because there is no model in that path to propose anything.
+	 * Completion criteria proposed with the draft, replacing the deterministic
+	 * split of the objective.
 	 */
 	criteria?: string[];
-}
-
-export type LoopCommand =
-	| { kind: "show" }
-	| { kind: LoopSubcommand }
-	| LoopStartArguments
-	| { kind: "error"; message: string };
-
-export function parseLoopCommand(args: string): LoopCommand {
-	const trimmed = args.trim();
-	if (!trimmed) return { kind: "show" };
-	if ((LOOP_SUBCOMMANDS as readonly string[]).includes(trimmed)) {
-		return { kind: trimmed as LoopSubcommand };
-	}
-
-	const tokens = [...args.matchAll(/\S+/g)].map((match) => ({
-		text: match[0],
-		index: match.index,
-	}));
-	const flags: LoopFlags = {};
-	const beforeInterval = scanFlags(tokens, 0, flags);
-	if (typeof beforeInterval !== "number") return beforeInterval;
-
-	const intervalToken = tokens[beforeInterval];
-	if (intervalToken === undefined) {
-		return { kind: "error", message: "An interval is required to start a loop, e.g. /loop 5m <prompt>." };
-	}
-	const interval = parseInterval(intervalToken.text);
-	if (!interval) {
-		return {
-			kind: "error",
-			message: `Invalid interval: ${intervalToken.text}. Use <number><unit> with unit s, m, h, or d, e.g. 5m.`,
-		};
-	}
-	// Flags are also accepted *after* the interval. They used to be positional,
-	// which meant `/loop 5m --max 3 fix the tests` silently made "--max 3 fix
-	// the tests" the objective: no error, a polluted objective, and a setting
-	// that quietly did not apply.
-	const afterInterval = scanFlags(tokens, beforeInterval + 1, flags);
-	if (typeof afterInterval !== "number") return afterInterval;
-	const { maxTurns, compactAt, expiresInMs } = flags;
-
-	const promptToken = tokens[afterInterval];
-	const prompt = promptToken === undefined ? undefined : args.slice(promptToken.index).trim();
-	return {
-		kind: "start",
-		requestedMs: interval.requestedMs,
-		intervalMs: interval.effectiveMs,
-		clamped: interval.clamped,
-		...(maxTurns === undefined ? {} : { maxTurns }),
-		...(compactAt === undefined ? {} : { compactAt }),
-		...(expiresInMs === undefined ? {} : { expiresInMs }),
-		...(prompt ? { prompt } : {}),
-	};
-}
-
-interface LoopFlags {
-	maxTurns?: number | null;
-	compactAt?: number | null;
-	expiresInMs?: number;
-}
-
-/**
- * Consume leading `--flag` tokens starting at `position`, filling `flags`.
- * Returns the index of the first non-flag token, or the parse error.
- */
-function scanFlags(
-	tokens: ReadonlyArray<{ text: string; index: number }>,
-	position: number,
-	flags: LoopFlags,
-): number | { kind: "error"; message: string } {
-	while (position < tokens.length) {
-		const token = tokens[position];
-		if (token === undefined || !token.text.startsWith("--")) break;
-		const [flag, inlineValue] = splitFlag(token.text);
-		const value = inlineValue ?? tokens[position + 1]?.text;
-		const consumed = inlineValue !== undefined ? 1 : 2;
-		if (flag === "--max") {
-			if (value === undefined) {
-				return {
-					kind: "error",
-					message: "--max needs a value (a positive number of loop turns, or unlimited).",
-				};
-			}
-			const parsed = parseMax(value);
-			if (parsed === undefined) {
-				return {
-					kind: "error",
-					message: `Invalid --max value: ${value}. Use a positive whole number or unlimited.`,
-				};
-			}
-			flags.maxTurns = parsed;
-		} else if (flag === "--compact-at") {
-			if (value === undefined) {
-				return { kind: "error", message: "--compact-at needs a value (e.g. 60% or off)." };
-			}
-			const parsed = parseCompactAt(value);
-			if (parsed === undefined) {
-				return {
-					kind: "error",
-					message: `Invalid --compact-at value: ${value}. Use a percentage between 1% and 99% (e.g. 60%), a fraction (0.6), or off.`,
-				};
-			}
-			flags.compactAt = parsed;
-		} else if (flag === "--expires") {
-			if (value === undefined) {
-				return { kind: "error", message: "--expires needs a duration (e.g. 3d)." };
-			}
-			const parsed = parseDuration(value);
-			if (parsed === undefined) {
-				return {
-					kind: "error",
-					message: `Invalid --expires value: ${value}. Use <number><unit> with unit s, m, h, or d, e.g. 3d.`,
-				};
-			}
-			flags.expiresInMs = parsed;
-		} else {
-			return {
-				kind: "error",
-				message: `Unknown flag: ${flag}. Known flags: --max, --compact-at, --expires.`,
-			};
-		}
-		position += consumed;
-	}
-	return position;
-}
-
-function splitFlag(token: string): [string, string | undefined] {
-	const equals = token.indexOf("=");
-	if (equals === -1) return [token, undefined];
-	return [token.slice(0, equals), token.slice(equals + 1)];
-}
-
-function parseMax(value: string): number | null | undefined {
-	if (value === "unlimited" || value === "null") return null;
-	const parsed = Number(value);
-	return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : undefined;
-}
-
-function parseCompactAt(value: string): number | null | undefined {
-	if (value === "off" || value === "none") return null;
-	let fraction: number;
-	if (value.endsWith("%")) {
-		fraction = Number(value.slice(0, -1)) / 100;
-	} else {
-		fraction = Number(value);
-	}
-	if (!Number.isFinite(fraction) || fraction <= 0 || fraction >= 1) return undefined;
-	return fraction;
-}
-
-export interface LoopArgumentCompletion {
-	value: string;
-	label: string;
-	description?: string;
-}
-
-const LOOP_ARGUMENT_COMPLETIONS: readonly LoopArgumentCompletion[] = [
-	{ value: "status", label: "status", description: "Show the current loop" },
-	{ value: "pause", label: "pause", description: "Pause the loop" },
-	{ value: "resume", label: "resume", description: "Resume a paused loop" },
-	{ value: "stop", label: "stop", description: "Stop the loop" },
-	{ value: "settings", label: "settings", description: "Open pi-loop settings" },
-];
-
-export function completeLoopArguments(prefix: string): LoopArgumentCompletion[] | null {
-	const trimmed = prefix.trimStart();
-	const matches = LOOP_ARGUMENT_COMPLETIONS.filter((candidate) =>
-		candidate.value.startsWith(trimmed),
-	);
-	return matches.length > 0 ? matches : null;
+	/** Hard constraints carried into the loop's per-turn objective append. */
+	groundRules?: string[];
 }

package/src/complete-tool.ts

@@ -120,7 +120,7 @@ export function registerLoopCompleteTool(pi: ExtensionAPI, controller: LoopContr
 				if (!loop || loop.objective === undefined) {
 					return {
 						content: toolContent(
-							"No /loop with an objective is active, so there is nothing to complete. Start one with /loop <interval> <objective>.",
+							"No /loop with an objective is active, so there is nothing to complete. Run /loop to plan and approve one.",
 						),
 						details: { loopId: params.loop_id },
 						isError: true,

package/src/index.ts

@@ -8,123 +8,136 @@
  */
 
 import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
-import { completeLoopArguments, parseLoopCommand } from "./command.js";
+import { 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 { registerLoopProposalRenderer } from "./presentation.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 { showLoopApproval, showLoopManager, showLoopSettings } from "./manager.js";
+import {
+	showLoopApproval,
+	showLoopLaunch,
+	showLoopManager,
+	showLoopPlanning,
+} from "./manager.js";
 import { buildLoopObjectivePrompt } from "./objective.js";
 import { registerLoopMessageRendering } from "./render.js";
+import { readPlanModeEnabled } from "./state.js";
+
+/** What the planning menu's "Request proposal now" asks for. */
+export const REQUEST_PROPOSAL_MESSAGE =
+	"Put the loop we have been drafting up for approval now: call loop_propose with the objective as an acceptance test, one requirement per bullet naming the check that proves it, plus any ground rules we agreed. If something material is still undecided, ask me that one question instead.";
 
 export default function loop(pi: ExtensionAPI, options: LoopControllerOptions = {}) {
 	const controller = new LoopController(pi, options);
-	// 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
-	// active.
+	const proposeTools = ["loop_propose"];
+	const runtimeTools = ["loop_complete", "loop_progress", "loop_wait"];
+	let proposeActivated = false;
+	let runtimeActivated = false;
+	const reconcileTools = () => {
+		const active = pi.getActiveTools();
+		const wanted = new Set(active);
+		for (const name of proposeTools) proposeActivated ? wanted.add(name) : wanted.delete(name);
+		for (const name of runtimeTools) runtimeActivated ? wanted.add(name) : wanted.delete(name);
+		const next = [...wanted];
+		if (next.length !== active.length || next.some((name, index) => name !== active[index])) {
+			pi.setActiveTools(next);
+		}
+	};
+	const activatePropose = () => {
+		proposeActivated = true;
+		reconcileTools();
+	};
+	const activateRuntime = () => {
+		runtimeActivated = true;
+		reconcileTools();
+	};
+
 	registerLoopCompleteTool(pi, controller);
-	// 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
-	// the hint did not arm. The user's message is never transformed.
-	const invocation = new InlineInvocationState();
-	registerInlineInvocation(pi, controller, invocation);
-	registerLoopStartTool(pi, controller, invocation);
+	registerLoopProposeTool(pi, controller, activateRuntime);
+	registerLoopProposalRenderer(pi);
+	// Narrowing happens at session_start, never here: Pi refuses action methods
+	// (getActiveTools/setActiveTools among them) during extension loading.
 	// Collapse loop pokes into one-line transcript chips (display-only; the
 	// stored message and model context are untouched).
 	registerLoopMessageRendering(pi);
 
+	/**
+	 * Send a user message on the user's behalf, exactly the way pi-plan-mode
+	 * seeds a planning conversation: an idle session takes it now, a busy one
+	 * takes it as a follow-up rather than steering the turn in flight.
+	 */
+	const sendPlanningMessage = (text: string, ctx: ExtensionCommandContext): void => {
+		try {
+			if (ctx.isIdle()) pi.sendUserMessage(text);
+			else pi.sendUserMessage(text, { deliverAs: "followUp" });
+		} catch (error) {
+			const detail = error instanceof Error ? error.message : String(error);
+			ctx.ui.notify(`Unable to send the loop planning message: ${detail}`, "error");
+		}
+	};
+
+	const beginPlanning = (ctx: ExtensionCommandContext): void => {
+		if (controller.planning.active) return;
+		activatePropose();
+		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",
+		);
+	};
+
 	pi.registerCommand("loop", {
-		description:
-			"Work an objective across many turns, waking the session if it goes quiet: /loop [--max N] [--compact-at 60%] [--expires 3d] <interval> [objective]",
-		getArgumentCompletions: (prefix: string) => completeLoopArguments(prefix),
+		description: "Plan, approve, and manage a long-running loop: /loop [what it should achieve]",
 		handler: async (args: string, ctx: ExtensionCommandContext) => {
 			const command = parseLoopCommand(args);
-			switch (command.kind) {
-				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();
+			const running = controller.state !== undefined && controller.state.status !== "stopped";
+			// `/loop <text>` mirrors `/plan <prompt>`: it opens planning and says the
+			// first thing. A loop already running owns the session, so the text goes
+			// nowhere and the manager opens instead of a second draft.
+			if (command.kind === "seed") {
+				if (running) {
 					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",
+						"A loop is already running in this session. Stop it from this menu before planning another.",
+						"warning",
 					);
+					await showLoopManager(controller, ctx);
 					return;
 				}
-				case "status":
-					ctx.ui.notify(controller.statusLines(ctx).join("\n"), "info");
-					return;
-				case "pause":
-					controller.pauseLoop(ctx);
-					return;
-				case "resume":
-					controller.resumeLoop(ctx);
-					return;
-				case "stop":
-					controller.stopLoop(ctx);
-					return;
-				case "settings":
-					await showLoopSettings(controller, ctx);
-					return;
-				case "error":
-					ctx.ui.notify(command.message, "error");
-					return;
-				case "start": {
-					const existing = controller.state;
-					if (existing && existing.status !== "stopped") {
-						const replace =
-							ctx.mode === "tui"
-								? await ctx.ui.confirm(
-										"Replace loop?",
-										"A loop already exists in this session. Replace it?",
-									)
-								: false;
-						if (!replace) {
-							ctx.ui.notify(
-								"A loop already exists; /loop stop it first or confirm replacement in the TUI.",
-								"warning",
-							);
-							return;
-						}
-					}
-					const result = controller.startLoop(ctx, command);
-					if (!result.ok) ctx.ui.notify(result.message, "error");
-					return;
-				}
+				beginPlanning(ctx);
+				sendPlanningMessage(command.text, ctx);
+				return;
 			}
+			// Bare /loop is the front door, and which door it opens is the state:
+			// manager, approval card, planning menu, or launch menu.
+			if (running) {
+				await showLoopManager(controller, ctx);
+				return;
+			}
+			if (controller.planning.proposal) {
+				await showLoopApproval(controller, ctx);
+				return;
+			}
+			if (controller.planning.active) {
+				await showLoopPlanning(controller, ctx, {
+					requestProposal: () => sendPlanningMessage(REQUEST_PROPOSAL_MESSAGE, ctx),
+				});
+				return;
+			}
+			await showLoopLaunch(controller, ctx, () => beginPlanning(ctx));
 		},
 	});
 
 	pi.on("session_start", async (_event, ctx) => {
+		proposeActivated = false;
+		runtimeActivated = false;
 		controller.onSessionStart(ctx);
+		if (controller.state?.status === "active") activateRuntime();
+		else reconcileTools();
 	});
 	pi.on("session_shutdown", async () => {
 		controller.onSessionShutdown();
@@ -143,7 +156,21 @@ export default function loop(pi: ExtensionAPI, options: LoopControllerOptions =
 	// 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) => {
+	pi.on("before_agent_start", (event, ctx) => {
+		// Self-heal the runtime tool set every turn an active loop takes, not just
+		// at session_start. `resumeLoop` flips a restored *paused* loop to active
+		// and dispatches a continuation from the /loop menu, which has no way to
+		// reach activateRuntime — so without this the resumed loop would run with
+		// loop_complete stripped, be told by its own objective append to call it,
+		// and then be re-paused by enforceToolAvailability blaming --tools for
+		// something this extension did to itself. Activation is monotonic, so this
+		// covers resumeAfterEdit and the fresh-session handoff too, and costs a
+		// no-op set comparison on every other turn.
+		if (controller.state?.status === "active") activateRuntime();
+		// Plan mode owns the prompt while active. Loop scheduling is already held
+		// by the same persisted state; suppressing the append removes the remaining
+		// mixed-workflow instruction surface.
+		if (readPlanModeEnabled(ctx.sessionManager.getBranch())) return;
 		// 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) {
@@ -155,4 +182,9 @@ export default function loop(pi: ExtensionAPI, options: LoopControllerOptions =
 		if (objectivePrompt === undefined) return;
 		return { systemPrompt: `${event.systemPrompt}\n\n${objectivePrompt}` };
 	});
+
+	// Pi ignores the return value; a test uses it. The controller *is* the
+	// extension's state, and a test holding a different instance of it would
+	// quietly assert against a loop nobody is running.
+	return controller;
 }

package/src/ledger.ts

@@ -99,8 +99,8 @@ export function deriveCriteria(objective: string): LoopCriterion[] {
 /**
  * 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
+ * Shared by the deterministic split and by any criteria supplied with an
+ * approved draft, 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.

package/src/loop-action-menus.ts

@@ -46,11 +46,12 @@ export function loopApprovalScreen(
 	proposal: LoopProposal,
 ): ActionsScreen<Screen, LoopApprovalAction> {
 	const criteria = `${proposal.criteria.length} ${proposal.criteria.length === 1 ? "criterion" : "criteria"}`;
+	const rules = proposal.groundRules?.length;
 	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)}`,
+			`${criteria}${rules ? ` · ${rules} ground rule${rules === 1 ? "" : "s"}` : ""} · 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: [