@agent-delivery-harness/cli 0.1.0 → 0.2.0

package/package.json

@@ -1,14 +1,19 @@
 {
   "name": "@agent-delivery-harness/cli",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "description": "Delivery harness CLI: prepare, review-context, submit-evidence, gate, record, verify, check",
   "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kwam1na/agent-delivery-harness.git",
+    "directory": "packages/cli"
+  },
   "engines": {
-    "node": ">=22"
+    "node": ">=22.6.0"
   },
   "dependencies": {
-    "@agent-delivery-harness/kernel": "0.1.0"
+    "@agent-delivery-harness/kernel": "0.2.0"
   },
   "exports": {
     ".": "./src/index.ts"

package/src/boundary.ts

@@ -1,9 +1,9 @@
 /**
  * The one boundary every CLI command runs behind.
  *
- * WHY ONE BOUNDARY. Seven commands, one place that loads config, wires the repo,
- * classifies exit codes, and renders failures. A command never touches
- * `process`, never prints a stack, never chooses an exit code of its own: it
+ * WHY ONE BOUNDARY. Nine config-loading commands, one place that loads config,
+ * wires the repo, classifies exit codes, and renders failures. A command never
+ * touches `process`, never prints a stack, never chooses an exit code of its own: it
  * returns a typed result and the boundary maps it. That is what keeps the three
  * exit semantics — policy block, usage error, interruption — identical across
  * commands, and what keeps every operator-facing byte flowing through the one
@@ -26,6 +26,7 @@
  * disagreement unconstructible in the first place.
  */
 import path from "node:path";
+import { randomUUID } from "node:crypto";
 import { pathToFileURL } from "node:url";
 import {
   BlockedError,
@@ -37,12 +38,14 @@ import {
   evaluateCandidateActivation,
   renderBlockers,
   resolveRecordStorage,
+  submitManifest,
   validateHarnessConfig,
   withDeliverableIdentity,
   type ArtifactsPort,
   type Blocker,
   type CaptureCandidate,
   type CapturedCandidate,
+  type CompiledAdopterPolicyBinding,
   type EnvSnapshot,
   type ExecutionContext,
   type HarnessConfig,
@@ -51,6 +54,13 @@ import {
   type ReviewActivationProjection,
   type WaiverPrompt,
 } from "@agent-delivery-harness/kernel";
+import {
+  invokeProviderRail,
+  openProviderRailProcess,
+  type ProviderRailInvocationResult,
+  type ProviderRailSession,
+} from "./provider-rails.ts";
+import { buildRunEvent, resolveRunSurface } from "./run-surface.ts";
 
 // ── Exit codes ───────────────────────────────────────────────────────────────
 
@@ -96,6 +106,8 @@ export interface RepoWiring {
 export interface CommandContext {
   readonly rootDir: string;
   readonly config: HarnessConfig;
+  /** Optional adopter binding; managed commands also load the persisted binding after registration. */
+  readonly policyBinding?: CompiledAdopterPolicyBinding;
   readonly env: EnvSnapshot;
   readonly stdinIsTTY: boolean;
   readonly stdoutIsTTY: boolean;
@@ -111,6 +123,12 @@ export interface CommandContext {
   /** Present only when the run can ask a human; the boundary gates it on a TTY. */
   readonly promptForWaiver?: WaiverPrompt;
   readonly liveResults?: readonly LiveProviderResult[];
+  /** Runs one configured provider through the neutral stdio rail, if it has a command. */
+  readonly invokeProvider?: (input: {
+    readonly providerId: string;
+    readonly payload: Readonly<Record<string, unknown>>;
+    readonly requiresEvidence: boolean;
+  }) => Promise<ProviderRailInvocationResult | undefined>;
   /** Emits one line of operator-facing output to stdout. */
   readonly write: (text: string) => void;
   /** Classifies the execution context from this invocation's env + TTY. */
@@ -125,6 +143,53 @@ export interface CommandDescriptor {
   run(context: CommandContext): Promise<CommandResult>;
 }
 
+// ── The config-free command class ────────────────────────────────────────────
+
+/**
+ * What a config-free command may reach. Deliberately much less than
+ * {@link CommandContext}: no config, no wiring, no provider rail, no artifacts
+ * port. A run event belongs to the repository, not to a configured gate, and
+ * `emit` has to work in a repository that has no `harness.config.ts` at all.
+ *
+ * The ONE thing a config-free command may do with `harness.config.ts` is ask
+ * whether the path exists (`lstat`, no follow) at a worktree root. It never
+ * imports it, loads it, or parses it — which is why the config loader is not
+ * reachable from here even as a seam.
+ */
+export interface ConfigFreeCommandContext {
+  readonly rootDir: string;
+  readonly env: EnvSnapshot;
+  /** Positional and flag arguments after the command name. */
+  readonly args: readonly string[];
+  /** The payload channel: everything on stdin, when a command reads one. */
+  readStdin(): Promise<string>;
+  /** Emits one line of operator-facing output to stdout. */
+  readonly write: (text: string) => void;
+  /**
+   * The invocation's cancellation, for the one config-free command that does
+   * not return on its own. `runs serve` holds a socket open until the operator
+   * ends it; without a signal it serves forever, which is exactly right for a
+   * terminal and useless for a caller that has to get its process back.
+   */
+  readonly signal?: AbortSignal;
+}
+
+export interface ConfigFreeCommandDescriptor {
+  readonly name: string;
+  readonly sourceId: string;
+  readonly summary: string;
+  /** The discriminator the boundary dispatches on, before any config load. */
+  readonly configFree: true;
+  run(context: ConfigFreeCommandContext): Promise<CommandResult>;
+}
+
+/** Either command class; the registry holds both. */
+export type AnyCommandDescriptor = CommandDescriptor | ConfigFreeCommandDescriptor;
+
+export function isConfigFreeCommand(descriptor: AnyCommandDescriptor): descriptor is ConfigFreeCommandDescriptor {
+  return (descriptor as ConfigFreeCommandDescriptor).configFree === true;
+}
+
 // ── Runtime the boundary is driven with ──────────────────────────────────────
 
 export interface CliRuntime {
@@ -136,11 +201,23 @@ export interface CliRuntime {
   readonly stderr: (text: string) => void;
   /** Loads the consumer config. Defaults to importing `harness.config.ts`. */
   readonly loadConfig?: (rootDir: string) => Promise<HarnessConfig>;
+  /** An embedding adopter may pass its already-compiled policy directly. */
+  readonly policyBinding?: CompiledAdopterPolicyBinding;
   /** The interactive waiver prompt. Only ever offered under a TTY. */
   readonly promptForWaiver?: WaiverPrompt;
   /** The filesystem port. Defaults to one rooted in the system temp directory. */
   readonly artifacts?: ArtifactsPort;
   readonly liveResults?: readonly LiveProviderResult[];
+  readonly signal?: AbortSignal;
+  /** Reads the whole of stdin, for the one command whose payload arrives there. */
+  readonly readStdin?: () => Promise<string>;
+  /** Test/embedding seam. The ordinary runtime opens the provider's configured command. */
+  readonly openProviderRail?: (input: {
+    readonly providerId: string;
+    readonly command: readonly [string, ...string[]];
+    readonly cwd: string;
+    readonly env: EnvSnapshot;
+  }) => Promise<ProviderRailSession>;
 }
 
 // ── Blocker helpers ──────────────────────────────────────────────────────────
@@ -225,7 +302,7 @@ export async function wireRepo(rootDir: string, config: HarnessConfig): Promise<
 
 // ── The boundary ─────────────────────────────────────────────────────────────
 
-const USAGE = (commands: readonly CommandDescriptor[]): string =>
+const USAGE = (commands: readonly AnyCommandDescriptor[]): string =>
   [
     "Usage: delivery-harness <command> [options]",
     "",
@@ -233,6 +310,76 @@ const USAGE = (commands: readonly CommandDescriptor[]): string =>
     ...commands.map((command) => `  ${command.name.padEnd(16)}${command.summary}`),
   ].join("\n");
 
+/**
+ * THE WRAPPED COMMANDS, NAMED ONE BY ONE.
+ *
+ * Exactly the candidate-facing loop plus its preflight. `managed` and
+ * `maintain` are deliberately absent: they are host-facing and
+ * installation-scoped, and a completion event for them would describe
+ * something that is not a step of the delivery run the journal is about.
+ * `emit` and `runs` are absent because a viewer that recorded its own
+ * invocations would fill the journal it renders.
+ *
+ * An allowlist rather than a denylist: a command added to the registry is
+ * unwrapped until someone decides it belongs here, which is the direction that
+ * fails safe for a store nothing authoritative may read.
+ */
+export const COMPLETION_WRAPPED_COMMANDS: readonly string[] = [
+  "check",
+  "prepare",
+  "review-context",
+  "submit-evidence",
+  "gate",
+  "record",
+  "verify",
+];
+
+/** The four exit codes, as the closed outcome enum `command.completed` carries. */
+function outcomeOfExit(code: number): "ok" | "policy" | "usage" | "interrupted" {
+  if (code === EXIT_OK) return "ok";
+  if (code === EXIT_USAGE) return "usage";
+  if (code === EXIT_INTERRUPTED) return "interrupted";
+  return "policy";
+}
+
+/**
+ * Appends this invocation's `command.completed`, when — and only when — a run
+ * is current for the invoking worktree.
+ *
+ * BEST-EFFORT, TOTAL, AND SILENT. Every failure is swallowed: an unresolvable
+ * repository, a refused pointer, a store that will not accept the append. The
+ * caller has already decided the exit code, and a run journal that could
+ * change a gate's verdict would be evidence. It is not evidence, so it is not
+ * allowed to matter. A refused append still lands one bounded line in the
+ * run's note, which the store writes.
+ */
+async function recordCommandCompletion(input: {
+  readonly cwd: string;
+  readonly command: string;
+  readonly exitCode: number;
+  readonly durationMs: number;
+}): Promise<void> {
+  try {
+    const resolved = await resolveRunSurface(input.cwd);
+    if (!resolved.ok) return;
+    const { store, commonDir, worktreeKey } = resolved.surface;
+    const current = await store.current(worktreeKey);
+    if (!current.ok || current.runId === undefined) return;
+    await store.append(
+      current.runId,
+      buildRunEvent({
+        runId: current.runId,
+        commonDir,
+        kind: "command.completed",
+        role: "cli",
+        payload: { command: input.command, outcome: outcomeOfExit(input.exitCode), durationMs: input.durationMs },
+      }),
+    );
+  } catch {
+    // Deliberately silent. See the paragraph above.
+  }
+}
+
 /**
  * Runs one CLI invocation to an exit code. Total: it maps every command result
  * and every throw to one of the four codes, and renders every failure through
@@ -240,7 +387,7 @@ const USAGE = (commands: readonly CommandDescriptor[]): string =>
  */
 export async function runCliBoundary(
   argv: readonly string[],
-  commands: readonly CommandDescriptor[],
+  commands: readonly AnyCommandDescriptor[],
   runtime: CliRuntime,
 ): Promise<number> {
   const [commandName, ...args] = argv;
@@ -256,6 +403,76 @@ export async function runCliBoundary(
     return EXIT_USAGE;
   }
 
+  // CONFIG-FREE COMMANDS ARE DISPATCHED FIRST, before any config load. That
+  // ordering is the whole point of the class: `emit` runs in a repository with
+  // no `harness.config.ts`, and no other command's `config_unloadable` timing
+  // moves because of it.
+  if (isConfigFreeCommand(descriptor)) {
+    return runConfigFreeCommand(descriptor, args, runtime);
+  }
+
+  const startedAt = Date.now();
+  const code = await runConfiguredCommand(descriptor, args, runtime);
+  if (COMPLETION_WRAPPED_COMMANDS.includes(descriptor.name)) {
+    await recordCommandCompletion({
+      cwd: runtime.cwd,
+      command: descriptor.name,
+      exitCode: code,
+      durationMs: Date.now() - startedAt,
+    });
+  }
+  return code;
+}
+
+/** The config-free path: a typed result mapped to an exit code, and nothing else. */
+async function runConfigFreeCommand(
+  descriptor: ConfigFreeCommandDescriptor,
+  args: readonly string[],
+  runtime: CliRuntime,
+): Promise<number> {
+  try {
+    const result = await descriptor.run({
+      rootDir: runtime.cwd,
+      env: runtime.env,
+      args,
+      readStdin: runtime.readStdin ?? (async () => ""),
+      write: (text) => runtime.stdout(`${text}\n`),
+      ...(runtime.signal === undefined ? {} : { signal: runtime.signal }),
+    });
+    if (result.kind === "ok") {
+      if (result.summary !== undefined && result.summary !== "") runtime.stdout(`${result.summary}\n`);
+      return EXIT_OK;
+    }
+    if (result.kind === "usage") {
+      runtime.stderr(`${result.message}\n`);
+      return EXIT_USAGE;
+    }
+    runtime.stderr(`${renderBlockers(result.blockers)}\n`);
+    return EXIT_POLICY;
+  } catch (error) {
+    if (error instanceof CliInterruption) {
+      runtime.stderr(`${error.message}\n`);
+      return EXIT_INTERRUPTED;
+    }
+    if (error instanceof BlockedError) {
+      runtime.stderr(`${renderBlockers(error.blockers)}\n`);
+      return EXIT_POLICY;
+    }
+    const blocker = createInternalErrorBlocker({
+      source: { kind: "command", id: descriptor.sourceId },
+      error,
+      reproduce: ["delivery-harness", descriptor.name],
+    });
+    runtime.stderr(`${renderBlockers([blocker])}\n`);
+    return EXIT_POLICY;
+  }
+}
+
+async function runConfiguredCommand(
+  descriptor: CommandDescriptor,
+  args: readonly string[],
+  runtime: CliRuntime,
+): Promise<number> {
   const loadConfig = runtime.loadConfig ?? importHarnessConfig;
   const artifacts = runtime.artifacts ?? createArtifactsPort();
 
@@ -271,6 +488,7 @@ export async function runCliBoundary(
     const context: CommandContext = {
       rootDir: runtime.cwd,
       config,
+      ...(runtime.policyBinding === undefined ? {} : { policyBinding: runtime.policyBinding }),
       env: runtime.env,
       stdinIsTTY: runtime.stdinIsTTY,
       stdoutIsTTY: runtime.stdoutIsTTY,
@@ -283,6 +501,65 @@ export async function runCliBoundary(
         ? { promptForWaiver: runtime.promptForWaiver }
         : {}),
       ...(runtime.liveResults === undefined ? {} : { liveResults: runtime.liveResults }),
+      invokeProvider: async ({ providerId, payload, requiresEvidence }) => {
+        const provider = config.providers.find((registration) => registration.id === providerId);
+        if (provider?.command === undefined) return undefined;
+        const command = provider.command;
+        const requestId = randomUUID();
+        const allocation = await artifacts.allocateRunRoot({ providerId, runId: requestId });
+        if (!allocation.ok) {
+          throw new BlockedError([
+            commandBlocker({
+              code: "provider_rail_run_root_refused",
+              sourceId: "delivery-harness.cli.provider-rails",
+              summary: "The provider run root could not be allocated.",
+              details: `${providerId}/${requestId}: ${allocation.reason}`,
+              remediations: [
+                {
+                  id: "check-provider-identity",
+                  kind: "code_change",
+                  summary: "Correct the provider id or restore the harness run-root location, then retry.",
+                },
+              ],
+            }),
+          ]);
+        }
+        const wiring = await wire();
+        const interruptController = runtime.signal === undefined ? new AbortController() : undefined;
+        const onInterrupt = (): void => interruptController?.abort();
+        if (interruptController !== undefined) process.once("SIGINT", onInterrupt);
+        try {
+          return await invokeProviderRail(
+            {
+              providerId,
+              requestId,
+              idempotencyKey: randomUUID(),
+              payload: { ...payload, runId: requestId, runRoot: allocation.runRoot.path },
+              requiresEvidence,
+            },
+            {
+              open: () =>
+                runtime.openProviderRail === undefined
+                  ? openProviderRailProcess({ command, cwd: runtime.cwd, env: { ...runtime.env } })
+                  : runtime.openProviderRail({ providerId, command, cwd: runtime.cwd, env: runtime.env }),
+              publishManifest: (manifestPath) =>
+                submitManifest(
+                  { rootDir: runtime.cwd, config, manifestPath },
+                  {
+                    captureCandidate: wiring.captureCandidate,
+                    artifacts,
+                    expectedProviderAttempt: { providerId, runId: requestId, runRootPath: allocation.runRoot.path },
+                    ...wiring.storageOptions,
+                  },
+                ),
+              signal: runtime.signal ?? interruptController?.signal,
+              cancellationId: randomUUID(),
+            },
+          );
+        } finally {
+          if (interruptController !== undefined) process.off("SIGINT", onInterrupt);
+        }
+      },
       write: (text) => runtime.stdout(`${text}\n`),
       classifyContext: () =>
         classifyExecutionContext({