@hank-warren/pi-loop 0.9.0 → 1.1.0

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 } : {}),
+	};
+}

package/src/loop-manager-menu.ts

@@ -0,0 +1,191 @@
+/**
+ * The manager: every lifecycle control a running loop has.
+ *
+ * Pause, resume, stop, status, focus and cadence used to be typed
+ * subcommands (`/loop pause`, `/loop status`, …). They are here instead,
+ * because a lifecycle control nobody can discover is a control nobody uses,
+ * and because the loop is the kind of thing you reach for when you want to
+ * *look* at it — at which point a menu that shows the state and offers the
+ * actions beats remembering six words.
+ *
+ * Pause and Resume are mutually exclusive by construction: the screen is
+ * built from the loop's status, so a paused loop never offers Pause and an
+ * active one never offers Resume. Pinned in the tests, because an item that
+ * silently does nothing is the failure mode a menu invites.
+ */
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ActionsScreen, DetailScreen, InputScreen } from "@narumitw/pi-tui-kit";
+import { defineMenu, runMenu } from "@narumitw/pi-tui-kit";
+
+export type LoopManagerScreen = "main" | "status" | "focus" | "cadence";
+export type LoopManagerAction =
+	| "pause"
+	| "resume"
+	| "stop"
+	| "settings"
+	| "set-focus"
+	| "set-cadence";
+
+/** What the manager renders: the loop as the menu needs to see it. */
+export interface LoopManagerView {
+	/** `stopped` never reaches here; the menu only exists for a live loop. */
+	status: "active" | "paused";
+	/** The widget line, so the manager and the footer tell the same story. */
+	headline: string;
+	/** Full status detail, one line each. */
+	statusLines: readonly string[];
+	/** The loop's recurring focus, when it has one. */
+	focus?: string;
+	/** The current fallback heartbeat, formatted. */
+	interval: string;
+}
+
+export function loopManagerScreen(
+	view: LoopManagerView,
+): ActionsScreen<LoopManagerScreen, LoopManagerAction> {
+	return {
+		kind: "actions",
+		title: `Loop · ${view.status}`,
+		lines: [view.headline],
+		items: [
+			{ id: "status", label: "Status", description: "The loop's full state.", to: "status" },
+			...(view.status === "active"
+				? ([
+						{
+							id: "pause",
+							label: "Pause",
+							description: "Stop continuing and waking. The loop keeps its state.",
+							action: "pause" as const,
+						},
+					] as const)
+				: ([
+						{
+							id: "resume",
+							label: "Resume",
+							description: "Continue the objective now, and re-arm the heartbeat.",
+							action: "resume" as const,
+						},
+					] as const)),
+			{
+				id: "focus",
+				label: "Edit focus…",
+				description: "A recurring note restated on every loop message.",
+				to: "focus",
+			},
+			{
+				id: "cadence",
+				label: "Edit cadence…",
+				description: `Fallback heartbeat, currently every ${view.interval}.`,
+				to: "cadence",
+			},
+			{
+				id: "stop",
+				label: "Stop",
+				description: "End the loop. The ledger stays on disk.",
+				action: "stop",
+			},
+			{ id: "settings", label: "Settings", action: "settings" },
+		],
+		hint: "close",
+	};
+}
+
+export function loopStatusScreen(view: LoopManagerView): DetailScreen {
+	return {
+		kind: "detail",
+		title: "Loop status",
+		lines: [...view.statusLines],
+		hint: "back",
+	};
+}
+
+export function loopFocusScreen(view: LoopManagerView): InputScreen<LoopManagerAction> {
+	return {
+		kind: "input",
+		title: "Loop focus",
+		lines: [
+			view.focus ? `Currently: ${view.focus}` : "No focus set.",
+			"Restated on every loop message. Leave empty to clear it.",
+		],
+		placeholder: view.focus ?? "e.g. keep the diff small and reversible",
+		action: "set-focus",
+		hint: "back",
+	};
+}
+
+export function loopCadenceScreen(view: LoopManagerView): InputScreen<LoopManagerAction> {
+	return {
+		kind: "input",
+		title: "Fallback heartbeat",
+		lines: [
+			`Currently every ${view.interval}.`,
+			"The loop advances whenever the session settles; this only fires when it has gone quiet.",
+		],
+		placeholder: view.interval,
+		action: "set-cadence",
+		hint: "back",
+	};
+}
+
+export interface LoopManagerMenuOptions {
+	getView(): LoopManagerView | undefined;
+	signal?: AbortSignal;
+	isCurrent?(): boolean;
+	pause(): void;
+	resume(): void;
+	stop(): void;
+	settings(signal: AbortSignal): Promise<void>;
+	/** Returns false when the value was rejected, so the input screen stays open. */
+	setFocus(value: string): boolean;
+	setCadence(value: string): boolean;
+}
+
+export async function showLoopManagerMenu(ctx: ExtensionContext, options: LoopManagerMenuOptions) {
+	const first = options.getView();
+	if (!first) return;
+	// The view is re-read on every render: a pause taken from this menu has to
+	// turn the Pause item into Resume without closing and reopening it.
+	const view = () => options.getView() ?? first;
+	const menu = defineMenu<
+		LoopManagerView,
+		LoopManagerScreen,
+		LoopManagerAction,
+		ExtensionContext
+	>({
+		start: "main",
+		screens: {
+			main: ({ state }) => loopManagerScreen(state),
+			status: ({ state }) => loopStatusScreen(state),
+			focus: ({ state }) => loopFocusScreen(state),
+			cadence: ({ state }) => loopCadenceScreen(state),
+		},
+		actions: {
+			pause: async () => {
+				options.pause();
+				return { kind: "stay" };
+			},
+			resume: async () => {
+				options.resume();
+				return { kind: "stay" };
+			},
+			stop: async () => {
+				options.stop();
+				return { kind: "close" };
+			},
+			settings: async ({ signal }) => {
+				await options.settings(signal);
+				return { kind: "stay" };
+			},
+			"set-focus": async ({ value }) =>
+				options.setFocus(value ?? "") ? { kind: "to", screen: "main" } : { kind: "rejected" },
+			"set-cadence": async ({ value }) =>
+				options.setCadence(value ?? "") ? { kind: "to", screen: "main" } : { kind: "rejected" },
+		},
+	});
+	return runMenu(ctx, menu, {
+		getState: view,
+		...(options.signal ? { signal: options.signal } : {}),
+		...(options.isCurrent ? { isCurrent: options.isCurrent } : {}),
+	});
+}