@myagentroam/agent 0.9.86 → 0.9.87

package/dist/model/contracts.d.ts

@@ -1,11 +1,4 @@
 import type { MarAgentModelConfiguration, MarAgentReasoningEffort, ModelCredentialAcquireReason } from './configuration.js';
-export interface ModelContinuationCheckpoint {
-    readonly version: 2;
-    readonly protocol: 'OPENAI_RESPONSES';
-    readonly configurationHash: string;
-    readonly responseId: string;
-    readonly inputPrefixLength: number;
-}
 export interface ClientToolDefinition {
     name: string;
     description: string;
@@ -75,10 +68,6 @@ export interface ModelRequest {
         mimeType: string;
         dataBase64: string;
     }[];
-    continuation?: {
-        previousResponseId: string;
-        deltaMessages: readonly ModelMessage[];
-    };
     onAttemptDiagnostic?: (diagnostic: ModelAttemptDiagnostic) => Promise<void> | void;
 }
 export interface ModelUsage {
@@ -158,13 +147,11 @@ export interface ModelAdapter {
      * The returned commit callback must be synchronous and non-throwing.
      */
     prepareReconfigure?(configuration: MarAgentModelConfiguration): (() => void) | undefined;
-    restoreContinuation?(checkpoint: ModelContinuationCheckpoint): boolean;
     close?(): Promise<void>;
 }
 export interface ModelTurnSession {
     start(request: ModelRequest, signal: AbortSignal): AsyncIterable<ModelEvent>;
     /** Drops incremental response state after a local context replacement. */
     resetContinuation?(): void;
-    continuationCheckpoint?(): ModelContinuationCheckpoint | undefined;
     close(): Promise<void>;
 }

package/dist/model/openai-responses.d.ts

@@ -1,7 +1,7 @@
 import { MarAgentError } from '../error.js';
 import { type MarAgentModelConfiguration, type ModelCredentialAcquireReason } from './configuration.js';
 import WebSocket from 'ws';
-import type { ModelAdapter, ModelAttemptDiagnostic, ModelContinuationCheckpoint, ModelEvent, ModelRequest, ModelTurnSession } from './contracts.js';
+import type { ModelAdapter, ModelAttemptDiagnostic, ModelEvent, ModelRequest, ModelTurnSession } from './contracts.js';
 export declare const OPENAI_RESPONSES_EARLY_EOF_REASON = "OPENAI_RESPONSES_EARLY_EOF";
 export declare const OPENAI_RESPONSES_WEBSOCKET_CONNECTION_LIMIT_REASON = "OPENAI_RESPONSES_WEBSOCKET_CONNECTION_LIMIT";
 type ResponsesRequestBody = Readonly<Record<string, unknown>> & {
@@ -19,7 +19,6 @@ interface ResponsesSessionState {
         readonly responseId: string;
         readonly outputItems: readonly Record<string, unknown>[];
     };
-    restoredContinuation?: ModelContinuationCheckpoint;
 }
 interface PreparedResponsesRequest {
     readonly fullBody: ResponsesRequestBody;
@@ -32,7 +31,6 @@ export declare class OpenAiResponsesAdapter implements ModelAdapter {
     constructor(configuration: MarAgentModelConfiguration);
     get configuration(): MarAgentModelConfiguration;
     prepareReconfigure(configuration: MarAgentModelConfiguration): (() => void) | undefined;
-    restoreContinuation(checkpoint: ModelContinuationCheckpoint): boolean;
     start(request: ModelRequest, signal: AbortSignal): AsyncIterable<ModelEvent>;
     createTurnSession(): ModelTurnSession;
     close(): Promise<void>;
@@ -49,7 +47,6 @@ declare class OpenAiResponsesTurnSession implements ModelTurnSession {
     start(request: ModelRequest, signal: AbortSignal): AsyncIterable<ModelEvent>;
     close(): Promise<void>;
     resetContinuation(): void;
-    continuationCheckpoint(): ModelContinuationCheckpoint | undefined;
     prepareRequest(request: ModelRequest): PreparedResponsesRequest;
     fullRequestBody(): ResponsesRequestBody;
     currentTurnState(): string | undefined;

package/dist/model/openai-responses.js

@@ -31,23 +31,6 @@ export class OpenAiResponsesAdapter {
             this.#configuration = configuration;
         };
     }
-    restoreContinuation(checkpoint) {
-        if (this.#cacheLeased ||
-            this.#cachedState.lastRequest !== undefined ||
-            this.#cachedState.lastResponse !== undefined ||
-            !responsesPersistedContinuationEnabled(this.#configuration) ||
-            checkpoint.version !== 2 ||
-            checkpoint.protocol !== 'OPENAI_RESPONSES' ||
-            typeof checkpoint.responseId !== 'string' ||
-            checkpoint.responseId.length === 0 ||
-            checkpoint.responseId.length > 1024 ||
-            !Number.isSafeInteger(checkpoint.inputPrefixLength) ||
-            checkpoint.inputPrefixLength < 0 ||
-            checkpoint.configurationHash !== responsesContinuationIdentityHash(this.#configuration))
-            return false;
-        this.#cachedState.restoredContinuation = checkpoint;
-        return true;
-    }
     async *start(request, signal) {
         const turn = new OpenAiResponsesTurnSession(this, {}, false);
         try {
@@ -79,8 +62,10 @@ export class OpenAiResponsesAdapter {
             invalidateResponsesWebSocket(state, true);
             return;
         }
-        if (state.socket !== undefined && state.socket.readyState !== WebSocket.OPEN)
+        if (state.socket !== undefined && state.socket.readyState !== WebSocket.OPEN) {
             invalidateResponsesWebSocket(state, false);
+            clearResponsesContinuation(state);
+        }
         this.#cachedState = state;
         this.#cacheLeased = false;
     }
@@ -160,6 +145,24 @@ export class OpenAiResponsesAdapter {
                     ...(options.retryDelayMs === undefined ? {} : { retryDelayMs: options.retryDelayMs }),
                     ...(options.retryReason === undefined ? {} : { retryReason: options.retryReason })
                 });
+                if (!signal.aborted &&
+                    !sawSemanticEvent &&
+                    useContinuation &&
+                    !invalidContinuationFallbackUsed &&
+                    isLocalContinuationReset(error)) {
+                    invalidContinuationFallbackUsed = true;
+                    useContinuation = false;
+                    requestBody = prepared.fullBody;
+                    turn.resetContinuation();
+                    turn.invalidateWebSocket();
+                    retryState.attempts = Math.max(0, retryState.attempts - 1);
+                    credentialReason = 'RECONNECT';
+                    await reportFailure(true, {
+                        retryDelayMs: 0,
+                        retryReason: 'INVALID_CONTINUATION'
+                    });
+                    continue;
+                }
                 if (!signal.aborted &&
                     attemptNumber < maxAttempts &&
                     !sawSemanticEvent &&
@@ -169,6 +172,7 @@ export class OpenAiResponsesAdapter {
                     invalidContinuationFallbackUsed = true;
                     useContinuation = false;
                     requestBody = prepared.fullBody;
+                    turn.resetContinuation();
                     turn.invalidateWebSocket();
                     credentialReason = 'RECONNECT';
                     await reportFailure(true, {
@@ -637,7 +641,6 @@ class OpenAiResponsesTurnSession {
                 (outputItems.length > 0 || !sawUnrepresentedOutput)) {
                 this.state.lastRequest = prepared.fullBody;
                 this.state.lastResponse = { responseId, outputItems };
-                delete this.state.restoredContinuation;
             }
             else
                 clearResponsesContinuation(this.state);
@@ -660,27 +663,13 @@ class OpenAiResponsesTurnSession {
     resetContinuation() {
         clearResponsesContinuation(this.state);
     }
-    continuationCheckpoint() {
-        if (!responsesPersistedContinuationEnabled(this.adapter.configuration))
-            return undefined;
-        const request = this.state.lastRequest;
-        const response = this.state.lastResponse;
-        if (request === undefined || response === undefined)
-            return this.state.restoredContinuation;
-        const baseline = [...request.input, ...response.outputItems];
-        return {
-            version: 2,
-            protocol: 'OPENAI_RESPONSES',
-            configurationHash: responsesContinuationIdentityHash(this.adapter.configuration),
-            responseId: response.responseId,
-            inputPrefixLength: baseline.length
-        };
-    }
     prepareRequest(request) {
         if (this.adapter.configuration.responsesTransport?.transport === 'WEBSOCKET' &&
             this.state.socket !== undefined &&
-            this.state.socket.readyState !== WebSocket.OPEN)
+            this.state.socket.readyState !== WebSocket.OPEN) {
             invalidateResponsesWebSocket(this.state, false);
+            clearResponsesContinuation(this.state);
+        }
         const fullBody = responsesRequestBody(this.adapter.configuration, request, request.messages, this.adapter.prefixIdentity);
         if (responsesContinuationEnabled(this.adapter.configuration)) {
             const incremental = incrementalResponsesInput(this.state, fullBody);
@@ -743,8 +732,17 @@ class OpenAiResponsesTurnSession {
         const endpoint = webSocketEndpoint(input.configuration.baseUrl);
         const existingSocket = this.state.socket;
         if (existingSocket !== undefined &&
-            (existingSocket.readyState !== WebSocket.OPEN || this.state.endpoint !== endpoint))
+            (existingSocket.readyState !== WebSocket.OPEN || this.state.endpoint !== endpoint)) {
             invalidateResponsesWebSocket(this.state, false);
+            if (input.continuation) {
+                clearResponsesContinuation(this.state);
+                throw localContinuationReset();
+            }
+        }
+        if (input.continuation && this.state.socket === undefined) {
+            clearResponsesContinuation(this.state);
+            throw localContinuationReset();
+        }
         if (this.state.socket === undefined) {
             const handshakeCredential = await acquireResponsesCredential(input.configuration, input.reason);
             input.credentialAcquired(handshakeCredential.revision);
@@ -755,6 +753,10 @@ class OpenAiResponsesTurnSession {
         if (requestCredential.revision !== this.state.credentialRevision ||
             responsesCredentialFingerprint(requestCredential) !== this.state.credentialFingerprint) {
             invalidateResponsesWebSocket(this.state, false);
+            if (input.continuation) {
+                clearResponsesContinuation(this.state);
+                throw localContinuationReset();
+            }
             await this.connectWebSocket(endpoint, requestCredential, input.promptCacheKey, input.signal);
         }
         if (input.signal.aborted) {
@@ -814,6 +816,12 @@ class OpenAiResponsesTurnSession {
         this.state.proxyType = proxyType;
     }
 }
+function localContinuationReset() {
+    return new MarAgentError('MAR_AGENT_RESPONSES_CONTINUATION_RESET', 'The Responses connection changed before the incremental request was sent.');
+}
+function isLocalContinuationReset(error) {
+    return error instanceof MarAgentError && error.code === 'MAR_AGENT_RESPONSES_CONTINUATION_RESET';
+}
 function responsesRequestBody(configuration, request, messages, prefixIdentity = '') {
     const tools = request.allowTools === false
         ? []
@@ -887,13 +895,8 @@ function uuidV5(namespace, value) {
 function incrementalResponsesInput(state, current) {
     const previous = state.lastRequest;
     const completion = state.lastResponse;
-    if (previous === undefined || completion === undefined) {
-        const restored = state.restoredContinuation;
-        if (restored === undefined || current.input.length < restored.inputPrefixLength)
-            return undefined;
-        state.lastResponse = { responseId: restored.responseId, outputItems: [] };
-        return current.input.slice(restored.inputPrefixLength);
-    }
+    if (previous === undefined || completion === undefined)
+        return undefined;
     const baseline = [...previous.input, ...completion.outputItems];
     if (current.input.length < baseline.length)
         return undefined;
@@ -905,25 +908,14 @@ function incrementalResponsesInput(state, current) {
 function clearResponsesContinuation(state) {
     delete state.lastRequest;
     delete state.lastResponse;
-    delete state.restoredContinuation;
 }
 function hashResponsesValue(value) {
     return createHash('sha256').update(JSON.stringify(value)).digest('hex');
 }
-function responsesContinuationIdentityHash(configuration) {
-    return hashResponsesValue({
-        endpoint: new URL(responsesEndpoint(configuration.baseUrl)).toString(),
-        modelId: configuration.modelId,
-        responsesEncoding: configuration.responsesEncoding ?? 'STANDARD'
-    });
-}
 function responsesContinuationEnabled(configuration) {
     return (configuration.responsesPreviousResponseId === true &&
         configuration.responsesTransport?.transport === 'WEBSOCKET');
 }
-function responsesPersistedContinuationEnabled(configuration) {
-    return responsesContinuationEnabled(configuration) && configuration.responsesEncoding !== 'LITE';
-}
 function responsesCredentialFingerprint(credential) {
     return hashResponsesValue({
         bearer: credential.bearer.reveal(),

package/dist/sdk/agent.js

@@ -1,5 +1,6 @@
 import { createHash, randomUUID } from 'node:crypto';
 import { posix } from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
 import { describeMarAgentError, MarAgentError } from '../error.js';
 import { negotiateHost } from '../host/contracts.js';
 import { AnthropicMessagesAdapter, isAnthropicRecoverableStreamError } from '../model/anthropic-messages.js';
@@ -101,7 +102,6 @@ export async function createMarAgent(options) {
             sessionRuntime = {
                 sourceType: sessionSource.type,
                 adapterGeneration: modelGeneration,
-                responsesChain: undefined,
                 adapters: new Map()
             };
             sessionRuntimes.set(sessionId, sessionRuntime);
@@ -133,7 +133,6 @@ export async function createMarAgent(options) {
                 return;
             const retainedByActiveSessions = activeAdaptersExcept(sessionId);
             await closeModelAdapters([...sessionRuntime.adapters.values()].filter((adapter) => !retainedByActiveSessions.has(adapter)));
-            sessionRuntime.responsesChain = undefined;
             sessionRuntime.adapters.clear();
             sessionRuntime.adapterGeneration = generation;
         };
@@ -253,9 +252,17 @@ export async function createMarAgent(options) {
                     const contextRecords = sessionState.contextRecords;
                     const contextualWorldStateGeneration = latestContextualWorldStateGeneration(contextRecords);
                     const restoredContextualWorldState = sessionRuntime.contextualWorldState;
+                    const persistedContextualWorldState = parsePersistedContextualWorldState(await store.readContextualWorldState(sessionId));
                     let contextualWorldState;
-                    if (restoredContextualWorldState === undefined ||
-                        restoredContextualWorldState.generation !== contextualWorldStateGeneration) {
+                    if (restoredContextualWorldState !== undefined &&
+                        restoredContextualWorldState.generation === contextualWorldStateGeneration)
+                        contextualWorldState = restoredContextualWorldState;
+                    else if (persistedContextualWorldState !== undefined &&
+                        persistedContextualWorldState.generation === contextualWorldStateGeneration) {
+                        contextualWorldState = persistedContextualWorldState;
+                        sessionRuntime.contextualWorldState = contextualWorldState;
+                    }
+                    else {
                         contextualWorldState = {
                             generation: contextualWorldStateGeneration,
                             initialized: false,
@@ -265,8 +272,6 @@ export async function createMarAgent(options) {
                         };
                         sessionRuntime.contextualWorldState = contextualWorldState;
                     }
-                    else
-                        contextualWorldState = restoredContextualWorldState;
                     const compactMayContainAgentInstructions = contextRecords.some((record) => compactSummaryFromCheckpoint(record) !== undefined);
                     const compactMayContainRetainedResources = compactHistoryMayContainRetainedResources(contextRecords);
                     const restored = await restoreMessages(store, sessionId, contextRecords, {
@@ -320,8 +325,6 @@ export async function createMarAgent(options) {
                         }));
                     const currentExecutionToolImages = [];
                     let currentExecutionUserIndex;
-                    if (mode === 'compact')
-                        sessionRuntime.responsesChain = undefined;
                     if (mode !== 'compact') {
                         await recordEnvironment();
                         const inputImageMetadata = input.images?.length
@@ -373,9 +376,6 @@ export async function createMarAgent(options) {
                         });
                     selectedAdapter = sessionAdapter(input.modelId ?? executionDefaultModelId, executionModels);
                     const selectedModel = executionModels.get(input.modelId ?? executionDefaultModelId);
-                    const restoredContinuation = latestModelContinuationCheckpoint(contextRecords, selectedModel.id);
-                    if (restoredContinuation !== undefined)
-                        selectedAdapter.restoreContinuation?.(restoredContinuation);
                     if (options.adapterFactory !== undefined &&
                         selectedAdapter.createTurnSession === undefined) {
                         executionScopedAdapters.add(selectedAdapter);
@@ -487,6 +487,7 @@ export async function createMarAgent(options) {
                         };
                     };
                     let currentResourceSnapshot = retainedSessionResourcesSnapshot(await loadRetainedSessionResources());
+                    const previousContextualWorldState = contextualWorldState;
                     contextualWorldState = updateContextualWorldState(contextualWorldState, agentInstructionInsertIndex, {
                         instructionSnapshot: currentInstructionSnapshot,
                         instructionContent: renderAgentInstructions(instructionEntries, compactMayContainAgentInstructions ||
@@ -495,6 +496,8 @@ export async function createMarAgent(options) {
                         previousMayContainResources: compactMayContainRetainedResources
                     });
                     sessionRuntime.contextualWorldState = contextualWorldState;
+                    if (!isDeepStrictEqual(previousContextualWorldState, contextualWorldState))
+                        await persistContextualWorldState(store, sessionId, contextualWorldState);
                     const buildExecutionSystemPrompt = (availableTools = executionTools, promptMode = mode) => buildSystemPrompt({
                         mode: promptMode,
                         platform: description.platform,
@@ -659,14 +662,12 @@ export async function createMarAgent(options) {
                                 }
                                 catch (error) {
                                     if (await recoverModelStream(error, compactionRetryState, operation.signal)) {
-                                        sessionRuntime.responsesChain = undefined;
                                         continue;
                                     }
                                     if (isProviderContextOverflow(error) && usingNativeMessages) {
                                         usingNativeMessages = false;
                                         compactMessages = fallbackMessages();
                                         compactionRetryState.attempts = 0;
-                                        sessionRuntime.responsesChain = undefined;
                                         continue;
                                     }
                                     if (isProviderContextOverflow(error))
@@ -707,7 +708,7 @@ export async function createMarAgent(options) {
                             previousMayContainResources: compactSummary.includes('# Retained Session resources')
                         });
                         sessionRuntime.contextualWorldState = contextualWorldState;
-                        sessionRuntime.responsesChain = undefined;
+                        await persistContextualWorldState(store, sessionId, contextualWorldState);
                         lastServerContextTokens = undefined;
                         lastServerUsage = undefined;
                         await emit({ type: 'context.compacted', compactionId });
@@ -731,7 +732,6 @@ export async function createMarAgent(options) {
                         await appendMailboxMessages();
                         let stop;
                         let sawTool = false;
-                        let responseId;
                         let latestUsage;
                         const pendingTools = [];
                         let incompleteToolCall = false;
@@ -741,27 +741,9 @@ export async function createMarAgent(options) {
                         const systemPrompt = mode === 'compact'
                             ? buildExecutionSystemPrompt(roundTools, 'run')
                             : buildExecutionSystemPrompt(roundTools);
-                        const requestSignature = createHash('sha256')
-                            .update(stableJson({
-                            modelId: selectedModel.id,
-                            systemPrompt,
-                            contextualWorldState: contextualWorldState.entries,
-                            tools: roundTools,
-                            reasoningEffort
-                        }))
-                            .digest('hex');
                         const requestContextMessages = pendingOutputContinuation === undefined
                             ? messages
                             : [...messages, pendingOutputContinuation];
-                        const continuation = selectedModel.responsesPreviousResponseId &&
-                            sessionRuntime.responsesChain?.modelId === selectedModel.id &&
-                            sessionRuntime.responsesChain.requestSignature === requestSignature &&
-                            sessionRuntime.responsesChain.messageCount <= requestContextMessages.length
-                            ? {
-                                previousResponseId: sessionRuntime.responsesChain.responseId,
-                                deltaMessages: requestContextMessages.slice(sessionRuntime.responsesChain.messageCount)
-                            }
-                            : undefined;
                         const modelMessages = mode === 'compact'
                             ? normalizeMessagesForModel(requestContextMessages, { supportsImages: false })
                             : normalizeMessagesForModel(insertContextualWorldState(requestContextMessages, contextualWorldState.entries), {
@@ -808,16 +790,13 @@ export async function createMarAgent(options) {
                                         ? {}
                                         : { allowTools: false }),
                                 promptCacheKey: sessionId,
-                                ...(continuation ? { continuation } : {}),
                                 reasoningEffort,
                                 ...(modelInputImages?.length ? { images: modelInputImages } : {}),
                                 onAttemptDiagnostic: recordModelAttempt(mode === 'compact' ? 'COMPACTION' : 'EXECUTION')
                             })) {
                                 if (event.type !== 'response.started' && event.type !== 'usage')
                                     sawModelSemanticEvent = true;
-                                if (event.type === 'response.started')
-                                    responseId = event.responseId;
-                                else if (event.type === 'response.item') {
+                                if (event.type === 'response.item') {
                                     // Compaction keeps only its successful checkpoint, never intermediate native output.
                                     if (mode === 'compact')
                                         continue;
@@ -955,8 +934,6 @@ export async function createMarAgent(options) {
                         catch (error) {
                             planOutputPrefixes.clear();
                             if (await recoverModelStream(error, modelRetryState, manualCompaction?.signal ?? controller.signal)) {
-                                sessionRuntime.responsesChain = undefined;
-                                responseId = undefined;
                                 finalAnswer = '';
                                 if (mode === 'compact')
                                     messages.splice(roundMessageCount);
@@ -971,16 +948,13 @@ export async function createMarAgent(options) {
                                 !sawModelSemanticEvent &&
                                 isProviderContextOverflow(error) &&
                                 useManualCompactionFallback?.()) {
-                                sessionRuntime.responsesChain = undefined;
                                 modelRetryState.attempts = 0;
-                                responseId = undefined;
                                 finalAnswer = '';
                                 continue;
                             }
                             else if (mode !== 'compact' &&
                                 !sawModelSemanticEvent &&
                                 isProviderContextOverflow(error)) {
-                                sessionRuntime.responsesChain = undefined;
                                 if (!recoveringFromContextOverflow && (await compactContext())) {
                                     modelRetryState.attempts = 0;
                                     recoveringFromContextOverflow = true;
@@ -992,26 +966,6 @@ export async function createMarAgent(options) {
                                 throw error;
                         }
                         recoveringFromContextOverflow = false;
-                        if (selectedModel.responsesPreviousResponseId && responseId)
-                            sessionRuntime.responsesChain = {
-                                modelId: selectedModel.id,
-                                responseId,
-                                requestSignature,
-                                messageCount: messages.length
-                            };
-                        else if (selectedModel.responsesPreviousResponseId)
-                            sessionRuntime.responsesChain = undefined;
-                        const continuationCheckpoint = selected.continuationCheckpoint?.();
-                        if (mode !== 'compact' && continuationCheckpoint !== undefined)
-                            await store.append(sessionId, {
-                                type: 'responses.continuation',
-                                payload: {
-                                    modelId: selectedModel.id,
-                                    checkpoint: continuationCheckpoint
-                                },
-                                executionId,
-                                turnId
-                            });
                         if (pendingTools.length === 0 && mailbox.length > 0) {
                             await appendMailboxMessages();
                             finalAnswer = '';
@@ -1186,7 +1140,6 @@ export async function createMarAgent(options) {
                                 }
                             });
                             if (committed) {
-                                sessionRuntime.responsesChain = undefined;
                                 selected.resetContinuation?.();
                                 const refreshed = await restoreMessages(store, sessionId, committed.records, {
                                     includeImages: true,
@@ -1208,6 +1161,7 @@ export async function createMarAgent(options) {
                                     previousMayContainResources: compactHistoryMayContainRetainedResources(committed.records)
                                 });
                                 sessionRuntime.contextualWorldState = contextualWorldState;
+                                await persistContextualWorldState(store, sessionId, contextualWorldState);
                             }
                         }
                         if (controller.signal.aborted) {
@@ -1402,9 +1356,6 @@ export async function createMarAgent(options) {
                     for (const [modelId, adapter] of runtime.adapters)
                         if (!retainedAdapters.has(adapter))
                             runtime.adapters.delete(modelId);
-                    if (runtime.responsesChain !== undefined &&
-                        !retainedAdapters.has(runtime.adapters.get(runtime.responsesChain.modelId)))
-                        runtime.responsesChain = undefined;
                 }
                 await closeModelAdapters(adapters);
                 if (disposed)
@@ -1572,44 +1523,9 @@ function createModelTurnSession(adapter) {
             }
         },
         resetContinuation: () => turn.resetContinuation?.(),
-        continuationCheckpoint: () => turn.continuationCheckpoint?.(),
         close: () => turn.close()
     };
 }
-function latestModelContinuationCheckpoint(records, modelId) {
-    let checkpoint;
-    for (const record of records) {
-        if (record.type === 'compact.completed' || record.type === 'context.gc.completed') {
-            checkpoint = undefined;
-            continue;
-        }
-        if (record.type !== 'responses.continuation')
-            continue;
-        const payload = record.payload;
-        if (payload === null || typeof payload !== 'object' || Array.isArray(payload))
-            continue;
-        const candidateModelId = payload.modelId;
-        const candidate = payload.checkpoint;
-        if (candidateModelId !== modelId || !isModelContinuationCheckpoint(candidate))
-            continue;
-        checkpoint = candidate;
-    }
-    return checkpoint;
-}
-function isModelContinuationCheckpoint(value) {
-    if (value === null || typeof value !== 'object' || Array.isArray(value))
-        return false;
-    const checkpoint = value;
-    return (checkpoint.version === 2 &&
-        checkpoint.protocol === 'OPENAI_RESPONSES' &&
-        isBoundedString(checkpoint.configurationHash, 64) &&
-        isBoundedString(checkpoint.responseId, 1_024) &&
-        Number.isSafeInteger(checkpoint.inputPrefixLength) &&
-        checkpoint.inputPrefixLength >= 0);
-}
-function isBoundedString(value, maximumLength) {
-    return typeof value === 'string' && value.length > 0 && value.length <= maximumLength;
-}
 function modelAttemptFailureDiagnostic(diagnostic, summary) {
     if (summary === undefined)
         return diagnostic;
@@ -1906,6 +1822,73 @@ function latestContextualWorldStateGeneration(records) {
             generation = record.recordId;
     return generation;
 }
+const MAX_CONTEXTUAL_WORLD_STATE_ENTRIES = 1_024;
+const MAX_CONTEXTUAL_WORLD_STATE_CONTENT_BYTES = 8 * 1024 * 1024;
+function parsePersistedContextualWorldState(payload) {
+    if (payload === null || typeof payload !== 'object' || Array.isArray(payload))
+        return undefined;
+    const record = payload;
+    if (record.version !== 1)
+        return undefined;
+    const generation = record.generation === null
+        ? undefined
+        : typeof record.generation === 'string' && record.generation.length <= 128
+            ? record.generation
+            : null;
+    if (generation === null)
+        return undefined;
+    const instructionSnapshot = nullableWorldStateString(record.instructionSnapshot);
+    const resourceSnapshot = nullableWorldStateString(record.resourceSnapshot);
+    if (instructionSnapshot === null || resourceSnapshot === null || !Array.isArray(record.entries))
+        return undefined;
+    if (record.entries.length > MAX_CONTEXTUAL_WORLD_STATE_ENTRIES)
+        return undefined;
+    const entries = [];
+    let contentBytes = 0;
+    for (const value of record.entries) {
+        if (value === null || typeof value !== 'object' || Array.isArray(value))
+            return undefined;
+        const entry = value;
+        if (!Number.isSafeInteger(entry.index) ||
+            entry.index < 0 ||
+            (entry.kind !== 'instructions' && entry.kind !== 'resources') ||
+            typeof entry.content !== 'string' ||
+            entry.content.length === 0)
+            return undefined;
+        contentBytes += Buffer.byteLength(entry.content);
+        if (contentBytes > MAX_CONTEXTUAL_WORLD_STATE_CONTENT_BYTES)
+            return undefined;
+        entries.push({
+            index: entry.index,
+            kind: entry.kind,
+            content: entry.content
+        });
+    }
+    return {
+        generation,
+        initialized: true,
+        instructionSnapshot,
+        resourceSnapshot,
+        entries
+    };
+}
+function nullableWorldStateString(value) {
+    if (value === null)
+        return undefined;
+    return typeof value === 'string' &&
+        Buffer.byteLength(value) <= MAX_CONTEXTUAL_WORLD_STATE_CONTENT_BYTES
+        ? value
+        : null;
+}
+async function persistContextualWorldState(store, sessionId, state) {
+    await store.writeContextualWorldState(sessionId, {
+        version: 1,
+        generation: state.generation ?? null,
+        instructionSnapshot: state.instructionSnapshot ?? null,
+        resourceSnapshot: state.resourceSnapshot ?? null,
+        entries: state.entries
+    });
+}
 function compactHistoryMayContainRetainedResources(records) {
     return records.some((record) => compactSummaryFromCheckpoint(record)?.includes('# Retained Session resources'));
 }

package/dist/session/jsonl-store.d.ts

@@ -94,6 +94,8 @@ export declare class JsonlSessionStore {
         source?: SessionSource;
     }): Promise<SessionMeta>;
     sessionDirectory(sessionId: string): string;
+    readContextualWorldState(sessionId: string): Promise<unknown | undefined>;
+    writeContextualWorldState(sessionId: string, state: unknown): Promise<void>;
     persistInputImages(sessionId: string, images: readonly SessionInputImage[]): Promise<SessionInputImageMetadata[]>;
     readInputImages(sessionId: string, value: unknown): Promise<RestoredSessionInputImage[]>;
     readInputImage(sessionId: string, input: {

package/dist/session/jsonl-store.js

@@ -12,6 +12,8 @@ const REVERSE_READ_CHUNK_BYTES = 64 * 1024;
 const MAX_INPUT_IMAGES = 5;
 const MAX_INPUT_IMAGE_BYTES = 5 * 1024 * 1024;
 const MAX_INPUT_IMAGES_BYTES = 10 * 1024 * 1024;
+const MAX_CONTEXTUAL_WORLD_STATE_BYTES = 8 * 1024 * 1024;
+const CONTEXTUAL_WORLD_STATE_FILE = 'context-world-state.json';
 const INPUT_IMAGE_MIME_TYPES = new Set(['image/png', 'image/jpeg', 'image/gif', 'image/webp']);
 export class JsonlSessionStore {
     static #instances = new Map();
@@ -54,6 +56,8 @@ export class JsonlSessionStore {
         catch {
             // A missing index starts empty; JSONL remains authoritative for explicit session reads.
         }
+        for (const session of index.sessions)
+            await recoverContextualWorldStateTransactions(root, session);
         return {
             root,
             index,
@@ -157,6 +161,57 @@ export class JsonlSessionStore {
             throw new MarAgentError('MAR_AGENT_SESSION_NOT_FOUND', 'Session was not found.');
         return join(this.#shared.root, 'sessions', sessionId);
     }
+    async readContextualWorldState(sessionId) {
+        const path = join(this.sessionDirectory(sessionId), CONTEXTUAL_WORLD_STATE_FILE);
+        try {
+            const pathInfo = await lstat(path);
+            if (!pathInfo.isFile())
+                return undefined;
+            const file = await open(path, 'r');
+            try {
+                const info = await file.stat();
+                if (!info.isFile() || info.size > MAX_CONTEXTUAL_WORLD_STATE_BYTES)
+                    return undefined;
+                const envelope = JSON.parse(await file.readFile('utf8'));
+                const meta = this.#shared.index.sessions.find((item) => item.id === sessionId);
+                if (envelope.version !== 1 ||
+                    !Number.isSafeInteger(envelope.historySequence) ||
+                    envelope.historySequence < 1 ||
+                    meta === undefined ||
+                    envelope.historySequence >= meta.nextSequence)
+                    return undefined;
+                return envelope.state;
+            }
+            finally {
+                await file.close();
+            }
+        }
+        catch {
+            return undefined;
+        }
+    }
+    async writeContextualWorldState(sessionId, state) {
+        const directory = this.sessionDirectory(sessionId);
+        const meta = this.#shared.index.sessions.find((item) => item.id === sessionId);
+        if (!meta)
+            throw new MarAgentError('MAR_AGENT_SESSION_NOT_FOUND', 'Session was not found.');
+        const path = join(directory, CONTEXTUAL_WORLD_STATE_FILE);
+        const temporary = `${path}.${randomUUID()}.tmp`;
+        const serialized = JSON.stringify({
+            version: 1,
+            historySequence: meta.nextSequence - 1,
+            state
+        });
+        if (Buffer.byteLength(serialized) > MAX_CONTEXTUAL_WORLD_STATE_BYTES)
+            throw new MarAgentError('MAR_AGENT_HOST_LIMIT_EXCEEDED', 'Contextual world state exceeds the storage limit.');
+        try {
+            await writeFile(temporary, serialized, { mode: 0o600, flag: 'wx' });
+            await rename(temporary, path);
+        }
+        finally {
+            await rm(temporary, { force: true });
+        }
+    }
     async persistInputImages(sessionId, images) {
         this.#assertOpen();
         if (images.length === 0)
@@ -373,6 +428,10 @@ export class JsonlSessionStore {
                 .filter((record) => record.type !== 'responses.continuation');
             const staged = await stageRollbackSegments(this.sessionDirectory(sessionId), retained);
             const transactionId = randomUUID();
+            const targetNextSequence = (retained.at(-1)?.sequence ?? 0) + 1;
+            const contextualWorldStatePath = join(this.sessionDirectory(sessionId), CONTEXTUAL_WORLD_STATE_FILE);
+            const contextualWorldStateBackup = `${contextualWorldStatePath}.${targetNextSequence}.${transactionId}.rollback-backup`;
+            let contextualWorldStateStaged = false;
             let generatedTrash = [];
             let inputTrash = [];
             const originalMeta = structuredClone(meta);
@@ -386,6 +445,7 @@ export class JsonlSessionStore {
             const installedPaths = [];
             let committed = false;
             try {
+                contextualWorldStateStaged = await renameIfExists(contextualWorldStatePath, contextualWorldStateBackup);
                 generatedTrash = await stageUnreferencedImages(this.sessionDirectory(sessionId), 'generated_images', new Set(generatedImageFileNames(retained)), transactionId);
                 inputTrash = await stageUnreferencedImages(this.sessionDirectory(sessionId), 'input_images', new Set(inputImageReferencesFromRecords(retained).map((image) => image.fileName)), transactionId);
                 for (const item of backups)
@@ -398,7 +458,7 @@ export class JsonlSessionStore {
                 const completedAt = new Date().toISOString();
                 meta.title = retainedSessionTitle(retained, meta.title);
                 meta.lastActivityAt = completedAt;
-                meta.nextSequence = (retained.at(-1)?.sequence ?? 0) + 1;
+                meta.nextSequence = targetNextSequence;
                 meta.automaticTitlePending = state.automaticTitlePending;
                 meta.resume = state.resume;
                 meta.segments = staged.segments;
@@ -407,6 +467,8 @@ export class JsonlSessionStore {
                 this.#shared.indexDirty = true;
                 await this.#saveIndex();
                 committed = true;
+                if (contextualWorldStateStaged)
+                    await rm(contextualWorldStateBackup, { force: true });
                 await Promise.all([
                     ...backups.map((item) => rm(item.backup, { force: true }).catch(() => undefined)),
                     ...generatedTrash.map((item) => rm(item.trash, { force: true }).catch(() => undefined)),
@@ -425,6 +487,10 @@ export class JsonlSessionStore {
                 if (!committed) {
                     await Promise.all(installedPaths.map((path) => rm(path, { force: true }))).catch(() => undefined);
                     await restoreRenamedFiles(backups.map((item) => ({ from: item.backup, to: item.path })));
+                    if (contextualWorldStateStaged)
+                        await restoreRenamedFiles([
+                            { from: contextualWorldStateBackup, to: contextualWorldStatePath }
+                        ]);
                     await restoreRenamedFiles([...generatedTrash, ...inputTrash]);
                     restoreSessionMeta(meta, originalMeta);
                     this.#shared.index.revision = originalIndexRevision;
@@ -489,6 +555,9 @@ export class JsonlSessionStore {
             ];
             const staged = await stageRollbackSegments(this.sessionDirectory(sessionId), retained);
             const transactionId = randomUUID();
+            const contextualWorldStatePath = join(this.sessionDirectory(sessionId), CONTEXTUAL_WORLD_STATE_FILE);
+            const contextualWorldStateBackup = `${contextualWorldStatePath}.2.${transactionId}.clear-backup`;
+            let contextualWorldStateStaged = false;
             let generatedTrash = [];
             let inputTrash = [];
             const originalMeta = structuredClone(meta);
@@ -502,6 +571,7 @@ export class JsonlSessionStore {
             const installedPaths = [];
             let committed = false;
             try {
+                contextualWorldStateStaged = await renameIfExists(contextualWorldStatePath, contextualWorldStateBackup);
                 generatedTrash = await stageUnreferencedImages(this.sessionDirectory(sessionId), 'generated_images', new Set(), transactionId);
                 inputTrash = await stageUnreferencedImages(this.sessionDirectory(sessionId), 'input_images', new Set(), transactionId);
                 for (const item of backups)
@@ -519,6 +589,8 @@ export class JsonlSessionStore {
                 this.#shared.indexDirty = true;
                 await this.#saveIndex();
                 committed = true;
+                if (contextualWorldStateStaged)
+                    await rm(contextualWorldStateBackup, { force: true });
                 await Promise.all([
                     ...backups.map((item) => rm(item.backup, { force: true }).catch(() => undefined)),
                     ...generatedTrash.map((item) => rm(item.trash, { force: true }).catch(() => undefined)),
@@ -537,6 +609,10 @@ export class JsonlSessionStore {
                 if (!committed) {
                     await Promise.all(installedPaths.map((path) => rm(path, { force: true }))).catch(() => undefined);
                     await restoreRenamedFiles(backups.map((item) => ({ from: item.backup, to: item.path })));
+                    if (contextualWorldStateStaged)
+                        await restoreRenamedFiles([
+                            { from: contextualWorldStateBackup, to: contextualWorldStatePath }
+                        ]);
                     await restoreRenamedFiles([...generatedTrash, ...inputTrash]);
                     restoreSessionMeta(meta, originalMeta);
                     this.#shared.index.revision = originalIndexRevision;
@@ -1072,6 +1148,49 @@ async function sessionDirectoryExists(path) {
         throw error;
     }
 }
+async function renameIfExists(from, to) {
+    try {
+        await rename(from, to);
+        return true;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+}
+async function recoverContextualWorldStateTransactions(root, meta) {
+    const directory = join(root, 'sessions', meta.id);
+    let names;
+    try {
+        names = await readdir(directory);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return;
+        throw error;
+    }
+    const pattern = /^context-world-state\.json\.(\d+)\.[0-9a-f-]+\.(?:rollback|clear)-backup$/u;
+    const backups = names.filter((name) => pattern.test(name));
+    if (backups.length === 0)
+        return;
+    const eventNames = names.filter((name) => /^events-\d{6}\.jsonl$/u.test(name)).sort();
+    const latestEventName = eventNames.at(-1);
+    if (latestEventName === undefined)
+        throw new MarAgentError('MAR_AGENT_SESSION_CORRUPT', 'Session history is corrupt.');
+    const latestRecords = await readRecords(join(directory, latestEventName));
+    const actualNextSequence = (latestRecords.at(-1)?.sequence ?? 0) + 1;
+    const canonical = join(directory, CONTEXTUAL_WORLD_STATE_FILE);
+    for (const name of backups) {
+        const match = pattern.exec(name);
+        const backup = join(directory, name);
+        const targetNextSequence = Number(match[1]);
+        if (actualNextSequence === targetNextSequence || (await sessionDirectoryExists(canonical)))
+            await rm(backup, { force: true });
+        else
+            await rename(backup, canonical);
+    }
+}
 function generatedImageFileNames(records) {
     const names = new Set();
     for (const record of records) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@myagentroam/agent",
-  "version": "0.9.86",
+  "version": "0.9.87",
   "description": "Embeddable MAR coding agent SDK and CLI.",
   "license": "Apache-2.0",
   "type": "module",