@myagentroam/agent 0.11.12 → 0.11.14

package/dist/agent-core/runtime/compaction/retained-context.js

@@ -1,4 +1,4 @@
-import { parseModelInputMetadata } from '../../session/store/index.js';
+import { parseModelInputMetadata } from '../../session/store/execution-state.js';
 import { restoreModelContext } from '../context/projection.js';
 /** Use a public native identity, never private context text, as the visible boundary. */
 export function compactSnapshotAnchor(messages, sources) {

package/dist/agent-core/runtime/compaction/smart.d.ts

@@ -1,5 +1,5 @@
 import type { ModelMessage } from '../../model/contracts.js';
-import { type SessionRecord } from '../../session/store/index.js';
+import type { SessionRecord } from '../../session/store/contracts.js';
 export declare const SMART_COMPACTION_MARKER = "<mar_runtime>\n  <smart_compaction>For this message only, smart_compact may be considered at a clear transition into sustained new work, when the previous phase is largely complete and its details have low continuation value.</smart_compaction>\n</mar_runtime>";
 export interface SmartCompactionInput {
     readonly recordId: string;

package/dist/agent-core/runtime/compaction/smart.js

@@ -1,5 +1,5 @@
 import { MarAgentError } from '../../error.js';
-import { compactSummaryFromCheckpoint } from '../../session/store/index.js';
+import { compactSummaryFromCheckpoint } from '../../session/store/execution-state.js';
 export const SMART_COMPACTION_MARKER = '<mar_runtime>\n  <smart_compaction>For this message only, smart_compact may be considered at a clear transition into sustained new work, when the previous phase is largely complete and its details have low continuation value.</smart_compaction>\n</mar_runtime>';
 /** A measured watermark, not the stricter native-request budget calibration. */
 export function latestSmartContextTokens(records, modelId, contextWindowTokens) {

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

@@ -1,9 +1,9 @@
 import type { ClientToolDefinition, ModelUsage } from '../../model/contracts.js';
 import { type ContextGcPlatform } from '../../session/context-gc-checkpoint.js';
-import { JsonlSessionStore, type SessionRecord } from '../../session/store/index.js';
+import type { SessionStore, SessionRecord } from '../../session/store/contracts.js';
 import { type ContextProjection } from './projection.js';
 export interface ContextGcRuntimeInput {
-    readonly store: JsonlSessionStore;
+    readonly store: SessionStore;
     readonly sessionId: string;
     readonly records?: readonly SessionRecord[];
     readonly system: string;

package/dist/agent-core/runtime/context/projection.js

@@ -1,6 +1,6 @@
 import { restoreNativeModelContext } from '../../model/native-context.js';
 import { appliedInputRecord } from '../../session/deferred-input.js';
-import { inputMetadataFromRecord } from '../../session/store/index.js';
+import { inputMetadataFromRecord } from '../../session/store/execution-state.js';
 import { contextGcTargetKey, latestValidContextGcCheckpoint } from '../../session/context-gc-checkpoint.js';
 import { TOOL_EXECUTION_LIMITS } from '../../tools/execution-limits.js';
 import { replaceReadContextItems } from '../../tools/local/read-context.js';

package/dist/agent-core/runtime/context/restore.d.ts

@@ -1,8 +1,9 @@
+import type { SessionStore } from '../../session/store/contracts.js';
 import type { ModelMessage } from '../../model/contracts.js';
-import { type CompactUserInput, type JsonlSessionStore } from '../../session/store/index.js';
+import type { CompactUserInput } from '../../session/store/contracts.js';
 import type { EnvironmentContextState } from './contracts.js';
 import { type ContextProjection } from './projection.js';
-export declare function restoreMessages(store: JsonlSessionStore, sessionId: string, records: readonly import('../../session/store/index.js').SessionRecord[], options: {
+export declare function restoreMessages(store: SessionStore, sessionId: string, records: readonly import('../../session/store/index.js').SessionRecord[], options: {
     includeImages: boolean;
     strictImages?: boolean;
     currentTurnId?: string;

package/dist/agent-core/runtime/context/restore.js

@@ -1,6 +1,6 @@
 import { MarAgentError } from '../../error.js';
 import { appliedInputRecord, pendingDeferredInputs } from '../../session/deferred-input.js';
-import { compactSummaryFromCheckpoint, replacementHistoryFromCheckpoint, inputMetadataFromRecord } from '../../session/store/index.js';
+import { compactSummaryFromCheckpoint, replacementHistoryFromCheckpoint, inputMetadataFromRecord } from '../../session/store/execution-state.js';
 import { compactedHistoryMessages, continuationMessage } from '../compaction/history.js';
 import { restoreCompactTail } from '../compaction/retained-context.js';
 import { environmentContextUpdate, restoreEnvironmentState } from './environment.js';

package/dist/agent-core/runtime/context/usage.js

@@ -1,6 +1,6 @@
 import { isDeepStrictEqual } from 'node:util';
 import { marAgentReasoningEffortSchema } from '../../model/configuration.js';
-import { compactSummaryFromCheckpoint } from '../../session/store/index.js';
+import { compactSummaryFromCheckpoint } from '../../session/store/execution-state.js';
 import { estimatedRequestTokens } from './request-budget.js';
 export function latestModelUsage(records, selectedModelId) {
     let usage;

package/dist/agent-core/runtime/context/world-state.d.ts

@@ -19,7 +19,7 @@ export declare function insertContextualWorldState(messages: readonly ModelMessa
 export declare function latestContextualWorldStateGeneration(records: readonly import('../../session/store/index.js').SessionRecord[]): string | undefined;
 export declare function updatePromptWorldState(state: ContextualWorldState, index: number, parts: readonly ContextualPart[]): ContextualWorldState;
 export declare function parsePersistedContextualWorldState(payload: unknown): ContextualWorldState | undefined;
-export declare function persistContextualWorldState(store: import('../../session/store/index.js').JsonlSessionStore, sessionId: string, state: ContextualWorldState): Promise<void>;
+export declare function persistContextualWorldState(store: import('../../session/store/contracts.js').SessionStore, sessionId: string, state: ContextualWorldState): Promise<void>;
 export declare function updateContextualWorldState(state: ContextualWorldState, index: number, current: {
     instructionSnapshot: string | undefined;
     instructionContent: string | undefined;

package/dist/agent-core/runtime/context/world-state.js

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 import { MarAgentError } from '../../error.js';
 import { contextualBlock, contextualChanges } from './contextual-blocks.js';
-import { compactSummaryFromCheckpoint } from '../../session/store/index.js';
+import { compactSummaryFromCheckpoint } from '../../session/store/execution-state.js';
 export function insertContextualWorldState(messages, entries) {
     const result = [...messages];
     // Entries can be restored before the latest user after Compact. Sort anchors,

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,17 +196,29 @@ 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}:`)))
@@ -243,7 +258,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 +270,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 +295,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,13 +316,20 @@ 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 () => {
@@ -342,6 +369,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 +381,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 ?? '';
@@ -297,6 +299,7 @@ export function createSessionOpener(services) {
                 const operation = emitTail.then(async () => {
                     assertLive?.();
                     const persistent = eventForPersistence(full);
+                    let committedTerminal = false;
                     if (persistent !== undefined && releaseSession !== undefined) {
                         const stored = await store.append(sessionId, {
                             type: full.type,
@@ -307,7 +310,7 @@ export function createSessionOpener(services) {
                         if (full.type === 'execution.completed' ||
                             full.type === 'execution.failed' ||
                             full.type === 'execution.cancelled')
-                            persistedTerminal = true;
+                            committedTerminal = persistedTerminal = true;
                         if (full.type === 'message.completed') {
                             const message = liveModelMessages.findLast((item) => item.role === 'assistant' && item.content === full.text);
                             if (message)
@@ -316,8 +319,30 @@ export function createSessionOpener(services) {
                     }
                     queue.push(full);
                     compactRequests.publish(full);
-                    if (internal.publishHostEvents !== false)
-                        await host.emit(full);
+                    if (internal.publishHostEvents !== false) {
+                        try {
+                            await host.emit(full);
+                        }
+                        catch (error) {
+                            if (!committedTerminal)
+                                throw error;
+                            // Host observation cannot rewrite a terminal already committed to the Store.
+                            try {
+                                // Host errors may contain private data; publish only SDK-owned facts.
+                                process.emitWarning(new MarAgentError('MAR_AGENT_HOST_EVENT_PUBLICATION_FAILED', `Host publication of ${full.type} failed for Execution ${executionId}.`, {
+                                    details: {
+                                        sessionId,
+                                        executionId,
+                                        eventId: full.eventId,
+                                        eventType: full.type
+                                    }
+                                }));
+                            }
+                            catch {
+                                // A diagnostic sink must not change the committed outcome either.
+                            }
+                        }
+                    }
                 });
                 emitTail = operation.catch(() => undefined);
                 return operation;

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

@@ -68,10 +68,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/store/contracts.d.ts

@@ -0,0 +1,140 @@
+import type { CoreCheckpoint, CoreJsonValue } from '../../extensions/data.js';
+import type { ModelMessage, ModelUsage } from '../../model/contracts.js';
+import type { EnvironmentContextState } from '../../runtime/context/contracts.js';
+import type { CodeModeStateEntry } from '../../tools/code-mode/state.js';
+import type { AvailableToolResultResource } from '../../tools/result-extensions.js';
+import type { MarAgentSessionPage, MarAgentSessionSummary } from '../catalog.js';
+import type { ContextGcCheckpointDraft } from '../context-gc-checkpoint.js';
+import type { ToolResultResourceInput, ToolResultResourcePage } from '../tool-result-resources.js';
+import type { SessionListInput, SessionSource, SessionTitleUpdateInput } from '../types.js';
+import type { CompactHistoryMessage, RestoredSessionInputImage, SessionExecutionState, SessionInputImage, SessionInputImageData, SessionInputImageMetadata, SessionRecord } from './types.js';
+export type { CompactHistoryMessage, CompactUserInput, RestoredSessionInputImage, SessionExecutionState, SessionInputImage, SessionInputImageData, SessionInputImageMetadata, SessionRecord } from './types.js';
+export type { CodeModeStateEntry } from '../../tools/code-mode/state.js';
+export type { TodoSnapshot, TodoItem } from '../../tools/contracts.js';
+export type { CodeToolCallRecord, CodeObservation } from '../../tools/code-mode/observations.js';
+export type { ModelMessage, ModelUsage, ModelInputMetadata, ModelTextBlock, ModelContextualBlock } from '../../model/contracts.js';
+export type { EnvironmentContextState } from '../../runtime/context/contracts.js';
+export type { ContextGcCheckpointDraft, ContextGcBase, ContextGcPlatform, ContextGcEconomicsPolicy, ContextGcMetrics, ContextGcReplacement, ContextGcTarget, ContextGcReadItemReplacement } from '../context-gc-checkpoint.js';
+export type { ContextGcWebToolName } from '../context-gc-replacements.js';
+export type { ContextGcSubagentToolName } from '../context-gc-subagent.js';
+export type { AvailableToolResultResource } from '../../tools/result-extensions.js';
+/** Logical Session identity, without a physical index or recovery layout. */
+export interface SessionStoreSession {
+    id: string;
+    title: string;
+    workspace: string;
+    createdAt: string;
+    lastActivityAt: string;
+    source?: SessionSource | undefined;
+}
+export interface SessionRecordInput {
+    type: string;
+    payload: unknown;
+    executionId?: string;
+    turnId?: string;
+    timestamp?: string;
+}
+export interface SessionStoreCompactInput {
+    summary: string;
+    replacementHistory?: readonly CompactHistoryMessage[];
+    retainedModelContext?: readonly ModelMessage[];
+    pendingInputs?: readonly SessionRecord[];
+    snapshotRecordId?: string;
+    snapshotMessageCount?: number;
+    environment?: EnvironmentContextState;
+    automatic?: boolean;
+    modelId?: string;
+    contextWindowTokens?: number;
+    usage?: ModelUsage;
+    executionId?: string;
+    turnId?: string;
+}
+/**
+ * Session persistence port. Implementations preserve record order, committed-resource
+ * visibility and the existing per-Session writer/checkpoint atomic boundaries.
+ * Owned handles are closed by their creator; injected instances are borrowed.
+ */
+export interface SessionStore {
+    createSession(input: {
+        title?: string;
+        workspace: string;
+        source?: SessionSource;
+    }): Promise<SessionStoreSession>;
+    getSession(sessionId: string): Promise<MarAgentSessionSummary & {
+        automaticTitlePending: boolean;
+    }>;
+    list(input?: SessionListInput): Promise<MarAgentSessionPage>;
+    listSubagentChildren(parentSessionId: string): Promise<Array<MarAgentSessionSummary & {
+        source: Extract<SessionSource, {
+            type: 'subagent';
+        }>;
+    }>>;
+    executionConfiguration(sessionId: string): Promise<{
+        readonly modelId: string;
+        readonly modelName?: string;
+        readonly reasoningEffort?: string;
+    } | undefined>;
+    firstUserMessagePreview(sessionId: string): Promise<string | undefined>;
+    sessionTree(sessionId: string): Promise<readonly string[]>;
+    updateTitle(sessionId: string, title: string, input?: SessionTitleUpdateInput, owner?: object): Promise<boolean>;
+    append(sessionId: string, input: SessionRecordInput, options?: {
+        readonly signal?: AbortSignal;
+    }): Promise<SessionRecord>;
+    read(sessionId: string): Promise<SessionRecord[]>;
+    readPage(sessionId: string, input?: {
+        limit?: number;
+        beforeSequence?: number;
+    }): Promise<{
+        records: SessionRecord[];
+        previousBeforeSequence?: number;
+    }>;
+    readExecutionState(sessionId: string): Promise<SessionExecutionState>;
+    userTurnCount(sessionId: string): Promise<number>;
+    readContextualWorldState(sessionId: string): Promise<unknown | undefined>;
+    writeContextualWorldState(sessionId: string, state: unknown): Promise<void>;
+    readCodeModeState(sessionId: string): Promise<CodeModeStateEntry[]>;
+    commitCodeModeState(sessionId: string, mutations: unknown, input: {
+        readonly executionId: string;
+        readonly turnId: string;
+        readonly expectedState?: readonly CodeModeStateEntry[];
+    }): Promise<CodeModeStateEntry[]>;
+    readExtensionCheckpoint(sessionId: string, extensionId: string, key: string): Promise<CoreCheckpoint>;
+    writeExtensionCheckpoint(sessionId: string, extensionId: string, key: string, value: CoreJsonValue | undefined, expectedRevision: number | undefined, input: {
+        owner: object;
+        signal: AbortSignal;
+        executionId?: string;
+        turnId?: string;
+    }): Promise<CoreCheckpoint>;
+    compact(sessionId: string, input: SessionStoreCompactInput, options?: {
+        readonly signal?: AbortSignal;
+    }): Promise<SessionRecord>;
+    commitContextGc(sessionId: string, draft: ContextGcCheckpointDraft, planningRecords?: readonly SessionRecord[]): Promise<SessionRecord>;
+    persistInputImages(sessionId: string, images: readonly SessionInputImage[]): Promise<SessionInputImageMetadata[]>;
+    readInputImages(sessionId: string, value: unknown): Promise<RestoredSessionInputImage[]>;
+    readInputImage(sessionId: string, input: {
+        readonly sequence: number;
+        readonly imageIndex: number;
+    }): Promise<SessionInputImageData | undefined>;
+    writeToolResultResource(sessionId: string, text: string): Promise<AvailableToolResultResource>;
+    readToolResultResource(sessionId: string, input: ToolResultResourceInput): Promise<ToolResultResourcePage>;
+    /** One main Execution per Session; an owner may reuse its healthy retained writer. */
+    acquireSessionLease(sessionId: string, owner?: object): Promise<() => Promise<void>>;
+    /** Native writes join the same owner's writer, without admitting another Execution. */
+    acquireSessionWriteLease(sessionId: string, owner: object): Promise<() => Promise<void>>;
+    /** Retention requires the originating owner to hold an active Execution lease. */
+    retainSessionLease(sessionId: string, owner: object): Promise<() => Promise<void>>;
+    hasRetainedSessionLease(sessionId: string, owner: object): boolean;
+    forkSession(sessionId: string, input: {
+        readonly boundaryTurnId: string | null;
+        readonly title: string;
+    }): Promise<SessionStoreSession>;
+    rollbackSession(sessionId: string, input: {
+        readonly boundaryTurnId: string | null;
+    }): Promise<MarAgentSessionSummary>;
+    clearSession(sessionId: string): Promise<MarAgentSessionSummary>;
+    delete(sessionId: string): Promise<{
+        readonly deleted: boolean;
+    }>;
+    /** Stop using the handle and release its leases before closing it. Never preempts other owners. */
+    close(): Promise<void>;
+}

package/dist/agent-core/session/store/contracts.js

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

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

@@ -1,20 +1,12 @@
+import type { SessionStore, SessionRecordInput, SessionStoreCompactInput } from './contracts.js';
 import { type CoreCheckpoint, type CoreJsonValue } from '../../extensions/data.js';
-import type { ModelMessage, ModelUsage } from '../../model/contracts.js';
-import type { EnvironmentContextState } from '../../runtime/context/contracts.js';
 import { type CodeModeStateEntry } from '../../tools/code-mode/state.js';
 import { type ContextGcCheckpointDraft } from '../context-gc-checkpoint.js';
 import { type ToolResultResourceInput } from '../tool-result-resources.js';
 import type { SessionListInput, SessionSource, SessionTitleUpdateInput } from '../types.js';
-import type { CompactHistoryMessage, RestoredSessionInputImage, SessionExecutionState, SessionInputImage, SessionInputImageData, SessionInputImageMetadata, SessionMeta, SessionRecord } from './types.js';
-interface SessionRecordInput {
-    type: string;
-    payload: unknown;
-    executionId?: string;
-    turnId?: string;
-    timestamp?: string;
-}
+import type { RestoredSessionInputImage, SessionExecutionState, SessionInputImage, SessionInputImageData, SessionInputImageMetadata, SessionMeta, SessionRecord } from './types.js';
 /** SDK-owned JSONL history with per-HOME in-process sharing and cross-process file locks. */
-export declare class JsonlSessionStore {
+export declare class JsonlSessionStore implements SessionStore {
     #private;
     private constructor();
     static open(home: string): Promise<JsonlSessionStore>;
@@ -110,21 +102,7 @@ export declare class JsonlSessionStore {
         records: SessionRecord[];
         previousBeforeSequence?: number;
     }>;
-    compact(sessionId: string, input: {
-        summary: string;
-        replacementHistory?: readonly CompactHistoryMessage[];
-        retainedModelContext?: readonly ModelMessage[];
-        pendingInputs?: readonly SessionRecord[];
-        snapshotRecordId?: string;
-        snapshotMessageCount?: number;
-        environment?: EnvironmentContextState;
-        automatic?: boolean;
-        modelId?: string;
-        contextWindowTokens?: number;
-        usage?: ModelUsage;
-        executionId?: string;
-        turnId?: string;
-    }, options?: {
+    compact(sessionId: string, input: SessionStoreCompactInput, options?: {
         readonly signal?: AbortSignal;
     }): Promise<SessionRecord>;
     /** A warm cell retains physical writer ownership between Executions of the same Agent. */
@@ -183,4 +161,3 @@ export declare class JsonlSessionStore {
     }>;
     close(): Promise<void>;
 }
-export {};

package/dist/index.d.ts

@@ -41,6 +41,8 @@ export type { CoreProcessesApi, CoreProcessesBackend, CoreProcessInput, CoreProc
 export type { CreateMarAgentOptions, CreateSessionInput, ExecutionHandle, CompactInput, SteerInput, SteerResult, MarAgent, MarAgentSession, SessionTitleUpdateInput } from './agent-core/sdk/types.js';
 export { openMarAgentSessionCatalog, type MarAgentContextUsage, type MarAgentHistoryEntry, type MarAgentHistoryPage, type MarAgentSessionCatalog, type MarAgentSessionDeleteResult, type MarAgentSessionImage, type MarAgentSessionPage, type MarAgentSessionSummary } from './agent-core/session/catalog.js';
 export type { SessionListInput, SessionSource } from './agent-core/session/types.js';
+export type { SessionStore, SessionStoreSession, SessionRecordInput, SessionStoreCompactInput, SessionRecord, SessionExecutionState, CompactHistoryMessage, CompactUserInput, SessionInputImage, SessionInputImageMetadata, SessionInputImageData, RestoredSessionInputImage, CodeModeStateEntry, TodoSnapshot, TodoItem, CodeToolCallRecord, CodeObservation, ModelMessage, ModelUsage, ModelInputMetadata, ModelTextBlock, ModelContextualBlock, EnvironmentContextState, ContextGcCheckpointDraft, ContextGcBase, ContextGcPlatform, ContextGcEconomicsPolicy, ContextGcMetrics, ContextGcReplacement, ContextGcTarget, ContextGcReadItemReplacement, ContextGcWebToolName, ContextGcSubagentToolName, AvailableToolResultResource } from './agent-core/session/store/contracts.js';
+export type { OpenMarAgentSessionCatalogInput } from './agent-core/session/catalog.js';
 export type { ApplyPatchFileResult, ApplyPatchResult, ApplyPatchPartialResult, ClientToolDefinition, MarAgentToolArtifact, MarAgentToolImageArtifact, McpCatalogTool, McpToolCallContext, McpToolCatalog, McpToolCatalogContext, ToolCall, ToolCaller, ToolExecutionContext, ToolExecutionResult } from './agent-core/tools/contracts.js';
 export { MCP_DEFINITION_LIMITS, assertMcpToolCatalog, assertMcpToolDefinition } from './agent-core/tools/mcp/catalog.js';
 export type { WorkspacePathMount } from './agent-core/tools/shared/path-resolver.js';

package/package.json

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