@a5c-ai/babysitter-sdk 0.0.16

package/dist/testing/deterministic.js

@@ -0,0 +1,449 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withDeterministicIds = withDeterministicIds;
+exports.withFixedClock = withFixedClock;
+exports.createTempDeterministicRun = createTempDeterministicRun;
+exports.snapshotRunState = snapshotRunState;
+exports.installFixedClock = installFixedClock;
+exports.installDeterministicUlids = installDeterministicUlids;
+exports.createDeterministicRunHarness = createDeterministicRunHarness;
+const fs_1 = require("fs");
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+const journal_1 = require("../storage/journal");
+const createRunDir_1 = require("../storage/createRunDir");
+const ulids_1 = require("../storage/ulids");
+const clock_1 = require("../storage/clock");
+const stateCache_1 = require("../runtime/replay/stateCache");
+const CROCKFORD_BASE32 = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+const DEFAULT_CLOCK_START_MS = Date.UTC(2025, 0, 1, 0, 0, 0, 0);
+const DEFAULT_CLOCK_STEP_MS = 1000;
+const TEMP_RUN_PREFIX = "babysitter-deterministic-run-";
+const DEFAULT_DETERMINISTIC_RUN_ID = "det-run-0001";
+async function withDeterministicIds(sequence, fn) {
+    if (!Array.isArray(sequence) || sequence.length === 0) {
+        throw new Error("withDeterministicIds requires a non-empty sequence");
+    }
+    const handle = installDeterministicUlids({ preset: sequence });
+    handle.apply();
+    try {
+        return await fn();
+    }
+    finally {
+        handle.restore();
+    }
+}
+async function withFixedClock(sequenceOrValue, fn) {
+    const handle = installFixedClock({ sequence: sequenceOrValue });
+    handle.apply();
+    try {
+        return await fn();
+    }
+    finally {
+        handle.restore();
+    }
+}
+async function createTempDeterministicRun(options) {
+    if (!options.processSource || !options.processSource.trim()) {
+        throw new Error("createTempDeterministicRun requires processSource contents");
+    }
+    const runsRoot = await fs_1.promises.mkdtemp(path_1.default.join(os_1.default.tmpdir(), TEMP_RUN_PREFIX));
+    const runId = options.runId ?? DEFAULT_DETERMINISTIC_RUN_ID;
+    const request = options.request ?? "deterministic-test";
+    const clock = installFixedClock(options.clock !== undefined ? { sequence: options.clock } : undefined);
+    const ulids = installDeterministicUlids(options.ulids && options.ulids.length > 0 ? { preset: options.ulids } : undefined);
+    clock.apply();
+    ulids.apply();
+    let restored = false;
+    function restoreProviders() {
+        if (restored)
+            return;
+        restored = true;
+        try {
+            ulids.restore();
+        }
+        finally {
+            clock.restore();
+        }
+    }
+    async function cleanupRoot() {
+        restoreProviders();
+        await fs_1.promises.rm(runsRoot, { recursive: true, force: true });
+    }
+    try {
+        const processPath = await writeProcessFixture(runsRoot, runId, options.processSource);
+        const { runDir } = await (0, createRunDir_1.createRunDir)({
+            runsRoot,
+            runId,
+            request,
+            processPath,
+            inputs: options.inputs,
+        });
+        await (0, journal_1.appendEvent)({
+            runDir,
+            eventType: "RUN_CREATED",
+            event: { runId, request },
+        });
+        return {
+            runDir,
+            restore: restoreProviders,
+            async cleanup() {
+                await cleanupRoot();
+            },
+        };
+    }
+    catch (error) {
+        await cleanupRoot().catch(() => undefined);
+        throw error;
+    }
+}
+async function snapshotRunState(runDir) {
+    const events = await (0, journal_1.loadJournal)(runDir);
+    const journal = events.map((event) => ({
+        seq: event.seq,
+        ulid: event.ulid,
+        recordedAt: event.recordedAt,
+        type: event.type,
+        data: event.data,
+    }));
+    const state = await (0, stateCache_1.readStateCache)(runDir);
+    const stateSummary = state
+        ? {
+            savedAt: state.savedAt,
+            stateVersion: state.stateVersion,
+            journalHead: state.journalHead ?? null,
+            pendingEffectsByKind: state.pendingEffectsByKind,
+            effectsByInvocation: state.effectsByInvocation,
+            rebuildReason: state.rebuildReason ?? null,
+        }
+        : null;
+    return { journal, state: stateSummary };
+}
+function installFixedClock(options) {
+    const controller = createClockController(options);
+    let depth = 0;
+    let release = null;
+    function apply() {
+        depth += 1;
+        if (depth === 1) {
+            release = applyClockController(controller);
+        }
+        return () => {
+            if (depth === 0) {
+                return;
+            }
+            depth -= 1;
+            if (depth === 0 && release) {
+                release();
+                release = null;
+            }
+        };
+    }
+    function restore() {
+        depth = 0;
+        if (release) {
+            release();
+            release = null;
+        }
+        else {
+            (0, clock_1.resetClock)();
+        }
+    }
+    return {
+        now: () => controller.now(),
+        advance: (ms) => controller.advance(ms),
+        reset: () => controller.reset(),
+        timestamp: () => controller.timestamp(),
+        apply,
+        restore,
+    };
+}
+function installDeterministicUlids(options) {
+    const issued = [];
+    const controller = createUlidController(options);
+    let depth = 0;
+    let release = null;
+    function next() {
+        const value = controller.next();
+        issued.push(value);
+        return value;
+    }
+    function apply() {
+        depth += 1;
+        if (depth === 1) {
+            (0, ulids_1.setUlidFactoryForTests)(() => next());
+            release = () => {
+                (0, ulids_1.resetUlidFactory)();
+            };
+        }
+        return () => {
+            if (depth === 0) {
+                return;
+            }
+            depth -= 1;
+            if (depth === 0 && release) {
+                release();
+                release = null;
+            }
+        };
+    }
+    function restore() {
+        depth = 0;
+        if (release) {
+            release();
+            release = null;
+        }
+        else {
+            (0, ulids_1.resetUlidFactory)();
+        }
+    }
+    return {
+        issued,
+        next,
+        reset() {
+            issued.length = 0;
+            controller.reset();
+        },
+        apply,
+        restore,
+    };
+}
+async function createDeterministicRunHarness(options) {
+    if (!options.processPath && !options.processSource) {
+        throw new Error("createDeterministicRunHarness requires processPath or processSource");
+    }
+    const runsRoot = await fs_1.promises.mkdtemp(path_1.default.join(os_1.default.tmpdir(), TEMP_RUN_PREFIX));
+    const runId = options.runId ?? DEFAULT_DETERMINISTIC_RUN_ID;
+    const request = options.request ?? "deterministic-test";
+    const clock = installFixedClock(options.clock);
+    const ulids = installDeterministicUlids(options.ulids);
+    clock.apply();
+    ulids.apply();
+    let cleanedUp = false;
+    async function cleanupRoot() {
+        if (cleanedUp)
+            return;
+        cleanedUp = true;
+        try {
+            ulids.restore();
+        }
+        finally {
+            clock.restore();
+        }
+        await fs_1.promises.rm(runsRoot, { recursive: true, force: true });
+    }
+    try {
+        const processPath = options.processPath ?? (await writeProcessFixture(runsRoot, runId, options.processSource));
+        const entrypoint = options.exportName || !options.processSource
+            ? {
+                importPath: processPath,
+                exportName: options.exportName ?? "process",
+            }
+            : undefined;
+        const { runDir } = await (0, createRunDir_1.createRunDir)({
+            runsRoot,
+            runId,
+            request,
+            processPath,
+            entrypoint,
+            inputs: options.inputs,
+        });
+        await (0, journal_1.appendEvent)({
+            runDir,
+            eventType: "RUN_CREATED",
+            event: { runId, request },
+        });
+        return {
+            runId,
+            runDir,
+            runsRoot,
+            clock,
+            ulids,
+            async cleanup() {
+                await cleanupRoot();
+            },
+        };
+    }
+    catch (error) {
+        await cleanupRoot().catch(() => undefined);
+        throw error;
+    }
+}
+function createClockController(options) {
+    if (options?.sequence !== undefined) {
+        const sequence = normalizeClockSequence(options.sequence);
+        return createSequenceClockController(sequence);
+    }
+    const start = resolveClockStart(options?.start);
+    const stepMs = options?.stepMs ?? DEFAULT_CLOCK_STEP_MS;
+    return createTickingClockController(start, stepMs);
+}
+function createSequenceClockController(sequence) {
+    if (sequence.length === 0) {
+        throw new Error("Clock sequence must include at least one entry");
+    }
+    let index = 0;
+    function currentIndex() {
+        return Math.min(index, sequence.length - 1);
+    }
+    function clone(date) {
+        return new Date(date.getTime());
+    }
+    return {
+        issue() {
+            const value = clone(sequence[currentIndex()]);
+            if (index < sequence.length - 1) {
+                index += 1;
+            }
+            return value;
+        },
+        now() {
+            return clone(sequence[currentIndex()]);
+        },
+        advance() {
+            if (index < sequence.length - 1) {
+                index += 1;
+            }
+            return clone(sequence[currentIndex()]);
+        },
+        reset() {
+            index = 0;
+        },
+        timestamp() {
+            return sequence[currentIndex()].getTime();
+        },
+    };
+}
+function createTickingClockController(startMs, stepMs) {
+    if (!Number.isFinite(stepMs) || stepMs <= 0) {
+        throw new Error("stepMs must be a positive finite number");
+    }
+    const initial = startMs;
+    let current = startMs;
+    return {
+        issue() {
+            const value = new Date(current);
+            current += stepMs;
+            return value;
+        },
+        now() {
+            return new Date(current);
+        },
+        advance(ms = stepMs) {
+            if (!Number.isFinite(ms)) {
+                throw new Error("advance requires a finite number of milliseconds");
+            }
+            current += ms;
+            return new Date(current);
+        },
+        reset() {
+            current = initial;
+        },
+        timestamp() {
+            return current;
+        },
+    };
+}
+function applyClockController(controller) {
+    (0, clock_1.setClockForTests)(() => controller.issue());
+    return () => {
+        (0, clock_1.resetClock)();
+    };
+}
+function createUlidController(options) {
+    if (options?.preset && options.preset.length > 0) {
+        return createPresetUlidController(options.preset);
+    }
+    const epochMs = options?.epochMs ?? DEFAULT_CLOCK_START_MS;
+    const incrementMs = options?.incrementMs ?? DEFAULT_CLOCK_STEP_MS;
+    const randomnessSeed = options?.randomnessSeed ?? 0;
+    return createRollingUlidController(epochMs, incrementMs, randomnessSeed);
+}
+function createPresetUlidController(preset) {
+    let index = 0;
+    return {
+        next() {
+            const value = preset[index];
+            if (value === undefined) {
+                throw new Error("Deterministic ULID preset exhausted");
+            }
+            index += 1;
+            return value;
+        },
+        reset() {
+            index = 0;
+        },
+    };
+}
+function createRollingUlidController(epochMs, incrementMs, randomnessSeed) {
+    let tick = 0;
+    return {
+        next() {
+            const timestamp = epochMs + tick * incrementMs;
+            const timePart = encodeBase32(timestamp, 10);
+            const randomPart = encodeBase32(randomnessSeed + tick, 16);
+            tick += 1;
+            return `${timePart}${randomPart}`;
+        },
+        reset() {
+            tick = 0;
+        },
+    };
+}
+async function writeProcessFixture(runsRoot, runId, source) {
+    if (!source.trim()) {
+        throw new Error("processSource must be non-empty");
+    }
+    const processDir = path_1.default.join(runsRoot, "processes");
+    await fs_1.promises.mkdir(processDir, { recursive: true });
+    const processPath = path_1.default.join(processDir, `${runId}.mjs`);
+    await fs_1.promises.writeFile(processPath, source, "utf8");
+    return processPath;
+}
+function normalizeClockSequence(input) {
+    if (Array.isArray(input)) {
+        if (input.length === 0) {
+            throw new Error("Clock sequence must not be empty");
+        }
+        return input.map(toClockDate);
+    }
+    return [toClockDate(input)];
+}
+function toClockDate(value) {
+    if (value instanceof Date) {
+        return new Date(value.getTime());
+    }
+    if (typeof value === "number") {
+        if (!Number.isFinite(value)) {
+            throw new Error("Clock numeric value must be finite");
+        }
+        return new Date(value);
+    }
+    if (typeof value === "string") {
+        const parsed = Date.parse(value);
+        if (!Number.isFinite(parsed)) {
+            throw new Error(`Invalid clock string: ${value}`);
+        }
+        return new Date(parsed);
+    }
+    throw new Error("Invalid clock value");
+}
+function resolveClockStart(start) {
+    if (start === undefined) {
+        return DEFAULT_CLOCK_START_MS;
+    }
+    return toClockDate(start).getTime();
+}
+function encodeBase32(value, length) {
+    let remaining = Math.max(0, Math.floor(value));
+    let out = "";
+    while (out.length < length) {
+        const idx = remaining % 32;
+        out = CROCKFORD_BASE32[idx] + out;
+        remaining = Math.floor(remaining / 32);
+    }
+    return out.slice(-length);
+}

package/dist/testing/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./runHarness";
+export * from "./deterministic";
+export { captureRunSnapshot, readJournalSnapshot, readStateSnapshot, type RunSnapshot, type JournalSnapshotEntry } from "./snapshots";
+//# sourceMappingURL=index.d.ts.map

package/dist/testing/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,KAAK,WAAW,EAAE,KAAK,oBAAoB,EAAE,MAAM,aAAa,CAAC"}

package/dist/testing/index.js

@@ -0,0 +1,23 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readStateSnapshot = exports.readJournalSnapshot = exports.captureRunSnapshot = void 0;
+__exportStar(require("./runHarness"), exports);
+__exportStar(require("./deterministic"), exports);
+var snapshots_1 = require("./snapshots");
+Object.defineProperty(exports, "captureRunSnapshot", { enumerable: true, get: function () { return snapshots_1.captureRunSnapshot; } });
+Object.defineProperty(exports, "readJournalSnapshot", { enumerable: true, get: function () { return snapshots_1.readJournalSnapshot; } });
+Object.defineProperty(exports, "readStateSnapshot", { enumerable: true, get: function () { return snapshots_1.readStateSnapshot; } });

package/dist/testing/runHarness.d.ts

@@ -0,0 +1,64 @@
+import type { EffectAction, IterationMetadata, IterationResult, ProcessLogger, EffectSchedulerHints } from "../runtime/types";
+import type { JsonRecord } from "../storage/types";
+import type { DeterministicUlidHandle, FixedClockHandle } from "./deterministic";
+export interface FakeActionSuccess {
+    status: "ok";
+    value?: unknown;
+    stdout?: string;
+    stderr?: string;
+    metadata?: JsonRecord;
+    startedAt?: string;
+    finishedAt?: string;
+}
+export interface FakeActionError {
+    status: "error";
+    error: unknown;
+    stdout?: string;
+    stderr?: string;
+    metadata?: JsonRecord;
+    startedAt?: string;
+    finishedAt?: string;
+}
+export type FakeActionResolution = FakeActionSuccess | FakeActionError;
+export type FakeActionResolver = ((action: EffectAction) => FakeActionResolution | undefined | Promise<FakeActionResolution | undefined>);
+export interface RunToCompletionWithFakeRunnerOptions {
+    runDir: string;
+    resolve: FakeActionResolver;
+    maxIterations?: number;
+    logger?: ProcessLogger;
+    onIteration?: (iteration: IterationResult) => void | Promise<void>;
+    now?: Date | (() => Date);
+    clock?: FixedClockHandle;
+    ulids?: DeterministicUlidHandle;
+}
+export interface ExecutedFakeAction {
+    action: EffectAction;
+    resolution: FakeActionResolution;
+}
+export interface RunToCompletionResult {
+    status: "completed" | "failed" | "waiting";
+    output?: unknown;
+    error?: unknown;
+    pending?: EffectAction[];
+    metadata: IterationMetadata | null;
+    iterations: number;
+    executed: ExecutedFakeAction[];
+    executionLog: HarnessIterationLogEntry[];
+}
+export interface HarnessIterationLogEntry {
+    iteration: number;
+    status: IterationResult["status"];
+    metadata: IterationMetadata | null;
+    pending: HarnessActionSnapshot[];
+    executed: HarnessActionSnapshot[];
+}
+export interface HarnessActionSnapshot {
+    effectId: string;
+    invocationKey: string;
+    taskId?: string;
+    stepId?: string;
+    kind?: string;
+    schedulerHints?: EffectSchedulerHints;
+}
+export declare function runToCompletionWithFakeRunner(options: RunToCompletionWithFakeRunnerOptions): Promise<RunToCompletionResult>;
+//# sourceMappingURL=runHarness.d.ts.map

package/dist/testing/runHarness.d.ts.map

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