@kylecheng3146/agent-ops 0.5.3 → 0.7.0

package/dist/runtime/src/task/store.js

@@ -3,6 +3,8 @@ import { TASK_SCHEMA_VERSION } from "../contracts.js";
 import { AgentOpsError } from "../fs/paths.js";
 import { validateTask } from "../schema/validate.js";
 import { readPrivateFile, withPrivateFileLock, writePrivateFile } from "../security/permissions.js";
+import { taskContractHash } from "./contract.js";
+import { commitIdentity, acceptanceSourcePath } from "../schema/acceptance.js";
 const DEFAULT_MAX_BYTES = 1024 * 1024;
 const SESSION_ID_PATTERN = /^[^\0\r\n]{1,256}$/u;
 function isMissing(error) {
@@ -66,12 +68,9 @@ function parseTaskRecord(value) {
     ];
     // Every record written before an optional field existed must still parse, so
     // the accepted shapes are every combination of them.
-    const optionalKeys = ["completionBase", "failureFingerprint", "policyConfigHash", "reviewBase"];
-    const allowedKeys = new Set(Array.from({ length: 1 << optionalKeys.length }, (_unused, mask) => [
-        ...baseKeys,
-        ...optionalKeys.filter((_key, position) => (mask & (1 << position)) !== 0)
-    ].sort().join("\0")));
-    if (!isRecord(value) || !allowedKeys.has(Object.keys(value).sort().join("\0"))) {
+    const optionalKeys = ["completionBase", "failureFingerprint", "policyConfigHash", "reviewBase", "createdSourceCommit", "revisions", "supersededBy", "noChangePaths"];
+    if (!isRecord(value) || !baseKeys.every(k => Object.hasOwn(value, k)) ||
+        Object.keys(value).some(k => !baseKeys.includes(k) && !optionalKeys.includes(k))) {
         return invalidState("Task state contains an invalid task record.");
     }
     const task = validateTask(value.task);
@@ -150,8 +149,43 @@ function parseTaskRecord(value) {
         (typeof value.reviewBase !== "string" || !/^[a-f0-9]{40,64}$/u.test(value.reviewBase))) {
         return invalidState("Task state contains an invalid review base.");
     }
+    if (value.noChangePaths !== undefined && (!Array.isArray(value.noChangePaths) || value.noChangePaths.length === 0 || value.noChangePaths.length > 128 ||
+        value.noChangePaths.some(p => typeof p !== "string" || !acceptanceSourcePath(p)) || new Set(value.noChangePaths).size !== value.noChangePaths.length))
+        return invalidState("Invalid no-change scope.");
+    if (value.supersededBy !== undefined && (!Array.isArray(value.supersededBy) || value.supersededBy.length === 0 || value.supersededBy.length > 128 ||
+        value.supersededBy.some(v => typeof v !== "string" || !/^[a-z][a-z0-9-]{0,127}$/u.test(v)) || new Set(value.supersededBy).size !== value.supersededBy.length || status !== "archived"))
+        return invalidState("Invalid supersession mapping.");
+    if (value.createdSourceCommit !== undefined && !commitIdentity(value.createdSourceCommit))
+        return invalidState("Invalid task creation commit.");
+    if (value.revisions !== undefined) {
+        if (!Array.isArray(value.revisions) || value.revisions.length > 1024)
+            return invalidState("Invalid revision history.");
+        let previousCurrent;
+        for (const revision of value.revisions) {
+            if (!isRecord(revision) || !hasExactKeys(revision, ["previousTask", "previousEvidence", "previousFailure", "previousHash", "currentHash", "reason", "at", "diagnostics"]) ||
+                typeof revision.reason !== "string" || revision.reason.trim() === "" || revision.reason.length > 8192 || revision.reason.includes("\0") ||
+                !isTimestamp(revision.at) || !Array.isArray(revision.diagnostics) || revision.diagnostics.length > 512 ||
+                revision.diagnostics.some(d => typeof d !== "string" || d.length > 4096 || d.includes("\0")) ||
+                typeof revision.currentHash !== "string" || !/^[a-f0-9]{64}$/u.test(revision.currentHash))
+                return invalidState("Invalid revision metadata.");
+            const before = validateTask(revision.previousTask);
+            if (!before.ok || before.value.id !== task.value.id || taskContractHash(before.value) !== revision.previousHash ||
+                (previousCurrent !== undefined && revision.previousHash !== previousCurrent))
+                return invalidState("Invalid revision chain.");
+            parseEvidence(revision.previousEvidence, before.value, false);
+            if (revision.previousFailure !== null && (!isRecord(revision.previousFailure) || typeof revision.previousFailure.value !== "string" || !/^[a-f0-9]{64}$/u.test(revision.previousFailure.value)))
+                return invalidState("Invalid revision failure provenance.");
+            previousCurrent = revision.currentHash;
+        }
+        if (previousCurrent !== undefined && previousCurrent !== taskContractHash(task.value))
+            return invalidState("Revision history does not match current contract.");
+    }
     return {
         task: task.value,
+        ...(value.noChangePaths === undefined ? {} : { noChangePaths: value.noChangePaths }),
+        ...(value.createdSourceCommit === undefined ? {} : { createdSourceCommit: value.createdSourceCommit }),
+        ...(value.revisions === undefined ? {} : { revisions: value.revisions }),
+        ...(value.supersededBy === undefined ? {} : { supersededBy: value.supersededBy }),
         status,
         evidence,
         createdAt: value.createdAt,
@@ -204,7 +238,7 @@ function parseState(source) {
     }
     if (!isRecord(value) ||
         !hasExactKeys(value, ["schemaVersion", "sessions", "tasks"]) ||
-        value.schemaVersion !== TASK_SCHEMA_VERSION ||
+        (value.schemaVersion !== 1 && value.schemaVersion !== TASK_SCHEMA_VERSION) ||
         !Array.isArray(value.tasks) ||
         !Array.isArray(value.sessions)) {
         return invalidState("Task state has an unsupported structure.");
@@ -217,6 +251,22 @@ function parseState(source) {
         return invalidState("Task and session identifiers must be unique.");
     }
     const tasksById = new Map(tasks.map((record) => [record.task.id, record]));
+    for (const old of tasks) {
+        for (const successor of old.supersededBy ?? []) {
+            if (successor === old.task.id || !tasksById.has(successor))
+                return invalidState("Supersession must name a distinct known task.");
+            const seen = new Set([old.task.id]);
+            const visit = (id) => {
+                if (seen.has(id))
+                    return invalidState("Cyclic task supersession.");
+                seen.add(id);
+                for (const next of tasksById.get(id)?.supersededBy ?? [])
+                    visit(next);
+                seen.delete(id);
+            };
+            visit(successor);
+        }
+    }
     if (sessions.some(({ taskId }) => {
         const record = tasksById.get(taskId);
         return record === undefined || record.status === "archived";

package/dist/runtime/src/verify/acceptance-coverage.js

@@ -0,0 +1,85 @@
+import { calculateConfigHash, canonicalJson } from "../config/hash.js";
+import { readPrivateFile } from "../security/permissions.js";
+import { join } from "node:path";
+import { sha256 } from "../fs/hash.js";
+import { criterionContractHash, taskContractHash } from "../task/contract.js";
+/** Only current, paired check evidence discharges a mechanical contract. */
+export async function acceptanceCoverage(record, config, sourceFingerprint, store) {
+    const contract = taskContractHash(record.task);
+    const configHash = calculateConfigHash(config);
+    const rows = [];
+    for (const criterion of record.task.criteria) {
+        const definition = criterion.acceptance;
+        const refs = record.evidence[criterion.id] ?? [];
+        const matching = [];
+        for (const reference of refs) {
+            if (reference.startsWith("review:"))
+                continue;
+            const evidence = await store.load(reference);
+            if (evidence?.schemaVersion === 4 && evidence.taskId === record.task.id &&
+                evidence.criterionId === criterion.id && evidence.configHash === configHash &&
+                evidence.sourceFingerprint === sourceFingerprint && evidence.taskContractHash === contract &&
+                evidence.acceptance?.criterionContractHash === criterionContractHash(criterion)) {
+                matching.push({ reference, evidence });
+            }
+        }
+        const authenticated = [];
+        for (const item of matching) {
+            const proof = item.evidence.acceptance;
+            try {
+                const source = await readPrivateFile(join(store.root, ...proof.executionArtifact.split("/")), store.root);
+                if (source === null || proof.executionArtifact !== ".agent-ops/tasks/acceptance/" + sha256(source) + ".json")
+                    continue;
+                const artifact = JSON.parse(source);
+                if (artifact.commit !== proof.commit || artifact.phase !== proof.phase || artifact.pairedCommit !== proof.pairedCommit ||
+                    artifact.materialDigest !== proof.materialDigest || artifact.executionDigest !== proof.executionDigest ||
+                    artifact.runner?.id !== item.evidence.commandId || artifact.run?.completed !== true ||
+                    artifact.aggregate?.status === "UNKNOWN" || !Array.isArray(artifact.run?.results) ||
+                    proof.checks.some(check => !artifact.run.results.some((actual) => actual.checkId === check.checkId && actual.status === check.status && actual.attempts === 1 &&
+                        (actual.failureClass === "assertion-failed" ? "assertion" : actual.failureClass) === check.failureClass)))
+                    continue;
+                authenticated.push(item);
+            }
+            catch { /* Missing, modified or malformed execution records cannot prove a contract. */ }
+        }
+        const authenticatedRefs = new Set(authenticated.map(item => item.reference));
+        for (let i = 0; i < matching.length; i++)
+            if (!authenticatedRefs.has(matching[i].reference)) {
+                const item = matching[i];
+                matching[i] = { ...item, evidence: { ...item.evidence, status: "UNKNOWN", failureClass: "execution-artifact-invalid" } };
+            }
+        const row = { criterionId: criterion.id, mode: definition?.mode ?? "legacy",
+            evidenceReferences: matching.map(item => item.reference) };
+        if (definition === undefined || definition.mode === "review-only") {
+            rows.push({ ...row, status: "undischarged", reason: definition?.mode === "review-only"
+                    ? "Review-only: " + definition.reviewOnlyReason + "; requires independent review against the original goal."
+                    : "Requires independent review against the original goal." });
+            continue;
+        }
+        let proven = true;
+        for (const binding of definition.bindings) {
+            const phase = (name) => matching.filter(({ evidence }) => evidence.commandId === binding.runnerId && evidence.acceptance?.phase === name &&
+                evidence.acceptance.bindingHash === sha256(canonicalJson({ runnerId: binding.runnerId, materials: binding.materials })))
+                .sort((a, b) => Date.parse(b.evidence.finishedAt) - Date.parse(a.evidence.finishedAt) ||
+                (a.evidence.status === "PASS" ? 1 : -1))[0]?.evidence;
+            const baseline = phase("baseline");
+            const candidate = phase("candidate");
+            const base = baseline?.acceptance;
+            const head = candidate?.acceptance;
+            if (baseline?.status !== "PASS" || candidate?.status !== "PASS" || base === undefined || head === undefined ||
+                base.commit !== definition.baselineCommit || head.pairedCommit !== definition.baselineCommit ||
+                base.pairedCommit !== head.commit || base.materialDigest !== head.materialDigest ||
+                binding.checkIds.some(id => !head.checks.some(check => check.checkId === id && check.status === "PASS")) ||
+                binding.checkIds.some(id => !base.checks.some(check => check.checkId === id)) ||
+                base.checks.some(check => check.status === "UNKNOWN") ||
+                (binding.redCheckIds ?? []).some(id => !base.checks.some(check => check.checkId === id && check.status === "FAIL" && check.failureClass === "assertion")))
+                proven = false;
+        }
+        rows.push({ ...row, status: proven ? "proven" : "undischarged",
+            reason: proven ? "Current paired check evidence satisfies the contract." : "Paired check evidence is missing, stale, unknown or non-discriminating." });
+    }
+    return rows;
+}
+export function coverageDigest(rows) {
+    return sha256(canonicalJson(rows));
+}

package/dist/runtime/src/verify/acceptance-protocol.js

@@ -0,0 +1,252 @@
+/**
+ * The small, framework-neutral result protocol used by acceptance adapters.
+ *
+ * Adapters are deliberately consumers of structured harness output. They do
+ * not infer assertion failures from arbitrary stdout, and this module keeps
+ * the final safety decision in one place.
+ */
+export const ACCEPTANCE_PROTOCOL_VERSION = 1;
+export const ACCEPTANCE_FAILURE = {
+    assertion: "assertion-failed",
+    collection: "collection-error",
+    duplicate: "duplicate-check",
+    emptyEvidence: "empty-evidence",
+    fixture: "fixture-error",
+    hook: "hook-error",
+    incomplete: "incomplete-output",
+    infrastructure: "infrastructure-error",
+    malformed: "malformed-output",
+    missing: "missing-check",
+    retry: "retry",
+    skipped: "skipped",
+    timeout: "timeout",
+    todo: "todo",
+    unexpected: "unexpected-check",
+    unsupported: "unsupported-output",
+    xfail: "xfail"
+};
+const MAX_TEXT = 4096;
+const MAX_RESULTS = 4096;
+const MAX_EVIDENCE = 32;
+function text(value, field) {
+    if (typeof value !== "string" || value.length === 0 ||
+        value.length > MAX_TEXT || value.includes("\0") ||
+        /[\r\n]/u.test(value)) {
+        throw new TypeError(`${field} must be a bounded single-line string.`);
+    }
+    return value;
+}
+function boundedEvidence(values) {
+    if (values.length === 0 || values.length > MAX_EVIDENCE ||
+        values.some((value) => {
+            try {
+                text(value, "evidence");
+                return false;
+            }
+            catch {
+                return true;
+            }
+        })) {
+        throw new TypeError("evidence must contain one to 32 bounded strings.");
+    }
+    return [...values];
+}
+function attempts(value) {
+    if (value === null || value === undefined)
+        return null;
+    if (!Number.isSafeInteger(value) || value < 1 || value > 1000) {
+        throw new TypeError("attempts must be a positive safe integer or null.");
+    }
+    return value;
+}
+export function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function stringValue(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+export function stableCheckId(parts) {
+    const normalized = parts
+        .map((part) => part.trim())
+        .filter((part) => part.length > 0);
+    if (normalized.length === 0) {
+        throw new TypeError("A check needs a stable identity.");
+    }
+    return normalized.join("::");
+}
+export function makeAcceptanceCheck(input) {
+    const status = input.status;
+    if (status !== "PASS" && status !== "FAIL" && status !== "UNKNOWN") {
+        throw new TypeError("Invalid acceptance status.");
+    }
+    if (input.phase !== "baseline" && input.phase !== "candidate") {
+        throw new TypeError("Invalid acceptance phase.");
+    }
+    const failureClass = input.failureClass ?? (status === "PASS" ? "none" : ACCEPTANCE_FAILURE.infrastructure);
+    if (status === "PASS" && failureClass !== "none") {
+        throw new TypeError("A passing check must have failureClass none.");
+    }
+    if (status === "FAIL" && failureClass === "none") {
+        throw new TypeError("A failed check needs a failure class.");
+    }
+    return {
+        executionId: text(input.executionId, "executionId"),
+        framework: text(input.framework, "framework"),
+        frameworkVersion: text(input.frameworkVersion, "frameworkVersion"),
+        checkId: text(input.checkId, "checkId"),
+        phase: input.phase,
+        status,
+        failureClass,
+        attempts: attempts(input.attempts),
+        evidence: boundedEvidence(input.evidence)
+    };
+}
+export function makeAcceptanceRun(input) {
+    if (input.results.length > MAX_RESULTS) {
+        throw new TypeError("An acceptance run contains too many check results.");
+    }
+    if (input.phase !== "baseline" && input.phase !== "candidate") {
+        throw new TypeError("Invalid acceptance phase.");
+    }
+    const completionEvidence = input.completionEvidence ?? [];
+    if (input.completed)
+        boundedEvidence(completionEvidence);
+    const diagnostics = input.diagnostics ?? [];
+    diagnostics.forEach((value) => text(value, "diagnostic"));
+    for (const result of input.results) {
+        if (result.executionId !== input.executionId ||
+            result.framework !== input.framework ||
+            result.frameworkVersion !== input.frameworkVersion ||
+            result.phase !== input.phase) {
+            throw new TypeError("Every check result must use the run execution identity.");
+        }
+    }
+    return {
+        protocolVersion: ACCEPTANCE_PROTOCOL_VERSION,
+        executionId: text(input.executionId, "executionId"),
+        framework: text(input.framework, "framework"),
+        frameworkVersion: text(input.frameworkVersion, "frameworkVersion"),
+        phase: input.phase,
+        results: [...input.results],
+        completed: input.completed,
+        completionEvidence: [...completionEvidence],
+        diagnostics: [...diagnostics]
+    };
+}
+function sortedUnique(values) {
+    return [...new Set(values)].sort();
+}
+function unknown(run, results, failureClass, diagnostics, missingCheckIds = [], duplicateCheckIds = [], unexpectedCheckIds = []) {
+    return {
+        status: "UNKNOWN",
+        failureClass,
+        results,
+        missingCheckIds,
+        duplicateCheckIds,
+        unexpectedCheckIds,
+        diagnostics: [...run.diagnostics, ...diagnostics]
+    };
+}
+export function aggregateAcceptanceRun(run, requestedCheckIds) {
+    const requested = sortedUnique(requestedCheckIds);
+    if (requested.length !== requestedCheckIds.length || requested.length === 0) {
+        return unknown(run, run.results, ACCEPTANCE_FAILURE.malformed, [
+            "Requested check IDs must be non-empty and unique."
+        ]);
+    }
+    if (!run.completed || run.completionEvidence.length === 0) {
+        return unknown(run, run.results, ACCEPTANCE_FAILURE.incomplete, [
+            "The adapter did not emit a complete terminal marker."
+        ]);
+    }
+    const expected = new Set(requested);
+    const counts = new Map();
+    for (const result of run.results) {
+        counts.set(result.checkId, (counts.get(result.checkId) ?? 0) + 1);
+    }
+    const duplicateCheckIds = sortedUnique([...counts.entries()].filter(([, count]) => count > 1).map(([id]) => id));
+    const unexpectedCheckIds = sortedUnique(run.results.filter((result) => !expected.has(result.checkId)).map((result) => result.checkId));
+    const missingCheckIds = requested.filter((id) => !counts.has(id));
+    if (duplicateCheckIds.length > 0 || unexpectedCheckIds.length > 0 || missingCheckIds.length > 0) {
+        return unknown(run, run.results, duplicateCheckIds.length > 0 ? ACCEPTANCE_FAILURE.duplicate :
+            missingCheckIds.length > 0 ? ACCEPTANCE_FAILURE.missing : ACCEPTANCE_FAILURE.unexpected, ["The observed checks do not match the requested checks exactly."], missingCheckIds, duplicateCheckIds, unexpectedCheckIds);
+    }
+    const requestedResults = requested.map((id) => run.results.find((result) => result.checkId === id));
+    if (run.diagnostics.length > 0) {
+        return unknown(run, requestedResults, ACCEPTANCE_FAILURE.infrastructure, [
+            "The adapter reported execution diagnostics.",
+            ...run.diagnostics
+        ]);
+    }
+    for (const result of requestedResults) {
+        if (result.evidence.length === 0) {
+            return unknown(run, requestedResults, ACCEPTANCE_FAILURE.emptyEvidence, [
+                `Check ${result.checkId} has no evidence.`
+            ]);
+        }
+        if (result.attempts === null || result.attempts !== 1 || result.failureClass === ACCEPTANCE_FAILURE.retry) {
+            return unknown(run, requestedResults, ACCEPTANCE_FAILURE.retry, [
+                `Check ${result.checkId} has missing or repeated attempts.`
+            ]);
+        }
+        if (result.status === "UNKNOWN") {
+            return unknown(run, requestedResults, result.failureClass, [
+                `Check ${result.checkId} did not produce a mechanical result.`
+            ]);
+        }
+        if (result.status === "PASS" && result.failureClass !== "none") {
+            return unknown(run, requestedResults, ACCEPTANCE_FAILURE.malformed, [
+                `Check ${result.checkId} marked PASS with a failure class.`
+            ]);
+        }
+        if (result.status === "FAIL" && result.failureClass !== ACCEPTANCE_FAILURE.assertion) {
+            return unknown(run, requestedResults, result.failureClass, [
+                `Check ${result.checkId} failed outside an assertion.`
+            ]);
+        }
+    }
+    if (requestedResults.some((result) => result.status === "FAIL")) {
+        return {
+            status: "FAIL",
+            failureClass: ACCEPTANCE_FAILURE.assertion,
+            results: requestedResults,
+            missingCheckIds: [],
+            duplicateCheckIds: [],
+            unexpectedCheckIds: [],
+            diagnostics: [...run.diagnostics]
+        };
+    }
+    return {
+        status: "PASS",
+        failureClass: "none",
+        results: requestedResults,
+        missingCheckIds: [],
+        duplicateCheckIds: [],
+        unexpectedCheckIds: [],
+        diagnostics: [...run.diagnostics]
+    };
+}
+export function parseJsonLines(source) {
+    const values = [];
+    const invalidLines = [];
+    source.split(/\r?\n/u).forEach((line, index) => {
+        const trimmed = line.trim();
+        if (trimmed.length === 0)
+            return;
+        try {
+            values.push(JSON.parse(trimmed));
+        }
+        catch {
+            invalidLines.push(index + 1);
+        }
+    });
+    return { values, invalidLines };
+}
+export function parseJsonDocument(source) {
+    try {
+        return JSON.parse(source);
+    }
+    catch {
+        return undefined;
+    }
+}