@cat-factory/executor-harness 1.108.0 → 1.110.2

package/dist/multi-repo-coding.js

@@ -0,0 +1,379 @@
+import { mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { makeDirClaimer } from './checkout-dir.js';
+import { branchAheadOfBase, branchHasCommitsSince, cloneExistingBranch, cloneRepo, commitTrackedEdits, createBranch, excludeFromGit, fetchReferenceBranches, headCommit, listUntrackedFiles, pushBranch, refreshFromBaseIfClean, remoteBranchExists, } from './git.js';
+import { openPullRequest } from './vcs-api.js';
+import { applyPrDescription, PR_DESCRIPTION_FILE, readPrDescription } from './pr-description.js';
+import { runAgentInWorkspace, withWorkspace } from './pi-workspace.js';
+import { log } from './logger.js';
+import { prepopulateDependencies, withDependencyNote } from './dependency-install.js';
+import { resolvePrTemplateNote, withPrTemplateNote, } from './pr-template.js';
+import { noChangesReason } from './coding-agent.js';
+/**
+ * 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, opts = {}) {
+    const logger = (opts.log ?? log).child({ kind: 'multi-repo', jobId: job.jobId });
+    const peers = job.peerRepos ?? [];
+    const references = 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 = [
+        {
+            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) => ({
+            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.frameIds?.length ? { frameIds: peer.frameIds } : {}),
+            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) => ({
+            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 } : {}),
+            ...(job.designImages ? { designImages: job.designImages } : {}),
+            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, legs, job, logger, opts) {
+    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, job, logger, opts, 
+/** The workspace root the agent ran in — the fallback probe for the primary's briefing. */
+root, 
+/** Which legs' briefings are filled templates — see the `titleFromHeading` read below. */
+prTemplate) {
+    const { signal } = opts;
+    opts.onPhase?.('push');
+    let primaryPushed = false;
+    let primaryPrUrl;
+    const 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 = 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.frameIds?.length ? { frameIds: leg.frameIds } : {}),
+                prUrl,
+                branch: leg.workBranch,
+            });
+        }
+    }
+    return { primaryPushed, primaryPrUrl, peerPullRequests };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/executor-harness",
-  "version": "1.108.0",
+  "version": "1.110.2",
   "description": "Container payload: a thin TypeScript wrapper that runs the Pi coding agent against a cloned repo and opens a PR. Runs in the Cloudflare Container (and, in local native mode, as a host process); carries no secrets.",
   "repository": {
     "type": "git",
@@ -30,9 +30,9 @@
     "hono": "^4.13.1",
     "typescript": "7.0.2",
     "vitest": "^4.1.10",
-    "@cat-factory/kernel": "0.284.0",
-    "@cat-factory/server": "0.267.0",
-    "@cat-factory/spend": "0.15.63"
+    "@cat-factory/kernel": "0.292.1",
+    "@cat-factory/server": "0.278.1",
+    "@cat-factory/spend": "0.15.80"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",

package/src/agent.ts

@@ -30,7 +30,8 @@ import { inferVcsProvider, openPullRequest } from './vcs-api.js'
 import type { PiRunStats, RunDiagnostics } from './pi-reduction.js'
 import { applyPrDescription } from './pr-description.js'
 import { makeDirClaimer } from './checkout-dir.js'
-import { noChangesReason, runCodingAgent, runMultiRepoCoding } from './coding-agent.js'
+import { noChangesReason, runCodingAgent } from './coding-agent.js'
+import { runMultiRepoCoding } from './multi-repo-coding.js'
 import { validationFailureMessage } from './validation-checks.js'
 import { prepopulateDependencies, withDependencyNote } from './dependency-install.js'
 import { agentCapabilities, mergeEffort } from './agent-shared.js'
@@ -49,6 +50,7 @@ import {
   diagnosticsSuffix,
   resolveStructuredOutput,
 } from './structured-output.js'
+import { extractJsonObject } from './json-reply.js'
 import type { RunOptions } from './runner.js'
 import { log, type Logger } from './logger.js'
 
@@ -262,23 +264,6 @@ async function resolveReplyCustom(
   return { value: resolved.value, diagnostics: resolved.diagnostics }
 }
 
-/** Extract the first JSON object from an agent's final message (tolerating fences/prose). */
-function extractJsonObject(text: string): unknown {
-  const trimmed = text.trim()
-  const fenced = /^```(?:json)?\s*([\s\S]*?)\s*```$/i.exec(trimmed)
-  const body = fenced ? (fenced[1] ?? '') : trimmed
-  try {
-    return JSON.parse(body)
-  } catch {
-    const start = body.indexOf('{')
-    const end = body.lastIndexOf('}')
-    if (start === -1 || end === -1 || end <= start) {
-      throw new Error('agent did not return a JSON object')
-    }
-    return JSON.parse(body.slice(start, end + 1))
-  }
-}
-
 /**
  * The service work directory for a checkout at `dir`: the monorepo service subtree
  * (`repo.serviceDirectory`, created if missing) when the job is service-scoped, else the clone