pi-harness-runtime 0.9.14 → 0.9.16

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`;
+}

package/packages/autonomous-runtime/test/autonomous-runtime.test.ts

@@ -0,0 +1,194 @@
+/**
+ * Tests for autonomous-runtime (RFC-0101 Phase 1)
+ *
+ * Covers: TaskRecord, TaskStatus, TaskLease, TaskInbox, LeaseManager
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from "bun:test";
+import { mkdtempSync, rmSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import type { TaskRecord, TaskLease } from "../src/types.js";
+import { TaskInbox, LeaseManager } from "../src/index.js";
+
+const TEST_DIR = mkdtempSync(join(tmpdir(), "pi-autonomous-"));
+const INBOX_DIR = join(TEST_DIR, "inbox");
+const LEASE_DIR = join(TEST_DIR, "leases");
+
+afterEach(() => {
+	try {
+		rmSync(TEST_DIR, { recursive: true, force: true });
+	} catch {
+		// ignore
+	}
+});
+
+describe("TaskRecord types", () => {
+	it("accepts valid task shape", () => {
+		const task: TaskRecord = {
+			id: "task-1",
+			status: "pending",
+			title: "Test task",
+			created_at: new Date().toISOString(),
+			updated_at: new Date().toISOString(),
+			attempts: 0,
+		};
+		expect(task.id).toBe("task-1");
+		expect(task.status).toBe("pending");
+	});
+});
+
+describe("LeaseManager", () => {
+	it("grants exclusive lease to first worker", async () => {
+		const mgr = new LeaseManager({ leases_dir: LEASE_DIR });
+		const lease = await mgr.acquire("task-1", "worker-1");
+		expect(lease).not.toBeNull();
+		expect(lease!.worker_id).toBe("worker-1");
+		expect(lease!.task_id).toBe("task-1");
+		expect(lease!.acquired_at).toBeTruthy();
+	});
+
+	it("denies lease to second worker", async () => {
+		const mgr = new LeaseManager({ leases_dir: LEASE_DIR });
+		await mgr.acquire("task-1", "worker-1");
+		const second = await mgr.acquire("task-1", "worker-2");
+		expect(second).toBeNull();
+	});
+
+	it("releases and allows re-acquisition", async () => {
+		const mgr = new LeaseManager({ leases_dir: LEASE_DIR });
+		await mgr.acquire("task-1", "worker-1");
+		await mgr.release("task-1", "worker-1");
+		const next = await mgr.acquire("task-1", "worker-2");
+		expect(next).not.toBeNull();
+		expect(next!.worker_id).toBe("worker-2");
+	});
+
+	it("only owner can release", async () => {
+		const mgr = new LeaseManager({ leases_dir: LEASE_DIR });
+		await mgr.acquire("task-1", "worker-1");
+		const released = await mgr.release("task-1", "worker-2");
+		expect(released).toBe(false);
+	});
+
+	it("renewLease extends expiry if owner", async () => {
+		const mgr = new LeaseManager({ leases_dir: LEASE_DIR });
+		await mgr.acquire("task-1", "worker-1");
+		const renewed = await mgr.renewLease("task-1", "worker-1");
+		expect(renewed).toBe(true);
+	});
+
+	it("renewLease fails for non-owner", async () => {
+		const mgr = new LeaseManager({ leases_dir: LEASE_DIR });
+		await mgr.acquire("task-1", "worker-1");
+		const renewed = await mgr.renewLease("task-1", "worker-2");
+		expect(renewed).toBe(false);
+	});
+
+	it("getLease returns current lease", async () => {
+		const mgr = new LeaseManager({ leases_dir: LEASE_DIR });
+		const lease = await mgr.acquire("task-1", "worker-1");
+		const found = await mgr.getLease("task-1");
+		expect(found).toEqual(lease);
+	});
+
+	it("expired lease allows re-acquisition", async () => {
+		const mgr = new LeaseManager({ leases_dir: LEASE_DIR, default_ttl_ms: 1 });
+		await mgr.acquire("task-1", "worker-1");
+		// Wait for expiry
+		await new Promise((r) => setTimeout(r, 10));
+		const next = await mgr.acquire("task-1", "worker-2");
+		expect(next).not.toBeNull();
+		expect(next!.worker_id).toBe("worker-2");
+	});
+});
+
+describe("TaskInbox", () => {
+	it("accepts and returns pending tasks", async () => {
+		const inbox = new TaskInbox({ inbox_dir: INBOX_DIR });
+		await inbox.submit({
+			title: "Do the thing",
+			description: "A test task",
+			capability: "read",
+		});
+		const tasks = await inbox.getPending();
+		expect(tasks.length).toBe(1);
+		expect(tasks[0].status).toBe("pending");
+	});
+
+	it("assigns sequential integer IDs", async () => {
+		const inbox = new TaskInbox({ inbox_dir: INBOX_DIR });
+		await inbox.submit({ title: "Task 1", capability: "read" });
+		await inbox.submit({ title: "Task 2", capability: "read" });
+		const tasks = await inbox.getPending();
+		expect(tasks.length).toBe(2);
+		expect(tasks[0].id).toMatch(/^\d+$/);
+		expect(tasks[1].id).toMatch(/^\d+$/);
+		expect(Number(tasks[0].id)).toBeLessThan(Number(tasks[1].id));
+	});
+
+	it("transitions pending → running → completed", async () => {
+		const inbox = new TaskInbox({ inbox_dir: INBOX_DIR });
+		await inbox.submit({ title: "Test", capability: "read" });
+
+		const task = (await inbox.getPending())[0];
+		const started = await inbox.start(task.id);
+		expect(started.status).toBe("running");
+
+		const completed = await inbox.complete(task.id, { success: true });
+		expect(completed.status).toBe("completed");
+	});
+
+	it("fails a running task", async () => {
+		const inbox = new TaskInbox({ inbox_dir: INBOX_DIR });
+		await inbox.submit({ title: "Fail task", capability: "read" });
+		const task = (await inbox.getPending())[0];
+		await inbox.start(task.id);
+		const failed = await inbox.fail(task.id, "Intentional test failure");
+		expect(failed.status).toBe("failed");
+		expect(failed.error).toBe("Intentional test failure");
+	});
+
+	it("retries a failed task if max_attempts not exceeded", async () => {
+		const inbox = new TaskInbox({
+			inbox_dir: INBOX_DIR,
+			options: { max_attempts: 2 },
+		});
+		await inbox.submit({ title: "Retry task", capability: "read" });
+		const task = (await inbox.getPending())[0];
+		await inbox.start(task.id);
+		await inbox.fail(task.id, "First attempt failed");
+		const retried = (await inbox.getPending()).find((t) => t.id === task.id);
+		expect(retried).not.toBeUndefined();
+		expect(retried!.attempts).toBe(1);
+	});
+
+	it("does not retry if max_attempts exceeded", async () => {
+		const inbox = new TaskInbox({
+			inbox_dir: INBOX_DIR,
+			options: { max_attempts: 1 },
+		});
+		await inbox.submit({ title: "No retry task", capability: "read" });
+		const task = (await inbox.getPending())[0];
+		await inbox.start(task.id);
+		await inbox.fail(task.id, "Final failure");
+		const retried = await inbox.getTask(task.id);
+		expect(retried?.status).toBe("failed");
+		expect(retried?.attempts).toBe(1);
+	});
+
+	it("getTask returns specific task by id", async () => {
+		const inbox = new TaskInbox({ inbox_dir: INBOX_DIR });
+		await inbox.submit({ title: "Specific task", capability: "read" });
+		const [task] = await inbox.getPending();
+		const found = await inbox.getTask(task.id);
+		expect(found?.id).toBe(task.id);
+	});
+
+	it("returns null for non-existent task", async () => {
+		const inbox = new TaskInbox({ inbox_dir: INBOX_DIR });
+		const found = await inbox.getTask("nonexistent");
+		expect(found).toBeNull();
+	});
+});