@cat-factory/executor-harness 1.34.4 → 1.34.10

package/src/coding-agent.ts

@@ -1,6 +1,6 @@
 import { mkdir } from 'node:fs/promises'
 import { join } from 'node:path'
-import type { HarnessAuthFields, RepoSpec } from './job.js'
+import type { AgentJob, AgentResult, HarnessAuthFields, PeerRepoSpec, RepoSpec } from './job.js'
 import {
   branchAheadOfBase,
   branchHasCommitsSince,
@@ -11,6 +11,7 @@ import {
   excludeFromGit,
   headCommit,
   listUntrackedFiles,
+  openPullRequest,
   prepareExistingCheckout,
   pushBranch,
   refreshFromBaseIfClean,
@@ -23,6 +24,7 @@ import {
   agentNeverActed,
   agentOutputTail,
   runAgentInWorkspace,
+  withWorkspace,
 } from './pi-workspace.js'
 import type { ProgressGuardLimits } from './pi.js'
 import type { RunOptions } from './runner.js'
@@ -399,6 +401,292 @@ export async function runCodingAgent(
   )
 }
 
+/** Sanitise an owner/name into a safe single path segment for a sibling checkout directory. */
+export function safeDirSegment(value: string): string {
+  return value.replace(/[^A-Za-z0-9._-]/g, '-') || '_'
+}
+
+/**
+ * A sibling-directory allocator for a multi-repo run: returns the checkout directory name for a
+ * repo under the workspace root. Deterministic (`owner__name`) and collision-free by construction
+ * — the checkout set is deduped by `owner/name` upstream and GitHub owners contain no `_`, so the
+ * `owner__name` join is unique per repo without a stateful collision dance. Kept as a factory so
+ * the coding + read-only explore fan-outs share ONE scheme, and it MUST stay byte-identical to the
+ * backend's `siblingCheckoutDir` / `renderMultiRepoWorkspaceSection` in `@cat-factory/server`
+ * (jobBody.ts), which names this exact directory in the agent's prompt — the two are computed
+ * independently, so a divergent rule would point the agent at a directory that does not exist.
+ */
+export function makeDirClaimer(): (repo: Pick<RepoSpec, 'name' | 'owner'>) => string {
+  return (repo) => `${safeDirSegment(repo.owner)}__${safeDirSegment(repo.name)}`
+}
+
+/** 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
+  /** 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 { signal } = opts
+  const logger = (opts.log ?? log).child({ kind: 'multi-repo', jobId: job.jobId })
+  const peers: PeerRepoSpec[] = job.peerRepos ?? []
+  const primaryWorkBranch = job.pushBranch ?? job.newBranch ?? job.branch
+
+  // Assign the sibling directory per repo via the shared deterministic allocator (`owner__name`,
+  // 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,
+      }),
+    ),
+  ]
+
+  return withWorkspace('multi', async (root) => {
+    // Clone phase: 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.
+    opts.onPhase?.('clone')
+    for (const leg of legs) {
+      const dir = join(root, leg.dirName)
+      await mkdir(dir, { recursive: true })
+      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
+      // 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,
+          })
+        }
+      }
+    }
+
+    // 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 } = await runAgentInWorkspace(
+      {
+        dir: root,
+        systemPrompt: job.systemPrompt,
+        userPrompt: job.userPrompt,
+        model: job.model,
+        harness: job.harness,
+        subscriptionToken: job.subscriptionToken,
+        subscriptionBaseUrl: job.subscriptionBaseUrl,
+        ambientAuth: job.ambientAuth,
+        proxyBaseUrl: job.proxyBaseUrl,
+        sessionToken: job.sessionToken,
+        webToolsGuidance: job.webToolsGuidance,
+        webSearchProxy: job.webSearch,
+        guardLimits: job.guardLimits,
+        ...(job.contextFiles ? { contextFiles: job.contextFiles } : {}),
+        multiRepo: true,
+      },
+      opts,
+    )
+
+    // Push phase: 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).
+    opts.onPhase?.('push')
+    let primaryPushed = false
+    let primaryPrUrl: string | undefined
+    const peerPullRequests: NonNullable<AgentResult['peerPullRequests']> = []
+    for (const leg of legs) {
+      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: leg.pr,
+          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,
+        })
+      }
+    }
+
+    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 } : {}),
+        }
+      }
+      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 } : {}),
+      }
+    }
+    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 } : {}),
+    }
+  })
+}
+
 /**
  * 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.

package/src/job.ts

@@ -61,6 +61,29 @@ export interface PrSpec {
   body: string
 }
 
+/**
+ * A connected service's repo to check out as a SIBLING alongside the primary during a
+ * multi-repo coding run (service-connections phase 3). The agent clones every peer repo
+ * into a sibling directory under the workspace root, makes the coherent cross-service
+ * change, and the harness opens ONE PR per peer repo it actually changed. The clone URL is
+ * host-allowlisted exactly like the primary `repo.cloneUrl`.
+ */
+export interface PeerRepoSpec {
+  repo: RepoSpec
+  /** The involved service frame this repo resolved from, echoed back on the peer PR. */
+  frameId?: string
+  /**
+   * The work branch to create off the peer's base and push (the shared `cat-factory/<block>`).
+   * Present for a COING fan-out (coder / ci-fixer). Absent for a READ-ONLY explore fan-out
+   * (the bug-investigator), which only clones the peer to read it and never pushes.
+   */
+  newBranch?: string
+  /** Open a PR/MR in this peer when set AND the run changed the peer (skipped for a clean repo). */
+  pr?: PrSpec
+  /** Per-repo GitHub token; defaults to the job's `ghToken` (one installation per workspace today). */
+  ghToken?: string
+}
+
 function str(value: unknown, path: string): string {
   if (typeof value !== 'string' || value.length === 0) {
     throw new Error(`Invalid job: '${path}' must be a non-empty string`)
@@ -179,6 +202,38 @@ function parseRepoSpec(repo: Record<string, unknown>): RepoSpec {
   return spec
 }
 
+/**
+ * Parse the optional multi-repo peer list (service-connections phase 3). Each entry carries a
+ * full {@link RepoSpec} (validated + sanitised like the primary), the work branch to push, and
+ * an optional PR + per-repo token. A malformed list throws; an absent one yields `[]`.
+ */
+function parsePeerRepos(value: unknown): PeerRepoSpec[] {
+  if (value === undefined || value === null) return []
+  if (!Array.isArray(value)) throw new Error("Invalid job: 'peerRepos' must be an array")
+  return value.map((entry, i) => {
+    if (typeof entry !== 'object' || entry === null) {
+      throw new Error(`Invalid job: 'peerRepos[${i}]' must be an object`)
+    }
+    const e = entry as Record<string, unknown>
+    const spec: PeerRepoSpec = {
+      repo: parseRepoSpec((e.repo ?? {}) as Record<string, unknown>),
+    }
+    // `newBranch` is required for a coding fan-out (it pushes to it) but ABSENT for a
+    // read-only explore fan-out (bug-investigator) — validate it only when present.
+    if (e.newBranch !== undefined) spec.newBranch = str(e.newBranch, `peerRepos[${i}].newBranch`)
+    if (typeof e.frameId === 'string' && e.frameId) spec.frameId = e.frameId
+    if (typeof e.ghToken === 'string' && e.ghToken) spec.ghToken = e.ghToken
+    if (typeof e.pr === 'object' && e.pr !== null) {
+      const p = e.pr as Record<string, unknown>
+      spec.pr = {
+        title: str(p.title, `peerRepos[${i}].pr.title`),
+        body: typeof p.body === 'string' ? p.body : '',
+      }
+    }
+    return spec
+  })
+}
+
 /** Parse the optional `repo.provider` discriminator (defaults to undefined ⇒ host inference). */
 function parseVcsProvider(value: unknown): 'github' | 'gitlab' | undefined {
   if (value === undefined || value === null) return undefined
@@ -529,6 +584,13 @@ export interface AgentJob extends HarnessAuthFields {
   commitMessage?: string
   /** Coding mode: open this PR when the run pushed changes. Absent ⇒ push only, no PR. */
   pr?: PrSpec
+  /**
+   * Coding mode (implementer): connected services' repos to clone as SIBLINGS for a MULTI-REPO
+   * change (service-connections phase 3). When present, the agent works with its cwd at the
+   * workspace ROOT (all repos are sibling checkouts under it), and the harness opens one PR per
+   * peer repo it actually changed — in addition to the primary. Absent ⇒ single-repo run.
+   */
+  peerRepos?: PeerRepoSpec[]
   /**
    * Coding mode: whether a no-op run (nothing changed) is a failure. The implementer
    * fails on a no-op; the in-place fixers (ci-fix / fix-tests) treat it as a non-fatal
@@ -617,6 +679,13 @@ export interface AgentResult {
   pushed?: boolean
   prUrl?: string
   branch?: string
+  /**
+   * Coding mode (multi-repo): the PRs opened in the connected services' PEER repos, one per
+   * repo the run actually changed (service-connections phase 3). Beside the own-service
+   * `prUrl`/`branch`; the backend lifts these onto the block's `peerPullRequests`. Absent for
+   * a single-repo run.
+   */
+  peerPullRequests?: { repo: string; frameId?: string; prUrl: string; branch: string }[]
   /** Coding mode (bootstrap): the default branch the bootstrapped contents were pushed to. */
   defaultBranch?: string
   error?: string
@@ -856,6 +925,7 @@ export function parseAgentJob(input: unknown): AgentJob {
         })()
       : undefined
   const infra = parseAgentInfraSpec(o.infra)
+  const peerRepos = parsePeerRepos(o.peerRepos)
   const bootstrap = parseAgentBootstrapSpec(o.bootstrap)
   const contextFiles = parseContextFiles(o.contextFiles)
   const packageRegistries = parsePackageRegistries(o.packageRegistries)
@@ -886,6 +956,7 @@ export function parseAgentJob(input: unknown): AgentJob {
       ? { commitMessage: o.commitMessage }
       : {}),
     ...(pr ? { pr } : {}),
+    ...(peerRepos.length ? { peerRepos } : {}),
     ...(o.noChangesIsError === false ? { noChangesIsError: false } : {}),
     ...(o.persistentCheckout === true ? { persistentCheckout: true } : {}),
     ...(o.streamFollowUps === true ? { streamFollowUps: true } : {}),
@@ -896,5 +967,11 @@ export function parseAgentJob(input: unknown): AgentJob {
   // Bootstrap pushes the result to a SEPARATE target repo, so its clone URL must be an
   // allowed GitHub host too (the installation token is sent to it on the force-push).
   if (job.bootstrap) assertAllowedHost(job.bootstrap.target.cloneUrl, 'bootstrap.target.cloneUrl')
+  // Each peer repo's clone URL receives the installation token on clone/push, so it must be
+  // an allowed GitHub host too — a body-supplied peer pointing at an attacker host would
+  // exfiltrate the token exactly like a rogue primary clone URL.
+  for (const [i, peer] of (job.peerRepos ?? []).entries()) {
+    assertAllowedHost(peer.repo.cloneUrl, `peerRepos[${i}].repo.cloneUrl`)
+  }
   return job
 }

package/src/pi-workspace.ts

@@ -209,6 +209,12 @@ export interface AgentRunSpec {
    * is present directly in the container env (the self-hosted runner-pool path).
    */
   webSearchProxy?: boolean
+  /**
+   * Multi-repo run (service-connections phase 3): the cwd (`dir`) is the WORKSPACE ROOT with
+   * every involved repo checked out as a sibling under it. Suppresses the single-repo monorepo
+   * note in AGENTS.md and adds the multi-repo mechanics note instead. Absent ⇒ single-repo.
+   */
+  multiRepo?: boolean
 }
 
 /**
@@ -274,6 +280,7 @@ export async function runAgentInWorkspace(
     guidance: spec.webToolsGuidance,
     serviceDirectory: spec.serviceDirectory,
     contextFiles,
+    ...(spec.multiRepo ? { multiRepo: true } : {}),
   })
   await writePiModelsConfig({ model: spec.model, proxyBaseUrl })
   const { signal, onActivity, onProgress, onSpan } = opts

package/src/pi.ts

@@ -141,6 +141,7 @@ export async function writeAgentsContext(
     guidance?: string
     serviceDirectory?: string
     contextFiles?: ContextFileInfo[]
+    multiRepo?: boolean
   } = {},
 ): Promise<void> {
   const dir = join(homedir(), '.pi', 'agent')
@@ -152,18 +153,44 @@ export async function writeAgentsContext(
   const webTools = opts.webSearch ? (opts.guidance ?? WEB_TOOLS_GUIDANCE) : ''
   // Tell the agent it's in a monorepo and which subtree is its service, so it scopes
   // its work (and its build/test commands) there. Only present when the dispatcher
-  // resolved a monorepo service directory; the agent's cwd already points at it.
-  const monorepo = opts.serviceDirectory ? monorepoGuidance(opts.serviceDirectory) : ''
+  // resolved a monorepo service directory; the agent's cwd already points at it. A
+  // MULTI-REPO run runs at the workspace root (cwd spans sibling checkouts), so the
+  // monorepo note is suppressed there — the multi-repo mechanics note replaces it.
+  const monorepo =
+    opts.serviceDirectory && !opts.multiRepo ? monorepoGuidance(opts.serviceDirectory) : ''
+  // Multi-repo mechanics note (service-connections phase 3): the concrete repo→role mapping
+  // is in the backend-composed system prompt above; this explains the shared MECHANICS (cwd
+  // is the workspace root, repos are sibling checkouts, one PR per dirty repo).
+  const multiRepo = opts.multiRepo ? MULTI_REPO_GUIDANCE : ''
   // Point the agent at any linked context the backend materialised into the checkout
   // (requirements / RFCs / PRDs / tracker issues) so it reads them on demand.
   const context = contextGuidance(opts.contextFiles ?? [])
   await writeFile(
     join(dir, 'AGENTS.md'),
-    `${systemPrompt}${BLUEPRINT_GUIDANCE}${SPEC_GUIDANCE}${TODO_GUIDANCE}${monorepo}${webTools}${context}`,
+    `${systemPrompt}${BLUEPRINT_GUIDANCE}${SPEC_GUIDANCE}${TODO_GUIDANCE}${monorepo}${multiRepo}${webTools}${context}`,
     'utf8',
   )
 }
 
+/** The MULTI-REPO mechanics note appended to AGENTS.md when a run spans sibling checkouts. */
+const MULTI_REPO_GUIDANCE = `
+
+## Multi-repo workspace (work across sibling checkouts)
+
+This task spans MORE THAN ONE repository. Your working directory is the WORKSPACE ROOT, and
+each involved repository is checked out as a sibling directory directly under it. The workspace
+root itself is NOT a git repository — run git INSIDE each repository's directory. The system
+prompt above lists which repository is which and each one's role. Make the cross-service
+change coherently across every repository the task requires — a provider's API and its
+consumer's call site belong in the SAME piece of work. Run each repository's own build/test
+commands inside that repository's directory.
+
+Commit your own work inside each repository you change (\`cd\` into it, stage the files that
+belong — INCLUDING any new files you added — and commit). The platform will NOT add untracked
+files for you, so anything you leave uncommitted and untracked is lost. Each repository you
+change is opened as a SEPARATE pull request; leave a repository untouched if the task does not
+require changing it.`
+
 /** Directory in the checkout where linked-context files are materialised (see CONTEXT_DIR in agents). */
 export const CONTEXT_DIR = '.cat-context'