@cat-factory/orchestration 0.6.0

package/dist/modules/clarity/ClarityReviewService.js

@@ -0,0 +1,63 @@
+import { CLARITY_REVIEW_SYSTEM_PROMPT, CLARITY_REWORK_SYSTEM_PROMPT } from '@cat-factory/agents';
+import { IterativeReviewService, } from '../review/IterativeReviewService.js';
+import { buildClarityPrompt, buildClarityReworkPrompt, } from './clarity.logic.js';
+/**
+ * The clarity-review (bug-report triage) agent. A single LLM call triages a block's bug
+ * report for fixability and raises findings, humans answer them, and a second LLM call folds
+ * the answers into a clarified report. The iterative loop lives in
+ * {@link IterativeReviewService}; this class supplies only the bug-report subject (optionally
+ * enriched by an investigator), the prompts and the persisted document field
+ * (`clarifiedReport`).
+ */
+export class ClarityReviewService extends IterativeReviewService {
+    repository;
+    constructor(deps) {
+        super(deps);
+        this.repository = deps.clarityReviewRepository;
+    }
+    entityName = 'Clarity review';
+    reviewerLabel = 'clarity reviewer';
+    reviewAgentKind = 'clarity-review';
+    reworkAgentKind = 'clarity-rework';
+    reviewSystemPrompt = CLARITY_REVIEW_SYSTEM_PROMPT;
+    reworkSystemPrompt = CLARITY_REWORK_SYSTEM_PROMPT;
+    reviewIdPrefix = 'clr';
+    itemIdPrefix = 'clri';
+    revisedNoun = 'revised bug report';
+    truncationMessage = 'The reworked bug report was cut off before completion (model output limit reached). ' +
+        'Try splitting this work into smaller tasks, then rework again.';
+    notificationType = 'clarity_review';
+    notificationSubject = 'The clarity reviewer';
+    notificationTitle(block) {
+        return `Bug-report triage: ${block.title}`;
+    }
+    buildReviewPrompt(ctx) {
+        return buildClarityPrompt(ctx);
+    }
+    buildReworkPrompt(ctx, items) {
+        return buildClarityReworkPrompt(ctx, items);
+    }
+    applyIncorporatedDoc(ctx, doc) {
+        ctx.clarifiedDoc = doc;
+    }
+    applyFeedback(ctx, feedback) {
+        ctx.reworkFeedback = feedback;
+    }
+    readDoc(review) {
+        return review.clarifiedReport;
+    }
+    withDoc(review, doc) {
+        return { ...review, clarifiedReport: doc };
+    }
+    newReview(common) {
+        return { ...common, clarifiedReport: null };
+    }
+    /** Assemble the bug report under review (block + optional investigation). */
+    async gatherContext(_workspaceId, block, input) {
+        return {
+            block: { title: block.title, type: block.type, description: block.description },
+            investigation: input.investigation,
+        };
+    }
+}
+//# sourceMappingURL=ClarityReviewService.js.map

package/dist/modules/clarity/ClarityReviewService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ClarityReviewService.js","sourceRoot":"","sources":["../../../src/modules/clarity/ClarityReviewService.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,4BAA4B,EAAE,4BAA4B,EAAE,MAAM,qBAAqB,CAAA;AAChG,OAAO,EAEL,sBAAsB,GAGvB,MAAM,qCAAqC,CAAA;AAC5C,OAAO,EAEL,kBAAkB,EAClB,wBAAwB,GACzB,MAAM,oBAAoB,CAAA;AAY3B;;;;;;;GAOG;AACH,MAAM,OAAO,oBAAqB,SAAQ,sBAIzC;IACoB,UAAU,CAAiC;IAE9D,YAAY,IAAsC;QAChD,KAAK,CAAC,IAAI,CAAC,CAAA;QACX,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,uBAAuB,CAAA;IAChD,CAAC;IAEkB,UAAU,GAAG,gBAAgB,CAAA;IAC7B,aAAa,GAAG,kBAAkB,CAAA;IAClC,eAAe,GAAG,gBAAgB,CAAA;IAClC,eAAe,GAAG,gBAAgB,CAAA;IAClC,kBAAkB,GAAG,4BAA4B,CAAA;IACjD,kBAAkB,GAAG,4BAA4B,CAAA;IACjD,cAAc,GAAG,KAAK,CAAA;IACtB,YAAY,GAAG,MAAM,CAAA;IACrB,WAAW,GAAG,oBAAoB,CAAA;IAClC,iBAAiB,GAClC,sFAAsF;QACtF,gEAAgE,CAAA;IAC/C,gBAAgB,GAAG,gBAAyB,CAAA;IAC5C,mBAAmB,GAAG,sBAAsB,CAAA;IAErD,iBAAiB,CAAC,KAAY;QACtC,OAAO,sBAAsB,KAAK,CAAC,KAAK,EAAE,CAAA;IAC5C,CAAC;IAES,iBAAiB,CAAC,GAAmB;QAC7C,OAAO,kBAAkB,CAAC,GAAG,CAAC,CAAA;IAChC,CAAC;IAES,iBAAiB,CAAC,GAAmB,EAAE,KAA8B;QAC7E,OAAO,wBAAwB,CAAC,GAAG,EAAE,KAAK,CAAC,CAAA;IAC7C,CAAC;IAES,oBAAoB,CAAC,GAAmB,EAAE,GAAW;QAC7D,GAAG,CAAC,YAAY,GAAG,GAAG,CAAA;IACxB,CAAC;IAES,aAAa,CAAC,GAAmB,EAAE,QAAgB;QAC3D,GAAG,CAAC,cAAc,GAAG,QAAQ,CAAA;IAC/B,CAAC;IAES,OAAO,CAAC,MAAqB;QACrC,OAAO,MAAM,CAAC,eAAe,CAAA;IAC/B,CAAC;IAES,OAAO,CAAC,MAAqB,EAAE,GAAW;QAClD,OAAO,EAAE,GAAG,MAAM,EAAE,eAAe,EAAE,GAAG,EAAE,CAAA;IAC5C,CAAC;IAES,SAAS,CAAC,MAAoB;QACtC,OAAO,EAAE,GAAG,MAAM,EAAE,eAAe,EAAE,IAAI,EAAE,CAAA;IAC7C,CAAC;IAED,6EAA6E;IACnE,KAAK,CAAC,aAAa,CAC3B,YAAoB,EACpB,KAAY,EACZ,KAA0B;QAE1B,OAAO;YACL,KAAK,EAAE,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,WAAW,EAAE,KAAK,CAAC,WAAW,EAAE;YAC/E,aAAa,EAAE,KAAK,CAAC,aAAa;SACnC,CAAA;IACH,CAAC;CACF"}

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

@@ -0,0 +1,36 @@
+import type { Block, RequirementReviewItem } from '@cat-factory/kernel';
+export { coerceReviewItems, disposeReview, extractJson, hasNotesToIncorporate, type ReviewDisposition, } from '../requirements/requirements.logic.js';
+/** Everything the clarity reviewer reasons over: the bug report plus any investigation. */
+export interface ClarityContext {
+    block: Pick<Block, 'title' | 'type' | 'description'>;
+    /**
+     * The prose report an upstream `bug-investigator` step produced (enriched bug report +
+     * optional working hypothesis). When present it is the primary triage subject — the raw
+     * description becomes background. Absent when no investigator ran.
+     */
+    investigation?: string;
+    /**
+     * The clarified bug report produced by a prior incorporation. When present (a re-review
+     * or a redo), it is the authoritative report the reviewer/rework reasons over. Absent on
+     * the first pass.
+     */
+    clarifiedDoc?: string;
+    /** The human's freeform "do it differently" comment when redoing a merge. Absent otherwise. */
+    reworkFeedback?: string;
+}
+/**
+ * Render the bug report under review as a single Markdown document — the clarified report
+ * when one exists (a later cycle), else the block description plus the investigator's
+ * enriched report when present. Used both as the reviewer's input and as the base the
+ * incorporate step rewrites.
+ */
+export declare function renderBugReport(ctx: ClarityContext): string;
+export declare function buildClarityPrompt(ctx: ClarityContext): string;
+/**
+ * Build the user prompt for the clarity-rework step: the gathered bug report plus the
+ * human's answers (folded in) and dismissals (kept out). Works with an empty item list
+ * (the "no challenges" path simply restates the report in the standard structure). The
+ * {@link CLARITY_REWORK_SYSTEM_PROMPT} (in `@cat-factory/agents`) defines the output shape.
+ */
+export declare function buildClarityReworkPrompt(ctx: ClarityContext, items: RequirementReviewItem[]): string;
+//# sourceMappingURL=clarity.logic.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"clarity.logic.d.ts","sourceRoot":"","sources":["../../../src/modules/clarity/clarity.logic.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAA;AAWvE,OAAO,EACL,iBAAiB,EACjB,aAAa,EACb,WAAW,EACX,qBAAqB,EACrB,KAAK,iBAAiB,GACvB,MAAM,uCAAuC,CAAA;AAE9C,2FAA2F;AAC3F,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,aAAa,CAAC,CAAA;IACpD;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,+FAA+F;IAC/F,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,cAAc,GAAG,MAAM,CAsB3D;AAED,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,cAAc,GAAG,MAAM,CAwB9D;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,GAAG,EAAE,cAAc,EACnB,KAAK,EAAE,qBAAqB,EAAE,GAC7B,MAAM,CA0CR"}

package/dist/modules/clarity/clarity.logic.js

@@ -0,0 +1,98 @@
+// Pure logic for the clarity-review (bug-report triage) agent: assembling the bug
+// report under review (the block description, optionally enriched by an upstream
+// `bug-investigator` step's prose report), and building the triage + rework prompts.
+// The item parsing / disposition helpers are subject-agnostic and REUSED from the
+// requirements logic — this file only supplies the clarity-specific subject + prompts.
+//
+// Re-export the shared helpers so the clarity service imports its whole logic surface
+// from here (one import site), mirroring how `requirements.logic` is the requirements
+// service's surface.
+export { coerceReviewItems, disposeReview, extractJson, hasNotesToIncorporate, } from '../requirements/requirements.logic.js';
+/**
+ * Render the bug report under review as a single Markdown document — the clarified report
+ * when one exists (a later cycle), else the block description plus the investigator's
+ * enriched report when present. Used both as the reviewer's input and as the base the
+ * incorporate step rewrites.
+ */
+export function renderBugReport(ctx) {
+    const lines = ctx.clarifiedDoc?.trim()
+        ? [
+            `# ${ctx.block.title} (${ctx.block.type})`,
+            '',
+            '## Current standardized bug report (under review)',
+            ctx.clarifiedDoc.trim(),
+        ]
+        : [
+            `# ${ctx.block.title} (${ctx.block.type})`,
+            '',
+            '## Reported bug',
+            ctx.block.description?.trim() || '(no description provided)',
+        ];
+    if (!ctx.clarifiedDoc?.trim() && ctx.investigation?.trim()) {
+        lines.push('', '## Investigation (read-only findings from the codebase)', ctx.investigation.trim());
+    }
+    return lines.join('\n');
+}
+export function buildClarityPrompt(ctx) {
+    return [
+        'Here is the bug report to triage for fixability:',
+        '',
+        renderBugReport(ctx),
+        '',
+        'Produce a JSON object of this exact shape:',
+        '{',
+        '  "items": [',
+        '    {',
+        '      "category": "gap|clarification|assumption|risk|question",',
+        '      "severity": "low|medium|high",',
+        '      "title": "short headline of the concern",',
+        '      "detail": "the full question / gap / challenge, phrased for the bug reporter"',
+        '    }',
+        '  ]',
+        '}',
+        '',
+        'Assign a severity to EVERY item — no item may omit it. Use `high` for a missing detail ' +
+            'that would block a confident fix (e.g. no reproduction steps), `medium` for one that ' +
+            'risks fixing the wrong thing, and `low` for a minor clarification. Raise between 0 and ' +
+            '20 items, ordered by severity (high first). If the bug report is genuinely clear and ' +
+            'fixable, return an empty items array. Output JSON only.',
+    ].join('\n');
+}
+/**
+ * Build the user prompt for the clarity-rework step: the gathered bug report plus the
+ * human's answers (folded in) and dismissals (kept out). Works with an empty item list
+ * (the "no challenges" path simply restates the report in the standard structure). The
+ * {@link CLARITY_REWORK_SYSTEM_PROMPT} (in `@cat-factory/agents`) defines the output shape.
+ */
+export function buildClarityReworkPrompt(ctx, items) {
+    const lines = ['Current bug report:', '', renderBugReport(ctx), ''];
+    const answered = items.filter((i) => (i.status === 'answered' || i.status === 'resolved') && i.reply?.trim());
+    const dismissed = items.filter((i) => i.status === 'dismissed');
+    if (answered.length) {
+        lines.push('Clarifications the reporter provided (fold these in):', '');
+        for (const i of answered) {
+            lines.push(`- Q (${i.category}): ${i.title} — ${i.detail}`);
+            lines.push(`  A: ${i.reply?.trim() || '(no answer recorded)'}`);
+        }
+        lines.push('');
+    }
+    if (dismissed.length) {
+        lines.push('Items the reporter dismissed as out of scope (do NOT add these):', '');
+        for (const i of dismissed)
+            lines.push(`- ${i.title}`);
+        lines.push('');
+    }
+    if (!answered.length && !dismissed.length) {
+        lines.push('The reviewer raised no open questions — restate the bug report cleanly in the ' +
+            'standard structure without inventing new facts.', '');
+    }
+    if (ctx.reworkFeedback?.trim()) {
+        lines.push('', 'The reviewer was UNHAPPY with your previous reworked report and asked you to redo it ' +
+            'with this specific direction — follow it closely:', '', ctx.reworkFeedback.trim(), '');
+    }
+    lines.push('Rewrite the bug report as a single self-contained Markdown document in the standard ' +
+        'structure described in your instructions, folding in every answer above. Output the ' +
+        'revised bug report only.');
+    return lines.join('\n');
+}
+//# sourceMappingURL=clarity.logic.js.map

package/dist/modules/clarity/clarity.logic.js.map

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

package/dist/modules/estimation/estimate.logic.d.ts

@@ -0,0 +1,11 @@
+import type { TaskEstimate } from '@cat-factory/kernel';
+/**
+ * Coerce a task-estimator agent's output into a {@link TaskEstimate}. Tolerant:
+ * accepts a JSON object embedded in prose, clamps the three axes to [0,1], and
+ * defaults a missing rationale to empty. Returns null when no usable scores are
+ * present (caller then leaves the block estimate untouched).
+ */
+export declare function coerceTaskEstimate(output: string, model: string | null, now: number): TaskEstimate | null;
+/** A concise markdown summary of an estimate for the step's reviewable output. */
+export declare function summarizeEstimate(estimate: TaskEstimate): string;
+//# sourceMappingURL=estimate.logic.d.ts.map

package/dist/modules/estimation/estimate.logic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"estimate.logic.d.ts","sourceRoot":"","sources":["../../../src/modules/estimation/estimate.logic.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAcvD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,GAAG,IAAI,EACpB,GAAG,EAAE,MAAM,GACV,YAAY,GAAG,IAAI,CAUrB;AAED,kFAAkF;AAClF,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,YAAY,GAAG,MAAM,CAMhE"}

package/dist/modules/estimation/estimate.logic.js

@@ -0,0 +1,37 @@
+import { extractJson } from '../requirements/requirements.logic.js';
+// Pure helpers for the core `task-estimator` step: tolerant parsing of the
+// agent's JSON triage into a {@link TaskEstimate}, plus a readable summary the
+// board shows in place of the raw JSON. Kept pure (no I/O) for unit testing. The
+// tolerant JSON extraction is the shared `extractJson` helper (same package).
+/** Clamp a finite number into [0,1]; null for anything non-numeric. */
+function clamp01(value) {
+    if (typeof value !== 'number' || !Number.isFinite(value))
+        return null;
+    return Math.max(0, Math.min(1, value));
+}
+/**
+ * Coerce a task-estimator agent's output into a {@link TaskEstimate}. Tolerant:
+ * accepts a JSON object embedded in prose, clamps the three axes to [0,1], and
+ * defaults a missing rationale to empty. Returns null when no usable scores are
+ * present (caller then leaves the block estimate untouched).
+ */
+export function coerceTaskEstimate(output, model, now) {
+    const raw = extractJson(output);
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const obj = raw;
+    const complexity = clamp01(obj.complexity);
+    const risk = clamp01(obj.risk);
+    const impact = clamp01(obj.impact);
+    if (complexity === null || risk === null || impact === null)
+        return null;
+    const rationale = typeof obj.rationale === 'string' ? obj.rationale : '';
+    return { complexity, risk, impact, rationale, model, createdAt: now };
+}
+/** A concise markdown summary of an estimate for the step's reviewable output. */
+export function summarizeEstimate(estimate) {
+    const pct = (n) => `${Math.round(n * 100)}%`;
+    const header = `**Task estimate** — Complexity ${pct(estimate.complexity)} · Risk ${pct(estimate.risk)} · Impact ${pct(estimate.impact)}`;
+    return estimate.rationale ? `${header}\n\n${estimate.rationale}` : header;
+}
+//# sourceMappingURL=estimate.logic.js.map

package/dist/modules/estimation/estimate.logic.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"estimate.logic.js","sourceRoot":"","sources":["../../../src/modules/estimation/estimate.logic.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,uCAAuC,CAAA;AAEnE,2EAA2E;AAC3E,+EAA+E;AAC/E,iFAAiF;AACjF,8EAA8E;AAE9E,uEAAuE;AACvE,SAAS,OAAO,CAAC,KAAc;IAC7B,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAA;IACrE,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAA;AACxC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAChC,MAAc,EACd,KAAoB,EACpB,GAAW;IAEX,MAAM,GAAG,GAAG,WAAW,CAAC,MAAM,CAAC,CAAA;IAC/B,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAA;IAChD,MAAM,GAAG,GAAG,GAA8B,CAAA;IAC1C,MAAM,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,CAAA;IAC1C,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;IAC9B,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAA;IAClC,IAAI,UAAU,KAAK,IAAI,IAAI,IAAI,KAAK,IAAI,IAAI,MAAM,KAAK,IAAI;QAAE,OAAO,IAAI,CAAA;IACxE,MAAM,SAAS,GAAG,OAAO,GAAG,CAAC,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAA;IACxE,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,EAAE,CAAA;AACvE,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,iBAAiB,CAAC,QAAsB;IACtD,MAAM,GAAG,GAAG,CAAC,CAAS,EAAU,EAAE,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,GAAG,CAAC,GAAG,CAAA;IAC5D,MAAM,MAAM,GAAG,kCAAkC,GAAG,CAAC,QAAQ,CAAC,UAAU,CAAC,WAAW,GAAG,CACrF,QAAQ,CAAC,IAAI,CACd,aAAa,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAA;IACpC,OAAO,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,MAAM,OAAO,QAAQ,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,MAAM,CAAA;AAC3E,CAAC"}

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

@@ -0,0 +1,114 @@
+import type { AccountRepository, AgentRunContext, Block, BlockRepository, ClarityReviewRepository, DocumentRepository, ExecutionInstance, PipelineStep, RequirementReviewRepository, TaskRepository, WorkspaceRepository } from '@cat-factory/kernel';
+import type { EnvironmentProvisioningService } from '@cat-factory/integrations';
+/**
+ * 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 declare function buildRevisionContext(step: PipelineStep): {
+    revision?: {
+        previousProposal: string;
+        feedback: string;
+        comments?: {
+            quotedSource?: string;
+            body: string;
+        }[];
+    };
+};
+/** The collaborators the context builder reads from (all owned by the engine container). */
+export interface AgentContextBuilderDeps {
+    workspaceRepository: WorkspaceRepository;
+    blockRepository: BlockRepository;
+    accountRepository: AccountRepository;
+    documents?: DocumentRepository;
+    tasks?: TaskRepository;
+    requirementReviews?: RequirementReviewRepository;
+    clarityReviews?: ClarityReviewRepository;
+    environmentProvisioning?: EnvironmentProvisioningService;
+}
+/**
+ * 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 declare class AgentContextBuilder {
+    private readonly deps;
+    constructor(deps: AgentContextBuilderDeps);
+    /** Assemble the {@link AgentRunContext} for a step from the run + block state. */
+    buildContext(workspaceId: string, instance: ExecutionInstance, step: PipelineStep, isFinalStep: boolean, block: Block): Promise<AgentRunContext>;
+    /** The service-frame id for a block (walks up frame → module → task; cycle-guarded). */
+    resolveServiceFrameId(workspaceId: string, blockId: string): Promise<string | 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.
+     */
+    resolveServiceConfig(workspaceId: string, block: Block): Promise<AgentRunContext['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).
+     */
+    private resolveAccountDefaultProvider;
+    /**
+     * 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.
+     */
+    private resolveReworkedRequirements;
+    /**
+     * 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}.
+     */
+    private resolveClarifiedBrief;
+    /**
+     * 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).
+     */
+    private resolveFragments;
+    /**
+     * 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.
+     */
+    private resolveServiceFragmentIds;
+    /**
+     * 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.
+     */
+    private resolveContextDocs;
+    /**
+     * 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.
+     */
+    private resolveContextTasks;
+    /**
+     * 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.
+     */
+    private resolveEnvironment;
+}
+//# sourceMappingURL=AgentContextBuilder.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"AgentContextBuilder.d.ts","sourceRoot":"","sources":["../../../src/modules/execution/AgentContextBuilder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,iBAAiB,EACjB,eAAe,EACf,KAAK,EACL,eAAe,EACf,uBAAuB,EAEvB,kBAAkB,EAClB,iBAAiB,EACjB,YAAY,EACZ,2BAA2B,EAC3B,cAAc,EACd,mBAAmB,EACpB,MAAM,qBAAqB,CAAA;AAG5B,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,2BAA2B,CAAA;AAE/E;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,YAAY,GAAG;IACxD,QAAQ,CAAC,EAAE;QACT,gBAAgB,EAAE,MAAM,CAAA;QACxB,QAAQ,EAAE,MAAM,CAAA;QAChB,QAAQ,CAAC,EAAE;YAAE,YAAY,CAAC,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAE,EAAE,CAAA;KACrD,CAAA;CACF,CA6BA;AAED,4FAA4F;AAC5F,MAAM,WAAW,uBAAuB;IACtC,mBAAmB,EAAE,mBAAmB,CAAA;IACxC,eAAe,EAAE,eAAe,CAAA;IAChC,iBAAiB,EAAE,iBAAiB,CAAA;IACpC,SAAS,CAAC,EAAE,kBAAkB,CAAA;IAC9B,KAAK,CAAC,EAAE,cAAc,CAAA;IACtB,kBAAkB,CAAC,EAAE,2BAA2B,CAAA;IAChD,cAAc,CAAC,EAAE,uBAAuB,CAAA;IACxC,uBAAuB,CAAC,EAAE,8BAA8B,CAAA;CACzD;AAED;;;;;;;;GAQG;AACH,qBAAa,mBAAmB;IAClB,OAAO,CAAC,QAAQ,CAAC,IAAI;IAAjC,YAA6B,IAAI,EAAE,uBAAuB,EAAI;IAE9D,kFAAkF;IAC5E,YAAY,CAChB,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,iBAAiB,EAC3B,IAAI,EAAE,YAAY,EAClB,WAAW,EAAE,OAAO,EACpB,KAAK,EAAE,KAAK,GACX,OAAO,CAAC,eAAe,CAAC,CA2E1B;IAED,wFAAwF;IAClF,qBAAqB,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAQxF;IAED;;;;;;;;OAQG;IACG,oBAAoB,CACxB,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,KAAK,GACX,OAAO,CAAC,eAAe,CAAC,SAAS,CAAC,GAAG,SAAS,CAAC,CAoBjD;IAED;;;OAGG;YACW,6BAA6B;IAS3C;;;;;OAKG;YACW,2BAA2B;IAYzC;;;;OAIG;YACW,qBAAqB;IAYnC;;;;;;;;;OASG;YACW,gBAAgB;IA+B9B;;;;;OAKG;YACW,yBAAyB;IASvC;;;;;OAKG;YACW,kBAAkB;IAShC;;;;;OAKG;YACW,mBAAmB;IAiBjC;;;;;OAKG;YACW,kBAAkB;CAIjC"}