@cat-factory/orchestration 0.123.4 → 0.123.5

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

@@ -0,0 +1,185 @@
+import type { AgentRunResult, Block, BlockRepository, ContainerEvictionKind, ExecutionInstance, PipelineStep, ProvisionContext } from '@cat-factory/kernel';
+import type { EnvironmentProvisioningService } from '@cat-factory/integrations';
+import type { AgentContextBuilder } from './AgentContextBuilder.js';
+import type { RunStateMachine } from './RunStateMachine.js';
+import type { AdvanceResult } from './advance.js';
+/**
+ * Collaborators + the {@link RunDispatcher} seams the deployer step family needs. The
+ * completion hub (`recordStepResult`) and the shared poll folds / eviction recovery stay on
+ * the dispatcher (the agent path uses them too) and are injected as callbacks, so the two
+ * paths can't drift on budgets or fold semantics.
+ */
+export interface DeployerStepControllerDeps {
+    blockRepository: BlockRepository;
+    contextBuilder: AgentContextBuilder;
+    runStateMachine: RunStateMachine;
+    environmentProvisioning?: EnvironmentProvisioningService;
+    recordStepResult: (workspaceId: string, instance: ExecutionInstance, step: PipelineStep, isFinalStep: boolean, result: AgentRunResult) => Promise<AdvanceResult>;
+    applyContainerRunning: (step: PipelineStep, update: {
+        phase?: string;
+        container?: {
+            id?: string;
+            url?: string;
+        };
+    }) => boolean;
+    applySubtaskProgress: (step: PipelineStep, counts: PipelineStep['subtasks']) => boolean;
+    recoverContainerEviction: (workspaceId: string, instance: ExecutionInstance, step: PipelineStep, error: string | undefined, evicted: ContainerEvictionKind | undefined, onBeforeRedispatch?: () => Promise<void>) => Promise<AdvanceResult | null>;
+}
+/**
+ * The deterministic `deployer` step family, extracted out of {@link RunDispatcher}: the
+ * multi-frame provision fan-out (own frame + involved-service peers, provider-before-consumer),
+ * the async container-backed deploy-job poll, the per-frame settle/failure bookkeeping on
+ * `step.deployEnvs`, and the environment projection every env-aware step surfaces on its run
+ * details. No LLM and no token usage anywhere in this family — the deployer provisions
+ * environments through the {@link EnvironmentProvisioningService} provider only. Pure code
+ * movement from the dispatcher; no behaviour changes.
+ */
+export declare class DeployerStepController {
+    private readonly blockRepository;
+    private readonly contextBuilder;
+    private readonly runStateMachine;
+    private readonly environmentProvisioning?;
+    private readonly recordStepResult;
+    private readonly applyContainerRunning;
+    private readonly applySubtaskProgress;
+    private readonly recoverContainerEviction;
+    constructor(deps: DeployerStepControllerDeps);
+    /**
+     * Stamp `step.environment` from the block's live ephemeral environment so a run's
+     * details show its spinning-up / running / shut-down / errored state + the exact
+     * error. Best-effort: a no-op when the env integration isn't wired, and never
+     * throws (a projection failure must not break the run). Returns whether it changed,
+     * so the poll path can fold it into its single emit. The `human-test` gate keeps
+     * its own `humanTest.environment`, so this is for the other env-consuming steps
+     * (tester/coder/deployer).
+     */
+    attachEnvironmentProjection(workspaceId: string, blockId: string, step: PipelineStep, frameId?: string): Promise<boolean>;
+    /**
+     * Deterministically provision an ephemeral environment for a `deployer` step and turn the
+     * outcome into the step's advance result (no LLM, no token usage). On success the env
+     * summary is recorded as the step output. On a provisioning failure — the provider threw
+     * OR returned `status:'failed'` — the breakage is surfaced as a real, DISPLAYED step
+     * failure rather than a green step with the error buried in its prose output: `step.environment`
+     * is stamped with the errored env (its `lastError` renders in the step's Environment panel)
+     * and a structured `environment` failure is returned (the board's failure card). A deployer
+     * that can't provision IS failed — the downstream tester/coder steps need that environment.
+     *
+     * The failure is TERMINAL and surfaced for a human/`Retry`, NOT auto-retried by the durable
+     * driver — DELIBERATELY, and symmetric with `handleAgentStep`'s dispatch-failure path
+     * (a container that never started is likewise terminal regardless of `rethrowAgentErrors`).
+     * Environment provisioning is infra spin-up, not agent execution: treating it like the
+     * `dispatch` failure (surface the verbatim cause + one-click retry) keeps the `environment`
+     * classification and the provider's real error visible, where rethrowing for the driver's
+     * per-step retry would re-collapse it into a generic `agent` failure on exhaustion and bury
+     * the root cause. So do NOT reintroduce a `rethrowAgentErrors` branch here.
+     */
+    runDeployerStep(workspaceId: string, instance: ExecutionInstance, step: PipelineStep, block: Block, isFinalStep: boolean): Promise<AdvanceResult>;
+    /**
+     * Advance a `deployer` fan-out over its already-resolved `targets`: dispatch the first un-settled
+     * frame (parking on an async deploy job) or, once every frame has settled, complete the step. One
+     * deploy job per frame, dispatched SEQUENTIALLY (parking between) so a later provider can receive
+     * the already-ready peers' URLs. `step.deployEnvs` records each frame's TERMINAL outcome, so a
+     * replay resumes at the first un-settled frame. Re-entered (with the SAME targets) after each
+     * synchronous/infraless/failed-peer frame settles — never re-reading the block list per frame.
+     */
+    private advanceDeployerFrames;
+    /**
+     * Resolve the ordered set of service frames a `deployer` step provisions environments for: the
+     * task's OWN service frame (always, `isPrimary`) plus each involved-service frame (read-time
+     * stale-filtered to ids that are still a connection neighbour AND resolve to a `service` frame
+     * WITH declared provisioning — an involved frame with none stands nothing up here). Ordered
+     * PROVIDER-before-CONSUMER over the connection edges among the targets (see
+     * {@link orderProvisionTargets}) so a later provision can receive its ready peers' URLs. One
+     * workspace block-list read; no per-frame point read.
+     *
+     * `pinnedPrimaryFrameId` (from {@link PipelineStep.deployPrimaryFrameId}, set on the first
+     * resolution) keeps the OWN/primary frame STABLE across re-entries: once the fan-out has started,
+     * a mid-flight reparent must not re-classify which frame is primary — that would flip an
+     * own-frame failure from terminal to a non-terminal peer failure. Prefer the pinned frame when it
+     * still resolves; fall back to a fresh `frameOf` walk otherwise.
+     */
+    private resolveDeployTargets;
+    /**
+     * Record one frame's TERMINAL deploy outcome onto `step.deployEnvs`, then continue the fan-out.
+     * A `ready` handle records the env and re-enters {@link advanceDeployerFrames} for the next
+     * frame; a `failed` handle routes to {@link settleDeployerFailure} (terminal only for the own
+     * frame). Shared by the synchronous-provision and async-finalized paths.
+     */
+    private settleDeployerFrame;
+    /**
+     * Record a frame's FAILED deploy outcome and decide whether it is terminal. The task's OWN
+     * (primary) service frame failing fails the whole deploy step (unchanged from the single-env
+     * path). An involved PEER frame failing is NON-terminal — the peer's env is best-effort context
+     * enrichment, so the run proceeds to the remaining frames without that peer's URL rather than
+     * failing a task because a service it merely "involves" has a misconfigured provider. The failed
+     * outcome is still recorded (surfaced in {@link completeDeployerStep}).
+     */
+    private settleDeployerFailure;
+    /**
+     * Poll a `deployer` step's dispatched CONTAINER-backed deploy job (the async kustomize/helm
+     * path) through the environment provisioning service — NOT the agent executor. Mirrors
+     * `pollAgentJob`: surfaces live container/subtask progress while running, recovers a
+     * container eviction by re-dispatching a fresh deploy job (within the same budgets), and on a
+     * genuine terminal state finalizes the job into an environment record + the step result.
+     */
+    pollDeployerJob(workspaceId: string, instance: ExecutionInstance, step: PipelineStep): Promise<AdvanceResult>;
+    /**
+     * The {@link ProvisionArgs} for provisioning ONE target frame's environment (synchronous or
+     * async). The env is keyed by the task `block.id` + the target `frameId` — so a task's own env
+     * and each involved-service env coexist under the same block, discriminated by frame (see the
+     * per-`(blockId, frameId)` supersede). The repo/clone the provider resolves is the TARGET
+     * FRAME's (via `frameId`), so an involved-service env clones that peer's repo at its default
+     * branch, while the OWN frame targets the task's PR branch (its git/PR context); a peer carries
+     * no PR context. The `{{input.*}}` identity (blockId/title/…) is the TARGET FRAME's for a peer
+     * (see {@link deployTargetInputs}) so each peer's provider namespace is distinct — the task-
+     * scoped inputs would collapse every peer onto one namespace. Injects `frontendOrigins` (the
+     * browser origins binding this service) and `peerEnvUrls` (the already-ready peers) too.
+     */
+    private deployerProvisionArgs;
+    /**
+     * The `{{input.*}}` identity a target frame provisions with. The OWN frame keeps the historical
+     * task-scoped inputs (its namespace is uniquified by the task's PR repo/number). An involved PEER
+     * frame is scoped to the PEER FRAME's identity, with a `(task, peer)` composite `blockId` — so
+     * the provider namespace derived from `{{input.blockId}}` is distinct per peer AND per task,
+     * where the task-scoped inputs would collapse every peer of a task onto ONE namespace (each
+     * clobbering the previous, teardown deleting the wrong one).
+     */
+    private deployTargetInputs;
+    /**
+     * The `frontendOrigins` provision input for a service frame: the comma-joined browser origins
+     * of every `frontend` frame that binds this service (see `frontendOriginsForService`), for a
+     * manifest to fold into the backend's CORS allow-list via `{{input.frontendOrigins}}`. Empty
+     * string when no frontend binds it (the key is then omitted). One workspace block-list read —
+     * no per-frame point read (mirrors the visual-pipeline gate).
+     */
+    frontendOriginsInput(workspaceId: string, serviceFrameId: string): Promise<string>;
+    /**
+     * Turn a provisioned environment handle into the `deployer` step's advance result: a `failed`
+     * env is surfaced as a displayed step failure (its `lastError` renders in the Environment
+     * panel); otherwise the env summary (status / URL / provision type / engine) is recorded as the
+     * step output. Shared by the synchronous and async-finalized provision paths.
+     */
+    private completeDeployerStep;
+    /**
+     * Resolve the SERVICE frame's declared provisioning for a run block. The run may target a
+     * task/module nested under the frame, so walk up to the frame (mirrors the blueprint /
+     * tester-gate resolution) and read its `provisioning`. Returns null when undeclared.
+     */
+    private resolveServiceProvisioning;
+    /**
+     * Stamp the errored environment onto the deployer step (so its details show the verbatim
+     * `lastError`), persist + emit, then return a structured `environment` failure carrying the
+     * provider's message as the detail. Mirrors `handleAgentStep`'s dispatch-failure path.
+     */
+    private failDeployerStep;
+    /** Provision inputs (`{{input.*}}`) derived from the block under deployment. */
+    deployInputs(block: Block): Record<string, string>;
+    /**
+     * Typed git/PR/repo context for the deployer, derived from the block's PR ref. A
+     * PR-environment provider (e.g. an in-house adapter) needs the branch/repo to target
+     * the right environment; the same values are also flattened into `{{input.*}}` for
+     * the manifest path. `owner`/`repo` are parsed from the PR url when present.
+     */
+    deployContext(block: Block): ProvisionContext;
+}
+//# sourceMappingURL=DeployerStepController.d.ts.map

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

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