@hank-warren/pi-loop 0.1.0

package/src/messages.ts

@@ -0,0 +1,108 @@
+/**
+ * Builders for every loop-injected message: pokes, the proactive compaction
+ * instructions, and the post-compaction continuation. Pure string functions so
+ * tests can pin their contracts — most importantly that the continuation never
+ * embeds a runnable /loop command (research: Claude Code compaction summaries
+ * re-executed scheduling commands, issue #50554).
+ */
+
+import { formatDuration } from "./interval.js";
+import { appendContinuationMarker, appendPokeMarker } from "./markers.js";
+import type { GoalSnapshot, LoopState } from "./state.js";
+
+function formatIteration(loop: LoopState): string {
+	const cap = loop.maxIterations === null ? "unlimited" : `${loop.maxIterations}`;
+	return `${loop.iteration + 1}/${cap}`;
+}
+
+/** The recurring-prompt poke: the stored prompt with a short scheduled preamble. */
+export function buildPromptPoke(loop: LoopState, preambleOverride: string | null): string {
+	const preamble =
+		preambleOverride ??
+		`Scheduled loop iteration ${formatIteration(loop)} (every ${formatDuration(loop.intervalMs)}). Continue the recurring task below; if its work is exhausted, say so instead of inventing new work.`;
+	const prompt = loop.prompt ?? "";
+	return appendPokeMarker(`${preamble}\n\n${prompt}`.trim(), loop.id, loop.iteration + 1);
+}
+
+/** The goal-bound poke: restate the goal and wake goal_wait if applicable. */
+export function buildGoalPoke(
+	loop: LoopState,
+	goal: GoalSnapshot,
+	reason: "goal-stalled" | "goal-waiting",
+): string {
+	const lines = [
+		`Scheduled loop wakeup ${formatIteration(loop)} (every ${formatDuration(loop.intervalMs)}).`,
+		reason === "goal-waiting"
+			? "This is the external wake for your waiting goal. Re-check whatever the goal was waiting on and continue."
+			: "The session went idle but the active goal is not complete. Continue working toward it.",
+		"",
+		`Active goal: ${goal.text}`,
+	];
+	if (loop.prompt) lines.push("", `Loop focus: ${loop.prompt}`);
+	lines.push("", "Use the goal tools (goal_complete, goal_blocked, goal_wait) when their conditions are met.");
+	return appendPokeMarker(lines.join("\n"), loop.id, loop.iteration + 1);
+}
+
+/**
+ * Instructions for the loop-owned proactive compaction. Encodes the
+ * research-backed preservation list, including cumulative carry-forward of
+ * prior summaries so detail does not decay geometrically across compactions.
+ */
+export function buildCompactionInstructions(
+	loop: LoopState,
+	goal: GoalSnapshot | undefined,
+	override: string | null,
+): string {
+	if (override) return override;
+	const objective = goal
+		? `The session is working toward this goal: ${goal.text}`
+		: loop.prompt
+			? `The session is running a recurring task: ${loop.prompt}`
+			: "The session is running a recurring loop.";
+	return [
+		`${objective}`,
+		"This summary must let that work continue seamlessly. Preserve verbatim:",
+		"- the current objective and its acceptance criteria",
+		"- decisions made and their rationale, including rejected approaches and dead-ends (they must not be retried)",
+		"- exact files modified and what remains to be done",
+		"- exact commands run, their results, and any unresolved errors",
+		"- the next 1-3 concrete actions",
+		"- any prior compaction summary's still-relevant content, carried forward cumulatively",
+		"Discard raw tool output, file contents that live on disk, and duplicate exploration.",
+	].join("\n");
+}
+
+/**
+ * The post-compaction continuation message. Restates the loop and goal state
+ * (including pi-goal's thresholds) so work resumes coherently. Deliberately
+ * references /loop only as inert prose-free metadata: no line of this message
+ * is a dispatchable command.
+ */
+export function buildPostCompactContinuation(
+	loop: LoopState,
+	goal: GoalSnapshot | undefined,
+): string {
+	const lines = [
+		"Context was just compacted. Loop status, restored from outside the context window:",
+		`- loop iteration: ${loop.iteration}${loop.maxIterations === null ? "" : ` of ${loop.maxIterations}`}, waking every ${formatDuration(loop.intervalMs)}`,
+	];
+	if (loop.prompt) lines.push(`- recurring task: ${loop.prompt}`);
+	if (goal) {
+		lines.push(`- active goal (status ${goal.status}): ${goal.text}`);
+		const thresholds: string[] = [];
+		if (goal.iteration !== undefined) thresholds.push(`goal iteration ${goal.iteration}`);
+		if (goal.automaticModelTurns !== undefined) {
+			thresholds.push(`${goal.automaticModelTurns} automatic turns used`);
+		}
+		if (goal.tokensUsed !== undefined) {
+			thresholds.push(
+				`${goal.tokensUsed} tokens used${goal.tokenBudget !== undefined ? ` of a ${goal.tokenBudget} budget` : ""}`,
+			);
+		}
+		if (thresholds.length > 0) lines.push(`- goal accounting: ${thresholds.join(", ")}`);
+	}
+	lines.push(
+		"Re-read any plan, progress, or state files the work relies on before continuing, then resume from the next concrete action.",
+	);
+	return appendContinuationMarker(lines.join("\n"), loop.id);
+}

package/src/settings.ts

@@ -0,0 +1,239 @@
+/**
+ * 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
+ * never created implicitly, saves are atomic and preserve unknown fields, and
+ * an invalid file warns and falls back to defaults without being overwritten.
+ */
+
+import { randomUUID } from "node:crypto";
+import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { parseDuration } from "./interval.js";
+
+export const LOOP_SETTINGS_FILE = "pi-loop.json";
+
+export interface LoopCompactionSettings {
+	enabled: boolean;
+	/** Fraction of the context window that triggers a proactive compact. */
+	threshold: number;
+	postCompactContinuation: boolean;
+	/** Override for the built-in compaction instruction template. */
+	instructions: string | null;
+}
+
+export interface LoopSettings {
+	/** Delivered-poke cap; null means unlimited (explicit opt-in). */
+	maxIterations: number | null;
+	/** Wall-clock expiry for a loop, e.g. "7d" (research: bound forgotten loops). */
+	maxLoopDuration: string;
+	compaction: LoopCompactionSettings;
+	/** Override for the built-in poke preamble template. */
+	pokePreamble: string | null;
+	/** Recognize /loop mid-prompt. */
+	inlineInvocation: boolean;
+}
+
+export const DEFAULT_LOOP_SETTINGS: LoopSettings = {
+	maxIterations: 25,
+	maxLoopDuration: "7d",
+	compaction: {
+		enabled: true,
+		threshold: 0.7,
+		postCompactContinuation: true,
+		instructions: null,
+	},
+	pokePreamble: null,
+	inlineInvocation: true,
+};
+
+export type LoopSettingsLoadResult =
+	| { kind: "missing"; settings: LoopSettings }
+	| { kind: "invalid"; reason: string; settings: LoopSettings }
+	| { kind: "loaded"; settings: LoopSettings };
+
+export function normalizeLoopSettings(value: unknown): LoopSettings | undefined {
+	const record = ownRecord(value);
+	if (!record) return undefined;
+
+	const maxIterations = normalizeCap(record.maxIterations, DEFAULT_LOOP_SETTINGS.maxIterations);
+	if (maxIterations === false) return undefined;
+
+	const maxLoopDuration = Object.hasOwn(record, "maxLoopDuration")
+		? record.maxLoopDuration
+		: DEFAULT_LOOP_SETTINGS.maxLoopDuration;
+	if (typeof maxLoopDuration !== "string" || parseDuration(maxLoopDuration) === undefined) {
+		return undefined;
+	}
+
+	const compactionValue = Object.hasOwn(record, "compaction") ? record.compaction : undefined;
+	if (compactionValue !== undefined && !ownRecord(compactionValue)) return undefined;
+	const compactionRecord = ownRecord(compactionValue) ?? {};
+	const enabled = readBoolean(compactionRecord, "enabled", DEFAULT_LOOP_SETTINGS.compaction.enabled);
+	const postCompactContinuation = readBoolean(
+		compactionRecord,
+		"postCompactContinuation",
+		DEFAULT_LOOP_SETTINGS.compaction.postCompactContinuation,
+	);
+	const threshold = Object.hasOwn(compactionRecord, "threshold")
+		? compactionRecord.threshold
+		: DEFAULT_LOOP_SETTINGS.compaction.threshold;
+	const instructions = readNullableString(
+		compactionRecord,
+		"instructions",
+		DEFAULT_LOOP_SETTINGS.compaction.instructions,
+	);
+	if (
+		typeof enabled !== "boolean" ||
+		typeof postCompactContinuation !== "boolean" ||
+		instructions === false ||
+		typeof threshold !== "number" ||
+		!Number.isFinite(threshold) ||
+		threshold <= 0 ||
+		threshold >= 1
+	) {
+		return undefined;
+	}
+
+	const pokePreamble = readNullableString(
+		record,
+		"pokePreamble",
+		DEFAULT_LOOP_SETTINGS.pokePreamble,
+	);
+	if (pokePreamble === false) return undefined;
+
+	const inlineInvocation = readBoolean(
+		record,
+		"inlineInvocation",
+		DEFAULT_LOOP_SETTINGS.inlineInvocation,
+	);
+	if (typeof inlineInvocation !== "boolean") return undefined;
+
+	return {
+		maxIterations,
+		maxLoopDuration,
+		compaction: { enabled, threshold, postCompactContinuation, instructions },
+		pokePreamble,
+		inlineInvocation,
+	};
+}
+
+/** Returns the cap, or false when invalid. */
+function normalizeCap(value: unknown, fallback: number | null): number | null | false {
+	if (value === undefined) return fallback;
+	if (value === null) return null;
+	return typeof value === "number" && Number.isSafeInteger(value) && value > 0 ? value : false;
+}
+
+function readBoolean(record: Record<string, unknown>, key: string, fallback: boolean): unknown {
+	return Object.hasOwn(record, key) ? record[key] : fallback;
+}
+
+/** Returns the string, null, the fallback, or false when invalid. */
+function readNullableString(
+	record: Record<string, unknown>,
+	key: string,
+	fallback: string | null,
+): string | null | false {
+	if (!Object.hasOwn(record, key)) return fallback;
+	const value = record[key];
+	if (value === null) return null;
+	return typeof value === "string" && value.trim().length > 0 ? value : false;
+}
+
+export function loopSettingsPath(): string {
+	return join(getAgentDir(), LOOP_SETTINGS_FILE);
+}
+
+export function readLoopSettings(settingsPath = loopSettingsPath()): LoopSettingsLoadResult {
+	let contents: string;
+	try {
+		contents = readFileSync(settingsPath, "utf8");
+	} catch (error) {
+		if (isNodeError(error) && error.code === "ENOENT") {
+			return { kind: "missing", settings: structuredClone(DEFAULT_LOOP_SETTINGS) };
+		}
+		return {
+			kind: "invalid",
+			reason: `${settingsPath}: ${formatError(error)}`,
+			settings: structuredClone(DEFAULT_LOOP_SETTINGS),
+		};
+	}
+	try {
+		const settings = normalizeLoopSettings(JSON.parse(contents) as unknown);
+		return settings
+			? { kind: "loaded", settings }
+			: {
+					kind: "invalid",
+					reason: `${settingsPath}: invalid settings shape`,
+					settings: structuredClone(DEFAULT_LOOP_SETTINGS),
+				};
+	} catch (error) {
+		return {
+			kind: "invalid",
+			reason: `${settingsPath}: ${formatError(error)}`,
+			settings: structuredClone(DEFAULT_LOOP_SETTINGS),
+		};
+	}
+}
+
+export function saveLoopSettings(settings: LoopSettings, settingsPath = loopSettingsPath()): void {
+	const normalized = normalizeLoopSettings(settings);
+	if (!normalized) throw new Error("Refusing to save invalid pi-loop settings.");
+
+	let raw: Record<string, unknown> = {};
+	try {
+		const parsed = JSON.parse(readFileSync(settingsPath, "utf8")) as unknown;
+		if (!normalizeLoopSettings(parsed)) {
+			throw new Error(`${settingsPath}: invalid settings shape`);
+		}
+		raw = ownRecord(parsed) ?? {};
+	} catch (error) {
+		if (!isNodeError(error) || error.code !== "ENOENT") {
+			throw new Error(`Cannot save over invalid settings file: ${formatError(error)}`);
+		}
+	}
+
+	const compaction = ownRecord(raw.compaction) ?? {};
+	const document = `${JSON.stringify(
+		{
+			...raw,
+			maxIterations: normalized.maxIterations,
+			maxLoopDuration: normalized.maxLoopDuration,
+			compaction: { ...compaction, ...normalized.compaction },
+			pokePreamble: normalized.pokePreamble,
+			inlineInvocation: normalized.inlineInvocation,
+		},
+		null,
+		2,
+	)}\n`;
+	const temporaryPath = join(
+		dirname(settingsPath),
+		`.${basename(settingsPath)}.${randomUUID()}.tmp`,
+	);
+	try {
+		mkdirSync(dirname(settingsPath), { recursive: true });
+		writeFileSync(temporaryPath, document, { encoding: "utf8", flag: "wx" });
+		renameSync(temporaryPath, settingsPath);
+	} finally {
+		try {
+			rmSync(temporaryPath, { force: true });
+		} catch {
+			// Best-effort cleanup must not replace the save result.
+		}
+	}
+}
+
+function ownRecord(value: unknown): Record<string, unknown> | undefined {
+	return value && typeof value === "object" && !Array.isArray(value)
+		? (value as Record<string, unknown>)
+		: undefined;
+}
+
+function isNodeError(error: unknown): error is NodeJS.ErrnoException {
+	return error instanceof Error && "code" in error;
+}
+
+function formatError(error: unknown) {
+	return error instanceof Error ? error.message : String(error);
+}

package/src/state.ts

@@ -0,0 +1,169 @@
+/**
+ * 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.
+ */
+
+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";
+
+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. */
+	prompt?: 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;
+	/** Delivered pokes so far. */
+	iteration: number;
+	startedAt: number;
+	expiresAt: number;
+	lastWakeAt?: number;
+}
+
+const MAX_PROMPT_LENGTH = 100_000;
+const MAX_TIMESTAMP = 8_640_000_000_000_000;
+
+export function normalizeLoopState(value: unknown): LoopState | undefined {
+	const record = ownRecord(value);
+	if (!record) return undefined;
+	const id = typeof record.id === "string" ? record.id.trim() : "";
+	if (!id || id.length > 200 || /[\s:>]/.test(id)) return undefined;
+	const status = record.status;
+	if (!LOOP_STATUSES.includes(status as LoopStatus)) return undefined;
+	let prompt: string | undefined;
+	if (record.prompt !== undefined) {
+		if (typeof record.prompt !== "string") return undefined;
+		prompt = record.prompt.trim();
+		if (!prompt || prompt.length > MAX_PROMPT_LENGTH) return undefined;
+	}
+	const intervalMs = record.intervalMs;
+	if (!isPositiveSafeInteger(intervalMs)) return undefined;
+	const maxIterations = record.maxIterations;
+	if (maxIterations !== null && !isPositiveSafeInteger(maxIterations)) return undefined;
+	const compactAt = record.compactAt;
+	if (
+		compactAt !== null &&
+		(typeof compactAt !== "number" || !Number.isFinite(compactAt) || compactAt <= 0 || compactAt >= 1)
+	) {
+		return undefined;
+	}
+	const iteration = record.iteration;
+	if (typeof iteration !== "number" || !Number.isSafeInteger(iteration) || iteration < 0) {
+		return undefined;
+	}
+	if (!isTimestamp(record.startedAt) || !isTimestamp(record.expiresAt)) return undefined;
+	if (record.lastWakeAt !== undefined && !isTimestamp(record.lastWakeAt)) return undefined;
+	return {
+		id,
+		status: status as LoopStatus,
+		...(prompt === undefined ? {} : { prompt }),
+		intervalMs,
+		maxIterations: maxIterations as number | null,
+		compactAt: compactAt as number | null,
+		iteration,
+		startedAt: record.startedAt as number,
+		expiresAt: record.expiresAt as number,
+		...(record.lastWakeAt === undefined ? {} : { lastWakeAt: record.lastWakeAt as number }),
+	};
+}
+
+// --- session-branch entry readers ---
+
+interface SessionEntryLike {
+	type?: string;
+	customType?: string;
+	data?: unknown;
+}
+
+function lastCustomEntryData(entries: unknown[], customType: string): unknown {
+	for (let index = entries.length - 1; index >= 0; index -= 1) {
+		const entry = entries[index] as SessionEntryLike | undefined;
+		if (entry?.type === "custom" && entry.customType === customType) return entry.data;
+	}
+	return undefined;
+}
+
+/** Restore the persisted loop state from a session branch, fail-open. */
+export function restoreLoopState(entries: unknown[]): LoopState | undefined {
+	const data = lastCustomEntryData(entries, LOOP_STATE_ENTRY_TYPE);
+	const record = ownRecord(data);
+	if (!record) return undefined;
+	return normalizeLoopState(record.loop);
+}
+
+export const GOAL_SAFETY_STATUSES = ["paused", "blocked", "usage_limited", "budget_limited"] as const;
+
+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.
+ */
+export function readGoalSnapshot(entries: unknown[]): GoalSnapshot | undefined {
+	const data = ownRecord(lastCustomEntryData(entries, GOAL_STATE_ENTRY_TYPE));
+	if (!data) return undefined;
+	const goal = ownRecord(data.goal);
+	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));
+	return data?.enabled === true;
+}
+
+function ownRecord(value: unknown): Record<string, unknown> | undefined {
+	return value && typeof value === "object" && !Array.isArray(value)
+		? (value as Record<string, unknown>)
+		: undefined;
+}
+
+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
+	);
+}