@cat-factory/executor-harness 1.106.0 → 1.110.0

package/src/coding-agent.ts

@@ -1,14 +1,9 @@
 import { mkdir } from 'node:fs/promises'
 import { join } from 'node:path'
 import { runCapturedCommand } from './captured-command.js'
-import { makeDirClaimer } from './checkout-dir.js'
 import type {
-  AgentJob,
-  AgentResult,
   HarnessAuthFields,
-  PeerRepoSpec,
-  ReferenceRepoSpec,
-  ReferenceScreenshotsSpec,
+  ImageManifestSpec,
   RepoSpec,
   SkillSpec,
   McpServerSpec,
@@ -30,14 +25,12 @@ import {
   refreshFromBaseIfClean,
   remoteBranchExists,
 } from './git.js'
-import { openPullRequest } from './vcs-api.js'
 import { FOLLOW_UPS_FILENAME, FollowUpTailer } from './follow-ups.js'
 import type { HarnessCallMetric } from './pi.js'
 import type { PiRunStats } from './pi-reduction.js'
 import { EFFORT_REPORT_FILE, type EffortReport } from './effort.js'
 import {
   type AgentPrDescription,
-  applyPrDescription,
   PR_DESCRIPTION_FILE,
   readPrDescription,
 } from './pr-description.js'
@@ -46,7 +39,6 @@ import {
   agentNeverActed,
   agentOutputTail,
   runAgentInWorkspace,
-  withWorkspace,
 } from './pi-workspace.js'
 import type { ProgressGuardLimits } from './progress-guard.js'
 import type { RunOptions } from './runner.js'
@@ -77,7 +69,7 @@ import {
 // CI-fixer (`/ci-fix`) agents are conceptually the same job — only what they clone
 // onto and what they do with the outcome differ — so they share this whole flow
 // rather than each re-deriving (and separately bug-fixing) it. Built on the thinner
-// {@link withWorkspace}/{@link runAgentInWorkspace} base shared with the non-pushing
+// `withWorkspace`/{@link runAgentInWorkspace} base shared with the non-pushing
 // agents (bootstrap/blueprint/merger). Mirrors their secret handling: the per-job
 // GitHub + proxy tokens arrive in the spec and live only for the job's duration.
 
@@ -188,7 +180,14 @@ export interface CodingAgentSpec extends HarnessAuthFields {
    * UI-facing kind may well be a coding one, and nothing here switches on which built-in it is.
    * Absent ⇒ none (the normal case).
    */
-  referenceScreenshots?: ReferenceScreenshotsSpec
+  referenceScreenshots?: ImageManifestSpec
+  /**
+   * The PICTURES of the task's designs, downloaded into `.cat-context/design-renders/` before the
+   * agent's first turn. Carried here for the same reason the capture set is: what earns a run its
+   * pictures is the KIND's declared trait plus a harness that can read an image, and a coding kind
+   * is the commonest holder of both. Absent ⇒ none (the normal case).
+   */
+  designImages?: ImageManifestSpec
 }
 
 /** The outcome of a coding agent run, before each caller maps it to its own result shape. */
@@ -208,7 +207,7 @@ export interface CodingAgentOutcome {
   effortReport?: EffortReport
   /**
    * The agent-authored PR description, lifted from its sentinel file (absent when it wrote none).
-   * The PR-opening caller folds it over the dispatch-time title/body via {@link applyPrDescription};
+   * The PR-opening caller folds it over the dispatch-time title/body via `applyPrDescription`;
    * absent means the fallback text, unchanged.
    */
   prDescription?: AgentPrDescription
@@ -470,6 +469,7 @@ export async function runCodingAgent(
             ...(spec.referenceScreenshots
               ? { referenceScreenshots: spec.referenceScreenshots }
               : {}),
+            ...(spec.designImages ? { designImages: spec.designImages } : {}),
           },
           opts,
         )
@@ -1031,449 +1031,6 @@ export async function runRalphValidation(
   }
 }
 
-/** One repository participating in a multi-repo run: where to clone it + what to do after. */
-interface RepoLeg {
-  repo: RepoSpec
-  /** Sibling directory name under the workspace root. */
-  dirName: string
-  /** Absolute checkout directory (filled during the clone phase). */
-  dir: string
-  /** Branch to clone (the repo's base). */
-  cloneBranch: string
-  /** Branch to create off the clone and push the work to (the shared `cat-factory/<block>`). */
-  workBranch: string
-  ghToken: string
-  pr?: { title: string; body: string }
-  frameId?: string
-  primary: boolean
-  /**
-   * A READ-ONLY reference checkout (doc-writer's `referenceRepos`): cloned at its base branch for
-   * the agent to read, but NEVER given a work branch, committed, or pushed. Skipped entirely in the
-   * push phase, so it is structurally impossible for the run to write to it. Absent ⇒ a writable leg.
-   */
-  readOnly?: boolean
-  /** The branch tip before the run — work iff the branch advances past it. */
-  baseSha: string
-  /** Whether an existing remote work branch was resumed (already carries prior work). */
-  resumed: boolean
-}
-
-/**
- * Multi-repo coding (service-connections phase 3): clone the primary repo AND every connected
- * peer repo as SIBLING checkouts under one workspace root, run the agent ONCE with its cwd at
- * that root (so it makes the cross-service change coherently across all of them), then commit +
- * push each repo that actually changed and open one PR per dirty repo. The task's own-service PR
- * is reported as `prUrl`/`branch`; the peer PRs as `peerPullRequests`.
- *
- * Deliberately simpler than the single-repo {@link runCodingAgent} for the first cut: NO mid-run
- * checkpoint pushes (an evicted multi-repo run re-clones on retry — the deterministic work branch
- * still lets it resume any commits it managed to push at the end), NO warm-pool persistent
- * checkout (always ephemeral), and NO follow-up sentinel streaming. It reuses the SAME dir-scoped
- * git helpers, so the per-repo clone/commit/push/PR mechanics match the single-repo path exactly.
- */
-export async function runMultiRepoCoding(
-  job: AgentJob,
-  opts: RunOptions = {},
-): Promise<AgentResult> {
-  const logger = (opts.log ?? log).child({ kind: 'multi-repo', jobId: job.jobId })
-  const peers: PeerRepoSpec[] = job.peerRepos ?? []
-  const references: ReferenceRepoSpec[] = job.referenceRepos ?? []
-  const primaryWorkBranch = job.pushBranch ?? job.newBranch ?? job.branch
-
-  // Assign the sibling directory per repo via the shared deterministic allocator
-  // (`owner__name__digest`, matching the backend prompt's `siblingCheckoutDir`), shared with the
-  // read-only explore fan-out.
-  const claimDir = makeDirClaimer()
-  const legs: RepoLeg[] = [
-    {
-      repo: job.repo,
-      dirName: claimDir(job.repo),
-      dir: '',
-      cloneBranch: job.branch,
-      workBranch: primaryWorkBranch,
-      ghToken: job.ghToken,
-      ...(job.pr ? { pr: job.pr } : {}),
-      primary: true,
-      baseSha: '',
-      resumed: false,
-    },
-    ...peers.map((peer): RepoLeg => ({
-      repo: peer.repo,
-      dirName: claimDir(peer.repo),
-      dir: '',
-      cloneBranch: peer.repo.baseBranch,
-      // Coding peers always carry `newBranch` (the backend sets the shared work branch);
-      // fall back to the primary's for the type (read-only peers never reach this path).
-      workBranch: peer.newBranch ?? primaryWorkBranch,
-      ghToken: peer.ghToken ?? job.ghToken,
-      ...(peer.pr ? { pr: peer.pr } : {}),
-      ...(peer.frameId ? { frameId: peer.frameId } : {}),
-      primary: false,
-      baseSha: '',
-      resumed: false,
-    })),
-    // Read-only reference repos (doc-writer): cloned as siblings the agent reads but never writes.
-    // `workBranch` is set to the base only to satisfy the type — a read-only leg never branches or
-    // pushes (guarded by `readOnly` in both the clone and push phases below).
-    ...references.map((reference): RepoLeg => ({
-      repo: reference.repo,
-      dirName: claimDir(reference.repo),
-      dir: '',
-      cloneBranch: reference.repo.baseBranch,
-      workBranch: reference.repo.baseBranch,
-      ghToken: reference.ghToken ?? job.ghToken,
-      primary: false,
-      readOnly: true,
-      baseSha: '',
-      resumed: false,
-    })),
-  ]
-
-  return withWorkspace('multi', async (root) => {
-    // Clone (or resume) every sibling checkout under the workspace root and fetch the primary's
-    // reference branches. Mutates each leg's `dir`/`resumed`/`baseSha` in place.
-    await prepareMultiRepoCheckouts(root, legs, job, logger, opts)
-
-    // DEPENDENCY PREPOPULATION for the PRIMARY leg, exactly as the read-only multi-repo fan-out
-    // does it. The install is declared on ONE service frame (the primary repo's), so it runs in
-    // that leg's checkout and is never fanned out across peers, whose own frames declare configs
-    // this dispatch never resolved — running a `pnpm install` inside a Go checkout is not a
-    // degraded outcome, it is a wrong one. A cross-repo implementer needs its dependencies for
-    // the same reason a cross-repo investigator does; the note names the sibling directory
-    // because the agent itself stands at the workspace root.
-    //
-    // At the leg's checkout ROOT, not a `serviceDirectory` subtree: this layout applies no
-    // service-directory scoping anywhere (the agent runs at the root and the prompt explains the
-    // sibling checkouts), and a root install is the one that resolves a monorepo workspace whole.
-    const primaryLeg = legs.find((leg) => leg.primary)
-    const dependencyNote = primaryLeg
-      ? await prepopulateDependencies({
-          spec: job.dependencyInstall,
-          installDir: primaryLeg.dir,
-          repoDir: primaryLeg.dir,
-          agentDir: root,
-          logger,
-          opts,
-        })
-      : undefined
-
-    // THE REPOS' OWN PR TEMPLATES: one per leg that will actually open a pull request, each named
-    // by its sibling directory so the agent knows which checkout's briefing takes which shape —
-    // the repos in a workspace need not share a template, or ship one at all. A read-only
-    // reference leg is excluded by construction: it carries no `pr`, so nothing publishes for it.
-    const prTemplate = await resolvePrTemplateNote({
-      targets: legs
-        .filter((leg) => leg.pr)
-        .map((leg) => ({
-          repoDir: leg.dir,
-          repoLabel: leg.dirName,
-          ...(leg.repo.provider ? { provider: leg.repo.provider } : {}),
-        })),
-      logger,
-    })
-
-    // Run the agent ONCE with its cwd at the workspace root, so it sees every sibling checkout
-    // and can change them coherently. No monorepo/service-directory scoping — the multi-repo
-    // note + the backend system-prompt section explain the layout.
-    opts.onPhase?.('agent')
-    logger.info('multi-repo: running agent', { repos: legs.map((l) => l.dirName) })
-    const { summary, stats, stderrTail, usage, callMetrics, effortReport } =
-      await runAgentInWorkspace(
-        {
-          dir: root,
-          systemPrompt: job.systemPrompt,
-          userPrompt: withDependencyNote(
-            withPrTemplateNote(job.userPrompt, prTemplate.note),
-            dependencyNote,
-          ),
-          model: job.model,
-          harness: job.harness,
-          subscriptionToken: job.subscriptionToken,
-          subscriptionBaseUrl: job.subscriptionBaseUrl,
-          ambientAuth: job.ambientAuth,
-          proxyBaseUrl: job.proxyBaseUrl,
-          proxyPhasePath: job.proxyPhasePath,
-          sessionToken: job.sessionToken,
-          webToolsGuidance: job.webToolsGuidance,
-          webSearchProxy: job.webSearch,
-          guardLimits: job.guardLimits,
-          ...(job.contextFiles ? { contextFiles: job.contextFiles } : {}),
-          // Skills + tool servers apply to a multi-repo run exactly as to a single-repo one: they
-          // are properties of the AGENT KIND, not of the checkout layout.
-          ...(job.skills?.length ? { skills: job.skills } : {}),
-          ...(job.mcpServers?.length ? { mcpServers: job.mcpServers } : {}),
-          ...(job.referenceScreenshots ? { referenceScreenshots: job.referenceScreenshots } : {}),
-          multiRepo: true,
-        },
-        opts,
-      )
-
-    // Commit forgotten tracked edits, then push + open a PR for each repo the run actually changed.
-    const { primaryPushed, primaryPrUrl, peerPullRequests } = await pushMultiRepoLegs(
-      legs,
-      job,
-      logger,
-      opts,
-      root,
-      prTemplate,
-    )
-
-    const anyWork = primaryPushed || peerPullRequests.length > 0
-    if (!anyWork) {
-      // Nothing changed in ANY repo. For the implementer this is a failure (as in the
-      // single-repo path); a caller that tolerates a no-op (never the implementer today)
-      // gets a clean non-event.
-      if (job.noChangesIsError === false) {
-        return {
-          pushed: false,
-          branch: primaryWorkBranch,
-          summary,
-          stats,
-          ...(usage ? { usage } : {}),
-          ...(callMetrics ? { callMetrics } : {}),
-          ...(effortReport ? { effortReport } : {}),
-        }
-      }
-      return {
-        pushed: false,
-        branch: primaryWorkBranch,
-        summary,
-        stats,
-        error: noChangesReason(
-          'the agent produced no file changes in any repository',
-          stats,
-          stderrTail,
-        ),
-        failureCause: 'no-changes',
-        ...(usage ? { usage } : {}),
-        ...(callMetrics ? { callMetrics } : {}),
-        ...(effortReport ? { effortReport } : {}),
-      }
-    }
-    logger.info('multi-repo: complete', {
-      primaryPushed,
-      primaryPrUrl: primaryPrUrl ?? null,
-      peers: peerPullRequests.length,
-    })
-    return {
-      pushed: primaryPushed,
-      ...(primaryPrUrl ? { prUrl: primaryPrUrl } : {}),
-      branch: primaryWorkBranch,
-      ...(peerPullRequests.length ? { peerPullRequests } : {}),
-      summary,
-      stats,
-      ...(usage ? { usage } : {}),
-      ...(callMetrics ? { callMetrics } : {}),
-      ...(effortReport ? { effortReport } : {}),
-    }
-  })
-}
-
-/**
- * Clone phase for {@link runMultiRepoCoding}: every repo into its sibling dir under the workspace
- * root. Resume an existing remote work branch (an evicted retry) rather than branching off base
- * again, then fetch the primary repo's reference branches. Mutates each leg's `dir`/`resumed`/
- * `baseSha` in place. Extracted so the multi-repo body stays small.
- */
-async function prepareMultiRepoCheckouts(
-  root: string,
-  legs: RepoLeg[],
-  job: AgentJob,
-  logger: Logger,
-  opts: RunOptions,
-): Promise<void> {
-  const { signal } = opts
-  opts.onPhase?.('clone')
-  for (const leg of legs) {
-    const dir = join(root, leg.dirName)
-    await mkdir(dir, { recursive: true })
-    // A read-only reference leg: clone its base branch for the agent to read, and stop there —
-    // no work branch, no resume, no base-refresh. It is skipped in the push phase, so it can
-    // never be written to. (Kept in the loop so it lands in the same workspace root as siblings.)
-    if (leg.readOnly) {
-      logger.info('multi-repo: cloning read-only reference', {
-        repo: leg.dirName,
-        cloneBranch: leg.cloneBranch,
-      })
-      await cloneRepo({
-        repo: { ...leg.repo, baseBranch: leg.cloneBranch },
-        ghToken: leg.ghToken,
-        dir,
-        signal,
-      })
-      leg.dir = dir
-      continue
-    }
-    leg.resumed = await remoteBranchExists(leg.repo.cloneUrl, leg.workBranch, leg.ghToken, signal)
-    if (leg.resumed) {
-      logger.info('multi-repo: resuming existing branch', {
-        repo: leg.dirName,
-        branch: leg.workBranch,
-      })
-      await cloneExistingBranch({
-        cloneUrl: leg.repo.cloneUrl,
-        branch: leg.workBranch,
-        ghToken: leg.ghToken,
-        dir,
-        signal,
-      })
-    } else {
-      logger.info('multi-repo: cloning', { repo: leg.dirName, cloneBranch: leg.cloneBranch })
-      await cloneRepo({
-        repo: { ...leg.repo, baseBranch: leg.cloneBranch },
-        ghToken: leg.ghToken,
-        dir,
-        signal,
-      })
-      await createBranch(dir, leg.workBranch, signal)
-    }
-    leg.dir = dir
-    // Exclude the agent-authored PR-description sentinel locally (as the single-repo path does)
-    // so the agent's own `git add` can never stage the briefing into the PR it describes.
-    await excludeFromGit(dir, PR_DESCRIPTION_FILE, signal)
-    // The branch tip before the agent runs. Captured BEFORE the resume base refresh below so
-    // that refresh's merge commit counts as advancement and is pushed (as in the single-repo
-    // path). A fresh leg produced work iff its branch advances past this; a resumed leg already
-    // carries prior work.
-    leg.baseSha = await headCommit(dir, signal)
-    // A resumed branch was cut from an OLDER base; merge the latest base in when the two merge
-    // cleanly so the agent works against current base and the peer/own PRs stay current. On a
-    // conflict this is a best-effort no-op (the merge gate handles a conflicting PR downstream),
-    // mirroring the single-repo {@link runCodingAgent} resume refresh.
-    if (leg.resumed) {
-      const refreshed = await refreshFromBaseIfClean(
-        dir,
-        leg.cloneBranch,
-        leg.ghToken,
-        signal,
-      ).catch(() => false)
-      if (!refreshed) {
-        logger.info('multi-repo: resume base refresh skipped (conflict or error)', {
-          repo: leg.dirName,
-          base: leg.cloneBranch,
-        })
-      }
-    }
-  }
-
-  // Reference branches attach to the PRIMARY repo, so fetch them into the primary sibling
-  // checkout's `origin/<b>` refs (best-effort per branch). The backend's reference-branches
-  // prompt section names the primary repo's directory to run the read commands in.
-  if (job.referenceBranches?.length) {
-    const primaryLeg = legs.find((l) => l.primary)
-    if (primaryLeg?.dir) {
-      const fetched = await fetchReferenceBranches({
-        dir: primaryLeg.dir,
-        branches: job.referenceBranches,
-        ghToken: primaryLeg.ghToken,
-        signal,
-        onSkip: (branch, reason) =>
-          logger.warn('multi-repo: reference branch fetch skipped', { branch, reason }),
-      })
-      logger.info('multi-repo: fetched reference branches', {
-        requested: job.referenceBranches.length,
-        fetched: fetched.length,
-      })
-    }
-  }
-}
-
-/**
- * Push phase for {@link runMultiRepoCoding}: commit forgotten tracked edits, then push + open a PR
- * for each repo the run actually changed (a repo the agent left untouched is skipped — no branch,
- * no PR; a read-only reference leg is never committed or pushed). Extracted so the multi-repo body
- * stays small; returns the primary's push/PR state plus the peer PRs.
- */
-async function pushMultiRepoLegs(
-  legs: RepoLeg[],
-  job: AgentJob,
-  logger: Logger,
-  opts: RunOptions,
-  /** The workspace root the agent ran in — the fallback probe for the primary's briefing. */
-  root: string,
-  /** Which legs' briefings are filled templates — see the `titleFromHeading` read below. */
-  prTemplate: PrTemplateResolution,
-): Promise<{
-  primaryPushed: boolean
-  primaryPrUrl: string | undefined
-  peerPullRequests: NonNullable<AgentResult['peerPullRequests']>
-}> {
-  const { signal } = opts
-  opts.onPhase?.('push')
-  let primaryPushed = false
-  let primaryPrUrl: string | undefined
-  const peerPullRequests: NonNullable<AgentResult['peerPullRequests']> = []
-  for (const leg of legs) {
-    // A read-only reference leg is never committed or pushed — the third layer of the read-only
-    // guarantee (the spec carries no branch/PR, and the clone phase gave it no work branch).
-    if (leg.readOnly) continue
-    // Lift (and remove) the agent-authored PR description for THIS repo's PR before anything
-    // else touches the checkout — each sibling checkout carries its own briefing for its own PR.
-    // The agent's cwd here is the WORKSPACE ROOT rather than any one checkout, so an agent that
-    // read the prompt loosely may well have written a single briefing there instead. Fall back
-    // to it for the PRIMARY leg only: at the root there is nothing to say which repo it
-    // describes, and the primary is the one the run is actually about.
-    //
-    // Per-leg `titleFromHeading`: only a leg whose OWN repo ships a template has repo-authored
-    // headings in its sentinel, and the legs of a workspace need not agree about that — so this
-    // is keyed on the leg, never on whether the run found any template at all.
-    const readOptions = { titleFromHeading: !prTemplate.templated.has(leg.dir) }
-    const agentPrDescription =
-      (await readPrDescription(leg.dir, readOptions)) ??
-      (leg.primary ? await readPrDescription(root, readOptions) : undefined)
-    await commitTrackedEdits(leg.dir, job.commitMessage ?? leg.pr?.title ?? 'Agent changes', signal)
-    const advanced = await branchHasCommitsSince(leg.dir, leg.baseSha, signal)
-    let hasWork = advanced || leg.resumed
-    if (leg.resumed && !advanced) {
-      const ahead = await branchAheadOfBase(leg.dir, leg.repo.baseBranch, leg.ghToken, signal)
-      if (ahead === false) hasWork = false
-    }
-    const leftover = await listUntrackedFiles(leg.dir, signal)
-    if (leftover.length > 0) {
-      logger.warn('multi-repo: uncommitted new files left behind (not pushed)', {
-        repo: leg.dirName,
-        count: leftover.length,
-        files: leftover.slice(0, 20),
-      })
-    }
-    if (!hasWork) {
-      logger.info('multi-repo: no changes for repo', { repo: leg.dirName })
-      continue
-    }
-    await pushBranch(leg.dir, leg.workBranch, leg.ghToken, signal)
-    let prUrl: string | null = null
-    if (leg.pr) {
-      prUrl = await openPullRequest({
-        owner: leg.repo.owner,
-        name: leg.repo.name,
-        ghToken: leg.ghToken,
-        head: leg.workBranch,
-        base: leg.repo.baseBranch,
-        pr: applyPrDescription(leg.pr, agentPrDescription),
-        // See the single-repo call site: refresh a resumed leg's already-open PR, but only
-        // when the text is the agent's own briefing rather than the dispatch-time fallback.
-        ...(agentPrDescription ? { refreshExisting: true } : {}),
-        apiBase: job.githubApiBase,
-        cloneUrl: leg.repo.cloneUrl,
-        ...(leg.repo.provider ? { provider: leg.repo.provider } : {}),
-        signal,
-      })
-    }
-    if (leg.primary) {
-      primaryPushed = true
-      if (prUrl) primaryPrUrl = prUrl
-    } else if (prUrl) {
-      peerPullRequests.push({
-        repo: `${leg.repo.owner}/${leg.repo.name}`,
-        ...(leg.frameId ? { frameId: leg.frameId } : {}),
-        prUrl,
-        branch: leg.workBranch,
-      })
-    }
-  }
-  return { primaryPushed, primaryPrUrl, peerPullRequests }
-}
-
 /**
  * The "no changes" reason both coding agents report: a caller-supplied lead phrase
  * plus the shared "never acted" cause and a credential-scrubbed tail of Pi's stderr.