agent-cli-runtime 0.1.0-alpha.0

package/dist/storage/storage-lease.js

@@ -0,0 +1,223 @@
+import { appendFileSync, closeSync, existsSync, ftruncateSync, mkdirSync, openSync, readFileSync, unlinkSync, writeFileSync, writeSync } from "node:fs";
+import path from "node:path";
+import { createId } from "../core/ids.js";
+import { redactUnknown } from "../core/redaction.js";
+export const STORAGE_LOCK_FILE = "runtime.lock.json";
+export const DEFAULT_LEASE_STALE_MS = 30_000;
+export class StorageLease {
+    storageDir;
+    owner;
+    staleMs;
+    faults;
+    closed = false;
+    lost = false;
+    constructor(storageDir, owner, staleMs, faults = {}) {
+        this.storageDir = storageDir;
+        this.owner = owner;
+        this.staleMs = staleMs;
+        this.faults = faults;
+    }
+    static acquire(storageDir, init = {}) {
+        const staleMs = init.staleMs ?? DEFAULT_LEASE_STALE_MS;
+        mkdirSync(storageDir, { recursive: true });
+        const owner = createRuntimeOwner();
+        const lockPath = path.join(storageDir, STORAGE_LOCK_FILE);
+        const diagnostics = [];
+        while (true) {
+            try {
+                init.faults?.beforeAcquire?.(lockPath);
+                const fd = openSync(lockPath, "wx");
+                try {
+                    writeFileSync(fd, `${JSON.stringify(owner, null, 2)}\n`, "utf8");
+                }
+                finally {
+                    closeSync(fd);
+                }
+                if (diagnostics.length > 0)
+                    appendLeaseDiagnostics(storageDir, diagnostics);
+                return new StorageLease(storageDir, owner, staleMs, init.faults);
+            }
+            catch (error) {
+                if (!isFileExistsError(error))
+                    throw error;
+                const inspection = inspectStorageLock(storageDir, { staleMs });
+                if (inspection.status !== "stale" && inspection.status !== "closed" && inspection.status !== "invalid") {
+                    const heldBy = inspection.owner ? `pid ${inspection.owner.pid}` : "another runtime";
+                    throw new Error(`storageDir is already open for writing by ${heldBy}; use read-only inspection commands or wait for the owner to close`);
+                }
+                diagnostics.push(`Storage lock takeover: previous owner was ${inspection.status}${inspection.reason ? ` (${inspection.reason})` : ""}.`);
+                try {
+                    unlinkSync(lockPath);
+                }
+                catch (unlinkError) {
+                    if (existsSync(lockPath))
+                        throw unlinkError;
+                }
+            }
+        }
+    }
+    currentOwner() {
+        return { ...this.owner };
+    }
+    ownsCurrentLock() {
+        if (this.closed || this.lost)
+            return false;
+        let fd;
+        try {
+            fd = openSync(path.join(this.storageDir, STORAGE_LOCK_FILE), "r");
+            const current = parseRuntimeOwner(JSON.parse(readFileSync(fd, "utf8")));
+            if (current?.runtimeInstanceId !== this.owner.runtimeInstanceId) {
+                this.lost = true;
+                return false;
+            }
+            return true;
+        }
+        catch {
+            this.lost = true;
+            return false;
+        }
+        finally {
+            if (fd !== undefined)
+                closeSync(fd);
+        }
+    }
+    heartbeat() {
+        if (this.closed || this.lost)
+            return undefined;
+        this.owner.heartbeatAt = Date.now();
+        if (!this.writeIfCurrentOwner(this.owner))
+            return undefined;
+        return this.currentOwner();
+    }
+    close() {
+        if (this.closed || this.lost)
+            return undefined;
+        this.closed = true;
+        this.owner.heartbeatAt = Date.now();
+        this.owner.closedAt = this.owner.heartbeatAt;
+        this.faults.beforeClose?.(path.join(this.storageDir, STORAGE_LOCK_FILE));
+        if (!this.writeIfCurrentOwner(this.owner))
+            return undefined;
+        return this.currentOwner();
+    }
+    writeIfCurrentOwner(owner) {
+        let fd;
+        try {
+            fd = openSync(path.join(this.storageDir, STORAGE_LOCK_FILE), "r+");
+            const current = parseRuntimeOwner(JSON.parse(readFileSync(fd, "utf8")));
+            if (current?.runtimeInstanceId !== this.owner.runtimeInstanceId) {
+                this.lost = true;
+                return false;
+            }
+            ftruncateSync(fd, 0);
+            writeSync(fd, `${JSON.stringify(redactUnknown(owner), null, 2)}\n`, 0, "utf8");
+            return true;
+        }
+        catch {
+            this.lost = true;
+            return false;
+        }
+        finally {
+            if (fd !== undefined)
+                closeSync(fd);
+        }
+    }
+}
+export function createRuntimeOwner() {
+    const now = Date.now();
+    return {
+        runtimeInstanceId: createId("runtime"),
+        pid: process.pid,
+        startedAt: now,
+        heartbeatAt: now,
+    };
+}
+export function inspectStorageLock(storageDir, init = {}) {
+    const staleMs = init.staleMs ?? DEFAULT_LEASE_STALE_MS;
+    const file = STORAGE_LOCK_FILE;
+    const lockPath = path.join(storageDir, STORAGE_LOCK_FILE);
+    if (!existsSync(lockPath))
+        return { file, status: "missing", staleMs, diagnostics: [] };
+    try {
+        const parsed = JSON.parse(readFileSync(lockPath, "utf8"));
+        const owner = parseRuntimeOwner(parsed);
+        if (!owner)
+            return { file, status: "invalid", staleMs, diagnostics: ["Storage lock owner is invalid."] };
+        const inspected = inspectOwner(owner, { staleMs });
+        return redactUnknown({ file, staleMs, diagnostics: [], ...inspected });
+    }
+    catch (error) {
+        return {
+            file,
+            status: "invalid",
+            staleMs,
+            diagnostics: [error instanceof Error ? error.message : String(error)],
+        };
+    }
+}
+export function inspectOwner(owner, init = {}) {
+    if (!owner)
+        return { status: "missing", reason: "owner metadata is missing" };
+    const now = init.now ?? Date.now();
+    const staleMs = init.staleMs ?? DEFAULT_LEASE_STALE_MS;
+    const ageMs = Math.max(0, now - owner.heartbeatAt);
+    if (owner.closedAt !== undefined)
+        return { status: "closed", owner, ageMs, reason: "owner closed the lease" };
+    if (ageMs > staleMs)
+        return { status: "stale", owner, ageMs, reason: "owner heartbeat is stale" };
+    if (!isPidAlive(owner.pid))
+        return { status: "stale", owner, ageMs, reason: "owner process is not alive" };
+    return { status: "live", owner, ageMs };
+}
+export function parseRuntimeOwner(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    const record = value;
+    if (typeof record.runtimeInstanceId !== "string")
+        return undefined;
+    if (typeof record.pid !== "number")
+        return undefined;
+    if (typeof record.startedAt !== "number" || typeof record.heartbeatAt !== "number")
+        return undefined;
+    if ("closedAt" in record && record.closedAt !== undefined && typeof record.closedAt !== "number")
+        return undefined;
+    return {
+        runtimeInstanceId: record.runtimeInstanceId,
+        pid: record.pid,
+        startedAt: record.startedAt,
+        heartbeatAt: record.heartbeatAt,
+        closedAt: typeof record.closedAt === "number" ? record.closedAt : undefined,
+    };
+}
+function appendLeaseDiagnostics(storageDir, messages) {
+    for (const message of messages) {
+        try {
+            appendFileSync(path.join(storageDir, "diagnostics.jsonl"), `${JSON.stringify(redactUnknown({
+                timestamp: Date.now(),
+                diagnostic: {
+                    code: "AGENT_STORAGE_LEASE_TAKEOVER",
+                    message,
+                    retryable: false,
+                },
+            }))}\n`, "utf8");
+        }
+        catch {
+            // Lease diagnostics must never block lock acquisition.
+        }
+    }
+}
+function isPidAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function isFileExistsError(error) {
+    return Boolean(error && typeof error === "object" && "code" in error && error.code === "EEXIST");
+}
+//# sourceMappingURL=storage-lease.js.map

package/dist/storage/storage-lease.js.map

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

package/dist/storage/storage-types.d.ts

@@ -0,0 +1,55 @@
+import type { ReplayEvent } from "../core/events.js";
+import type { GoalRecord } from "../goals/goal-types.js";
+import type { RunRecord } from "../runs/run-types.js";
+import type { AgentEvent, SchedulerEvent } from "../core/events.js";
+export interface JsonlReadResult<T> {
+    records: Array<ReplayEvent<T>>;
+    error?: Error;
+    issue?: JsonlReadIssue;
+    issues: JsonlReadIssue[];
+}
+export interface JsonlReadIssue {
+    file: string;
+    line: number;
+    reason: string;
+    retainedEventCount: number;
+    partialTail: boolean;
+    corruptLineCount: number;
+    partialTailDetected: boolean;
+    lastGoodEventId?: number;
+    lastGoodSequence?: number;
+    repairRecommendation: "none" | "truncate_partial_tail" | "isolate_corrupt_line" | "manual_review";
+    redactedTailPreview?: string;
+}
+export interface StoredRunSnapshot {
+    manifest: RunRecord;
+    events: Array<ReplayEvent<AgentEvent>>;
+    manifestError?: Error;
+    eventsError?: Error;
+    eventsIssue?: JsonlReadIssue;
+}
+export interface StoredGoalSnapshot {
+    manifest: GoalRecord;
+    events: Array<ReplayEvent<SchedulerEvent>>;
+    manifestError?: Error;
+    eventsError?: Error;
+    eventsIssue?: JsonlReadIssue;
+}
+export interface FileStorage {
+    listRuns(): StoredRunSnapshot[];
+    writeRunManifest(record: RunRecord): void;
+    appendRunEvent(runId: string, event: ReplayEvent<AgentEvent>): void;
+    listGoals(): StoredGoalSnapshot[];
+    writeGoalManifest(record: GoalRecord): void;
+    appendGoalEvent(goalId: string, event: ReplayEvent<SchedulerEvent>): void;
+}
+export type StorageDurability = "relaxed" | "fsync";
+export interface StorageSyncHooks {
+    fdatasyncSync?: (fd: number) => void;
+    fsyncSync?: (fd: number) => void;
+}
+export interface StorageFaultHooks {
+    beforeManifestTempWrite?: (file: string) => void;
+    beforeManifestRename?: (tmp: string, file: string) => void;
+    beforeJsonlAppend?: (file: string) => void;
+}

package/dist/storage/storage-types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=storage-types.js.map

package/dist/storage/storage-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage-types.js","sourceRoot":"","sources":["../../src/storage/storage-types.ts"],"names":[],"mappings":""}

package/dist/storage/store-inspection.d.ts

@@ -0,0 +1,28 @@
+import type { ReplayEvent } from "../core/events.js";
+import type { AgentEvent, SchedulerEvent } from "../core/events.js";
+import type { RunRecord } from "../runs/run-types.js";
+import type { GoalRecord } from "../goals/goal-types.js";
+import type { DiagnosticsBundle, ExportDiagnosticsRequest, StorageLockInspection, StoreHealth, StoreRepairReport } from "../public-types.js";
+export interface StoreRepairFaultHooks {
+    beforeBackupWrite?: (file: string) => void;
+    beforeRepairRewrite?: (file: string) => void;
+}
+export declare function inspectStoreDirectory(storageDir: string): StoreHealth;
+export declare function inspectStoreLock(storageDir: string): StorageLockInspection;
+export declare function listStoredRuns(storageDir: string, options?: {
+    status?: "active" | RunRecord["status"];
+}): RunRecord[];
+export declare function getStoredRun(storageDir: string, runId: string): RunRecord | null;
+export declare function replayStoredRunEvents(storageDir: string, runId: string, afterEventId?: number): Array<ReplayEvent<AgentEvent>>;
+export declare function listStoredGoals(storageDir: string, options?: {
+    status?: "active" | GoalRecord["status"];
+}): GoalRecord[];
+export declare function getStoredGoal(storageDir: string, goalId: string): GoalRecord | null;
+export declare function replayStoredGoalEvents(storageDir: string, goalId: string, afterEventId?: number): Array<ReplayEvent<SchedulerEvent>>;
+export declare function inspectStoreRepairDryRun(storageDir: string): StoreRepairReport;
+export declare function inspectStoreRepair(storageDir: string, options?: {
+    apply?: boolean;
+    faults?: StoreRepairFaultHooks;
+}): StoreRepairReport;
+export declare function exportDiagnosticsBundle(request: ExportDiagnosticsRequest, storageDir: string): DiagnosticsBundle;
+export declare function atomicWriteJsonFile(file: string, value: unknown): void;