@cat-factory/orchestration 0.110.0 → 0.112.0

package/dist/modules/execution/RunDispatcher.js

@@ -1,4 +1,4 @@
-import { ConflictError, DEFAULT_RISK_POLICY, failureKindFromHarnessCause, getErrorMessage, getErrorReason, getProvider, INITIATIVE_ANALYST_AGENT_KIND, INITIATIVE_COMMITTER_AGENT_KIND, INITIATIVE_PLANNER_AGENT_KIND, isAsyncAgentExecutor, NotFoundError, parseLocalModelId, recordGateAttempt, registeredGateFactories, registeredStepResolverFactories, requireProvider, RunContendedError, sameSubtasks, } from '@cat-factory/kernel';
+import { ConflictError, DEFAULT_RISK_POLICY, failureKindFromHarnessCause, FIXER_AGENT_KIND, getErrorMessage, getErrorReason, getProvider, INITIATIVE_ANALYST_AGENT_KIND, INITIATIVE_COMMITTER_AGENT_KIND, INITIATIVE_PLANNER_AGENT_KIND, isAsyncAgentExecutor, NotFoundError, parseLocalModelId, recordGateAttempt, registeredGateFactories, registeredStepResolverFactories, requireProvider, RunContendedError, sameSubtasks, } from '@cat-factory/kernel';
 import { frameProfile, frontendOriginsForService, parseBlueprintService, parseSpecDoc, resolveAprioriWorkingBranch, } from '@cat-factory/contracts';
 import { blueprintPostOp, commitInitiativeTracker, FORK_PROPOSER_KIND, PR_REVIEWER_KIND, hasTrait, isCompanionKind, isContainerBackedCompanion, INTERVIEW_GATE_TRAIT, moduleSlug, runRepoOps, specPostOp, TASK_ESTIMATOR_AGENT_KIND, } from '@cat-factory/agents';
 import { DEPLOYER_AGENT_KIND, isDeployStep } from '@cat-factory/integrations';
@@ -19,6 +19,7 @@ import { MergeResolver } from './MergeResolver.js';
 import { ReviewGateController } from './ReviewGateController.js';
 import { ForkDecisionController } from './ForkDecisionController.js';
 import { PrReviewController, PR_REVIEW_STEP_KIND } from './PrReviewController.js';
+import { buildPrReviewPost, renderPrReviewFixerFeedback } from './prReview.logic.js';
 import { DEFAULT_FORK_MAX_CHAT_TURNS, forkPhasePending, resolveForkTriState, shouldProposeForkAuto, } from './forkDecision.logic.js';
 import { RunStateMachine } from './RunStateMachine.js';
 import { StepGraph } from './StepGraph.js';
@@ -58,6 +59,19 @@ function parseRepoFromPullUrl(url) {
         return undefined;
     return { owner: match[1], repo: match[2] };
 }
+/**
+ * The PR number a `review` task targets: the explicit `prNumber` field wins, else parse it from
+ * the `prUrl` (`…/pull/42` on GitHub, `…/merge_requests/42` on GitLab). Undefined when neither
+ * yields one — the PR-review `fix`/`post` resolutions then report the PR unresolvable.
+ */
+function reviewPrNumber(block) {
+    const fields = block?.taskTypeFields;
+    if (typeof fields?.prNumber === 'number')
+        return fields.prNumber;
+    const url = fields?.prUrl?.trim();
+    const match = url ? /\/(?:pull|merge_requests)\/(\d+)/.exec(url) : null;
+    return match ? Number(match[1]) : undefined;
+}
 /**
  * The `peerEnvUrls` provision input for the frame about to be provisioned: a comma-joined set of
  * `slug=url` pairs for every target frame whose env is ALREADY ready this run — so a later
@@ -215,7 +229,7 @@ export class RunDispatcher {
      * what the dispatch chain falls through to; all the deterministic / gate / inline-review
      * kinds are claimed earlier by their own handlers (see {@link buildStepHandlerRegistry}).
      */
-    async handleAgentStep(ctx, dispatchKind) {
+    async handleAgentStep(ctx, dispatchKind, augmentContext) {
         const { workspaceId, instance, step, block, isFinalStep, options } = ctx;
         // Async (container) steps don't block: dispatch the job and park. The durable
         // driver polls `pollAgentJob` between sleeps so the run can span far longer
@@ -228,6 +242,10 @@ export class RunDispatcher {
         // job as a HELPER off the coder step (Phase A). The completion still records against the
         // coder step, and the fork-proposal interceptor keys on `step.agentKind` + the fork state.
         const context = await this.contextBuilder.buildContext(workspaceId, instance, step, isFinalStep, block, dispatchKind ? { agentKind: dispatchKind } : undefined);
+        // A caller re-dispatching this step under an overriding kind can fold extra context in
+        // (e.g. the PR-review `fix` resolution points the Fixer at the reviewed PR's head branch and
+        // hands it the selected findings). Runs before pre-ops / dispatch so the job body sees it.
+        augmentContext?.(context);
         // A registered custom kind's PRE-ops run deterministic backend repo work before the
         // agent dispatches (e.g. read a baseline `spec/` shard into the prompt). Gated on the
         // step not having dispatched yet so a Workflows replay (jobId already set) doesn't
@@ -2280,6 +2298,19 @@ export class RunDispatcher {
                 canHandle: ({ step, block }) => forkPhasePending(step, resolveForkTriState(block.agentConfig)),
                 handle: (ctx) => this.handleForkDecisionPhase(ctx),
             },
+            // The PR deep-review RESOLUTION phase (PR 3): after the human resolved a parked review with
+            // `fix` / `post`, `PrReviewController.resolve` re-armed this `pr-reviewer` step and woke the
+            // driver. Claim it by the re-armed status so it re-dispatches as the Fixer (`fixing`) or
+            // posts the selected findings as inline PR comments (`posting`) — never the generic
+            // pr-reviewer clone the fallthrough would run. A `reviewing`/`awaiting_selection`/resolved
+            // step falls through (this handler doesn't claim it). See {@link handlePrReviewResolution}.
+            {
+                kind: 'pr-review-resolution',
+                order: 175,
+                canHandle: ({ step }) => step.agentKind === PR_REVIEW_STEP_KIND &&
+                    (step.prReview?.status === 'fixing' || step.prReview?.status === 'posting'),
+                handle: (ctx) => this.handlePrReviewResolution(ctx),
+            },
             // The generic container/inline-agent step — claims every step no more-specific handler
             // did. Highest order so it always runs last. See {@link handleAgentStep}.
             {
@@ -2903,6 +2934,122 @@ export class RunDispatcher {
         // Dispatch (or re-attach to) the proposer as a helper off this coder step.
         return this.handleAgentStep(ctx, FORK_PROPOSER_KIND);
     }
+    /**
+     * Drive a re-armed PR-review step's RESOLUTION (PR 3). The human resolved a parked review with
+     * `fix` or `post`; {@link PrReviewController.resolve} re-armed this step and woke the driver.
+     * - `fixing`: dispatch the Fixer against the reviewed PR's head branch with the selected
+     *   findings folded in (parks on the job; its completion marks the review `done`).
+     * - `posting`: publish the selected findings as inline PR review comments, then finish the step.
+     */
+    async handlePrReviewResolution(ctx) {
+        const { step } = ctx;
+        if (step.prReview?.status === 'posting')
+            return this.postPrReview(ctx);
+        return this.dispatchPrReviewFixer(ctx);
+    }
+    /**
+     * Dispatch the Fixer for a PR-review `fix` resolution. A `review` task carries no own work
+     * branch — it reviews an EXISTING PR — so resolve the PR's head branch (via the checkout-free
+     * `RepoFiles`) and point the Fixer's clone/push at it: fold a synthetic `pullRequest` + an
+     * apriori WORKING branch into the dispatch context so the shared `container-coding` +
+     * `clone:{branch:'pr'}` fixer body clones + pushes that branch (no new PR), and hand it the
+     * selected findings as a prior output (the same injection point the gate helpers use). Fails
+     * the run loudly when the PR branch can't be resolved (nothing to push to) rather than pushing
+     * blind. On a replay (jobId already set) it re-attaches without re-resolving.
+     */
+    async dispatchPrReviewFixer(ctx) {
+        const { workspaceId, instance, step, block } = ctx;
+        const review = step.prReview;
+        const selected = (review.findings ?? []).filter((f) => review.selectedFindingIds?.includes(f.id));
+        let headRef = null;
+        let prNumber;
+        if (!step.jobId) {
+            prNumber = reviewPrNumber(block);
+            const runRepo = prNumber != null ? await this.resolveRunRepoContext?.(workspaceId, block.id) : null;
+            const repo = runRepo?.repo;
+            headRef =
+                prNumber != null && repo?.pullRequestHeadRef
+                    ? await this.runInitiatorScope(instance.initiatedBy, () => repo.pullRequestHeadRef(prNumber))
+                    : null;
+            if (prNumber == null || !headRef) {
+                return {
+                    kind: 'job_failed',
+                    failureKind: 'preflight',
+                    error: "Can't resolve the reviewed pull request's head branch to push fixes to. The " +
+                        "'fix' resolution needs a same-repo pull request on this service's linked repository " +
+                        '(a cross-repo or fork PR is not yet supported — post the findings as comments instead).',
+                };
+            }
+        }
+        const resolvedHeadRef = headRef;
+        const resolvedPrNumber = prNumber;
+        return this.handleAgentStep(ctx, FIXER_AGENT_KIND, (context) => {
+            if (resolvedHeadRef && resolvedPrNumber != null) {
+                context.block.pullRequest = {
+                    number: resolvedPrNumber,
+                    branch: resolvedHeadRef,
+                    url: review.prUrl ?? '',
+                };
+                // Build inside the PR head branch (probed, never created) so the work-branch machinery
+                // targets it rather than minting a stray `cat-factory/<blockId>` off base.
+                context.aprioriBranches = [{ name: resolvedHeadRef, mode: 'working' }];
+            }
+            context.priorOutputs = [
+                ...context.priorOutputs,
+                { agentKind: FIXER_AGENT_KIND, output: renderPrReviewFixerFeedback(selected) },
+            ];
+        });
+    }
+    /**
+     * Post a PR-review `post` resolution: publish the human-selected findings as a single advisory
+     * (`COMMENT`) inline review on the reviewed PR via the checkout-free `RepoFiles.createReview`,
+     * then finish the step. At-most-once: the `pendingPrReviewPost` marker is consumed (cleared +
+     * persisted) BEFORE the (side-effecting) post so a Workflows retry can't submit it twice. When
+     * no VCS review write is wired (tests / no GitHub) the findings are still recorded and the step
+     * finishes — the review pipeline never reaches this without GitHub in practice.
+     *
+     * If `createReview` itself throws (GitHub rejects the batched review — e.g. a finding anchored
+     * to a line outside the PR diff 422s the WHOLE review — or a transient network/5xx error), the
+     * marker is already consumed, so a driver retry would NOT re-post. Rather than silently
+     * completing the step as `done` with nothing actually posted (the human would believe the
+     * comments landed), fail the step LOUDLY so the failure surfaces on the board — mirroring the
+     * `fix` resolution's loud preflight failure. `post` is a fallback resolution, so a hard failure
+     * is visible and the human can re-run or choose `fix`/`finish` instead.
+     */
+    async postPrReview(ctx) {
+        const { workspaceId, instance, step, block, isFinalStep } = ctx;
+        const review = step.prReview;
+        const selected = (review.findings ?? []).filter((f) => review.selectedFindingIds?.includes(f.id));
+        let posted = false;
+        if (step.pendingPrReviewPost) {
+            step.pendingPrReviewPost = null;
+            await this.runStateMachine.casPersist(workspaceId, instance);
+            const prNumber = reviewPrNumber(block);
+            const runRepo = prNumber != null ? await this.resolveRunRepoContext?.(workspaceId, block.id) : null;
+            const repo = runRepo?.repo;
+            if (prNumber != null && repo?.createReview) {
+                try {
+                    await this.runInitiatorScope(instance.initiatedBy, () => repo.createReview(prNumber, buildPrReviewPost(selected, review.summary)));
+                }
+                catch (error) {
+                    return {
+                        kind: 'job_failed',
+                        failureKind: 'agent',
+                        error: `Failed to post the ${selected.length} selected finding` +
+                            `${selected.length === 1 ? '' : 's'} as a pull-request review: ${getErrorMessage(error)}. ` +
+                            'GitHub rejects a review whose inline comment anchors a line outside the PR diff — ' +
+                            "try the 'fix' resolution, or re-run to post again.",
+                    };
+                }
+                posted = true;
+            }
+        }
+        step.prReview = { ...review, status: 'done' };
+        const output = posted
+            ? `Posted ${selected.length} review comment${selected.length === 1 ? '' : 's'} to the pull request.`
+            : `Recorded ${selected.length} selected finding${selected.length === 1 ? '' : 's'}.`;
+        return this.recordStepResult(workspaceId, instance, step, isFinalStep, { output });
+    }
     /** Read a run's active implementation-fork decision state, or null. */
     getForkDecision(workspaceId, executionId) {
         return this.forkDecisionController.getActive(workspaceId, executionId);