@cat-factory/orchestration 0.70.1 → 0.71.0

package/dist/modules/execution/ExecutionService.js

@@ -1,5 +1,5 @@
-import { DEFAULT_COMPANION_MAX_ATTEMPTS, frameAllowsVisualPipeline, isLocalRunner, pipelineHasVisualStep, } from '@cat-factory/contracts';
-import { BINARY_STORAGE_TRAIT, companionFor, companionTargets, hasTrait, isCompanionKind, isInlineModelStep, } from '@cat-factory/agents';
+import { allPullRequests, DEFAULT_COMPANION_MAX_ATTEMPTS, frameAllowsVisualPipeline, isLocalRunner, pipelineHasVisualStep, } from '@cat-factory/contracts';
+import { BINARY_STORAGE_TRAIT, bugInvestigation, companionFor, companionTargets, hasTrait, isCompanionKind, isInlineModelStep, } from '@cat-factory/agents';
 import { assertPipelineLaunchable, validatePipelineShape, } from '../pipelines/pipelineShape.js';
 import { shouldRunGatedStep } from './stepGating.logic.js';
 import { resolveIndividualVendors, } from './individualVendors.logic.js';
@@ -14,13 +14,14 @@ import { RunStateMachine } from './RunStateMachine.js';
 import { RunDispatcher } from './RunDispatcher.js';
 import { inferTechnicalLabel } from './technical.logic.js';
 import { MergeResolver } from './MergeResolver.js';
+import { orderPrsForMerge } from './mergeOrder.logic.js';
 import { ReviewGateController } from './ReviewGateController.js';
 import { BrainstormActions, ClarityReviewActions, RequirementReviewActions, } from './gate-window-facades.js';
 import { TesterController } from './TesterController.js';
 import { HumanTestController } from './HumanTestController.js';
 import { VisualConfirmationController } from './VisualConfirmationController.js';
 import { InitiativeInterviewController } from './InitiativeInterviewController.js';
-import { assertInitiativeShapeAllowed } from '../initiative/initiative.logic.js';
+import { assertInitiativeShapeAllowed, } from '../initiative/initiative.logic.js';
 import { isAsyncAgentExecutor } from '@cat-factory/kernel';
 import { dependenciesMet, descendantIds, serviceOf, unmetDependencies, } from '../board/board.logic.js';
 import { requireWorkspace } from '@cat-factory/kernel';
@@ -48,6 +49,8 @@ export class ExecutionService {
     /** The async instance/block state-machine spine (persist/emit/park/advance/finalize/fail). */
     runStateMachine;
     agentExecutor;
+    /** App-owned agent-kind registry (custom-kind traits/inline-surface + pre/post-op hooks). */
+    agentKindRegistry;
     workRunner;
     events;
     board;
@@ -92,6 +95,7 @@ export class ExecutionService {
     // so the constructor forwards the destructured params straight to those collaborators.
     workspaceSettingsService;
     prMerger;
+    notifications;
     mergePresetRepository;
     issueWriteback;
     subscriptionActivations;
@@ -118,7 +122,7 @@ export class ExecutionService {
      * / `resolveGatePollExhaustion` + the follow-up human-action API are thin pass-throughs.
      */
     runDispatcher;
-    constructor({ workspaceRepository, blockRepository, pipelineRepository, executionRepository, accountRepository, idGenerator, clock, agentExecutor, workRunner, executionEventPublisher, boardService, spendService, documentRepository, documentUrlResolver, taskRepository, requirementReviewRepository, requirementReviewService, testerQualityReviewer, kaizenScheduler, clarityReviewRepository, clarityReviewService, brainstormServices, brainstormSessionRepository, fragmentResolver, environmentProvisioning, environmentTeardown, branchUpdater, blueprintReconciler, initiativeService, initiativeRepository, initiativeInterviewService, notificationService, resolveBinaryArtifactStore, workspaceSettingsService, llmObservability, pullRequestMerger, mergePresetRepository, ticketTrackerProvider, issueWriteback, subscriptionActivationRepository, resolveWorkspaceModelDefault, resolveProviderCapabilities, inlineHarnessRef, localTestInfraSupported, resolveRunRepoContext, assertAgentBackendConfigured, runInitiatorScope, pokeInitiativeLoop, }) {
+    constructor({ workspaceRepository, blockRepository, pipelineRepository, executionRepository, accountRepository, idGenerator, clock, agentExecutor, workRunner, executionEventPublisher, boardService, spendService, documentRepository, documentUrlResolver, taskRepository, requirementReviewRepository, requirementReviewService, testerQualityReviewer, kaizenScheduler, clarityReviewRepository, clarityReviewService, brainstormServices, brainstormSessionRepository, fragmentResolver, environmentProvisioning, environmentTeardown, branchUpdater, blueprintReconciler, initiativeService, initiativeRepository, initiativeInterviewService, notificationService, resolveBinaryArtifactStore, workspaceSettingsService, llmObservability, pullRequestMerger, mergePresetRepository, ticketTrackerProvider, issueWriteback, bugIntakeService, subscriptionActivationRepository, resolveWorkspaceModelDefault, resolveProviderCapabilities, inlineHarnessRef, localTestInfraSupported, resolveRunRepoContext, assertAgentBackendConfigured, runInitiatorScope, pokeInitiativeLoop, agentKindRegistry, }) {
         // Forward-only: the run-initiator scope is consumed solely by RunDispatcher (below), so it
         // is hoisted to a local with its default applied rather than stored as a `this.` field.
         const runInitiatorScopeFn = runInitiatorScope ?? ((_initiatedBy, fn) => fn());
@@ -145,6 +149,7 @@ export class ExecutionService {
             pokeInitiativeLoop,
         });
         this.agentExecutor = agentExecutor;
+        this.agentKindRegistry = agentKindRegistry;
         this.workRunner = workRunner;
         this.events = executionEventPublisher;
         this.board = boardService;
@@ -157,6 +162,7 @@ export class ExecutionService {
             workspaceRepository,
             blockRepository,
             accountRepository,
+            agentKindRegistry,
             documents: documentRepository,
             documentUrlResolver,
             tasks: taskRepository,
@@ -281,6 +287,7 @@ export class ExecutionService {
             blockRepository,
             executionRepository,
             agentExecutor,
+            agentKindRegistry,
             workRunner,
             events: executionEventPublisher,
             idGenerator,
@@ -304,6 +311,7 @@ export class ExecutionService {
             environmentProvisioning,
             ticketTrackerProvider,
             issueWriteback,
+            bugIntakeService,
             notificationService,
             blueprintReconciler,
             initiativeService,
@@ -320,6 +328,7 @@ export class ExecutionService {
         this.brainstormActions = new BrainstormActions(this.reviewGate, (stage) => this.brainstormKindFor(stage));
         this.workspaceSettingsService = workspaceSettingsService;
         this.prMerger = pullRequestMerger;
+        this.notifications = notificationService;
         this.mergePresetRepository = mergePresetRepository;
         this.issueWriteback = issueWriteback;
         this.subscriptionActivations = subscriptionActivationRepository;
@@ -507,7 +516,7 @@ export class ExecutionService {
      * no storage) — matching the other optional start guards.
      */
     async assertBinaryStorageConfigured(workspaceId, agentKinds) {
-        if (!agentKinds.some((kind) => hasTrait(kind, BINARY_STORAGE_TRAIT)))
+        if (!agentKinds.some((kind) => hasTrait(kind, BINARY_STORAGE_TRAIT, this.agentKindRegistry)))
             return;
         const resolve = this.resolveBinaryArtifactStore;
         if (!resolve)
@@ -553,12 +562,12 @@ export class ExecutionService {
         if (block.modelId) {
             // A block-level pin applies to every step; it must satisfy an inline step too when the
             // pipeline has one.
-            check(block.modelId, agentKinds.some(isInlineModelStep));
+            check(block.modelId, agentKinds.some((kind) => isInlineModelStep(kind, this.agentKindRegistry)));
         }
         else if (this.resolveWorkspaceModelDefault) {
             // Independent per-kind resolutions on the start path — run them concurrently.
             const ids = await Promise.all(agentKinds.map((kind) => this.resolveWorkspaceModelDefault(workspaceId, kind, block.modelPresetId)));
-            agentKinds.forEach((kind, i) => check(ids[i], isInlineModelStep(kind)));
+            agentKinds.forEach((kind, i) => check(ids[i], isInlineModelStep(kind, this.agentKindRegistry)));
         }
         if (unconfigured.size > 0) {
             throw new ConflictError(`This pipeline uses models with no configured provider: ${[...unconfigured].join(', ')}. ` +
@@ -1227,25 +1236,81 @@ export class ExecutionService {
      */
     buildClarityKind() {
         const require = () => {
-            if (!this.clarityReviewService?.enabled) {
+            if (!this.clarityReviewService) {
                 throw new ConflictError('The clarity reviewer is not configured');
             }
             return this.clarityReviewService;
         };
         return {
             agentKind: CLARITY_REVIEW_AGENT_KIND,
+            // Enabled whenever the clarity STORE is wired — the bug-triage seed/auto-pass path is
+            // deterministic (driven by the upstream investigator's structured triage) and needs no
+            // reviewer model, so the gate must activate even with no model configured. The LLM
+            // review/incorporate/re-review paths still resolve their own model (and degrade gracefully
+            // when unwired: no investigation + no model ⇒ the review closure auto-passes).
             entityName: 'Clarity review',
-            enabled: () => !!this.clarityReviewService?.enabled,
+            enabled: () => !!this.clarityReviewService,
             getForBlock: (ws, blockId) => require().getForBlock(ws, blockId),
-            review: async (ws, block, preset) => require().review(ws, block.id, {
-                maxIterations: preset.maxRequirementIterations,
-                concernThreshold: preset.maxRequirementConcernAllowed,
-                investigation: await this.investigationForBlock(ws, block.id),
-            }),
-            reReview: (ws, reviewId, preset) => require().reReview(ws, reviewId, { concernThreshold: preset.maxRequirementConcernAllowed }),
+            review: async (ws, block, preset) => {
+                const svc = require();
+                const structured = await this.structuredInvestigationForBlock(ws, block.id);
+                let review;
+                if (structured) {
+                    // An upstream structured `bug-investigator`: seed the gate from its triage — NO reviewer
+                    // LLM. `clear` → auto-pass; `needs_clarification` → one blocking finding per question.
+                    // The investigator explicitly asked for clarification, so those questions ALWAYS park
+                    // for a human — the requirements-review concern tolerance (`maxRequirementConcernAllowed`,
+                    // which governs the requirements reviewer, not bug triage) must not silently auto-pass
+                    // them — hence a fixed `none` threshold here rather than the preset's.
+                    review = await svc.seedReview(ws, block.id, {
+                        clarity: structured.clarity,
+                        questions: structured.questions,
+                        maxIterations: preset.maxRequirementIterations,
+                        concernThreshold: 'none',
+                    });
+                }
+                else if (!svc.enabled) {
+                    // No structured investigation and no reviewer model: nothing to review against, so
+                    // auto-pass (equivalent to the old pass-through when the reviewer wasn't configured).
+                    review = await svc.seedReview(ws, block.id, {
+                        clarity: 'clear',
+                        questions: [],
+                        maxIterations: preset.maxRequirementIterations,
+                        concernThreshold: preset.maxRequirementConcernAllowed,
+                    });
+                }
+                else {
+                    review = await svc.review(ws, block.id, {
+                        maxIterations: preset.maxRequirementIterations,
+                        concernThreshold: preset.maxRequirementConcernAllowed,
+                        investigation: await this.investigationForBlock(ws, block.id),
+                    });
+                }
+                // Whenever the gate parks with open questions — from the deterministic seed OR the LLM
+                // reviewer — best-effort echo them onto the linked tracker issue (answers still arrive
+                // in-app). A settled/auto-passed review echoes nothing; a tracker outage never fails the run.
+                await this.echoClarityQuestions(ws, block.id, review);
+                return review;
+            },
+            reReview: async (ws, reviewId, preset) => {
+                const svc = require();
+                // No reviewer model wired: a re-review can't run, so settle the loop (converge) instead of
+                // throwing — the deterministic seed path can reach a park with no model configured.
+                if (!svc.enabled)
+                    return svc.markIncorporated(ws, reviewId);
+                return svc.reReview(ws, reviewId, { concernThreshold: preset.maxRequirementConcernAllowed });
+            },
             incorporate: async (ws, blockId, reviewId, feedback) => {
+                const svc = require();
+                // No reviewer model: can't LLM-fold the answers into a clarified report, so settle the
+                // review as-is (the run advances on the raw report + the recorded answers) instead of
+                // throwing — keeps the model-free seed path resolvable.
+                if (!svc.enabled) {
+                    await svc.markIncorporated(ws, reviewId);
+                    return;
+                }
                 const investigation = await this.investigationForBlock(ws, blockId);
-                await require().incorporate(ws, reviewId, { feedback, investigation });
+                await svc.incorporate(ws, reviewId, { feedback, investigation });
             },
             markIncorporated: (ws, reviewId) => require().markIncorporated(ws, reviewId),
             markReReviewing: (ws, reviewId) => require().markReReviewing(ws, reviewId),
@@ -1400,6 +1465,49 @@ export class ExecutionService {
         const instance = await this.executionRepository.get(workspaceId, block.executionId);
         return instance ? this.investigationFor(instance) : undefined;
     }
+    /**
+     * The latest `bug-investigator` step's STRUCTURED triage on a run — its `clarity` verdict +
+     * `questions` — parsed leniently from `step.custom`. Drives the clarity gate's seed/auto-pass
+     * (see {@link buildClarityKind}): a structured investigator upstream means the gate seeds its
+     * findings from `questions` (or auto-passes on `clarity === 'clear'`) instead of running its
+     * own reviewer LLM. Undefined when no investigator ran or its result wasn't structured (an
+     * older prose investigator, or an unparseable reply) — the gate then falls back to the LLM path.
+     */
+    structuredInvestigationFor(instance) {
+        for (let i = instance.steps.length - 1; i >= 0; i--) {
+            const s = instance.steps[i];
+            if (s.agentKind !== BUG_INVESTIGATOR_AGENT_KIND || s.custom === undefined)
+                continue;
+            const parsed = bugInvestigation.safeParse(s.custom);
+            if (!parsed)
+                return undefined;
+            return { clarity: parsed.clarity, questions: parsed.questions };
+        }
+        return undefined;
+    }
+    /** Resolve a block's structured investigator triage via its current execution. */
+    async structuredInvestigationForBlock(workspaceId, blockId) {
+        const block = await this.blockRepository.get(workspaceId, blockId);
+        if (!block?.executionId)
+            return undefined;
+        const instance = await this.executionRepository.get(workspaceId, block.executionId);
+        return instance ? this.structuredInvestigationFor(instance) : undefined;
+    }
+    /**
+     * Best-effort echo of a parked clarity review's open questions onto the block's linked tracker
+     * issue (see {@link IssueWritebackProvider.postQuestions}). Fires for BOTH the deterministic
+     * investigator seed and the LLM reviewer, so identical human-parked states behave the same. A
+     * settled/auto-passed review (status `incorporated`) or one with no open items echoes nothing,
+     * and a tracker outage never fails the run.
+     */
+    async echoClarityQuestions(workspaceId, blockId, review) {
+        if (!this.issueWriteback || review.status === 'incorporated')
+            return;
+        const questions = review.items.filter((i) => i.status === 'open').map((i) => i.detail);
+        if (questions.length === 0)
+            return;
+        await this.issueWriteback.postQuestions(workspaceId, blockId, questions).catch(() => { });
+    }
     // The clarity / human-testing / visual-confirmation gate-window actions now live on the
     // per-feature sub-facades (`clarityReview` / `humanTest` / `visualConfirm`); see the getters
     // above and {@link gate-window-facades}.
@@ -1453,26 +1561,59 @@ export class ExecutionService {
         return instance;
     }
     /**
-     * Merge a block's PR for real, then mark it `done`. The remote merge happens
-     * FIRST (via the {@link PullRequestMerger} port) and only on its success does the
-     * block flip to `done` — so `done` provably means "merged", not a board-only
-     * status. When no merger is wired (tests) this degrades to the old board-only
-     * flip. Throws if the remote merge fails so callers can fall back to a manual
-     * merge / review notification.
+     * Merge a block's PR(s) for real, then mark it `done`. The remote merge happens FIRST (via
+     * the {@link PullRequestMerger} port) and only on its success does the block flip to `done`
+     * — so `done` provably means "merged", not a board-only status. When no merger is wired
+     * (tests) this degrades to the old board-only flip.
+     *
+     * Multi-repo (service-connections phase 4): a cross-service task opens one PR per changed
+     * repo. All of them are merged in provider-before-consumer order (see {@link orderPrsForMerge}),
+     * stopping at the first failure. A COMPLETE failure (nothing merged) THROWS so the caller
+     * falls back to a review notification, exactly as the single-repo path did. A PARTIAL failure
+     * (some merged, then one failed — cross-repo merges are non-atomic) leaves the block `blocked`
+     * and raises an enumerated `merge_review` notification, and is reported to the caller as
+     * `partial` so it labels the decision without raising a second card.
      */
     async finalizeMerge(workspaceId, blockId) {
         const block = await this.blockRepository.get(workspaceId, blockId);
         if (!block)
-            return;
+            return { kind: 'merged' };
         // Idempotent under durable-driver replays: a crash between the real merge and the
         // instance persist re-runs the merger resolver, and re-merging an already-merged PR
         // throws — which the resolver's fall-through would then misread as a failed merge
         // and downgrade the block to `pr_ready`. `done` already means "merged"; keep it.
         if (block.status === 'done')
-            return;
-        if (this.prMerger && block.pullRequest) {
-            // Throws on a blocked/failed merge — the caller decides what to do next.
-            await this.prMerger.mergeForBlock(workspaceId, blockId);
+            return { kind: 'merged' };
+        // Same idempotency guard for a PARTIALLY-merged multi-repo task: the first pass merged some
+        // PRs, then one failed, so it left the block `blocked` and raised the enumerated card. A
+        // durable-driver replay must NOT re-run the merge — re-merging the already-merged PRs throws
+        // (GitHub 405) and would be misread as a TOTAL failure (`merged.length === 0` → throw → the
+        // resolver downgrades the block to `pr_ready` + raises a SECOND card). The merger step only
+        // ever enters `finalizeMerge` on an already-`blocked` block on such a replay (the manual
+        // `mergePr` path gates on `pr_ready`), so return the already-recorded partial outcome.
+        if (block.status === 'blocked')
+            return { kind: 'partial', merged: [], unmerged: [] };
+        // Merge every PR the task opened (own-service + peers) — not just `block.pullRequest`, since a
+        // multi-repo task can have changed ONLY peer repos (own service untouched, no own PR).
+        const ordered = orderPrsForMerge(allPullRequests(block).map((p) => ({
+            ...(p.repo ? { repo: p.repo } : {}),
+            ...(p.frameId ? { frameId: p.frameId } : {}),
+            ref: p.ref,
+        })));
+        if (this.prMerger && ordered.length > 0) {
+            const outcome = await this.prMerger.mergePullRequests(workspaceId, blockId, ordered);
+            if (outcome.failed) {
+                // Nothing merged → behave like the old single-PR throw so the caller raises a review.
+                if (outcome.merged.length === 0)
+                    throw new Error(outcome.failed.error);
+                // Partial: leave the block blocked and enumerate the split for a human to finish/revert.
+                const label = (e) => e.repo ?? 'own service';
+                const merged = outcome.merged.map(label);
+                const unmerged = [outcome.failed.entry, ...outcome.skipped].map(label);
+                await this.blockRepository.update(workspaceId, blockId, { status: 'blocked' });
+                await this.raisePartialMergeNotification(workspaceId, block, merged, unmerged);
+                return { kind: 'partial', merged, unmerged };
+            }
         }
         await this.blockRepository.update(workspaceId, blockId, { status: 'done', progress: 1 });
         // Best-effort writeback: comment + close the task's linked tracker issue(s) as
@@ -1498,6 +1639,30 @@ export class ExecutionService {
             if (block.initiativeId)
                 this.pokeInitiativeLoop?.(workspaceId, block.initiativeId);
         }
+        return { kind: 'merged' };
+    }
+    /**
+     * Raise the `merge_review` card for a PARTIALLY-merged multi-repo task: some PRs merged, then
+     * an intermediate one failed. Cross-repo merges can't be atomic, so the human finishes or
+     * reverts the split by hand; the card enumerates which repos merged vs are still open.
+     */
+    async raisePartialMergeNotification(workspaceId, block, merged, unmerged) {
+        if (!this.notifications)
+            return;
+        await this.notifications.raise(workspaceId, {
+            type: 'merge_review',
+            blockId: block.id,
+            executionId: block.executionId ?? null,
+            title: `Finish the multi-repo merge for "${block.title}"`,
+            body: `Merged ${merged.length} PR(s) (${merged.join(', ')}) but could not merge ` +
+                `${unmerged.length} more (${unmerged.join(', ')}). Cross-repo merges aren't atomic — ` +
+                `merge the rest or revert the merged PR(s) by hand.`,
+            payload: {
+                mergedRepos: merged,
+                unmergedRepos: unmerged,
+                ...(block.pullRequest?.url ? { prUrl: block.pullRequest.url } : {}),
+            },
+        });
     }
     /**
      * After a task with `autoStartDependents` merges, start every task that `dependsOn` it