@cat-factory/orchestration 0.38.1 → 0.39.1

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

@@ -0,0 +1,479 @@
+import type { AgentExecutor, AgentRunContext, AgentRunResult, Block, BlockRepository, BrainstormSession, ClarityReview, Clock, ExecutionEventPublisher, ExecutionInstance, ExecutionRepository, FollowUpsStepState, GateDefinition, IdGenerator, IssueWritebackProvider, PipelineStep, ProviderCapabilities, ProvisionContext, RequirementConcernLevel, RequirementReview, ResolveRunRepoContext, RunInitiatorScope, TicketTrackerProvider, WorkRunner } from '@cat-factory/kernel';
+import type { EnvironmentProvisioningService } from '@cat-factory/integrations';
+import { AgentContextBuilder } from './AgentContextBuilder.js';
+import { CompanionController } from './CompanionController.js';
+import { HumanTestController } from './HumanTestController.js';
+import { MergeResolver } from './MergeResolver.js';
+import { ReviewGateController, type ReviewKind } from './ReviewGateController.js';
+import { RunStateMachine } from './RunStateMachine.js';
+import { StepGraph } from './StepGraph.js';
+import { TesterController } from './TesterController.js';
+import { VisualConfirmationController } from './VisualConfirmationController.js';
+import { type StepHandlerContext } from './step-handler-registry.js';
+import type { AdvanceOptions, AdvanceResult } from './advance.js';
+import type { NotificationService } from '../notifications/NotificationService.js';
+import type { SpendService } from '@cat-factory/spend';
+import type { BlueprintReconciler } from './ExecutionService.js';
+/**
+ * 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.resolveMergePreset}.
+ */
+type ResolvedMergePreset = {
+    maxComplexity: number;
+    maxRisk: number;
+    maxImpact: number;
+    ciMaxAttempts: number;
+    maxRequirementIterations: number;
+    maxRequirementConcernAllowed: RequirementConcernLevel;
+    releaseWatchWindowMinutes: number;
+    releaseMaxAttempts: number;
+    humanReviewGraceMinutes: number;
+};
+/** Collaborators + leaf dependencies the {@link RunDispatcher} needs. */
+export interface RunDispatcherDeps {
+    blockRepository: BlockRepository;
+    executionRepository: ExecutionRepository;
+    agentExecutor: AgentExecutor;
+    workRunner: WorkRunner;
+    events: ExecutionEventPublisher;
+    idGenerator: IdGenerator;
+    clock: Clock;
+    spend: SpendService;
+    stepGraph: StepGraph;
+    runStateMachine: RunStateMachine;
+    contextBuilder: AgentContextBuilder;
+    mergeResolver: MergeResolver;
+    companionController: CompanionController;
+    testerController: TesterController;
+    humanTestController: HumanTestController;
+    visualConfirmationController: VisualConfirmationController;
+    reviewGate: ReviewGateController;
+    requirementsKind: ReviewKind<RequirementReview>;
+    clarityKind: ReviewKind<ClarityReview>;
+    requirementsBrainstormKind: ReviewKind<BrainstormSession>;
+    architectureBrainstormKind: ReviewKind<BrainstormSession>;
+    runInitiatorScope: RunInitiatorScope;
+    environmentProvisioning?: EnvironmentProvisioningService;
+    ticketTrackerProvider?: TicketTrackerProvider;
+    issueWriteback?: IssueWritebackProvider;
+    notificationService?: NotificationService;
+    blueprintReconciler?: BlueprintReconciler;
+    resolveRunRepoContext?: ResolveRunRepoContext;
+    resolveProviderCapabilities?: (workspaceId: string, initiatedBy?: string | null) => Promise<ProviderCapabilities>;
+    /** Resolve a task's merge preset (stays on the engine, shared with the merge subgraph). */
+    resolveMergePreset: (workspaceId: string, block: Block) => Promise<ResolvedMergePreset>;
+    /** Whether a resolved model id incurs metered monetary cost (the start gate's predicate). */
+    modelIdIsMetered: (id: string | undefined, caps: ProviderCapabilities) => boolean;
+}
+/**
+ * The per-step dispatch + completion spine of the execution engine. It owns the four
+ * registries (step handlers, completion interceptors, post-completion / terminal resolvers,
+ * polling gates), the completion hub (`recordStepResult` / `handleAgentStep`), the gate
+ * machinery (`evaluateGate` / `dispatchGateHelper` / `pollGate` / `resolveGatePollExhaustion`),
+ * the deterministic `deployer` / `tracker` steps, the registered pre/post-op cluster, the
+ * structured-artifact ingest helpers, and the follow-up companion gate + its human-action API.
+ *
+ * Extracted out of `ExecutionService` so the handlers depend on a cohesive surface rather than
+ * a fat per-callback bag. It composes the existing collaborators ({@link RunStateMachine} /
+ * {@link StepGraph} / the five gate controllers / {@link MergeResolver}); the merge/auto-start
+ * subgraph deliberately STAYS on the engine, reached only through the injected
+ * `resolveMergePreset` callback + the {@link MergeResolver} (which itself closes over the
+ * engine's `finalizeMerge`). `ExecutionService.stepInstance` / `pollAgentJob` / `pollGate`
+ * delegate here; no behaviour changes in the move.
+ */
+export declare class RunDispatcher {
+    private readonly blockRepository;
+    private readonly executionRepository;
+    private readonly agentExecutor;
+    private readonly workRunner;
+    private readonly events;
+    private readonly idGenerator;
+    private readonly clock;
+    private readonly spend;
+    private readonly stepGraph;
+    private readonly runStateMachine;
+    private readonly contextBuilder;
+    private readonly mergeResolver;
+    private readonly companionController;
+    private readonly testerController;
+    private readonly humanTestController;
+    private readonly visualConfirmationController;
+    private readonly reviewGate;
+    private readonly requirementsKind;
+    private readonly clarityKind;
+    private readonly requirementsBrainstormKind;
+    private readonly architectureBrainstormKind;
+    private readonly runInitiatorScope;
+    private readonly environmentProvisioning?;
+    private readonly ticketTrackerProvider?;
+    private readonly issueWriteback?;
+    private readonly notificationService?;
+    private readonly blueprintReconciler?;
+    private readonly resolveRunRepoContext?;
+    private readonly resolveProviderCapabilities?;
+    private readonly resolveMergePreset;
+    private readonly modelIdIsMetered;
+    /** Lazily-built polling-gate registry, keyed by `agentKind`. See {@link gateFor}. */
+    private gateRegistryCache?;
+    /** Lazily-built post-completion resolver registry, keyed by `agentKind`. */
+    private stepResolverCache?;
+    /** Lazily-built, order-sorted per-step-kind handler list. See {@link dispatchStepHandler}. */
+    private stepHandlerCache?;
+    /** Lazily-built, order-sorted completion-path interceptor list. */
+    private stepCompletionInterceptorCache?;
+    constructor(deps: RunDispatcherDeps);
+    /**
+     * The generic container/inline-agent step — the lowest-priority StepHandler, claiming
+     * every step no more-specific handler did (coder, architect, spec-writer, merger,
+     * task-estimator, the container-backed companions, …). Builds the agent context, runs the
+     * kind's pre-ops, then either dispatches an async container job and parks (the durable
+     * driver polls between sleeps) or runs the inline LLM call and records the result. This is
+     * what the dispatch chain falls through to; all the deterministic / gate / inline-review
+     * kinds are claimed earlier by their own handlers (see {@link buildStepHandlerRegistry}).
+     */
+    private handleAgentStep;
+    /**
+     * Preview the model a step will run (`provider:model`) ahead of the work, so the
+     * board can show it during the inline query / container cold-boot rather than only
+     * once the result or job handle lands. Best-effort: the executor may not implement
+     * a preview, and a resolution failure (e.g. an unwired container kind that fails at
+     * dispatch anyway) must never break the run — both yield undefined.
+     */
+    previewStepModel(context: AgentRunContext): Promise<string | undefined>;
+    /**
+     * Whether the current step incurs NO metered monetary LLM cost, so the spend gate can
+     * let it proceed even when the budget is exhausted. Two non-metered cases:
+     *  - a flat-rate SUBSCRIPTION (quota) model — Claude Code / Codex on a pooled token;
+     *    resolved through the executor (the authority on "subscriptions always win").
+     *  - a LOCAL-runner model (Ollama / LM Studio / …) — keyless, runs on the user's own
+     *    endpoint, so it costs the deployment nothing; detected off the resolved model id.
+     * This is what makes a `0` budget mean "no PAID spend" without bricking a workspace that
+     * deliberately runs only local models or subscriptions (see the spend-budget docs).
+     *
+     * Once the executor resolves the step's concrete model id, the metered/non-metered
+     * decision is delegated to the SAME {@link modelIdIsMetered} predicate the up-front
+     * {@link assertBudgetAllowsPipeline} gate uses, so the two gates can't classify a model
+     * differently (a divergence would let a run pass the start gate then immediately pause,
+     * or vice versa). The executor's `isQuotaBased` is still consulted first as the
+     * authoritative subscription-routing signal; the shared predicate covers local-runner +
+     * subscription-by-capability + Cloudflare classification identically to the start gate.
+     * Falls back to a bare local-id check when no capability resolver is wired.
+     *
+     * Best-effort and side-effect-free: an executor without the capability, a missing block,
+     * or any resolution error all report false (treated as budget-metered, the prior
+     * behaviour). Only consulted on the over-budget path, so it never touches the happy path.
+     */
+    currentStepIsNonMetered(workspaceId: string, instance: ExecutionInstance, step: ExecutionInstance['steps'][number]): Promise<boolean>;
+    /**
+     * Poll the asynchronous job a parked step dispatched. Returns `awaiting_job`
+     * while it runs (the driver keeps polling), records the result and advances on
+     * success, or reports `job_failed` so the driver can fail the run. Reading run
+     * state from storage on every call keeps it safe under Workflows replay/retry:
+     * once a job's result is recorded the step's `jobId` is cleared, so a re-poll
+     * simply lets the driver advance the now-current step.
+     */
+    pollAgentJob(workspaceId: string, executionId: string): Promise<AdvanceResult>;
+    /**
+     * Re-run a polling gate step's precheck from the durable driver's `awaiting_gate`
+     * loop: which gate (ci / conflicts) is resolved from the current step's `agentKind`,
+     * and it returns the same outcomes as the initial evaluation (precheck passes →
+     * advance, still computing → keep polling, fails → dispatch a helper or give up).
+     * Safe under replay: reads run state fresh each call. A no-op unless the current
+     * step is a gate actively in its `checking` phase.
+     */
+    pollGate(workspaceId: string, executionId: string): Promise<AdvanceResult>;
+    /**
+     * Decide what happens when the durable driver's GATE poll budget (ciMaxPolls ×
+     * ciPollInterval) is spent while a gate is still `pending` — called by both runtime
+     * drivers (Cloudflare ExecutionWorkflow / Node `driveExecution`) instead of failing
+     * the run directly, so the per-gate policy lives in one place. Most gates `fail`
+     * (CI never went green / the PR never became mergeable). A time-windowed watch gate
+     * (post-release-health, `pollExhaustion: 'pass'`) instead PASSES: the watch window
+     * simply outlasted the poll budget with no regression observed, which is healthy — not
+     * a timeout. Returns the result the driver should act on (it never re-fails for a fail
+     * gate; it returns a `job_failed` the driver funnels through its single `failRun`).
+     */
+    resolveGatePollExhaustion(workspaceId: string, executionId: string): Promise<AdvanceResult>;
+    /**
+     * 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).
+     */
+    private attachEnvironmentProjection;
+    /**
+     * Finish a gated step that was skipped (its estimate gate was not satisfied) and either
+     * complete the run or advance to the next step — the deterministic finish/advance tail
+     * of {@link recordStepResult}, minus all the agent-result handling (no LLM ran, so there
+     * is no usage / decision / PR / artifact / approval / resolver to process). The step is
+     * marked `skipped` with empty output so the UI renders "skipped (gated)".
+     */
+    skipGatedStep(workspaceId: string, instance: ExecutionInstance, step: PipelineStep, isFinalStep: boolean): Promise<AdvanceResult>;
+    /**
+     * Record a completed agent step's result and report what the driver should do
+     * next: meter token usage, park on a raised decision, or persist the output
+     * (and any opened PR) and either finish the run or advance to the next step.
+     * Shared by the inline path and the async-job poll path.
+     */
+    private recordStepResult;
+    /**
+     * Deterministically provision an ephemeral environment for a deployer step.
+     * Produces a human-readable summary as the step output and reports no token
+     * usage (it incurs no LLM cost). Errors are swallowed into the output unless
+     * the durable driver wants them surfaced for its per-step retry.
+     */
+    private runDeployer;
+    /**
+     * File a tracking issue/ticket for a `tracker` step from the preceding `analysis`
+     * output. Non-LLM and best-effort: when no provider is wired or none is configured
+     * for the workspace it simply notes the skip; a filing error is folded into the
+     * step output rather than failing the run (the implementation still proceeds).
+     */
+    private runTracker;
+    /**
+     * The polling-gate registry, keyed by `agentKind`. A gate runs a programmatic
+     * precheck against a provider and only escalates to a helper container agent on a
+     * negative verdict. Built lazily (the closures capture `this`, so the providers /
+     * merge preset / notification helpers resolve at call time) and cached per instance.
+     * The registry merges deployment-registered gates ({@link registeredGateFactories}),
+     * which are a STARTUP import side effect — a gate registered after this cache is first
+     * built is invisible to this instance, so register at startup, before serving. Returns
+     * undefined for a non-gate kind. See {@link GateDefinition} and {@link evaluateGate}.
+     */
+    gateFor(agentKind: string): GateDefinition | undefined;
+    /**
+     * Resolve the concrete branch a registered kind's pre/post-op reads or writes, from
+     * its declared clone target — mirroring the container executor's mapping so a backend
+     * op and the container agent operate on the SAME branch:
+     *   - `base` → the repo default branch (the ONLY way a committing op targets `main`).
+     *   - `pr`   → the block's PR branch (the coder's branch); when no PR is open, the
+     *              per-block work branch (created from base if missing) — NOT base, so a
+     *              committing post-op can't silently land on the default branch.
+     *   - `work` (default) → the per-block work branch, ENSURED to exist exactly as
+     *              {@link ContainerAgentExecutor}'s `ensureWorkBranch` does. The old code
+     *              returned base here whenever no PR was open yet, diverging from the
+     *              container agent (which clones `cat-factory/<blockId>`) and letting a
+     *              post-op commit onto the default branch.
+     * The work-branch name (`cat-factory/<blockId>`) is the same convention
+     * {@link ContainerAgentExecutor} uses.
+     */
+    private resolveRepoOpBranch;
+    /**
+     * Ensure the per-block work branch `cat-factory/<blockId>` exists — creating it from the
+     * repo default branch's head when absent — and return it. The checkout-free analogue of
+     * {@link ContainerAgentExecutor}'s `ensureWorkBranch`, so a backend pre/post-op writes
+     * the SAME branch the container agent does instead of the default branch. Falls back to
+     * the base branch only when the repo has no default-branch head to fork from (an empty
+     * repo), so the caller always gets a real branch.
+     */
+    private ensureWorkBranch;
+    /**
+     * Run a registered kind's PRE-op hooks before its agent step dispatches: deterministic
+     * backend work (read a baseline artifact into the prompt, etc.) over a checkout-free
+     * {@link RepoFiles}. No-op for built-in / unregistered kinds, when the kind declares no
+     * pre-ops, or when GitHub isn't wired (no `resolveRunRepoContext`) — so the engine runs
+     * unchanged without the feature. A throwing op propagates to fail the step.
+     */
+    private runRegisteredPreOps;
+    /**
+     * Resolve a block's run-repo context for its pre/post-op hooks. Returns null only when
+     * the resolver is UNWIRED (tests / GitHub not connected) so a deployment without the
+     * feature simply skips the hooks. When the resolver IS wired, its result — including a
+     * THROW from `resolveRepoTarget` for a block that isn't under a linked service — is
+     * propagated as-is: a registered kind with repo hooks run on a misconfigured block fails
+     * the run loudly rather than silently committing nothing (or guessing a repo), the same
+     * way a container custom kind fails at dispatch.
+     */
+    private resolveRunRepo;
+    /**
+     * Run a registered kind's POST-op hooks after its agent step's result is recorded:
+     * deterministic backend work that consumes the agent's structured output (coerce its
+     * JSON, render artifact files, commit them via {@link RepoFiles}) — the
+     * blueprint/spec rendering that used to live in the harness. Same gating + symmetry as
+     * {@link runRegisteredPreOps}; the agent's {@link AgentRunResult} is threaded through.
+     */
+    private runRegisteredPostOps;
+    /**
+     * The BUILT-IN (non-registry) post-ops for a migrated built-in kind, keyed by agent
+     * kind — the deterministic render + commit lifted out of the executor-harness. Kept
+     * OUT of the agent-kind registry on purpose: registering the built-ins would leak them
+     * into `customAgentKinds` / the SPA palette. Empty for every other kind.
+     */
+    private builtInPostOps;
+    /**
+     * The built-in (NON-registry) post-ops keyed by kind. A small map rather than an
+     * `if`-chain so each migrated built-in is one entry as the strangler converts more
+     * kinds; deliberately NOT the agent-kind registry (that would leak the built-ins into
+     * `customAgentKinds` / the SPA palette).
+     */
+    private static readonly BUILT_IN_POST_OPS;
+    /**
+     * The branch a built-in kind's post-op reads/commits, resolved to MATCH the kind's
+     * container dispatch (so the post-op commits onto exactly the branch the explore agent
+     * cloned).
+     *  - blueprints clones the PR branch when one is open, else the repo's default branch —
+     *    so the initial bootstrap map lands directly on the default branch, mirroring
+     *    {@link ContainerAgentExecutor}'s `pr`-clone resolution (`prBranch ?? baseBranch`).
+     *    Deliberately NOT {@link resolveRepoOpBranch}, whose `pr` case ensures a work branch
+     *    for the no-PR case — correct for a committing CUSTOM kind, wrong for the blueprint.
+     *  - spec-writer commits onto the per-block WORK branch (`cat-factory/<blockId>`), created
+     *    from base when absent. It is a WRITER (not read-only), so its container dispatch
+     *    always ensures + clones that work branch ({@link ContainerAgentExecutor}'s
+     *    `workBranchReady ? workBranch : …` resolves to the work branch). We mirror that
+     *    DETERMINISTICALLY here — NOT via {@link resolveRepoOpBranch}'s `work` case, whose
+     *    PR-preferring branch would commit onto a divergent PR branch (read one tree, write
+     *    another) if a PR were ever open on a branch other than `cat-factory/<blockId>`.
+     */
+    private builtInRepoOpBranch;
+    /**
+     * The post-completion resolver for an agent kind, or undefined when the kind has none.
+     * A resolver runs DETERMINISTIC backend follow-up once the step's agent finishes — e.g.
+     * the merger performs the real GitHub merge — independent of the step's position in the
+     * pipeline. Built lazily (closures capture `this`) and cached per instance; the registry
+     * merges deployment-registered resolvers ({@link registeredStepResolverFactories}), a
+     * 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: StepHandlerContext): Promise<AdvanceResult>;
+    /**
+     * 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`.
+     */
+    private buildStepHandlerRegistry;
+    /**
+     * Run the first completion-path interceptor that claims this finished step, returning its
+     * short-circuit {@link AdvanceResult} (the companion verdict loop / tester re-test) or
+     * `null` to let `recordStepResult`'s normal finish/advance spine run. Engine-internal,
+     * mirroring {@link dispatchStepHandler}.
+     */
+    private dispatchStepCompletionInterceptor;
+    /**
+     * Build the order-sorted completion-path interceptors (companion / tester verdict
+     * short-circuits), mirroring {@link buildStepHandlerRegistry} — built-ins constructed
+     * inline closing over `this`, no public registration seam.
+     */
+    private buildStepCompletionInterceptors;
+    private stepResolverFor;
+    private buildStepResolverRegistry;
+    /** The shared engine seams handed to a deployment-registered step resolver's factory. */
+    private makeResolverContext;
+    private buildGateRegistry;
+    /** The shared engine seams handed to a deployment-registered gate's factory. */
+    private makeGateContext;
+    /**
+     * Evaluate a polling gate step once and decide (shared by the initial advance and the
+     * durable `awaiting_gate` re-poll):
+     *   - no provider wired → pass-through (advance; nothing to gate);
+     *   - precheck passes   → advance to the next step (the helper agent is NEVER spun up);
+     *   - still computing   → `awaiting_gate` (the driver sleeps then calls {@link pollGate});
+     *   - fails, budget left → dispatch the helper container agent (`awaiting_job`);
+     *   - fails, budget spent → the gate's exhaustion handler, then fail the run.
+     */
+    private evaluateGate;
+    /**
+     * Dispatch a gate's helper container agent on a failed precheck: build the agent
+     * context with the kind overridden to the helper (it clones the PR head branch and
+     * pushes — no new PR), park on the job, and flip the gate to `working`. Idempotent
+     * under replay via the step's `jobId` (re-attach handled in {@link evaluateGate}).
+     */
+    private dispatchGateHelper;
+    /**
+     * Append the items the harness streamed since the last poll onto the Coder step's
+     * follow-up state as fresh `pending` items. A no-op when the companion is off or nothing
+     * was streamed. Returns whether anything was added (so the poller persists + emits).
+     */
+    private appendStreamedFollowUps;
+    /**
+     * The Follow-up companion gate, evaluated when the Coder step completes: park the run on
+     * a durable decision while any item is undecided; else loop the Coder for the queued /
+     * answered items (within the budget); else fall through (return undefined) so the normal
+     * advance/finish logic runs. Returns an {@link AdvanceResult} only when it parks or loops.
+     */
+    private evaluateFollowUpGate;
+    /**
+     * Reset the Coder step and fold the human's queued follow-ups / answered questions into
+     * its rework so the next pass extends the prior work. Marks those items `sentToCoder` so
+     * a later completion doesn't re-loop them, and counts the loop against the budget. Shared
+     * by the at-completion path ({@link evaluateFollowUpGate}) and the parked-resume path.
+     */
+    private loopCoderForFollowUps;
+    /** Raise the "follow-ups need decisions" inbox card when the Coder parks on undecided items. */
+    private raiseFollowUpPending;
+    /**
+     * The run's "active" follow-up companion step for a read with no item context (the GET /
+     * the inbox-card open). A pipeline may carry MORE THAN ONE follow-up-enabled Coder step,
+     * so this must not blindly pick the first: prefer the step the run is currently on (a Coder
+     * parked on its follow-up gate), else the latest enabled step that has surfaced items, else
+     * the first enabled one.
+     */
+    private activeFollowUpStep;
+    /** Read a run's live follow-up companion state (the active Coder step's items), or null. */
+    getFollowUps(workspaceId: string, executionId: string): Promise<FollowUpsStepState | null>;
+    /**
+     * Locate the run + the Coder step that OWNS the addressed item + the item, throwing 404
+     * when absent. Routes by item id (not "the first enabled step") so a pipeline carrying more
+     * than one follow-up-enabled Coder step decides each item on the step that surfaced it —
+     * otherwise a later Coder's items 404 and its gate can never be cleared.
+     */
+    private loadFollowUpItem;
+    /** File a `follow_up` item as a tracker issue (GitHub / Jira), recording the ticket ref. */
+    fileFollowUp(workspaceId: string, executionId: string, itemId: string): Promise<FollowUpsStepState>;
+    /** Queue a `follow_up` item to send back to the Coder on its next pass. */
+    queueFollowUp(workspaceId: string, executionId: string, itemId: string): Promise<FollowUpsStepState>;
+    /** Answer a `question` item; the answer is folded into the Coder's next pass. */
+    answerFollowUp(workspaceId: string, executionId: string, itemId: string, answer: string): Promise<FollowUpsStepState>;
+    /** Dismiss a follow-up / question item without acting on it. */
+    dismissFollowUp(workspaceId: string, executionId: string, itemId: string): Promise<FollowUpsStepState>;
+    /**
+     * Persist an item decision and, when the run is PARKED on this step's follow-up gate and
+     * every item is now decided, drive it forward: loop the Coder for the queued / answered
+     * items (within the budget), else advance past the gate. When the run is not parked (the
+     * Coder is still running, or it already moved on) this only persists + emits the change.
+     */
+    private driveFollowUpsAfterDecision;
+    /** 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;
+    /**
+     * Invoke the agent for an already-built context. Failures are swallowed into the
+     * step output so a run never wedges — unless `rethrowAgentErrors` is set (the
+     * durable path), in which case the error propagates so the driver's per-step
+     * retry can take over.
+     */
+    runAgent(context: AgentRunContext, options?: AdvanceOptions): Promise<AgentRunResult>;
+    /**
+     * Strictly parse a Blueprinter step's tree and reconcile it onto the board. The
+     * blueprint maps the whole repository, so it is reconciled onto the run block's
+     * **service frame** (walked up from the block), not the task the run targeted.
+     * Best-effort and reconciler-gated: a parse/reconcile failure is logged-by-throw
+     * upstream only when the reconciler is wired; with no reconciler it is a no-op so
+     * the blueprint's in-repo files still land.
+     */
+    private ingestBlueprint;
+    /**
+     * Strictly validate a spec-writer step's unified specification. The canonical record
+     * is the in-repo `spec/` files the harness already committed; this is the trust
+     * boundary (a malformed payload is dropped, never trusted) plus a client refresh
+     * nudge. A persisted board projection is a deliberate later phase.
+     */
+    private ingestSpec;
+}
+export {};
+//# sourceMappingURL=RunDispatcher.d.ts.map

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

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