@hank-warren/pi-loop 0.5.0 → 0.7.0

package/src/state.ts

@@ -1,14 +1,12 @@
 /**
- * Loop state persisted as `loop-state` custom session entries, plus read-only
- * fail-open readers for the sibling extensions' entries: pi-goal's
- * `goal-state` and pi-plan-mode's `plan-mode-state`. The coupling is
- * deliberately loose — no package dependency, no RPC; an absent or
- * unrecognizable entry degrades pi-loop to standalone behavior, never crashes
- * it.
+ * Loop state persisted as `loop-state` custom session entries, plus one
+ * read-only fail-open reader for a sibling extension's entries:
+ * pi-plan-mode's `plan-mode-state`. The coupling is deliberately loose — no
+ * package dependency, no RPC; an absent or unrecognizable entry degrades
+ * pi-loop to "not planning", never crashes it.
  */
 
 export const LOOP_STATE_ENTRY_TYPE = "loop-state";
-export const GOAL_STATE_ENTRY_TYPE = "goal-state";
 export const PLAN_MODE_STATE_ENTRY_TYPE = "plan-mode-state";
 
 import { type LoopWait, normalizeLoopWait } from "./wait.js";
@@ -19,29 +17,30 @@ export type LoopStatus = (typeof LOOP_STATUSES)[number];
 export interface LoopState {
 	id: string;
 	status: LoopStatus;
-	/** The recurring prompt; undefined for a goal-bound loop started bare. */
+	/**
+	 * An optional recurring focus, restated on every loop message. Also the
+	 * only field a loop persisted before 0.6.0 may carry instead of an
+	 * objective; the restore shim adopts it as one.
+	 */
 	prompt?: string;
 	/**
-	 * The loop's own objective and completion criteria. Its presence *is* the
-	 * loop's mode: set means standalone (this loop owns when the work is done,
-	 * ended by the `loop_complete` tool or a cap), absent means goal-bound (an
-	 * active pi-goal goal owns it, exactly as before).
+	 * The loop's objective and completion criteria: what it works on, and what
+	 * `loop_complete` answers for. Optional only because a loop persisted
+	 * before 0.6.0 may predate it — every loop started now has one.
 	 */
 	objective?: string;
 	intervalMs: number;
-	/** Delivered-poke cap; null means unlimited. */
-	maxIterations: number | null;
-	/** Proactive-compaction threshold fraction, or null when disabled per loop. */
-	compactAt: number | null;
 	/**
-	 * Turns this loop caused; null means unlimited. Counted separately from
-	 * `maxIterations` because one wake now yields many turns: a settle-driven
-	 * continuation chain runs without any wake at all.
+	 * Cap on the turns this loop causes (continuations plus pokes); null means
+	 * unlimited. The only cap: a settle-driven continuation chain runs without
+	 * any wake at all, so a wake cap bounded nothing this one does not.
 	 */
-	maxAutomaticTurns: number | null;
-	/** Delivered wakes so far (fallback pokes only). */
+	maxTurns: number | null;
+	/** Proactive-compaction threshold fraction, or null when disabled per loop. */
+	compactAt: number | null;
+	/** Delivered wakes so far (fallback pokes only); uncapped, and displayed. */
 	iteration: number;
-	/** Loop-caused turns so far (continuations + pokes). */
+	/** Loop-caused turns so far (continuations + pokes): what `maxTurns` caps. */
 	automaticTurns: number;
 	startedAt: number;
 	expiresAt: number;
@@ -90,8 +89,8 @@ export function normalizeLoopState(value: unknown): LoopState | undefined {
 	}
 	const intervalMs = record.intervalMs;
 	if (!isPositiveSafeInteger(intervalMs)) return undefined;
-	const maxIterations = record.maxIterations;
-	if (maxIterations !== null && !isPositiveSafeInteger(maxIterations)) return undefined;
+	const maxTurns = readTurnCap(record);
+	if (maxTurns === false) return undefined;
 	const compactAt = record.compactAt;
 	if (
 		compactAt !== null &&
@@ -99,16 +98,12 @@ export function normalizeLoopState(value: unknown): LoopState | undefined {
 	) {
 		return undefined;
 	}
-	const maxAutomaticTurns = Object.hasOwn(record, "maxAutomaticTurns")
-		? record.maxAutomaticTurns
-		: null;
-	if (maxAutomaticTurns !== null && !isPositiveSafeInteger(maxAutomaticTurns)) return undefined;
 	const iteration = record.iteration;
 	if (typeof iteration !== "number" || !Number.isSafeInteger(iteration) || iteration < 0) {
 		return undefined;
 	}
-	// Loops persisted before the two-counter split carry no automaticTurns; an
-	// absent counter restores as zero rather than rejecting the whole state.
+	// A loop persisted before the turn counter existed carries no automaticTurns;
+	// an absent counter restores as zero rather than rejecting the whole state.
 	const automaticTurns = Object.hasOwn(record, "automaticTurns") ? record.automaticTurns : 0;
 	if (
 		typeof automaticTurns !== "number" ||
@@ -146,8 +141,7 @@ export function normalizeLoopState(value: unknown): LoopState | undefined {
 		...(prompt === undefined ? {} : { prompt }),
 		...(objective === undefined ? {} : { objective }),
 		intervalMs,
-		maxIterations: maxIterations as number | null,
-		maxAutomaticTurns: maxAutomaticTurns as number | null,
+		maxTurns,
 		compactAt: compactAt as number | null,
 		iteration,
 		automaticTurns,
@@ -163,6 +157,33 @@ export function normalizeLoopState(value: unknown): LoopState | undefined {
 	};
 }
 
+/**
+ * The turn cap, adopting the caps a loop persisted by an older version
+ * carries: `maxAutomaticTurns` (turns) and `maxIterations` (wakes). An
+ * in-flight loop restored mid-upgrade keeps the tighter of them rather than
+ * having its bound widened or being dropped as unparsable; its wake *counter*
+ * is kept for display but no longer caps anything. Returns the cap, or false
+ * when a present value is invalid.
+ */
+function readTurnCap(record: Record<string, unknown>): number | null | false {
+	if (Object.hasOwn(record, "maxTurns")) {
+		const value = record.maxTurns;
+		if (value === null) return null;
+		return isPositiveSafeInteger(value) ? value : false;
+	}
+	let adopted: number | null | undefined;
+	for (const key of ["maxAutomaticTurns", "maxIterations"]) {
+		if (!Object.hasOwn(record, key)) continue;
+		const value = record[key];
+		if (value !== null && !isPositiveSafeInteger(value)) return false;
+		const cap = value as number | null;
+		// null is unlimited, so it only wins when every legacy cap is unlimited.
+		if (adopted === undefined || adopted === null) adopted = cap;
+		else if (cap !== null) adopted = Math.min(adopted, cap);
+	}
+	return adopted === undefined ? null : adopted;
+}
+
 // --- session-branch entry readers ---
 
 interface SessionEntryLike {
@@ -172,17 +193,11 @@ interface SessionEntryLike {
 }
 
 function lastCustomEntryData(entries: unknown[], customType: string): unknown {
-	return lastCustomEntryDatas(entries, customType, 1)[0];
-}
-
-/** Newest-first data of the last `limit` custom entries of `customType`. */
-function lastCustomEntryDatas(entries: unknown[], customType: string, limit: number): unknown[] {
-	const datas: unknown[] = [];
-	for (let index = entries.length - 1; index >= 0 && datas.length < limit; index -= 1) {
+	for (let index = entries.length - 1; index >= 0; index -= 1) {
 		const entry = entries[index] as SessionEntryLike | undefined;
-		if (entry?.type === "custom" && entry.customType === customType) datas.push(entry.data);
+		if (entry?.type === "custom" && entry.customType === customType) return entry.data;
 	}
-	return datas;
+	return undefined;
 }
 
 /** Restore the persisted loop state from a session branch, fail-open. */
@@ -193,77 +208,6 @@ export function restoreLoopState(entries: unknown[]): LoopState | undefined {
 	return normalizeLoopState(record.loop);
 }
 
-/**
- * A standalone loop owns its own completion criteria; a goal-bound loop
- * delegates that to pi-goal. Presence of `objective` is the discriminator.
- */
-export function isStandaloneLoop(loop: LoopState): boolean {
-	return loop.objective !== undefined;
-}
-
-export const GOAL_SAFETY_STATUSES = ["paused", "blocked", "usage_limited", "budget_limited"] as const;
-
-/** How many `goal-state` entries a clear may be scanned back through. */
-const GOAL_CLEAR_SCAN_LIMIT = 8;
-
-export interface GoalSnapshot {
-	status: string;
-	text: string;
-	/** Present while the goal is in a goal_wait external-event wait. */
-	waiting: boolean;
-	iteration?: number;
-	tokensUsed?: number;
-	tokenBudget?: number;
-	automaticModelTurns?: number;
-}
-
-/**
- * Read pi-goal's persisted goal, fail-open: undefined when absent or when the
- * entry shape is not recognizably a goal. Only fields pi-loop consumes are
- * extracted; unknown statuses are preserved verbatim so the caller can treat
- * anything outside its known sets conservatively.
- *
- * Completion race: pi-goal persists the finished goal (status "complete") and
- * then clears the entry (goal: null), so by the loop's next tick the last
- * entry is the clear. When the newest entry is a clear (or unreadable), scan
- * back over the consecutive run of clears for the goal they cleared: a
- * complete goal is reported, so the loop stops with "goal completed" instead
- * of pausing as goal-missing. A clear over any other status (user /goal clear
- * mid-flight) still reads as no goal. The scan is bounded so a long history of
- * clears cannot make the read walk the branch.
- */
-export function readGoalSnapshot(entries: unknown[]): GoalSnapshot | undefined {
-	const datas = lastCustomEntryDatas(entries, GOAL_STATE_ENTRY_TYPE, GOAL_CLEAR_SCAN_LIMIT);
-	const newest = parseGoalSnapshot(ownRecord(datas[0])?.goal);
-	if (newest) return newest;
-	for (let index = 1; index < datas.length; index += 1) {
-		const cleared = parseGoalSnapshot(ownRecord(datas[index])?.goal);
-		// Another clear or an unreadable entry: keep scanning back.
-		if (!cleared) continue;
-		return cleared.status === "complete" ? cleared : undefined;
-	}
-	return undefined;
-}
-
-function parseGoalSnapshot(value: unknown): GoalSnapshot | undefined {
-	const goal = ownRecord(value);
-	if (!goal) return undefined;
-	const status = typeof goal.status === "string" ? goal.status : undefined;
-	const text = typeof goal.text === "string" ? goal.text.trim() : "";
-	if (!status || !text) return undefined;
-	return {
-		status,
-		text,
-		waiting: ownRecord(goal.waiting) !== undefined,
-		...(isNonNegativeNumber(goal.iteration) ? { iteration: goal.iteration } : {}),
-		...(isNonNegativeNumber(goal.tokensUsed) ? { tokensUsed: goal.tokensUsed } : {}),
-		...(isNonNegativeNumber(goal.tokenBudget) ? { tokenBudget: goal.tokenBudget } : {}),
-		...(isNonNegativeNumber(goal.automaticModelTurns)
-			? { automaticModelTurns: goal.automaticModelTurns }
-			: {}),
-	};
-}
-
 /** Read pi-plan-mode's persisted state, fail-open: absent or malformed = not planning. */
 export function readPlanModeEnabled(entries: unknown[]): boolean {
 	const data = ownRecord(lastCustomEntryData(entries, PLAN_MODE_STATE_ENTRY_TYPE));
@@ -288,10 +232,6 @@ function isPositiveSafeInteger(value: unknown): value is number {
 	return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
 }
 
-function isNonNegativeNumber(value: unknown): value is number {
-	return typeof value === "number" && Number.isFinite(value) && value >= 0;
-}
-
 function isTimestamp(value: unknown): value is number {
 	return (
 		typeof value === "number" && Number.isSafeInteger(value) && value >= 0 && value <= MAX_TIMESTAMP

package/src/wait-tool.ts

@@ -10,7 +10,7 @@
  * Registered unconditionally, like `loop_complete`, and for the same reason:
  * tools are part of the cached request prefix, so adding or removing one
  * mid-session invalidates the whole conversation cache. It refuses when no
- * standalone loop is active.
+ * loop is active.
  */
 
 import { defineTool, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
@@ -59,7 +59,7 @@ export function registerLoopWaitTool(pi: ExtensionAPI, controller: LoopControlle
 				if (!loop || loop.objective === undefined) {
 					return {
 						content: toolContent(
-							"No standalone /loop is active. loop_wait only applies to a loop that carries its own objective; a goal-bound loop waits through pi-goal.",
+							"No /loop with an objective is active, so there is nothing to wait on. Start one with /loop <interval> <objective>.",
 						),
 						details: {},
 						isError: true,

package/src/widget.ts

@@ -1,6 +1,6 @@
 /**
  * The loop widget: a compact themed line above the editor mirroring the
- * footer status (interval · iteration/cap · next wake), with the loop focus
+ * footer status (interval · loop turns/cap · next wake), with the loop focus
  * dimmed below it when set.
  *
  * Presentation only: every entry point tolerates a host without setWidget
@@ -61,13 +61,15 @@ export function clearLoopWidget(ui: WidgetHost) {
 export function loopWidgetLine(view: LoopWidgetView) {
 	const loop = view.loop;
 	if (loop.status === "paused") return "⏸ loop paused";
-	const cap = loop.maxIterations === null ? "∞" : `${loop.maxIterations}`;
+	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}`;
+	// 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}`;
 }
 
 function identity(text: string) {