@agent-delivery-harness/cli 0.2.0 → 0.7.3

package/src/run-export.ts

@@ -0,0 +1,202 @@
+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,
+  runActionReconciliationError,
+  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 ?? "",
+          ),
+        }
+      : {}),
+  };
+}
+
+/**
+ * The readout members a stored export is CHECKED against.
+ *
+ * The per-violation sentences are derived from the same events by the same
+ * pass on every read, so an export never has to carry them and is never
+ * refused for lacking them: an archive written before the readout explained
+ * itself stays valid, and one carrying invented sentences gains nothing,
+ * because the value returned below is rebuilt from the recomputation either
+ * way. Compare what the events fix; recompute what they derive.
+ */
+function comparableReadout(readout: object): Record<string, unknown> {
+  const comparable: Record<string, unknown> = { ...readout };
+  delete comparable["explanations"];
+  return comparable;
+}
+
+/**
+ * The summary members a stored export is CHECKED against.
+ *
+ * `phases` is derived from the same events by the same pass on every read, for
+ * exactly the reason the readout's sentences are: an archive written before the
+ * phase breakdown existed stays valid, and one carrying invented phases gains
+ * nothing, because the value returned below is rebuilt from the recomputation
+ * either way. Compare what the events fix; recompute what they derive.
+ */
+function comparableSummary(summary: object): Record<string, unknown> {
+  const comparable: Record<string, unknown> = { ...summary };
+  delete comparable["phases"];
+  return comparable;
+}
+
+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;
+    const prefix: RunEvent[] = [];
+    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;
+      const validated = event as unknown as RunEvent;
+      if (runActionReconciliationError(prefix, validated)) return invalid;
+      prefix.push(validated);
+    }
+    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 (
+      !isRecord(value["summary"]) ||
+      canonicalize(comparableSummary(value["summary"])) !== canonicalize(comparableSummary(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(comparableReadout(readout)) !==
+        canonicalize(comparableReadout(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 });
+})();`;