@cat-factory/orchestration 0.37.0 → 0.37.1

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

@@ -0,0 +1,70 @@
+import type { Clock, ExecutionInstance, PipelineStep } from '@cat-factory/kernel';
+/**
+ * The pure, synchronous step/cursor mutators of the execution engine — the dependency-free
+ * inner layer of the run state-machine spine. Every method operates on a passed
+ * {@link PipelineStep} / {@link ExecutionInstance} and mutates it in place; the only
+ * collaborator is the {@link Clock} the timing stamps come from. Lifted verbatim out of
+ * `ExecutionService` so the engine AND every gate controller share ONE definition of "what
+ * does it mean to start / finish / park / reset a step" instead of each receiving the
+ * mutators as a loose callback bag.
+ *
+ * Deliberately holds NO repositories, event publisher or runner — those async,
+ * instance-persisting concerns live in {@link RunStateMachine}, which composes this. Keeping
+ * the pure mutators separate is what lets a controller depend on the timing rules without
+ * pulling in the whole persistence/emission surface.
+ */
+export declare class StepGraph {
+    private readonly clock;
+    constructor(clock: Clock);
+    /** Transition a step into `working`, stamping its start time once, and resume its clock. */
+    startStep(step: PipelineStep): void;
+    /**
+     * Transition a step into `done`, stamping its finish time once. Set-once so the
+     * approval-gate flow (which re-asserts `done` after a human approves, long after
+     * the agent actually finished) keeps the agent's true completion time, and so a
+     * replay doesn't move it. With {@link startStep}'s `startedAt` this yields the
+     * step's execution duration. A step finished directly out of a parked approval
+     * stopped *working* when it parked, so its duration is billed to the pause instant
+     * ({@link pauseStepForInput}), not the (later) moment the human decided.
+     */
+    finishStep(step: PipelineStep): void;
+    /**
+     * Park a step on a human decision and freeze its duration clock. Records when the
+     * step stopped working (`pausedAt`) so elapsed time no longer accrues while it waits
+     * for input — the symmetric counterpart of the terminal freeze on `finishedAt`.
+     * Set-once (a Workflows replay re-parking keeps the original instant); cleared when
+     * the step resumes ({@link startStep}) or finishes ({@link finishStep}).
+     */
+    pauseStepForInput(step: PipelineStep): void;
+    /**
+     * Reset a step so the durable driver re-runs it from scratch: clear its live container
+     * job handle (so it dispatches FRESH work rather than re-attaching to a stale/evicted
+     * job), timings, approval, subtasks and prior output.
+     */
+    resetStepForRerun(step: PipelineStep): void;
+    /**
+     * Loop a producer step back for rework and re-run every step from it up to and
+     * including the companion at `companionIndex`: each one is reset (crucially clearing
+     * stale container job handles so an intermediate container step re-dispatches fresh
+     * work instead of re-attaching to its evicted job), the producer is handed the
+     * `rework` feedback + started, and the instance cursor is moved back to the producer.
+     * Shared by the automatic companion loop and the human "request changes" path.
+     */
+    rerunProducerThrough(instance: ExecutionInstance, producerIndex: number, companionIndex: number, rework: NonNullable<PipelineStep['rework']>): void;
+    /**
+     * The index of the nearest preceding step a companion grades (one of its target
+     * producer kinds), or -1 when none precedes it. The single producer-search used by the
+     * automatic companion loop, the human "request changes" redirect, and the iteration-cap
+     * extra-round resolution.
+     */
+    companionProducerIndex(instance: ExecutionInstance, companionIndex: number): number;
+    /**
+     * Loop a companion's producer back for one more automatic rework cycle: charge one
+     * attempt against the budget, then re-run the producer (and any intermediate steps) up
+     * to and including the companion so it re-grades. Shared by the automatic
+     * below-threshold loop and the human-granted extra round, so both consume the budget
+     * identically.
+     */
+    loopCompanionProducer(instance: ExecutionInstance, companionIndex: number, rework: NonNullable<PipelineStep['rework']>): void;
+}
+//# sourceMappingURL=StepGraph.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"StepGraph.d.ts","sourceRoot":"","sources":["../../../src/modules/execution/StepGraph.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAGjF;;;;;;;;;;;;;GAaG;AACH,qBAAa,SAAS;IACR,OAAO,CAAC,QAAQ,CAAC,KAAK;IAAlC,YAA6B,KAAK,EAAE,KAAK,EAAI;IAE7C,4FAA4F;IAC5F,SAAS,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,CAMlC;IAED;;;;;;;;OAQG;IACH,UAAU,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,CAInC;IAED;;;;;;OAMG;IACH,iBAAiB,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,CAG1C;IAED;;;;OAIG;IACH,iBAAiB,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,CAc1C;IAED;;;;;;;OAOG;IACH,oBAAoB,CAClB,QAAQ,EAAE,iBAAiB,EAC3B,aAAa,EAAE,MAAM,EACrB,cAAc,EAAE,MAAM,EACtB,MAAM,EAAE,WAAW,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC,GAC1C,IAAI,CAQN;IAED;;;;;OAKG;IACH,sBAAsB,CAAC,QAAQ,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,GAAG,MAAM,CAMlF;IAED;;;;;;OAMG;IACH,qBAAqB,CACnB,QAAQ,EAAE,iBAAiB,EAC3B,cAAc,EAAE,MAAM,EACtB,MAAM,EAAE,WAAW,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC,GAC1C,IAAI,CAMN;CACF"}

package/dist/modules/execution/StepGraph.js

@@ -0,0 +1,124 @@
+import { companionTargets } from '@cat-factory/agents';
+/**
+ * The pure, synchronous step/cursor mutators of the execution engine — the dependency-free
+ * inner layer of the run state-machine spine. Every method operates on a passed
+ * {@link PipelineStep} / {@link ExecutionInstance} and mutates it in place; the only
+ * collaborator is the {@link Clock} the timing stamps come from. Lifted verbatim out of
+ * `ExecutionService` so the engine AND every gate controller share ONE definition of "what
+ * does it mean to start / finish / park / reset a step" instead of each receiving the
+ * mutators as a loose callback bag.
+ *
+ * Deliberately holds NO repositories, event publisher or runner — those async,
+ * instance-persisting concerns live in {@link RunStateMachine}, which composes this. Keeping
+ * the pure mutators separate is what lets a controller depend on the timing rules without
+ * pulling in the whole persistence/emission surface.
+ */
+export class StepGraph {
+    clock;
+    constructor(clock) {
+        this.clock = clock;
+    }
+    /** Transition a step into `working`, stamping its start time once, and resume its clock. */
+    startStep(step) {
+        step.state = 'working';
+        if (step.startedAt == null)
+            step.startedAt = this.clock.now();
+        // (Re)entering `working` means the step is no longer parked on a human: resume
+        // its duration clock (see {@link pauseStepForInput}).
+        step.pausedAt = null;
+    }
+    /**
+     * Transition a step into `done`, stamping its finish time once. Set-once so the
+     * approval-gate flow (which re-asserts `done` after a human approves, long after
+     * the agent actually finished) keeps the agent's true completion time, and so a
+     * replay doesn't move it. With {@link startStep}'s `startedAt` this yields the
+     * step's execution duration. A step finished directly out of a parked approval
+     * stopped *working* when it parked, so its duration is billed to the pause instant
+     * ({@link pauseStepForInput}), not the (later) moment the human decided.
+     */
+    finishStep(step) {
+        step.state = 'done';
+        if (step.finishedAt == null)
+            step.finishedAt = step.pausedAt ?? this.clock.now();
+        step.pausedAt = null;
+    }
+    /**
+     * Park a step on a human decision and freeze its duration clock. Records when the
+     * step stopped working (`pausedAt`) so elapsed time no longer accrues while it waits
+     * for input — the symmetric counterpart of the terminal freeze on `finishedAt`.
+     * Set-once (a Workflows replay re-parking keeps the original instant); cleared when
+     * the step resumes ({@link startStep}) or finishes ({@link finishStep}).
+     */
+    pauseStepForInput(step) {
+        step.state = 'waiting_decision';
+        if (step.pausedAt == null)
+            step.pausedAt = this.clock.now();
+    }
+    /**
+     * Reset a step so the durable driver re-runs it from scratch: clear its live container
+     * job handle (so it dispatches FRESH work rather than re-attaching to a stale/evicted
+     * job), timings, approval, subtasks and prior output.
+     */
+    resetStepForRerun(step) {
+        step.state = 'pending';
+        step.startedAt = null;
+        step.finishedAt = null;
+        step.pausedAt = null;
+        step.jobId = undefined;
+        step.approval = null;
+        step.subtasks = undefined;
+        step.progress = 0;
+        step.output = undefined;
+        // Drop the prior run's structured output too, so a re-run that produces no `custom`
+        // doesn't leave stale JSON for the `generic-structured` result view to render.
+        step.custom = undefined;
+        step.rework = undefined;
+    }
+    /**
+     * Loop a producer step back for rework and re-run every step from it up to and
+     * including the companion at `companionIndex`: each one is reset (crucially clearing
+     * stale container job handles so an intermediate container step re-dispatches fresh
+     * work instead of re-attaching to its evicted job), the producer is handed the
+     * `rework` feedback + started, and the instance cursor is moved back to the producer.
+     * Shared by the automatic companion loop and the human "request changes" path.
+     */
+    rerunProducerThrough(instance, producerIndex, companionIndex, rework) {
+        for (let i = producerIndex; i <= companionIndex; i++) {
+            this.resetStepForRerun(instance.steps[i]);
+        }
+        const producer = instance.steps[producerIndex];
+        producer.rework = rework;
+        this.startStep(producer);
+        instance.currentStep = producerIndex;
+    }
+    /**
+     * The index of the nearest preceding step a companion grades (one of its target
+     * producer kinds), or -1 when none precedes it. The single producer-search used by the
+     * automatic companion loop, the human "request changes" redirect, and the iteration-cap
+     * extra-round resolution.
+     */
+    companionProducerIndex(instance, companionIndex) {
+        const targets = companionTargets(instance.steps[companionIndex].agentKind);
+        for (let i = companionIndex - 1; i >= 0; i--) {
+            if (targets.includes(instance.steps[i].agentKind))
+                return i;
+        }
+        return -1;
+    }
+    /**
+     * Loop a companion's producer back for one more automatic rework cycle: charge one
+     * attempt against the budget, then re-run the producer (and any intermediate steps) up
+     * to and including the companion so it re-grades. Shared by the automatic
+     * below-threshold loop and the human-granted extra round, so both consume the budget
+     * identically.
+     */
+    loopCompanionProducer(instance, companionIndex, rework) {
+        const companionStep = instance.steps[companionIndex];
+        const producerIndex = this.companionProducerIndex(instance, companionIndex);
+        companionStep.companion.attempts += 1;
+        this.rerunProducerThrough(instance, producerIndex, companionIndex, rework);
+        if (instance.status === 'blocked')
+            instance.status = 'running';
+    }
+}
+//# sourceMappingURL=StepGraph.js.map

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/orchestration",
-  "version": "0.37.0",
+  "version": "0.37.1",
   "description": "Delivery-workflow engine for the Agent Architecture Board (execution, bootstrap, pipelines, board, boardScan, requirements, and composition root).",
   "repository": {
     "type": "git",