@dungle-scrubs/harness-cli-normalizer 0.1.3 → 0.3.1

package/src/execution/failure.ts

@@ -0,0 +1,159 @@
+/**
+ * failure: typed taxonomy for every way a turn can fail, and the reduction
+ * that collapses many observations into one self-sufficient summary on `done`.
+ *
+ * Provider-unavailable vs work-verdict is the load-bearing split: a provider-
+ * unavailable failure (rate-limit, usage-limit, quota, auth, transport) reached
+ * no verdict on the work, so routing the same work elsewhere is safe. A
+ * work-verdict failure (task, budget) means the model did the work and the
+ * work is wrong or incomplete - the router must NOT auto-route it elsewhere,
+ * or it would hide a model error behind a retry. `rejected` is the library
+ * refusing to build the call at all (unexpressible option, bad value); it is
+ * non-retryable across the whole model chain because the remedy is different
+ * options or a different harness, not a different model.
+ */
+
+import type { RefusalIssue } from "../interpretation/refusal.js";
+import type {
+  AuthFailureKind,
+  DiscoveryFacet,
+  LimitCode,
+  TurnOptionKey,
+} from "../knowledge/descriptor.js";
+
+export const FAILURE_CLASSES = Object.freeze([
+  "rate-limit",
+  "usage-limit",
+  "quota",
+  "auth",
+  "budget",
+  "task",
+  "transport",
+  "rejected",
+] as const);
+export type FailureClass = (typeof FAILURE_CLASSES)[number];
+
+export interface FailureSummary {
+  readonly class: FailureClass;
+  readonly retryable: boolean;
+  readonly message: string;
+  readonly code?: LimitCode;
+  readonly authKind?: AuthFailureKind;
+  readonly resetsAt?: number;
+  readonly issue?: RefusalIssue;
+  readonly option?: TurnOptionKey;
+  readonly facet?: DiscoveryFacet;
+  readonly supported?: readonly string[];
+}
+
+export const retryableOf = (cls: FailureClass): boolean =>
+  cls !== "task" && cls !== "budget" && cls !== "rejected";
+
+const messageFor = (cls: FailureClass, detail?: string): string => {
+  switch (cls) {
+    case "rate-limit":
+      return `Rate limit hit${detail ? ` (${detail})` : ""} - retry after backoff or route to another provider`;
+    case "usage-limit":
+      return `Usage limit reached${detail ? ` (${detail})` : ""} - wait for reset or route to another provider`;
+    case "quota":
+      return `Quota exceeded${detail ? ` (${detail})` : ""} - replenish quota or route to another provider`;
+    case "auth":
+      return `Authentication failed${detail ? ` (${detail})` : ""} - re-authenticate this provider`;
+    case "budget":
+      return `Step budget exhausted${detail ? ` (${detail})` : ""} - raise the step cap and retry on the same model`;
+    case "task":
+      return `Task failed${detail ? ` (${detail})` : ""} - surface to caller, do not auto-route`;
+    case "transport":
+      return `Transport failure${detail ? ` (${detail})` : ""} - retry or route to another provider`;
+    case "rejected":
+      return `Request rejected${detail ? ` (${detail})` : ""} - change options or harness`;
+    default:
+      return `Failure${detail ? ` (${detail})` : ""}`;
+  }
+};
+
+export const failureFromLimit = (code: LimitCode): FailureSummary => {
+  const cls: FailureClass =
+    code === "rate-limit"
+      ? "rate-limit"
+      : code === "credits" || code === "quota"
+        ? "quota"
+        : "usage-limit";
+  return {
+    class: cls,
+    retryable: retryableOf(cls),
+    message: messageFor(cls, code),
+    code: code as LimitCode,
+  };
+};
+
+export const failureFromAuth = (kind: AuthFailureKind): FailureSummary => ({
+  class: "auth",
+  retryable: true,
+  message: messageFor("auth", kind),
+  authKind: kind,
+});
+
+export const failureFromTask = (detail?: string): FailureSummary => ({
+  class: "task",
+  retryable: false,
+  message: messageFor("task", detail),
+});
+
+export const failureFromBudget = (detail?: string): FailureSummary => ({
+  class: "budget",
+  retryable: false,
+  message: messageFor("budget", detail),
+});
+
+export const failureFromTransport = (detail?: string): FailureSummary => ({
+  class: "transport",
+  retryable: true,
+  message: messageFor("transport", detail),
+});
+
+export const failureFromRejected = (opts: {
+  issue: RefusalIssue;
+  option?: TurnOptionKey;
+  facet?: DiscoveryFacet;
+  supported?: readonly string[];
+  detail?: string;
+}): FailureSummary => ({
+  class: "rejected",
+  retryable: false,
+  message: messageFor("rejected", opts.detail ?? opts.issue),
+  issue: opts.issue,
+  option: opts.option,
+  facet: opts.facet,
+  supported: opts.supported,
+});
+
+/** Precedence for reduction: lower number = higher priority (wins). */
+const PRECEDENCE: Record<FailureClass, number> = {
+  auth: 1,
+  "rate-limit": 2,
+  "usage-limit": 2,
+  quota: 2,
+  budget: 3,
+  task: 3,
+  transport: 4,
+  rejected: 0, // rejected is separate, not reduced with others? But per spec, rejected is non-retryable and stands alone
+};
+
+export const reduceFailures = (failures: readonly FailureSummary[]): FailureSummary | undefined => {
+  if (failures.length === 0) return undefined;
+  if (failures.length === 1) return failures[0];
+  // Sort by precedence, then by earliest (stable). Lower precedence number wins.
+  let best = failures[0]!;
+  let bestPrec = PRECEDENCE[best.class] ?? 99;
+  for (let i = 1; i < failures.length; i++) {
+    const cur = failures[i]!;
+    const curPrec = PRECEDENCE[cur.class] ?? 99;
+    if (curPrec < bestPrec) {
+      best = cur;
+      bestPrec = curPrec;
+    }
+    // ties keep earliest (do nothing)
+  }
+  return best;
+};

package/src/execution/node-deps.ts

@@ -91,8 +91,25 @@ export const disposableOutputStream = (
 const realSpawn = (argv: readonly string[], opts: SpawnOptions): SpawnedProcess => {
   const [bin, ...args] = argv;
   if (bin === undefined) throw new Error("empty argv");
+  const env =
+    opts.env === undefined
+      ? undefined
+      : (() => {
+          const merged: Record<string, string | undefined> = { ...process.env };
+          for (const [k, v] of Object.entries(opts.env)) {
+            if (v === "") delete merged[k];
+            else merged[k] = v;
+          }
+          // Filter out undefined to satisfy Node's env type (string -> string)
+          const out: Record<string, string> = {};
+          for (const [k, v] of Object.entries(merged)) {
+            if (v !== undefined) out[k] = v;
+          }
+          return out;
+        })();
   const child = nodeSpawn(bin, args, {
     ...(opts.cwd !== undefined ? { cwd: opts.cwd } : {}),
+    ...(env !== undefined ? { env } : {}),
     stdio: [
       opts.stdin === "pipe" ? "pipe" : opts.stdin === "close" ? "ignore" : "inherit",
       "pipe",

package/src/execution/stream-turn.ts

@@ -17,11 +17,21 @@ import {
 } from "../interpretation/argv.js";
 import { stdinPolicyOf } from "../interpretation/dimensions.js";
 import { detectAuthFailureInLine, detectLimitInLine } from "../interpretation/limits.js";
+import { ArgvRefusalError } from "../interpretation/refusal.js";
 import type { HarnessDescriptor } from "../knowledge/descriptor.js";
+import { matcherOverridesOf } from "../knowledge/overrides.js";
 import { AsyncChannel } from "./channel.js";
 import { decodeLine, freshDecodeState } from "./decode.js";
 import type { RunnerDeps, SpawnedProcess } from "./deps.js";
 import type { ExitCause, HarnessEvent } from "./events.js";
+import type { FailureSummary } from "./failure.js";
+import {
+  failureFromAuth,
+  failureFromLimit,
+  failureFromRejected,
+  failureFromTransport,
+  reduceFailures,
+} from "./failure.js";
 import { LineBuffer } from "./lines.js";
 
 /** Fallback correlation when the host does not mint turn ids: monotonic per
@@ -45,13 +55,18 @@ const SECRETISH = /(sk-[A-Za-z0-9_-]{8,}|(?:token|key|secret|password)=\S+)/i;
 
 /** Redact by POSITION, not shape: the prompt is a known argv slot and is
  * masked wholesale (content never reaches a log line - v1 D-005); every
- * other token is kept unless it is secret-shaped. */
-export const redactArgv = (argv: readonly string[], prompt?: string): string[] =>
-  argv.map((token) => {
-    if (prompt !== undefined && token === prompt) return `[prompt:${prompt.length}ch]`;
+ * other token is kept unless it is secret-shaped. Only the prompt's
+ * positional slot is masked, so a one-word prompt that equals a flag
+ * value does not cause that flag value to be masked. */
+export const redactArgv = (argv: readonly string[], prompt?: string): string[] => {
+  const promptIndex = prompt !== undefined ? argv.lastIndexOf(prompt) : -1;
+  const promptLabel = prompt !== undefined ? `[prompt:${prompt.length}ch]` : "";
+  return argv.map((token, index) => {
+    if (index === promptIndex) return promptLabel;
     if (SECRETISH.test(token)) return "[redacted]";
     return token;
   });
+};
 
 /** Bounded tail of unmatched stderr - the crash context a nonzero exit is
  * explained by (v1 kept the turn's output slice for exactly this). Shared
@@ -79,6 +94,8 @@ export interface TurnRunOptions extends LaunchOptions {
   readonly resume?: string;
   /** Working directory for the spawned harness. */
   readonly cwd?: string;
+  /** Per-call environment, merged over parent; "" deletes. */
+  readonly env?: Readonly<Record<string, string>>;
 }
 
 export async function* streamTurn(
@@ -88,18 +105,87 @@ export async function* streamTurn(
 ): AsyncIterable<HarnessEvent> {
   const turnId = deps.turnId ?? `turn-${++turnCounter}`;
   const log = deps.log ?? (() => {});
-  const argv =
-    opts.resume === undefined
-      ? buildLaunchArgv(h, opts)
-      : buildResumeArgv(h, { ...opts, sessionId: opts.resume });
-  const granularity = streamingGranularityOf(h, argv);
 
+  // Validate env before building argv so an invalid env is a refusal, not a spawn
+  if (opts.env !== undefined) {
+    for (const [k, v] of Object.entries(opts.env)) {
+      if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(k) || k.includes("\0") || v.includes("\0")) {
+        const refusal = new ArgvRefusalError({
+          issue: "invalid-env",
+          harness: h.name,
+          supported: ["env keys must match /^[A-Za-z_][A-Za-z0-9_]*$/ and no NUL"],
+          detail: k,
+        });
+        const failure = failureFromRejected({
+          issue: refusal.issue,
+          option: undefined,
+          supported: refusal.supported,
+          detail: k,
+        });
+        log({
+          event: "rejected",
+          turnId,
+          harness: h.name,
+          issue: refusal.issue,
+          supported: refusal.supported,
+          argv: redactArgv([], opts.prompt),
+        });
+        yield { kind: "failure", ...failure };
+        yield { kind: "done", exitCode: null, cause: "failed", failure };
+        return;
+      }
+    }
+  }
+
+  let argv: string[];
+  let granularity: import("../knowledge/descriptor.js").StreamingGranularity;
+  try {
+    argv =
+      opts.resume === undefined
+        ? buildLaunchArgv(h, opts)
+        : buildResumeArgv(h, { ...opts, sessionId: opts.resume });
+    granularity = streamingGranularityOf(h, argv);
+  } catch (e) {
+    if (e instanceof ArgvRefusalError) {
+      const failure = failureFromRejected({
+        issue: e.issue,
+        option: e.option,
+        facet: e.facet,
+        supported: e.supported,
+        detail: e.message,
+      });
+      // No process spawned on a refusal - log rejected instead of spawn
+      let argvForLog: string[] = [];
+      try {
+        argvForLog = redactArgv([], opts.prompt);
+      } catch {}
+      log({
+        event: "rejected",
+        turnId,
+        harness: h.name,
+        issue: e.issue,
+        option: e.option,
+        facet: e.facet,
+        supported: e.supported,
+        argv: argvForLog,
+      });
+      yield { kind: "failure", ...failure };
+      yield { kind: "done", exitCode: null, cause: "failed", failure };
+      return;
+    }
+    throw e;
+  }
+
+  const matcherOverrides = matcherOverridesOf.get(h);
+  const envKeys = opts.env ? Object.keys(opts.env) : undefined;
   log({
     event: "spawn",
     turnId,
     harness: h.name,
     argv: redactArgv(argv, opts.prompt),
     granularity,
+    ...(matcherOverrides ? { matcherOverrides } : {}),
+    ...(envKeys?.length ? { envKeys } : {}),
   });
 
   let proc: SpawnedProcess;
@@ -107,11 +193,12 @@ export async function* streamTurn(
     proc = deps.spawn(argv, {
       stdin: stdinPolicyOf(h) === "close-required" ? "close" : "inherit",
       ...(opts.cwd !== undefined ? { cwd: opts.cwd } : {}),
+      ...(opts.env !== undefined ? { env: opts.env } : {}),
     });
   } catch (cause) {
-    // A spawn that cannot start still honors the contract: error, done,
-    // and a closed exit log - never a throw out of the first next().
+    // Spawn failure is a transport failure, not merely a crash
     const message = cause instanceof Error ? cause.message : String(cause);
+    const failure = failureFromTransport(`spawn failed: ${message}`);
     log({
       event: "exit",
       turnId,
@@ -121,7 +208,8 @@ export async function* streamTurn(
       spawnError: message,
     });
     yield { kind: "error", message: `spawn failed: ${message}` };
-    yield { kind: "done", exitCode: 127, cause: "crash" };
+    yield { kind: "failure", ...failure };
+    yield { kind: "done", exitCode: 127, cause: "failed", failure };
     return;
   }
 
@@ -148,21 +236,62 @@ export async function* streamTurn(
     }, KILL_GRACE_MS);
   };
 
+  const failures: FailureSummary[] = [];
+  const pushFailure = async (f: FailureSummary): Promise<void> => {
+    failures.push(f);
+    await queue.push({ kind: "failure", ...f });
+  };
+
   let watchdog: number | null = null;
+  let turnDeadline: number | null = null;
+  let watchdogReason: "inactivity" | "turn-deadline" | null = null;
   const disarm = (): void => {
     if (watchdog !== null) deps.clock.clearTimeout(watchdog);
     watchdog = null;
+    if (turnDeadline !== null) deps.clock.clearTimeout(turnDeadline);
+    turnDeadline = null;
   };
   const rearm = (): void => {
-    if (granularity !== "none" || deps.stallMs === undefined) return;
-    disarm();
+    if (deps.stallMs === undefined) return;
+    if (watchdog !== null) deps.clock.clearTimeout(watchdog);
     watchdog = deps.clock.setTimeout(() => {
       killedByWatchdog = true;
-      log({ event: "stall", turnId, harness: h.name, stallMs: deps.stallMs });
+      watchdogReason = "inactivity";
+      log({
+        event: "stall",
+        turnId,
+        harness: h.name,
+        reason: "inactivity",
+        budgetMs: deps.stallMs,
+      });
+      // Disarm the other budget
+      if (turnDeadline !== null) {
+        deps.clock.clearTimeout(turnDeadline);
+        turnDeadline = null;
+      }
       escalate();
     }, deps.stallMs);
   };
+  // Arm both budgets
   rearm();
+  if (deps.turnTimeoutMs !== undefined) {
+    turnDeadline = deps.clock.setTimeout(() => {
+      killedByWatchdog = true;
+      watchdogReason = "turn-deadline";
+      log({
+        event: "stall",
+        turnId,
+        harness: h.name,
+        reason: "turn-deadline",
+        budgetMs: deps.turnTimeoutMs,
+      });
+      if (watchdog !== null) {
+        deps.clock.clearTimeout(watchdog);
+        watchdog = null;
+      }
+      escalate();
+    }, deps.turnTimeoutMs);
+  }
 
   let pipeGrace: number | null = null;
   void proc.exited.then((code) => {
@@ -186,16 +315,26 @@ export async function* streamTurn(
     const lines = new LineBuffer();
     for await (const chunk of proc.stdout) {
       if (cancelled) break;
-      rearm();
+      // Any output chunk rearms the inactivity budget, but not the wall-clock deadline
+      if (deps.stallMs !== undefined) rearm();
       for (const line of lines.push(chunk)) {
         for (const event of decodeLine(h, line, state, opts.model ?? "")) {
+          if ((event as unknown as { kind: string }).kind === "failure") {
+            // Directly from decode's rate_limit_event handling - track for reduction
+            failures.push(event as unknown as FailureSummary);
+          }
           await queue.push(event);
         }
       }
     }
     const rest = lines.flush();
     if (rest !== null && !cancelled) {
-      for (const event of decodeLine(h, rest, state, opts.model ?? "")) await queue.push(event);
+      for (const event of decodeLine(h, rest, state, opts.model ?? "")) {
+        if ((event as unknown as { kind: string }).kind === "failure") {
+          failures.push(event as unknown as FailureSummary);
+        }
+        await queue.push(event);
+      }
     }
   };
 
@@ -203,20 +342,26 @@ export async function* streamTurn(
     const lines = new LineBuffer();
     for await (const chunk of proc.stderr) {
       if (cancelled) break;
-      rearm();
+      if (deps.stallMs !== undefined) rearm();
       for (const line of lines.push(chunk)) {
         const limit = detectLimitInLine(h, line);
         if (limit !== null) {
           state.limitSeen = true;
+          const failure = failureFromLimit(limit);
+          // Emit both limit (for 0.1.3 compat) and failure
           await queue.push({
             kind: "limit",
             code: limit,
             message: `limit wall detected (${limit})`,
           });
+          await pushFailure(failure);
           continue;
         }
         const auth = detectAuthFailureInLine(h, line);
         if (auth !== null) {
+          const failure = failureFromAuth(auth);
+          await pushFailure(failure);
+          // Emit error alongside failure for 0.1.3 compat
           await queue.push({ kind: "error", message: `auth wall: ${auth}` });
           continue;
         }
@@ -240,6 +385,7 @@ export async function* streamTurn(
         issue: "read-failed",
       });
       await queue.push({ kind: "error", message: pumpFailureMessage(stream, cause) });
+      await pushFailure(failureFromTransport(pumpFailureMessage(stream, cause)));
       escalate();
       await proc.exited;
       proc.disposeOutput();
@@ -254,7 +400,27 @@ export async function* streamTurn(
   try {
     for await (const event of queue) yield event;
 
-    const cause: ExitCause = state.limitSeen
+    // Post-queue failure sources: nonzero exit with no other failure is transport
+    if (
+      failures.length === 0 &&
+      exitCode !== 0 &&
+      exitCode !== null &&
+      !killedByWatchdog &&
+      !state.limitSeen
+    ) {
+      const f = failureFromTransport(`nonzero exit ${exitCode}`);
+      failures.push(f);
+      // Need to emit this failure before done, even though queue is closed
+      yield { kind: "failure", ...f };
+    }
+    // Stall watchdog also implies a transport failure if not already present
+    if (killedByWatchdog && failures.length === 0) {
+      const f = failureFromTransport(`stalled: ${watchdogReason ?? "inactivity"}`);
+      failures.push(f);
+      yield { kind: "failure", ...f };
+    }
+
+    let cause: ExitCause = state.limitSeen
       ? "limit"
       : killedByWatchdog && exitCode !== 0
         ? "stall"
@@ -263,6 +429,8 @@ export async function* streamTurn(
           : exitCode === null
             ? "killed"
             : "crash";
+    const reduced = reduceFailures(failures);
+    if (reduced && cause === "clean") cause = "failed";
     const tail = stderrTail.snapshot();
     log({
       event: "exit",
@@ -271,7 +439,10 @@ export async function* streamTurn(
       exitCode,
       cause,
       ...(pipesOpenAtExit ? { pipesOpenAtExit } : {}),
-      ...(cause === "crash" || cause === "stall" || cause === "killed" ? { stderrTail: tail } : {}),
+      ...(cause === "crash" || cause === "stall" || cause === "killed" || cause === "failed"
+        ? { stderrTail: tail }
+        : {}),
+      ...(reduced ? { failure: reduced } : {}),
     });
     // A failure with captured stderr surfaces as a stream-level error, not
     // only in the exit log - so a crash from the real adapter's async spawn
@@ -280,7 +451,7 @@ export async function* streamTurn(
       yield { kind: "error", message: tail.join("\n").slice(0, 4096) };
     }
     terminalEventReached = true;
-    yield { kind: "done", exitCode, cause };
+    yield { kind: "done", exitCode, cause, ...(reduced ? { failure: reduced } : {}) };
   } finally {
     const abandoned = !terminalEventReached;
     cancelled = true;