@hank-warren/pi-loop 0.4.1 → 0.6.0

package/src/state.ts

@@ -1,29 +1,32 @@
 /**
- * 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";
+
 export const LOOP_STATUSES = ["active", "paused", "stopped"] as const;
 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;
@@ -31,11 +34,37 @@ export interface LoopState {
 	maxIterations: number | null;
 	/** Proactive-compaction threshold fraction, or null when disabled per loop. */
 	compactAt: number | null;
-	/** Delivered pokes so far. */
+	/**
+	 * 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.
+	 */
+	maxAutomaticTurns: number | null;
+	/** Delivered wakes so far (fallback pokes only). */
 	iteration: number;
+	/** Loop-caused turns so far (continuations + pokes). */
+	automaticTurns: number;
 	startedAt: number;
 	expiresAt: number;
 	lastWakeAt?: number;
+	/** Set while the model has declared an external wait through `loop_wait`. */
+	waiting?: LoopWait;
+	/**
+	 * The reason of a wait cancelled by something other than its own deadline,
+	 * surfaced once in the next loop message so the context is not simply lost.
+	 */
+	cancelledWaitReason?: string;
+	/** Consecutive tool-free loop turns with identical visible output. */
+	toolFreeRepeatCount?: number;
+	lastFingerprint?: string;
+	/** Why a paused loop paused, for the widget and status after a restore. */
+	pauseCause?: string;
+	/**
+	 * Set once the expiry's final wake has been delivered. The loop is still
+	 * active for exactly that one turn, so the objective append is present
+	 * while it writes its state down; the next settle stops it.
+	 */
+	expiring?: true;
 }
 
 const MAX_PROMPT_LENGTH = 100_000;
@@ -71,12 +100,47 @@ 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.
+	const automaticTurns = Object.hasOwn(record, "automaticTurns") ? record.automaticTurns : 0;
+	if (
+		typeof automaticTurns !== "number" ||
+		!Number.isSafeInteger(automaticTurns) ||
+		automaticTurns < 0
+	) {
+		return undefined;
+	}
 	if (!isTimestamp(record.startedAt) || !isTimestamp(record.expiresAt)) return undefined;
 	if (record.lastWakeAt !== undefined && !isTimestamp(record.lastWakeAt)) return undefined;
+	let waiting: LoopWait | undefined;
+	if (record.waiting !== undefined) {
+		waiting = normalizeLoopWait(record.waiting);
+		if (!waiting) return undefined;
+	}
+	const cancelledWaitReason = optionalText(record.cancelledWaitReason);
+	if (cancelledWaitReason === false) return undefined;
+	const pauseCause = optionalText(record.pauseCause);
+	if (pauseCause === false) return undefined;
+	const toolFreeRepeatCount = record.toolFreeRepeatCount;
+	if (
+		toolFreeRepeatCount !== undefined &&
+		(typeof toolFreeRepeatCount !== "number" ||
+			!Number.isSafeInteger(toolFreeRepeatCount) ||
+			toolFreeRepeatCount < 0)
+	) {
+		return undefined;
+	}
+	const lastFingerprint = optionalText(record.lastFingerprint);
+	if (lastFingerprint === false) return undefined;
+	if (record.expiring !== undefined && record.expiring !== true) return undefined;
 	return {
 		id,
 		status: status as LoopStatus,
@@ -84,11 +148,19 @@ export function normalizeLoopState(value: unknown): LoopState | undefined {
 		...(objective === undefined ? {} : { objective }),
 		intervalMs,
 		maxIterations: maxIterations as number | null,
+		maxAutomaticTurns: maxAutomaticTurns as number | null,
 		compactAt: compactAt as number | null,
 		iteration,
+		automaticTurns,
 		startedAt: record.startedAt as number,
 		expiresAt: record.expiresAt as number,
 		...(record.lastWakeAt === undefined ? {} : { lastWakeAt: record.lastWakeAt as number }),
+		...(waiting === undefined ? {} : { waiting }),
+		...(cancelledWaitReason === undefined ? {} : { cancelledWaitReason }),
+		...(toolFreeRepeatCount === undefined ? {} : { toolFreeRepeatCount }),
+		...(lastFingerprint === undefined ? {} : { lastFingerprint }),
+		...(pauseCause === undefined ? {} : { pauseCause }),
+		...(record.expiring === true ? { expiring: true as const } : {}),
 	};
 }
 
@@ -101,17 +173,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. */
@@ -122,77 +188,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));
@@ -205,12 +200,16 @@ function ownRecord(value: unknown): Record<string, unknown> | undefined {
 		: undefined;
 }
 
-function isPositiveSafeInteger(value: unknown): value is number {
-	return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
+/** A present-but-optional string: the value, undefined when absent, false when invalid. */
+function optionalText(value: unknown): string | undefined | false {
+	if (value === undefined) return undefined;
+	if (typeof value !== "string") return false;
+	const trimmed = value.trim();
+	return trimmed && trimmed.length <= MAX_PROMPT_LENGTH ? trimmed : false;
 }
 
-function isNonNegativeNumber(value: unknown): value is number {
-	return typeof value === "number" && Number.isFinite(value) && value >= 0;
+function isPositiveSafeInteger(value: unknown): value is number {
+	return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
 }
 
 function isTimestamp(value: unknown): value is number {

package/src/wait-tool.ts

@@ -0,0 +1,114 @@
+/**
+ * `loop_wait`: the loop's adaptive wake.
+ *
+ * Without it a loop has exactly one answer to "progress depends on something
+ * outside this session": keep continuing, and burn turns re-checking. With
+ * it, the model says what it is waiting for and roughly how long, the loop
+ * stops continuing on its own, and the wait's deadline becomes the next thing
+ * that speaks.
+ *
+ * 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
+ * loop is active.
+ */
+
+import { defineTool, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import type { LoopController } from "./loop.js";
+import { formatDuration } from "./interval.js";
+import { MAX_WAIT_DELAY_MS, MAX_WAIT_REASON_LENGTH, MIN_WAIT_DELAY_MS } from "./wait.js";
+
+export const LOOP_WAIT_TOOL = "loop_wait";
+
+export function registerLoopWaitTool(pi: ExtensionAPI, controller: LoopController) {
+	pi.registerTool(
+		defineTool({
+			name: LOOP_WAIT_TOOL,
+			label: "Loop Wait",
+			description:
+				"Pause the active /loop's automatic continuations while progress depends on an external event. The loop stays active; it simply stops continuing on its own until resume_after_ms elapses or something else wakes the session. Never use it for ordinary unfinished work.",
+			promptSnippet: "Wait for an external event without ending the active /loop",
+			promptGuidelines: [
+				"Call loop_wait only when progress genuinely depends on a later external event (a CI run, a deploy, a human reply), never for ordinary unfinished work and never as a way to end a turn early.",
+				"Give a one-sentence reason: it is shown in the loop widget and status, and it is the only record of what the loop was waiting for.",
+				"Never poll for work Pi already notifies you about — background processes, subagents, and tool completions wake the session on their own.",
+				// The cache-window guidance: a wake just after the provider's
+				// prompt-cache TTL pays a full cache miss for nothing.
+				"Avoid resume_after_ms near 300000 (5 minutes): that is the prompt-cache dead zone, where the cache has just expired and the next turn re-reads the whole conversation at full price.",
+				"Use a value at or below 270000 only when actively polling external state that nothing else will report. Otherwise commit to 1200000 or more.",
+				`resume_after_ms is clamped to [${MIN_WAIT_DELAY_MS}, ${MAX_WAIT_DELAY_MS}]; the clamped value is echoed back. Omitting it waits until something else wakes the session.`,
+				"Call loop_wait alone: sibling tool calls in the same turn can prevent the turn from ending, which is the point of the wait.",
+			],
+			parameters: Type.Object({
+				reason: Type.String({
+					minLength: 1,
+					maxLength: MAX_WAIT_REASON_LENGTH,
+					description:
+						"One sentence naming the external event being waited for. Shown in the loop widget and status.",
+				}),
+				resume_after_ms: Type.Optional(
+					Type.Number({
+						description:
+							"Optional bounded safety wake-up in milliseconds, clamped to [60000, 3600000]. Omit to wait until something else wakes the session.",
+					}),
+				),
+			}),
+			async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+				const loop = controller.state;
+				if (!loop || loop.objective === undefined) {
+					return {
+						content: toolContent(
+							"No /loop with an objective is active, so there is nothing to wait on. Start one with /loop <interval> <objective>.",
+						),
+						details: {},
+						isError: true,
+					};
+				}
+				if (loop.status !== "active") {
+					return {
+						content: toolContent(`The /loop is ${loop.status}; there is nothing to wait on.`),
+						details: { loopId: loop.id, status: loop.status },
+						isError: true,
+					};
+				}
+				const reason = params.reason.trim();
+				if (!reason) {
+					return {
+						content: toolContent("loop_wait needs a reason: name the external event in one sentence."),
+						details: { loopId: loop.id },
+						isError: true,
+					};
+				}
+				const wait = controller.enterWait(reason, params.resume_after_ms);
+				if (!wait) {
+					return {
+						content: toolContent("The /loop could not enter a wait; it is no longer active."),
+						details: { loopId: loop.id },
+						isError: true,
+					};
+				}
+				const deadline =
+					wait.effectiveMs === undefined
+						? "No deadline: the loop stays quiet until something else wakes the session."
+						: `${wait.clamped ? `Requested ${Math.round((wait.requestedMs ?? 0) / 1000)}s, clamped to ` : "Waking in "}${formatDuration(wait.effectiveMs)}.`;
+				return {
+					content: toolContent(
+						`Loop waiting: ${reason}\n${deadline} Automatic continuations are held; the loop stays active.`,
+					),
+					details: {
+						loopId: loop.id,
+						reason,
+						...(wait.requestedMs === undefined ? {} : { requestedMs: wait.requestedMs }),
+						...(wait.effectiveMs === undefined ? {} : { effectiveMs: wait.effectiveMs }),
+						clamped: wait.clamped,
+					},
+				};
+			},
+		}),
+	);
+}
+
+function toolContent(text: string) {
+	return [{ type: "text" as const, text }];
+}

package/src/wait.ts

@@ -0,0 +1,95 @@
+/**
+ * `loop_wait` state: the model's declaration that progress now depends on
+ * something outside the session.
+ *
+ * A wait does not stop the loop and does not cancel the pacemaker. It
+ * supersedes the *next* fallback wake — the loop stops continuing on its own
+ * and the wait's own deadline becomes the next thing that speaks. That is the
+ * whole difference between "waiting" and "paused": a paused loop needs the
+ * user, a waiting loop needs the world.
+ *
+ * The clamp is a range, not a floor. Below 60s a wait is polling, which is
+ * what the tool exists to replace; above an hour it stops being a wait and
+ * becomes an abandonment, and the fallback heartbeat covers that case better.
+ */
+
+export interface LoopWait {
+	reason: string;
+	resumeAt?: number;
+}
+
+export const MAX_WAIT_REASON_LENGTH = 1_000;
+export const MIN_WAIT_DELAY_MS = 60_000;
+export const MAX_WAIT_DELAY_MS = 3_600_000;
+const MAX_TIMESTAMP = 8_640_000_000_000_000;
+
+export interface ResolvedWaitDelay {
+	requestedMs?: number;
+	effectiveMs?: number;
+	clamped: boolean;
+}
+
+export function resolveWaitDelay(resumeAfterMs: number | undefined): ResolvedWaitDelay {
+	if (resumeAfterMs === undefined || !Number.isFinite(resumeAfterMs)) return { clamped: false };
+	const effectiveMs = Math.min(MAX_WAIT_DELAY_MS, Math.max(MIN_WAIT_DELAY_MS, resumeAfterMs));
+	return { requestedMs: resumeAfterMs, effectiveMs, clamped: effectiveMs !== resumeAfterMs };
+}
+
+export function createLoopWait(
+	reason: string,
+	resumeAfterMs: number | undefined,
+	now: number,
+): LoopWait {
+	const { effectiveMs } = resolveWaitDelay(resumeAfterMs);
+	return {
+		reason,
+		...(effectiveMs === undefined ? {} : { resumeAt: now + effectiveMs }),
+	};
+}
+
+export function normalizeLoopWait(value: unknown): LoopWait | undefined {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+	const record = value as Record<string, unknown>;
+	const reason = typeof record.reason === "string" ? record.reason.trim() : "";
+	if (!reason || reason.length > MAX_WAIT_REASON_LENGTH) return undefined;
+	if (!Object.hasOwn(record, "resumeAt")) return { reason };
+	const resumeAt = record.resumeAt;
+	if (
+		typeof resumeAt !== "number" ||
+		!Number.isSafeInteger(resumeAt) ||
+		resumeAt < 0 ||
+		resumeAt > MAX_TIMESTAMP
+	) {
+		return undefined;
+	}
+	return { reason, resumeAt };
+}
+
+/**
+ * A single-slot timer whose callbacks are generation-guarded, so a wait that
+ * was cleared or replaced can never fire against the loop that replaced it.
+ */
+export class LoopWaitTimer {
+	private generation = 0;
+	private timer: NodeJS.Timeout | undefined;
+
+	clear(): void {
+		this.generation += 1;
+		if (!this.timer) return;
+		clearTimeout(this.timer);
+		this.timer = undefined;
+	}
+
+	schedule(resumeAt: number, onDue: () => void, now: number = Date.now()): void {
+		this.clear();
+		const generation = this.generation;
+		const delay = Math.max(0, Math.min(MAX_WAIT_DELAY_MS, resumeAt - now));
+		this.timer = setTimeout(() => {
+			if (generation !== this.generation) return;
+			this.timer = undefined;
+			onDue();
+		}, delay);
+		// A pending wake must never hold the process open.
+		this.timer.unref?.();
+	}
+}