@hank-warren/pi-loop 0.4.0 → 0.5.0

package/src/schedule/model.ts

@@ -0,0 +1,237 @@
+/**
+ * The scheduled-task model: what a task is, when it next fires, and how it is
+ * normalized back off disk.
+ *
+ * Two task kinds, deliberately different in lifetime:
+ *
+ * - `prompt` injects a prompt into the owning session. It is **session
+ *   scoped** — it lives in memory and dies with the session, because a prompt
+ *   with no session to arrive in is not a task, it is a leak.
+ * - `run` spawns a headless `pi -p` in a working directory. It outlives the
+ *   session, so it is the only kind persisted, and the only kind that needs
+ *   the single-writer lease.
+ *
+ * Every task is bounded twice: `maxRuns` (default 25, `unlimited` is an
+ * explicit opt-in, mirroring the loop caps) and a hard 90-day expiry. A
+ * forgotten schedule that fires forever is the failure mode this whole family
+ * of features is prone to.
+ */
+
+import { type CronSpec, nextCronFire, parseCron } from "./cron.js";
+
+export const DEFAULT_MAX_RUNS = 25;
+export const TASK_LIFETIME_MS = 90 * 86_400_000;
+/** Interval floor, matching the loop's own 1-minute clamp. */
+export const MIN_INTERVAL_MS = 60_000;
+
+export type ScheduleSpec =
+	| { kind: "once"; at: number }
+	| { kind: "interval"; everyMs: number }
+	| { kind: "cron"; expression: string };
+
+export type WakeOn = "always" | "failure" | "success" | "never";
+export const WAKE_ON_VALUES: readonly WakeOn[] = ["always", "failure", "success", "never"];
+
+export type TaskSpec =
+	| { kind: "prompt"; prompt: string }
+	| { kind: "run"; prompt: string; cwd: string; wakeOn: WakeOn };
+
+export type TaskStatus = "active" | "paused" | "done";
+
+export interface ScheduledTask {
+	id: string;
+	name: string;
+	schedule: ScheduleSpec;
+	task: TaskSpec;
+	status: TaskStatus;
+	createdAt: number;
+	expiresAt: number;
+	/** null means unlimited, and must be asked for explicitly. */
+	maxRuns: number | null;
+	runs: number;
+	lastRunAt?: number;
+	lastResult?: { at: number; ok: boolean; detail?: string };
+}
+
+export function isPersistentTask(task: ScheduledTask): boolean {
+	return task.task.kind === "run";
+}
+
+/**
+ * The next fire at or after `after`, or undefined when the task will never
+ * fire again (expired, done, paused, a one-shot already past, or a cron
+ * expression with no future match).
+ *
+ * A missed one-shot still returns its own time, in the past: catching up is
+ * the caller's decision, and it is exactly one fire, never one per missed
+ * occurrence.
+ */
+export function nextFireAt(task: ScheduledTask, after: number): number | undefined {
+	if (task.status !== "active") return undefined;
+	if (after >= task.expiresAt) return undefined;
+	if (task.maxRuns !== null && task.runs >= task.maxRuns) return undefined;
+	const fire = computeNextFire(task, after);
+	if (fire === undefined || fire >= task.expiresAt) return undefined;
+	return fire;
+}
+
+function computeNextFire(task: ScheduledTask, after: number): number | undefined {
+	switch (task.schedule.kind) {
+		case "once":
+			// Still pending if it has never run, whether or not it is overdue.
+			return task.runs === 0 ? task.schedule.at : undefined;
+		case "interval": {
+			const base = task.lastRunAt ?? task.createdAt;
+			const elapsed = after - base;
+			if (elapsed < task.schedule.everyMs) return base + task.schedule.everyMs;
+			// Overdue by any number of intervals: one fire, now. Firing once per
+			// missed interval is how a laptop that slept for a weekend wakes up
+			// to two hundred queued turns.
+			return after;
+		}
+		case "cron": {
+			const parsed = parseCron(task.schedule.expression);
+			if (!parsed.ok) return undefined;
+			return nextCronFireForTask(parsed.spec, task, after);
+		}
+	}
+}
+
+function nextCronFireForTask(
+	spec: CronSpec,
+	task: ScheduledTask,
+	after: number,
+): number | undefined {
+	// A cron occurrence missed while nothing was running is coalesced the same
+	// way: the search starts from the last run, and anything already past
+	// collapses into a single fire at `after`.
+	const from = task.lastRunAt ?? task.createdAt;
+	const next = nextCronFire(spec, Math.max(from, task.createdAt) - 1);
+	if (next === undefined) return undefined;
+	return next <= after ? after : next;
+}
+
+export function describeSchedule(schedule: ScheduleSpec): string {
+	switch (schedule.kind) {
+		case "once":
+			return `once at ${new Date(schedule.at).toLocaleString()}`;
+		case "interval":
+			return `every ${formatMs(schedule.everyMs)}`;
+		case "cron":
+			return `cron ${schedule.expression}`;
+	}
+}
+
+function formatMs(ms: number): string {
+	for (const [unit, size] of [
+		["d", 86_400_000],
+		["h", 3_600_000],
+		["m", 60_000],
+	] as const) {
+		if (ms >= size && ms % size === 0) return `${ms / size}${unit}`;
+	}
+	return `${Math.round(ms / 1_000)}s`;
+}
+
+// --- normalization ---
+
+const MAX_TEXT = 100_000;
+const MAX_TIMESTAMP = 8_640_000_000_000_000;
+
+export function normalizeTask(value: unknown): ScheduledTask | undefined {
+	const record = asRecord(value);
+	if (!record) return undefined;
+	const id = text(record.id, 200);
+	const name = text(record.name, 200);
+	if (!id || !name || /[\s/]/.test(id)) return undefined;
+	const schedule = normalizeSchedule(record.schedule);
+	const task = normalizeTaskSpec(record.task);
+	if (!schedule || !task) return undefined;
+	const status = record.status;
+	if (status !== "active" && status !== "paused" && status !== "done") return undefined;
+	if (!isTimestamp(record.createdAt) || !isTimestamp(record.expiresAt)) return undefined;
+	const maxRuns = record.maxRuns;
+	if (maxRuns !== null && !isPositiveInteger(maxRuns)) return undefined;
+	const runs = record.runs;
+	if (typeof runs !== "number" || !Number.isSafeInteger(runs) || runs < 0) return undefined;
+	if (record.lastRunAt !== undefined && !isTimestamp(record.lastRunAt)) return undefined;
+	const lastResult = normalizeResult(record.lastResult);
+	if (lastResult === false) return undefined;
+	return {
+		id,
+		name,
+		schedule,
+		task,
+		status,
+		createdAt: record.createdAt as number,
+		expiresAt: record.expiresAt as number,
+		maxRuns: maxRuns as number | null,
+		runs,
+		...(record.lastRunAt === undefined ? {} : { lastRunAt: record.lastRunAt as number }),
+		...(lastResult === undefined ? {} : { lastResult }),
+	};
+}
+
+function normalizeSchedule(value: unknown): ScheduleSpec | undefined {
+	const record = asRecord(value);
+	if (!record) return undefined;
+	if (record.kind === "once") {
+		return isTimestamp(record.at) ? { kind: "once", at: record.at as number } : undefined;
+	}
+	if (record.kind === "interval") {
+		const everyMs = record.everyMs;
+		return isPositiveInteger(everyMs) && everyMs >= MIN_INTERVAL_MS
+			? { kind: "interval", everyMs }
+			: undefined;
+	}
+	if (record.kind === "cron") {
+		const expression = text(record.expression, 200);
+		if (!expression || !parseCron(expression).ok) return undefined;
+		return { kind: "cron", expression };
+	}
+	return undefined;
+}
+
+function normalizeTaskSpec(value: unknown): TaskSpec | undefined {
+	const record = asRecord(value);
+	if (!record) return undefined;
+	const prompt = text(record.prompt, MAX_TEXT);
+	if (!prompt) return undefined;
+	if (record.kind === "prompt") return { kind: "prompt", prompt };
+	if (record.kind !== "run") return undefined;
+	const cwd = text(record.cwd, 4_096);
+	const wakeOn = record.wakeOn;
+	if (!cwd || !WAKE_ON_VALUES.includes(wakeOn as WakeOn)) return undefined;
+	return { kind: "run", prompt, cwd, wakeOn: wakeOn as WakeOn };
+}
+
+function normalizeResult(value: unknown): ScheduledTask["lastResult"] | undefined | false {
+	if (value === undefined) return undefined;
+	const record = asRecord(value);
+	if (!record || !isTimestamp(record.at) || typeof record.ok !== "boolean") return false;
+	const detail = record.detail === undefined ? undefined : text(record.detail, 4_000);
+	if (record.detail !== undefined && !detail) return false;
+	return { at: record.at as number, ok: record.ok, ...(detail ? { detail } : {}) };
+}
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+	return value && typeof value === "object" && !Array.isArray(value)
+		? (value as Record<string, unknown>)
+		: undefined;
+}
+
+function text(value: unknown, max: number): string | undefined {
+	if (typeof value !== "string") return undefined;
+	const trimmed = value.trim();
+	return trimmed && trimmed.length <= max ? trimmed : undefined;
+}
+
+function isPositiveInteger(value: unknown): value is number {
+	return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
+}
+
+function isTimestamp(value: unknown): value is number {
+	return (
+		typeof value === "number" && Number.isSafeInteger(value) && value >= 0 && value <= MAX_TIMESTAMP
+	);
+}

package/src/schedule/runner.ts

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