agentera 3.0.0-dev.4 → 3.0.0-dev.46

package/dist/state/write/candidateMutation.js

@@ -0,0 +1,269 @@
+import { isDeepStrictEqual } from "node:util";
+import { isExactArchiveReplay, recoverArchivedEntry, } from "../archiveReplay.js";
+import { localDate, localTimestamp, nextEntryNumber, nextTaskNumber } from "./assign.js";
+import { reject } from "./errors.js";
+import { array, findByNumber, mapping, mappingPath } from "./helpers.js";
+import { mutatePlanTaskEvaluation } from "./planEvaluation.js";
+function buildProgress(doc, values) {
+    const entry = {
+        number: nextEntryNumber(doc, "cycles"),
+        timestamp: values.timestamp ?? localTimestamp(),
+        type: values.type,
+        phase: values.phase,
+        what: values.what,
+    };
+    for (const field of ["inspiration", "discovered", "verified", "next"])
+        if (values[field] !== undefined)
+            entry[field] = values[field];
+    const context = { intent: mappingPath(values, "context.intent") };
+    for (const field of ["constraints", "unknowns", "scope"]) {
+        const value = mappingPath(values, `context.${field}`);
+        if (value !== undefined)
+            context[field] = value;
+    }
+    entry.context = context;
+    return entry;
+}
+function buildDecision(doc, values) {
+    const alternatives = mapping(values.alternatives);
+    const rejected = Array.isArray(alternatives.rejected) ? alternatives.rejected : [];
+    const entry = {
+        number: nextEntryNumber(doc, "decisions"),
+        date: values.date ?? localDate(),
+        question: values.question,
+        context: values.context,
+        alternatives: [
+            { name: alternatives.chosen, status: "chosen" },
+            ...rejected.map((name) => ({ name, status: "rejected" })),
+        ],
+        choice: values.choice,
+        reasoning: values.reasoning,
+        confidence: values.confidence,
+    };
+    if (values.feeds_into !== undefined)
+        entry.feeds_into = values.feeds_into;
+    return entry;
+}
+function normalizedDecisionPayload(values) {
+    const payload = { ...values };
+    const alternatives = mapping(values.alternatives);
+    payload.alternatives = [
+        { name: alternatives.chosen, status: "chosen" },
+        ...(Array.isArray(alternatives.rejected) ? alternatives.rejected : []).map((name) => ({
+            name,
+            status: "rejected",
+        })),
+    ];
+    return payload;
+}
+export function mutateCandidate(req, doc, recovered) {
+    const candidate = structuredClone(doc);
+    if (req.artifact === "progress") {
+        const payload = req.callerPayload;
+        const entries = array(candidate, "cycles");
+        const replay = entries.find((entry) => isExactArchiveReplay(entry, payload));
+        if (replay)
+            return {
+                candidate,
+                written: replay,
+                assigned: { number: replay.number, timestamp: replay.timestamp },
+                replay: true,
+            };
+        if (recovered) {
+            recoverArchivedEntry(candidate, "cycles", entries, recovered, true);
+            return {
+                candidate,
+                written: recovered,
+                assigned: { number: recovered.number, timestamp: recovered.timestamp },
+                replay: true,
+            };
+        }
+        const entry = buildProgress(candidate, req.values);
+        candidate.cycles = [entry, ...entries];
+        return {
+            candidate,
+            written: entry,
+            assigned: { number: entry.number, timestamp: entry.timestamp },
+            replay: false,
+        };
+    }
+    if (req.artifact === "decisions" && req.spec.verb === "append") {
+        const entries = array(candidate, "decisions");
+        const payload = normalizedDecisionPayload(req.callerPayload);
+        const replay = entries.find((entry) => isExactArchiveReplay(entry, payload));
+        if (replay) {
+            const entry = replay;
+            return {
+                candidate,
+                written: entry,
+                assigned: { number: entry.number, date: entry.date },
+                replay: true,
+            };
+        }
+        if (recovered) {
+            recoverArchivedEntry(candidate, "decisions", entries, recovered, false);
+            return {
+                candidate,
+                written: recovered,
+                assigned: { number: recovered.number, date: recovered.date },
+                replay: true,
+            };
+        }
+        const entry = buildDecision(candidate, req.values);
+        candidate.decisions = [...entries, entry];
+        return {
+            candidate,
+            written: entry,
+            assigned: { number: entry.number, date: entry.date },
+            replay: false,
+        };
+    }
+    if (req.artifact === "health") {
+        if (req.input && ("audits" in req.input || "archive" in req.input)) {
+            reject({
+                class: "schema_violation",
+                message: "health append input must be one audit entry, not a whole health artifact",
+                violations: ["remove audits/archive wrapper fields"],
+            });
+        }
+        const entries = array(candidate, "audits");
+        const payload = req.callerPayload;
+        const replay = entries.find((entry) => isExactArchiveReplay(entry, payload));
+        if (replay) {
+            const entry = replay;
+            return {
+                candidate,
+                written: entry,
+                assigned: { number: entry.number, date: entry.date },
+                replay: true,
+            };
+        }
+        if (recovered) {
+            recoverArchivedEntry(candidate, "audits", entries, recovered, false);
+            return {
+                candidate,
+                written: recovered,
+                assigned: { number: recovered.number, date: recovered.date },
+                replay: true,
+            };
+        }
+        const entry = {
+            number: nextEntryNumber(candidate, "audits"),
+            date: req.input?.date ?? localDate(),
+            ...req.input,
+        };
+        candidate.audits = [...entries, entry];
+        return {
+            candidate,
+            written: entry,
+            assigned: { number: entry.number, date: entry.date },
+            replay: false,
+        };
+    }
+    const tasks = array(candidate, "tasks");
+    if (req.spec.verb === "append") {
+        const sameName = tasks.find((task) => task.name === req.values.name);
+        const payload = req.callerPayload;
+        if (sameName) {
+            if (isExactArchiveReplay(sameName, payload))
+                return {
+                    candidate,
+                    written: sameName,
+                    assigned: { number: sameName.number },
+                    replay: true,
+                };
+            reject({
+                class: "conflict",
+                message: `plan task "${req.values.name}" exists with different fields; use 'state plan update --id ID --input task-patch.yaml' to modify it`,
+            });
+        }
+        const entry = {
+            number: nextTaskNumber(candidate),
+            name: req.values.name,
+            status: req.values.status ?? "pending",
+        };
+        for (const field of ["depends_on", "acceptance"])
+            if (req.values[field] !== undefined)
+                entry[field] = req.values[field];
+        candidate.tasks = [...tasks, entry];
+        return { candidate, written: entry, assigned: { number: entry.number }, replay: false };
+    }
+    if (req.spec.verb === "update") {
+        const number = Number(req.values.task);
+        const entry = findByNumber(tasks, number);
+        if (!entry)
+            reject({ class: "unsupported_target", message: `no plan task with number ${number}` });
+        let changed = false;
+        for (const field of [
+            "name",
+            "depends_on",
+            "acceptance",
+            "status",
+            "evidence",
+            "blocked_reason",
+        ]) {
+            if (req.values[field] !== undefined && !isDeepStrictEqual(entry[field], req.values[field])) {
+                entry[field] = req.values[field];
+                changed = true;
+            }
+        }
+        if (req.values.surprise !== undefined) {
+            const current = String(candidate.surprises ?? "").trim();
+            const surprise = String(req.values.surprise);
+            if (!current.split("\n").includes(surprise)) {
+                candidate.surprises = current ? `${current}\n${surprise}` : surprise;
+                changed = true;
+            }
+        }
+        return { candidate, written: entry, assigned: { number }, replay: !changed };
+    }
+    if (req.spec.verb === "set-plan-status") {
+        const status = String(req.values.status);
+        if (status === "complete" && tasks.some((task) => task.status !== "complete")) {
+            reject({
+                class: "conflict",
+                message: "plan cannot be marked complete while incomplete tasks remain",
+            });
+        }
+        const header = mapping(candidate.header);
+        const replay = header.status === status;
+        header.status = status;
+        candidate.header = header;
+        return { candidate, written: header, assigned: {}, replay };
+    }
+    if (req.spec.verb === "set-status") {
+        const taskNumber = Number(req.values.task);
+        const status = String(req.values.status);
+        if (!["complete", "in_progress", "pending", "blocked"].includes(status))
+            reject({
+                class: "invalid_choice",
+                message: `argument --status: invalid choice: '${status}'`,
+                valid_values: ["complete", "in_progress", "pending", "blocked"],
+            });
+        const entry = findByNumber(tasks, taskNumber);
+        if (!entry)
+            reject({ class: "unsupported_target", message: `no plan task with number ${taskNumber}` });
+        const replay = entry.status === status;
+        entry.status = status;
+        return { candidate, written: entry, assigned: { number: taskNumber }, replay };
+    }
+    if (req.spec.verb === "record-evaluation") {
+        const taskNumber = Number(req.values.task);
+        const entry = findByNumber(tasks, taskNumber);
+        if (!entry)
+            reject({ class: "unsupported_target", message: `no plan task with number ${taskNumber}` });
+        const mutation = mutatePlanTaskEvaluation(entry, req.values.evaluation, `plan task ${taskNumber}`);
+        return {
+            candidate,
+            written: entry,
+            assigned: {
+                number: taskNumber,
+                attempt_count: mutation.attemptCount,
+                failure_count: mutation.failureCount,
+            },
+            replay: mutation.replay,
+        };
+    }
+    throw new Error(`unsupported transaction ${req.artifact} ${req.spec.verb}`);
+}
+export { normalizedDecisionPayload };

package/dist/state/write/errors.js

@@ -0,0 +1,11 @@
+export class StateWriteInputError extends Error {
+    body;
+    constructor(body) {
+        super(body.message);
+        this.name = "StateWriteInputError";
+        this.body = body;
+    }
+}
+export function reject(body) {
+    throw new StateWriteInputError(body);
+}

package/dist/state/write/experimentPublication.js

@@ -0,0 +1,192 @@
+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 */
+        }
+    }
+}