@agent-delivery-harness/cli 0.2.0 → 0.5.0

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

package/src/run-projection.ts

@@ -21,6 +21,8 @@
 import {
   RUN_JOURNAL_REQUIRED_ENTRIES,
   runJournalCarries,
+  runPrimaryTicket,
+  projectRunActivities,
   type RunEvent,
   type RunJournalEvaluation,
   type RunJournalRequiredEntry,
@@ -30,9 +32,91 @@ import { harnessConfigPresentAt, oneLine, oneLineOf } from "./run-surface.ts";
 /** The three labels every readout carries, so no reader mistakes this for evidence. */
 export const READOUT_LABELS = "self-attested; observability, not evidence; unbound to a record";
 
+/** A single progress view shared by renderers; callers supply their observation clock. */
+export function projectRunProgress(events: readonly RunEvent[], now: string, freshnessWindowMs?: number) {
+  const projection = projectRunActivities(events, { now, ...(freshnessWindowMs === undefined ? {} : { freshnessWindowMs }) });
+  const latestFindings = new Map<string, (typeof projection.findings)[number]>();
+  for (const finding of projection.findings) {
+    if (finding.current) latestFindings.set(String(finding.payload["findingId"]), finding);
+  }
+  return {
+    asOf: now,
+    ...projection,
+    currentFindings: [...latestFindings.values()],
+    findingsCoverage: events.some(e => e.kind === "finding.observed") ? "reported" as const : "unreported" as const,
+  };
+}
+
+export function costLabel(value: unknown): string {
+  const cost = typeof value === "object" && value !== null ? value as Record<string, unknown> : {};
+  if (cost["coverage"] === "unreported" || cost["total"] === undefined) return "unreported";
+  const measured = `${oneLineOf(cost["total"])} ${oneLineOf(cost["unit"])}`.trim();
+  return cost["coverage"] === "partial" ? `${measured} (partial coverage)` : measured;
+}
+
+/** Aggregate only comparable review counters; the run-wide counter overlaps them. */
+export function projectCosts(events: readonly RunEvent[]) {
+  const allClosed = events.filter((event) => event.kind === "review.round.closed");
+  // v2 round costs are reported cumulative snapshots. Repeated/reopened round
+  // snapshots cannot be summed as independent consumption. Keep the latest
+  // comparable value and mark coverage partial when supersession occurred.
+  const snapshots = new Map<string, RunEvent>();
+  for (const event of allClosed) {
+    const payload = payloadOf(event);
+    const cost = payload["cost"] as Record<string, unknown>;
+    const key = event.version === "run-event/2"
+      ? JSON.stringify([payload["roundId"], cost["reportedBy"], cost["unit"] ?? "unreported"])
+      : `legacy-${event.seq}`;
+    snapshots.set(key, event);
+  }
+  const closed = [...snapshots.values()];
+  const totals = new Map<string, { unit: string; reportedBy: string; total: number | null }>();
+  let unreportedEntries = 0;
+  let partial = allClosed.length !== closed.length || events.filter((event) => event.kind === "review.round.opened").length !== closed.length;
+  for (const event of closed) {
+    const cost = payloadOf(event)["cost"] as Record<string, unknown>;
+    if (cost["coverage"] === "unreported") {
+      unreportedEntries += 1;
+      continue;
+    }
+    if (cost["coverage"] === "partial") partial = true;
+    const unit = cost["unit"] as string;
+    const reportedBy = cost["reportedBy"] as string;
+    const key = JSON.stringify([reportedBy, unit]);
+    const prior = totals.get(key);
+    const sum = prior?.total === null ? Infinity : (prior?.total ?? 0) + (cost["total"] as number);
+    // The validated event keeps the original finite measurement even if a sum
+    // exceeds the numeric range. Null is unavailable, never measured zero.
+    if (!Number.isFinite(sum)) partial = true;
+    totals.set(key, { unit, total: Number.isFinite(sum) ? sum : null, reportedBy });
+  }
+  const ended = events.find((event) => event.kind === "run.ended");
+  return {
+    review: {
+      coverage: totals.size === 0 ? "unreported" : partial || unreportedEntries > 0 ? "partial" : "complete",
+      unreportedEntries,
+      totals: [...totals.values()],
+    },
+    run: ended === undefined ? { coverage: "unreported" } : payloadOf(ended)["cost"],
+  };
+}
+
 export const payloadOf = (event: RunEvent): Record<string, unknown> =>
   typeof event.payload === "object" && event.payload !== null ? (event.payload as Record<string, unknown>) : {};
 
+/**
+ * The ticket an entry BOUND ITSELF to, as a row suffix, or nothing.
+ *
+ * Only the entry's own binding is rendered. An entry that omits `ticket` binds
+ * to the run's primary, which the runs table already names in the row above
+ * every timeline — repeating it on each unbound line would turn the one thing
+ * the member exists to say, that THIS entry belongs to THAT ticket, into
+ * boilerplate an operator learns to skip. The envelope is read rather than the
+ * payload because the validator holds the two to exact agreement and the
+ * envelope is what every other reader here reads.
+ */
+const boundTicket = (event: RunEvent): string => (event.ticket === undefined ? "" : ` for ${oneLineOf(event.ticket, 128)}`);
+
 /**
  * One row's detail for one event: enough to read the run without printing the
  * whole payload back at the operator.
@@ -43,11 +127,11 @@ export function detailOf(event: RunEvent): string {
     case "run.started":
       return oneLineOf(payload["host"]) + (payload["displacedRunId"] === undefined ? "" : ` displaced ${oneLineOf(payload["displacedRunId"])}`);
     case "run.ended":
-      return `${oneLineOf(payload["result"])} cost ${oneLineOf((payload["cost"] as { total?: unknown } | undefined)?.total)}`;
+      return `${oneLineOf(payload["result"])} cost ${costLabel(payload["cost"])}`;
     case "ticket.read":
       return `${oneLineOf(payload["ticket"])} via ${oneLineOf(payload["tracker"])}`;
     case "posture.declared":
-      return oneLineOf(payload["posture"]);
+      return oneLineOf(payload["posture"]) + boundTicket(event);
     case "lens.selected":
       return `mandated ${oneLineOf(payload["mandated"])} selected ${oneLineOf(payload["selected"])} — ${oneLineOf(payload["rationale"])}`;
     case "review.round.opened":
@@ -57,15 +141,20 @@ export function detailOf(event: RunEvent): string {
     case "command.completed":
       return `${oneLineOf(payload["command"])} ${oneLineOf(payload["outcome"])} in ${oneLineOf(payload["durationMs"])}ms`;
     case "gate.reported":
-      return `${oneLineOf(payload["command"])} ${oneLineOf(payload["outcome"])} in ${oneLineOf(payload["durationMs"])}ms`;
+      return `${oneLineOf(payload["command"])} ${oneLineOf(payload["outcome"])} in ${oneLineOf(payload["durationMs"])}ms${boundTicket(event)}`;
     case "pr.opened":
-      return `${oneLineOf(payload["url"], 400)} on ${oneLineOf(event.candidateTreeSha)}`;
+      return `${oneLineOf(payload["url"], 400)} on ${oneLineOf(event.candidateTreeSha)}${boundTicket(event)}`;
     case "blocker.recorded":
       return `${oneLineOf(payload["code"])} — ${oneLineOf(payload["summary"])}`;
     case "decision.recorded":
       return `${oneLineOf(payload["fork"])} — ${oneLineOf(payload["choice"])}${payload["cited"] === undefined ? "" : ` (cited ${oneLineOf(payload["cited"])})`}`;
     case "compounding.recorded":
       return `${oneLineOf(payload["outcome"])}${payload["reference"] === undefined ? "" : ` — ${oneLineOf(payload["reference"])}`}`;
+    case "context.saved":
+      return `stage ${oneLineOf(payload["stage"])} (observation only)`;
+    case "action.intent":
+    case "action.observed":
+      return `${oneLineOf(payload["actionId"])} ${oneLineOf(payload["outcome"] ?? "unknown")} reference ${oneLineOf(payload["reference"])}`;
     default:
       return "";
   }
@@ -109,6 +198,20 @@ export function roundEntries(events: readonly RunEvent[]): readonly RoundEntry[]
   });
 }
 
+/**
+ * The lenses a round carried, or the fact that it never opened.
+ *
+ * A round with no `review.round.opened` has no lens set to name, and the two
+ * surfaces have to say the SAME thing about that. The terminal already said
+ * `never opened`; the page rendered nothing, which an operator reads as a
+ * round that opened carrying no lens. That is a second answer to one question
+ * about one file, which is exactly what this module exists to prevent — so the
+ * words live here, once, and each surface only escapes and places them.
+ */
+export function roundLenses(entry: RoundEntry): string {
+  return entry.opened === undefined ? "never opened" : oneLineOf(payloadOf(entry.opened)["lenses"]);
+}
+
 /** One text row per round, each carrying the candidate it was bound to. */
 export function roundRows(events: readonly RunEvent[]): readonly string[] {
   return roundEntries(events).map((entry) => {
@@ -116,8 +219,8 @@ export function roundRows(events: readonly RunEvent[]): readonly string[] {
     return [
       `  round ${entry.round}`,
       `candidate ${entry.candidateTreeSha || "(none)"}`,
-      entry.opened === undefined ? "never opened" : `lenses ${oneLineOf(payloadOf(entry.opened)["lenses"])}`,
-      closed === undefined ? "open" : `${oneLineOf(closed["outcome"])} findings ${oneLineOf(closed["findings"])} cost ${oneLineOf((closed["cost"] as { total?: unknown } | undefined)?.total)}`,
+      entry.opened === undefined ? roundLenses(entry) : `lenses ${roundLenses(entry)}`,
+      closed === undefined ? "open" : `${oneLineOf(closed["outcome"])} findings ${oneLineOf(closed["findings"])} cost ${costLabel(closed["cost"])}`,
     ].join("  ");
   });
 }
@@ -146,10 +249,10 @@ export interface Readout {
  * and a reader would eventually be told an entry is both present and missing —
  * which is exactly what a rewritten copy of the pairing rule did.
  */
-export function readoutOf(events: readonly RunEvent[], evaluation: RunJournalEvaluation, rootDir: string): Readout {
+export function readoutOf(events: readonly RunEvent[], evaluation: RunJournalEvaluation, rootDir?: string): Readout {
   const present = RUN_JOURNAL_REQUIRED_ENTRIES.filter((entry) => runJournalCarries(events, entry));
   const note =
-    evaluation.status === "complete-executor-only" && harnessConfigPresentAt(rootDir)
+    evaluation.status === "complete-executor-only" && rootDir !== undefined && harnessConfigPresentAt(rootDir)
       ? `no CLI gate completion in this journal; harness.config.ts present at ${oneLine(rootDir, 400)}`
       : undefined;
   return {
@@ -187,7 +290,12 @@ export interface WrittenOutcome {
 }
 
 export interface RunSummary {
-  /** From the envelope of the first event that carries one; `emit` mirrors it from the payload. */
+  /**
+   * The run's PRIMARY ticket, by the family's own rule: the first the journal
+   * names. A run that read two — a dogfood item and the ordinary item it
+   * delivered — is named here by the first, and every entry that bound no
+   * ticket of its own belongs to it.
+   */
   readonly ticket: string;
   /** A run with no `run.ended` is open, whatever else it holds. */
   readonly open: boolean;
@@ -218,8 +326,18 @@ export interface RunSummary {
   readonly result?: string;
 }
 
+/**
+ * The CLI-written completion of one command that governs, which is the LAST of
+ * them — the same binding `evaluateRunJournal`'s own `cliCompletion` settled
+ * under V26-1709, for the same reason: a command is re-run to supersede its
+ * earlier outcome. The table and the completeness block sit on one row of one
+ * page, so a projection reading the first would report the outcome of a gate
+ * the delivery abandoned beside a verdict taken on the re-run —
+ * `run-01c68dea9d1d5fd0` in this repository's own store is a journal that gates
+ * twice and would read that way.
+ */
 const cliCompletionFor = (events: readonly RunEvent[], command: string): RunEvent | undefined =>
-  events.find(
+  events.findLast(
     (event) => event.kind === "command.completed" && event.actor.role === "cli" && payloadOf(event)["command"] === command,
   );
 
@@ -256,7 +374,7 @@ export function summarize(events: readonly RunEvent[]): RunSummary {
         : undefined;
 
   return {
-    ticket: oneLineOf(events.find((event) => event.ticket !== undefined)?.ticket, 128),
+    ticket: oneLineOf(runPrimaryTicket(events), 128),
     open: ended === undefined,
     startedAt,
     lastAt,