@sema-agent/core/dist/core/runner/run-turn-boundary.js

Stateless, task-oriented AI agent core

import { compactionKindOf } from "../task-notification.js";
import { mintSystemReminder } from "../reminder-mint.js";
import { eventDefaultOn } from "../../prompt-assembly/event-registry.js";
import { DEFAULT_COMPACTION_INSTRUCTIONS, isCompactionManualCancel, maybeCompact, mintCompactedEvent, nextTrimForceBackoff, recordCompactionAndCheckRapidRefill } from "../auto-compaction.js";
import { emitTrace } from "../trace.js";
import { redactThenCut } from "../../agents/subagent-steps.js";
import { ATTACHMENT_BYTE_CAP, CHANGED_FILES_MAX, TOTAL_TOKENS_REMINDER_DEFAULT_MODE, attachmentEnvelopeTags, clipToBytes, collectDateChange, collectDueAttachments, collectInstructionsChange, commitAgentListing, commitInstructionsChange, commitSkillsListing, isIntactSource, rebaseCadenceWindows, renderAgentListingFrame, renderMcpDroppedTools, renderMcpInstructionsDelta, selectMcpDroppedBatch, renderSkillsListingFrame, renderToolsDelta } from "./turn-attachments.js";
import { announceListingTruncation } from "../skill-listing-budget.js";
import { buildWorkingFileAttachments, centerAdoptionOption, contextInstructionFilesOption, emitInputTruncated, forkContextOption, legCompactionSettings, legContextOverlayOption } from "./compaction-call-options.js";
import { hookSeatExpiredError, runHookSeat } from "../hooks.js";
import { sanitizeUntrustedText, SHELLED_BODY_ENVELOPE_TAGS } from "../untrusted-text.js";
import { droppedToolDigest, withAnnounceDigests } from "./announce-once-ledger.js";
import { formatDiagnosticsBlock } from "../lsp-diagnostics.js";
import { workflowSizeGuidelineChangeNotice } from "../../orchestration/workflow-size-guideline.js";
import { awaitChargeWithSlowDisclosure, discloseUnevaluableWindow, ENV_DUE_GOVERNANCE_READ_BUDGET_MS, GOVERNANCE_READ_STALLED, LIMIT_APPROACH_DEFAULT_THRESHOLDS, limitApproachFrames, platformLimitTerminal, raceUntilDeadline } from "./clock-and-limits.js";
import { appendBoundaryFrames, compactionRestateOptions } from "./compaction-restate.js";
import { COMPACTION_FREED_EPSILON, COMPACTION_REGROWTH_FACTOR, MAX_CONSECUTIVE_COMPACTION_FAILURES } from "./compaction-knobs.js";
import { compactionHookOptions, recordCompactionReuse, seamCCompactionOptions } from "./compaction-seams.js";
import { contextUsageSections } from "../../prompt-assembly/section-usage.js";
import { asThrownError, thrownText } from "../thrown-value.js";
const BATCH_CONTEXT_MIN_KEEP_BYTES = 160;
const BATCH_TRUNCATION_MARKER = "\n…[truncated]";
export function createTurnBoundary(input) {
    const { prepared, stats, rs, deps } = input;
    const { spec, queue, manualCompactRef, todoToolMounted, taskToolsMounted, walltimeMonotonicDeadline, timeout, ident, postToolBatchHook, batchArgs, compactionBrain, withinTaskCompaction, compactionBreaker, windowSafetyOptions, rapidRefill, drainManualCompact, runnerHooks, runner } = deps;
    let finalVerifySeenAtLastBoundary = 0;
    let legContinues = true;
    const boundaryPass = async (event) => {
        let boundarySteered = false;
        const noNextRequest = () => prepared.stopRequestedRef.current || deps.loopLatch.userHalted;
        const walltimeHit = walltimeMonotonicDeadline !== undefined && performance.now() >= walltimeMonotonicDeadline;
        const preemptHit = spec.preemptSignal?.aborted === true;
        if (preemptHit && !prepared.suspendForResource && !rs.counters.preemptIgnoredReported) {
            rs.counters.preemptIgnoredReported = true;
            emitTrace(rs.telemetry.tracer, () => ({ kind: "preempt.ignored", version: 1, taskId: rs.telemetry.taskId, ts: Date.now() }));
        }
        let platformCause;
        let platformRetryAfterMs;
        const preemptWillSuspend = preemptHit && prepared.suspendForResource !== undefined;
        if (!preemptWillSuspend && prepared.pausedRef.current === undefined && !prepared.abortController.signal.aborted) {
            const ledgerReadDeadline = prepared.envLifetimeSuspendAt !== undefined ? prepared.envLifetimeSuspendAt + ENV_DUE_GOVERNANCE_READ_BUDGET_MS : undefined;
            if (prepared.usageGovernance !== undefined) {
                const governance = prepared.usageGovernance;
                try {
                    const at = Date.now();
                    await awaitChargeWithSlowDisclosure(governance.commit(stats.tokens, rs.telemetry.unpricedSpend ? undefined : stats.costMicroUsd, at), () => runnerHooks.onError?.(new Error("the usage ledger CHARGE has not settled after 10s — still waiting (a charge is never abandoned: walking away would double-charge on the end-of-task flush). A wedged ledger store wedges this boundary, now visibly."), { phase: "config", sessionId: prepared.sessionId }));
                    const windowRead = governance.check(at);
                    let answer;
                    if (ledgerReadDeadline !== undefined) {
                        answer = await raceUntilDeadline(windowRead, ledgerReadDeadline);
                        if (answer === GOVERNANCE_READ_STALLED) {
                            void windowRead.catch((lateErr) => {
                                try {
                                    runnerHooks.onError?.(asThrownError(lateErr), { phase: "config", sessionId: prepared.sessionId });
                                }
                                catch {
                                }
                            });
                            try {
                                runnerHooks.onError?.(new Error("the usage ledger did not answer before the execution environment's suspend deadline — stopping for the environment, the cause this run can still prove. The window state for this boundary is UNKNOWN and was not enforced."), { phase: "config", sessionId: prepared.sessionId });
                            }
                            catch {
                            }
                        }
                    }
                    else {
                        answer = await windowRead;
                    }
                    if (answer !== GOVERNANCE_READ_STALLED) {
                        platformRetryAfterMs = answer;
                        if (platformRetryAfterMs !== undefined)
                            platformCause = "usage_window";
                    }
                }
                catch (govErr) {
                    rs.limits.platformTerminal = asThrownError(govErr);
                    void prepared.harness.abort();
                    prepared.abortController.abort();
                    legContinues = false;
                    return undefined;
                }
            }
            if (platformCause === undefined && prepared.envLifetimeSuspendAt !== undefined && Date.now() >= prepared.envLifetimeSuspendAt) {
                platformCause = "env_lifetime";
            }
        }
        if (platformCause !== undefined) {
            const platformSpend = { costMicroUsd: stats.costMicroUsd, tokens: stats.tokens, turns: stats.turns, walltimeMs: Math.round(performance.now() - rs.telemetry.taskStartMonotonic) };
            const committed = prepared.suspendForPlatformLimit !== undefined &&
                (await prepared.suspendForPlatformLimit(platformCause, platformSpend, platformRetryAfterMs !== undefined ? { resumeAfterMs: platformRetryAfterMs } : undefined));
            if (committed) {
                rs.limits.turnsExceeded = false;
                rs.limits.budgetHit = undefined;
                legContinues = false;
                return undefined;
            }
            const terminal = platformLimitTerminal(platformCause, platformRetryAfterMs);
            rs.limits.platformTerminal = terminal;
            try {
                runnerHooks.onError?.(terminal, { phase: "config", sessionId: prepared.sessionId });
            }
            catch {
            }
            void prepared.harness.abort();
            prepared.abortController.abort();
            legContinues = false;
            return undefined;
        }
        if (prepared.suspendForResource &&
            (rs.limits.turnsExceeded || rs.limits.budgetHit !== undefined || walltimeHit || preemptHit) &&
            prepared.pausedRef.current === undefined) {
            const reason = preemptHit
                ? "preempt"
                : rs.limits.budgetHit !== undefined
                    ? rs.limits.budgetAxis === "tokens"
                        ? "budget_tokens"
                        : "budget_cost"
                    : rs.limits.turnsExceeded
                        ? "turns"
                        : "walltime";
            const sliceSpend = { costMicroUsd: stats.costMicroUsd, tokens: stats.tokens, turns: stats.turns, walltimeMs: Math.round(performance.now() - rs.telemetry.taskStartMonotonic) };
            if (await prepared.suspendForResource(reason, sliceSpend)) {
                rs.limits.turnsExceeded = false;
                rs.limits.budgetHit = undefined;
            }
            else {
                void prepared.harness.abort();
                prepared.abortController.abort();
            }
            legContinues = false;
            return undefined;
        }
        if (walltimeMonotonicDeadline !== undefined &&
            prepared.suspendForResource === undefined &&
            performance.now() >= walltimeMonotonicDeadline) {
            if (!timeout.fired) {
                timeout.fired = true;
                timeout.clear();
                timeout.latenessMs = Math.max(timeout.latenessMs ?? 0, performance.now() - walltimeMonotonicDeadline);
                rs.counters.walltimeSyncBackstopFired = true;
                void prepared.harness.abort();
                prepared.abortController.abort();
            }
            legContinues = false;
            return undefined;
        }
        const approachCfg = spec.limits?.approachNotice;
        if (approachCfg !== false &&
            rs.counters.approachNoticesSent < LIMIT_APPROACH_DEFAULT_THRESHOLDS.length &&
            prepared.suspendForResource === undefined &&
            rs.turn.lastTurnHadToolCalls &&
            prepared.batchHaltRef.current === undefined &&
            !boundarySteered &&
            !prepared.abortController.signal.aborted) {
            const thresholds = approachCfg?.at ?? LIMIT_APPROACH_DEFAULT_THRESHOLDS;
            const ratios = [];
            if (rs.budget.maxTokensWindow !== undefined && rs.budget.maxTokensWindow > 0) {
                ratios.push({ axis: "token budget", ratio: stats.tokens / rs.budget.maxTokensWindow });
            }
            if (rs.budget.maxCostMicroUsd !== undefined && rs.budget.maxCostMicroUsd > 0) {
                ratios.push({ axis: "cost budget", ratio: stats.costMicroUsd / rs.budget.maxCostMicroUsd });
            }
            const declaredMaxTurns = spec.limits?.maxTurns;
            if (declaredMaxTurns !== undefined && declaredMaxTurns > 0) {
                ratios.push({ axis: "turn budget", ratio: (stats.turns + 1) / declaredMaxTurns });
            }
            if (walltimeMonotonicDeadline !== undefined) {
                const walltimeWindowMs = walltimeMonotonicDeadline - rs.telemetry.taskStartMonotonic;
                if (walltimeWindowMs > 0) {
                    ratios.push({ axis: "walltime budget", ratio: (performance.now() - rs.telemetry.taskStartMonotonic) / walltimeWindowMs });
                }
            }
            let tightest;
            for (const r of ratios)
                if (tightest === undefined || r.ratio > tightest.ratio)
                    tightest = r;
            const index = rs.counters.approachNoticesSent;
            if (tightest !== undefined && tightest.ratio >= thresholds[index]) {
                rs.counters.approachNoticesSent += 1;
                const percent = Math.min(100, Math.round(tightest.ratio * 100));
                const body = limitApproachFrames(index === 0 ? 0 : 1, tightest.axis, percent, prepared.reminderMark);
                void prepared.harness.steer(body, { engineMinted: true }).catch(() => undefined);
                queue.push({ type: "steering_injected", source: "limit_approach", preview: body.slice(0, 220), ...ident() });
                boundarySteered = true;
            }
        }
        if (prepared.reviewRequestRef.pending !== undefined) {
            const { reason } = prepared.reviewRequestRef.pending;
            prepared.reviewRequestRef.pending = undefined;
            const honorable = prepared.suspendForReview !== undefined &&
                !prepared.abortController.signal.aborted &&
                prepared.pausedRef.current === undefined;
            if (honorable && prepared.suspendForReview) {
                await prepared.suspendForReview(reason);
                legContinues = !prepared.abortController.signal.aborted && prepared.pausedRef.current === undefined;
                return undefined;
            }
            emitTrace(rs.telemetry.tracer, () => ({ kind: "review.dropped", version: 1, taskId: rs.telemetry.taskId, ts: Date.now() }));
        }
        if (!noNextRequest() && !prepared.abortController.signal.aborted)
            await appendBoundaryFrames(prepared, rs.turn.lastTurnHadToolCalls);
        if (prepared.lspDiagnostics &&
            !prepared.lspDiagnostics.registry.isEmpty() &&
            !prepared.abortController.signal.aborted &&
            prepared.batchHaltRef.current === undefined) {
            const files = prepared.lspDiagnostics.registry.drain(prepared.lspDiagnostics.runIdent);
            if (files.length > 0) {
                queue.push({ type: "diagnostics", files, isNew: true, ...ident() });
                const block = mintSystemReminder(formatDiagnosticsBlock(files), prepared.reminderMark);
                void prepared.harness.steer(block, { provenance: "engine-note" }).catch(() => undefined);
                boundarySteered = true;
            }
        }
        let boundaryAttachmentBytes = 0;
        let attachmentsPayload;
        const receiptCommits = [];
        if ((rs.attach.dateState !== undefined ||
            rs.attach.instrState !== undefined ||
            rs.attach.sizeGuidelineState !== undefined ||
            rs.attach.attachState !== undefined) &&
            !boundarySteered &&
            prepared.batchHaltRef.current === undefined &&
            !noNextRequest() &&
            rs.counters.finalVerifyInjections === 0 &&
            !prepared.abortController.signal.aborted) {
            const due = [];
            if (rs.attach.attachState !== undefined) {
                const attachState = rs.attach.attachState;
                const changedFilesOn = Boolean(rs.attach.attachmentsCfg?.changedFiles);
                let changed;
                if (changedFilesOn && prepared.detectExternalChanges !== undefined) {
                    const maxFiles = typeof rs.attach.attachmentsCfg?.changedFiles === "object"
                        ? (rs.attach.attachmentsCfg.changedFiles.maxFiles ?? CHANGED_FILES_MAX)
                        : CHANGED_FILES_MAX;
                    const SCAN_CEILING_MS = 2_000;
                    const scan = await Promise.race([
                        prepared.detectExternalChanges(maxFiles),
                        new Promise((resolve) => {
                            setTimeout(() => resolve({ changed: [], evicted: [] }), SCAN_CEILING_MS);
                        }),
                    ]);
                    for (const p of scan.evicted)
                        rs.attach.attachState.surfacedMtime.delete(p);
                    changed = scan.changed;
                }
                const backgroundTasksOn = (rs.attach.attachmentsCfg?.backgroundTasks ?? eventDefaultOn("background_tasks")) === true;
                const bgTasks = backgroundTasksOn && rs.attach.attachState.postCompactPending ? prepared.listBackgroundTasks() : undefined;
                const toolsDeltaOn = rs.attach.attachmentsCfg?.toolsDelta === true;
                let announcedOnceDirty = false;
                const tdRef = toolsDeltaOn ? prepared.toolsDeltaRef : undefined;
                const pendingTools = tdRef !== undefined && tdRef.pending.length > 0 ? [...tdRef.pending] : undefined;
                const pendingRemovedTools = tdRef !== undefined && tdRef.pendingRemoved.length > 0 ? [...tdRef.pendingRemoved] : undefined;
                const pendingReaddedTools = tdRef !== undefined && tdRef.pendingReadded.length > 0 ? [...tdRef.pendingReadded] : undefined;
                const pendingFailedMcp = tdRef !== undefined && tdRef.pendingFailed.length > 0 ? tdRef.pendingFailed.map((f) => ({ ...f })) : undefined;
                const mcpToolsDelta = pendingRemovedTools !== undefined || pendingReaddedTools !== undefined || pendingFailedMcp !== undefined
                    ? {
                        ...(pendingRemovedTools !== undefined ? { removed: pendingRemovedTools } : {}),
                        ...(pendingReaddedTools !== undefined ? { readded: pendingReaddedTools } : {}),
                        ...(pendingFailedMcp !== undefined ? { failedServers: pendingFailedMcp } : {}),
                    }
                    : undefined;
                const mcpInstructionsOn = rs.attach.attachmentsCfg?.mcpInstructions === true;
                const mcpDelta = prepared.mcp.instructionsDelta;
                const mcpAdds = mcpInstructionsOn && mcpDelta.pendingAdds.length > 0 ? [...mcpDelta.pendingAdds] : undefined;
                const mcpRemovals = mcpInstructionsOn && mcpDelta.pendingRemovals.length > 0 ? [...mcpDelta.pendingRemovals] : undefined;
                const mcpDropped = mcpInstructionsOn && prepared.mcp.droppedTools.length > 0 ? selectMcpDroppedBatch(prepared.mcp.droppedTools) : undefined;
                const budgetUsdOn = rs.attach.attachmentsCfg?.budgetUsd === true && rs.budget.maxCostMicroUsd !== undefined && rs.turn.lastTurnHadToolCalls;
                const totalTokensDeclared = rs.attach.attachmentsCfg?.totalTokensReminder;
                const totalTokensMode = rs.attach.attachmentsCfg?.totalTokensReminderMode ?? TOTAL_TOKENS_REMINDER_DEFAULT_MODE;
                const totalTokensArmedByDefault = totalTokensDeclared === undefined &&
                    eventDefaultOn("total_tokens_reminder") &&
                    totalTokensMode !== "fixed" &&
                    totalTokensMode !== "infinite";
                const totalTokensOn = (totalTokensDeclared === true || totalTokensArmedByDefault) && rs.turn.lastTurnHadToolCalls;
                const toolSearchReminderOn = rs.attach.attachmentsCfg?.toolSearchReminder === true && prepared.deferredToolNames !== undefined;
                const undiscoveredTools = toolSearchReminderOn
                    ? [...prepared.deferredToolNames].filter((n) => !prepared.activeTools.has(n)).sort()
                    : undefined;
                const receiptPending = (source) => prepared.frameReceipts.pending.some((r) => r.source === source);
                const agentListingDue = rs.attach.agentListingOn && prepared.agentListing !== undefined && !receiptPending("agent_listing");
                const skillsListingDue = rs.attach.skillsListingOn && prepared.skillsListing !== undefined && !receiptPending("skills_listing");
                const listingBudget = prepared.skillsListing?.budget ?? prepared.agentListing?.budget;
                due.push(...collectDueAttachments(rs.attach.attachState, {
                    turn: stats.turns,
                    cadenceTurn: rs.counters.cadenceTurns,
                    todoMounted: todoToolMounted,
                    taskListMounted: taskToolsMounted,
                    config: {
                        todoReminder: rs.attach.attachmentsCfg?.todoReminder === true,
                        ...(rs.attach.attachmentsCfg?.todoReminderMode !== undefined ? { todoReminderMode: rs.attach.attachmentsCfg.todoReminderMode } : {}),
                        toolSearchReminder: toolSearchReminderOn,
                        changedFiles: changedFilesOn,
                        budgetUsd: budgetUsdOn,
                        totalTokensReminder: totalTokensOn,
                        ...(rs.attach.attachmentsCfg?.totalTokensReminderMode !== undefined
                            ? { totalTokensReminderMode: rs.attach.attachmentsCfg.totalTokensReminderMode }
                            : {}),
                        backgroundTasks: backgroundTasksOn,
                        toolsDelta: toolsDeltaOn,
                        agentListing: rs.attach.agentListingOn,
                        skillsListing: rs.attach.skillsListingOn,
                        mcpInstructions: mcpInstructionsOn,
                    },
                    ...(prepared.outputStyleFrame !== undefined && rs.turn.lastTurnHadToolCalls ? { outputStyle: prepared.outputStyleFrame } : {}),
                    ...(undiscoveredTools !== undefined && undiscoveredTools.length > 0
                        ? { undiscoveredTools, deferDirectCall: prepared.deferDirectCall }
                        : {}),
                    ...(changed !== undefined ? { changedFiles: changed } : {}),
                    ...(budgetUsdOn && rs.budget.maxCostMicroUsd !== undefined
                        ? { budgetUsd: { used: stats.costMicroUsd / 1e6, total: rs.budget.maxCostMicroUsd / 1e6 } }
                        : {}),
                    ...(totalTokensOn && rs.budget.maxTokensWindow !== undefined
                        ? { totalTokens: { used: stats.tokens, total: rs.budget.maxTokensWindow } }
                        : {}),
                    ...(bgTasks !== undefined ? { backgroundTasks: bgTasks } : {}),
                    ...(pendingTools !== undefined ? { newTools: pendingTools } : {}),
                    ...(prepared.toolMaterializeStatic ? { newToolsStaticFace: true } : {}),
                    ...(prepared.toolMaterializeStatic && pendingTools !== undefined
                        ? { newToolsSwappedUnderStatic: pendingTools.filter((n) => prepared.staticFaceFor?.(n) !== true) }
                        : {}),
                    ...(prepared.toolMaterializeStatic && pendingReaddedTools !== undefined
                        ? { readdedToolsSwappedUnderStatic: pendingReaddedTools.filter((n) => prepared.staticFaceFor?.(n) !== true) }
                        : {}),
                    ...(mcpToolsDelta !== undefined ? { mcpToolsDelta } : {}),
                    ...(agentListingDue
                        ? {
                            agentListing: prepared.agentListing.entries,
                            agentToolName: prepared.agentListing.toolName,
                            ...(prepared.agentListing.models !== undefined ? { agentModels: prepared.agentListing.models } : {}),
                        }
                        : {}),
                    ...(skillsListingDue ? { skillsListing: prepared.skillsListing.entries } : {}),
                    ...(listingBudget !== undefined ? { listingBudget } : {}),
                    ...(mcpAdds !== undefined || mcpRemovals !== undefined
                        ? { mcpInstructions: { added: mcpAdds ?? [], removed: mcpRemovals ?? [] } }
                        : {}),
                    ...(mcpDropped !== undefined ? { mcpDroppedTools: mcpDropped } : {}),
                }));
                if (pendingTools !== undefined || mcpToolsDelta !== undefined) {
                    const exact = renderToolsDelta({
                        ...(pendingTools !== undefined ? { added: pendingTools } : {}),
                        ...(prepared.toolMaterializeStatic ? { staticFace: true } : {}),
                        ...(prepared.toolMaterializeStatic && pendingTools !== undefined
                            ? { swappedUnderStatic: pendingTools.filter((n) => prepared.staticFaceFor?.(n) !== true) }
                            : {}),
                        ...(prepared.toolMaterializeStatic && pendingReaddedTools !== undefined
                            ? { readdedSwappedUnderStatic: pendingReaddedTools.filter((n) => prepared.staticFaceFor?.(n) !== true) }
                            : {}),
                        ...(mcpToolsDelta ?? {}),
                    });
                    if (exact !== undefined && due.some((a) => a.source === "tools_delta" && a.body === exact)) {
                        const ref = prepared.toolsDeltaRef;
                        if (pendingTools !== undefined)
                            ref.pending.splice(0, pendingTools.length);
                        if (pendingRemovedTools !== undefined)
                            ref.pendingRemoved.splice(0, pendingRemovedTools.length);
                        if (pendingReaddedTools !== undefined)
                            ref.pendingReadded.splice(0, pendingReaddedTools.length);
                        if (pendingFailedMcp !== undefined) {
                            ref.pendingFailed.splice(0, pendingFailedMcp.length);
                            if (!noNextRequest()) {
                                prepared.announcedListingsRef.mcpFailed = [...(prepared.announcedListingsRef.mcpFailed ?? []), ...pendingFailedMcp];
                                announcedOnceDirty = true;
                            }
                        }
                    }
                }
                if ((mcpAdds !== undefined || mcpRemovals !== undefined) &&
                    due.some((a) => a.source === "mcp_instructions" && a.body === renderMcpInstructionsDelta(mcpAdds ?? [], mcpRemovals ?? []))) {
                    if (mcpAdds !== undefined)
                        mcpDelta.pendingAdds.splice(0, mcpAdds.length);
                    if (mcpRemovals !== undefined)
                        mcpDelta.pendingRemovals.splice(0, mcpRemovals.length);
                }
                if (mcpDropped !== undefined &&
                    due.some((a) => a.source === "mcp_dropped_tools" && a.body === renderMcpDroppedTools(mcpDropped))) {
                    prepared.mcp.droppedTools.splice(0, mcpDropped.length);
                    if (!noNextRequest()) {
                        prepared.announcedListingsRef.advisories = withAnnounceDigests(prepared.announcedListingsRef.advisories, mcpDropped.map(droppedToolDigest));
                        announcedOnceDirty = true;
                    }
                }
                if (agentListingDue && due.some((a) => a.source === "agent_listing")) {
                    const listing = prepared.agentListing;
                    const frame = renderAgentListingFrame(attachState, listing.entries, listing.toolName, listing.models, listing.budget);
                    receiptCommits.push({
                        source: "agent_listing",
                        commit: () => {
                            commitAgentListing(attachState, listing.entries, listing.models);
                            prepared.announcedListingsRef.agents = listing.entries.map((e) => e.name);
                            if (listing.models !== undefined)
                                prepared.announcedListingsRef.models = [...listing.models];
                            prepared.frameReceipts.listingSnapshotOwed = true;
                            announceListingTruncation(deps.runner.deps.onNotice, { listing: "agents", total: frame.listed, nameOnly: frame.nameOnly, dropped: frame.dropped, budget: listing.budget, sessionId: prepared.sessionId });
                        },
                    });
                }
                if (skillsListingDue && due.some((a) => a.source === "skills_listing")) {
                    const listing = prepared.skillsListing;
                    const frame = renderSkillsListingFrame(attachState, listing.entries, listing.budget);
                    receiptCommits.push({
                        source: "skills_listing",
                        commit: () => {
                            commitSkillsListing(attachState, listing.entries);
                            prepared.announcedListingsRef.skills = listing.entries.map((e) => e.name);
                            prepared.frameReceipts.listingSnapshotOwed = true;
                            announceListingTruncation(deps.runner.deps.onNotice, { listing: "skills", total: frame.listed, nameOnly: frame.nameOnly, dropped: frame.dropped, budget: listing.budget, sessionId: prepared.sessionId });
                        },
                    });
                }
                if (announcedOnceDirty)
                    prepared.frameReceipts.listingSnapshotOwed = true;
            }
            if (rs.attach.dateState !== undefined && rs.turn.lastTurnHadToolCalls && !prepared.frameReceipts.pending.some((r) => r.source === "date_change")) {
                const today = prepared.dateChange.today();
                const cand = collectDateChange(rs.attach.dateState, today);
                if (cand !== undefined) {
                    due.unshift(cand);
                    receiptCommits.push({ source: "date_change", commit: () => void (rs.attach.dateState.announcedDate = today) });
                }
            }
            if (rs.attach.sizeGuidelineState !== undefined && rs.turn.lastTurnHadToolCalls) {
                const guideline = rs.attach.sizeGuidelineState.current();
                if (guideline !== rs.attach.sizeGuidelineState.announcedGuideline) {
                    due.splice(due.length > 0 && due[0].source === "date_change" ? 1 : 0, 0, {
                        source: "workflow_size_guideline_change",
                        body: workflowSizeGuidelineChangeNotice(guideline),
                    });
                    rs.attach.sizeGuidelineState.announcedGuideline = guideline;
                }
            }
            if (rs.attach.instrState !== undefined && rs.attach.instrProbe !== undefined && rs.turn.lastTurnHadToolCalls) {
                let probed = null;
                try {
                    const PROBE_CEILING_MS = 2_000;
                    probed = await Promise.race([
                        rs.attach.instrProbe(prepared.instructionSources),
                        new Promise((resolve) => {
                            setTimeout(() => resolve(null), PROBE_CEILING_MS);
                        }),
                    ]);
                }
                catch {
                    probed = null;
                }
                const cand = collectInstructionsChange(rs.attach.instrState, probed);
                if (cand !== undefined) {
                    due.splice(due.length > 0 && due[0].source === "date_change" ? 1 : 0, 0, cand.attachment);
                    commitInstructionsChange(rs.attach.instrState, cand.announced);
                }
            }
            if (due.length > 0) {
                attachmentsPayload = due.map((a) => mintSystemReminder(sanitizeUntrustedText(a.body, attachmentEnvelopeTags(a.source)), prepared.reminderMark)).join("\n");
                for (const a of due)
                    if (!isIntactSource(a.source))
                        boundaryAttachmentBytes += Buffer.byteLength(a.body, "utf8");
                rs.attach.attachmentsInjected += due.length;
                for (const a of due) {
                    queue.push({ type: "steering_injected", source: a.source, preview: redactThenCut(a.body, 220), ...ident() });
                }
            }
        }
        let batchContextBlock;
        const finalVerifyInjectedThisTurn = rs.counters.finalVerifyInjections !== finalVerifySeenAtLastBoundary;
        finalVerifySeenAtLastBoundary = rs.counters.finalVerifyInjections;
        if (postToolBatchHook !== undefined && rs.turn.toolBatch.length > 0) {
            const batch = rs.turn.toolBatch;
            rs.turn.toolBatch = [];
            batchArgs?.clear();
            const injectedThisTurn = finalVerifyInjectedThisTurn ? "final_verification" : undefined;
            if (!boundarySteered && !prepared.abortController.signal.aborted) {
                try {
                    const batchSeat = await runHookSeat("postToolBatch", { timeoutMs: prepared.hookTimeoutMs, signal: prepared.abortController.signal }, (sig) => postToolBatchHook(batch, injectedThisTurn !== undefined ? { injectedThisTurn } : undefined, { identity: prepared.hookIdentity, permissionMode: prepared.permissionMode.observed, signal: sig }));
                    if (batchSeat.expired) {
                        runnerHooks.onError?.(hookSeatExpiredError("postToolBatch", prepared.hookTimeoutMs, batchSeat.cause, "the boundary observation was abandoned and its additionalContext dropped; the turn boundary itself is unchanged"), { phase: "hook", sessionId: prepared.sessionId });
                    }
                    const r = batchSeat.expired ? undefined : batchSeat.value;
                    if (r?.additionalContext && injectedThisTurn === undefined) {
                        const body = sanitizeUntrustedText(r.additionalContext, SHELLED_BODY_ENVELOPE_TAGS);
                        const budget = ATTACHMENT_BYTE_CAP - boundaryAttachmentBytes;
                        if (budget >= BATCH_CONTEXT_MIN_KEEP_BYTES) {
                            const clipped = clipToBytes(body, budget) === body
                                ? body
                                : `${clipToBytes(body, budget - Buffer.byteLength(BATCH_TRUNCATION_MARKER, "utf8"))}${BATCH_TRUNCATION_MARKER}`;
                            batchContextBlock = mintSystemReminder(clipped, prepared.reminderMark);
                        }
                    }
                }
                catch (err) {
                    try {
                        runnerHooks.onError?.(asThrownError(err), { phase: "hook", sessionId: prepared.sessionId });
                    }
                    catch {
                    }
                }
            }
        }
        if ((attachmentsPayload !== undefined || batchContextBlock !== undefined) && prepared.batchHaltRef.current === undefined) {
            const payload = attachmentsPayload !== undefined && batchContextBlock !== undefined ? `${attachmentsPayload}\n${batchContextBlock}` : (attachmentsPayload ?? batchContextBlock);
            for (const c of receiptCommits)
                prepared.frameReceipts.pending.push({ source: c.source, text: payload, commit: c.commit });
            void prepared.harness.steer(payload, { engineMinted: true }).catch(() => {
                prepared.frameReceipts.pending = prepared.frameReceipts.pending.filter((r) => r.text !== payload);
            });
        }
        const forceManual = manualCompactRef.requested;
        if ((!withinTaskCompaction() && !forceManual) ||
            prepared.abortController.signal.aborted ||
            prepared.pausedRef.current !== undefined) {
            if (forceManual) {
                emitTrace(rs.telemetry.tracer, () => ({ kind: "compaction.mooted", version: 1, taskId: rs.telemetry.taskId, reason: "task_ending", ts: Date.now() }));
                queue.push({ type: "compaction_outcome", outcome: "mooted", trigger: "manual", reason: "task_ending", ...ident() });
                drainManualCompact("mooted");
            }
            legContinues = !prepared.abortController.signal.aborted && prepared.pausedRef.current === undefined;
            return undefined;
        }
        if (compactionBreaker.failures >= MAX_CONSECUTIVE_COMPACTION_FAILURES) {
            if (forceManual) {
                emitTrace(rs.telemetry.tracer, () => ({
                    kind: "compaction.failed",
                    version: 1,
                    taskId: rs.telemetry.taskId,
                    trigger: "manual",
                    reason: "compaction circuit breaker open (3 consecutive failures this task) — manual request drained without an attempt",
                    ts: Date.now(),
                }));
                queue.push({ type: "compaction_outcome", outcome: "failed", trigger: "manual", reason: "compaction circuit breaker open (3 consecutive failures this task) — manual request drained without an attempt", ...ident() });
                drainManualCompact("failed");
            }
            return undefined;
        }
        const claimedManual = forceManual
            ? (() => {
                const waiters = manualCompactRef.waiters.splice(0);
                let instructions;
                for (let i = waiters.length - 1; i >= 0; i--) {
                    if (waiters[i].instructions !== undefined) {
                        instructions = waiters[i].instructions;
                        break;
                    }
                }
                return { instructions, waiters };
            })()
            : undefined;
        if (forceManual) {
            manualCompactRef.requested = false;
        }
        const resolveClaimedWaiters = (outcome) => {
            if (claimedManual !== undefined)
                for (const w of claimedManual.waiters.splice(0))
                    w.resolve(outcome);
        };
        const claimedCancelSignals = claimedManual?.waiters.flatMap((w) => (w.signal !== undefined ? [w.signal] : [])) ?? [];
        const manualCancelSignal = claimedCancelSignals.length === 0
            ? undefined
            : claimedCancelSignals.length === 1
                ? claimedCancelSignals[0]
                : AbortSignal.any(claimedCancelSignals);
        const compactionPassSignal = claimedCancelSignals.length > 0
            ? AbortSignal.any([prepared.abortController.signal, ...claimedCancelSignals])
            : prepared.abortController.signal;
        const trimPressureArmed = prepared.trimPressureRef.droppedMessages;
        if (trimPressureArmed)
            prepared.trimPressureRef.droppedMessages = false;
        const trimPressure = trimPressureArmed && !rs.counters.trimForceBackoff;
        const passTrigger = trimPressure ? "forced" : forceManual ? "manual" : "auto";
        let manualOutcome = "failed";
        const manualInstructions = claimedManual?.instructions;
        try {
            const comp = await maybeCompact({
                session: prepared.session,
                epochDeclaredSections: prepared.epochDeclaredSections,
                ...centerAdoptionOption(prepared),
                model: event.model,
                ...legContextOverlayOption(prepared, runner),
                compactionModel: prepared.compModel,
                ...forkContextOption(prepared, false),
                brain: compactionBrain,
                getApiKeyAndHeaders: spec.getApiKeyAndHeaders,
                thinking: prepared.thinking,
                settings: legCompactionSettings(spec, legContextOverlayOption(prepared, runner).contextOverlay),
                customInstructions: manualInstructions ?? spec.compaction?.instructions ?? DEFAULT_COMPACTION_INSTRUCTIONS,
                signal: compactionPassSignal,
                ...(manualCancelSignal !== undefined ? { manualCancelSignal } : {}),
                minTokens: forceManual ? 0 : rs.counters.compactionFloor,
                force: forceManual,
                onInputTruncated: emitInputTruncated(rs.telemetry.tracer, rs.telemetry.taskId),
                forceUnderThreshold: trimPressure,
                overheadTokens: prepared.promptOverheadTokens,
                ...(prepared.activeTools.size > 0 ? { activeTools: [...prepared.activeTools] } : {}),
                workingFileAttachments: buildWorkingFileAttachments(spec, prepared),
                ...contextInstructionFilesOption(prepared),
                ...(prepared.onCompactionApplied ? { onApplied: prepared.onCompactionApplied } : {}),
                ...seamCCompactionOptions(runner, prepared),
                ...compactionRestateOptions(prepared),
                ...windowSafetyOptions(event.model),
                ...compactionHookOptions(runner, spec, prepared.sessionId, passTrigger, prepared.hookIdentity, { timeoutMs: prepared.hookTimeoutMs, signal: prepared.abortController.signal }),
            });
            if (comp.blocked) {
                emitTrace(rs.telemetry.tracer, () => ({
                    kind: "compaction.blocked",
                    version: 1,
                    taskId: rs.telemetry.taskId,
                    trigger: forceManual ? "manual" : "auto",
                    ts: Date.now(),
                }));
            }
            else {
                compactionBreaker.failures = 0;
            }
            rs.counters.trimForceBackoff = nextTrimForceBackoff(rs.counters.trimForceBackoff, comp, trimPressure);
            if (comp.contextUsage) {
                const sections = contextUsageSections(prepared.promptManifest.sections);
                queue.push({ type: "context_usage", ...comp.contextUsage, ...(sections !== undefined ? { sections } : {}), ...ident() });
            }
            if (comp.unevaluableWindow) {
                discloseUnevaluableWindow(comp.unevaluableWindow, prepared, rs.telemetry.tracer, rs.telemetry.taskId, runnerHooks.onError);
            }
            if (comp.suppressedByFloor) {
                const s = comp.suppressedByFloor;
                emitTrace(rs.telemetry.tracer, () => ({
                    kind: "compaction.suppressed",
                    version: 1,
                    taskId: rs.telemetry.taskId,
                    estTokens: s.estTokens,
                    floor: s.floor,
                    ts: Date.now(),
                }));
            }
            manualOutcome = comp.compacted ? "compacted" : comp.blocked ? "blocked" : comp.disabled ? "disabled" : "noop";
            if (forceManual && !comp.compacted && !comp.blocked) {
                if (comp.disabled) {
                    emitTrace(rs.telemetry.tracer, () => ({ kind: "compaction.disabled", version: 1, taskId: rs.telemetry.taskId, ts: Date.now() }));
                }
                else {
                    emitTrace(rs.telemetry.tracer, () => ({ kind: "compaction.noop", version: 1, taskId: rs.telemetry.taskId, ts: Date.now() }));
                }
            }
            if (!comp.compacted) {
                const outcome = comp.blocked
                    ? "blocked"
                    : comp.disabled
                        ? (forceManual || trimPressure ? "disabled" : undefined)
                        : comp.suppressedByFloor
                            ? "suppressed"
                            : comp.noop || forceManual
                                ? "noop"
                                : undefined;
                if (outcome !== undefined) {
                    queue.push({ type: "compaction_outcome", outcome, trigger: passTrigger, ...ident() });
                }
            }
            recordCompactionReuse(runner, prepared, comp);
            if (comp.compacted) {
                queue.push(mintCompactedEvent(comp, passTrigger, ident()));
                rs.counters.compactionPasses += 1;
                rs.counters.compactionKind = compactionKindOf(passTrigger);
                if (!forceManual && recordCompactionAndCheckRapidRefill(rapidRefill, stats.turns)) {
                    compactionBreaker.failures = MAX_CONSECUTIVE_COMPACTION_FAILURES;
                    queue.push({ type: "compaction_outcome", outcome: "disabled", trigger: passTrigger, reason: "rapid_refill: compaction disabled for the rest of this task", ...ident() });
                    runnerHooks.onError?.(new Error("compaction.rapid_refill: the context refilled within <3 turns of compaction 3 times in a row — compaction disabled for the rest of this task (thrash spiral; the transcript is dominated by incompressible content)"), { phase: "compaction", sessionId: prepared.sessionId });
                }
                if (comp.phaseDurations !== undefined && comp.durationMs !== undefined) {
                    const pd = comp.phaseDurations;
                    const pdDur = comp.durationMs;
                    emitTrace(rs.telemetry.tracer, () => ({ kind: "compaction.phase_timings", version: 1, taskId: rs.telemetry.taskId, ...pd, durationMs: pdDur, ts: Date.now() }));
                }
                prepared.cacheBreakDetector?.notifyCompaction();
                if (rs.attach.attachState !== undefined) {
                    rs.attach.attachState.postCompactPending = true;
                    rebaseCadenceWindows(rs.attach.attachState, rs.counters.cadenceTurns);
                }
                if ((comp.freedTokens ?? 0) >= COMPACTION_FREED_EPSILON && comp.postTriggerTokens !== undefined) {
                    rs.counters.compactionFloor = Math.ceil(comp.postTriggerTokens * COMPACTION_REGROWTH_FACTOR);
                }
            }
        }
        catch (err) {
            const manualCancelAbort = !prepared.abortController.signal.aborted && isCompactionManualCancel(err);
            if (manualCancelAbort) {
                emitTrace(rs.telemetry.tracer, () => ({ kind: "compaction.mooted", version: 1, taskId: rs.telemetry.taskId, reason: "cancelled", ts: Date.now() }));
                queue.push({ type: "compaction_outcome", outcome: "mooted", trigger: passTrigger, reason: "cancelled", ...ident() });
                manualOutcome = "mooted";
            }
            else if (!prepared.abortController.signal.aborted) {
                compactionBreaker.failures += 1;
                runnerHooks.onError?.(err, { phase: "compaction", sessionId: prepared.sessionId });
                const msg = thrownText(err);
                const failReason = msg.length > 512 ? `${msg.slice(0, 512)}…` : msg;
                emitTrace(rs.telemetry.tracer, () => ({
                    kind: "compaction.failed",
                    version: 1,
                    taskId: rs.telemetry.taskId,
                    trigger: passTrigger,
                    reason: failReason,
                    ts: Date.now(),
                }));
                queue.push({ type: "compaction_outcome", outcome: "failed", trigger: passTrigger, reason: failReason, ...ident() });
                manualOutcome = "failed";
            }
            else {
                manualOutcome = "mooted";
            }
        }
        if (forceManual)
            resolveClaimedWaiters(manualOutcome);
        return undefined;
    };
    const onTurnBoundary = async (event) => {
        legContinues = true;
        try {
            return await boundaryPass(event);
        }
        finally {
            const round = prepared.peerBoundaryRound;
            if (round !== undefined) {
                try {
                    await round({ continues: legContinues });
                }
                catch {
                }
            }
        }
    };
    return onTurnBoundary;
}