pi-harness-runtime 0.10.12 → 0.10.13

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

@@ -0,0 +1,273 @@
+/**
+ * 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 { getLeasesDir } from "./types.js";
+// --- Errors -------------------------------------------------------------------
+export class LeaseError extends Error {
+    constructor(msg) {
+        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
+/**
+ * Manages task leases on disk using atomic write-tmp-then-rename.
+ */
+export class LeaseManager {
+    leasesDir;
+    leaseTtlMs;
+    constructor(options = {}) {
+        this.leasesDir = options.leasesDir ?? getLeasesDir();
+        this.leaseTtlMs = options.leaseTtlMs ?? DEFAULT_LEASE_TTL_MS;
+    }
+    /** Ensure the claimed/ directory exists. */
+    ensureDir() {
+        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, workerId, attempt = 1) {
+        this.ensureDir();
+        const now = new Date().toISOString();
+        const expiresAt = new Date(Date.now() + this.leaseTtlMs).toISOString();
+        const lease = {
+            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;
+        try {
+            fd = openSync(targetPath, "wx", 0o644); // mode 0644 = rw-r--r--
+        }
+        catch (err) {
+            const code = err.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) {
+            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, workerId) {
+        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 = {
+            ...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, workerId) {
+        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) {
+        const path = this._leasePath(taskId);
+        if (!existsSync(path))
+            return null;
+        try {
+            return JSON.parse(readFileSync(path, "utf8"));
+        }
+        catch {
+            return null;
+        }
+    }
+    // --- isExpired ------------------------------------------------------------
+    /** Check if a lease has expired (expiresAt is in the past). */
+    isExpired(lease) {
+        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() {
+        if (!existsSync(this.leasesDir))
+            return [];
+        const now = Date.now();
+        const expired = [];
+        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"));
+                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() {
+        const expired = this.reap();
+        const released = [];
+        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() {
+        return this.reapAndRelease();
+    }
+    // --- listActive -----------------------------------------------------------
+    /** Return all active (non-expired) leases. */
+    listActive() {
+        if (!existsSync(this.leasesDir))
+            return [];
+        const now = Date.now();
+        const active = [];
+        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"));
+                if (new Date(lease.expiresAt).getTime() >= now) {
+                    active.push(lease);
+                }
+            }
+            catch {
+                // Corrupt — remove
+                try {
+                    unlinkSync(path);
+                }
+                catch {
+                    /* ignore */
+                }
+            }
+        }
+        return active;
+    }
+    // --- internals -----------------------------------------------------------
+    _leasePath(taskId) {
+        return join(this.leasesDir, `${taskId}.lease.json`);
+    }
+    _writeLease(lease) {
+        this.ensureDir();
+        const tmp = `${this._leasePath(lease.taskId)}.tmp`;
+        writeFileSync(tmp, JSON.stringify(lease), "utf8");
+        renameSync(tmp, this._leasePath(lease.taskId));
+    }
+    _removeLease(taskId) {
+        const path = this._leasePath(taskId);
+        if (existsSync(path))
+            unlinkSync(path);
+    }
+}
+//# sourceMappingURL=lease.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"lease.js","sourceRoot":"","sources":["../src/lease.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EACN,SAAS,EACT,UAAU,EACV,SAAS,EACT,QAAQ,EACR,YAAY,EACZ,WAAW,EACX,UAAU,EACV,UAAU,EACV,aAAa,EACb,SAAS,GACT,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE1C,iFAAiF;AAEjF,MAAM,OAAO,UAAW,SAAQ,KAAK;IACpC,YAAY,GAAW;QACtB,KAAK,CAAC,gBAAgB,GAAG,EAAE,CAAC,CAAC;QAC7B,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC;IAC1B,CAAC;CACD;AAED,iFAAiF;AAEjF,qEAAqE;AACrE,MAAM,CAAC,MAAM,oBAAoB,GAAG,MAAM,CAAC,CAAC,OAAO;AAEnD,6CAA6C;AAC7C,MAAM,CAAC,MAAM,qBAAqB,GAAG,KAAK,CAAC,CAAC,MAAM;AAElD,mDAAmD;AACnD,MAAM,CAAC,MAAM,sBAAsB,GAAG,MAAM,CAAC,CAAC,iBAAiB;AAU/D;;GAEG;AACH,MAAM,OAAO,YAAY;IACP,SAAS,CAAS;IAClB,UAAU,CAAS;IAEpC,YAAY,OAAO,GAAiB,EAAE;QACrC,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,YAAY,EAAE,CAAC;QACrD,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,oBAAoB,CAAC;IAC9D,CAAC;IAED,4CAA4C;IAC5C,SAAS;QACR,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;YACjC,SAAS,CAAC,IAAI,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAChD,CAAC;IACF,CAAC;IAED,4EAA4E;IAE5E;;;;;;;;;;;;OAYG;IACH,KAAK,CAAC,MAAc,EAAE,QAAgB,EAAE,OAAO,GAAG,CAAC;QAClD,IAAI,CAAC,SAAS,EAAE,CAAC;QAEjB,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QACrC,MAAM,SAAS,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC,WAAW,EAAE,CAAC;QACvE,MAAM,KAAK,GAAc;YACxB,MAAM;YACN,QAAQ;YACR,UAAU,EAAE,GAAG;YACf,SAAS;YACT,WAAW,EAAE,GAAG;YAChB,OAAO;SACP,CAAC;QAEF,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;QAE3C,0EAA0E;QAC1E,4EAA4E;QAC5E,IAAI,EAAU,CAAC;QACf,IAAI,CAAC;YACJ,EAAE,GAAG,QAAQ,CAAC,UAAU,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC,wBAAwB;QACjE,CAAC;QAAC,OAAO,GAAY,EAAE,CAAC;YACvB,MAAM,IAAI,GAAI,GAA6B,CAAC,IAAI,CAAC;YACjD,IAAI,IAAI,KAAK,QAAQ,EAAE,CAAC;gBACvB,OAAO,IAAI,CAAC,CAAC,iCAAiC;YAC/C,CAAC;YACD,MAAM,GAAG,CAAC;QACX,CAAC;QAED,IAAI,CAAC;YACJ,SAAS,CAAC,EAAE,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,CAAC;YAC5C,SAAS,CAAC,EAAE,CAAC,CAAC;YACd,OAAO,KAAK,CAAC;QACd,CAAC;QAAC,OAAO,GAAY,EAAE,CAAC;YACvB,IAAI,CAAC;gBACJ,SAAS,CAAC,EAAE,CAAC,CAAC;YACf,CAAC;YAAC,MAAM,CAAC;gBACR,YAAY;YACb,CAAC;YACD,IAAI,CAAC;gBACJ,UAAU,CAAC,UAAU,CAAC,CAAC;YACxB,CAAC;YAAC,MAAM,CAAC;gBACR,YAAY;YACb,CAAC;YACD,MAAM,GAAG,CAAC;QACX,CAAC;IACF,CAAC;IAED,6EAA6E;IAE7E;;;;;OAKG;IACH,SAAS,CAAC,MAAc,EAAE,QAAgB;QACzC,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QAC/B,IAAI,CAAC,KAAK;YAAE,OAAO,IAAI,CAAC;QACxB,IAAI,KAAK,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;YACjC,MAAM,IAAI,UAAU,CACnB,UAAU,QAAQ,+BAA+B,MAAM,aAAa,KAAK,CAAC,QAAQ,EAAE,CACpF,CAAC;QACH,CAAC;QAED,MAAM,OAAO,GAAc;YAC1B,GAAG,KAAK;YACR,WAAW,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YACrC,SAAS,EAAE,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC,WAAW,EAAE;SAC/D,CAAC;QAEF,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;QAC1B,OAAO,OAAO,CAAC;IAChB,CAAC;IAED,4EAA4E;IAE5E;;OAEG;IACH,OAAO,CAAC,MAAc,EAAE,QAAgB;QACvC,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QAC/B,IAAI,CAAC,KAAK;YAAE,OAAO;QACnB,IAAI,KAAK,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;YACjC,MAAM,IAAI,UAAU,CACnB,UAAU,QAAQ,6BAA6B,MAAM,aAAa,KAAK,CAAC,QAAQ,EAAE,CAClF,CAAC;QACH,CAAC;QACD,IAAI,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC;IAC3B,CAAC;IAED,4EAA4E;IAE5E,yDAAyD;IACzD,GAAG,CAAC,MAAc;QACjB,MAAM,IAAI,GAAG,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;QACrC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;YAAE,OAAO,IAAI,CAAC;QACnC,IAAI,CAAC;YACJ,OAAO,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAc,CAAC;QAC5D,CAAC;QAAC,MAAM,CAAC;YACR,OAAO,IAAI,CAAC;QACb,CAAC;IACF,CAAC;IAED,6EAA6E;IAE7E,+DAA+D;IAC/D,SAAS,CAAC,KAAgB;QACzB,OAAO,IAAI,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACzD,CAAC;IAED,4EAA4E;IAE5E;;;OAGG;IACH,IAAI;QACH,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC;YAAE,OAAO,EAAE,CAAC;QAC3C,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,MAAM,OAAO,GAAgB,EAAE,CAAC;QAEhC,KAAK,MAAM,QAAQ,IAAI,WAAW,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;YACpD,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,aAAa,CAAC;gBAAE,SAAS;YAChD,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;YAC5C,IAAI,CAAC;gBACJ,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAc,CAAC;gBAClE,IAAI,IAAI,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,GAAG,GAAG,EAAE,CAAC;oBAC/C,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;gBACrB,CAAC;YACF,CAAC;YAAC,MAAM,CAAC;gBACR,2BAA2B;gBAC3B,IAAI,CAAC;oBACJ,UAAU,CAAC,IAAI,CAAC,CAAC;gBAClB,CAAC;gBAAC,MAAM,CAAC;oBACR,YAAY;gBACb,CAAC;YACF,CAAC;QACF,CAAC;QAED,OAAO,OAAO,CAAC;IAChB,CAAC;IAED;;;OAGG;IACH,cAAc;QACb,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;QAC5B,MAAM,QAAQ,GAAa,EAAE,CAAC;QAC9B,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;YAC7B,IAAI,CAAC;gBACJ,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;gBAChC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;YAC7B,CAAC;YAAC,MAAM,CAAC;gBACR,2BAA2B;YAC5B,CAAC;QACF,CAAC;QACD,OAAO,QAAQ,CAAC;IACjB,CAAC;IAED,4EAA4E;IAE5E;;;;;;OAMG;IACH,gBAAgB;QACf,OAAO,IAAI,CAAC,cAAc,EAAE,CAAC;IAC9B,CAAC;IAED,6EAA6E;IAE7E,8CAA8C;IAC9C,UAAU;QACT,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC;YAAE,OAAO,EAAE,CAAC;QAC3C,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,MAAM,MAAM,GAAgB,EAAE,CAAC;QAE/B,KAAK,MAAM,QAAQ,IAAI,WAAW,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;YACpD,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,aAAa,CAAC;gBAAE,SAAS;YAChD,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;YAC5C,IAAI,CAAC;gBACJ,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAc,CAAC;gBAClE,IAAI,IAAI,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,IAAI,GAAG,EAAE,CAAC;oBAChD,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;gBACpB,CAAC;YACF,CAAC;YAAC,MAAM,CAAC;gBACR,mBAAmB;gBACnB,IAAI,CAAC;oBACJ,UAAU,CAAC,IAAI,CAAC,CAAC;gBAClB,CAAC;gBAAC,MAAM,CAAC;oBACR,YAAY;gBACb,CAAC;YACF,CAAC;QACF,CAAC;QAED,OAAO,MAAM,CAAC;IACf,CAAC;IAED,4EAA4E;IAEpE,UAAU,CAAC,MAAc;QAChC,OAAO,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,GAAG,MAAM,aAAa,CAAC,CAAC;IACrD,CAAC;IAEO,WAAW,CAAC,KAAgB;QACnC,IAAI,CAAC,SAAS,EAAE,CAAC;QACjB,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC;QACnD,aAAa,CAAC,GAAG,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,CAAC;QAClD,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC;IAChD,CAAC;IAEO,YAAY,CAAC,MAAc;QAClC,MAAM,IAAI,GAAG,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;QACrC,IAAI,UAAU,CAAC,IAAI,CAAC;YAAE,UAAU,CAAC,IAAI,CAAC,CAAC;IACxC,CAAC;CACD"}

package/packages/autonomous-runtime/dist/types.d.ts

@@ -0,0 +1,160 @@
+/** 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" | "automatic_reversible" | "human_approval_required" | "forbidden";
+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;
+    kind: "claimed" | "started" | "checkpointed" | "progress" | "blocked" | "approval_requested" | "approved" | "denied" | "failed" | "completed" | "recovered" | "dead_lettered" | "transitioned";
+    payload?: Record<string, unknown>;
+};
+/** The primary durable record for a task. */
+export interface TaskRecord {
+    id: string;
+    objective: string;
+    acceptanceCriteria: string[];
+    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;
+    capabilities: CapabilityName[];
+    approvalClass: ApprovalClass;
+    status: TaskStatus;
+    attempts: number;
+    maxAttempts: number;
+    context?: ExecutionContext;
+    createdAt: string;
+    updatedAt: string;
+    leaseId?: string;
+    result?: TaskResult;
+    failureReason?: string;
+    history: TaskEvent[];
+}
+/** A lease held by a worker on a specific task. */
+export interface TaskLease {
+    taskId: string;
+    workerId: string;
+    acquiredAt: string;
+    expiresAt: string;
+    heartbeatAt: string;
+    attempt: number;
+}
+/** Heartbeat emitted by a worker every 5 s to worker-registry.json. */
+export interface WorkerHeartbeat {
+    workerId: string;
+    startedAt: string;
+    lastBeatAt: string;
+    capacity: number;
+    inflightTaskIds: string[];
+}
+/** A resolved grant from the privilege broker. */
+export interface CapabilityGrant {
+    name: CapabilityName;
+    argv: string[];
+    envWhitelist?: string[];
+    user: string;
+    cwd?: string;
+    timeoutMs: number;
+}
+/** An in-flight human approval request. */
+export interface ApprovalRequest {
+    id: string;
+    taskId: string;
+    capability: CapabilityName;
+    rationale: string;
+    signedBy?: {
+        keyFingerprint: string;
+        ts: string;
+    };
+    decision?: "approved" | "denied";
+    decidedAt?: string;
+    expiresAt: string;
+}
+/** 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;
+};
+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>;
+}
+export interface Checkpoint {
+    taskId: string;
+    attempt: number;
+    state: Record<string, unknown>;
+    savedAt: string;
+}
+/** 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[];
+}
+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;
+    };
+}
+/** Returns the standard storage root for the runtime. */
+export declare function getRuntimeRoot(): string;
+/** Returns the inbox directory path. */
+export declare function getInboxDir(): string;
+/** Returns the claimed leases directory path. */
+export declare function getLeasesDir(): string;
+/** Returns the task JSONL file path. */
+export declare function getTasksPath(): string;
+/** Returns the worker registry path. */
+export declare function getWorkerRegistryPath(): string;
+//# sourceMappingURL=types.d.ts.map

package/packages/autonomous-runtime/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAWA,8DAA8D;AAC9D,MAAM,MAAM,cAAc,GACvB,YAAY,GACZ,aAAa,GACb,YAAY,GACZ,YAAY,GACZ,UAAU,GACV,UAAU,GACV,gBAAgB,GAChB,wBAAwB,GACxB,aAAa,GACb,eAAe,GACf,aAAa,GACb,eAAe,GACf,qBAAqB,GACrB,oBAAoB,GACpB,aAAa,GACb,YAAY,CAAC;AAEhB,iDAAiD;AACjD,MAAM,MAAM,aAAa,GACtB,qBAAqB,GACrB,sBAAsB,GACtB,yBAAyB,GACzB,WAAW,CAAC;AAIf,MAAM,MAAM,UAAU,GACnB,QAAQ,GACR,SAAS,GACT,SAAS,GACT,kBAAkB,GAClB,eAAe,GACf,UAAU,GACV,WAAW,GACX,QAAQ,GACR,aAAa,CAAC;AAEjB,gDAAgD;AAChD,MAAM,MAAM,SAAS,GAAG;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EACD,SAAS,GACT,SAAS,GACT,cAAc,GACd,UAAU,GACV,SAAS,GACT,oBAAoB,GACpB,UAAU,GACV,QAAQ,GACR,QAAQ,GACR,WAAW,GACX,WAAW,GACX,eAAe,GACf,cAAc,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC,CAAC;AAIF,6CAA6C;AAC7C,MAAM,WAAW,UAAU;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,kBAAkB,EAAE,MAAM,EAAE,CAAC;IAC7B,MAAM,EACH;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAChC;QAAE,IAAI,EAAE,UAAU,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,GACxC;QAAE,IAAI,EAAE,SAAS,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,GAChC;QAAE,IAAI,EAAE,UAAU,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,GAC1C;QAAE,IAAI,EAAE,QAAQ,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IACzC,QAAQ,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC5B,YAAY,EAAE,cAAc,EAAE,CAAC;IAC/B,aAAa,EAAE,aAAa,CAAC;IAC7B,MAAM,EAAE,UAAU,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,gBAAgB,CAAC;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,OAAO,EAAE,SAAS,EAAE,CAAC;CACrB;AAID,mDAAmD;AACnD,MAAM,WAAW,SAAS;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;CAChB;AAID,uEAAuE;AACvE,MAAM,WAAW,eAAe;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,EAAE,MAAM,EAAE,CAAC;CAC1B;AAID,kDAAkD;AAClD,MAAM,WAAW,eAAe;IAC/B,IAAI,EAAE,cAAc,CAAC;IACrB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;CAClB;AAID,2CAA2C;AAC3C,MAAM,WAAW,eAAe;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,cAAc,CAAC;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE;QAAE,cAAc,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC;IAClD,QAAQ,CAAC,EAAE,UAAU,GAAG,QAAQ,CAAC;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;CAClB;AAID,kCAAkC;AAClC,MAAM,WAAW,aAAa;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,YAAY,EAAE,IAAI,CACjB,UAAU,EACV,IAAI,GAAG,QAAQ,GAAG,UAAU,GAAG,WAAW,GAAG,WAAW,GAAG,SAAS,CACpE,CAAC;IACF,QAAQ,EAAE,YAAY,CAAC;IACvB,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,YAAY,GACrB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GACpC;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GACxC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC;AAIhC,MAAM,MAAM,wBAAwB,GACjC,cAAc,GACd,cAAc,GACd,gBAAgB,GAChB,aAAa,GACb,uBAAuB,GACvB,oBAAoB,GACpB,eAAe,GACf,gBAAgB,GAChB,gBAAgB,GAChB,mBAAmB,GACnB,iBAAiB,GACjB,kBAAkB,CAAC;AAEtB,MAAM,WAAW,iBAAiB;IACjC,IAAI,EAAE,wBAAwB,CAAC;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;AAID,MAAM,WAAW,UAAU;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,OAAO,EAAE,MAAM,CAAC;CAChB;AAID,mEAAmE;AACnE,MAAM,WAAW,gBAAgB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,mBAAmB,EAAE,cAAc,EAAE,CAAC;IACtC,aAAa,EAAE,aAAa,CAAC;IAC7B,KAAK,EAAE,SAAS,CAAC;IACjB,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,UAAU,EAAE,MAAM,EAAE,CAAC;CACrB;AAID,MAAM,WAAW,UAAU;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,WAAW,GAAG,QAAQ,GAAG,aAAa,CAAC;IAC/C,YAAY,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAChD,qBAAqB,EAAE;QACtB,SAAS,EAAE,MAAM,CAAC;QAClB,MAAM,EAAE,OAAO,CAAC;QAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;KAClB,EAAE,CAAC;IACJ,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;CAC7E;AAMD,yDAAyD;AACzD,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAED,wCAAwC;AACxC,wBAAgB,WAAW,IAAI,MAAM,CAEpC;AAED,iDAAiD;AACjD,wBAAgB,YAAY,IAAI,MAAM,CAErC;AAED,wCAAwC;AACxC,wBAAgB,YAAY,IAAI,MAAM,CAErC;AAED,wCAAwC;AACxC,wBAAgB,qBAAqB,IAAI,MAAM,CAE9C"}

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

@@ -0,0 +1,31 @@
+/**
+ * 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";
+// --- Storage paths ------------------------------------------------------------
+const DEFAULT_ROOT = `${env["HOME"] ?? "."}/.pi/harness`;
+/** Returns the standard storage root for the runtime. */
+export function getRuntimeRoot() {
+    return env["PI_HARNESS_RUNTIME_ROOT"] ?? DEFAULT_ROOT;
+}
+/** Returns the inbox directory path. */
+export function getInboxDir() {
+    return `${getRuntimeRoot()}/inbox`;
+}
+/** Returns the claimed leases directory path. */
+export function getLeasesDir() {
+    return `${getInboxDir()}/claimed`;
+}
+/** Returns the task JSONL file path. */
+export function getTasksPath() {
+    return `${getInboxDir()}/tasks.jsonl`;
+}
+/** Returns the worker registry path. */
+export function getWorkerRegistryPath() {
+    return `${getRuntimeRoot()}/worker-registry.json`;
+}
+//# sourceMappingURL=types.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AA8NnC,iFAAiF;AAEjF,MAAM,YAAY,GAAG,GAAG,GAAG,CAAC,MAAM,CAAC,IAAI,GAAG,cAAc,CAAC;AAEzD,yDAAyD;AACzD,MAAM,UAAU,cAAc;IAC7B,OAAO,GAAG,CAAC,yBAAyB,CAAC,IAAI,YAAY,CAAC;AACvD,CAAC;AAED,wCAAwC;AACxC,MAAM,UAAU,WAAW;IAC1B,OAAO,GAAG,cAAc,EAAE,QAAQ,CAAC;AACpC,CAAC;AAED,iDAAiD;AACjD,MAAM,UAAU,YAAY;IAC3B,OAAO,GAAG,WAAW,EAAE,UAAU,CAAC;AACnC,CAAC;AAED,wCAAwC;AACxC,MAAM,UAAU,YAAY;IAC3B,OAAO,GAAG,WAAW,EAAE,cAAc,CAAC;AACvC,CAAC;AAED,wCAAwC;AACxC,MAAM,UAAU,qBAAqB;IACpC,OAAO,GAAG,cAAc,EAAE,uBAAuB,CAAC;AACnD,CAAC"}

package/packages/autonomous-runtime/dist/worker.d.ts

@@ -0,0 +1,63 @@
+/**
+ * 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()`.
+ */
+import type { TaskResult, WorkerStatus } from "./types.js";
+import type { TaskInbox } from "./inbox.js";
+import type { TaskLease } from "./lease.js";
+export interface WorkerConfig {
+    inbox: TaskInbox;
+    workerId: string;
+    heartbeatIntervalMs?: number;
+    onError?: (taskId: string, error: unknown) => void;
+}
+export interface WorkerEvents {
+    onLease: (lease: TaskLease) => void;
+    onLeaseExpired: (taskId: string) => void;
+    onComplete: (taskId: string, result: TaskResult) => void;
+    onError: (taskId: string, error: unknown) => void;
+}
+/**
+ * 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 declare class Worker {
+    private readonly config;
+    private readonly events;
+    private running;
+    private heartbeatTimer;
+    constructor(config: WorkerConfig);
+    on<K extends keyof WorkerEvents>(event: K, handler: WorkerEvents[K]): void;
+    /**
+     * Start the worker — begins polling for available tasks.
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the worker — stops polling and expires any held leases.
+     */
+    stop(): Promise<void>;
+    /**
+     * Status of this worker.
+     */
+    status(): WorkerStatus;
+    private _poll;
+    private _processTask;
+    /**
+     * Run a single task. Stub — replaces with actual harness loop integration.
+     */
+    private _runTask;
+    private _heartbeat;
+}
+//# sourceMappingURL=worker.d.ts.map

package/packages/autonomous-runtime/dist/worker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker.d.ts","sourceRoot":"","sources":["../src/worker.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAEX,UAAU,EACV,YAAY,EACZ,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C,MAAM,WAAW,YAAY;IAC5B,KAAK,EAAE,SAAS,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CACnD;AAED,MAAM,WAAW,YAAY;IAC5B,OAAO,EAAE,CAAC,KAAK,EAAE,SAAS,KAAK,IAAI,CAAC;IACpC,cAAc,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IACzC,UAAU,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,KAAK,IAAI,CAAC;IACzD,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CAClD;AAED;;;;;;;;;;GAUG;AACH,qBAAa,MAAM;IAClB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAe;IACtC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA6B;IACpD,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,cAAc,CAA+C;IAErE,YAAY,MAAM,EAAE,YAAY,EAK/B;IAED,EAAE,CAAC,CAAC,SAAS,MAAM,YAAY,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,IAAI,CAEzE;IAED;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAY3B;IAED;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAW1B;IAED;;OAEG;IACH,MAAM,IAAI,YAAY,CAMrB;YAEa,KAAK;YAmBL,YAAY;IAuB1B;;OAEG;YACW,QAAQ;YAUR,UAAU;CASxB"}