@hank-warren/pi-loop 0.9.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/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.

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: [

package/src/loop-launch-menu.ts

@@ -0,0 +1,158 @@
+/**
+ * The two pre-loop menus: the launch menu (nothing running, nothing drafted)
+ * and the planning menu (a drafting conversation is open, no proposal yet).
+ *
+ * They are the front door, and they are deliberately shaped like
+ * pi-plan-mode's launch menu — same title/status/items/detail-screen skeleton,
+ * same "How it works" affordance. The two extensions are one family: a user
+ * who has run `/plan` should recognise `/loop` without reading anything.
+ *
+ * Screen builders are pure and exported so a test can pin exactly what each
+ * menu offers without a terminal. That set is the contract; the wiring is not.
+ */
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ActionsScreen, DetailScreen } from "@narumitw/pi-tui-kit";
+import { defineMenu, runMenu } from "@narumitw/pi-tui-kit";
+
+export type LoopLaunchScreen = "main" | "how";
+export type LoopLaunchAction = "start-planning" | "settings";
+export type LoopPlanningAction = "request-proposal" | "cancel" | "settings";
+
+/**
+ * What a loop actually is, for someone who has never run one.
+ *
+ * It answers the questions the old one-line notification could not: what
+ * paces it, what ends it, where its state lives, and what bounds it now that
+ * a turn budget no longer does.
+ */
+export const HOW_LOOPS_WORK_LINES = [
+	"A loop works one objective across many turns, continuing itself until the objective is met.",
+	"It is paced by the session settling, not by a clock: every time the agent goes idle with the objective unfinished, the loop continues it. The interval is only a fallback heartbeat for a session that has gone quiet.",
+	"The objective is drafted with you first and becomes the loop's completion criteria. The approval card shows the exact criteria before anything starts.",
+	"Ground rules are hard constraints approved alongside the objective — what the loop must never do while nobody is watching.",
+	"loop_complete ends the loop, and it is gated: every criterion needs cited evidence. Effort exhaustion is not completion.",
+	"A durable ledger (PROGRESS.md and criteria.json) holds the loop's state, so it survives compaction and hands off between sessions.",
+	"Nothing caps the turns by default. A loop is bounded by its expiry and by the no-progress breaker, which pauses it when it repeats itself; set a turn budget in Settings to add one.",
+	"You stay in control: /loop opens this menu at any time to pause, resume, or stop it, and Esc interrupts the turn in flight.",
+] as const;
+
+function howItWorksScreen(): DetailScreen {
+	return {
+		kind: "detail",
+		title: "How loops work",
+		lines: [...HOW_LOOPS_WORK_LINES],
+		hint: "back",
+	};
+}
+
+/** The off-state launch menu. */
+export function loopLaunchScreen(): ActionsScreen<LoopLaunchScreen, LoopLaunchAction> {
+	return {
+		kind: "actions",
+		title: "Loop",
+		lines: ["Status: Off."],
+		items: [
+			{
+				id: "start-planning",
+				label: "Start loop planning",
+				description: "Draft an objective with the agent. Nothing starts until you approve it.",
+				action: "start-planning",
+			},
+			{ id: "settings", label: "Settings", action: "settings" },
+			{ id: "how", label: "How loops work", to: "how" },
+		],
+		hint: "close",
+	};
+}
+
+/** Planning is open and no draft has been proposed yet. */
+export function loopPlanningScreen(): ActionsScreen<LoopLaunchScreen, LoopPlanningAction> {
+	return {
+		kind: "actions",
+		title: "Loop planning",
+		lines: [
+			"Status: drafting an objective. No loop is running.",
+			"Describe what the loop should achieve and how you will know it is done.",
+		],
+		items: [
+			{
+				id: "request-proposal",
+				label: "Request proposal now",
+				description: "Ask the agent to put the current draft up for approval.",
+				action: "request-proposal",
+			},
+			{
+				id: "cancel",
+				label: "Cancel planning",
+				description: "Close planning. Nothing is started.",
+				action: "cancel",
+			},
+			{ id: "settings", label: "Settings", action: "settings" },
+			{ id: "how", label: "How loops work", to: "how" },
+		],
+		hint: "close",
+	};
+}
+
+export interface LoopLaunchMenuOptions {
+	signal?: AbortSignal;
+	isCurrent?(): boolean;
+	startPlanning(): void;
+	settings(signal: AbortSignal): Promise<void>;
+}
+
+export async function showLoopLaunchMenu(ctx: ExtensionContext, options: LoopLaunchMenuOptions) {
+	const menu = defineMenu<undefined, LoopLaunchScreen, LoopLaunchAction, ExtensionContext>({
+		start: "main",
+		screens: { main: () => loopLaunchScreen(), how: () => howItWorksScreen() },
+		actions: {
+			"start-planning": async () => {
+				options.startPlanning();
+				return { kind: "close" };
+			},
+			settings: async ({ signal }) => {
+				await options.settings(signal);
+				return { kind: "stay" };
+			},
+		},
+	});
+	return runMenu(ctx, menu, { getState: () => undefined, ...lifecycle(options) });
+}
+
+export interface LoopPlanningMenuOptions {
+	signal?: AbortSignal;
+	isCurrent?(): boolean;
+	requestProposal(): void;
+	cancelPlanning(): void;
+	settings(signal: AbortSignal): Promise<void>;
+}
+
+export async function showLoopPlanningMenu(ctx: ExtensionContext, options: LoopPlanningMenuOptions) {
+	const menu = defineMenu<undefined, LoopLaunchScreen, LoopPlanningAction, ExtensionContext>({
+		start: "main",
+		screens: { main: () => loopPlanningScreen(), how: () => howItWorksScreen() },
+		actions: {
+			"request-proposal": async () => {
+				options.requestProposal();
+				return { kind: "close" };
+			},
+			cancel: async () => {
+				options.cancelPlanning();
+				return { kind: "close" };
+			},
+			settings: async ({ signal }) => {
+				await options.settings(signal);
+				return { kind: "stay" };
+			},
+		},
+	});
+	return runMenu(ctx, menu, { getState: () => undefined, ...lifecycle(options) });
+}
+
+function lifecycle(options: { signal?: AbortSignal; isCurrent?(): boolean }) {
+	return {
+		...(options.signal ? { signal: options.signal } : {}),
+		...(options.isCurrent ? { isCurrent: options.isCurrent } : {}),
+	};
+}