@agent-delivery-harness/cli 0.1.0 → 0.5.0

package/src/review-evidence.ts

@@ -0,0 +1,284 @@
+/**
+ * The shipped review-outcome evidence writer. It transcribes concluded host
+ * results without running reviewers or upgrading their self-attestation.
+ *
+ * Capture `delivery-harness review-context --json` before review, then pass
+ * that original document to `emit-review-evidence --context <path>` with a
+ * review-outcome/1 document on stdin naming its contextDigest. Reviewer names
+ * come from the resolved activated charters; for example a named result is
+ * `{ "id": "outcome-correctness", "result": "rejected" }`.
+ *
+ * The raw context and outcome remain digest-bound artifacts. Submission is
+ * still the authority on whether the resulting evidence satisfies the gate.
+ */
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import {
+  resolveReviewCharters,
+  validateReviewedContext, parseReviewOutcome, deriveTelemetry, reviewerLists,
+  capturePortableEvidenceContext, repositoryEvidenceReader, createArtifactsPort,
+  ReviewInputError as OutcomeError,
+  BlockedError,
+  digestCanonical,
+  evaluatePreparationReceipt,
+  sha256Hex,
+  type CapturedCandidate,
+  type PreparationReceipt,
+  type HarnessConfig,
+  REVIEW_GREEN_1,
+  REVIEW_GREEN_2,
+} from "@agent-delivery-harness/kernel";
+import type { CommandContext } from "./boundary.ts";
+
+// ── The charters the compiled policy activates ───────────────────────────────
+
+/**
+ * The compiled policy this repository is judged under, and the installed
+ * generation whose archive carries the charters its lenses reference by
+ * identity. One activated lens is one reviewer, and the basename of the
+ * charter path the archive's manifest declares is the reviewer id the evidence
+ * carries — the same two documents `policy-projection-check.ts` compiles the
+ * projection from.
+ */
+export const COMPILED_SNAPSHOT_FILE = ".agents/policy/compiled-snapshot.json";
+export const INSTALLED_ARCHIVE_DIR = ".agent-skills/current";
+
+export const CHARTER_EXTENSION = ".md";
+
+/** Review payloads this provider can emit, in preference order. */
+export const REVIEW_PAYLOAD_SPECS = [REVIEW_GREEN_2, REVIEW_GREEN_1] as const;
+export const REVIEW_PAYLOAD_SPEC = REVIEW_GREEN_2;
+
+/** The envelope spec the manifest declares. */
+export const ENVELOPE_SPEC = "delivery-evidence/1";
+
+/** The outcome document this emitter reads. */
+export const OUTCOME_SPEC = "review-outcome/1";
+
+/** This emitter's own version, carried in the manifest's provider triple. */
+export const EMITTER_VERSION = "1.0.0";
+
+export type { ResolvedCharter } from "@agent-delivery-harness/kernel";
+export async function resolveActivatedCharters(rootDir: string, config?: Pick<HarnessConfig, "additionalReviewLenses">) {
+  return resolveReviewCharters(repositoryEvidenceReader(rootDir, createArtifactsPort()), config);
+}
+export async function resolveReviewerCharters(rootDir: string): Promise<string[]> {
+  return (await resolveActivatedCharters(rootDir)).map((charter) => charter.reviewerId).sort();
+}
+
+/** Exact review input, retained by the host before acquiring any outcomes. */
+export const REVIEW_CONTEXT_SPEC = "review-context/1";
+
+function manifestCandidate(captured: CapturedCandidate) {
+  return {
+    vcs: captured.vcs,
+    treeSha: captured.treeSha,
+    headSha: captured.headSha,
+    deliverable: { digest: captured.deliverable.digest, identity: captured.deliverable.identity },
+    base: { ref: captured.base.ref, tipSha: captured.base.tipSha, mergeBaseSha: captured.base.mergeBaseSha },
+    workspaceId: captured.workspaceId,
+  };
+}
+
+export async function buildReviewContext(
+  rootDir: string,
+  config: HarnessConfig,
+  candidate: CapturedCandidate,
+  receipt: PreparationReceipt,
+) {
+  const inputs = await capturePortableEvidenceContext(config, repositoryEvidenceReader(rootDir, createArtifactsPort()), receipt.preparationFingerprint);
+  const charters = inputs.reviewerCharters;
+  if (charters.length === 0 || inputs.release === null) throw new OutcomeError("the compiled policy activates no review lens or installed release");
+  const binding = {
+    gate: resolveGateBinding(config),
+    candidate: manifestCandidate(candidate),
+    preparationFingerprint: inputs.preparationFingerprint,
+    configurationDigest: inputs.configurationDigest,
+    policyDigest: inputs.policyDigest,
+    release: inputs.release,
+    workflowGraphSha256: inputs.workflowGraphSha256,
+    charters,
+  };
+  return { spec: REVIEW_CONTEXT_SPEC, digest: digestCanonical(binding), binding };
+}
+
+export type ReviewContextDocument = Awaited<ReturnType<typeof buildReviewContext>>;
+
+export { validateReviewedContext, parseReviewOutcome, deriveTelemetry, reviewerLists, REVIEWER_RESULTS } from "@agent-delivery-harness/kernel";
+export type { ReviewOutcome, ReviewerOutcome, ReviewerResult } from "@agent-delivery-harness/kernel";
+export { OutcomeError };
+// ── The gate this provider serves ────────────────────────────────────────────
+
+export interface GateBinding {
+  readonly obligationId: string;
+  readonly providerId: string;
+}
+
+/**
+ * The obligation this manifest answers, and the provider it answers as, taken
+ * from the config rather than from a constant — a provider id that has drifted
+ * from the gate it serves is rejected as `unknown_provider` at evaluation, long
+ * after the review it describes has been paid for.
+ */
+export function resolveGateBinding(config: HarnessConfig): GateBinding {
+  const obligations = config.obligations.filter((obligation) =>
+    REVIEW_PAYLOAD_SPECS.some((payloadSpec) => obligation.acceptedPayloadSpecs.includes(payloadSpec)),
+  );
+  if (obligations.length !== 1) {
+    throw new OutcomeError(
+      `the gate declares ${obligations.length} obligations accepting a supported review.green payload; this provider serves exactly one`,
+    );
+  }
+  const obligation = obligations[0]!;
+  if (obligation.providers.length !== 1) {
+    throw new OutcomeError(
+      `obligation ${obligation.id} names ${obligation.providers.length} providers; this provider serves exactly one`,
+    );
+  }
+  return { obligationId: obligation.id, providerId: obligation.providers[0]! };
+}
+
+function resolveReviewPayloadSpec(
+  config: HarnessConfig,
+  obligationId: string,
+): (typeof REVIEW_PAYLOAD_SPECS)[number] {
+  const obligation = config.obligations.find((entry) => entry.id === obligationId);
+  const payloadSpec = REVIEW_PAYLOAD_SPECS.find((candidate) => obligation?.acceptedPayloadSpecs.includes(candidate));
+  if (payloadSpec === undefined) throw new OutcomeError(`obligation ${obligationId} accepts no supported review.green payload`);
+  return payloadSpec;
+}
+
+// ── The manifest ─────────────────────────────────────────────────────────────
+
+export interface EmitResult {
+  readonly manifestPath: string;
+  readonly runRoot: string;
+}
+
+/**
+ * Capture the candidate, allocate the run root, stamp one approval per
+ * approving reviewer, and write the manifest. The capture is deliberately the
+ * same call the recorder makes at submission (same config, same workspace id,
+ * same identity computation): anything else describes a tree the recorder will
+ * refuse to recognise.
+ */
+export async function emitReviewEvidence(context: CommandContext, original: unknown, document: unknown): Promise<EmitResult> {
+  const { rootDir, config } = context;
+  const wiring = await context.wire();
+  const capture = await wiring.captureCandidate();
+  if (!capture.ok) throw new OutcomeError(`the candidate could not be captured: ${capture.code}`);
+  const captured = capture.candidate;
+  const preparation = await evaluatePreparationReceipt(rootDir, { config, candidate: captured }, wiring.storageOptions);
+  if (!preparation.prepared) throw new BlockedError([...preparation.blockers]);
+  const current = await buildReviewContext(rootDir, config, captured, preparation.receipt);
+  validateReviewedContext(original, current, document);
+  const charters = current.binding.charters.map((charter) => charter.reviewerId).sort();
+  const outcome = parseReviewOutcome(document, charters);
+  const binding = current.binding.gate;
+  const payloadSpec = resolveReviewPayloadSpec(config, binding.obligationId);
+  const candidate = manifestCandidate(captured);
+
+  const provider = {
+    id: binding.providerId,
+    version: EMITTER_VERSION,
+    // One emitter run is one evaluated pass over this candidate.
+    runId: `r-${randomUUID()}`,
+    finalPassId: outcome.finalPassId ?? "pass-1",
+  };
+  const reviewed = original as ReviewContextDocument;
+  const originalRunHistory = outcome.runHistory ?? [{
+    preparedTreeSha: reviewed.binding.candidate.treeSha,
+    evaluatedInPassId: provider.finalPassId,
+  }];
+  const finalEntry = originalRunHistory.at(-1)!;
+  if (finalEntry["preparedTreeSha"] !== reviewed.binding.candidate.treeSha ||
+      finalEntry["evaluatedInPassId"] !== provider.finalPassId) {
+    throw new OutcomeError("the supplied final review pass does not name the original reviewed candidate");
+  }
+  // ENV-9's final tree is a preparation coordinate. A proven neutral reuse
+  // projects that coordinate without claiming the reviewers saw a new raw
+  // tree, adding a round, or overwriting their original history.
+  const runHistory = originalRunHistory.map((entry, index) => index === originalRunHistory.length - 1
+    ? { ...entry, preparedTreeSha: captured.treeSha } : entry);
+
+  const allocation = await context.artifacts.allocateRunRoot({ providerId: provider.id, runId: provider.runId });
+  if (!allocation.ok) throw new OutcomeError(`the run root was refused: ${allocation.reason}`);
+  const runRoot = allocation.runRoot.path;
+
+  const lists = reviewerLists(charters, outcome);
+  await mkdir(path.join(runRoot, "reviewers"), { recursive: true });
+  const artifacts: { path: string; sha256: string; role: string }[] = [];
+  for (const [name, value] of [["review-context", original], ["review-outcome", document]] as const) {
+    const bytes = `${JSON.stringify(value, null, 2)}\n`;
+    await writeFile(path.join(runRoot, `${name}.json`), bytes, "utf8");
+    artifacts.push({ path: `${name}.json`, sha256: sha256Hex(bytes), role: name });
+  }
+  if (digestCanonical(reviewed.binding.candidate) !== digestCanonical(candidate)) {
+    const bytes = `${JSON.stringify({
+      spec: "review-context-projection/1",
+      basis: "unchanged-deliverable-and-review-inputs",
+      originalContextDigest: reviewed.digest,
+      reviewedCandidate: reviewed.binding.candidate,
+      preparedCandidate: candidate,
+      originalRunHistory,
+      reviewRoundAdded: false,
+    }, null, 2)}\n`;
+    await writeFile(path.join(runRoot, "review-context-projection.json"), bytes, "utf8");
+    artifacts.push({ path: "review-context-projection.json", sha256: sha256Hex(bytes), role: "review-context-projection" });
+  }
+  for (const reviewerId of lists.approved) {
+    // §9.2: the stamp re-states the whole binding, so each approval is
+    // independently interpretable in an audit.
+    const stamp = `${JSON.stringify(
+      {
+        schemaVersion: 1,
+        reviewerId,
+        result: "approved",
+        provider: { id: provider.id, runId: provider.runId, finalPassId: provider.finalPassId },
+        workspaceId: candidate.workspaceId,
+        candidate,
+      },
+      null,
+      2,
+    )}\n`;
+    const relativePath = `reviewers/${reviewerId}.json`;
+    await writeFile(path.join(runRoot, relativePath), stamp, "utf8");
+    artifacts.push({ path: relativePath, sha256: sha256Hex(stamp), role: "reviewer-approval" });
+  }
+
+  const manifest = {
+    spec: ENVELOPE_SPEC,
+    provider,
+    candidate,
+    repository: null,
+    runHistory,
+    artifacts,
+    attestation: { level: "self", signatures: [] },
+    recordedAt: new Date().toISOString(),
+    claims: [
+      {
+        obligation: binding.obligationId,
+        payloadSpec,
+        payload: {
+          verdict: outcome.verdict,
+          finalized: true,
+          editedAfterFinalPass: false,
+          reviewers: {
+            selected: lists.selected,
+            completed: lists.completed,
+            failed: lists.failed,
+            timedOut: lists.timedOut,
+          },
+          findings: outcome.findings,
+          telemetry: { ...deriveTelemetry(outcome.findings, runHistory.length), ...(outcome.cost === undefined ? {} : { cost: outcome.cost }) },
+        },
+      },
+    ],
+  };
+
+  const manifestPath = path.join(runRoot, "manifest.json");
+  await writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+  return { manifestPath, runRoot };
+}

package/src/run-archive-commands.ts

@@ -0,0 +1,164 @@
+import { constants } from "node:fs";
+import { open, realpath } from "node:fs/promises";
+import path from "node:path";
+import {
+  createArtifactsPort,
+  readRunArtifact,
+  MAX_PORTABLE_RECORD_BYTES,
+} from "@agent-delivery-harness/kernel";
+import { buildRunArchive, readArchiveArtifact } from "./run-archive.ts";
+import { parseRunExport } from "./run-export.ts";
+import {
+  resolveRunSurface,
+  oneLine,
+  runSurfaceBlocker,
+} from "./run-surface.ts";
+import type { ConfigFreeCommandContext, CommandResult } from "./boundary.ts";
+const blocked = (reason: string): CommandResult => ({
+  kind: "blocked",
+  blockers: [
+    runSurfaceBlocker({
+      code: "run_archive_unavailable",
+      summary: "The run archive is unavailable.",
+      details: oneLine(reason),
+      remediation: {
+        id: "inspect-run-archive",
+        summary:
+          "Check the selected archive or retained run attachments and retry.",
+      },
+    }),
+  ],
+});
+/** Explicit file input only, bounded on the opened descriptor; never a server path. */
+export async function readArchiveFile(file: string): Promise<string> {
+  // Inspect the descriptor before reading; a FIFO must not wait for a writer.
+  const h = await open(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+  try {
+    const stat = await h.stat();
+    if (!stat.isFile() || stat.size > MAX_PORTABLE_RECORD_BYTES)
+      throw Error("archive must be a regular file no larger than 16 MiB");
+    const buffer = Buffer.alloc(
+      Math.min(stat.size + 1, MAX_PORTABLE_RECORD_BYTES + 1),
+    );
+    let offset = 0;
+    while (offset < buffer.length) {
+      const read = await h.read(buffer, offset, buffer.length - offset, null);
+      if (!read.bytesRead) break;
+      offset += read.bytesRead;
+    }
+    if (offset !== stat.size || offset > MAX_PORTABLE_RECORD_BYTES)
+      throw Error("archive changed size while reading");
+    return buffer.subarray(0, offset).toString("utf8");
+  } finally {
+    await h.close();
+  }
+}
+async function resolvedDestination(file: string): Promise<string> {
+  let parent = path.dirname(file);
+  const suffix = [path.basename(file)];
+  for (;;) {
+    try {
+      return path.join(await realpath(parent), ...suffix);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+      suffix.unshift(path.basename(parent));
+      const next = path.dirname(parent);
+      if (next === parent) throw error;
+      parent = next;
+    }
+  }
+}
+const within = (parent: string, child: string) => {
+  const relative = path.relative(parent, child);
+  return (
+    relative === "" ||
+    (!relative.startsWith("..") && !path.isAbsolute(relative))
+  );
+};
+export async function runArchiveCommand(
+  context: ConfigFreeCommandContext,
+  command: "export" | "archive",
+  args: readonly string[],
+): Promise<CommandResult> {
+  if (command === "export" && (args.length !== 3 || args[1] !== "--output"))
+    return {
+      kind: "usage",
+      message: "Usage: runs export <run-id> --output <file>",
+    };
+  if (
+    command === "archive" &&
+    !(args.length === 1 || (args.length === 3 && args[1] === "--artifact"))
+  )
+    return {
+      kind: "usage",
+      message: "Usage: runs archive <file> [--artifact <id>]",
+    };
+  try {
+    if (command === "archive") {
+      const text = await readArchiveFile(
+        path.resolve(context.rootDir, args[0]!),
+      );
+      const parsed = parseRunExport(text);
+      if (!parsed.ok) return blocked("archive invalid or unsupported");
+      if (args[1] === "--artifact") {
+        const artifact = readArchiveArtifact(text, args[2]!);
+        if (!artifact.ok) return blocked(artifact.reason);
+        context.write(
+          JSON.stringify({
+            spec: "run-artifact/1",
+            historical: true,
+            authority: "observation",
+            runId: parsed.value.runId,
+            ...artifact,
+          }),
+        );
+      } else
+        context.write(
+          JSON.stringify({
+            historical: true,
+            authority: "observation",
+            archive: parsed.value,
+          }),
+        );
+      return { kind: "ok" };
+    }
+    const resolved = await resolveRunSurface(context.rootDir);
+    if (!resolved.ok) return blocked(resolved.reason);
+    const store = resolved.surface.store;
+    const runId = args[0]!;
+    const journal = await store.read(runId);
+    if (!journal.ok) return blocked("run unavailable");
+    const archive = await buildRunArchive({
+      runId,
+      events: journal.events,
+      refusedAppends: await store.readNotes(runId),
+      readArtifact: (id) => readRunArtifact(store, runId, id),
+    });
+    if (!archive.ok) return blocked(archive.reason);
+    const destination = await resolvedDestination(
+      path.resolve(context.rootDir, args[2]!),
+    );
+    if (
+      within(await realpath(resolved.surface.commonDir), destination) ||
+      within(await realpath(resolved.surface.runsDir), destination)
+    )
+      return blocked(
+        "archive output cannot replace repository metadata or the live run store",
+      );
+    await createArtifactsPort().writeTextFile(destination, archive.text, {
+      mode: 0o600,
+    });
+    context.write(
+      JSON.stringify({
+        spec: "run-archive-export/1",
+        runId,
+        path: path.resolve(context.rootDir, args[2]!),
+        sizeBytes: Buffer.byteLength(archive.text),
+        authority: "observation",
+      }),
+    );
+    return { kind: "ok" };
+  } catch {
+    return blocked("archive file unreadable, oversized, unsafe, or unwritable");
+  }
+}

package/src/run-archive.ts

@@ -0,0 +1,127 @@
+import {
+  applySecretDiscipline,
+  canonicalize,
+  MAX_PORTABLE_RECORD_BYTES,
+  MAX_PORTABLE_ARTIFACTS,
+  MAX_PORTABLE_EVIDENCE_BYTES,
+  type RunArtifactResult,
+  type RunEvent,
+} from "@agent-delivery-harness/kernel";
+import { buildRunExport, parseRunExport } from "./run-export.ts";
+import {
+  referencedAttachments,
+  validateRunAttachments,
+  type ArchivedAttachment,
+} from "./run-attachments.ts";
+export type RunArchiveBuildResult =
+  | { readonly ok: true; readonly text: string }
+  | { readonly ok: false; readonly reason: string };
+/** Capture a snapshot; does not write or modify the source journal. */
+export async function buildRunArchive(input: {
+  readonly runId: string;
+  readonly events: readonly RunEvent[];
+  readonly refusedAppends?: readonly unknown[];
+  readonly readArtifact: (artifactId: string) => Promise<RunArtifactResult>;
+}): Promise<RunArchiveBuildResult> {
+  const base = buildRunExport(input);
+  if (
+    Buffer.byteLength(JSON.stringify(base), "utf8") > MAX_PORTABLE_RECORD_BYTES
+  )
+    return { ok: false, reason: "archive exceeds 16 MiB serialized limit" };
+  if (!parseRunExport(JSON.stringify(base)).ok)
+    return { ok: false, reason: "invalid run export" };
+  if (!applySecretDiscipline(base, new Set()).ok)
+    return { ok: false, reason: "archive contains a secret-like value" };
+  const refs = referencedAttachments(input.events);
+  if (refs && refs.size > MAX_PORTABLE_ARTIFACTS)
+    return { ok: false, reason: "archive exceeds 128 attachments" };
+  if (!refs)
+    return { ok: false, reason: "conflicting attachment reference bindings" };
+  const entries: ArchivedAttachment[] = [];
+  const blobs: Record<string, string> = Object.create(null) as Record<
+    string,
+    string
+  >;
+  if (base.spec === "delivery-run-export/2")
+    for (const metadata of refs.values()) {
+      const artifact = await input.readArtifact(metadata.artifactId);
+      if (!artifact.ok) {
+        if (artifact.code !== "missing" && artifact.code !== "access_refused")
+          return {
+            ok: false,
+            reason: `retained attachment ${artifact.code}; export refused`,
+          };
+        entries.push({
+          metadata,
+          availability: "unavailable",
+          code: artifact.code,
+          reason: artifact.reason.slice(0, 512),
+        });
+        continue;
+      }
+      if (canonicalize(artifact.metadata) !== canonicalize(metadata))
+        return { ok: false, reason: "attachment binding differs from journal" };
+      if (
+        blobs[metadata.digest] !== undefined &&
+        blobs[metadata.digest] !== artifact.base64
+      )
+        return { ok: false, reason: "conflicting attachment bytes" };
+      blobs[metadata.digest] = artifact.base64;
+      entries.push({ metadata, availability: "retained" });
+      if (
+        Buffer.byteLength(JSON.stringify({ entries, blobs }), "utf8") >
+        MAX_PORTABLE_EVIDENCE_BYTES
+      )
+        return {
+          ok: false,
+          reason: "archive exceeds 8 MiB serialized attachment limit",
+        };
+    }
+  const attachments = { entries, blobs };
+  if (
+    base.spec === "delivery-run-export/2" &&
+    !validateRunAttachments(attachments, input.events)
+  )
+    return {
+      ok: false,
+      reason: "attachment bytes, bindings or serialized limits are invalid",
+    };
+  const text = JSON.stringify({
+    ...base,
+    ...(base.spec === "delivery-run-export/2" ? { attachments } : {}),
+  });
+  if (Buffer.byteLength(text, "utf8") > MAX_PORTABLE_RECORD_BYTES)
+    return { ok: false, reason: "archive exceeds 16 MiB serialized limit" };
+  return { ok: true, text };
+}
+/** Historical read only: never resumes, imports, verifies a candidate, or resolves paths. */
+export function readArchiveArtifact(
+  text: string,
+  artifactId: string,
+): RunArtifactResult {
+  if (Buffer.byteLength(text, "utf8") > MAX_PORTABLE_RECORD_BYTES)
+    return {
+      ok: false,
+      code: "invalid",
+      reason: "archive exceeds 16 MiB serialized limit",
+    };
+  const parsed = parseRunExport(text);
+  if (!parsed.ok)
+    return { ok: false, code: "invalid", reason: "archive invalid" };
+  const entry = parsed.value.attachments?.entries.find(
+    (e) => e.metadata.artifactId === artifactId,
+  );
+  if (!entry)
+    return {
+      ok: false,
+      code: "invalid",
+      reason: "attachment not retained in this archive",
+    };
+  if (entry.availability === "unavailable")
+    return { ok: false, code: entry.code!, reason: entry.reason! };
+  return {
+    ok: true,
+    metadata: entry.metadata,
+    base64: parsed.value.attachments!.blobs[entry.metadata.digest]!,
+  };
+}