pi-harness-runtime 0.10.7 → 0.10.11

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

@@ -1,318 +0,0 @@
-/**
- * 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

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