@a5c-ai/babysitter-sdk 0.0.16

package/dist/storage/index.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.writeTaskResult = exports.readTaskResult = exports.readTaskDefinition = exports.writeTaskDefinition = exports.writeRunOutput = exports.readRunInputs = exports.readRunMetadata = exports.readRunLock = exports.releaseRunLock = exports.acquireRunLock = exports.findOrphanedBlobs = exports.getDiskUsage = exports.storeTaskArtifacts = exports.snapshotState = exports.loadJournal = exports.appendEvent = exports.createRunDir = void 0;
+var createRunDir_1 = require("./createRunDir");
+Object.defineProperty(exports, "createRunDir", { enumerable: true, get: function () { return createRunDir_1.createRunDir; } });
+var journal_1 = require("./journal");
+Object.defineProperty(exports, "appendEvent", { enumerable: true, get: function () { return journal_1.appendEvent; } });
+Object.defineProperty(exports, "loadJournal", { enumerable: true, get: function () { return journal_1.loadJournal; } });
+var snapshotState_1 = require("./snapshotState");
+Object.defineProperty(exports, "snapshotState", { enumerable: true, get: function () { return snapshotState_1.snapshotState; } });
+var storeTaskArtifacts_1 = require("./storeTaskArtifacts");
+Object.defineProperty(exports, "storeTaskArtifacts", { enumerable: true, get: function () { return storeTaskArtifacts_1.storeTaskArtifacts; } });
+var cleanup_1 = require("./cleanup");
+Object.defineProperty(exports, "getDiskUsage", { enumerable: true, get: function () { return cleanup_1.getDiskUsage; } });
+Object.defineProperty(exports, "findOrphanedBlobs", { enumerable: true, get: function () { return cleanup_1.findOrphanedBlobs; } });
+var lock_1 = require("./lock");
+Object.defineProperty(exports, "acquireRunLock", { enumerable: true, get: function () { return lock_1.acquireRunLock; } });
+Object.defineProperty(exports, "releaseRunLock", { enumerable: true, get: function () { return lock_1.releaseRunLock; } });
+Object.defineProperty(exports, "readRunLock", { enumerable: true, get: function () { return lock_1.readRunLock; } });
+var runFiles_1 = require("./runFiles");
+Object.defineProperty(exports, "readRunMetadata", { enumerable: true, get: function () { return runFiles_1.readRunMetadata; } });
+Object.defineProperty(exports, "readRunInputs", { enumerable: true, get: function () { return runFiles_1.readRunInputs; } });
+Object.defineProperty(exports, "writeRunOutput", { enumerable: true, get: function () { return runFiles_1.writeRunOutput; } });
+var tasks_1 = require("./tasks");
+Object.defineProperty(exports, "writeTaskDefinition", { enumerable: true, get: function () { return tasks_1.writeTaskDefinition; } });
+Object.defineProperty(exports, "readTaskDefinition", { enumerable: true, get: function () { return tasks_1.readTaskDefinition; } });
+Object.defineProperty(exports, "readTaskResult", { enumerable: true, get: function () { return tasks_1.readTaskResult; } });
+Object.defineProperty(exports, "writeTaskResult", { enumerable: true, get: function () { return tasks_1.writeTaskResult; } });

package/dist/storage/journal.d.ts

@@ -0,0 +1,4 @@
+import { AppendEventOptions, AppendEventResult, JournalEvent } from "./types";
+export declare function appendEvent(opts: AppendEventOptions): Promise<AppendEventResult>;
+export declare function loadJournal(runDir: string): Promise<JournalEvent[]>;
+//# sourceMappingURL=journal.d.ts.map

package/dist/storage/journal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"journal.d.ts","sourceRoot":"","sources":["../../src/storage/journal.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,YAAY,EAAc,MAAM,SAAS,CAAC;AAuB1F,wBAAsB,WAAW,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAmBtF;AAWD,wBAAsB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CA6BzE"}

package/dist/storage/journal.js

@@ -0,0 +1,103 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.appendEvent = appendEvent;
+exports.loadJournal = loadJournal;
+const fs_1 = require("fs");
+const path_1 = __importDefault(require("path"));
+const crypto_1 = __importDefault(require("crypto"));
+const paths_1 = require("./paths");
+const atomic_1 = require("./atomic");
+const ulids_1 = require("./ulids");
+const clock_1 = require("./clock");
+function formatSeq(seq) {
+    return seq.toString().padStart(6, "0");
+}
+async function getExistingSeqs(journalDir) {
+    try {
+        const entries = await fs_1.promises.readdir(journalDir);
+        return entries
+            .map((name) => Number(name.split(".")[0]))
+            .filter((n) => Number.isFinite(n));
+    }
+    catch (error) {
+        const err = error;
+        if (err.code === "ENOENT")
+            return [];
+        throw error;
+    }
+}
+async function appendEvent(opts) {
+    const journalDir = (0, paths_1.getJournalDir)(opts.runDir);
+    await fs_1.promises.mkdir(journalDir, { recursive: true });
+    const seqs = await getExistingSeqs(journalDir);
+    const seq = (seqs.length ? Math.max(...seqs) : 0) + 1;
+    const ulid = (0, ulids_1.nextUlid)();
+    const filename = `${formatSeq(seq)}.${ulid}.json`;
+    const recordedAt = (0, clock_1.getClockIsoString)();
+    const eventPayload = {
+        type: opts.eventType,
+        recordedAt,
+        data: opts.event,
+    };
+    const contents = JSON.stringify(eventPayload, null, 2) + "\n";
+    const checksum = crypto_1.default.createHash("sha256").update(contents).digest("hex");
+    const payloadWithChecksum = JSON.stringify({ ...eventPayload, checksum }, null, 2) + "\n";
+    const targetPath = path_1.default.join(journalDir, filename);
+    await (0, atomic_1.writeFileAtomic)(targetPath, payloadWithChecksum);
+    return { seq, ulid, filename, checksum, path: targetPath, recordedAt };
+}
+function parseJournalFilename(filename) {
+    const [seqPart, ulidPart] = filename.replace(/\.json$/i, "").split(".");
+    const seq = Number(seqPart);
+    if (!Number.isFinite(seq) || !ulidPart) {
+        throw new Error(`Invalid journal filename: ${filename}`);
+    }
+    return { seq, ulid: ulidPart };
+}
+async function loadJournal(runDir) {
+    const journalDir = (0, paths_1.getJournalDir)(runDir);
+    try {
+        const entries = await fs_1.promises.readdir(journalDir);
+        const sorted = entries
+            .filter((name) => name.endsWith(".json"))
+            .sort();
+        const events = [];
+        for (const file of sorted) {
+            const { seq, ulid } = parseJournalFilename(file);
+            const fullPath = path_1.default.join(journalDir, file);
+            const raw = await parseJournalFile(fullPath);
+            events.push({
+                seq,
+                ulid,
+                filename: file,
+                path: fullPath,
+                type: raw.type,
+                recordedAt: typeof raw.recordedAt === "string" ? raw.recordedAt : (0, clock_1.getClockIsoString)(),
+                data: (raw.data ?? {}),
+                checksum: typeof raw.checksum === "string" ? raw.checksum : undefined,
+            });
+        }
+        return events;
+    }
+    catch (error) {
+        const err = error;
+        if (err.code === "ENOENT")
+            return [];
+        throw error;
+    }
+}
+async function parseJournalFile(fullPath) {
+    const contents = await fs_1.promises.readFile(fullPath, "utf8");
+    try {
+        return JSON.parse(contents);
+    }
+    catch (error) {
+        const parseError = new Error(`Failed to parse journal file ${fullPath}: ${error.message}`);
+        parseError.code = "JOURNAL_PARSE_FAILED";
+        parseError.path = fullPath;
+        throw parseError;
+    }
+}

package/dist/storage/lock.d.ts

@@ -0,0 +1,5 @@
+import { RunLockInfo } from "./types";
+export declare function acquireRunLock(runDir: string, owner: string): Promise<RunLockInfo>;
+export declare function releaseRunLock(runDir: string): Promise<void>;
+export declare function readRunLock(runDir: string): Promise<RunLockInfo | null>;
+//# sourceMappingURL=lock.d.ts.map

package/dist/storage/lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lock.d.ts","sourceRoot":"","sources":["../../src/storage/lock.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAItC,wBAAsB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAcxF;AAED,wBAAsB,cAAc,CAAC,MAAM,EAAE,MAAM,iBAGlD;AAED,wBAAsB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAU7E"}

package/dist/storage/lock.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.acquireRunLock = acquireRunLock;
+exports.releaseRunLock = releaseRunLock;
+exports.readRunLock = readRunLock;
+const fs_1 = require("fs");
+const paths_1 = require("./paths");
+const clock_1 = require("./clock");
+async function acquireRunLock(runDir, owner) {
+    const lockPath = (0, paths_1.getLockPath)(runDir);
+    const lockInfo = { pid: process.pid, owner, acquiredAt: (0, clock_1.getClockIsoString)() };
+    try {
+        await fs_1.promises.writeFile(lockPath, JSON.stringify(lockInfo, null, 2) + "\n", { flag: "wx" });
+        return lockInfo;
+    }
+    catch (error) {
+        const err = error;
+        if (err.code === "EEXIST") {
+            const existing = JSON.parse(await fs_1.promises.readFile(lockPath, "utf8"));
+            throw new Error(`run.lock already held by pid ${existing.pid} (${existing.owner})`);
+        }
+        throw err;
+    }
+}
+async function releaseRunLock(runDir) {
+    const lockPath = (0, paths_1.getLockPath)(runDir);
+    await fs_1.promises.rm(lockPath, { force: true });
+}
+async function readRunLock(runDir) {
+    const lockPath = (0, paths_1.getLockPath)(runDir);
+    try {
+        const data = await fs_1.promises.readFile(lockPath, "utf8");
+        return JSON.parse(data);
+    }
+    catch (error) {
+        const err = error;
+        if (err.code === "ENOENT")
+            return null;
+        throw err;
+    }
+}

package/dist/storage/paths.d.ts

@@ -0,0 +1,19 @@
+export declare const JOURNAL_DIR = "journal";
+export declare const TASKS_DIR = "tasks";
+export declare const BLOBS_DIR = "blobs";
+export declare const STATE_DIR = "state";
+export declare const ORPHANED_DIR = "orphaned";
+export declare const PROCESS_DIR = "process";
+export declare const RUN_METADATA_FILE = "run.json";
+export declare const INPUTS_FILE = "inputs.json";
+export declare const LOCK_FILE = "run.lock";
+export declare const STATE_FILE = "state.json";
+export declare const DEFAULT_LAYOUT_VERSION = "2026.01-storage-preview";
+export declare function getRunDir(runsRoot: string, runId: string): string;
+export declare function getJournalDir(runDir: string): string;
+export declare function getTasksDir(runDir: string): string;
+export declare function getBlobsDir(runDir: string): string;
+export declare function getStateDir(runDir: string): string;
+export declare function getStateFile(runDir: string): string;
+export declare function getLockPath(runDir: string): string;
+//# sourceMappingURL=paths.d.ts.map

package/dist/storage/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../src/storage/paths.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,WAAW,YAAY,CAAC;AACrC,eAAO,MAAM,SAAS,UAAU,CAAC;AACjC,eAAO,MAAM,SAAS,UAAU,CAAC;AACjC,eAAO,MAAM,SAAS,UAAU,CAAC;AACjC,eAAO,MAAM,YAAY,aAAa,CAAC;AACvC,eAAO,MAAM,WAAW,YAAY,CAAC;AACrC,eAAO,MAAM,iBAAiB,aAAa,CAAC;AAC5C,eAAO,MAAM,WAAW,gBAAgB,CAAC;AACzC,eAAO,MAAM,SAAS,aAAa,CAAC;AACpC,eAAO,MAAM,UAAU,eAAe,CAAC;AAEvC,eAAO,MAAM,sBAAsB,4BAA4B,CAAC;AAEhE,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAEjE;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAElD;AAED,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAElD;AAED,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAElD;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAElD"}

package/dist/storage/paths.js

@@ -0,0 +1,46 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_LAYOUT_VERSION = exports.STATE_FILE = exports.LOCK_FILE = exports.INPUTS_FILE = exports.RUN_METADATA_FILE = exports.PROCESS_DIR = exports.ORPHANED_DIR = exports.STATE_DIR = exports.BLOBS_DIR = exports.TASKS_DIR = exports.JOURNAL_DIR = void 0;
+exports.getRunDir = getRunDir;
+exports.getJournalDir = getJournalDir;
+exports.getTasksDir = getTasksDir;
+exports.getBlobsDir = getBlobsDir;
+exports.getStateDir = getStateDir;
+exports.getStateFile = getStateFile;
+exports.getLockPath = getLockPath;
+const path_1 = __importDefault(require("path"));
+exports.JOURNAL_DIR = "journal";
+exports.TASKS_DIR = "tasks";
+exports.BLOBS_DIR = "blobs";
+exports.STATE_DIR = "state";
+exports.ORPHANED_DIR = "orphaned";
+exports.PROCESS_DIR = "process";
+exports.RUN_METADATA_FILE = "run.json";
+exports.INPUTS_FILE = "inputs.json";
+exports.LOCK_FILE = "run.lock";
+exports.STATE_FILE = "state.json";
+exports.DEFAULT_LAYOUT_VERSION = "2026.01-storage-preview";
+function getRunDir(runsRoot, runId) {
+    return path_1.default.join(runsRoot, runId);
+}
+function getJournalDir(runDir) {
+    return path_1.default.join(runDir, exports.JOURNAL_DIR);
+}
+function getTasksDir(runDir) {
+    return path_1.default.join(runDir, exports.TASKS_DIR);
+}
+function getBlobsDir(runDir) {
+    return path_1.default.join(runDir, exports.BLOBS_DIR);
+}
+function getStateDir(runDir) {
+    return path_1.default.join(runDir, exports.STATE_DIR);
+}
+function getStateFile(runDir) {
+    return path_1.default.join(getStateDir(runDir), exports.STATE_FILE);
+}
+function getLockPath(runDir) {
+    return path_1.default.join(runDir, exports.LOCK_FILE);
+}

package/dist/storage/runFiles.d.ts

@@ -0,0 +1,5 @@
+import { RunMetadata } from "./types";
+export declare function readRunMetadata(runDir: string): Promise<RunMetadata>;
+export declare function readRunInputs(runDir: string): Promise<unknown | undefined>;
+export declare function writeRunOutput(runDir: string, output: unknown): Promise<string>;
+//# sourceMappingURL=runFiles.d.ts.map

package/dist/storage/runFiles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runFiles.d.ts","sourceRoot":"","sources":["../../src/storage/runFiles.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAKtC,wBAAsB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAI1E;AAED,wBAAsB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC,CAYhF;AAED,wBAAsB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,mBAMnE"}

package/dist/storage/runFiles.js

@@ -0,0 +1,39 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readRunMetadata = readRunMetadata;
+exports.readRunInputs = readRunInputs;
+exports.writeRunOutput = writeRunOutput;
+const fs_1 = require("fs");
+const path_1 = __importDefault(require("path"));
+const paths_1 = require("./paths");
+const atomic_1 = require("./atomic");
+const OUTPUT_FILE = "output.json";
+async function readRunMetadata(runDir) {
+    const metadataPath = path_1.default.join(runDir, paths_1.RUN_METADATA_FILE);
+    const raw = await fs_1.promises.readFile(metadataPath, "utf8");
+    return JSON.parse(raw);
+}
+async function readRunInputs(runDir) {
+    const inputsPath = path_1.default.join(runDir, paths_1.INPUTS_FILE);
+    try {
+        const raw = await fs_1.promises.readFile(inputsPath, "utf8");
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        const err = error;
+        if (err.code === "ENOENT") {
+            return undefined;
+        }
+        throw error;
+    }
+}
+async function writeRunOutput(runDir, output) {
+    const stateDir = path_1.default.join(runDir, paths_1.STATE_DIR);
+    await fs_1.promises.mkdir(stateDir, { recursive: true });
+    const outputPath = path_1.default.join(stateDir, OUTPUT_FILE);
+    await (0, atomic_1.writeFileAtomic)(outputPath, JSON.stringify(output, null, 2) + "\n");
+    return path_1.default.relative(runDir, outputPath).replace(/\\/g, "/");
+}

package/dist/storage/snapshotState.d.ts

@@ -0,0 +1,10 @@
+import { SnapshotStateOptions } from "./types";
+export declare function snapshotState(options: SnapshotStateOptions): Promise<{
+    journalHead: {
+        seq: number;
+        ulid: string;
+    } | null;
+    savedAt: string;
+    state: import("./types").JsonRecord;
+}>;
+//# sourceMappingURL=snapshotState.d.ts.map

package/dist/storage/snapshotState.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshotState.d.ts","sourceRoot":"","sources":["../../src/storage/snapshotState.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AAK/C,wBAAsB,aAAa,CAAC,OAAO,EAAE,oBAAoB;;;;;;;GAQhE"}

package/dist/storage/snapshotState.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.snapshotState = snapshotState;
+const paths_1 = require("./paths");
+const atomic_1 = require("./atomic");
+const clock_1 = require("./clock");
+async function snapshotState(options) {
+    const payload = {
+        journalHead: options.journalHead ?? null,
+        savedAt: (0, clock_1.getClockIsoString)(),
+        state: options.state,
+    };
+    await (0, atomic_1.writeFileAtomic)((0, paths_1.getStateFile)(options.runDir), JSON.stringify(payload, null, 2) + "\n");
+    return payload;
+}

package/dist/storage/storeTaskArtifacts.d.ts

@@ -0,0 +1,6 @@
+import { StoreTaskArtifactsOptions } from "./types";
+export declare function storeTaskArtifacts(options: StoreTaskArtifactsOptions): Promise<{
+    name: string;
+    storedAt: string;
+}[]>;
+//# sourceMappingURL=storeTaskArtifacts.d.ts.map

package/dist/storage/storeTaskArtifacts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storeTaskArtifacts.d.ts","sourceRoot":"","sources":["../../src/storage/storeTaskArtifacts.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,yBAAyB,EAAE,MAAM,SAAS,CAAC;AAoBpD,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,yBAAyB;UAWrC,MAAM;cAAY,MAAM;KAsB7D"}

package/dist/storage/storeTaskArtifacts.js

@@ -0,0 +1,58 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.storeTaskArtifacts = storeTaskArtifacts;
+const fs_1 = require("fs");
+const path_1 = __importDefault(require("path"));
+const paths_1 = require("./paths");
+const atomic_1 = require("./atomic");
+const crypto_1 = __importDefault(require("crypto"));
+const ARTIFACT_SPILL_THRESHOLD = 512 * 1024; // 512 KB
+async function writeArtifact(targetPath, data) {
+    if (typeof data === "string") {
+        await (0, atomic_1.writeFileAtomic)(targetPath, data);
+    }
+    else {
+        await (0, atomic_1.writeFileAtomic)(targetPath, data);
+    }
+}
+function hashBuffer(data) {
+    const buf = typeof data === "string" ? Buffer.from(data) : data;
+    return crypto_1.default.createHash("sha256").update(buf).digest("hex");
+}
+async function storeTaskArtifacts(options) {
+    const taskDir = path_1.default.join((0, paths_1.getTasksDir)(options.runDir), options.effectId);
+    await fs_1.promises.mkdir(taskDir, { recursive: true });
+    if (options.task) {
+        await (0, atomic_1.writeFileAtomic)(path_1.default.join(taskDir, "task.json"), JSON.stringify(options.task, null, 2) + "\n");
+    }
+    if (options.result) {
+        await (0, atomic_1.writeFileAtomic)(path_1.default.join(taskDir, "result.json"), JSON.stringify(options.result, null, 2) + "\n");
+    }
+    const savedArtifacts = [];
+    for (const artifact of options.artifacts ?? []) {
+        const data = typeof artifact.data === "string" ? Buffer.from(artifact.data) : artifact.data;
+        if (data.length > ARTIFACT_SPILL_THRESHOLD) {
+            const hash = hashBuffer(data);
+            const blobPath = path_1.default.join((0, paths_1.getBlobsDir)(options.runDir), hash);
+            try {
+                await fs_1.promises.access(blobPath);
+            }
+            catch (err) {
+                await writeArtifact(blobPath, data);
+            }
+            savedArtifacts.push({ name: artifact.name, storedAt: `blobs/${hash}` });
+        }
+        else {
+            const artifactPath = path_1.default.join(taskDir, "artifacts");
+            await fs_1.promises.mkdir(artifactPath, { recursive: true });
+            const filePath = path_1.default.join(artifactPath, artifact.name);
+            await writeArtifact(filePath, data);
+            savedArtifacts.push({ name: artifact.name, storedAt: `tasks/${options.effectId}/artifacts/${artifact.name}` });
+        }
+    }
+    await (0, atomic_1.writeFileAtomic)(path_1.default.join(taskDir, "artifacts.json"), JSON.stringify(savedArtifacts, null, 2) + "\n");
+    return savedArtifacts;
+}

package/dist/storage/tasks.d.ts

@@ -0,0 +1,17 @@
+import { JsonRecord, StoredTaskResult } from "./types";
+export declare function writeTaskDefinition(runDir: string, effectId: string, taskDef: JsonRecord): Promise<string>;
+export declare function readTaskDefinition(runDir: string, effectId: string): Promise<JsonRecord | undefined>;
+export declare function readTaskResult(runDir: string, effectId: string, resultRef?: string): Promise<StoredTaskResult | undefined>;
+export interface WriteTaskResultOptions {
+    runDir: string;
+    effectId: string;
+    result: StoredTaskResult;
+    stdout?: string;
+    stderr?: string;
+}
+export declare function writeTaskResult(options: WriteTaskResultOptions): Promise<{
+    resultRef: string;
+    stdoutRef: string | undefined;
+    stderrRef: string | undefined;
+}>;
+//# sourceMappingURL=tasks.d.ts.map

package/dist/storage/tasks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tasks.d.ts","sourceRoot":"","sources":["../../src/storage/tasks.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAOvD,wBAAsB,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,mBAM9F;AAED,wBAAsB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC,CAY1G;AAED,wBAAsB,cAAc,CAClC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAAC,CAgBvC;AAED,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,gBAAgB,CAAC;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,wBAAsB,eAAe,CAAC,OAAO,EAAE,sBAAsB;;;;GAuBpE"}

package/dist/storage/tasks.js

@@ -0,0 +1,82 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.writeTaskDefinition = writeTaskDefinition;
+exports.readTaskDefinition = readTaskDefinition;
+exports.readTaskResult = readTaskResult;
+exports.writeTaskResult = writeTaskResult;
+const fs_1 = require("fs");
+const path_1 = __importDefault(require("path"));
+const paths_1 = require("./paths");
+const atomic_1 = require("./atomic");
+function resolveTaskPath(runDir, effectId, relative) {
+    return path_1.default.join((0, paths_1.getTasksDir)(runDir), effectId, relative);
+}
+async function writeTaskDefinition(runDir, effectId, taskDef) {
+    const taskDir = path_1.default.join((0, paths_1.getTasksDir)(runDir), effectId);
+    await fs_1.promises.mkdir(taskDir, { recursive: true });
+    const taskPath = path_1.default.join(taskDir, "task.json");
+    await (0, atomic_1.writeFileAtomic)(taskPath, JSON.stringify(taskDef, null, 2) + "\n");
+    return path_1.default.relative(runDir, taskPath).replace(/\\/g, "/");
+}
+async function readTaskDefinition(runDir, effectId) {
+    const taskPath = resolveTaskPath(runDir, effectId, "task.json");
+    try {
+        const raw = await fs_1.promises.readFile(taskPath, "utf8");
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        const err = error;
+        if (err.code === "ENOENT") {
+            return undefined;
+        }
+        throw error;
+    }
+}
+async function readTaskResult(runDir, effectId, resultRef) {
+    const resolvedPath = resultRef
+        ? path_1.default.isAbsolute(resultRef)
+            ? resultRef
+            : path_1.default.join(runDir, resultRef)
+        : resolveTaskPath(runDir, effectId, "result.json");
+    try {
+        const raw = await fs_1.promises.readFile(resolvedPath, "utf8");
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        const err = error;
+        if (err.code === "ENOENT") {
+            return undefined;
+        }
+        throw error;
+    }
+}
+async function writeTaskResult(options) {
+    const taskDir = path_1.default.join((0, paths_1.getTasksDir)(options.runDir), options.effectId);
+    await fs_1.promises.mkdir(taskDir, { recursive: true });
+    const resultPath = path_1.default.join(taskDir, "result.json");
+    const relativeResultPath = path_1.default.relative(options.runDir, resultPath).replace(/\\/g, "/");
+    const stdoutRef = await writeTextIfProvided(options.runDir, options.effectId, "stdout.log", options.stdout);
+    const stderrRef = await writeTextIfProvided(options.runDir, options.effectId, "stderr.log", options.stderr);
+    if (stdoutRef && !options.result.stdoutRef) {
+        options.result.stdoutRef = stdoutRef;
+    }
+    if (stderrRef && !options.result.stderrRef) {
+        options.result.stderrRef = stderrRef;
+    }
+    await (0, atomic_1.writeFileAtomic)(resultPath, JSON.stringify(options.result, null, 2) + "\n");
+    return {
+        resultRef: relativeResultPath,
+        stdoutRef,
+        stderrRef,
+    };
+}
+async function writeTextIfProvided(runDir, effectId, filename, contents) {
+    if (typeof contents !== "string")
+        return undefined;
+    const filePath = resolveTaskPath(runDir, effectId, filename);
+    await (0, atomic_1.writeFileAtomic)(filePath, contents);
+    return path_1.default.relative(runDir, filePath).replace(/\\/g, "/");
+}

package/dist/storage/types.d.ts

@@ -0,0 +1,112 @@
+import { Stats } from "fs";
+export type JsonRecord = Record<string, unknown>;
+export interface RunEntrypointMetadata {
+    importPath: string;
+    exportName: string;
+}
+export interface RunMetadata extends JsonRecord {
+    runId: string;
+    request: string;
+    processId: string;
+    entrypoint: RunEntrypointMetadata;
+    processPath?: string;
+    processRevision?: string;
+    layoutVersion: string;
+    createdAt: string;
+}
+export interface CreateRunDirOptions {
+    runsRoot: string;
+    runId: string;
+    request: string;
+    processId?: string;
+    entrypoint?: {
+        importPath: string;
+        exportName?: string;
+    };
+    processPath?: string;
+    processRevision?: string;
+    layoutVersion?: string;
+    inputs?: unknown;
+    extraMetadata?: Record<string, unknown>;
+}
+export interface AppendEventOptions {
+    runDir: string;
+    event: JsonRecord;
+    eventType: string;
+}
+export interface AppendEventResult {
+    seq: number;
+    ulid: string;
+    filename: string;
+    checksum: string;
+    path: string;
+    recordedAt: string;
+}
+export interface SnapshotStateOptions {
+    runDir: string;
+    state: JsonRecord;
+    journalHead?: {
+        seq: number;
+        ulid: string;
+    };
+}
+export interface StoreTaskArtifactsOptions {
+    runDir: string;
+    effectId: string;
+    task?: JsonRecord;
+    result?: JsonRecord;
+    artifacts?: Array<{
+        name: string;
+        data: Buffer | string;
+    }>;
+}
+export interface DiskUsageReport {
+    totalBytes: number;
+    journalBytes: number;
+    tasksBytes: number;
+    blobsBytes: number;
+    stateBytes: number;
+}
+export interface OrphanedBlobInfo {
+    hash: string;
+    bytes: number;
+    path: string;
+}
+export interface RunLockInfo {
+    pid: number;
+    owner: string;
+    acquiredAt: string;
+}
+export type FileStatGetter = (path: string) => Promise<Stats>;
+export interface JournalEvent {
+    seq: number;
+    ulid: string;
+    filename: string;
+    path: string;
+    type: string;
+    recordedAt: string;
+    data: JsonRecord;
+    checksum?: string;
+}
+export interface StoredTaskResult {
+    schemaVersion: string;
+    effectId: string;
+    taskId: string;
+    invocationKey: string;
+    status: "ok" | "error";
+    result?: unknown;
+    value?: unknown;
+    resultRef?: string;
+    error?: {
+        name?: string;
+        message?: string;
+        stack?: string;
+        data?: unknown;
+    };
+    stdoutRef?: string;
+    stderrRef?: string;
+    startedAt?: string;
+    finishedAt?: string;
+    metadata?: JsonRecord;
+}
+//# sourceMappingURL=types.d.ts.map

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

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

package/dist/storage/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });