@myagentroam/agent 0.11.32 → 0.11.34

package/dist/runtime/context/gc.js

@@ -0,0 +1,552 @@
+import { ContextGcCheckpointCache, contextGcBaseFromRecords, contextGcCheckpointIntervalEligible, contextGcMinimumUsageGrowth, contextGcTargetKey, normalizeContextGcReplacements } from '../../session/context-gc-checkpoint.js';
+import { CONTEXT_GC_TOKEN_ESTIMATOR, contextGcCacheImpact, contextGcMessageTokens, contextGcPrefixTokens, contextGcReclaimedTokens } from './gc-tokens.js';
+import { applyContextGcReplacementsToMessages, providerToolCallId } from './projection.js';
+import { CONTEXT_GC_POLICY, COMPACT_CREDIT_ACTIVATION_RATIO, COMPACT_THRESHOLD_RATIO, evaluateContextGcEconomics, contextGcMinimumGrossReductionRate, contextGcMinimumReclaimedTokens, contextGcEligibleUsage, contextGcMarginalCacheInvestmentPaysBack, contextGcImminentCompactAvoidanceCredit, contextGcAppliedCompactCreditCostUnits, modelContextUsage, clamp } from './gc-economics.js';
+import { buildToolGroups, countSuccessfulNormalRollouts, isRecord } from './gc-candidates.js';
+import { collectCodeModeCandidates } from './gc-candidates-code.js';
+import { collectStageACandidates } from './gc-candidates-read-patch.js';
+import { collectSubagentCandidates } from './gc-candidates-subagent.js';
+import { collectExecCandidates } from './gc-candidates-exec.js';
+import { collectWebCandidates } from './gc-candidates-web.js';
+export { CONTEXT_GC_POLICY, evaluateContextGcEconomics, contextGcMinimumGrossReductionRate, contextGcMinimumReclaimedTokens, contextGcEligibleUsage, contextGcMarginalCacheInvestmentPaysBack, contextGcImminentCompactAvoidanceCredit, contextGcAppliedCompactCreditCostUnits } from './gc-economics.js';
+export function planContextGc(input) {
+    return inspectContextGc(input).plan;
+}
+export function inspectContextGc(input) {
+    const text = inspectTextGc(input);
+    const media = input.inlineMedia;
+    if (!media || (media.reason === 'TEXT_GC' && !text.plan))
+        return text;
+    const currentUsage = modelContextUsage(input.usage);
+    const usageRecord = (currentUsage === undefined ? undefined : latestUsageRecord(input.records, input.modelId)) ??
+        input.records.at(-1);
+    const contextUsageTokens = currentUsage ?? 0;
+    if (!usageRecord)
+        return text;
+    input = {
+        ...input,
+        tokenCache: new Map(),
+        checkpointCache: input.checkpointCache ?? new ContextGcCheckpointCache()
+    };
+    const state = {
+        stage: text.plan?.stage ?? 'INLINE_MEDIA',
+        contextUsageTokens,
+        usageRatio: contextUsageTokens / input.contextWindowTokens,
+        usageRecord,
+        normalRolloutOrdinal: countSuccessfulNormalRollouts(input.records, input.modelId, input.contextWindowTokens),
+        protectedCandidateTokens: text.plan?.metrics.protectedCandidateTokens ?? 0
+    };
+    if (text.plan) {
+        const combined = evaluateCandidateSet(input, [], [
+            {
+                replacements: text.plan.draft.replacements,
+                observedRollouts: text.plan.metrics.minimumObservedRollouts,
+                evidenceSequence: text.plan.draft.boundarySequence
+            }
+        ], state, media.project);
+        if (combined?.economics.passes) {
+            const plan = finalizePlan(input, combined, true);
+            if (plan)
+                return { plan };
+        }
+        if (media.reason === 'TEXT_GC')
+            return text;
+    }
+    // Byte pressure has its own admission signal; it never relaxes text GC eligibility.
+    const onlyMedia = evaluateCandidateSet(input, input.checkpointCache.read(input.records)?.payload.replacements ?? [], [
+        {
+            replacements: [],
+            observedRollouts: media.reason === 'HARD_LIMIT' ? 0 : 2,
+            evidenceSequence: input.records.at(-1).sequence
+        }
+    ], { ...state, stage: 'INLINE_MEDIA', mediaOnly: true }, media.project);
+    const plan = onlyMedia && finalizePlan(input, onlyMedia, true);
+    return plan ? { plan } : text;
+}
+function inspectTextGc(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);
+    const checkpointEligible = contextGcCheckpointIntervalEligible({
+        usageSequence: usageRecord.sequence,
+        contextInputTokens: contextUsageTokens,
+        contextWindowTokens: input.contextWindowTokens,
+        normalRolloutOrdinal,
+        modelId: input.modelId,
+        platform: input.platform
+    }, previous?.payload.trigger);
+    // Discovery and economic evaluation have their own low-growth opportunities;
+    // neither a protected candidate nor periodic discovery makes a draft eligible.
+    if (previous?.payload.trigger.modelId === input.modelId &&
+        previous.payload.trigger.contextWindowTokens === input.contextWindowTokens) {
+        const rolloutGrowth = normalRolloutOrdinal - previous.payload.trigger.normalRolloutOrdinal;
+        if (rolloutGrowth < 2 ||
+            (previous.payload.metrics.protectedCandidateTokens === 0 &&
+                rolloutGrowth < CONTEXT_GC_POLICY.largeExecProtectionRollouts &&
+                contextUsageTokens - previous.payload.trigger.contextInputTokens <
+                    contextGcMinimumUsageGrowth(input.contextWindowTokens)))
+            return {};
+    }
+    if (input.messages.length !== input.messageSources.length)
+        return {};
+    const groups = buildToolGroups(input.records, input.messages, input.messageSources);
+    const existing = previous?.payload.replacements ?? [];
+    const candidateSavings = createCandidateSavingsEstimator(input, existing);
+    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, candidateSavings);
+    const subagent = collectSubagentCandidates(input, groups, existingTargets, candidateSavings);
+    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 exec = collectExecCandidates(input, groups, existingTargets, candidateSavings);
+        const codeMode = collectCodeModeCandidates(input, groups, existingTargets, candidateSavings);
+        const web = collectWebCandidates(input, groups, existingTargets, candidateSavings);
+        const protectedCandidateTokens = deterministicProtectedTokens +
+            exec.protectedTokens +
+            codeMode.protectedTokens +
+            web.protectedTokens;
+        const stageAPlanWithProtectedCandidates = evaluateCandidateSet(input, existing, deterministicCandidates, {
+            stage: 'STAGE_A',
+            contextUsageTokens,
+            usageRatio,
+            usageRecord,
+            normalRolloutOrdinal,
+            protectedCandidateTokens
+        }) ?? stageAPlan;
+        const marginal = mergeMarginalLargeOutputCandidates(input, existing, deterministicCandidates, [...exec.eligible, ...codeMode.eligible, ...web.eligible], stageAPlanWithProtectedCandidates, {
+            contextUsageTokens,
+            usageRatio,
+            usageRecord,
+            normalRolloutOrdinal,
+            protectedCandidateTokens
+        });
+        const plan = checkpointEligible
+            ? finalizePlan(input, marginal ?? stageAPlanWithProtectedCandidates)
+            : undefined;
+        const retryAfterRollouts = Math.min(exec.retryAfterRollouts, codeMode.retryAfterRollouts, web.retryAfterRollouts);
+        if (!plan && checkpointEligible)
+            return {};
+        return {
+            ...(plan ? { plan } : {}),
+            ...(protectedCandidateTokens > 0 && Number.isFinite(retryAfterRollouts)
+                ? { retryAfterRollouts }
+                : {})
+        };
+    }
+    const exec = collectExecCandidates(input, groups, existingTargets, candidateSavings);
+    const codeMode = collectCodeModeCandidates(input, groups, existingTargets, candidateSavings);
+    const web = collectWebCandidates(input, groups, existingTargets, candidateSavings);
+    const protectedCandidateTokens = deterministicProtectedTokens +
+        exec.protectedTokens +
+        codeMode.protectedTokens +
+        web.protectedTokens;
+    const combined = evaluateCandidateSet(input, existing, [...deterministicCandidates, ...exec.eligible, ...codeMode.eligible, ...web.eligible], {
+        stage: 'STAGE_A_AND_EXEC',
+        contextUsageTokens,
+        usageRatio,
+        usageRecord,
+        normalRolloutOrdinal,
+        protectedCandidateTokens
+    });
+    if (combined?.economics.passes && checkpointEligible) {
+        const plan = finalizePlan(input, combined);
+        return plan ? { plan } : {};
+    }
+    const retryAfterRollouts = Math.min(stageA.retryAfterRollouts, subagent.retryAfterRollouts, exec.retryAfterRollouts, codeMode.retryAfterRollouts, web.retryAfterRollouts);
+    // A worthwhile mixed set retains every positive protected candidate's retry
+    // hint even when the checkpoint interval prevents a durable draft.
+    return protectedCandidateTokens > 0 &&
+        (combined?.economics.passes ||
+            protectedCandidateTokens >=
+                contextGcMinimumReclaimedTokens(contextUsageTokens, input.contextWindowTokens)) &&
+        Number.isFinite(retryAfterRollouts)
+        ? { retryAfterRollouts }
+        : {};
+}
+function mergeMarginalLargeOutputCandidates(input, existing, deterministicCandidates, execCandidates, stageAPlan, state) {
+    let selected = [...deterministicCandidates];
+    let current = stageAPlan;
+    const stageAEarliestSequence = contextGcEarliestReplacementSequence(deterministicCandidates.flatMap((candidate) => candidate.replacements));
+    for (const candidate of [...execCandidates].sort((left, right) => right.evidenceSequence - left.evidenceSequence)) {
+        const evaluated = evaluateCandidateSet(input, existing, [...selected, candidate], {
+            stage: 'STAGE_A_AND_EXEC',
+            ...state
+        });
+        if (!evaluated?.economics.passes || evaluated.reclaimedTokens <= current.reclaimedTokens)
+            continue;
+        const doesNotMoveInvalidationEarlier = contextGcEarliestReplacementSequence(candidate.replacements) >= stageAEarliestSequence;
+        if (!doesNotMoveInvalidationEarlier &&
+            !contextGcMarginalCacheInvestmentPaysBack({
+                reclaimedTokens: current.reclaimedTokens,
+                reclaimedCachedTokens: current.reclaimedCachedTokens,
+                cacheRebuildPenaltyCostUnits: current.economics.cacheRebuildPenaltyCostUnits
+            }, {
+                reclaimedTokens: evaluated.reclaimedTokens,
+                reclaimedCachedTokens: evaluated.reclaimedCachedTokens,
+                cacheRebuildPenaltyCostUnits: evaluated.economics.cacheRebuildPenaltyCostUnits
+            }))
+            continue;
+        selected = [...selected, candidate];
+        current = evaluated;
+    }
+    return current === stageAPlan ? undefined : current;
+}
+export function contextGcEarliestReplacementSequence(replacements) {
+    return Math.min(...replacements.flatMap((replacement) => [
+        replacement.target.sequence,
+        ...(replacement.kind === 'TOOL_CALL_INPUT'
+            ? replacement.providerAliasTargets.map((target) => target.sequence)
+            : [])
+    ]));
+}
+function finalizePlan(input, evaluated, includeMedia = false) {
+    if (!evaluated)
+        return undefined;
+    let inlineMedia;
+    if (includeMedia && input.inlineMedia) {
+        const { project: _project, ...checkpoint } = input.inlineMedia;
+        inlineMedia = checkpoint;
+    }
+    const base = contextGcBaseFromRecords(input.records, evaluated.boundarySequence);
+    if (!base)
+        return undefined;
+    const replacements = normalizeContextGcReplacements(evaluated.replacements);
+    if (!replacements || (replacements.length === 0 && !inlineMedia))
+        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: Number.isFinite(evaluated.economics.requiredPositiveNetRollouts)
+            ? evaluated.economics.requiredPositiveNetRollouts
+            : null,
+        requiredTargetRoiRollouts: Number.isFinite(evaluated.economics.requiredTargetRoiRollouts)
+            ? evaluated.economics.requiredTargetRoiRollouts
+            : null,
+        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 = {
+        ...(inlineMedia ? { inlineMedia } : {}),
+        version: 1,
+        base,
+        boundarySequence: evaluated.boundarySequence,
+        replacements,
+        trigger: {
+            usageSequence: modelContextUsage(input.usage) !== undefined &&
+                isRecord(evaluated.usageRecord.payload) &&
+                evaluated.usageRecord.payload.type === 'usage.updated'
+                ? evaluated.usageRecord.sequence
+                : null,
+            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, mediaProjection) {
+    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 projectedMessages = mediaProjection?.(projected.messages) ?? projected.messages;
+    const reclaimedTokens = contextGcReclaimedTokens(input, input.messages, projectedMessages);
+    const minimumGrossReductionRate = contextGcMinimumGrossReductionRate(state.usageRatio);
+    const minimumReclaimedTokens = contextGcMinimumReclaimedTokens(state.contextUsageTokens, input.contextWindowTokens);
+    if (!state.mediaOnly && reclaimedTokens < minimumReclaimedTokens)
+        return undefined;
+    const beforeTokens = contextGcPrefixTokens(input) + contextGcMessageTokens(input, input.messages);
+    const afterTokens = contextGcPrefixTokens(input) + contextGcMessageTokens(input, projectedMessages);
+    if (!state.mediaOnly && reclaimedTokens === 0)
+        return undefined;
+    const cache = contextGcCacheImpact(input, input.messages, projectedMessages, input.usage.cacheReadTokens ?? 0, reclaimedTokens);
+    const growthSamples = collectContextGrowthSamples(input.records, input.modelId, input.contextWindowTokens, 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 (!state.mediaOnly && 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,
+        reclaimedCachedTokens: cache.reclaimedCachedTokens,
+        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 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, checkpointCache) {
+    const previous = checkpointCache.read(records);
+    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);
+}
+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;
+}
+/** Measure only affected call families, retaining native aliases for provider lowering. */
+function createCandidateSavingsEstimator(input, existing) {
+    const byCall = new Map();
+    const byRecord = new Map();
+    for (const [index, message] of input.messages.entries()) {
+        const callId = message.role === 'provider' ? providerToolCallId(message) : message.callId;
+        if (callId) {
+            const indices = byCall.get(callId) ?? [];
+            indices.push(index);
+            byCall.set(callId, indices);
+        }
+        const recordId = input.messageSources[index].recordId;
+        const indices = byRecord.get(recordId) ?? [];
+        indices.push(index);
+        byRecord.set(recordId, indices);
+    }
+    return (candidate) => {
+        const indices = new Set();
+        for (const replacement of candidate.replacements) {
+            const targets = [
+                replacement.target,
+                ...(replacement.kind === 'TOOL_CALL_INPUT' ? replacement.providerAliasTargets : [])
+            ];
+            for (const target of targets) {
+                for (const index of byRecord.get(target.recordId) ?? [])
+                    indices.add(index);
+                if (target.callId)
+                    for (const index of byCall.get(target.callId) ?? [])
+                        indices.add(index);
+            }
+        }
+        const ordered = [...indices].sort((a, b) => a - b);
+        const messages = ordered.map((index) => input.messages[index]);
+        const sources = ordered.map((index) => input.messageSources[index]);
+        const replacements = normalizeContextGcReplacements([...existing, ...candidate.replacements]);
+        if (!replacements)
+            return 0;
+        const projected = applyContextGcReplacementsToMessages(messages, sources, replacements);
+        return contextGcReclaimedTokens(input, messages, projected.messages);
+    };
+}
+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 nonnegativeNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : undefined;
+}

package/dist/runtime/context/instructions.d.ts

@@ -0,0 +1,37 @@
+import type { HostSkill } from '../../host/skill-contract.js';
+export interface AgentInstructionEntry {
+    kind: 'user' | 'project' | 'scoped';
+    label: string;
+    sourcePath: string;
+    displayPath: string;
+    scopePath: string;
+    displayScope: string;
+    content: string;
+    truncated: boolean;
+}
+interface FileAgentSkill {
+    name: string;
+    description: string;
+    path: string;
+    displayPath: string;
+    boundary: string;
+    source?: 'file';
+}
+export type AgentSkill = FileAgentSkill | (HostSkill & {
+    source: 'host';
+});
+export declare function agentSkillSource(skill: AgentSkill): string;
+export declare function loadAgentInstructions(input: {
+    home: string;
+    workspace: string;
+    workspaceDisplayPath?: string;
+    availableTools?: ReadonlySet<string>;
+    hostSkills?: readonly HostSkill[];
+}): Promise<{
+    entries: readonly AgentInstructionEntry[];
+    skillCatalog: string;
+    skills: ReadonlyMap<string, AgentSkill>;
+}>;
+export declare function renderAgentInstructions(entries: readonly AgentInstructionEntry[], previousMayContainInstructions: boolean): string | undefined;
+export declare function loadAgentSkill(skill: AgentSkill): Promise<string>;
+export {};