@dieulc/workflow 0.3.1 → 0.4.0

package/review-runtime.ts

@@ -22,13 +22,17 @@
  * instructions — the reviewer only supplies judgement.
  */
 
+import * as path from "node:path";
+
 import {
   DEFAULT_REVIEW_MODE_CONFIG,
   createReviewRoundGate,
   createReviewSession,
   createReviewState,
   planHash,
+  readProviderErrorEvent,
   reviewNeedsVerification,
+  truncateErrorText,
   type CreateReviewSessionOptions,
   type CreateReviewSessionResult,
   type ReviewChildSession,
@@ -44,6 +48,7 @@ import {
   type ReviewVerdict,
   ReviewTranscript as Transcript,
 } from "./review.ts";
+import { appendProviderAuthHint } from "./review-providers.ts";
 import { createReviewTools } from "./review-tools.ts";
 import { renderReviewContextBlock, type ReviewFinding } from "./utils.ts";
 
@@ -71,6 +76,15 @@ export interface ReviewRuntimeDeps {
     | undefined;
   /** Resolve a model from the parent's registry. */
   findModel: (provider: string, id: string) => unknown;
+  /**
+   * Parent-side provider-registration surface for the reviewer runtime, found
+   * with `findParentProviderSurface(ctx)` at session-creation time. Providers
+   * the parent knows that the isolated child does not compose yet are seeded
+   * onto it before `createAgentSession`. Optional: when absent (or when the
+   * probe finds no surface) nothing is seeded and the provider-auth preflight
+   * reports the generic escape hatch instead.
+   */
+  parentProviders?: () => unknown;
   /** Plan path Plan Mode chose (absolute or cwd-relative), if known. */
   planPath: () => string | undefined;
   /** Current plan text on disk, if it exists. */
@@ -279,6 +293,29 @@ export function createReviewRuntime(deps: ReviewRuntimeDeps): ReviewRuntime {
   let abortController: AbortController | undefined;
   /** True while `runRound` is in flight (gates prompt routing). */
   let roundActive = false;
+  /**
+   * The reviewer's most recent provider failure, captured live from child
+   * events (`auto_retry_start`, failed `auto_retry_end`, an `agent_end` that
+   * stopped on error). Latest wins. Cleared at the start of every pass so a
+   * stale error can never mislabel a later clean settle (see runRound).
+   */
+  let lastProviderError:
+    | { message: string; retries: number; at: number }
+    | undefined;
+
+  /** Record one provider failure. The message arrives pre-decoded, non-empty. */
+  const noteProviderError = (message: string, retries: number): void => {
+    lastProviderError = {
+      message,
+      retries: Math.max(0, Math.trunc(retries)),
+      at: Date.now(),
+    };
+  };
+
+  /** Drop the captured error when a new pass starts. */
+  const clearProviderError = (): void => {
+    lastProviderError = undefined;
+  };
 
   const config = (): ReviewModeConfig => {
     try {
@@ -594,6 +631,11 @@ export function createReviewRuntime(deps: ReviewRuntimeDeps): ReviewRuntime {
           // Reuse the already-resolved module instead of importing twice.
           loadSdk: async () => sdk,
         };
+        // Probed lazily, at creation time: the parent context is live here.
+        const parentSurface = deps.parentProviders?.();
+        if (parentSurface !== undefined) {
+          createOptions.parentProviders = parentSurface;
+        }
 
         const created: CreateReviewSessionResult =
           await createReviewSession(createOptions);
@@ -633,6 +675,29 @@ export function createReviewRuntime(deps: ReviewRuntimeDeps): ReviewRuntime {
             }
           }
           const type = readEventType(event);
+          // Capture provider failures as they happen, so a pass that ends
+          // without a submission can be diagnosed with the reviewer's real
+          // API error instead of a generic "no plan" message (see runRound).
+          try {
+            const failure = readProviderErrorEvent(event);
+            if (failure.kind === "retry") {
+              noteProviderError(failure.message, failure.retries);
+            } else if (failure.kind === "exhaust") {
+              noteProviderError(
+                failure.message ||
+                  lastProviderError?.message ||
+                  "provider error (no detail)",
+                failure.retries || lastProviderError?.retries || 0,
+              );
+            } else if (failure.kind === "stop") {
+              noteProviderError(
+                failure.message,
+                lastProviderError?.retries ?? 0,
+              );
+            }
+          } catch {
+            /* error capture is diagnostics only: never break the review */
+          }
           if (type === "agent_settled") {
             noteSettled();
           } else if (type === "agent_end") {
@@ -738,6 +803,7 @@ export function createReviewRuntime(deps: ReviewRuntimeDeps): ReviewRuntime {
       // ── Pass 1 ──────────────────────────────────────────────────────
       await settleInFlight(deadline, rc);
       gate.reset();
+      clearProviderError();
       const pass1Prompt = buildPass1Prompt({
         planPath: input.planPath,
         planText: originalPlan,
@@ -755,7 +821,16 @@ export function createReviewRuntime(deps: ReviewRuntimeDeps): ReviewRuntime {
 
       if (p1.stop === "error") {
         await abortChild();
-        return fail(`could not prompt the reviewer: ${errorText(p1.error)}`);
+        // Safety net for any provider-source gap the preflight could not see:
+        // the bare "No API key found for <provider>." gains the actionable
+        // hint ONLY when the failing provider is the reviewer's own.
+        return fail(
+          `could not prompt the reviewer: ${appendProviderAuthHint(
+            errorText(p1.error),
+            deps.reviewerModel()?.provider,
+            path.join(deps.agentDir, "models.json"),
+          )}`,
+        );
       }
       if (p1.stop === "aborted" || rc.signal.aborted) {
         await abortChild();
@@ -773,10 +848,23 @@ export function createReviewRuntime(deps: ReviewRuntimeDeps): ReviewRuntime {
         // The run is over (or out of time) and nothing reached the plan file.
         // Fail now — waiting longer cannot produce a submission.
         await abortChild();
+        if (p1.stop === "timeout") {
+          return fail(
+            `the reviewer did not finish within ${Math.round((limitMs ?? 0) / 1000)}s and submitted no plan`,
+            originalPlan,
+          );
+        }
+        // A provider failure settles the run without a submission — name the
+        // real cause (with the provider's own message) instead of blaming the
+        // write path. The slot only holds errors captured during THIS pass.
+        if (lastProviderError) {
+          return fail(
+            `the reviewer's provider failed after ${lastProviderError.retries} retry attempt(s): ${truncateErrorText(lastProviderError.message)}`,
+            originalPlan,
+          );
+        }
         return fail(
-          p1.stop === "timeout"
-            ? `the reviewer did not finish within ${Math.round((limitMs ?? 0) / 1000)}s and submitted no plan`
-            : "the reviewer finished without submitting a plan — it has no write path unless review_submit_plan succeeds",
+          "the reviewer finished without submitting a plan — it has no write path unless review_submit_plan succeeds",
           originalPlan,
         );
       }
@@ -802,6 +890,7 @@ export function createReviewRuntime(deps: ReviewRuntimeDeps): ReviewRuntime {
         setPhase("verifying");
         await settleInFlight(deadline, rc);
         gate.reset();
+        clearProviderError();
         const pass2Prompt = buildPass2Prompt({
           planPath: input.planPath,
           originalPlan,
@@ -811,14 +900,28 @@ export function createReviewRuntime(deps: ReviewRuntimeDeps): ReviewRuntime {
         const p2 = await runPass(2, deadline, rc, () =>
           child.followUp(pass2Prompt),
         );
+        // Name the provider when the verification pass died on one; pass 2
+        // stays best-effort either way — pass 1's plan is never lost to it.
+        const p2Provider = lastProviderError
+          ? `provider error after ${lastProviderError.retries} retry attempt(s): ${truncateErrorText(lastProviderError.message)}`
+          : undefined;
         if (p2.error !== undefined) {
           // Verification is an enhancement: never lose pass 1's plan over it.
           deps.log(
-            `Review Mode verification pass failed (${errorText(p2.error)}) — keeping pass 1's plan.`,
+            p2Provider
+              ? `Review Mode verification pass failed (${p2Provider}; send error: ${errorText(p2.error)}) — keeping pass 1's plan.`
+              : `Review Mode verification pass failed (${errorText(p2.error)}) — keeping pass 1's plan.`,
             "warning",
           );
         } else if (p2.submitted) {
           finalPlan = p2.submitted.planText;
+        } else if (p2Provider) {
+          // The run settled without a submission AND a provider error was
+          // seen this pass: say why, then keep going with pass 1's rewrite.
+          deps.log(
+            `Review Mode verification pass ended without a submission (${p2Provider}) — keeping pass 1's plan.`,
+            "warning",
+          );
         }
         if (p2.stop === "timeout") await abortChild();
       }

package/review-ui.ts

@@ -253,6 +253,7 @@ const LINE_COLORS: Record<ReviewEntryLineKind, ThemeColor> = {
   finding: "warning",
   notice: "warning",
   status: "muted",
+  error: "error",
   user: "success",
 };
 

package/review.ts

@@ -36,6 +36,13 @@ import {
   type ReviewFinding,
   type ReviewTier,
 } from "./utils.ts";
+import {
+  checkReviewerProviderAuth,
+  isParentProviderSurface,
+  seedChildRuntimeProviders,
+  unconfiguredReviewerProviderMessage,
+  type ProviderSeedResult,
+} from "./review-providers.ts";
 
 // Re-exported so `review.ts` is the single import surface for Review Mode.
 export type { ReviewDisposition, ReviewFinding, ReviewTier };
@@ -567,7 +574,8 @@ export type ReviewLineKind =
   | "tool"
   | "finding"
   | "notice"
-  | "status";
+  | "status"
+  | "error";
 
 /** One line in the reviewer pane. Kept small: the pane renders these verbatim. */
 export interface ReviewTranscriptLine {
@@ -1099,6 +1107,103 @@ function truncateLabel(s: string, max: number): string {
   return s.length <= max ? s : `${s.slice(0, max - 1).trimEnd()}…`;
 }
 
+/** Longest provider-error excerpt shown inline in a transcript line. */
+export const MAX_ERROR_TEXT = 160;
+
+/**
+ * One-line excerpt of a provider error message for `notify` and the reviewer
+ * pane. Provider errors are often multi-line JSON blobs; they must become a
+ * single line to survive a transcript entry and a `ui.notify` banner.
+ * Pure and total: empty/undefined input yields "", never throws.
+ */
+export function truncateErrorText(input: unknown, max: number = MAX_ERROR_TEXT): string {
+  const raw = typeof input === "string" ? input : "";
+  const flat = raw.replace(/\s+/g, " ").trim();
+  if (!flat) return "";
+  const cap = Math.max(1, Math.trunc(max));
+  return flat.length <= cap ? flat : `${flat.slice(0, cap - 1).trimEnd()}…`;
+}
+
+/**
+ * Extract the provider error message when a run stopped on an error: scan an
+ * `agent_end` event's messages from the end for the last assistant message
+ * with `stopReason === "error"`. Structural on purpose — SDK message shapes
+ * are not imported here. Returns undefined for clean runs and junk input.
+ */
+export function lastAssistantErrorStop(messages: unknown): string | undefined {
+  if (!Array.isArray(messages)) return undefined;
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const rec = messages[i] as Record<string, unknown> | null | undefined;
+    if (!rec || typeof rec !== "object") continue;
+    if (rec.role !== "assistant") continue;
+    // Last assistant message reached: a non-error stop means a clean run.
+    if (rec.stopReason !== "error") return undefined;
+    const err = typeof rec.errorMessage === "string" ? rec.errorMessage : "";
+    return err || "unknown provider error";
+  }
+  return undefined;
+}
+
+/**
+ * What a child-session event says about provider health, decoded at the
+ * boundary so callers branch on typed values instead of SDK event shapes:
+ *
+ * - `retry`   → the SDK scheduled another attempt (`auto_retry_start`) and
+ *   reported the provider's error message.
+ * - `exhaust` → the retry budget ran out (`auto_retry_end`, `success: false`);
+ *   the run is about to settle on an error. `message` may be empty when the
+ *   event carries no `finalError` — callers then keep their earlier message.
+ * - `stop`    → the run itself ended with `stopReason === "error"` on its last
+ *   assistant message (auto-retry disabled, or a non-retryable failure).
+ * - `none`    → anything else, including a retry that recovered.
+ */
+export type ReviewProviderFailure =
+  | { kind: "retry"; message: string; retries: number }
+  | { kind: "exhaust"; message: string; retries: number }
+  | { kind: "stop"; message: string }
+  | { kind: "none" };
+
+/** Structural decode of one provider-failure event. Never throws. */
+export function readProviderErrorEvent(
+  event: unknown,
+): ReviewProviderFailure {
+  const e = eventRecord(event);
+  if (!e) return { kind: "none" };
+  const type = typeof e.type === "string" ? e.type : "";
+  if (type === "auto_retry_start") {
+    const message =
+      typeof e.errorMessage === "string" ? e.errorMessage.trim() : "";
+    if (!message) return { kind: "none" };
+    return {
+      kind: "retry",
+      message,
+      retries: readRetryAttempt(e.attempt),
+    };
+  }
+  if (type === "auto_retry_end") {
+    if (e.success !== false) return { kind: "none" };
+    const message = typeof e.finalError === "string" ? e.finalError.trim() : "";
+    return {
+      kind: "exhaust",
+      message,
+      retries: readRetryAttempt(e.attempt),
+    };
+  }
+  if (type === "agent_end") {
+    const message = lastAssistantErrorStop(e.messages);
+    if (message === undefined) return { kind: "none" };
+    return { kind: "stop", message };
+  }
+  return { kind: "none" };
+}
+
+/** Non-negative attempt count from a retry event; 0 when absent or junk. */
+function readRetryAttempt(value: unknown): number {
+  return typeof value === "number" && Number.isFinite(value) && value > 0
+    ? Math.trunc(value)
+    : 0;
+}
+
 /**
  * Human-readable header for a tool call: the tool name plus a short, safe
  * excerpt of its key argument (`▸ read src/app.ts`, `▸ review_bash: git log -5`).
@@ -1170,6 +1275,12 @@ export function formatActionLabel(toolName: unknown, args: unknown): string {
  * `toolLabels` is owned by the stateful caller (`ReviewTranscript`): the end
  * event carries no args, so the start event registers `toolCallId → label` and
  * the end event consumes it. Pure otherwise; junk input never throws.
+ *
+ * Provider failures are surfaced with their real (truncated) text: the
+ * `auto_retry_start` notice carries the provider's message, and a failed
+ * `auto_retry_end` or an `agent_end` that stopped on `stopReason === "error"`
+ * appends an `error` line — a dead provider is then visible in the pane during
+ * the review instead of resurfacing later as a mysterious "no plan" failure.
  */
 export function translateReviewEvent(
   event: unknown,
@@ -1207,15 +1318,70 @@ export function translateReviewEvent(
   if (type === "agent_start") {
     return [{ op: "new", kind: "status", text: "reviewer started" }];
   }
+  return providerErrorOps(e, type);
+}
+
+/**
+ * Provider-error events → transcript lines, split out of
+ * `translateReviewEvent` to keep the dispatcher flat:
+ *
+ * - `agent_end`        → status line, plus an `error` line when the run
+ *   stopped on `stopReason === "error"` (auto-retry disabled, or the first
+ *   failure was not retryable).
+ * - `auto_retry_start` → notice carrying the provider's message (truncated).
+ * - `auto_retry_end`   → `error` line when the retry budget is exhausted
+ *   (`success: false`); a recovered retry (`success: true`) stays silent.
+ *
+ * Unknown types and junk fields degrade to empty ops; never throws.
+ */
+function providerErrorOps(
+  e: Record<string, unknown>,
+  type: string,
+): ReviewTranscriptOp[] {
   if (type === "agent_end") {
-    return [{ op: "new", kind: "status", text: "reviewer finished this run" }];
+    const ops: ReviewTranscriptOp[] = [
+      { op: "new", kind: "status", text: "reviewer finished this run" },
+    ];
+    const failed = lastAssistantErrorStop(e.messages);
+    if (failed) {
+      ops.push({
+        op: "new",
+        kind: "error",
+        text: `reviewer run ended on a provider error: ${truncateErrorText(failed)}`,
+      });
+    }
+    return ops;
   }
   if (type === "auto_retry_start") {
+    const msg = typeof e.errorMessage === "string" ? e.errorMessage : "";
     return [
-      { op: "new", kind: "notice", text: "retrying after a provider error" },
+      {
+        op: "new",
+        kind: "notice",
+        text: msg
+          ? `retrying after a provider error: ${truncateErrorText(msg)}`
+          : "retrying after a provider error",
+      },
     ];
   }
-
+  if (type === "auto_retry_end") {
+    // `success: false` ends the retry loop with the provider still failing —
+    // the run is about to settle on an error stop. `success: true` means a
+    // retry recovered; the earlier notice already covers that case.
+    if (e.success === false) {
+      const detail = truncateErrorText(e.finalError);
+      return [
+        {
+          op: "new",
+          kind: "error",
+          text: detail
+            ? `reviewer retry budget exhausted: ${detail}`
+            : "reviewer retry budget exhausted",
+        },
+      ];
+    }
+    return [];
+  }
   return [];
 }
 
@@ -1443,6 +1609,23 @@ export interface CreateReviewSessionOptions {
   reviewPrompt: string;
   /** Reviewer-only tools, built by the caller. */
   customTools: unknown[];
+  /**
+   * Parent-side provider-registration surface (structural, feature-detected),
+   * found with `findParentProviderSurface(ctx)` — the session's model registry
+   * facade or its underlying model runtime.
+   *
+   * The reviewer session is deliberately created without ambient extensions,
+   * so a provider registered only in the parent session (e.g. by a provider
+   * extension) does not exist in the reviewer's fresh runtime. When this
+   * surface is given, every provider the parent knows that the child does not
+   * yet compose is registered onto the child BEFORE `createAgentSession` —
+   * natively when the parent has a provider object, otherwise by config.
+   * Absent or surface-less ⇒ nothing is seeded and the provider-auth preflight
+   * (below) reports the generic escape hatch instead. Providers the child
+   * already composes are skipped, so this is a no-op for every provider the
+   * runtime builds in by construction.
+   */
+  parentProviders?: unknown;
   /** Injectable for tests; defaults to a real dynamic import. */
   loadSdk?: ReviewSdkLoader;
 }
@@ -1453,6 +1636,8 @@ export interface CreateReviewSessionResult {
   modelLabel: string;
   /** Tool names the child actually has enabled, when the SDK exposes them. */
   activeTools?: string[];
+  /** What provider seeding did before the session was created, when probed. */
+  providerSeed?: ProviderSeedResult;
   error?: string;
 }
 
@@ -1601,6 +1786,36 @@ export async function createReviewSession(
       };
     }
 
+    // Seed providers the child does not compose yet (e.g. providers registered
+    // only in the parent session) BEFORE the session exists. Present-probe:
+    // only the difference is registered, native-first, per-provider
+    // fault-isolated — never fatal, never layer-aware.
+    const providerSeed = seedChildRuntimeProviders(
+      modelRuntime,
+      options.parentProviders,
+    );
+
+    // Provider-agnostic auth preflight, mirroring the child session's own
+    // prompt gate: fail fast here — with the seed report and the generic
+    // escape hatch — instead of mid-review with a bare "No API key found".
+    const auth = await checkReviewerProviderAuth(
+      modelRuntime,
+      options.modelRef.provider,
+    );
+    if (!auth.configured) {
+      return {
+        ok: false,
+        modelLabel,
+        providerSeed,
+        error: unconfiguredReviewerProviderMessage({
+          providerId: options.modelRef.provider,
+          seed: providerSeed,
+          parentSurfaceFound: isParentProviderSurface(options.parentProviders),
+          modelsJsonPath: path.join(options.agentDir, "models.json"),
+        }),
+      };
+    }
+
     // No ambient extensions, no skills/prompts/themes: the reviewer gets exactly
     // the system prompt below and nothing from the user's other packages.
     // Project context files (AGENTS.md etc.) DO load — they are the framework