@navels/neal 0.1.0

package/dist/neal/agents/rounds.js

@@ -0,0 +1,706 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import { getAgentTurnRetryLimit, getAgentTurnStartupTimeoutMs, getApiRetryLimit, getInactivityTimeoutMs, } from '../config.js';
+import { runWithAgentTurnLiveness } from '../providers/liveness.js';
+import { normalizeExecutionShapeDeclaration } from '../plan-validation.js';
+import { getCoderAdapter, getStructuredAdvisorAdapter } from '../providers/registry.js';
+import { createProviderTelemetrySink } from '../providers/telemetry.js';
+import { isNealProviderError, NealProviderError } from '../providers/types.js';
+import { getReviewerDoctrineAccessMode, reviewerNeedsInlineContext, } from '../context/inline-review-context.js';
+import { AUTONOMY_BLOCKED, AUTONOMY_CHUNK_DONE, AUTONOMY_DONE, AUTONOMY_SCOPE_DONE, AUTONOMY_SPLIT_PLAN, buildBlockedRecoveryCoderPrompt, buildCoderResponsePrompt, buildCoderPlanResponsePrompt, buildFinalCompletionReviewerPrompt, buildFinalCompletionSummaryPrompt, buildLegacyScopePrompt, buildLegacyPlanningPrompt, buildPlanReviewerPrompt, buildPlanningPrompt, buildReviewerPrompt, buildBlockedAdjudicatorPrompt, buildScopePrompt, } from './prompts.js';
+import { buildCoderBlockedRecoveryDispositionSchema, buildCoderPlanSchema, buildCoderScopeSchema, buildCoderPlanResponseSchema, buildCoderResponseSchema, buildBlockedAdjudicatorSchema, buildFinalCompletionSummarySchema, buildFinalCompletionReviewerSchema, buildPlanReviewerSchema, buildReviewerSchema, parseExecuteScopeProgressPayload, parseFinalCompletionReviewerPayload, parseFinalCompletionSummaryPayload, stripExecuteScopeProgressPayload, validateCoderBlockedRecoveryDispositionPayload, validateCoderPlanPayload, validateCoderPlanResponsePayload, validateCoderResponsePayload, validateCoderScopePayload, validatePlanReviewerPayload, validateBlockedAdjudicatorVerdictPayload, validateReviewerPayload, } from './schemas.js';
+import { runCoderStructuredPrompt, translateCoderProviderError } from './structured-coder.js';
+export class ReviewerRoundError extends Error {
+    sessionHandle;
+    providerError;
+    kind;
+    retryable;
+    subtype;
+    constructor(providerError) {
+        super(providerError.message);
+        this.name = 'ReviewerRoundError';
+        this.sessionHandle = providerError.sessionHandle;
+        this.providerError = providerError;
+        this.kind = providerError.kind;
+        this.retryable = providerError.retryable;
+        this.subtype = providerError.kind;
+    }
+}
+function validationErrorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+export class FinalCompletionReviewerVerdictError extends Error {
+    originalValidationMessage;
+    sessionHandle;
+    subtype;
+    cause;
+    constructor(args) {
+        const message = validationErrorMessage(args.cause);
+        super(message, { cause: args.cause });
+        this.name = 'FinalCompletionReviewerVerdictError';
+        this.originalValidationMessage = message;
+        this.sessionHandle = args.sessionHandle;
+        this.subtype = 'final_completion_verdict_invalid';
+        this.cause = args.cause;
+    }
+}
+// Legacy marker-protocol compatibility for active legacy_marker_v1 primary
+// sessions. New primary planning/execution sessions use structured envelopes.
+function extractMarker(message) {
+    for (const rawLine of message.split(/\r?\n/)) {
+        const line = rawLine.trim();
+        if (line === AUTONOMY_SCOPE_DONE ||
+            line === AUTONOMY_CHUNK_DONE ||
+            line === AUTONOMY_DONE ||
+            line === AUTONOMY_BLOCKED ||
+            line === AUTONOMY_SPLIT_PLAN) {
+            return line;
+        }
+    }
+    return null;
+}
+function translateReviewerProviderError(error) {
+    if (isNealProviderError(error)) {
+        return new ReviewerRoundError(error);
+    }
+    return error;
+}
+async function safeReadText(path) {
+    try {
+        return await readFile(path, 'utf8');
+    }
+    catch {
+        return '';
+    }
+}
+function getCoderRuntimeOptions(cwd) {
+    return {
+        inactivityTimeoutMs: getInactivityTimeoutMs(cwd),
+    };
+}
+function getStructuredAdvisorRuntimeOptions(cwd) {
+    return {
+        inactivityTimeoutMs: getInactivityTimeoutMs(cwd),
+        apiRetryLimit: getApiRetryLimit(cwd),
+    };
+}
+function buildStructuredJsonProtocolSpec(args) {
+    return {
+        protocol: 'neal-json-block-v1',
+        schemaLabel: args.schemaLabel,
+        schema: args.schema,
+        validator: args.validator,
+        repairAttemptLimit: args.repairAttemptLimit ?? 2,
+    };
+}
+function createCoderProviderEventSink(args) {
+    return createProviderTelemetrySink({
+        logger: args.logger,
+        provider: args.coder.provider,
+        role: 'coder',
+        ...(args.label ? { label: args.label } : {}),
+        cwd: args.cwd,
+    });
+}
+function createStructuredAdvisorProviderEventSink(args) {
+    return createProviderTelemetrySink({
+        logger: args.logger,
+        provider: args.advisor.provider,
+        role: 'structured-advisor',
+        label: args.label,
+        cwd: args.cwd,
+    });
+}
+// Fail-fast guard for reviewer rounds whose prompts still contain
+// repository/tool-access instructions. A reviewer provider without read tool
+// access must never receive such a prompt: either the round supplies
+// Neal-inlined reviewer context (inlineContextSupplied), or the round must
+// reject the configuration with a clear error instead of silently sending
+// instructions the provider cannot follow. Every reviewer round label now
+// supports inline context, but a call site that fails to supply it for a
+// no-read reviewer must still fail fast here.
+//
+// The guard throws a ReviewerRoundError backed by a non-retryable
+// NealProviderError with sessionHandle: null so it flows through the same
+// orchestrator reviewer failure path as any other reviewer round failure
+// (persisted failed state, written artifacts, logged phase errors).
+function assertReviewerRoundSupportsNoReadReviewer(args) {
+    if (args.inlineContextSupplied || !reviewerNeedsInlineContext(args.reviewer)) {
+        return;
+    }
+    throw new ReviewerRoundError(new NealProviderError({
+        message: [
+            `Reviewer provider ${JSON.stringify(args.reviewer.provider)} has no repository read access,`,
+            `and the ${args.label} reviewer round did not receive Neal-inlined reviewer context,`,
+            'so its prompt would contain repository-access instructions the provider cannot follow.',
+            'Configure a read-capable reviewer provider (agent.reviewer.provider) for runs that reach',
+            `${args.label} rounds until this round supports inline reviewer context.`,
+        ].join(' '),
+        provider: args.reviewer.provider,
+        role: 'structured-advisor',
+        sessionHandle: null,
+        kind: 'provider_failed',
+        retryable: false,
+    }));
+}
+async function runReviewerStructuredRound(args) {
+    try {
+        const advisor = getStructuredAdvisorAdapter(args.reviewer);
+        const result = await runWithAgentTurnLiveness({
+            provider: args.reviewer.provider,
+            role: 'structured-advisor',
+            label: args.label,
+            startupTimeoutMs: Math.min(getAgentTurnStartupTimeoutMs(args.cwd), getInactivityTimeoutMs(args.cwd)),
+            // Structured-advisor turns retry locally: they are non-writing by policy
+            // and do not resume sessions at this call site.
+            retryLimit: getAgentTurnRetryLimit(args.cwd),
+            logger: args.logger,
+            baseSink: createStructuredAdvisorProviderEventSink({
+                advisor: args.reviewer,
+                cwd: args.cwd,
+                label: args.label,
+                logger: args.logger,
+            }),
+            run: (events, attempt) => advisor.runStructuredRound({
+                label: args.label,
+                cwd: args.cwd,
+                prompt: args.prompt,
+                schema: args.schema,
+                structuredJsonProtocol: args.structuredJsonProtocol,
+                // Liveness retry sits outside the adapter-owned apiRetryLimit; it
+                // does not replace provider API retry.
+                ...getStructuredAdvisorRuntimeOptions(args.cwd),
+                signal: attempt.signal,
+                events,
+            }),
+        });
+        return {
+            sessionHandle: result.sessionHandle,
+            structured: result.structured,
+        };
+    }
+    catch (error) {
+        throw translateReviewerProviderError(error);
+    }
+}
+export async function runReviewerRound(args) {
+    assertReviewerRoundSupportsNoReadReviewer({
+        reviewer: args.reviewer,
+        label: 'review',
+        inlineContextSupplied: Boolean(args.inlineContext),
+    });
+    const schema = buildReviewerSchema();
+    const { sessionHandle, structured } = await runReviewerStructuredRound({
+        reviewer: args.reviewer,
+        label: 'review',
+        cwd: args.cwd,
+        // The doctrine access mode comes from the reviewer provider's declared
+        // structured-advisor tool access, not from inline-context presence alone.
+        prompt: buildReviewerPrompt({ ...args, accessMode: getReviewerDoctrineAccessMode(args.reviewer) }),
+        schema,
+        structuredJsonProtocol: buildStructuredJsonProtocolSpec({
+            schemaLabel: 'reviewer_payload',
+            schema,
+            validator: validateReviewerPayload,
+        }),
+        logger: args.logger,
+    });
+    return {
+        sessionHandle,
+        summary: structured.summary,
+        findings: structured.findings.map((finding) => ({
+            round: args.round,
+            source: 'reviewer',
+            severity: finding.severity,
+            files: finding.files,
+            claim: finding.claim,
+            evidence: finding.evidence,
+            requiredAction: finding.requiredAction,
+            roundSummary: structured.summary,
+        })),
+        meaningfulProgress: {
+            action: structured.meaningfulProgressAction,
+            rationale: structured.meaningfulProgressRationale,
+        },
+    };
+}
+export async function runPlanReviewerRound(args) {
+    assertReviewerRoundSupportsNoReadReviewer({
+        reviewer: args.reviewer,
+        label: 'plan-review',
+        inlineContextSupplied: Boolean(args.inlineContext),
+    });
+    const schema = buildPlanReviewerSchema();
+    const { sessionHandle, structured } = await runReviewerStructuredRound({
+        reviewer: args.reviewer,
+        label: 'plan-review',
+        cwd: args.cwd,
+        // The doctrine access mode comes from the reviewer provider's declared
+        // structured-advisor tool access, not from inline-context presence alone.
+        prompt: buildPlanReviewerPrompt({ ...args, accessMode: getReviewerDoctrineAccessMode(args.reviewer) }),
+        schema,
+        structuredJsonProtocol: buildStructuredJsonProtocolSpec({
+            schemaLabel: 'plan_reviewer_payload',
+            schema,
+            validator: validatePlanReviewerPayload,
+        }),
+        logger: args.logger,
+    });
+    return {
+        sessionHandle,
+        summary: structured.summary,
+        executionShape: structured.executionShape,
+        findings: structured.findings.map((finding) => ({
+            round: args.round,
+            source: 'reviewer',
+            severity: finding.severity,
+            files: finding.files,
+            claim: finding.claim,
+            requiredAction: finding.requiredAction,
+            roundSummary: structured.summary,
+        })),
+    };
+}
+// Read-only, inline-only round for the review_stuck arbiter. It runs through the
+// same runReviewerStructuredRound plumbing the support / final-completion
+// reviewers use (read-only tools only, zero commits, zero file edits). Because
+// the arbiter judges entirely from Neal-inlined in-memory artifacts (plan, open
+// blocking findings, reviewer-round snapshots), it has a single no-read-safe
+// prompt variant and therefore requires a non-null inlineContext. The guard
+// fires for a no-read reviewer paired with a null context before any adapter
+// contact; the explicit null check below additionally covers a read-capable
+// reviewer that was handed a null context (the adjudicator always passes a
+// non-null context in production).
+export async function runBlockedAdjudicatorRound(args) {
+    assertReviewerRoundSupportsNoReadReviewer({
+        reviewer: args.reviewer,
+        label: 'review-stuck-arbiter',
+        inlineContextSupplied: Boolean(args.inlineContext),
+    });
+    if (!args.inlineContext) {
+        throw new ReviewerRoundError(new NealProviderError({
+            message: 'review-stuck-arbiter round requires Neal-inlined reviewer context',
+            provider: args.reviewer.provider,
+            role: 'structured-advisor',
+            sessionHandle: null,
+            kind: 'provider_failed',
+            retryable: false,
+        }));
+    }
+    const schema = buildBlockedAdjudicatorSchema();
+    const { sessionHandle, structured } = await runReviewerStructuredRound({
+        reviewer: args.reviewer,
+        label: 'review-stuck-arbiter',
+        cwd: args.cwd,
+        prompt: buildBlockedAdjudicatorPrompt({
+            blockedReason: args.blockedReason,
+            inlineContext: args.inlineContext,
+        }),
+        schema,
+        structuredJsonProtocol: buildStructuredJsonProtocolSpec({
+            schemaLabel: 'blocked_adjudicator_payload',
+            schema,
+            validator: validateBlockedAdjudicatorVerdictPayload,
+        }),
+        logger: args.logger,
+    });
+    return {
+        sessionHandle,
+        verdict: validateBlockedAdjudicatorVerdictPayload(structured),
+    };
+}
+export async function runCoderFinalCompletionSummaryRound(args) {
+    try {
+        const advisor = getStructuredAdvisorAdapter(args.coder);
+        const schema = buildFinalCompletionSummarySchema();
+        const result = await runWithAgentTurnLiveness({
+            provider: args.coder.provider,
+            role: 'structured-advisor',
+            label: 'final-completion',
+            startupTimeoutMs: Math.min(getAgentTurnStartupTimeoutMs(args.cwd), getInactivityTimeoutMs(args.cwd)),
+            // Structured-advisor turns retry locally: they are non-writing by policy
+            // and do not resume sessions at this call site.
+            retryLimit: getAgentTurnRetryLimit(args.cwd),
+            logger: args.logger,
+            baseSink: createStructuredAdvisorProviderEventSink({
+                advisor: args.coder,
+                cwd: args.cwd,
+                label: 'final-completion',
+                logger: args.logger,
+            }),
+            run: (events, attempt) => advisor.runStructuredRound({
+                label: 'final-completion',
+                cwd: args.cwd,
+                prompt: buildFinalCompletionSummaryPrompt(args),
+                schema,
+                structuredJsonProtocol: buildStructuredJsonProtocolSpec({
+                    schemaLabel: 'final_completion_summary_payload',
+                    schema,
+                    validator: parseFinalCompletionSummaryPayload,
+                }),
+                ...getStructuredAdvisorRuntimeOptions(args.cwd),
+                signal: attempt.signal,
+                events,
+            }),
+        });
+        return {
+            sessionHandle: result.sessionHandle,
+            summary: parseFinalCompletionSummaryPayload(result.structured),
+        };
+    }
+    catch (error) {
+        throw translateCoderProviderError(error);
+    }
+}
+export async function runReviewerFinalCompletionRound(args) {
+    assertReviewerRoundSupportsNoReadReviewer({
+        reviewer: args.reviewer,
+        label: 'final-completion',
+        inlineContextSupplied: Boolean(args.inlineContext),
+    });
+    const schema = buildFinalCompletionReviewerSchema();
+    const { sessionHandle, structured } = await runReviewerStructuredRound({
+        reviewer: args.reviewer,
+        label: 'final-completion',
+        cwd: args.cwd,
+        // The doctrine access mode comes from the reviewer provider's declared
+        // structured-advisor tool access, not from inline-context presence alone.
+        prompt: buildFinalCompletionReviewerPrompt({ ...args, accessMode: getReviewerDoctrineAccessMode(args.reviewer) }),
+        schema,
+        structuredJsonProtocol: buildStructuredJsonProtocolSpec({
+            schemaLabel: 'final_completion_reviewer_payload',
+            schema,
+            validator: parseFinalCompletionReviewerPayload,
+        }),
+        logger: args.logger,
+    });
+    let verdict;
+    try {
+        verdict = parseFinalCompletionReviewerPayload(structured);
+    }
+    catch (error) {
+        throw new FinalCompletionReviewerVerdictError({
+            sessionHandle,
+            cause: error,
+        });
+    }
+    return {
+        sessionHandle,
+        verdict,
+    };
+}
+export async function runCoderScopeRound(args) {
+    if (args.sessionHandle && args.coderSessionProtocol === null) {
+        throw new Error('Cannot resume coder scope session without coderSessionProtocol.');
+    }
+    if (!args.sessionHandle || args.coderSessionProtocol === 'structured_json_v1') {
+        const progressText = await safeReadText(args.progressMarkdownPath);
+        const schema = buildCoderScopeSchema();
+        const { sessionHandle, structured } = await runCoderStructuredPrompt({
+            coder: args.coder,
+            cwd: args.cwd,
+            prompt: buildScopePrompt(args.planDoc, progressText, { unattended: args.unattended }),
+            schema,
+            label: 'Coder scope round',
+            structuredJsonProtocol: buildStructuredJsonProtocolSpec({
+                schemaLabel: 'coder_scope_payload',
+                schema,
+                validator: validateCoderScopePayload,
+            }),
+            resumeHandle: args.sessionHandle,
+            onSessionStarted: args.onSessionStarted,
+            logger: args.logger,
+        });
+        const payload = validateCoderScopePayload(structured);
+        const marker = markerForCoderScopeAction(payload.action);
+        const responseWithoutProgressPayload = renderCoderScopeResponseWithoutProgressPayload(payload);
+        return {
+            sessionHandle,
+            finalResponse: renderCoderScopePayload(payload, marker),
+            responseWithoutProgressPayload,
+            marker,
+            progressJustification: payload.progress,
+            manualGate: payload.manualGate,
+        };
+    }
+    const coder = getCoderAdapter(args.coder);
+    const progressText = await safeReadText(args.progressMarkdownPath);
+    let finalResponse;
+    let sessionHandle;
+    try {
+        const result = await runWithAgentTurnLiveness({
+            provider: args.coder.provider,
+            role: 'coder',
+            startupTimeoutMs: Math.min(getAgentTurnStartupTimeoutMs(args.cwd), getInactivityTimeoutMs(args.cwd)),
+            // Resumed sessions never retry in the supervisor; the orchestrator's
+            // fresh-session retry owns recovery. This legacy
+            // branch always resumes, so the retry limit is always 0 here.
+            retryLimit: args.sessionHandle ? 0 : getAgentTurnRetryLimit(args.cwd),
+            logger: args.logger,
+            baseSink: createCoderProviderEventSink({
+                coder: args.coder,
+                cwd: args.cwd,
+                logger: args.logger,
+            }),
+            run: (events, attempt) => coder.runPrompt({
+                cwd: args.cwd,
+                prompt: buildLegacyScopePrompt(args.planDoc, progressText),
+                ...getCoderRuntimeOptions(args.cwd),
+                resumeHandle: args.sessionHandle,
+                // Guarded so an abandoned attempt's late session handle can never
+                // overwrite a newer attempt's handle.
+                onSessionStarted: attempt.guard(args.onSessionStarted),
+                signal: attempt.signal,
+                events,
+            }),
+        });
+        finalResponse = result.finalResponse;
+        sessionHandle = result.sessionHandle;
+    }
+    catch (error) {
+        throw translateCoderProviderError(error);
+    }
+    const progressJustification = parseExecuteScopeProgressPayload(finalResponse);
+    const responseWithoutProgressPayload = stripExecuteScopeProgressPayload(finalResponse);
+    const marker = extractMarker(responseWithoutProgressPayload);
+    if (marker === AUTONOMY_SPLIT_PLAN) {
+        const derivedPlan = responseWithoutProgressPayload
+            .split(/\r?\n/)
+            .filter((line) => line.trim() !== AUTONOMY_SPLIT_PLAN)
+            .join('\n')
+            .trim();
+        if (!derivedPlan) {
+            throw new Error('Coder scope round returned AUTONOMY_SPLIT_PLAN without a derived plan body.');
+        }
+    }
+    return {
+        sessionHandle,
+        finalResponse,
+        responseWithoutProgressPayload,
+        marker,
+        progressJustification,
+        manualGate: null,
+    };
+}
+function markerForCoderScopeAction(action) {
+    switch (action) {
+        case 'continue':
+            return AUTONOMY_CHUNK_DONE;
+        case 'scope_done':
+            return AUTONOMY_SCOPE_DONE;
+        case 'done':
+            return AUTONOMY_DONE;
+        case 'blocked':
+            return AUTONOMY_BLOCKED;
+        case 'split_plan':
+            return AUTONOMY_SPLIT_PLAN;
+        case 'manual_gate':
+            return null;
+    }
+}
+function renderCoderScopeResponseWithoutProgressPayload(payload) {
+    if (payload.action === 'split_plan') {
+        return payload.derivedPlan.trim();
+    }
+    if (payload.action === 'blocked') {
+        return (payload.blockedReason || payload.message).trim();
+    }
+    if (payload.action === 'manual_gate') {
+        return payload.message.trim();
+    }
+    return payload.message.trim();
+}
+function renderCoderScopePayload(payload, marker) {
+    return [renderCoderScopeResponseWithoutProgressPayload(payload), marker ?? '']
+        .map((part) => part.trim())
+        .filter((part) => part.length > 0)
+        .join('\n\n');
+}
+async function readPlanDocumentForPrompt(planDoc) {
+    try {
+        return await readFile(planDoc, 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+export async function runCoderPlanRound(args) {
+    if (args.sessionHandle && args.coderSessionProtocol === null) {
+        throw new Error('Cannot resume planner planning session without plannerSessionProtocol.');
+    }
+    if (!args.sessionHandle || args.coderSessionProtocol === 'structured_json_v1') {
+        const schema = buildCoderPlanSchema();
+        const planDocument = await readPlanDocumentForPrompt(args.planDoc);
+        const { sessionHandle, structured } = await runCoderStructuredPrompt({
+            coder: args.coder,
+            cwd: args.cwd,
+            prompt: buildPlanningPrompt(args.planDoc, planDocument, {
+                unattended: args.unattended,
+                authoredOneShot: args.authoredOneShot,
+            }),
+            schema,
+            label: 'Planner plan round',
+            structuredJsonProtocol: buildStructuredJsonProtocolSpec({
+                schemaLabel: 'coder_plan_payload',
+                schema,
+                validator: validateCoderPlanPayload,
+            }),
+            toolPolicy: { allowedWritePaths: [args.planDoc], allowRun: false },
+            resumeHandle: args.sessionHandle,
+            onSessionStarted: args.onSessionStarted,
+            telemetryLabel: 'planner',
+            logger: args.logger,
+        });
+        const payload = validateCoderPlanPayload(structured);
+        const marker = payload.action === 'blocked' ? AUTONOMY_BLOCKED : AUTONOMY_DONE;
+        const normalizedPayload = payload.action === 'ready_for_review'
+            ? {
+                ...payload,
+                planBody: normalizeExecutionShapeDeclaration(payload.planBody, payload.executionShape),
+            }
+            : payload;
+        if (normalizedPayload.action === 'ready_for_review') {
+            await writeFile(args.planDoc, normalizedPayload.planBody, 'utf8');
+        }
+        const finalResponse = renderCoderPlanPayload(normalizedPayload, marker);
+        return {
+            sessionHandle,
+            finalResponse,
+            marker,
+        };
+    }
+    const coder = getCoderAdapter(args.coder);
+    let finalResponse;
+    let sessionHandle;
+    const planDocument = await readPlanDocumentForPrompt(args.planDoc);
+    try {
+        const result = await runWithAgentTurnLiveness({
+            provider: args.coder.provider,
+            role: 'coder',
+            label: 'planner',
+            startupTimeoutMs: Math.min(getAgentTurnStartupTimeoutMs(args.cwd), getInactivityTimeoutMs(args.cwd)),
+            // Resumed sessions never retry in the supervisor; the orchestrator's
+            // fresh-session retry owns recovery. This legacy
+            // branch always resumes, so the retry limit is always 0 here.
+            retryLimit: args.sessionHandle ? 0 : getAgentTurnRetryLimit(args.cwd),
+            logger: args.logger,
+            baseSink: createCoderProviderEventSink({
+                coder: args.coder,
+                cwd: args.cwd,
+                label: 'planner',
+                logger: args.logger,
+            }),
+            run: (events, attempt) => coder.runPrompt({
+                cwd: args.cwd,
+                prompt: buildLegacyPlanningPrompt(args.planDoc, planDocument),
+                ...getCoderRuntimeOptions(args.cwd),
+                toolPolicy: { allowedWritePaths: [args.planDoc], allowRun: false },
+                resumeHandle: args.sessionHandle,
+                // Guarded so an abandoned attempt's late session handle can never
+                // overwrite a newer attempt's handle.
+                onSessionStarted: attempt.guard(args.onSessionStarted),
+                signal: attempt.signal,
+                events,
+            }),
+        });
+        finalResponse = result.finalResponse;
+        sessionHandle = result.sessionHandle;
+    }
+    catch (error) {
+        throw translateCoderProviderError(error);
+    }
+    const marker = extractMarker(finalResponse);
+    return {
+        sessionHandle,
+        finalResponse,
+        marker,
+    };
+}
+function renderCoderPlanPayload(payload, marker) {
+    const parts = [payload.message, payload.planBody, payload.blockedReason]
+        .map((part) => part.trim())
+        .filter((part) => part.length > 0);
+    return [...parts, marker].join('\n\n');
+}
+export async function runCoderResponseRound(args) {
+    const progressText = await safeReadText(args.progressMarkdownPath);
+    const schema = buildCoderResponseSchema();
+    const { sessionHandle, structured } = await runCoderStructuredPrompt({
+        coder: args.coder,
+        cwd: args.cwd,
+        prompt: buildCoderResponsePrompt({
+            planDoc: args.planDoc,
+            progressText,
+            verificationHint: args.verificationHint,
+            openFindings: args.openFindings,
+            mode: args.mode,
+        }),
+        schema,
+        label: 'Coder response round',
+        structuredJsonProtocol: buildStructuredJsonProtocolSpec({
+            schemaLabel: 'coder_response_payload',
+            schema,
+            validator: validateCoderResponsePayload,
+        }),
+        resumeHandle: args.sessionHandle,
+        logger: args.logger,
+    });
+    return {
+        sessionHandle,
+        payload: validateCoderResponsePayload(structured),
+    };
+}
+export async function runBlockedRecoveryCoderRound(args) {
+    const progressText = await safeReadText(args.progressMarkdownPath);
+    const schema = buildCoderBlockedRecoveryDispositionSchema();
+    const { sessionHandle, structured } = await runCoderStructuredPrompt({
+        coder: args.coder,
+        cwd: args.cwd,
+        prompt: buildBlockedRecoveryCoderPrompt({
+            planDoc: args.planDoc,
+            progressText,
+            recoveryMarkdownPath: args.recoveryMarkdownPath,
+            blockedReason: args.blockedReason,
+            operatorGuidance: args.operatorGuidance,
+            maxTurns: args.maxTurns,
+            turnsTaken: args.turnsTaken,
+            terminalOnly: args.terminalOnly,
+            allowReplacement: args.allowReplacement,
+        }),
+        schema,
+        label: 'Coder blocked-recovery round',
+        structuredJsonProtocol: buildStructuredJsonProtocolSpec({
+            schemaLabel: 'coder_blocked_recovery_disposition_payload',
+            schema,
+            validator: validateCoderBlockedRecoveryDispositionPayload,
+        }),
+        resumeHandle: args.sessionHandle,
+        logger: args.logger,
+    });
+    return {
+        sessionHandle,
+        payload: validateCoderBlockedRecoveryDispositionPayload(structured),
+    };
+}
+export async function runCoderPlanResponseRound(args) {
+    const schema = buildCoderPlanResponseSchema();
+    const { sessionHandle, structured } = await runCoderStructuredPrompt({
+        coder: args.coder,
+        cwd: args.cwd,
+        prompt: buildCoderPlanResponsePrompt(args),
+        schema,
+        label: 'Planner plan-response round',
+        structuredJsonProtocol: buildStructuredJsonProtocolSpec({
+            schemaLabel: 'coder_plan_response_payload',
+            schema,
+            validator: validateCoderPlanResponsePayload,
+        }),
+        toolPolicy: { allowedWritePaths: [args.planDoc], allowRun: false },
+        resumeHandle: args.sessionHandle,
+        telemetryLabel: 'planner',
+        logger: args.logger,
+    });
+    return {
+        sessionHandle,
+        payload: validateCoderPlanResponsePayload(structured),
+    };
+}