@agent-delivery-harness/cli 0.2.0 → 0.7.3

package/src/scoped-diagnostics.ts

@@ -0,0 +1,124 @@
+import path from "node:path";
+import { digestCanonical, resolveRecordStorage, type ExecOutcome, type HarnessConfig, type ScopedCheckAttempt } from "@agent-delivery-harness/kernel";
+import { AttemptStore } from "./scoped-attempts.ts";
+import { CheckSnapshotError } from "./check-snapshot.ts";
+import { projectScopedAttempt } from "./scoped-observations.ts";
+
+const phases = ["snapshot-setup", "pre-command-verification", "command", "post-command-verification", "output-capture", "complete"] as const;
+const failureCodes = ["check_snapshot_interrupted", "check_snapshot_timeout", "check_snapshot_unavailable", "check_snapshot_escape", "check_snapshot_drift", "check_snapshot_cleanup_failed", "check_dependency_source_overlap", "check_dependency_failed", "check_command_failed", "check_output_missing", "check_attempt_superseded", "check_artifact_unavailable", "check_evidence_rejected"] as const;
+const executionCodes = ["ENOENT", "EACCES", "EPERM", "ABORT_ERR", "ERR_CHILD_PROCESS_STDIO_MAXBUFFER", "SIGKILL", "SIGTERM", "execution_failed"] as const;
+export type ScopedDiagnosticPhase = typeof phases[number];
+export type ScopedDiagnosticFailureCode = typeof failureCodes[number];
+export type ScopedDiagnosticExecutionCode = typeof executionCodes[number];
+export type ScopedDiagnosticCommand =
+  | { readonly exitCode: number | null; readonly outputTail: string; readonly truncated: boolean }
+  | { readonly unavailable: "not-started" | "not-completed" };
+export interface ScopedDependencyDiagnostic {
+  readonly durationMs: number;
+  readonly executionErrorCode?: ScopedDiagnosticExecutionCode;
+  readonly command: ScopedDiagnosticCommand;
+}
+export interface RecordedScopedAttemptDiagnostic {
+  readonly availability: "available";
+  readonly phase: ScopedDiagnosticPhase;
+  readonly failure: { readonly code: ScopedDiagnosticFailureCode; readonly executionErrorCode?: ScopedDiagnosticExecutionCode }
+    | { readonly unavailable: "not-failed" | "unclassified" };
+  readonly command: ScopedDiagnosticCommand;
+  /** Present only when this attempt actually ran dependency setup; never borrowed from a reused snapshot. */
+  readonly dependency?: ScopedDependencyDiagnostic;
+}
+export type ScopedAttemptDiagnostic = RecordedScopedAttemptDiagnostic
+  | { readonly availability: "unavailable"; readonly reason: "legacy" | "running" };
+export interface ScopedCheckDiagnostics {
+  readonly version: "scoped-check-diagnostics/1";
+  readonly providers: readonly {
+    readonly providerId: string;
+    readonly attempts: readonly (ScopedCheckAttempt & { readonly durationMs?: number; readonly diagnostic: ScopedAttemptDiagnostic })[];
+  }[];
+  readonly unavailableAttemptIds: readonly string[];
+}
+
+export function scopedDiagnosticFailure(error: unknown, executionErrorCode?: string): RecordedScopedAttemptDiagnostic["failure"] {
+  if (!(error instanceof CheckSnapshotError) || !(failureCodes as readonly string[]).includes(error.code)) return { unavailable: "unclassified" };
+  return { code: error.code as ScopedDiagnosticFailureCode,
+    ...((executionCodes as readonly string[]).includes(executionErrorCode ?? "") ? { executionErrorCode: executionErrorCode as ScopedDiagnosticExecutionCode } : {}) };
+}
+export function redactScopedOutput(text: string, secrets: readonly string[]): string {
+  return [...secrets].filter(Boolean).sort((a, b) => b.length - a.length).reduce((value, secret) => value.split(secret).join("[REDACTED]"), text);
+}
+export function scopedCommandDiagnostic(result: ExecOutcome, secrets: readonly string[]): ScopedDiagnosticCommand {
+  // execFile can clip a fully emitted credential before full-value redaction.
+  // The typed execution failure remains available; this partial capture is not safe to export.
+  if (result.errorCode === "ERR_CHILD_PROCESS_STDIO_MAXBUFFER") return { unavailable: "not-completed" };
+  const numericExit = result.errorCode === undefined || result.errorCode === String(result.code);
+  if (!numericExit && result.stdout.length + result.stderr.length === 0) return { unavailable: ["ENOENT", "EACCES", "EPERM"].includes(result.errorCode!) ? "not-started" : "not-completed" };
+  const redacted = redactScopedOutput(`${result.stdout}\n${result.stderr}`, secrets);
+  return { exitCode: numericExit ? result.code : null, outputTail: redacted.slice(-4000), truncated: redacted.length > 4000 };
+}
+
+export function scopedDependencyDiagnostic(result: ExecOutcome, durationMs: number, secrets: readonly string[]): ScopedDependencyDiagnostic {
+  return { durationMs, command: scopedCommandDiagnostic(result, secrets),
+    ...((executionCodes as readonly string[]).includes(result.errorCode ?? "") ? { executionErrorCode: result.errorCode as ScopedDiagnosticExecutionCode } : {}) };
+}
+
+function projectDiagnostic(value: unknown): RecordedScopedAttemptDiagnostic {
+  const corrupt = (): never => { throw new CheckSnapshotError("check_attempt_corrupt", "Selected scoped diagnostics are malformed."); };
+  const object = (v: unknown): Record<string, unknown> => v !== null && typeof v === "object" && !Array.isArray(v) ? v as Record<string, unknown> : corrupt();
+  const row = object(value), failure = object(row["failure"]);
+  if (row["availability"] !== "available" || !(phases as readonly unknown[]).includes(row["phase"])) return corrupt();
+  let safeFailure: RecordedScopedAttemptDiagnostic["failure"];
+  if ("unavailable" in failure) {
+    if (typeof failure["unavailable"] !== "string" || !["not-failed", "unclassified"].includes(failure["unavailable"]) || "code" in failure || "executionErrorCode" in failure) return corrupt();
+    safeFailure = { unavailable: failure["unavailable"] as "not-failed" | "unclassified" };
+  } else {
+    if (!(failureCodes as readonly unknown[]).includes(failure["code"]) || ("executionErrorCode" in failure && !(executionCodes as readonly unknown[]).includes(failure["executionErrorCode"]))) return corrupt();
+    safeFailure = { code: failure["code"] as ScopedDiagnosticFailureCode, ...("executionErrorCode" in failure ? { executionErrorCode: failure["executionErrorCode"] as ScopedDiagnosticExecutionCode } : {}) };
+  }
+  const commandDiagnostic = (value: unknown): ScopedDiagnosticCommand => {
+    const command = object(value);
+    if ("unavailable" in command) {
+      if (typeof command["unavailable"] !== "string" || !["not-started", "not-completed"].includes(command["unavailable"]) || "exitCode" in command || "outputTail" in command || "truncated" in command) return corrupt();
+      return { unavailable: command["unavailable"] as "not-started" | "not-completed" };
+    }
+    if (!(command["exitCode"] === null || typeof command["exitCode"] === "number" && Number.isSafeInteger(command["exitCode"]) && command["exitCode"] >= 0) || typeof command["outputTail"] !== "string" || command["outputTail"].length > 4000 || typeof command["truncated"] !== "boolean") return corrupt();
+    return { exitCode: command["exitCode"] as number | null, outputTail: command["outputTail"], truncated: command["truncated"] };
+  };
+  let dependency: ScopedDependencyDiagnostic | undefined;
+  if ("dependency" in row) {
+    const value = object(row["dependency"]);
+    if (typeof value["durationMs"] !== "number" || !Number.isFinite(value["durationMs"]) || value["durationMs"] < 0 ||
+        ("executionErrorCode" in value && !(executionCodes as readonly unknown[]).includes(value["executionErrorCode"]))) return corrupt();
+    dependency = { durationMs: value["durationMs"], command: commandDiagnostic(value["command"]),
+      ...("executionErrorCode" in value ? { executionErrorCode: value["executionErrorCode"] as ScopedDiagnosticExecutionCode } : {}) };
+  }
+  return { availability: "available", phase: row["phase"] as ScopedDiagnosticPhase, failure: safeFailure, command: commandDiagnostic(row["command"]),
+    ...(dependency === undefined ? {} : { dependency }) };
+}
+
+/** Read at most 100 explicit attempts. No logs from legacy payloads, no writes,
+ * and no claim of applicability/admission. Unselected provider history is ignored. */
+export async function readScopedCheckDiagnostics(input: {
+  readonly rootDir: string;
+  readonly config: Pick<HarnessConfig, "gateId" | "storageNamespace" | "providers">;
+  readonly attemptIds: readonly string[];
+}): Promise<ScopedCheckDiagnostics> {
+  const { rootDir, config, attemptIds } = input;
+  if (!Array.isArray(attemptIds) || attemptIds.length > 100 || attemptIds.some(id => typeof id !== "string" || !id.length || id.length > 128) || new Set(attemptIds).size !== attemptIds.length) throw new CheckSnapshotError("check_diagnostics_request_invalid", "Diagnostics require at most 100 unique nonempty attempt identifiers.");
+  const requested = new Set(attemptIds), seen = new Set<string>();
+  const providers: ScopedCheckDiagnostics["providers"][number][] = [];
+  const storage = await resolveRecordStorage(rootDir, { storageNamespace: config.storageNamespace, leaf: "scoped-attempts" });
+  for (const provider of config.providers.filter(p => p.check?.scope !== undefined)) {
+    const rows = requested.size ? await new AttemptStore(path.join(storage.storageDir, digestCanonical({ gate: config.gateId, provider: provider.id }))).read() : [];
+    if (rows.some(row => row.attempt.providerId !== provider.id)) throw new CheckSnapshotError("check_attempt_corrupt", "Scoped history belongs to a different provider.");
+    const attempts: ScopedCheckDiagnostics["providers"][number]["attempts"][number][] = [];
+    for (const { attempt, payload } of rows.filter(row => requested.has(row.attempt.attemptId))) {
+      if (seen.has(attempt.attemptId)) throw new CheckSnapshotError("check_attempt_corrupt", "A requested attempt identifier is ambiguous.");
+      seen.add(attempt.attemptId);
+      const diagnostic: ScopedAttemptDiagnostic = attempt.status === "running" ? { availability: "unavailable", reason: "running" }
+        : payload?.diagnostic === undefined ? { availability: "unavailable", reason: "legacy" } : projectDiagnostic(payload.diagnostic);
+      attempts.push({ ...projectScopedAttempt(attempt, payload?.durationMs), diagnostic });
+    }
+    providers.push({ providerId: provider.id, attempts });
+  }
+  return { version: "scoped-check-diagnostics/1", providers, unavailableAttemptIds: attemptIds.filter(id => !seen.has(id)) };
+}

package/src/scoped-observations.ts

@@ -0,0 +1,51 @@
+import path from "node:path";
+import { digestCanonical, resolveRecordStorage, type HarnessConfig, type ScopedCheckAttempt } from "@agent-delivery-harness/kernel";
+import { AttemptStore } from "./scoped-attempts.ts";
+import { CheckSnapshotError } from "./check-snapshot.ts";
+
+export interface ScopedCheckObservations {
+  readonly version: "scoped-check-observations/1";
+  readonly providers: readonly {
+    readonly providerId: string;
+    readonly attempts: readonly (ScopedCheckAttempt & { readonly durationMs?: number })[];
+  }[];
+}
+
+export function projectScopedAttempt(attempt: ScopedCheckAttempt, durationMs?: number): ScopedCheckAttempt & { readonly durationMs?: number } {
+  return {
+    version: attempt.version, providerId: attempt.providerId, attemptId: attempt.attemptId,
+    generation: attempt.generation, inputDigest: attempt.inputDigest, profileDigest: attempt.profileDigest,
+    status: attempt.status, origin: { runId: attempt.origin.runId, candidate: {
+      treeSha: attempt.origin.candidate.treeSha, deliverableDigest: attempt.origin.candidate.deliverableDigest,
+      identityToken: attempt.origin.candidate.identityToken, baseRef: attempt.origin.candidate.baseRef,
+      baseTipSha: attempt.origin.candidate.baseTipSha, mergeBaseSha: attempt.origin.candidate.mergeBaseSha,
+      workspaceId: attempt.origin.candidate.workspaceId,
+    } }, ...(durationMs === undefined ? {} : { durationMs }),
+  };
+}
+
+/**
+ * Read retained attempts for the supplied scoped providers, in configuration
+ * order and ascending generation order. This creates no directories or evidence.
+ * Providers removed from this supplied configuration are not inventoried.
+ * Absent history is empty; corrupt selected history throws. Durations are reported only
+ * when recorded by the executor. These observations make no statement about
+ * reuse, current applicability or admission; use the gate/verify for those.
+ */
+export async function readScopedCheckObservations(input: {
+  readonly rootDir: string;
+  readonly config: Pick<HarnessConfig, "gateId" | "storageNamespace" | "providers">;
+}): Promise<ScopedCheckObservations> {
+  const { rootDir, config } = input;
+  const storage = await resolveRecordStorage(rootDir, { storageNamespace: config.storageNamespace, leaf: "scoped-attempts" });
+  const providers: ScopedCheckObservations["providers"][number][] = [];
+  for (const provider of config.providers.filter(provider => provider.check?.scope !== undefined)) {
+    const store = new AttemptStore(path.join(storage.storageDir, digestCanonical({ gate: config.gateId, provider: provider.id })));
+    const retained = await store.read();
+    if (retained.some(row => row.attempt.providerId !== provider.id)) {
+      throw new CheckSnapshotError("check_attempt_corrupt", "Scoped check attempt history belongs to a different provider.");
+    }
+    providers.push({ providerId: provider.id, attempts: retained.map(({ attempt, payload }) => projectScopedAttempt(attempt, payload?.durationMs)) });
+  }
+  return { version: "scoped-check-observations/1", providers };
+}

package/src/snapshot-inventory-worker.ts

@@ -0,0 +1,40 @@
+/** Inline so the distributed single-file runtime owns the worker bytes too.
+ * Only Node builtins are available; no author code or credentials are loaded. */
+export const snapshotInventoryWorker = String.raw`
+import { lstat, readFile, readdir, readlink, realpath } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+const { root, outputs, excludeDependencies, forbidGit } = JSON.parse(process.env.DELIVERY_SNAPSHOT_REQUEST);
+const entries = [];
+const inside = target => {
+  const relative = path.relative(root, target);
+  return relative !== '..' && !relative.startsWith('..' + path.sep) && !path.isAbsolute(relative);
+};
+const escape = () => { throw { code: 'check_snapshot_escape' }; };
+const walk = async relative => {
+  if (relative === '.git' || (excludeDependencies && relative.split('/').includes('node_modules')) ||
+      outputs.some(o => o.endsWith('/') ? relative === o.slice(0, -1) || relative.startsWith(o) : relative === o)) return;
+  const absolute = path.join(root, relative), stat = await lstat(absolute);
+  if (stat.isSymbolicLink()) {
+    const target = await readlink(absolute);
+    if (path.isAbsolute(target) || !inside(path.resolve(path.dirname(absolute), target))) escape();
+    try { if (!inside(await realpath(absolute))) escape(); }
+    catch (error) { if (error.code !== 'ENOENT') throw error; }
+    entries.push([relative, 'link', target]);
+  } else if (stat.isDirectory()) {
+    for (const name of (await readdir(absolute)).sort()) await walk(relative ? relative + '/' + name : name);
+  } else if (stat.isFile()) {
+    entries.push([relative, stat.mode & 0o111, createHash('sha256').update(await readFile(absolute)).digest('hex')]);
+  } else escape();
+};
+try {
+  if (forbidGit && await lstat(path.join(root, '.git')).then(() => true, error => { if (error.code === 'ENOENT') return false; throw error; })) throw { code: 'check_snapshot_drift' };
+  await walk('');
+  // Tuples contain only arrays, strings and permission integers: JSON.stringify
+  // has exactly the same bytes as canonical JSON for this restricted shape.
+  process.stdout.write(JSON.stringify({ digest: createHash('sha256').update(JSON.stringify(entries)).digest('hex') }));
+} catch (error) {
+  process.stdout.write(JSON.stringify({ code: ['check_snapshot_escape', 'check_snapshot_drift'].includes(error.code) ? error.code : 'check_snapshot_unavailable' }));
+  process.exitCode = 1;
+}
+`;