@myagentroam/agent 0.11.33 → 0.11.34

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

@@ -0,0 +1,26 @@
+import type { SessionModelMessage as ModelMessage } from './model-request.js';
+import type { SessionRecord } from './record-contract.js';
+export declare const INLINE_MEDIA_POLICY: Readonly<{
+    historicalInlineMediaTrigger: number;
+    historicalInlineMediaTarget: number;
+    requestInlineMediaHardLimit: number;
+}>;
+import type { InlineMediaCursor, InlineMediaState, InlineMediaGcCheckpoint } from './inline-media-contract.js';
+export type { InlineMediaCursor, InlineMediaState, InlineMediaGcCheckpoint } from './inline-media-contract.js';
+export interface InlineMediaGcCandidate extends InlineMediaGcCheckpoint {
+    /** Apply the proposed eviction to the current visual-window projection. */
+    readonly project: (messages: readonly ModelMessage[]) => ModelMessage[];
+}
+export declare function parseInlineMediaGc(value: unknown): InlineMediaGcCheckpoint | undefined;
+export declare function inlineMediaSource(message: ModelMessage): string | ModelMessage;
+/** GC may advance only a durable, already-considered source prefix. */
+export declare function inlineMediaGcAnchored(records: readonly SessionRecord[], media: InlineMediaGcCheckpoint): boolean;
+export declare function parseInlineMediaState(value: unknown): InlineMediaState | undefined;
+/** Recover ordering once at the lifecycle boundary, including GC-omitted sources. */
+export declare function inlineMediaHistory(records: readonly SessionRecord[]): {
+    cursors: (InlineMediaCursor & {
+        rollout: number;
+    })[];
+    rollouts: number;
+    state?: InlineMediaState;
+};

package/dist/session/inline-media.js

@@ -0,0 +1,138 @@
+import { AgentError } from '../error.js';
+import { REQUEST_INLINE_MEDIA_HARD_LIMIT } from '../model/inline-media-budget.js';
+import { appliedInputRecord } from './deferred-input.js';
+const MiB = 1_048_576;
+export const INLINE_MEDIA_POLICY = Object.freeze({
+    historicalInlineMediaTrigger: 7 * MiB,
+    historicalInlineMediaTarget: 5 * MiB,
+    requestInlineMediaHardLimit: REQUEST_INLINE_MEDIA_HARD_LIMIT
+});
+export function parseInlineMediaGc(value) {
+    if (!value || typeof value !== 'object')
+        return undefined;
+    const item = value;
+    const state = parseInlineMediaState(item.state);
+    return state?.evictedThrough &&
+        state.consideredThrough &&
+        Number.isSafeInteger(item.beforeBytes) &&
+        item.beforeBytes > 0 &&
+        Number.isSafeInteger(item.afterBytes) &&
+        item.afterBytes >= 0 &&
+        item.afterBytes <= INLINE_MEDIA_POLICY.historicalInlineMediaTarget &&
+        item.afterBytes < item.beforeBytes &&
+        (item.reason === 'SOFT_LIMIT' || item.reason === 'HARD_LIMIT' || item.reason === 'TEXT_GC') &&
+        (item.reason !== 'SOFT_LIMIT' ||
+            item.beforeBytes > INLINE_MEDIA_POLICY.historicalInlineMediaTrigger) &&
+        (item.reason !== 'TEXT_GC' ||
+            item.beforeBytes > INLINE_MEDIA_POLICY.historicalInlineMediaTarget)
+        ? { reason: item.reason, state, beforeBytes: item.beforeBytes, afterBytes: item.afterBytes }
+        : undefined;
+}
+export function inlineMediaSource(message) {
+    return message.callId !== undefined
+        ? `tool:${message.callId}`
+        : message.metadata?.recordId !== undefined
+            ? `input:${message.metadata.recordId}`
+            : message;
+}
+/** GC may advance only a durable, already-considered source prefix. */
+export function inlineMediaGcAnchored(records, media) {
+    const history = inlineMediaHistory(records);
+    const positions = new Map();
+    const key = (cursor) => JSON.stringify([cursor?.sourceId, cursor?.imageIndex]);
+    for (const cursor of history.cursors) {
+        const identity = key({ sourceId: cursor.sourceId, imageIndex: cursor.imageIndex });
+        if (!positions.has(identity))
+            positions.set(identity, { index: positions.size, rollout: cursor.rollout });
+    }
+    const evicted = positions.get(key(media.state.evictedThrough));
+    const considered = positions.get(key(media.state.consideredThrough));
+    const previous = positions.get(key(history.state?.evictedThrough));
+    return (evicted !== undefined &&
+        considered !== undefined &&
+        key(media.state.consideredThrough) === key(history.state?.consideredThrough) &&
+        evicted.index <= considered.index &&
+        evicted.index > (previous?.index ?? -1) &&
+        (media.reason === 'HARD_LIMIT' || history.rollouts - evicted.rollout >= 2));
+}
+export function parseInlineMediaState(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const state = value;
+    const cursor = (value) => {
+        if (!value || typeof value !== 'object')
+            return false;
+        const item = value;
+        return (typeof item.sourceId === 'string' &&
+            item.sourceId.length > 0 &&
+            item.sourceId.length <= 256 &&
+            Number.isSafeInteger(item.imageIndex) &&
+            item.imageIndex >= 0);
+    };
+    if (state.version !== 1 ||
+        (state.consideredThrough !== undefined && !cursor(state.consideredThrough)) ||
+        (state.evictedThrough !== undefined && !cursor(state.evictedThrough)))
+        return undefined;
+    return structuredClone(state);
+}
+/** Recover ordering once at the lifecycle boundary, including GC-omitted sources. */
+export function inlineMediaHistory(records) {
+    const cursors = [];
+    let rollouts = 0;
+    let state;
+    const add = (sourceId, images) => {
+        if (!sourceId || !Array.isArray(images))
+            return;
+        for (let imageIndex = 0; imageIndex < images.length; imageIndex++)
+            cursors.push({ sourceId, imageIndex, rollout: rollouts });
+    };
+    for (const record of records) {
+        const payload = record.payload;
+        if (!payload || typeof payload !== 'object')
+            continue;
+        if (record.type === 'model.attempt' &&
+            payload.purpose === 'EXECUTION' &&
+            payload.state === 'SUCCEEDED')
+            rollouts++;
+        if (record.type === 'compact.completed') {
+            cursors.splice(0);
+            state = parseInlineMediaState(payload.inlineMediaState);
+            for (const item of (payload.retainedModelContext ?? [])) {
+                const applied = appliedInputRecord({ ...record, type: 'model.context', payload: item });
+                if (applied) {
+                    add(`input:${applied.recordId}`, applied.payload.images);
+                    continue;
+                }
+                const key = inlineMediaSource(item);
+                add(typeof key === 'string' ? key : undefined, item.images);
+            }
+        }
+        else if (record.type === 'resource.window') {
+            state = parseInlineMediaState(payload);
+        }
+        else if (record.type === 'context.gc.completed' && payload.inlineMedia !== undefined) {
+            const media = parseInlineMediaGc(payload.inlineMedia);
+            if (!media)
+                throw new AgentError('MAR_AGENT_SESSION_CORRUPT', 'Inline media GC state is invalid.');
+            state = media.state;
+        }
+        else if ((record.type === 'turn.user' || record.type === 'extension.input') &&
+            payload.deferred !== true) {
+            add(`input:${record.recordId}`, payload.images);
+        }
+        else if (record.type === 'model.context') {
+            const applied = appliedInputRecord(record);
+            if (applied) {
+                add(`input:${applied.recordId}`, applied.payload.images);
+                continue;
+            }
+            const key = typeof payload.inputRef === 'string'
+                ? `input:${payload.inputRef}`
+                : typeof payload.callId === 'string'
+                    ? `tool:${payload.callId}`
+                    : undefined;
+            add(key, payload.images);
+        }
+    }
+    return { cursors, rollouts, ...(state ? { state } : {}) };
+}

package/dist/session/model-request.d.ts

@@ -0,0 +1,14 @@
+import type { ModelMessage, ModelRequest } from '../model/contracts.js';
+import type { ClientToolDefinition } from '../tools/contracts.js';
+import type { CodeObservation, CodeToolCallRecord } from './code-observation-contract.js';
+/** Durable execution facts, projected to protocol input at the SDK adapter boundary. */
+export interface SessionModelMessage extends ModelMessage {
+    calls?: readonly CodeToolCallRecord[];
+    observations?: readonly CodeObservation[];
+    observationId?: string;
+    toolSearchTools?: readonly ClientToolDefinition[];
+}
+export interface SessionModelRequest extends ModelRequest {
+    messages: readonly SessionModelMessage[];
+    tools: readonly ClientToolDefinition[];
+}

package/dist/session/model-request.js

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

package/dist/session/record-contract.d.ts

@@ -0,0 +1,19 @@
+import type { ModelInputMetadata } from '../model/contracts.js';
+export interface SessionRecord {
+    recordId: string;
+    sequence: number;
+    timestamp: string;
+    sessionId: string;
+    executionId?: string;
+    turnId?: string;
+    type: string;
+    payload: unknown;
+}
+export interface CompactUserInput {
+    content: string;
+    metadata?: ModelInputMetadata;
+}
+export interface CompactHistoryMessage extends CompactUserInput {
+    role: 'user';
+    kind: 'user_input' | 'extension_input' | 'summary';
+}

package/dist/session/record-contract.js

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

package/dist/session/record-projection.d.ts

@@ -0,0 +1,6 @@
+import type { ModelInputMetadata } from '../model/contracts.js';
+import type { CompactHistoryMessage, SessionRecord } from './record-contract.js';
+export declare function compactSummaryFromCheckpoint(record: SessionRecord | undefined): string | undefined;
+export declare function replacementHistoryFromCheckpoint(record: SessionRecord): CompactHistoryMessage[] | undefined;
+export declare function parseModelInputMetadata(value: unknown): ModelInputMetadata | undefined;
+export declare function inputMetadataFromRecord(record: SessionRecord): ModelInputMetadata;

package/dist/session/record-projection.js

@@ -0,0 +1,80 @@
+export function compactSummaryFromCheckpoint(record) {
+    if (record?.type !== 'compact.completed')
+        return undefined;
+    const payload = record.payload;
+    if (payload === null || typeof payload !== 'object' || Array.isArray(payload))
+        return undefined;
+    const summary = payload.summary;
+    return typeof summary === 'string' && summary.trim().length > 0 ? summary : undefined;
+}
+export function replacementHistoryFromCheckpoint(record) {
+    if (compactSummaryFromCheckpoint(record) === undefined)
+        return undefined;
+    const history = record.payload.replacementHistory;
+    if (!Array.isArray(history))
+        return undefined;
+    const result = [];
+    let summaries = 0;
+    for (const message of history) {
+        if (message === null ||
+            typeof message !== 'object' ||
+            message.role !== 'user' ||
+            typeof message.content !== 'string' ||
+            (message.kind !== 'user_input' &&
+                message.kind !== 'extension_input' &&
+                !(message.kind === 'summary' && message.content.trim().length > 0)))
+            return undefined;
+        const metadata = parseModelInputMetadata(message.metadata);
+        if (message.metadata !== undefined &&
+            (!metadata ||
+                (message.kind === 'extension_input'
+                    ? metadata.source !== 'extension'
+                    : message.kind !== 'user_input' || metadata.source === 'extension')))
+            return undefined;
+        if (message.kind === 'summary')
+            summaries++;
+        result.push({
+            role: 'user',
+            content: message.content,
+            kind: message.kind,
+            ...(metadata === undefined ? {} : { metadata })
+        });
+    }
+    return summaries === 1 ? result : undefined;
+}
+export function parseModelInputMetadata(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const metadata = value;
+    if (metadata.source !== 'user' &&
+        metadata.source !== 'parent_agent' &&
+        metadata.source !== 'extension')
+        return undefined;
+    return {
+        source: metadata.source,
+        ...(typeof metadata.recordId === 'string' && metadata.recordId.length <= 128
+            ? { recordId: metadata.recordId }
+            : {}),
+        ...(typeof metadata.extensionId === 'string' && metadata.extensionId.length <= 128
+            ? { extensionId: metadata.extensionId }
+            : {}),
+        ...(metadata.truncated === true ? { truncated: true } : {}),
+        ...(metadata.smartCompaction === true ? { smartCompaction: true } : {})
+    };
+}
+export function inputMetadataFromRecord(record) {
+    const payload = record.payload;
+    const source = payload.source;
+    return {
+        source: record.type === 'extension.input' || payload.inputSource === 'extension'
+            ? 'extension'
+            : payload.inputSource === 'parent_agent'
+                ? 'parent_agent'
+                : 'user',
+        recordId: record.recordId,
+        ...(payload.smartCompaction === true ? { smartCompaction: true } : {}),
+        ...(typeof source?.extensionId === 'string' && source.extensionId.length <= 128
+            ? { extensionId: source.extensionId }
+            : {})
+    };
+}

package/dist/session/resource-contract.d.ts

@@ -0,0 +1,9 @@
+export interface SessionResource {
+    readonly resourceInputVersion?: 1;
+    readonly resourceId: string;
+    readonly mimeType: string;
+    readonly byteSize: number;
+    readonly sha256: string;
+    readonly url?: string;
+    readonly urlExpiresAt?: number;
+}

package/dist/session/resource-contract.js

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

package/dist/session/rollback.d.ts

@@ -0,0 +1,13 @@
+import type { SessionRecord } from './store/types.js';
+export type AgentSessionRollbackInput = {
+    readonly boundaryTurnId: string | null;
+    readonly beforeInput?: never;
+} | {
+    readonly boundaryTurnId?: never;
+    readonly beforeInput: {
+        readonly turnId: string;
+        readonly clientMessageId: string;
+    };
+};
+/** Resolve the retained prefix only from records read under the Session maintenance lease. */
+export declare function rollbackBoundaryIndex(records: readonly SessionRecord[], input: AgentSessionRollbackInput): number;

package/dist/session/rollback.js

@@ -0,0 +1,46 @@
+import { AgentError } from '../error.js';
+/** Resolve the retained prefix only from records read under the Session maintenance lease. */
+export function rollbackBoundaryIndex(records, input) {
+    const invalid = () => new AgentError('MAR_AGENT_ROLLBACK_TARGET_INVALID', 'Session rollback target was not found or is ambiguous.');
+    if (input.beforeInput !== undefined) {
+        const target = input.beforeInput;
+        if (input.boundaryTurnId !== undefined ||
+            target === null ||
+            typeof target !== 'object' ||
+            typeof target.turnId !== 'string' ||
+            !target.turnId.trim() ||
+            typeof target.clientMessageId !== 'string' ||
+            !target.clientMessageId.trim())
+            throw invalid();
+        let firstInput = -1;
+        let selected = -1;
+        for (const [index, record] of records.entries()) {
+            if (record.type !== 'turn.user' || record.turnId !== target.turnId)
+                continue;
+            if (firstInput < 0)
+                firstInput = index;
+            const payload = record.payload;
+            if (payload === null || typeof payload !== 'object' || Array.isArray(payload))
+                continue;
+            if (payload.clientMessageId !== target.clientMessageId)
+                continue;
+            if (selected >= 0)
+                throw invalid();
+            selected = index;
+        }
+        if (selected < 0)
+            throw invalid();
+        // The initial input owns execution-start records; subsequent inputs own only their tail.
+        return ((selected === firstInput
+            ? records.findIndex((record) => record.turnId === target.turnId)
+            : selected) - 1);
+    }
+    if (input.boundaryTurnId === null)
+        return 0;
+    if (typeof input.boundaryTurnId !== 'string' || !input.boundaryTurnId.trim())
+        throw invalid();
+    const index = records.findLastIndex((record) => record.turnId === input.boundaryTurnId);
+    if (index < 0)
+        throw invalid();
+    return index;
+}

package/dist/session/store/contracts.d.ts

@@ -0,0 +1,160 @@
+import type { SessionModelMessage as ModelMessage } from '../model-request.js';
+import type { ExtensionCheckpoint, ExtensionJsonValue } from '../extension-checkpoint.js';
+import type { ModelUsage } from '../../model/contracts.js';
+import type { EnvironmentContextState } from '../../runtime/context/contracts.js';
+import type { CodeModeStateEntry } from '../code-state.js';
+import type { AvailableToolResultResource } from '../../tools/result-extension-contract.js';
+import type { AgentSessionPage, AgentSessionSummary } from '../summary.js';
+import type { ContextGcCheckpointDraft } from '../context-gc-contract.js';
+import type { SessionResource } from '../resource-contract.js';
+import type { ToolResultResourceInput, ToolResultResourcePage } from '../tool-result-resources.js';
+import type { SessionListInput, SessionSource, SessionTitleUpdateInput } from '../types.js';
+import type { AgentSessionRollbackInput } from '../rollback.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 '../code-state.js';
+export type { SessionResource } from '../resource-contract.js';
+export type { TodoSnapshot, TodoItem } from '../todo.js';
+export type { CodeToolCallRecord, CodeObservation } from '../code-observation-contract.js';
+export type { SessionModelMessage as ModelMessage } from '../model-request.js';
+export type { 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-contract.js';
+export type { ContextGcWebToolName, ContextGcSubagentToolName } from '../context-gc-contract.js';
+export type { AvailableToolResultResource } from '../../tools/result-extension-contract.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[];
+    inlineMediaState?: import('../inline-media.js').InlineMediaState;
+    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<AgentSessionSummary & {
+        automaticTitlePending: boolean;
+    }>;
+    list(input?: SessionListInput): Promise<AgentSessionPage>;
+    listSubagentChildren(parentSessionId: string): Promise<Array<AgentSessionSummary & {
+        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<ExtensionCheckpoint>;
+    writeExtensionCheckpoint(sessionId: string, extensionId: string, key: string, value: ExtensionJsonValue | undefined, expectedRevision: number | undefined, input: {
+        owner: object;
+        signal: AbortSignal;
+        executionId?: string;
+        turnId?: string;
+    }): Promise<ExtensionCheckpoint>;
+    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[]>;
+    persistResource(sessionId: string, image: import('../../model/image.js').ModelImage): Promise<SessionResource>;
+    setResourceUrl(sessionId: string, resourceId: string, published: {
+        url: string;
+        urlExpiresAt: number;
+    }): Promise<SessionResource>;
+    readResource(sessionId: string, resourceId: string): Promise<{
+        mimeType: string;
+        dataBase64: string;
+    } | undefined>;
+    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: AgentSessionRollbackInput): Promise<AgentSessionSummary>;
+    clearSession(sessionId: string, maintenance?: SessionStoreMaintenance): Promise<AgentSessionSummary>;
+    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/session/store/contracts.js

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

package/dist/session/store/current-state.d.ts

@@ -0,0 +1,17 @@
+import { type ExtensionCheckpoint } from '../extension-checkpoint.js';
+import { type CodeModeStateEntry } from '../code-state.js';
+interface StateRecord {
+    readonly type: string;
+    readonly payload: unknown;
+}
+export type ExtensionCheckpointIndex = Map<string, Map<string, Record<string, unknown>>>;
+/** Derived non-model state owned by one physical Session writer lease. */
+export interface SessionCurrentState {
+    codeState?: CodeModeStateEntry[];
+    extensionCheckpoints?: ExtensionCheckpointIndex;
+}
+export declare function updateSessionCurrentState(cache: SessionCurrentState | undefined, type: string, serialized: string): void;
+export declare function restoreExtensionCheckpoint(records: readonly StateRecord[], extensionId: string, key: string): ExtensionCheckpoint;
+export declare function indexExtensionCheckpoint(index: ExtensionCheckpointIndex, payload: unknown): void;
+export declare function extensionCheckpointFromPayload(payload: Record<string, unknown> | undefined): ExtensionCheckpoint;
+export {};

package/dist/session/store/current-state.js

@@ -0,0 +1,53 @@
+import { AgentError } from '../../error.js';
+import { cloneCoreJson } from '../extension-checkpoint.js';
+import { restoreCodeModeState } from '../code-state.js';
+export function updateSessionCurrentState(cache, type, serialized) {
+    if (!cache)
+        return;
+    if (type === 'code.state.updated' && cache.codeState !== undefined) {
+        try {
+            cache.codeState = restoreCodeModeState([JSON.parse(serialized)], cache.codeState);
+        }
+        catch {
+            // Cache maintenance must not fail an already durable append.
+            delete cache.codeState;
+        }
+    }
+    else if (type === 'extension.checkpoint.updated' && cache.extensionCheckpoints) {
+        indexExtensionCheckpoint(cache.extensionCheckpoints, JSON.parse(serialized).payload);
+    }
+}
+export function restoreExtensionCheckpoint(records, extensionId, key) {
+    for (const record of records.toReversed()) {
+        if (record.type !== 'extension.checkpoint.updated')
+            continue;
+        const payload = record.payload;
+        if (!payload || payload.extensionId !== extensionId || payload.key !== key)
+            continue;
+        return extensionCheckpointFromPayload(payload);
+    }
+    return { revision: 0 };
+}
+export function indexExtensionCheckpoint(index, payload) {
+    if (typeof payload !== 'object' || payload === null || Array.isArray(payload))
+        return;
+    const value = payload;
+    if (typeof value.extensionId !== 'string' || typeof value.key !== 'string')
+        return;
+    let namespace = index.get(value.extensionId);
+    if (!namespace)
+        index.set(value.extensionId, (namespace = new Map()));
+    namespace.set(value.key, value);
+}
+export function extensionCheckpointFromPayload(payload) {
+    if (!payload)
+        return { revision: 0 };
+    if (typeof payload.revision !== 'number' ||
+        !Number.isSafeInteger(payload.revision) ||
+        payload.revision < 1)
+        throw new AgentError('MAR_AGENT_SESSION_CORRUPT', 'Extension checkpoint revision is corrupt.');
+    return {
+        revision: payload.revision,
+        ...(payload.deleted === true ? {} : { value: cloneCoreJson(payload.value) })
+    };
+}

package/dist/session/store/execution-state.d.ts

@@ -0,0 +1,13 @@
+import type { SessionExecutionState, SessionMeta, SessionRecord } from './types.js';
+export declare function deriveExecutionState(records: readonly SessionRecord[]): SessionExecutionState & {
+    resume: NonNullable<SessionMeta['resume']>;
+};
+export declare function isNativeUserTurn(record: SessionRecord): boolean;
+export declare function userMessagePreviewFromRecord(record: SessionRecord): string | undefined;
+export declare function executionModelFromRecord(record: SessionRecord): {
+    modelId: string;
+    modelName?: string;
+    reasoningEffort?: string;
+} | undefined;
+export declare function isCompactCheckpoint(record: SessionRecord | undefined): boolean;
+export declare function sameResumeIndex(left: SessionMeta['resume'], right: NonNullable<SessionMeta['resume']>): boolean;