@myagentroam/agent 0.11.13 → 0.11.15

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

@@ -0,0 +1,148 @@
+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;
+}
+/** Store-issued ownership spanning SDK cleanup and the final durable mutation. */
+export interface SessionStoreMaintenance {
+    readonly sessionIds: readonly string[];
+    /** Idempotent; releases maintenance only, never another owner's Execution/retained references. */
+    release(): Promise<void>;
+}
+/**
+ * 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;
+    /** Conflicts fail before cleanup; delete includes the Store's current Session tree. */
+    acquireSessionMaintenance(sessionId: string, kind: 'clear' | 'delete', owner?: object): Promise<SessionStoreMaintenance>;
+    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, maintenance?: SessionStoreMaintenance): Promise<MarAgentSessionSummary>;
+    delete(sessionId: string, maintenance?: SessionStoreMaintenance): 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/execution-state.js

@@ -1,5 +1,4 @@
 import { todoItemsFromSnapshot } from '../../tools/agent/todo.js';
-import { contextGcBaseSequence, latestValidContextGcCheckpoint } from '../context-gc-checkpoint.js';
 export function deriveExecutionState(records) {
     let automaticTitle = false;
     let sawUserTurn = false;
@@ -36,7 +35,6 @@ export function deriveExecutionState(records) {
             executionModel = candidate;
     }
     const boundary = records.findLastIndex(isCompactCheckpoint);
-    const checkpoint = latestValidContextGcCheckpoint(records);
     return {
         automaticTitlePending: automaticTitle && !sawUserTurn,
         todo: { revision: todoRevision, items: todoItems },
@@ -45,13 +43,6 @@ export function deriveExecutionState(records) {
             version: 1,
             userTurns,
             ...(compactSequence === undefined ? {} : { compactSequence }),
-            ...(checkpoint === undefined
-                ? {}
-                : {
-                    gcSequence: checkpoint.record.sequence,
-                    gcGeneration: checkpoint.payload.generation,
-                    gcBaseSequence: contextGcBaseSequence(checkpoint.payload.base)
-                }),
             ...(todoSequence === undefined ? {} : { todoSequence }),
             todoRevision,
             executionModelIndexed: true,
@@ -170,9 +161,6 @@ export function sameResumeIndex(left, right) {
     return (left?.version === right.version &&
         left.userTurns === right.userTurns &&
         left.compactSequence === right.compactSequence &&
-        left.gcSequence === right.gcSequence &&
-        left.gcGeneration === right.gcGeneration &&
-        left.gcBaseSequence === right.gcBaseSequence &&
         left.todoSequence === right.todoSequence &&
         left.todoRevision === right.todoRevision &&
         left.executionModelIndexed === right.executionModelIndexed &&

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

@@ -1,24 +1,15 @@
+import type { SessionStore, SessionStoreMaintenance, 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>;
-    /** Append the durable creation record before making this Session visible in the index. */
     createSession(input: {
         title?: string;
         workspace: string;
@@ -65,7 +56,7 @@ export declare class JsonlSessionStore {
     }>;
     updateTitle(sessionId: string, title: string, input?: SessionTitleUpdateInput, owner?: object): Promise<boolean>;
     /** Reset history with the same recovery journal while preserving the Session identity. */
-    clearSession(sessionId: string): Promise<{
+    clearSession(sessionId: string, maintenance?: SessionStoreMaintenance): Promise<{
         id: string;
         title: string;
         workspace: string;
@@ -110,26 +101,13 @@ 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. */
     acquireSessionLease(sessionId: string, owner?: object): Promise<() => Promise<void>>;
     hasRetainedSessionLease(sessionId: string, owner: object): boolean;
+    acquireSessionMaintenance(sessionId: string, kind: 'clear' | 'delete', owner?: object): Promise<SessionStoreMaintenance>;
     /** Native writes join their Agent's sole writer, without admitting another Execution. */
     acquireSessionWriteLease(sessionId: string, owner: object): Promise<() => Promise<void>>;
     retainSessionLease(sessionId: string, owner: object): Promise<() => Promise<void>>;
@@ -178,9 +156,8 @@ export declare class JsonlSessionStore {
     /** Counts native input records, not the post-Compact model context. */
     userTurnCount(sessionId: string): Promise<number>;
     firstUserMessagePreview(sessionId: string): Promise<string | undefined>;
-    delete(sessionId: string): Promise<{
+    delete(sessionId: string, maintenance?: SessionStoreMaintenance): Promise<{
         readonly deleted: boolean;
     }>;
     close(): Promise<void>;
 }
-export {};

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

@@ -7,7 +7,7 @@ import { cloneCoreJson } from '../../extensions/data.js';
 import { acquireFileLock } from '../../storage/file-lock.js';
 import { todoItemsFromSnapshot } from '../../tools/agent/todo.js';
 import { applyCodeModeStateMutations, parseCodeModeStateMutations, restoreCodeModeState } from '../../tools/code-mode/state.js';
-import { contextGcBaseFromRecords, contextGcBaseSequence, contextGcMinimumUsageGrowth, latestValidContextGcCheckpoint, normalizeContextGcReplacements, parseContextGcCheckpoint, sameContextGcBase, validateContextGcCheckpoint } from '../context-gc-checkpoint.js';
+import { contextGcBaseFromRecords, contextGcCheckpointIntervalEligible, latestValidContextGcCheckpoint, normalizeContextGcReplacements, sameContextGcBase, validateContextGcCheckpoint } from '../context-gc-checkpoint.js';
 import { bindToolResultResources, cleanupUnreferencedToolResources, completeToolResultResources, copyToolResultResources, readToolResultResource, toolResultResourceFiles, writeToolResultResource } from '../tool-result-resources.js';
 import { beginSessionStorageTransaction, isUnjournaledTransactionFile, recoverSessionStorageTransaction } from '../transaction-recovery.js';
 import { extensionCheckpointFromPayload, indexExtensionCheckpoint, restoreExtensionCheckpoint, updateSessionCurrentState } from './current-state.js';
@@ -23,6 +23,7 @@ export class JsonlSessionStore {
     static #instances = new Map();
     static #opening = new Map();
     #shared;
+    #maintenance = new WeakMap();
     #leaseClosed = false;
     constructor(shared) {
         this.#shared = shared;
@@ -283,9 +284,22 @@ export class JsonlSessionStore {
         }
         return { directory, release };
     }
-    /** Append the durable creation record before making this Session visible in the index. */
     async createSession(input) {
         this.#assertOpen();
+        const source = normalizeSessionSource(input.source);
+        if (source.type !== 'subagent')
+            return this.#createSession(input, source);
+        // Publish under the parent's existing serial domain so tree admission cannot miss a child.
+        return this.#serializeRecordOperation(source.parentSessionId, async () => {
+            this.#assertOpen();
+            if (this.#shared.writerLeases.get(source.parentSessionId)?.maintenance)
+                throw new MarAgentError('MAR_AGENT_SESSION_LOCKED', 'Session is under maintenance.');
+            await this.getSession(source.parentSessionId);
+            return this.#createSession(input, source);
+        });
+    }
+    /** Append the durable creation record before making this Session visible in the index. */
+    async #createSession(input, source) {
         const id = randomUUID();
         const now = new Date().toISOString();
         const meta = {
@@ -294,7 +308,7 @@ export class JsonlSessionStore {
             workspace: input.workspace,
             createdAt: now,
             lastActivityAt: now,
-            source: normalizeSessionSource(input.source),
+            source,
             nextSequence: 1,
             automaticTitlePending: input.title === undefined,
             resume: {
@@ -697,9 +711,11 @@ export class JsonlSessionStore {
         }
     }
     /** Reset history with the same recovery journal while preserving the Session identity. */
-    async clearSession(sessionId) {
+    async clearSession(sessionId, maintenance) {
         this.#assertOpen();
-        const release = await this.acquireSessionLease(sessionId);
+        const holding = maintenance ?? (await this.acquireSessionMaintenance(sessionId, 'clear'));
+        this.#assertMaintenance(sessionId, 'clear', holding);
+        let failed = false;
         try {
             const meta = this.#shared.index.sessions.find((item) => item.id === sessionId);
             if (!meta)
@@ -726,8 +742,18 @@ export class JsonlSessionStore {
             ];
             return await this.#replaceHistory(meta, retained, { kind: 'clear', clearedAt });
         }
+        catch (error) {
+            failed = true;
+            throw error;
+        }
         finally {
-            await release();
+            if (!maintenance) {
+                const releasing = holding.release();
+                if (failed)
+                    await releasing.catch(() => undefined);
+                else
+                    await releasing;
+            }
         }
     }
     /** Called only while rollback or clear holds the maintenance lease. */
@@ -1123,14 +1149,9 @@ export class JsonlSessionStore {
                 records.at(-1)?.sessionId !== sessionId ||
                 !sameContextGcBase(contextGcBaseFromRecords(records, boundarySequence), draft.base))
                 throw new MarAgentError('MAR_AGENT_SESSION_CORRUPT', 'Context GC planning boundary is invalid.');
-            const previous = latestValidContextGcCheckpoint(records, boundarySequence, meta.workspace);
-            if (previous) {
-                const minimumUsageGrowth = contextGcMinimumUsageGrowth(draft.trigger.contextWindowTokens);
-                if (draft.trigger.normalRolloutOrdinal - previous.payload.trigger.normalRolloutOrdinal < 2 ||
-                    draft.trigger.contextInputTokens - previous.payload.trigger.contextInputTokens <
-                        minimumUsageGrowth)
-                    throw new MarAgentError('MAR_AGENT_SESSION_CORRUPT', 'Context GC checkpoint interval validation failed.');
-            }
+            const previous = latestValidContextGcCheckpoint(records, boundarySequence);
+            if (!contextGcCheckpointIntervalEligible(draft.trigger, previous?.payload.trigger))
+                throw new MarAgentError('MAR_AGENT_SESSION_CORRUPT', 'Context GC checkpoint interval validation failed.');
             const plannedReplacements = normalizeContextGcReplacements(draft.replacements);
             if (!plannedReplacements || plannedReplacements.length === 0)
                 throw new MarAgentError('MAR_AGENT_SESSION_CORRUPT', 'Context GC checkpoint must contain a replacement.');
@@ -1236,7 +1257,7 @@ export class JsonlSessionStore {
             this.#assertOpen();
             let lease = this.#shared.writerLeases.get(sessionId);
             if (lease) {
-                if (lease.executing || owner === undefined || lease.owner !== owner)
+                if (lease.maintenance || lease.executing || owner === undefined || lease.owner !== owner)
                     throw new MarAgentError('MAR_AGENT_SESSION_LOCKED', 'Session already has a writer.');
                 if (lease.appendFailure)
                     throw lease.appendFailure.error;
@@ -1262,12 +1283,89 @@ export class JsonlSessionStore {
         const lease = this.#shared.writerLeases.get(sessionId);
         return lease?.owner === owner && lease.retained > 0;
     }
+    async acquireSessionMaintenance(sessionId, kind, owner) {
+        this.#assertOpen();
+        const acquired = new Map();
+        let sessionIds = [];
+        let released = false;
+        const holding = Object.freeze({
+            get sessionIds() {
+                return sessionIds;
+            },
+            release: async () => {
+                if (released)
+                    return;
+                released = true;
+                this.#maintenance.delete(holding);
+                let failure;
+                for (const [id, writer] of [...acquired].reverse()) {
+                    try {
+                        await this.#serializeRecordOperation(id, async () => {
+                            delete writer.maintenance;
+                            await this.#releaseUnusedWriter(id, writer);
+                        });
+                    }
+                    catch (error) {
+                        failure ??= { error };
+                    }
+                }
+                if (failure)
+                    throw failure.error;
+            }
+        });
+        try {
+            // Re-read membership after acquiring writers; never hand the SDK a pre-lock tree snapshot.
+            for (;;) {
+                const tree = kind === 'delete' ? await this.sessionTree(sessionId) : [sessionId];
+                for (const id of tree.toReversed()) {
+                    if (acquired.has(id))
+                        continue;
+                    await this.#serializeRecordOperation(id, async () => {
+                        this.#assertOpen();
+                        let writer = this.#shared.writerLeases.get(id);
+                        if (writer &&
+                            (writer.maintenance ||
+                                owner === undefined ||
+                                writer.owner !== owner ||
+                                (kind === 'clear' && writer.executing)))
+                            throw new MarAgentError('MAR_AGENT_SESSION_LOCKED', 'Session already has a writer.');
+                        if (!writer) {
+                            // Deleting a stale index entry must not recreate its missing directory.
+                            const release = kind === 'delete' && !(await sessionDirectoryExists(this.#sessionDirectory(id)))
+                                ? async () => { }
+                                : await this.#acquireSessionLease(id);
+                            writer = { owner, executing: false, retained: 0, release };
+                            this.#shared.writerLeases.set(id, writer);
+                        }
+                        writer.maintenance = holding;
+                        acquired.set(id, writer);
+                    });
+                }
+                const current = kind === 'clear' ? tree : await this.sessionTree(sessionId);
+                if (current.every((id) => acquired.has(id))) {
+                    sessionIds = Object.freeze(current);
+                    break;
+                }
+            }
+            this.#maintenance.set(holding, { sessionId, kind });
+            return holding;
+        }
+        catch (error) {
+            await holding.release().catch(() => undefined);
+            throw error;
+        }
+    }
+    #assertMaintenance(sessionId, kind, holding) {
+        const current = this.#maintenance.get(holding);
+        if (current?.sessionId !== sessionId || current.kind !== kind)
+            throw new MarAgentError('MAR_AGENT_SESSION_LOCKED', 'Session maintenance ownership is invalid.');
+    }
     /** Native writes join their Agent's sole writer, without admitting another Execution. */
     async acquireSessionWriteLease(sessionId, owner) {
         return this.#serializeRecordOperation(sessionId, async () => {
             this.#assertOpen();
             let lease = this.#shared.writerLeases.get(sessionId);
-            if (lease && lease.owner !== owner)
+            if (lease && (lease.maintenance || lease.owner !== owner))
                 throw new MarAgentError('MAR_AGENT_SESSION_LOCKED', 'Session already has a writer.');
             if (lease?.appendFailure)
                 throw lease.appendFailure.error;
@@ -1291,7 +1389,7 @@ export class JsonlSessionStore {
     async retainSessionLease(sessionId, owner) {
         return this.#serializeRecordOperation(sessionId, async () => {
             const lease = this.#shared.writerLeases.get(sessionId);
-            if (!lease || !lease.executing || lease.owner !== owner)
+            if (!lease || lease.maintenance || !lease.executing || lease.owner !== owner)
                 throw new MarAgentError('MAR_AGENT_SESSION_LOCKED', 'Retained work requires its originating Session writer.');
             lease.retained++;
             let released = false;
@@ -1305,7 +1403,7 @@ export class JsonlSessionStore {
         });
     }
     async #releaseUnusedWriter(sessionId, lease) {
-        if (lease.executing || lease.retained)
+        if (lease.maintenance || lease.executing || lease.retained)
             return;
         try {
             await lease.release();
@@ -1472,20 +1570,8 @@ export class JsonlSessionStore {
             else
                 resume.reasoningEffort = executionModel.reasoningEffort;
         }
-        if (isCompactCheckpoint(record)) {
+        if (isCompactCheckpoint(record))
             resume.compactSequence = record.sequence;
-            delete resume.gcSequence;
-            delete resume.gcGeneration;
-            delete resume.gcBaseSequence;
-        }
-        else {
-            const checkpoint = parseContextGcCheckpoint(record);
-            if (checkpoint) {
-                resume.gcSequence = record.sequence;
-                resume.gcGeneration = checkpoint.generation;
-                resume.gcBaseSequence = contextGcBaseSequence(checkpoint.base);
-            }
-        }
         if (record.type !== 'todo.updated' || !todoItemsFromSnapshot(record.payload))
             return;
         resume.todoSequence = record.sequence;
@@ -1723,22 +1809,12 @@ export class JsonlSessionStore {
             throw error;
         }
     }
-    async delete(sessionId) {
+    async delete(sessionId, maintenance) {
         this.#assertOpen();
-        await this.#refreshIndex();
-        const tree = sessionTreeIds(this.#shared.index.sessions, sessionId);
-        if (tree.length === 0)
-            throw new MarAgentError('MAR_AGENT_SESSION_NOT_FOUND', 'Session was not found.');
-        const releases = [];
-        try {
-            for (const id of tree.toReversed())
-                if (await sessionDirectoryExists(join(this.#shared.root, 'sessions', id)))
-                    releases.push(await this.acquireSessionLease(id));
-        }
-        catch (error) {
-            await Promise.allSettled(releases.toReversed().map((release) => release()));
-            throw error;
-        }
+        const holding = maintenance ?? (await this.acquireSessionMaintenance(sessionId, 'delete'));
+        this.#assertMaintenance(sessionId, 'delete', holding);
+        const tree = holding.sessionIds;
+        let failed = false;
         try {
             const deleted = await sessionDirectoryExists(join(this.#shared.root, 'sessions', sessionId));
             for (const id of tree.toReversed()) {
@@ -1751,8 +1827,18 @@ export class JsonlSessionStore {
             await this.#saveIndex(tree);
             return { deleted };
         }
+        catch (error) {
+            failed = true;
+            throw error;
+        }
         finally {
-            await Promise.allSettled(releases.toReversed().map((release) => release()));
+            if (!maintenance) {
+                const releasing = holding.release();
+                if (failed)
+                    await releasing.catch(() => undefined);
+                else
+                    await releasing;
+            }
         }
     }
     #assertOpen() {

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

@@ -58,9 +58,6 @@ export interface SessionMeta {
         version: 1;
         userTurns?: number;
         compactSequence?: number;
-        gcSequence?: number;
-        gcGeneration?: number;
-        gcBaseSequence?: number;
         todoSequence?: number;
         todoRevision: number;
         executionModelIndexed?: true;

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, SessionStoreMaintenance, 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.13",
+  "version": "0.11.15",
   "description": "Embeddable MAR coding agent SDK and CLI.",
   "license": "Apache-2.0",
   "type": "module",