@myagentroam/agent 0.11.21 → 0.11.22

package/dist/agent-core/sdk/session.js

@@ -1,10 +1,12 @@
-import { restoreMessages } from '../runtime/context/restore.js';
+import { readResourceImages, restoreMessages } from '../runtime/context/restore.js';
 import { createNativeSteer } from './native-steer.js';
 import { latestModelUsage, reasoningEffortBaseline } from '../runtime/context/usage.js';
 import { splitContextualPrompt } from '../runtime/context/contextual-blocks.js';
 import { contextualInstructionInsertIndex, latestContextualWorldStateGeneration, parsePersistedContextualWorldState, persistContextualWorldState, resetContextualWorldState, updateContextualWorldState, updatePromptWorldState } from '../runtime/context/world-state.js';
 import { eventForPersistence, publicModelUsage } from '../runtime/event-projection.js';
 import { ExecutionLoop } from '../runtime/execution.js';
+import { publishModelResources } from '../runtime/resource-publication.js';
+import { ResourceInputProjection } from './resource-input.js';
 import { closeModelAdapters, createExecutionModelResources, createModelTurnSession } from './model-runtime.js';
 import { prepareSessionModelRequest, projectSessionRequestMessages } from './request-preparation.js';
 import { createSubagentBackend } from './subagent-backend.js';
@@ -543,6 +545,7 @@ export function createSessionOpener(services) {
                             replaceCompactMessages(replacementHistory, retainedModelContext) {
                                 messages.splice(0, messages.length, environmentContextUpdate(executionEnvironment), ...compactedHistoryMessages(replacementHistory), ...retainedModelContext);
                                 pendingAppends.length = 0;
+                                resourceInput.replace(messages);
                                 selected.resetContinuation?.();
                             },
                             // Derived state follows the committed splice, never delays it past the writer window.
@@ -579,6 +582,8 @@ export function createSessionOpener(services) {
                                     .filter((entry) => !restoredIds.has(entry.recordId))
                                     .map((entry) => entry.message);
                                 messages.splice(0, messages.length, ...refreshed.messages, ...lateMessages);
+                                resourceInput.replace(messages);
+                                resourceInput.adoptGc(committed.projection.checkpoint?.inlineMedia?.state);
                                 restoreMcpDiscovery();
                                 recordedEnvironment = refreshed.environmentState;
                                 userMessages = [...refreshed.userMessages];
@@ -620,8 +625,18 @@ export function createSessionOpener(services) {
                                 smartPercent !== undefined &&
                                 smartPercent >= AGENT_EXECUTION_POLICY.smartCompactionPercent &&
                                 smartPercent < AGENT_EXECUTION_POLICY.automaticCompactionPercent;
-                            const images = content.images?.length
-                                ? await store.persistInputImages(sessionId, content.images)
+                            const modelImages = await publishModelResources(host, content.images, {
+                                sessionId,
+                                executionId
+                            }, store);
+                            const actualContent = modelImages === content.images
+                                ? content
+                                : {
+                                    ...content,
+                                    ...(modelImages === undefined ? {} : { images: modelImages })
+                                };
+                            const images = modelImages?.length
+                                ? await store.persistInputImages(sessionId, modelImages)
                                 : [];
                             const record = await store.append(sessionId, {
                                 type,
@@ -649,7 +664,7 @@ export function createSessionOpener(services) {
                                 content: content.modelText ?? content.text,
                                 metadata: inputMetadata
                             });
-                            committed(content, record.recordId, inputMetadata);
+                            committed(actualContent, record.recordId, inputMetadata);
                             for (const text of content.modelContext ?? content.context ?? [])
                                 messages.push({ role: 'user', content: text, contextKind: 'contextual' });
                         });
@@ -757,10 +772,7 @@ export function createSessionOpener(services) {
                                 metadata,
                                 ...(actual.images?.length
                                     ? {
-                                        images: actual.images.map(({ mimeType, dataBase64 }) => ({
-                                            mimeType,
-                                            dataBase64
-                                        }))
+                                        images: actual.images.map((image) => ({ ...image }))
                                     }
                                     : {})
                             });
@@ -775,6 +787,7 @@ export function createSessionOpener(services) {
                     }, inputs.boundarySize);
                     const hasRestoredUserImages = messages.some((message) => message.role === 'user' && Boolean(message.images?.length));
                     let modelInputImages;
+                    const inputImageBytes = new Map();
                     const currentExecutionToolImages = [];
                     let currentExecutionUserIndex;
                     await emit({ type: 'execution.started', mode, permissionMode: permissionPolicy.mode });
@@ -791,6 +804,18 @@ export function createSessionOpener(services) {
                         });
                     selectedAdapter = sessionAdapter(input.modelId ?? executionDefaultModelId, executionModels);
                     const selectedModel = executionModels.get(input.modelId ?? executionDefaultModelId);
+                    const restoredMessageCount = messages.length;
+                    const resourceInput = new ResourceInputProjection(selectedModel.useResourceUrl === true, store, sessionId, messages, {
+                        records: contextRecords,
+                        persist: async (state) => {
+                            await withRecordProjection(() => store.append(sessionId, {
+                                type: 'resource.window',
+                                payload: state,
+                                executionId,
+                                turnId
+                            }));
+                        }
+                    });
                     const selected = modelResources.openTurn(selectedAdapter, services.hasCustomAdapters && selectedAdapter.createTurnSession === undefined);
                     let lastServerUsage = latestModelUsage(contextRecords, selectedModel.id);
                     let smartContextTokens = latestSmartContextTokens(contextRecords, selectedModel.id, selectedModel.contextWindowTokens);
@@ -898,9 +923,7 @@ export function createSessionOpener(services) {
                         ?.filter((binding) => !executionSourceNames.has(binding.definition.name)) ?? [];
                     const sources = (executionToolSources = new ExecutionToolSources(executionId, sessionId, combinedTools, builtinTools, mcpCatalog, supplementalBindings));
                     const sourceBindings = sources.bindings;
-                    const coreExtensions = await services.extensions.prepare(sessionId, controller.signal, sourceBindings, sessionSource.type === 'user' &&
-                        (mode === 'run' || mode === 'plan') &&
-                        !internal.automaticInput);
+                    const coreExtensions = await services.extensions.prepare(sessionId, controller.signal, sourceBindings, sessionSource.type === 'user' && !internal.automaticInput);
                     executionContext.toolSources = sources;
                     const operation = (run) => services.extensions.operations.run({
                         sessionId,
@@ -928,9 +951,11 @@ export function createSessionOpener(services) {
                     const transformModelRequest = async (candidate, bindings = captureTools(), modelId = selectedModel.id, purpose = mode === 'compact' ? 'compact' : 'conversation') => {
                         let lowered = candidate;
                         if (coreExtensions.hooks.hasInterceptors('model.request')) {
-                            const bridge = new ExtensionRequestBridge(modelId, candidate);
+                            const bridge = new ExtensionRequestBridge(modelId, candidate, undefined, selected.continuationInputCount?.() ?? 0);
                             const request = await operation((call) => coreExtensions.hooks.invoke('model.request', bridge.view, call, async (view) => view));
                             lowered = bridge.lower(request);
+                            if (bridge.rewroteCommittedInput)
+                                selected.resetContinuation?.();
                         }
                         for (const definition of lowered.tools) {
                             const binding = bindings.get(definition.name);
@@ -1068,6 +1093,7 @@ export function createSessionOpener(services) {
                             : subagents.captureParentFrame(executionId);
                         const roundSmartInput = smartInput;
                         const toolContext = {
+                            imageStore: store,
                             host: host,
                             requestSmartCompact: () => {
                                 controller.signal.throwIfAborted();
@@ -1117,7 +1143,20 @@ export function createSessionOpener(services) {
                                 return sources.withFrame(context, () => parentFrame === undefined ? invoke() : parentFrame(invoke));
                             }
                         };
-                        const recentImages = () => currentExecutionImages(modelInputImages, currentExecutionToolImages);
+                        const recentImages = async () => {
+                            const inputImages = await Promise.all((modelInputImages ?? []).map(async (image) => {
+                                if (image.dataBase64 !== undefined || image.resourceId === undefined)
+                                    return image;
+                                const cached = inputImageBytes.get(image.resourceId);
+                                if (cached !== undefined)
+                                    return cached;
+                                const source = await store.readResource(sessionId, image.resourceId);
+                                const restored = { ...image, ...source };
+                                inputImageBytes.set(image.resourceId, restored);
+                                return restored;
+                            }));
+                            return currentExecutionImages(inputImages, currentExecutionToolImages);
+                        };
                         const toolScope = {
                             context: toolContext,
                             tools: roundTools,
@@ -1141,8 +1180,7 @@ export function createSessionOpener(services) {
                             recentImages,
                             captureCodeContext: () => ({
                                 ...toolContext,
-                                waitInterrupt: undefined,
-                                recentImages: recentImages()
+                                waitInterrupt: undefined
                             }),
                             codeModeContext: async (call) => {
                                 const stateSnapshot = call.name === 'code_exec' ? await store.readCodeModeState(sessionId) : [];
@@ -1214,6 +1252,9 @@ export function createSessionOpener(services) {
                     sources.bind(captureRoundToolScope().toolScope);
                     let preparingRequestMessages;
                     let preparingRequestBaseLength = 0;
+                    let dispatchedInputCount = 0;
+                    const completedMediaRequests = new WeakSet();
+                    let dispatchedLocalCount = 0;
                     executionContext.requestMessages = {
                         read: () => preparingRequestMessages !== undefined
                             ? normalizeMessagesForModel([...preparingRequestMessages, ...messages.slice(preparingRequestBaseLength)], { supportsImages: selectedModel.inputCapabilities.includes('IMAGE') })
@@ -1245,14 +1286,12 @@ export function createSessionOpener(services) {
                                 ...(input.clientMessageId ? { clientMessageId: input.clientMessageId } : {})
                             }, call, (actual, recordId, metadata) => {
                                 entered = true;
-                                modelInputImages = actual.images?.map(({ mimeType, dataBase64 }) => ({
-                                    mimeType,
-                                    dataBase64
-                                }));
+                                modelInputImages = actual.images?.map((image) => ({ ...image }));
                                 messages.push({
                                     role: 'user',
                                     content: actual.modelText ?? actual.text,
-                                    metadata
+                                    metadata,
+                                    ...(modelInputImages?.length ? { images: modelInputImages } : {})
                                 });
                                 currentExecutionUserIndex = messages.length - 1;
                                 internal.inputCommitted?.(recordId);
@@ -1288,8 +1327,12 @@ export function createSessionOpener(services) {
                                 call.signal.throwIfAborted();
                                 if (content.images?.length && !selectedModel.inputCapabilities.includes('IMAGE'))
                                     throw new MarAgentError('MAR_AGENT_INPUT_CAPABILITY_UNSUPPORTED', 'Selected model does not support image input.');
-                                const images = content.images?.length
-                                    ? await store.persistInputImages(sessionId, content.images)
+                                const modelImages = await publishModelResources(host, content.images, {
+                                    sessionId,
+                                    executionId
+                                }, store);
+                                const images = modelImages?.length
+                                    ? await store.persistInputImages(sessionId, modelImages)
                                     : [];
                                 const record = await store.append(sessionId, {
                                     type: 'turn.user',
@@ -1401,7 +1444,12 @@ export function createSessionOpener(services) {
                             turnId
                         });
                         let lastServerContextTokens = lastServerUsage?.contextInputTokens;
-                        let compactBoundary = messages.length;
+                        let compactBoundary = restoredMessageCount;
+                        const advanceCompactBoundary = () => {
+                            // Keep a new image with its complete tool round until a model accepts it.
+                            if (!resourceInput.hasPendingImages(messages.slice(compactBoundary)))
+                                compactBoundary = messages.length;
+                        };
                         const invalidateCompactUsage = () => {
                             lastServerContextTokens = undefined;
                             lastServerUsage = undefined;
@@ -1421,7 +1469,7 @@ export function createSessionOpener(services) {
                                 message.contextKind === undefined ||
                                 message.contextKind === 'summary'))
                                 return false;
-                            const compactHistory = structuredClone(prefix);
+                            const compactHistory = structuredClone(prefix).map(({ images: _images, ...message }) => message);
                             const prefixInputs = modelContext.compactInputs(prefix);
                             const snapshotTools = structuredClone(projectTools(executionTools));
                             const generation = modelContext.worldState.generation;
@@ -1503,6 +1551,7 @@ export function createSessionOpener(services) {
                                 const record = await store.compact(sessionId, {
                                     summary: actual,
                                     replacementHistory,
+                                    inlineMediaState: resourceInput.checkpoint(retainedModelContext),
                                     retainedModelContext: retainedModelContext.map((message) => {
                                         const source = messageSources.get(message);
                                         const saved = source?.type === 'model.context' &&
@@ -1516,7 +1565,14 @@ export function createSessionOpener(services) {
                                                 ...saved,
                                                 ...(message.metadata ? { metadata: message.metadata } : {})
                                             }
-                                            : message;
+                                            : {
+                                                ...message,
+                                                ...(message.images?.length
+                                                    ? {
+                                                        images: message.images.map(({ dataBase64: _bytes, ...image }) => image)
+                                                    }
+                                                    : {})
+                                            };
                                     }),
                                     pendingInputs: [...pendingInputs.values()],
                                     snapshotMessageCount: prefix.length,
@@ -1530,6 +1586,7 @@ export function createSessionOpener(services) {
                                     turnId
                                 }, options);
                                 modelContext.replaceCompactMessages(replacementHistory, retainedModelContext);
+                                compactBoundary = messages.length - retainedModelContext.length;
                                 return record;
                             });
                             await modelContext.adoptCompactCheckpoint(compactRecord.recordId, replacementHistory, retainedModelContext, compactResources);
@@ -1619,7 +1676,7 @@ export function createSessionOpener(services) {
                                     controller.signal.throwIfAborted();
                                     if (!hadPending)
                                         throw error;
-                                    compactBoundary = messages.length;
+                                    advanceCompactBoundary();
                                     compacted = await compactContext();
                                 }
                                 if (!compacted)
@@ -1680,7 +1737,7 @@ export function createSessionOpener(services) {
                                 updateMcpRegistry();
                                 executionTools = mcpRegistry.project(baseTools());
                                 await modelContext.syncMcpWorldState(messages.length);
-                                compactBoundary = messages.length;
+                                advanceCompactBoundary();
                                 const blocking = compactRequests.drain((input) => startCompact({
                                     ...(input.prompt === undefined ? {} : { focus: input.prompt }),
                                     async: input.async === true
@@ -1737,24 +1794,61 @@ export function createSessionOpener(services) {
                                     // Never sample the candidate assembled against the replaced context.
                                     return prepareRound(pendingOutputContinuation, true);
                                 }
-                                return { request, toolScope };
+                                resourceInput.observe(candidateRequest.messages);
+                                const media = sessionSource.type === 'subagent'
+                                    ? undefined
+                                    : await resourceInput.gcCandidate(request, candidateRequest.images);
+                                if (media?.reason === 'HARD_LIMIT') {
+                                    const appendBoundary = pendingAppends.length;
+                                    const committed = await contextGc.run({
+                                        inlineMedia: media,
+                                        mediaView: (messages) => resourceInput.historyView(messages),
+                                        store,
+                                        sessionId,
+                                        system: request.system,
+                                        tools: toolScope.tools,
+                                        modelId: selectedModel.id,
+                                        contextWindowTokens: selectedModel.contextWindowTokens,
+                                        usage: lastServerUsage ?? {},
+                                        ...modelConfiguration.contextProjection,
+                                        workspace: logicalWorkspace,
+                                        platform: description.platform
+                                    });
+                                    if (committed) {
+                                        await modelContext.adoptGcCheckpoint(committed, appendBoundary);
+                                        return prepareRound(pendingOutputContinuation, true);
+                                    }
+                                }
+                                return {
+                                    request: await resourceInput.prepare(request, candidateRequest.images, candidateRequest.messages),
+                                    toolScope
+                                };
                             },
                             startModel: async function* (request) {
                                 const snapshots = (sessionRuntime.requestSnapshots ??=
                                     new ExtensionRequestSnapshots());
                                 const snapshot = snapshots.record(selectedModel.id, request);
+                                dispatchedInputCount = request.messages.length;
+                                dispatchedLocalCount = messages.length;
                                 yield* streamModel(async function* (nativeSignal) {
                                     for await (const event of selected.start(request, nativeSignal)) {
-                                        if (snapshot && event.type === 'completed' && event.reason !== 'cancelled')
-                                            snapshots.complete(snapshot);
+                                        if (event.type === 'completed' && event.reason !== 'cancelled') {
+                                            completedMediaRequests.add(request.messages);
+                                            if (snapshot)
+                                                snapshots.complete(snapshot);
+                                        }
                                         yield event;
                                     }
                                 }, controller.signal);
                             },
                             recoverySignal: () => controller.signal,
                             compactContext,
-                            afterModel: async (closedPrefixLength) => {
-                                compactBoundary = closedPrefixLength;
+                            afterModel: async (closedPrefixLength, acceptedRequest) => {
+                                selected.commitContinuationInput?.(dispatchedInputCount + messages.length - dispatchedLocalCount);
+                                if (acceptedRequest && completedMediaRequests.has(acceptedRequest.messages)) {
+                                    await resourceInput.complete(acceptedRequest);
+                                    compactBoundary = closedPrefixLength;
+                                }
                                 if (lastServerContextTokens !== undefined &&
                                     (lastServerContextTokens * 100) / selectedModel.contextWindowTokens >=
                                         AGENT_EXECUTION_POLICY.backgroundCompactionPercent &&
@@ -1773,7 +1867,7 @@ export function createSessionOpener(services) {
                                 }
                             },
                             checkpoint: async (round, latestUsage) => {
-                                compactBoundary = messages.length;
+                                advanceCompactBoundary();
                                 const blocking = compactRequests.drain((input) => startCompact({
                                     ...(input.prompt === undefined ? {} : { focus: input.prompt }),
                                     async: input.async === true
@@ -1784,19 +1878,19 @@ export function createSessionOpener(services) {
                                     await compactCoordinator.checkpoint(false).catch(() => {
                                         controller.signal.throwIfAborted();
                                     });
-                                if (!compactCoordinator.pending &&
-                                    sessionSource.type !== 'subagent' &&
-                                    latestUsage !== undefined) {
+                                if (!compactCoordinator.pending && sessionSource.type !== 'subagent') {
                                     // Only a committed GC checkpoint may replace active context and invalidate continuation.
                                     const appendBoundary = pendingAppends.length;
                                     const committed = await contextGc.run({
+                                        inlineMedia: await resourceInput.gcCandidate(),
+                                        mediaView: (messages) => resourceInput.historyView(messages),
                                         store,
                                         sessionId,
                                         system: round.request.system,
                                         tools: round.toolScope.tools,
                                         modelId: selectedModel.id,
                                         contextWindowTokens: selectedModel.contextWindowTokens,
-                                        usage: latestUsage,
+                                        usage: latestUsage ?? {},
                                         ...modelConfiguration.contextProjection,
                                         workspace: logicalWorkspace,
                                         platform: description.platform,
@@ -2052,8 +2146,19 @@ export function createSessionOpener(services) {
                 call.signal.throwIfAborted();
                 const targetRuntime = sessionRuntimes.get(target);
                 const requestMessages = targetRuntime?.execution?.requestMessages;
-                if (selection.view === 'request' && requestMessages)
-                    return sessionMessagesPage(requestMessages.read(), selection);
+                if (selection.view === 'request' && requestMessages) {
+                    const messages = requestMessages.read();
+                    const restored = selection.includeImages
+                        ? await Promise.all(messages.map(async (message) => message.images?.length
+                            ? {
+                                ...message,
+                                images: await readResourceImages(store, target, message.images)
+                            }
+                            : message))
+                        : messages;
+                    call.signal.throwIfAborted();
+                    return sessionMessagesPage(restored, selection);
+                }
                 const modelState = services.modelState();
                 const requestModel = selection.view === 'request'
                     ? modelState.models.get(targetModelId ?? modelState.defaultModelId)

package/dist/agent-core/session/catalog.d.ts

@@ -72,6 +72,10 @@ export interface MarAgentSessionCatalog {
         readonly sequence: number;
         readonly imageIndex: number;
     }): Promise<MarAgentSessionImage | undefined>;
+    readResource(sessionId: string, resourceId: string): Promise<{
+        mimeType: string;
+        dataBase64: string;
+    } | undefined>;
     contextUsage(sessionId: string): Promise<MarAgentContextUsage | undefined>;
     readToolResultResource(sessionId: string, input: import('./tool-result-resources.js').ToolResultResourceInput): Promise<import('./tool-result-resources.js').ToolResultResourcePage>;
     fork(sessionId: string, input: {

package/dist/agent-core/session/catalog.js

@@ -103,6 +103,10 @@ export async function openMarAgentSessionCatalog(input) {
                     dataBase64: image.dataBase64
                 };
         },
+        readResource: async (sessionId, resourceId) => {
+            assertOpen();
+            return store.readResource(sessionId, resourceId);
+        },
         readToolResultResource: async (sessionId, input) => {
             assertOpen();
             return store.readToolResultResource(sessionId, input);

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

@@ -1,3 +1,4 @@
+import { type InlineMediaGcCheckpoint } from './inline-media.js';
 import { type ContextGcWebToolName } from './context-gc-replacements.js';
 import { type ContextGcSubagentToolName } from './context-gc-subagent.js';
 import type { SessionRecord } from './store/index.js';
@@ -93,7 +94,7 @@ export type ContextGcReplacement = {
     readonly evidenceSequence: number;
 };
 export interface ContextGcMetrics {
-    readonly stage: 'STAGE_A' | 'STAGE_A_AND_EXEC';
+    readonly stage: 'STAGE_A' | 'STAGE_A_AND_EXEC' | 'INLINE_MEDIA';
     readonly tokenEstimator?: 'UTF8_BYTES_V1';
     readonly beforeTokens: number;
     readonly afterTokens: number;
@@ -105,8 +106,8 @@ export interface ContextGcMetrics {
     readonly compactDeferralCreditCostUnits: number;
     readonly imminentCompactAvoidanceCreditCostUnits?: number;
     readonly appliedCompactCreditCostUnits?: number;
-    readonly requiredPositiveNetRollouts: number;
-    readonly requiredTargetRoiRollouts: number;
+    readonly requiredPositiveNetRollouts: number | null;
+    readonly requiredTargetRoiRollouts: number | null;
     readonly projectedRolloutsUntilCompactAfterGc: number;
     readonly projectedTokensBeforeGc?: number;
     readonly projectedTokensAfterGc?: number;
@@ -121,12 +122,13 @@ export interface ContextGcMetrics {
     readonly cachePenaltyKnown?: boolean;
 }
 export interface ContextGcCheckpointDraft {
+    readonly inlineMedia?: InlineMediaGcCheckpoint;
     readonly version: 1;
     readonly base: ContextGcBase;
     readonly boundarySequence: number;
     readonly replacements: readonly ContextGcReplacement[];
     readonly trigger: {
-        readonly usageSequence: number;
+        readonly usageSequence: number | null;
         readonly contextInputTokens: number;
         readonly contextWindowTokens: number;
         readonly normalRolloutOrdinal: number;

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

@@ -1,5 +1,6 @@
 import { posix, win32 } from 'node:path';
 import { isDeepStrictEqual } from 'node:util';
+import { inlineMediaGcAnchored, parseInlineMediaGc } from './inline-media.js';
 import { codeCallEvidence, codePartialPatchCallEvidence, callsFromRecord, codeObservationEvidence, observationsFromRecord, retainedCodeInputs } from './context-gc-observations.js';
 import { parseReadContextOutput } from '../tools/local/read-context.js';
 import { codeCellCompletionSequence, contextGcApplyPatchInputReplacement, contextGcCodeModeInputReplacement, contextGcCodeModeOutputReplacement, contextGcExecInputReplacement, contextGcExecOutputReplacement, contextGcPatchResultFromCompletedPayload, contextGcPatchResultFromFailedPayload, contextGcStaleReadReplacement, contextGcWebOutputReplacement, normalizeContextGcCodeModeInput, normalizeContextGcExecResult } from './context-gc-replacements.js';
@@ -120,10 +121,11 @@ export function parseContextGcCheckpoint(record) {
         !isContextGcBase(payload.base) ||
         !isPositiveInteger(payload.boundarySequence) ||
         !Array.isArray(payload.replacements) ||
-        payload.replacements.length === 0 ||
+        (payload.replacements.length === 0 && payload.inlineMedia === undefined) ||
         !isContextGcTrigger(payload.trigger) ||
         !isContextGcEconomicsPolicy(payload.economics) ||
-        !isContextGcMetrics(payload.metrics))
+        !isContextGcMetrics(payload.metrics) ||
+        (payload.inlineMedia !== undefined && !parseInlineMediaGc(payload.inlineMedia)))
         return undefined;
     const replacements = normalizeContextGcReplacements(payload.replacements);
     if (!replacements || replacements.length !== payload.replacements.length)
@@ -137,7 +139,10 @@ export function parseContextGcCheckpoint(record) {
         replacements,
         trigger: structuredClone(payload.trigger),
         economics: structuredClone(payload.economics),
-        metrics: structuredClone(payload.metrics)
+        metrics: structuredClone(payload.metrics),
+        ...(payload.inlineMedia === undefined
+            ? {}
+            : { inlineMedia: parseInlineMediaGc(payload.inlineMedia) })
     };
 }
 export function validateContextGcCheckpoint(records, record, workspace = sessionWorkspace(records), committedReplacements = []) {
@@ -150,9 +155,14 @@ export function validateContextGcCheckpoint(records, record, workspace = session
     const baseSequence = contextGcBaseSequence(payload.base);
     // Later cell completion cannot retroactively authorize an earlier checkpoint.
     records = records.filter((item) => item.sequence <= payload.boundarySequence);
+    if (payload.inlineMedia && !inlineMediaGcAnchored(records, payload.inlineMedia))
+        return undefined;
     const recordsBySequence = new Map(records.map((item) => [item.sequence, item]));
     if (!triggerMatchesRecords(records, recordsBySequence, payload))
         return undefined;
+    if (payload.trigger.usageSequence === null &&
+        !isDeepStrictEqual(payload.replacements, committedReplacements))
+        return undefined;
     const committed = new Map(committedReplacements.map((replacement) => [contextGcReplacementKey(replacement), replacement]));
     const changed = payload.replacements.flatMap((replacement) => {
         const previous = committed.get(contextGcReplacementKey(replacement));
@@ -603,14 +613,25 @@ function isSuccessfulExecLifecycleEvidence(replacement, source, records, records
         targetResult.sequence <= evidence.result.sequence);
 }
 function triggerMatchesRecords(records, recordsBySequence, payload) {
-    if (payload.trigger.usageSequence < contextGcBaseSequence(payload.base) ||
-        payload.trigger.usageSequence > payload.boundarySequence)
+    if (payload.trigger.usageSequence !== null &&
+        (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)
+    const withoutUsage = payload.trigger.usageSequence === null;
+    if (withoutUsage &&
+        (!payload.inlineMedia ||
+            payload.inlineMedia.reason === 'TEXT_GC' ||
+            payload.metrics.stage !== 'INLINE_MEDIA' ||
+            payload.trigger.contextInputTokens !== 0))
+        return false;
+    const usageRecord = withoutUsage
+        ? undefined
+        : recordsBySequence.get(payload.trigger.usageSequence);
+    if (!withoutUsage &&
+        (!usageRecord ||
+            !isRecord(usageRecord.payload) ||
+            usageRecord.payload.type !== 'usage.updated' ||
+            modelContextUsage(usageRecord.payload) !== payload.trigger.contextInputTokens))
         return false;
     const baseSequence = contextGcBaseSequence(payload.base);
     let modelId;
@@ -632,7 +653,7 @@ function triggerMatchesRecords(records, recordsBySequence, payload) {
         }
         const matchingConfiguration = modelId === payload.trigger.modelId &&
             contextWindowTokens === payload.trigger.contextWindowTokens;
-        if (record.sequence === usageRecord.sequence)
+        if (record.sequence === usageRecord?.sequence || withoutUsage)
             triggerConfigurationMatches = matchingConfiguration;
         if (matchingConfiguration &&
             isRecord(record.payload) &&
@@ -647,7 +668,9 @@ function triggerMatchesRecords(records, recordsBySequence, payload) {
             normalRolloutOrdinal++;
     }
     return (triggerConfigurationMatches &&
-        latestMatchingUsageSequence === payload.trigger.usageSequence &&
+        (withoutUsage
+            ? latestMatchingUsageSequence === undefined
+            : latestMatchingUsageSequence === payload.trigger.usageSequence) &&
         normalRolloutOrdinal === payload.trigger.normalRolloutOrdinal);
 }
 function modelContextUsage(value) {
@@ -822,7 +845,7 @@ function isContextGcBase(value) {
 }
 function isContextGcTrigger(value) {
     return (isRecord(value) &&
-        isPositiveInteger(value.usageSequence) &&
+        (value.usageSequence === null || isPositiveInteger(value.usageSequence)) &&
         isNonnegativeInteger(value.contextInputTokens) &&
         isPositiveInteger(value.contextWindowTokens) &&
         isNonnegativeInteger(value.normalRolloutOrdinal) &&
@@ -851,7 +874,10 @@ function isContextGcEconomicsPolicy(value) {
         ].every((key) => isNonnegativeFinite(value[key])));
 }
 function isContextGcMetrics(value) {
-    if (!isRecord(value) || (value.stage !== 'STAGE_A' && value.stage !== 'STAGE_A_AND_EXEC'))
+    if (!isRecord(value) ||
+        (value.stage !== 'STAGE_A' &&
+            value.stage !== 'STAGE_A_AND_EXEC' &&
+            value.stage !== 'INLINE_MEDIA'))
         return false;
     const nonnegative = [
         'beforeTokens',
@@ -860,8 +886,6 @@ function isContextGcMetrics(value) {
         'grossReductionRate',
         'cacheRebuildPenaltyCostUnits',
         'compactDeferralCreditCostUnits',
-        'requiredPositiveNetRollouts',
-        'requiredTargetRoiRollouts',
         'projectedRolloutsUntilCompactAfterGc',
         'contextGrowthSampleCount',
         'contextGrowthP75Tokens',
@@ -879,6 +903,7 @@ function isContextGcMetrics(value) {
         'projectedTokensAfterGc'
     ];
     return (nonnegative.every((key) => isNonnegativeFinite(value[key])) &&
+        ['requiredPositiveNetRollouts', 'requiredTargetRoiRollouts'].every((key) => isNonnegativeFinite(value[key]) || (value.stage === 'INLINE_MEDIA' && value[key] === null)) &&
         optionalNonnegative.every((key) => value[key] === undefined || isNonnegativeFinite(value[key])) &&
         Number.isFinite(value.expectedNetSavedCostUnits) &&
         Number.isFinite(value.cacheInvestmentRoi) &&

package/dist/agent-core/session/inline-media.d.ts

@@ -0,0 +1,45 @@
+import type { ModelMessage, ModelRequest } from '../model/contracts.js';
+import type { ModelImage } from '../model/image.js';
+import type { SessionRecord } from './store/types.js';
+export declare const INLINE_MEDIA_POLICY: Readonly<{
+    historicalInlineMediaTrigger: number;
+    historicalInlineMediaTarget: number;
+    requestInlineMediaHardLimit: number;
+}>;
+export interface InlineMediaCursor {
+    sourceId: string;
+    imageIndex: number;
+}
+/** Processing progress, not evidence that the provider inspected an image. */
+export interface InlineMediaState {
+    version: 1;
+    consideredThrough?: InlineMediaCursor;
+    evictedThrough?: InlineMediaCursor;
+}
+export interface InlineMediaGcCheckpoint {
+    readonly reason: 'SOFT_LIMIT' | 'HARD_LIMIT' | 'TEXT_GC';
+    readonly state: InlineMediaState;
+    readonly beforeBytes: number;
+    readonly afterBytes: number;
+}
+export interface InlineMediaGcCandidate extends InlineMediaGcCheckpoint {
+    /** Apply the proposed eviction to the current visual-window projection. */
+    readonly project: (messages: readonly ModelMessage[]) => ModelMessage[];
+}
+export declare function parseInlineMediaGc(value: unknown): InlineMediaGcCheckpoint | undefined;
+export declare function inlineMediaSource(message: ModelMessage): string | ModelMessage;
+/** GC may advance only a durable, already-considered source prefix. */
+export declare function inlineMediaGcAnchored(records: readonly SessionRecord[], media: InlineMediaGcCheckpoint): boolean;
+export declare function inlineMediaBytes(image: ModelImage): number;
+export declare function inlineMediaLimit(): never;
+/** Final encoding guard; URL-only images do not consume the inline budget. */
+export declare function assertInlineMediaBudget(request: Pick<ModelRequest, 'messages' | 'images'>): void;
+export declare function parseInlineMediaState(value: unknown): InlineMediaState | undefined;
+/** Recover ordering once at the lifecycle boundary, including GC-omitted sources. */
+export declare function inlineMediaHistory(records: readonly SessionRecord[]): {
+    cursors: (InlineMediaCursor & {
+        rollout: number;
+    })[];
+    rollouts: number;
+    state?: InlineMediaState;
+};