@hank-warren/pi-loop 0.7.0 → 0.8.0

package/src/schedule/runner.ts

@@ -1,351 +0,0 @@
-/**
- * The scheduler runtime: one timer, two delivery paths.
- *
- * A `prompt` task is delivered exactly like a loop wake — only at a settled
- * idle boundary, coalescing when the session is busy, because a scheduler
- * that interrupts a running turn is a worse tool than no scheduler. A `run`
- * task spawns a headless `pi -p` and never touches the conversation unless
- * its `wakeOn` policy says to report back.
- *
- * The model gets no scheduling tools at all. `/schedule` is user-typed, the
- * same doctrine `/loop` follows: a model that can schedule its own future
- * turns can schedule its way around every limit the loop imposes.
- */
-
-import { spawn } from "node:child_process";
-import { createWriteStream, mkdirSync } from "node:fs";
-import { randomUUID } from "node:crypto";
-import { dirname } from "node:path";
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import {
-	DEFAULT_MAX_RUNS,
-	isPersistentTask,
-	nextFireAt,
-	type ScheduledTask,
-	TASK_LIFETIME_MS,
-	type ScheduleSpec,
-	type TaskSpec,
-} from "./model.js";
-import {
-	acquireLease,
-	LEASE_HEARTBEAT_MS,
-	readTasks,
-	releaseLease,
-	runLogPath,
-	schedulePaths,
-	type SchedulePaths,
-	writeTasks,
-} from "./store.js";
-
-/** Longest a single headless run may take before it is killed. */
-export const RUN_TIMEOUT_MS = 30 * 60_000;
-const MAX_TIMER_MS = 2_147_483_647;
-
-export interface SchedulerOptions {
-	agentDir?: string;
-	now?: () => number;
-	/** Injected for tests; defaults to spawning a real headless Pi. */
-	spawnRun?: (task: ScheduledTask, logPath: string) => Promise<{ ok: boolean; detail: string }>;
-}
-
-export interface CreateTaskInput {
-	name: string;
-	schedule: ScheduleSpec;
-	task: TaskSpec;
-	maxRuns?: number | null;
-}
-
-export class Scheduler {
-	private readonly pi: ExtensionAPI;
-	private readonly now: () => number;
-	private readonly paths: SchedulePaths;
-	private readonly owner = randomUUID();
-	private readonly spawnRun: NonNullable<SchedulerOptions["spawnRun"]>;
-	/** Session-scoped prompt tasks; they die with the session by design. */
-	private sessionTasks: ScheduledTask[] = [];
-	private timer: NodeJS.Timeout | undefined;
-	private leaseTimer: NodeJS.Timeout | undefined;
-	private ctx: ExtensionContext | undefined;
-	private pendingPrompts: string[] = [];
-	private started = false;
-
-	constructor(pi: ExtensionAPI, options: SchedulerOptions = {}) {
-		this.pi = pi;
-		this.now = options.now ?? Date.now;
-		this.paths = schedulePaths(options.agentDir);
-		this.spawnRun = options.spawnRun ?? spawnHeadlessRun;
-	}
-
-	// --- lifecycle ---
-
-	onSessionStart(ctx: ExtensionContext): void {
-		this.ctx = ctx;
-		this.sessionTasks = [];
-		this.pendingPrompts = [];
-		this.started = true;
-		this.renewLease();
-		this.reschedule();
-	}
-
-	onSessionShutdown(): void {
-		this.started = false;
-		this.clearTimers();
-		releaseLease(this.paths, this.owner);
-		this.ctx = undefined;
-		// Prompt tasks are session scoped: a prompt with no session to arrive
-		// in is not a task, it is a leak.
-		this.sessionTasks = [];
-	}
-
-	/** Deliver anything that came due while the session was busy. */
-	onAgentSettled(ctx: ExtensionContext): void {
-		this.ctx = ctx;
-		this.flushPrompts(ctx);
-		this.reschedule();
-	}
-
-	// --- task management ---
-
-	tasks(): ScheduledTask[] {
-		return [...this.sessionTasks, ...readTasks(this.paths)].sort(
-			(a, b) => (nextFireAt(a, this.now()) ?? Infinity) - (nextFireAt(b, this.now()) ?? Infinity),
-		);
-	}
-
-	find(idPrefix: string): ScheduledTask | undefined {
-		const matches = this.tasks().filter((task) => task.id.startsWith(idPrefix));
-		return matches.length === 1 ? matches[0] : undefined;
-	}
-
-	create(input: CreateTaskInput): { task: ScheduledTask; warning?: string } {
-		const now = this.now();
-		const task: ScheduledTask = {
-			id: randomUUID().slice(0, 8),
-			name: input.name,
-			schedule: input.schedule,
-			task: input.task,
-			status: "active",
-			createdAt: now,
-			expiresAt: now + TASK_LIFETIME_MS,
-			maxRuns: input.maxRuns === undefined ? DEFAULT_MAX_RUNS : input.maxRuns,
-			runs: 0,
-		};
-		const warning = this.save(task);
-		this.reschedule();
-		return { task, ...(warning ? { warning } : {}) };
-	}
-
-	update(task: ScheduledTask): string | undefined {
-		const warning = this.save(task);
-		this.reschedule();
-		return warning;
-	}
-
-	remove(id: string): boolean {
-		const before = this.sessionTasks.length;
-		this.sessionTasks = this.sessionTasks.filter((task) => task.id !== id);
-		if (this.sessionTasks.length !== before) {
-			this.reschedule();
-			return true;
-		}
-		const persisted = readTasks(this.paths);
-		const kept = persisted.filter((task) => task.id !== id);
-		if (kept.length === persisted.length) return false;
-		writeTasks(this.paths, kept);
-		this.reschedule();
-		return true;
-	}
-
-	private save(task: ScheduledTask): string | undefined {
-		if (!isPersistentTask(task)) {
-			this.sessionTasks = [...this.sessionTasks.filter((other) => other.id !== task.id), task];
-			return undefined;
-		}
-		const persisted = readTasks(this.paths).filter((other) => other.id !== task.id);
-		return writeTasks(this.paths, [...persisted, task]);
-	}
-
-	// --- firing ---
-
-	/** Fire everything due now. Exposed for the manager's "run now". */
-	runDue(): void {
-		if (!this.started) return;
-		const now = this.now();
-		const headlessAllowed = this.renewLease();
-		for (const task of this.tasks()) {
-			const fire = nextFireAt(task, now);
-			if (fire === undefined || fire > now) continue;
-			if (task.task.kind === "run" && !headlessAllowed) continue;
-			this.fire(task, now);
-		}
-		this.reschedule();
-	}
-
-	fireNow(task: ScheduledTask): void {
-		this.fire(task, this.now());
-		this.reschedule();
-	}
-
-	private fire(task: ScheduledTask, now: number): void {
-		// Count the run before doing it: a task that throws must not become a
-		// hot loop, and a one-shot must not fire twice.
-		const ran: ScheduledTask = { ...task, runs: task.runs + 1, lastRunAt: now };
-		const finished =
-			ran.schedule.kind === "once" || (ran.maxRuns !== null && ran.runs >= ran.maxRuns);
-		this.save(finished ? { ...ran, status: "done" } : ran);
-		if (task.task.kind === "prompt") {
-			this.deliverPrompt(task);
-			return;
-		}
-		void this.startRun(ran);
-	}
-
-	private deliverPrompt(task: ScheduledTask): void {
-		if (task.task.kind !== "prompt") return;
-		const message = `Scheduled task "${task.name}" fired.\n\n${task.task.prompt}`;
-		this.pendingPrompts.push(message);
-		const ctx = this.ctx;
-		if (ctx) this.flushPrompts(ctx);
-	}
-
-	/**
-	 * Prompts deliver only at a fully idle boundary, and a queue that built up
-	 * while the session was busy delivers in order once it settles.
-	 */
-	private flushPrompts(ctx: ExtensionContext): void {
-		if (this.pendingPrompts.length === 0) return;
-		if (!ctx.isIdle() || ctx.hasPendingMessages()) return;
-		const queued = this.pendingPrompts;
-		this.pendingPrompts = [];
-		for (const message of queued) {
-			try {
-				this.pi.sendUserMessage(message);
-			} catch {
-				// Re-queue the rest for the next settle rather than dropping them.
-				this.pendingPrompts.push(message);
-			}
-		}
-	}
-
-	private async startRun(task: ScheduledTask): Promise<void> {
-		if (task.task.kind !== "run") return;
-		const at = this.now();
-		const logPath = runLogPath(this.paths, task.id, at);
-		let result: { ok: boolean; detail: string };
-		try {
-			result = await this.spawnRun(task, logPath);
-		} catch (error) {
-			result = { ok: false, detail: error instanceof Error ? error.message : String(error) };
-		}
-		const current = this.find(task.id) ?? task;
-		this.save({
-			...current,
-			lastResult: { at: this.now(), ok: result.ok, detail: `${result.detail} (log: ${logPath})` },
-		});
-		this.reportRun(task, result, logPath);
-	}
-
-	private reportRun(
-		task: ScheduledTask,
-		result: { ok: boolean; detail: string },
-		logPath: string,
-	): void {
-		if (task.task.kind !== "run") return;
-		const wakeOn = task.task.wakeOn;
-		const wanted =
-			wakeOn === "always" ||
-			(wakeOn === "failure" && !result.ok) ||
-			(wakeOn === "success" && result.ok);
-		if (!wanted) return;
-		const ctx = this.ctx;
-		if (!ctx) return;
-		ctx.ui.notify(
-			`Scheduled run "${task.name}" ${result.ok ? "succeeded" : "failed"}: ${result.detail}\nLog: ${logPath}`,
-			result.ok ? "info" : "warning",
-		);
-	}
-
-	// --- timers ---
-
-	private reschedule(): void {
-		this.clearFireTimer();
-		if (!this.started) return;
-		const now = this.now();
-		let earliest: number | undefined;
-		for (const task of this.tasks()) {
-			const fire = nextFireAt(task, now);
-			if (fire === undefined) continue;
-			if (earliest === undefined || fire < earliest) earliest = fire;
-		}
-		if (earliest === undefined) return;
-		const delay = Math.max(0, Math.min(MAX_TIMER_MS, earliest - now));
-		this.timer = setTimeout(() => {
-			this.timer = undefined;
-			this.runDue();
-		}, delay);
-		this.timer.unref?.();
-	}
-
-	/**
-	 * Hold the headless-firing lease. Returns whether this process holds it;
-	 * prompt tasks never consult it, since they are session-scoped and cannot
-	 * be double-fired by another process.
-	 */
-	private renewLease(): boolean {
-		const held = acquireLease(this.paths, this.owner, this.now());
-		if (!this.leaseTimer && this.started) {
-			this.leaseTimer = setInterval(() => {
-				acquireLease(this.paths, this.owner, this.now());
-			}, LEASE_HEARTBEAT_MS);
-			this.leaseTimer.unref?.();
-		}
-		return held;
-	}
-
-	private clearFireTimer(): void {
-		if (this.timer) clearTimeout(this.timer);
-		this.timer = undefined;
-	}
-
-	private clearTimers(): void {
-		this.clearFireTimer();
-		if (this.leaseTimer) clearInterval(this.leaseTimer);
-		this.leaseTimer = undefined;
-	}
-}
-
-/**
- * The default headless runner: `pi -p "<prompt>"` in the task's directory,
- * with stdout and stderr tee'd to the run log.
- */
-async function spawnHeadlessRun(
-	task: ScheduledTask,
-	logPath: string,
-): Promise<{ ok: boolean; detail: string }> {
-	if (task.task.kind !== "run") return { ok: false, detail: "not a run task" };
-	const { prompt, cwd } = task.task;
-	mkdirSync(dirname(logPath), { recursive: true });
-	const log = createWriteStream(logPath, { flags: "a" });
-	log.write(`# ${new Date().toISOString()} ${task.name}\n# cwd: ${cwd}\n# prompt: ${prompt}\n\n`);
-	return await new Promise((resolve) => {
-		const child = spawn("pi", ["-p", prompt], { cwd, stdio: ["ignore", "pipe", "pipe"] });
-		const timeout = setTimeout(() => child.kill("SIGTERM"), RUN_TIMEOUT_MS);
-		timeout.unref?.();
-		child.stdout?.pipe(log, { end: false });
-		child.stderr?.pipe(log, { end: false });
-		child.on("error", (error) => {
-			clearTimeout(timeout);
-			log.end(`\n# spawn failed: ${error.message}\n`);
-			resolve({ ok: false, detail: `could not start pi: ${error.message}` });
-		});
-		child.on("close", (code, signal) => {
-			clearTimeout(timeout);
-			log.end(`\n# exit ${code ?? "null"}${signal ? ` (${signal})` : ""}\n`);
-			resolve(
-				signal
-					? { ok: false, detail: `killed by ${signal}` }
-					: { ok: code === 0, detail: `exit ${code ?? "unknown"}` },
-			);
-		});
-	});
-}

package/src/schedule/store.ts

@@ -1,183 +0,0 @@
-/**
- * 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`);
-}