pi-harness-runtime 0.9.15 → 0.9.16

package/packages/autonomous-runtime/dist/worker.js

@@ -0,0 +1,133 @@
+/**
+ * Worker Stub — RFC-0101 §4
+ *
+ * A worker is a pi session that owns tasks from the inbox.
+ * This is the lightweight worker-side of the lease protocol.
+ *
+ * The worker picks up work via the inbox's `claim()` method
+ * and reports results via `complete()`.
+ */
+/**
+ * Worker — picks up tasks from the inbox and processes them.
+ *
+ * Lifecycle:
+ * 1. Construct with inbox + workerId
+ * 2. `start()` — begins polling/claiming tasks
+ * 3. `stop()` — stops claiming, expires held leases
+ *
+ * The worker does NOT run tasks itself — it delegates to the harness
+ * loop runtime. It just manages the lease lifecycle.
+ */
+export class Worker {
+    config;
+    events = {};
+    running = false;
+    heartbeatTimer = null;
+    constructor(config) {
+        this.config = {
+            heartbeatIntervalMs: 30_000,
+            ...config,
+        };
+    }
+    on(event, handler) {
+        this.events[event] = handler;
+    }
+    /**
+     * Start the worker — begins polling for available tasks.
+     */
+    async start() {
+        if (this.running)
+            return;
+        this.running = true;
+        // Start heartbeat
+        this.heartbeatTimer = setInterval(() => this._heartbeat(), this.config.heartbeatIntervalMs);
+        // Claim any immediately available tasks
+        await this._poll();
+    }
+    /**
+     * Stop the worker — stops polling and expires any held leases.
+     */
+    async stop() {
+        if (!this.running)
+            return;
+        this.running = false;
+        if (this.heartbeatTimer) {
+            clearInterval(this.heartbeatTimer);
+            this.heartbeatTimer = null;
+        }
+        // Expire all leases held by this worker
+        // (inbox.expireLease is idempotent — safe to call repeatedly)
+    }
+    /**
+     * Status of this worker.
+     */
+    status() {
+        return {
+            workerId: this.config.workerId,
+            running: this.running,
+            heartbeatIntervalMs: this.config.heartbeatIntervalMs ?? 30_000,
+        };
+    }
+    async _poll() {
+        if (!this.running)
+            return;
+        try {
+            // Try to claim one task
+            const lease = await this.config.inbox.claim({
+                workerId: this.config.workerId,
+                heartbeatIntervalMs: this.config.heartbeatIntervalMs ?? 30_000,
+            });
+            if (lease) {
+                this.events.onLease?.(lease);
+                await this._processTask(lease);
+            }
+        }
+        catch (err) {
+            this.config.onError?.("__poll__", err);
+        }
+    }
+    async _processTask(lease) {
+        const task = lease.task;
+        try {
+            // Delegate to harness loop runtime (stub — will be wired in Phase 2)
+            const result = await this._runTask(task);
+            // Report completion
+            await this.config.inbox.complete(lease.taskId, result);
+            this.events.onComplete?.(lease.taskId, result);
+        }
+        catch (err) {
+            this.events.onError?.(lease.taskId, err);
+            await this.config.inbox.complete(lease.taskId, {
+                ok: false,
+                error: String(err),
+                completedAt: new Date().toISOString(),
+            });
+        }
+        // Continue polling for more work
+        if (this.running)
+            void this._poll();
+    }
+    /**
+     * Run a single task. Stub — replaces with actual harness loop integration.
+     */
+    async _runTask(task) {
+        // TODO(Phase 2): Wire to harness loop runtime
+        // For now, return a stub result so the lease protocol works end-to-end.
+        return {
+            ok: true,
+            summary: `[stub] Processed ${task.id}`,
+            completedAt: new Date().toISOString(),
+        };
+    }
+    async _heartbeat() {
+        // Refresh leases held by this worker
+        // The inbox tracks which leases this worker holds and refreshes them.
+        try {
+            await this.config.inbox.refreshLeases(this.config.workerId);
+        }
+        catch {
+            // Non-fatal — lease will expire naturally
+        }
+    }
+}
+//# sourceMappingURL=worker.js.map

package/packages/autonomous-runtime/dist/worker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker.js","sourceRoot":"","sources":["../src/worker.ts"],"names":[],"mappings":"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"}

package/packages/autonomous-runtime/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@pi/autonomous-runtime",
+  "version": "0.9.15",
+  "description": "Autonomous Operations Runtime — task inbox, lease management, and worker lifecycle (RFC-0101)",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "bun test",
+    "test:watch": "bun test --watch",
+    "clean": "rm -rf dist"
+  },
+  "keywords": [
+    "autonomous",
+    "runtime",
+    "task-queue",
+    "lease",
+    "worker",
+    "rfc-0101"
+  ],
+  "author": "",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "typescript": "^7.0.2"
+  }
+}

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

@@ -0,0 +1,266 @@
+/**
+ * Task Inbox — RFC-0101 §2
+ *
+ * Append-only durable store for TaskRecords backed by `tasks.jsonl`.
+ * One JSONL line per task — easy to tail, grep, and replay.
+ */
+import {
+	appendFileSync,
+	existsSync,
+	mkdirSync,
+	readFileSync,
+	writeFileSync,
+} from "node:fs";
+import { dirname } from "node:path";
+import type { TaskRecord, TaskStatus, TaskEvent } from "./types.js";
+import { getInboxDir, getTasksPath } from "./types.js";
+
+// ─── Errors ───────────────────────────────────────────────────────────────────
+
+export class InboxError extends Error {
+	constructor(msg: string) {
+		super(`[InboxError] ${msg}`);
+		this.name = "InboxError";
+	}
+}
+
+// ─── TaskInbox ────────────────────────────────────────────────────────────────
+
+/**
+ * Manages the append-only task inbox at `~/.pi/harness/inbox/tasks.jsonl`.
+ *
+ * Storage layout:
+ * ```
+ * ~/.pi/harness/inbox/
+ * ├── tasks.jsonl   # append-only log (one JSON line per task)
+ * ├── claimed/      # active leases (one JSON file per task)
+ * └── BACKLOG.md   # human-friendly authoring surface (optional)
+ * ```
+ *
+ * Operations are:
+ * - **append**  — append a new task to tasks.jsonl
+ * - **list**    — read all tasks, filterable by status
+ * - **transition** — update a task's status in-place (rewrite)
+ * - **get**     — read one task by id
+ * - **reindex** — compact tasks.jsonl by rewriting it from in-memory state
+ */
+export class TaskInbox {
+	private readonly tasksPath: string;
+	private readonly inboxDir: string;
+	private _cache: TaskRecord[] | null = null;
+
+	constructor(options: { tasksPath?: string; inboxDir?: string } = {}) {
+		this.inboxDir = options.inboxDir ?? getInboxDir();
+		this.tasksPath = options.tasksPath ?? getTasksPath();
+	}
+
+	/** Ensure the inbox directory exists. Call before any write. */
+	ensureDir(): void {
+		if (!existsSync(this.inboxDir)) {
+			mkdirSync(this.inboxDir, { recursive: true });
+		}
+	}
+
+	// ─── append ──────────────────────────────────────────────────────────────
+
+	/**
+	 * Append a new task to tasks.jsonl.
+	 * The task is validated before writing. Duplicate ids are rejected.
+	 *
+	 * @throws {InboxError} if the task id already exists or validation fails
+	 */
+	append(task: TaskRecord): void {
+		this.ensureDir();
+
+		// Guard against duplicate ids
+		const existing = this.list().find((t) => t.id === task.id);
+		if (existing) {
+			throw new InboxError(
+				`Task ${task.id} already exists in inbox (status=${existing.status})`,
+			);
+		}
+
+		const line = JSON.stringify(task) + "\n";
+		appendFileSync(this.tasksPath, line, "utf8");
+		this._cache = null; // invalidate
+	}
+
+	// ─── list ─────────────────────────────────────────────────────────────────
+
+	/**
+	 * Read all tasks from tasks.jsonl.
+	 * Results are sorted by priority ASC then createdAt ASC (oldest first).
+	 *
+	 * @param filter Optionally filter by status. If omitted, returns all.
+	 */
+	list(filter?: { status?: TaskStatus | TaskStatus[] }): TaskRecord[] {
+		if (!existsSync(this.tasksPath)) {
+			return [];
+		}
+
+		const raw = readFileSync(this.tasksPath, "utf8");
+		const tasks: TaskRecord[] = [];
+
+		for (const line of raw.split("\n")) {
+			const trimmed = line.trim();
+			if (!trimmed) continue;
+			try {
+				const task = JSON.parse(trimmed) as TaskRecord;
+				tasks.push(task);
+			} catch {
+				// Corrupt line — skip but don't fail the whole list
+				console.warn(`[TaskInbox] Skipping corrupt line in ${this.tasksPath}`);
+			}
+		}
+
+		// Filter by status
+		let filtered = tasks;
+		if (filter?.status !== undefined) {
+			const statuses = Array.isArray(filter.status)
+				? filter.status
+				: [filter.status];
+			filtered = tasks.filter((t) => statuses.includes(t.status));
+		}
+
+		// Sort: priority ASC, then createdAt ASC
+		filtered.sort((a, b) => {
+			if (a.priority !== b.priority) return a.priority - b.priority;
+			return a.createdAt.localeCompare(b.createdAt);
+		});
+
+		return filtered;
+	}
+
+	// ─── get ─────────────────────────────────────────────────────────────────
+
+	/** Retrieve a single task by id, or null if not found. */
+	get(id: string): TaskRecord | null {
+		const tasks = this.list();
+		return tasks.find((t) => t.id === id) ?? null;
+	}
+
+	// ─── transition ──────────────────────────────────────────────────────────
+
+	/**
+	 * Update a task's status in-place inside tasks.jsonl.
+	 *
+	 * Uses read→parse→update→rewrite to avoid corrupting the JSONL file.
+	 * The rewrite is atomic (write-tmp-then-rename).
+	 *
+	 * @param taskId       The id of the task to transition
+	 * @param newStatus    The target status
+	 * @param extra       Optional additional fields to merge into the task record
+	 * @param event       Optional TaskEvent to append to the history
+	 * @throws {InboxError} if the task does not exist
+	 */
+	transition(
+		taskId: string,
+		newStatus: TaskStatus,
+		extra?: Partial<TaskRecord>,
+		event?: TaskEvent,
+	): TaskRecord {
+		if (!existsSync(this.tasksPath)) {
+			throw new InboxError(`tasks.jsonl does not exist at ${this.tasksPath}`);
+		}
+
+		const tasks = this.list();
+		const idx = tasks.findIndex((t) => t.id === taskId);
+		if (idx === -1) {
+			throw new InboxError(`Task ${taskId} not found in inbox`);
+		}
+
+		const updated: TaskRecord = {
+			...tasks[idx],
+			...extra,
+			status: newStatus,
+			updatedAt: new Date().toISOString(),
+			history: event
+				? [...tasks[idx].history, event]
+				: [
+						...tasks[idx].history,
+						{
+							ts: new Date().toISOString(),
+							kind: "transitioned",
+							payload: { from: tasks[idx].status, to: newStatus },
+						},
+					],
+		};
+
+		// Rewrite tasks.jsonl atomically
+		this._rewriteAll([
+			...tasks.slice(0, idx),
+			updated,
+			...tasks.slice(idx + 1),
+		]);
+		this._cache = null;
+
+		return updated;
+	}
+
+	// ─── markDone / markFailed ───────────────────────────────────────────────
+
+	/** Convenience: mark a task as completed with a result. */
+	complete(taskId: string, result: TaskRecord["result"]): TaskRecord {
+		return this.transition(
+			taskId,
+			"completed",
+			{ result },
+			{
+				ts: new Date().toISOString(),
+				kind: "completed",
+				payload: { result },
+			},
+		);
+	}
+
+	/** Convenience: mark a task as failed with a reason. */
+	fail(taskId: string, reason: string): TaskRecord {
+		const task = this.get(taskId);
+		const attempts = (task?.attempts ?? 0) + 1;
+		const newStatus =
+			attempts >= (task?.maxAttempts ?? 3) ? "dead_letter" : "retrying";
+		return this.transition(
+			taskId,
+			newStatus,
+			{ failureReason: reason, attempts },
+			{
+				ts: new Date().toISOString(),
+				kind: newStatus === "dead_letter" ? "dead_lettered" : "failed",
+				payload: { reason, attempts },
+			},
+		);
+	}
+
+	// ─── reindex ─────────────────────────────────────────────────────────────
+
+	/** Rewrite tasks.jsonl from the given task list. */
+	private _rewriteAll(tasks: TaskRecord[]): void {
+		const tmp = `${this.tasksPath}.tmp`;
+		const content = tasks.map((t) => JSON.stringify(t)).join("\n") + "\n";
+		writeFileSync(tmp, content, "utf8");
+		// Atomic rename (POSIX guarantees atomicity)
+		// Bun/Node will use the native rename which is atomic on POSIX
+		const { renameSync } = require("node:fs");
+		renameSync(tmp, this.tasksPath);
+	}
+
+	/** Force a full reindex. Call after manual edits to tasks.jsonl. */
+	reindex(): void {
+		if (!existsSync(this.tasksPath)) return;
+		const tasks = this.list(); // reads and validates
+		this._rewriteAll(tasks);
+		this._cache = null;
+	}
+
+	// ─── count ───────────────────────────────────────────────────────────────
+
+	/** Return counts of tasks grouped by status. */
+	stats(): Record<TaskStatus, number> {
+		const tasks = this.list();
+		const counts: Record<string, number> = {};
+		for (const t of tasks) {
+			counts[t.status] = (counts[t.status] ?? 0) + 1;
+		}
+		return counts as Record<TaskStatus, number>;
+	}
+}

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

@@ -0,0 +1,22 @@
+/**
+ * Autonomous Operations Runtime — Public API
+ *
+ * Phase 1 exports (RFC-0101 §1-2):
+ * - TaskRecord, TaskLease, TaskEvent, TaskStatus, CapabilityName, ApprovalClass types
+ * - TaskInbox: append, list, get, transition, complete, fail
+ * - LeaseManager: claim, heartbeat, release, reap, recoverOnStartup
+ *
+ * Phase 2+ exports (added as implemented):
+ * - Worker lifecycle (worker.ts)
+ * - Privilege broker (privilege-broker package)
+ * - Scheduler adapter (scheduler-adapter package)
+ */
+export * from "./types.js";
+export { TaskInbox, InboxError } from "./inbox.js";
+export {
+	LeaseManager,
+	LeaseError,
+	DEFAULT_LEASE_TTL_MS,
+	HEARTBEAT_INTERVAL_MS,
+	HEARTBEAT_EXTENSION_MS,
+} from "./lease.js";