@myagentroam/agent 0.9.64 → 0.9.66

package/dist/cli/main.js

@@ -226,8 +226,7 @@ async function main() {
         stdout.write(HELP);
         return;
     }
-    const command = arguments_[0];
-    if (command === 'models') {
+    if (arguments_[0] === 'models') {
         await modelsCommand(home, arguments_, codexAuthFile);
         return;
     }
@@ -240,6 +239,7 @@ async function main() {
         : parseReasoningEffort(reasoningEffortOption, '--reasoning-effort');
     const access = (takeOption(arguments_, '--access') ?? 'on-request');
     const format = takeOption(arguments_, '--format') ?? 'text';
+    const command = arguments_[0];
     if (access !== 'on-request' && access !== 'full-access')
         throw new MarAgentError('MAR_AGENT_CLI_ARGUMENT_INVALID', 'Access must be on-request or full-access.');
     const selectedModel = catalog.models.find((model) => model.id === modelId && model.enabled);
@@ -249,14 +249,18 @@ async function main() {
         throw new MarAgentError('MAR_AGENT_CLI_ARGUMENT_INVALID', `Reasoning effort "${reasoningEffort}" is not supported by model "${selectedModel.id}".`);
     const interactive = command !== 'run';
     let prompt = command === 'run' ? arguments_.slice(1).join(' ') : '';
-    const terminal = createInterface({ input: stdin, output: stdout });
+    // `run` does not need stdin until an approval or question occurs. Create
+    // readline lazily so a closed or pseudo-TTY stream in an external harness
+    // cannot fail the execution before its first model request.
+    let terminal;
+    const requireTerminal = () => (terminal ??= createInterface({ input: stdin, output: stdout }));
     const host = new LocalAgentHost({
         homeDirectory: home,
         workspace,
         approve: async (call) => {
             if (!stdin.isTTY)
                 return 'denied';
-            const answer = await terminal.question(`Approve ${call.name}? [y/N] `);
+            const answer = await requireTerminal().question(`Approve ${call.name}? [y/N] `);
             return /^y(es)?$/i.test(answer.trim()) ? 'approved' : 'denied';
         },
         question: async (request) => {
@@ -266,7 +270,7 @@ async function main() {
             for (const question of request.questions) {
                 const value = question;
                 const id = typeof value.id === 'string' ? value.id : String(Object.keys(answers).length);
-                answers[id] = await terminal.question(`${typeof value.question === 'string' ? value.question : JSON.stringify(question)} `);
+                answers[id] = await requireTerminal().question(`${typeof value.question === 'string' ? value.question : JSON.stringify(question)} `);
             }
             return answers;
         }
@@ -298,7 +302,7 @@ async function main() {
             const listed = (await agent.listSessions());
             for (const item of listed.sessions ?? [])
                 stdout.write(`${item.id}\t${item.title}\t${item.lastActivityAt}\n`);
-            resumeId = (await terminal.question('Session ID: ')).trim();
+            resumeId = (await requireTerminal().question('Session ID: ')).trim();
             if (!resumeId)
                 throw new MarAgentError('MAR_AGENT_CLI_ARGUMENT_INVALID', 'Session id is required.');
         }
@@ -314,7 +318,7 @@ async function main() {
             if (activeHandle)
                 activeHandle.cancel();
             else
-                terminal.close();
+                terminal?.close();
             process.exitCode = 130;
             if (interrupts > 1)
                 activeHandle?.cancel();
@@ -323,7 +327,7 @@ async function main() {
         try {
             do {
                 if (interactive)
-                    prompt = await terminal.question('> ');
+                    prompt = await requireTerminal().question('> ');
                 if (!prompt.trim())
                     break;
                 const invocation = parseExecutionInvocation(prompt);
@@ -360,7 +364,7 @@ async function main() {
         }
     }
     finally {
-        terminal.close();
+        terminal?.close();
         await agent.dispose();
     }
 }

package/dist/model/openai-responses.js

@@ -4,7 +4,7 @@ import { describeMarAgentError, MarAgentError } from '../error.js';
 import { resolveModelDefaultReasoningEffort } from './configuration.js';
 import WebSocket from 'ws';
 import { isRetryableUpstreamOverloadCode, number, parseSse, record, text } from './sse.js';
-import { connectSocks5Target, fetchModelResponse, isRetryableModelTransportError, modelRetryMaxAttempts, isRetryableModelRequestError, modelRetryDelay, waitForModelRetry } from './http.js';
+import { connectSocks5Target, fetchModelResponse, isRetryableModelHttpStatus, isRetryableModelTransportError, modelRetryMaxAttempts, isRetryableModelRequestError, modelRetryDelay, waitForModelRetry } from './http.js';
 import { acquireModelCredential, appendModelCredentialHeaders } from './runtime-credential.js';
 const WEBSOCKET_IDLE_TIMEOUT_MS = 300_000;
 export const OPENAI_RESPONSES_EARLY_EOF_REASON = 'OPENAI_RESPONSES_EARLY_EOF';
@@ -742,7 +742,11 @@ class OpenAiResponsesTurnSession {
         if (socket?.readyState !== WebSocket.OPEN) {
             invalidateResponsesWebSocket(this.state, true);
             throw new MarAgentError('MAR_AGENT_MODEL_CONNECTION_FAILED', 'OpenAI Responses WebSocket connection is unavailable.', {
-                details: { transport: 'WEBSOCKET', continuation: input.continuation },
+                details: {
+                    transport: 'WEBSOCKET',
+                    continuation: input.continuation,
+                    reason: 'MODEL_TRANSPORT_FAILURE'
+                },
                 retryable: true
             });
         }
@@ -1003,15 +1007,32 @@ async function waitForWebSocketOpen(socket, signal) {
             reject(signal.reason);
         });
         const open = () => settle(resolve);
-        const error = (cause) => settle(() => reject(new MarAgentError('MAR_AGENT_MODEL_CONNECTION_FAILED', 'OpenAI Responses WebSocket connection failed.', { cause })));
-        const close = () => settle(() => reject(new MarAgentError('MAR_AGENT_MODEL_CONNECTION_FAILED', 'OpenAI Responses WebSocket closed during connection.')));
+        const error = (cause) => settle(() => reject(new MarAgentError('MAR_AGENT_MODEL_CONNECTION_FAILED', 'OpenAI Responses WebSocket connection failed.', {
+            details: { reason: 'MODEL_TRANSPORT_FAILURE', transport: 'WEBSOCKET' },
+            retryable: true,
+            cause
+        })));
+        const close = () => settle(() => reject(new MarAgentError('MAR_AGENT_MODEL_CONNECTION_FAILED', 'OpenAI Responses WebSocket closed during connection.', {
+            details: { reason: 'MODEL_TRANSPORT_FAILURE', transport: 'WEBSOCKET' },
+            retryable: true
+        })));
         const unexpectedResponse = (_request, response) => settle(() => {
             const status = response.statusCode ?? 0;
             response.resume();
             terminateWebSocket(socket);
+            const retryable = status !== 401 && isRetryableModelHttpStatus(status);
+            const retryAfter = response.headers['retry-after'];
+            const retryAfterValue = Array.isArray(retryAfter) ? retryAfter[0] : retryAfter;
             reject(new MarAgentError(status === 401 ? 'MAR_AGENT_MODEL_AUTH_FAILED' : 'MAR_AGENT_MODEL_CONNECTION_FAILED', status === 401
                 ? 'OpenAI Responses WebSocket authentication failed.'
-                : 'OpenAI Responses WebSocket handshake failed.', { details: { status } }));
+                : 'OpenAI Responses WebSocket handshake failed.', {
+                details: {
+                    status,
+                    transport: 'WEBSOCKET',
+                    ...(retryAfterValue === undefined ? {} : { retryAfter: retryAfterValue })
+                },
+                ...(retryable ? { retryable: true } : {})
+            }));
         });
         signal.addEventListener('abort', abort, { once: true });
         socket.once('open', open);

package/dist/prompts/output.d.ts

@@ -1 +1,2 @@
 export declare const outputStylePrompt = "# Output and communication style\nBe direct, natural, and concise. Match detail and structure to the user's needs and the task's complexity. Lead with the result; include actual verification, material risks, and unfinished work when relevant. Avoid repeating progress, dumping logs, or adding empty sections. For a requested review, lead with actionable findings ordered by severity and file evidence; if none were found, say so and note validation gaps. Preserve exact paths, identifiers, error codes, citations, and useful line locations when they are evidence. Never expose hidden reasoning.";
+export declare const modelOutputContinuationMessage = "Continue the previous response from exactly where it stopped. Do not repeat completed content.";

package/dist/prompts/output.js

@@ -1 +1,2 @@
 export const outputStylePrompt = "# Output and communication style\nBe direct, natural, and concise. Match detail and structure to the user's needs and the task's complexity. Lead with the result; include actual verification, material risks, and unfinished work when relevant. Avoid repeating progress, dumping logs, or adding empty sections. For a requested review, lead with actionable findings ordered by severity and file evidence; if none were found, say so and note validation gaps. Preserve exact paths, identifiers, error codes, citations, and useful line locations when they are evidence. Never expose hidden reasoning.";
+export const modelOutputContinuationMessage = 'Continue the previous response from exactly where it stopped. Do not repeat completed content.';

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

@@ -1,18 +1,20 @@
 import { isDeepStrictEqual } from 'node:util';
 import { ContextGcCheckpointCache, contextGcMinimumUsageGrowth, contextGcReplacementKey, contextGcSourceProjectionHash } from '../session/context-gc-checkpoint.js';
-import { contextGcEligibleUsage, inspectContextGc } from './context-gc.js';
+import { CONTEXT_GC_POLICY, contextGcEligibleUsage, inspectContextGc } from './context-gc.js';
 import { buildContextProjection } from './context-projection.js';
 /** Only scheduling metadata survives a call; records and validation caches do not. */
 export class ContextGcRuntime {
     #scope = '';
     #lastUsage;
     #checkpoint;
+    #rolloutsSinceCheckpoint = 0;
     #failures = 0;
     #remaining = 0;
     reset() {
         this.#scope = '';
         this.#lastUsage = undefined;
         this.#checkpoint = undefined;
+        this.#rolloutsSinceCheckpoint = 0;
         this.#failures = 0;
         this.#remaining = 0;
     }
@@ -39,26 +41,39 @@ export class ContextGcRuntime {
             this.#remaining = 0;
         }
         this.#lastUsage = usage;
+        if (this.#checkpoint)
+            this.#rolloutsSinceCheckpoint++;
         const maximumInterval = usage / input.contextWindowTokens >= 0.8 ? 2 : 8;
         this.#remaining = Math.min(this.#remaining, maximumInterval - 1);
         if (this.#remaining > 0) {
             this.#remaining--;
             return false;
         }
-        if (this.#checkpoint?.modelId === input.modelId &&
-            this.#checkpoint.contextWindowTokens === input.contextWindowTokens &&
-            usage - this.#checkpoint.contextInputTokens <
+        if (this.#checkpoint?.trigger.modelId === input.modelId &&
+            this.#checkpoint.trigger.contextWindowTokens === input.contextWindowTokens &&
+            !this.#checkpoint.protectedCandidatesPending &&
+            this.#rolloutsSinceCheckpoint < CONTEXT_GC_POLICY.largeExecProtectionRollouts &&
+            usage - this.#checkpoint.trigger.contextInputTokens <
                 contextGcMinimumUsageGrowth(input.contextWindowTokens))
             return false;
         const attempt = await attemptContextGc(input);
         if (attempt.result) {
-            this.#checkpoint = { ...attempt.result.projection.checkpoint.trigger };
+            this.#checkpoint = {
+                trigger: { ...attempt.result.projection.checkpoint.trigger },
+                protectedCandidatesPending: attempt.result.projection.checkpoint.metrics.protectedCandidateTokens > 0
+            };
+            this.#rolloutsSinceCheckpoint = 0;
             this.#failures = 0;
             this.#remaining = 1;
         }
         else {
             if (attempt.checkpointTrigger)
-                this.#checkpoint = { ...attempt.checkpointTrigger };
+                this.#checkpoint = {
+                    trigger: { ...attempt.checkpointTrigger },
+                    protectedCandidatesPending: attempt.protectedCandidatesPending === true
+                };
+            if (attempt.checkpointTrigger)
+                this.#rolloutsSinceCheckpoint = 0;
             this.#failures = Math.min(3, this.#failures + 1);
             this.#remaining =
                 Math.min(2 ** this.#failures, maximumInterval, attempt.retryAfterRollouts ?? Infinity) - 1;
@@ -85,9 +100,22 @@ async function attemptContextGc(input) {
         const checkpointCache = new ContextGcCheckpointCache();
         const previous = checkpointCache.read(records, undefined, input.workspace);
         if (previous) {
-            deferred = { ...deferred, checkpointTrigger: previous.payload.trigger };
-            if (contextUsage - previous.payload.trigger.contextInputTokens <
-                contextGcMinimumUsageGrowth(input.contextWindowTokens))
+            deferred = {
+                ...deferred,
+                checkpointTrigger: previous.payload.trigger,
+                protectedCandidatesPending: previous.payload.metrics.protectedCandidateTokens > 0
+            };
+            const rolloutGrowth = records.filter((record) => record.sequence > previous.record.sequence &&
+                record.type === 'model.attempt' &&
+                isRecord(record.payload) &&
+                record.payload.purpose === 'EXECUTION' &&
+                record.payload.state === 'SUCCEEDED').length;
+            const minimumRollouts = previous.payload.metrics.protectedCandidateTokens > 0
+                ? 2
+                : CONTEXT_GC_POLICY.largeExecProtectionRollouts;
+            if (rolloutGrowth < minimumRollouts &&
+                contextUsage - previous.payload.trigger.contextInputTokens <
+                    contextGcMinimumUsageGrowth(input.contextWindowTokens))
                 return deferred;
         }
         const projection = buildContextProjection(records, input.workspace, checkpointCache);
@@ -107,7 +135,13 @@ async function attemptContextGc(input) {
             activeProcessIds: input.activeProcessIds ?? (await input.getActiveProcessIds?.()) ?? new Set()
         });
         if (inspection.retryAfterRollouts !== undefined)
-            deferred = { ...deferred, retryAfterRollouts: inspection.retryAfterRollouts };
+            deferred = {
+                ...deferred,
+                protectedCandidatesPending: true,
+                retryAfterRollouts: inspection.retryAfterRollouts
+            };
+        else if (!inspection.plan)
+            deferred = { ...deferred, protectedCandidatesPending: false };
         const plan = inspection.plan;
         if (!plan)
             return deferred;
@@ -161,3 +195,6 @@ async function matchingCheckpointWasPersisted(store, sessionId, draft, workspace
     });
     return matches ? { records: state.contextRecords, projection } : false;
 }
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}

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

@@ -1,5 +1,5 @@
 import type { ClientToolDefinition, ModelMessage, ModelUsage } from '../model/contracts.js';
-import { ContextGcCheckpointCache, type ContextGcCheckpointDraft, type ContextGcEconomicsPolicy, type ContextGcMetrics, type ContextGcPlatform } from '../session/context-gc-checkpoint.js';
+import { ContextGcCheckpointCache, type ContextGcCheckpointDraft, type ContextGcEconomicsPolicy, type ContextGcMetrics, type ContextGcPlatform, type ContextGcReplacement } from '../session/context-gc-checkpoint.js';
 import type { SessionRecord } from '../session/jsonl-store.js';
 export declare const CONTEXT_GC_POLICY: ContextGcEconomicsPolicy;
 interface ContextGcEconomicsInput {
@@ -28,6 +28,11 @@ export interface ContextGcPlan {
     readonly draft: ContextGcCheckpointDraft;
     readonly metrics: ContextGcMetrics;
 }
+interface ContextGcCacheEconomicsProfile {
+    readonly reclaimedTokens: number;
+    readonly reclaimedCachedTokens: number;
+    readonly cacheRebuildPenaltyCostUnits: number;
+}
 export interface ContextGcInspection {
     readonly plan?: ContextGcPlan;
     readonly retryAfterRollouts?: number;
@@ -54,6 +59,8 @@ export declare function contextGcMinimumReclaimedTokens(contextUsageTokens: numb
 export declare function contextGcEligibleUsage(usage: ModelUsage, contextWindowTokens: number): number | undefined;
 export declare function planContextGc(input: ContextGcPlannerInput): ContextGcPlan | undefined;
 export declare function inspectContextGc(input: ContextGcPlannerInput): ContextGcInspection;
+export declare function contextGcMarginalCacheInvestmentPaysBack(current: ContextGcCacheEconomicsProfile, combined: ContextGcCacheEconomicsProfile): boolean;
+export declare function contextGcEarliestReplacementSequence(replacements: readonly ContextGcReplacement[]): number;
 export declare function contextGcImminentCompactAvoidanceCredit(input: {
     readonly contextUsageTokens: number;
     readonly contextWindowTokens: number;

package/dist/runtime/context-gc.js

@@ -1,6 +1,6 @@
 import { ContextGcCheckpointCache, contextGcBaseFromRecords, contextGcLogicalPathKey, contextGcMinimumUsageGrowth, contextGcRecordSourceHash, contextGcTargetKey, normalizeContextGcReplacements } from '../session/context-gc-checkpoint.js';
-import { contextGcApplyPatchInputReplacement, contextGcExecInputReplacement, contextGcExecOutputReplacement, contextGcPatchResultFromCompletedPayload, contextGcStaleReadReplacement, normalizeContextGcExecResult } from '../session/context-gc-replacements.js';
-import { contextGcSubagentNeedsRetainedPriorFinal, contextGcSubagentOutputReplacement, contextGcSubagentPriorFinalIsRetained, contextGcSubagentSnapshotIsSuperseded, contextGcSubagentSnapshotTurnId, normalizeContextGcSubagentSnapshot } from '../session/context-gc-subagent.js';
+import { contextGcApplyPatchInputReplacement, contextGcExecInputReplacement, contextGcExecOutputReplacement, contextGcPatchResultFromCompletedPayload, contextGcStaleReadReplacement, contextGcWebOutputReplacement, normalizeContextGcExecResult } from '../session/context-gc-replacements.js';
+import { contextGcSubagentNeedsRetainedPriorFinal, contextGcSubagentOutputReplacement, contextGcSubagentPriorFinalIsRetained, contextGcSubagentSnapshotIsPreciselyCovered, contextGcSubagentSnapshotIsSuperseded, contextGcSubagentSnapshotTurnId, normalizeContextGcSubagentSnapshot } from '../session/context-gc-subagent.js';
 import { parseReadContextOutput } from '../tools/read-context.js';
 import { CONTEXT_GC_TOKEN_ESTIMATOR, contextGcCacheImpact, contextGcMessageTokens, contextGcPrefixTokens, contextGcReclaimedTokens } from './context-gc-tokens.js';
 import { applyContextGcReplacementsToMessages, providerToolCallId, providerToolName } from './context-projection.js';
@@ -27,7 +27,8 @@ const MINIMUM_CONTEXT_WINDOW_REDUCTION_RATIO = 0.05;
 const COMPACT_CREDIT_ACTIVATION_RATIO = 0.8;
 const COMPACT_THRESHOLD_RATIO = 0.9;
 const IMMINENT_COMPACT_CREDIT_DISCOUNT = 0.8;
-const LARGE_EXEC_TOKENS = 4_096;
+const LARGE_TERMINAL_OUTPUT_TOKENS = 4_096;
+const HIGH_WATER_LARGE_TERMINAL_OUTPUT_TOKENS = 2_048;
 export function evaluateContextGcEconomics(input) {
     const reclaimedTokens = Math.max(0, input.reclaimedTokens);
     const cacheReadTokens = Math.max(0, input.cacheReadTokens);
@@ -134,8 +135,12 @@ export function inspectContextGc(input) {
     const previous = input.checkpointCache.read(input.records, undefined, input.workspace);
     if (previous) {
         const minimumUsageGrowth = contextGcMinimumUsageGrowth(input.contextWindowTokens);
-        if (normalRolloutOrdinal - previous.payload.trigger.normalRolloutOrdinal < 2 ||
-            contextUsageTokens - previous.payload.trigger.contextInputTokens < minimumUsageGrowth)
+        const protectedCandidatesPending = previous.payload.metrics.protectedCandidateTokens > 0;
+        const rolloutGrowth = normalRolloutOrdinal - previous.payload.trigger.normalRolloutOrdinal;
+        if (rolloutGrowth < 2 ||
+            (!protectedCandidatesPending &&
+                rolloutGrowth < CONTEXT_GC_POLICY.largeExecProtectionRollouts &&
+                contextUsageTokens - previous.payload.trigger.contextInputTokens < minimumUsageGrowth))
             return {};
     }
     if (input.messages.length !== input.messageSources.length)
@@ -161,29 +166,114 @@ export function inspectContextGc(input) {
         protectedCandidateTokens: deterministicProtectedTokens
     });
     if (stageAPlan?.economics.passes) {
-        const plan = finalizePlan(input, stageAPlan);
-        return plan ? { plan } : {};
+        const exec = collectExecCandidates(input, groups, existingTargets, usageRatio);
+        const web = collectWebCandidates(input, groups, existingTargets, usageRatio);
+        const protectedCandidateTokens = deterministicProtectedTokens + exec.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, ...web.eligible], stageAPlanWithProtectedCandidates, {
+            contextUsageTokens,
+            usageRatio,
+            usageRecord,
+            normalRolloutOrdinal,
+            protectedCandidateTokens
+        });
+        const plan = finalizePlan(input, marginal ?? stageAPlanWithProtectedCandidates);
+        const retryAfterRollouts = Math.min(exec.retryAfterRollouts, web.retryAfterRollouts);
+        return plan
+            ? {
+                plan,
+                ...(protectedCandidateTokens > 0 && Number.isFinite(retryAfterRollouts)
+                    ? { retryAfterRollouts }
+                    : {})
+            }
+            : {};
     }
-    const exec = collectExecCandidates(input, groups, existingTargets);
-    const combined = evaluateCandidateSet(input, existing, [...deterministicCandidates, ...exec.eligible], {
+    const exec = collectExecCandidates(input, groups, existingTargets, usageRatio);
+    const web = collectWebCandidates(input, groups, existingTargets, usageRatio);
+    const combined = evaluateCandidateSet(input, existing, [...deterministicCandidates, ...exec.eligible, ...web.eligible], {
         stage: 'STAGE_A_AND_EXEC',
         contextUsageTokens,
         usageRatio,
         usageRecord,
         normalRolloutOrdinal,
-        protectedCandidateTokens: deterministicProtectedTokens + exec.protectedTokens
+        protectedCandidateTokens: deterministicProtectedTokens + exec.protectedTokens + web.protectedTokens
     });
     if (combined?.economics.passes) {
         const plan = finalizePlan(input, combined);
         return plan ? { plan } : {};
     }
-    const retryAfterRollouts = Math.min(stageA.retryAfterRollouts, subagent.retryAfterRollouts, exec.retryAfterRollouts);
-    return deterministicProtectedTokens + exec.protectedTokens >=
+    const retryAfterRollouts = Math.min(stageA.retryAfterRollouts, subagent.retryAfterRollouts, exec.retryAfterRollouts, web.retryAfterRollouts);
+    return deterministicProtectedTokens + exec.protectedTokens + web.protectedTokens >=
         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 contextGcMarginalCacheInvestmentPaysBack(current, combined) {
+    const marginalPenalty = combined.cacheRebuildPenaltyCostUnits - current.cacheRebuildPenaltyCostUnits;
+    if (marginalPenalty <= 0)
+        return true;
+    const firstRolloutSavings = (profile) => {
+        const reclaimedCachedTokens = clamp(profile.reclaimedCachedTokens, 0, Math.max(0, profile.reclaimedTokens));
+        return (reclaimedCachedTokens * CONTEXT_GC_POLICY.cacheReadCostRate +
+            Math.max(0, profile.reclaimedTokens - reclaimedCachedTokens) *
+                CONTEXT_GC_POLICY.normalInputCostRate);
+    };
+    const marginalFirstRolloutSavings = firstRolloutSavings(combined) - firstRolloutSavings(current);
+    const marginalSteadyRolloutSavings = Math.max(0, combined.reclaimedTokens - current.reclaimedTokens) *
+        CONTEXT_GC_POLICY.cacheReadCostRate;
+    for (let rollouts = 1; rollouts <= CONTEXT_GC_POLICY.immediatePaybackRollouts; rollouts++) {
+        const net = -marginalPenalty +
+            marginalFirstRolloutSavings +
+            Math.max(0, rollouts - 1) * marginalSteadyRolloutSavings;
+        if (net > 0 && net / marginalPenalty >= CONTEXT_GC_POLICY.minimumCacheInvestmentRoi)
+            return true;
+    }
+    return false;
+}
+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) {
     if (!evaluated)
         return undefined;
@@ -302,6 +392,7 @@ function evaluateCandidateSet(input, existing, candidates, state) {
     return {
         ...state,
         economics,
+        reclaimedCachedTokens: cache.reclaimedCachedTokens,
         replacements,
         beforeTokens,
         afterTokens,
@@ -444,7 +535,9 @@ function collectSubagentCandidates(input, groups, existingTargets) {
     })
         .sort((left, right) => left.group.result.record.sequence - right.group.result.record.sequence);
     for (const [index, source] of invocations.entries()) {
-        if (source.group.toolName !== 'agent_wait' && source.group.toolName !== 'agent_message')
+        if (source.group.toolName !== 'agent_wait' &&
+            source.group.toolName !== 'agent_message' &&
+            source.group.toolName !== 'agent_cancel')
             continue;
         const sourceTarget = targetFor(source.group.result.record, source.group.result.message);
         if (!sourceTarget || existingTargets.has(contextGcTargetKey(sourceTarget)))
@@ -461,7 +554,8 @@ function collectSubagentCandidates(input, groups, existingTargets) {
             .slice(index + 1)
             .find((candidate) => candidate.snapshot.agentId === source.snapshot.agentId &&
             candidate.turnId === source.turnId &&
-            contextGcSubagentSnapshotIsSuperseded(source.snapshot, candidate.snapshot, retainedPriorFinal?.snapshot));
+            (contextGcSubagentSnapshotIsSuperseded(source.snapshot, candidate.snapshot, retainedPriorFinal?.snapshot) ||
+                contextGcSubagentSnapshotIsPreciselyCovered(source.snapshot, candidate.snapshot)));
         if (!terminal)
             continue;
         const sourceContent = source.group.result.message.content;
@@ -508,7 +602,7 @@ function collectSubagentCandidates(input, groups, existingTargets) {
     }
     return { eligible, protectedTokens, retryAfterRollouts };
 }
-function collectExecCandidates(input, groups, existingTargets) {
+function collectExecCandidates(input, groups, existingTargets, usageRatio) {
     const eligible = [];
     let protectedTokens = 0;
     let retryAfterRollouts = Infinity;
@@ -568,7 +662,10 @@ function collectExecCandidates(input, groups, existingTargets) {
             invocation.group.result.message,
             ...invocation.group.aliases.map((alias) => alias.message)
         ]));
-        if (visibleTokens < LARGE_EXEC_TOKENS)
+        const minimumVisibleTokens = usageRatio >= COMPACT_CREDIT_ACTIVATION_RATIO
+            ? HIGH_WATER_LARGE_TERMINAL_OUTPUT_TOKENS
+            : LARGE_TERMINAL_OUTPUT_TOKENS;
+        if (visibleTokens < minimumVisibleTokens)
             continue;
         const evidenceSequence = final.group.result.record.sequence;
         const observedRollouts = successfulRolloutsAfter(input.records, evidenceSequence, input.modelId, input.contextWindowTokens);
@@ -617,12 +714,69 @@ function collectExecCandidates(input, groups, existingTargets) {
     }
     return { eligible, protectedTokens, retryAfterRollouts };
 }
+function collectWebCandidates(input, groups, existingTargets, usageRatio) {
+    const eligible = [];
+    let protectedTokens = 0;
+    let retryAfterRollouts = Infinity;
+    const minimumVisibleTokens = usageRatio >= COMPACT_CREDIT_ACTIVATION_RATIO
+        ? HIGH_WATER_LARGE_TERMINAL_OUTPUT_TOKENS
+        : LARGE_TERMINAL_OUTPUT_TOKENS;
+    for (const group of [...groups.values()].sort((left, right) => (left.result?.record.sequence ?? Number.MAX_SAFE_INTEGER) -
+        (right.result?.record.sequence ?? Number.MAX_SAFE_INTEGER))) {
+        if (!isContextGcWebToolName(group.toolName) ||
+            !group.call ||
+            !group.result ||
+            group.failed ||
+            !group.completed ||
+            group.call.message.role !== 'tool_call' ||
+            group.result.message.role !== 'tool' ||
+            typeof group.result.message.content !== 'string' ||
+            !isRecord(group.completed.payload) ||
+            group.completed.payload.type !== 'tool.completed' ||
+            group.completed.payload.callId !== group.callId ||
+            group.completed.payload.toolName !== group.toolName ||
+            typeof group.completed.payload.truncated !== 'boolean')
+            continue;
+        const target = targetFor(group.result.record, group.result.message);
+        if (!target || existingTargets.has(contextGcTargetKey(target)))
+            continue;
+        const visibleTokens = contextGcMessageTokens(input, [group.result.message]);
+        if (visibleTokens < minimumVisibleTokens)
+            continue;
+        const evidenceSequence = group.result.record.sequence;
+        const observedRollouts = successfulRolloutsAfter(input.records, evidenceSequence, input.modelId, input.contextWindowTokens);
+        const candidate = {
+            replacements: [
+                {
+                    kind: 'WEB_OUTPUT',
+                    toolName: group.toolName,
+                    callId: group.callId,
+                    target,
+                    replacementContent: contextGcWebOutputReplacement(group.toolName, group.result.message.content, group.completed.payload.truncated),
+                    evidenceSequence
+                }
+            ],
+            observedRollouts,
+            evidenceSequence
+        };
+        if (observedRollouts >= CONTEXT_GC_POLICY.largeExecProtectionRollouts)
+            eligible.push(candidate);
+        else {
+            protectedTokens += candidateTokens(input, candidate);
+            retryAfterRollouts = Math.min(retryAfterRollouts, CONTEXT_GC_POLICY.largeExecProtectionRollouts - observedRollouts);
+        }
+    }
+    return { eligible, protectedTokens, retryAfterRollouts };
+}
 function isContextGcSubagentToolName(value) {
     return (value === 'agent_start' ||
         value === 'agent_wait' ||
         value === 'agent_message' ||
         value === 'agent_cancel');
 }
+function isContextGcWebToolName(value) {
+    return value === 'web_search' || value === 'web_fetch';
+}
 function buildToolGroups(records, messages, sources) {
     const groups = new Map();
     const group = (callId, toolName = '') => {

package/dist/runtime/context-projection.js

@@ -60,7 +60,9 @@ export function applyContextGcReplacementsToMessages(messages, messageSources, r
                 };
             else if (replacement.kind === 'TOOL_CALL_INPUT' && next.role === 'tool_call')
                 next = { ...next, arguments: structuredClone(replacement.replacementArguments) };
-            else if ((replacement.kind === 'EXEC_OUTPUT' || replacement.kind === 'SUBAGENT_OUTPUT') &&
+            else if ((replacement.kind === 'EXEC_OUTPUT' ||
+                replacement.kind === 'SUBAGENT_OUTPUT' ||
+                replacement.kind === 'WEB_OUTPUT') &&
                 next.role === 'tool')
                 next = { ...next, content: replacement.replacementContent };
         }