agent-cli-runtime 0.1.0-alpha.0

package/dist/storage/file-storage.js

@@ -0,0 +1,271 @@
+import { closeSync, existsSync, fdatasyncSync, fsyncSync, mkdirSync, openSync, readdirSync, readFileSync, renameSync, appendFileSync, unlinkSync, writeSync, } from "node:fs";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { redactUnknown } from "../core/redaction.js";
+import { appendJsonl, readJsonl } from "./jsonl-store.js";
+import { validateGoalManifest, validateRunManifest } from "./manifest-validation.js";
+export class JsonFileStorage {
+    rootDir;
+    options;
+    diagnostics = [];
+    durability;
+    constructor(rootDir, options = {}) {
+        this.rootDir = rootDir;
+        this.options = options;
+        this.durability = options.durability ?? "relaxed";
+        mkdirSync(this.runsDir, { recursive: true });
+        mkdirSync(this.goalsDir, { recursive: true });
+    }
+    listRuns() {
+        return listManifestDirs(this.runsDir).map((dir) => {
+            const runId = path.basename(dir);
+            const manifest = readRunManifest(path.join(dir, "manifest.json"), runId);
+            const events = readJsonl(path.join(dir, "events.jsonl"));
+            return {
+                manifest: manifest.value ?? corruptRunManifest(runId, manifest.error),
+                manifestError: manifest.error,
+                events: events.records.map((record) => normalizeReplayEvent(record, { runId })),
+                eventsError: events.error,
+                eventsIssue: events.issue,
+            };
+        });
+    }
+    writeRunManifest(record) {
+        this.assertCanWrite();
+        atomicWriteJson(this.runManifestPath(record.id), sanitizeForStorage(record), this.writeOptions("manifest"));
+    }
+    appendRunEvent(runId, event) {
+        this.assertCanWrite();
+        this.ensureRunDir(runId);
+        appendJsonl(this.runEventsPath(runId), sanitizeForStorage(event), this.writeOptions("event"));
+    }
+    listGoals() {
+        return listManifestDirs(this.goalsDir).map((dir) => {
+            const goalId = path.basename(dir);
+            const manifest = readGoalManifest(path.join(dir, "manifest.json"), goalId);
+            const events = readJsonl(path.join(dir, "events.jsonl"));
+            return {
+                manifest: manifest.value ?? corruptGoalManifest(goalId, manifest.error),
+                manifestError: manifest.error,
+                events: events.records.map((record) => normalizeReplayEvent(record, { goalId })),
+                eventsError: events.error,
+                eventsIssue: events.issue,
+            };
+        });
+    }
+    writeGoalManifest(record) {
+        this.assertCanWrite();
+        atomicWriteJson(this.goalManifestPath(record.id), sanitizeForStorage(record), this.writeOptions("manifest"));
+    }
+    appendGoalEvent(goalId, event) {
+        this.assertCanWrite();
+        this.ensureGoalDir(goalId);
+        appendJsonl(this.goalEventsPath(goalId), sanitizeForStorage(event), this.writeOptions("event"));
+    }
+    getDurabilityDiagnostics() {
+        return [...this.diagnostics];
+    }
+    get runsDir() {
+        return path.join(this.rootDir, "runs");
+    }
+    get goalsDir() {
+        return path.join(this.rootDir, "goals");
+    }
+    ensureRunDir(runId) {
+        mkdirSync(path.join(this.runsDir, runId), { recursive: true });
+    }
+    ensureGoalDir(goalId) {
+        mkdirSync(path.join(this.goalsDir, goalId), { recursive: true });
+    }
+    runManifestPath(runId) {
+        this.ensureRunDir(runId);
+        return path.join(this.runsDir, runId, "manifest.json");
+    }
+    runEventsPath(runId) {
+        return path.join(this.runsDir, runId, "events.jsonl");
+    }
+    goalManifestPath(goalId) {
+        this.ensureGoalDir(goalId);
+        return path.join(this.goalsDir, goalId, "manifest.json");
+    }
+    goalEventsPath(goalId) {
+        return path.join(this.goalsDir, goalId, "events.jsonl");
+    }
+    writeOptions(operation) {
+        return {
+            durability: this.durability,
+            sync: this.options.sync,
+            faults: this.options.faults,
+            onSyncDiagnostic: (message) => {
+                this.recordDurabilityDiagnostic(`Storage ${operation} sync fallback: ${message}`);
+            },
+        };
+    }
+    recordDurabilityDiagnostic(message) {
+        const safeMessage = redactUnknown(message);
+        this.diagnostics.push(safeMessage);
+        try {
+            appendFileSync(path.join(this.rootDir, "diagnostics.jsonl"), `${JSON.stringify({
+                timestamp: Date.now(),
+                diagnostic: {
+                    code: "AGENT_STORAGE_SYNC_FALLBACK",
+                    message: safeMessage,
+                    retryable: false,
+                },
+            })}\n`, "utf8");
+        }
+        catch {
+            // Sync fallback diagnostics are best-effort and must not make the primary write fail.
+        }
+    }
+    assertCanWrite() {
+        if (this.options.canWrite && !this.options.canWrite()) {
+            throw new Error("storage lease is no longer held by this runtime");
+        }
+    }
+}
+function listManifestDirs(parent) {
+    if (!existsSync(parent))
+        return [];
+    return readdirSync(parent, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory() && existsSync(path.join(parent, entry.name, "manifest.json")))
+        .map((entry) => path.join(parent, entry.name));
+}
+function readRunManifest(file, runId) {
+    const parsed = readJson(file);
+    if (parsed.error)
+        return { error: parsed.error };
+    return validateRunManifest(parsed.value, runId);
+}
+function readGoalManifest(file, goalId) {
+    const parsed = readJson(file);
+    if (parsed.error)
+        return { error: parsed.error };
+    return validateGoalManifest(parsed.value, goalId);
+}
+function readJson(file) {
+    try {
+        return { value: JSON.parse(readFileSync(file, "utf8")) };
+    }
+    catch (error) {
+        return { error: new Error(`${path.basename(file)} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`) };
+    }
+}
+function atomicWriteJson(file, value, options = {}) {
+    mkdirSync(path.dirname(file), { recursive: true });
+    const tmp = path.join(path.dirname(file), `.manifest.${process.pid}.${randomUUID()}.tmp`);
+    let fd;
+    let renamed = false;
+    try {
+        options.faults?.beforeManifestTempWrite?.(file);
+        fd = openSync(tmp, "w");
+        writeSync(fd, `${JSON.stringify(value, null, 2)}\n`, undefined, "utf8");
+        syncFileDescriptor(fd, options);
+        closeSync(fd);
+        fd = undefined;
+        options.faults?.beforeManifestRename?.(tmp, file);
+        renameSync(tmp, file);
+        renamed = true;
+        syncDirectory(path.dirname(file), options);
+    }
+    finally {
+        if (fd !== undefined)
+            closeSync(fd);
+        if (!renamed) {
+            try {
+                if (existsSync(tmp))
+                    unlinkSync(tmp);
+            }
+            catch {
+                // Temp cleanup is best-effort; the old manifest remains untouched.
+            }
+        }
+    }
+}
+function sanitizeForStorage(value) {
+    return redactUnknown(value);
+}
+function normalizeReplayEvent(record, scope) {
+    const sequence = typeof record.sequence === "number" ? record.sequence : record.id;
+    return {
+        ...record,
+        ...scope,
+        sequence,
+    };
+}
+function syncFileDescriptor(fd, options) {
+    if (options.durability !== "fsync")
+        return;
+    try {
+        const fdatasync = options.sync?.fdatasyncSync ?? fdatasyncSync;
+        fdatasync(fd);
+    }
+    catch (fdatasyncError) {
+        try {
+            const fsync = options.sync?.fsyncSync ?? fsyncSync;
+            fsync(fd);
+        }
+        catch (fsyncError) {
+            options.onSyncDiagnostic?.(`fdatasync failed (${errorMessage(fdatasyncError)}); fsync fallback failed (${errorMessage(fsyncError)}); continuing with relaxed durability`);
+        }
+    }
+}
+function syncDirectory(dir, options) {
+    if (options.durability !== "fsync")
+        return;
+    let fd;
+    try {
+        fd = openSync(dir, "r");
+        const fsync = options.sync?.fsyncSync ?? fsyncSync;
+        fsync(fd);
+    }
+    catch (error) {
+        options.onSyncDiagnostic?.(`directory fsync skipped (${errorMessage(error)}); continuing with file-level durability`);
+    }
+    finally {
+        if (fd !== undefined)
+            closeSync(fd);
+    }
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function corruptRunManifest(runId, error) {
+    const now = Date.now();
+    return {
+        id: runId,
+        agentId: "unknown",
+        cwd: "<unknown>",
+        status: "failed",
+        createdAt: now,
+        updatedAt: now,
+        exitCode: null,
+        signal: null,
+        error: error?.message ?? "Run manifest is corrupt.",
+        errorCode: "AGENT_STORE_RECORD_CORRUPT",
+        diagnostics: [{
+                code: "AGENT_STORE_RECORD_CORRUPT",
+                message: error?.message ?? "Run manifest is corrupt.",
+                retryable: false,
+            }],
+    };
+}
+function corruptGoalManifest(goalId, error) {
+    const now = Date.now();
+    return {
+        id: goalId,
+        cwd: "<unknown>",
+        objective: "<unknown>",
+        status: "failed",
+        result: "failed",
+        tasks: [],
+        diagnostics: [{
+                code: "AGENT_STORE_RECORD_CORRUPT",
+                message: error?.message ?? "Goal manifest is corrupt.",
+                retryable: false,
+            }],
+        createdAt: now,
+        updatedAt: now,
+    };
+}
+//# sourceMappingURL=file-storage.js.map

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

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

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

@@ -0,0 +1,9 @@
+import type { ReplayEvent } from "../core/events.js";
+import type { JsonlReadResult, StorageDurability, StorageFaultHooks, StorageSyncHooks } from "./storage-types.js";
+export declare function appendJsonl<T>(file: string, record: ReplayEvent<T>, options?: {
+    durability?: StorageDurability;
+    sync?: StorageSyncHooks;
+    faults?: StorageFaultHooks;
+    onSyncDiagnostic?: (message: string) => void;
+}): void;
+export declare function readJsonl<T>(file: string): JsonlReadResult<T>;

package/dist/storage/jsonl-store.js

@@ -0,0 +1,138 @@
+import { closeSync, existsSync, fdatasyncSync, fsyncSync, mkdirSync, openSync, readFileSync, readSync, statSync, writeSync, } from "node:fs";
+import path from "node:path";
+import { redactText } from "../core/redaction.js";
+export function appendJsonl(file, record, options = {}) {
+    mkdirSync(path.dirname(file), { recursive: true });
+    options.faults?.beforeJsonlAppend?.(file);
+    const fd = openSync(file, "a");
+    try {
+        if (needsJsonlBoundary(file)) {
+            writeSync(fd, "\n", undefined, "utf8");
+        }
+        writeSync(fd, `${JSON.stringify(record)}\n`, undefined, "utf8");
+        syncFileDescriptor(fd, options);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function needsJsonlBoundary(file) {
+    if (!existsSync(file))
+        return false;
+    try {
+        const { size } = statSync(file);
+        if (size === 0)
+            return false;
+        const handle = openSync(file, "r");
+        try {
+            const buffer = Buffer.alloc(1);
+            readSync(handle, buffer, 0, 1, size - 1);
+            return buffer[0] !== 10;
+        }
+        finally {
+            closeSync(handle);
+        }
+    }
+    catch {
+        return false;
+    }
+}
+export function readJsonl(file) {
+    if (!existsSync(file))
+        return { records: [], issues: [] };
+    const text = readFileSync(file, "utf8");
+    const records = [];
+    const lines = text.split(/\r?\n/);
+    const lastNonEmptyLine = lastNonEmptyLineIndex(lines);
+    const issues = [];
+    for (let index = 0; index < lines.length; index += 1) {
+        const line = lines[index];
+        if (!line.trim())
+            continue;
+        try {
+            const parsed = JSON.parse(line);
+            if (!isReplayEvent(parsed)) {
+                issues.push(jsonlIssue(file, index + 1, "line is not a replay event", records, false, line));
+                continue;
+            }
+            records.push(parsed);
+        }
+        catch (error) {
+            const reason = error instanceof Error ? error.message : String(error);
+            const partialTail = isPartialTail(text, index, lastNonEmptyLine, reason);
+            issues.push(jsonlIssue(file, index + 1, reason, records, partialTail, line));
+            if (partialTail)
+                break;
+        }
+    }
+    if (issues.length === 0)
+        return { records, issues };
+    return {
+        records,
+        error: new Error(issueSummary(issues)),
+        issue: issues[0],
+        issues,
+    };
+}
+function jsonlIssue(file, line, reason, records, partialTail, rawLine) {
+    const lastGood = records.at(-1);
+    return {
+        file: path.basename(file),
+        line,
+        reason,
+        retainedEventCount: records.length,
+        partialTail,
+        corruptLineCount: 1,
+        partialTailDetected: partialTail,
+        lastGoodEventId: lastGood?.id,
+        lastGoodSequence: lastGood?.sequence,
+        repairRecommendation: partialTail ? "truncate_partial_tail" : "isolate_corrupt_line",
+        redactedTailPreview: redactText(rawLine.slice(0, 256)),
+    };
+}
+function issueSummary(issues) {
+    const [first] = issues;
+    const partialTailCount = issues.filter((issue) => issue.partialTail).length;
+    return `${first?.file ?? "events.jsonl"} has ${issues.length} corrupt JSONL line(s)`
+        + `${partialTailCount > 0 ? ` including ${partialTailCount} partial tail(s)` : ""}`
+        + `; retained ${first?.retainedEventCount ?? 0} event(s) before first issue`;
+}
+function isReplayEvent(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const record = value;
+    return typeof record.id === "number" && typeof record.timestamp === "number" && Boolean(record.event);
+}
+function lastNonEmptyLineIndex(lines) {
+    for (let index = lines.length - 1; index >= 0; index -= 1) {
+        if (lines[index]?.trim())
+            return index;
+    }
+    return -1;
+}
+function isPartialTail(text, index, lastNonEmptyLine, reason) {
+    return index === lastNonEmptyLine
+        && !/\r?\n$/u.test(text)
+        && /(end of JSON input|unterminated|string|property name|after|expected|unexpected)/iu.test(reason);
+}
+function syncFileDescriptor(fd, options) {
+    if (options.durability !== "fsync")
+        return;
+    try {
+        const fdatasync = options.sync?.fdatasyncSync ?? fdatasyncSync;
+        fdatasync(fd);
+    }
+    catch (fdatasyncError) {
+        try {
+            const fsync = options.sync?.fsyncSync ?? fsyncSync;
+            fsync(fd);
+        }
+        catch (fsyncError) {
+            options.onSyncDiagnostic?.(`fdatasync failed (${errorMessage(fdatasyncError)}); fsync fallback failed (${errorMessage(fsyncError)}); continuing with relaxed durability`);
+        }
+    }
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+//# sourceMappingURL=jsonl-store.js.map

package/dist/storage/jsonl-store.js.map

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

package/dist/storage/manifest-validation.d.ts

@@ -0,0 +1,11 @@
+import type { GoalRecord } from "../goals/goal-types.js";
+import type { RunRecord } from "../runs/run-types.js";
+export declare function validateRunManifest(value: unknown, runId: string): {
+    value?: RunRecord;
+    error?: Error;
+};
+export declare function validateGoalManifest(value: unknown, goalId: string): {
+    value?: GoalRecord;
+    error?: Error;
+};
+export declare function isRecord(value: unknown): value is Record<string, unknown>;

package/dist/storage/manifest-validation.js

@@ -0,0 +1,102 @@
+import { parseRuntimeOwner } from "./storage-lease.js";
+export function validateRunManifest(value, runId) {
+    if (!isRecord(value))
+        return invalidManifest("run", "manifest is not an object");
+    if (value.id !== runId)
+        return invalidManifest("run", "id does not match storage directory");
+    if (typeof value.agentId !== "string")
+        return invalidManifest("run", "agentId must be a string");
+    if (typeof value.cwd !== "string")
+        return invalidManifest("run", "cwd must be a string");
+    if (!isRunStatus(value.status))
+        return invalidManifest("run", "status is invalid");
+    if (typeof value.createdAt !== "number" || typeof value.updatedAt !== "number") {
+        return invalidManifest("run", "createdAt and updatedAt must be numbers");
+    }
+    if ("diagnostics" in value && !Array.isArray(value.diagnostics))
+        return invalidManifest("run", "diagnostics must be an array");
+    return {
+        value: {
+            id: value.id,
+            agentId: value.agentId,
+            cwd: value.cwd,
+            status: value.status,
+            createdAt: value.createdAt,
+            updatedAt: value.updatedAt,
+            exitCode: typeof value.exitCode === "number" || value.exitCode === null ? value.exitCode : null,
+            signal: typeof value.signal === "string" || value.signal === null ? value.signal : null,
+            error: typeof value.error === "string" || value.error === null ? value.error : null,
+            errorCode: typeof value.errorCode === "string" || value.errorCode === null ? value.errorCode : null,
+            diagnostics: Array.isArray(value.diagnostics) ? value.diagnostics : [],
+            owner: parseRuntimeOwner(value.owner),
+        },
+    };
+}
+export function validateGoalManifest(value, goalId) {
+    if (!isRecord(value))
+        return invalidManifest("goal", "manifest is not an object");
+    if (value.id !== goalId)
+        return invalidManifest("goal", "id does not match storage directory");
+    if (typeof value.cwd !== "string")
+        return invalidManifest("goal", "cwd must be a string");
+    if (typeof value.objective !== "string")
+        return invalidManifest("goal", "objective must be a string");
+    if (!isGoalStatus(value.status))
+        return invalidManifest("goal", "status is invalid");
+    if (!Array.isArray(value.tasks))
+        return invalidManifest("goal", "tasks must be an array");
+    if (!value.tasks.every(isStoredTask))
+        return invalidManifest("goal", "tasks entries are invalid");
+    if (typeof value.createdAt !== "number" || typeof value.updatedAt !== "number") {
+        return invalidManifest("goal", "createdAt and updatedAt must be numbers");
+    }
+    if ("diagnostics" in value && !Array.isArray(value.diagnostics))
+        return invalidManifest("goal", "diagnostics must be an array");
+    if ("result" in value && value.result !== undefined && !isRunResult(value.result))
+        return invalidManifest("goal", "result is invalid");
+    return {
+        value: {
+            id: value.id,
+            cwd: value.cwd,
+            objective: value.objective,
+            status: value.status,
+            tasks: value.tasks,
+            diagnostics: Array.isArray(value.diagnostics) ? value.diagnostics : [],
+            createdAt: value.createdAt,
+            updatedAt: value.updatedAt,
+            result: value.result,
+            owner: parseRuntimeOwner(value.owner),
+        },
+    };
+}
+export function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function invalidManifest(kind, reason) {
+    return { error: new Error(`${kind} manifest is corrupt: ${reason}`) };
+}
+function isRunStatus(value) {
+    return value === "queued" || value === "running" || value === "succeeded" || value === "failed" || value === "canceled";
+}
+function isGoalStatus(value) {
+    return value === "planning" || value === "running" || value === "succeeded" || value === "failed" || value === "canceled";
+}
+function isRunResult(value) {
+    return value === "success" || value === "failed" || value === "cancelled";
+}
+function isStoredTask(value) {
+    if (!isRecord(value))
+        return false;
+    return typeof value.id === "string"
+        && typeof value.title === "string"
+        && typeof value.objective === "string"
+        && isTaskStatus(value.status)
+        && Array.isArray(value.dependencies)
+        && value.dependencies.every((dependency) => typeof dependency === "string")
+        && typeof value.cwd === "string"
+        && typeof value.permissionPolicy === "string";
+}
+function isTaskStatus(value) {
+    return value === "pending" || value === "running" || value === "succeeded" || value === "failed" || value === "canceled" || value === "blocked";
+}
+//# sourceMappingURL=manifest-validation.js.map

package/dist/storage/manifest-validation.js.map

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

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

@@ -0,0 +1,40 @@
+import type { OwnerStatus, RuntimeOwner, StorageLockInspection } from "../public-types.js";
+export declare const STORAGE_LOCK_FILE = "runtime.lock.json";
+export declare const DEFAULT_LEASE_STALE_MS = 30000;
+export interface OwnerInspection {
+    status: OwnerStatus;
+    owner?: RuntimeOwner;
+    ageMs?: number;
+    reason?: string;
+}
+export interface StorageLeaseFaultHooks {
+    beforeAcquire?: (file: string) => void;
+    beforeClose?: (file: string) => void;
+}
+export declare class StorageLease {
+    private readonly storageDir;
+    private readonly owner;
+    private readonly staleMs;
+    private readonly faults;
+    private closed;
+    private lost;
+    private constructor();
+    static acquire(storageDir: string, init?: {
+        staleMs?: number;
+        faults?: StorageLeaseFaultHooks;
+    }): StorageLease;
+    currentOwner(): RuntimeOwner;
+    ownsCurrentLock(): boolean;
+    heartbeat(): RuntimeOwner | undefined;
+    close(): RuntimeOwner | undefined;
+    private writeIfCurrentOwner;
+}
+export declare function createRuntimeOwner(): RuntimeOwner;
+export declare function inspectStorageLock(storageDir: string, init?: {
+    staleMs?: number;
+}): StorageLockInspection;
+export declare function inspectOwner(owner: RuntimeOwner | undefined, init?: {
+    staleMs?: number;
+    now?: number;
+}): OwnerInspection;
+export declare function parseRuntimeOwner(value: unknown): RuntimeOwner | undefined;