pi-harness-runtime 0.9.15 → 0.9.16

package/packages/autonomous-runtime/src/lease.ts

@@ -0,0 +1,318 @@
+/**
+ * Lease Manager — RFC-0101 §4
+ *
+ * Manages task leases on disk using atomic write-tmp-then-rename.
+ * This prevents double-execution when two workers claim the same task concurrently.
+ *
+ * Filesystem layout:
+ * ```
+ * ~/.pi/harness/inbox/
+ * ├── tasks.jsonl        # task records
+ * └── claimed/
+ *     └── <task-id>.lease.json   # one lease file per claimed task
+ * ```
+ *
+ * Safety properties:
+ * - Claiming is single-execution: POSIX rename is atomic, so only one writer wins.
+ * - A worker that dies: its lease expires, the reaper releases it back to queued.
+ * - On startup, recoverOrphanLeases() cleans up any stale leases.
+ */
+import {
+	closeSync,
+	existsSync,
+	mkdirSync,
+	openSync,
+	readFileSync,
+	readdirSync,
+	renameSync,
+	unlinkSync,
+	writeFileSync,
+	writeSync,
+} from "node:fs";
+import { join } from "node:path";
+import type { TaskLease } from "./types.js";
+import { getLeasesDir } from "./types.js";
+
+// ─── Errors ───────────────────────────────────────────────────────────────────
+
+export class LeaseError extends Error {
+	constructor(msg: string) {
+		super(`[LeaseError] ${msg}`);
+		this.name = "LeaseError";
+	}
+}
+
+// ─── Constants ────────────────────────────────────────────────────────────────
+
+/** Default lease duration before heartbeat extension is required. */
+export const DEFAULT_LEASE_TTL_MS = 30_000; // 30 s
+
+/** Heartbeat interval sent by the worker. */
+export const HEARTBEAT_INTERVAL_MS = 5_000; // 5 s
+
+/** Default worker heartbeat interval extension. */
+export const HEARTBEAT_EXTENSION_MS = 30_000; // extend by 30 s
+
+// ─── LeaseManager ─────────────────────────────────────────────────────────────
+
+export interface LeaseOptions {
+	leasesDir?: string;
+	/** TTL in ms for new leases. Default: DEFAULT_LEASE_TTL_MS */
+	leaseTtlMs?: number;
+}
+
+/**
+ * Manages task leases on disk using atomic write-tmp-then-rename.
+ */
+export class LeaseManager {
+	private readonly leasesDir: string;
+	private readonly leaseTtlMs: number;
+
+	constructor(options: LeaseOptions = {}) {
+		this.leasesDir = options.leasesDir ?? getLeasesDir();
+		this.leaseTtlMs = options.leaseTtlMs ?? DEFAULT_LEASE_TTL_MS;
+	}
+
+	/** Ensure the claimed/ directory exists. */
+	ensureDir(): void {
+		if (!existsSync(this.leasesDir)) {
+			mkdirSync(this.leasesDir, { recursive: true });
+		}
+	}
+
+	// ─── claim ───────────────────────────────────────────────────────────────
+
+	/**
+	 * Atomically claim a task for a worker.
+	 *
+	 * Algorithm:
+	 * 1. Write lease to a temp file in the same directory (same filesystem → fast rename)
+	 * 2. Attempt atomic rename to `claimed/<taskId>.lease.json`
+	 * 3. If rename fails (EEXIST) → another worker won → return null
+	 *
+	 * @param taskId    The task to claim
+	 * @param workerId  The worker claiming it
+	 * @param attempt   Which attempt number (for retry)
+	 * @returns The TaskLease if won, null if another worker claimed first
+	 */
+	claim(taskId: string, workerId: string, attempt = 1): TaskLease | null {
+		this.ensureDir();
+
+		const now = new Date().toISOString();
+		const expiresAt = new Date(Date.now() + this.leaseTtlMs).toISOString();
+		const lease: TaskLease = {
+			taskId,
+			workerId,
+			acquiredAt: now,
+			expiresAt,
+			heartbeatAt: now,
+			attempt,
+		};
+
+		const targetPath = this._leasePath(taskId);
+
+		// Use open() with O_CREAT | O_EXCL — this is atomic and fails immediately
+		// if another worker has already created the lease file. No tmp file needed.
+		let fd: number;
+		try {
+			fd = openSync(targetPath, "wx", 0o644); // mode 0644 = rw-r--r--
+		} catch (err: unknown) {
+			const code = (err as NodeJS.ErrnoException).code;
+			if (code === "EEXIST") {
+				return null; // another worker already claimed
+			}
+			throw err;
+		}
+
+		try {
+			writeSync(fd, JSON.stringify(lease) + "\n");
+			closeSync(fd);
+			return lease;
+		} catch (err: unknown) {
+			try {
+				closeSync(fd);
+			} catch {
+				/* ignore */
+			}
+			try {
+				unlinkSync(targetPath);
+			} catch {
+				/* ignore */
+			}
+			throw err;
+		}
+	}
+
+	// ─── heartbeat ────────────────────────────────────────────────────────────
+
+	/**
+	 * Extend a lease's expiry time.
+	 * Only the worker that holds the lease can extend it.
+	 *
+	 * @returns Updated lease, or null if the lease no longer exists
+	 */
+	heartbeat(taskId: string, workerId: string): TaskLease | null {
+		const lease = this.get(taskId);
+		if (!lease) return null;
+		if (lease.workerId !== workerId) {
+			throw new LeaseError(
+				`Worker ${workerId} cannot heartbeat lease for ${taskId}: held by ${lease.workerId}`,
+			);
+		}
+
+		const updated: TaskLease = {
+			...lease,
+			heartbeatAt: new Date().toISOString(),
+			expiresAt: new Date(Date.now() + this.leaseTtlMs).toISOString(),
+		};
+
+		this._writeLease(updated);
+		return updated;
+	}
+
+	// ─── release ─────────────────────────────────────────────────────────────
+
+	/**
+	 * Explicitly release a lease (task completed or failed without retry).
+	 */
+	release(taskId: string, workerId: string): void {
+		const lease = this.get(taskId);
+		if (!lease) return;
+		if (lease.workerId !== workerId) {
+			throw new LeaseError(
+				`Worker ${workerId} cannot release lease for ${taskId}: held by ${lease.workerId}`,
+			);
+		}
+		this._removeLease(taskId);
+	}
+
+	// ─── get ─────────────────────────────────────────────────────────────────
+
+	/** Read a lease by taskId. Returns null if not found. */
+	get(taskId: string): TaskLease | null {
+		const path = this._leasePath(taskId);
+		if (!existsSync(path)) return null;
+		try {
+			return JSON.parse(readFileSync(path, "utf8")) as TaskLease;
+		} catch {
+			return null;
+		}
+	}
+
+	// ─── isExpired ────────────────────────────────────────────────────────────
+
+	/** Check if a lease has expired (expiresAt is in the past). */
+	isExpired(lease: TaskLease): boolean {
+		return new Date(lease.expiresAt).getTime() < Date.now();
+	}
+
+	// ─── reap ────────────────────────────────────────────────────────────────
+
+	/**
+	 * Scan all leases and return the ones that have expired.
+	 * Does NOT remove them — call reapAndRelease() to remove atomically.
+	 */
+	reap(): TaskLease[] {
+		if (!existsSync(this.leasesDir)) return [];
+		const now = Date.now();
+		const expired: TaskLease[] = [];
+
+		for (const filename of readdirSync(this.leasesDir)) {
+			if (!filename.endsWith(".lease.json")) continue;
+			const path = join(this.leasesDir, filename);
+			try {
+				const lease = JSON.parse(readFileSync(path, "utf8")) as TaskLease;
+				if (new Date(lease.expiresAt).getTime() < now) {
+					expired.push(lease);
+				}
+			} catch {
+				// Corrupt file — remove it
+				try {
+					unlinkSync(path);
+				} catch {
+					/* ignore */
+				}
+			}
+		}
+
+		return expired;
+	}
+
+	/**
+	 * Release all expired leases and return their taskIds.
+	 * Idempotent — safe to call on every heartbeat interval.
+	 */
+	reapAndRelease(): string[] {
+		const expired = this.reap();
+		const released: string[] = [];
+		for (const lease of expired) {
+			try {
+				this._removeLease(lease.taskId);
+				released.push(lease.taskId);
+			} catch {
+				// Already removed — ignore
+			}
+		}
+		return released;
+	}
+
+	// ─── recoverOrphanLeases ─────────────────────────────────────────────────
+
+	/**
+	 * On worker startup, release any leases held by dead workers.
+	 * A lease is orphaned if its worker has not re-claimed it since startup.
+	 *
+	 * Strategy: remove all leases whose expiresAt has passed.
+	 * Safe because the next claim will succeed (no other worker holds it).
+	 */
+	recoverOnStartup(): string[] {
+		return this.reapAndRelease();
+	}
+
+	// ─── listActive ───────────────────────────────────────────────────────────
+
+	/** Return all active (non-expired) leases. */
+	listActive(): TaskLease[] {
+		if (!existsSync(this.leasesDir)) return [];
+		const now = Date.now();
+		const active: TaskLease[] = [];
+
+		for (const filename of readdirSync(this.leasesDir)) {
+			if (!filename.endsWith(".lease.json")) continue;
+			const path = join(this.leasesDir, filename);
+			try {
+				const lease = JSON.parse(readFileSync(path, "utf8")) as TaskLease;
+				if (new Date(lease.expiresAt).getTime() >= now) {
+					active.push(lease);
+				}
+			} catch {
+				// Corrupt — remove
+				try {
+					unlinkSync(path);
+				} catch {
+					/* ignore */
+				}
+			}
+		}
+
+		return active;
+	}
+
+	// ─── internals ───────────────────────────────────────────────────────────
+
+	private _leasePath(taskId: string): string {
+		return join(this.leasesDir, `${taskId}.lease.json`);
+	}
+
+	private _writeLease(lease: TaskLease): void {
+		this.ensureDir();
+		const tmp = `${this._leasePath(lease.taskId)}.tmp`;
+		writeFileSync(tmp, JSON.stringify(lease), "utf8");
+		renameSync(tmp, this._leasePath(lease.taskId));
+	}
+
+	private _removeLease(taskId: string): void {
+		const path = this._leasePath(taskId);
+		if (existsSync(path)) unlinkSync(path);
+	}
+}

package/packages/autonomous-runtime/src/types.ts

@@ -0,0 +1,257 @@
+/**
+ * Autonomous Operations Runtime — TypeScript Contracts
+ * Based on RFC-0101 §14
+ *
+ * Consumers: LoopRuntime, privilege-broker, scheduler-adapter, notification-runtime.
+ * These types are the canonical contracts. Do not re-define them in other packages.
+ */
+import { env } from "node:process";
+
+// ─── Capability model ──────────────────────────────────────────────────────────
+
+/** A named capability that the privilege broker may grant. */
+export type CapabilityName =
+	| "files.read"
+	| "files.write"
+	| "files.exec"
+	| "git.commit"
+	| "git.push"
+	| "git.pull"
+	| "system.restart"
+	| "system.restart-service"
+	| "system.logs"
+	| "bench.migrate"
+	| "bench.build"
+	| "bench.restart"
+	| "okf.promote-pattern"
+	| "okf.promote-lesson"
+	| "notify.send"
+	| "llm.invoke";
+
+/** What approval class a capability requires. */
+export type ApprovalClass =
+	| "automatic_read_only" // safe, no side effects
+	| "automatic_reversible" // side effects but trivially reversible
+	| "human_approval_required" // must ask operator
+	| "forbidden"; // never grant, regardless of override
+
+// ─── Task lifecycle ───────────────────────────────────────────────────────────
+
+export type TaskStatus =
+	| "queued"
+	| "claimed"
+	| "running"
+	| "waiting_approval"
+	| "waiting_quota"
+	| "retrying"
+	| "completed"
+	| "failed"
+	| "dead_letter";
+
+/** Immutable log of what happened to a task. */
+export type TaskEvent = {
+	ts: string; // ISO-8601
+	kind:
+		| "claimed"
+		| "started"
+		| "checkpointed"
+		| "progress"
+		| "blocked"
+		| "approval_requested"
+		| "approved"
+		| "denied"
+		| "failed"
+		| "completed"
+		| "recovered"
+		| "dead_lettered"
+		| "transitioned"; // generic status change
+	payload?: Record<string, unknown>;
+};
+
+// ─── Task record ─────────────────────────────────────────────────────────────
+
+/** The primary durable record for a task. */
+export interface TaskRecord {
+	id: string; // e.g. "task-2026-07-23-001"
+	objective: string; // natural-language goal
+	acceptanceCriteria: string[]; // verifiable outcomes
+	source:
+		| { kind: "chat"; userId: string }
+		| { kind: "schedule"; scheduleId: string }
+		| { kind: "webhook"; url: string }
+		| { kind: "subagent"; parentTaskId: string }
+		| { kind: "manual"; createdBy: string };
+	priority: 0 | 1 | 2 | 3 | 4; // P0..P4 (RFC-0015 convention)
+	capabilities: CapabilityName[]; // capabilities this task may need
+	approvalClass: ApprovalClass; // initial class (may escalate)
+	status: TaskStatus;
+	attempts: number;
+	maxAttempts: number; // default 3
+	context?: ExecutionContext; // planner-provided inputs
+	createdAt: string; // ISO-8601
+	updatedAt: string; // ISO-8601
+	leaseId?: string;
+	result?: TaskResult;
+	failureReason?: string;
+	history: TaskEvent[];
+}
+
+// ─── Leasing ──────────────────────────────────────────────────────────────────
+
+/** A lease held by a worker on a specific task. */
+export interface TaskLease {
+	taskId: string;
+	workerId: string;
+	acquiredAt: string; // ISO-8601
+	expiresAt: string; // ISO-8601
+	heartbeatAt: string; // ISO-8601
+	attempt: number; // which attempt this lease covers
+}
+
+// ─── Worker registry ──────────────────────────────────────────────────────────
+
+/** Heartbeat emitted by a worker every 5 s to worker-registry.json. */
+export interface WorkerHeartbeat {
+	workerId: string;
+	startedAt: string;
+	lastBeatAt: string;
+	capacity: number; // max concurrent tasks
+	inflightTaskIds: string[];
+}
+
+// ─── Privilege broker ─────────────────────────────────────────────────────────
+
+/** A resolved grant from the privilege broker. */
+export interface CapabilityGrant {
+	name: CapabilityName;
+	argv: string[]; // exact, no shell
+	envWhitelist?: string[]; // env vars that may be passed
+	user: string; // service account to run as
+	cwd?: string; // working directory
+	timeoutMs: number;
+}
+
+// ─── Approval ─────────────────────────────────────────────────────────────────
+
+/** An in-flight human approval request. */
+export interface ApprovalRequest {
+	id: string;
+	taskId: string;
+	capability: CapabilityName;
+	rationale: string; // human-readable description
+	signedBy?: { keyFingerprint: string; ts: string };
+	decision?: "approved" | "denied";
+	decidedAt?: string;
+	expiresAt: string; // ISO-8601 — timeout threshold
+}
+
+// ─── Scheduler ───────────────────────────────────────────────────────────────
+
+/** A scheduled recurring task. */
+export interface ScheduledTask {
+	id: string;
+	taskTemplate: Omit<
+		TaskRecord,
+		"id" | "status" | "attempts" | "createdAt" | "updatedAt" | "history"
+	>;
+	schedule: ScheduleSpec;
+	enabled: boolean;
+	lastFiredAt?: string;
+	nextFireAt?: string;
+}
+
+export type ScheduleSpec =
+	| { kind: "cron"; expression: string }
+	| { kind: "interval"; intervalMs: number }
+	| { kind: "once"; at: string };
+
+// ─── Notification ─────────────────────────────────────────────────────────────
+
+export type RuntimeNotificationEvent =
+	| "task.claimed"
+	| "task.started"
+	| "task.completed"
+	| "task.failed"
+	| "task.waiting_approval"
+	| "task.dead_lettered"
+	| "lease.expired"
+	| "worker.started"
+	| "worker.stopped"
+	| "approval.approved"
+	| "approval.denied"
+	| "approval.expired";
+
+export interface NotificationEvent {
+	kind: RuntimeNotificationEvent;
+	ts: string;
+	taskId?: string;
+	workerId?: string;
+	payload: Record<string, unknown>;
+}
+
+// ─── Checkpoint ───────────────────────────────────────────────────────────────
+
+export interface Checkpoint {
+	taskId: string;
+	attempt: number;
+	state: Record<string, unknown>;
+	savedAt: string; // ISO-8601
+}
+
+// ─── Execution context ────────────────────────────────────────────────────────
+
+/** The context given to the loop runtime when executing a task. */
+export interface ExecutionContext {
+	taskId: string;
+	workerId: string;
+	inputs: Record<string, unknown>;
+	capabilitiesGranted: CapabilityName[];
+	approvalClass: ApprovalClass;
+	lease: TaskLease;
+	checkpoint?: Checkpoint;
+	okfBundles: string[]; // content hashes available to planner
+}
+
+// ─── Task result ─────────────────────────────────────────────────────────────
+
+export interface TaskResult {
+	taskId: string;
+	status: "completed" | "failed" | "dead_letter";
+	deliverables?: { path: string; mime: string }[];
+	acceptanceCriteriaMet: {
+		criterion: string;
+		passed: boolean;
+		evidence?: string;
+	}[];
+	durationMs: number;
+	modelUsage?: { inputTokens: number; outputTokens: number; provider: string };
+}
+
+// ─── Storage paths ────────────────────────────────────────────────────────────
+
+const DEFAULT_ROOT = `${env["HOME"] ?? "."}/.pi/harness`;
+
+/** Returns the standard storage root for the runtime. */
+export function getRuntimeRoot(): string {
+	return env["PI_HARNESS_RUNTIME_ROOT"] ?? DEFAULT_ROOT;
+}
+
+/** Returns the inbox directory path. */
+export function getInboxDir(): string {
+	return `${getRuntimeRoot()}/inbox`;
+}
+
+/** Returns the claimed leases directory path. */
+export function getLeasesDir(): string {
+	return `${getInboxDir()}/claimed`;
+}
+
+/** Returns the task JSONL file path. */
+export function getTasksPath(): string {
+	return `${getInboxDir()}/tasks.jsonl`;
+}
+
+/** Returns the worker registry path. */
+export function getWorkerRegistryPath(): string {
+	return `${getRuntimeRoot()}/worker-registry.json`;
+}