@hank-warren/pi-loop 0.8.0 → 1.0.0

package/src/loop-action-menus.ts

@@ -0,0 +1,130 @@
+/**
+ * The approval card's actions, as a menu.
+ *
+ * Presentation and choices are separate surfaces on purpose, the way
+ * pi-plan-mode splits `presentation.ts` from `plan-action-menus.ts`: the card
+ * is a durable artifact in the transcript that the user can scroll back to,
+ * and the menu is a transient dialog over it. A plain `ui.select` of label
+ * strings could not say what "start in a fresh session" means, and that is
+ * exactly the entry that needs explaining.
+ *
+ * The screen is built by a pure function so a test can assert what the menu
+ * offers without a terminal.
+ */
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { defineMenu, runMenu } from "@narumitw/pi-tui-kit";
+import type { ActionsScreen } from "@narumitw/pi-tui-kit";
+import { formatDuration } from "./interval.js";
+import type { LoopProposal } from "./planning.js";
+
+export type LoopApprovalAction =
+	| "start-here"
+	| "start-fresh"
+	| "change-cadence"
+	| "keep-editing"
+	| "cancel";
+
+type Screen = "approval";
+
+export interface LoopApprovalMenuOptions {
+	proposal: LoopProposal;
+	signal?: AbortSignal;
+	isCurrent?(): boolean;
+	startHere(): void | Promise<void>;
+	startFresh(signal: AbortSignal): void | Promise<void>;
+	changeCadence(): void | Promise<void>;
+	keepEditing(): void;
+	cancel(): void;
+}
+
+/**
+ * The approval screen. Pure and exported for tests: the set of actions on
+ * offer is the contract, and it is cheaper to pin here than through a TUI.
+ */
+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}${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: [
+			{
+				id: "start-here",
+				label: "Start loop here",
+				description: "Run it in this session, keeping the planning conversation.",
+				action: "start-here",
+			},
+			{
+				id: "start-fresh",
+				label: "Start loop in a fresh session",
+				description:
+					"Open a new session that runs the loop with only the objective — no planning history.",
+				action: "start-fresh",
+				busyLabel: "Starting the loop in a fresh session…",
+			},
+			{
+				id: "change-cadence",
+				label: "Change cadence…",
+				description: "Edit the fallback heartbeat before starting.",
+				action: "change-cadence",
+			},
+			{
+				id: "keep-editing",
+				label: "Keep editing",
+				description: "Go back to drafting; tell the agent what to change.",
+				action: "keep-editing",
+			},
+			{
+				id: "cancel",
+				label: "Cancel",
+				description: "Discard the draft. Nothing is started.",
+				action: "cancel",
+			},
+		],
+		hint: "close",
+	};
+}
+
+export async function showLoopApprovalMenu(
+	ctx: ExtensionContext,
+	options: LoopApprovalMenuOptions,
+) {
+	const menu = defineMenu<undefined, Screen, LoopApprovalAction, ExtensionContext>({
+		start: "approval",
+		screens: { approval: () => loopApprovalScreen(options.proposal) },
+		actions: {
+			"start-here": async () => {
+				await options.startHere();
+				return { kind: "close" };
+			},
+			"start-fresh": async ({ signal }) => {
+				await options.startFresh(signal);
+				return { kind: "close" };
+			},
+			"change-cadence": async () => {
+				await options.changeCadence();
+				return { kind: "close" };
+			},
+			"keep-editing": async () => {
+				options.keepEditing();
+				return { kind: "close" };
+			},
+			cancel: async () => {
+				options.cancel();
+				return { kind: "close" };
+			},
+		},
+	});
+	return runMenu(ctx, menu, {
+		getState: () => undefined,
+		...(options.signal ? { signal: options.signal } : {}),
+		...(options.isCurrent ? { isCurrent: options.isCurrent } : {}),
+	});
+}

package/src/loop-env.ts

@@ -0,0 +1,50 @@
+/**
+ * The loop-active environment contract.
+ *
+ * pi-loop publishes two variables into its own process environment while a
+ * loop is active, and removes them the moment it is not:
+ *
+ * - `PI_LOOP_ACTIVE=1` — an unattended loop is running in this session.
+ * - `PI_LOOP_ID=<id>` — the loop's id, so a reader can tell one loop from the
+ *   next without asking pi-loop anything.
+ *
+ * It exists for other extensions, and pi-auto-permissions is the first
+ * consumer: a modal permission prompt does not pause a loop, it deadlocks it,
+ * so a guardian that would have asked a human needs to know there is no human
+ * to ask. The mechanism is deliberately the one `pi-subagents` already
+ * established with `PI_SUBAGENT_CHILD=1` and `detectSubagentContext` reads —
+ * an environment variable, not a package dependency, not an import, not an
+ * RPC. Neither extension needs the other installed, in either direction, and
+ * a reader that never sees the variable behaves exactly as it does today.
+ *
+ * Both variables are set on the process, so they are visible to every
+ * extension in the session and inherited by anything it spawns. That is the
+ * point: a subagent launched by a looping session is running unattended for
+ * the same reason its parent is.
+ */
+
+import type { LoopState } from "./state.js";
+
+export const LOOP_ACTIVE_ENV = "PI_LOOP_ACTIVE";
+export const LOOP_ID_ENV = "PI_LOOP_ID";
+
+/**
+ * Publish (or withdraw) the loop-active signal for `loop`.
+ *
+ * Only an `active` loop publishes. A paused loop is not working unattended —
+ * the user paused it and is, by construction, present — and a stopped loop is
+ * not working at all, so both withdraw the signal rather than leaving a stale
+ * one behind for the rest of the session.
+ */
+export function publishLoopEnv(
+	loop: LoopState | undefined,
+	env: Record<string, string | undefined> = process.env,
+): void {
+	if (loop?.status === "active") {
+		env[LOOP_ACTIVE_ENV] = "1";
+		env[LOOP_ID_ENV] = loop.id;
+		return;
+	}
+	delete env[LOOP_ACTIVE_ENV];
+	delete env[LOOP_ID_ENV];
+}

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