@rse/ase 1.0.7 → 2.0.0

package/dst/ase-agent-runtime-claim.js

@@ -0,0 +1,189 @@
+/*
+**  Agentic Software Engineering (ASE)
+**  Copyright (c) 2025-2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
+**  Licensed under Apache 2.0 <https://spdx.org/licenses/Apache-2.0>
+*/
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import lockfile from "proper-lockfile";
+import { Task } from "./ase-task.js";
+import { userStateDir } from "./ase-config-scope.js";
+import { pidAlive, pidStart } from "./ase-agent-runtime-exec.js";
+/*  the duration after which the run lock of a terminated agent process counts as stale  */
+const runStale = 30 * 1000;
+/*  the identity of the per-user state directory on this host, which holds the run locks,
+    so only the runs of the same user (and home directory) on the same host are recovered  */
+export const runOwner = crypto.createHash("sha1")
+    .update(`${os.hostname()}\n${userStateDir()}`).digest("hex").slice(0, 12);
+/*  the run of an agent process of a kind, guarded by a run lock in the per-user state
+    directory (hence per host and user), below a sub-directory per task store (as the
+    recorded task ids are unique per task store only, so no run of another project is
+    ever recovered against the wrong tasks), and recording the process id and the claims
+    of the tasks processed by it, so the agents of the same kind started later for the
+    same task store can recover the tasks left behind by the terminated runs (whose run
+    lock is gone or stale, and whose process is no longer alive, where the recorded start
+    time of the process guards against a process id reused meanwhile by another process)  */
+export class AgentRun {
+    log;
+    kind;
+    id = crypto.randomUUID();
+    unlock = null;
+    claims = new Map();
+    seized = new Map();
+    start = "";
+    _dir = "";
+    constructor(log, kind) {
+        this.log = log;
+        this.kind = kind;
+    }
+    /*  the directory of the runs of the agent kind for the task store, and the files of a run  */
+    get dir() {
+        if (this._dir === "")
+            this._dir = path.join(userStateDir(), `agent-${this.kind}`, crypto.createHash("sha1").update(Task.storeKey(this.log)).digest("hex").slice(0, 12));
+        return this._dir;
+    }
+    file(run, ext = "") {
+        return path.join(this.dir, `${run}${ext}`);
+    }
+    /*  the record (process id, its start time, and claims) of a run  */
+    record(run) {
+        try {
+            const data = JSON.parse(fs.readFileSync(this.file(run, ".json"), "utf8"));
+            return { pid: Number(data.pid ?? 0), start: String(data.start ?? ""), claims: data.claims ?? {} };
+        }
+        catch (_err) {
+            return { pid: 0, start: "", claims: {} };
+        }
+    }
+    /*  save the record of a run (atomically)  */
+    store(run, record) {
+        const file = this.file(run, ".json");
+        fs.writeFileSync(`${file}.tmp`, JSON.stringify(record));
+        fs.renameSync(`${file}.tmp`, file);
+    }
+    save() {
+        this.store(this.id, { pid: process.pid, start: this.start, claims: Object.fromEntries(this.claims) });
+    }
+    /*  acquire the run lock (refreshed periodically, where a compromised one, e.g. one
+        removed as stale while this process was suspended, is reported instead of thrown)  */
+    async acquire() {
+        fs.mkdirSync(this.dir, { recursive: true });
+        this.start = await pidStart(process.pid);
+        this.unlock = await lockfile.lock(this.file(this.id), {
+            realpath: false, stale: runStale, update: runStale / 3,
+            onCompromised: (err) => {
+                this.log.write("warning", `agent: run lock of ${this.kind} compromised: ${err.message}`);
+            }
+        });
+        this.save();
+    }
+    /*  release the run lock (and the run locks of the terminated runs still seized), and remove
+        the record of this run, unless it still records claims (to be recovered by a later run)  */
+    async release() {
+        for (const run of [...this.seized.keys()])
+            await this.free(run);
+        if (this.unlock === null)
+            return;
+        await this.unlock().catch(() => { });
+        this.unlock = null;
+        if (this.claims.size === 0)
+            fs.rmSync(this.file(this.id, ".json"), { force: true });
+    }
+    /*  whether a run is alive: this run, a run whose process (by its given or recorded
+        process id, and, if recorded, by the start time of the process, so a reused process
+        id does not count) is still alive, or one whose run lock is still held  */
+    async alive(run, pid = 0) {
+        if (run === "")
+            return false;
+        else if (run === this.id)
+            return true;
+        const record = this.record(run);
+        const id = pid > 0 ? pid : record.pid;
+        const start = id === record.pid ? record.start : "";
+        if (pidAlive(id) && (start === "" || await pidStart(id) === start))
+            return true;
+        return lockfile.check(this.file(run), { realpath: false, stale: runStale }).catch(() => false);
+    }
+    /*  the runs of the agent kind for the task store (by their run lock or record)  */
+    runs() {
+        return [...new Set(fs.readdirSync(this.dir)
+                .filter((entry) => /\.(?:lock|json)$/.test(entry))
+                .map((entry) => entry.replace(/\.(?:lock|json)$/, "")))];
+    }
+    /*  the terminated runs of the agent kind for the task store, with their recorded claims  */
+    async dead() {
+        const dead = [];
+        for (const run of this.runs())
+            if (!(await this.alive(run)))
+                dead.push({ run, claims: this.record(run).claims });
+        return dead;
+    }
+    /*  seize a terminated run for its recovery, by taking over its (stale or removed) run lock,
+        so the agents started concurrently never recover the same run, returning its claims
+        recorded at that time (as a concurrent recovery might have reduced them meanwhile),
+        or null if the run is seized by another agent (or is alive again)  */
+    async seize(run) {
+        if (this.seized.has(run))
+            return this.record(run).claims;
+        try {
+            const unlock = await lockfile.lock(this.file(run), {
+                realpath: false, stale: runStale, update: runStale / 3, onCompromised: () => { }
+            });
+            this.seized.set(run, unlock);
+        }
+        catch (_err) {
+            return null;
+        }
+        return this.record(run).claims;
+    }
+    /*  release the run lock of a seized terminated run, without removing its record  */
+    async free(run) {
+        const unlock = this.seized.get(run);
+        if (unlock === undefined)
+            return;
+        this.seized.delete(run);
+        await unlock().catch(() => { });
+    }
+    /*  forget a recovered claim of a seized terminated run (so it is never recovered again,
+        even if the recovery of another claim of the run fails and is retried by a later run)  */
+    forget(run, id) {
+        const record = this.record(run);
+        if (record.pid === 0 || !Object.hasOwn(record.claims, id))
+            return;
+        record.claims = Object.fromEntries(Object.entries(record.claims).filter(([key]) => key !== id));
+        this.store(run, record);
+    }
+    /*  whether a task is claimed by this run or by another run whose process is still
+        alive (independent of its run lock, which is also held while a terminated run is
+        seized for its recovery), i.e., by an agent still processing it  */
+    async claimed(id) {
+        if (this.claims.has(id))
+            return true;
+        for (const run of this.runs()) {
+            const record = this.record(run);
+            if (run !== this.id && Object.hasOwn(record.claims, id) && pidAlive(record.pid)
+                && (record.start === "" || await pidStart(record.pid) === record.start))
+                return true;
+        }
+        return false;
+    }
+    /*  remove the record and the run lock of a (seized) terminated run  */
+    async purge(run) {
+        fs.rmSync(this.file(run, ".json"), { force: true });
+        if (this.seized.has(run))
+            await this.free(run);
+        else
+            fs.rmSync(this.file(run, ".lock"), { recursive: true, force: true });
+    }
+    /*  record resp. forget the claim of a task by this run  */
+    claim(id, claim) {
+        this.claims.set(id, claim);
+        this.save();
+    }
+    unclaim(id) {
+        if (this.claims.delete(id))
+            this.save();
+    }
+}