@hank-warren/pi-loop 0.6.0 → 0.8.0

package/src/widget.ts

@@ -1,15 +1,33 @@
 /**
- * The loop widget: a compact themed line above the editor mirroring the
- * footer status (interval · iteration/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,16 +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";
-	const cap = loop.maxIterations === null ? "∞" : `${loop.maxIterations}`;
+	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";
-	return `⟳ loop every ${formatDuration(loop.intervalMs)} · ${loop.iteration}/${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;
-}

package/src/schedule/cron.ts

@@ -1,182 +0,0 @@
-/**
- * A five-field cron parser, minute granularity, stdlib only.
- *
- * Deliberately small and numeric: `minute hour day-of-month month
- * day-of-week`, each field `*`, a number, `a-b`, `a,b,c`, `*/n`, or
- * `a-b/n`. No names, no `@daily`, no seconds, no timezones beyond the host's
- * local time. Every one of those is a place where two implementations
- * disagree, and a scheduler whose semantics are debatable is worse than one
- * that refuses the expression.
- *
- * Day-of-month and day-of-week follow the traditional cron rule: when both
- * are restricted, a day matching *either* fires. That is genuinely surprising
- * behaviour, but it is what every crontab in the world means, and inventing a
- * more sensible rule here would be the bigger trap.
- */
-
-export interface CronSpec {
-	expression: string;
-	minutes: ReadonlySet<number>;
-	hours: ReadonlySet<number>;
-	daysOfMonth: ReadonlySet<number>;
-	months: ReadonlySet<number>;
-	daysOfWeek: ReadonlySet<number>;
-	/** Both day fields restricted: match either, per traditional cron. */
-	dayUnion: boolean;
-}
-
-interface FieldRange {
-	min: number;
-	max: number;
-}
-
-const FIELDS: ReadonlyArray<{ name: string; range: FieldRange }> = [
-	{ name: "minute", range: { min: 0, max: 59 } },
-	{ name: "hour", range: { min: 0, max: 23 } },
-	{ name: "day-of-month", range: { min: 1, max: 31 } },
-	{ name: "month", range: { min: 1, max: 12 } },
-	{ name: "day-of-week", range: { min: 0, max: 7 } },
-];
-
-export type CronParseResult =
-	| { ok: true; spec: CronSpec }
-	| { ok: false; error: string };
-
-export function parseCron(expression: string): CronParseResult {
-	const fields = expression.trim().split(/\s+/u);
-	if (fields.length !== 5) {
-		return {
-			ok: false,
-			error: `a cron expression has 5 fields (minute hour day-of-month month day-of-week), got ${fields.length}`,
-		};
-	}
-	const parsed: Array<Set<number>> = [];
-	for (let index = 0; index < FIELDS.length; index += 1) {
-		const field = FIELDS[index];
-		const text = fields[index];
-		if (!field || text === undefined) return { ok: false, error: "malformed cron expression" };
-		const values = parseField(text, field.range);
-		if (!values) return { ok: false, error: `invalid ${field.name} field: ${text}` };
-		parsed.push(values);
-	}
-	const [minutes, hours, daysOfMonth, months, rawDaysOfWeek] = parsed as [
-		Set<number>,
-		Set<number>,
-		Set<number>,
-		Set<number>,
-		Set<number>,
-	];
-	// 7 and 0 are both Sunday.
-	const daysOfWeek = new Set([...rawDaysOfWeek].map((day) => (day === 7 ? 0 : day)));
-	return {
-		ok: true,
-		spec: {
-			expression: fields.join(" "),
-			minutes,
-			hours,
-			daysOfMonth,
-			months,
-			daysOfWeek,
-			dayUnion: fields[2] !== "*" && fields[4] !== "*",
-		},
-	};
-}
-
-function parseField(text: string, range: FieldRange): Set<number> | undefined {
-	const values = new Set<number>();
-	for (const part of text.split(",")) {
-		const [spec, stepText] = part.split("/");
-		if (spec === undefined || spec === "") return undefined;
-		let step = 1;
-		if (stepText !== undefined) {
-			step = Number(stepText);
-			if (!Number.isSafeInteger(step) || step <= 0) return undefined;
-		}
-		let from: number;
-		let to: number;
-		if (spec === "*") {
-			from = range.min;
-			to = range.max;
-		} else if (spec.includes("-")) {
-			const [fromText, toText, ...rest] = spec.split("-");
-			if (rest.length > 0) return undefined;
-			from = Number(fromText);
-			to = Number(toText);
-		} else {
-			from = Number(spec);
-			to = from;
-		}
-		if (!Number.isSafeInteger(from) || !Number.isSafeInteger(to) || from > to) return undefined;
-		if (from < range.min || to > range.max) return undefined;
-		for (let value = from; value <= to; value += step) values.add(value);
-	}
-	return values.size > 0 ? values : undefined;
-}
-
-/** Whether a local-time date matches the spec, to the minute. */
-export function cronMatches(spec: CronSpec, date: Date): boolean {
-	if (!spec.minutes.has(date.getMinutes())) return false;
-	if (!spec.hours.has(date.getHours())) return false;
-	if (!spec.months.has(date.getMonth() + 1)) return false;
-	const domMatch = spec.daysOfMonth.has(date.getDate());
-	const dowMatch = spec.daysOfWeek.has(date.getDay());
-	return spec.dayUnion ? domMatch || dowMatch : domMatch && dowMatch;
-}
-
-/** How far ahead a next-fire search gives up, in days. */
-const SEARCH_LIMIT_DAYS = 5 * 366;
-
-/**
- * The next local-time minute at or after `after` that matches, or undefined
- * when the expression can never fire again (30 February and friends).
- *
- * Scans day by day and only walks minutes inside a matching day, so an
- * expression that fires once a year costs a few thousand cheap comparisons
- * rather than half a million.
- */
-export function nextCronFire(spec: CronSpec, after: number): number | undefined {
-	const cursor = new Date(after);
-	cursor.setSeconds(0, 0);
-	cursor.setMinutes(cursor.getMinutes() + 1);
-	for (let day = 0; day <= SEARCH_LIMIT_DAYS; day += 1) {
-		if (dayCouldMatch(spec, cursor)) {
-			const hit = firstMatchingMinuteOfDay(spec, cursor, day === 0);
-			if (hit !== undefined) return hit;
-		}
-		cursor.setDate(cursor.getDate() + 1);
-		cursor.setHours(0, 0, 0, 0);
-	}
-	return undefined;
-}
-
-function dayCouldMatch(spec: CronSpec, date: Date): boolean {
-	if (!spec.months.has(date.getMonth() + 1)) return false;
-	const domMatch = spec.daysOfMonth.has(date.getDate());
-	const dowMatch = spec.daysOfWeek.has(date.getDay());
-	return spec.dayUnion ? domMatch || dowMatch : domMatch && dowMatch;
-}
-
-function firstMatchingMinuteOfDay(
-	spec: CronSpec,
-	dayStart: Date,
-	respectCursorTime: boolean,
-): number | undefined {
-	const startHour = respectCursorTime ? dayStart.getHours() : 0;
-	const startMinute = respectCursorTime ? dayStart.getMinutes() : 0;
-	for (const hour of sorted(spec.hours)) {
-		if (hour < startHour) continue;
-		for (const minute of sorted(spec.minutes)) {
-			if (hour === startHour && minute < startMinute) continue;
-			const candidate = new Date(dayStart);
-			candidate.setHours(hour, minute, 0, 0);
-			// A DST jump can move the wall clock off the requested slot; the
-			// match check is authoritative.
-			if (cronMatches(spec, candidate)) return candidate.getTime();
-		}
-	}
-	return undefined;
-}
-
-function sorted(values: ReadonlySet<number>): number[] {
-	return [...values].sort((a, b) => a - b);
-}