@myagentroam/agent 0.9.62 → 0.9.64

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

@@ -0,0 +1,35 @@
+import type { ClientToolDefinition, ModelUsage } from '../model/contracts.js';
+import { type ContextGcPlatform } from '../session/context-gc-checkpoint.js';
+import { JsonlSessionStore, type SessionRecord } from '../session/jsonl-store.js';
+import { type ContextProjection } from './context-projection.js';
+export interface ContextGcRuntimeInput {
+    readonly store: JsonlSessionStore;
+    readonly sessionId: string;
+    readonly records?: readonly SessionRecord[];
+    readonly system: string;
+    readonly tools: readonly ClientToolDefinition[];
+    readonly modelId: string;
+    readonly modelProtocol?: string;
+    readonly contextWindowTokens: number;
+    readonly usage: ModelUsage;
+    readonly workspace: string;
+    readonly platform: ContextGcPlatform;
+    readonly activeProcessIds?: ReadonlySet<string>;
+    readonly getActiveProcessIds?: () => Promise<ReadonlySet<string>>;
+}
+export interface ContextGcCommitResult {
+    readonly records: readonly SessionRecord[];
+    readonly projection: ContextProjection;
+}
+/** Only scheduling metadata survives a call; records and validation caches do not. */
+export declare class ContextGcRuntime {
+    #private;
+    reset(): void;
+    run(input: ContextGcRuntimeInput): Promise<ContextGcCommitResult | false>;
+}
+/**
+ * Runs the deterministic planner and commits its checkpoint. Planning and
+ * commit failures are opportunistic no-ops unless the checkpoint is confirmed
+ * durable after an ambiguous append result.
+ */
+export declare function tryCommitContextGc(input: ContextGcRuntimeInput): Promise<ContextGcCommitResult | false>;

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

@@ -0,0 +1,163 @@
+import { isDeepStrictEqual } from 'node:util';
+import { ContextGcCheckpointCache, contextGcMinimumUsageGrowth, contextGcReplacementKey, contextGcSourceProjectionHash } from '../session/context-gc-checkpoint.js';
+import { 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;
+    #failures = 0;
+    #remaining = 0;
+    reset() {
+        this.#scope = '';
+        this.#lastUsage = undefined;
+        this.#checkpoint = undefined;
+        this.#failures = 0;
+        this.#remaining = 0;
+    }
+    async run(input) {
+        const scope = JSON.stringify([
+            input.sessionId,
+            input.modelId,
+            input.modelProtocol,
+            input.contextWindowTokens
+        ]);
+        if (scope !== this.#scope) {
+            this.reset();
+            this.#scope = scope;
+        }
+        const usage = contextGcEligibleUsage(input.usage, input.contextWindowTokens);
+        if (usage === undefined) {
+            this.#lastUsage = undefined;
+            this.#failures = 0;
+            this.#remaining = 0;
+            return false;
+        }
+        if (this.#lastUsage !== undefined && usage < this.#lastUsage) {
+            this.#failures = 0;
+            this.#remaining = 0;
+        }
+        this.#lastUsage = usage;
+        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 <
+                contextGcMinimumUsageGrowth(input.contextWindowTokens))
+            return false;
+        const attempt = await attemptContextGc(input);
+        if (attempt.result) {
+            this.#checkpoint = { ...attempt.result.projection.checkpoint.trigger };
+            this.#failures = 0;
+            this.#remaining = 1;
+        }
+        else {
+            if (attempt.checkpointTrigger)
+                this.#checkpoint = { ...attempt.checkpointTrigger };
+            this.#failures = Math.min(3, this.#failures + 1);
+            this.#remaining =
+                Math.min(2 ** this.#failures, maximumInterval, attempt.retryAfterRollouts ?? Infinity) - 1;
+        }
+        return attempt.result;
+    }
+}
+/**
+ * Runs the deterministic planner and commits its checkpoint. Planning and
+ * commit failures are opportunistic no-ops unless the checkpoint is confirmed
+ * durable after an ambiguous append result.
+ */
+export async function tryCommitContextGc(input) {
+    return (await attemptContextGc(input)).result;
+}
+async function attemptContextGc(input) {
+    const contextUsage = contextGcEligibleUsage(input.usage, input.contextWindowTokens);
+    if (contextUsage === undefined)
+        return { result: false };
+    let deferred = { result: false };
+    let draft;
+    try {
+        const records = input.records ?? (await input.store.readExecutionState(input.sessionId)).contextRecords;
+        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))
+                return deferred;
+        }
+        const projection = buildContextProjection(records, input.workspace, checkpointCache);
+        const inspection = inspectContextGc({
+            records,
+            checkpointCache,
+            messages: projection.entries.map((entry) => entry.message),
+            messageSources: projection.entries.map((entry) => entry.record),
+            system: input.system,
+            tools: input.tools,
+            modelId: input.modelId,
+            ...(input.modelProtocol === undefined ? {} : { modelProtocol: input.modelProtocol }),
+            contextWindowTokens: input.contextWindowTokens,
+            usage: input.usage,
+            workspace: input.workspace,
+            platform: input.platform,
+            activeProcessIds: input.activeProcessIds ?? (await input.getActiveProcessIds?.()) ?? new Set()
+        });
+        if (inspection.retryAfterRollouts !== undefined)
+            deferred = { ...deferred, retryAfterRollouts: inspection.retryAfterRollouts };
+        const plan = inspection.plan;
+        if (!plan)
+            return deferred;
+        const hash = contextGcSourceProjectionHash(records, plan.draft.boundarySequence, plan.draft.base);
+        if (!hash)
+            return deferred;
+        plan.draft.sourceProjectionHash = hash;
+        draft = plan.draft;
+    }
+    catch {
+        return deferred;
+    }
+    try {
+        await input.store.commitContextGc(input.sessionId, draft);
+        return {
+            ...deferred,
+            result: await matchingCheckpointWasPersisted(input.store, input.sessionId, draft, input.workspace)
+        };
+    }
+    catch (commitError) {
+        try {
+            return {
+                ...deferred,
+                result: await matchingCheckpointWasPersisted(input.store, input.sessionId, draft, input.workspace)
+            };
+        }
+        catch { }
+        void commitError;
+        return deferred;
+    }
+}
+async function matchingCheckpointWasPersisted(store, sessionId, draft, workspace) {
+    const state = await store.readExecutionState(sessionId);
+    const projection = buildContextProjection(state.contextRecords, workspace);
+    const payload = projection.checkpoint;
+    const latest = payload ? { payload } : undefined;
+    if (latest?.payload.boundarySequence !== draft.boundarySequence ||
+        latest.payload.sourceProjectionHash !== draft.sourceProjectionHash ||
+        !isDeepStrictEqual(latest.payload.base, draft.base) ||
+        !isDeepStrictEqual(latest.payload.trigger, draft.trigger) ||
+        !isDeepStrictEqual(latest.payload.economics, draft.economics) ||
+        !isDeepStrictEqual(latest.payload.metrics, draft.metrics))
+        return false;
+    const persisted = new Map(latest.payload.replacements.map((replacement) => [
+        contextGcReplacementKey(replacement),
+        replacement
+    ]));
+    const matches = draft.replacements.every((replacement) => {
+        const value = persisted.get(contextGcReplacementKey(replacement));
+        return value !== undefined && isDeepStrictEqual(value, replacement);
+    });
+    return matches ? { records: state.contextRecords, projection } : false;
+}

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

@@ -0,0 +1,24 @@
+import type { ClientToolDefinition, ModelMessage } from '../model/contracts.js';
+export { MODEL_TOKEN_ESTIMATOR as CONTEXT_GC_TOKEN_ESTIMATOR } from './token-budget.js';
+interface TokenContext {
+    readonly modelId: string;
+    readonly modelProtocol?: string;
+    readonly system: string;
+    readonly tools: readonly ClientToolDefinition[];
+    readonly messages?: readonly ModelMessage[];
+    readonly tokenCache?: Map<string, number>;
+}
+/** Uses Responses lowering, including native alias and cross-model filtering. */
+export declare function contextGcTokenEntries(input: TokenContext, messages: readonly ModelMessage[]): {
+    tokens: number;
+    key: string;
+    text: string;
+}[];
+/** Cancel identical entries, including multiplicity, before estimating the difference. */
+export declare function contextGcReclaimedTokens(input: TokenContext, before: readonly ModelMessage[], after: readonly ModelMessage[]): number;
+export declare function contextGcPrefixTokens(input: TokenContext): number;
+export declare function contextGcMessageTokens(input: TokenContext, messages: readonly ModelMessage[]): number;
+export declare function contextGcCacheImpact(input: TokenContext, before: readonly ModelMessage[], after: readonly ModelMessage[], cacheRead: number, reclaimedTokens: number): {
+    preservedCachedPrefixTokens: number;
+    reclaimedCachedTokens: number;
+};

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

@@ -0,0 +1,83 @@
+import { openAiInput } from '../model/openai-responses.js';
+import { countModelTokens } from './token-budget.js';
+export { MODEL_TOKEN_ESTIMATOR as CONTEXT_GC_TOKEN_ESTIMATOR } from './token-budget.js';
+/** Uses Responses lowering, including native alias and cross-model filtering. */
+export function contextGcTokenEntries(input, messages) {
+    return serializedEntries(input, messages).map((entry) => ({
+        ...entry,
+        tokens: tokensFor(input, entry.text)
+    }));
+}
+function serializedEntries(input, messages) {
+    const responses = input.modelProtocol === 'OPENAI_RESPONSES' ||
+        (input.modelProtocol === undefined &&
+            (input.messages ?? messages).some((message) => message.provider === 'OPENAI_RESPONSES'));
+    const values = responses
+        ? openAiInput(messages, undefined, input.modelId, true)
+        : messages.filter((message) => message.role !== 'provider' ||
+            (message.provider === 'ANTHROPIC_MESSAGES' && message.providerModelId === input.modelId));
+    return values.map((value, index) => {
+        const item = value;
+        const callId = item.call_id ?? item.callId;
+        const output = item.role === 'tool' ||
+            item.type === 'function_call_output' ||
+            item.type === 'custom_tool_call_output';
+        const key = typeof callId === 'string'
+            ? `${output ? 'output' : 'input'}:${callId}`
+            : typeof item.id === 'string'
+                ? `id:${item.id}`
+                : `index:${index}`;
+        const text = stableJson(value);
+        return { key, text };
+    });
+}
+/** Cancel identical entries, including multiplicity, before estimating the difference. */
+export function contextGcReclaimedTokens(input, before, after) {
+    const counts = new Map();
+    for (const entry of serializedEntries(input, before))
+        counts.set(entry.text, (counts.get(entry.text) ?? 0) + 1);
+    for (const entry of serializedEntries(input, after))
+        counts.set(entry.text, (counts.get(entry.text) ?? 0) - 1);
+    let reclaimed = 0;
+    for (const [text, count] of counts)
+        if (count !== 0)
+            reclaimed += count * tokensFor(input, text);
+    return Math.max(0, reclaimed);
+}
+export function contextGcPrefixTokens(input) {
+    return tokensFor(input, stableJson({ system: input.system, tools: input.tools }));
+}
+export function contextGcMessageTokens(input, messages) {
+    return contextGcTokenEntries(input, messages).reduce((sum, entry) => sum + entry.tokens, 0);
+}
+export function contextGcCacheImpact(input, before, after, cacheRead, reclaimedTokens) {
+    const afterByKey = new Map(contextGcTokenEntries(input, after).map((entry) => [entry.key, entry]));
+    let offset = contextGcPrefixTokens(input);
+    let earliest = cacheRead;
+    let reclaimedCachedTokens = 0;
+    for (const entry of contextGcTokenEntries(input, before)) {
+        const replacement = afterByKey.get(entry.key);
+        if (entry.text !== replacement?.text) {
+            earliest = Math.min(earliest, offset);
+            reclaimedCachedTokens += Math.min(Math.max(0, entry.tokens - (replacement?.tokens ?? 0)), Math.max(0, cacheRead - offset));
+        }
+        offset += entry.tokens;
+    }
+    return {
+        preservedCachedPrefixTokens: Math.max(0, Math.min(cacheRead, earliest)),
+        reclaimedCachedTokens: Math.min(reclaimedTokens, reclaimedCachedTokens)
+    };
+}
+function tokensFor(input, text) {
+    const cached = input.tokenCache?.get(text);
+    if (cached !== undefined)
+        return cached;
+    const tokens = countModelTokens(text);
+    input.tokenCache?.set(text, tokens);
+    return tokens;
+}
+function stableJson(value) {
+    return JSON.stringify(value, (_key, item) => item && typeof item === 'object' && !Array.isArray(item)
+        ? Object.fromEntries(Object.entries(item).sort(([a], [b]) => a.localeCompare(b)))
+        : item);
+}

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

@@ -0,0 +1,66 @@
+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 type { SessionRecord } from '../session/jsonl-store.js';
+export declare const CONTEXT_GC_POLICY: ContextGcEconomicsPolicy;
+interface ContextGcEconomicsInput {
+    readonly contextUsageTokens: number;
+    readonly reclaimedTokens: number;
+    readonly reclaimedCachedTokens: number;
+    readonly cacheReadTokens: number;
+    readonly preservedCachedPrefixTokens: number;
+    readonly compactDeferralCreditCostUnits: number;
+    readonly projectedRolloutsUntilCompactAfterGc: number;
+    readonly contextGrowthSampleCount: number;
+    readonly minimumGrossReductionRate?: number;
+    readonly minimumReclaimedTokens?: number;
+}
+export interface ContextGcEconomicsResult {
+    readonly cacheRebuildPenaltyCostUnits: number;
+    readonly requiredPositiveNetRollouts: number;
+    readonly requiredTargetRoiRollouts: number;
+    readonly expectedNetSavedCostUnits: number;
+    readonly cacheInvestmentRoi: number;
+    readonly grossReductionRate: number;
+    readonly passes: boolean;
+}
+export interface ContextGcPlan {
+    readonly stage: 'STAGE_A' | 'STAGE_A_AND_EXEC';
+    readonly draft: ContextGcCheckpointDraft;
+    readonly metrics: ContextGcMetrics;
+}
+export interface ContextGcInspection {
+    readonly plan?: ContextGcPlan;
+    readonly retryAfterRollouts?: number;
+}
+export interface ContextGcPlannerInput {
+    readonly records: readonly SessionRecord[];
+    readonly messages: readonly ModelMessage[];
+    readonly messageSources: readonly SessionRecord[];
+    readonly system: string;
+    readonly tools: readonly ClientToolDefinition[];
+    readonly modelId: string;
+    readonly modelProtocol?: string;
+    readonly contextWindowTokens: number;
+    readonly usage: ModelUsage;
+    readonly workspace: string;
+    readonly platform: ContextGcPlatform;
+    readonly activeProcessIds: ReadonlySet<string>;
+    readonly tokenCache?: Map<string, number>;
+    readonly checkpointCache?: ContextGcCheckpointCache;
+}
+export declare function evaluateContextGcEconomics(input: ContextGcEconomicsInput): ContextGcEconomicsResult;
+export declare function contextGcMinimumGrossReductionRate(usageRatio: number): number;
+export declare function contextGcMinimumReclaimedTokens(contextUsageTokens: number, contextWindowTokens: number): number;
+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 contextGcImminentCompactAvoidanceCredit(input: {
+    readonly contextUsageTokens: number;
+    readonly contextWindowTokens: number;
+    readonly compactThresholdTokens: number;
+    readonly projectedTokensBeforeGc: number;
+    readonly projectedTokensAfterGc: number;
+    readonly contextGrowthP75Tokens: number;
+}): number;
+export declare function contextGcAppliedCompactCreditCostUnits(compactDeferralCreditCostUnits: number, imminentCompactAvoidanceCreditCostUnits: number): number;
+export {};