@agent-delivery-harness/cli 0.2.0 → 0.7.3

package/src/main.ts

@@ -8,11 +8,9 @@
  * prints every obligation one "yes" would cover, reads a single line, and turns
  * a Ctrl-C into the typed {@link CliInterruption} the boundary maps to exit 130.
  */
-import { realpathSync } from "node:fs";
 import { createInterface } from "node:readline";
-import { fileURLToPath } from "node:url";
-import { CliInterruption, EXIT_POLICY, runCli, type CliRuntime } from "./index.ts";
-import type { WaiverPrompt } from "@agent-delivery-harness/kernel";
+import { CliInterruption, EXIT_INTERRUPTED, EXIT_POLICY, runCli, type CliRuntime } from "./index.ts";
+import { invokedDirectly, type WaiverPrompt } from "@agent-delivery-harness/kernel";
 
 /**
  * Reads a yes/no answer after naming every obligation the waiver would cover.
@@ -37,33 +35,49 @@ import type { WaiverPrompt } from "@agent-delivery-harness/kernel";
  * would reject and then resolve, and a settled promise silently ignoring its
  * second settlement is exactly how this class of bug hides.
  */
-export function createWaiverPrompt(input: NodeJS.ReadableStream, output: NodeJS.WritableStream): WaiverPrompt {
-  return (_decision, obligationIds) =>
-    new Promise<boolean>((resolve, reject) => {
+export function createWaiverPrompt(input: NodeJS.ReadableStream, output: NodeJS.WritableStream, signal?: AbortSignal): WaiverPrompt {
+  return (decision, obligationIds) =>
+    new Promise<Awaited<ReturnType<WaiverPrompt>>>((resolve, reject) => {
+      if (signal?.aborted) { reject(new CliInterruption()); return; }
       const rl = createInterface({ input, output });
       let settled = false;
       const settle = (action: () => void): void => {
         if (settled) return;
         settled = true;
+        signal?.removeEventListener("abort", interrupt);
         action();
       };
 
-      rl.on("SIGINT", () => {
-        settle(() => {
-          rl.close();
-          reject(new CliInterruption("Waiver prompt interrupted."));
-        });
+      const interrupt = () => settle(() => {
+        rl.close();
+        reject(new CliInterruption("Waiver prompt interrupted."));
       });
+      rl.on("SIGINT", interrupt);
+      signal?.addEventListener("abort", interrupt, { once: true });
       // Ctrl-D, a closed pipe, or any other end of input.
       rl.on("close", () => {
         settle(() => resolve(false));
       });
 
       output.write(`Waiving covers ${obligationIds.length} obligation(s): ${obligationIds.join(", ")}.\n`);
+      output.write(`Candidate: ${decision.candidate.treeSha}. Approval covers only these findings under the current policy; live obligations require new approval each invocation.\n`);
+      for (const resolution of decision.resolutions) {
+        if (resolution.kind === "blocked" && obligationIds.includes(resolution.obligationId)) {
+          for (const blocker of resolution.blockers) output.write(`${resolution.obligationId}: [${blocker.code}] ${blocker.summary}\n`);
+        }
+      }
+      const finish = (value: Awaited<ReturnType<WaiverPrompt>>) => settle(() => {
+        rl.close();
+        resolve(value);
+      });
       rl.question("Waive all of them? [y/N] ", (answer) => {
-        settle(() => {
-          rl.close();
-          resolve(/^\s*y(es)?\s*$/i.test(answer));
+        if (!/^\s*y(es)?\s*$/i.test(answer)) return finish(false);
+        rl.question("Author: ", (author) => {
+          if (!author.trim() || author.length > 256) return finish(false);
+          rl.question("Reason: ", (reason) => {
+            if (!reason.trim() || reason.length > 4096) return finish(false);
+            finish({ author: author.trim(), reason: reason.trim() });
+          });
         });
       });
     });
@@ -72,45 +86,6 @@ export function createWaiverPrompt(input: NodeJS.ReadableStream, output: NodeJS.
 export const readlineWaiverPrompt: WaiverPrompt = (decision, obligationIds) =>
   createWaiverPrompt(process.stdin, process.stderr)(decision, obligationIds);
 
-/** The spelling the filesystem can vouch for: the realpath where it can answer, the spelling itself where it cannot. */
-function canonicalEntryPath(entryPath: string): string {
-  try {
-    return realpathSync(entryPath);
-  } catch {
-    return entryPath;
-  }
-}
-
-/**
- * Whether this module is the entry the process was started with.
- *
- * argv and `import.meta.url` may spell the same file differently: argv is the
- * caller's spelling, and Node builds the module URL from the realpath by
- * default but from the caller's spelling under `--preserve-symlinks-main`. So
- * each side is canonicalized independently and the canonical forms compared:
- * a symlinked spelling matches its realpath whenever the link can be read
- * (`/tmp` → `/private/tmp` on macOS, a wrapper script's stored path, a pnpm
- * workspace link), and equal spellings still match when neither side resolves.
- *
- * What is NOT claimed: a symlink the filesystem cannot resolve cannot be seen
- * through, and the failing-exit-code floor below sits inside this guard, so an
- * under-match exits 0 in silence — the CLI reporting success having verified
- * nothing. The floor cannot be hoisted above the guard: that would stamp a
- * failing exit code on every process that merely *imports* this module. And a
- * non-`file:` module href (a bundled or single-executable build) never
- * matches — such a build must invoke `main` explicitly.
- */
-export function invokedDirectly(argvEntry: string | undefined, moduleHref: string): boolean {
-  if (argvEntry === undefined) return false;
-  let modulePath: string;
-  try {
-    modulePath = fileURLToPath(moduleHref);
-  } catch {
-    return false;
-  }
-  return canonicalEntryPath(argvEntry) === canonicalEntryPath(modulePath);
-}
-
 /**
  * Reads the whole of stdin as UTF-8.
  *
@@ -120,20 +95,29 @@ export function invokedDirectly(argvEntry: string | undefined, moduleHref: strin
  * reads as empty, and the store refuses the empty payload with a diagnostic,
  * which is a far better answer than silence.
  */
-export function readStdinText(input: NodeJS.ReadableStream & { isTTY?: boolean }): Promise<string> {
+export function readStdinText(input: NodeJS.ReadableStream & { isTTY?: boolean }, signal?: AbortSignal): Promise<string> {
+  if (signal?.aborted) return Promise.reject(new CliInterruption());
   if (input.isTTY === true) return Promise.resolve("");
-  return new Promise((resolve) => {
+  return new Promise((resolve, reject) => {
     let text = "";
+    const cleanup = () => {
+      input.removeListener("data", data);
+      input.removeListener("error", finish);
+      input.removeListener("end", finish);
+      signal?.removeEventListener("abort", interrupt);
+    };
+    const data = (chunk: string) => { text += chunk; };
+    const finish = () => { cleanup(); resolve(text); };
+    const interrupt = () => { cleanup(); input.pause(); reject(new CliInterruption()); };
     input.setEncoding("utf8");
-    input.on("data", (chunk: string) => {
-      text += chunk;
-    });
-    input.once("error", () => resolve(text));
-    input.once("end", () => resolve(text));
+    input.on("data", data);
+    input.once("error", finish);
+    input.once("end", finish);
+    signal?.addEventListener("abort", interrupt, { once: true });
   });
 }
 
-export function defaultRuntime(): CliRuntime {
+export function defaultRuntime(signal?: AbortSignal): CliRuntime {
   return {
     cwd: process.cwd(),
     env: process.env,
@@ -141,13 +125,20 @@ export function defaultRuntime(): CliRuntime {
     stdoutIsTTY: process.stdout.isTTY === true,
     stdout: (text) => process.stdout.write(text),
     stderr: (text) => process.stderr.write(text),
-    promptForWaiver: readlineWaiverPrompt,
-    readStdin: () => readStdinText(process.stdin),
+    ...(signal ? { signal } : {}),
+    promptForWaiver: createWaiverPrompt(process.stdin, process.stderr, signal),
+    readStdin: () => readStdinText(process.stdin, signal),
   };
 }
 
 export async function main(argv: readonly string[]): Promise<number> {
-  return runCli(argv, defaultRuntime());
+  const controller = new AbortController();
+  const interrupt = () => controller.abort();
+  process.on("SIGINT", interrupt);
+  try {
+    const code = await runCli(argv, defaultRuntime(controller.signal));
+    return controller.signal.aborted ? EXIT_INTERRUPTED : code;
+  } finally { process.removeListener("SIGINT", interrupt); }
 }
 
 if (invokedDirectly(process.argv[1], import.meta.url)) {

package/src/ordinary-context.ts

@@ -0,0 +1,83 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { HARNESS_VERSION, digestCanonical, type Blocker, type RunEvent, type RunEventVersion } from "@agent-delivery-harness/kernel";
+import { commandBlocker, type CommandContext } from "./boundary.ts";
+import { oneLine, resolveRunSurface, type RunSurface } from "./run-surface.ts";
+
+export function recoveryBlocker(code: string, summary: string, details?: string): Blocker {
+  return commandBlocker({ code, sourceId: "delivery-harness.cli.resume", summary,
+    ...(details === undefined ? {} : { details }),
+    remediations: [{ id: "reconcile-delivery-context", kind: "manual_action", summary: "Inspect the saved context and actual workspace/external state with host tools; rerun preparation and gates where evidence is not current. Never replay an uncertain action automatically." }],
+  });
+}
+
+/**
+ * What a store rejection may say to an operator: the store's own code, the
+ * JSON pointer at the offending member, and the store's own message. All three
+ * are written by the store rather than taken from the refused payload, so the
+ * diagnostic names the field without ever echoing its value — a contract a
+ * caller must keep, because the payload it refused is the one place a
+ * credential could have been.
+ */
+export function rejectionDetails(rejections: readonly { readonly code: string; readonly pointer: string; readonly message: string }[]): string {
+  const first = rejections[0];
+  if (first === undefined) return "the store refused the append";
+  return `${oneLine(first.code, 64)} at ${oneLine(first.pointer, 128) || "/"}: ${oneLine(first.message, 200)}`;
+}
+
+/**
+ * The writer members an ordinary-context event carries, for the version the
+ * selected run was started at.
+ *
+ * WHY THE ID IS DERIVED FROM THE OBSERVATION. A v2 event id is a retry key:
+ * the store admits a repeat of an id only when the whole event matches, and
+ * refuses the id outright for different content. An id derived from the
+ * payload's canonical digest is therefore exactly the key the contract wants —
+ * the same save repeated is the same event and appends nothing new, while a
+ * changed observation is a different id and a new entry, so neither an
+ * interrupted retry nor a genuine second save can produce a refusal an
+ * operator has to reason about. It is also stable across processes and hosts,
+ * which a random id is not.
+ */
+export function ordinaryEventWriter(version: RunEventVersion, kind: "context.saved", payload: unknown): {
+  readonly version: RunEventVersion;
+  readonly eventId?: string;
+} {
+  if (version !== "run-event/2") return { version };
+  // `kind` is narrowed to the one kind this writer serves, so the prefix is a
+  // constant that keeps the id readable and inside the store's 128-character
+  // run-id charset. It is deliberately not a general scoping claim: dots are
+  // folded to hyphens, which is not injective over arbitrary kinds, so a
+  // second kind must not be added here without an injective encoding.
+  return { version, eventId: `${kind.replaceAll(".", "-")}-${digestCanonical(payload)}` };
+}
+
+export async function recoveryRun(rootDir: string, named?: string): Promise<
+  { ok: true; surface: RunSurface; runId: string; events: readonly RunEvent[]; version: RunEventVersion } | { ok: false; blocker: Blocker }
+> {
+  const resolved = await resolveRunSurface(rootDir);
+  if (!resolved.ok) return { ok: false, blocker: recoveryBlocker("resume_context_invalid", "The repository run store cannot be read.") };
+  const current = await resolved.surface.store.current(resolved.surface.worktreeKey);
+  const runId = named ?? (current.ok ? current.runId : undefined);
+  if (!runId) return { ok: false, blocker: recoveryBlocker("resume_context_missing", "No current delivery run was found; start a run or name its existing id with --run.") };
+  const read = await resolved.surface.store.read(runId);
+  if (!read.ok) return { ok: false, blocker: recoveryBlocker("resume_context_invalid", "The delivery journal is missing, corrupt, or inaccessible.", rejectionDetails(read.rejections)) };
+  // The writer version is selected when the run starts and never upgraded, so
+  // every writer into this journal reads it from the journal's first event.
+  return { ok: true, surface: resolved.surface, runId, events: read.events, version: read.events[0]?.version ?? "run-event/1" };
+}
+
+export async function installedRelease(rootDir: string) {
+  const document: unknown = JSON.parse(await readFile(path.join(rootDir, ".agent-skills/active.json"), "utf8"));
+  const release = (document as { release?: { releaseId?: unknown; profile?: unknown; archiveSha256?: unknown } } | null)?.release;
+  if (!release || typeof release.releaseId !== "string" || typeof release.profile !== "string" ||
+      typeof release.archiveSha256 !== "string" || !/^[0-9a-f]{64}$/.test(release.archiveSha256)) {
+    throw new Error("Installed workflow release identity is missing or malformed.");
+  }
+  return { runtimeVersion: HARNESS_VERSION, releaseId: release.releaseId, profile: release.profile, archiveSha256: release.archiveSha256 };
+}
+
+export const policyDigest = (context: CommandContext) => digestCanonical({ config: context.config, policyBinding: context.policyBinding ?? null });
+
+// One reduction is shared with the atomic journal append validator.
+export { reconciliationActions } from "@agent-delivery-harness/kernel";