@cat-factory/orchestration 0.192.0 → 0.194.0

package/dist/modules/execution/RunDispatcherDependencies.d.ts

@@ -0,0 +1,142 @@
+import type { AgentExecutor, Block, BlockRepository, BrainstormSession, ClarityReview, Clock, ExecutionEventPublisher, ExecutionRepository, GateOutcomeRepository, GateRegistry, IdGenerator, IssueWritebackProvider, JudgeAssessor, JudgeRegistry, Logger, ProviderCapabilities, ProviderRegistry, RequirementConcernLevel, RequirementReview, ResolveRunRepoContext, RunInitiatorScope, StepGating, StepResolverRegistry, TicketTrackerProvider, WorkRunner } from '@cat-factory/kernel';
+import type { SettledGate } from '../observability/GateOutcomeRecorder.js';
+import type { AgentKindRegistry } from '@cat-factory/agents';
+import type { BugIntakeService, EnvironmentProvisioningService } from '@cat-factory/integrations';
+import type { SpendService } from '@cat-factory/spend';
+import type { AgentContextBuilder, FragmentBodyResolver } from './AgentContextBuilder.js';
+import type { CompanionController } from './CompanionController.js';
+import type { ForkDecisionController } from './ForkDecisionController.js';
+import type { HumanTestController } from './HumanTestController.js';
+import type { InterviewGateController } from './InterviewGateController.js';
+import type { MergeResolver } from './MergeResolver.js';
+import type { PrReviewController } from './PrReviewController.js';
+import type { PrVerificationReportController } from './PrVerificationReportController.js';
+import type { RalphController } from './RalphController.js';
+import type { ReviewGateController, ReviewKind } from './ReviewGateController.js';
+import type { RunStateMachine } from './RunStateMachine.js';
+import type { StepGraph } from './StepGraph.js';
+import type { TesterController } from './TesterController.js';
+import type { VisualConfirmationController } from './VisualConfirmationController.js';
+import type { BlueprintReconciler } from './ExecutionService.js';
+import type { InitiativeService } from '../initiative/InitiativeService.js';
+import type { NotificationService } from '../notifications/NotificationService.js';
+export /**
+ * The task's fully-resolved merge-threshold preset (block pin → workspace default →
+ * built-in). The dispatcher only reads the gate-relevant fields; the full shape is kept so
+ * a gate's `attemptBudget(preset)` sees every knob. Mirrors {@link ExecutionService.resolveRiskPolicy}.
+ */ type ResolvedRiskPolicy = {
+    maxComplexity: number;
+    maxRisk: number;
+    maxImpact: number;
+    ciMaxAttempts: number;
+    maxRequirementIterations: number;
+    maxRequirementConcernAllowed: RequirementConcernLevel;
+    judgeMinScore: number;
+    judgeMaxBounces: number;
+    releaseWatchWindowMinutes: number;
+    releaseMaxAttempts: number;
+    humanReviewGraceMinutes: number;
+    forkDecision?: StepGating | null;
+};
+/** Collaborators + leaf dependencies the {@link RunDispatcher} needs. */
+export interface RunDispatcherDeps {
+    blockRepository: BlockRepository;
+    executionRepository: ExecutionRepository;
+    agentExecutor: AgentExecutor;
+    /** App-owned agent-kind registry: a registered kind's step spec + pre/post-op hooks. */
+    agentKindRegistry: AgentKindRegistry;
+    /** App-owned polling-gate registry (built-ins installed by the facade via `registerBuiltinGates`). */
+    gateRegistry: GateRegistry;
+    /**
+     * The app-owned JUDGE registry (the fourth step-taxonomy bucket) the composition root
+     * injected, plus the verdict producer. An absent / disabled assessor makes every judge step
+     * a pass-through, which is exactly what a deployment with no model wired (and the
+     * conformance/e2e suites) gets. See `docs/initiatives/judge-registry.md`.
+     */
+    judgeRegistry: JudgeRegistry;
+    judgeAssessor?: JudgeAssessor;
+    /**
+     * The prompt-fragment library, used by the judge driver for ONE thing: resolving a rubric's
+     * per-workspace override body (see `JudgeRubric.fragmentId`). Absent ⇒ the registration's
+     * default rubric.
+     */
+    fragmentResolver?: FragmentBodyResolver;
+    /** App-owned step-completion-resolver registry (deployment-registered resolvers). */
+    stepResolverRegistry: StepResolverRegistry;
+    /** App-owned provider registry the gate machine's {@link GateContext} reads (gate data sources). */
+    providerRegistry: ProviderRegistry;
+    workRunner: WorkRunner;
+    events: ExecutionEventPublisher;
+    idGenerator: IdGenerator;
+    clock: Clock;
+    /**
+     * Where the dispatcher's best-effort hooks (issue writeback, lease release, repo ops) report
+     * their drops. Absent ⇒ `noopLogger`, which is what the engine unit tests construct with.
+     */
+    logger?: Logger;
+    /**
+     * Optional settled-gate projection: the gate machine records each terminal verdict into it
+     * for the operator dashboard's attempt statistics. Absent ⇒ nothing is recorded.
+     */
+    gateOutcomeRepository?: GateOutcomeRepository;
+    spend: SpendService;
+    stepGraph: StepGraph;
+    runStateMachine: RunStateMachine;
+    contextBuilder: AgentContextBuilder;
+    mergeResolver: MergeResolver;
+    companionController: CompanionController;
+    testerController: TesterController;
+    ralphController: RalphController;
+    humanTestController: HumanTestController;
+    visualConfirmationController: VisualConfirmationController;
+    reviewGate: ReviewGateController;
+    forkDecisionController: ForkDecisionController;
+    prReviewController: PrReviewController;
+    requirementsKind: ReviewKind<RequirementReview>;
+    clarityKind: ReviewKind<ClarityReview>;
+    requirementsBrainstormKind: ReviewKind<BrainstormSession>;
+    architectureBrainstormKind: ReviewKind<BrainstormSession>;
+    /**
+     * The interactive-interviewer gates wired for this deployment (initiative-planning, document
+     * interview, …). Each rides the shared {@link InterviewGateController} spine and is routed by
+     * the `interview-gate` TRAIT, keyed on its own `agentKind` — so adding a new interviewer wires
+     * its controller here, with no new dispatch branch. Absent/unwired kinds pass through.
+     */
+    interviewControllers?: InterviewGateController<unknown>[];
+    /** Keeps the run's verification report current on its PR; a no-op with no publisher wired. */
+    prVerificationReport: PrVerificationReportController;
+    runInitiatorScope: RunInitiatorScope;
+    environmentProvisioning?: EnvironmentProvisioningService;
+    ticketTrackerProvider?: TicketTrackerProvider;
+    issueWriteback?: IssueWritebackProvider;
+    /** The recurring `bug-intake` step's read-and-claim helper; absent → the step is a no-op. */
+    bugIntakeService?: BugIntakeService;
+    notificationService?: NotificationService;
+    blueprintReconciler?: BlueprintReconciler;
+    initiativeService?: InitiativeService;
+    resolveRunRepoContext?: ResolveRunRepoContext;
+    resolveProviderCapabilities?: (workspaceId: string, initiatedBy?: string | null, modelPresetId?: string) => Promise<ProviderCapabilities>;
+    /** Resolve a task's merge preset (stays on the engine, shared with the merge subgraph). */
+    resolveRiskPolicy: (workspaceId: string, block: Block) => Promise<ResolvedRiskPolicy>;
+    /** Whether a resolved model id incurs metered monetary cost (the start gate's predicate). */
+    modelIdIsMetered: (id: string | undefined, caps: ProviderCapabilities) => boolean;
+}
+/**
+ * The `recordGateOutcome` callback both gate-settling controllers take, or nothing when no
+ * projection is wired.
+ *
+ * Computed ONCE and spread into both: a gate reaches a terminal verdict down two paths, the
+ * precheck/exhaustion machine in {@link GateStepController} and the investigate-don't-fix
+ * completion in {@link PollRunningController}, and wiring only the first is why the
+ * `post-release-health` gate was absent from the statistics entirely. Two call sites, one
+ * recorder, so a third settling path has one obvious thing to reach for.
+ *
+ * A free function rather than an inline branch in the constructor: each controller takes ONE
+ * bound callback and must stay independent of the sink's collaborators, and the constructor is
+ * already at its statement budget (budgets are split triggers). It lives beside the deps it
+ * `Pick`s from, so the dispatcher imports it rather than re-declaring that slice.
+ */
+export declare function gateOutcomeRecording(deps: Pick<RunDispatcherDeps, 'gateOutcomeRepository' | 'clock'>, logger: Logger): {
+    recordGateOutcome?: (settled: SettledGate) => Promise<void>;
+};
+//# sourceMappingURL=RunDispatcherDependencies.d.ts.map

package/dist/modules/execution/RunDispatcherDependencies.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RunDispatcherDependencies.d.ts","sourceRoot":"","sources":["../../../src/modules/execution/RunDispatcherDependencies.ts"],"names":[],"mappings":"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"}

package/dist/modules/execution/RunDispatcherDependencies.js

@@ -0,0 +1,27 @@
+import { GateOutcomeRecorder } from '../observability/GateOutcomeRecorder.js';
+/**
+ * The `recordGateOutcome` callback both gate-settling controllers take, or nothing when no
+ * projection is wired.
+ *
+ * Computed ONCE and spread into both: a gate reaches a terminal verdict down two paths, the
+ * precheck/exhaustion machine in {@link GateStepController} and the investigate-don't-fix
+ * completion in {@link PollRunningController}, and wiring only the first is why the
+ * `post-release-health` gate was absent from the statistics entirely. Two call sites, one
+ * recorder, so a third settling path has one obvious thing to reach for.
+ *
+ * A free function rather than an inline branch in the constructor: each controller takes ONE
+ * bound callback and must stay independent of the sink's collaborators, and the constructor is
+ * already at its statement budget (budgets are split triggers). It lives beside the deps it
+ * `Pick`s from, so the dispatcher imports it rather than re-declaring that slice.
+ */
+export function gateOutcomeRecording(deps, logger) {
+    if (!deps.gateOutcomeRepository)
+        return {};
+    const recorder = new GateOutcomeRecorder({
+        gateOutcomeRepository: deps.gateOutcomeRepository,
+        now: () => deps.clock.now(),
+        logger,
+    });
+    return { recordGateOutcome: (settled) => recorder.record(settled) };
+}
+//# sourceMappingURL=RunDispatcherDependencies.js.map

package/dist/modules/execution/RunDispatcherDependencies.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RunDispatcherDependencies.js","sourceRoot":"","sources":["../../../src/modules/execution/RunDispatcherDependencies.ts"],"names":[],"mappings":"AA2BA,OAAO,EAAE,mBAAmB,EAAE,MAAM,yCAAyC,CAAA;AAwI7E;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,oBAAoB,CAClC,IAAgE,EAChE,MAAc;IAEd,IAAI,CAAC,IAAI,CAAC,qBAAqB;QAAE,OAAO,EAAE,CAAA;IAC1C,MAAM,QAAQ,GAAG,IAAI,mBAAmB,CAAC;QACvC,qBAAqB,EAAE,IAAI,CAAC,qBAAqB;QACjD,GAAG,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE;QAC3B,MAAM;KACP,CAAC,CAAA;IACF,OAAO,EAAE,iBAAiB,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAA;AACrE,CAAC"}

package/dist/modules/execution/RunLifecycleController.d.ts

@@ -0,0 +1,141 @@
+import type { AgentFailureKind, Block, BlockRepository, Clock, ExecutionEventPublisher, ExecutionInstance, ExecutionRepository, IdGenerator, PipelineRepository, SubscriptionActivationRepository, WorkRunner } from '@cat-factory/kernel';
+import type { PreloadedBlocks } from '@cat-factory/kernel';
+import type { AgentContextBuilder } from './AgentContextBuilder.js';
+import type { RunAdmission } from './RunAdmission.js';
+import type { RunStateMachine } from './RunStateMachine.js';
+import type { RunStartOptions } from './runStartOptions.js';
+/**
+ * What the run-lifecycle surface needs. The two guards (`requireWorkspace` / `requireBlock`) and
+ * `failRun` arrive as bound call-backs, so this controller depends on no concrete guard and on no
+ * part of the state machine it does not itself drive.
+ */
+export interface RunLifecycleDeps {
+    admission: RunAdmission;
+    blockRepository: BlockRepository;
+    clock: Clock;
+    contextBuilder: AgentContextBuilder;
+    events: ExecutionEventPublisher;
+    executionRepository: ExecutionRepository;
+    idGenerator: IdGenerator;
+    pipelineRepository: PipelineRepository;
+    runStateMachine: RunStateMachine;
+    workRunner: WorkRunner;
+    subscriptionActivations?: SubscriptionActivationRepository;
+    requireWorkspace: (workspaceId: string) => Promise<unknown>;
+    requireBlock: (workspaceId: string, id: string) => Promise<Block>;
+    failRun: (workspaceId: string, executionId: string, message: string, kind?: AgentFailureKind, detail?: string | null, reason?: string | null) => Promise<void>;
+}
+/**
+ * A run's LIFECYCLE surface: every entry point that launches one (`start`), re-launches one
+ * (`retry` / `restartFromStep`), lifts a spend pause (`resumePaused`), or ends one (`cancel` /
+ * `stopRun` / `teardownForBlockTree`).
+ *
+ * They belong together because all three launch paths write the SAME two things in the SAME order:
+ * the atomic live-run claim, then the durable/SPA/outbound hand-off (both owned by `runStart.ts`,
+ * reached through the one `runStartDeps` getter below). They differ only in the block patch written
+ * between the two and in what each tears down first. Keeping that order in one place is what stops
+ * a new entry point from claiming without handing off (a run nothing drives) or announcing before
+ * the claim commits.
+ *
+ * `ExecutionService` keeps thin delegates, so no HTTP call site changed. The per-step machine
+ * (`advanceInstance` / `stepInstance`) and the human decision surface (`StepDecisionController`)
+ * deliberately stay where they are: those act on a run that is already live.
+ */
+export declare class RunLifecycleController {
+    private readonly deps;
+    constructor(deps: RunLifecycleDeps);
+    /** Start a pipeline against a block, replacing any prior run on it. */
+    start(workspaceId: string, blockId: string, pipelineId: string, options?: RunStartOptions): Promise<ExecutionInstance>;
+    /**
+     * Retry a failed run: re-drive the same pipeline on the same block, **resuming
+     * from the step that actually failed** rather than restarting from step 0. The
+     * steps that already completed are preserved (so a `coder` failure in `pl_full`
+     * doesn't re-run the human-gated `requirements`/`architect` steps before it);
+     * the failed step and everything after it are reset to a clean, re-runnable
+     * state. Only a `failed` run can be retried.
+     *
+     * A fresh instance id is minted because the durable runner addresses one
+     * Workflows instance per execution id and the failed one is terminal — the new
+     * instance simply starts with `currentStep` pointed at the failed step, so the
+     * driver advances forward from there and never re-issues the completed steps'
+     * work. Mirrors {@link BootstrapService.retry}; both are reached via the unified
+     * `POST /agent-runs/:id/retry` endpoint.
+     */
+    retry(workspaceId: string, executionId: string, 
+    /** The retrying user (their personal subscription is used for individual-usage
+     *  models). Falls back to the original initiator when omitted. */
+    initiatedBy?: string | null, 
+    /** Mint the per-run personal-credential activation (see {@link start}). */
+    activate?: (executionId: string) => Promise<void>): Promise<ExecutionInstance>;
+    /**
+     * Restart a run from a human-chosen step: re-run from `fromStepIndex` onward,
+     * regardless of how far the run had progressed (a `done`, `failed`, `blocked`,
+     * `paused` or still-`running` run are all valid sources). Unlike {@link retry}
+     * (which resumes at the first FAILURE) this rewinds to an arbitrary step the user
+     * picked — so it can re-run steps that already completed.
+     *
+     * What is preserved vs reset:
+     * - Steps BEFORE `fromStepIndex` keep their `output`/approval/timing untouched, so
+     *   the engine still hands the restarted step its predecessors' work as
+     *   `priorOutputs` (and their resolved `decisions`) — a useful handoff.
+     * - The chosen step and every later one are reset to a clean, re-runnable state,
+     *   dropping each step's iteration counters (companion attempts, gate/test attempts,
+     *   eviction recoveries) so the restart starts those loops from zero.
+     * - A block's incorporated requirements are NOT touched: they live on the
+     *   requirement-review record, so a restarted spec-writer/coder still receives the
+     *   incorporated document (or the base description when none was generated). When the
+     *   chosen step is the `requirements-review` gate ITSELF, re-running it mints a fresh
+     *   iteration-1 review (the reviewer's `review()` replaces the prior one), which is
+     *   exactly the "reset the iterations counter from this step" semantics.
+     *
+     * Like {@link retry} a fresh instance id is minted (the durable runner addresses one
+     * driver per execution id). Any still-live driver/container for the run being
+     * replaced is torn down first, so restarting a RUNNING run never orphans a container
+     * or a parked Workflows instance.
+     */
+    restartFromStep(workspaceId: string, executionId: string, fromStepIndex: number, 
+    /** The restarting user (their personal subscription is used for individual-usage
+     *  models). Falls back to the original initiator when omitted. */
+    initiatedBy?: string | null, 
+    /** Mint the per-run personal-credential activation (see {@link start}). */
+    activate?: (executionId: string) => Promise<void>): Promise<ExecutionInstance>;
+    /**
+     * The bound callbacks the two run-start funnels (`runStart.ts`) need, so they depend on no
+     * concrete repository or service. Those funnels own the ORDER between a run's atomic claim and
+     * its hand-off and are documented there; every start path calls both, writing the block state
+     * that path owns in between.
+     */
+    private get runStartDeps();
+    /**
+     * Resume every run paused by the spend safeguard in this workspace. Flips them
+     * back to `running` and re-drives the durable runner. If the budget is still
+     * exhausted the spend gate will simply pause them again on their next step.
+     */
+    resumePaused(workspaceId: string): Promise<ExecutionInstance[]>;
+    /** Cancel the run on a block, returning it to `planned`. */
+    cancel(workspaceId: string, blockId: string): Promise<Block>;
+    /**
+     * Explicitly stop a *running* run by id (the unified `POST /agent-runs/:id/stop`
+     * surface): kill its per-run container, tear down the durable driver, then record
+     * a terminal `cancelled` failure so the board shows the run stopped (with retry)
+     * rather than spinning forever. Idempotent — a run already terminal is returned
+     * as-is. `opts.reason`/`opts.kind` let the orphan sweep reuse this with its own
+     * wording instead of the user-facing default.
+     */
+    stopRun(workspaceId: string, executionId: string, opts?: {
+        reason?: string;
+        kind?: AgentFailureKind;
+    }): Promise<ExecutionInstance>;
+    /**
+     * Tear down every run under a block subtree — kill each container, terminate each
+     * durable driver, and delete the run record — so deleting a service/module never
+     * orphans a container or a Workflows instance. Best-effort and silent: the board
+     * delete that follows emits the coarse refresh, so no per-run event is needed.
+     *
+     * Returns the workspace block list it loaded so the immediately-following `removeBlock`
+     * can reuse it instead of re-listing the whole board (this teardown deletes only run
+     * records, never blocks, so the list is still current) — see {@link PreloadedBlocks}.
+     */
+    teardownForBlockTree(workspaceId: string, rootId: string): Promise<PreloadedBlocks>;
+}
+//# sourceMappingURL=RunLifecycleController.d.ts.map

package/dist/modules/execution/RunLifecycleController.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RunLifecycleController.d.ts","sourceRoot":"","sources":["../../../src/modules/execution/RunLifecycleController.ts"],"names":[],"mappings":"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"}