@hank-warren/pi-loop 0.7.0 → 0.8.0

package/src/propose-tool.ts

@@ -0,0 +1,119 @@
+/**
+ * `loop_propose`: put a drafted loop up for the user's approval.
+ *
+ * It starts nothing. That separation is the point — the model drafts, the user
+ * approves, and the approval is what arms the start. `loop_start`'s gate
+ * exists because a loop is self-continuing and must never begin on model
+ * initiative; an explicit approval on a card showing the objective, the
+ * criteria, the cadence and the caps is stronger evidence of intent than a
+ * typed token, not weaker, so it arms the same gate rather than bypassing it.
+ *
+ * Registered unconditionally, like the other loop tools: the tool set is part
+ * of the cached request prefix, so it never changes with loop state.
+ */
+
+import { defineTool, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { MAX_INTERVAL_MS, parseDuration } from "./interval.js";
+import type { LoopController } from "./loop.js";
+import { renderProposalCard } from "./planning.js";
+
+export const LOOP_PROPOSE_TOOL = "loop_propose";
+
+export function registerLoopProposeTool(pi: ExtensionAPI, controller: LoopController) {
+	pi.registerTool(
+		defineTool({
+			name: LOOP_PROPOSE_TOOL,
+			label: "Loop Propose",
+			description:
+				"Put a drafted loop objective up for the user's approval during loop planning. Renders an approval card showing the exact completion criteria the objective will produce. Starts nothing: the user approves, edits, or cancels.",
+			promptSnippet: "Propose a drafted loop objective for approval",
+			promptGuidelines: [
+				"Call loop_propose only while loop planning is open, and only once the objective reads as an acceptance test: one requirement per bullet, each naming the check that proves it.",
+				"Pass the objective you and the user agreed on, not a tidier version of it. The criteria are derived from this text and frozen when the loop starts.",
+				"Do not call loop_start for a planned loop; approving the card is what starts it.",
+				"loop_propose starts nothing, so the rule that a loop needs an inline /loop token in the user's message does not apply to it. While planning is open, a conversational request for a loop is the signal to draft one and propose it — never to refuse and ask the user to type /loop instead.",
+			],
+			parameters: Type.Object({
+				objective: Type.String({
+					minLength: 1,
+					maxLength: 100_000,
+					description:
+						"The drafted objective, one requirement per bullet, each naming how it is verified.",
+				}),
+				interval: Type.Optional(
+					Type.String({
+						description:
+							"Fallback heartbeat as <number><unit> (s, m, h, d), e.g. 30m. Omit to use the configured default.",
+					}),
+				),
+				max_turns: Type.Optional(
+					Type.Number({
+						description:
+							"Cap on loop-caused turns. Omit for the configured default; the user can change it on the card.",
+					}),
+				),
+				expires: Type.Optional(
+					Type.String({
+						description: "Loop lifetime as <number><unit>, e.g. 3d. Omit for the default.",
+					}),
+				),
+			}),
+			async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+				if (!controller.planning.active) {
+					return failure(
+						"Loop planning is not open, so there is nothing to propose. The user opens it by running /loop with no loop running.",
+					);
+				}
+				if (controller.state && controller.state.status !== "stopped") {
+					return failure(
+						"A loop is already running in this session. Stop it with /loop stop before planning another.",
+					);
+				}
+				const objective = params.objective.trim();
+				if (!objective) return failure("A proposal needs an objective.");
+
+				const overrides: { intervalMs?: number; maxTurns?: number | null; expiresInMs?: number } =
+					{};
+				if (params.interval !== undefined) {
+					const parsed = parseDuration(params.interval);
+					if (parsed === undefined) {
+						return failure(
+							`Invalid interval: ${params.interval}. Use <number><unit> with unit s, m, h, or d, e.g. 30m.`,
+						);
+					}
+					overrides.intervalMs = Math.min(parsed, MAX_INTERVAL_MS);
+				}
+				if (params.expires !== undefined) {
+					const parsed = parseDuration(params.expires);
+					if (parsed === undefined) {
+						return failure(
+							`Invalid expires: ${params.expires}. Use <number><unit> with unit s, m, h, or d, e.g. 3d.`,
+						);
+					}
+					overrides.expiresInMs = parsed;
+				}
+				if (params.max_turns !== undefined) {
+					if (!Number.isSafeInteger(params.max_turns) || params.max_turns <= 0) {
+						return failure("max_turns must be a positive whole number.");
+					}
+					overrides.maxTurns = params.max_turns;
+				}
+
+				const proposal = controller.propose(objective, overrides);
+				return {
+					content: [{ type: "text" as const, text: renderProposalCard(proposal).join("\n") }],
+					details: {
+						criteria: proposal.criteria.length,
+						intervalMs: proposal.intervalMs,
+						maxTurns: proposal.maxTurns,
+					},
+				};
+			},
+		}),
+	);
+}
+
+function failure(text: string) {
+	return { content: [{ type: "text" as const, text }], details: {}, isError: true };
+}

package/src/widget.ts

@@ -1,15 +1,33 @@
 /**
- * The loop widget: a compact themed line above the editor mirroring the
- * footer status (interval · loop turns/cap · next wake), with the loop focus
+ * The loop widget: one themed line above the editor, with the loop's focus
  * dimmed below it when set.
  *
+ * Two rules shape what goes on that line.
+ *
+ * **Show progress, not consumption.** The line used to lead with the interval
+ * and then report turns against the turn cap. The interval is a fallback
+ * heartbeat — a settle-paced loop can run its whole life without delivering
+ * one — and turns-against-cap is budget burn, which says nothing about how
+ * much of the objective is done. Criteria met over criteria total is the
+ * progress number, and it leads.
+ *
+ * **One surface, one story.** The widget and the footer status render the same
+ * state, so they render it from the same function. They disagreed before:
+ * `setStatus` handled `loop.waiting` and the widget did not, so a loop blocked
+ * on CI showed an ordinary "next 17:53" above the editor while the footer said
+ * it was waiting.
+ *
+ * States are ordered by how much they want a human, because the top of that
+ * order is the whole reason to glance at the line: paused and blocked and
+ * expiring come before the ordinary running line.
+ *
  * Presentation only: every entry point tolerates a host without setWidget
  * (test fixtures, print mode) and swallows render-side failures, because a
  * widget must never interrupt loop state transitions.
  */
 
 import { Text } from "@earendil-works/pi-tui";
-import { formatClock, formatDuration } from "./interval.js";
+import { formatClock, formatElapsed } from "./interval.js";
 import type { LoopState } from "./state.js";
 
 export const LOOP_WIDGET_KEY = "loop";
@@ -21,27 +39,61 @@ interface WidgetTheme {
 
 type WidgetHost = { setWidget?: unknown };
 
-export interface LoopWidgetView {
+/** Criteria progress, absent when the loop has no readable ledger. */
+export interface CriteriaProgress {
+	met: number;
+	total: number;
+}
+
+/** The loop is being drafted with the user and has not started. */
+export interface LoopPlanningView {
+	kind: "planning";
+	/** Criteria in the proposed draft, once one has been put up for approval. */
+	proposedCriteria?: number;
+}
+
+export interface LoopRunningView {
+	kind: "loop";
 	loop: LoopState;
 	/** A wake is held for the next idle boundary. */
 	wakePending: boolean;
 	/** Epoch ms of the next scheduled tick, when armed. */
 	nextWakeAt: number | undefined;
+	criteria?: CriteriaProgress;
+	/**
+	 * How long the session has been busy with no completed turn. Set only past
+	 * the stall threshold, where a blocking prompt is the likely explanation.
+	 */
+	blockedForMs?: number;
+	/** Injected so the elapsed span is deterministic in tests. */
+	now?: number;
 }
 
+export type LoopWidgetView = LoopPlanningView | LoopRunningView;
+
+/** How urgently a line wants a human; picks the colour. */
+type Tone = "normal" | "attention" | "planning";
+
 export function updateLoopWidget(ui: WidgetHost, view: LoopWidgetView | undefined) {
 	const setWidget = resolveSetWidget(ui);
 	if (!setWidget) return;
 	try {
-		if (!view || view.loop.status === "stopped") {
+		if (!view || (view.kind === "loop" && view.loop.status === "stopped")) {
 			setWidget(LOOP_WIDGET_KEY, undefined);
 			return;
 		}
 		setWidget(LOOP_WIDGET_KEY, (_tui: unknown, theme: WidgetTheme) => {
 			const bold = theme.bold ?? identity;
+			const paint = (tone: Tone, text: string) => {
+				if (tone === "normal") return text;
+				return theme.fg?.(tone === "attention" ? "warning" : "accent", text) ?? text;
+			};
 			const dim = (text: string) => theme.fg?.("dim", text) ?? text;
-			const focus = view.loop.prompt ? `\n${dim(`  focus: ${view.loop.prompt}`)}` : "";
-			return new Text(`${bold(loopWidgetLine(view))}${focus}`);
+			const focus =
+				view.kind === "loop" && view.loop.prompt
+					? `\n${dim(`  focus: ${view.loop.prompt}`)}`
+					: "";
+			return new Text(`${paint(widgetTone(view), bold(loopWidgetLine(view)))}${focus}`);
 		});
 	} catch {
 		// Presentation only; a widget failure must never break a loop transition.
@@ -58,18 +110,56 @@ export function clearLoopWidget(ui: WidgetHost) {
 	}
 }
 
-export function loopWidgetLine(view: LoopWidgetView) {
+/** Exported for tests: the tone the line renders in. */
+export function widgetTone(view: LoopWidgetView): Tone {
+	if (view.kind === "planning") return "planning";
 	const loop = view.loop;
-	if (loop.status === "paused") return "⏸ loop paused";
+	if (loop.status === "paused" || loop.expiring || view.blockedForMs !== undefined) {
+		return "attention";
+	}
+	return "normal";
+}
+
+export function loopWidgetLine(view: LoopWidgetView): string {
+	if (view.kind === "planning") {
+		return view.proposedCriteria === undefined
+			? "◆ loop planning · drafting an objective"
+			: `◆ loop planning · ${view.proposedCriteria} criteria proposed · approve to start`;
+	}
+	const loop = view.loop;
+
+	// Ordered by how much the state wants a human. A paused or blocked loop is
+	// not making progress, so reporting progress numbers first would bury the
+	// only fact that matters.
+	if (loop.status === "paused") {
+		return `⏸ loop paused${loop.pauseCause ? ` · ${loop.pauseCause}` : ""}`;
+	}
+	if (loop.expiring) return "⚠ loop expiring · write your state into the ledger";
+	if (view.blockedForMs !== undefined) {
+		// The engine cannot see the prompt itself: it only knows the session has
+		// been busy without completing a turn, which a blocking prompt explains
+		// and ordinary long work also explains. Say which one is being reported.
+		return `⚠ loop blocked · no turn for ${formatElapsed(view.blockedForMs)} · a prompt may be waiting`;
+	}
+	if (loop.waiting) {
+		const until =
+			loop.waiting.resumeAt === undefined
+				? "no deadline"
+				: `until ${formatClock(loop.waiting.resumeAt)}`;
+		return `⏳ loop waiting · ${loop.waiting.reason} · ${until}`;
+	}
+
 	const cap = loop.maxTurns === null ? "∞" : `${loop.maxTurns}`;
 	const next = view.wakePending
 		? "next on idle"
 		: view.nextWakeAt !== undefined
 			? `next ${formatClock(view.nextWakeAt)}`
 			: "next unscheduled";
-	// The turn counter, not the wake counter: the cap counts turns, so a
-	// progress line against that cap has to count the same thing.
-	return `⟳ loop every ${formatDuration(loop.intervalMs)} · ${loop.automaticTurns}/${cap} · ${next}`;
+	const elapsed = formatElapsed((view.now ?? Date.now()) - loop.startedAt);
+	// Progress leads when there is progress to report. Turns are still shown,
+	// but as the budget they are, not as the headline.
+	const progress = view.criteria ? `${view.criteria.met}/${view.criteria.total} done · ` : "";
+	return `⟳ loop ${progress}turn ${loop.automaticTurns}/${cap} · ${elapsed} · ${next}`;
 }
 
 function identity(text: string) {

package/src/schedule/command.ts

@@ -1,255 +0,0 @@
-/**
- * Deterministic `/schedule` parsing. Grammar:
- *
- *   /schedule                                       manager TUI
- *   /schedule list
- *   /schedule every <dur>  [flags] <prompt...>
- *   /schedule at <ISO|+dur> [flags] <prompt...>
- *   /schedule cron "<m h dom mon dow>" [flags] <prompt...>
- *   /schedule pause|resume|delete|run|status <id>
- *
- * Flags: --run (headless instead of an in-session prompt), --cwd <path>,
- * --max <n|unlimited>, --wake always|failure|success|never, --name <text>.
- *
- * The extension owns this grammar, never the model — same reason `/loop`
- * does. A model that can schedule its own future turns can schedule its way
- * around every limit the loop imposes.
- */
-
-import { parseDuration } from "../interval.js";
-import { parseCron } from "./cron.js";
-import {
-	MIN_INTERVAL_MS,
-	type ScheduleSpec,
-	type TaskSpec,
-	WAKE_ON_VALUES,
-	type WakeOn,
-} from "./model.js";
-
-export const SCHEDULE_SUBCOMMANDS = [
-	"list",
-	"pause",
-	"resume",
-	"delete",
-	"run",
-	"status",
-] as const;
-export type ScheduleSubcommand = (typeof SCHEDULE_SUBCOMMANDS)[number];
-
-export interface ScheduleCreateCommand {
-	kind: "create";
-	name: string;
-	schedule: ScheduleSpec;
-	task: TaskSpec;
-	maxRuns?: number | null;
-	/** Set when a sub-minute interval was raised to the floor. */
-	clampedFrom?: number;
-}
-
-export type ScheduleCommand =
-	| { kind: "show" }
-	| { kind: "list" }
-	| { kind: ScheduleSubcommand; id: string }
-	| ScheduleCreateCommand
-	| { kind: "error"; message: string };
-
-export interface ParseScheduleOptions {
-	/** Default working directory for a headless run. */
-	cwd: string;
-	now?: number;
-}
-
-export function parseScheduleCommand(
-	args: string,
-	options: ParseScheduleOptions,
-): ScheduleCommand {
-	const trimmed = args.trim();
-	if (!trimmed) return { kind: "show" };
-	const tokens = [...args.matchAll(/\S+/g)].map((match) => ({
-		text: match[0],
-		index: match.index,
-	}));
-	const head = tokens[0]?.text ?? "";
-	if (head === "list") return { kind: "list" };
-	if ((SCHEDULE_SUBCOMMANDS as readonly string[]).includes(head)) {
-		const id = tokens[1]?.text;
-		if (!id) return { kind: "error", message: `/schedule ${head} needs a task id.` };
-		return { kind: head as ScheduleSubcommand, id };
-	}
-
-	const now = options.now ?? Date.now();
-	let position = 1;
-	let schedule: ScheduleSpec | undefined;
-	let clampedFrom: number | undefined;
-	if (head === "every") {
-		const value = tokens[1]?.text;
-		if (!value) return { kind: "error", message: "/schedule every needs a duration, e.g. 30m." };
-		const everyMs = parseDuration(value);
-		if (everyMs === undefined) {
-			return {
-				kind: "error",
-				message: `Invalid interval: ${value}. Use <number><unit> with unit s, m, h, or d.`,
-			};
-		}
-		if (everyMs < MIN_INTERVAL_MS) clampedFrom = everyMs;
-		schedule = { kind: "interval", everyMs: Math.max(MIN_INTERVAL_MS, everyMs) };
-		position = 2;
-	} else if (head === "at") {
-		const value = tokens[1]?.text;
-		if (!value) {
-			return {
-				kind: "error",
-				message: "/schedule at needs a time: an ISO timestamp, or +<duration> such as +90m.",
-			};
-		}
-		const at = parseAt(value, now);
-		if (at === undefined) {
-			return {
-				kind: "error",
-				message: `Invalid time: ${value}. Use an ISO timestamp (2026-01-31T09:00) or +<duration> such as +90m.`,
-			};
-		}
-		if (at <= now) return { kind: "error", message: `That time is in the past: ${value}.` };
-		schedule = { kind: "once", at };
-		position = 2;
-	} else if (head === "cron") {
-		const quoted = readQuoted(args, tokens[1]?.index ?? 0);
-		const expression = quoted?.value ?? tokens.slice(1, 6).map((token) => token.text).join(" ");
-		const parsed = parseCron(expression);
-		if (!parsed.ok) return { kind: "error", message: `Invalid cron expression: ${parsed.error}.` };
-		schedule = { kind: "cron", expression: parsed.spec.expression };
-		position = quoted ? tokenIndexAfter(tokens, quoted.end) : 6;
-	} else {
-		return {
-			kind: "error",
-			message: `Unknown /schedule form: ${head}. Use every <dur>, at <time>, cron "<expr>", list, pause, resume, run, status, or delete.`,
-		};
-	}
-
-	let headless = false;
-	let cwd = options.cwd;
-	let wakeOn: WakeOn = "failure";
-	let maxRuns: number | null | undefined;
-	let name: string | undefined;
-	while (position < tokens.length) {
-		const token = tokens[position];
-		if (token === undefined || !token.text.startsWith("--")) break;
-		const [flag, inline] = splitFlag(token.text);
-		const value = inline ?? tokens[position + 1]?.text;
-		if (flag === "--run") {
-			headless = true;
-			position += 1;
-			continue;
-		}
-		if (value === undefined) return { kind: "error", message: `${flag} needs a value.` };
-		if (flag === "--cwd") {
-			cwd = value;
-		} else if (flag === "--wake") {
-			if (!WAKE_ON_VALUES.includes(value as WakeOn)) {
-				return {
-					kind: "error",
-					message: `Invalid --wake value: ${value}. Use ${WAKE_ON_VALUES.join(", ")}.`,
-				};
-			}
-			wakeOn = value as WakeOn;
-		} else if (flag === "--max") {
-			if (value === "unlimited" || value === "null") maxRuns = null;
-			else {
-				const parsed = Number(value);
-				if (!Number.isSafeInteger(parsed) || parsed <= 0) {
-					return {
-						kind: "error",
-						message: `Invalid --max value: ${value}. Use a positive whole number or unlimited.`,
-					};
-				}
-				maxRuns = parsed;
-			}
-		} else if (flag === "--name") {
-			name = value;
-		} else {
-			return {
-				kind: "error",
-				message: `Unknown flag: ${flag}. Known flags: --run, --cwd, --max, --wake, --name.`,
-			};
-		}
-		position += inline === undefined ? 2 : 1;
-	}
-
-	const promptToken = tokens[position];
-	const prompt = promptToken === undefined ? "" : args.slice(promptToken.index).trim();
-	if (!prompt) {
-		return { kind: "error", message: "A scheduled task needs a prompt to run." };
-	}
-	return {
-		kind: "create",
-		name: name ?? summarize(prompt),
-		schedule,
-		task: headless ? { kind: "run", prompt, cwd, wakeOn } : { kind: "prompt", prompt },
-		...(maxRuns === undefined ? {} : { maxRuns }),
-		...(clampedFrom === undefined ? {} : { clampedFrom }),
-	};
-}
-
-function parseAt(value: string, now: number): number | undefined {
-	if (value.startsWith("+")) {
-		const delay = parseDuration(value.slice(1));
-		return delay === undefined ? undefined : now + delay;
-	}
-	const parsed = Date.parse(value);
-	return Number.isFinite(parsed) ? parsed : undefined;
-}
-
-/** Read a quoted string starting at `from`, or undefined when unquoted. */
-function readQuoted(args: string, from: number): { value: string; end: number } | undefined {
-	const quote = args[from];
-	if (quote !== '"' && quote !== "'") return undefined;
-	const end = args.indexOf(quote, from + 1);
-	if (end === -1) return undefined;
-	return { value: args.slice(from + 1, end), end };
-}
-
-function tokenIndexAfter(
-	tokens: ReadonlyArray<{ text: string; index: number }>,
-	offset: number,
-): number {
-	for (let index = 0; index < tokens.length; index += 1) {
-		const token = tokens[index];
-		if (token && token.index > offset) return index;
-	}
-	return tokens.length;
-}
-
-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 summarize(prompt: string): string {
-	const collapsed = prompt.replace(/\s+/gu, " ").trim();
-	return collapsed.length <= 60 ? collapsed : `${collapsed.slice(0, 59)}…`;
-}
-
-export interface ScheduleArgumentCompletion {
-	value: string;
-	label: string;
-	description?: string;
-}
-
-const COMPLETIONS: readonly ScheduleArgumentCompletion[] = [
-	{ value: "every", label: "every", description: "Repeat on an interval, e.g. every 30m" },
-	{ value: "at", label: "at", description: "Fire once, e.g. at +90m or an ISO timestamp" },
-	{ value: "cron", label: "cron", description: 'Fire on a cron expression, e.g. cron "0 9 * * 1"' },
-	{ value: "list", label: "list", description: "List scheduled tasks" },
-	{ value: "pause", label: "pause", description: "Pause a task" },
-	{ value: "resume", label: "resume", description: "Resume a paused task" },
-	{ value: "run", label: "run", description: "Run a task now" },
-	{ value: "status", label: "status", description: "Show one task in detail" },
-	{ value: "delete", label: "delete", description: "Delete a task" },
-];
-
-export function completeScheduleArguments(prefix: string): ScheduleArgumentCompletion[] | null {
-	const trimmed = prefix.trimStart();
-	const matches = COMPLETIONS.filter((candidate) => candidate.value.startsWith(trimmed));
-	return matches.length > 0 ? matches : null;
-}