@cat-factory/executor-harness 1.78.0 → 1.82.0

package/src/runner.ts

@@ -2,6 +2,7 @@ import { redactSecrets } from './redact.js'
 import type { FollowUpLine } from './follow-ups.js'
 import type { ValidationReport } from './validation-checks.js'
 import type { ReproductionReport } from './reproduction-proof.js'
+import type { SliceReview } from './subagents.js'
 import type { HarnessCallMetric, TodoProgress, ToolSpan } from './pi.js'
 import { log, type Logger } from './logger.js'
 import {
@@ -47,6 +48,14 @@ export interface RunOptions {
    * attempt is final, and the loop republishes a whole new one — with a fresh `at` — per round.
    */
   onReproductionProof?: (report: ReproductionReport) => void
+  /**
+   * Receives the full set of per-slice reviews a parallel review has captured, republished each
+   * time a slice's subagent returns. Latest-wins (NOT a drain buffer), for the same reason as
+   * {@link onValidationReport} but with more at stake: these carry the slices' actual review work,
+   * and a review whose aggregation never finishes is recoverable ONLY from what the backend
+   * already persisted. Absent for a job that dispatched no subagents.
+   */
+  onSliceReviews?: (reviews: SliceReview[]) => void
   /**
    * Receives each per-call telemetry row the moment the agent's CLI stream yields it, so a
    * run's model calls reach `llm_call_metrics` WHILE it runs rather than only in its terminal
@@ -203,6 +212,18 @@ export interface JobView<TResult extends JobResultBase = JobResultBase> {
    * that carried no reproduction declaration.
    */
   reproductionReport?: ReproductionReport
+  /**
+   * The per-slice reviews captured so far on a parallel (subagent-fanned) review — each slice's
+   * label, whether its subagent returned, and its verbatim report. A whole-value latest publish
+   * like {@link validationReport}, not drain-on-read.
+   *
+   * This is the durable half of a PR review. The reviewer returns `slices`/`findings` only in its
+   * TERMINAL structured output, so before this existed a review killed mid-run (or one whose
+   * aggregation pass wedged) lost every finished slice and could only be re-run from zero. The
+   * backend persists these onto the step as they arrive, which is what a manual resume re-aggregates
+   * from. Absent for a job that dispatched no subagents.
+   */
+  sliceReviews?: SliceReview[]
 }
 
 interface JobEntry<TResult extends JobResultBase> extends JobView<TResult> {
@@ -473,6 +494,9 @@ export class JobRegistry<TJob = unknown, TResult extends JobResultBase = JobResu
         onValidationReport: (report) => {
           entry.validationReport = report
         },
+        onSliceReviews: (reviews) => {
+          entry.sliceReviews = reviews
+        },
         onReproductionProof: (report) => {
           entry.reproductionReport = report
         },

package/src/subagents.ts

@@ -4,6 +4,7 @@ import { basename, join } from 'node:path'
 import {
   claudeAssistantContent,
   claudeCallUsage,
+  claudeToolResultText,
   isObject,
   redactBody,
   SUBAGENT_TOOL_NAMES,
@@ -54,20 +55,52 @@ import { publishCallMetric, type HarnessCallMetric, type TodoProgress } from './
 // Slice / progress tracking off the PARENT stream (D2.1)
 // ---------------------------------------------------------------------------
 
+/**
+ * How much of one slice's terminal report is kept. A slice review is prose (findings for a handful
+ * of files), not a transcript, so this is far above a real report while still bounding what a
+ * runaway subagent can push onto the step — the reports ride the job view on every poll and are
+ * persisted on the run.
+ */
+export const SLICE_REPORT_MAX_CHARS = 24_000
+
 interface TrackedSlice {
   /** The dispatch's tool_use id, used to pair the terminal tool_result. */
   toolUseId: string
   /** The subagent's description (`Review <slice> slice`), rendered as the progress label. */
   description: string
   done: boolean
+  /**
+   * The subagent's verbatim terminal report, captured from the paired `tool_result`; undefined
+   * until it lands. This is the slice's actual review work — the reason a stuck aggregation no
+   * longer costs the whole run (see `prReviewSliceReviewSchema`). Truncated to
+   * {@link SLICE_REPORT_MAX_CHARS} and scrubbed of leased credentials before it leaves here.
+   */
+  report?: string
+}
+
+/** One slice's live review, as published on the job view. Mirrors `prReviewSliceReviewSchema`. */
+export interface SliceReview {
+  label: string
+  status: 'in_progress' | 'completed'
+  report?: string | null
 }
 
 /** Tracks parallel subagents seen on the parent stream to derive slice progress. */
 export interface SliceTracker {
   /** Feed an `assistant` message's content blocks: registers any subagent dispatches. */
   onAssistant(content: unknown[]): void
-  /** Feed a `user` message's content blocks: marks the paired subagent(s) complete. */
+  /**
+   * Feed a `user` message's content blocks: marks the paired subagent(s) complete AND captures
+   * each one's terminal report (see {@link SliceTracker.sliceReviews}).
+   */
   onUser(content: unknown[]): void
+  /**
+   * Every dispatched slice with its status and captured report, in dispatch order — the durable
+   * half of this tracker. Published as a whole value on each poll (NOT drain-on-read): the set
+   * only grows, and a dropped poll response must never permanently lose a finished slice's
+   * review, which is the entire point of capturing it. Empty when nothing was dispatched.
+   */
+  sliceReviews(): SliceReview[]
   /** Whether any `Task` subagent has been dispatched (⇒ this run parallelised). */
   hasSlices(): boolean
   /**
@@ -80,7 +113,12 @@ export interface SliceTracker {
   progress(): TodoProgress | undefined
 }
 
-export function createSliceTracker(): SliceTracker {
+/**
+ * @param secrets Leased-credential strings scrubbed from every captured report. A subagent can
+ *   echo a token it saw in the checkout, and these reports are persisted on the run, so they are
+ *   redacted on the way in rather than trusting each consumer to do it.
+ */
+export function createSliceTracker(secrets: string[] = []): SliceTracker {
   // Insertion-ordered so the progress `items` render in dispatch order.
   const slices = new Map<string, TrackedSlice>()
 
@@ -106,9 +144,25 @@ export function createSliceTracker(): SliceTracker {
         if (!isObject(block) || block.type !== 'tool_result') continue
         const id = typeof block.tool_use_id === 'string' ? block.tool_use_id : undefined
         const slice = id ? slices.get(id) : undefined
-        if (slice) slice.done = true
+        if (!slice) continue
+        slice.done = true
+        // The report is captured here or nowhere: this `tool_result` is the only place the
+        // subagent's findings appear on the parent stream, and the next poll may be the last one
+        // this job ever answers.
+        const report = redactBody(claudeToolResultText(block), secrets).trim()
+        if (report) slice.report = report.slice(0, SLICE_REPORT_MAX_CHARS)
       }
     },
+    sliceReviews() {
+      return [...slices.values()].map((s) => ({
+        label: s.description,
+        status: (s.done ? 'completed' : 'in_progress') as 'completed' | 'in_progress',
+        // A slice that finished but whose result carried no readable text is reported as
+        // completed with a null report rather than being dropped: a resume must still know it
+        // does not need re-reviewing, and silently omitting it would send it round again.
+        report: s.report ?? null,
+      }))
+    },
     hasSlices() {
       return slices.size > 0
     },