@hank-warren/pi-loop 0.7.0 → 0.8.0

package/src/schedule/cron.ts

@@ -1,182 +0,0 @@
-/**
- * A five-field cron parser, minute granularity, stdlib only.
- *
- * Deliberately small and numeric: `minute hour day-of-month month
- * day-of-week`, each field `*`, a number, `a-b`, `a,b,c`, `*/n`, or
- * `a-b/n`. No names, no `@daily`, no seconds, no timezones beyond the host's
- * local time. Every one of those is a place where two implementations
- * disagree, and a scheduler whose semantics are debatable is worse than one
- * that refuses the expression.
- *
- * Day-of-month and day-of-week follow the traditional cron rule: when both
- * are restricted, a day matching *either* fires. That is genuinely surprising
- * behaviour, but it is what every crontab in the world means, and inventing a
- * more sensible rule here would be the bigger trap.
- */
-
-export interface CronSpec {
-	expression: string;
-	minutes: ReadonlySet<number>;
-	hours: ReadonlySet<number>;
-	daysOfMonth: ReadonlySet<number>;
-	months: ReadonlySet<number>;
-	daysOfWeek: ReadonlySet<number>;
-	/** Both day fields restricted: match either, per traditional cron. */
-	dayUnion: boolean;
-}
-
-interface FieldRange {
-	min: number;
-	max: number;
-}
-
-const FIELDS: ReadonlyArray<{ name: string; range: FieldRange }> = [
-	{ name: "minute", range: { min: 0, max: 59 } },
-	{ name: "hour", range: { min: 0, max: 23 } },
-	{ name: "day-of-month", range: { min: 1, max: 31 } },
-	{ name: "month", range: { min: 1, max: 12 } },
-	{ name: "day-of-week", range: { min: 0, max: 7 } },
-];
-
-export type CronParseResult =
-	| { ok: true; spec: CronSpec }
-	| { ok: false; error: string };
-
-export function parseCron(expression: string): CronParseResult {
-	const fields = expression.trim().split(/\s+/u);
-	if (fields.length !== 5) {
-		return {
-			ok: false,
-			error: `a cron expression has 5 fields (minute hour day-of-month month day-of-week), got ${fields.length}`,
-		};
-	}
-	const parsed: Array<Set<number>> = [];
-	for (let index = 0; index < FIELDS.length; index += 1) {
-		const field = FIELDS[index];
-		const text = fields[index];
-		if (!field || text === undefined) return { ok: false, error: "malformed cron expression" };
-		const values = parseField(text, field.range);
-		if (!values) return { ok: false, error: `invalid ${field.name} field: ${text}` };
-		parsed.push(values);
-	}
-	const [minutes, hours, daysOfMonth, months, rawDaysOfWeek] = parsed as [
-		Set<number>,
-		Set<number>,
-		Set<number>,
-		Set<number>,
-		Set<number>,
-	];
-	// 7 and 0 are both Sunday.
-	const daysOfWeek = new Set([...rawDaysOfWeek].map((day) => (day === 7 ? 0 : day)));
-	return {
-		ok: true,
-		spec: {
-			expression: fields.join(" "),
-			minutes,
-			hours,
-			daysOfMonth,
-			months,
-			daysOfWeek,
-			dayUnion: fields[2] !== "*" && fields[4] !== "*",
-		},
-	};
-}
-
-function parseField(text: string, range: FieldRange): Set<number> | undefined {
-	const values = new Set<number>();
-	for (const part of text.split(",")) {
-		const [spec, stepText] = part.split("/");
-		if (spec === undefined || spec === "") return undefined;
-		let step = 1;
-		if (stepText !== undefined) {
-			step = Number(stepText);
-			if (!Number.isSafeInteger(step) || step <= 0) return undefined;
-		}
-		let from: number;
-		let to: number;
-		if (spec === "*") {
-			from = range.min;
-			to = range.max;
-		} else if (spec.includes("-")) {
-			const [fromText, toText, ...rest] = spec.split("-");
-			if (rest.length > 0) return undefined;
-			from = Number(fromText);
-			to = Number(toText);
-		} else {
-			from = Number(spec);
-			to = from;
-		}
-		if (!Number.isSafeInteger(from) || !Number.isSafeInteger(to) || from > to) return undefined;
-		if (from < range.min || to > range.max) return undefined;
-		for (let value = from; value <= to; value += step) values.add(value);
-	}
-	return values.size > 0 ? values : undefined;
-}
-
-/** Whether a local-time date matches the spec, to the minute. */
-export function cronMatches(spec: CronSpec, date: Date): boolean {
-	if (!spec.minutes.has(date.getMinutes())) return false;
-	if (!spec.hours.has(date.getHours())) return false;
-	if (!spec.months.has(date.getMonth() + 1)) return false;
-	const domMatch = spec.daysOfMonth.has(date.getDate());
-	const dowMatch = spec.daysOfWeek.has(date.getDay());
-	return spec.dayUnion ? domMatch || dowMatch : domMatch && dowMatch;
-}
-
-/** How far ahead a next-fire search gives up, in days. */
-const SEARCH_LIMIT_DAYS = 5 * 366;
-
-/**
- * The next local-time minute at or after `after` that matches, or undefined
- * when the expression can never fire again (30 February and friends).
- *
- * Scans day by day and only walks minutes inside a matching day, so an
- * expression that fires once a year costs a few thousand cheap comparisons
- * rather than half a million.
- */
-export function nextCronFire(spec: CronSpec, after: number): number | undefined {
-	const cursor = new Date(after);
-	cursor.setSeconds(0, 0);
-	cursor.setMinutes(cursor.getMinutes() + 1);
-	for (let day = 0; day <= SEARCH_LIMIT_DAYS; day += 1) {
-		if (dayCouldMatch(spec, cursor)) {
-			const hit = firstMatchingMinuteOfDay(spec, cursor, day === 0);
-			if (hit !== undefined) return hit;
-		}
-		cursor.setDate(cursor.getDate() + 1);
-		cursor.setHours(0, 0, 0, 0);
-	}
-	return undefined;
-}
-
-function dayCouldMatch(spec: CronSpec, date: Date): boolean {
-	if (!spec.months.has(date.getMonth() + 1)) return false;
-	const domMatch = spec.daysOfMonth.has(date.getDate());
-	const dowMatch = spec.daysOfWeek.has(date.getDay());
-	return spec.dayUnion ? domMatch || dowMatch : domMatch && dowMatch;
-}
-
-function firstMatchingMinuteOfDay(
-	spec: CronSpec,
-	dayStart: Date,
-	respectCursorTime: boolean,
-): number | undefined {
-	const startHour = respectCursorTime ? dayStart.getHours() : 0;
-	const startMinute = respectCursorTime ? dayStart.getMinutes() : 0;
-	for (const hour of sorted(spec.hours)) {
-		if (hour < startHour) continue;
-		for (const minute of sorted(spec.minutes)) {
-			if (hour === startHour && minute < startMinute) continue;
-			const candidate = new Date(dayStart);
-			candidate.setHours(hour, minute, 0, 0);
-			// A DST jump can move the wall clock off the requested slot; the
-			// match check is authoritative.
-			if (cronMatches(spec, candidate)) return candidate.getTime();
-		}
-	}
-	return undefined;
-}
-
-function sorted(values: ReadonlySet<number>): number[] {
-	return [...values].sort((a, b) => a - b);
-}

package/src/schedule/manager.ts

@@ -1,129 +0,0 @@
-/**
- * The `/schedule` manager, in the same shape as the `/loop` manager: Pi's
- * native dialog primitives, and a plain notification in non-TUI modes so
- * every action is reachable without a menu.
- */
-
-import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
-import { describeSchedule, nextFireAt, type ScheduledTask } from "./model.js";
-import type { Scheduler } from "./runner.js";
-
-export async function showScheduleManager(
-	scheduler: Scheduler,
-	ctx: ExtensionCommandContext,
-): Promise<void> {
-	if (ctx.mode !== "tui") {
-		ctx.ui.notify(listTasks(scheduler).join("\n"), "info");
-		return;
-	}
-	for (;;) {
-		const tasks = scheduler.tasks();
-		if (tasks.length === 0) {
-			ctx.ui.notify(
-				'No scheduled tasks. Create one with /schedule every 30m <prompt>, /schedule at +2h <prompt>, or /schedule cron "0 9 * * 1" <prompt>.',
-				"info",
-			);
-			return;
-		}
-		const rows = tasks.map((task) => summarizeRow(task));
-		const choice = await ctx.ui.select("Scheduled tasks", rows);
-		if (choice === undefined) return;
-		const task = tasks[rows.indexOf(choice)];
-		if (!task) return;
-		if (!(await manageTask(scheduler, ctx, task))) return;
-	}
-}
-
-/** Returns false when the manager should close. */
-async function manageTask(
-	scheduler: Scheduler,
-	ctx: ExtensionCommandContext,
-	task: ScheduledTask,
-): Promise<boolean> {
-	const actions = [
-		"Details",
-		task.status === "paused" ? "Resume" : "Pause",
-		"Run now",
-		"Delete",
-		"Back",
-	];
-	const action = await ctx.ui.select(`${task.name} · ${task.status}`, actions);
-	if (action === undefined || action === "Back") return true;
-	switch (action) {
-		case "Details":
-			ctx.ui.notify(describeTask(task).join("\n"), "info");
-			return true;
-		case "Pause":
-			scheduler.update({ ...task, status: "paused" });
-			ctx.ui.notify(`Paused "${task.name}".`, "info");
-			return true;
-		case "Resume":
-			scheduler.update({ ...task, status: "active" });
-			ctx.ui.notify(`Resumed "${task.name}".`, "info");
-			return true;
-		case "Run now":
-			scheduler.fireNow(task);
-			ctx.ui.notify(`Running "${task.name}" now.`, "info");
-			return true;
-		case "Delete": {
-			const confirmed = await ctx.ui.confirm("Delete task?", `Delete "${task.name}"?`);
-			if (!confirmed) return true;
-			scheduler.remove(task.id);
-			ctx.ui.notify(`Deleted "${task.name}".`, "info");
-			return true;
-		}
-		default:
-			return true;
-	}
-}
-
-export function listTasks(scheduler: Scheduler): string[] {
-	const tasks = scheduler.tasks();
-	if (tasks.length === 0) {
-		return [
-			"No scheduled tasks.",
-			'Create one with /schedule every 30m <prompt>, /schedule at +2h <prompt>, or /schedule cron "0 9 * * 1" <prompt>.',
-		];
-	}
-	return tasks.map((task) => summarizeRow(task));
-}
-
-function summarizeRow(task: ScheduledTask): string {
-	const next = nextFireAt(task, Date.now());
-	// A finished or paused task has no "next" to report; saying "next done"
-	// reads as though something were still scheduled.
-	const when =
-		task.status !== "active"
-			? task.status
-			: next === undefined
-				? "never again"
-				: `next ${new Date(next).toLocaleString()}`;
-	const result = task.lastResult ? ` · last ${task.lastResult.ok ? "ok" : "failed"}` : "";
-	return `${task.id} · ${task.task.kind} · ${describeSchedule(task.schedule)} · ${when}${result} · ${task.name}`;
-}
-
-export function describeTask(task: ScheduledTask): string[] {
-	const next = nextFireAt(task, Date.now());
-	const lines = [
-		`Task: ${task.name}`,
-		`Id: ${task.id}`,
-		`Kind: ${task.task.kind === "run" ? "headless run" : "in-session prompt"}`,
-		`Schedule: ${describeSchedule(task.schedule)}`,
-		`Status: ${task.status}`,
-		`Runs: ${task.runs}${task.maxRuns === null ? " (unlimited)" : ` of ${task.maxRuns}`}`,
-		`Next fire: ${next === undefined ? "never again" : new Date(next).toLocaleString()}`,
-		`Expires: ${new Date(task.expiresAt).toLocaleString()}`,
-	];
-	if (task.task.kind === "run") {
-		lines.push(`Working directory: ${task.task.cwd}`, `Wake the session: ${task.task.wakeOn}`);
-	}
-	if (task.lastResult) {
-		lines.push(
-			`Last result: ${task.lastResult.ok ? "ok" : "failed"} at ${new Date(task.lastResult.at).toLocaleString()}${
-				task.lastResult.detail ? ` — ${task.lastResult.detail}` : ""
-			}`,
-		);
-	}
-	lines.push(`Prompt: ${task.task.prompt}`);
-	return lines;
-}

package/src/schedule/model.ts

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