@myagentroam/agent 0.9.62 → 0.9.64

package/dist/runtime/context-gc.js

@@ -0,0 +1,909 @@
+import { ContextGcCheckpointCache, contextGcBaseFromRecords, contextGcLogicalPathKey, contextGcMinimumUsageGrowth, contextGcRecordSourceHash, contextGcTargetKey, normalizeContextGcReplacements } from '../session/context-gc-checkpoint.js';
+import { contextGcApplyPatchInputReplacement, contextGcExecInputReplacement, contextGcExecOutputReplacement, contextGcPatchResultFromCompletedPayload, contextGcStaleReadReplacement, normalizeContextGcExecResult } from '../session/context-gc-replacements.js';
+import { contextGcSubagentNeedsRetainedPriorFinal, contextGcSubagentOutputReplacement, contextGcSubagentPriorFinalIsRetained, contextGcSubagentSnapshotIsSuperseded, contextGcSubagentSnapshotTurnId, normalizeContextGcSubagentSnapshot } from '../session/context-gc-subagent.js';
+import { parseReadContextOutput } from '../tools/read-context.js';
+import { CONTEXT_GC_TOKEN_ESTIMATOR, contextGcCacheImpact, contextGcMessageTokens, contextGcPrefixTokens, contextGcReclaimedTokens } from './context-gc-tokens.js';
+import { applyContextGcReplacementsToMessages, providerToolCallId, providerToolName } from './context-projection.js';
+export const CONTEXT_GC_POLICY = {
+    version: 1,
+    immediatePaybackRollouts: 3,
+    maximumPaybackRollouts: 20,
+    contextGrowthSampleWindow: 16,
+    minimumContextGrowthSamples: 6,
+    minimumObservationRollouts: 1,
+    stageAProtectionRollouts: 2,
+    largeExecProtectionRollouts: 6,
+    normalInputCostRate: 1,
+    cacheReadCostRate: 0.1,
+    cacheWriteCostRate: 1.25,
+    outputCostRate: 1,
+    minimumGrossReductionRate: 0.2,
+    minimumCacheInvestmentRoi: 0.1
+};
+const CONTEXT_GC_START_RATIO = 0.5;
+const HIGH_WATER_GROSS_REDUCTION_START_RATIO = 0.7;
+const HIGH_WATER_MINIMUM_GROSS_REDUCTION_RATE = 0.1;
+const MINIMUM_CONTEXT_WINDOW_REDUCTION_RATIO = 0.05;
+const COMPACT_CREDIT_ACTIVATION_RATIO = 0.8;
+const COMPACT_THRESHOLD_RATIO = 0.9;
+const IMMINENT_COMPACT_CREDIT_DISCOUNT = 0.8;
+const LARGE_EXEC_TOKENS = 4_096;
+export function evaluateContextGcEconomics(input) {
+    const reclaimedTokens = Math.max(0, input.reclaimedTokens);
+    const cacheReadTokens = Math.max(0, input.cacheReadTokens);
+    const preservedCachedPrefixTokens = clamp(input.preservedCachedPrefixTokens, 0, cacheReadTokens);
+    const invalidatedCachedSuffixTokens = cacheReadTokens - preservedCachedPrefixTokens;
+    const reclaimedCachedTokens = clamp(input.reclaimedCachedTokens, 0, invalidatedCachedSuffixTokens);
+    const invalidatedRetainedCachedTokens = Math.max(0, invalidatedCachedSuffixTokens - reclaimedCachedTokens);
+    const cacheRebuildPenaltyCostUnits = invalidatedRetainedCachedTokens *
+        (CONTEXT_GC_POLICY.cacheWriteCostRate - CONTEXT_GC_POLICY.cacheReadCostRate);
+    const reclaimedUncachedTokens = Math.max(0, reclaimedTokens - reclaimedCachedTokens);
+    const firstRolloutSavingsCostUnits = reclaimedCachedTokens * CONTEXT_GC_POLICY.cacheReadCostRate +
+        reclaimedUncachedTokens * CONTEXT_GC_POLICY.normalInputCostRate;
+    const steadyRolloutSavingsCostUnits = reclaimedTokens * CONTEXT_GC_POLICY.cacheReadCostRate;
+    const netAt = (rollouts) => input.compactDeferralCreditCostUnits -
+        cacheRebuildPenaltyCostUnits +
+        (rollouts <= 0
+            ? 0
+            : firstRolloutSavingsCostUnits + Math.max(0, rollouts - 1) * steadyRolloutSavingsCostUnits);
+    const maximumSearch = Math.max(CONTEXT_GC_POLICY.maximumPaybackRollouts + 1, 10_000);
+    const requiredPositiveNetRollouts = firstMatchingRollout(maximumSearch, (rollouts) => netAt(rollouts) > 0);
+    const requiredTargetRoiRollouts = cacheRebuildPenaltyCostUnits === 0
+        ? requiredPositiveNetRollouts
+        : firstMatchingRollout(maximumSearch, (rollouts) => netAt(rollouts) > 0 &&
+            netAt(rollouts) / cacheRebuildPenaltyCostUnits >=
+                CONTEXT_GC_POLICY.minimumCacheInvestmentRoi);
+    const targetRollouts = Number.isFinite(requiredTargetRoiRollouts)
+        ? requiredTargetRoiRollouts
+        : CONTEXT_GC_POLICY.maximumPaybackRollouts;
+    const expectedNetSavedCostUnits = netAt(targetRollouts);
+    const cacheInvestmentRoi = cacheRebuildPenaltyCostUnits === 0
+        ? 0
+        : expectedNetSavedCostUnits / cacheRebuildPenaltyCostUnits;
+    const grossReductionRate = reclaimedTokens / Math.max(1, Math.max(0, input.contextUsageTokens));
+    const minimumGrossReductionRate = Math.max(0, input.minimumGrossReductionRate ?? CONTEXT_GC_POLICY.minimumGrossReductionRate);
+    const minimumReclaimedTokens = Math.max(0, input.minimumReclaimedTokens ??
+        Math.ceil(Math.max(0, input.contextUsageTokens) * minimumGrossReductionRate));
+    const immediate = requiredTargetRoiRollouts <= CONTEXT_GC_POLICY.immediatePaybackRollouts;
+    const passes = reclaimedTokens > 0 &&
+        reclaimedTokens >= minimumReclaimedTokens &&
+        Number.isFinite(requiredTargetRoiRollouts) &&
+        (immediate ||
+            (requiredTargetRoiRollouts <= CONTEXT_GC_POLICY.maximumPaybackRollouts &&
+                input.contextGrowthSampleCount >= CONTEXT_GC_POLICY.minimumContextGrowthSamples &&
+                requiredTargetRoiRollouts <= input.projectedRolloutsUntilCompactAfterGc));
+    return {
+        cacheRebuildPenaltyCostUnits,
+        requiredPositiveNetRollouts,
+        requiredTargetRoiRollouts,
+        expectedNetSavedCostUnits,
+        cacheInvestmentRoi,
+        grossReductionRate,
+        passes
+    };
+}
+export function contextGcMinimumGrossReductionRate(usageRatio) {
+    if (!Number.isFinite(usageRatio) || usageRatio <= HIGH_WATER_GROSS_REDUCTION_START_RATIO)
+        return CONTEXT_GC_POLICY.minimumGrossReductionRate;
+    if (usageRatio >= COMPACT_THRESHOLD_RATIO)
+        return HIGH_WATER_MINIMUM_GROSS_REDUCTION_RATE;
+    const progress = (usageRatio - HIGH_WATER_GROSS_REDUCTION_START_RATIO) /
+        (COMPACT_THRESHOLD_RATIO - HIGH_WATER_GROSS_REDUCTION_START_RATIO);
+    return (CONTEXT_GC_POLICY.minimumGrossReductionRate -
+        progress *
+            (CONTEXT_GC_POLICY.minimumGrossReductionRate - HIGH_WATER_MINIMUM_GROSS_REDUCTION_RATE));
+}
+export function contextGcMinimumReclaimedTokens(contextUsageTokens, contextWindowTokens) {
+    if (!Number.isFinite(contextUsageTokens) ||
+        contextUsageTokens < 0 ||
+        !Number.isFinite(contextWindowTokens) ||
+        contextWindowTokens <= 0)
+        return 0;
+    const usageRatio = contextUsageTokens / contextWindowTokens;
+    const required = Math.max(contextUsageTokens * contextGcMinimumGrossReductionRate(usageRatio), contextWindowTokens * MINIMUM_CONTEXT_WINDOW_REDUCTION_RATIO);
+    return Math.ceil(required - 1e-9);
+}
+export function contextGcEligibleUsage(usage, contextWindowTokens) {
+    const contextUsageTokens = modelContextUsage(usage);
+    if (contextUsageTokens === undefined ||
+        !Number.isSafeInteger(contextWindowTokens) ||
+        contextWindowTokens <= 0)
+        return undefined;
+    const usageRatio = contextUsageTokens / contextWindowTokens;
+    if (usageRatio < CONTEXT_GC_START_RATIO || usageRatio >= COMPACT_THRESHOLD_RATIO)
+        return undefined;
+    return contextUsageTokens;
+}
+export function planContextGc(input) {
+    return inspectContextGc(input).plan;
+}
+export function inspectContextGc(input) {
+    const contextUsageTokens = contextGcEligibleUsage(input.usage, input.contextWindowTokens);
+    if (contextUsageTokens === undefined)
+        return {};
+    input = {
+        ...input,
+        tokenCache: new Map(),
+        checkpointCache: input.checkpointCache ?? new ContextGcCheckpointCache()
+    };
+    const usageRatio = contextUsageTokens / input.contextWindowTokens;
+    const usageRecord = latestUsageRecord(input.records, input.modelId);
+    if (!usageRecord)
+        return {};
+    const normalRolloutOrdinal = countSuccessfulNormalRollouts(input.records, input.modelId, input.contextWindowTokens);
+    const previous = input.checkpointCache.read(input.records, undefined, input.workspace);
+    if (previous) {
+        const minimumUsageGrowth = contextGcMinimumUsageGrowth(input.contextWindowTokens);
+        if (normalRolloutOrdinal - previous.payload.trigger.normalRolloutOrdinal < 2 ||
+            contextUsageTokens - previous.payload.trigger.contextInputTokens < minimumUsageGrowth)
+            return {};
+    }
+    if (input.messages.length !== input.messageSources.length)
+        return {};
+    const groups = buildToolGroups(input.records, input.messages, input.messageSources);
+    const existing = previous?.payload.replacements ?? [];
+    const existingTargets = new Set(existing.flatMap((replacement) => [
+        contextGcTargetKey(replacement.target),
+        ...(replacement.kind === 'TOOL_CALL_INPUT'
+            ? replacement.providerAliasTargets.map(contextGcTargetKey)
+            : [])
+    ]));
+    const stageA = collectStageACandidates(input, groups, existing, existingTargets);
+    const subagent = collectSubagentCandidates(input, groups, existingTargets);
+    const deterministicCandidates = [...stageA.eligible, ...subagent.eligible];
+    const deterministicProtectedTokens = stageA.protectedTokens + subagent.protectedTokens;
+    const stageAPlan = evaluateCandidateSet(input, existing, deterministicCandidates, {
+        stage: 'STAGE_A',
+        contextUsageTokens,
+        usageRatio,
+        usageRecord,
+        normalRolloutOrdinal,
+        protectedCandidateTokens: deterministicProtectedTokens
+    });
+    if (stageAPlan?.economics.passes) {
+        const plan = finalizePlan(input, stageAPlan);
+        return plan ? { plan } : {};
+    }
+    const exec = collectExecCandidates(input, groups, existingTargets);
+    const combined = evaluateCandidateSet(input, existing, [...deterministicCandidates, ...exec.eligible], {
+        stage: 'STAGE_A_AND_EXEC',
+        contextUsageTokens,
+        usageRatio,
+        usageRecord,
+        normalRolloutOrdinal,
+        protectedCandidateTokens: deterministicProtectedTokens + exec.protectedTokens
+    });
+    if (combined?.economics.passes) {
+        const plan = finalizePlan(input, combined);
+        return plan ? { plan } : {};
+    }
+    const retryAfterRollouts = Math.min(stageA.retryAfterRollouts, subagent.retryAfterRollouts, exec.retryAfterRollouts);
+    return deterministicProtectedTokens + exec.protectedTokens >=
+        contextGcMinimumReclaimedTokens(contextUsageTokens, input.contextWindowTokens) &&
+        Number.isFinite(retryAfterRollouts)
+        ? { retryAfterRollouts }
+        : {};
+}
+function finalizePlan(input, evaluated) {
+    if (!evaluated)
+        return undefined;
+    const base = contextGcBaseFromRecords(input.records, evaluated.boundarySequence);
+    if (!base)
+        return undefined;
+    const replacements = normalizeContextGcReplacements(evaluated.replacements);
+    if (!replacements || replacements.length === 0)
+        return undefined;
+    const metrics = {
+        stage: evaluated.stage,
+        tokenEstimator: CONTEXT_GC_TOKEN_ESTIMATOR,
+        beforeTokens: evaluated.beforeTokens,
+        afterTokens: evaluated.afterTokens,
+        reclaimedTokens: evaluated.reclaimedTokens,
+        grossReductionRate: evaluated.economics.grossReductionRate,
+        effectiveMinimumGrossReductionRate: evaluated.minimumGrossReductionRate,
+        minimumRequiredReclaimedTokens: evaluated.minimumReclaimedTokens,
+        cacheRebuildPenaltyCostUnits: evaluated.economics.cacheRebuildPenaltyCostUnits,
+        compactDeferralCreditCostUnits: evaluated.compactDeferralCreditCostUnits,
+        imminentCompactAvoidanceCreditCostUnits: evaluated.imminentCompactAvoidanceCreditCostUnits,
+        appliedCompactCreditCostUnits: evaluated.appliedCompactCreditCostUnits,
+        requiredPositiveNetRollouts: evaluated.economics.requiredPositiveNetRollouts,
+        requiredTargetRoiRollouts: evaluated.economics.requiredTargetRoiRollouts,
+        projectedRolloutsUntilCompactAfterGc: evaluated.projectedRolloutsUntilCompactAfterGc,
+        projectedTokensBeforeGc: evaluated.projectedTokensBeforeGc,
+        projectedTokensAfterGc: evaluated.projectedTokensAfterGc,
+        contextGrowthSampleCount: evaluated.contextGrowthSamples.length,
+        contextGrowthP75Tokens: evaluated.contextGrowthP75Tokens,
+        expectedNetSavedCostUnits: evaluated.economics.expectedNetSavedCostUnits,
+        cacheInvestmentRoi: evaluated.economics.cacheInvestmentRoi,
+        minimumObservedRollouts: evaluated.minimumObservedRollouts,
+        protectedCandidateTokens: evaluated.protectedCandidateTokens,
+        eligibleCandidateCount: evaluated.eligibleCandidateCount,
+        eligibleTargetCount: replacements.reduce((count, replacement) => count +
+            1 +
+            (replacement.kind === 'TOOL_CALL_INPUT' ? replacement.providerAliasTargets.length : 0), 0),
+        cachePenaltyKnown: input.usage.cacheReadTokens !== undefined
+    };
+    const draft = {
+        version: 1,
+        base,
+        boundarySequence: evaluated.boundarySequence,
+        sourceProjectionHash: '',
+        replacements,
+        trigger: {
+            usageSequence: evaluated.usageRecord.sequence,
+            contextInputTokens: evaluated.contextUsageTokens,
+            contextWindowTokens: input.contextWindowTokens,
+            normalRolloutOrdinal: evaluated.normalRolloutOrdinal,
+            modelId: input.modelId,
+            platform: input.platform
+        },
+        economics: CONTEXT_GC_POLICY,
+        metrics
+    };
+    return { stage: evaluated.stage, draft, metrics };
+}
+function evaluateCandidateSet(input, existing, candidates, state) {
+    if (candidates.length === 0)
+        return undefined;
+    const replacements = normalizeContextGcReplacements([
+        ...existing,
+        ...candidates.flatMap((candidate) => candidate.replacements)
+    ]);
+    if (!replacements)
+        return undefined;
+    const projected = applyContextGcReplacementsToMessages(input.messages, input.messageSources, replacements);
+    const reclaimedTokens = contextGcReclaimedTokens(input, input.messages, projected.messages);
+    const minimumGrossReductionRate = contextGcMinimumGrossReductionRate(state.usageRatio);
+    const minimumReclaimedTokens = contextGcMinimumReclaimedTokens(state.contextUsageTokens, input.contextWindowTokens);
+    if (reclaimedTokens < minimumReclaimedTokens)
+        return undefined;
+    const beforeTokens = contextGcPrefixTokens(input) + contextGcMessageTokens(input, input.messages);
+    const afterTokens = contextGcPrefixTokens(input) + contextGcMessageTokens(input, projected.messages);
+    if (reclaimedTokens === 0)
+        return undefined;
+    const cache = contextGcCacheImpact(input, input.messages, projected.messages, input.usage.cacheReadTokens ?? 0, reclaimedTokens);
+    const growthSamples = collectContextGrowthSamples(input.records, input.modelId, input.contextWindowTokens, input.workspace, input.checkpointCache);
+    const contextGrowthP75Tokens = percentile75(growthSamples);
+    const compactThresholdTokens = Math.floor(input.contextWindowTokens * COMPACT_THRESHOLD_RATIO);
+    // Usage describes the request before its generated output and tool results.
+    const pendingMessages = input.messages.filter((_message, index) => input.messageSources[index].sequence > state.usageRecord.sequence);
+    const pendingTokens = Math.max(0, input.usage.outputTokens ?? 0) + contextGcMessageTokens(input, pendingMessages);
+    const projectedTokensBeforeGc = state.contextUsageTokens + pendingTokens;
+    const projectedTokensAfterGc = Math.max(0, projectedTokensBeforeGc - reclaimedTokens);
+    if (projectedTokensAfterGc >= compactThresholdTokens)
+        return undefined;
+    const projectedRolloutsUntilCompactAfterGc = contextGrowthP75Tokens <= 0
+        ? 0
+        : Math.max(0, Math.floor((compactThresholdTokens - projectedTokensAfterGc) / Math.max(1, contextGrowthP75Tokens)));
+    const compactDeferralCreditCostUnits = state.usageRatio >= COMPACT_CREDIT_ACTIVATION_RATIO
+        ? compactDeferralCredit(input, reclaimedTokens, compactThresholdTokens)
+        : 0;
+    const imminentCompactAvoidanceCreditCostUnits = contextGcImminentCompactAvoidanceCredit({
+        contextUsageTokens: state.contextUsageTokens,
+        contextWindowTokens: input.contextWindowTokens,
+        compactThresholdTokens,
+        projectedTokensBeforeGc,
+        projectedTokensAfterGc,
+        contextGrowthP75Tokens
+    });
+    const appliedCompactCreditCostUnits = contextGcAppliedCompactCreditCostUnits(compactDeferralCreditCostUnits, imminentCompactAvoidanceCreditCostUnits);
+    const economics = evaluateContextGcEconomics({
+        contextUsageTokens: state.contextUsageTokens,
+        reclaimedTokens,
+        reclaimedCachedTokens: cache.reclaimedCachedTokens,
+        cacheReadTokens: input.usage.cacheReadTokens ?? 0,
+        preservedCachedPrefixTokens: cache.preservedCachedPrefixTokens,
+        compactDeferralCreditCostUnits: appliedCompactCreditCostUnits,
+        projectedRolloutsUntilCompactAfterGc,
+        contextGrowthSampleCount: growthSamples.length,
+        minimumGrossReductionRate,
+        minimumReclaimedTokens
+    });
+    return {
+        ...state,
+        economics,
+        replacements,
+        beforeTokens,
+        afterTokens,
+        reclaimedTokens,
+        contextGrowthSamples: growthSamples,
+        contextGrowthP75Tokens,
+        minimumGrossReductionRate,
+        minimumReclaimedTokens,
+        projectedRolloutsUntilCompactAfterGc,
+        projectedTokensBeforeGc,
+        projectedTokensAfterGc,
+        compactDeferralCreditCostUnits,
+        imminentCompactAvoidanceCreditCostUnits,
+        appliedCompactCreditCostUnits,
+        boundarySequence: input.records.at(-1)?.sequence ?? state.usageRecord.sequence,
+        minimumObservedRollouts: Math.min(...candidates.map((candidate) => candidate.observedRollouts)),
+        eligibleCandidateCount: candidates.length
+    };
+}
+function collectStageACandidates(input, groups, existingReplacements, existingTargets) {
+    const eligible = [];
+    let protectedTokens = 0;
+    let retryAfterRollouts = Infinity;
+    const existingReadReplacements = new Map(existingReplacements.flatMap((replacement) => replacement.kind === 'READ_OUTPUT_ITEMS'
+        ? [[contextGcTargetKey(replacement.target), replacement]]
+        : []));
+    const reads = [...groups.values()].filter((group) => group.toolName === 'read' &&
+        group.call?.message.role === 'tool_call' &&
+        group.result?.message.role === 'tool');
+    const claimedReadItems = new Set([...existingReadReplacements.values()].flatMap((replacement) => replacement.items.map((item) => `${replacement.target.recordId}:${item.index}`)));
+    const patches = [...groups.values()]
+        .flatMap((patch) => {
+        if (patch.toolName !== 'apply_patch' ||
+            !patch.call ||
+            !patch.result ||
+            patch.failed ||
+            !patch.completed)
+            return [];
+        const result = contextGcPatchResultFromCompletedPayload(patch.completed.payload);
+        return result ? [{ patch, result, evidenceSequence: patch.result.record.sequence }] : [];
+    })
+        .sort((left, right) => left.evidenceSequence - right.evidenceSequence);
+    for (const { patch, result, evidenceSequence } of patches) {
+        const patchCall = patch.call;
+        const observedRollouts = successfulRolloutsAfter(input.records, evidenceSequence, input.modelId, input.contextWindowTokens);
+        const replacements = [];
+        const patchTarget = targetFor(patchCall.record, patchCall.message);
+        if (patchTarget && !existingTargets.has(contextGcTargetKey(patchTarget)))
+            replacements.push({
+                kind: 'TOOL_CALL_INPUT',
+                toolName: 'apply_patch',
+                callId: patch.callId,
+                target: patchTarget,
+                replacementArguments: contextGcApplyPatchInputReplacement(patchCall.message.arguments, result, evidenceSequence),
+                providerAliasTargets: patch.aliases
+                    .map(({ record, message }) => targetFor(record, message))
+                    .filter((target) => target !== undefined),
+                evidenceSequence
+            });
+        for (const read of reads) {
+            if (read.result.record.sequence >= evidenceSequence)
+                continue;
+            const parsed = parseReadContextOutput(read.result.message.content);
+            if (!parsed)
+                continue;
+            const selected = parsed.items.flatMap((item) => {
+                const itemKey = `${read.result.record.recordId}:${item.index}`;
+                if (claimedReadItems.has(itemKey))
+                    return [];
+                const pathKey = contextGcLogicalPathKey(item.path, input.workspace, input.platform);
+                const matched = result.files.find((file) => file.operation !== 'added' &&
+                    contextGcLogicalPathKey(file.path, input.workspace, input.platform) === pathKey);
+                if (!pathKey || !matched || matched.operation === 'added')
+                    return [];
+                claimedReadItems.add(itemKey);
+                return [
+                    {
+                        index: item.index,
+                        path: item.path,
+                        replacement: contextGcStaleReadReplacement({
+                            path: item.path,
+                            content: item.content,
+                            evidenceSequence,
+                            supersededByCallId: patch.callId,
+                            operation: matched.operation
+                        }),
+                        evidenceSequence
+                    }
+                ];
+            });
+            if (selected.length === 0)
+                continue;
+            const target = targetFor(read.result.record, read.result.message);
+            if (!target)
+                continue;
+            const existingRead = existingReadReplacements.get(contextGcTargetKey(target));
+            replacements.push({
+                kind: 'READ_OUTPUT_ITEMS',
+                callId: read.callId,
+                target,
+                items: [...(existingRead?.items ?? []), ...selected],
+                evidenceSequences: [
+                    ...new Set([...(existingRead?.evidenceSequences ?? []), evidenceSequence])
+                ]
+            });
+        }
+        if (replacements.length === 0)
+            continue;
+        const candidate = {
+            replacements,
+            observedRollouts,
+            evidenceSequence
+        };
+        if (observedRollouts >= CONTEXT_GC_POLICY.stageAProtectionRollouts)
+            eligible.push(candidate);
+        else {
+            protectedTokens += candidateTokens(input, candidate);
+            retryAfterRollouts = Math.min(retryAfterRollouts, CONTEXT_GC_POLICY.stageAProtectionRollouts - observedRollouts);
+        }
+    }
+    return { eligible, protectedTokens, retryAfterRollouts };
+}
+function collectSubagentCandidates(input, groups, existingTargets) {
+    const eligible = [];
+    let protectedTokens = 0;
+    let retryAfterRollouts = Infinity;
+    const invocations = [...groups.values()]
+        .flatMap((group) => {
+        if (!isContextGcSubagentToolName(group.toolName) ||
+            !group.call ||
+            !group.result ||
+            group.failed ||
+            !group.completed ||
+            group.call.message.role !== 'tool_call' ||
+            group.result.message.role !== 'tool')
+            return [];
+        const snapshot = normalizeContextGcSubagentSnapshot(group.result.message.content, group.completed.payload, group.toolName);
+        const turnId = snapshot && contextGcSubagentSnapshotTurnId(snapshot);
+        return snapshot && turnId ? [{ group, snapshot, turnId }] : [];
+    })
+        .sort((left, right) => left.group.result.record.sequence - right.group.result.record.sequence);
+    for (const [index, source] of invocations.entries()) {
+        if (source.group.toolName !== 'agent_wait' && source.group.toolName !== 'agent_message')
+            continue;
+        const sourceTarget = targetFor(source.group.result.record, source.group.result.message);
+        if (!sourceTarget || existingTargets.has(contextGcTargetKey(sourceTarget)))
+            continue;
+        const needsRetainedPriorFinal = contextGcSubagentNeedsRetainedPriorFinal(source.snapshot);
+        const retainedPriorFinal = needsRetainedPriorFinal
+            ? invocations
+                .slice(0, index)
+                .findLast((candidate) => contextGcSubagentPriorFinalIsRetained(source.snapshot, candidate.snapshot))
+            : undefined;
+        if (needsRetainedPriorFinal && retainedPriorFinal === undefined)
+            continue;
+        const terminal = invocations
+            .slice(index + 1)
+            .find((candidate) => candidate.snapshot.agentId === source.snapshot.agentId &&
+            candidate.turnId === source.turnId &&
+            contextGcSubagentSnapshotIsSuperseded(source.snapshot, candidate.snapshot, retainedPriorFinal?.snapshot));
+        if (!terminal)
+            continue;
+        const sourceContent = source.group.result.message.content;
+        if (typeof sourceContent !== 'string')
+            continue;
+        const evidenceSequence = terminal.group.result.record.sequence;
+        const observedRollouts = successfulRolloutsAfter(input.records, evidenceSequence, input.modelId, input.contextWindowTokens);
+        const replacement = {
+            kind: 'SUBAGENT_OUTPUT',
+            toolName: source.group.toolName,
+            callId: source.group.callId,
+            target: sourceTarget,
+            replacementContent: contextGcSubagentOutputReplacement({
+                sourceContent,
+                source: source.snapshot,
+                terminal: terminal.snapshot,
+                terminalCallId: terminal.group.callId,
+                evidenceSequence
+            }),
+            terminalToolName: terminal.group.toolName,
+            terminalCallId: terminal.group.callId,
+            evidenceSequence,
+            ...(retainedPriorFinal === undefined
+                ? {}
+                : {
+                    retainedPriorFinal: {
+                        toolName: retainedPriorFinal.group.toolName,
+                        callId: retainedPriorFinal.group.callId,
+                        evidenceSequence: retainedPriorFinal.group.result.record.sequence
+                    }
+                })
+        };
+        const candidate = {
+            replacements: [replacement],
+            observedRollouts,
+            evidenceSequence
+        };
+        if (observedRollouts >= CONTEXT_GC_POLICY.stageAProtectionRollouts)
+            eligible.push(candidate);
+        else {
+            protectedTokens += candidateTokens(input, candidate);
+            retryAfterRollouts = Math.min(retryAfterRollouts, CONTEXT_GC_POLICY.stageAProtectionRollouts - observedRollouts);
+        }
+    }
+    return { eligible, protectedTokens, retryAfterRollouts };
+}
+function collectExecCandidates(input, groups, existingTargets) {
+    const eligible = [];
+    let protectedTokens = 0;
+    let retryAfterRollouts = Infinity;
+    const execGroups = [...groups.values()]
+        .filter((group) => group.toolName === 'exec')
+        .sort((left, right) => (left.call?.record.sequence ?? Number.MAX_SAFE_INTEGER) -
+        (right.call?.record.sequence ?? Number.MAX_SAFE_INTEGER));
+    const invocations = new Map();
+    for (const group of execGroups) {
+        if (!group.call ||
+            !group.result ||
+            group.failed ||
+            !group.completed ||
+            group.call.message.role !== 'tool_call' ||
+            group.result.message.role !== 'tool' ||
+            !isRecord(group.call.message.arguments))
+            continue;
+        const result = normalizeContextGcExecResult(group.result.message.content, group.completed.payload);
+        if (result)
+            invocations.set(group.callId, {
+                group,
+                input: group.call.message.arguments,
+                result
+            });
+    }
+    for (const startGroup of execGroups) {
+        const start = invocations.get(startGroup.callId);
+        if (!start || start.input.action !== 'start')
+            continue;
+        const lifecycle = [start];
+        let processId;
+        let terminal = start.result.status !== 'running';
+        if (!terminal) {
+            processId = typeof start.result.processId === 'string' ? start.result.processId : undefined;
+            if (!processId)
+                continue;
+            const relatedGroups = execGroups.filter((group) => (group.call?.record.sequence ?? 0) > start.group.call.record.sequence &&
+                isRecord(group.call?.message.arguments) &&
+                group.call.message.arguments.processId === processId);
+            if (relatedGroups.some((group) => !invocations.has(group.callId)) ||
+                relatedGroups.length === 0)
+                continue;
+            for (const relatedGroup of relatedGroups) {
+                const invocation = invocations.get(relatedGroup.callId);
+                lifecycle.push(invocation);
+                if (invocation.result.status !== 'running') {
+                    terminal = true;
+                    break;
+                }
+            }
+        }
+        if (!terminal || (processId && input.activeProcessIds.has(processId)))
+            continue;
+        const final = lifecycle.at(-1);
+        const visibleTokens = contextGcMessageTokens(input, lifecycle.flatMap((invocation) => [
+            invocation.group.call.message,
+            invocation.group.result.message,
+            ...invocation.group.aliases.map((alias) => alias.message)
+        ]));
+        if (visibleTokens < LARGE_EXEC_TOKENS)
+            continue;
+        const evidenceSequence = final.group.result.record.sequence;
+        const observedRollouts = successfulRolloutsAfter(input.records, evidenceSequence, input.modelId, input.contextWindowTokens);
+        const replacements = [];
+        for (const invocation of lifecycle) {
+            const callTarget = targetFor(invocation.group.call.record, invocation.group.call.message);
+            const resultTarget = targetFor(invocation.group.result.record, invocation.group.result.message);
+            if (!callTarget || !resultTarget) {
+                replacements.splice(0);
+                break;
+            }
+            if (!existingTargets.has(contextGcTargetKey(callTarget)))
+                replacements.push({
+                    kind: 'TOOL_CALL_INPUT',
+                    toolName: 'exec',
+                    callId: invocation.group.callId,
+                    target: callTarget,
+                    replacementArguments: contextGcExecInputReplacement(invocation.input),
+                    providerAliasTargets: invocation.group.aliases
+                        .map(({ record, message }) => targetFor(record, message))
+                        .filter((target) => target !== undefined),
+                    evidenceSequence
+                });
+            if (!existingTargets.has(contextGcTargetKey(resultTarget)))
+                replacements.push({
+                    kind: 'EXEC_OUTPUT',
+                    callId: invocation.group.callId,
+                    target: resultTarget,
+                    replacementContent: contextGcExecOutputReplacement(invocation.result),
+                    evidenceSequence
+                });
+        }
+        if (replacements.length === 0)
+            continue;
+        const candidate = {
+            replacements,
+            observedRollouts,
+            evidenceSequence
+        };
+        if (observedRollouts >= CONTEXT_GC_POLICY.largeExecProtectionRollouts)
+            eligible.push(candidate);
+        else {
+            protectedTokens += candidateTokens(input, candidate);
+            retryAfterRollouts = Math.min(retryAfterRollouts, CONTEXT_GC_POLICY.largeExecProtectionRollouts - observedRollouts);
+        }
+    }
+    return { eligible, protectedTokens, retryAfterRollouts };
+}
+function isContextGcSubagentToolName(value) {
+    return (value === 'agent_start' ||
+        value === 'agent_wait' ||
+        value === 'agent_message' ||
+        value === 'agent_cancel');
+}
+function buildToolGroups(records, messages, sources) {
+    const groups = new Map();
+    const group = (callId, toolName = '') => {
+        const current = groups.get(callId);
+        if (current) {
+            if (!current.toolName && toolName)
+                current.toolName = toolName;
+            return current;
+        }
+        const created = { callId, toolName, aliases: [] };
+        groups.set(callId, created);
+        return created;
+    };
+    for (const [index, message] of messages.entries()) {
+        const record = sources[index];
+        if (message.role === 'tool_call' && message.callId && message.name)
+            group(message.callId, message.name).call = { message, record };
+        else if (message.role === 'tool' && message.callId)
+            group(message.callId).result = { message, record };
+        else if (message.role === 'provider') {
+            const callId = providerToolCallId(message);
+            if (callId)
+                group(callId, providerToolName(message)).aliases.push({ message, record });
+        }
+    }
+    for (const record of records) {
+        if (!isRecord(record.payload))
+            continue;
+        const type = record.payload.type;
+        const callId = record.payload.callId;
+        const toolName = record.payload.toolName;
+        if (typeof callId !== 'string' || typeof toolName !== 'string')
+            continue;
+        const current = group(callId, toolName);
+        if (type === 'tool.completed')
+            current.completed = record;
+        else if (type === 'tool.failed')
+            current.failed = record;
+    }
+    return groups;
+}
+function successfulRolloutsAfter(records, evidenceSequence, modelId, contextWindowTokens) {
+    return countSuccessfulNormalRollouts(records.filter((record) => record.sequence > evidenceSequence), modelId, contextWindowTokens, modelConfigurationAt(records, evidenceSequence, modelId, contextWindowTokens));
+}
+function countSuccessfulNormalRollouts(records, modelId, contextWindowTokens, initial = {
+    modelId,
+    contextWindowTokens
+}) {
+    let activeModelId = initial.modelId;
+    let activeContextWindowTokens = initial.contextWindowTokens;
+    let count = 0;
+    for (const record of records) {
+        if (record.type === 'execution.header' && isRecord(record.payload)) {
+            activeModelId =
+                typeof record.payload.modelId === 'string' ? record.payload.modelId : activeModelId;
+            activeContextWindowTokens =
+                typeof record.payload.contextWindowTokens === 'number' &&
+                    Number.isSafeInteger(record.payload.contextWindowTokens) &&
+                    record.payload.contextWindowTokens > 0
+                    ? record.payload.contextWindowTokens
+                    : activeContextWindowTokens;
+            continue;
+        }
+        if (activeModelId === modelId &&
+            activeContextWindowTokens === contextWindowTokens &&
+            record.type === 'model.attempt' &&
+            isRecord(record.payload) &&
+            record.payload.purpose === 'EXECUTION' &&
+            record.payload.state === 'SUCCEEDED')
+            count++;
+    }
+    return count;
+}
+function modelConfigurationAt(records, boundarySequence, fallbackModelId, fallbackContextWindowTokens) {
+    let modelId = fallbackModelId;
+    let contextWindowTokens = fallbackContextWindowTokens;
+    for (const record of records) {
+        if (record.sequence > boundarySequence)
+            break;
+        if (record.type !== 'execution.header' || !isRecord(record.payload))
+            continue;
+        if (typeof record.payload.modelId === 'string')
+            modelId = record.payload.modelId;
+        if (typeof record.payload.contextWindowTokens === 'number' &&
+            Number.isSafeInteger(record.payload.contextWindowTokens) &&
+            record.payload.contextWindowTokens > 0)
+            contextWindowTokens = record.payload.contextWindowTokens;
+    }
+    return { modelId, contextWindowTokens };
+}
+function latestUsageRecord(records, selectedModelId) {
+    let activeModelId = selectedModelId;
+    let latest;
+    for (const record of records) {
+        if (record.type === 'execution.header') {
+            const modelId = modelIdFromRecord(record);
+            if (modelId)
+                activeModelId = modelId;
+        }
+        else if (activeModelId === selectedModelId &&
+            isRecord(record.payload) &&
+            record.payload.type === 'usage.updated' &&
+            modelContextUsage(record.payload) !== undefined)
+            latest = record;
+    }
+    return latest;
+}
+function collectContextGrowthSamples(records, modelId, contextWindowTokens, workspace, checkpointCache) {
+    const previous = checkpointCache.read(records, undefined, workspace);
+    const base = contextGcBaseFromRecords(records);
+    const startSequence = previous?.record.sequence ?? (base?.type === 'COMPACT' ? base.sequence : base?.firstSequence);
+    let activeModelId = modelId;
+    let activeWindow = contextWindowTokens;
+    let previousUsage;
+    const samples = [];
+    for (const record of records) {
+        if (startSequence !== undefined && record.sequence <= startSequence)
+            continue;
+        if (record.type === 'execution.header' && isRecord(record.payload)) {
+            const nextModel = modelIdFromRecord(record);
+            const nextWindow = record.payload.contextWindowTokens;
+            if (nextModel !== modelId ||
+                (typeof nextWindow === 'number' && nextWindow !== contextWindowTokens)) {
+                activeModelId = nextModel ?? activeModelId;
+                activeWindow =
+                    typeof nextWindow === 'number' && Number.isSafeInteger(nextWindow)
+                        ? nextWindow
+                        : activeWindow;
+                previousUsage = undefined;
+            }
+            else {
+                activeModelId = modelId;
+                activeWindow = contextWindowTokens;
+            }
+            continue;
+        }
+        if (activeModelId !== modelId ||
+            activeWindow !== contextWindowTokens ||
+            !isRecord(record.payload) ||
+            record.payload.type !== 'usage.updated')
+            continue;
+        const usage = modelContextUsage(record.payload);
+        if (usage === undefined) {
+            previousUsage = undefined;
+            continue;
+        }
+        if (previousUsage !== undefined && usage > previousUsage)
+            samples.push(usage - previousUsage);
+        previousUsage = usage;
+    }
+    return samples.slice(-CONTEXT_GC_POLICY.contextGrowthSampleWindow);
+}
+export function contextGcImminentCompactAvoidanceCredit(input) {
+    if (input.contextUsageTokens >= input.compactThresholdTokens ||
+        input.contextGrowthP75Tokens <= 0 ||
+        input.projectedTokensBeforeGc < input.compactThresholdTokens)
+        return 0;
+    const safetyMarginTokens = Math.max(input.contextWindowTokens * MINIMUM_CONTEXT_WINDOW_REDUCTION_RATIO, input.contextGrowthP75Tokens * CONTEXT_GC_POLICY.immediatePaybackRollouts);
+    if (input.projectedTokensAfterGc > input.compactThresholdTokens - safetyMarginTokens)
+        return 0;
+    return (input.contextUsageTokens *
+        CONTEXT_GC_POLICY.normalInputCostRate *
+        IMMINENT_COMPACT_CREDIT_DISCOUNT);
+}
+export function contextGcAppliedCompactCreditCostUnits(compactDeferralCreditCostUnits, imminentCompactAvoidanceCreditCostUnits) {
+    return Math.max(0, compactDeferralCreditCostUnits, imminentCompactAvoidanceCreditCostUnits);
+}
+function compactDeferralCredit(input, reclaimedTokens, compactThresholdTokens) {
+    const base = contextGcBaseFromRecords(input.records);
+    if (base?.type !== 'COMPACT')
+        return 0;
+    const compact = input.records.find((record) => record.sequence === base.sequence);
+    if (!compact || !isRecord(compact.payload))
+        return 0;
+    if (compact.payload.modelId !== input.modelId ||
+        compact.payload.contextWindowTokens !== input.contextWindowTokens ||
+        !isRecord(compact.payload.usage))
+        return 0;
+    const usage = compact.payload.usage;
+    const contextInput = modelContextUsage(usage);
+    const cacheRead = nonnegativeNumber(usage.cacheReadTokens);
+    const cacheWrite = nonnegativeNumber(usage.cacheWriteTokens);
+    const output = nonnegativeNumber(usage.outputTokens);
+    if (contextInput === undefined ||
+        cacheRead === undefined ||
+        cacheWrite === undefined ||
+        output === undefined)
+        return 0;
+    const baseline = firstMatchingUsageAfter(input.records, compact.sequence, input.modelId, input.contextWindowTokens);
+    if (baseline === undefined || baseline >= compactThresholdTokens)
+        return 0;
+    const fresh = Math.max(0, contextInput - cacheRead - cacheWrite);
+    const compactCost = fresh * CONTEXT_GC_POLICY.normalInputCostRate +
+        cacheRead * CONTEXT_GC_POLICY.cacheReadCostRate +
+        cacheWrite * CONTEXT_GC_POLICY.cacheWriteCostRate +
+        output * CONTEXT_GC_POLICY.outputCostRate;
+    const cycleCapacity = Math.max(1, compactThresholdTokens - baseline);
+    return compactCost * clamp(reclaimedTokens / cycleCapacity, 0, 1);
+}
+function firstMatchingUsageAfter(records, sequence, modelId, contextWindowTokens) {
+    let activeModelId = modelId;
+    let activeContextWindowTokens = contextWindowTokens;
+    for (const record of records) {
+        if (record.sequence <= sequence)
+            continue;
+        if (record.type === 'execution.header' && isRecord(record.payload)) {
+            if (typeof record.payload.modelId === 'string')
+                activeModelId = record.payload.modelId;
+            if (typeof record.payload.contextWindowTokens === 'number' &&
+                Number.isSafeInteger(record.payload.contextWindowTokens) &&
+                record.payload.contextWindowTokens > 0)
+                activeContextWindowTokens = record.payload.contextWindowTokens;
+            continue;
+        }
+        if (activeModelId !== modelId ||
+            activeContextWindowTokens !== contextWindowTokens ||
+            !isRecord(record.payload) ||
+            record.payload.type !== 'usage.updated')
+            continue;
+        const usage = modelContextUsage(record.payload);
+        if (usage !== undefined)
+            return usage;
+    }
+    return undefined;
+}
+function candidateTokens(input, candidate) {
+    const targets = new Set(candidate.replacements.flatMap((replacement) => [
+        contextGcTargetKey(replacement.target),
+        ...(replacement.kind === 'TOOL_CALL_INPUT'
+            ? replacement.providerAliasTargets.map(contextGcTargetKey)
+            : [])
+    ]));
+    return contextGcMessageTokens(input, input.messages.filter((message, index) => {
+        const target = targetFor(input.messageSources[index], message);
+        return target !== undefined && targets.has(contextGcTargetKey(target));
+    }));
+}
+function targetFor(record, message) {
+    if (record.type !== 'model.context' ||
+        (message.role !== 'tool_call' && message.role !== 'tool' && message.role !== 'provider'))
+        return undefined;
+    const callId = message.role === 'provider' ? providerToolCallId(message) : message.callId;
+    const toolName = message.role === 'provider' ? providerToolName(message) : message.name;
+    return {
+        sequence: record.sequence,
+        recordId: record.recordId,
+        role: message.role,
+        ...(callId === undefined ? {} : { callId }),
+        ...(toolName === undefined ? {} : { toolName }),
+        sourceHash: contextGcRecordSourceHash(record)
+    };
+}
+function modelContextUsage(value) {
+    const context = value.contextInputTokens ?? value.inputTokens;
+    return typeof context === 'number' && Number.isSafeInteger(context) && context >= 0
+        ? context
+        : undefined;
+}
+function modelIdFromRecord(record) {
+    if (!isRecord(record.payload))
+        return undefined;
+    return typeof record.payload.modelId === 'string' ? record.payload.modelId : undefined;
+}
+function percentile75(values) {
+    if (values.length === 0)
+        return 0;
+    const sorted = [...values].sort((left, right) => left - right);
+    return sorted[Math.max(0, Math.ceil(sorted.length * 0.75) - 1)];
+}
+function firstMatchingRollout(limit, predicate) {
+    for (let rollouts = 0; rollouts <= limit; rollouts++)
+        if (predicate(rollouts))
+            return rollouts;
+    return Number.POSITIVE_INFINITY;
+}
+function nonnegativeNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : undefined;
+}
+function clamp(value, minimum, maximum) {
+    return Math.min(maximum, Math.max(minimum, value));
+}
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}