@cat-factory/orchestration 0.30.0 → 0.32.0

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

@@ -0,0 +1,102 @@
+import type { AgentExecutor, BinaryArtifactStore, Block, BlockRepository, ExecutionInstance, ExecutionRepository, PipelineStep, WorkRunner } from '@cat-factory/kernel';
+import type { NotificationService } from '../notifications/NotificationService.js';
+import type { AdvanceResult } from './advance.js';
+import type { AgentContextBuilder } from './AgentContextBuilder.js';
+/**
+ * The engine collaborators the visual-confirmation gate drives (kept on the engine, injected
+ * here). The binary-artifact store + notification channel are optional — absent ones put the
+ * gate into a degraded "manual" mode rather than failing.
+ */
+export interface VisualConfirmationControllerDeps {
+    blockRepository: BlockRepository;
+    executionRepository: ExecutionRepository;
+    workRunner: WorkRunner;
+    agentExecutor: AgentExecutor;
+    contextBuilder: AgentContextBuilder;
+    notificationService?: NotificationService;
+    /** The binary-artifact store the gate reads screenshots + reference designs from. */
+    binaryArtifactStore?: BinaryArtifactStore;
+    /** The task's helper attempt budget (from the resolved merge preset). */
+    resolveMergePreset: (workspaceId: string, block: Block) => Promise<{
+        ciMaxAttempts: number;
+    }>;
+    parkStepOnDecision: (workspaceId: string, instance: ExecutionInstance, step: PipelineStep, proposal?: string) => Promise<AdvanceResult>;
+    finishStep: (step: PipelineStep) => void;
+    startStep: (step: PipelineStep) => void;
+    updateBlockProgress: (workspaceId: string, instance: ExecutionInstance, status: 'in_progress' | 'blocked') => Promise<void>;
+    finalizeBlock: (workspaceId: string, instance: ExecutionInstance, confidence: number | undefined) => Promise<void>;
+    stopRunContainer: (workspaceId: string, instance: ExecutionInstance) => Promise<void>;
+    persistInstance: (workspaceId: string, instance: ExecutionInstance) => Promise<void>;
+    emitInstance: (workspaceId: string, instance: ExecutionInstance) => Promise<void>;
+    clockNow: () => number;
+}
+/** The settle outcome of a helper (fixer) job, as seen by the gate. */
+type HelperUpdate = {
+    state: 'done';
+} | {
+    state: 'failed';
+};
+/**
+ * Drives the `visual-confirmation` gate: a non-LLM engine step where a HUMAN is the verdict.
+ * When reached it gathers the UI tester's captured screenshots + the human-uploaded reference
+ * designs (paired by view) and PARKS; a person reviews actual-vs-reference and drives one of:
+ * approve (advance), request a fix from findings (dispatch the Tester's `fixer`, then re-park),
+ * or recapture (refresh the pairs from the latest UI-tester report). Modelled like the
+ * `human-test` gate (the slow/awaiting work runs in the durable driver; the human actions just
+ * record intent + signal). Passes through (auto-advances) when no binary-artifact store is wired.
+ */
+export declare class VisualConfirmationController {
+    private readonly deps;
+    constructor(deps: VisualConfirmationControllerDeps);
+    /**
+     * Run the gate from `step`. FRESH entry gathers screenshots and parks (or passes through
+     * when no store is wired). RE-ENTRY after a human action consumes the pending action.
+     */
+    evaluate(workspaceId: string, instance: ExecutionInstance, step: PipelineStep, block: Block, isFinalStep: boolean): Promise<AdvanceResult>;
+    /**
+     * A fixer job the gate dispatched has settled (delegated from `pollAgentJob`). Record the
+     * round's outcome, refresh the pairs from the latest UI-tester report, and re-park the human.
+     * We never fail the run here — the human is in control.
+     */
+    onHelperComplete(workspaceId: string, instance: ExecutionInstance, step: PipelineStep, update: HelperUpdate): Promise<AdvanceResult>;
+    /** The human approved the screenshots: advance the run. */
+    approve(workspaceId: string, blockId: string): Promise<ExecutionInstance>;
+    /** The human wrote findings and asked for a fix: dispatch the Tester's `fixer`. */
+    requestFix(workspaceId: string, blockId: string, findings: string): Promise<ExecutionInstance>;
+    /**
+     * Re-pair actual-vs-reference from the current store state: the latest UI-tester report's
+     * screenshots PLUS any reference design images uploaded since the gate parked. This is the
+     * action a human takes after uploading (or replacing) reference images mid-review, or after an
+     * out-of-band UI-tester re-run. NOTE: it does not itself re-run the UI tester — auto re-capture
+     * after a fix is a deferred enhancement (see the visual-confirmation handover doc) — so with no
+     * new references/run it is a harmless refresh that re-reads the same pairs.
+     */
+    recapture(workspaceId: string, blockId: string): Promise<ExecutionInstance>;
+    /** Fresh entry: gather screenshots and park (or pass through when no store is wired). */
+    private begin;
+    /** Consume a human-requested action on re-entry. */
+    private handleAction;
+    /** Dispatch the Tester's `fixer` from the human's findings and park on its job. */
+    private dispatchFixer;
+    /** Gather actual-vs-reference pairs: the latest UI-tester report's screenshots + block references. */
+    private gatherPairs;
+    /** Flip to awaiting-human, summon the human (idempotent notification), and park. */
+    private toAwaitingHuman;
+    /** Finish the gate step and advance to the next step (or finish the run). */
+    private completeStep;
+    /**
+     * Record the human's action on the parked gate step and wake the durable driver, which
+     * re-enters {@link evaluate} and acts on it. Re-arms the run to `running` first.
+     */
+    private signalAction;
+    /** Locate the run + gate step a block's visual-confirmation gate is parked on (or null). */
+    private findParked;
+    private requireParked;
+    private proposal;
+    /** Summon the human to review (idempotent per block+type). Best-effort. */
+    private raiseReadyNotification;
+    /** Dismiss the "ready for review" card once the gate passes. Best-effort. */
+    private clearReadyNotification;
+}
+export {};
+//# sourceMappingURL=VisualConfirmationController.d.ts.map

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

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

package/dist/modules/execution/VisualConfirmationController.js

@@ -0,0 +1,352 @@
+import { ConflictError, isAsyncAgentExecutor } from '@cat-factory/kernel';
+import { FIXER_AGENT_KIND, UI_TESTER_AGENT_KIND, VISUAL_CONFIRM_AGENT_KIND } from './ci.logic.js';
+/** Render the human's findings as the resolved-context block handed to the fixer. */
+function renderFindingsForFixer(findings) {
+    return [
+        'A human reviewed the UI screenshots against the reference designs and asked for the',
+        'changes below. Fix them and push to the PR branch; the UI will be reviewed again.',
+        '',
+        findings.trim(),
+    ]
+        .join('\n')
+        .trim();
+}
+/**
+ * Drives the `visual-confirmation` gate: a non-LLM engine step where a HUMAN is the verdict.
+ * When reached it gathers the UI tester's captured screenshots + the human-uploaded reference
+ * designs (paired by view) and PARKS; a person reviews actual-vs-reference and drives one of:
+ * approve (advance), request a fix from findings (dispatch the Tester's `fixer`, then re-park),
+ * or recapture (refresh the pairs from the latest UI-tester report). Modelled like the
+ * `human-test` gate (the slow/awaiting work runs in the durable driver; the human actions just
+ * record intent + signal). Passes through (auto-advances) when no binary-artifact store is wired.
+ */
+export class VisualConfirmationController {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    // ---- driver-entry paths --------------------------------------------------
+    /**
+     * Run the gate from `step`. FRESH entry gathers screenshots and parks (or passes through
+     * when no store is wired). RE-ENTRY after a human action consumes the pending action.
+     */
+    async evaluate(workspaceId, instance, step, block, isFinalStep) {
+        const vc = step.visualConfirm;
+        if (vc?.pendingAction) {
+            const action = vc.pendingAction;
+            vc.pendingAction = null;
+            // Checkpoint the consumed action BEFORE any slow/side-effecting work (a fixer dispatch
+            // is a real container), so a retry can't re-consume it and dispatch a second helper.
+            await this.deps.persistInstance(workspaceId, instance);
+            return this.handleAction(workspaceId, instance, step, block, isFinalStep, action);
+        }
+        if (!vc)
+            return this.begin(workspaceId, instance, step, block, isFinalStep);
+        // A fixer is in flight: re-attach to its job rather than re-parking.
+        if (vc.phase === 'fixing' && step.jobId) {
+            return { kind: 'awaiting_job', jobId: step.jobId, stepIndex: instance.currentStep };
+        }
+        return this.deps.parkStepOnDecision(workspaceId, instance, step, this.proposal(vc));
+    }
+    /**
+     * A fixer job the gate dispatched has settled (delegated from `pollAgentJob`). Record the
+     * round's outcome, refresh the pairs from the latest UI-tester report, and re-park the human.
+     * We never fail the run here — the human is in control.
+     */
+    async onHelperComplete(workspaceId, instance, step, update) {
+        const vc = step.visualConfirm;
+        if (!vc)
+            return { kind: 'continue' };
+        const rounds = vc.rounds ?? [];
+        const last = rounds[rounds.length - 1];
+        if (last && !last.outcome)
+            last.outcome = update.state === 'failed' ? 'failed' : 'completed';
+        step.jobId = undefined;
+        step.subtasks = undefined;
+        // Reclaim the finished helper container before re-parking.
+        await this.deps.stopRunContainer(workspaceId, instance);
+        const block = await this.deps.blockRepository.get(workspaceId, instance.blockId);
+        if (!block)
+            return { kind: 'noop' };
+        vc.pairs = await this.gatherPairs(workspaceId, instance, block);
+        // The pairs come from the LAST UI-tester report, which predates this fix — the gate does
+        // not auto re-run the UI tester yet (see the handover doc). Flag the staleness so the human
+        // knows to recapture (or re-run the UI tester) before judging the screenshots as final,
+        // unless the fix itself failed (then the existing pre-fix shots are still the right ones).
+        vc.degradedReason =
+            update.state === 'failed'
+                ? 'The requested fix did not complete — review the change manually, then approve or retry.'
+                : 'A fix was applied. These screenshots were captured BEFORE it — recapture (or re-run the UI tester) to refresh them before approving.';
+        return this.toAwaitingHuman(workspaceId, instance, step, block);
+    }
+    // ---- human actions (called from ExecutionService, driven server-side) ----
+    /** The human approved the screenshots: advance the run. */
+    async approve(workspaceId, blockId) {
+        return this.signalAction(workspaceId, blockId, { type: 'approve' });
+    }
+    /** The human wrote findings and asked for a fix: dispatch the Tester's `fixer`. */
+    async requestFix(workspaceId, blockId, findings) {
+        return this.signalAction(workspaceId, blockId, { type: 'request-fix', findings });
+    }
+    /**
+     * Re-pair actual-vs-reference from the current store state: the latest UI-tester report's
+     * screenshots PLUS any reference design images uploaded since the gate parked. This is the
+     * action a human takes after uploading (or replacing) reference images mid-review, or after an
+     * out-of-band UI-tester re-run. NOTE: it does not itself re-run the UI tester — auto re-capture
+     * after a fix is a deferred enhancement (see the visual-confirmation handover doc) — so with no
+     * new references/run it is a harmless refresh that re-reads the same pairs.
+     */
+    async recapture(workspaceId, blockId) {
+        return this.signalAction(workspaceId, blockId, { type: 'recapture' });
+    }
+    // ---- internals -----------------------------------------------------------
+    /** Fresh entry: gather screenshots and park (or pass through when no store is wired). */
+    async begin(workspaceId, instance, step, block, isFinalStep) {
+        // No store ⇒ nowhere to read screenshots from: pass through so a pipeline that includes
+        // the gate still completes (tests / a deployment without blob storage).
+        if (!this.deps.binaryArtifactStore) {
+            return this.completeStep(workspaceId, instance, step, isFinalStep);
+        }
+        const maxAttempts = (await this.deps.resolveMergePreset(workspaceId, block)).ciMaxAttempts;
+        const pairs = await this.gatherPairs(workspaceId, instance, block);
+        step.visualConfirm = {
+            phase: 'awaiting_human',
+            pairs,
+            attempts: 0,
+            maxAttempts,
+            rounds: [],
+            ...(pairs.length === 0
+                ? {
+                    degradedReason: 'No UI screenshots were captured for this task — review the change manually, then approve or request a fix.',
+                }
+                : {}),
+        };
+        return this.toAwaitingHuman(workspaceId, instance, step, block);
+    }
+    /** Consume a human-requested action on re-entry. */
+    async handleAction(workspaceId, instance, step, block, isFinalStep, action) {
+        switch (action.type) {
+            case 'approve': {
+                const vc = step.visualConfirm;
+                if (vc)
+                    vc.phase = 'approved';
+                await this.clearReadyNotification(workspaceId, instance.blockId);
+                return this.completeStep(workspaceId, instance, step, isFinalStep);
+            }
+            case 'request-fix':
+                return this.dispatchFixer(workspaceId, instance, step, block, action.findings ?? '');
+            case 'recapture': {
+                const vc = step.visualConfirm;
+                if (vc)
+                    vc.pairs = await this.gatherPairs(workspaceId, instance, block);
+                return this.toAwaitingHuman(workspaceId, instance, step, block);
+            }
+        }
+    }
+    /** Dispatch the Tester's `fixer` from the human's findings and park on its job. */
+    async dispatchFixer(workspaceId, instance, step, block, findings) {
+        const vc = step.visualConfirm;
+        const executor = this.deps.agentExecutor;
+        // The fixer pushes onto the PR branch, so it needs one to exist + an async executor. If
+        // it can't run, DON'T silently swallow the human's findings: surface why on the gate (a
+        // degraded reason + a recorded failed round) and re-park, so the human sees the request
+        // didn't dispatch rather than the window quietly resetting.
+        if (!isAsyncAgentExecutor(executor) || !block.pullRequest?.branch) {
+            vc.degradedReason = !block.pullRequest?.branch
+                ? 'Could not request a fix: this task has no open pull-request branch for the fixer to push to. Review the change manually, then approve.'
+                : 'Could not request a fix: no async agent executor is wired in this runtime. Review the change manually, then approve.';
+            vc.rounds = [
+                ...(vc.rounds ?? []),
+                {
+                    findings,
+                    helperKind: FIXER_AGENT_KIND,
+                    jobId: null,
+                    outcome: 'failed',
+                    at: this.deps.clockNow(),
+                },
+            ];
+            return this.toAwaitingHuman(workspaceId, instance, step, block);
+        }
+        const isFinalStep = instance.currentStep === instance.steps.length - 1;
+        const base = await this.deps.contextBuilder.buildContext(workspaceId, instance, step, isFinalStep, block);
+        const context = {
+            ...base,
+            agentKind: FIXER_AGENT_KIND,
+            priorOutputs: [
+                ...base.priorOutputs,
+                { agentKind: VISUAL_CONFIRM_AGENT_KIND, output: renderFindingsForFixer(findings) },
+            ],
+        };
+        const handle = await executor.startJob(context);
+        step.jobId = handle.jobId;
+        if (handle.model)
+            step.model = handle.model;
+        step.startingContainer = true;
+        step.subtasks = undefined;
+        // Leave the parked decision state: while the helper runs the step is `working` with a
+        // live job, NOT parked on a stale approval (a re-drive would otherwise abandon the job).
+        this.deps.startStep(step);
+        step.approval = null;
+        vc.phase = 'fixing';
+        // A fix is now in flight: clear any prior degraded note (e.g. a previous failed dispatch).
+        vc.degradedReason = null;
+        vc.attempts += 1;
+        vc.rounds = [
+            ...(vc.rounds ?? []),
+            {
+                findings,
+                helperKind: FIXER_AGENT_KIND,
+                jobId: handle.jobId,
+                outcome: null,
+                at: this.deps.clockNow(),
+            },
+        ];
+        await this.deps.persistInstance(workspaceId, instance);
+        await this.deps.emitInstance(workspaceId, instance);
+        return { kind: 'awaiting_job', jobId: step.jobId, stepIndex: instance.currentStep };
+    }
+    /** Gather actual-vs-reference pairs: the latest UI-tester report's screenshots + block references. */
+    async gatherPairs(workspaceId, instance, block) {
+        const byView = new Map();
+        // The artifact ids the run ACTUALLY uploaded — so a screenshot id the agent reported but
+        // that was never stored (a fabricated/typo'd id), or one since removed by the retention
+        // sweep, is treated as "not captured" rather than rendered as a dangling/404 gallery image.
+        const validActualIds = this.deps.binaryArtifactStore
+            ? new Set((await this.deps.binaryArtifactStore.listByExecution(workspaceId, instance.id))
+                .filter((r) => r.kind === 'screenshot')
+                .map((r) => r.id))
+            : null;
+        // Actual: the most recent `tester-ui` step's captured screenshots.
+        const uiStep = [...instance.steps]
+            .reverse()
+            .find((s) => s.agentKind === UI_TESTER_AGENT_KIND && s.test?.lastReport);
+        for (const shot of uiStep?.test?.lastReport?.screenshots ?? []) {
+            const actualArtifactId = validActualIds === null || validActualIds.has(shot.artifactId) ? shot.artifactId : null;
+            byView.set(shot.view, {
+                view: shot.view,
+                actualArtifactId,
+                referenceArtifactId: shot.referenceArtifactId ?? null,
+            });
+        }
+        // Reference: the block's uploaded reference design images (carry no executionId).
+        if (this.deps.binaryArtifactStore) {
+            const refs = (await this.deps.binaryArtifactStore.listByBlock(workspaceId, block.id)).filter((r) => r.kind === 'reference');
+            // `listByBlock` returns references oldest-first, so assign unconditionally: the LAST
+            // (newest) reference uploaded for a view wins. A human re-uploading a corrected reference
+            // for a view they already populated must override the stale one, not be discarded.
+            for (const ref of refs) {
+                const view = ref.view ?? '(reference)';
+                const existing = byView.get(view);
+                if (existing)
+                    existing.referenceArtifactId = ref.id;
+                else
+                    byView.set(view, { view, actualArtifactId: null, referenceArtifactId: ref.id });
+            }
+        }
+        return [...byView.values()];
+    }
+    /** Flip to awaiting-human, summon the human (idempotent notification), and park. */
+    async toAwaitingHuman(workspaceId, instance, step, block) {
+        const vc = step.visualConfirm;
+        vc.phase = 'awaiting_human';
+        await this.raiseReadyNotification(workspaceId, instance, block, vc);
+        return this.deps.parkStepOnDecision(workspaceId, instance, step, this.proposal(vc));
+    }
+    /** Finish the gate step and advance to the next step (or finish the run). */
+    async completeStep(workspaceId, instance, step, isFinalStep) {
+        this.deps.finishStep(step);
+        step.progress = 1;
+        step.subtasks = undefined;
+        step.approval = null;
+        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' };
+    }
+    /**
+     * Record the human's action on the parked gate step and wake the durable driver, which
+     * re-enters {@link evaluate} and acts on it. Re-arms the run to `running` first.
+     */
+    async signalAction(workspaceId, blockId, action) {
+        const { instance, step } = this.requireParked(await this.findParked(workspaceId, blockId));
+        const vc = step.visualConfirm;
+        if (action.type === 'request-fix' && vc.attempts >= vc.maxAttempts) {
+            throw new ConflictError(`This task has reached its fix-attempt limit (${vc.maxAttempts}); approve the change or review it manually.`);
+        }
+        vc.pendingAction = action;
+        if (instance.status === 'blocked')
+            instance.status = 'running';
+        await this.deps.persistInstance(workspaceId, instance);
+        await this.deps.emitInstance(workspaceId, instance);
+        await this.deps.workRunner.signalDecision(workspaceId, instance.id, step.approval.id, 'visual-confirmation');
+        return instance;
+    }
+    /** Locate the run + gate step a block's visual-confirmation gate is parked on (or null). */
+    async findParked(workspaceId, blockId) {
+        const block = await this.deps.blockRepository.get(workspaceId, blockId);
+        if (!block?.executionId)
+            return null;
+        const instance = await this.deps.executionRepository.get(workspaceId, block.executionId);
+        if (!instance)
+            return null;
+        const step = instance.steps.find((s) => s.agentKind === VISUAL_CONFIRM_AGENT_KIND &&
+            s.state === 'waiting_decision' &&
+            s.approval?.status === 'pending');
+        return step ? { instance, step } : null;
+    }
+    requireParked(found) {
+        if (!found)
+            throw new ConflictError('No visual-confirmation gate is currently awaiting input');
+        return found;
+    }
+    proposal(vc) {
+        const n = vc.pairs?.length ?? 0;
+        return n > 0
+            ? `Review ${n} screenshot${n === 1 ? '' : 's'} against the reference designs, then approve or request a fix.`
+            : 'Review the UI change, then approve or request a fix.';
+    }
+    /** Summon the human to review (idempotent per block+type). Best-effort. */
+    async raiseReadyNotification(workspaceId, instance, block, vc) {
+        if (!this.deps.notificationService)
+            return;
+        const n = vc.pairs?.length ?? 0;
+        await this.deps.notificationService.raise(workspaceId, {
+            type: 'visual_confirmation_ready',
+            blockId: block.id,
+            executionId: instance.id,
+            title: `"${block.title}" is ready for visual confirmation`,
+            body: n > 0
+                ? `Review ${n} captured screenshot${n === 1 ? '' : 's'} against the reference designs, then approve or request a fix.`
+                : 'Review the UI change, then approve or request a fix.',
+            payload: {
+                ...(block.pullRequest?.url ? { prUrl: block.pullRequest.url } : {}),
+                pipelineName: instance.pipelineName,
+            },
+        });
+    }
+    /** Dismiss the "ready for review" card once the gate passes. Best-effort. */
+    async clearReadyNotification(workspaceId, blockId) {
+        const svc = this.deps.notificationService;
+        if (!svc)
+            return;
+        const open = await svc.listOpen(workspaceId);
+        for (const card of open) {
+            if (card.type === 'visual_confirmation_ready' && card.blockId === blockId) {
+                await svc.resolve(workspaceId, card.id, 'act');
+            }
+        }
+    }
+}
+//# sourceMappingURL=VisualConfirmationController.js.map

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

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

package/dist/modules/execution/ci.logic.d.ts

@@ -54,12 +54,26 @@ export declare const BLUEPRINTS_AGENT_KIND = "blueprints";
 /** The agent kind of the container agent that scores a PR for the merge decision. */
 export declare const MERGER_AGENT_KIND = "merger";
 /**
- * The agent kind of the special `tester` gate step: a container agent that runs the
- * project's tests (local docker-compose infra or an ephemeral env) and returns a
- * structured report. On a withheld greenlight the engine loops the `fixer` agent
- * with the report and re-tests — mirroring the CI gate / ci-fixer loop.
+ * The agent kind of the API/general tester gate step (formerly `tester`): a container
+ * agent that runs the project's tests (local docker-compose infra or an ephemeral env)
+ * and returns a structured report. On a withheld greenlight the engine loops the `fixer`
+ * agent with the report and re-tests — mirroring the CI gate / ci-fixer loop. The UI
+ * tester ({@link UI_TESTER_AGENT_KIND}) is its browser-driven, screenshot-capturing sibling.
  */
-export declare const TESTER_AGENT_KIND = "tester";
+export declare const TESTER_AGENT_KIND = "tester-api";
+/**
+ * The agent kind of the UI tester gate step: like {@link TESTER_AGENT_KIND} but it drives
+ * a real browser (Playwright/Chromium — supplied by a dedicated UI-tester container image)
+ * against the running app, captures a non-redundant screenshot of each distinct view, and
+ * uploads them to the binary-artifact store. Its report carries `screenshots[]`, which the
+ * visual-confirmation gate reviews against the supplied reference designs. Shares the
+ * Tester→Fixer loop and the `tester.environment` infra choice; always needs a running app.
+ */
+export declare const UI_TESTER_AGENT_KIND = "tester-ui";
+/** Both tester gate kinds (API + UI). They share the Tester→Fixer loop + infra choice. */
+export declare const TESTER_KINDS: readonly string[];
+/** Whether an agent kind is one of the tester gate kinds (API or UI). */
+export declare function isTesterKind(kind: string): boolean;
 /**
  * The agent kind of the read-only code-analysis agent that opens the tech-debt
  * recurring pipeline: it inspects the repo and emits a prioritized markdown report
@@ -82,4 +96,13 @@ export declare const TRACKER_AGENT_KIND = "tracker";
  * (no-env) mode when no ephemeral-environment provider is wired.
  */
 export declare const HUMAN_TEST_AGENT_KIND = "human-test";
+/**
+ * The agent kind of the special `visual-confirmation` gate: a non-LLM engine step that
+ * PARKS for a human to review the UI tester's screenshots against the uploaded reference
+ * designs, then on demand dispatches the Tester's `fixer` (from the human's findings) and
+ * re-captures via the UI tester. Approving advances the run. Handled by the
+ * {@link VisualConfirmationController}; passes through (auto-advances) when no binary-artifact
+ * store is wired (nowhere to read screenshots from).
+ */
+export declare const VISUAL_CONFIRM_AGENT_KIND = "visual-confirmation";
 //# sourceMappingURL=ci.logic.d.ts.map

package/dist/modules/execution/ci.logic.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ci.logic.d.ts","sourceRoot":"","sources":["../../../src/modules/execution/ci.logic.ts"],"names":[],"mappings":"AAIA,OAAO,EACL,aAAa,EACb,mBAAmB,EACnB,oBAAoB,EACpB,4BAA4B,EAC5B,gBAAgB,EAChB,uBAAuB,EACvB,KAAK,SAAS,EACd,WAAW,EACX,SAAS,EACT,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,qBAAqB,CAAA;AAE5B;;;;;;GAMG;AACH,eAAO,MAAM,8BAA8B,wBAAwB,CAAA;AAEnE;;;;;;;GAOG;AACH,eAAO,MAAM,yBAAyB,mBAAmB,CAAA;AAEzD;;;;;;;;;GASG;AACH,eAAO,MAAM,kCAAkC,4BAA4B,CAAA;AAC3E,eAAO,MAAM,kCAAkC,4BAA4B,CAAA;AAE3E;;;;;;;GAOG;AACH,eAAO,MAAM,2BAA2B,qBAAqB,CAAA;AAE7D;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,gBAAgB,CAAA;AAEnD;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,eAAe,CAAA;AAEjD,qFAAqF;AACrF,eAAO,MAAM,iBAAiB,WAAW,CAAA;AAEzC;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,WAAW,CAAA;AAEzC;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,aAAa,CAAA;AAE7C;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,YAAY,CAAA;AAE3C;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB,eAAe,CAAA"}
+{"version":3,"file":"ci.logic.d.ts","sourceRoot":"","sources":["../../../src/modules/execution/ci.logic.ts"],"names":[],"mappings":"AAIA,OAAO,EACL,aAAa,EACb,mBAAmB,EACnB,oBAAoB,EACpB,4BAA4B,EAC5B,gBAAgB,EAChB,uBAAuB,EACvB,KAAK,SAAS,EACd,WAAW,EACX,SAAS,EACT,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,qBAAqB,CAAA;AAE5B;;;;;;GAMG;AACH,eAAO,MAAM,8BAA8B,wBAAwB,CAAA;AAEnE;;;;;;;GAOG;AACH,eAAO,MAAM,yBAAyB,mBAAmB,CAAA;AAEzD;;;;;;;;;GASG;AACH,eAAO,MAAM,kCAAkC,4BAA4B,CAAA;AAC3E,eAAO,MAAM,kCAAkC,4BAA4B,CAAA;AAE3E;;;;;;;GAOG;AACH,eAAO,MAAM,2BAA2B,qBAAqB,CAAA;AAE7D;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,gBAAgB,CAAA;AAEnD;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,eAAe,CAAA;AAEjD,qFAAqF;AACrF,eAAO,MAAM,iBAAiB,WAAW,CAAA;AAEzC;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,eAAe,CAAA;AAE7C;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,cAAc,CAAA;AAE/C,0FAA0F;AAC1F,eAAO,MAAM,YAAY,EAAE,SAAS,MAAM,EAA8C,CAAA;AAExF,yEAAyE;AACzE,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAElD;AAED;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,aAAa,CAAA;AAE7C;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,YAAY,CAAA;AAE3C;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB,eAAe,CAAA;AAEjD;;;;;;;GAOG;AACH,eAAO,MAAM,yBAAyB,wBAAwB,CAAA"}

package/dist/modules/execution/ci.logic.js

@@ -58,12 +58,28 @@ export const BLUEPRINTS_AGENT_KIND = 'blueprints';
 /** The agent kind of the container agent that scores a PR for the merge decision. */
 export const MERGER_AGENT_KIND = 'merger';
 /**
- * The agent kind of the special `tester` gate step: a container agent that runs the
- * project's tests (local docker-compose infra or an ephemeral env) and returns a
- * structured report. On a withheld greenlight the engine loops the `fixer` agent
- * with the report and re-tests — mirroring the CI gate / ci-fixer loop.
+ * The agent kind of the API/general tester gate step (formerly `tester`): a container
+ * agent that runs the project's tests (local docker-compose infra or an ephemeral env)
+ * and returns a structured report. On a withheld greenlight the engine loops the `fixer`
+ * agent with the report and re-tests — mirroring the CI gate / ci-fixer loop. The UI
+ * tester ({@link UI_TESTER_AGENT_KIND}) is its browser-driven, screenshot-capturing sibling.
  */
-export const TESTER_AGENT_KIND = 'tester';
+export const TESTER_AGENT_KIND = 'tester-api';
+/**
+ * The agent kind of the UI tester gate step: like {@link TESTER_AGENT_KIND} but it drives
+ * a real browser (Playwright/Chromium — supplied by a dedicated UI-tester container image)
+ * against the running app, captures a non-redundant screenshot of each distinct view, and
+ * uploads them to the binary-artifact store. Its report carries `screenshots[]`, which the
+ * visual-confirmation gate reviews against the supplied reference designs. Shares the
+ * Tester→Fixer loop and the `tester.environment` infra choice; always needs a running app.
+ */
+export const UI_TESTER_AGENT_KIND = 'tester-ui';
+/** Both tester gate kinds (API + UI). They share the Tester→Fixer loop + infra choice. */
+export const TESTER_KINDS = [TESTER_AGENT_KIND, UI_TESTER_AGENT_KIND];
+/** Whether an agent kind is one of the tester gate kinds (API or UI). */
+export function isTesterKind(kind) {
+    return kind === TESTER_AGENT_KIND || kind === UI_TESTER_AGENT_KIND;
+}
 /**
  * The agent kind of the read-only code-analysis agent that opens the tech-debt
  * recurring pipeline: it inspects the repo and emits a prioritized markdown report
@@ -86,4 +102,13 @@ export const TRACKER_AGENT_KIND = 'tracker';
  * (no-env) mode when no ephemeral-environment provider is wired.
  */
 export const HUMAN_TEST_AGENT_KIND = 'human-test';
+/**
+ * The agent kind of the special `visual-confirmation` gate: a non-LLM engine step that
+ * PARKS for a human to review the UI tester's screenshots against the uploaded reference
+ * designs, then on demand dispatches the Tester's `fixer` (from the human's findings) and
+ * re-captures via the UI tester. Approving advances the run. Handled by the
+ * {@link VisualConfirmationController}; passes through (auto-advances) when no binary-artifact
+ * store is wired (nowhere to read screenshots from).
+ */
+export const VISUAL_CONFIRM_AGENT_KIND = 'visual-confirmation';
 //# sourceMappingURL=ci.logic.js.map

package/dist/modules/execution/ci.logic.js.map

@@ -1 +1 @@
-{"version":3,"file":"ci.logic.js","sourceRoot":"","sources":["../../../src/modules/execution/ci.logic.ts"],"names":[],"mappings":"AAAA,sFAAsF;AACtF,oFAAoF;AACpF,yFAAyF;AACzF,iDAAiD;AACjD,OAAO,EACL,aAAa,EACb,mBAAmB,EACnB,oBAAoB,EACpB,4BAA4B,EAC5B,gBAAgB,EAChB,uBAAuB,EAEvB,WAAW,EACX,SAAS,EACT,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,qBAAqB,CAAA;AAE5B;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,8BAA8B,GAAG,qBAAqB,CAAA;AAEnE;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,gBAAgB,CAAA;AAEzD;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,kCAAkC,GAAG,yBAAyB,CAAA;AAC3E,MAAM,CAAC,MAAM,kCAAkC,GAAG,yBAAyB,CAAA;AAE3E;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,kBAAkB,CAAA;AAE7D;;;;;GAKG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,aAAa,CAAA;AAEnD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,YAAY,CAAA;AAEjD,qFAAqF;AACrF,MAAM,CAAC,MAAM,iBAAiB,GAAG,QAAQ,CAAA;AAEzC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,QAAQ,CAAA;AAEzC;;;;GAIG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,UAAU,CAAA;AAE7C;;;;;GAKG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,SAAS,CAAA;AAE3C;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,YAAY,CAAA"}
+{"version":3,"file":"ci.logic.js","sourceRoot":"","sources":["../../../src/modules/execution/ci.logic.ts"],"names":[],"mappings":"AAAA,sFAAsF;AACtF,oFAAoF;AACpF,yFAAyF;AACzF,iDAAiD;AACjD,OAAO,EACL,aAAa,EACb,mBAAmB,EACnB,oBAAoB,EACpB,4BAA4B,EAC5B,gBAAgB,EAChB,uBAAuB,EAEvB,WAAW,EACX,SAAS,EACT,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,qBAAqB,CAAA;AAE5B;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,8BAA8B,GAAG,qBAAqB,CAAA;AAEnE;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,gBAAgB,CAAA;AAEzD;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,kCAAkC,GAAG,yBAAyB,CAAA;AAC3E,MAAM,CAAC,MAAM,kCAAkC,GAAG,yBAAyB,CAAA;AAE3E;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,kBAAkB,CAAA;AAE7D;;;;;GAKG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,aAAa,CAAA;AAEnD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,YAAY,CAAA;AAEjD,qFAAqF;AACrF,MAAM,CAAC,MAAM,iBAAiB,GAAG,QAAQ,CAAA;AAEzC;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,YAAY,CAAA;AAE7C;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,WAAW,CAAA;AAE/C,0FAA0F;AAC1F,MAAM,CAAC,MAAM,YAAY,GAAsB,CAAC,iBAAiB,EAAE,oBAAoB,CAAC,CAAA;AAExF,yEAAyE;AACzE,MAAM,UAAU,YAAY,CAAC,IAAY;IACvC,OAAO,IAAI,KAAK,iBAAiB,IAAI,IAAI,KAAK,oBAAoB,CAAA;AACpE,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,UAAU,CAAA;AAE7C;;;;;GAKG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,SAAS,CAAA;AAE3C;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,YAAY,CAAA;AAEjD;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,qBAAqB,CAAA"}

package/dist/modules/observability/observability.logic.d.ts

@@ -16,6 +16,12 @@ export declare function classifyCall(metric: Pick<LlmCallMetric, 'ok' | 'finishR
 export declare function outputHeadroomRatio(peakCompletionTokens: number, maxOutputTokens: number | null): number | null;
 /** Share of total latency spent in transport/proxy overhead (0..1), or null when no timing. */
 export declare function transportOverheadRatio(upstreamMs: number, overheadMs: number): number | null;
+/**
+ * Share of prompt tokens served from the provider's prefix cache (0..1), or null when
+ * there were no prompt tokens. A low rate on a multi-turn run flags a cache-less hot
+ * path (e.g. a Workers-AI flavour) re-billing the whole prompt every turn.
+ */
+export declare function cacheHitRate(cachedPromptTokens: number, promptTokens: number): number | null;
 /** The previous call's chain tip: enough to decide if the next call extends it. */
 export interface PromptChainTip {
     /** The previous call's full message count (its `messageCount`). */

package/dist/modules/observability/observability.logic.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"observability.logic.d.ts","sourceRoot":"","sources":["../../../src/modules/observability/observability.logic.ts"],"names":[],"mappings":"AAAA,OAAO,EAA8B,KAAK,aAAa,EAAE,MAAM,qBAAqB,CAAA;AACpF,OAAO,KAAK,EAAoB,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AAMhF,MAAM,MAAM,cAAc,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAAA;AAEvD,uFAAuF;AACvF,wBAAgB,qBAAqB,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAI1E;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,IAAI,CAAC,aAAa,EAAE,IAAI,GAAG,cAAc,CAAC,GAAG,cAAc,CAI/F;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,oBAAoB,EAAE,MAAM,EAC5B,eAAe,EAAE,MAAM,GAAG,IAAI,GAC7B,MAAM,GAAG,IAAI,CAGf;AAED,+FAA+F;AAC/F,wBAAgB,sBAAsB,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAG5F;AAkBD,mFAAmF;AACnF,MAAM,WAAW,cAAc;IAC7B,mEAAmE;IACnE,YAAY,EAAE,MAAM,CAAA;IACpB,qFAAqF;IACrF,UAAU,EAAE,MAAM,CAAA;CACnB;AAED,iEAAiE;AACjE,MAAM,WAAW,YAAY;IAC3B,UAAU,EAAE,MAAM,CAAA;IAClB,iBAAiB,EAAE,MAAM,CAAA;IACzB,UAAU,EAAE,MAAM,CAAA;CACnB;AAED,uFAAuF;AACvF,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAS/C;AAWD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,cAAc,EAAE,MAAM,EACtB,IAAI,EAAE,cAAc,GAAG,IAAI,GAC1B,YAAY,CAkBd;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,aAAa,EAAE,GAAG,aAAa,EAAE,CAgC1E;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,aAAa,EAAE,EAC5B,WAAW,EAAE,MAAM,GAClB,gBAAgB,CAwDlB"}
+{"version":3,"file":"observability.logic.d.ts","sourceRoot":"","sources":["../../../src/modules/observability/observability.logic.ts"],"names":[],"mappings":"AAAA,OAAO,EAA8B,KAAK,aAAa,EAAE,MAAM,qBAAqB,CAAA;AACpF,OAAO,KAAK,EAAoB,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AAMhF,MAAM,MAAM,cAAc,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAAA;AAEvD,uFAAuF;AACvF,wBAAgB,qBAAqB,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAI1E;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,IAAI,CAAC,aAAa,EAAE,IAAI,GAAG,cAAc,CAAC,GAAG,cAAc,CAI/F;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,oBAAoB,EAAE,MAAM,EAC5B,eAAe,EAAE,MAAM,GAAG,IAAI,GAC7B,MAAM,GAAG,IAAI,CAGf;AAED,+FAA+F;AAC/F,wBAAgB,sBAAsB,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAG5F;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,kBAAkB,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAG5F;AAkBD,mFAAmF;AACnF,MAAM,WAAW,cAAc;IAC7B,mEAAmE;IACnE,YAAY,EAAE,MAAM,CAAA;IACpB,qFAAqF;IACrF,UAAU,EAAE,MAAM,CAAA;CACnB;AAED,iEAAiE;AACjE,MAAM,WAAW,YAAY;IAC3B,UAAU,EAAE,MAAM,CAAA;IAClB,iBAAiB,EAAE,MAAM,CAAA;IACzB,UAAU,EAAE,MAAM,CAAA;CACnB;AAED,uFAAuF;AACvF,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAS/C;AAWD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,cAAc,EAAE,MAAM,EACtB,IAAI,EAAE,cAAc,GAAG,IAAI,GAC1B,YAAY,CAkBd;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,aAAa,EAAE,GAAG,aAAa,EAAE,CAgC1E;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,aAAa,EAAE,EAC5B,WAAW,EAAE,MAAM,GAClB,gBAAgB,CAgElB"}