@agent-delivery-harness/cli 0.2.0 → 0.5.0

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]!,
+  };
+}

package/src/run-artifact-commands.ts

@@ -0,0 +1,163 @@
+/** Explicit acquisition capture; retained reports remain observations. */
+import {
+  captureRunArtifact,
+  readRunArtifact,
+  validateRunEventInput,
+  type RunArtifactMetadata,
+} from "@agent-delivery-harness/kernel";
+import {
+  buildRunEvent,
+  oneLine,
+  resolveRunSurface,
+  runSurfaceBlocker,
+} from "./run-surface.ts";
+import type { CommandResult, ConfigFreeCommandContext } from "./boundary.ts";
+const blocked = (reason: string): CommandResult => ({
+  kind: "blocked",
+  blockers: [
+    runSurfaceBlocker({
+      code: "run_artifact_unavailable",
+      summary: "The run attachment is unavailable.",
+      details: oneLine(reason),
+      remediation: {
+        id: "inspect-selected-report",
+        summary:
+          "Check the explicit report binding and selected source file, then retry capture.",
+      },
+    }),
+  ],
+});
+const record = (v: unknown): v is Record<string, unknown> =>
+  v !== null && typeof v === "object" && !Array.isArray(v);
+export async function runArtifactCommand(
+  context: ConfigFreeCommandContext,
+  command: "capture" | "artifact",
+  args: readonly string[],
+): Promise<CommandResult> {
+  if (
+    command === "artifact" &&
+    (args.length < 2 ||
+      args.length > 3 ||
+      (args[2] !== undefined && args[2] !== "--json"))
+  )
+    return {
+      kind: "usage",
+      message: "Usage: runs artifact <run-id> <artifact-id> [--json]",
+    };
+  if (command === "capture" && (args.length !== 3 || args[1] !== "--json"))
+    return {
+      kind: "usage",
+      message: "Usage: runs capture <run-id> --json <request>",
+    };
+  const resolved = await resolveRunSurface(context.rootDir);
+  if (!resolved.ok) return blocked(resolved.reason);
+  const { store, commonDir } = resolved.surface;
+  const runId = args[0]!;
+  if (command === "artifact") {
+    const result = await readRunArtifact(store, runId, args[1]!);
+    if (!result.ok) return blocked(result.reason);
+    context.write(
+      args[2] === "--json"
+        ? `${JSON.stringify({ spec: "run-artifact/1", labels: "self-attested observation; not admission evidence", runId, ...result })}\n`
+        : `${oneLine(Buffer.from(result.base64, "base64").toString("utf8"), 2 * 1024 * 1024)}\n`,
+    );
+    return { kind: "ok" };
+  }
+  let request: unknown;
+  try {
+    if (Buffer.byteLength(args[2]!, "utf8") > 16384)
+      return blocked("capture request exceeds 16 KiB");
+    request = JSON.parse(args[2]!);
+  } catch {
+    return { kind: "usage", message: "Capture request must be JSON." };
+  }
+  if (
+    !record(request) ||
+    Object.keys(request).sort().join(",") !==
+      "artifact,eventId,report,sourcePath,sourceRoot" ||
+    typeof request["sourceRoot"] !== "string" ||
+    typeof request["sourcePath"] !== "string" ||
+    typeof request["eventId"] !== "string" ||
+    !record(request["artifact"]) ||
+    !record(request["report"])
+  )
+    return {
+      kind: "usage",
+      message:
+        "Capture requires artifact, report, eventId, sourceRoot and sourcePath.",
+    };
+  const artifact = request["artifact"];
+  const report = request["report"];
+  const binding = {
+    activityId: artifact["activityId"],
+    attemptId: artifact["attemptId"],
+    candidateTreeSha: artifact["candidateTreeSha"],
+    ...(artifact["roundId"] === undefined
+      ? {}
+      : { roundId: artifact["roundId"] }),
+    ...(artifact["round"] === undefined ? {} : { round: artifact["round"] }),
+    ...(artifact["lensId"] === undefined ? {} : { lensId: artifact["lensId"] }),
+  };
+  const journal = await store.read(runId);
+  if (!journal.ok || journal.events[0]?.version !== "run-event/2")
+    return blocked(
+      "capture requires an existing run-event/2 run; start an explicit successor for a legacy run",
+    );
+  const make = (suffix: string, kind: string, payload: unknown) => {
+    const event = buildRunEvent({
+      runId,
+      commonDir,
+      kind,
+      role: "executor",
+      payload,
+      version: "run-event/2",
+      eventId: `${request["eventId"]}-${suffix}`,
+    });
+    return event;
+  };
+  const artifactEvent = make("artifact", "artifact.referenced", artifact);
+  const reportEvent = make("report", "report.referenced", {
+    ...report,
+    ...binding,
+    availability: "referenced",
+    artifactId: artifact["artifactId"],
+  });
+  // Report input cannot override the capture's binding or carry success fields.
+  if (
+    Object.keys(report).some(
+      (k) =>
+        !["reportId", "role", "originatingReportId", "findingId"].includes(k),
+    ) ||
+    !validateRunEventInput(artifactEvent).ok ||
+    !validateRunEventInput(reportEvent).ok
+  )
+    return blocked("invalid report or artifact event binding");
+  const result = await captureRunArtifact({
+    store,
+    runId,
+    metadata: artifact as unknown as RunArtifactMetadata,
+    sourceRoot: request["sourceRoot"],
+    sourcePath: request["sourcePath"],
+  });
+  if (!result.ok) {
+    const unavailable = make("unavailable", "report.referenced", {
+      ...report,
+      ...binding,
+      availability: "unavailable",
+      reason: result.reason,
+    });
+    await store.append(runId, unavailable, { reuseExistingTimestamp: true });
+    return blocked(result.reason);
+  }
+  for (const event of [artifactEvent, reportEvent]) {
+    const appended = await store.append(runId, event, { reuseExistingTimestamp: true });
+    if (!appended.ok)
+      return blocked(
+        `bytes retained but reference append refused: ${appended.rejections.map((r) => r.message).join("; ")}`,
+      );
+  }
+  context.write(
+    `${JSON.stringify({ spec: "run-artifact-capture/1", runId, artifactId: result.metadata.artifactId, digest: result.metadata.digest, availability: "referenced", authority: "observation" })}\n`,
+  );
+  return { kind: "ok" };
+}

package/src/run-attachments.ts

@@ -0,0 +1,112 @@
+/** Bounded observational attachment transport; no path is followed by this parser. */
+import {
+  canonicalize,
+  sha256Hex,
+  portableArtifactContents,
+  applySecretDiscipline,
+  MAX_PORTABLE_ARTIFACTS,
+  MAX_PORTABLE_EVIDENCE_BYTES,
+  type RunArtifactMetadata,
+  type RunEvent,
+} from "@agent-delivery-harness/kernel";
+export interface ArchivedAttachment {
+  readonly metadata: RunArtifactMetadata;
+  readonly availability: "retained" | "unavailable";
+  readonly reason?: string;
+  readonly code?: "missing" | "access_refused";
+}
+export interface RunAttachments {
+  readonly entries: readonly ArchivedAttachment[];
+  readonly blobs: Readonly<Record<string, string>>;
+}
+const record = (v: unknown): v is Record<string, unknown> =>
+  v !== null && typeof v === "object" && !Array.isArray(v);
+export function referencedAttachments(
+  events: readonly RunEvent[],
+): Map<string, RunArtifactMetadata> | undefined {
+  const entries = new Map<string, RunArtifactMetadata>();
+  for (const event of events) {
+    if (event.kind !== "artifact.referenced") continue;
+    const metadata = event.payload as unknown as RunArtifactMetadata;
+    const prior = entries.get(metadata.artifactId);
+    if (prior && canonicalize(prior) !== canonicalize(metadata))
+      return undefined;
+    entries.set(metadata.artifactId, metadata);
+  }
+  return entries;
+}
+export function validateRunAttachments(
+  value: unknown,
+  events: readonly RunEvent[],
+): value is RunAttachments {
+  if (
+    !record(value) ||
+    Object.keys(value).sort().join(",") !== "blobs,entries" ||
+    !Array.isArray(value["entries"]) ||
+    !record(value["blobs"]) ||
+    Buffer.byteLength(JSON.stringify(value), "utf8") >
+      MAX_PORTABLE_EVIDENCE_BYTES
+  )
+    return false;
+  const refs = referencedAttachments(events);
+  if (
+    !refs ||
+    refs.size > MAX_PORTABLE_ARTIFACTS ||
+    value["entries"].length !== refs.size
+  )
+    return false;
+  const seen = new Set<string>();
+  const needed = new Set<string>();
+  const read = portableArtifactContents(value["blobs"]);
+  if (read.blockers.length) return false;
+  for (const entry of value["entries"]) {
+    if (!record(entry) || !record(entry["metadata"])) return false;
+    const metadata = entry["metadata"] as unknown as RunArtifactMetadata;
+    if (
+      seen.has(metadata.artifactId) ||
+      !refs.has(metadata.artifactId) ||
+      canonicalize(metadata) !== canonicalize(refs.get(metadata.artifactId))
+    )
+      return false;
+    seen.add(metadata.artifactId);
+    if (entry["availability"] === "unavailable") {
+      if (
+        Object.keys(entry).sort().join(",") !==
+          "availability,code,metadata,reason" ||
+        !["missing", "access_refused"].includes(String(entry["code"])) ||
+        typeof entry["reason"] !== "string" ||
+        !entry["reason"].length ||
+        entry["reason"].length > 512
+      )
+        return false;
+    } else if (entry["availability"] === "retained") {
+      if (Object.keys(entry).sort().join(",") !== "availability,metadata")
+        return false;
+      const observed = read.observations.get(metadata.digest);
+      if (!observed || observed.base64 === undefined) return false;
+      const bytes = Buffer.from(observed.base64, "base64");
+      if (
+        bytes.length !== metadata.sizeBytes ||
+        sha256Hex(bytes) !== metadata.digest
+      )
+        return false;
+      let structured: unknown = null;
+      try {
+        structured = JSON.parse(bytes.toString("utf8"));
+      } catch {}
+      if (
+        !applySecretDiscipline(
+          { text: bytes.toString("utf8"), structured },
+          new Set(),
+        ).ok
+      )
+        return false;
+      needed.add(metadata.digest);
+    } else return false;
+  }
+  return (
+    Object.keys(value["blobs"]).length === needed.size &&
+    Object.keys(value["blobs"]).every((key) => needed.has(key)) &&
+    applySecretDiscipline(value["entries"], new Set()).ok
+  );
+}