@cat-factory/orchestration 0.35.1 → 0.36.1

package/dist/modules/execution/ExecutionService.js

@@ -9,7 +9,7 @@ import { assertFound, ConflictError, getErrorMessage, isModelUsable, NotFoundErr
 import { DEFAULT_MERGE_PRESET } from '@cat-factory/kernel';
 import { CONFLICTS_AGENT_KIND, MERGER_AGENT_KIND, REQUIREMENTS_REVIEW_AGENT_KIND, CLARITY_REVIEW_AGENT_KIND, REQUIREMENTS_BRAINSTORM_AGENT_KIND, ARCHITECTURE_BRAINSTORM_AGENT_KIND, BUG_INVESTIGATOR_AGENT_KIND, TRACKER_AGENT_KIND, ANALYSIS_AGENT_KIND, TESTER_AGENT_KIND, UI_TESTER_AGENT_KIND, isTesterKind, HUMAN_TEST_AGENT_KIND, VISUAL_CONFIRM_AGENT_KIND, HUMAN_REVIEW_AGENT_KIND, BLUEPRINTS_AGENT_KIND, SPEC_WRITER_AGENT_KIND, } from './ci.logic.js';
 import { DEFAULT_FOLLOW_UP_MAX_LOOPS, FOLLOW_UP_PRODUCER_KIND, followUpsToSendBack, hasPendingFollowUps, renderFollowUpRework, shouldLoopCoder, } from './followUp.logic.js';
-import { AgentContextBuilder } from './AgentContextBuilder.js';
+import { AgentContextBuilder, } from './AgentContextBuilder.js';
 import { CompanionController } from './CompanionController.js';
 import { inferTechnicalLabel } from './technical.logic.js';
 import { MergeResolver } from './MergeResolver.js';
@@ -17,9 +17,10 @@ import { ReviewGateController } from './ReviewGateController.js';
 import { TesterController } from './TesterController.js';
 import { HumanTestController } from './HumanTestController.js';
 import { VisualConfirmationController } from './VisualConfirmationController.js';
+import { FALLTHROUGH_STEP_HANDLER_ORDER, } from './step-handler-registry.js';
 import { getProvider, recordGateAttempt, registeredGateFactories, registeredStepResolverFactories, requireProvider, } from '@cat-factory/kernel';
 import { isAsyncAgentExecutor } from '@cat-factory/kernel';
-import { isDeployStep } from '@cat-factory/integrations';
+import { isDeployStep, DEPLOYER_AGENT_KIND } from '@cat-factory/integrations';
 import { dependenciesMet, descendantIds, serviceOf, unmetDependencies, } from '../board/board.logic.js';
 import { requireWorkspace } from '@cat-factory/kernel';
 import { planResumedSteps, planRestartFromStep } from './retry.logic.js';
@@ -147,7 +148,12 @@ export class ExecutionService {
      * {@link stepResolverFor} and {@link StepCompletionResolver}.
      */
     stepResolverCache;
-    constructor({ workspaceRepository, blockRepository, pipelineRepository, executionRepository, accountRepository, idGenerator, clock, agentExecutor, workRunner, executionEventPublisher, boardService, spendService, documentRepository, taskRepository, requirementReviewRepository, requirementReviewService, kaizenScheduler, clarityReviewRepository, clarityReviewService, brainstormServices, brainstormSessionRepository, fragmentResolver, environmentProvisioning, environmentTeardown, branchUpdater, blueprintReconciler, notificationService, binaryArtifactStore, workspaceSettingsService, llmObservability, pullRequestMerger, mergePresetRepository, ticketTrackerProvider, issueWriteback, subscriptionActivationRepository, resolveWorkspaceModelDefault, resolveProviderCapabilities, localTestInfraSupported, resolveRunRepoContext, resolveTesterFallbackDefault, resolveRequireEnvironmentProvider, assertAgentBackendConfigured, runInitiatorScope, }) {
+    /**
+     * Lazily-built, order-sorted per-step-kind handler list. See {@link dispatchStepHandler}
+     * and {@link StepHandler}. Engine-internal (no public registration seam).
+     */
+    stepHandlerCache;
+    constructor({ workspaceRepository, blockRepository, pipelineRepository, executionRepository, accountRepository, idGenerator, clock, agentExecutor, workRunner, executionEventPublisher, boardService, spendService, documentRepository, documentUrlResolver, taskRepository, requirementReviewRepository, requirementReviewService, kaizenScheduler, clarityReviewRepository, clarityReviewService, brainstormServices, brainstormSessionRepository, fragmentResolver, environmentProvisioning, environmentTeardown, branchUpdater, blueprintReconciler, notificationService, binaryArtifactStore, workspaceSettingsService, llmObservability, pullRequestMerger, mergePresetRepository, ticketTrackerProvider, issueWriteback, subscriptionActivationRepository, resolveWorkspaceModelDefault, resolveProviderCapabilities, localTestInfraSupported, resolveRunRepoContext, resolveTesterFallbackDefault, resolveRequireEnvironmentProvider, assertAgentBackendConfigured, runInitiatorScope, }) {
         this.runInitiatorScope = runInitiatorScope ?? ((_initiatedBy, fn) => fn());
         this.workspaceRepository = workspaceRepository;
         this.blockRepository = blockRepository;
@@ -173,6 +179,7 @@ export class ExecutionService {
             blockRepository,
             accountRepository,
             documents: documentRepository,
+            documentUrlResolver,
             tasks: taskRepository,
             requirementReviews: requirementReviewRepository,
             clarityReviews: clarityReviewRepository,
@@ -810,21 +817,29 @@ export class ExecutionService {
         if (step.gating?.enabled && !shouldRunGatedStep(block.estimate, step.gating)) {
             return this.skipGatedStep(workspaceId, instance, step, isFinalStep);
         }
-        // A `deployer` step provisions an ephemeral environment deterministically via
-        // the provider — no LLM, no token usage — when the integration is wired.
-        // Otherwise it falls through to the normal agent path.
-        if (this.environmentProvisioning && isDeployStep(step.agentKind)) {
-            const result = await this.runDeployer(workspaceId, instance, block, options);
-            return this.recordStepResult(workspaceId, instance, step, isFinalStep, result);
-        }
-        // A `tracker` step files a GitHub issue / Jira ticket from the preceding
-        // `analysis` output (the tech-debt pipeline) — no LLM of its own. It is a
-        // pass-through when no tracker provider is wired or none is configured for the
-        // workspace. See {@link runTracker}.
-        if (step.agentKind === TRACKER_AGENT_KIND) {
-            const result = await this.runTracker(workspaceId, instance, block);
-            return this.recordStepResult(workspaceId, instance, step, isFinalStep, result);
-        }
+        // The fixed run-lifecycle preamble is done; hand the per-kind work to the
+        // engine-internal StepHandler registry (the first handler whose `canHandle` claims
+        // this step). See {@link dispatchStepHandler} / {@link runStepBody}.
+        return this.dispatchStepHandler({
+            workspaceId,
+            instance,
+            step,
+            block,
+            isFinalStep,
+            options,
+        });
+    }
+    /**
+     * The per-step-kind body run by the StepHandler registry once {@link stepInstance}'s
+     * preamble has completed. Phase 0 of the ExecutionService split: a single fallthrough
+     * handler delegates the ENTIRE body here unchanged (so dispatch is wired with zero
+     * behaviour change); later phases lift each branch below into its own handler and shrink
+     * this method until only the generic container/inline-agent tail remains.
+     */
+    async runStepBody(ctx) {
+        const { workspaceId, instance, step, block, isFinalStep, options } = ctx;
+        // (The `deployer` and `tracker` steps are handled by their own StepHandlers — see
+        // {@link buildStepHandlerRegistry} — so they no longer branch here.)
         // A `requirements-review` step runs the inline reviewer and parks for the dedicated
         // review window, driving the iterative answer → incorporate → re-review loop. NOT a
         // container/prose agent. Pass-through when the reviewer isn't wired. The clarity gate
@@ -2055,6 +2070,65 @@ export class ExecutionService {
      * startup import side effect (see {@link gateFor} for the same caching caveat). See
      * {@link StepCompletionResolver}.
      */
+    /**
+     * Dispatch a step (whose preamble already ran in {@link stepInstance}) to the first
+     * registered {@link StepHandler} whose `canHandle` claims it, ordered by `order`. The
+     * fallthrough handler claims everything, so this always resolves to a handler.
+     */
+    dispatchStepHandler(ctx) {
+        if (!this.stepHandlerCache)
+            this.stepHandlerCache = this.buildStepHandlerRegistry();
+        const handler = this.stepHandlerCache.find((h) => h.canHandle(ctx));
+        // The fallthrough handler's `canHandle` is unconditional, so this is unreachable; it
+        // exists only to satisfy the type and to fail loudly if that invariant is ever broken.
+        if (!handler)
+            throw new Error(`No step handler for agentKind "${ctx.step.agentKind}"`);
+        return handler.handle(ctx);
+    }
+    /**
+     * Build the order-sorted per-step-kind handler list, mirroring
+     * {@link buildStepResolverRegistry} (built-ins constructed inline, closing over `this`).
+     * Engine-internal: there is no public `registerStepHandler` seam. Phase 0 registers only
+     * the generic fallthrough; later phases prepend more-specific handlers with lower `order`.
+     */
+    buildStepHandlerRegistry() {
+        const handlers = [
+            // A `deployer` step provisions an ephemeral environment deterministically via the
+            // provider — no LLM, no token usage — when the integration is wired. Unwired, its
+            // `canHandle` is false so the step falls through to the generic agent path.
+            {
+                kind: DEPLOYER_AGENT_KIND,
+                order: 100,
+                canHandle: ({ step }) => !!this.environmentProvisioning && isDeployStep(step.agentKind),
+                handle: async ({ workspaceId, instance, step, block, isFinalStep, options }) => {
+                    const result = await this.runDeployer(workspaceId, instance, block, options);
+                    return this.recordStepResult(workspaceId, instance, step, isFinalStep, result);
+                },
+            },
+            // A `tracker` step files a GitHub issue / Jira ticket from the preceding `analysis`
+            // output (the tech-debt pipeline) — no LLM of its own. It is a pass-through when no
+            // tracker provider is wired or none is configured for the workspace (handled inside
+            // {@link runTracker}, which still records a result), so it always claims the step.
+            {
+                kind: TRACKER_AGENT_KIND,
+                order: 110,
+                canHandle: ({ step }) => step.agentKind === TRACKER_AGENT_KIND,
+                handle: async ({ workspaceId, instance, step, block, isFinalStep }) => {
+                    const result = await this.runTracker(workspaceId, instance, block);
+                    return this.recordStepResult(workspaceId, instance, step, isFinalStep, result);
+                },
+            },
+            // The generic container/inline-agent fallthrough — claims every step no more-specific
+            // handler did (today's `runStepBody` tail). Highest order so it always runs last.
+            {
+                kind: '*',
+                order: FALLTHROUGH_STEP_HANDLER_ORDER,
+                canHandle: () => true,
+                handle: (ctx) => this.runStepBody(ctx),
+            },
+        ];
+        return handlers.sort((a, b) => a.order - b.order);
+    }
     stepResolverFor(agentKind) {
         if (!this.stepResolverCache)
             this.stepResolverCache = this.buildStepResolverRegistry();