clinkx 0.2.0 → 0.2.1

package/clinkx-workflows/dist/state.js

@@ -0,0 +1,838 @@
+import { createHash } from "node:crypto";
+import { execFileSync } from "node:child_process";
+import { mkdir, open, readFile, rename, rm, stat, unlink, writeFile } from "node:fs/promises";
+import { dirname, basename, isAbsolute, join, relative, resolve } from "node:path";
+import { hostname } from "node:os";
+import { fileURLToPath } from "node:url";
+import { WorkflowError } from "./errors.js";
+import { buildFidelityMetadata, } from "./fidelity.js";
+import { fingerprintsMatch, generateFingerprint, generateWorkflowFingerprint, } from "./fingerprint.js";
+import { deriveAllowedRoots, getArtifactsDir, getChildConfigPath, getChildMaxConcurrent, getChildMaxOutputBytes, getChildMaxPromptBytes, getChildMaxResponseChars, getLogLevel, getRunStateDir, getStateDir, resolveWorkspaceRoot, } from "./config.js";
+import { logger } from "./logger.js";
+const STATE_FILENAME = "state.json";
+const STATE_TMP_FILENAME = "state.json.tmp";
+const WORKFLOW_SNAPSHOT_FILENAME = "workflow.snapshot.json";
+const INPUTS_SNAPSHOT_FILENAME = "inputs.snapshot.json";
+const CHILD_CONFIG_DIRNAME = "child-config";
+const CHILD_CONFIG_SNAPSHOT_FILENAME = "snapshot.json";
+const RUN_LOCK_FILENAME = "run.lock";
+const OUTPUT_INLINE_THRESHOLD_BYTES = 10 * 1024;
+export class WorkflowStateStore {
+    runDir;
+    definition;
+    variables;
+    hooks;
+    resume;
+    state;
+    lockPath;
+    debugKeepArtifacts;
+    writeChain = Promise.resolve();
+    lockHeld = true;
+    constructor(options) {
+        this.runDir = options.runDir;
+        this.definition = options.definition;
+        this.variables = options.variables;
+        this.state = options.state;
+        this.resume = options.resume;
+        this.debugKeepArtifacts = options.debugKeepArtifacts;
+        this.lockPath = join(options.runDir, RUN_LOCK_FILENAME);
+        this.hooks = {
+            onRunStateChange: async (event) => {
+                await this.enqueueWrite(async () => {
+                    const nextState = structuredClone(this.state);
+                    nextState.status = event.state;
+                    nextState.startedAt = event.startedAt ?? nextState.startedAt;
+                    nextState.completedAt = event.completedAt;
+                    nextState.error = event.error;
+                    nextState.failureClass = event.failureClass;
+                    this.state = nextState;
+                    await this.writeState();
+                });
+            },
+            onCallPrepared: async (event) => {
+                await this.enqueueWrite(async () => {
+                    const inputPath = `${event.stageId}.${event.callId}.input.json`;
+                    await writeJsonAtomic(join(this.runDir, inputPath), event.input);
+                    const nextState = structuredClone(this.state);
+                    const callEntry = getCallEntry(nextState, event.stageId, event.callId);
+                    callEntry.materializedInputPath = inputPath;
+                    callEntry.contextProducing = event.contextProducing;
+                    callEntry.retryCount = event.retryCount;
+                    this.state = nextState;
+                    await this.writeState();
+                });
+            },
+            onCallStateChange: async (event) => {
+                await this.enqueueWrite(async () => {
+                    const nextState = structuredClone(this.state);
+                    const callEntry = getCallEntry(nextState, event.stageId, event.callId);
+                    callEntry.state = event.state;
+                    callEntry.retryCount = event.retryCount;
+                    callEntry.startedAt = event.startedAt;
+                    callEntry.completedAt = event.completedAt;
+                    callEntry.durationMs = event.durationMs;
+                    callEntry.errorMessage = event.error;
+                    callEntry.failureClass = event.failureClass;
+                    callEntry.childDebugMetadata = event.childDebugMetadata;
+                    callEntry.contextProducing = callEntry.contextProducing ?? false;
+                    if (event.outputText != null) {
+                        const { outputInline, outputPath } = await persistOutput(this.runDir, event.stageId, event.callId, event.outputText);
+                        callEntry.outputInline = outputInline;
+                        callEntry.outputPath = outputPath;
+                    }
+                    if (event.artifact != null) {
+                        callEntry.artifactPath = relative(this.runDir, event.artifact.filePath);
+                    }
+                    if (event.fidelity != null) {
+                        callEntry.fidelity = buildPersistedFidelity(event.fidelity, callEntry.contextProducing ?? false);
+                    }
+                    for (const stageEntry of nextState.stages) {
+                        stageEntry.state = deriveStageState(stageEntry.calls);
+                        stageEntry.startedAt = stageEntry.calls.find((call) => call.startedAt != null)?.startedAt;
+                        stageEntry.completedAt = deriveStageCompletedAt(stageEntry.calls);
+                    }
+                    this.state = nextState;
+                    await this.writeState();
+                });
+            },
+            onRetryScheduled: async (event) => {
+                await this.applyRetryUpdate(event);
+            },
+        };
+    }
+    static async create(options) {
+        const runDir = options.runDir ?? getRunStateDir(options.runId);
+        const debugKeepArtifacts = options.debugKeepArtifacts ?? false;
+        const recycled = await prepareRunDirForCreate(runDir, options.runId);
+        let lockHeld = false;
+        try {
+            await acquireRunLock(runDir);
+            lockHeld = true;
+            const workflowSnapshotHash = await writeJsonSnapshot(join(runDir, WORKFLOW_SNAPSHOT_FILENAME), options.definition);
+            const inputsSnapshotHash = await writeJsonSnapshot(join(runDir, INPUTS_SNAPSHOT_FILENAME), options.variables);
+            const childConfigPath = getChildConfigPath();
+            const resumable = childConfigPath != null;
+            const fingerprintData = resumable
+                ? await buildChildConfigFingerprint(options.definition)
+                : undefined;
+            if (fingerprintData != null) {
+                const childConfigDir = join(runDir, CHILD_CONFIG_DIRNAME);
+                await mkdir(childConfigDir, { recursive: true });
+                await writeJsonAtomic(join(childConfigDir, CHILD_CONFIG_SNAPSHOT_FILENAME), fingerprintData.snapshot);
+            }
+            const state = {
+                state_version: 1,
+                runId: options.runId,
+                workflowName: options.definition.name,
+                workflowVersion: options.definition.version,
+                status: "pending",
+                resumable,
+                fingerprint: fingerprintData?.fingerprint,
+                workflowSnapshotPath: WORKFLOW_SNAPSHOT_FILENAME,
+                workflowSnapshotHash,
+                inputsSnapshotPath: INPUTS_SNAPSHOT_FILENAME,
+                inputsSnapshotHash,
+                childConfigSnapshotPath: fingerprintData != null
+                    ? join(CHILD_CONFIG_DIRNAME, CHILD_CONFIG_SNAPSHOT_FILENAME)
+                    : undefined,
+                stages: options.definition.stages.map((stage) => ({
+                    stageId: stage.id,
+                    state: "pending",
+                    calls: stage.calls.map((call) => ({
+                        stageId: stage.id,
+                        callId: call.id,
+                        state: "pending",
+                        retryCount: 0,
+                        contextProducing: isContextProducing(options.definition, stage.id, call.id),
+                    })),
+                })),
+                variables: options.variables,
+                debugKeepArtifacts,
+            };
+            await writeJsonAtomic(join(runDir, STATE_FILENAME), state);
+            if (recycled) {
+                await rm(`${runDir}.recycled`, { recursive: true, force: true }).catch(() => { });
+            }
+            return new WorkflowStateStore({
+                runDir,
+                definition: options.definition,
+                variables: options.variables,
+                state,
+                resume: {},
+                debugKeepArtifacts,
+            });
+        }
+        catch (error) {
+            if (lockHeld) {
+                await safeUnlink(join(runDir, RUN_LOCK_FILENAME));
+            }
+            if (recycled) {
+                try {
+                    await rm(runDir, { recursive: true, force: true });
+                    await rename(`${runDir}.recycled`, runDir);
+                }
+                catch {
+                    // Best effort — if both are gone, nothing we can do
+                }
+            }
+            else {
+                await rm(runDir, { recursive: true, force: true }).catch(() => { });
+            }
+            throw error;
+        }
+    }
+    static async resume(options) {
+        const runDir = options.runDir ?? getRunStateDir(options.runId);
+        const debugKeepArtifacts = options.debugKeepArtifacts ?? false;
+        await acquireRunLock(runDir);
+        try {
+            const state = await readRunState(runDir);
+            if (!state.resumable) {
+                throw new Error(`Run ${options.runId} is non-resumable because it was started from ambient child config`);
+            }
+            const workflowSnapshotPath = join(runDir, state.workflowSnapshotPath ?? WORKFLOW_SNAPSHOT_FILENAME);
+            const inputsSnapshotPath = join(runDir, state.inputsSnapshotPath ?? INPUTS_SNAPSHOT_FILENAME);
+            const definition = await readJsonFile(workflowSnapshotPath);
+            const variables = await readJsonFile(inputsSnapshotPath);
+            await verifySnapshotHash(workflowSnapshotPath, state.workflowSnapshotHash, "workflow snapshot");
+            await verifySnapshotHash(inputsSnapshotPath, state.inputsSnapshotHash, "inputs snapshot");
+            if (state.fingerprint == null) {
+                throw new Error(`Run ${options.runId} is missing a persisted fingerprint and cannot be resumed`);
+            }
+            // Verify fingerprint from persisted snapshot (self-contained, no live config dependency)
+            if (state.childConfigSnapshotPath == null) {
+                throw new Error(`Run ${options.runId} is missing a persisted child-config snapshot and cannot be resumed`);
+            }
+            const snapshotPath = join(runDir, state.childConfigSnapshotPath);
+            let persistedSnapshot;
+            try {
+                persistedSnapshot = await readJsonFile(snapshotPath);
+            }
+            catch (err) {
+                throw new Error(`Run ${options.runId} has a corrupted or missing child-config snapshot at ${snapshotPath}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            const snapshotFingerprint = generateFingerprint(persistedSnapshot);
+            if (!fingerprintsMatch(state.fingerprint, snapshotFingerprint)) {
+                throw new Error(`Run ${options.runId} fingerprint does not match persisted snapshot. The snapshot may be corrupted; start a new run instead.`);
+            }
+            // Also verify live config hasn't drifted from original run
+            const childConfigPath = getChildConfigPath();
+            if (childConfigPath != null) {
+                const currentFingerprint = await buildChildConfigFingerprint(definition);
+                if (!fingerprintsMatch(state.fingerprint, currentFingerprint.fingerprint)) {
+                    throw new Error(`Run ${options.runId} cannot be resumed: live child config at ${childConfigPath} has changed since the original run. ` +
+                        `Restore the original config or start a new run.`);
+                }
+            }
+            else {
+                // Live config path is missing but run was created with one
+                throw new Error(`Run ${options.runId} cannot be resumed: CLINKX_WORKFLOWS_CHILD_CONFIG_PATH is not set but the original run required it for child spawning.`);
+            }
+            const recovered = structuredClone(state);
+            const recoveredAt = new Date().toISOString();
+            let mutated = false;
+            if (recovered.status === "running") {
+                recovered.status = "failed";
+                recovered.completedAt = recoveredAt;
+                recovered.error = "Recovered stale running run during resume";
+                recovered.failureClass = "transient";
+                mutated = true;
+            }
+            for (const stage of recovered.stages) {
+                for (const call of stage.calls) {
+                    if (call.state === "running") {
+                        call.state = "failed";
+                        call.completedAt = recoveredAt;
+                        call.errorMessage = "Recovered stale running call during resume";
+                        call.failureClass = "transient";
+                        mutated = true;
+                    }
+                }
+                stage.state = deriveStageState(stage.calls);
+                stage.completedAt = deriveStageCompletedAt(stage.calls);
+            }
+            if (mutated) {
+                await writeJsonAtomic(join(runDir, STATE_FILENAME), recovered);
+            }
+            const resume = await buildResumeState(definition, recovered, runDir);
+            return new WorkflowStateStore({
+                runDir,
+                definition,
+                variables,
+                state: recovered,
+                resume,
+                debugKeepArtifacts,
+            });
+        }
+        catch (error) {
+            await safeUnlink(join(runDir, RUN_LOCK_FILENAME));
+            throw error;
+        }
+    }
+    get runState() {
+        return structuredClone(this.state);
+    }
+    async markCancelled(reason = "Workflow cancelled") {
+        await this.enqueueWrite(async () => {
+            const nextState = structuredClone(this.state);
+            nextState.status = "cancelled";
+            nextState.completedAt = new Date().toISOString();
+            nextState.error = reason;
+            this.state = nextState;
+            await this.writeState();
+        });
+    }
+    async flush() {
+        await this.writeChain;
+    }
+    async close() {
+        await this.flush();
+        if (this.state.status === "succeeded" && !this.debugKeepArtifacts) {
+            this.lockHeld = false;
+            await rm(this.runDir, { recursive: true, force: true });
+            return;
+        }
+        if (this.lockHeld) {
+            await safeUnlink(this.lockPath);
+            this.lockHeld = false;
+        }
+    }
+    async applyRetryUpdate(event) {
+        await this.enqueueWrite(async () => {
+            const nextState = structuredClone(this.state);
+            const callEntry = getCallEntry(nextState, event.stageId, event.callId);
+            callEntry.retryCount = event.nextRetryCount;
+            callEntry.errorMessage = event.error;
+            callEntry.failureClass = event.failureClass;
+            this.state = nextState;
+            await this.writeState();
+        });
+    }
+    async enqueueWrite(task) {
+        const next = this.writeChain.then(task, task);
+        this.writeChain = next.catch(() => { });
+        await next;
+    }
+    async writeState() {
+        await writeJsonAtomic(join(this.runDir, STATE_FILENAME), this.state);
+    }
+}
+async function prepareRunDirForCreate(runDir, runId) {
+    await mkdir(dirname(runDir), { recursive: true });
+    try {
+        await mkdir(runDir);
+        return false;
+    }
+    catch (error) {
+        if (!(error instanceof Error) || !("code" in error) || error.code !== "EEXIST") {
+            throw error;
+        }
+    }
+    const recycled = await recycleSucceededRunDir(runDir);
+    if (recycled) {
+        const recycledPath = `${runDir}.recycled`;
+        try {
+            await mkdir(runDir);
+        }
+        catch (error) {
+            if (error instanceof Error && "code" in error && error.code === "EEXIST") {
+                throw duplicateRunDirError(runId);
+            }
+            try {
+                await rename(recycledPath, runDir);
+            }
+            catch {
+                logger.warn({ recycledPath }, "failed to restore recycled directory after mkdir failure");
+            }
+            throw error;
+        }
+        return true;
+    }
+    throw duplicateRunDirError(runId);
+}
+function duplicateRunDirError(runId) {
+    return new WorkflowError(`Run directory for run_id "${runId}" already exists. Use a unique run_id for new runs. If this is a failed/cancelled resumable run, try resume_workflow.`);
+}
+async function recycleSucceededRunDir(runDir) {
+    const lockPath = join(runDir, RUN_LOCK_FILENAME);
+    let lockHeld = false;
+    try {
+        await acquireRunLock(runDir);
+        lockHeld = true;
+    }
+    catch {
+        return false;
+    }
+    try {
+        const state = await readRunState(runDir);
+        if (state.status !== "succeeded") {
+            return false;
+        }
+        await rename(runDir, `${runDir}.recycled`);
+        lockHeld = false;
+        return true;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        if (lockHeld) {
+            await safeUnlink(lockPath);
+        }
+    }
+}
+function getCallEntry(state, stageId, callId) {
+    const stage = state.stages.find((entry) => entry.stageId === stageId);
+    if (stage == null) {
+        throw new Error(`Unknown stage "${stageId}" in persisted state`);
+    }
+    const call = stage.calls.find((entry) => entry.callId === callId);
+    if (call == null) {
+        throw new Error(`Unknown call "${stageId}.${callId}" in persisted state`);
+    }
+    return call;
+}
+function deriveStageState(calls) {
+    if (calls.every((call) => call.state === "succeeded")) {
+        return "succeeded";
+    }
+    if (calls.some((call) => call.state === "running")) {
+        return "running";
+    }
+    if (calls.some((call) => call.state === "cancelled")) {
+        return "cancelled";
+    }
+    if (calls.some((call) => call.state === "failed")) {
+        return "failed";
+    }
+    return "pending";
+}
+function deriveStageCompletedAt(calls) {
+    const completedValues = calls
+        .map((call) => call.completedAt)
+        .filter((value) => value != null)
+        .sort();
+    return completedValues.length > 0 ? completedValues[completedValues.length - 1] : undefined;
+}
+async function persistOutput(runDir, stageId, callId, outputText) {
+    const sizeBytes = Buffer.byteLength(outputText, "utf-8");
+    if (sizeBytes <= OUTPUT_INLINE_THRESHOLD_BYTES) {
+        return {
+            outputInline: outputText,
+            outputPath: undefined,
+        };
+    }
+    const relativePath = `${stageId}.${callId}.output.txt`;
+    await writeTextAtomic(join(runDir, relativePath), outputText);
+    return {
+        outputInline: undefined,
+        outputPath: relativePath,
+    };
+}
+async function buildResumeState(definition, state, runDir) {
+    const completedCalls = new Map();
+    const preparedInputs = new Map();
+    const failedCalls = new Map();
+    const firstIncompleteStageIndex = definition.stages.findIndex((stage) => {
+        const persistedStage = state.stages.find((entry) => entry.stageId === stage.id);
+        return !persistedStage?.calls.every((call) => call.state === "succeeded");
+    });
+    const resumeStageIndex = firstIncompleteStageIndex === -1
+        ? definition.stages.length
+        : firstIncompleteStageIndex;
+    for (let stageIndex = 0; stageIndex < definition.stages.length; stageIndex += 1) {
+        const stage = definition.stages[stageIndex];
+        const persistedStage = state.stages.find((entry) => entry.stageId === stage.id);
+        if (persistedStage == null) {
+            continue;
+        }
+        if (stageIndex < resumeStageIndex) {
+            for (const call of stage.calls) {
+                const entry = persistedStage.calls.find((candidate) => candidate.callId === call.id);
+                if (entry?.state === "succeeded") {
+                    completedCalls.set(`${stage.id}.${call.id}`, await rehydrateExecutedCall(runDir, entry));
+                }
+                else if (entry?.state === "failed" && entry.errorMessage != null) {
+                    failedCalls.set(`${stage.id}.${call.id}`, {
+                        stageId: stage.id,
+                        callId: call.id,
+                        error: entry.errorMessage,
+                    });
+                }
+            }
+            continue;
+        }
+        if (stageIndex === resumeStageIndex) {
+            for (const call of stage.calls) {
+                const entry = persistedStage.calls.find((candidate) => candidate.callId === call.id);
+                if (entry?.state === "succeeded") {
+                    completedCalls.set(`${stage.id}.${call.id}`, await rehydrateExecutedCall(runDir, entry));
+                    continue;
+                }
+                if (entry?.state === "failed" && entry.errorMessage != null) {
+                    failedCalls.set(`${stage.id}.${call.id}`, {
+                        stageId: stage.id,
+                        callId: call.id,
+                        error: entry.errorMessage,
+                    });
+                }
+                if (entry?.materializedInputPath != null) {
+                    preparedInputs.set(`${stage.id}.${call.id}`, await readJsonFile(join(runDir, entry.materializedInputPath)));
+                }
+            }
+        }
+    }
+    return {
+        completedCalls,
+        preparedInputs,
+        failedCalls,
+    };
+}
+async function rehydrateExecutedCall(runDir, entry) {
+    const outputText = await readPersistedOutput(runDir, entry);
+    const artifact = entry.artifactPath != null
+        ? await rehydrateArtifact(runDir, entry.stageId, entry.callId, entry.artifactPath)
+        : undefined;
+    const fidelity = entry.fidelity != null ? rehydrateFidelity(entry.fidelity) : undefined;
+    return {
+        stageId: entry.stageId,
+        callId: entry.callId,
+        ok: true,
+        outputText,
+        artifact,
+        fidelity,
+    };
+}
+async function readPersistedOutput(runDir, entry) {
+    if (entry.outputInline != null) {
+        return entry.outputInline;
+    }
+    if (entry.outputPath != null) {
+        return await readFile(join(runDir, entry.outputPath), "utf-8");
+    }
+    throw new Error(`Succeeded call ${entry.stageId}.${entry.callId} is missing persisted output`);
+}
+async function rehydrateArtifact(runDir, stageId, callId, artifactPath) {
+    const filePath = join(runDir, artifactPath);
+    const serialized = await readFile(filePath, "utf-8");
+    const parsed = JSON.parse(serialized);
+    const stats = await stat(filePath);
+    return {
+        stageId,
+        callId,
+        reference: `${stageId}.${callId}`,
+        filePath,
+        filename: basename(filePath),
+        sizeBytes: stats.size,
+        parsed,
+    };
+}
+function rehydrateFidelity(metadata) {
+    return {
+        responseTruncated: metadata.responseTruncated,
+        responseTrailer: metadata.responseTrailer,
+        captureTruncated: metadata.captureTruncated,
+        stdoutTruncated: metadata.stdoutTruncated,
+        stderrTruncated: metadata.stderrTruncated,
+        parseSource: metadata.extractionPath === "result_contract" ? "result_contract" : "parser",
+    };
+}
+function buildPersistedFidelity(fidelity, contextProducing) {
+    return buildFidelityMetadata(fidelity, {
+        contextProducing,
+        resultContractEnabled: fidelity.parseSource === "result_contract",
+    });
+}
+async function buildChildConfigFingerprint(definition) {
+    const configPath = getChildConfigPath();
+    if (configPath == null) {
+        throw new Error("Persistent resume requires CLINKX_WORKFLOWS_CHILD_CONFIG_PATH");
+    }
+    const adapterConfigs = await loadNormalizedAdapterConfigs(configPath);
+    const resolvedPrompts = await loadResolvedPrompts(configPath, adapterConfigs);
+    const workspaceRoot = resolveWorkspaceRoot();
+    const childEnv = {
+        CLINKX_MAX_CONCURRENT: String(getChildMaxConcurrent()),
+        CLINKX_MAX_RESPONSE_CHARS: String(getChildMaxResponseChars()),
+        CLINKX_MAX_OUTPUT_BYTES: String(getChildMaxOutputBytes()),
+        CLINKX_MAX_PROMPT_BYTES: String(getChildMaxPromptBytes()),
+        CLINKX_CONFIG_PATH: configPath,
+        CLINKX_ALLOWED_ROOTS: deriveAllowedRoots(workspaceRoot, getStateDir(), getArtifactsDir()),
+        CLINKX_LOG_LEVEL: getLogLevel(),
+    };
+    return generateWorkflowFingerprint(definition, adapterConfigs, resolvedPrompts, childEnv);
+}
+async function loadNormalizedAdapterConfigs(configPath) {
+    const paths = await listConfigFiles(configPath);
+    const configs = new Map();
+    for (const filePath of paths) {
+        const raw = await readJsonFile(filePath);
+        const config = normalizeAdapterConfig(raw);
+        if (configs.has(config.name)) {
+            continue;
+        }
+        configs.set(config.name, {
+            ...config,
+            command: resolveCommandPath(config.command),
+        });
+    }
+    return Object.fromEntries([...configs.entries()].sort(([a], [b]) => a.localeCompare(b)));
+}
+async function loadResolvedPrompts(configPath, adapterConfigs) {
+    const configFiles = await listConfigFiles(configPath);
+    const filesByName = new Map();
+    for (const filePath of configFiles) {
+        const raw = await readJsonFile(filePath);
+        const config = normalizeAdapterConfig(raw);
+        if (!filesByName.has(config.name)) {
+            filesByName.set(config.name, filePath);
+        }
+    }
+    const prompts = new Map();
+    for (const [name, value] of Object.entries(adapterConfigs)) {
+        const config = value;
+        const filePath = filesByName.get(name);
+        if (filePath == null) {
+            continue;
+        }
+        for (const [roleName, role] of Object.entries(config.roles)) {
+            const prompt = await resolveRolePrompt(filePath, role);
+            if (prompt != null) {
+                prompts.set(`${name}.${roleName}`, prompt);
+            }
+        }
+    }
+    return Object.fromEntries([...prompts.entries()].sort(([a], [b]) => a.localeCompare(b)));
+}
+async function resolveRolePrompt(configFilePath, role) {
+    if (role.inline_prompt != null) {
+        return role.inline_prompt;
+    }
+    if (role.prompt_file == null) {
+        return undefined;
+    }
+    const resolved = resolve(dirname(configFilePath), role.prompt_file);
+    const builtinFallback = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..", "conf", "adapters", role.prompt_file);
+    if (await fileExists(resolved)) {
+        return (await readFile(resolved, "utf-8")).trimEnd();
+    }
+    if (await fileExists(builtinFallback)) {
+        return (await readFile(builtinFallback, "utf-8")).trimEnd();
+    }
+    throw new Error(`Prompt file not found for ${configFilePath}: ${role.prompt_file}`);
+}
+function normalizeAdapterConfig(raw) {
+    const rolesRecord = asRecord(raw["roles"]);
+    const roles = Object.fromEntries(Object.entries(rolesRecord).map(([name, value]) => [name, normalizeRoleConfig(asRecord(value))]));
+    return {
+        name: expectString(raw["name"], "adapter.name"),
+        command: expectString(raw["command"], "adapter.command"),
+        runner: asOptionalString(raw["runner"]),
+        args: asStringArray(raw["args"]),
+        unsafe_args: asStringArray(raw["unsafe_args"]),
+        env: asStringRecord(raw["env"]),
+        env_allowlist: asStringArray(raw["env_allowlist"]),
+        timeout_seconds: asOptionalNumber(raw["timeout_seconds"]) ?? 600,
+        idle_timeout_seconds: asOptionalNumber(raw["idle_timeout_seconds"]),
+        idle_timeout_startup_seconds: asOptionalNumber(raw["idle_timeout_startup_seconds"]),
+        parser: asOptionalString(raw["parser"]) ?? "text",
+        tolerate_nonzero_exit_for_parse: asOptionalBoolean(raw["tolerate_nonzero_exit_for_parse"]) ?? false,
+        capabilities_hint: asOptionalString(raw["capabilities_hint"]),
+        roles,
+        supports_images: asOptionalBoolean(raw["supports_images"]) ?? false,
+        requires_tty: asOptionalBoolean(raw["requires_tty"]) ?? false,
+        result_contract: normalizeResultContract(asRecord(raw["result_contract"])),
+        prompt_mode: normalizePromptMode(raw["prompt_mode"]),
+        stdin_placeholder_arg: asOptionalString(raw["stdin_placeholder_arg"]),
+        native_output_file_flag: asOptionalString(raw["native_output_file_flag"]),
+        suppress_stdout: asOptionalBoolean(raw["suppress_stdout"]) ?? false,
+    };
+}
+function normalizeRoleConfig(raw) {
+    return {
+        inline_prompt: asOptionalString(raw["inline_prompt"]),
+        prompt_file: asOptionalString(raw["prompt_file"]),
+        parser: asOptionalString(raw["parser"]),
+        extra_args: asStringArray(raw["extra_args"]),
+    };
+}
+function normalizeResultContract(raw) {
+    return {
+        enabled: asOptionalBoolean(raw["enabled"]) ?? false,
+        filename: raw["filename"] === "RESULT.json" ? "RESULT.json" : "RESULT.md",
+    };
+}
+function normalizePromptMode(raw) {
+    return raw === "arg" || raw === "file" ? raw : "stdin";
+}
+async function listConfigFiles(configPath) {
+    const configStats = await stat(configPath);
+    if (!configStats.isDirectory()) {
+        return [configPath];
+    }
+    const entries = await (await import("node:fs/promises")).readdir(configPath, { withFileTypes: true });
+    return entries
+        .filter((entry) => entry.isFile() && entry.name.endsWith(".json"))
+        .map((entry) => join(configPath, entry.name))
+        .sort();
+}
+async function readRunState(runDir) {
+    const statePath = join(runDir, STATE_FILENAME);
+    const state = await readJsonFile(statePath);
+    if (state.state_version !== 1) {
+        throw new Error(`Unsupported state_version ${String(state.state_version)} in ${statePath}`);
+    }
+    return state;
+}
+async function verifySnapshotHash(filePath, expectedHash, label) {
+    if (expectedHash == null) {
+        throw new Error(`Missing ${label} hash for ${filePath}`);
+    }
+    const content = await readFile(filePath, "utf-8");
+    const actualHash = hashContent(content);
+    if (actualHash !== expectedHash) {
+        throw new Error(`Corrupted ${label}: hash mismatch for ${filePath}`);
+    }
+}
+async function writeJsonSnapshot(filePath, value) {
+    const serialized = serializeJson(value);
+    await writeTextAtomic(filePath, serialized);
+    return hashContent(serialized);
+}
+async function writeJsonAtomic(filePath, value) {
+    await writeTextAtomic(filePath, serializeJson(value));
+}
+async function writeTextAtomic(filePath, content) {
+    await mkdir(dirname(filePath), { recursive: true });
+    const tmpPath = `${filePath}.tmp`;
+    await writeFile(tmpPath, content, "utf-8");
+    await rename(tmpPath, filePath);
+}
+function serializeJson(value) {
+    return `${JSON.stringify(value, null, 2)}\n`;
+}
+function hashContent(content) {
+    return createHash("sha256").update(content, "utf-8").digest("hex");
+}
+async function readJsonFile(filePath) {
+    return JSON.parse(await readFile(filePath, "utf-8"));
+}
+async function acquireRunLock(runDir) {
+    const lockPath = join(runDir, RUN_LOCK_FILENAME);
+    const record = {
+        pid: process.pid,
+        hostname: hostname(),
+        startedAt: new Date().toISOString(),
+    };
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        try {
+            const handle = await open(lockPath, "wx");
+            try {
+                await handle.writeFile(serializeJson(record), "utf-8");
+            }
+            finally {
+                await handle.close();
+            }
+            return;
+        }
+        catch (error) {
+            if (!(error instanceof Error) || !("code" in error) || error.code !== "EEXIST") {
+                throw error;
+            }
+            const existing = await readJsonFile(lockPath);
+            if (existing.hostname === hostname() && !isPidLive(existing.pid)) {
+                await unlink(lockPath);
+                continue;
+            }
+            throw new Error(`Run lock is held for ${runDir} by pid ${String(existing.pid)} on ${existing.hostname} since ${existing.startedAt}`);
+        }
+    }
+}
+function isPidLive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code !== "ESRCH";
+    }
+}
+function resolveCommandPath(command) {
+    if (command.includes("/")) {
+        return isAbsolute(command) ? command : resolve(command);
+    }
+    try {
+        return execFileSync("which", [command], { encoding: "utf-8" }).trim();
+    }
+    catch {
+        return command;
+    }
+}
+function isContextProducing(definition, stageId, callId) {
+    const target = `${stageId}.${callId}`;
+    for (const stage of definition.stages) {
+        for (const call of stage.calls) {
+            for (const ref of call.context_from ?? []) {
+                if (ref === target) {
+                    return true;
+                }
+                if (ref === stageId) {
+                    return true;
+                }
+            }
+        }
+    }
+    return false;
+}
+async function safeUnlink(filePath) {
+    try {
+        await unlink(filePath);
+    }
+    catch (error) {
+        const code = error.code;
+        if (code !== "ENOENT") {
+            logger.warn({ path: filePath, err: error instanceof Error ? error.message : String(error) }, "failed to remove file");
+        }
+    }
+}
+async function fileExists(filePath) {
+    try {
+        await stat(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function asRecord(value) {
+    return value != null && typeof value === "object" ? value : {};
+}
+function asOptionalString(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function expectString(value, label) {
+    const parsed = asOptionalString(value);
+    if (parsed == null) {
+        throw new Error(`Expected ${label} to be a non-empty string`);
+    }
+    return parsed;
+}
+function asOptionalNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+function asOptionalBoolean(value) {
+    return typeof value === "boolean" ? value : undefined;
+}
+function asStringArray(value) {
+    return Array.isArray(value) ? value.filter((item) => typeof item === "string") : [];
+}
+function asStringRecord(value) {
+    const result = {};
+    for (const [key, entry] of Object.entries(asRecord(value))) {
+        if (typeof entry === "string") {
+            result[key] = entry;
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=state.js.map