@agent-delivery-harness/cli 0.1.0 → 0.5.0

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
+  );
+}

package/src/run-export.ts

@@ -0,0 +1,164 @@
+import {
+  validateRunAttachments,
+  type RunAttachments,
+} from "./run-attachments.ts";
+/** Retained observability, projected and checked by the same product code. */
+import {
+  canonicalize,
+  MAX_PORTABLE_RECORD_BYTES,
+  applySecretDiscipline,
+  evaluateRunJournal,
+  RUN_STORE_ID,
+  validateRunEvent,
+  type RunEvent,
+} from "@agent-delivery-harness/kernel";
+import {
+  READOUT_LABELS,
+  projectCosts,
+  projectRunProgress,
+  readoutOf,
+  summarize,
+} from "./run-projection.ts";
+
+export function buildRunExport(input: {
+  readonly runId: string;
+  readonly events: readonly RunEvent[];
+  readonly rootDir?: string;
+  readonly refusedAppends?: readonly unknown[];
+}) {
+  const v2 = input.events[0]?.version === "run-event/2";
+  return {
+    spec: v2
+      ? ("delivery-run-export/2" as const)
+      : ("delivery-run-export/1" as const),
+    labels: READOUT_LABELS,
+    runId: input.runId,
+    events: input.events,
+    summary: summarize(input.events),
+    costs: projectCosts(input.events),
+    readout: readoutOf(
+      input.events,
+      evaluateRunJournal(input.events),
+      input.rootDir,
+    ),
+    refusedAppends: input.refusedAppends ?? [],
+    // Exported progress is a historical projection at the last observation,
+    // never a claim about whether the producer is executing now.
+    ...(v2
+      ? {
+          progress: projectRunProgress(
+            input.events,
+            input.events.at(-1)?.at ?? "",
+          ),
+        }
+      : {}),
+  };
+}
+
+export type DeliveryRunExport = ReturnType<typeof buildRunExport> & {
+  readonly attachments?: RunAttachments;
+};
+export type RunExportParseResult =
+  | { readonly ok: true; readonly value: DeliveryRunExport }
+  | { readonly ok: false; readonly code: "run_export_invalid" };
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  value !== null && typeof value === "object" && !Array.isArray(value);
+
+/** Validate observations and recompute totals; this never establishes admission. */
+export function parseRunExport(text: string): RunExportParseResult {
+  const invalid = { ok: false, code: "run_export_invalid" } as const;
+  try {
+    if (Buffer.byteLength(text, "utf8") > MAX_PORTABLE_RECORD_BYTES)
+      return invalid;
+    const value: unknown = JSON.parse(text);
+    if (
+      !isRecord(value) ||
+      !["delivery-run-export/1", "delivery-run-export/2"].includes(
+        String(value["spec"]),
+      ) ||
+      value["labels"] !== READOUT_LABELS ||
+      typeof value["runId"] !== "string" ||
+      value["runId"].length > 128 ||
+      !RUN_STORE_ID.test(value["runId"]) ||
+      !Array.isArray(value["events"]) ||
+      !Array.isArray(value["refusedAppends"]) ||
+      !isRecord(value["readout"])
+    )
+      return invalid;
+    const v2 = value["spec"] === "delivery-run-export/2";
+    const hasAttachments = Object.prototype.hasOwnProperty.call(
+      value,
+      "attachments",
+    );
+    if (hasAttachments && (!v2 || !applySecretDiscipline(value, new Set()).ok))
+      return invalid;
+    if (
+      Object.keys(value)
+        .filter((key) => key !== "attachments")
+        .sort()
+        .join(",") !==
+      (v2
+        ? "costs,events,labels,progress,readout,refusedAppends,runId,spec,summary"
+        : "costs,events,labels,readout,refusedAppends,runId,spec,summary")
+    )
+      return invalid;
+    for (const [index, event] of value["events"].entries()) {
+      if (
+        !validateRunEvent(event).ok ||
+        !isRecord(event) ||
+        event["runId"] !== value["runId"] ||
+        event["seq"] !== index + 1 ||
+        event["version"] !== (v2 ? "run-event/2" : "run-event/1")
+      )
+        return invalid;
+    }
+    if (
+      hasAttachments &&
+      !validateRunAttachments(
+        value["attachments"],
+        value["events"] as RunEvent[],
+      )
+    )
+      return invalid;
+    const expected = buildRunExport({
+      runId: value["runId"],
+      events: value["events"] as RunEvent[],
+    });
+    if (
+      expected.spec !== value["spec"] ||
+      canonicalize(value["progress"] ?? null) !==
+        canonicalize(expected.progress ?? null)
+    )
+      return invalid;
+    if (
+      canonicalize(value["summary"]) !== canonicalize(expected.summary) ||
+      canonicalize(value["costs"]) !== canonicalize(expected.costs)
+    )
+      return invalid;
+    // The optional note describes config presence in the exporting workspace;
+    // it cannot be recomputed in a different checkout and grants no authority.
+    const { note, ...readout } = value["readout"];
+    if (
+      (note !== undefined && typeof note !== "string") ||
+      canonicalize(readout) !== canonicalize(expected.readout)
+    )
+      return invalid;
+    return {
+      ok: true,
+      value: {
+        ...expected,
+        ...(hasAttachments
+          ? { attachments: value["attachments"] as RunAttachments }
+          : {}),
+        refusedAppends: value["refusedAppends"],
+        readout: {
+          ...expected.readout,
+          ...(note === undefined ? {} : { note }),
+        },
+      },
+    };
+  } catch {
+    return invalid;
+  }
+}

package/src/run-live.ts

@@ -0,0 +1,102 @@
+/** Fixed, hash-authorized enhancement. No executor content enters this script. */
+export const RUN_LIVE_SCRIPT = String.raw`(() => {
+  const root = document.querySelector('main');
+  const toggle = document.querySelector('[data-live-toggle]');
+  const status = document.querySelector('[data-live-status]');
+  if (!root || !toggle || !status) return;
+  let paused = false;
+  let timer;
+  let interactingUntil = 0;
+  const interval = Number(root.dataset.pollSeconds) * 1000;
+  const interact = () => { interactingUntil = Date.now() + 1500; };
+  for (const event of ['pointerdown', 'keydown', 'wheel', 'touchstart']) {
+    document.addEventListener(event, interact, { passive: true });
+  }
+  toggle.addEventListener('click', event => {
+    event.preventDefault();
+    paused = !paused;
+    toggle.textContent = paused ? 'Resume live updates' : 'Pause updates';
+    status.textContent = paused ? 'Updates paused' : 'Live';
+  });
+  // Preserve existing nodes wherever possible, including focused controls and
+  // native disclosure state. Stable keys keep newly inserted cards from taking
+  // the identity of an earlier card the operator is reading.
+  const key = node => node.nodeType === 1 ? node.id || node.getAttribute('data-key') : null;
+  function patch(current, next) {
+    if (current.nodeType !== next.nodeType || current.nodeName !== next.nodeName) {
+      current.replaceWith(next.cloneNode(true));
+      return;
+    }
+    if (current.nodeType !== 1) {
+      if (current.nodeValue !== next.nodeValue) current.nodeValue = next.nodeValue;
+      return;
+    }
+    if (current.hasAttribute('data-live-controls')) return;
+    for (const attr of [...current.attributes]) {
+      if (current.tagName === 'DETAILS' && attr.name === 'open') continue;
+      if (!next.hasAttribute(attr.name)) current.removeAttribute(attr.name);
+    }
+    for (const attr of next.attributes) {
+      if (current.tagName !== 'DETAILS' || attr.name !== 'open') current.setAttribute(attr.name, attr.value);
+    }
+    const children = [...current.childNodes];
+    const used = new Set();
+    let cursor = current.firstChild;
+    for (const incoming of next.childNodes) {
+      const incomingKey = key(incoming);
+      const existing = incomingKey
+        ? children.find(child => !used.has(child) && key(child) === incomingKey)
+        : children.find(child => !used.has(child) && !key(child) && child.nodeType === incoming.nodeType && child.nodeName === incoming.nodeName);
+      if (existing) {
+        used.add(existing);
+        if (existing !== cursor) current.insertBefore(existing, cursor);
+        patch(existing, incoming);
+        cursor = existing.nextSibling;
+      } else {
+        const added = incoming.cloneNode(true);
+        current.insertBefore(added, cursor);
+      }
+    }
+    for (const child of children) if (!used.has(child)) child.remove();
+  }
+  const busy = () => Date.now() < interactingUntil || !window.getSelection()?.isCollapsed;
+  async function poll() {
+    if (paused || document.hidden || busy()) {
+      timer = setTimeout(poll, interval);
+      return;
+    }
+    try {
+      const response = await fetch(location.pathname, { cache: 'no-store', signal: AbortSignal.timeout(10000) });
+      if (!response.ok) throw Error('read');
+      const page = new DOMParser().parseFromString(await response.text(), 'text/html');
+      const next = page.querySelector('main');
+      if (!next) throw Error('read');
+      if (paused || document.hidden || busy()) { timer = setTimeout(poll, interval); return; }
+      const focused = document.activeElement;
+      if (focused && focused !== document.body && !focused.closest('[data-live-controls]')) {
+        const context = focused.closest('[id], [data-key]');
+        const replacement = context && [...next.querySelectorAll('[id], [data-key]')].find(element => key(element) === key(context));
+        // A completed attempt may move into collapsed history. Keep the current
+        // reading snapshot until focus leaves it, rather than removing the
+        // focused control or presenting a stale duplicate as current work.
+        if (!replacement || context.closest('section')?.id !== replacement.closest('section')?.id) {
+          status.textContent = 'New update ready · Finish reading to apply';
+          timer = setTimeout(poll, interval);
+          return;
+        }
+      }
+      const anchor = [...root.querySelectorAll('[id], [data-key]')].find(element => element.getBoundingClientRect().top >= 0 && element.getBoundingClientRect().top < window.innerHeight && element.getBoundingClientRect().height > 0);
+      const offset = anchor?.getBoundingClientRect().top;
+      const scroll = window.scrollY;
+      patch(root, next);
+      if (focused?.isConnected && document.activeElement !== focused) focused.focus({ preventScroll: true });
+      if (anchor?.isConnected && offset !== undefined) window.scrollBy(0, anchor.getBoundingClientRect().top - offset);
+      else window.scrollTo(0, scroll);
+      status.textContent = next.dataset.live === 'true' ? 'Live' : 'Saved observations';
+      if (next.dataset.live !== 'true') { toggle.hidden = true; return; }
+    } catch { status.textContent = 'Update unavailable · Retrying'; }
+    timer = setTimeout(poll, interval);
+  }
+  timer = setTimeout(poll, interval);
+  window.addEventListener('pagehide', () => clearTimeout(timer), { once: true });
+})();`;