@agent-delivery-harness/cli 0.8.3 → 0.8.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-delivery-harness/cli",
-  "version": "0.8.3",
+  "version": "0.8.6",
   "type": "module",
   "description": "Delivery harness CLI: admit, prepare, review-context, submit-evidence, gate, record, verify, check",
   "license": "FSL-1.1-ALv2",
@@ -13,7 +13,7 @@
     "node": ">=22.6.0"
   },
   "dependencies": {
-    "@agent-delivery-harness/kernel": "0.8.3"
+    "@agent-delivery-harness/kernel": "0.8.6"
   },
   "exports": {
     ".": "./src/index.ts"

package/src/boundary.ts

@@ -135,6 +135,8 @@ export interface CommandContext {
     readonly providerId: string;
     readonly payload: Readonly<Record<string, unknown>>;
     readonly requiresEvidence: boolean;
+    /** Cancels this one attempt through the rail, as an interruption of the invocation would. */
+    readonly signal?: AbortSignal;
   }) => Promise<ProviderRailInvocationResult | undefined>;
   /** Emits one line of operator-facing output to stdout. */
   readonly write: (text: string) => void;
@@ -530,7 +532,7 @@ async function runConfiguredCommand(
         ? { promptForWaiver: observation?.prompt(runtime.promptForWaiver) ?? runtime.promptForWaiver }
         : {}),
       ...(runtime.liveResults === undefined ? {} : { liveResults: runtime.liveResults }),
-      invokeProvider: async ({ providerId, payload, requiresEvidence }) => {
+      invokeProvider: async ({ providerId, payload, requiresEvidence, signal: attemptSignal }) => {
         const provider = config.providers.find((registration) => registration.id === providerId);
         if (provider?.command === undefined) return undefined;
         const command = provider.command;
@@ -583,7 +585,7 @@ async function runConfiguredCommand(
                     ...wiring.storageOptions,
                   },
                 ),
-              signal: runtime.signal ?? interruptController?.signal,
+              signal: [runtime.signal ?? interruptController?.signal, attemptSignal].filter((s): s is AbortSignal => s !== undefined).reduce<AbortSignal | undefined>((one, other) => one ? AbortSignal.any([one, other]) : other, undefined),
               cancellationId: randomUUID(),
             },
           );

package/src/commands/gate.ts

@@ -14,7 +14,7 @@ import { refuseOverBudget } from "../scoped-budget.ts";
  * only ever offers a waiver to a `human` context, all-or-nothing over waivable
  * findings; the CLI adds no waiver logic of its own.
  */
-import { computeDeliverableIdentity, runAdmission, type AdmissionResult, type Blocker, type LiveProviderResult } from "@agent-delivery-harness/kernel";
+import { computeDeliverableIdentity, digestCanonical, runAdmission, type AdmissionResult, type Blocker, type LiveProviderResult } from "@agent-delivery-harness/kernel";
 import { CliInterruption, type CommandContext, type CommandDescriptor, type CommandResult } from "../boundary.ts";
 import { focusedOutcome } from "../delivery-posture.ts";
 import { oneLine } from "../run-surface.ts";
@@ -58,6 +58,8 @@ async function providerAdmission(
   }
 
   const liveResults: LiveProviderResult[] = options.includeInjectedLiveResults ? [...(context.liveResults ?? [])] : [];
+  const invokeProvider = context.invokeProvider;
+  const besideOutcomes = new Map<string, ({ result: Awaited<ReturnType<NonNullable<CommandContext["invokeProvider"]>>> } | { error: unknown }) & { obligationIds: readonly string[] }>();
   const attempted = new Set<string>();
   const attemptBlockers: Blocker[] = [];
   let admission = await admit(input, admissionOptions);
@@ -90,9 +92,45 @@ async function providerAdmission(
     const scoped = session !== undefined && session.concurrency > 1 ? [...requested].filter(([id]) => context.config.providers.find(p => p.id === id)!.check?.scope) : [];
     if (session !== undefined && scoped.length > 0) {
       for (const [id] of scoped) attempted.add(id);
-      const failures = await session.executeAll(scoped.map(([id, request]) => ({ provider: context.config.providers.find(p => p.id === id)!, obligationIds: request.obligationIds })));
+      // Live rail providers that declare they read no scoped result start alongside the scoped checks. Each outcome
+      // waits for the serial loop below to reach that provider, which applies it exactly as if it had run then: same
+      // order, same admission between each. A provider an existential obligation shares with another is left to the
+      // loop, which may never need it.
+      const shared = (id: string) => context.config.obligations.some(o => (o.providerPolicy ?? "all") === "existential" && o.providers.includes(id) && o.providers.length > 1);
+      const beside = invokeProvider === undefined ? [] : [...requested].filter(([id, request]) => {
+        const registration = context.config.providers.find(p => p.id === id)!;
+        return registration.independentOfScopedChecks === true && registration.command !== undefined && request.needsLiveResult && !request.requiresEvidence && !shared(id) && !besideOutcomes.has(id);
+      });
+      const cancelBeside = new AbortController();
+      let cancelledAfter: string | undefined;
+      // They start once the pool is saturated (every worker holds a check, or none is left to hand out), not at
+      // once: the checks handed out first, the longest expected first, have then been handed out, usually with time
+      // to size themselves while the rest wait on their bases.
+      const besideRuns: Promise<{ result: Awaited<ReturnType<NonNullable<CommandContext["invokeProvider"]>>> } | { error: unknown }>[] = [];
+      const startBeside = () => {
+        if (besideRuns.length > 0 || cancelBeside.signal.aborted) return;
+        for (const [providerId, request] of beside) besideRuns.push(invokeProvider!({ providerId, requiresEvidence: false, signal: cancelBeside.signal,
+          payload: { gateId: context.config.gateId, providerId, obligationIds: [...new Set(request.obligationIds)].sort(), candidate: admission.candidate! } })
+          .then(result => ({ result }), (error: unknown) => ({ error })));
+      };
+      let failures: CheckSnapshotError[];
+      try {
+        // The first scoped failure under failFast ends them too: nothing else of this admission may finish.
+        failures = await session.executeAll(scoped.map(([id, request]) => ({ provider: context.config.providers.find(p => p.id === id)!, obligationIds: request.obligationIds })),
+          failed => { cancelledAfter = failed; cancelBeside.abort(); }, startBeside);
+      } catch (error) { cancelBeside.abort(); await Promise.all(besideRuns); throw error; }
+      // executeAll either throws or has reported saturation: at once when the pool has nothing left, otherwise when its
+      // workers fill or its last check is handed out. A failFast cancel leaves them unstarted, as serial would.
+      const settled = await Promise.all(besideRuns);
+      // An interrupted invocation is an interruption, not a scoped failure's cancellation.
+      if (context.signal?.aborted) throw new CliInterruption();
       attemptBlockers.push(...failures.map(scopedCheckBlocker));
       failedFast = failFast && failures.length > 0;
+      for (const [index, [providerId]] of beside.entries()) {
+        // Stopped, or finished too late to count: never reported as passed, and its obligation stays unmet.
+        if (cancelledAfter !== undefined) context.write(`interrupted ${providerId}: check_cancelled after ${cancelledAfter} failed`);
+        else besideOutcomes.set(providerId, { ...settled[index]!, obligationIds: [...new Set(beside[index]![1].obligationIds)].sort() });
+      }
       admission = await admit({ ...input, ...(liveResults.length === 0 ? {} : { liveResults }) }, admissionOptions);
       continue;
     }
@@ -118,7 +156,12 @@ async function providerAdmission(
       admission = await admit({ ...input, ...(liveResults.length === 0 ? {} : { liveResults }) }, admissionOptions);
       continue;
     }
-    const result = await context.invokeProvider?.({
+    // A provider that already ran beside the scoped checks takes its outcome here, where serial would have run it.
+    // Only for the very request it answered: one the loop now makes differently runs again, as serial would run it.
+    const stored = besideOutcomes.get(providerId);
+    const early = stored && digestCanonical(stored.obligationIds) === digestCanonical([...new Set(request.obligationIds)].sort()) ? stored : undefined;
+    if (early && "error" in early) throw early.error;
+    const result = early ? early.result : await context.invokeProvider?.({
       providerId,
       requiresEvidence: request.requiresEvidence,
       payload: {

package/src/scoped-checks.ts

@@ -310,7 +310,11 @@ export class ScopedChecks {
    * worker takes the startable id expected to run longest instead, and its clone queues by that cost, so
    * the critical path gets its base, clone and worker first.
    */
-  private async pool(ids: readonly string[], run: (id: string, lane: Lane) => Promise<void>, halted: () => boolean = () => false, expected?: ReadonlyMap<string, number>): Promise<void> {
+  private async pool(ids: readonly string[], run: (id: string, lane: Lane) => Promise<void>, halted: () => boolean = () => false, expected?: ReadonlyMap<string, number>, onSaturated?: () => void): Promise<void> {
+    // Once every worker holds a check, or none remains to hand out: whichever comes first, and only once.
+    let busy = 0, saturated = false;
+    const saturate = () => { if (!saturated) { saturated = true; onSaturated?.(); } };
+    if (ids.length === 0) saturate();
     const failures = new Map<string, unknown>(), remaining = [...ids];
     const sleepers = new Set<() => void>();
     const woken = () => new Promise<void>(resolve => { sleepers.add(resolve); });
@@ -321,7 +325,7 @@ export class ScopedChecks {
         if (failures.size > 0 || remaining.length === 0) return undefined;
         const index = halted() ? 0 : remaining.reduce((best, id, i) => !this.startable(id) ? best
           : best < 0 || (expected?.get(id) ?? 0) > (expected?.get(remaining[best]!) ?? 0) ? i : best, -1);
-        if (index >= 0) { const id = remaining.splice(index, 1)[0]!; this.claim(id); return id; }
+        if (index >= 0) { const id = remaining.splice(index, 1)[0]!; this.claim(id); busy += 1; if (remaining.length === 0 || busy >= this.workers.length) saturate(); return id; }
         await Promise.race([woken(), ...remaining.flatMap(id => { const key = this.keyOf(id), base = this.bases.get(key); return base ? [this.settling.get(base)!] : this.claims.has(key) ? [this.claims.get(key)!.released] : []; })]);
       }
     };
@@ -331,7 +335,7 @@ export class ScopedChecks {
           const lines: string[] = [];
           try { await run(id, this.concurrency === 1 ? this.serial : { snapshots, write: text => { lines.push(text); }, priority: expected?.get(id) ?? 0 }); }
           catch (error) { failures.set(id, error); this.wakePools(); }
-          finally { this.release(this.keyOf(id), id); for (const line of lines) this.context.write(line); }
+          finally { busy -= 1; this.release(this.keyOf(id), id); for (const line of lines) this.context.write(line); }
         }
       }));
     } finally { this.poolWakers.delete(waker); }
@@ -385,9 +389,11 @@ export class ScopedChecks {
    * Runs the gate's requested checks on the pool. A check's own failure is returned in request order. Without
    * `scopedExecution.failFast` it stops nothing; with it, the first failure cancels every other check: one not
    * yet started never starts and one running has its process group signalled, and both are recorded
-   * `interrupted` with `check_cancelled` and left out of the returned failures.
+   * `interrupted` with `check_cancelled` and left out of the returned failures. `onFailFast` hears that first
+   * failure. `onAllStarted` hears, once, that the pool is saturated: every worker holds a check, or every
+   * requested check has been handed out (at once when none remains for the pool). Not at all if the pool throws.
    */
-  async executeAll(requests: readonly { readonly provider: ProviderRegistration; readonly obligationIds: readonly string[] }[]): Promise<CheckSnapshotError[]> {
+  async executeAll(requests: readonly { readonly provider: ProviderRegistration; readonly obligationIds: readonly string[] }[], onFailFast?: (failed: string) => void, onAllStarted?: () => void): Promise<CheckSnapshotError[]> {
     const failures = new Map<string, CheckSnapshotError>();
     const failFast = this.context.config.scopedExecution?.failFast === true;
     const running = new Map<string, AbortController>(), unstarted: string[] = [];
@@ -404,6 +410,7 @@ export class ScopedChecks {
         failures.set(id, error);
         if (failFast && firstFailure === undefined) {
           firstFailure = id;
+          onFailFast?.(id);
           for (const [other, controller] of running) if (other !== id) controller.abort();
           // A worker waiting for a base takes the rest now, which never start.
           this.wakePools();
@@ -421,8 +428,8 @@ export class ScopedChecks {
     await this.prewarm(requests.map(r => r.provider.id), expected, serialIds);
     if (resource) {
       for (const id of serialIds) await run(id, this.serial);
-      await this.pool(requests.map(r => r.provider.id).filter(id => !serialIds.includes(id)), run, halted, expected);
-    } else await this.pool(requests.map(r => r.provider.id), run, halted, expected);
+      await this.pool(requests.map(r => r.provider.id).filter(id => !serialIds.includes(id)), run, halted, expected, onAllStarted);
+    } else await this.pool(requests.map(r => r.provider.id), run, halted, expected, onAllStarted);
     if (firstFailure !== undefined) await this.cancelUnstarted(unstarted, firstFailure);
     return requests.flatMap(r => failures.has(r.provider.id) ? [failures.get(r.provider.id)!] : []);
   }