agentcert 0.2.4 → 0.2.6

package/README.md

@@ -49,6 +49,11 @@ files, 10 MiB per file, and 50 MiB total. Skipped references are reported in
 the CLI and hosted run timeline. Companion uploads are restricted to
 PNG/JPEG/WebP, JSON/JSONL, HTML, PDF, and ZIP; other extensions are skipped
 before they are read. Pass `--no-artifacts` to upload only the JSON bundle.
+Hosted pushes embed an `agentcert.artifact_manifest.v0.1` declaration with the
+normalized path, SHA-256 digest, byte size, and kind of every prepared
+companion artifact. The control plane reports `complete` only after every
+hosted object exactly matches that declaration; missing, skipped, undeclared,
+or mismatched artifacts remain observable as `partial` or `rejected`.
 Project API keys can create runs, record events, and upload evidence, but
 cannot approve their own runtime actions.
 

package/dist/artifact-manifest.js

@@ -0,0 +1,37 @@
+import { createHash } from "node:crypto";
+import { AGENTCERT_ARTIFACT_MANIFEST_VERSION, } from "./types.js";
+export function buildArtifactManifest(artifacts) {
+    const entries = artifacts.map((artifact) => ({
+        path: normalizeManifestPath(artifact.sourcePath),
+        sha256: createHash("sha256").update(artifact.bytes).digest("hex"),
+        sizeBytes: artifact.bytes.byteLength,
+        kind: artifact.kind,
+    })).sort((left, right) => left.path.localeCompare(right.path));
+    const paths = new Set();
+    for (const entry of entries) {
+        if (paths.has(entry.path))
+            throw new Error(`Artifact manifest contains duplicate path ${entry.path}.`);
+        paths.add(entry.path);
+    }
+    return { schemaVersion: AGENTCERT_ARTIFACT_MANIFEST_VERSION, entries };
+}
+export function withArtifactManifest(bundle, artifacts) {
+    return { ...bundle, artifactManifest: buildArtifactManifest(artifacts) };
+}
+export function serializeHostedEvidenceBundle(bundle, artifacts) {
+    const reconciledBundle = withArtifactManifest(bundle, artifacts);
+    return {
+        bundle: reconciledBundle,
+        bytes: new TextEncoder().encode(`${JSON.stringify(reconciledBundle, null, 2)}\n`),
+    };
+}
+export function normalizeManifestPath(value) {
+    const path = value.replace(/\\/g, "/").replace(/^\.\//, "").trim();
+    if (!path || path.length > 1024 || path.startsWith("/") || /^[A-Za-z]:\//.test(path)) {
+        throw new Error(`Artifact manifest path must be a relative path: ${value}`);
+    }
+    if (path.split("/").some((segment) => segment === ".." || segment === "")) {
+        throw new Error(`Artifact manifest path cannot contain empty or parent segments: ${value}`);
+    }
+    return path;
+}

package/dist/cli.js

@@ -20,10 +20,17 @@ import { serveAgentCertMonitor } from "./local-server.js";
 import { parseSchemaId, validateAgentCertSchema } from "./schema-validator.js";
 import { applyRunOverrides, loadRunProfile, profileFromArtifactFlags, renderRunSummary, runAgentCertProfile, } from "./runner.js";
 import { buildRobustnessLabSnapshot, readRobustnessLabConfig, renderRobustnessLabSummary, writeRobustnessLabSnapshot } from "./lab.js";
+import { renderCommandHelp } from "./command-help.js";
 process.on("uncaughtException", reportFatalError);
 process.on("unhandledRejection", reportFatalError);
 const command = process.argv[2] ?? "help";
-if (command === "init") {
+const commandHelp = process.argv.some((argument) => argument === "--help" || argument === "-h")
+    ? renderCommandHelp(command)
+    : undefined;
+if (commandHelp) {
+    process.stdout.write(commandHelp);
+}
+else if (command === "init") {
     const outPath = resolve(readFlag("--out") ?? "agentcert.config.json");
     const tripwireConfigPath = resolve(readFlag("--tripwire-config") ?? "tripwire.yml");
     const githubWorkflowPath = resolve(readFlag("--github-action-out") ?? ".github/workflows/agentcert-tripwire.yml");

package/dist/command-help.js

@@ -0,0 +1,19 @@
+export function renderCommandHelp(command) {
+    if (command !== "push")
+        return undefined;
+    return `Usage:
+  agentcert push --evidence .agentcert/latest/agentcert-evidence.json
+  agentcert push --evidence <path> --server <url> --project <project-id> [--api-key <key>]
+
+Options:
+  --evidence <path>       Evidence bundle (default: .agentcert/latest/agentcert-evidence.json)
+  --connection <name>    Saved hosted connection
+  --server <url>         Hosted AgentCert base URL
+  --project <id>         Hosted project ID
+  --api-key <key>        Project API key (prefer AGENTCERT_API_KEY in CI)
+  --external-id <id>     Idempotent hosted run ID
+  --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 { serializeHostedEvidenceBundle } from "./artifact-manifest.js";
 import { MAX_REPORTED_COMPANION_ARTIFACT_SKIPS, } from "./companion-artifacts.js";
 export class ControlPlaneRequestError extends Error {
     status;
@@ -40,8 +41,16 @@ export async function pushEvidenceToControlPlane(options) {
     }
     const request = options.fetch ?? fetch;
     const projectUrl = `${baseUrl}/v1/projects/${encodeURIComponent(options.projectId)}`;
-    const externalId = options.externalId ?? options.bundle.runId;
-    const kind = hostedRunKind(options.bundle);
+    const companionArtifacts = options.companionArtifacts ?? [];
+    const hostedEvidence = options.companionArtifacts === undefined && options.bundle.artifactManifest
+        ? {
+            bundle: options.bundle,
+            bytes: new TextEncoder().encode(`${JSON.stringify(options.bundle, null, 2)}\n`),
+        }
+        : serializeHostedEvidenceBundle(options.bundle, companionArtifacts);
+    const bundle = hostedEvidence.bundle;
+    const externalId = options.externalId ?? bundle.runId;
+    const kind = hostedRunKind(bundle);
     const headers = { authorization: `Bearer ${options.apiKey}` };
     const run = await requestJson(request, `${projectUrl}/runs`, {
         method: "POST",
@@ -49,11 +58,11 @@ export async function pushEvidenceToControlPlane(options) {
         body: JSON.stringify({
             externalId,
             kind,
-            schemaVersion: options.bundle.schemaVersion,
-            startedAt: options.bundle.generatedAt,
+            schemaVersion: bundle.schemaVersion,
+            startedAt: bundle.generatedAt,
             metadata: {
-                subject: options.bundle.subject,
-                products: options.bundle.summary.products,
+                subject: bundle.subject,
+                products: bundle.summary.products,
             },
         }),
     });
@@ -65,12 +74,12 @@ export async function pushEvidenceToControlPlane(options) {
                     sequence: 0,
                     type: "agentcert.evidence.created",
                     actor: "agentcert-cli",
-                    occurredAt: options.bundle.generatedAt,
+                    occurredAt: bundle.generatedAt,
                     payload: {
-                        verdict: options.bundle.verdict,
-                        totalEvidence: options.bundle.summary.totalEvidence,
-                        criticalEvidence: options.bundle.summary.criticalEvidence,
-                        highEvidence: options.bundle.summary.highEvidence,
+                        verdict: bundle.verdict,
+                        totalEvidence: bundle.summary.totalEvidence,
+                        criticalEvidence: bundle.summary.criticalEvidence,
+                        highEvidence: bundle.summary.highEvidence,
                     },
                 }],
         }),
@@ -78,22 +87,21 @@ export async function pushEvidenceToControlPlane(options) {
     const query = new URLSearchParams({
         fileName: options.fileName ?? "agentcert-evidence.json",
         kind: "evidence_bundle",
-        schemaVersion: options.bundle.schemaVersion,
+        schemaVersion: bundle.schemaVersion,
         runId: run.id,
     });
     const evidence = await requestJson(request, `${projectUrl}/evidence?${query}`, {
         method: "POST",
         headers: { ...headers, "content-type": "application/json" },
-        body: new Uint8Array(options.evidenceBytes).buffer,
+        body: new Uint8Array(hostedEvidence.bytes).buffer,
     });
-    const companionArtifacts = options.companionArtifacts ?? [];
     const skippedArtifacts = options.skippedCompanionArtifacts ?? [];
     let artifactBytesUploaded = 0;
     for (const artifact of companionArtifacts) {
         const artifactQuery = new URLSearchParams({
             fileName: artifact.fileName,
             kind: artifact.kind,
-            schemaVersion: options.bundle.schemaVersion,
+            schemaVersion: bundle.schemaVersion,
             runId: run.id,
             sourcePath: artifact.sourcePath,
         });
@@ -113,7 +121,7 @@ export async function pushEvidenceToControlPlane(options) {
                         sequence: 1,
                         type: "agentcert.companion_artifacts.processed",
                         actor: "agentcert-cli",
-                        occurredAt: options.bundle.generatedAt,
+                        occurredAt: bundle.generatedAt,
                         payload: {
                             uploadedCount: companionArtifacts.length,
                             skippedCount: skippedArtifacts.length,
@@ -127,19 +135,20 @@ export async function pushEvidenceToControlPlane(options) {
             }),
         });
     }
-    const firstDivergence = options.bundle.evidence.find((item) => item.severity === "critical" || item.severity === "high")?.message;
+    const firstDivergence = bundle.evidence.find((item) => item.severity === "critical" || item.severity === "high")?.message;
     await requestJson(request, `${projectUrl}/runs/${encodeURIComponent(run.id)}/complete`, {
         method: "POST",
         headers: { ...headers, "content-type": "application/json" },
         body: JSON.stringify({
-            status: options.bundle.verdict.passed ? "passed" : "failed",
-            score: options.bundle.verdict.score,
-            summary: `${options.bundle.subject.name}: ${options.bundle.verdict.level}`,
+            status: bundle.verdict.passed ? "passed" : "failed",
+            score: bundle.verdict.score,
+            summary: `${bundle.subject.name}: ${bundle.verdict.level}`,
             firstDivergence,
-            completedAt: options.bundle.generatedAt,
+            completedAt: bundle.generatedAt,
             metadata: {
                 evidenceId: evidence.id,
-                evidenceSchemaVersion: options.bundle.schemaVersion,
+                evidenceSchemaVersion: bundle.schemaVersion,
+                artifactManifestVersion: bundle.artifactManifest?.schemaVersion,
                 companionArtifactsUploaded: companionArtifacts.length,
                 companionArtifactsSkipped: skippedArtifacts.length,
                 companionArtifactBytesUploaded: artifactBytesUploaded,

package/dist/types.js

@@ -1,2 +1,3 @@
 export const AGENTCERT_EVIDENCE_SCHEMA_VERSION = "agentcert.evidence.v0.1";
 export const AGENTCERT_EVIDENCE_SCHEMA_SEMVER = "0.1.0";
+export const AGENTCERT_ARTIFACT_MANIFEST_VERSION = "agentcert.artifact_manifest.v0.1";

package/package.json

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