agentcert 0.6.0 → 0.6.1

package/README.md

@@ -64,7 +64,9 @@ case by declaring the exact reviewed scope:
 npx agentcert run --config agentcert.config.json --push \
   --assurance-case "$AGENTCERT_ASSURANCE_CASE_ID" \
   --assurance-scope agentcert.assurance-scope.json \
-  --assurance-trigger auto
+  --assurance-trigger auto \
+  --require-current auto \
+  --continuous-health-out .agentcert/canary/generated-kit-health.json
 ```
 
 Validate the scope before CI uses it:
@@ -79,6 +81,10 @@ npx agentcert schema validate \
 and other GitHub runs as release checks. Authoritative failure or scope drift
 sets the Hosted contract to `REVALIDATION_REQUIRED`; only an independently
 issued successor case establishes a new `CURRENT` baseline.
+Release and nightly checks fail unless Hosted returns `CURRENT`. The optional
+health output is redacted and captures the Hosted run/evidence identifiers,
+evidence completeness, freshness transition, and install-to-CURRENT timing for
+external canaries and operational dashboards.
 
 Add `--push` to `agentcert run` to run locally and upload the resulting bundle
 in one command. By default, both commands also upload local files referenced by

package/dist/cli.js

@@ -9,7 +9,7 @@ import { collectCompanionArtifacts, MAX_REPORTED_COMPANION_ARTIFACT_SKIPS } from
 import { recordsFromAgentCertResult, evaluateFailureClassifier, renderCorpusSummary, summarizeCorpus, writeReviewedFailureDataset, } from "./corpus.js";
 import { openCorpusStore, parseCorpusStoreKind } from "./corpus-store.js";
 import { deleteCorpusRecords, exportGovernedCorpus, governCorpusRecords, parseCorpusConsent } from "./corpus-governance.js";
-import { pushEvidenceToControlPlane, verifyControlPlaneConnection } from "./control-plane.js";
+import { pushEvidenceToControlPlane, requireContinuousAssuranceCurrent, verifyControlPlaneConnection } from "./control-plane.js";
 import { runEvidenceConformance } from "./conformance.js";
 import { DEFAULT_AGENTCERT_SERVER, resolveConnection, saveConnection } from "./credentials.js";
 import { applyFailureReviews, appendFailureReview, createFailureReview, findFailurePattern, parseFailureReviewStatus, parseFailureType, parseReviewConfidence, readFailureReviews, } from "./failure-review.js";
@@ -601,6 +601,11 @@ async function pushHostedEvidence(bundle, bytes, fileName) {
     const companions = readBoolFlag("--no-artifacts")
         ? undefined
         : await collectCompanionArtifacts(bundle, resolve(readFlag("--artifact-root") ?? process.cwd()));
+    const assurance = await readContinuousAssuranceBinding();
+    const healthOut = readFlag("--continuous-health-out");
+    const requireCurrent = readBoolFlag("--require-current");
+    if (requireCurrent && !assurance)
+        throw new Error("--require-current needs --assurance-case and --assurance-scope.");
     const result = await pushEvidenceToControlPlane({
         baseUrl: connection.server,
         projectId: connection.projectId,
@@ -611,7 +616,8 @@ async function pushHostedEvidence(bundle, bytes, fileName) {
         externalId: readFlag("--external-id"),
         companionArtifacts: companions?.artifacts,
         skippedCompanionArtifacts: companions?.skipped,
-        assurance: await readContinuousAssuranceBinding(),
+        assurance,
+        verifyContinuousAssurance: Boolean(assurance && (healthOut || requireCurrent)),
     });
     process.stdout.write(`Hosted run: ${result.runId}\nHosted evidence: ${result.evidenceId}\n`);
     if (companions) {
@@ -623,6 +629,17 @@ async function pushHostedEvidence(bundle, bytes, fileName) {
             process.stderr.write(`${companions.skipped.length - MAX_REPORTED_COMPANION_ARTIFACT_SKIPS} additional skipped artifacts omitted.\n`);
         }
     }
+    if (result.continuousAssuranceHealth) {
+        process.stdout.write(`Hosted assurance: ${result.continuousAssuranceHealth.status} (${result.continuousAssuranceHealth.healthy ? "healthy" : "attention required"})\n`);
+        if (healthOut) {
+            const outputPath = resolve(healthOut);
+            await mkdir(dirname(outputPath), { recursive: true });
+            await writeFile(outputPath, `${JSON.stringify(result.continuousAssuranceHealth, null, 2)}\n`, "utf8");
+            process.stdout.write(`Continuous assurance health: ${outputPath}\n`);
+        }
+        if (requireCurrent)
+            requireContinuousAssuranceCurrent(result.continuousAssuranceHealth);
+    }
 }
 async function readContinuousAssuranceBinding() {
     const caseId = readFlag("--assurance-case");

package/dist/command-help.js

@@ -37,6 +37,8 @@ Options:
   --assurance-case <id>  Issued assurance case to reconcile
   --assurance-scope <p>  Declared agent/model/prompt/tools/policy/suite scope JSON
   --assurance-trigger <t> auto, pull_request, release, or nightly (default: auto)
+  --require-current       Fail unless Hosted confirms authoritative CURRENT and complete evidence
+  --continuous-health-out <path>  Write the redacted Hosted health contract
   --artifact-root <dir>  Allowed root for companion artifacts (default: current directory)
   --no-artifacts         Upload only the evidence bundle
   --help, -h             Show this help

package/dist/control-plane.js

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import { serializeHostedEvidenceBundle } from "./artifact-manifest.js";
 import { MAX_REPORTED_COMPANION_ARTIFACT_SKIPS, } from "./companion-artifacts.js";
 export class ControlPlaneRequestError extends Error {
@@ -58,6 +59,8 @@ export async function pushEvidenceToControlPlane(options) {
     const externalId = options.externalId ?? bundle.runId;
     const kind = hostedRunKind(bundle);
     const headers = { authorization: `Bearer ${options.apiKey}` };
+    const trace = hostedTrace(options.projectId, externalId);
+    const observationEvents = buildHostedObservationEvents(bundle, trace);
     const run = await requestJson(request, `${projectUrl}/runs`, {
         method: "POST",
         headers: { ...headers, "content-type": "application/json" },
@@ -66,6 +69,8 @@ export async function pushEvidenceToControlPlane(options) {
             kind,
             schemaVersion: bundle.schemaVersion,
             startedAt: bundle.generatedAt,
+            traceId: trace.traceId,
+            rootSpanId: trace.rootSpanId,
             metadata: {
                 subject: bundle.subject,
                 products: bundle.summary.products,
@@ -77,18 +82,7 @@ export async function pushEvidenceToControlPlane(options) {
         method: "POST",
         headers: { ...headers, "content-type": "application/json" },
         body: JSON.stringify({
-            events: [{
-                    sequence: 0,
-                    type: "agentcert.evidence.created",
-                    actor: "agentcert-cli",
-                    occurredAt: bundle.generatedAt,
-                    payload: {
-                        verdict: bundle.verdict,
-                        totalEvidence: bundle.summary.totalEvidence,
-                        criticalEvidence: bundle.summary.criticalEvidence,
-                        highEvidence: bundle.summary.highEvidence,
-                    },
-                }],
+            events: observationEvents,
         }),
     });
     const query = new URLSearchParams({
@@ -119,29 +113,32 @@ export async function pushEvidenceToControlPlane(options) {
         });
         artifactBytesUploaded += artifact.bytes.byteLength;
     }
-    if (companionArtifacts.length > 0 || skippedArtifacts.length > 0) {
-        await requestJson(request, `${projectUrl}/runs/${encodeURIComponent(run.id)}/events`, {
-            method: "POST",
-            headers: { ...headers, "content-type": "application/json" },
-            body: JSON.stringify({
-                events: [{
-                        sequence: 1,
-                        type: "agentcert.companion_artifacts.processed",
-                        actor: "agentcert-cli",
-                        occurredAt: bundle.generatedAt,
-                        payload: {
-                            uploadedCount: companionArtifacts.length,
-                            skippedCount: skippedArtifacts.length,
-                            uploadedBytes: artifactBytesUploaded,
-                            skipped: skippedArtifacts
-                                .slice(0, MAX_REPORTED_COMPANION_ARTIFACT_SKIPS)
-                                .map(({ sourcePath, reason }) => ({ sourcePath, reason })),
-                            skippedDetailsTruncated: skippedArtifacts.length > MAX_REPORTED_COMPANION_ARTIFACT_SKIPS,
-                        },
-                    }],
-            }),
-        });
-    }
+    await requestJson(request, `${projectUrl}/runs/${encodeURIComponent(run.id)}/events`, {
+        method: "POST",
+        headers: { ...headers, "content-type": "application/json" },
+        body: JSON.stringify({
+            events: [{
+                    sequence: observationEvents.length,
+                    type: "agentcert.evidence.uploaded",
+                    actor: "agentcert-cli",
+                    occurredAt: bundle.generatedAt,
+                    payload: {
+                        evidenceId: evidence.id,
+                        bundleSchemaVersion: bundle.schemaVersion,
+                        uploadedCount: companionArtifacts.length,
+                        skippedCount: skippedArtifacts.length,
+                        uploadedBytes: artifactBytesUploaded,
+                        skipped: skippedArtifacts
+                            .slice(0, MAX_REPORTED_COMPANION_ARTIFACT_SKIPS)
+                            .map(({ sourcePath, reason }) => ({ sourcePath, reason })),
+                        skippedDetailsTruncated: skippedArtifacts.length > MAX_REPORTED_COMPANION_ARTIFACT_SKIPS,
+                    },
+                    traceId: trace.traceId,
+                    spanId: stableSpanId(`${trace.traceId}:evidence-uploaded`),
+                    parentSpanId: trace.rootSpanId,
+                }],
+        }),
+    });
     const firstDivergence = bundle.evidence.find((item) => item.severity === "critical" || item.severity === "high")?.message;
     await requestJson(request, `${projectUrl}/runs/${encodeURIComponent(run.id)}/complete`, {
         method: "POST",
@@ -162,6 +159,17 @@ export async function pushEvidenceToControlPlane(options) {
             },
         }),
     });
+    const continuousAssuranceHealth = options.assurance && options.verifyContinuousAssurance
+        ? await loadContinuousAssuranceHealth({
+            baseUrl,
+            projectId: options.projectId,
+            apiKey: options.apiKey,
+            runId: run.id,
+            expectedCaseId: options.assurance.caseId,
+            expectedScopeFingerprintSha256: scopeFingerprint(options.assurance.scope),
+            fetch: request,
+        })
+        : undefined;
     return {
         runId: run.id,
         evidenceId: evidence.id,
@@ -169,8 +177,67 @@ export async function pushEvidenceToControlPlane(options) {
         artifactsUploaded: companionArtifacts.length,
         artifactsSkipped: skippedArtifacts.length,
         artifactBytesUploaded,
+        ...(continuousAssuranceHealth ? { continuousAssuranceHealth } : {}),
+    };
+}
+export async function loadContinuousAssuranceHealth(options) {
+    const baseUrl = options.baseUrl.replace(/\/$/, "");
+    const request = options.fetch ?? fetch;
+    const analysis = await requestJson(request, `${baseUrl}/v1/projects/${encodeURIComponent(options.projectId)}/runs/${encodeURIComponent(options.runId)}/analysis`, { headers: { authorization: `Bearer ${options.apiKey}` } });
+    const run = object(analysis.run);
+    const metadata = object(run.metadata);
+    const binding = object(metadata.continuousAssurance);
+    const reconciliation = object(binding.reconciliation);
+    const completeness = object(analysis.evidenceCompleteness);
+    const manifest = object(completeness.reconciliation);
+    const runStatus = text(run.status) ?? "unknown";
+    const nextStatus = assuranceStatus(reconciliation.nextStatus);
+    const evidenceStatus = evidenceCompletenessStatus(completeness.status);
+    const diagnostics = [];
+    if (!text(binding.caseId))
+        diagnostics.push(diagnostic("assurance_binding_missing", "Hosted run has no continuous assurance binding.", "Regenerate the kit from an issued assurance case and rerun the workflow."));
+    if (options.expectedCaseId && binding.caseId !== options.expectedCaseId)
+        diagnostics.push(diagnostic("assurance_case_mismatch", "Hosted run is bound to a different assurance case.", "Use the unmodified generated workflow and case ID."));
+    if (options.expectedScopeFingerprintSha256 && binding.scopeFingerprintSha256 !== options.expectedScopeFingerprintSha256)
+        diagnostics.push(diagnostic("scope_fingerprint_mismatch", "Hosted scope fingerprint does not match the generated scope file.", "Restore the generated scope file or start a formal revalidation."));
+    if (reconciliation.authoritative !== true)
+        diagnostics.push(diagnostic("non_authoritative_trigger", "The Hosted reconciliation is prospective, not authoritative.", "Run the release or nightly workflow; pull requests cannot establish CURRENT."));
+    if (reconciliation.outcome !== "current" || nextStatus !== "CURRENT")
+        diagnostics.push(diagnostic("assurance_not_current", `Hosted reconciliation ended in ${nextStatus}.`, "Review changed scope components or failed tests, then revalidate before release."));
+    if (runStatus !== "passed")
+        diagnostics.push(diagnostic("run_not_passed", `Hosted run status is ${runStatus}.`, "Open the run trace, fix the first divergence, and rerun the same generated kit."));
+    if (evidenceStatus !== "complete")
+        diagnostics.push(diagnostic("evidence_incomplete", `Hosted evidence is ${evidenceStatus}.`, "Upload every declared companion artifact and verify manifest hashes before retrying."));
+    return {
+        schemaVersion: "agentcert.continuous_assurance_health.v0.1",
+        healthy: diagnostics.length === 0,
+        status: nextStatus,
+        checkedAt: new Date().toISOString(),
+        run: { id: text(run.id) ?? options.runId, externalId: text(run.externalId) ?? "unknown", status: runStatus },
+        assurance: {
+            caseId: text(binding.caseId),
+            trigger: assuranceTrigger(binding.trigger),
+            scopeFingerprintSha256: text(binding.scopeFingerprintSha256),
+            authoritative: boolean(reconciliation.authoritative),
+            outcome: text(reconciliation.outcome),
+            firstAuthoritativeCurrentAt: text(reconciliation.firstAuthoritativeCurrentAt),
+            timeToFirstCurrentMs: finiteNumber(reconciliation.timeToFirstCurrentMs),
+        },
+        evidence: {
+            status: evidenceStatus,
+            declared: finiteNumber(manifest.declared) ?? 0,
+            matched: finiteNumber(manifest.matched) ?? 0,
+            reasons: stringArray(completeness.reasons),
+        },
+        diagnostics,
     };
 }
+export function requireContinuousAssuranceCurrent(health) {
+    if (health.healthy)
+        return;
+    const details = health.diagnostics.map((item) => `${item.code}: ${item.message} ${item.recovery}`).join("\n");
+    throw new Error(`Hosted continuous assurance did not reach CURRENT.\n${details}`);
+}
 function hostedRunKind(bundle) {
     const products = new Set(bundle.summary.products);
     if (products.size > 1)
@@ -183,6 +250,135 @@ function hostedRunKind(bundle) {
         return "runtime";
     return "custom";
 }
+function hostedTrace(projectId, externalId) {
+    const traceId = createHash("sha256").update(`agentcert:${projectId}:${externalId}`).digest("hex").slice(0, 32);
+    return { traceId, rootSpanId: stableSpanId(`${traceId}:root`) };
+}
+function buildHostedObservationEvents(bundle, trace) {
+    const events = [{
+            sequence: 0,
+            type: "agentcert.run.started",
+            actor: "agentcert-cli",
+            occurredAt: bundle.generatedAt,
+            payload: redactedPayload({ subject: bundle.subject, products: bundle.summary.products, schemaVersion: bundle.schemaVersion }),
+            traceId: trace.traceId,
+            spanId: trace.rootSpanId,
+        }];
+    for (const [resultIndex, result] of bundle.results.entries()) {
+        if (events.length >= 478)
+            break;
+        const resultSpanId = stableSpanId(`${trace.traceId}:result:${resultIndex}:${result.runId}`);
+        events.push({
+            sequence: events.length,
+            type: "agentcert.product.result",
+            actor: result.product,
+            occurredAt: result.timestamp || bundle.generatedAt,
+            payload: redactedPayload({ product: result.product, phase: result.phase, passed: result.passed, score: result.score, certLevel: result.certLevel, summary: result.summary, sourceRunId: result.runId }),
+            traceId: trace.traceId,
+            spanId: resultSpanId,
+            parentSpanId: trace.rootSpanId,
+        });
+        for (const [findingIndex, finding] of result.evidence.entries()) {
+            if (events.length >= 478)
+                break;
+            events.push({
+                sequence: events.length,
+                type: findingEventType(result.product, finding.kind),
+                actor: result.product,
+                occurredAt: result.timestamp || bundle.generatedAt,
+                payload: redactedPayload({
+                    findingId: finding.id,
+                    kind: finding.kind,
+                    severity: finding.severity,
+                    message: finding.message,
+                    source: finding.source,
+                    artifactPath: finding.artifactPath,
+                    suggestedFix: finding.suggestedFix,
+                    metadata: finding.metadata,
+                    passed: !new Set(["critical", "high"]).has(finding.severity),
+                }),
+                traceId: trace.traceId,
+                spanId: stableSpanId(`${trace.traceId}:finding:${resultIndex}:${findingIndex}:${finding.id}`),
+                parentSpanId: resultSpanId,
+            });
+        }
+    }
+    events.push({
+        sequence: events.length,
+        type: "agentcert.run.evaluated",
+        actor: "agentcert-cli",
+        occurredAt: bundle.generatedAt,
+        payload: redactedPayload({ verdict: bundle.verdict, summary: bundle.summary, evidenceStrength: bundle.evidenceStrength?.level }),
+        traceId: trace.traceId,
+        spanId: stableSpanId(`${trace.traceId}:evaluated`),
+        parentSpanId: trace.rootSpanId,
+    });
+    return events;
+}
+function findingEventType(product, kind) {
+    if (product === "tripwire-ci")
+        return "tripwire.fault.assertion";
+    if (product === "mcpbench")
+        return /policy|permission|security|violation/i.test(kind) ? "mcpbench.policy.violation" : "mcpbench.assertion";
+    if (product === "onegent-runtime") {
+        if (/approval/i.test(kind))
+            return "onegent.approval.decision";
+        if (/outcome|verification/i.test(kind))
+            return "onegent.outcome.verification";
+        if (/policy|mandate|authorization/i.test(kind))
+            return "onegent.policy.decision";
+        return "onegent.action.observation";
+    }
+    return "agentcert.finding";
+}
+function stableSpanId(seed) {
+    return createHash("sha256").update(seed).digest("hex").slice(0, 16);
+}
+function redactedPayload(value, depth = 0) {
+    if (depth > 4)
+        return "[TRUNCATED]";
+    if (typeof value === "string")
+        return value.length > 1_000 ? `${value.slice(0, 1_000)}...[TRUNCATED]` : value;
+    if (typeof value === "number" || typeof value === "boolean" || value === null)
+        return value;
+    if (Array.isArray(value))
+        return value.slice(0, 50).map((item) => redactedPayload(item, depth + 1));
+    if (value && typeof value === "object") {
+        const result = {};
+        for (const [key, item] of Object.entries(value).slice(0, 50)) {
+            result[key] = /(authorization|api.?key|token|secret|password|credential)/i.test(key) ? "[REDACTED]" : redactedPayload(item, depth + 1);
+        }
+        return result;
+    }
+    return undefined;
+}
+function scopeFingerprint(scope) {
+    return createHash("sha256").update(canonicalJson(scope)).digest("hex");
+}
+function canonicalJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(",")}]`;
+    if (value && typeof value === "object") {
+        const source = value;
+        return `{${Object.keys(source).sort().map((key) => `${JSON.stringify(key)}:${canonicalJson(source[key])}`).join(",")}}`;
+    }
+    return JSON.stringify(value) ?? "null";
+}
+function object(value) { return value && typeof value === "object" && !Array.isArray(value) ? value : {}; }
+function text(value) { return typeof value === "string" && value ? value : undefined; }
+function boolean(value) { return typeof value === "boolean" ? value : undefined; }
+function finiteNumber(value) { return typeof value === "number" && Number.isFinite(value) ? value : undefined; }
+function stringArray(value) { return Array.isArray(value) ? value.filter((item) => typeof item === "string") : []; }
+function assuranceStatus(value) {
+    return value === "CURRENT" || value === "REVALIDATION_REQUIRED" || value === "SUSPENDED" || value === "EXPIRED" ? value : "UNKNOWN";
+}
+function evidenceCompletenessStatus(value) {
+    return value === "complete" || value === "partial" || value === "rejected" ? value : "unknown";
+}
+function assuranceTrigger(value) {
+    return value === "pull_request" || value === "release" || value === "nightly" ? value : undefined;
+}
+function diagnostic(code, message, recovery) { return { code, message, recovery }; }
 async function requestJson(request, url, init) {
     let response;
     try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentcert",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "Assurance release gates, runtime evidence, and regression CI for AI agents.",
   "type": "module",
   "license": "Apache-2.0",