pi-harness-runtime 0.10.11 → 0.10.12

package/packages/scheduler-adapter/src/cron.ts

@@ -0,0 +1,123 @@
+/**
+ * Cron Scheduler Adapter — RFC-0101 §6
+ *
+ * Writes crontab entries for scheduled tasks.
+ * Entries are managed via a marker block so unschedule() is clean.
+ */
+import { execSync } from "node:child_process";
+import { writeFileSync, unlinkSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { SchedulerAdapter } from "./interface.js";
+import type { ScheduledTask } from "./interface.js";
+
+export class CronAdapter implements SchedulerAdapter {
+	readonly name = "cron" as const;
+	private readonly runtimeBin: string;
+
+	constructor(options: { runtimeBin?: string } = {}) {
+		this.runtimeBin = options.runtimeBin ?? "/usr/local/bin/pi-harness-runtime";
+	}
+
+	async install(): Promise<void> {
+		// Idempotent — verify cron is available
+		try {
+			execSync("crontab -l >/dev/null 2>&1", { stdio: "pipe" });
+		} catch {
+			// No existing crontab — that's fine
+		}
+	}
+
+	async schedule(task: ScheduledTask): Promise<void> {
+		const cronExpr = this._toCronExpr(task);
+		const marker = `# PI-HARNESS-RUNTIME: ${task.id}`;
+		const line = `${cronExpr} ${this.runtimeBin} run-scheduled --task-id ${task.id}`;
+		const existing = this._getCrontab();
+
+		// Remove any existing entry for this task
+		const cleaned = existing.filter(
+			(l) => !l.includes(`PI-HARNESS-RUNTIME: ${task.id}`),
+		);
+		const updated = [...cleaned, marker, line].join("\n") + "\n";
+		this._setCrontab(updated);
+	}
+
+	async unschedule(taskId: string): Promise<void> {
+		const existing = this._getCrontab();
+		const cleaned = existing.filter(
+			(l) => !l.includes(`PI-HARNESS-RUNTIME: ${taskId}`),
+		);
+		if (cleaned.length === 0) {
+			try {
+				execSync("crontab -r 2>/dev/null", { stdio: "pipe" });
+			} catch {
+				// No crontab to remove — that's fine
+			}
+		} else {
+			this._setCrontab(cleaned.join("\n") + "\n");
+		}
+	}
+
+	async listScheduled(): Promise<ScheduledTask[]> {
+		const lines = this._getCrontab();
+		return lines
+			.filter((l) => l.includes("PI-HARNESS-RUNTIME: "))
+			.map((l) => {
+				const match = l.match(/PI-HARNESS-RUNTIME: ([\w-]+)/);
+				return {
+					id: match?.[1] ?? "unknown",
+					taskTemplate: {},
+					schedule: { kind: "cron" as const, expression: "" },
+					enabled: true,
+				} as unknown as ScheduledTask;
+			});
+	}
+
+	async healthCheck(): Promise<{ healthy: boolean; error?: string }> {
+		try {
+			execSync("crontab -l >/dev/null 2>&1", { stdio: "pipe" });
+			return { healthy: true };
+		} catch {
+			return { healthy: false, error: "crontab not accessible" };
+		}
+	}
+
+	private _getCrontab(): string[] {
+		try {
+			const out = execSync("crontab -l 2>/dev/null", { encoding: "utf8" });
+			return out.split("\n").filter((l) => l.trim());
+		} catch {
+			return [];
+		}
+	}
+
+	private _setCrontab(content: string): void {
+		const tmpFile = join(tmpdir(), `pi-harness-cron-${Date.now()}.tmp`);
+		try {
+			writeFileSync(tmpFile, content);
+			execSync(`crontab "${tmpFile}"`, { stdio: "pipe" });
+		} finally {
+			try {
+				unlinkSync(tmpFile);
+			} catch {
+				/* ignore */
+			}
+		}
+	}
+
+	private _toCronExpr(task: ScheduledTask): string {
+		if (task.schedule.kind === "cron") return task.schedule.expression;
+		if (task.schedule.kind === "interval") {
+			const ms = task.schedule.intervalMs;
+			const minutes = Math.round(ms / 60_000);
+			if (minutes < 60) return `*/${minutes} * * * *`;
+			const hours = Math.round(ms / 3_600_000);
+			return `${minutes % 60} */${hours} * * *`;
+		}
+		if (task.schedule.kind === "once") {
+			const d = new Date(task.schedule.at);
+			return `${d.getUTCMinutes()} ${d.getUTCHours()} ${d.getUTCDate()} ${d.getUTCMonth() + 1} *`;
+		}
+		return "* * * * *";
+	}
+}

package/packages/scheduler-adapter/src/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Scheduler Adapter Package — Barrel
+ * RFC-0101 §6
+ */
+
+export type { SchedulerAdapter, ScheduledTask } from "./interface.js";
+export { CronAdapter } from "./cron.js";
+export { SystemdAdapter } from "./systemd.js";
+export { InternalAdapter } from "./internal.js";

package/packages/scheduler-adapter/src/interface.ts

@@ -0,0 +1,61 @@
+/**
+ * Scheduler Adapter — Common Interface
+ * RFC-0101 §6
+ *
+ * All scheduler adapters implement this interface.
+ * The runtime selects an adapter at install time and uses it for all scheduled tasks.
+ */
+// ScheduledTask duplicated here to avoid cross-package import resolution issues
+// in the workspace. Replace with:
+//   import type { ScheduledTask } from "@pi/autonomous-runtime";
+export type ScheduledTask = {
+	id: string;
+	taskTemplate: Record<string, unknown>;
+	schedule:
+		| { kind: "cron"; expression: string }
+		| { kind: "interval"; intervalMs: number }
+		| { kind: "once"; at: string };
+	enabled: boolean;
+	lastFiredAt?: string;
+	nextFireAt?: string;
+};
+
+/**
+ * Supported scheduler adapter backends.
+ * Set at install time; can be changed via config.
+ */
+export type SchedulerAdapterKind = "systemd" | "cron" | "launchd" | "internal";
+
+export interface SchedulerAdapter {
+	/** Human-readable name. */
+	readonly name: SchedulerAdapterKind;
+
+	/**
+	 * Install the scheduler adapter.
+	 * Idempotent — re-running does not duplicate units.
+	 * @throws if installation fails (e.g. no systemd on this system)
+	 */
+	install(): Promise<void>;
+
+	/**
+	 * Schedule a task. Installs the timer/unit if not yet installed.
+	 * @param task The scheduled task to materialise
+	 */
+	schedule(task: ScheduledTask): Promise<void>;
+
+	/**
+	 * Remove a scheduled task.
+	 * @param taskId The id of the task to unschedule
+	 */
+	unschedule(taskId: string): Promise<void>;
+
+	/**
+	 * List all scheduled tasks currently installed by this adapter.
+	 */
+	listScheduled(): Promise<ScheduledTask[]>;
+
+	/**
+	 * Check if the adapter is healthy (e.g. systemd is running).
+	 */
+	healthCheck(): Promise<{ healthy: boolean; error?: string }>;
+}

package/packages/scheduler-adapter/src/internal.ts

@@ -0,0 +1,99 @@
+/**
+ * Scheduler Adapter — Internal (In-Process) Backend
+ * RFC-0101 §6
+ *
+ * Uses in-process setTimeout / setInterval for scheduling.
+ * Useful for testing, local development, and environments where
+ * systemd/cron are not available.
+ */
+
+import type { SchedulerAdapter, ScheduledTask } from "./interface.js";
+
+interface InternalTask {
+	task: ScheduledTask;
+	timerId: ReturnType<typeof setTimeout>;
+	createdAt: Date;
+}
+
+export class InternalAdapter implements SchedulerAdapter {
+	readonly name = "internal" as const;
+
+	private tasks = new Map<string, InternalTask>();
+	private handlers = new Map<string, (task: ScheduledTask) => unknown>();
+
+	async install(): Promise<void> {
+		// Nothing to install for in-process scheduling
+	}
+
+	async healthCheck(): Promise<{ healthy: boolean; error?: string }> {
+		return { healthy: true };
+	}
+
+	/**
+	 * Register a task handler before scheduling.
+	 * The adapter calls `handler(task)` when the task fires.
+	 */
+	setHandler(handler: (task: ScheduledTask) => unknown): void {
+		this.handlers.set("default", handler);
+	}
+
+	async schedule(task: ScheduledTask): Promise<void> {
+		if (this.tasks.has(task.id)) {
+			await this.unschedule(task.id);
+		}
+
+		const handler = this.handlers.get("default");
+		if (!handler) {
+			throw new Error(
+				"[InternalAdapter] No task handler registered. Call setHandler() first.",
+			);
+		}
+
+		if (!task.enabled) return; // skip disabled tasks
+
+		let delayMs: number;
+		if (task.schedule.kind === "once") {
+			delayMs = new Date(task.schedule.at).getTime() - Date.now();
+		} else if (task.schedule.kind === "interval") {
+			delayMs = task.schedule.intervalMs;
+		} else {
+			// cron — resolve to next occurrence (simplified: 1h from now)
+			delayMs = 3_600_000;
+		}
+
+		if (delayMs <= 0) delayMs = 1000;
+
+		const tick = (): void => {
+			const t = this.tasks.get(task.id);
+			if (!t) return;
+			handler(task);
+			// Re-schedule if interval
+			if (task.schedule.kind === "interval") {
+				t.timerId = setTimeout(tick, task.schedule.intervalMs);
+			}
+		};
+
+		const timerId = setTimeout(tick, delayMs);
+		this.tasks.set(task.id, { task, timerId, createdAt: new Date() });
+	}
+
+	async unschedule(taskId: string): Promise<void> {
+		const t = this.tasks.get(taskId);
+		if (t) {
+			clearTimeout(t.timerId);
+			this.tasks.delete(taskId);
+		}
+	}
+
+	async listScheduled(): Promise<ScheduledTask[]> {
+		return Array.from(this.tasks.values()).map((t) => t.task);
+	}
+
+	/** Fire a task immediately (useful for testing). */
+	fireNow(taskId: string): void {
+		const t = this.tasks.get(taskId);
+		if (!t) return;
+		const handler = this.handlers.get("default");
+		if (handler) handler(t.task);
+	}
+}

package/packages/scheduler-adapter/src/systemd.ts

@@ -0,0 +1,221 @@
+/**
+ * Scheduler Adapter — systemd Backend
+ * RFC-0101 §6
+ *
+ * Uses systemd user timers as the scheduling backend.
+ * Each scheduled task becomes a .timer + .service unit pair.
+ * Works on any Linux system with systemd (no root required for user units).
+ */
+
+import { execSync } from "node:child_process";
+import { existsSync, mkdirSync, writeFileSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import type { SchedulerAdapter, ScheduledTask } from "./interface.js";
+
+// ScheduledTask duplicated here — see interface.ts for details.
+
+/**
+ * Install systemd user units (runs `systemctl --user`).
+ * Must call this once before scheduling.
+ */
+export class SystemdAdapter implements SchedulerAdapter {
+	readonly name = "systemd" as const;
+	/** Per-task unit files live in ~/.config/systemd/user/ */
+	private readonly unitDir: string;
+	private installed = false;
+
+	constructor(unitDir?: string) {
+		this.unitDir = unitDir ?? join(homedir(), ".config", "systemd", "user");
+	}
+
+	async install(): Promise<void> {
+		// Verify systemd user mode is available
+		try {
+			execSync("systemctl --user show-environment >/dev/null 2>&1", {
+				stdio: "pipe",
+			});
+		} catch {
+			throw new Error(
+				"[SystemdAdapter] systemd user mode is not available. " +
+					"Ensure systemd is running and $SYSTEMD_RUNTIME_DIRECTORY is set.",
+			);
+		}
+
+		// Ensure unit directory exists
+		if (!existsSync(this.unitDir)) {
+			mkdirSync(this.unitDir, { recursive: true });
+		}
+
+		// Reload systemd to pick up new units
+		try {
+			execSync("systemctl --user daemon-reload", { stdio: "pipe" });
+		} catch {
+			throw new Error("[SystemdAdapter] Failed to reload systemd daemon");
+		}
+
+		this.installed = true;
+	}
+
+	async schedule(task: ScheduledTask): Promise<void> {
+		if (!this.installed) await this.install();
+
+		const id = task.id.replace(/[^a-zA-Z0-9_-]/g, "-");
+		const base = `pi-runtime-${id}`;
+		const servicePath = join(this.unitDir, `${base}.service`);
+		const timerPath = join(this.unitDir, `${base}.timer`);
+		const scriptPath = join(this.unitDir, `${base}.sh`);
+
+		// Build the run script
+		const runScript = [
+			"#!/usr/bin/env bash",
+			`# Generated by pi-harness-runtime — ${new Date().toISOString()}`,
+			"",
+			`PI_HARNESS_TASK_ID="${task.id}" \\`,
+			`PI_HARNESS_WORKER_ID="$(hostname)-$(id -u)" \\`,
+			`PI_HARNESS_RUNTIME_ROOT="${process.env.PI_HARNESS_RUNTIME_ROOT ?? join(homedir(), ".pi", "harness")}" \\`,
+			`exec "${process.env.PI_HARNESS_RUNTIME_ROOT}/bin/run-task.sh" \\`,
+			`  --task-id "${task.id}" \\`,
+			`  --worker-id "$PI_HARNESS_WORKER_ID"`,
+		].join("\n");
+
+		// Write script
+		writeFileSync(scriptPath, runScript, { mode: 0o755 });
+
+		// Service unit: runs the script
+		const service = [
+			"[Unit]",
+			"Description=pi-harness-runtime task: ${task.id}",
+			"[Service]",
+			`ExecStart=${scriptPath}`,
+			"Type=oneshot",
+			"Environment=SYSTEMD_EXEC_PID=$$",
+			"[Install]",
+			"WantedBy=default.target",
+		].join("\n");
+
+		// Timer unit: schedules the service
+		const timerContent = [
+			"[Unit]",
+			`Description=pi-harness-runtime schedule: ${task.id}`,
+			"[Timer]",
+			this._toTimerLine(task.schedule),
+			"Persistent=true",
+			"[Install]",
+			"WantedBy=timers.target",
+		].join("\n");
+
+		writeFileSync(servicePath, service);
+		writeFileSync(timerPath, timerContent);
+
+		// Reload and enable
+		try {
+			execSync("systemctl --user daemon-reload", { stdio: "pipe" });
+			execSync(`systemctl --user enable ${base}.timer`, { stdio: "pipe" });
+			execSync(`systemctl --user start ${base}.timer`, { stdio: "pipe" });
+		} catch (e) {
+			const err = e as { message?: string };
+			throw new Error(
+				`[SystemdAdapter] Failed to enable/start ${base}.timer: ${err?.message ?? String(e)}`,
+			);
+		}
+	}
+
+	async unschedule(taskId: string): Promise<void> {
+		const id = taskId.replace(/[^a-zA-Z0-9_-]/g, "-");
+		const base = `pi-runtime-${id}`;
+		const servicePath = join(this.unitDir, `${base}.service`);
+		const timerPath = join(this.unitDir, `${base}.timer`);
+		const scriptPath = join(this.unitDir, `${base}.sh`);
+
+		// Stop and disable
+		try {
+			execSync(`systemctl --user stop ${base}.timer`, { stdio: "pipe" });
+			execSync(`systemctl --user disable ${base}.timer`, { stdio: "pipe" });
+		} catch {
+			// Ignore if not running
+		}
+
+		// Remove files
+		for (const p of [servicePath, timerPath, scriptPath]) {
+			try {
+				if (existsSync(p)) unlinkSync(p);
+			} catch {
+				// Ignore cleanup errors
+			}
+		}
+
+		try {
+			execSync("systemctl --user daemon-reload", { stdio: "pipe" });
+		} catch {
+			// Ignore
+		}
+	}
+
+	async listScheduled(): Promise<ScheduledTask[]> {
+		try {
+			const out = execSync(
+				"systemctl --user list-timers --all --no-legend --output json 2>/dev/null | grep pi-runtime- || true",
+				{ encoding: "utf8" },
+			);
+
+			if (!out.trim()) return [];
+
+			let timers: Array<{ Unit?: string; Next?: string }> = [];
+			try {
+				timers = JSON.parse(out.trim());
+			} catch {
+				return [];
+			}
+
+			return timers
+				.filter((t) => t.Unit?.startsWith("pi-runtime-"))
+				.map((t) => {
+					const id = (t.Unit ?? "").replace(/^pi-runtime-(.+)\.timer$/, "$1");
+					return {
+						id,
+						taskTemplate: {},
+						schedule: { kind: "interval" as const, intervalMs: 0 },
+						enabled: true,
+					} satisfies ScheduledTask;
+				});
+		} catch {
+			return [];
+		}
+	}
+
+	/** Convert a schedule to a systemd.timer OnCalendar or OnUnitActiveSec line. */
+	private _toTimerLine(schedule: ScheduledTask["schedule"]): string {
+		if (schedule.kind === "cron") {
+			// Convert cron to systemd calendar format
+			const parts = schedule.expression.trim().split(/\s+/);
+			if (parts.length >= 5) {
+				const [min, hour, dom, month] = parts;
+				return `OnCalendar=${dom}.${month}.* ${hour}:${min.padStart(2, "0")}`;
+			}
+			return `OnCalendar=${schedule.expression}`;
+		}
+		if (schedule.kind === "interval") {
+			const sec = Math.round(schedule.intervalMs / 1000);
+			if (sec >= 86400) return `OnUnitActiveSec=${Math.round(sec / 86400)}d`;
+			if (sec >= 3600) return `OnUnitActiveSec=${Math.round(sec / 3600)}h`;
+			if (sec >= 60) return `OnUnitActiveSec=${Math.round(sec / 60)}min`;
+			return `OnUnitActiveSec=${sec}s`;
+		}
+		if (schedule.kind === "once") {
+			return `OnCalendar=${new Date(schedule.at).toISOString().split("T").join(" ")}`;
+		}
+		return "OnUnitActiveSec=1h"; // fallback
+	}
+
+	async healthCheck(): Promise<{ healthy: boolean; error?: string }> {
+		try {
+			execSync("systemctl --user show-environment >/dev/null 2>&1", {
+				stdio: "pipe",
+			});
+			return { healthy: true };
+		} catch {
+			return { healthy: false, error: "systemd user mode not available" };
+		}
+	}
+}