@myagentroam/agent 0.11.54 → 0.11.55

package/dist/runtime/context/gc-economics.d.ts

@@ -2,9 +2,10 @@ import type { ModelUsage } from '../../model/contracts.js';
 import { type ContextGcEconomicsPolicy } from '../../session/context-gc-checkpoint.js';
 export declare const CONTEXT_GC_POLICY: ContextGcEconomicsPolicy;
 export declare const COMPACT_CREDIT_ACTIVATION_RATIO = 0.8;
-export declare const COMPACT_THRESHOLD_RATIO = 0.9;
+export declare const COMPACT_THRESHOLD_RATIO: number;
 interface ContextGcEconomicsInput {
     readonly contextUsageTokens: number;
+    readonly contextWindowTokens: number;
     readonly reclaimedTokens: number;
     readonly reclaimedCachedTokens: number;
     readonly cacheReadTokens: number;
@@ -17,10 +18,8 @@ interface ContextGcEconomicsInput {
 }
 export interface ContextGcEconomicsResult {
     readonly cacheRebuildPenaltyCostUnits: number;
-    readonly requiredPositiveNetRollouts: number;
-    readonly requiredTargetRoiRollouts: number;
+    readonly requiredPositiveNetRollouts: number | null;
     readonly expectedNetSavedCostUnits: number;
-    readonly cacheInvestmentRoi: number;
     readonly grossReductionRate: number;
     readonly passes: boolean;
 }

package/dist/runtime/context/gc-economics.js

@@ -1,3 +1,4 @@
+import { AGENT_EXECUTION_POLICY } from '../execution-policy.js';
 export const CONTEXT_GC_POLICY = {
     version: 1,
     immediatePaybackRollouts: 3,
@@ -8,18 +9,16 @@ export const CONTEXT_GC_POLICY = {
     stageAProtectionRollouts: 6,
     largeExecProtectionRollouts: 6,
     normalInputCostRate: 1,
-    cacheReadCostRate: 0.1,
-    cacheWriteCostRate: 1.25,
+    cacheReadCostRate: 0.05,
     outputCostRate: 1,
-    minimumGrossReductionRate: 0.2,
-    minimumCacheInvestmentRoi: 0.1
+    minimumGrossReductionRate: 0.2
 };
 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;
 export const COMPACT_CREDIT_ACTIVATION_RATIO = 0.8;
-export const COMPACT_THRESHOLD_RATIO = 0.9;
+export const COMPACT_THRESHOLD_RATIO = AGENT_EXECUTION_POLICY.backgroundCompactionPercent / 100;
 const IMMINENT_COMPACT_CREDIT_DISCOUNT = 0.8;
 export function evaluateContextGcEconomics(input) {
     const reclaimedTokens = Math.max(0, input.reclaimedTokens);
@@ -28,49 +27,58 @@ export function evaluateContextGcEconomics(input) {
     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);
+    // Calculate token-derived costs in cache-read units to keep exact zero exact.
+    const unitsPerNormalInput = CONTEXT_GC_POLICY.normalInputCostRate / CONTEXT_GC_POLICY.cacheReadCostRate;
+    const cacheRebuildPenalty = invalidatedRetainedCachedTokens * (unitsPerNormalInput - 1);
+    const cacheRebuildPenaltyCostUnits = cacheRebuildPenalty * 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 firstRolloutSavings = reclaimedCachedTokens + reclaimedUncachedTokens * unitsPerNormalInput;
+    const steadyRolloutSavings = reclaimedTokens;
+    const netAt = (rollouts) => (rollouts <= 0
+        ? -cacheRebuildPenalty
+        : firstRolloutSavings +
+            Math.max(0, rollouts - 1) * steadyRolloutSavings -
+            cacheRebuildPenalty) +
+        input.compactDeferralCreditCostUnits / CONTEXT_GC_POLICY.cacheReadCostRate;
+    let requiredPositiveNetRollouts;
+    if (netAt(0) > 0)
+        requiredPositiveNetRollouts = 0;
+    else if (netAt(1) > 0)
+        requiredPositiveNetRollouts = 1;
+    else if (steadyRolloutSavings <= 0)
+        requiredPositiveNetRollouts = null;
+    else {
+        requiredPositiveNetRollouts = Math.max(2, Math.floor(-netAt(1) / steadyRolloutSavings) + 2);
+        if (netAt(requiredPositiveNetRollouts - 1) > 0)
+            requiredPositiveNetRollouts--;
+        else if (netAt(requiredPositiveNetRollouts) <= 0)
+            requiredPositiveNetRollouts++;
+    }
+    const expectedNetSavedCostUnits = netAt(requiredPositiveNetRollouts ?? 0) * CONTEXT_GC_POLICY.cacheReadCostRate;
     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 usageRatio = input.contextUsageTokens / input.contextWindowTokens;
+    const thresholdPercent = AGENT_EXECUTION_POLICY.backgroundCompactionPercent;
+    const activationPercent = COMPACT_CREDIT_ACTIVATION_RATIO * 100;
+    const withinWindow = requiredPositiveNetRollouts !== null &&
+        (usageRatio <= COMPACT_CREDIT_ACTIVATION_RATIO
+            ? requiredPositiveNetRollouts <= CONTEXT_GC_POLICY.maximumPaybackRollouts
+            : requiredPositiveNetRollouts *
+                (thresholdPercent * input.contextWindowTokens - 100 * input.contextUsageTokens) <=
+                CONTEXT_GC_POLICY.maximumPaybackRollouts *
+                    (thresholdPercent - activationPercent) *
+                    input.contextWindowTokens);
     const passes = reclaimedTokens > 0 &&
         reclaimedTokens >= minimumReclaimedTokens &&
-        Number.isFinite(requiredTargetRoiRollouts) &&
-        (immediate ||
-            (requiredTargetRoiRollouts <= CONTEXT_GC_POLICY.maximumPaybackRollouts &&
-                input.contextGrowthSampleCount >= CONTEXT_GC_POLICY.minimumContextGrowthSamples &&
-                requiredTargetRoiRollouts <= input.projectedRolloutsUntilCompactAfterGc));
+        Number.isFinite(usageRatio) &&
+        usageRatio < COMPACT_THRESHOLD_RATIO &&
+        withinWindow;
     return {
         cacheRebuildPenaltyCostUnits,
         requiredPositiveNetRollouts,
-        requiredTargetRoiRollouts,
         expectedNetSavedCostUnits,
-        cacheInvestmentRoi,
         grossReductionRate,
         passes
     };
@@ -128,12 +136,6 @@ export function modelContextUsage(value) {
         ? context
         : undefined;
 }
-function firstMatchingRollout(limit, predicate) {
-    for (let rollouts = 0; rollouts <= limit; rollouts++)
-        if (predicate(rollouts))
-            return rollouts;
-    return Number.POSITIVE_INFINITY;
-}
 export function clamp(value, minimum, maximum) {
     return Math.min(maximum, Math.max(minimum, value));
 }

package/dist/runtime/context/gc.js

@@ -181,19 +181,13 @@ function finalizePlan(input, evaluated, includeMedia = false) {
         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,
+        requiredPositiveNetRollouts: evaluated.economics.requiredPositiveNetRollouts,
         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,
@@ -254,8 +248,6 @@ function evaluateCandidateSet(input, existing, candidates, state, mediaProjectio
     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)));
@@ -273,6 +265,7 @@ function evaluateCandidateSet(input, existing, candidates, state, mediaProjectio
     const appliedCompactCreditCostUnits = contextGcAppliedCompactCreditCostUnits(compactDeferralCreditCostUnits, imminentCompactAvoidanceCreditCostUnits);
     const economics = evaluateContextGcEconomics({
         contextUsageTokens: state.contextUsageTokens,
+        contextWindowTokens: input.contextWindowTokens,
         reclaimedTokens,
         reclaimedCachedTokens: cache.reclaimedCachedTokens,
         cacheReadTokens: input.usage.cacheReadTokens ?? 0,
@@ -382,20 +375,15 @@ function compactDeferralCredit(input, reclaimedTokens, compactThresholdTokens) {
     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)
+    if (contextInput === undefined || cacheRead === 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 fresh = Math.max(0, contextInput - cacheRead);
     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);

package/dist/session/context-gc-checkpoint.js

@@ -1113,11 +1113,10 @@ function isContextGcEconomicsPolicy(value) {
         [
             'normalInputCostRate',
             'cacheReadCostRate',
-            'cacheWriteCostRate',
             'outputCostRate',
-            'minimumGrossReductionRate',
-            'minimumCacheInvestmentRoi'
-        ].every((key) => isNonnegativeFinite(value[key])));
+            'minimumGrossReductionRate'
+        ].every((key) => isNonnegativeFinite(value[key])) &&
+        ['cacheWriteCostRate', 'minimumCacheInvestmentRoi'].every((key) => value[key] === undefined || isNonnegativeFinite(value[key])));
 }
 function isContextGcMetrics(value) {
     if (!isRecord(value) ||
@@ -1150,10 +1149,13 @@ function isContextGcMetrics(value) {
         'projectedTokensAfterGc'
     ];
     return (nonnegative.every((key) => isNonnegativeFinite(value[key])) &&
-        ['requiredPositiveNetRollouts', 'requiredTargetRoiRollouts'].every((key) => isNonnegativeFinite(value[key]) || (value.stage === 'INLINE_MEDIA' && value[key] === null)) &&
+        [
+            'requiredPositiveNetRollouts',
+            ...(value.requiredTargetRoiRollouts === undefined ? [] : ['requiredTargetRoiRollouts'])
+        ].every((key) => isNonnegativeFinite(value[key]) || (value.stage === 'INLINE_MEDIA' && value[key] === null)) &&
         optionalNonnegative.every((key) => value[key] === undefined || isNonnegativeFinite(value[key])) &&
         Number.isFinite(value.expectedNetSavedCostUnits) &&
-        Number.isFinite(value.cacheInvestmentRoi) &&
+        (value.cacheInvestmentRoi === undefined || Number.isFinite(value.cacheInvestmentRoi)) &&
         (value.tokenEstimator === undefined || value.tokenEstimator === 'UTF8_BYTES_V1') &&
         (value.cachePenaltyKnown === undefined || typeof value.cachePenaltyKnown === 'boolean'));
 }

package/dist/session/context-gc-contract.d.ts

@@ -13,10 +13,10 @@ export interface ContextGcEconomicsPolicy {
     readonly largeExecProtectionRollouts: number;
     readonly normalInputCostRate: number;
     readonly cacheReadCostRate: number;
-    readonly cacheWriteCostRate: number;
+    readonly cacheWriteCostRate?: number;
     readonly outputCostRate: number;
     readonly minimumGrossReductionRate: number;
-    readonly minimumCacheInvestmentRoi: number;
+    readonly minimumCacheInvestmentRoi?: number;
 }
 export type ContextGcBase = {
     readonly type: 'SESSION_START';
@@ -112,14 +112,14 @@ export interface ContextGcMetrics {
     readonly imminentCompactAvoidanceCreditCostUnits?: number;
     readonly appliedCompactCreditCostUnits?: number;
     readonly requiredPositiveNetRollouts: number | null;
-    readonly requiredTargetRoiRollouts: number | null;
+    readonly requiredTargetRoiRollouts?: number | null;
     readonly projectedRolloutsUntilCompactAfterGc: number;
     readonly projectedTokensBeforeGc?: number;
     readonly projectedTokensAfterGc?: number;
     readonly contextGrowthSampleCount: number;
     readonly contextGrowthP75Tokens: number;
     readonly expectedNetSavedCostUnits: number;
-    readonly cacheInvestmentRoi: number;
+    readonly cacheInvestmentRoi?: number;
     readonly minimumObservedRollouts: number;
     readonly protectedCandidateTokens: number;
     readonly eligibleCandidateCount: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@myagentroam/agent",
-  "version": "0.11.54",
+  "version": "0.11.55",
   "description": "Embeddable MAR coding agent SDK and CLI.",
   "license": "Apache-2.0",
   "type": "module",