@myagentroam/agent 0.11.54 → 0.11.56

package/dist/runtime/context/gc-candidates-code.js

@@ -2,6 +2,7 @@ import { retainedCodeInputs } from '../../session/context-gc-observations.js';
 import { contextGcTargetKey } from '../../session/context-gc-checkpoint.js';
 import { codeCellCompletionSequence, contextGcCodeModeInputReplacement, contextGcCodeModeOutputReplacement, hasGenericContextGcPreview, normalizeContextGcCodeModeInput } from '../../session/context-gc-replacements.js';
 import { CONTEXT_GC_POLICY } from './gc-economics.js';
+import { contextGcProtectionMature } from '../../session/context-gc-protection.js';
 import { targetFor, isRecord } from './gc-candidates.js';
 export function collectCodeModeCandidates(input, groups, existingTargets, candidateSavings) {
     const eligible = [];
@@ -41,8 +42,7 @@ export function collectCodeModeCandidates(input, groups, existingTargets, candid
             const reclaimedTokens = candidateSavings(candidate);
             if (reclaimedTokens <= 0)
                 continue;
-            if (candidate.observedRollouts >= CONTEXT_GC_POLICY.largeExecProtectionRollouts &&
-                protection.thinking >= 3)
+            if (contextGcProtectionMature(protection))
                 eligible.push(candidate);
             else if (candidate.observedRollouts < CONTEXT_GC_POLICY.largeExecProtectionRollouts) {
                 protectedTokens += reclaimedTokens;
@@ -74,12 +74,12 @@ export function collectCodeModeCandidates(input, groups, existingTargets, candid
                 replacementArguments: contextGcCodeModeInputReplacement(code, group.result.message.observations
                     ? retainedCodeInputs(input.records, group.callId, (original, successor) => {
                         const maturity = input.protection.after(Math.max(evidenceSequence, completionSequence, original.sequence, successor.sequence));
-                        return maturity.rollouts >= 6 && maturity.thinking >= 3;
+                        return contextGcProtectionMature(maturity);
                     }, {
                         activeProcessIds: input.activeProcessIds,
                         evidenceMature: (sequence) => {
                             const maturity = input.protection.after(Math.max(evidenceSequence, completionSequence, sequence));
-                            return maturity.rollouts >= 6 && maturity.thinking >= 3;
+                            return contextGcProtectionMature(maturity);
                         }
                     })
                     : []),
@@ -105,8 +105,7 @@ export function collectCodeModeCandidates(input, groups, existingTargets, candid
         const reclaimedTokens = candidateSavings(candidate);
         if (reclaimedTokens <= 0)
             continue;
-        if (observedRollouts >= CONTEXT_GC_POLICY.largeExecProtectionRollouts &&
-            protection.thinking >= 3)
+        if (contextGcProtectionMature(protection))
             eligible.push(candidate);
         else if (observedRollouts < CONTEXT_GC_POLICY.largeExecProtectionRollouts) {
             protectedTokens += reclaimedTokens;

package/dist/runtime/context/gc-candidates-exec.js

@@ -1,6 +1,7 @@
 import { contextGcTargetKey } from '../../session/context-gc-checkpoint.js';
 import { contextGcExecInputReplacement, contextGcExecOutputReplacement, normalizeContextGcExecResult } from '../../session/context-gc-replacements.js';
 import { CONTEXT_GC_POLICY } from './gc-economics.js';
+import { contextGcProtectionMature } from '../../session/context-gc-protection.js';
 import { targetFor, isRecord } from './gc-candidates.js';
 import { terminalExecLifecycles } from '../../session/context-gc-exec-lifecycle.js';
 export function collectExecCandidates(input, groups, existingTargets, candidateSavings) {
@@ -80,8 +81,7 @@ export function collectExecCandidates(input, groups, existingTargets, candidateS
         let observedRollouts = Infinity;
         for (const replacement of replacements) {
             const protection = input.protection.after(Math.max(evidenceSequence, replacement.target.sequence));
-            if (protection.rollouts >= CONTEXT_GC_POLICY.largeExecProtectionRollouts &&
-                protection.thinking >= 3) {
+            if (contextGcProtectionMature(protection)) {
                 mature.push(replacement);
                 observedRollouts = Math.min(observedRollouts, protection.rollouts);
             }

package/dist/runtime/context/gc-candidates-read-patch.js

@@ -2,6 +2,7 @@ import { contextGcLogicalPathKey, contextGcTargetKey } from '../../session/conte
 import { contextGcApplyPatchInputReplacement, contextGcPatchResultFromCompletedPayload, contextGcPatchResultFromFailedPayload, contextGcStaleReadReplacement, contextGcReadRangeCovers, contextGcCoveredReadReplacement } from '../../session/context-gc-replacements.js';
 import { parseReadContextOutput } from '../../prompts/read-context.js';
 import { CONTEXT_GC_POLICY } from './gc-economics.js';
+import { contextGcProtectionMature } from '../../session/context-gc-protection.js';
 import { targetFor } from './gc-candidates.js';
 export function collectDeterministicCandidates(input, groups, existingReplacements, existingTargets, candidateSavings) {
     const eligible = [];
@@ -103,8 +104,7 @@ export function collectDeterministicCandidates(input, groups, existingReplacemen
         let observedRollouts = Infinity;
         for (const replacement of replacements) {
             const protection = input.protection.after(Math.max(evidenceSequence, replacement.target.sequence));
-            if (protection.rollouts >= CONTEXT_GC_POLICY.largeExecProtectionRollouts &&
-                protection.thinking >= 3) {
+            if (contextGcProtectionMature(protection)) {
                 mature.push(replacement);
                 observedRollouts = Math.min(observedRollouts, protection.rollouts);
             }
@@ -162,7 +162,7 @@ export function collectDeterministicCandidates(input, groups, existingReplacemen
                     ?.items.some((prior) => prior.index === candidate.index)));
             const successor = later.findLast((entry) => {
                 const count = input.protection.after(entry.target.sequence);
-                return count.rollouts >= 6 && count.thinking >= 3;
+                return contextGcProtectionMature(count);
             });
             if (!successor)
                 continue;

package/dist/runtime/context/gc-candidates-web.js

@@ -2,6 +2,7 @@ import { contextGcTargetKey } from '../../session/context-gc-checkpoint.js';
 import { completedTodoWrite, todoInputReplacement, todoSnapshotReplacement, visibleTodoSnapshot } from '../../session/context-gc-todo.js';
 import { contextGcWebOutputReplacement, contextGcToolOutputReplacement, contextGcSkillOutputReplacement, hasGenericContextGcPreview, isGenericContextGcTool } from '../../session/context-gc-replacements.js';
 import { CONTEXT_GC_POLICY } from './gc-economics.js';
+import { contextGcProtectionMature } from '../../session/context-gc-protection.js';
 import { targetFor, isRecord } from './gc-candidates.js';
 export function collectWebCandidates(input, groups, existingTargets, candidateSavings) {
     const eligible = [];
@@ -46,8 +47,7 @@ export function collectWebCandidates(input, groups, existingTargets, candidateSa
         const reclaimedTokens = candidateSavings(candidate);
         if (reclaimedTokens <= 0)
             continue;
-        if (observedRollouts >= CONTEXT_GC_POLICY.largeExecProtectionRollouts &&
-            protection.thinking >= 3)
+        if (contextGcProtectionMature(protection))
             eligible.push(candidate);
         else if (observedRollouts < CONTEXT_GC_POLICY.largeExecProtectionRollouts) {
             protectedTokens += reclaimedTokens;
@@ -82,7 +82,7 @@ export function collectToolOutputCandidates(input, groups, existingTargets, cand
                 candidate.result.message.toolSearchTools.some((item) => item.name === tool.name) &&
                 (() => {
                     const count = input.protection.after(Math.max(target.sequence, candidate.result.record.sequence));
-                    return count.rollouts >= 6 && count.thinking >= 3;
+                    return contextGcProtectionMature(count);
                 })());
             if (successor)
                 evidence.push(successor.result.record.sequence);
@@ -133,8 +133,7 @@ export function collectToolOutputCandidates(input, groups, existingTargets, cand
             continue;
         const successor = writes
             .filter((write) => write.revision > currentRevision &&
-            input.protection.after(Math.max(target.sequence, group.completed.sequence, write.record.sequence)).rollouts >= 6 &&
-            input.protection.after(Math.max(target.sequence, group.completed.sequence, write.record.sequence)).thinking >= 3)
+            contextGcProtectionMature(input.protection.after(Math.max(target.sequence, group.completed.sequence, write.record.sequence))))
             .sort((a, b) => b.revision - a.revision)[0];
         if (!successor)
             continue;
@@ -196,7 +195,7 @@ export function collectToolOutputCandidates(input, groups, existingTargets, cand
         });
         const successor = later.findLast((candidate) => {
             const count = input.protection.after(Math.max(target.sequence, candidate.result.record.sequence));
-            return count.rollouts >= 6 && count.thinking >= 3;
+            return contextGcProtectionMature(count);
         });
         if (!successor)
             continue;
@@ -259,8 +258,7 @@ export function collectToolOutputCandidates(input, groups, existingTargets, cand
         const reclaimedTokens = candidateSavings(candidate);
         if (reclaimedTokens <= 0)
             continue;
-        if (observedRollouts >= CONTEXT_GC_POLICY.largeExecProtectionRollouts &&
-            protection.thinking >= 3)
+        if (contextGcProtectionMature(protection))
             eligible.push(candidate);
         else if (observedRollouts < CONTEXT_GC_POLICY.largeExecProtectionRollouts) {
             protectedTokens += reclaimedTokens;

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

@@ -1,10 +1,24 @@
 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 CONTEXT_GC_POLICY: {
+    version: 1;
+    immediatePaybackRollouts: number;
+    minimumPaybackRollouts: number;
+    maximumPaybackRollouts: number;
+    contextGrowthSampleWindow: number;
+    minimumContextGrowthSamples: number;
+    minimumObservationRollouts: number;
+    stageAProtectionRollouts: number;
+    largeExecProtectionRollouts: number;
+    normalInputCostRate: number;
+    cacheReadCostRate: number;
+    outputCostRate: number;
+    minimumGrossReductionRate: number;
+};
 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 +31,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,25 +1,26 @@
+import { AGENT_EXECUTION_POLICY } from '../execution-policy.js';
+import { CONTEXT_GC_TEXT_PROTECTION_ROLLOUTS } from '../../session/context-gc-protection.js';
 export const CONTEXT_GC_POLICY = {
     version: 1,
     immediatePaybackRollouts: 3,
-    maximumPaybackRollouts: 20,
+    minimumPaybackRollouts: 30,
+    maximumPaybackRollouts: 60,
     contextGrowthSampleWindow: 16,
     minimumContextGrowthSamples: 6,
     minimumObservationRollouts: 1,
-    stageAProtectionRollouts: 6,
-    largeExecProtectionRollouts: 6,
+    stageAProtectionRollouts: CONTEXT_GC_TEXT_PROTECTION_ROLLOUTS,
+    largeExecProtectionRollouts: CONTEXT_GC_TEXT_PROTECTION_ROLLOUTS,
     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 +29,51 @@ 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;
+    let requiredPositiveNetRollouts;
+    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 progress = clamp((usageRatio - CONTEXT_GC_START_RATIO) / (COMPACT_THRESHOLD_RATIO - CONTEXT_GC_START_RATIO), 0, 1);
+    const paybackWindow = CONTEXT_GC_POLICY.minimumPaybackRollouts +
+        progress *
+            (CONTEXT_GC_POLICY.maximumPaybackRollouts - CONTEXT_GC_POLICY.minimumPaybackRollouts);
+    const withinWindow = requiredPositiveNetRollouts !== null && requiredPositiveNetRollouts <= paybackWindow;
     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 >= CONTEXT_GC_START_RATIO &&
+        usageRatio < COMPACT_THRESHOLD_RATIO &&
+        withinWindow;
     return {
         cacheRebuildPenaltyCostUnits,
         requiredPositiveNetRollouts,
-        requiredTargetRoiRollouts,
         expectedNetSavedCostUnits,
-        cacheInvestmentRoi,
         grossReductionRate,
         passes
     };
@@ -128,12 +131,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

@@ -2,7 +2,7 @@ import { ContextGcCheckpointCache, contextGcBaseFromRecords, contextGcCheckpoint
 import { buildContextGcProtection } from '../../session/context-gc-protection.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, contextGcImminentCompactAvoidanceCredit, contextGcAppliedCompactCreditCostUnits, modelContextUsage, clamp } from './gc-economics.js';
+import { CONTEXT_GC_POLICY, COMPACT_CREDIT_ACTIVATION_RATIO, COMPACT_THRESHOLD_RATIO, evaluateContextGcEconomics, contextGcMinimumGrossReductionRate, contextGcMinimumReclaimedTokens, contextGcEligibleUsage, contextGcImminentCompactAvoidanceCredit, modelContextUsage, clamp } from './gc-economics.js';
 import { buildToolGroups, countSuccessfulNormalRollouts, isRecord } from './gc-candidates.js';
 import { collectCodeModeCandidates } from './gc-candidates-code.js';
 import { collectDeterministicCandidates } from './gc-candidates-read-patch.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)));
@@ -270,9 +262,11 @@ function evaluateCandidateSet(input, existing, candidates, state, mediaProjectio
         projectedTokensAfterGc,
         contextGrowthP75Tokens
     });
-    const appliedCompactCreditCostUnits = contextGcAppliedCompactCreditCostUnits(compactDeferralCreditCostUnits, imminentCompactAvoidanceCreditCostUnits);
+    // Compact estimates remain diagnostic; only normal-request savings repay GC.
+    const appliedCompactCreditCostUnits = 0;
     const economics = evaluateContextGcEconomics({
         contextUsageTokens: state.contextUsageTokens,
+        contextWindowTokens: input.contextWindowTokens,
         reclaimedTokens,
         reclaimedCachedTokens: cache.reclaimedCachedTokens,
         cacheReadTokens: input.usage.cacheReadTokens ?? 0,
@@ -382,20 +376,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

@@ -1,7 +1,7 @@
 import { posix, win32 } from 'node:path';
 import { isDeepStrictEqual } from 'node:util';
 import { inlineMediaGcAnchored, parseInlineMediaGc } from './inline-media.js';
-import { buildContextGcProtection } from './context-gc-protection.js';
+import { buildContextGcProtection, contextGcProtectionMature } from './context-gc-protection.js';
 import { completedTodoWrite, todoInputReplacement, todoSnapshotReplacement, visibleTodoSnapshot } from './context-gc-todo.js';
 import { contextGcRetainedInputMarkup } from './context-gc-markup.js';
 import { codeCallEvidence, codePartialPatchCallEvidence, callsFromRecord, codeObservationEvidence, observationsFromRecord, retainedCodeInputs } from './context-gc-observations.js';
@@ -239,7 +239,7 @@ export function validateContextGcCheckpoint(records, record, workspace = session
         }
         if (anchors.some((anchor) => {
             const count = protection.after(anchor);
-            return count.rollouts < 6 || count.thinking < 3;
+            return !contextGcProtectionMature(count);
         }))
             return undefined;
         if (!replacementMatchesRecords(replacement, records, recordsBySequence, workspace, payload.trigger.platform, payload.replacements, protection, committed.get(contextGcReplacementKey(replacement))))
@@ -408,12 +408,12 @@ function replacementMatchesRecords(replacement, records, recordsBySequence, work
             isDeepStrictEqual(replacement.replacementArguments, contextGcCodeModeInputReplacement(input, observationsFromRecord(evidence.result)
                 ? retainedCodeInputs(records, replacement.callId, (original, successor) => {
                     const count = protection.after(Math.max(replacement.target.sequence, replacement.evidenceSequence, codeCellCompletionSequence(records, evidence.completed) ?? 0, original.sequence, successor.sequence));
-                    return count.rollouts >= 6 && count.thinking >= 3;
+                    return contextGcProtectionMature(count);
                 }, {
                     activeProcessIds: new Set(),
                     evidenceMature: (sequence) => {
                         const count = protection.after(Math.max(replacement.target.sequence, replacement.evidenceSequence, codeCellCompletionSequence(records, evidence.completed) ?? 0, sequence));
-                        return count.rollouts >= 6 && count.thinking >= 3;
+                        return contextGcProtectionMature(count);
                     },
                     selected: (callId, toolName, summary) => {
                         const argument = replacement.replacementArguments;
@@ -1110,14 +1110,15 @@ function isContextGcEconomicsPolicy(value) {
             'stageAProtectionRollouts',
             'largeExecProtectionRollouts'
         ].every((key) => isNonnegativeInteger(value[key])) &&
+        (value.minimumPaybackRollouts === undefined ||
+            isNonnegativeInteger(value.minimumPaybackRollouts)) &&
         [
             '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 +1151,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

@@ -5,6 +5,7 @@ export type ContextGcPlatform = 'linux' | 'darwin' | 'win32';
 export interface ContextGcEconomicsPolicy {
     readonly version: 1;
     readonly immediatePaybackRollouts: number;
+    readonly minimumPaybackRollouts?: number;
     readonly maximumPaybackRollouts: number;
     readonly contextGrowthSampleWindow: number;
     readonly minimumContextGrowthSamples: number;
@@ -13,10 +14,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 +113,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/dist/session/context-gc-protection.d.ts

@@ -1,4 +1,9 @@
 import type { SessionRecord } from './record-contract.js';
+export declare const CONTEXT_GC_TEXT_PROTECTION_ROLLOUTS = 10;
+export declare function contextGcProtectionMature(count: {
+    readonly rollouts: number;
+    readonly thinking: number;
+}): boolean;
 /** One immutable boundary index, shared by all candidate anchors in this evaluation. */
 export declare function buildContextGcProtection(records: readonly SessionRecord[], modelId: string, contextWindowTokens: number): {
     after(anchor: number): {

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

@@ -1,4 +1,8 @@
 import { completedNativeThinkingIdentity } from '../model/native-context.js';
+export const CONTEXT_GC_TEXT_PROTECTION_ROLLOUTS = 10;
+export function contextGcProtectionMature(count) {
+    return count.rollouts >= CONTEXT_GC_TEXT_PROTECTION_ROLLOUTS && count.thinking >= 3;
+}
 /** One immutable boundary index, shared by all candidate anchors in this evaluation. */
 export function buildContextGcProtection(records, modelId, contextWindowTokens) {
     const configurations = new Map();

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

@@ -24,7 +24,7 @@ export function contextGcCodeModeInputReplacement(input, retainedInputs = []) {
         originalBytes: Buffer.byteLength(input.code),
         lines: lineCount(input.code),
         inputMode: input.inputMode,
-        contextGc: 'Completed Code Mode source was reclaimed after six successful rollouts. The paired output, images, completion evidence, and nested tool side effects remain in history.',
+        contextGc: 'Completed Code Mode source was reclaimed after the protection period. The paired output, images, completion evidence, and nested tool side effects remain in history.',
         retainedInputs
     });
     return input.inputMode === 'freeform' ? content : { code: content };
@@ -37,7 +37,7 @@ export function contextGcCodeModeOutputReplacement(originalContent, truncated, v
         truncated,
         preview,
         previewComplete: !truncated && preview === originalContent,
-        contextGc: 'Detailed Code Mode output was reclaimed after six successful rollouts. An incomplete preview is not the complete cell output. The source was not replayed and nested tool side effects were not changed.'
+        contextGc: 'Detailed Code Mode output was reclaimed after the protection period. An incomplete preview is not the complete cell output. The source was not replayed and nested tool side effects were not changed.'
     });
 }
 export function contextGcPatchResultFromCompletedPayload(payload) {
@@ -111,7 +111,7 @@ export function contextGcWebOutputReplacement(toolName, originalContent, truncat
         truncated,
         preview,
         previewComplete: preview === originalContent,
-        contextGc: 'Detailed web tool output was reclaimed after six successful rollouts. An incomplete preview is not the complete search result or page, and GC did not access the network.'
+        contextGc: 'Detailed web tool output was reclaimed after the protection period. An incomplete preview is not the complete search result or page, and GC did not access the network.'
     });
 }
 /** Tools with their own evidence and lifecycle policies are never handled as generic output. */
@@ -142,7 +142,7 @@ export function contextGcToolOutputReplacement(toolName, originalContent, trunca
         truncated,
         preview,
         previewComplete: !truncated && preview === originalContent,
-        contextGc: 'Detailed tool output was reclaimed after six successful rollouts. An incomplete preview is not the complete result; the tool was not replayed.'
+        contextGc: 'Detailed tool output was reclaimed after the protection period. An incomplete preview is not the complete result; the tool was not replayed.'
     });
 }
 export function contextGcSkillOutputReplacement(name, originalContent, successorCallId) {

package/dist/session/store/jsonl/fork-session.js

@@ -3,7 +3,7 @@ import { mkdir, rename, rm } from 'node:fs/promises';
 import { join } from 'node:path';
 import { AgentError } from '../../../error.js';
 import { inlineMediaHistory } from '../../inline-media.js';
-import { copyToolResultResources } from '../../tool-result-resources.js';
+import { prepareToolResultResources, writeToolResultResourceIndex } from '../../tool-result-resources.js';
 import { syncJsonlDirectory } from './fs-durability.js';
 import { forkedPayload, stageSessionSegments } from './history.js';
 import { copyGeneratedImages, generatedImageFileNames } from './images.js';
@@ -63,14 +63,49 @@ export async function forkSessionOperation(source, records, input, sourceRoot, s
             }
         ];
         const retained = input.boundaryTurnId === null ? [] : records.slice(1, boundaryIndex + 1);
+        const resourcesByOwner = new Map();
+        for (const [resourceRef, { owner, bytes }] of await prepareToolResultResources(sourceDirectory, retained)) {
+            const resources = resourcesByOwner.get(owner) ?? [];
+            resources.push({ resourceRef, bytes });
+            resourcesByOwner.set(owner, resources);
+        }
+        const resourceLocators = new Map();
         const inlineState = inlineMediaHistory(retained).state;
         const stateAnchor = inlineState &&
             retained.findLast((record) => record.type === 'resource.window' || record.type === 'compact.completed');
         const forkIdentities = new Map();
         for (const record of retained) {
-            if (record.type === 'context.gc.completed' || record.type === 'responses.continuation')
+            if (record.type === 'context.gc.completed' ||
+                record.type === 'responses.continuation' ||
+                record.type === 'tool.resource')
                 continue;
+            const pendingLocators = [];
+            for (const { resourceRef, bytes } of resourcesByOwner.get(record.recordId) ?? []) {
+                const bodySequences = [];
+                // Small private records share normal segment durability and rollback boundaries.
+                for (let offset = 0; offset < Math.max(1, bytes.length); offset += 1024 * 1024) {
+                    const sequence = copied.length + 1;
+                    bodySequences.push(sequence);
+                    copied.push({
+                        recordId: randomUUID(),
+                        sequence,
+                        sessionId: target.id,
+                        type: 'tool.resource',
+                        payload: {
+                            resourceRef,
+                            dataBase64: bytes.subarray(offset, offset + 1024 * 1024).toString('base64')
+                        },
+                        ...(record.executionId === undefined ? {} : { executionId: record.executionId }),
+                        ...(record.turnId === undefined ? {} : { turnId: record.turnId }),
+                        timestamp: record.timestamp
+                    });
+                }
+                pendingLocators.push({ resourceRef, bodySequences });
+            }
+            resourcesByOwner.delete(record.recordId);
             const identity = { recordId: randomUUID(), sequence: copied.length + 1 };
+            for (const { resourceRef, bodySequences } of pendingLocators)
+                resourceLocators.set(resourceRef, { ...identity, bodySequences });
             forkIdentities.set(record.recordId, identity);
             copied.push({
                 ...identity,
@@ -95,7 +130,7 @@ export async function forkSessionOperation(source, records, input, sourceRoot, s
             await rename(file.temporaryPath, file.path);
         target.segments = staged.segments;
         target.nextSequence = copied.length + 1;
-        await copyToolResultResources(sourceDirectory, targetDirectory, copied);
+        await writeToolResultResourceIndex(targetDirectory, resourceLocators);
         await copyGeneratedImages(sourceRoot, publication.directory, generatedImageFileNames(retained));
         await copyResources(sourceDirectory, targetDirectory, retained);
         for (const path of [

package/dist/session/store/jsonl/history-replacement.d.ts

@@ -39,8 +39,9 @@ export type HistoryIndexOutcome = {
     readonly error: unknown;
 };
 /** Execute one rollback/clear transaction while its caller holds maintenance. */
-export declare function replaceSessionHistory(meta: SessionMeta, retained: readonly SessionRecord[], operation: {
+export declare function replaceSessionHistory(meta: SessionMeta, prefix: readonly SessionRecord[], operation: {
     kind: 'rollback';
+    reuseSegments: boolean;
 } | {
     kind: 'clear';
     clearedAt: string;

package/dist/session/store/jsonl/history-replacement.js

@@ -4,17 +4,26 @@ import { basename, join } from 'node:path';
 import { toolResultResourceFiles } from '../../tool-result-resources.js';
 import { beginSessionStorageTransaction, retiredSessionTrashPath, recoverSessionStorageTransaction } from './transaction-recovery.js';
 import { deriveExecutionState } from '../execution-state.js';
-import { renameIfExists, retainedSessionTitle, stageSessionSegments, stageUnreferencedImages } from './history.js';
+import { renameIfExists, retainedSessionTitle, stageRollbackSegments, stageSessionSegments, stageUnreferencedImages } from './history.js';
 import { generatedImageFileNames } from './images.js';
 import { CONTEXTUAL_WORLD_STATE_FILE } from './open-recovery.js';
 import { resourceFiles } from './resources.js';
 import { syncJsonlDirectory } from './fs-durability.js';
 /** Execute one rollback/clear transaction while its caller holds maintenance. */
-export async function replaceSessionHistory(meta, retained, operation, context) {
+export async function replaceSessionHistory(meta, prefix, operation, context) {
+    const retained = operation.kind === 'rollback'
+        ? prefix.filter((record) => record.type !== 'responses.continuation')
+        : prefix;
     const targetDirectory = context.targetGeneration === undefined
         ? context.directory
         : join(context.sessionDirectory, 'v2', context.targetGeneration);
-    const staged = await stageSessionSegments(targetDirectory, retained);
+    const incremental = operation.kind === 'rollback' &&
+        operation.reuseSegments &&
+        meta.storage?.encoding === 2 &&
+        meta.segments !== undefined;
+    const staged = incremental
+        ? await stageRollbackSegments(targetDirectory, prefix, meta.segments)
+        : await stageSessionSegments(targetDirectory, retained);
     const transactionId = randomUUID();
     const targetNextSequence = operation.kind === 'clear' ? 2 : (retained.at(-1)?.sequence ?? 0) + 1;
     const contextualWorldStatePath = join(context.directory, CONTEXTUAL_WORLD_STATE_FILE);
@@ -22,7 +31,9 @@ export async function replaceSessionHistory(meta, retained, operation, context)
     const originalTransactionId = meta.storageTransactionId;
     const originalPaths = await context.segmentPaths();
     const retiredPaths = await retiredSessionPaths(context.sessionDirectory, context.directory, targetDirectory);
-    const backups = originalPaths.map((path) => ({
+    const backups = originalPaths
+        .filter((path) => !staged.reused?.has(basename(path)))
+        .map((path) => ({
         path,
         backup: `${path}.${transactionId}.${operation.kind}-backup`
     }));
@@ -30,7 +41,7 @@ export async function replaceSessionHistory(meta, retained, operation, context)
         version: 1,
         id: transactionId,
         kind: operation.kind,
-        originalSegments: originalPaths.map((path) => basename(path)),
+        originalSegments: backups.map((item) => basename(item.path)),
         stagedSegments: staged.files.map((item) => ({
             path: basename(item.path),
             temporary: basename(item.temporaryPath)

package/dist/session/store/jsonl/history.d.ts

@@ -6,8 +6,13 @@ interface StagedSessionSegments {
         readonly temporaryPath: string;
     }[];
     readonly segments: NonNullable<SessionMeta['segments']>;
+    readonly reused?: ReadonlySet<string>;
 }
 export declare function stageSessionSegments(sessionDirectory: string, records: readonly SessionRecord[], operation?: 'rollback' | 'fork'): Promise<StagedSessionSegments>;
+/** Reuse intact files in ordered v2 histories; journal only replacements and removals. */
+export declare function stageRollbackSegments(directory: string, prefix: readonly SessionRecord[], originals: NonNullable<SessionMeta['segments']>): Promise<StagedSessionSegments & {
+    readonly reused: ReadonlySet<string>;
+}>;
 export declare function stageUnreferencedImages(sessionDirectory: string, directoryName: 'generated_images' | 'tool_results' | 'resources', retained: ReadonlySet<string>, transactionId: string): Promise<Array<{
     from: string;
     to: string;

package/dist/session/store/jsonl/history.js

@@ -4,6 +4,7 @@ import { join } from 'node:path';
 import { AgentError } from '../../../error.js';
 import { parseInlineMediaState } from '../../inline-media.js';
 import { MAX_SEGMENT_BYTES } from './records.js';
+import { forEachTransactionFile } from './transaction-files.js';
 export async function renameIfExists(from, to) {
     try {
         await rename(from, to);
@@ -26,23 +27,9 @@ export async function stageSessionSegments(sessionDirectory, records, operation
         if (group === undefined)
             return;
         const number = segments.length + 1;
-        const path = join(sessionDirectory, `events-${String(number).padStart(6, '0')}.jsonl`);
-        const temporaryPath = `${path}.${transactionId}.${operation}-tmp`;
-        const handle = await open(temporaryPath, 'wx', 0o600);
-        files.push({ path, temporaryPath });
-        try {
-            await handle.writeFile(group.lines.join(''));
-            await handle.sync();
-        }
-        finally {
-            await handle.close();
-        }
-        segments.push({
-            number,
-            firstSequence: group.firstSequence,
-            lastSequence: group.lastSequence,
-            bytes: group.bytes
-        });
+        const staged = await writeStagedSegment(sessionDirectory, group, number, transactionId, operation);
+        files.push(staged.file);
+        segments.push(staged.segment);
         group = undefined;
     };
     try {
@@ -67,10 +54,86 @@ export async function stageSessionSegments(sessionDirectory, records, operation
         return { files, segments };
     }
     catch (error) {
-        await Promise.all(files.map((item) => rm(item.temporaryPath, { force: true }))).catch(() => undefined);
+        await forEachTransactionFile(files, (file) => rm(file.temporaryPath, { force: true }).catch(() => undefined));
+        throw error;
+    }
+}
+/** Reuse intact files in ordered v2 histories; journal only replacements and removals. */
+export async function stageRollbackSegments(directory, prefix, originals) {
+    const files = [];
+    const segments = [];
+    const reused = new Set();
+    const transactionId = randomUUID();
+    let offset = 0;
+    try {
+        for (const original of originals) {
+            const start = offset;
+            while (offset < prefix.length && prefix[offset].sequence <= original.lastSequence)
+                offset++;
+            const source = prefix.slice(start, offset);
+            if (source.length === 0)
+                break;
+            const retained = source.filter((record) => record.type !== 'responses.continuation');
+            if (retained.length === source.length && source.at(-1).sequence === original.lastSequence) {
+                reused.add(`events-${String(original.number).padStart(6, '0')}.jsonl`);
+                segments.push({ ...original });
+            }
+            else if (retained.length > 0) {
+                const lines = retained.map((record) => `${JSON.stringify(record)}\n`);
+                const staged = await writeStagedSegment(directory, {
+                    lines,
+                    bytes: lines.reduce((total, line) => total + Buffer.byteLength(line), 0),
+                    firstSequence: retained[0].sequence,
+                    lastSequence: retained.at(-1).sequence
+                }, original.number, transactionId, 'rollback');
+                files.push(staged.file);
+                segments.push(staged.segment);
+            }
+        }
+        return { files, segments, reused };
+    }
+    catch (error) {
+        await forEachTransactionFile(files, (file) => rm(file.temporaryPath, { force: true }).catch(() => undefined));
         throw error;
     }
 }
+async function writeStagedSegment(directory, group, number, transactionId, operation) {
+    const path = join(directory, `events-${String(number).padStart(6, '0')}.jsonl`);
+    const temporaryPath = `${path}.${transactionId}.${operation}-tmp`;
+    const handle = await open(temporaryPath, 'wx', 0o600);
+    let failed = false;
+    let failure;
+    try {
+        await handle.writeFile(group.lines.join(''));
+        await handle.sync();
+    }
+    catch (error) {
+        failed = true;
+        failure = error;
+    }
+    try {
+        await handle.close();
+    }
+    catch (error) {
+        if (!failed) {
+            failed = true;
+            failure = error;
+        }
+    }
+    if (failed) {
+        await rm(temporaryPath, { force: true }).catch(() => undefined);
+        throw failure;
+    }
+    return {
+        file: { path, temporaryPath },
+        segment: {
+            number,
+            firstSequence: group.firstSequence,
+            lastSequence: group.lastSequence,
+            bytes: group.bytes
+        }
+    };
+}
 export async function stageUnreferencedImages(sessionDirectory, directoryName, retained, transactionId) {
     const directory = join(sessionDirectory, directoryName);
     let names;
@@ -84,14 +147,12 @@ export async function stageUnreferencedImages(sessionDirectory, directoryName, r
     }
     const moved = [];
     try {
-        for (const name of names) {
-            if (retained.has(name))
-                continue;
+        await forEachTransactionFile(names.filter((name) => !retained.has(name)), async (name) => {
             const from = join(directory, name);
             const trash = join(directory, `.${name}.${transactionId}.rollback-trash`);
             await rename(from, trash);
             moved.push({ from: trash, to: from, trash });
-        }
+        });
         return moved;
     }
     catch (error) {
@@ -100,8 +161,7 @@ export async function stageUnreferencedImages(sessionDirectory, directoryName, r
     }
 }
 export async function restoreRenamedFiles(files) {
-    for (const file of files.toReversed())
-        await rename(file.from, file.to).catch(() => undefined);
+    await forEachTransactionFile(files, (file) => rename(file.from, file.to).catch(() => undefined));
 }
 export function retainedSessionTitle(records, fallback) {
     let title = fallback;

package/dist/session/store/jsonl/jsonl-store.js

@@ -698,14 +698,28 @@ export class JsonlSessionStore {
             const meta = this.#shared.index.sessions.find((item) => item.id === sessionId);
             if (!meta)
                 throw new AgentError('MAR_AGENT_SESSION_NOT_FOUND', 'Session was not found.');
-            const records = await this.read(sessionId);
+            const indexedSegments = meta.segments;
+            let segmentIndex = 0;
+            let matchingSegments = indexedSegments !== undefined;
+            // Check optional cache bounds during the history read already required by rollback.
+            const records = await this.#serializeRecordOperation(sessionId, () => this.#readRecords(sessionId, undefined, (path, segment) => {
+                const indexed = indexedSegments?.[segmentIndex];
+                segmentIndex++;
+                matchingSegments &&=
+                    indexed !== undefined &&
+                        path === this.#segmentPath(sessionId, indexed.number, meta) &&
+                        segment[0]?.sequence === indexed.firstSequence &&
+                        segment.at(-1)?.sequence === indexed.lastSequence;
+            }));
             if (records[0]?.type !== 'session.created')
                 throw new AgentError('MAR_AGENT_SESSION_CORRUPT', 'Session history is corrupt.');
             const boundaryIndex = rollbackBoundaryIndex(records, input);
-            const retained = records
-                .slice(0, boundaryIndex + 1)
-                .filter((record) => record.type !== 'responses.continuation');
-            return await this.#replaceHistory(meta, retained, { kind: 'rollback' });
+            const retained = records.slice(0, boundaryIndex + 1);
+            // Migrated v1 histories may preserve duplicate or non-increasing sequences.
+            const reuseSegments = matchingSegments &&
+                segmentIndex === indexedSegments?.length &&
+                records.every((record, index) => index === 0 || record.sequence > records[index - 1].sequence);
+            return await this.#replaceHistory(meta, retained, { kind: 'rollback', reuseSegments });
         }
         catch (error) {
             failed = true;
@@ -1110,7 +1124,7 @@ export class JsonlSessionStore {
     async read(sessionId) {
         return this.#serializeRecordOperation(sessionId, () => this.#readRecords(sessionId));
     }
-    async #readRecords(sessionId, selectedMeta) {
+    async #readRecords(sessionId, selectedMeta, onSegment) {
         return withSessionReadPin(this.#sessionRoot(sessionId), async () => {
             this.#assertOpen();
             if (!selectedMeta)
@@ -1125,8 +1139,11 @@ export class JsonlSessionStore {
                 const records = [];
                 const meta = selectedMeta ?? this.#shared.index.sessions.find((item) => item.id === sessionId);
                 const encoding = meta?.storage?.encoding ?? 1;
-                for (const path of await this.#segmentPaths(sessionId, meta))
-                    records.push(...(await readRecords(path, encoding)));
+                for (const path of await this.#segmentPaths(sessionId, meta)) {
+                    const segment = await readRecords(path, encoding);
+                    onSegment?.(path, segment);
+                    records.push(...segment);
+                }
                 return records;
             }
             catch (cause) {

package/dist/session/store/jsonl/transaction-files.d.ts

@@ -0,0 +1,2 @@
+/** Stop scheduling on the first failure, then drain all in-flight filesystem operations. */
+export declare function forEachTransactionFile<T>(files: readonly T[], operation: (file: T) => Promise<unknown>): Promise<void>;

package/dist/session/store/jsonl/transaction-files.js

@@ -0,0 +1,22 @@
+/** Stop scheduling on the first failure, then drain all in-flight filesystem operations. */
+export async function forEachTransactionFile(files, operation) {
+    let next = 0;
+    let failed = false;
+    let failure;
+    await Promise.all(Array.from({ length: Math.min(8, files.length) }, async () => {
+        while (!failed && next < files.length) {
+            const file = files[next++];
+            try {
+                await operation(file);
+            }
+            catch (error) {
+                if (!failed) {
+                    failed = true;
+                    failure = error;
+                }
+            }
+        }
+    }));
+    if (failed)
+        throw failure;
+}

package/dist/session/store/jsonl/transaction-recovery.js

@@ -2,6 +2,7 @@ import { randomUUID } from 'node:crypto';
 import { lstat, mkdir, readFile, readdir, rename, rm, writeFile } from 'node:fs/promises';
 import { basename, dirname, join } from 'node:path';
 import { AgentError } from '../../../error.js';
+import { forEachTransactionFile } from './transaction-files.js';
 const JOURNAL = 'storage-transaction.json';
 const SEGMENT = /^events-\d{6}\.jsonl$/u;
 const TRANSACTION_ID = /^[0-9a-f-]{36}$/iu;
@@ -291,24 +292,24 @@ export async function recoverSessionStorageTransaction(directory, committedTrans
         ? directory
         : join(sessionDirectory, 'v2', transaction.targetGeneration);
     const originals = new Set(transaction.originalSegments);
-    for (const name of transaction.originalSegments) {
+    await forEachTransactionFile([...originals], async (name) => {
         const canonical = join(directory, name);
         const backup = `${canonical}.${transaction.id}.${transaction.kind}-backup`;
-        if (!(await exists(backup)))
-            continue;
         if (committed)
             await rm(backup, { force: true });
         else {
+            if (!(await exists(backup)))
+                return;
             await rm(canonical, { force: true });
             await rename(backup, canonical);
         }
-    }
+    });
     if (!committed)
-        for (const entry of transaction.stagedSegments)
+        await forEachTransactionFile(transaction.stagedSegments, async (entry) => {
             if (stagedDirectory !== directory || !originals.has(entry.path))
                 await rm(join(stagedDirectory, entry.path), { force: true });
-    for (const entry of transaction.stagedSegments)
-        await rm(join(stagedDirectory, entry.temporary), { force: true });
+        });
+    await forEachTransactionFile(transaction.stagedSegments, (entry) => rm(join(stagedDirectory, entry.temporary), { force: true }));
     if (!committed && transaction.targetGeneration !== undefined)
         await rm(stagedDirectory, { recursive: true, force: true });
     const sidecar = join(directory, 'context-world-state.json');
@@ -333,15 +334,13 @@ export async function recoverSessionStorageTransaction(directory, committedTrans
             throw error;
         }
         const suffix = `.${transaction.id}.rollback-trash`;
-        for (const name of names) {
-            if (!name.startsWith('.') || !name.endsWith(suffix))
-                continue;
+        await forEachTransactionFile(names.filter((name) => name.startsWith('.') && name.endsWith(suffix)), async (name) => {
             const trash = join(path, name);
             if (committed)
                 await rm(trash, { force: true });
             else
                 await rename(trash, join(path, name.slice(1, -suffix.length)));
-        }
+        });
     }
     for (const path of transaction.retiredPaths ?? []) {
         const source = join(sessionDirectory, path);
@@ -357,9 +356,7 @@ export async function recoverSessionStorageTransaction(directory, committedTrans
     await removeUnjournaledTransactionFiles(directory);
 }
 async function removeUnjournaledTransactionFiles(directory) {
-    for (const name of await readdir(directory))
-        if (isUnjournaledTransactionFile(name))
-            await rm(join(directory, name), { force: true });
+    await forEachTransactionFile((await readdir(directory)).filter(isUnjournaledTransactionFile), (name) => rm(join(directory, name), { force: true }));
 }
 async function exists(path) {
     try {

package/dist/session/tool-result-resources.d.ts

@@ -20,7 +20,16 @@ export declare function recordToolResources(record: Pick<SessionRecord, 'type' |
 /** A locator is only a hint: reads must verify its exact committed record identity. */
 export declare function bindToolResultResources(directory: string, record: SessionRecord, readRecord?: (sequence: number) => Promise<SessionRecord | undefined>, degrade?: boolean): Promise<void>;
 export declare function toolResultResourceFiles(records: readonly SessionRecord[]): Set<string>;
-export declare function copyToolResultResources(source: string, target: string, records: readonly SessionRecord[]): Promise<void>;
+export interface ToolResourceLocator {
+    sequence: number;
+    recordId: string;
+    bodySequences?: number[];
+}
+export declare function prepareToolResultResources(source: string, records: readonly SessionRecord[]): Promise<Map<string, {
+    owner: string;
+    bytes: Buffer;
+}>>;
+export declare function writeToolResultResourceIndex(target: string, locators: ReadonlyMap<string, ToolResourceLocator>): Promise<void>;
 export declare function completeToolResultResources(directory: string, record: SessionRecord): Promise<void>;
 export declare function cleanupUnreferencedToolResources(directory: string, readRecords: () => Promise<readonly SessionRecord[]>): Promise<void>;
 /** Caller must hold a stable history and resource generation for the entire read. */

package/dist/session/tool-result-resources.js

@@ -1,6 +1,6 @@
 import { createHash, randomUUID } from 'node:crypto';
 import { lstat, mkdir, readFile, readdir, rename, rm, writeFile } from 'node:fs/promises';
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
 import { AgentError } from '../error.js';
 import { parseToolResultExtensions } from '../tools/result-extensions.js';
 const REF = /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/u;
@@ -73,13 +73,8 @@ export async function bindToolResultResources(directory, record, readRecord, deg
 async function bindToolResultResource(directory, record, resource, readRecord) {
     const path = join(directory, 'tool_results', `${resource.resourceRef}.json`);
     try {
-        await writeFile(path, JSON.stringify({ sequence: record.sequence, recordId: record.recordId }), { flag: 'wx', mode: 0o600, flush: true });
-    }
-    catch (error) {
-        if (error.code !== 'EEXIST')
-            throw error;
-        try {
-            const locator = JSON.parse(await readFile(path, 'utf8'));
+        const locator = await readToolResourceLocator(path, resource.resourceRef);
+        if (locator !== undefined) {
             const existing = locator.sequence === record.sequence && locator.recordId === record.recordId
                 ? record
                 : Number.isSafeInteger(locator.sequence)
@@ -89,46 +84,103 @@ async function bindToolResultResource(directory, record, resource, readRecord) {
                 existing.recordId !== locator.recordId ||
                 !recordToolResources(existing).some((entry) => entry.resourceRef === resource.resourceRef && entry.sha256 === resource.sha256))
                 throw resourceError('CORRUPT', 'Tool resource locator conflicts with committed history.');
+            return;
         }
-        catch (cause) {
+    }
+    catch (cause) {
+        if (cause.code !== 'ENOENT')
             throw normalizedResourceError(cause);
-        }
     }
+    await writeFile(path, JSON.stringify({ sequence: record.sequence, recordId: record.recordId }), {
+        flag: 'wx',
+        mode: 0o600,
+        flush: true
+    });
 }
 export function toolResultResourceFiles(records) {
-    return new Set(records.flatMap((record) => recordToolResources(record).flatMap((resource) => [
+    const files = new Set(records.flatMap((record) => recordToolResources(record).flatMap((resource) => [
         `${resource.resourceRef}.diff`,
         `${resource.resourceRef}.json`
     ])));
+    if (files.size > 0)
+        files.add('index.json');
+    return files;
 }
-export async function copyToolResultResources(source, target, records) {
-    const copied = new Set();
+export async function prepareToolResultResources(source, records) {
+    const resources = new Map();
     for (const record of records) {
         for (const resource of recordToolResources(record)) {
-            if (copied.has(resource.resourceRef))
-                continue;
-            copied.add(resource.resourceRef);
+            const previous = resources.get(resource.resourceRef);
+            if (previous && previous.resource.sha256 !== resource.sha256)
+                throw resourceError('CORRUPT', 'Tool resource locator conflicts with committed history.');
+            if (!previous)
+                resources.set(resource.resourceRef, { record, resource });
+        }
+    }
+    const bodies = new Map();
+    if (resources.size === 0)
+        return bodies;
+    const bySequence = new Map(records.map((record) => [record.sequence, record]));
+    const pending = resources.values();
+    let failure;
+    const read = async () => {
+        while (!failure) {
+            const next = pending.next();
+            if (next.done)
+                return;
+            const { record, resource } = next.value;
             try {
-                const bytes = await readResourceBytes(source, resource);
-                const directory = join(target, 'tool_results');
-                await mkdir(directory, { recursive: true, mode: 0o700 });
-                await writeFile(join(directory, `${resource.resourceRef}.diff`), bytes, {
-                    flag: 'wx',
-                    mode: 0o600,
-                    flush: true
-                });
+                const bytes = await readResourceBytes(source, resource, async (sequence) => bySequence.get(sequence));
+                bodies.set(resource.resourceRef, { owner: record.recordId, bytes });
             }
             catch (error) {
-                if (error instanceof AgentError && error.code === 'MAR_AGENT_TOOL_RESOURCE_NOT_FOUND')
-                    continue;
-                throw error;
+                if (!(error instanceof AgentError && error.code === 'MAR_AGENT_TOOL_RESOURCE_NOT_FOUND'))
+                    failure ??= { error };
             }
         }
-        if (recordToolResources(record).length) {
-            await mkdir(join(target, 'tool_results'), { recursive: true, mode: 0o700 });
-            await bindToolResultResources(target, record, async (sequence) => records.find((item) => item.sequence === sequence));
-        }
+    };
+    await Promise.all(Array.from({ length: Math.min(8, resources.size) }, read));
+    if (failure)
+        throw failure.error;
+    return bodies;
+}
+export async function writeToolResultResourceIndex(target, locators) {
+    if (locators.size === 0)
+        return;
+    const directory = join(target, 'tool_results');
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    await writeFile(join(directory, 'index.json'), JSON.stringify({ version: 1, locators: Object.fromEntries(locators) }), {
+        flag: 'wx',
+        mode: 0o600,
+        flush: true
+    });
+}
+async function readToolResourceLocator(path, resourceRef) {
+    let text;
+    try {
+        text = await readFile(path, 'utf8');
     }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+        text = await readFile(join(dirname(path), 'index.json'), 'utf8');
+    }
+    const value = JSON.parse(text);
+    const locator = value?.version === 1 ? value.locators?.[resourceRef] : value;
+    if (value?.version === 1 && locator === undefined)
+        return undefined;
+    if (!Number.isSafeInteger(locator?.sequence) ||
+        locator.sequence < 1 ||
+        typeof locator.recordId !== 'string')
+        throw resourceError('CORRUPT', 'Invalid tool resource locator.');
+    if (locator.bodySequences !== undefined &&
+        (!Array.isArray(locator.bodySequences) ||
+            locator.bodySequences.length === 0 ||
+            !locator.bodySequences.every((sequence) => Number.isSafeInteger(sequence) &&
+                sequence > 0 &&
+                sequence < locator.sequence)))
+        throw resourceError('CORRUPT', 'Invalid tool resource body locator.');
+    return locator;
 }
 export async function completeToolResultResources(directory, record) {
     await Promise.all(recordToolResources(record).map((resource) => rm(join(directory, 'tool_results', `.${resource.resourceRef}.pending`), {
@@ -177,22 +229,20 @@ export async function readToolResultResource(directory, sessionId, input, readRe
     let locator;
     try {
         const file = join(directory, 'tool_results', `${input.resourceRef}.json`);
-        locator = JSON.parse(await readFile(file, 'utf8'));
+        locator = await readToolResourceLocator(file, input.resourceRef);
     }
     catch (error) {
         throw normalizedResourceError(error);
     }
-    if (!Number.isSafeInteger(locator.sequence) ||
-        locator.sequence < 1 ||
-        typeof locator.recordId !== 'string')
-        throw resourceError('CORRUPT', 'Invalid tool resource locator.');
+    if (locator === undefined)
+        throw resourceError('NOT_FOUND', 'Tool resource is unavailable.');
     const record = await readRecord(locator.sequence);
     const resource = record?.recordId === locator.recordId
         ? recordToolResources(record).find((entry) => entry.resourceRef === input.resourceRef)
         : undefined;
     if (!resource)
         throw resourceError('NOT_FOUND', 'Tool resource is not part of this session history.');
-    const bytes = await readResourceBytes(directory, resource);
+    const bytes = await readResourceBytes(directory, resource, readRecord, locator);
     let offset = 0;
     if (input.cursor !== undefined) {
         try {
@@ -237,10 +287,31 @@ export async function readToolResultResource(directory, sessionId, input, readRe
             : {})
     };
 }
-async function readResourceBytes(directory, resource) {
+async function readResourceBytes(directory, resource, readRecord, knownLocator) {
     try {
         return await readFile(join(directory, 'tool_results', `${resource.resourceRef}.diff`));
     }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw normalizedResourceError(error);
+    }
+    try {
+        const locator = knownLocator ??
+            (await readToolResourceLocator(join(directory, 'tool_results', `${resource.resourceRef}.json`), resource.resourceRef));
+        if (!locator?.bodySequences || !readRecord)
+            throw resourceError('NOT_FOUND', 'Tool resource is unavailable.');
+        const chunks = [];
+        for (const sequence of locator.bodySequences) {
+            const record = await readRecord(sequence);
+            const payload = record?.payload;
+            if (record?.type !== 'tool.resource' ||
+                payload?.resourceRef !== resource.resourceRef ||
+                typeof payload.dataBase64 !== 'string')
+                throw resourceError('CORRUPT', 'Invalid tool resource body.');
+            chunks.push(Buffer.from(payload.dataBase64, 'base64'));
+        }
+        return Buffer.concat(chunks);
+    }
     catch (error) {
         throw normalizedResourceError(error);
     }

package/package.json

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