@myagentroam/agent 0.11.32 → 0.11.34

package/dist/session/catalog.d.ts

@@ -0,0 +1,70 @@
+import type { AgentEvent } from '../runtime/events.js';
+import type { SessionStore } from './store/contracts.js';
+import type { SessionListInput } from './types.js';
+import type { AgentSessionRollbackInput } from './rollback.js';
+import type { AgentSessionSummary, AgentSessionPage } from './summary.js';
+export type { AgentSessionSummary, AgentSessionPage } from './summary.js';
+import type { AgentSessionHistoryImageMetadata, AgentUserHistoryEntry } from './user-history.js';
+export type { AgentSessionHistoryImageMetadata } from './user-history.js';
+export type AgentSessionHistoryEntry = AgentUserHistoryEntry | {
+    kind: 'event';
+    sequence: number;
+    event: AgentEvent;
+};
+export interface AgentSessionHistoryPage {
+    entries: AgentSessionHistoryEntry[];
+    nextCursor?: string;
+}
+export interface AgentSessionContextUsage {
+    inputTokens: number;
+}
+export interface AgentSessionDeleteResult {
+    readonly deleted: boolean;
+}
+export interface AgentSessionImage {
+    name: string;
+    mimeType: string;
+    byteSize: number;
+    dataBase64: string;
+}
+/** Public session catalog facade. Storage details remain SDK-private. */
+export interface AgentSessionCatalog {
+    list(input?: SessionListInput): Promise<AgentSessionPage>;
+    firstUserMessagePreview(sessionId: string): Promise<string | undefined>;
+    executionConfiguration(sessionId: string): Promise<{
+        readonly modelId: string;
+        readonly modelName?: string;
+        readonly reasoningEffort?: string;
+    } | undefined>;
+    history(sessionId: string, input?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<AgentSessionHistoryPage>;
+    readImage(sessionId: string, input: {
+        readonly sequence: number;
+        readonly imageIndex: number;
+    }): Promise<AgentSessionImage | undefined>;
+    readResource(sessionId: string, resourceId: string): Promise<{
+        mimeType: string;
+        dataBase64: string;
+    } | undefined>;
+    contextUsage(sessionId: string): Promise<AgentSessionContextUsage | undefined>;
+    readToolResultResource(sessionId: string, input: import('./tool-result-resources.js').ToolResultResourceInput): Promise<import('./tool-result-resources.js').ToolResultResourcePage>;
+    fork(sessionId: string, input: {
+        readonly boundaryTurnId: string | null;
+        readonly title: string;
+    }): Promise<AgentSessionSummary>;
+    rollback(sessionId: string, input: AgentSessionRollbackInput): Promise<AgentSessionSummary>;
+    clear(sessionId: string): Promise<AgentSessionSummary>;
+    delete(sessionId: string): Promise<AgentSessionDeleteResult>;
+    close(): Promise<void>;
+}
+export type OpenAgentSessionCatalogInput = {
+    homeDirectory: string;
+    sessionStore?: never;
+} | {
+    sessionStore: SessionStore;
+    homeDirectory?: never;
+};
+export declare function createSessionCatalog(store: Pick<SessionStore, 'list' | 'firstUserMessagePreview' | 'executionConfiguration' | 'readPage' | 'readInputImage' | 'readResource' | 'readToolResultResource' | 'forkSession' | 'rollbackSession' | 'clearSession' | 'delete' | 'close'>, borrowed: boolean): AgentSessionCatalog;
+export declare function imageMetadata(value: unknown): AgentSessionHistoryImageMetadata[];

package/dist/session/catalog.js

@@ -0,0 +1,194 @@
+import { AgentError } from '../error.js';
+import { publicHostedToolEvents } from '../runtime/event-projection.js';
+const MAX_INPUT_IMAGE_BYTES = 5 * 1024 * 1024;
+const INPUT_IMAGE_MIME_TYPES = new Set(['image/png', 'image/jpeg', 'image/gif', 'image/webp']);
+export function createSessionCatalog(store, borrowed) {
+    let closure;
+    const assertOpen = () => {
+        if (closure)
+            throw new AgentError('MAR_AGENT_DISPOSED', 'Session catalog is closed.');
+    };
+    return {
+        list: async (options) => {
+            assertOpen();
+            return store.list(options);
+        },
+        firstUserMessagePreview: async (sessionId) => {
+            assertOpen();
+            return store.firstUserMessagePreview(sessionId);
+        },
+        executionConfiguration: async (sessionId) => {
+            assertOpen();
+            return store.executionConfiguration(sessionId);
+        },
+        history: async (sessionId, options = {}) => {
+            assertOpen();
+            const beforeSequence = parseCursor(options.cursor);
+            const page = await store.readPage(sessionId, {
+                ...(options.limit === undefined ? {} : { limit: options.limit }),
+                ...(beforeSequence === undefined ? {} : { beforeSequence })
+            });
+            const entries = page.records.flatMap((record) => {
+                if (record.type === 'turn.user' &&
+                    record.executionId !== undefined &&
+                    record.turnId !== undefined &&
+                    isRecord(record.payload) &&
+                    typeof record.payload.prompt === 'string') {
+                    const images = imageMetadata(record.payload.images);
+                    return [
+                        {
+                            kind: 'user',
+                            ...(record.payload.deferred === true ? { recordId: record.recordId } : {}),
+                            sequence: record.sequence,
+                            timestamp: record.timestamp,
+                            sessionId: record.sessionId,
+                            executionId: record.executionId,
+                            turnId: record.turnId,
+                            text: record.payload.prompt,
+                            ...(typeof record.payload.clientMessageId === 'string'
+                                ? { clientMessageId: record.payload.clientMessageId }
+                                : {}),
+                            ...(record.payload.inputSource === 'parent_agent'
+                                ? { inputSource: 'parent_agent' }
+                                : {}),
+                            ...(images.length > 0 ? { images } : {})
+                        }
+                    ];
+                }
+                if (isAgentEvent(record.payload) && record.payload.type === 'hosted_tool.updated') {
+                    const legacy = record.payload;
+                    return publicHostedToolEvents({ ...legacy, type: 'hosted_tool' }).map((event) => ({
+                        kind: 'event',
+                        sequence: record.sequence,
+                        event: {
+                            sequence: legacy.sequence,
+                            timestamp: legacy.timestamp,
+                            sessionId: legacy.sessionId,
+                            executionId: legacy.executionId,
+                            ...(legacy.turnId === undefined ? {} : { turnId: legacy.turnId }),
+                            ...event,
+                            eventId: `${legacy.eventId}:${event.type}`
+                        }
+                    }));
+                }
+                if (isAgentEvent(record.payload)) {
+                    const event = record.payload;
+                    return [{ kind: 'event', sequence: record.sequence, event }];
+                }
+                return [];
+            });
+            return {
+                entries,
+                ...(page.previousBeforeSequence === undefined
+                    ? {}
+                    : { nextCursor: String(page.previousBeforeSequence) })
+            };
+        },
+        readImage: async (sessionId, input) => {
+            assertOpen();
+            const image = await store.readInputImage(sessionId, input);
+            return image === undefined
+                ? undefined
+                : {
+                    name: image.name,
+                    mimeType: image.mimeType,
+                    byteSize: image.byteSize,
+                    dataBase64: image.dataBase64
+                };
+        },
+        readResource: async (sessionId, resourceId) => {
+            assertOpen();
+            return store.readResource(sessionId, resourceId);
+        },
+        readToolResultResource: async (sessionId, input) => {
+            assertOpen();
+            return store.readToolResultResource(sessionId, input);
+        },
+        contextUsage: async (sessionId) => {
+            assertOpen();
+            const page = await store.readPage(sessionId, { limit: 1000 });
+            for (const record of page.records.toReversed()) {
+                if (!isAgentEvent(record.payload))
+                    continue;
+                if (record.payload.type === 'context.compacted')
+                    return record.payload.retainedContext === true ? undefined : { inputTokens: 0 };
+                if (record.payload.type === 'usage.updated' && record.payload.purpose !== 'compact') {
+                    const inputTokens = record.payload.contextInputTokens ?? record.payload.inputTokens;
+                    if (typeof inputTokens === 'number' &&
+                        Number.isSafeInteger(inputTokens) &&
+                        inputTokens >= 0)
+                        return { inputTokens };
+                }
+            }
+            return undefined;
+        },
+        fork: async (sessionId, options) => {
+            assertOpen();
+            const session = await store.forkSession(sessionId, options);
+            return { ...session, source: session.source ?? { type: 'user' } };
+        },
+        rollback: async (sessionId, options) => {
+            assertOpen();
+            return store.rollbackSession(sessionId, options);
+        },
+        clear: async (sessionId) => {
+            assertOpen();
+            return store.clearSession(sessionId);
+        },
+        delete: async (sessionId) => {
+            assertOpen();
+            return store.delete(sessionId);
+        },
+        close: () => {
+            closure ??= Promise.resolve().then(() => (borrowed ? undefined : store.close()));
+            return closure;
+        }
+    };
+}
+function parseCursor(cursor) {
+    if (cursor === undefined)
+        return undefined;
+    const value = Number(cursor);
+    if (!/^[1-9]\d*$/u.test(cursor) || !Number.isSafeInteger(value))
+        throw new AgentError('MAR_AGENT_TOOL_INPUT_INVALID', 'Session history cursor is invalid.');
+    return value;
+}
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+export function imageMetadata(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.flatMap((image) => isRecord(image) &&
+        typeof image.name === 'string' &&
+        typeof image.mimeType === 'string' &&
+        typeof image.byteSize === 'number' &&
+        Number.isSafeInteger(image.byteSize) &&
+        image.byteSize >= 0
+        ? [
+            {
+                name: image.name,
+                mimeType: image.mimeType,
+                byteSize: image.byteSize,
+                readable: INPUT_IMAGE_MIME_TYPES.has(image.mimeType) &&
+                    image.byteSize > 0 &&
+                    image.byteSize <= MAX_INPUT_IMAGE_BYTES &&
+                    image.resourceInputVersion === 1 &&
+                    typeof image.resourceId === 'string' &&
+                    /^[a-f0-9]{64}$/u.test(image.resourceId) &&
+                    typeof image.sha256 === 'string' &&
+                    /^[a-f0-9]{64}$/u.test(image.sha256)
+            }
+        ]
+        : []);
+}
+function isAgentEvent(value) {
+    return (isRecord(value) &&
+        typeof value.type === 'string' &&
+        value.type !== 'reasoning.summary' &&
+        typeof value.eventId === 'string' &&
+        typeof value.sequence === 'number' &&
+        typeof value.timestamp === 'string' &&
+        typeof value.sessionId === 'string' &&
+        typeof value.executionId === 'string');
+}

package/dist/session/code-observation-contract.d.ts

@@ -0,0 +1,40 @@
+/** Execution metadata is independent of explicit model observations. */
+export interface CodeToolCallRecord {
+    callId: string;
+    toolName: string;
+    input: unknown;
+    status: 'running' | 'completed' | 'failed';
+    resultExtensions?: readonly import('../tools/result-extension-contract.js').ToolResultExtension[];
+    result?: {
+        content: string;
+        data?: unknown;
+        truncated?: boolean;
+    };
+    error?: {
+        code: string;
+        message: string;
+    };
+}
+export type CodeObservation = {
+    type: 'tool_result';
+    id: string;
+    source: {
+        callId: string;
+        toolName: string;
+        input: unknown;
+    };
+    outcome: 'completed' | 'failed';
+    result: {
+        content: string;
+        data?: unknown;
+        truncated?: boolean;
+        imageIndices?: number[];
+    };
+} | {
+    type: 'value';
+    id: string;
+    format: 'text' | 'json' | 'image';
+    value: string;
+    truncated?: boolean;
+    imageIndices?: number[];
+};

package/dist/session/code-observation-contract.js

@@ -0,0 +1 @@
+export {};

package/dist/session/code-observation-projection.d.ts

@@ -0,0 +1,54 @@
+import type { ModelImage } from '../model/image.js';
+import type { CodeToolCallRecord, CodeObservation } from './code-observation-contract.js';
+export type { CodeToolCallRecord, CodeObservation } from './code-observation-contract.js';
+export declare function parseCodeCalls(value: unknown): CodeToolCallRecord[] | undefined;
+export declare function observationContent(value: CodeObservation): string;
+export declare function observationImages(value: CodeObservation): readonly number[];
+export declare function selectObservationImages(values: readonly CodeObservation[], images: readonly ModelImage[], offset?: number): {
+    observations: ({
+        result: {
+            imageIndices: number[];
+            content: string;
+            data?: unknown;
+            truncated?: boolean;
+        };
+        type: "tool_result";
+        id: string;
+        source: {
+            callId: string;
+            toolName: string;
+            input: unknown;
+        };
+        outcome: "completed" | "failed";
+    } | {
+        imageIndices: number[];
+        type: "value";
+        id: string;
+        format: "text" | "json" | "image";
+        value: string;
+        truncated?: boolean;
+    })[];
+    images: ModelImage[];
+};
+/** Only the visible projection crosses into model text; program data and inputs stay private. */
+export declare function visibleObservation(value: CodeObservation): Record<string, unknown>;
+export declare function renderObservations(values: readonly CodeObservation[]): string;
+export declare function visibleObservationText(value: CodeObservation): string;
+export declare function renderObservationResult(values: readonly CodeObservation[], original: string): string;
+export declare function observationModelParts(message: {
+    content?: string;
+    textBlocks?: readonly {
+        readonly text: string;
+    }[];
+    observations?: readonly CodeObservation[];
+    images?: readonly import('../model/image.js').ModelImage[];
+}): Array<{
+    type: 'text';
+    text: string;
+} | {
+    type: 'image';
+    image: import('../model/image.js').ModelImage;
+}> | undefined;
+/** Uses the same visible text as both adapters, without pixels or private observation data. */
+export declare function observationModelText(message: Parameters<typeof observationModelParts>[0]): string | undefined;
+export declare function parseObservations(value: unknown): CodeObservation[] | undefined;

package/dist/session/code-observation-projection.js

@@ -0,0 +1,165 @@
+export function parseCodeCalls(value) {
+    if (!Array.isArray(value) || value.length > 128)
+        return undefined;
+    const ids = new Set();
+    for (const item of value) {
+        if (!item ||
+            typeof item !== 'object' ||
+            typeof item.callId !== 'string' ||
+            !item.callId ||
+            ids.has(item.callId) ||
+            typeof item.toolName !== 'string' ||
+            !['running', 'completed', 'failed'].includes(item.status))
+            return undefined;
+        if (item.result !== undefined && (!item.result || typeof item.result.content !== 'string'))
+            return undefined;
+        ids.add(item.callId);
+    }
+    return value;
+}
+export function observationContent(value) {
+    return value.type === 'tool_result' ? value.result.content : value.value;
+}
+export function observationImages(value) {
+    return value.type === 'tool_result'
+        ? (value.result.imageIndices ?? [])
+        : (value.imageIndices ?? []);
+}
+export function selectObservationImages(values, images, offset = 0) {
+    const selected = [];
+    const indices = new Map();
+    const observations = values.map((value) => {
+        const remap = observationImages(value).flatMap((index) => {
+            const image = images[index - offset];
+            if (!image)
+                return [];
+            let next = indices.get(index);
+            if (next === undefined) {
+                next = selected.length;
+                indices.set(index, next);
+                selected.push(image);
+            }
+            return [next];
+        });
+        return value.type === 'tool_result'
+            ? { ...value, result: { ...value.result, imageIndices: remap } }
+            : { ...value, imageIndices: remap };
+    });
+    return { observations, images: selected };
+}
+/** Only the visible projection crosses into model text; program data and inputs stay private. */
+export function visibleObservation(value) {
+    return value.type === 'tool_result'
+        ? {
+            type: value.type,
+            toolName: value.source.toolName,
+            outcome: value.outcome,
+            content: value.result.content,
+            ...(value.result.truncated ? { truncated: true } : {})
+        }
+        : {
+            type: value.type,
+            format: value.format,
+            value: value.value,
+            ...(value.truncated ? { truncated: true } : {})
+        };
+}
+export function renderObservations(values) {
+    return JSON.stringify(values.map(visibleObservation));
+}
+export function visibleObservationText(value) {
+    const { content: _content, value: _value, ...header } = visibleObservation(value);
+    const body = observationContent(value);
+    return JSON.stringify(header) + (body.length ? `\n${body}` : '');
+}
+export function renderObservationResult(values, original) {
+    try {
+        const envelope = JSON.parse(original);
+        if (envelope && !Array.isArray(envelope) && typeof envelope === 'object')
+            return JSON.stringify({ ...envelope, observations: values.map(visibleObservation) });
+    }
+    catch {
+        // A non-JSON envelope falls back to the bounded observation rendering.
+    }
+    return renderObservations(values);
+}
+export function observationModelParts(message) {
+    if (message.textBlocks !== undefined || message.observations === undefined)
+        return undefined;
+    const prefix = [];
+    try {
+        const parsed = JSON.parse(message.content ?? '');
+        if (parsed && !Array.isArray(parsed) && typeof parsed === 'object') {
+            const { observations: _observations, ...metadata } = parsed;
+            const cellEnvelope = typeof metadata.cellId === 'string' &&
+                typeof metadata.status === 'string' &&
+                Array.isArray(_observations);
+            if (!message.observations.length && !cellEnvelope)
+                return undefined;
+            if (cellEnvelope) {
+                // Keep execution facts in storage; project only actionable lifecycle metadata.
+                delete metadata.toolCalls;
+                delete metadata.outputBytes;
+                if (metadata.outputDroppedBytes === 0)
+                    delete metadata.outputDroppedBytes;
+                if (metadata.truncated === false)
+                    delete metadata.truncated;
+                if (metadata.cached === false)
+                    delete metadata.cached;
+            }
+            prefix.push({ type: 'text', text: JSON.stringify(metadata) });
+        }
+    }
+    catch {
+        // Malformed envelope metadata must not hide structured observations.
+    }
+    if (!message.observations.length && !prefix.length)
+        return undefined;
+    return [
+        ...prefix,
+        ...message.observations.flatMap((value) => {
+            const parts = [{ type: 'text', text: visibleObservationText(value) }];
+            for (const index of observationImages(value)) {
+                const image = message.images?.[index];
+                if (image)
+                    parts.push({ type: 'image', image });
+            }
+            return parts;
+        })
+    ];
+}
+/** Uses the same visible text as both adapters, without pixels or private observation data. */
+export function observationModelText(message) {
+    return observationModelParts(message)
+        ?.flatMap((part) => (part.type === 'text' ? [part.text] : []))
+        .join('\n');
+}
+export function parseObservations(value) {
+    if (!Array.isArray(value) || value.length > 4096)
+        return undefined;
+    const ids = new Set();
+    for (const item of value) {
+        if (!item || typeof item !== 'object' || typeof item.id !== 'string' || ids.has(item.id))
+            return undefined;
+        ids.add(item.id);
+        if (item.type === 'tool_result') {
+            if (!item.source ||
+                typeof item.source.callId !== 'string' ||
+                typeof item.source.toolName !== 'string' ||
+                !['completed', 'failed'].includes(item.outcome) ||
+                !item.result ||
+                typeof item.result.content !== 'string')
+                return undefined;
+        }
+        else if (item.type !== 'value' ||
+            !['text', 'json', 'image'].includes(item.format) ||
+            typeof item.value !== 'string')
+            return undefined;
+        const indices = item.type === 'tool_result' ? item.result.imageIndices : item.imageIndices;
+        if (indices !== undefined &&
+            (!Array.isArray(indices) ||
+                indices.some((i) => !Number.isSafeInteger(i) || Number(i) < 0 || Number(i) >= 5)))
+            return undefined;
+    }
+    return value;
+}

package/dist/session/code-state.d.ts

@@ -0,0 +1,27 @@
+export interface CodeModeStateEntry {
+    readonly key: string;
+    readonly value: unknown;
+}
+export type CodeModeStateMutation = {
+    readonly operation: 'set';
+    readonly key: string;
+    readonly value: unknown;
+} | {
+    readonly operation: 'delete';
+    readonly key: string;
+};
+export declare const CODE_STATE_LIMITS: Readonly<{
+    codeStateMaxEntries: 128;
+    codeStateMaxMutations: 128;
+    codeStateMaxKeyBytes: 256;
+    codeStateMaxValueBytes: 65536;
+    codeStateMaxTotalBytes: 1048576;
+}>;
+type StateRecord = {
+    readonly type: string;
+    readonly payload: unknown;
+};
+export declare function parseCodeModeStateMutations(value: unknown): CodeModeStateMutation[];
+export declare function restoreCodeModeState(records: readonly StateRecord[], initialState?: CodeModeStateEntry[]): CodeModeStateEntry[];
+export declare function applyCodeModeStateMutations(entries: readonly CodeModeStateEntry[], mutations: readonly CodeModeStateMutation[]): CodeModeStateEntry[];
+export {};

package/dist/session/code-state.js

@@ -0,0 +1,89 @@
+import { AgentError } from '../error.js';
+export const CODE_STATE_LIMITS = Object.freeze({
+    codeStateMaxEntries: 128,
+    codeStateMaxMutations: 128,
+    codeStateMaxKeyBytes: 256,
+    codeStateMaxValueBytes: 65_536,
+    codeStateMaxTotalBytes: 1_048_576
+});
+const limits = CODE_STATE_LIMITS;
+export function parseCodeModeStateMutations(value) {
+    if (!Array.isArray(value) || value.length > limits.codeStateMaxMutations)
+        throw invalidState();
+    return value.map((item) => {
+        if (!isObject(item) || !validKey(item.key))
+            throw invalidState();
+        if (item.operation === 'delete' &&
+            Object.keys(item).every((key) => ['operation', 'key'].includes(key)))
+            return { operation: 'delete', key: item.key };
+        if (item.operation === 'set' &&
+            Object.keys(item).every((key) => ['operation', 'key', 'value'].includes(key)) &&
+            Object.prototype.hasOwnProperty.call(item, 'value'))
+            return { operation: 'set', key: item.key, value: cloneStateValue(item.value) };
+        throw invalidState();
+    });
+}
+export function restoreCodeModeState(records, initialState = []) {
+    let state = initialState;
+    for (const record of records) {
+        if (record.type !== 'code.state.updated')
+            continue;
+        if (!isObject(record.payload) ||
+            !Object.keys(record.payload).every((key) => key === 'mutations'))
+            throw corruptState();
+        let mutations;
+        try {
+            mutations = parseCodeModeStateMutations(record.payload.mutations);
+            state = applyCodeModeStateMutations(state, mutations);
+        }
+        catch (error) {
+            if (error instanceof AgentError)
+                throw new AgentError('MAR_AGENT_SESSION_CORRUPT', 'Code Mode state is corrupt.', {
+                    cause: error
+                });
+            throw error;
+        }
+    }
+    return state;
+}
+export function applyCodeModeStateMutations(entries, mutations) {
+    const state = new Map(entries.map((entry) => [entry.key, cloneStateValue(entry.value)]));
+    for (const mutation of mutations) {
+        if (mutation.operation === 'delete')
+            state.delete(mutation.key);
+        else
+            state.set(mutation.key, cloneStateValue(mutation.value));
+    }
+    if (state.size > limits.codeStateMaxEntries)
+        throw new AgentError('MAR_AGENT_TOOL_OUTPUT_LIMIT', 'Code Mode state has too many entries.');
+    const result = [...state].map(([key, value]) => ({ key, value }));
+    if (Buffer.byteLength(JSON.stringify(result)) > limits.codeStateMaxTotalBytes)
+        throw new AgentError('MAR_AGENT_TOOL_OUTPUT_LIMIT', 'Code Mode state is too large.');
+    return result;
+}
+function validKey(value) {
+    return (typeof value === 'string' &&
+        value.length > 0 &&
+        Buffer.byteLength(value) <= limits.codeStateMaxKeyBytes);
+}
+function cloneStateValue(value) {
+    let serialized;
+    try {
+        serialized = JSON.stringify(value);
+    }
+    catch {
+        throw invalidState();
+    }
+    if (serialized === undefined || Buffer.byteLength(serialized) > limits.codeStateMaxValueBytes)
+        throw invalidState();
+    return JSON.parse(serialized);
+}
+function invalidState() {
+    return new AgentError('MAR_AGENT_TOOL_INPUT_INVALID', 'Code Mode state mutation is invalid.');
+}
+function corruptState() {
+    return new AgentError('MAR_AGENT_SESSION_CORRUPT', 'Code Mode state is corrupt.');
+}
+function isObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}

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

@@ -0,0 +1,26 @@
+import type { SessionRecord } from './record-contract.js';
+import type { ContextGcPlatform, ContextGcBase, ContextGcTarget, ContextGcReplacement, ContextGcCheckpointDraft, ContextGcCheckpointPayload } from './context-gc-contract.js';
+export type { ContextGcPlatform, ContextGcEconomicsPolicy, ContextGcBase, ContextGcTarget, ContextGcReadItemReplacement, ContextGcReplacement, ContextGcMetrics, ContextGcCheckpointDraft, ContextGcCheckpointPayload } from './context-gc-contract.js';
+export declare const CONTEXT_GC_CHECKPOINT_VERSION: 1;
+export declare const CONTEXT_GC_MAX_TARGETS = 4096;
+/** Disposable memoization for one evaluation's immutable record snapshot. */
+export declare class ContextGcCheckpointCache {
+    #private;
+    read(records: readonly SessionRecord[], boundarySequence?: number): ReturnType<typeof latestValidContextGcCheckpoint>;
+}
+export declare function contextGcMinimumUsageGrowth(contextWindowTokens: number): number;
+/** Compare adjacent checkpoint triggers only within the same model/window scope. */
+export declare function contextGcCheckpointIntervalEligible(trigger: ContextGcCheckpointDraft['trigger'], previous?: ContextGcCheckpointDraft['trigger']): boolean;
+export declare function contextGcLogicalPathKey(path: string, workspace: string, platform?: ContextGcPlatform): string | undefined;
+export declare function contextGcTargetKey(target: ContextGcTarget): string;
+export declare function contextGcReplacementKey(replacement: ContextGcReplacement): string;
+export declare function contextGcBaseFromRecords(records: readonly SessionRecord[], boundarySequence?: number): ContextGcBase | undefined;
+export declare function contextGcBaseSequence(base: ContextGcBase): number;
+export declare function normalizeContextGcReplacements(replacements: readonly ContextGcReplacement[]): ContextGcReplacement[] | undefined;
+export declare function parseContextGcCheckpoint(record: SessionRecord | undefined): ContextGcCheckpointPayload | undefined;
+export declare function validateContextGcCheckpoint(records: readonly SessionRecord[], record: SessionRecord, workspace?: string | undefined, committedReplacements?: readonly ContextGcReplacement[]): ContextGcCheckpointPayload | undefined;
+export declare function latestValidContextGcCheckpoint(records: readonly SessionRecord[], boundarySequence?: number): {
+    readonly record: SessionRecord;
+    readonly payload: ContextGcCheckpointPayload;
+} | undefined;
+export declare function sameContextGcBase(left: ContextGcBase | undefined, right: ContextGcBase | undefined): boolean;