@cat-factory/orchestration 0.6.0

package/dist/modules/execution/AgentContextBuilder.js

@@ -0,0 +1,316 @@
+import { CODE_AWARE_TRAIT, hasTrait } from '@cat-factory/agents';
+import { getFragment } from '@cat-factory/prompt-fragments';
+/**
+ * The `revision` slice of an agent context when a step is being re-run with feedback
+ * — either a human's "request changes" on its approval gate, or a downstream
+ * companion's automatic rework (`step.rework`). The companion path wins when both are
+ * present. Empty object when neither applies (no revision context).
+ */
+export function buildRevisionContext(step) {
+    const source = step.rework
+        ? {
+            previousProposal: step.rework.previousProposal,
+            feedback: step.rework.feedback,
+            comments: step.rework.comments,
+        }
+        : step.approval?.status === 'changes_requested'
+            ? {
+                previousProposal: step.approval.proposal,
+                feedback: step.approval.feedback ?? '',
+                comments: step.approval.comments,
+            }
+            : undefined;
+    if (!source)
+        return {};
+    return {
+        revision: {
+            previousProposal: source.previousProposal,
+            feedback: source.feedback,
+            ...(source.comments?.length
+                ? {
+                    comments: source.comments.map((c) => ({
+                        ...(c.quotedSource ? { quotedSource: c.quotedSource } : {}),
+                        body: c.body,
+                    })),
+                }
+                : {}),
+        },
+    };
+}
+/**
+ * Assembles the {@link AgentRunContext} for a pipeline step from the run + block state:
+ * the (possibly reworked) requirements, linked docs/tracker issues, the live environment,
+ * the service-frame config, the best-practice fragments, prior step outputs, recorded
+ * decisions and any revision feedback. Pure inputs → output (it only reads repositories),
+ * extracted out of `ExecutionService` so the engine stays a thin state machine. Also the
+ * single home for service-frame resolution (`resolveServiceFrameId`/`resolveServiceConfig`),
+ * which a few other engine paths reuse.
+ */
+export class AgentContextBuilder {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /** Assemble the {@link AgentRunContext} for a step from the run + block state. */
+    async buildContext(workspaceId, instance, step, isFinalStep, block) {
+        // When a block's requirements have been reworked, that standardized document is
+        // the single source of truth for every agent step: it already folds in the
+        // description plus the linked docs / tracker issues, so it REPLACES the
+        // description and the (now-redundant) doc/task context. Reviews are only ever run
+        // on task blocks, so skip the lookup entirely for frames/modules — that keeps the
+        // extra read off every container/frame step rather than on the whole hot path.
+        // A converged clarity (bug-report triage) report substitutes downstream exactly like a
+        // reworked requirements doc. When both exist on one task the requirements doc — which
+        // runs after clarity and is the more refined artifact — takes precedence.
+        const reworked = block.level === 'task'
+            ? ((await this.resolveReworkedRequirements(workspaceId, block.id)) ??
+                (await this.resolveClarifiedBrief(workspaceId, block.id)))
+            : null;
+        const description = reworked ?? block.description;
+        const contextDocs = reworked ? [] : await this.resolveContextDocs(workspaceId, block.id);
+        const contextTasks = reworked ? [] : await this.resolveContextTasks(workspaceId, block.id);
+        const environment = await this.resolveEnvironment(workspaceId, block.id);
+        const service = await this.resolveServiceConfig(workspaceId, block);
+        const priorOutputs = instance.steps
+            .slice(0, instance.currentStep)
+            .filter((s) => s.output)
+            .map((s) => ({ agentKind: s.agentKind, output: s.output }));
+        // Resolve the best-practice fragments to inject for this step. `code-aware` kinds
+        // get the running service's selected fragments unioned with the block's own pins;
+        // other kinds keep only their block pins. Recorded on the step for observability.
+        const resolved = await this.resolveFragments(workspaceId, step, block);
+        return {
+            agentKind: step.agentKind,
+            pipelineName: instance.pipelineName,
+            workspaceId,
+            executionId: instance.id,
+            // Carry the run initiator so the container executor can lease their OWN personal
+            // (individual-usage) subscription for the step. Null on system/dev runs.
+            ...(instance.initiatedBy != null ? { initiatedByUserId: instance.initiatedBy } : {}),
+            stepIndex: instance.currentStep,
+            isFinalStep,
+            // Consensus config for this step (copied onto the step at run start). Read only
+            // by the optional consensus executor, which decides — possibly gated on the
+            // block estimate below — whether to run the multi-model process. Absent ⇒ standard.
+            ...(step.consensus ? { consensus: step.consensus } : {}),
+            block: {
+                id: block.id,
+                title: block.title,
+                type: block.type,
+                description,
+                fragmentIds: block.fragmentIds,
+                ...(resolved ? { resolvedFragments: resolved.fragments } : {}),
+                modelId: block.modelId,
+                ...(block.agentConfig ? { agentConfig: block.agentConfig } : {}),
+                ...(block.pullRequest ? { pullRequest: block.pullRequest } : {}),
+                ...(contextDocs.length ? { contextDocs } : {}),
+                ...(contextTasks.length ? { contextTasks } : {}),
+                // The task-estimator's triage, when produced earlier in this run — the
+                // consensus executor's gating input.
+                ...(block.estimate ? { estimate: block.estimate } : {}),
+            },
+            ...(environment ? { environment } : {}),
+            ...(service ? { service } : {}),
+            priorOutputs,
+            decisions: instance.steps
+                .filter((s, i) => i < instance.currentStep && s.decision?.chosen)
+                .map((s) => ({ question: s.decision.question, chosen: s.decision.chosen })),
+            resolvedDecision: step.decision?.chosen
+                ? { question: step.decision.question, chosen: step.decision.chosen }
+                : null,
+            // A re-run triggered either by a human "Request changes" on this step's
+            // approval gate OR by a downstream companion looping it back for rework: hand
+            // the agent its previous proposal plus the feedback so it revises rather than
+            // starting over. The companion's automatic rework (`step.rework`) and the
+            // human's gate feedback share one revision shape; the companion path takes
+            // precedence when both are present.
+            ...buildRevisionContext(step),
+        };
+    }
+    /** The service-frame id for a block (walks up frame → module → task; cycle-guarded). */
+    async resolveServiceFrameId(workspaceId, blockId) {
+        let current = await this.deps.blockRepository.get(workspaceId, blockId);
+        // Bounded walk (the tree is at most frame → module → task) guarded against cycles.
+        for (let i = 0; current && i < 8; i++) {
+            if (current.level === 'frame' || !current.parentId)
+                return current.id;
+            current = await this.deps.blockRepository.get(workspaceId, current.parentId);
+        }
+        return current?.id ?? null;
+    }
+    /**
+     * Resolve the service-level (frame) configuration for a run's block — the
+     * Tester's local-infra docker-compose path / "no infra" flag and the provisioning
+     * provider + instance size — by walking up to the service frame. When the frame
+     * pins no cloud provider it inherits the owning account's `defaultCloudProvider`
+     * (so the account-level default actually reaches dispatch, not just the UI).
+     * Returns undefined when no frame carries any of these settings, so callers can
+     * spread it conditionally onto the agent context.
+     */
+    async resolveServiceConfig(workspaceId, block) {
+        const frame = block.level === 'frame'
+            ? block
+            : await this.resolveServiceFrameId(workspaceId, block.id).then((id) => id ? this.deps.blockRepository.get(workspaceId, id) : null);
+        if (!frame)
+            return undefined;
+        const service = {};
+        if (frame.testComposePath)
+            service.testComposePath = frame.testComposePath;
+        if (frame.noInfraDependencies)
+            service.noInfraDependencies = frame.noInfraDependencies;
+        if (frame.cloudProvider)
+            service.cloudProvider = frame.cloudProvider;
+        else {
+            // No per-service override: fall back to the owning account's default provider
+            // so a pool/local deployment honours the account-level choice at dispatch.
+            const accountDefault = await this.resolveAccountDefaultProvider(workspaceId);
+            if (accountDefault)
+                service.cloudProvider = accountDefault;
+        }
+        if (frame.instanceSize)
+            service.instanceSize = frame.instanceSize;
+        return Object.keys(service).length ? service : undefined;
+    }
+    /**
+     * The owning account's `defaultCloudProvider`, or undefined when the workspace
+     * has no account or the account pins no default (so the transport keeps its own).
+     */
+    async resolveAccountDefaultProvider(workspaceId) {
+        const workspace = await this.deps.workspaceRepository.get(workspaceId);
+        if (!workspace?.accountId)
+            return undefined;
+        const account = await this.deps.accountRepository.get(workspace.accountId);
+        return account?.defaultCloudProvider;
+    }
+    /**
+     * The reworked ("incorporated") requirements for a block — the standard-format
+     * document the requirements-rework step produced — or `null` when the feature is
+     * unwired or the block has no incorporated review yet. Used both to substitute the
+     * agent context for every step and to feed the spec-writer.
+     */
+    async resolveReworkedRequirements(workspaceId, blockId) {
+        if (!this.deps.requirementReviews)
+            return null;
+        const review = await this.deps.requirementReviews.getByBlock(workspaceId, blockId);
+        if (review?.status === 'incorporated' && review.incorporatedRequirements) {
+            return review.incorporatedRequirements;
+        }
+        return null;
+    }
+    /**
+     * The clarified bug report for a block — the standard-format document the clarity-rework
+     * step produced — or `null` when the feature is unwired or the block has no incorporated
+     * clarity review yet. The clarity mirror of {@link resolveReworkedRequirements}.
+     */
+    async resolveClarifiedBrief(workspaceId, blockId) {
+        if (!this.deps.clarityReviews)
+            return null;
+        const review = await this.deps.clarityReviews.getByBlock(workspaceId, blockId);
+        if (review?.status === 'incorporated' && review.clarifiedReport) {
+            return review.clarifiedReport;
+        }
+        return null;
+    }
+    /**
+     * Resolve the best-practice fragments to fold into a step's system prompt. Service
+     * fragments reach an agent ONLY when its kind carries the `code-aware` trait: those
+     * kinds get the running SERVICE's selected fragments (the frame's
+     * `serviceFragmentIds`, seeded from the workspace default and editable per service)
+     * unioned with the block's own manual pins, resolved against the universal pool. A
+     * non-code-aware kind returns null so `composeBlockSystemPrompt` falls back to the
+     * block's own `fragmentIds` unchanged. Records the selected ids on the step for
+     * observability; never throws (a lookup failure degrades to the block pins).
+     */
+    async resolveFragments(workspaceId, step, block) {
+        if (!hasTrait(step.agentKind, CODE_AWARE_TRAIT))
+            return null;
+        try {
+            const serviceIds = await this.resolveServiceFragmentIds(workspaceId, block);
+            // Service standards first, then the block's own pins; deduped, stable order.
+            const ids = [];
+            const seen = new Set();
+            for (const id of [...serviceIds, ...(block.fragmentIds ?? [])]) {
+                if (seen.has(id))
+                    continue;
+                seen.add(id);
+                ids.push(id);
+            }
+            const fragments = ids
+                .map((id) => {
+                const fragment = getFragment(id);
+                return fragment ? { id, body: fragment.body } : null;
+            })
+                .filter((f) => f !== null);
+            if (fragments.length === 0)
+                return null;
+            step.selectedFragmentIds = fragments.map((f) => f.id);
+            return { fragments };
+        }
+        catch {
+            // Resolution must never wedge a run; fall back to the block's own pins.
+            return null;
+        }
+    }
+    /**
+     * The selected best-practice fragment ids of the block's owning service frame. Walks
+     * up from the block we already hold (bounded: frame → module → task, cycle-guarded),
+     * reading the frame's `serviceFragmentIds` — without re-fetching the block in hand or
+     * fetching the frame twice.
+     */
+    async resolveServiceFragmentIds(workspaceId, block) {
+        let current = block;
+        for (let i = 0; current && i < 8; i++) {
+            if (current.level === 'frame' || !current.parentId)
+                return current.serviceFragmentIds ?? [];
+            current = await this.deps.blockRepository.get(workspaceId, current.parentId);
+        }
+        return [];
+    }
+    /**
+     * Resolve documents (from any source) linked to the running block into compact
+     * agent context. A no-op unless the document-source integration is wired (the
+     * repository is an optional dependency), so the engine stays unchanged when it
+     * is off.
+     */
+    async resolveContextDocs(workspaceId, blockId) {
+        if (!this.deps.documents)
+            return [];
+        const docs = await this.deps.documents.listByBlock(workspaceId, blockId);
+        return docs.map((d) => ({ title: d.title, url: d.url, excerpt: d.excerpt }));
+    }
+    /**
+     * Resolve tracker issues (from any source) linked to the running block into
+     * structured agent context. A no-op unless the task-source integration is
+     * wired (the repository is an optional dependency), so the engine stays
+     * unchanged when it is off.
+     */
+    async resolveContextTasks(workspaceId, blockId) {
+        if (!this.deps.tasks)
+            return [];
+        const tasks = await this.deps.tasks.listByBlock(workspaceId, blockId);
+        return tasks.map((t) => ({
+            key: t.externalId,
+            url: t.url,
+            title: t.title,
+            status: t.status,
+            type: t.type,
+            assignee: t.assignee,
+            priority: t.priority,
+            labels: t.labels,
+            description: t.description,
+            comments: t.comments,
+        }));
+    }
+    /**
+     * Resolve the live ephemeral environment provisioned for the running block
+     * into compact agent context. A no-op unless the environment integration is
+     * wired (the provisioning service is an optional dependency), so the engine
+     * stays unchanged when it is off.
+     */
+    async resolveEnvironment(workspaceId, blockId) {
+        if (!this.deps.environmentProvisioning)
+            return null;
+        return this.deps.environmentProvisioning.resolveForBlock(workspaceId, blockId);
+    }
+}
+//# sourceMappingURL=AgentContextBuilder.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"AgentContextBuilder.js","sourceRoot":"","sources":["../../../src/modules/execution/AgentContextBuilder.ts"],"names":[],"mappings":"AAcA,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAA;AAChE,OAAO,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAA;AAG3D;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,IAAkB;IAOrD,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM;QACxB,CAAC,CAAC;YACE,gBAAgB,EAAE,IAAI,CAAC,MAAM,CAAC,gBAAgB;YAC9C,QAAQ,EAAE,IAAI,CAAC,MAAM,CAAC,QAAQ;YAC9B,QAAQ,EAAE,IAAI,CAAC,MAAM,CAAC,QAAQ;SAC/B;QACH,CAAC,CAAC,IAAI,CAAC,QAAQ,EAAE,MAAM,KAAK,mBAAmB;YAC7C,CAAC,CAAC;gBACE,gBAAgB,EAAE,IAAI,CAAC,QAAQ,CAAC,QAAQ;gBACxC,QAAQ,EAAE,IAAI,CAAC,QAAQ,CAAC,QAAQ,IAAI,EAAE;gBACtC,QAAQ,EAAE,IAAI,CAAC,QAAQ,CAAC,QAAQ;aACjC;YACH,CAAC,CAAC,SAAS,CAAA;IACf,IAAI,CAAC,MAAM;QAAE,OAAO,EAAE,CAAA;IACtB,OAAO;QACL,QAAQ,EAAE;YACR,gBAAgB,EAAE,MAAM,CAAC,gBAAgB;YACzC,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,GAAG,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM;gBACzB,CAAC,CAAC;oBACE,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;wBACpC,GAAG,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;wBAC3D,IAAI,EAAE,CAAC,CAAC,IAAI;qBACb,CAAC,CAAC;iBACJ;gBACH,CAAC,CAAC,EAAE,CAAC;SACR;KACF,CAAA;AACH,CAAC;AAcD;;;;;;;;GAQG;AACH,MAAM,OAAO,mBAAmB;IACD,IAAI;IAAjC,YAA6B,IAA6B;oBAA7B,IAAI;IAA4B,CAAC;IAE9D,kFAAkF;IAClF,KAAK,CAAC,YAAY,CAChB,WAAmB,EACnB,QAA2B,EAC3B,IAAkB,EAClB,WAAoB,EACpB,KAAY;QAEZ,gFAAgF;QAChF,2EAA2E;QAC3E,wEAAwE;QACxE,kFAAkF;QAClF,kFAAkF;QAClF,+EAA+E;QAC/E,uFAAuF;QACvF,sFAAsF;QACtF,0EAA0E;QAC1E,MAAM,QAAQ,GACZ,KAAK,CAAC,KAAK,KAAK,MAAM;YACpB,CAAC,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,2BAA2B,CAAC,WAAW,EAAE,KAAK,CAAC,EAAE,CAAC,CAAC;gBAChE,CAAC,MAAM,IAAI,CAAC,qBAAqB,CAAC,WAAW,EAAE,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC;YAC5D,CAAC,CAAC,IAAI,CAAA;QACV,MAAM,WAAW,GAAG,QAAQ,IAAI,KAAK,CAAC,WAAW,CAAA;QACjD,MAAM,WAAW,GAAG,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,kBAAkB,CAAC,WAAW,EAAE,KAAK,CAAC,EAAE,CAAC,CAAA;QACxF,MAAM,YAAY,GAAG,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,mBAAmB,CAAC,WAAW,EAAE,KAAK,CAAC,EAAE,CAAC,CAAA;QAC1F,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC,kBAAkB,CAAC,WAAW,EAAE,KAAK,CAAC,EAAE,CAAC,CAAA;QACxE,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,oBAAoB,CAAC,WAAW,EAAE,KAAK,CAAC,CAAA;QACnE,MAAM,YAAY,GAAG,QAAQ,CAAC,KAAK;aAChC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,WAAW,CAAC;aAC9B,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC;aACvB,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,SAAS,EAAE,MAAM,EAAE,CAAC,CAAC,MAAO,EAAE,CAAC,CAAC,CAAA;QAC9D,kFAAkF;QAClF,kFAAkF;QAClF,kFAAkF;QAClF,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,gBAAgB,CAAC,WAAW,EAAE,IAAI,EAAE,KAAK,CAAC,CAAA;QACtE,OAAO;YACL,SAAS,EAAE,IAAI,CAAC,SAAS;YACzB,YAAY,EAAE,QAAQ,CAAC,YAAY;YACnC,WAAW;YACX,WAAW,EAAE,QAAQ,CAAC,EAAE;YACxB,iFAAiF;YACjF,yEAAyE;YACzE,GAAG,CAAC,QAAQ,CAAC,WAAW,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,iBAAiB,EAAE,QAAQ,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACpF,SAAS,EAAE,QAAQ,CAAC,WAAW;YAC/B,WAAW;YACX,gFAAgF;YAChF,4EAA4E;YAC5E,oFAAoF;YACpF,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACxD,KAAK,EAAE;gBACL,EAAE,EAAE,KAAK,CAAC,EAAE;gBACZ,KAAK,EAAE,KAAK,CAAC,KAAK;gBAClB,IAAI,EAAE,KAAK,CAAC,IAAI;gBAChB,WAAW;gBACX,WAAW,EAAE,KAAK,CAAC,WAAW;gBAC9B,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,iBAAiB,EAAE,QAAQ,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC9D,OAAO,EAAE,KAAK,CAAC,OAAO;gBACtB,GAAG,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,KAAK,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAChE,GAAG,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,KAAK,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAChE,GAAG,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC9C,GAAG,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAChD,uEAAuE;gBACvE,qCAAqC;gBACrC,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aACxD;YACD,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACvC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC/B,YAAY;YACZ,SAAS,EAAE,QAAQ,CAAC,KAAK;iBACtB,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,QAAQ,CAAC,WAAW,IAAI,CAAC,CAAC,QAAQ,EAAE,MAAM,CAAC;iBAChE,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,QAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC,QAAS,CAAC,MAAO,EAAE,CAAC,CAAC;YAChF,gBAAgB,EAAE,IAAI,CAAC,QAAQ,EAAE,MAAM;gBACrC,CAAC,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE;gBACpE,CAAC,CAAC,IAAI;YACR,wEAAwE;YACxE,8EAA8E;YAC9E,8EAA8E;YAC9E,0EAA0E;YAC1E,2EAA2E;YAC3E,oCAAoC;YACpC,GAAG,oBAAoB,CAAC,IAAI,CAAC;SAC9B,CAAA;IACH,CAAC;IAED,wFAAwF;IACxF,KAAK,CAAC,qBAAqB,CAAC,WAAmB,EAAE,OAAe;QAC9D,IAAI,OAAO,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,WAAW,EAAE,OAAO,CAAC,CAAA;QACvE,mFAAmF;QACnF,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,OAAO,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;YACtC,IAAI,OAAO,CAAC,KAAK,KAAK,OAAO,IAAI,CAAC,OAAO,CAAC,QAAQ;gBAAE,OAAO,OAAO,CAAC,EAAE,CAAA;YACrE,OAAO,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,WAAW,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAA;QAC9E,CAAC;QACD,OAAO,OAAO,EAAE,EAAE,IAAI,IAAI,CAAA;IAC5B,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,oBAAoB,CACxB,WAAmB,EACnB,KAAY;QAEZ,MAAM,KAAK,GACT,KAAK,CAAC,KAAK,KAAK,OAAO;YACrB,CAAC,CAAC,KAAK;YACP,CAAC,CAAC,MAAM,IAAI,CAAC,qBAAqB,CAAC,WAAW,EAAE,KAAK,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,CAClE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAC3D,CAAA;QACP,IAAI,CAAC,KAAK;YAAE,OAAO,SAAS,CAAA;QAC5B,MAAM,OAAO,GAA4C,EAAE,CAAA;QAC3D,IAAI,KAAK,CAAC,eAAe;YAAE,OAAO,CAAC,eAAe,GAAG,KAAK,CAAC,eAAe,CAAA;QAC1E,IAAI,KAAK,CAAC,mBAAmB;YAAE,OAAO,CAAC,mBAAmB,GAAG,KAAK,CAAC,mBAAmB,CAAA;QACtF,IAAI,KAAK,CAAC,aAAa;YAAE,OAAO,CAAC,aAAa,GAAG,KAAK,CAAC,aAAa,CAAA;aAC/D,CAAC;YACJ,8EAA8E;YAC9E,2EAA2E;YAC3E,MAAM,cAAc,GAAG,MAAM,IAAI,CAAC,6BAA6B,CAAC,WAAW,CAAC,CAAA;YAC5E,IAAI,cAAc;gBAAE,OAAO,CAAC,aAAa,GAAG,cAAc,CAAA;QAC5D,CAAC;QACD,IAAI,KAAK,CAAC,YAAY;YAAE,OAAO,CAAC,YAAY,GAAG,KAAK,CAAC,YAAY,CAAA;QACjE,OAAO,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAA;IAC1D,CAAC;IAED;;;OAGG;IACK,KAAK,CAAC,6BAA6B,CACzC,WAAmB;QAEnB,MAAM,SAAS,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,mBAAmB,CAAC,GAAG,CAAC,WAAW,CAAC,CAAA;QACtE,IAAI,CAAC,SAAS,EAAE,SAAS;YAAE,OAAO,SAAS,CAAA;QAC3C,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,SAAS,CAAC,SAAS,CAAC,CAAA;QAC1E,OAAO,OAAO,EAAE,oBAAoB,CAAA;IACtC,CAAC;IAED;;;;;OAKG;IACK,KAAK,CAAC,2BAA2B,CACvC,WAAmB,EACnB,OAAe;QAEf,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,kBAAkB;YAAE,OAAO,IAAI,CAAA;QAC9C,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,kBAAkB,CAAC,UAAU,CAAC,WAAW,EAAE,OAAO,CAAC,CAAA;QAClF,IAAI,MAAM,EAAE,MAAM,KAAK,cAAc,IAAI,MAAM,CAAC,wBAAwB,EAAE,CAAC;YACzE,OAAO,MAAM,CAAC,wBAAwB,CAAA;QACxC,CAAC;QACD,OAAO,IAAI,CAAA;IACb,CAAC;IAED;;;;OAIG;IACK,KAAK,CAAC,qBAAqB,CACjC,WAAmB,EACnB,OAAe;QAEf,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,cAAc;YAAE,OAAO,IAAI,CAAA;QAC1C,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,cAAc,CAAC,UAAU,CAAC,WAAW,EAAE,OAAO,CAAC,CAAA;QAC9E,IAAI,MAAM,EAAE,MAAM,KAAK,cAAc,IAAI,MAAM,CAAC,eAAe,EAAE,CAAC;YAChE,OAAO,MAAM,CAAC,eAAe,CAAA;QAC/B,CAAC;QACD,OAAO,IAAI,CAAA;IACb,CAAC;IAED;;;;;;;;;OASG;IACK,KAAK,CAAC,gBAAgB,CAC5B,WAAmB,EACnB,IAAkB,EAClB,KAAY;QAEZ,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,SAAS,EAAE,gBAAgB,CAAC;YAAE,OAAO,IAAI,CAAA;QAC5D,IAAI,CAAC;YACH,MAAM,UAAU,GAAG,MAAM,IAAI,CAAC,yBAAyB,CAAC,WAAW,EAAE,KAAK,CAAC,CAAA;YAC3E,6EAA6E;YAC7E,MAAM,GAAG,GAAa,EAAE,CAAA;YACxB,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAA;YAC9B,KAAK,MAAM,EAAE,IAAI,CAAC,GAAG,UAAU,EAAE,GAAG,CAAC,KAAK,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;gBAC/D,IAAI,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;oBAAE,SAAQ;gBAC1B,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAA;gBACZ,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;YACd,CAAC;YACD,MAAM,SAAS,GAAG,GAAG;iBAClB,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE;gBACV,MAAM,QAAQ,GAAG,WAAW,CAAC,EAAE,CAAC,CAAA;gBAChC,OAAO,QAAQ,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,CAAA;YACtD,CAAC,CAAC;iBACD,MAAM,CAAC,CAAC,CAAC,EAAqC,EAAE,CAAC,CAAC,KAAK,IAAI,CAAC,CAAA;YAC/D,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC;gBAAE,OAAO,IAAI,CAAA;YACvC,IAAI,CAAC,mBAAmB,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAA;YACrD,OAAO,EAAE,SAAS,EAAE,CAAA;QACtB,CAAC;QAAC,MAAM,CAAC;YACP,wEAAwE;YACxE,OAAO,IAAI,CAAA;QACb,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACK,KAAK,CAAC,yBAAyB,CAAC,WAAmB,EAAE,KAAY;QACvE,IAAI,OAAO,GAAiB,KAAK,CAAA;QACjC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,OAAO,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;YACtC,IAAI,OAAO,CAAC,KAAK,KAAK,OAAO,IAAI,CAAC,OAAO,CAAC,QAAQ;gBAAE,OAAO,OAAO,CAAC,kBAAkB,IAAI,EAAE,CAAA;YAC3F,OAAO,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,WAAW,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAA;QAC9E,CAAC;QACD,OAAO,EAAE,CAAA;IACX,CAAC;IAED;;;;;OAKG;IACK,KAAK,CAAC,kBAAkB,CAC9B,WAAmB,EACnB,OAAe;QAEf,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS;YAAE,OAAO,EAAE,CAAA;QACnC,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,WAAW,CAAC,WAAW,EAAE,OAAO,CAAC,CAAA;QACxE,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC,GAAG,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAA;IAC9E,CAAC;IAED;;;;;OAKG;IACK,KAAK,CAAC,mBAAmB,CAAC,WAAmB,EAAE,OAAe;QACpE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK;YAAE,OAAO,EAAE,CAAA;QAC/B,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,WAAW,EAAE,OAAO,CAAC,CAAA;QACrE,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YACvB,GAAG,EAAE,CAAC,CAAC,UAAU;YACjB,GAAG,EAAE,CAAC,CAAC,GAAG;YACV,KAAK,EAAE,CAAC,CAAC,KAAK;YACd,MAAM,EAAE,CAAC,CAAC,MAAM;YAChB,IAAI,EAAE,CAAC,CAAC,IAAI;YACZ,QAAQ,EAAE,CAAC,CAAC,QAAQ;YACpB,QAAQ,EAAE,CAAC,CAAC,QAAQ;YACpB,MAAM,EAAE,CAAC,CAAC,MAAM;YAChB,WAAW,EAAE,CAAC,CAAC,WAAW;YAC1B,QAAQ,EAAE,CAAC,CAAC,QAAQ;SACrB,CAAC,CAAC,CAAA;IACL,CAAC;IAED;;;;;OAKG;IACK,KAAK,CAAC,kBAAkB,CAAC,WAAmB,EAAE,OAAe;QACnE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,uBAAuB;YAAE,OAAO,IAAI,CAAA;QACnD,OAAO,IAAI,CAAC,IAAI,CAAC,uBAAuB,CAAC,eAAe,CAAC,WAAW,EAAE,OAAO,CAAC,CAAA;IAChF,CAAC;CACF"}

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

@@ -0,0 +1,60 @@
+import type { AgentRunContext, AgentRunResult, Block, ExecutionInstance, IdGenerator, PipelineStep } from '@cat-factory/kernel';
+import type { SpendService } from '@cat-factory/spend';
+import type { AdvanceOptions, AdvanceResult } from './advance.js';
+import type { AgentContextBuilder } from './AgentContextBuilder.js';
+/**
+ * The engine flow-control operations the companion loop drives. These stay on
+ * `ExecutionService` (they are the shared state-machine primitives, reused by the human
+ * "request changes" path and the iteration-cap resolution) and are injected here so the
+ * companion evaluation can live in its own unit without duplicating them.
+ */
+export interface CompanionControllerDeps {
+    contextBuilder: AgentContextBuilder;
+    spend: SpendService;
+    idGenerator: IdGenerator;
+    previewStepModel: (context: AgentRunContext) => Promise<string | undefined>;
+    runAgent: (context: AgentRunContext, options: AdvanceOptions) => Promise<AgentRunResult>;
+    finishStep: (step: PipelineStep) => void;
+    startStep: (step: PipelineStep) => void;
+    pauseStepForInput: (step: PipelineStep) => void;
+    updateBlockProgress: (workspaceId: string, instance: ExecutionInstance, status: 'in_progress' | 'blocked') => Promise<void>;
+    persistInstance: (workspaceId: string, instance: ExecutionInstance) => Promise<void>;
+    emitInstance: (workspaceId: string, instance: ExecutionInstance) => Promise<void>;
+    stopRunContainer: (workspaceId: string, instance: ExecutionInstance) => Promise<void>;
+    finalizeBlock: (workspaceId: string, instance: ExecutionInstance, confidence: number | undefined) => Promise<void>;
+    parkStepOnDecision: (workspaceId: string, instance: ExecutionInstance, step: PipelineStep, proposal?: string) => Promise<AdvanceResult>;
+    raiseDecisionRequired: (workspaceId: string, instance: ExecutionInstance) => Promise<void>;
+    loopCompanionProducer: (instance: ExecutionInstance, companionIndex: number, rework: NonNullable<PipelineStep['rework']>) => void;
+}
+/**
+ * Drives a companion (reviewer / spec-companion / architect-companion) step: it runs the
+ * companion as a normal inline LLM step, parses its rating JSON (with one repair retry), and
+ * acts on the verdict —
+ *   - at/above threshold → finish; a gated companion raises the human approval gate on the
+ *     producer's output, else the run advances.
+ *   - below, budget left → loop the producer back with the feedback folded in (the automatic
+ *     analogue of "request changes").
+ *   - below, budget spent → park on the iteration-cap gate for a human (one more round /
+ *     proceed / stop & reset), NOT a failure.
+ * An unparseable verdict (even after the repair retry) fails the run (`companion_rejected`)
+ * rather than silently passing. Extracted out of `ExecutionService`; the shared step-graph
+ * primitives it calls (`loopCompanionProducer`, the parking gate, the block/instance writes)
+ * stay on the engine and are injected via {@link CompanionControllerDeps}.
+ */
+export declare class CompanionController {
+    private readonly deps;
+    constructor(deps: CompanionControllerDeps);
+    evaluate(workspaceId: string, instance: ExecutionInstance, step: PipelineStep, block: Block, isFinalStep: boolean, options: AdvanceOptions): Promise<AdvanceResult>;
+    /**
+     * Run a companion step and parse its JSON verdict, with ONE repair retry when the
+     * first reply doesn't parse (truncated, or wrapped in prose `extractJson` can't
+     * recover). The retry runs only when there is a producer to grade (`gradable`) — with
+     * none there is nothing to assess, so a malformed reply is irrelevant. Returns the
+     * parsed assessment (or `undefined` if even the repair failed) and the LAST call's
+     * result, with usage summed across both calls so the caller's single `spend.record`
+     * prices the whole thing. A still-unparseable verdict is handled by the caller (it
+     * surfaces to a human rather than passing), so this never wedges the run.
+     */
+    private runWithRepair;
+}
+//# sourceMappingURL=CompanionController.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"CompanionController.d.ts","sourceRoot":"","sources":["../../../src/modules/execution/CompanionController.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,eAAe,EACf,cAAc,EAEd,KAAK,EACL,iBAAiB,EACjB,WAAW,EACX,YAAY,EACb,MAAM,qBAAqB,CAAA;AAO5B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAEtD,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AACjE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAA;AAwBnE;;;;;GAKG;AACH,MAAM,WAAW,uBAAuB;IACtC,cAAc,EAAE,mBAAmB,CAAA;IACnC,KAAK,EAAE,YAAY,CAAA;IACnB,WAAW,EAAE,WAAW,CAAA;IACxB,gBAAgB,EAAE,CAAC,OAAO,EAAE,eAAe,KAAK,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAA;IAC3E,QAAQ,EAAE,CAAC,OAAO,EAAE,eAAe,EAAE,OAAO,EAAE,cAAc,KAAK,OAAO,CAAC,cAAc,CAAC,CAAA;IACxF,UAAU,EAAE,CAAC,IAAI,EAAE,YAAY,KAAK,IAAI,CAAA;IACxC,SAAS,EAAE,CAAC,IAAI,EAAE,YAAY,KAAK,IAAI,CAAA;IACvC,iBAAiB,EAAE,CAAC,IAAI,EAAE,YAAY,KAAK,IAAI,CAAA;IAC/C,mBAAmB,EAAE,CACnB,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,iBAAiB,EAC3B,MAAM,EAAE,aAAa,GAAG,SAAS,KAC9B,OAAO,CAAC,IAAI,CAAC,CAAA;IAClB,eAAe,EAAE,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,iBAAiB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACpF,YAAY,EAAE,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,iBAAiB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACjF,gBAAgB,EAAE,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,iBAAiB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACrF,aAAa,EAAE,CACb,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,iBAAiB,EAC3B,UAAU,EAAE,MAAM,GAAG,SAAS,KAC3B,OAAO,CAAC,IAAI,CAAC,CAAA;IAClB,kBAAkB,EAAE,CAClB,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,iBAAiB,EAC3B,IAAI,EAAE,YAAY,EAClB,QAAQ,CAAC,EAAE,MAAM,KACd,OAAO,CAAC,aAAa,CAAC,CAAA;IAC3B,qBAAqB,EAAE,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,iBAAiB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IAC1F,qBAAqB,EAAE,CACrB,QAAQ,EAAE,iBAAiB,EAC3B,cAAc,EAAE,MAAM,EACtB,MAAM,EAAE,WAAW,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC,KACxC,IAAI,CAAA;CACV;AAED;;;;;;;;;;;;;;GAcG;AACH,qBAAa,mBAAmB;IAClB,OAAO,CAAC,QAAQ,CAAC,IAAI;IAAjC,YAA6B,IAAI,EAAE,uBAAuB,EAAI;IAExD,QAAQ,CACZ,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,iBAAiB,EAC3B,IAAI,EAAE,YAAY,EAClB,KAAK,EAAE,KAAK,EACZ,WAAW,EAAE,OAAO,EACpB,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,aAAa,CAAC,CA6JxB;IAED;;;;;;;;;OASG;YACW,aAAa;CAiB5B"}

package/dist/modules/execution/CompanionController.js

@@ -0,0 +1,216 @@
+import { DEFAULT_COMPANION_MAX_ATTEMPTS, parseCompanionAssessment, } from '@cat-factory/contracts';
+import { companionFor, companionTargets } from '@cat-factory/agents';
+import { extractJson } from '../requirements/requirements.logic.js';
+/** Parse a companion's JSON verdict from a model reply, or `undefined` if it won't parse. */
+function parseCompanionOrUndefined(output) {
+    try {
+        return parseCompanionAssessment(extractJson(output ?? ''));
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Sum the token usage of two model calls (for the companion's repair retry). */
+function sumUsage(a, b) {
+    if (!a)
+        return b;
+    if (!b)
+        return a;
+    return {
+        inputTokens: a.inputTokens + b.inputTokens,
+        outputTokens: a.outputTokens + b.outputTokens,
+    };
+}
+/**
+ * Drives a companion (reviewer / spec-companion / architect-companion) step: it runs the
+ * companion as a normal inline LLM step, parses its rating JSON (with one repair retry), and
+ * acts on the verdict —
+ *   - at/above threshold → finish; a gated companion raises the human approval gate on the
+ *     producer's output, else the run advances.
+ *   - below, budget left → loop the producer back with the feedback folded in (the automatic
+ *     analogue of "request changes").
+ *   - below, budget spent → park on the iteration-cap gate for a human (one more round /
+ *     proceed / stop & reset), NOT a failure.
+ * An unparseable verdict (even after the repair retry) fails the run (`companion_rejected`)
+ * rather than silently passing. Extracted out of `ExecutionService`; the shared step-graph
+ * primitives it calls (`loopCompanionProducer`, the parking gate, the block/instance writes)
+ * stay on the engine and are injected via {@link CompanionControllerDeps}.
+ */
+export class CompanionController {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    async evaluate(workspaceId, instance, step, block, isFinalStep, options) {
+        const targets = companionTargets(step.agentKind);
+        // The nearest earlier step whose kind this companion reviews (the producer).
+        let producerIndex = -1;
+        for (let i = instance.currentStep - 1; i >= 0; i--) {
+            if (targets.includes(instance.steps[i].agentKind)) {
+                producerIndex = i;
+                break;
+            }
+        }
+        // Run the companion as a normal inline LLM step: its prompt asks for the rating
+        // JSON and `priorOutputs` already carries the producer's output for it to grade.
+        const context = await this.deps.contextBuilder.buildContext(workspaceId, instance, step, isFinalStep, block);
+        const previewModel = await this.deps.previewStepModel(context);
+        if (previewModel && previewModel !== step.model)
+            step.model = previewModel;
+        // Run the companion, parsing its JSON verdict with ONE repair retry when the first
+        // reply doesn't parse (truncated / wrapped in prose). Only retried when there is a
+        // producer to grade. `result` carries the LAST call's output + the summed usage.
+        const { assessment, result } = await this.runWithRepair(context, options, producerIndex >= 0);
+        if (result.usage) {
+            await this.deps.spend.record({
+                workspaceId,
+                executionId: instance.id,
+                agentKind: step.agentKind,
+                model: result.model ?? 'unknown',
+                usage: result.usage,
+            });
+        }
+        if (result.model)
+            step.model = result.model;
+        const companion = step.companion ?? {
+            threshold: companionFor(step.agentKind)?.defaultThreshold ?? 0.8,
+            maxAttempts: DEFAULT_COMPANION_MAX_ATTEMPTS,
+            attempts: 0,
+            verdicts: [],
+        };
+        const feedback = assessment?.summary ?? '';
+        // There IS a producer to grade but the companion's own verdict never parsed (even
+        // after the repair retry): do NOT silently treat that as a perfect pass. That is the
+        // bug where a truncated reviewer reply surfaced as "100% ≥ 80%" and dropped a real
+        // review. Surface it for a human instead, recording the raw reply as the detail.
+        if (producerIndex >= 0 && !assessment) {
+            step.output = result.output || '';
+            step.companion = companion;
+            await this.deps.persistInstance(workspaceId, instance);
+            // Hand the precise classification + the raw reply (the whole point of the failure,
+            // for triage) to the driver's single `failRun` funnel. Do NOT fail the run here as
+            // well: a second `failRun` from the driver would clobber this rich record with a
+            // generic `job_failed` ("the implementation container reported a failure", no
+            // detail), which is exactly the misleading surface this path is meant to avoid.
+            return {
+                kind: 'job_failed',
+                failureKind: 'companion_rejected',
+                error: `Companion "${step.agentKind}" did not return a parseable assessment (its reply ` +
+                    `was truncated or malformed) after a repair retry.`,
+                detail: (result.output ?? '').slice(0, 2000) || undefined,
+            };
+        }
+        // The score to judge: the parsed rating when there is a producer to grade, else a
+        // perfect score (no producer of this companion's target kind precedes it, so there
+        // is genuinely nothing to grade and the run advances).
+        const rating = assessment && producerIndex >= 0 ? assessment.rating : 1;
+        // The FIRST review batch ALWAYS loops the producer back when it raised any comments,
+        // regardless of rating; the configured threshold only governs the SECOND pass onward.
+        // `attempts` counts automatic reworks, so it is 0 on the first batch. Applies to every
+        // companion (reviewer / spec-companion / architect-companion). Gated on a real producer
+        // so the loop-back below always has a step to re-run.
+        const firstBatch = companion.attempts === 0;
+        const hasComments = producerIndex >= 0 && (assessment?.comments?.length ?? 0) > 0;
+        const passed = firstBatch && hasComments ? false : rating >= companion.threshold;
+        // Append this cycle's standardized verdict (the same shape the requirements-rework
+        // gate stores) so the whole correction sequence is visible, not just the latest.
+        companion.verdicts.push({
+            rating,
+            threshold: companion.threshold,
+            passed,
+            feedback,
+        });
+        step.companion = companion;
+        step.output = feedback || result.output || '';
+        // PASS: the producer cleared the bar (and was not force-looped on its first batch).
+        if (passed) {
+            this.deps.finishStep(step);
+            step.progress = 1;
+            // A gated companion now raises the HUMAN approval gate on the producer's output
+            // (the human reviews what the companion just cleared). Never on the final step.
+            if (step.requiresApproval && !isFinalStep && step.approval?.status !== 'approved') {
+                const producer = producerIndex >= 0 ? instance.steps[producerIndex] : undefined;
+                step.approval = {
+                    id: this.deps.idGenerator.next('appr'),
+                    status: 'pending',
+                    proposal: producer?.output ?? step.output,
+                };
+                this.deps.pauseStepForInput(step);
+                instance.status = 'blocked';
+                await this.deps.updateBlockProgress(workspaceId, instance, 'blocked');
+                await this.deps.persistInstance(workspaceId, instance);
+                await this.deps.emitInstance(workspaceId, instance);
+                return { kind: 'awaiting_decision', decisionId: step.approval.id };
+            }
+            if (isFinalStep) {
+                instance.status = 'done';
+                await this.deps.finalizeBlock(workspaceId, instance, undefined);
+                await this.deps.persistInstance(workspaceId, instance);
+                await this.deps.emitInstance(workspaceId, instance);
+                await this.deps.stopRunContainer(workspaceId, instance);
+                return { kind: 'done' };
+            }
+            instance.currentStep += 1;
+            const next = instance.steps[instance.currentStep];
+            if (next)
+                this.deps.startStep(next);
+            await this.deps.updateBlockProgress(workspaceId, instance, 'in_progress');
+            await this.deps.persistInstance(workspaceId, instance);
+            await this.deps.emitInstance(workspaceId, instance);
+            return { kind: 'continue' };
+        }
+        // BELOW THRESHOLD, automatic budget spent → DON'T get stuck. Park on a human
+        // decision (one more round / proceed anyway / stop & reset) — the same iteration-cap
+        // surface the requirements reviewer uses at its cap. Only AUTOMATIC reworks count
+        // against the budget (`attempts`); human "request changes" cycles on a gated
+        // companion re-run the producer without consuming it. `step.output` already holds the
+        // companion's latest feedback; the `exceeded` flag + the parked approval gate let the
+        // SPA render the three choices (resolved via `resolveCompanionExceeded`).
+        if (companion.attempts >= companion.maxAttempts) {
+            companion.exceeded = true;
+            step.companion = companion;
+            await this.deps.raiseDecisionRequired(workspaceId, instance);
+            return this.deps.parkStepOnDecision(workspaceId, instance, step, step.output ?? '');
+        }
+        // NOT PASSED, budget left → loop the producer back with the feedback folded in (the
+        // automatic analogue of a human "request changes"). Reached either below threshold or
+        // on the forced first-batch loop. `producerIndex` is guaranteed >= 0 here: a forced
+        // loop requires comments on a real producer, and a below-threshold rating requires a
+        // parsed verdict against a producer (otherwise rating defaulted to 1 and we passed).
+        const producer = instance.steps[producerIndex];
+        this.deps.loopCompanionProducer(instance, instance.currentStep, {
+            previousProposal: producer.output ?? '',
+            feedback: assessment?.summary ?? '',
+            ...(assessment?.comments?.length ? { comments: assessment.comments } : {}),
+        });
+        await this.deps.updateBlockProgress(workspaceId, instance, 'in_progress');
+        await this.deps.persistInstance(workspaceId, instance);
+        await this.deps.emitInstance(workspaceId, instance);
+        return { kind: 'continue' };
+    }
+    /**
+     * Run a companion step and parse its JSON verdict, with ONE repair retry when the
+     * first reply doesn't parse (truncated, or wrapped in prose `extractJson` can't
+     * recover). The retry runs only when there is a producer to grade (`gradable`) — with
+     * none there is nothing to assess, so a malformed reply is irrelevant. Returns the
+     * parsed assessment (or `undefined` if even the repair failed) and the LAST call's
+     * result, with usage summed across both calls so the caller's single `spend.record`
+     * prices the whole thing. A still-unparseable verdict is handled by the caller (it
+     * surfaces to a human rather than passing), so this never wedges the run.
+     */
+    async runWithRepair(context, options, gradable) {
+        const first = await this.deps.runAgent(context, options);
+        const parsed = parseCompanionOrUndefined(first.output);
+        if (parsed || !gradable)
+            return { assessment: parsed, result: first };
+        // The first reply didn't parse. Re-run the same grading step once more; with the
+        // companion's raised output budget this almost always clears a one-off truncation.
+        const second = await this.deps.runAgent(context, options);
+        const repaired = parseCompanionOrUndefined(second.output);
+        return {
+            assessment: repaired,
+            result: { ...second, usage: sumUsage(first.usage, second.usage) },
+        };
+    }
+}
+//# sourceMappingURL=CompanionController.js.map

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

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