@hank-warren/pi-loop 0.4.1 → 0.6.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

@@ -1,6 +1,6 @@
 /**
  * Global pi-loop settings: `~/.pi/agent/pi-loop.json`. Follows the sibling
- * convention (pi-goal, pi-plan-mode): an absent file means defaults and is
+ * convention (pi-plan-mode): an absent file means defaults and is
  * never created implicitly, saves are atomic and preserve unknown fields, and
  * an invalid file warns and falls back to defaults without being overwritten.
  */
@@ -22,16 +22,44 @@ 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;
+	/**
+	 * Detect an inline `/loop` token or a `loop:` prefixed line mid-prompt and
+	 * point the model at the `loop_start` tool. Pi only dispatches `/loop` from
+	 * position 0, so without this a mid-prompt invocation is silently prose.
+	 */
+	inlineInvocation: boolean;
+	/**
+	 * Fallback heartbeat used by an inline invocation that names no interval.
+	 * In a settle-paced loop the interval is only a fallback — the settle
+	 * boundary is the pacemaker — so this value is far less consequential than
+	 * it looks; it is still clamped to MIN_INTERVAL_MS.
+	 */
+	defaultInterval: string;
 	compaction: LoopCompactionSettings;
 }
 
 export const DEFAULT_LOOP_SETTINGS: LoopSettings = {
 	maxIterations: 25,
+	automaticTurns: 25,
+	noProgressTurns: 3,
 	maxLoopDuration: "7d",
+	inlineInvocation: true,
+	defaultInterval: "10m",
 	compaction: {
 		enabled: true,
 		threshold: 0.7,
@@ -51,6 +79,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;
@@ -58,12 +95,24 @@ export function normalizeLoopSettings(value: unknown): LoopSettings | undefined
 		return undefined;
 	}
 
+	const inlineInvocation = Object.hasOwn(record, "inlineInvocation")
+		? record.inlineInvocation
+		: DEFAULT_LOOP_SETTINGS.inlineInvocation;
+	if (typeof inlineInvocation !== "boolean") return undefined;
+
+	const defaultInterval = Object.hasOwn(record, "defaultInterval")
+		? record.defaultInterval
+		: DEFAULT_LOOP_SETTINGS.defaultInterval;
+	if (typeof defaultInterval !== "string" || parseDuration(defaultInterval) === undefined) {
+		return undefined;
+	}
+
 	const compactionValue = Object.hasOwn(record, "compaction") ? record.compaction : undefined;
 	if (compactionValue !== undefined && !ownRecord(compactionValue)) return undefined;
 	const compactionRecord = ownRecord(compactionValue) ?? {};
-	// `postCompactContinuation` was removed in favour of pi-goal owning the
-	// post-compaction re-prompt; a file still carrying it is preserved as an
-	// unknown field and ignored, never rejected.
+	// `postCompactContinuation` was removed in favour of the loop's own
+	// re-anchor; a file still carrying it is preserved as an unknown field and
+	// ignored, never rejected.
 	const enabled = readBoolean(compactionRecord, "enabled", DEFAULT_LOOP_SETTINGS.compaction.enabled);
 	const threshold = Object.hasOwn(compactionRecord, "threshold")
 		? compactionRecord.threshold
@@ -86,7 +135,11 @@ export function normalizeLoopSettings(value: unknown): LoopSettings | undefined
 
 	return {
 		maxIterations,
+		automaticTurns,
+		noProgressTurns,
 		maxLoopDuration,
+		inlineInvocation,
+		defaultInterval,
 		compaction: { enabled, threshold, instructions },
 	};
 }
@@ -172,7 +225,11 @@ export function saveLoopSettings(settings: LoopSettings, settingsPath = loopSett
 		{
 			...raw,
 			maxIterations: normalized.maxIterations,
+			automaticTurns: normalized.automaticTurns,
+			noProgressTurns: normalized.noProgressTurns,
 			maxLoopDuration: normalized.maxLoopDuration,
+			inlineInvocation: normalized.inlineInvocation,
+			defaultInterval: normalized.defaultInterval,
 			compaction: { ...compaction, ...normalized.compaction },
 		},
 		null,

package/src/start-tool.ts

@@ -0,0 +1,145 @@
+/**
+ * `loop_start`: the model-invoked way into a loop.
+ *
+ * Pi only dispatches `/loop` when it starts the message, so a mid-prompt
+ * `quick check /loop 10m get CI green` arrives as ordinary prose. The
+ * inline-invocation hooks append a one-turn reminder to the system prompt for
+ * exactly that message, and this tool is what the reminder points at. It
+ * reuses `LoopController.startLoop`, the same path the `/loop` command takes,
+ * so replacement rules, the loop_complete availability guard, the ledger, the
+ * kickoff anchor, and persistence all behave identically.
+ *
+ * The hard armed-gate is the deliberate divergence from pi-goal's equivalent
+ * tool, which relied on prompt guidelines alone. A loop is *self-continuing*:
+ * a spurious start does not produce one unwanted answer, it produces turns
+ * until a cap. So the tool refuses outright unless the inline hint armed for
+ * the turn that is calling 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 { LOOP_COMPLETE_TOOL } from "./complete-tool.js";
+import { formatDuration, parseDuration, parseInterval } from "./interval.js";
+import type { InlineInvocationState } from "./inline-invocation.js";
+import type { LoopController } from "./loop.js";
+
+export const LOOP_START_TOOL = "loop_start";
+
+/** Long enough for a real objective, short enough to reject a pasted file. */
+const MAX_OBJECTIVE_LENGTH = 4_000;
+
+export function registerLoopStartTool(
+	pi: ExtensionAPI,
+	controller: LoopController,
+	invocation: InlineInvocationState,
+) {
+	pi.registerTool(
+		defineTool({
+			name: LOOP_START_TOOL,
+			label: "Loop Start",
+			description:
+				"Start a /loop for an objective the user explicitly invoked with an inline /loop or loop: token in their message. Only for explicit invocations: never start a loop from general conversation, your own initiative, or an instruction that merely sounds loop-like. The objective is the text following the token.",
+			promptSnippet:
+				"Start a /loop when the user's message contains an explicit inline /loop or loop: invocation",
+			promptGuidelines: [
+				"Call loop_start only when the user's message contains an explicit `/loop <objective>` or `loop: <objective>` token. Never start a loop without that token, no matter how loop-like the request sounds; the tool refuses when the turn carries no inline invocation.",
+				"If the user is discussing, quoting, or documenting the /loop command rather than invoking it — asking how it works, pasting a transcript, or editing text that mentions it — do not call loop_start.",
+				"Pass the objective text that follows the token, without the token itself. A leading interval (`10m`, `2h`) and flags like `--max 5` or `--expires 3d` become the interval, max, and expires parameters, not part of the objective.",
+				"Call loop_start before doing any of the objective's work, then continue working toward it in the same turn.",
+				"Never call loop_complete in the same turn as loop_start: the starting turn has not done the work, and completion needs cited evidence per criterion.",
+			],
+			parameters: Type.Object({
+				objective: Type.String({
+					minLength: 1,
+					maxLength: MAX_OBJECTIVE_LENGTH,
+					description:
+						"The loop objective, including how the loop knows it is done: the user's text following the /loop or loop: token, verbatim, without the token, the interval, or flags.",
+				}),
+				interval: Type.Optional(
+					Type.String({
+						description:
+							"Fallback wake interval from the invocation, e.g. '10m' or '2h'. Omit when the user named none.",
+					}),
+				),
+				max: Type.Optional(
+					Type.Integer({
+						minimum: 1,
+						description: "Wake cap from a --max flag in the invocation.",
+					}),
+				),
+				expires: Type.Optional(
+					Type.String({
+						description: "Loop lifetime from an --expires flag in the invocation, e.g. '3d'.",
+					}),
+				),
+			}),
+			async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+				// The gate. Everything below is ordinary validation; this is the
+				// one check that makes a self-continuing tool safe to expose.
+				if (!invocation.invokedThisTurn) {
+					return refusal(
+						`${LOOP_START_TOOL} is only available on a turn whose user message contains an explicit inline /loop or loop: invocation. This turn has none, so no loop was started. If the user wants one, they can type /loop <interval> <objective>.`,
+						{},
+					);
+				}
+				const objective = params.objective.trim();
+				if (!objective) {
+					return refusal("Loop not started: the objective is empty.", {});
+				}
+				const existing = controller.state;
+				if (existing && existing.status !== "stopped") {
+					return refusal(
+						`Loop not started: a loop already exists in this session (${existing.status}). The user can replace it with /loop, or stop it with /loop stop.`,
+						{ existingLoopId: existing.id },
+					);
+				}
+				const intervalToken = params.interval?.trim() || controller.settings.defaultInterval;
+				const interval = parseInterval(intervalToken);
+				if (!interval) {
+					return refusal(
+						`Loop not started: invalid interval ${intervalToken}. Use <number><unit> with unit s, m, h, or d, e.g. 10m.`,
+						{ objective },
+					);
+				}
+				let expiresInMs: number | undefined;
+				if (params.expires !== undefined) {
+					expiresInMs = parseDuration(params.expires.trim());
+					if (expiresInMs === undefined) {
+						return refusal(
+							`Loop not started: invalid expiry ${params.expires}. Use <number><unit> with unit s, m, h, or d, e.g. 3d.`,
+							{ objective },
+						);
+					}
+				}
+				const result = controller.startLoop(ctx, {
+					kind: "start",
+					requestedMs: interval.requestedMs,
+					intervalMs: interval.effectiveMs,
+					clamped: interval.clamped,
+					...(params.max === undefined ? {} : { maxIterations: params.max }),
+					...(expiresInMs === undefined ? {} : { expiresInMs }),
+					prompt: objective,
+				});
+				if (!result.ok) return refusal(`Loop not started: ${result.message}`, { objective });
+				const loop = result.loop;
+				return {
+					content: toolContent(
+						`Loop started (loop_id ${loop.id}): ${objective}. Fallback wake every ${formatDuration(loop.intervalMs)}. Keep working the objective this turn; the loop continues at every idle boundary until you call ${LOOP_COMPLETE_TOOL} with this loop_id and cited evidence for every criterion, a cap is reached, or the user stops it. Do not call ${LOOP_COMPLETE_TOOL} in this turn.`,
+					),
+					details: { loopId: loop.id, objective, intervalMs: loop.intervalMs },
+				};
+			},
+		}),
+	);
+}
+
+function refusal(text: string, details: Record<string, unknown>) {
+	return { content: toolContent(text), details, isError: true };
+}
+
+function toolContent(text: string) {
+	return [{ type: "text" as const, text }];
+}