agentera 3.0.0-dev.8 → 3.0.0-dev.80

package/dist/state/todoSeverityHeadings.js

@@ -0,0 +1,71 @@
+import { reject } from "./write/errors.js";
+export const TODO_SEVERITY_HEADINGS = [
+    { section: "critical", name: "Critical", heading: "## ⇶ Critical" },
+    { section: "degraded", name: "Degraded", heading: "## ⇉ Degraded" },
+    { section: "normal", name: "Normal", heading: "## → Normal" },
+    { section: "annoying", name: "Annoying", heading: "## ⇢ Annoying" },
+    { section: "resolved", name: "Resolved", heading: "## ✓ Resolved" },
+];
+const DIAGNOSTIC_LIMIT = 20;
+const byName = new Map(TODO_SEVERITY_HEADINGS.map((entry) => [entry.name.toLowerCase(), entry]));
+function candidate(line) {
+    const content = line.trim().match(/^##\s+(.+?)\s*$/)?.[1];
+    if (!content)
+        return null;
+    const name = content.match(/^(?:[^\p{L}\p{N}\s]+\s+)?(Critical|Degraded|Normal|Annoying|Resolved)$/iu)?.[1];
+    return name ? byName.get(name.toLowerCase()) ?? null : null;
+}
+export function todoSeveritySectionForHeading(line) {
+    const entry = candidate(line);
+    return entry && line.trim() === entry.heading ? entry.section : null;
+}
+export function inspectTodoSeverityHeadings(markdown) {
+    const diagnostics = [];
+    const seen = new Set();
+    let greatestOrder = -1;
+    for (const [index, line] of markdown.split(/\r?\n/).entries()) {
+        const entry = candidate(line);
+        if (!entry)
+            continue;
+        const order = TODO_SEVERITY_HEADINGS.indexOf(entry);
+        const add = (diagnostic) => { diagnostics.push(diagnostic); };
+        if (line.trim() !== entry.heading)
+            add({
+                code: "todo_severity_heading_mismatch",
+                classification: "glyph_name_mismatch",
+                line: index + 1,
+                expected_heading: entry.heading,
+                recovery: `Replace TODO.md line ${index + 1} with '${entry.heading}'.`,
+            });
+        if (seen.has(entry.section))
+            add({
+                code: "todo_severity_heading_duplicate",
+                classification: "duplicate",
+                line: index + 1,
+                expected_heading: entry.heading,
+                recovery: `Keep exactly one '${entry.heading}' section and move its rows there.`,
+            });
+        if (order < greatestOrder)
+            add({
+                code: "todo_severity_heading_out_of_order",
+                classification: "out_of_order",
+                line: index + 1,
+                expected_heading: entry.heading,
+                recovery: "Order managed TODO sections as Critical, Degraded, Normal, Annoying, then Resolved; missing sections are allowed.",
+            });
+        seen.add(entry.section);
+        greatestOrder = Math.max(greatestOrder, order);
+    }
+    return { diagnostics: diagnostics.slice(0, DIAGNOSTIC_LIMIT), omitted_count: Math.max(0, diagnostics.length - DIAGNOSTIC_LIMIT) };
+}
+export function assertTodoSeverityHeadingStructure(markdown) {
+    const diagnosis = inspectTodoSeverityHeadings(markdown);
+    if (!diagnosis.diagnostics.length)
+        return;
+    reject({
+        class: "conflict",
+        message: "TODO.md managed severity section structure is malformed",
+        diagnosis: { classification: "todo_severity_heading_structure", ...diagnosis },
+        recovery: "Apply every bounded TODO.md heading correction exactly as reported, then retry; no state was changed.",
+    });
+}

package/dist/state/todoTransitionBatch.js

@@ -0,0 +1,65 @@
+import { createHash } from "node:crypto";
+import { canonicalRecordJson } from "./archiveDiscovery.js";
+import { reject } from "./write/errors.js";
+const ID = /^[a-z]{10}$/;
+const DATE = /^\d{4}-\d{2}-\d{2}$/;
+const SEVERITIES = new Set(["critical", "degraded", "normal", "annoying"]);
+export function todoTransitionBatchPostStateSha256(record) {
+    const value = structuredClone(record);
+    if (value.reconciliation && typeof value.reconciliation === "object" && !Array.isArray(value.reconciliation))
+        delete value.reconciliation.transition_batch;
+    return createHash("sha256").update(canonicalRecordJson(value)).digest("hex");
+}
+export function matchesTodoTransitionBatchPostState(record, receipt, entry, verb) {
+    const lifecycle = record.lifecycle && typeof record.lifecycle === "object" && !Array.isArray(record.lifecycle) ? record.lifecycle : null;
+    return receipt.post_state_sha256 === todoTransitionBatchPostStateSha256(record)
+        && lifecycle !== null
+        && canonicalRecordJson(lifecycle) === canonicalRecordJson({ operation: verb, reason: entry.reason, date: entry.date })
+        && (verb === "set-severity" ? record.severity === entry.severity : record.status === "resolved");
+}
+export function parseTodoTransitionBatch(input, verb) {
+    if (verb !== "set-severity" && verb !== "resolve")
+        return null;
+    const version = `agentera.todo${verb === "set-severity" ? "SetSeverity" : "Resolve"}Batch.v1`;
+    if (!input || input.schema_version !== version)
+        return null;
+    const member = verb === "set-severity" ? "transitions" : "resolutions";
+    const values = input[member];
+    const violations = [];
+    if (Object.keys(input).sort().join(",") !== ["schema_version", member].sort().join(",") || !Array.isArray(values))
+        violations.push(`batch envelope must contain exactly schema_version and ${member}`);
+    if (!Array.isArray(values) || values.length < 1 || values.length > 256)
+        violations.push(`${member} must contain 1 to 256 entries`);
+    const expected = verb === "set-severity" ? "date,id,reason,severity" : "date,id,reason";
+    const entries = (Array.isArray(values) ? values : []).map((value, index) => {
+        const item = value && typeof value === "object" && !Array.isArray(value) ? value : {};
+        if (Object.keys(item).sort().join(",") !== expected)
+            violations.push(`${member}[${index}] must contain exactly ${expected.split(",").join(", ")}`);
+        const id = String(item.id ?? "");
+        const reason = String(item.reason ?? "").trim();
+        const date = String(item.date ?? "");
+        const severity = item.severity === undefined ? undefined : String(item.severity);
+        if (!ID.test(id))
+            violations.push(`${member}[${index}].id must be a bare ten-letter TODO ID`);
+        if (!reason || [...reason].length > 500)
+            violations.push(`${member}[${index}].reason must contain 1 to 500 code points`);
+        const timestamp = Date.parse(`${date}T00:00:00Z`);
+        if (!DATE.test(date) || Number.isNaN(timestamp) || new Date(timestamp).toISOString().slice(0, 10) !== date)
+            violations.push(`${member}[${index}].date must be a valid YYYY-MM-DD date`);
+        if (verb === "set-severity" && !SEVERITIES.has(severity ?? ""))
+            violations.push(`${member}[${index}].severity is invalid`);
+        return { id, reason, date, ...(severity === undefined ? {} : { severity }) };
+    });
+    const seen = new Set();
+    for (const { id } of entries) {
+        if (id && seen.has(id))
+            violations.push(`duplicate ${verb} target '${id}'`);
+        seen.add(id);
+    }
+    if (violations.length)
+        reject({ class: "schema_violation", message: `todo ${verb} batch input is invalid`, violations, recovery: `Correct the strict ${version} envelope, then preview it again; no state was changed.` });
+    return { verb, entries };
+}
+export function todoTransitionBatchEffectSha256(input, mappingSha256, targets) {
+    return createHash("sha256").update(canonicalRecordJson({ input, mapping_sha256: mappingSha256, targets })).digest("hex");
+}

package/dist/state/todoUpdateBatch.js

@@ -0,0 +1,50 @@
+import { createHash } from "node:crypto";
+import { canonicalRecordJson } from "./archiveDiscovery.js";
+import { todoInputViolations } from "./todoDocsEntityValidation.js";
+import { reject } from "./write/errors.js";
+export const TODO_UPDATE_BATCH_VERSION = "agentera.todoUpdateBatch.v1";
+const ID = /^[a-z]{10}$/;
+function mapping(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+export function inspectTodoUpdateBatch(input) {
+    if (!input || input.schema_version !== TODO_UPDATE_BATCH_VERSION)
+        return null;
+    const strictEnvelope = Object.keys(input).sort().join(",") === "schema_version,updates" && Array.isArray(input.updates);
+    const violations = [];
+    if (Object.keys(input).sort().join(",") !== "schema_version,updates")
+        violations.push("batch envelope must contain exactly schema_version and updates");
+    if (!Array.isArray(input.updates) || input.updates.length < 1 || input.updates.length > 256)
+        violations.push("updates must contain 1 to 256 entries");
+    const updates = (Array.isArray(input.updates) ? input.updates : []).map((value, index) => {
+        if (!mapping(value) || Object.keys(value).sort().join(",") !== "id,patch" || !ID.test(String(value.id ?? "")) || !mapping(value.patch)) {
+            violations.push(`updates[${index}] must contain exactly one bare id and one patch mapping`);
+            return { id: "", patch: {} };
+        }
+        violations.push(...todoInputViolations(value.patch, "update").map((item) => `updates[${index}].patch: ${item}`));
+        return { id: String(value.id), patch: value.patch };
+    });
+    const seen = new Set();
+    for (const { id } of updates) {
+        if (id && seen.has(id))
+            violations.push(`duplicate update target '${id}'`);
+        seen.add(id);
+    }
+    return { strictEnvelope, updates, violations };
+}
+export function parseTodoUpdateBatch(input) {
+    const inspected = inspectTodoUpdateBatch(input);
+    if (!inspected)
+        return null;
+    if (inspected.violations.length)
+        reject({ class: "schema_violation", message: "todo update batch input is invalid", violations: inspected.violations, recovery: "Correct the strict agentera.todoUpdateBatch.v1 envelope, then preview it again; no state was changed." });
+    return inspected.updates;
+}
+export function todoUpdateBatchEffectSha256(input, mappingSha256, targets) {
+    return createHash("sha256").update(canonicalRecordJson({
+        schema_version: TODO_UPDATE_BATCH_VERSION,
+        input,
+        mapping_sha256: mappingSha256,
+        targets,
+    })).digest("hex");
+}

package/dist/state/write/assign.js

@@ -0,0 +1,20 @@
+import { yamlEntryNumber } from "../../hooks/compaction/index.js";
+function list(doc, key) {
+    return Array.isArray(doc[key]) ? doc[key] : [];
+}
+export function nextEntryNumber(doc, activeKey) {
+    const numbers = [...list(doc, activeKey), ...list(doc, "archive")].map(yamlEntryNumber);
+    return Math.max(0, ...numbers) + 1;
+}
+export function nextTaskNumber(doc) {
+    return Math.max(0, ...list(doc, "tasks").map(yamlEntryNumber)) + 1;
+}
+export function localDate(now = new Date()) {
+    const y = now.getFullYear();
+    const m = String(now.getMonth() + 1).padStart(2, "0");
+    const d = String(now.getDate()).padStart(2, "0");
+    return `${y}-${m}-${d}`;
+}
+export function localTimestamp(now = new Date()) {
+    return `${localDate(now)} ${String(now.getHours()).padStart(2, "0")}:${String(now.getMinutes()).padStart(2, "0")}`;
+}

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);
+}