@cat-factory/orchestration 0.13.0 → 0.15.0

package/dist/modules/execution/ExecutionService.js

@@ -7,13 +7,14 @@ import { reviewableArtifactOutput } from './artifact-review.logic.js';
 import { resolveIndividualVendors, } from './individualVendors.logic.js';
 import { assertFound, ConflictError, getErrorMessage, isModelUsable, NotFoundError, sameSubtasks, ValidationError, } from '@cat-factory/kernel';
 import { DEFAULT_MERGE_PRESET } from '@cat-factory/kernel';
-import { aggregateCi, CI_AGENT_KIND, CI_FIXER_AGENT_KIND, CONFLICTS_AGENT_KIND, CONFLICT_RESOLVER_AGENT_KIND, describeFailingChecks, listFailingChecks, isCiGreen, MERGER_AGENT_KIND, REQUIREMENTS_REVIEW_AGENT_KIND, CLARITY_REVIEW_AGENT_KIND, BUG_INVESTIGATOR_AGENT_KIND, TRACKER_AGENT_KIND, ANALYSIS_AGENT_KIND, TESTER_AGENT_KIND, BLUEPRINTS_AGENT_KIND, SPEC_WRITER_AGENT_KIND, } from './ci.logic.js';
+import { aggregateCi, CI_AGENT_KIND, CI_FIXER_AGENT_KIND, CONFLICTS_AGENT_KIND, CONFLICT_RESOLVER_AGENT_KIND, describeFailingChecks, listFailingChecks, isCiGreen, MERGER_AGENT_KIND, REQUIREMENTS_REVIEW_AGENT_KIND, CLARITY_REVIEW_AGENT_KIND, BUG_INVESTIGATOR_AGENT_KIND, TRACKER_AGENT_KIND, ANALYSIS_AGENT_KIND, TESTER_AGENT_KIND, HUMAN_TEST_AGENT_KIND, BLUEPRINTS_AGENT_KIND, SPEC_WRITER_AGENT_KIND, } from './ci.logic.js';
 import { POST_RELEASE_HEALTH_AGENT_KIND, ON_CALL_AGENT_KIND, classifyReleaseHealth, describeRegressedSignals, } from './release.logic.js';
 import { AgentContextBuilder } from './AgentContextBuilder.js';
 import { CompanionController } from './CompanionController.js';
 import { MergeResolver } from './MergeResolver.js';
 import { ReviewGateController } from './ReviewGateController.js';
 import { TesterController } from './TesterController.js';
+import { HumanTestController } from './HumanTestController.js';
 import { recordGateAttempt } from './gates.js';
 import { isAsyncAgentExecutor } from '@cat-factory/kernel';
 import { isDeployStep } from '@cat-factory/integrations';
@@ -115,6 +116,8 @@ export class ExecutionService {
     requirementReviewService;
     clarityReviewService;
     environmentProvisioning;
+    environmentTeardown;
+    branchUpdater;
     /** Assembles the per-step agent context (requirements, docs, env, service frame, fragments). */
     contextBuilder;
     /** Resolves a `merger` step's assessment into an auto-merge or a `merge_review` notification. */
@@ -123,6 +126,8 @@ export class ExecutionService {
     companionController;
     /** Drives the Tester gate's fix loop: report → greenlight / dispatch fixer / fail. */
     testerController;
+    /** Drives the human-testing gate: provision env → park → confirm / fix / pull-main / recreate. */
+    humanTestController;
     /** Drives both iterative review gates (requirements + clarity); kind-parameterised. */
     reviewGate;
     /** The requirements subject for {@link reviewGate}. */
@@ -159,7 +164,7 @@ 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, clarityReviewRepository, clarityReviewService, environmentProvisioning, blueprintReconciler, notificationService, workspaceSettingsService, llmObservability, ciStatusProvider, mergeabilityProvider, releaseHealthProvider, incidentEnrichment, pullRequestMerger, mergePresetRepository, ticketTrackerProvider, issueWriteback, subscriptionActivationRepository, resolveWorkspaceModelDefault, resolveProviderCapabilities, localTestInfraSupported, resolveRunRepoContext, runInitiatorScope, }) {
+    constructor({ workspaceRepository, blockRepository, pipelineRepository, executionRepository, accountRepository, idGenerator, clock, agentExecutor, workRunner, executionEventPublisher, boardService, spendService, documentRepository, taskRepository, requirementReviewRepository, requirementReviewService, clarityReviewRepository, clarityReviewService, environmentProvisioning, environmentTeardown, branchUpdater, blueprintReconciler, notificationService, workspaceSettingsService, llmObservability, ciStatusProvider, mergeabilityProvider, releaseHealthProvider, incidentEnrichment, pullRequestMerger, mergePresetRepository, ticketTrackerProvider, issueWriteback, subscriptionActivationRepository, resolveWorkspaceModelDefault, resolveProviderCapabilities, localTestInfraSupported, resolveRunRepoContext, runInitiatorScope, }) {
         this.runInitiatorScope = runInitiatorScope ?? ((_initiatedBy, fn) => fn());
         this.workspaceRepository = workspaceRepository;
         this.blockRepository = blockRepository;
@@ -176,6 +181,8 @@ export class ExecutionService {
         this.requirementReviewService = requirementReviewService;
         this.clarityReviewService = clarityReviewService;
         this.environmentProvisioning = environmentProvisioning;
+        this.environmentTeardown = environmentTeardown;
+        this.branchUpdater = branchUpdater;
         this.contextBuilder = new AgentContextBuilder({
             workspaceRepository,
             blockRepository,
@@ -220,6 +227,47 @@ export class ExecutionService {
             persistInstance: (ws, i) => this.executionRepository.upsert(ws, i),
             emitInstance: (ws, i) => this.emitInstance(ws, i),
         });
+        this.humanTestController = new HumanTestController({
+            blockRepository,
+            executionRepository,
+            workRunner,
+            agentExecutor,
+            contextBuilder: this.contextBuilder,
+            notificationService,
+            // Wrap the env services with the deployer's input/context derivation so the gate's
+            // provisioning matches a `deployer` step's. Left undefined when no provider is wired
+            // (the gate degrades to manual mode).
+            ...(environmentProvisioning
+                ? {
+                    provisionEnvironment: (ws, block, executionId) => environmentProvisioning.provision({
+                        workspaceId: ws,
+                        blockId: block.id,
+                        executionId,
+                        inputs: this.deployInputs(block),
+                        context: this.deployContext(block),
+                    }),
+                    refreshEnvironment: (ws, id) => environmentProvisioning.refreshStatus(ws, id),
+                }
+                : {}),
+            ...(environmentTeardown
+                ? {
+                    teardownEnvironment: async (ws, id) => {
+                        await environmentTeardown.teardown(ws, id);
+                    },
+                }
+                : {}),
+            ...(branchUpdater ? { branchUpdater } : {}),
+            resolveMergePreset: (ws, block) => this.resolveMergePreset(ws, block),
+            parkStepOnDecision: (ws, i, s, p) => this.parkStepOnDecision(ws, i, s, p),
+            finishStep: (s) => this.finishStep(s),
+            startStep: (s) => this.startStep(s),
+            updateBlockProgress: (ws, i, st) => this.updateBlockProgress(ws, i, st),
+            finalizeBlock: (ws, i, c) => this.finalizeBlock(ws, i, c),
+            stopRunContainer: (ws, i) => this.stopRunContainer(ws, i),
+            persistInstance: (ws, i) => this.executionRepository.upsert(ws, i),
+            emitInstance: (ws, i) => this.emitInstance(ws, i),
+            clockNow: () => this.clock.now(),
+        });
         this.reviewGate = new ReviewGateController({
             blockRepository,
             executionRepository,
@@ -639,7 +687,12 @@ export class ExecutionService {
             const reentrantRequirements = (step.agentKind === REQUIREMENTS_REVIEW_AGENT_KIND ||
                 step.agentKind === CLARITY_REVIEW_AGENT_KIND) &&
                 !!step.pendingIncorporation;
-            if (!reentrantRequirements) {
+            // The human-testing gate is likewise re-entrant: a human action (confirm / request a
+            // fix / pull main / recreate) records a `pendingAction` on the parked step and wakes
+            // the driver. Fall through so the gate re-evaluates and acts on it (dispatch a helper,
+            // rebuild the env, or advance) instead of immediately re-parking.
+            const reentrantHumanTest = step.agentKind === HUMAN_TEST_AGENT_KIND && !!step.humanTest?.pendingAction;
+            if (!reentrantRequirements && !reentrantHumanTest) {
                 // Parked on either an agent-raised decision or a human approval gate; both
                 // are addressed by the same durable event id.
                 const pendingId = step.decision?.id ?? step.approval?.id;
@@ -694,6 +747,15 @@ export class ExecutionService {
         if (step.agentKind === CLARITY_REVIEW_AGENT_KIND) {
             return this.reviewGate.evaluate(this.clarityKind, workspaceId, instance, step, block, isFinalStep);
         }
+        // A `human-test` gate spins up an ephemeral environment and PARKS for a human to
+        // validate the change in a live URL before the run continues — NOT a container/prose
+        // agent and NOT a programmatic polling gate (the human is the verdict). It also drives
+        // the same helpers the other gates use on demand: the Tester's `fixer` (from findings)
+        // and the `conflict-resolver` (after a conflicting pull-main). Degrades to a manual
+        // (no-env) mode when no ephemeral-environment provider is wired. See {@link HumanTestController}.
+        if (step.agentKind === HUMAN_TEST_AGENT_KIND) {
+            return this.humanTestController.evaluate(workspaceId, instance, step, block, isFinalStep);
+        }
         // A polling gate step (`ci` / `conflicts`) runs a programmatic precheck and only
         // escalates to a helper container agent (`ci-fixer` / `conflict-resolver`) on a
         // negative verdict — no LLM of its own. Pass-through when the gate's provider is
@@ -934,6 +996,17 @@ export class ExecutionService {
             await this.stopRunContainer(workspaceId, instance);
             return this.testerController.dispatchTester(workspaceId, instance, step, block);
         }
+        // A `human-test` gate in its `fixing` / `resolving_conflicts` phase has a helper job
+        // (fixer / conflict-resolver) in flight, NOT the step's own work: when it settles —
+        // done OR failed — record the round's outcome, rebuild the environment against the
+        // (now-updated) branch and re-park the human. We never fail the run here; the human is
+        // in control. Mirrors the Tester→Fixer loop.
+        if (step.agentKind === HUMAN_TEST_AGENT_KIND &&
+            (step.humanTest?.phase === 'fixing' || step.humanTest?.phase === 'resolving_conflicts')) {
+            return this.humanTestController.onHelperComplete(workspaceId, instance, step, {
+                state: update.state === 'failed' ? 'failed' : 'done',
+            });
+        }
         if (update.state === 'failed') {
             // A container eviction (the per-run container vanished, its in-memory job is
             // gone) is usually transient. Recover it by dropping the dead handle and
@@ -997,6 +1070,12 @@ export class ExecutionService {
             return { kind: 'noop' };
         }
         const step = instance.steps[instance.currentStep];
+        // The human-testing gate rides the same `awaiting_gate` poll loop while its ephemeral
+        // environment provisions — re-poll the env status (ready → park the human; still
+        // provisioning → keep polling; failed → degrade to manual mode).
+        if (step?.agentKind === HUMAN_TEST_AGENT_KIND) {
+            return this.humanTestController.pollEnvironment(workspaceId, instance);
+        }
         const gate = step ? this.gateFor(step.agentKind) : undefined;
         if (!step || !gate)
             return { kind: 'continue' };
@@ -1027,6 +1106,11 @@ export class ExecutionService {
             return { kind: 'noop' };
         }
         const step = instance.steps[instance.currentStep];
+        // The human-testing gate never times the RUN out while provisioning: instead of failing,
+        // park the human in degraded mode so they can wait, recreate, or test by hand.
+        if (step?.agentKind === HUMAN_TEST_AGENT_KIND) {
+            return this.humanTestController.onProvisionTimeout(workspaceId, instance);
+        }
         const gate = step ? this.gateFor(step.agentKind) : undefined;
         const timeoutError = 'Gate precheck did not settle within its polling budget';
         if (!step || !gate || gate.pollExhaustion !== 'pass') {
@@ -2178,6 +2262,9 @@ export class ExecutionService {
         if (step.agentKind === CLARITY_REVIEW_AGENT_KIND) {
             throw new ConflictError('Resolve the clarity review through its review window, not the approval gate');
         }
+        if (step.agentKind === HUMAN_TEST_AGENT_KIND) {
+            throw new ConflictError('Resolve the human-testing gate through its window (confirm / request a fix), not the approval gate');
+        }
         if (step.companion?.exceeded) {
             throw new ConflictError('Resolve this companion review through its iteration-cap prompt, not the approval gate');
         }
@@ -2435,6 +2522,29 @@ export class ExecutionService {
     resolveClarityExceeded(workspaceId, blockId, choice) {
         return this.reviewGate.resolveExceeded(this.clarityKind, workspaceId, blockId, choice);
     }
+    // ---- human-testing gate actions (driven from the dedicated window) -------
+    // Each mutates the parked gate step and wakes the durable driver, which re-enters the gate
+    // and performs the (env / helper) work; see {@link HumanTestController}.
+    /** Confirm the change works: tear the ephemeral env down and advance the run. */
+    confirmHumanTest(workspaceId, blockId) {
+        return this.humanTestController.confirm(workspaceId, blockId);
+    }
+    /** Submit findings and request a fix: dispatch the Tester's `fixer`, then rebuild the env. */
+    requestHumanTestFix(workspaceId, blockId, findings) {
+        return this.humanTestController.requestFix(workspaceId, blockId, findings);
+    }
+    /** Pull the repo default branch into the PR branch + redeploy (conflict → conflict-resolver). */
+    pullMainHumanTest(workspaceId, blockId) {
+        return this.humanTestController.pullMain(workspaceId, blockId);
+    }
+    /** Rebuild the ephemeral environment on demand. */
+    recreateHumanTestEnv(workspaceId, blockId) {
+        return this.humanTestController.recreateEnvironment(workspaceId, blockId);
+    }
+    /** Destroy the ephemeral environment on demand (the run stays parked). */
+    destroyHumanTestEnv(workspaceId, blockId) {
+        return this.humanTestController.destroyEnvironment(workspaceId, blockId);
+    }
     /**
      * Push the run's latest state to subscribed clients, alongside its rolled-up
      * block so the board updates without a refetch. Best-effort: the publisher