@myagentroam/agent 0.11.13 → 0.11.15

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

@@ -7,7 +7,7 @@ import { negotiateHost } from '../host/contracts.js';
 import { toolCallers } from '../tools/callers.js';
 import { AnthropicMessagesAdapter } from '../model/anthropic-messages.js';
 import { OpenAiResponsesAdapter } from '../model/openai-responses.js';
-import { JsonlSessionStore } from '../session/store/index.js';
+import { JsonlSessionStore } from '../session/store/jsonl-store.js';
 /** Validate models before Host negotiation and expose only built-in protocol adapters. */
 export async function createMarAgent(options) {
     if (Object.hasOwn(options, 'adapterFactory'))
@@ -23,7 +23,10 @@ export async function createMarAgentWithAdapter(options) {
     const description = negotiateHost(await options.host.describe());
     if (description.mode !== options.mode)
         throw new MarAgentError('MAR_AGENT_HOST_INCOMPATIBLE', 'Host mode does not match Agent mode.');
-    const store = await JsonlSessionStore.open(description.homeDirectory);
+    if (options.sessionStore === null)
+        throw new MarAgentError('MAR_AGENT_SESSION_STORE_INVALID', 'Session store must not be null.');
+    const ownsStore = options.sessionStore === undefined;
+    const store = options.sessionStore ?? (await JsonlSessionStore.open(description.homeDirectory));
     const active = new Map();
     const activeExecutionAdapters = new Set();
     const executionResults = new Map();
@@ -59,7 +62,7 @@ export async function createMarAgentWithAdapter(options) {
         }
         return pending;
     };
-    let reconfiguring = false;
+    let reconfiguration;
     const createAdapter = (modelId, configuredModels = models) => {
         const configuration = configuredModels.get(modelId);
         if (!configuration)
@@ -193,44 +196,73 @@ export async function createMarAgentWithAdapter(options) {
         assertSessionAdmission,
         assertCanStart: (sessionId) => {
             assertSessionAdmission(sessionId);
-            if (reconfiguring)
+            if (reconfiguration)
                 throw new MarAgentError('MAR_AGENT_EXECUTION_ACTIVE', 'Models are being reconfigured for the next execution.');
         }
     });
     return {
         extensionDiagnostics: () => extensions.diagnostics(),
-        createSession: async (input) => openSession((await store.createSession(input)).id, input.workspace),
+        createSession: async (input) => {
+            assertSessionAdmission();
+            return openSession((await store.createSession(input)).id, input.workspace);
+        },
         openSession: (id) => openSession(id),
-        listSessions: (input) => store.list(input),
-        getSession: (id) => store.getSession(id),
-        setSessionTitle: (id, title, input) => store.updateTitle(id, title, { ...input, automatic: input?.automatic ?? false }, sessionWriterOwner),
+        listSessions: async (input) => {
+            assertSessionAdmission();
+            return store.list(input);
+        },
+        getSession: async (id) => {
+            assertSessionAdmission();
+            return store.getSession(id);
+        },
+        setSessionTitle: async (id, title, input) => {
+            assertSessionAdmission();
+            return store.updateTitle(id, title, { ...input, automatic: input?.automatic ?? false }, sessionWriterOwner);
+        },
         clearSession: (id) => trackSessionLifecycle(id, 'clear', async () => {
             const runtime = sessionRuntimes.get(id);
             if ([...active.keys()].some((key) => key.startsWith(`${id}:`)))
                 throw new MarAgentError('MAR_AGENT_EXECUTION_ACTIVE', 'A session cannot be cleared while an execution is active.');
-            await extensions.endSession(id, 'clear');
-            extensions.retireSession(id);
-            await completeAgentCleanup([
-                () => extensions.clearSession(id),
-                () => runtime?.inputs?.retire(),
-                () => runtime?.subagents?.dispose(),
-                () => closeModelAdapters(runtime === undefined ? [] : [...runtime.adapters.values()]),
-                () => {
-                    // Existing SDK Session handles share this runtime and remain usable after clear.
-                    if (runtime) {
-                        runtime.adapters.clear();
-                        runtime.adapterGeneration = modelGeneration;
-                        delete runtime.todo;
-                        delete runtime.subagents;
-                        delete runtime.subagentsOpening;
-                        delete runtime.contextualWorldState;
-                        delete runtime.inputs;
-                        delete runtime.requestSnapshots;
-                    }
-                },
-                () => options.host.disposeSessionResources?.(id),
-                () => store.clearSession(id)
-            ]);
+            const maintenance = await store.acquireSessionMaintenance(id, 'clear', sessionWriterOwner);
+            let failed = false;
+            try {
+                await completeAgentCleanup([
+                    () => extensions.endSession(id, 'clear'),
+                    () => extensions.retireSession(id),
+                    () => extensions.clearSession(id),
+                    () => runtime?.inputs?.retire(),
+                    () => runtime?.subagents?.dispose(),
+                    () => closeModelAdapters(runtime === undefined ? [] : [...runtime.adapters.values()]),
+                    () => {
+                        // Existing SDK Session handles share this runtime and remain usable after clear.
+                        if (runtime) {
+                            runtime.adapters.clear();
+                            runtime.adapterGeneration = modelGeneration;
+                            delete runtime.todo;
+                            delete runtime.subagents;
+                            delete runtime.subagentsOpening;
+                            delete runtime.contextualWorldState;
+                            delete runtime.inputs;
+                            delete runtime.requestSnapshots;
+                        }
+                    },
+                    () => options.host.disposeSessionResources?.(id),
+                    () => store.clearSession(id, maintenance)
+                ]);
+            }
+            catch (error) {
+                failed = true;
+                throw error;
+            }
+            finally {
+                try {
+                    await maintenance.release();
+                }
+                catch (error) {
+                    if (!failed)
+                        throw error;
+                }
+            }
         }),
         setSystemInstruction: (systemInstruction) => {
             if (disposed)
@@ -243,7 +275,7 @@ export async function createMarAgentWithAdapter(options) {
         reconfigureModels: async (input) => {
             if (disposed)
                 throw new MarAgentError('MAR_AGENT_DISPOSED', 'Agent is disposed.');
-            if (reconfiguring)
+            if (reconfiguration)
                 throw new MarAgentError('MAR_AGENT_EXECUTION_ACTIVE', 'Models are already being reconfigured for the next execution.');
             const next = resolveAgentModels(input.models, input.defaultModelId);
             const activeSessions = activeSessionIds();
@@ -255,7 +287,10 @@ export async function createMarAgentWithAdapter(options) {
                     for (const adapter of runtime.adapters.values())
                         activeAdapters.add(adapter);
             const inactiveRuntimes = [...sessionRuntimes].flatMap(([sessionId, runtime]) => activeSessions.has(sessionId) ? [] : [runtime]);
-            reconfiguring = true;
+            const completion = Promise.withResolvers();
+            reconfiguration = completion.promise;
+            void completion.promise.catch(() => undefined);
+            let interruptedByDisposal = false;
             try {
                 const reconfigurationCommits = new Map();
                 for (const runtime of inactiveRuntimes)
@@ -277,8 +312,10 @@ export async function createMarAgentWithAdapter(options) {
                             runtime.adapters.delete(modelId);
                 }
                 await closeModelAdapters(adapters);
-                if (disposed)
+                if (disposed) {
+                    interruptedByDisposal = true;
                     throw new MarAgentError('MAR_AGENT_DISPOSED', 'Agent is disposed.');
+                }
                 for (const commit of reconfigurationCommits.values())
                     commit();
                 models = next.models;
@@ -296,41 +333,79 @@ export async function createMarAgentWithAdapter(options) {
                     for (const adapter of runtime.adapters.values())
                         addModelCredentialProviders(liveProviders, adapter.configuration);
                 const obsoleteProviders = [...credentialProviders].filter((provider) => !liveProviders.has(provider));
-                const providerCloseResults = await Promise.allSettled(obsoleteProviders.map((provider) => provider.close()));
+                const providerCloseResults = await Promise.allSettled(obsoleteProviders.map(async (provider) => provider.close()));
                 for (const [index, result] of providerCloseResults.entries())
                     if (result.status === 'fulfilled')
                         credentialProviders.delete(obsoleteProviders[index]);
             }
+            catch (error) {
+                if (!interruptedByDisposal)
+                    completion.reject(error);
+                throw error;
+            }
             finally {
-                reconfiguring = false;
+                completion.resolve();
+                if (reconfiguration === completion.promise)
+                    reconfiguration = undefined;
             }
         },
         deleteSession: (id) => trackSessionLifecycle(id, 'delete', async () => {
-            const sessionIds = await store.sessionTree(id);
-            const sessionIdSet = new Set(sessionIds);
-            const executionKeys = [...active.keys()].filter((key) => sessionIdSet.has(key.slice(0, key.indexOf(':'))));
-            for (const key of executionKeys)
-                active.get(key)?.abort();
-            await Promise.all(sessionIds.map((sessionId) => extensions.endSession(sessionId, 'other', false)));
-            for (const sessionId of sessionIds)
-                extensions.retireSession(sessionId);
-            const runtimes = sessionIds.flatMap((sessionId) => {
-                const runtime = sessionRuntimes.get(sessionId);
-                sessionRuntimes.delete(sessionId);
-                return runtime === undefined ? [] : [runtime];
-            });
-            await completeAgentCleanup([
-                ...sessionIds.map((sessionId) => () => extensions.clearSession(sessionId)),
-                ...runtimes.map((runtime) => () => runtime.inputs?.retire()),
-                ...runtimes.map((runtime) => () => runtime.subagents?.dispose()),
-                () => Promise.allSettled(executionKeys.flatMap((key) => {
-                    const result = executionResults.get(key);
-                    return result === undefined ? [] : [result];
-                })),
-                () => closeModelAdapters(runtimes.flatMap((runtime) => [...runtime.adapters.values()])),
-                ...sessionIds.map((sessionId) => () => options.host.disposeSessionResources?.(sessionId)),
-                () => store.delete(id)
-            ]);
+            const maintenance = await store.acquireSessionMaintenance(id, 'delete', sessionWriterOwner);
+            let failed = false;
+            try {
+                const sessionIds = maintenance.sessionIds;
+                const sessionIdSet = new Set(sessionIds);
+                const executionKeys = [...active.keys()].filter((key) => sessionIdSet.has(key.slice(0, key.indexOf(':'))));
+                for (const key of executionKeys)
+                    active.get(key)?.abort();
+                const runtimes = sessionIds.flatMap((sessionId) => {
+                    const runtime = sessionRuntimes.get(sessionId);
+                    return runtime === undefined ? [] : [runtime];
+                });
+                await completeAgentCleanup([
+                    async () => {
+                        let failure;
+                        await Promise.all(sessionIds.map(async (sessionId) => {
+                            try {
+                                await extensions.endSession(sessionId, 'other', false);
+                            }
+                            catch (error) {
+                                failure ??= { error };
+                            }
+                        }));
+                        if (failure)
+                            throw failure.error;
+                    },
+                    ...sessionIds.map((sessionId) => () => extensions.retireSession(sessionId)),
+                    () => {
+                        for (const sessionId of sessionIds)
+                            sessionRuntimes.delete(sessionId);
+                    },
+                    ...sessionIds.map((sessionId) => () => extensions.clearSession(sessionId)),
+                    ...runtimes.map((runtime) => () => runtime.inputs?.retire()),
+                    ...runtimes.map((runtime) => () => runtime.subagents?.dispose()),
+                    () => Promise.allSettled(executionKeys.flatMap((key) => {
+                        const result = executionResults.get(key);
+                        return result === undefined ? [] : [result];
+                    })),
+                    () => closeModelAdapters(runtimes.flatMap((runtime) => [...runtime.adapters.values()])),
+                    ...sessionIds.map((sessionId) => () => options.host.disposeSessionResources?.(sessionId)),
+                    () => store.delete(id, maintenance)
+                ]);
+            }
+            catch (error) {
+                failed = true;
+                throw error;
+            }
+            finally {
+                try {
+                    await maintenance.release();
+                }
+                catch (error) {
+                    if (!failed)
+                        throw error;
+                }
+            }
         }),
         dispose: () => {
             if (disposal)
@@ -342,6 +417,7 @@ export async function createMarAgentWithAdapter(options) {
             const extensionDisposal = extensions.dispose();
             void extensionDisposal.catch(() => undefined);
             const runtimes = [...sessionRuntimes.values()];
+            const pendingReconfiguration = reconfiguration;
             disposal = completeAgentCleanup([
                 async () => {
                     const results = await Promise.allSettled([...sessionLifecycles.values()].map(({ pending }) => pending));
@@ -353,10 +429,11 @@ export async function createMarAgentWithAdapter(options) {
                 ...runtimes.map((runtime) => () => runtime.inputs?.retire()),
                 ...runtimes.map((runtime) => () => runtime.subagents?.dispose()),
                 () => Promise.allSettled([...executionResults.values()]),
+                () => pendingReconfiguration,
                 () => closeModelAdapters(runtimes.flatMap((runtime) => [...runtime.adapters.values()])),
-                ...[...credentialProviders].map((provider) => () => provider.close()),
+                () => completeAgentCleanup([...credentialProviders].map((provider) => () => provider.close())),
                 () => options.host.dispose(),
-                () => store.close()
+                () => (ownsStore ? store.close() : undefined)
             ]);
             return disposal;
         }

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

@@ -1,3 +1,4 @@
+import type { SessionStore } from '../session/store/contracts.js';
 import type { ContextualWorldState } from '../runtime/context/world-state.js';
 import type { ResolvedModelConfiguration } from './model-runtime.js';
 import { ExecutionToolSources } from './extension-tools.js';
@@ -10,7 +11,6 @@ import type { HostDescription, MarAgentHost } from '../host/contracts.js';
 import type { MarAgentReasoningEffort } from '../model/configuration.js';
 import type { ModelAdapter, ModelMessage } from '../model/contracts.js';
 import { CompactRequests } from '../runtime/compaction/requests.js';
-import { JsonlSessionStore } from '../session/store/index.js';
 import { SubagentSessionController, type SubagentMailboxMessage, type SubagentMessageDelivery, type SubagentTurnHandle } from '../subagent/session-controller.js';
 import { createSessionToolScheduler } from '../tools/scheduler.js';
 import { TodoStore } from '../tools/agent/todo.js';
@@ -75,7 +75,7 @@ interface SessionServices {
     readonly host: MarAgentHost;
     readonly description: HostDescription;
     readonly settings: Pick<CreateMarAgentOptions, 'workspaceMapping' | 'systemInstruction'>;
-    readonly store: JsonlSessionStore;
+    readonly store: SessionStore;
     readonly extensions: ExtensionManager;
     readonly registry: AgentSessionRegistry;
     readonly hasCustomAdapters: boolean;
@@ -87,7 +87,7 @@ interface SessionServices {
     readonly createAdapter: (modelId: string, models: ReadonlyMap<string, ResolvedModelConfiguration>) => ModelAdapter;
     readonly activeAdaptersExcept: (sessionId: string) => ReadonlySet<ModelAdapter>;
     readonly assertCanStart: (sessionId?: string) => void;
-    readonly assertSessionAdmission: (sessionId: string) => void;
+    readonly assertSessionAdmission: (sessionId?: string) => void;
 }
 /** SDK Session orchestration owns warm resources; Runtime owns only the model/tool loop. */
 export declare function createSessionOpener(services: SessionServices): (sessionId: string, workspace?: string) => Promise<InternalMarAgentSession>;

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

@@ -45,7 +45,7 @@ import { AGENT_EXECUTION_POLICY } from '../runtime/execution-policy.js';
 import { loadAgentInstructions, renderAgentInstructions } from '../runtime/context/instructions.js';
 import { normalizeMessagesForModel } from '../runtime/context/normalize.js';
 import { latestSmartContextTokens, requestSmartCompaction } from '../runtime/compaction/smart.js';
-import { compactSummaryFromCheckpoint, inputMetadataFromRecord } from '../session/store/index.js';
+import { compactSummaryFromCheckpoint, inputMetadataFromRecord } from '../session/store/execution-state.js';
 import { SubagentSessionController } from '../subagent/session-controller.js';
 import { agentStartToolDefinitionWithModels } from '../tools/agent/agent-start.js';
 import { allowsDirectTool, allowsToolCaller, toolCallers } from '../tools/callers.js';
@@ -59,7 +59,9 @@ export function createSessionOpener(services) {
     const { host, description, settings, store, createAdapter, activeAdaptersExcept } = services;
     const { active, activeExecutionAdapters, executionResults, sessionRuntimes, sessionWriterOwner } = services.registry;
     const openSession = async (sessionId, workspace) => {
+        services.assertSessionAdmission();
         const storedSession = await store.getSession(sessionId);
+        services.assertSessionAdmission();
         const storedWorkspace = storedSession.workspace;
         const sessionSource = storedSession.source;
         const logicalWorkspace = settings.workspaceMapping?.logicalPath ?? workspace ?? storedWorkspace ?? '';

package/dist/agent-core/sdk/subagent-backend.d.ts

@@ -1,3 +1,3 @@
-import type { JsonlSessionStore } from '../session/store/index.js';
+import type { SessionStore } from '../session/store/contracts.js';
 import type { SubagentSessionControllerBackend } from '../subagent/session-controller.js';
-export declare function createSubagentBackend(store: JsonlSessionStore, workspace: string): SubagentSessionControllerBackend;
+export declare function createSubagentBackend(store: SessionStore, workspace: string): SubagentSessionControllerBackend;

package/dist/agent-core/sdk/types.d.ts

@@ -1,8 +1,8 @@
 import type { MarAgentHost } from '../host/contracts.js';
 import type { CoreExtensionSource, CoreRuntimeExtension } from '../extensions/contracts.js';
 import type { MarAgentModelConfiguration } from '../model/configuration.js';
-import type { ExecutionResult, RolloutBudgetOptions, RunInput } from '../runtime/contracts.js';
-import type { MarAgentEvent } from '../runtime/events.js';
+import type { RolloutBudgetOptions, RunInput } from '../runtime/contracts.js';
+import type { CompactInput, ExecutionHandle } from '../runtime/execution-handle.js';
 import type { MarAgentSessionPage, MarAgentSessionSummary } from '../session/catalog.js';
 import type { SessionListInput, SessionSource, SessionTitleUpdateInput } from '../session/types.js';
 export interface CreateSessionInput {
@@ -13,17 +13,8 @@ export type { SessionTitleUpdateInput } from '../session/types.js';
 export type { HostExecutionExtensions, HostSessionResourceSnapshot, HostSkill, MarAgentHost } from '../host/contracts.js';
 export type { AccessMode, ExecutionMode, ExecutionResult, MarAgentImageMetadata, RolloutBudgetOptions, RunInput, RunInputImage } from '../runtime/contracts.js';
 export type { MarAgentEvent, MarAgentEventBase } from '../runtime/events.js';
+export type { CompactInput, ExecutionHandle } from '../runtime/execution-handle.js';
 export type { CodeCellEventData, MarAgentToolArtifact, MarAgentToolImageArtifact, McpCatalogTool, McpToolCallContext, McpToolCatalog, McpToolCatalogContext, ToolCall, ToolExecutionContext, ToolExecutionResult } from '../tools/contracts.js';
-/** A live execution exposes streamed events separately from its terminal result. */
-export interface ExecutionHandle extends AsyncIterable<MarAgentEvent> {
-    readonly executionId: string;
-    result(): Promise<ExecutionResult>;
-    /** Signals abort; await result() to observe the terminal status and cleanup. */
-    cancel(): void;
-}
-export type CompactInput = Partial<RunInput> & {
-    readonly async?: boolean;
-};
 export interface SteerInput {
     readonly expectedExecutionId: string;
     readonly prompt: string;
@@ -68,10 +59,12 @@ export interface MarAgent {
         readonly defaultModelId?: string;
     }): Promise<void>;
     deleteSession(sessionId: string): Promise<void>;
-    /** Cancels active executions, then closes SDK-owned providers, the Host and the Session store. */
+    /** Joins executions/reconfiguration, closes owned resources, and releases borrowed Store leases. */
     dispose(): Promise<void>;
 }
 export interface CreateMarAgentOptions {
+    /** Ready-to-use borrowed Store. The caller closes it after all Agent/Catalog users finish. */
+    sessionStore?: import('../session/store/contracts.js').SessionStore;
     mode: 'normal' | 'node';
     host: MarAgentHost;
     models: readonly MarAgentModelConfiguration[];

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

@@ -1,5 +1,6 @@
 import type { MarAgentImageMetadata } from '../runtime/contracts.js';
 import type { MarAgentEvent } from '../runtime/events.js';
+import type { SessionStore } from './store/contracts.js';
 import type { SessionListInput, SessionSource } from './types.js';
 export interface MarAgentSessionSummary {
     id: string;
@@ -84,7 +85,12 @@ export interface MarAgentSessionCatalog {
     delete(sessionId: string): Promise<MarAgentSessionDeleteResult>;
     close(): Promise<void>;
 }
-export declare function openMarAgentSessionCatalog(input: {
+export type OpenMarAgentSessionCatalogInput = {
     homeDirectory: string;
-}): Promise<MarAgentSessionCatalog>;
+    sessionStore?: never;
+} | {
+    sessionStore: SessionStore;
+    homeDirectory?: never;
+};
+export declare function openMarAgentSessionCatalog(input: OpenMarAgentSessionCatalogInput): Promise<MarAgentSessionCatalog>;
 export declare function imageMetadata(value: unknown): MarAgentHistoryImageMetadata[];

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

@@ -1,15 +1,35 @@
 import { MarAgentError } from '../error.js';
 import { publicHostedToolEvents } from '../runtime/event-projection.js';
-import { JsonlSessionStore } from './store/index.js';
+import { JsonlSessionStore } from './store/jsonl-store.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 async function openMarAgentSessionCatalog(input) {
-    const store = await JsonlSessionStore.open(input.homeDirectory);
+    const borrowed = input.sessionStore !== undefined;
+    if (input.sessionStore === null ||
+        borrowed === (input.homeDirectory !== undefined) ||
+        (!borrowed && (typeof input.homeDirectory !== 'string' || !input.homeDirectory)))
+        throw new MarAgentError('MAR_AGENT_SESSION_STORE_INVALID', 'Specify exactly one Session store or home directory.');
+    const store = input.sessionStore ?? (await JsonlSessionStore.open(input.homeDirectory));
+    let closure;
+    const assertOpen = () => {
+        if (closure)
+            throw new MarAgentError('MAR_AGENT_DISPOSED', 'Session catalog is closed.');
+    };
     return {
-        list: (options) => store.list(options),
-        firstUserMessagePreview: (sessionId) => store.firstUserMessagePreview(sessionId),
-        executionConfiguration: (sessionId) => store.executionConfiguration(sessionId),
+        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 }),
@@ -72,6 +92,7 @@ export async function openMarAgentSessionCatalog(input) {
             };
         },
         readImage: async (sessionId, input) => {
+            assertOpen();
             const image = await store.readInputImage(sessionId, input);
             return image === undefined
                 ? undefined
@@ -82,8 +103,12 @@ export async function openMarAgentSessionCatalog(input) {
                     dataBase64: image.dataBase64
                 };
         },
-        readToolResultResource: (sessionId, input) => store.readToolResultResource(sessionId, input),
+        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 (!isMarAgentEvent(record.payload))
@@ -101,13 +126,26 @@ export async function openMarAgentSessionCatalog(input) {
             return undefined;
         },
         fork: async (sessionId, options) => {
+            assertOpen();
             const session = await store.forkSession(sessionId, options);
             return { ...session, source: session.source ?? { type: 'user' } };
         },
-        rollback: (sessionId, options) => store.rollbackSession(sessionId, options),
-        clear: (sessionId) => store.clearSession(sessionId),
-        delete: (sessionId) => store.delete(sessionId),
-        close: () => store.close()
+        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) {

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

@@ -143,9 +143,11 @@ export interface ContextGcCheckpointPayload extends ContextGcCheckpointDraft {
 /** Disposable memoization for one evaluation's immutable record snapshot. */
 export declare class ContextGcCheckpointCache {
     #private;
-    read(records: readonly SessionRecord[], boundarySequence?: number, workspace?: string): ReturnType<typeof latestValidContextGcCheckpoint>;
+    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;
@@ -154,7 +156,7 @@ 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, _workspace?: string): {
+export declare function latestValidContextGcCheckpoint(records: readonly SessionRecord[], boundarySequence?: number): {
     readonly record: SessionRecord;
     readonly payload: ContextGcCheckpointPayload;
 } | undefined;

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

@@ -9,20 +9,28 @@ export const CONTEXT_GC_MAX_TARGETS = 4_096;
 /** Disposable memoization for one evaluation's immutable record snapshot. */
 export class ContextGcCheckpointCache {
     #snapshot;
-    read(records, boundarySequence = records.at(-1)?.sequence ?? 0, workspace) {
+    read(records, boundarySequence = records.at(-1)?.sequence ?? 0) {
         const cached = this.#snapshot;
-        if (cached?.records === records &&
-            cached.boundarySequence === boundarySequence &&
-            cached.workspace === workspace)
+        if (cached?.records === records && cached.boundarySequence === boundarySequence)
             return cached.value;
-        const value = latestValidContextGcCheckpoint(records, boundarySequence, workspace);
-        this.#snapshot = { records, boundarySequence, workspace, value };
+        const value = latestValidContextGcCheckpoint(records, boundarySequence);
+        this.#snapshot = { records, boundarySequence, value };
         return value;
     }
 }
 export function contextGcMinimumUsageGrowth(contextWindowTokens) {
     return Math.max(2_000, Math.floor(contextWindowTokens * 0.05));
 }
+/** Compare adjacent checkpoint triggers only within the same model/window scope. */
+export function contextGcCheckpointIntervalEligible(trigger, previous) {
+    if (!previous ||
+        trigger.modelId !== previous.modelId ||
+        trigger.contextWindowTokens !== previous.contextWindowTokens)
+        return true;
+    return (trigger.normalRolloutOrdinal - previous.normalRolloutOrdinal >= 2 &&
+        trigger.contextInputTokens - previous.contextInputTokens >=
+            contextGcMinimumUsageGrowth(trigger.contextWindowTokens));
+}
 export function contextGcLogicalPathKey(path, workspace, platform) {
     if (!path || !workspace || path.includes('\0') || workspace.includes('\0'))
         return undefined;
@@ -198,7 +206,7 @@ export function validateContextGcCheckpoint(records, record, workspace = session
     }
     return payload;
 }
-export function latestValidContextGcCheckpoint(records, boundarySequence = records.at(-1)?.sequence ?? 0, _workspace) {
+export function latestValidContextGcCheckpoint(records, boundarySequence = records.at(-1)?.sequence ?? 0) {
     const base = contextGcBaseFromRecords(records, boundarySequence);
     if (!base)
         return undefined;