@myagentroam/agent 0.9.62 → 0.9.64

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

@@ -0,0 +1,665 @@
+import { createHash } from 'node:crypto';
+import { posix, win32 } from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+import { parseReadContextOutput } from '../tools/read-context.js';
+import { contextGcApplyPatchInputReplacement, contextGcExecInputReplacement, contextGcExecOutputReplacement, contextGcPatchResultFromCompletedPayload, contextGcStaleReadReplacement, normalizeContextGcExecResult } from './context-gc-replacements.js';
+import { contextGcSubagentNeedsRetainedPriorFinal, contextGcSubagentOutputReplacement, contextGcSubagentSnapshotIsSuperseded, normalizeContextGcSubagentSnapshot } from './context-gc-subagent.js';
+export const CONTEXT_GC_CHECKPOINT_VERSION = 1;
+export const CONTEXT_GC_MAX_TARGETS = 4_096;
+/** Disposable memoization for one evaluation's immutable record snapshot. */
+export class ContextGcCheckpointCache {
+    #snapshot;
+    read(records, boundarySequence = records.at(-1)?.sequence ?? 0, workspace = sessionWorkspace(records)) {
+        const cached = this.#snapshot;
+        if (cached?.records === records &&
+            cached.boundarySequence === boundarySequence &&
+            cached.workspace === workspace)
+            return cached.value;
+        const value = latestValidContextGcCheckpoint(records, boundarySequence, workspace);
+        this.#snapshot = { records, boundarySequence, workspace, value };
+        return value;
+    }
+}
+export function contextGcMinimumUsageGrowth(contextWindowTokens) {
+    return Math.max(2_000, Math.floor(contextWindowTokens * 0.05));
+}
+const PROJECTION_RECORD_TYPES = new Set([
+    'compact.completed',
+    'context.environment',
+    'execution.header',
+    'message.completed',
+    'model.context',
+    'plan.completed',
+    'turn.user'
+]);
+export function contextGcRecordSourceHash(record) {
+    return createHash('sha256').update(stableJson(record.payload)).digest('hex');
+}
+export function contextGcLogicalPathKey(path, workspace, platform) {
+    if (!path || !workspace || path.includes('\0') || workspace.includes('\0'))
+        return undefined;
+    const windows = platform === 'win32' ||
+        (platform === undefined &&
+            (/^[a-zA-Z]:[\\/]/u.test(workspace) || /^[\\/]{2}/u.test(workspace)));
+    if (windows) {
+        const root = win32.resolve(workspace.replaceAll('/', '\\'));
+        const resolved = win32.resolve(root, path.replaceAll('/', '\\'));
+        const relative = win32.relative(root, resolved);
+        if (relative === '..' || relative.startsWith(`..${win32.sep}`) || win32.isAbsolute(relative))
+            return undefined;
+        return resolved.replaceAll('\\', '/').toLowerCase();
+    }
+    const root = posix.resolve(workspace);
+    const resolved = posix.resolve(root, path);
+    const relative = posix.relative(root, resolved);
+    if (relative === '..' || relative.startsWith('../') || posix.isAbsolute(relative))
+        return undefined;
+    return resolved;
+}
+export function contextGcTargetKey(target) {
+    return `${target.sequence}:${target.recordId}:${target.role}:${target.callId ?? ''}:${target.toolName ?? ''}`;
+}
+export function contextGcReplacementKey(replacement) {
+    return contextGcTargetKey(replacement.target);
+}
+export function contextGcBaseFromRecords(records, boundarySequence = records.at(-1)?.sequence ?? 0) {
+    const compact = records.findLast((record) => record.sequence <= boundarySequence &&
+        record.type === 'compact.completed' &&
+        isNonemptyString(record.payload?.summary));
+    if (compact)
+        return { type: 'COMPACT', sequence: compact.sequence, recordId: compact.recordId };
+    const first = records.find((record) => record.sequence <= boundarySequence && record.type === 'session.created');
+    return first ? { type: 'SESSION_START', firstSequence: first.sequence } : undefined;
+}
+export function contextGcBaseSequence(base) {
+    return base.type === 'COMPACT' ? base.sequence : base.firstSequence;
+}
+export function contextGcSourceProjectionHash(records, boundarySequence, base = contextGcBaseFromRecords(records, boundarySequence)) {
+    if (!base || !isValidBoundary(boundarySequence))
+        return undefined;
+    const baseSequence = contextGcBaseSequence(base);
+    if (!sameContextGcBase(base, contextGcBaseFromRecords(records, boundarySequence)))
+        return undefined;
+    const source = records
+        .filter((record) => record.sequence >= baseSequence &&
+        record.sequence <= boundarySequence &&
+        PROJECTION_RECORD_TYPES.has(record.type))
+        .map((record) => ({
+        sequence: record.sequence,
+        recordId: record.recordId,
+        type: record.type,
+        payload: record.payload
+    }));
+    return createHash('sha256').update(stableJson(source)).digest('hex');
+}
+export function normalizeContextGcReplacements(replacements) {
+    const normalized = new Map();
+    for (const replacement of replacements) {
+        if (!isContextGcReplacement(replacement))
+            return undefined;
+        normalized.set(contextGcReplacementKey(replacement), structuredClone(replacement));
+    }
+    const values = [...normalized.values()];
+    const targets = new Set(values.flatMap((replacement) => [
+        contextGcTargetKey(replacement.target),
+        ...(replacement.kind === 'TOOL_CALL_INPUT'
+            ? replacement.providerAliasTargets.map(contextGcTargetKey)
+            : [])
+    ]));
+    if (targets.size > CONTEXT_GC_MAX_TARGETS)
+        return undefined;
+    return values.sort((left, right) => left.target.sequence - right.target.sequence ||
+        contextGcReplacementKey(left).localeCompare(contextGcReplacementKey(right)));
+}
+export function parseContextGcCheckpoint(record) {
+    if (record?.type !== 'context.gc.completed' || !isRecord(record.payload))
+        return undefined;
+    const payload = record.payload;
+    if (payload.version !== CONTEXT_GC_CHECKPOINT_VERSION ||
+        !isNonemptyString(payload.checkpointId) ||
+        !isPositiveInteger(payload.generation) ||
+        !isContextGcBase(payload.base) ||
+        !isPositiveInteger(payload.boundarySequence) ||
+        !isSha256(payload.sourceProjectionHash) ||
+        !Array.isArray(payload.replacements) ||
+        payload.replacements.length === 0 ||
+        !isContextGcTrigger(payload.trigger) ||
+        !isContextGcEconomicsPolicy(payload.economics) ||
+        !isContextGcMetrics(payload.metrics))
+        return undefined;
+    const replacements = normalizeContextGcReplacements(payload.replacements);
+    if (!replacements || replacements.length !== payload.replacements.length)
+        return undefined;
+    return {
+        version: 1,
+        checkpointId: payload.checkpointId,
+        generation: payload.generation,
+        base: structuredClone(payload.base),
+        boundarySequence: payload.boundarySequence,
+        sourceProjectionHash: payload.sourceProjectionHash,
+        replacements,
+        trigger: structuredClone(payload.trigger),
+        economics: structuredClone(payload.economics),
+        metrics: structuredClone(payload.metrics)
+    };
+}
+export function validateContextGcCheckpoint(records, record, workspace = sessionWorkspace(records)) {
+    const payload = parseContextGcCheckpoint(record);
+    if (!payload || payload.boundarySequence >= record.sequence)
+        return undefined;
+    const base = contextGcBaseFromRecords(records, payload.boundarySequence);
+    if (!sameContextGcBase(payload.base, base))
+        return undefined;
+    const baseSequence = contextGcBaseSequence(payload.base);
+    if (contextGcSourceProjectionHash(records, payload.boundarySequence, payload.base) !==
+        payload.sourceProjectionHash)
+        return undefined;
+    const recordsBySequence = new Map(records.map((item) => [item.sequence, item]));
+    if (!triggerMatchesRecords(records, recordsBySequence, payload))
+        return undefined;
+    const targets = payload.replacements.flatMap((replacement) => [
+        replacement.target,
+        ...(replacement.kind === 'TOOL_CALL_INPUT' ? replacement.providerAliasTargets : [])
+    ]);
+    if (new Set(targets.map(contextGcTargetKey)).size !== targets.length)
+        return undefined;
+    for (const target of targets) {
+        const source = recordsBySequence.get(target.sequence);
+        if (!source ||
+            source.sequence > payload.boundarySequence ||
+            !targetMatchesRecord(target, source))
+            return undefined;
+    }
+    for (const replacement of payload.replacements) {
+        const evidence = replacement.kind === 'READ_OUTPUT_ITEMS'
+            ? replacement.evidenceSequences
+            : [
+                replacement.evidenceSequence,
+                ...(replacement.kind === 'SUBAGENT_OUTPUT' &&
+                    replacement.retainedPriorFinal !== undefined
+                    ? [replacement.retainedPriorFinal.evidenceSequence]
+                    : [])
+            ];
+        if (evidence.some((sequence) => !isPositiveInteger(sequence) ||
+            sequence < baseSequence ||
+            sequence > payload.boundarySequence ||
+            !recordsBySequence.has(sequence)))
+            return undefined;
+        if (!replacementMatchesRecords(replacement, records, recordsBySequence, workspace, payload.trigger.platform))
+            return undefined;
+    }
+    return payload;
+}
+export function latestValidContextGcCheckpoint(records, boundarySequence = records.at(-1)?.sequence ?? 0, workspace = sessionWorkspace(records)) {
+    const base = contextGcBaseFromRecords(records, boundarySequence);
+    if (!base)
+        return undefined;
+    const candidates = records
+        .filter((record) => record.sequence <= boundarySequence &&
+        record.sequence >= contextGcBaseSequence(base) &&
+        record.type === 'context.gc.completed')
+        .toReversed();
+    for (const record of candidates) {
+        const payload = validateContextGcCheckpoint(records, record, workspace);
+        if (payload && sameContextGcBase(payload.base, base))
+            return { record, payload };
+    }
+    return undefined;
+}
+export function sameContextGcBase(left, right) {
+    if (!left || !right || left.type !== right.type)
+        return false;
+    return left.type === 'SESSION_START'
+        ? left.firstSequence ===
+            right.firstSequence
+        : left.sequence === right.sequence &&
+            left.recordId === right.recordId;
+}
+function targetMatchesRecord(target, record) {
+    if (record.type !== 'model.context' ||
+        record.recordId !== target.recordId ||
+        contextGcRecordSourceHash(record) !== target.sourceHash ||
+        !isRecord(record.payload) ||
+        record.payload.role !== target.role)
+        return false;
+    const messageCallId = modelContextCallId(record.payload);
+    const messageToolName = modelContextToolName(record.payload);
+    return ((target.callId === undefined || target.callId === messageCallId) &&
+        (target.toolName === undefined || target.toolName === messageToolName));
+}
+function replacementMatchesRecords(replacement, records, recordsBySequence, workspace, platform) {
+    const source = recordsBySequence.get(replacement.target.sequence);
+    if (!source || !isRecord(source.payload))
+        return false;
+    if (replacement.kind === 'READ_OUTPUT_ITEMS') {
+        if (!workspace || toolNameForCallId(records, replacement.callId, source.sequence) !== 'read')
+            return false;
+        const parsed = typeof source.payload.content === 'string'
+            ? parseReadContextOutput(source.payload.content)
+            : undefined;
+        if (!parsed)
+            return false;
+        const originalItems = new Map(parsed.items.map((item) => [item.index, item]));
+        return replacement.items.every((item) => {
+            const original = originalItems.get(item.index);
+            const evidence = successfulPatchEvidenceForPath(records, recordsBySequence, item.evidenceSequence, item.path, workspace, platform);
+            return (original?.path === item.path &&
+                evidence !== undefined &&
+                item.replacement ===
+                    contextGcStaleReadReplacement({
+                        path: item.path,
+                        content: original.content,
+                        evidenceSequence: item.evidenceSequence,
+                        supersededByCallId: evidence.callId,
+                        operation: evidence.file.operation
+                    }));
+        });
+    }
+    if (replacement.kind === 'TOOL_CALL_INPUT' && replacement.toolName === 'apply_patch') {
+        const evidence = successfulToolEvidence(records, recordsBySequence, replacement.evidenceSequence, 'apply_patch');
+        const result = contextGcPatchResultFromCompletedPayload(evidence?.completed.payload);
+        return (evidence?.callId === replacement.callId &&
+            evidence.call.sequence === replacement.target.sequence &&
+            result !== undefined &&
+            isDeepStrictEqual(replacement.replacementArguments, contextGcApplyPatchInputReplacement(source.payload.arguments, result, replacement.evidenceSequence)));
+    }
+    if (replacement.kind === 'SUBAGENT_OUTPUT') {
+        const retainedPriorFinal = replacement.retainedPriorFinal;
+        const sourceEvidence = successfulToolEvidence(records, recordsBySequence, source.sequence, replacement.toolName);
+        const terminalEvidence = successfulToolEvidence(records, recordsBySequence, replacement.evidenceSequence, replacement.terminalToolName);
+        if (!sourceEvidence ||
+            sourceEvidence.callId !== replacement.callId ||
+            !terminalEvidence ||
+            terminalEvidence.callId !== replacement.terminalCallId ||
+            !isRecord(terminalEvidence.result.payload) ||
+            !isRecord(sourceEvidence.result.payload))
+            return false;
+        let retainedPriorFinalEvidence;
+        let retainedPriorFinalSnapshot;
+        if (retainedPriorFinal !== undefined) {
+            retainedPriorFinalEvidence = successfulToolEvidence(records, recordsBySequence, retainedPriorFinal.evidenceSequence, retainedPriorFinal.toolName);
+            if (!retainedPriorFinalEvidence ||
+                retainedPriorFinalEvidence.callId !== retainedPriorFinal.callId ||
+                !isRecord(retainedPriorFinalEvidence.result.payload))
+                return false;
+            retainedPriorFinalSnapshot = normalizeContextGcSubagentSnapshot(retainedPriorFinalEvidence.result.payload.content, retainedPriorFinalEvidence.completed.payload, retainedPriorFinal.toolName);
+        }
+        const sourceSnapshot = normalizeContextGcSubagentSnapshot(sourceEvidence.result.payload.content, sourceEvidence.completed.payload, replacement.toolName);
+        const terminalSnapshot = normalizeContextGcSubagentSnapshot(terminalEvidence.result.payload.content, terminalEvidence.completed.payload, replacement.terminalToolName);
+        return (sourceSnapshot !== undefined &&
+            terminalSnapshot !== undefined &&
+            contextGcSubagentNeedsRetainedPriorFinal(sourceSnapshot) ===
+                (retainedPriorFinal !== undefined) &&
+            (retainedPriorFinalEvidence === undefined ||
+                retainedPriorFinalEvidence.result.sequence < sourceEvidence.result.sequence) &&
+            sourceEvidence.result.sequence < terminalEvidence.result.sequence &&
+            contextGcSubagentSnapshotIsSuperseded(sourceSnapshot, terminalSnapshot, retainedPriorFinalSnapshot) &&
+            replacement.replacementContent ===
+                contextGcSubagentOutputReplacement({
+                    sourceContent: sourceEvidence.result.payload.content,
+                    source: sourceSnapshot,
+                    terminal: terminalSnapshot,
+                    terminalCallId: replacement.terminalCallId,
+                    evidenceSequence: replacement.evidenceSequence
+                }));
+    }
+    if (!isSuccessfulExecLifecycleEvidence(replacement, source, records, recordsBySequence))
+        return false;
+    if (replacement.kind === 'TOOL_CALL_INPUT')
+        return isDeepStrictEqual(replacement.replacementArguments, contextGcExecInputReplacement(source.payload.arguments));
+    const targetEvidence = successfulToolEvidence(records, recordsBySequence, source.sequence, 'exec');
+    const result = normalizeContextGcExecResult(source.payload.content, targetEvidence?.completed.payload);
+    return (result !== undefined &&
+        replacement.replacementContent === contextGcExecOutputReplacement(result));
+}
+function toolNameForCallId(records, callId, beforeSequence) {
+    const call = modelToolCallForCallId(records, callId, beforeSequence);
+    return call && isRecord(call.payload) && typeof call.payload.name === 'string'
+        ? call.payload.name
+        : undefined;
+}
+function successfulToolEvidence(records, recordsBySequence, evidenceSequence, toolName) {
+    const result = recordsBySequence.get(evidenceSequence);
+    if (result?.type !== 'model.context' ||
+        !isRecord(result.payload) ||
+        result.payload.role !== 'tool' ||
+        typeof result.payload.callId !== 'string')
+        return undefined;
+    const callId = result.payload.callId;
+    const call = modelToolCallForCallId(records, callId, result.sequence);
+    if (!call || !isRecord(call.payload) || call.payload.name !== toolName)
+        return undefined;
+    const completed = records.findLast((record) => record.sequence > call.sequence &&
+        record.sequence < result.sequence &&
+        record.type === 'tool.completed' &&
+        isRecord(record.payload) &&
+        record.payload.type === 'tool.completed' &&
+        record.payload.callId === callId &&
+        record.payload.toolName === toolName);
+    return completed ? { callId, call, completed, result } : undefined;
+}
+function modelToolCallForCallId(records, callId, beforeSequence) {
+    return records.findLast((record) => record.sequence < beforeSequence &&
+        record.type === 'model.context' &&
+        isRecord(record.payload) &&
+        record.payload.role === 'tool_call' &&
+        record.payload.callId === callId);
+}
+function modelToolResultForCall(records, call, beforeSequence) {
+    if (!isRecord(call.payload) || typeof call.payload.callId !== 'string')
+        return undefined;
+    const callId = call.payload.callId;
+    return records.find((record) => record.sequence > call.sequence &&
+        record.sequence <= beforeSequence &&
+        record.type === 'model.context' &&
+        isRecord(record.payload) &&
+        record.payload.role === 'tool' &&
+        record.payload.callId === callId);
+}
+function successfulPatchEvidenceForPath(records, recordsBySequence, evidenceSequence, path, workspace, platform) {
+    const evidence = successfulToolEvidence(records, recordsBySequence, evidenceSequence, 'apply_patch');
+    if (!evidence || !isRecord(evidence.completed.payload))
+        return undefined;
+    const result = contextGcPatchResultFromCompletedPayload(evidence.completed.payload);
+    if (!result)
+        return undefined;
+    const expected = contextGcLogicalPathKey(path, workspace, platform);
+    if (!expected)
+        return undefined;
+    const file = result.files.find((file) => file.operation !== 'added' &&
+        contextGcLogicalPathKey(file.path, workspace, platform) === expected);
+    return file && file.operation !== 'added'
+        ? { callId: evidence.callId, file: { operation: file.operation } }
+        : undefined;
+}
+function isSuccessfulExecLifecycleEvidence(replacement, source, records, recordsBySequence) {
+    const evidence = successfulToolEvidence(records, recordsBySequence, replacement.evidenceSequence, 'exec');
+    if (!evidence || !isRecord(evidence.call.payload) || !isRecord(evidence.result.payload))
+        return false;
+    const finalResult = normalizeContextGcExecResult(evidence.result.payload.content, evidence.completed.payload);
+    if (!finalResult || finalResult.status === 'running')
+        return false;
+    const targetCall = replacement.kind === 'TOOL_CALL_INPUT'
+        ? source
+        : modelToolCallForCallId(records, replacement.callId, source.sequence);
+    if (!targetCall ||
+        targetCall.sequence > evidence.call.sequence ||
+        !isRecord(targetCall.payload) ||
+        targetCall.payload.role !== 'tool_call' ||
+        targetCall.payload.name !== 'exec' ||
+        targetCall.payload.callId !== replacement.callId)
+        return false;
+    const targetResult = replacement.kind === 'EXEC_OUTPUT'
+        ? source
+        : modelToolResultForCall(records, targetCall, evidence.result.sequence);
+    if (!targetResult)
+        return false;
+    const targetEvidence = successfulToolEvidence(records, recordsBySequence, targetResult.sequence, 'exec');
+    if (!targetEvidence || targetEvidence.call.sequence !== targetCall.sequence)
+        return false;
+    if (targetEvidence.callId === evidence.callId)
+        return targetEvidence.call.sequence === evidence.call.sequence;
+    const evidenceInput = evidence.call.payload.arguments;
+    const targetInput = targetCall.payload.arguments;
+    if (!isRecord(evidenceInput) || !isRecord(targetInput))
+        return false;
+    const evidenceProcessId = evidenceInput.processId;
+    const targetOutput = isRecord(targetResult.payload) && targetEvidence
+        ? normalizeContextGcExecResult(targetResult.payload.content, targetEvidence.completed.payload)
+        : undefined;
+    const targetProcessId = typeof targetInput.processId === 'string'
+        ? targetInput.processId
+        : typeof targetOutput?.processId === 'string'
+            ? targetOutput.processId
+            : undefined;
+    return (typeof evidenceProcessId === 'string' &&
+        targetProcessId === evidenceProcessId &&
+        targetResult.sequence <= evidence.result.sequence);
+}
+function triggerMatchesRecords(records, recordsBySequence, payload) {
+    if (payload.trigger.usageSequence < contextGcBaseSequence(payload.base) ||
+        payload.trigger.usageSequence > payload.boundarySequence)
+        return false;
+    const usageRecord = recordsBySequence.get(payload.trigger.usageSequence);
+    if (!usageRecord ||
+        !isRecord(usageRecord.payload) ||
+        usageRecord.payload.type !== 'usage.updated' ||
+        modelContextUsage(usageRecord.payload) !== payload.trigger.contextInputTokens)
+        return false;
+    const baseSequence = contextGcBaseSequence(payload.base);
+    let modelId;
+    let contextWindowTokens;
+    let triggerConfigurationMatches = false;
+    let latestMatchingUsageSequence;
+    let normalRolloutOrdinal = 0;
+    for (const record of records) {
+        if (record.sequence < baseSequence)
+            continue;
+        if (record.sequence > payload.boundarySequence)
+            break;
+        if ((record.type === 'execution.header' || record.type === 'compact.completed') &&
+            isRecord(record.payload)) {
+            if (typeof record.payload.modelId === 'string')
+                modelId = record.payload.modelId;
+            if (isPositiveInteger(record.payload.contextWindowTokens))
+                contextWindowTokens = record.payload.contextWindowTokens;
+        }
+        const matchingConfiguration = modelId === payload.trigger.modelId &&
+            contextWindowTokens === payload.trigger.contextWindowTokens;
+        if (record.sequence === usageRecord.sequence)
+            triggerConfigurationMatches = matchingConfiguration;
+        if (matchingConfiguration &&
+            isRecord(record.payload) &&
+            record.payload.type === 'usage.updated' &&
+            modelContextUsage(record.payload) !== undefined)
+            latestMatchingUsageSequence = record.sequence;
+        if (matchingConfiguration &&
+            record.type === 'model.attempt' &&
+            isRecord(record.payload) &&
+            record.payload.purpose === 'EXECUTION' &&
+            record.payload.state === 'SUCCEEDED')
+            normalRolloutOrdinal++;
+    }
+    return (triggerConfigurationMatches &&
+        latestMatchingUsageSequence === payload.trigger.usageSequence &&
+        normalRolloutOrdinal === payload.trigger.normalRolloutOrdinal);
+}
+function modelContextUsage(value) {
+    const context = value.contextInputTokens ?? value.inputTokens;
+    return isNonnegativeInteger(context) ? context : undefined;
+}
+function sessionWorkspace(records) {
+    const created = records.find((record) => record.type === 'session.created' && isRecord(record.payload));
+    return created && isRecord(created.payload) && isNonemptyString(created.payload.workspace)
+        ? created.payload.workspace
+        : undefined;
+}
+function modelContextCallId(payload) {
+    if (typeof payload.callId === 'string')
+        return payload.callId;
+    if (payload.role !== 'provider' || !isRecord(payload.item))
+        return undefined;
+    const value = payload.item.call_id;
+    return typeof value === 'string' ? value : undefined;
+}
+function modelContextToolName(payload) {
+    if (payload.role === 'tool_call' && typeof payload.name === 'string')
+        return payload.name;
+    if (payload.role !== 'provider' || !isRecord(payload.item))
+        return undefined;
+    const value = payload.item.name;
+    return typeof value === 'string' ? value : undefined;
+}
+function isContextGcReplacement(value) {
+    if (!isRecord(value) ||
+        !isContextGcTarget(value.target) ||
+        !isNonemptyString(value.callId) ||
+        value.target.callId !== value.callId)
+        return false;
+    if (value.kind === 'READ_OUTPUT_ITEMS') {
+        const items = value.items;
+        const evidenceSequences = value.evidenceSequences;
+        return (value.target.role === 'tool' &&
+            Array.isArray(items) &&
+            items.length > 0 &&
+            items.every((item) => isRecord(item) &&
+                isNonnegativeInteger(item.index) &&
+                isNonemptyString(item.path) &&
+                isNonemptyString(item.replacement) &&
+                isPositiveInteger(item.evidenceSequence)) &&
+            Array.isArray(evidenceSequences) &&
+            evidenceSequences.length > 0 &&
+            evidenceSequences.every(isPositiveInteger) &&
+            new Set(items.map((item) => item.index)).size === items.length &&
+            new Set(evidenceSequences).size === evidenceSequences.length &&
+            items.every((item) => evidenceSequences.includes(item.evidenceSequence)) &&
+            evidenceSequences.every((sequence) => items.some((item) => item.evidenceSequence === sequence)));
+    }
+    if (value.kind === 'TOOL_CALL_INPUT')
+        return (value.target.role === 'tool_call' &&
+            (value.toolName === 'apply_patch' || value.toolName === 'exec') &&
+            value.target.toolName === value.toolName &&
+            Array.isArray(value.providerAliasTargets) &&
+            value.providerAliasTargets.every((target) => isContextGcTarget(target) &&
+                target.role === 'provider' &&
+                target.callId === value.callId &&
+                target.toolName === value.toolName) &&
+            isPositiveInteger(value.evidenceSequence) &&
+            value.replacementArguments !== undefined);
+    if (value.kind === 'SUBAGENT_OUTPUT')
+        return (value.target.role === 'tool' &&
+            (value.toolName === 'agent_wait' || value.toolName === 'agent_message') &&
+            (value.target.toolName === undefined || value.target.toolName === value.toolName) &&
+            isNonemptyString(value.replacementContent) &&
+            (value.terminalToolName === 'agent_start' ||
+                value.terminalToolName === 'agent_wait' ||
+                value.terminalToolName === 'agent_message' ||
+                value.terminalToolName === 'agent_cancel') &&
+            isNonemptyString(value.terminalCallId) &&
+            isPositiveInteger(value.evidenceSequence) &&
+            (value.retainedPriorFinal === undefined ||
+                (isRecord(value.retainedPriorFinal) &&
+                    Object.keys(value.retainedPriorFinal).every((key) => ['toolName', 'callId', 'evidenceSequence'].includes(key)) &&
+                    (value.retainedPriorFinal.toolName === 'agent_start' ||
+                        value.retainedPriorFinal.toolName === 'agent_wait' ||
+                        value.retainedPriorFinal.toolName === 'agent_message' ||
+                        value.retainedPriorFinal.toolName === 'agent_cancel') &&
+                    isNonemptyString(value.retainedPriorFinal.callId) &&
+                    isPositiveInteger(value.retainedPriorFinal.evidenceSequence))));
+    return (value.kind === 'EXEC_OUTPUT' &&
+        value.target.role === 'tool' &&
+        isNonemptyString(value.replacementContent) &&
+        isPositiveInteger(value.evidenceSequence));
+}
+function isContextGcTarget(value) {
+    return (isRecord(value) &&
+        isPositiveInteger(value.sequence) &&
+        isNonemptyString(value.recordId) &&
+        (value.role === 'tool_call' || value.role === 'tool' || value.role === 'provider') &&
+        (value.callId === undefined || isNonemptyString(value.callId)) &&
+        (value.toolName === undefined || isNonemptyString(value.toolName)) &&
+        isSha256(value.sourceHash));
+}
+function isContextGcBase(value) {
+    return (isRecord(value) &&
+        ((value.type === 'SESSION_START' && isPositiveInteger(value.firstSequence)) ||
+            (value.type === 'COMPACT' &&
+                isPositiveInteger(value.sequence) &&
+                isNonemptyString(value.recordId))));
+}
+function isContextGcTrigger(value) {
+    return (isRecord(value) &&
+        isPositiveInteger(value.usageSequence) &&
+        isNonnegativeInteger(value.contextInputTokens) &&
+        isPositiveInteger(value.contextWindowTokens) &&
+        isNonnegativeInteger(value.normalRolloutOrdinal) &&
+        isNonemptyString(value.modelId) &&
+        (value.platform === 'linux' || value.platform === 'darwin' || value.platform === 'win32'));
+}
+function isContextGcEconomicsPolicy(value) {
+    return (isRecord(value) &&
+        value.version === 1 &&
+        [
+            'immediatePaybackRollouts',
+            'maximumPaybackRollouts',
+            'contextGrowthSampleWindow',
+            'minimumContextGrowthSamples',
+            'minimumObservationRollouts',
+            'stageAProtectionRollouts',
+            'largeExecProtectionRollouts'
+        ].every((key) => isNonnegativeInteger(value[key])) &&
+        [
+            'normalInputCostRate',
+            'cacheReadCostRate',
+            'cacheWriteCostRate',
+            'outputCostRate',
+            'minimumGrossReductionRate',
+            'minimumCacheInvestmentRoi'
+        ].every((key) => isNonnegativeFinite(value[key])));
+}
+function isContextGcMetrics(value) {
+    if (!isRecord(value) || (value.stage !== 'STAGE_A' && value.stage !== 'STAGE_A_AND_EXEC'))
+        return false;
+    const nonnegative = [
+        'beforeTokens',
+        'afterTokens',
+        'reclaimedTokens',
+        'grossReductionRate',
+        'cacheRebuildPenaltyCostUnits',
+        'compactDeferralCreditCostUnits',
+        'requiredPositiveNetRollouts',
+        'requiredTargetRoiRollouts',
+        'projectedRolloutsUntilCompactAfterGc',
+        'contextGrowthSampleCount',
+        'contextGrowthP75Tokens',
+        'minimumObservedRollouts',
+        'protectedCandidateTokens',
+        'eligibleCandidateCount',
+        'eligibleTargetCount'
+    ];
+    const optionalNonnegative = [
+        'effectiveMinimumGrossReductionRate',
+        'minimumRequiredReclaimedTokens',
+        'imminentCompactAvoidanceCreditCostUnits',
+        'appliedCompactCreditCostUnits',
+        'projectedTokensBeforeGc',
+        'projectedTokensAfterGc'
+    ];
+    return (nonnegative.every((key) => isNonnegativeFinite(value[key])) &&
+        optionalNonnegative.every((key) => value[key] === undefined || isNonnegativeFinite(value[key])) &&
+        Number.isFinite(value.expectedNetSavedCostUnits) &&
+        Number.isFinite(value.cacheInvestmentRoi) &&
+        (value.tokenEstimator === undefined || value.tokenEstimator === 'UTF8_BYTES_V1') &&
+        (value.cachePenaltyKnown === undefined || typeof value.cachePenaltyKnown === 'boolean'));
+}
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function isNonemptyString(value) {
+    return typeof value === 'string' && value.length > 0;
+}
+function isSha256(value) {
+    return typeof value === 'string' && /^[a-f0-9]{64}$/u.test(value);
+}
+function isPositiveInteger(value) {
+    return Number.isSafeInteger(value) && Number(value) > 0;
+}
+function isNonnegativeInteger(value) {
+    return Number.isSafeInteger(value) && Number(value) >= 0;
+}
+function isNonnegativeFinite(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0;
+}
+function isValidBoundary(value) {
+    return Number.isSafeInteger(value) && value > 0;
+}
+function stableJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(stableJson).join(',')}]`;
+    if (value !== null && typeof value === 'object')
+        return `{${Object.entries(value)
+            .sort(([left], [right]) => left.localeCompare(right))
+            .map(([key, entry]) => `${JSON.stringify(key)}:${stableJson(entry)}`)
+            .join(',')}}`;
+    return JSON.stringify(value) ?? 'undefined';
+}