@hank-warren/pi-loop 0.8.0 → 1.0.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/fresh-launch.ts

@@ -0,0 +1,128 @@
+/**
+ * Starting an approved loop in a fresh session.
+ *
+ * A loop started interactively owns the session it was planned in, and the
+ * planning conversation is the worst possible context for it: every turn of
+ * drafting is carried, re-read and re-billed for the whole run, and none of it
+ * is the objective. The card is where that gets fixed, because the card is
+ * where the user is already deciding how the loop should run.
+ *
+ * Modelled on `packages/pi-plan-mode/src/fresh-implementation.ts`, which
+ * solves the same problem for a plan. The difference is what crosses: a plan
+ * hands over a file path, while a loop hands over its state, appended to the
+ * new session in `setup` exactly as `persist` would have appended it here.
+ * Only the objective and the caps cross; the drafting conversation does not.
+ *
+ * The ledger is written before the handoff, from this session. It is a
+ * filesystem artifact keyed by loop id, not session state, and writing it here
+ * is what makes the approved criteria authoritative: the restoring session
+ * treats whatever is already on disk as the truth, so criteria written after
+ * it restores would arrive too late to be the ones it is held to.
+ */
+
+import type { ExtensionCommandContext, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { BuiltLoop } from "./loop.js";
+import { LOOP_STATE_ENTRY_TYPE } from "./state.js";
+
+type NewSessionOptions = Exclude<Parameters<ExtensionCommandContext["newSession"]>[0], undefined>;
+type SessionManagerLike = Parameters<NonNullable<NewSessionOptions["setup"]>>[0];
+
+export type FreshLoopResult =
+	| { kind: "started" }
+	| { kind: "cancelled" }
+	/** The session exists and holds the loop, but it could not be kicked off. */
+	| { kind: "partial"; detail: string }
+	| { kind: "rejected"; detail: string };
+
+export interface FreshLoopRequest {
+	built: BuiltLoop;
+	/** Write the ledger for `built` before the handoff; returns a failure detail. */
+	prepareLedger(): string | undefined;
+}
+
+export async function startLoopInFreshSession(
+	ctx: ExtensionContext,
+	request: FreshLoopRequest,
+): Promise<FreshLoopResult> {
+	if (!isCommandContext(ctx)) {
+		return {
+			kind: "rejected",
+			detail:
+				"Starting a loop in a fresh session needs the interactive /loop command. Run /loop again and choose it from the menu.",
+		};
+	}
+	if (ctx.mode === "print" || ctx.mode === "json") {
+		return {
+			kind: "rejected",
+			detail: "A fresh session is unavailable in print/JSON mode. Start the loop in this session.",
+		};
+	}
+
+	const ledgerFailure = request.prepareLedger();
+	if (ledgerFailure) {
+		// Not fatal to the loop — a loop runs without a ledger — but it is fatal
+		// to *this* path: the new session would derive its own criteria from the
+		// objective and could be held to a different gate than the one approved.
+		return {
+			kind: "rejected",
+			detail: `The loop's ledger could not be written (${ledgerFailure}), so the approved criteria could not be handed to a new session. Start the loop in this session instead.`,
+		};
+	}
+
+	await ctx.waitForIdle();
+
+	const parentSession = ctx.sessionManager.getSessionFile();
+	let setupError: string | undefined;
+
+	let result: Awaited<ReturnType<ExtensionCommandContext["newSession"]>>;
+	try {
+		result = await ctx.newSession({
+			...(parentSession ? { parentSession } : {}),
+			setup: async (sessionManager: SessionManagerLike) => {
+				try {
+					// The same entry `persist` writes, so the new session's ordinary
+					// restore path picks it up with no special case — plus the handoff
+					// flag, which is what tells that session it owns the first turn.
+					// The kickoff cannot be driven from here: Pi builds a new extension
+					// instance for the new session, so this session's controller is not
+					// the one that ends up holding the loop.
+					sessionManager.appendCustomEntry(LOOP_STATE_ENTRY_TYPE, {
+						loop: { ...request.built.loop, handoff: true },
+					});
+				} catch (error: unknown) {
+					setupError = errorDetail(error);
+				}
+			},
+			withSession: async (replacementCtx: ExtensionContext) => {
+				if (setupError) {
+					replacementCtx.ui.notify(
+						`Fresh session created, but the loop could not be handed to it: ${setupError}. Nothing is running; start the loop from /loop in either session.`,
+						"error",
+					);
+				}
+			},
+		});
+	} catch (error: unknown) {
+		return {
+			kind: "rejected",
+			detail: `Unable to start a fresh session: ${errorDetail(error)}. The draft is unchanged; start the loop in this session instead.`,
+		};
+	}
+
+	if (result.cancelled) return { kind: "cancelled" };
+	return setupError ? { kind: "partial", detail: setupError } : { kind: "started" };
+}
+
+function isCommandContext(ctx: ExtensionContext): ctx is ExtensionCommandContext {
+	return typeof (ctx as Partial<ExtensionCommandContext>).newSession === "function";
+}
+
+function errorDetail(error: unknown) {
+	const detail = error instanceof Error ? error.message : String(error);
+	const normalized =
+		detail
+			.replace(/[\u0000-\u001f\u007f-\u009f]/gu, " ")
+			.replace(/\s+/gu, " ")
+			.trim() || "unknown error";
+	return normalized.length > 500 ? `${normalized.slice(0, 499)}…` : normalized;
+}

package/src/index.ts

@@ -8,19 +8,26 @@
  */
 
 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 { 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";
 
+/** 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
@@ -33,93 +40,72 @@ export default function loop(pi: ExtensionAPI, options: LoopControllerOptions =
 	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);
 	// 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;
+		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));
 		},
 	});
 
@@ -155,4 +141,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.