agentera 3.0.0-dev.2 → 3.0.0-dev.21

package/dist/state/write/experimentPublication.js

@@ -0,0 +1,193 @@
+import fs from "node:fs";
+import path from "node:path";
+import { isDeepStrictEqual } from "node:util";
+import { splitLinesKeepEnds, unifiedDiff } from "../../core/difflib.js";
+import { dumpYamlMapping, loadYamlMapping } from "../../core/yaml.js";
+import { compactYamlFile } from "../../hooks/compaction/index.js";
+import { assertRealpathBoundary } from "../../registries/artifactRegistry.js";
+import { assertExperimentArchiveReplay, prepareExperimentArchive, } from "../experimentArchive.js";
+import { ExperimentIdentityError, discoverObjectiveArtifacts, inspectExperimentIdentities, validateExperimentPublicationIdentity, } from "../experimentIdentity.js";
+import { reject } from "./errors.js";
+import { schemaViolation } from "./helpers.js";
+import { validateArtifactBytes } from "./validate.js";
+function array(doc, key) {
+    return Array.isArray(doc[key])
+        ? doc[key].filter((value) => Boolean(value && typeof value === "object" && !Array.isArray(value)))
+        : [];
+}
+function readExisting(target) {
+    if (!fs.existsSync(target))
+        return { doc: {}, bytes: "" };
+    const bytes = fs.readFileSync(target, "utf8");
+    try {
+        return { doc: loadYamlMapping(bytes), bytes };
+    }
+    catch (error) {
+        throw new Error(`cannot parse existing artifact '${target}': ${error.message}; run agentera check validate artifact before retrying`);
+    }
+}
+function diffText(before, after, target) {
+    return unifiedDiff(splitLinesKeepEnds(before), splitLinesKeepEnds(after), target, target).join("");
+}
+function rejectIdentity(error) {
+    reject({
+        class: error.className === "invalid_request"
+            ? "invalid_request"
+            : error.className === "not_found"
+                ? "unsupported_target"
+                : "conflict",
+        message: error.message,
+        syntax: "agentera state experiments publish --objective OBJECTIVE_ID --number N --input EXPERIMENT.yaml --format json",
+        example: "agentera state experiments publish --objective objective:123e4567-e89b-42d3-a456-426614174000 --number 0 --input experiment.yaml --format json",
+        recovery: "Correct the objective or experiment identity and retry; no state was changed.",
+    });
+}
+function envelope(req, target, doc, written, assigned, replay, compaction, archive, preview) {
+    return {
+        schemaVersion: "agentera.stateWrite.v1",
+        command: "state experiments publish",
+        status: "pass",
+        artifact: "experiments",
+        path: target,
+        operation: { verb: "publish", dry_run: req.dryRun, idempotent_replay: replay, forced: false },
+        assigned,
+        written,
+        state: {
+            active_count: array(doc, "experiments").length,
+            archive_count: array(doc, "archive").length,
+        },
+        validation: { status: "pass", violations: [] },
+        compaction,
+        ...(archive ? {
+            archive: {
+                path: archive.target,
+                stable_id: archive.stableId,
+                record_sha256: archive.recordSha256,
+                provenance: archive.provenance,
+                idempotent_replay: archive.replay,
+            },
+        } : {}),
+        ...(preview ?? {}),
+    };
+}
+export function executeExperimentPublication(req, transaction) {
+    const objectiveId = String(req.values.objective ?? "");
+    const number = Number(req.values.number);
+    const input = structuredClone(req.input ?? {});
+    if ("number" in input)
+        reject({
+            class: "schema_violation",
+            message: "experiments publish assigns number; remove 'number' from the input document",
+            violations: ["CLI-owned field: number"],
+        });
+    const discovery = discoverObjectiveArtifacts(req.projectRoot);
+    const objective = discovery.objectives.find((candidate) => candidate.stableId === objectiveId);
+    try {
+        validateExperimentPublicationIdentity(discovery, { objectiveId, entries: [], caveats: [] }, objectiveId, number);
+    }
+    catch (error) {
+        if (error instanceof ExperimentIdentityError)
+            rejectIdentity(error);
+        throw error;
+    }
+    const canonicalPaths = objective?.paths.filter((candidate) => candidate.includes(`${path.sep}.agentera${path.sep}optimize${path.sep}`)) ?? [];
+    const objectivePath = objective?.paths.length === 1
+        ? objective.paths[0]
+        : canonicalPaths.length === 1
+            ? canonicalPaths[0]
+            : null;
+    if (!objectivePath)
+        reject({
+            class: "conflict",
+            message: `objective identity ${objectiveId} does not resolve to one publication target; no effects are allowed`,
+            recovery: `Resolve the objective path collision (${(objective?.paths ?? []).join(", ") || "no candidates"}) and retry; no state was changed.`,
+        });
+    const target = path.join(path.dirname(objectivePath), "experiments.yaml");
+    assertRealpathBoundary(req.projectRoot, target, "experiments");
+    const existing = readExisting(target);
+    if (existing.bytes) {
+        const violations = validateArtifactBytes("experiments", existing.bytes);
+        if (violations.length)
+            throw new Error(`existing artifact '${target}' is schema-invalid: ${violations.join("; ")}; repair it before retrying`);
+    }
+    const projection = inspectExperimentIdentities(objectiveId, existing.doc);
+    const written = { number, ...input };
+    const stableId = `${objectiveId}/experiment:${number}`;
+    const assigned = { objective: objectiveId, number, stable_id: stableId };
+    const retained = projection.entries.filter((entry) => entry.stableId === stableId);
+    if (retained.length === 1 && retained[0].addressable && isDeepStrictEqual(retained[0].data, written)) {
+        const archive = prepareExperimentArchive(req.projectRoot, objectivePath, objectiveId, number, written);
+        const archiveExists = fs.existsSync(archive.target);
+        let archiveReplay = archiveExists;
+        if (archiveExists) {
+            assertExperimentArchiveReplay(archive);
+        }
+        else if (!req.dryRun) {
+            const published = transaction?.publishExperimentArchive(archive, () => assertExperimentArchiveReplay(archive));
+            if (published === undefined)
+                throw new Error("state mutation transaction is unavailable");
+            archiveReplay = !published;
+        }
+        const preview = req.dryRun ? { diff: "", before: existing.doc, after: existing.doc } : undefined;
+        return envelope(req, target, existing.doc, written, assigned, true, null, { ...archive, replay: archiveReplay }, preview);
+    }
+    try {
+        validateExperimentPublicationIdentity(discovery, projection, objectiveId, number);
+    }
+    catch (error) {
+        if (error instanceof ExperimentIdentityError)
+            rejectIdentity(error);
+        throw error;
+    }
+    const inputViolations = validateArtifactBytes("experiments", dumpYamlMapping({ experiments: [written] }));
+    if (inputViolations.length)
+        schemaViolation(inputViolations);
+    const candidate = structuredClone(existing.doc);
+    candidate.experiments = [...array(candidate, "experiments"), written];
+    const candidateBytes = dumpYamlMapping(candidate);
+    const candidateViolations = validateArtifactBytes("experiments", candidateBytes);
+    if (candidateViolations.length)
+        schemaViolation(candidateViolations);
+    const archive = prepareExperimentArchive(req.projectRoot, objectivePath, objectiveId, number, written);
+    const stage = req.dryRun
+        ? path.join(path.dirname(target), `.${path.basename(target)}.writer.${process.pid}.${Date.now()}.tmp`)
+        : transaction?.stageProjection(target, candidateBytes);
+    if (!stage)
+        throw new Error("state mutation transaction is unavailable");
+    let compaction = null;
+    try {
+        if (req.dryRun)
+            fs.writeFileSync(stage, candidateBytes);
+        if (req.spec.compacts)
+            compaction = compactYamlFile(stage, "experiments", req.projectRoot);
+        const finalBytes = fs.readFileSync(stage, "utf8");
+        const finalViolations = validateArtifactBytes("experiments", finalBytes);
+        if (finalViolations.length)
+            throw new Error(`writer/compactor invariant failure: ${finalViolations.join("; ")}`);
+        const finalDoc = loadYamlMapping(finalBytes);
+        const preview = req.dryRun
+            ? { diff: diffText(existing.bytes, finalBytes, target), before: existing.doc, after: finalDoc }
+            : undefined;
+        if (!req.dryRun) {
+            transaction?.syncStaged(stage);
+            const published = transaction?.publishExperimentArchive(archive, () => assertExperimentArchiveReplay(archive));
+            if (published === undefined)
+                throw new Error("state mutation transaction is unavailable");
+            transaction?.publishProjection(stage, target, existing.bytes);
+            return envelope(req, target, finalDoc, written, assigned, false, compaction, { ...archive, replay: !published }, preview);
+        }
+        return envelope(req, target, finalDoc, written, assigned, false, compaction, { ...archive, replay: false }, preview);
+    }
+    finally {
+        try {
+            if (req.dryRun)
+                fs.unlinkSync(stage);
+            else
+                transaction?.removeStage(stage);
+        }
+        catch {
+            /* stage published or absent */
+        }
+    }
+}
+//# sourceMappingURL=experimentPublication.js.map

package/dist/state/write/experimentPublication.js.map

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

package/dist/state/write/explain.js

@@ -0,0 +1,169 @@
+import path from "node:path";
+import { ArtifactSchemaValidator } from "../../hooks/validateArtifact/index.js";
+import { loadArtifactRegistry, resolveArtifactPath } from "../../registries/artifactRegistry.js";
+import { loadYamlMapping } from "../../core/yaml.js";
+import fs from "node:fs";
+import { nextEntryNumber, nextTaskNumber } from "./assign.js";
+import { schemaBudget, projectedFields } from "./fields.js";
+import { operationSpec, verbsForArtifact, } from "./operations.js";
+import { reject } from "./errors.js";
+function liveDoc(p) {
+    if (!fs.existsSync(p))
+        return {};
+    return loadYamlMapping(fs.readFileSync(p, "utf8"));
+}
+function defaultVerb(artifact) {
+    return artifact === "experiments" ? "publish" : "append";
+}
+export function buildExplain(artifact, projectRoot, requestedVerb) {
+    const verb = (requestedVerb ?? defaultVerb(artifact));
+    const spec = operationSpec(artifact, verb);
+    if (!spec) {
+        reject({
+            class: "invalid_choice",
+            message: `verb "${verb}" does not apply to ${artifact}`,
+            valid_values: verbsForArtifact(artifact),
+        });
+    }
+    const record = loadArtifactRegistry().get(artifact);
+    if (!record)
+        reject({ class: "unsupported_target", message: `artifact "${artifact}" is not registered` });
+    const resolved = artifact === "experiments"
+        ? path.join(projectRoot, ".agentera", "optimize", "<objective>", "experiments.yaml")
+        : resolveArtifactPath(record, projectRoot, { strictWrite: true });
+    const doc = artifact === "experiments" ? {} : liveDoc(resolved);
+    const next = artifact === "experiments"
+        ? {}
+        : artifact === "plan"
+            ? { task_number: nextTaskNumber(doc) }
+            : {
+                number: nextEntryNumber(doc, artifact === "progress" ? "cycles" : artifact === "decisions" ? "decisions" : "audits"),
+            };
+    const validator = new ArtifactSchemaValidator();
+    const fields = projectedFields(spec, validator).map((field) => ({
+        flag: field.flag,
+        field: field.field,
+        required: Boolean(field.required),
+        type: field.kind,
+        ...(field.validValues ? { valid_values: field.validValues } : {}),
+        ...(field.repeatable ? { repeatable: true } : {}),
+        ...(field.description ? { description: field.description } : {}),
+        ...(field.kind === "date" ? { format: "YYYY-MM-DD" } : {}),
+        ...(field.kind === "datetime" ? { format: "YYYY-MM-DD HH:MM" } : {}),
+        ...(field.flag === "--timestamp" ? { default: "now" } : {}),
+        ...(field.flag === "--date" ? { default: "today" } : {}),
+    }));
+    const result = {
+        schemaVersion: "agentera.stateWriteExplain.v1",
+        command: `state ${artifact} explain`,
+        requested_verb: verb,
+        artifact,
+        path: path.relative(projectRoot, resolved) || resolved,
+        verbs: verbsForArtifact(artifact),
+        next,
+        budget: schemaBudget(artifact, validator),
+        fields,
+    };
+    if (spec.compacts) {
+        result.compaction = artifact === "experiments"
+            ? "uniform_10_40_50 (10 active full-detail and 40 one-line archive entries); runs automatically on publication; durable archival is deferred"
+            : "uniform_10_40_50 (bounded active/archive projections: 10 active full-detail and 40 archive entries; verified numbered archives remain authoritative; no destructive deletion; recovery refuses to omit entries when archive evidence is missing); runs automatically on append";
+    }
+    if (spec.inputRoot) {
+        result.input_schema = {
+            flag: "--input",
+            sources: ["file path", "- (stdin)"],
+            parser: "yaml",
+            accepts_json: true,
+            root: spec.inputRoot,
+            cli_owned_fields: spec.cliOwnedFields ?? [],
+            defaulted_fields: artifact === "health" ? { date: "today" } : {},
+            groups: artifact === "health"
+                ? ["AUDIT", "DIMENSION", "FINDING", "TRENDS"]
+                : artifact === "experiments"
+                    ? ["EXPERIMENT"]
+                    : ["HEADER", "PLAN", "SCOPE", "TASK"],
+        };
+    }
+    result.guidance = [
+        artifact === "plan" && verb === "create"
+            ? "supply sequential task numbers and valid dependencies; previous_plan_archived is assigned by the CLI"
+            : artifact === "plan"
+                ? "task numbers are assigned by the CLI for append"
+                : artifact === "health" && verb === "repair"
+                    ? "repair is a destructive projection edit; select an existing duplicate audit and pass --force"
+                    : artifact === "experiments"
+                        ? "pass the intended non-negative --number; the CLI validates and assigns it to the entry"
+                        : "number is assigned by the CLI; do not pass --number",
+        "do not embed commit hashes; evidence belongs in the commit message (Decision 66)",
+        "fold the artifact write into the implementation commit per AGENTS.md",
+    ];
+    result.example = exampleFor(artifact, verb);
+    return result;
+}
+export function exampleFor(artifact, verb) {
+    if (artifact === "progress")
+        return 'agentera state progress append --type fix --phase build --what "..." --intent "..." --format json';
+    if (artifact === "decisions" && verb === "update")
+        return 'agentera state decisions update --number 1 --satisfaction-state provisionally_satisfied --satisfaction-evidence "..."';
+    if (artifact === "decisions")
+        return 'agentera state decisions append --question "..." --context "..." --alternative-chosen "..." --choice "..." --reasoning "..." --confidence firm';
+    if (artifact === "health" && verb === "repair")
+        return "agentera state health repair --number 14 --keep first --force --format json";
+    if (artifact === "health")
+        return "agentera state health append --input audit.yaml --format json";
+    if (verb === "create")
+        return "agentera state plan create --input plan.yaml --format json";
+    if (verb === "archive")
+        return "agentera state plan archive --dry-run";
+    if (verb === "update")
+        return 'agentera state plan update --task 1 --name "..." --format json';
+    if (verb === "set-status")
+        return "agentera state plan set-status --task 1 --status complete --format json";
+    if (verb === "set-plan-status")
+        return "agentera state plan set-plan-status --status complete --format json";
+    if (verb === "record-evaluation")
+        return 'agentera state plan record-evaluation --task 1 --attempt-id audit-1 --verdict pass --provenance "audit report" --format json';
+    if (verb === "publish")
+        return "agentera state experiments publish --objective OBJECTIVE_ID --number 0 --input experiment.yaml --format json";
+    return `agentera state plan ${verb} --name "..."`;
+}
+export function renderExplainText(explain) {
+    const lines = [
+        `usage: agentera state ${explain.artifact} ${explain.requested_verb ?? "append"} [flags]`,
+        "",
+        `${explain.artifact} (${explain.path})`,
+    ];
+    const fields = Array.isArray(explain.fields)
+        ? explain.fields
+        : [];
+    if (fields.length) {
+        const required = fields.filter((field) => field.required);
+        const optional = fields.filter((field) => !field.required);
+        for (const [heading, entries] of [
+            ["Required", required],
+            ["Optional", optional],
+        ]) {
+            if (!entries.length)
+                continue;
+            lines.push("", `${heading}:`);
+            for (const field of entries) {
+                const values = Array.isArray(field.valid_values)
+                    ? ` one of: ${field.valid_values.join(", ")}`
+                    : "";
+                lines.push(`  ${String(field.flag).padEnd(24)}${values || String(field.description ?? field.field)}`);
+            }
+        }
+    }
+    if (explain.input_schema) {
+        lines.push("", "Required:", "  --input PATH             YAML/JSON document; use - for stdin");
+    }
+    if (explain.compaction)
+        lines.push("", `Compaction: ${explain.compaction}`);
+    lines.push("", "Guidance:");
+    for (const guidance of explain.guidance)
+        lines.push(`  ${guidance}`);
+    lines.push("", "Example:", `  ${explain.example}`);
+    return lines.join("\n") + "\n";
+}
+//# sourceMappingURL=explain.js.map

package/dist/state/write/explain.js.map

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

package/dist/state/write/fields.js

@@ -0,0 +1,62 @@
+import { ArtifactSchemaValidator } from "../../hooks/validateArtifact/index.js";
+function schemaEntry(schema, fieldPath) {
+    const leaf = fieldPath.split(".").at(-1);
+    for (const value of Object.values(schema)) {
+        if (!value || typeof value !== "object" || Array.isArray(value))
+            continue;
+        for (const entry of Object.values(value)) {
+            if (entry &&
+                typeof entry === "object" &&
+                !Array.isArray(entry) &&
+                String(entry.field ?? "") === leaf) {
+                return entry;
+            }
+        }
+    }
+    return null;
+}
+function valuesFromValidation(entry) {
+    if (!entry || !Array.isArray(entry.validation))
+        return undefined;
+    for (const raw of entry.validation) {
+        const match = /Must be one of:\s*(.+)$/i.exec(String(raw));
+        if (match)
+            return match[1]
+                .split(",")
+                .map((v) => v.trim())
+                .filter(Boolean);
+    }
+    return undefined;
+}
+export function projectedFields(spec, validator = new ArtifactSchemaValidator()) {
+    const schema = validator.loadSchema(spec.artifact);
+    if (!schema)
+        return spec.fields;
+    return spec.fields.map((field) => {
+        const entry = schemaEntry(schema, field.field);
+        return {
+            ...field,
+            required: field.required ?? Boolean(entry?.required),
+            validValues: field.validValues ?? valuesFromValidation(entry),
+            description: field.description ?? (entry?.description ? String(entry.description) : undefined),
+        };
+    });
+}
+export function schemaBudget(artifact, validator = new ArtifactSchemaValidator()) {
+    const schema = validator.loadSchema(artifact);
+    const result = {};
+    if (!schema ||
+        !schema.BUDGET ||
+        typeof schema.BUDGET !== "object" ||
+        Array.isArray(schema.BUDGET))
+        return result;
+    for (const entry of Object.values(schema.BUDGET)) {
+        if (!entry || typeof entry !== "object" || Array.isArray(entry))
+            continue;
+        const scope = String(entry.scope ?? "");
+        const key = scope.includes("full_file") ? "full_file_max_words" : "per_entry_max_words";
+        result[key] = typeof entry.max_words === "number" ? entry.max_words : null;
+    }
+    return result;
+}
+//# sourceMappingURL=fields.js.map

package/dist/state/write/fields.js.map

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

package/dist/state/write/helpers.js

@@ -0,0 +1,8 @@
+import { reject } from "./errors.js";
+export function schemaViolation(violations) {
+    reject({ class: "schema_violation", message: violations[0], violations });
+}
+export function findByNumber(entries, number) {
+    return entries.find((entry) => Number(entry.number) === number);
+}
+//# sourceMappingURL=helpers.js.map

package/dist/state/write/helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.js","sourceRoot":"","sources":["../../../src/state/write/helpers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC,MAAM,UAAU,eAAe,CAAC,UAAoB;IAClD,MAAM,CAAC,EAAE,KAAK,EAAE,kBAAkB,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC;AAC5E,CAAC;AAED,MAAM,UAAU,YAAY,CAC1B,OAAkC,EAClC,MAAc;IAEd,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,MAAM,CAAC,CAAC;AAClE,CAAC"}

package/dist/state/write/index.js

@@ -0,0 +1,12 @@
+export * from "./operations.js";
+export * from "./fields.js";
+export * from "./input.js";
+export * from "./assign.js";
+export * from "./explain.js";
+export * from "./lock.js";
+export * from "./mutation.js";
+export * from "./transaction.js";
+export * from "./validate.js";
+export * from "./serialize.js";
+export * from "./errors.js";
+//# sourceMappingURL=index.js.map

package/dist/state/write/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/state/write/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC;AAC9B,cAAc,kBAAkB,CAAC;AACjC,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC"}

package/dist/state/write/input.js

@@ -0,0 +1,22 @@
+import fs from "node:fs";
+import { loadYamlMapping } from "../../core/yaml.js";
+export function loadStructuredInput(source, readStdin) {
+    let text;
+    if (source === "-")
+        text = readStdin();
+    else {
+        try {
+            text = fs.readFileSync(source, "utf8");
+        }
+        catch {
+            throw new Error(`input file '${source}' is not readable`);
+        }
+    }
+    try {
+        return loadYamlMapping(text);
+    }
+    catch (error) {
+        throw new Error(`input is not valid YAML or JSON: ${error.message}`);
+    }
+}
+//# sourceMappingURL=input.js.map

package/dist/state/write/input.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"input.js","sourceRoot":"","sources":["../../../src/state/write/input.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AAEzB,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAErD,MAAM,UAAU,mBAAmB,CACjC,MAAc,EACd,SAAuB;IAEvB,IAAI,IAAY,CAAC;IACjB,IAAI,MAAM,KAAK,GAAG;QAAE,IAAI,GAAG,SAAS,EAAE,CAAC;SAClC,CAAC;QACJ,IAAI,CAAC;YACH,IAAI,GAAG,EAAE,CAAC,YAAY,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACzC,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,IAAI,KAAK,CAAC,eAAe,MAAM,mBAAmB,CAAC,CAAC;QAC5D,CAAC;IACH,CAAC;IACD,IAAI,CAAC;QACH,OAAO,eAAe,CAAC,IAAI,CAAC,CAAC;IAC/B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CAAC,oCAAqC,KAAe,CAAC,OAAO,EAAE,CAAC,CAAC;IAClF,CAAC;AACH,CAAC"}

package/dist/state/write/lock.js

@@ -0,0 +1,131 @@
+import fs from "node:fs";
+import path from "node:path";
+import { assertRealpathBoundary } from "../../registries/artifactRegistry.js";
+import { reject } from "./errors.js";
+const sleepArray = new Int32Array(new SharedArrayBuffer(4));
+const INITIALIZATION_GRACE_MS = 250;
+function malformedLockIsStale(lockPath) {
+    try {
+        return Date.now() - fs.statSync(lockPath).mtimeMs >= INITIALIZATION_GRACE_MS;
+    }
+    catch {
+        return true;
+    }
+}
+function ownerIsDead(lockPath) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(lockPath, "utf8"));
+        if (!Number.isInteger(parsed.pid))
+            return malformedLockIsStale(lockPath);
+        if (parsed.pid === process.pid)
+            return false;
+        try {
+            process.kill(parsed.pid, 0);
+            return false;
+        }
+        catch (error) {
+            return error.code === "ESRCH";
+        }
+    }
+    catch {
+        return malformedLockIsStale(lockPath);
+    }
+}
+function syncDirectory(directory) {
+    const fd = fs.openSync(directory, "r");
+    try {
+        fs.fsyncSync(fd);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+export function acquireWriterLock(projectRoot, timeoutMs = 2000) {
+    const dir = path.join(projectRoot, ".agentera");
+    assertRealpathBoundary(projectRoot, dir, "writer lock");
+    const createdDir = !fs.existsSync(dir);
+    fs.mkdirSync(dir, { recursive: true });
+    const lockPath = path.join(dir, ".writer.lock");
+    const deadline = Date.now() + timeoutMs;
+    while (true) {
+        let fd;
+        let createdLock = false;
+        try {
+            fd = fs.openSync(lockPath, "wx");
+            createdLock = true;
+            fs.writeFileSync(fd, JSON.stringify({ pid: process.pid, created_at: new Date().toISOString() }) + "\n");
+            fs.fsyncSync(fd);
+            fs.closeSync(fd);
+            fd = undefined;
+            syncDirectory(dir);
+            let released = false;
+            return {
+                path: lockPath,
+                release: () => {
+                    if (released)
+                        return;
+                    released = true;
+                    try {
+                        fs.unlinkSync(lockPath);
+                    }
+                    catch {
+                        /* already released */
+                    }
+                    try {
+                        syncDirectory(dir);
+                    }
+                    catch {
+                        /* lock removal is already visible to this process */
+                    }
+                    if (createdDir) {
+                        try {
+                            fs.rmdirSync(dir);
+                        }
+                        catch {
+                            /* a published artifact or peer now owns the directory */
+                        }
+                    }
+                },
+            };
+        }
+        catch (error) {
+            if (fd !== undefined) {
+                try {
+                    fs.closeSync(fd);
+                }
+                catch {
+                    /* acquisition already failed */
+                }
+            }
+            if (createdLock) {
+                try {
+                    fs.unlinkSync(lockPath);
+                }
+                catch {
+                    /* acquisition already failed */
+                }
+            }
+            if (error.code !== "EEXIST")
+                throw error;
+            if (ownerIsDead(lockPath)) {
+                try {
+                    fs.unlinkSync(lockPath);
+                }
+                catch {
+                    /* raced with another writer */
+                }
+                continue;
+            }
+            if (Date.now() >= deadline) {
+                reject({
+                    class: "conflict",
+                    message: `writer lock timeout at '${lockPath}'; retry the command after the active writer finishes`,
+                    syntax: "agentera state <artifact-id> <verb> ... --format json",
+                    example: "retry the same command after the active writer finishes",
+                });
+            }
+            Atomics.wait(sleepArray, 0, 0, 25);
+        }
+    }
+}
+//# sourceMappingURL=lock.js.map