@hank-warren/pi-loop 0.4.0 → 0.5.0

package/src/schedule/store.ts

@@ -0,0 +1,183 @@
+/**
+ * Persistence for `run` tasks (`~/.pi/agent/loop/schedules.json`) and the
+ * single-writer lease that decides which live Pi session is allowed to fire
+ * them.
+ *
+ * The lease exists because headless tasks are shared state: every open
+ * session reads the same file, and without arbitration a task scheduled for
+ * 09:00 fires once per session that happens to be running. A lockfile holding
+ * a pid and a heartbeat is enough — a holder that dies stops renewing, and
+ * the next session takes over after the stale window. Deliberately not a real
+ * distributed lock: the failure it must prevent is *duplicate work*, and the
+ * worst case it can produce is one skipped tick.
+ *
+ * Everything here is best-effort. A read-only home directory means "no
+ * headless scheduling", never a crash.
+ */
+
+import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { dirname, join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { normalizeTask, type ScheduledTask } from "./model.js";
+
+export const SCHEDULES_FILE = "schedules.json";
+export const LEASE_FILE = "schedules.lease";
+export const RUNS_DIR = "runs";
+
+/** A lease older than this is assumed abandoned. */
+export const LEASE_STALE_MS = 90_000;
+/** How often the holder refreshes it. */
+export const LEASE_HEARTBEAT_MS = 30_000;
+
+export interface SchedulePaths {
+	dir: string;
+	schedules: string;
+	lease: string;
+	runs: string;
+}
+
+export function schedulePaths(agentDir = getAgentDir()): SchedulePaths {
+	const dir = join(agentDir, "loop");
+	return {
+		dir,
+		schedules: join(dir, SCHEDULES_FILE),
+		lease: join(dir, LEASE_FILE),
+		runs: join(dir, RUNS_DIR),
+	};
+}
+
+/** Read persisted tasks, fail-open: an unreadable file means no tasks. */
+export function readTasks(paths: SchedulePaths): ScheduledTask[] {
+	let contents: string;
+	try {
+		contents = readFileSync(paths.schedules, "utf8");
+	} catch {
+		return [];
+	}
+	try {
+		const parsed: unknown = JSON.parse(contents);
+		if (!Array.isArray(parsed)) return [];
+		// One malformed entry drops itself, not the whole schedule.
+		return parsed
+			.map((value) => normalizeTask(value))
+			.filter((task): task is ScheduledTask => task !== undefined);
+	} catch {
+		return [];
+	}
+}
+
+/** Atomically replace the persisted tasks. Returns a failure reason, if any. */
+export function writeTasks(paths: SchedulePaths, tasks: ScheduledTask[]): string | undefined {
+	const document = `${JSON.stringify(tasks, null, 2)}\n`;
+	const temporary = join(paths.dir, `.${SCHEDULES_FILE}.${randomUUID()}.tmp`);
+	try {
+		mkdirSync(paths.dir, { recursive: true });
+		writeFileSync(temporary, document, { encoding: "utf8", flag: "wx" });
+		renameSync(temporary, paths.schedules);
+		return undefined;
+	} catch (error) {
+		return error instanceof Error ? error.message : String(error);
+	} finally {
+		try {
+			rmSync(temporary, { force: true });
+		} catch {
+			// Best-effort cleanup must not replace the write result.
+		}
+	}
+}
+
+export interface LeaseRecord {
+	pid: number;
+	heartbeat: number;
+	owner: string;
+}
+
+/**
+ * Take or renew the lease. Returns true when this process may fire headless
+ * tasks. `owner` identifies this runtime so a restarted process with a reused
+ * pid cannot mistake someone else's lease for its own.
+ */
+export function acquireLease(
+	paths: SchedulePaths,
+	owner: string,
+	now: number,
+	pid: number = process.pid,
+): boolean {
+	const current = readLease(paths);
+	if (current && current.owner !== owner) {
+		const fresh = now - current.heartbeat < LEASE_STALE_MS;
+		if (fresh && isProcessAlive(current.pid)) return false;
+	}
+	return writeLease(paths, { pid, heartbeat: now, owner });
+}
+
+/** Release the lease if this owner holds it. */
+export function releaseLease(paths: SchedulePaths, owner: string): void {
+	const current = readLease(paths);
+	if (!current || current.owner !== owner) return;
+	try {
+		rmSync(paths.lease, { force: true });
+	} catch {
+		// A lease we cannot delete simply goes stale.
+	}
+}
+
+export function readLease(paths: SchedulePaths): LeaseRecord | undefined {
+	try {
+		const parsed: unknown = JSON.parse(readFileSync(paths.lease, "utf8"));
+		if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return undefined;
+		const record = parsed as Record<string, unknown>;
+		if (
+			typeof record.pid !== "number" ||
+			typeof record.heartbeat !== "number" ||
+			typeof record.owner !== "string" ||
+			!record.owner
+		) {
+			return undefined;
+		}
+		return { pid: record.pid, heartbeat: record.heartbeat, owner: record.owner };
+	} catch {
+		return undefined;
+	}
+}
+
+function writeLease(paths: SchedulePaths, lease: LeaseRecord): boolean {
+	const temporary = join(dirname(paths.lease), `.${LEASE_FILE}.${randomUUID()}.tmp`);
+	try {
+		mkdirSync(paths.dir, { recursive: true });
+		writeFileSync(temporary, `${JSON.stringify(lease)}\n`, { encoding: "utf8", flag: "wx" });
+		renameSync(temporary, paths.lease);
+		return true;
+	} catch {
+		return false;
+	} finally {
+		try {
+			rmSync(temporary, { force: true });
+		} catch {
+			// Best-effort.
+		}
+	}
+}
+
+function isProcessAlive(pid: number): boolean {
+	if (!Number.isSafeInteger(pid) || pid <= 0) return false;
+	try {
+		// Signal 0 tests for existence without delivering anything.
+		process.kill(pid, 0);
+		return true;
+	} catch (error) {
+		// EPERM means it exists and belongs to someone else.
+		return isNodeError(error) && error.code === "EPERM";
+	}
+}
+
+function isNodeError(error: unknown): error is NodeJS.ErrnoException {
+	return error instanceof Error && "code" in error;
+}
+
+/** Where a headless run's output is logged. */
+export function runLogPath(paths: SchedulePaths, taskId: string, at: number): string {
+	const stamp = new Date(at).toISOString().replace(/[:.]/g, "-");
+	return join(paths.runs, taskId, `${stamp}.log`);
+}

package/src/settings.ts

@@ -22,8 +22,19 @@ export interface LoopCompactionSettings {
 }
 
 export interface LoopSettings {
-	/** Delivered-poke cap; null means unlimited (explicit opt-in). */
+	/** Delivered-wake cap; null means unlimited (explicit opt-in). */
 	maxIterations: number | null;
+	/**
+	 * Cap on turns the loop itself causes (settle continuations plus fallback
+	 * pokes); null means unlimited. A settle-paced loop can run many turns per
+	 * wake, so this is the bound that actually holds it.
+	 */
+	automaticTurns: number | null;
+	/**
+	 * Consecutive tool-free loop turns with identical output that pause the
+	 * loop; null disables the breaker.
+	 */
+	noProgressTurns: number | null;
 	/** Wall-clock expiry for a loop, e.g. "7d" (research: bound forgotten loops). */
 	maxLoopDuration: string;
 	compaction: LoopCompactionSettings;
@@ -31,6 +42,8 @@ export interface LoopSettings {
 
 export const DEFAULT_LOOP_SETTINGS: LoopSettings = {
 	maxIterations: 25,
+	automaticTurns: 25,
+	noProgressTurns: 3,
 	maxLoopDuration: "7d",
 	compaction: {
 		enabled: true,
@@ -51,6 +64,15 @@ export function normalizeLoopSettings(value: unknown): LoopSettings | undefined
 	const maxIterations = normalizeCap(record.maxIterations, DEFAULT_LOOP_SETTINGS.maxIterations);
 	if (maxIterations === false) return undefined;
 
+	const automaticTurns = normalizeCap(record.automaticTurns, DEFAULT_LOOP_SETTINGS.automaticTurns);
+	if (automaticTurns === false) return undefined;
+
+	const noProgressTurns = normalizeCap(
+		record.noProgressTurns,
+		DEFAULT_LOOP_SETTINGS.noProgressTurns,
+	);
+	if (noProgressTurns === false) return undefined;
+
 	const maxLoopDuration = Object.hasOwn(record, "maxLoopDuration")
 		? record.maxLoopDuration
 		: DEFAULT_LOOP_SETTINGS.maxLoopDuration;
@@ -86,6 +108,8 @@ export function normalizeLoopSettings(value: unknown): LoopSettings | undefined
 
 	return {
 		maxIterations,
+		automaticTurns,
+		noProgressTurns,
 		maxLoopDuration,
 		compaction: { enabled, threshold, instructions },
 	};
@@ -172,6 +196,8 @@ export function saveLoopSettings(settings: LoopSettings, settingsPath = loopSett
 		{
 			...raw,
 			maxIterations: normalized.maxIterations,
+			automaticTurns: normalized.automaticTurns,
+			noProgressTurns: normalized.noProgressTurns,
 			maxLoopDuration: normalized.maxLoopDuration,
 			compaction: { ...compaction, ...normalized.compaction },
 		},

package/src/state.ts

@@ -11,6 +11,8 @@ 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];
 
@@ -31,11 +33,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 +99,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 +147,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 } : {}),
 	};
 }
 
@@ -205,6 +276,14 @@ function ownRecord(value: unknown): Record<string, unknown> | undefined {
 		: undefined;
 }
 
+/** 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 isPositiveSafeInteger(value: unknown): value is number {
 	return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
 }

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
+ * standalone 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 standalone /loop is active. loop_wait only applies to a loop that carries its own objective; a goal-bound loop waits through pi-goal.",
+						),
+						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?.();
+	}
+}