@myagentroam/agent 0.10.59 → 0.10.60

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

@@ -0,0 +1,17 @@
+import { type CoreCheckpoint } from '../../extensions/data.js';
+import { type CodeModeStateEntry } from '../../tools/code-mode/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): CoreCheckpoint;
+export declare function indexExtensionCheckpoint(index: ExtensionCheckpointIndex, payload: unknown): void;
+export declare function extensionCheckpointFromPayload(payload: Record<string, unknown> | undefined): CoreCheckpoint;
+export {};

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

@@ -0,0 +1,53 @@
+import { MarAgentError } from '../../error.js';
+import { cloneCoreJson } from '../../extensions/data.js';
+import { restoreCodeModeState } from '../../tools/code-mode/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 MarAgentError('MAR_AGENT_SESSION_CORRUPT', 'Extension checkpoint revision is corrupt.');
+    return {
+        revision: payload.revision,
+        ...(payload.deleted === true ? {} : { value: cloneCoreJson(payload.value) })
+    };
+}

package/dist/agent-core/session/store/directory-index.d.ts

@@ -0,0 +1,18 @@
+import type { SessionListInput, SessionSource } from '../types.js';
+import type { SessionIndex, SessionMeta } from './types.js';
+/** Merge a derived cache only onto the unchanged history it was computed from. */
+export declare function mergeFirstUserMessagePreviewCache(current: SessionMeta, cached: SessionMeta): SessionMeta;
+export declare function readSessionIndex(path: string): Promise<SessionIndex | undefined>;
+export declare function persistSessionIndex(path: string, index: SessionIndex): Promise<void>;
+export declare function normalizeSessionSource(value: SessionSource | undefined): SessionSource;
+interface SessionListFilter {
+    readonly source: SessionSource['type'];
+    readonly parentSessionId?: string;
+    readonly rootSessionId?: string;
+}
+export declare function sessionListFilter(input: SessionListInput): SessionListFilter;
+export declare function sessionMatchesFilter(meta: SessionMeta, filter: SessionListFilter): boolean;
+export declare function encodeSessionListCursor(revision: number, offset: number, filter: SessionListFilter): string;
+export declare function decodeSessionListCursor(cursor: string | undefined, revision: number, filter: SessionListFilter): number;
+export declare function sessionTreeIds(sessions: readonly SessionMeta[], sessionId: string): string[];
+export {};

package/dist/agent-core/session/store/directory-index.js

@@ -0,0 +1,163 @@
+import { randomUUID } from 'node:crypto';
+import { readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { isDeepStrictEqual } from 'node:util';
+import { MarAgentError } from '../../error.js';
+/** Merge a derived cache only onto the unchanged history it was computed from. */
+export function mergeFirstUserMessagePreviewCache(current, cached) {
+    if (cached.resume?.firstUserMessageIndexed !== true ||
+        current.nextSequence !== cached.nextSequence ||
+        current.storageTransactionId !== cached.storageTransactionId ||
+        current.resume?.firstUserMessagePreview !== undefined ||
+        (current.resume?.firstUserMessageIndexed === true &&
+            cached.resume.firstUserMessagePreview === undefined))
+        return current;
+    return {
+        ...current,
+        resume: {
+            ...(current.resume ?? { version: 1, todoRevision: 0 }),
+            firstUserMessageIndexed: true,
+            ...(cached.resume?.firstUserMessagePreview === undefined
+                ? {}
+                : { firstUserMessagePreview: cached.resume.firstUserMessagePreview })
+        }
+    };
+}
+export async function readSessionIndex(path) {
+    let raw;
+    try {
+        raw = await readFile(path, 'utf8');
+    }
+    catch (cause) {
+        if (cause.code === 'ENOENT')
+            return undefined;
+        throw cause;
+    }
+    try {
+        const value = JSON.parse(raw);
+        if (value?.version !== 1 ||
+            !Number.isSafeInteger(value.revision) ||
+            value.revision < 0 ||
+            !Array.isArray(value.sessions) ||
+            value.sessions.some((session) => typeof session?.id !== 'string' ||
+                !/^[0-9a-f-]{36}$/iu.test(session.id) ||
+                typeof session.title !== 'string' ||
+                typeof session.workspace !== 'string' ||
+                typeof session.createdAt !== 'string' ||
+                typeof session.lastActivityAt !== 'string' ||
+                !Number.isSafeInteger(session.nextSequence) ||
+                session.nextSequence < 1))
+            throw new Error('invalid index shape');
+        return value;
+    }
+    catch (cause) {
+        throw new MarAgentError('MAR_AGENT_SESSION_CORRUPT', 'Session index is corrupt.', { cause });
+    }
+}
+export async function persistSessionIndex(path, index) {
+    const temporary = `${path}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(temporary, JSON.stringify(index), { mode: 0o600, flag: 'wx', flush: true });
+        await rename(temporary, path);
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}
+export function normalizeSessionSource(value) {
+    if (value === undefined || value.type === 'user')
+        return { type: 'user' };
+    if (value.type !== 'subagent' ||
+        typeof value.parentSessionId !== 'string' ||
+        !value.parentSessionId.trim() ||
+        typeof value.rootSessionId !== 'string' ||
+        !value.rootSessionId.trim() ||
+        (!value.parentExecutionId && !value.parentOperationId) ||
+        [
+            value.parentExecutionId,
+            value.parentOperationId,
+            value.ownerInstanceId,
+            value.extensionId
+        ].some((identity) => identity !== undefined && (typeof identity !== 'string' || !identity.trim())) ||
+        ((value.ownerInstanceId !== undefined || value.extensionId !== undefined) &&
+            value.parentOperationId === undefined) ||
+        typeof value.description !== 'string' ||
+        !value.description.trim() ||
+        (value.role !== 'general-purpose' && value.role !== 'explore'))
+        throw new MarAgentError('MAR_AGENT_TOOL_INPUT_INVALID', 'Session source is invalid.');
+    return {
+        type: 'subagent',
+        parentSessionId: value.parentSessionId,
+        rootSessionId: value.rootSessionId,
+        ...(value.parentExecutionId === undefined
+            ? {}
+            : { parentExecutionId: value.parentExecutionId }),
+        ...(value.parentOperationId === undefined
+            ? {}
+            : { parentOperationId: value.parentOperationId }),
+        ...(value.ownerInstanceId === undefined ? {} : { ownerInstanceId: value.ownerInstanceId }),
+        ...(value.extensionId === undefined ? {} : { extensionId: value.extensionId }),
+        role: value.role,
+        description: value.description.trim()
+    };
+}
+export function sessionListFilter(input) {
+    const source = input.source ??
+        (input.parentSessionId !== undefined || input.rootSessionId !== undefined
+            ? 'subagent'
+            : 'user');
+    if ((source !== 'user' && source !== 'subagent') ||
+        (input.parentSessionId !== undefined &&
+            (source !== 'subagent' || input.parentSessionId.length === 0)) ||
+        (input.rootSessionId !== undefined &&
+            (source !== 'subagent' || input.rootSessionId.length === 0)))
+        throw new MarAgentError('MAR_AGENT_TOOL_INPUT_INVALID', 'Session list filter is invalid.');
+    return {
+        source,
+        ...(input.parentSessionId === undefined ? {} : { parentSessionId: input.parentSessionId }),
+        ...(input.rootSessionId === undefined ? {} : { rootSessionId: input.rootSessionId })
+    };
+}
+export function sessionMatchesFilter(meta, filter) {
+    const source = normalizeSessionSource(meta.source);
+    return (source.type === filter.source &&
+        (filter.parentSessionId === undefined ||
+            (source.type === 'subagent' && source.parentSessionId === filter.parentSessionId)) &&
+        (filter.rootSessionId === undefined ||
+            (source.type === 'subagent' && source.rootSessionId === filter.rootSessionId)));
+}
+export function encodeSessionListCursor(revision, offset, filter) {
+    return Buffer.from(JSON.stringify({ version: 1, revision, offset, filter })).toString('base64url');
+}
+export function decodeSessionListCursor(cursor, revision, filter) {
+    if (cursor === undefined)
+        return 0;
+    try {
+        const value = JSON.parse(Buffer.from(cursor, 'base64url').toString('utf8'));
+        if (value.version !== 1 ||
+            value.revision !== revision ||
+            !Number.isSafeInteger(value.offset) ||
+            value.offset < 0 ||
+            !isDeepStrictEqual(value.filter, filter))
+            throw new Error('invalid cursor');
+        return value.offset;
+    }
+    catch {
+        throw new MarAgentError('MAR_AGENT_TOOL_INPUT_INVALID', 'Session list cursor is invalid.');
+    }
+}
+export function sessionTreeIds(sessions, sessionId) {
+    if (!sessions.some((session) => session.id === sessionId))
+        return [];
+    const ids = [sessionId];
+    for (let index = 0; index < ids.length; index++) {
+        const parentId = ids[index];
+        for (const session of sessions) {
+            const source = normalizeSessionSource(session.source);
+            if (source.type === 'subagent' &&
+                source.parentSessionId === parentId &&
+                !ids.includes(session.id))
+                ids.push(session.id);
+        }
+    }
+    return ids;
+}

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

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

package/dist/agent-core/session/store/execution-state.js

@@ -0,0 +1,178 @@
+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;
+    let compactSequence;
+    let todoSequence;
+    let todoRevision = 0;
+    let todoItems = [];
+    let executionModel;
+    let firstUserMessagePreview;
+    for (const record of records) {
+        firstUserMessagePreview ??= userMessagePreviewFromRecord(record);
+        if (record.type === 'session.created')
+            automaticTitle =
+                record.payload?.automaticTitle === true;
+        else if (record.type === 'turn.user')
+            sawUserTurn = true;
+        else if (record.type === 'session.title.updated')
+            automaticTitle = false;
+        else if (isCompactCheckpoint(record))
+            compactSequence = record.sequence;
+        else if (record.type === 'todo.updated') {
+            const items = todoItemsFromSnapshot(record.payload);
+            if (!items)
+                continue;
+            todoSequence = record.sequence;
+            todoRevision++;
+            todoItems = items;
+        }
+        const candidate = executionModelFromRecord(record);
+        if (candidate !== undefined)
+            executionModel = candidate;
+    }
+    const boundary = records.findLastIndex(isCompactCheckpoint);
+    const checkpoint = latestValidContextGcCheckpoint(records);
+    return {
+        automaticTitlePending: automaticTitle && !sawUserTurn,
+        todo: { revision: todoRevision, items: todoItems },
+        contextRecords: boundary < 0 ? [...records] : records.slice(boundary),
+        resume: {
+            version: 1,
+            ...(compactSequence === undefined ? {} : { compactSequence }),
+            ...(checkpoint === undefined
+                ? {}
+                : {
+                    gcSequence: checkpoint.record.sequence,
+                    gcGeneration: checkpoint.payload.generation,
+                    gcBaseSequence: contextGcBaseSequence(checkpoint.payload.base)
+                }),
+            ...(todoSequence === undefined ? {} : { todoSequence }),
+            todoRevision,
+            executionModelIndexed: true,
+            firstUserMessageIndexed: true,
+            ...(firstUserMessagePreview === undefined ? {} : { firstUserMessagePreview }),
+            ...(executionModel === undefined ? {} : executionModel)
+        }
+    };
+}
+export function userMessagePreviewFromRecord(record) {
+    if (record.type !== 'turn.user' ||
+        !isObject(record.payload) ||
+        record.payload.inputSource === 'parent_agent' ||
+        typeof record.payload.prompt !== 'string')
+        return undefined;
+    const preview = record.payload.prompt.trim().replace(/\s+/gu, ' ').slice(0, 160);
+    return preview || undefined;
+}
+export function executionModelFromRecord(record) {
+    if (record.type !== 'execution.header' || !isObject(record.payload))
+        return undefined;
+    const modelId = record.payload.modelId;
+    if (typeof modelId !== 'string' || modelId.trim().length === 0)
+        return undefined;
+    const modelName = record.payload.modelName;
+    const reasoningEffort = record.payload.reasoningEffort;
+    return {
+        modelId,
+        ...(typeof modelName === 'string' && modelName.trim().length > 0 ? { modelName } : {}),
+        ...(typeof reasoningEffort === 'string' && reasoningEffort.trim().length > 0
+            ? { reasoningEffort }
+            : {})
+    };
+}
+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) ||
+        !history.every((message) => message !== null &&
+            typeof message === 'object' &&
+            message.role === 'user' &&
+            typeof message.content === 'string' &&
+            (message.metadata === undefined ||
+                (parseModelInputMetadata(message.metadata) !== undefined &&
+                    (message.kind === 'extension_input'
+                        ? message.metadata.source === 'extension'
+                        : message.kind === 'user_input' && message.metadata.source !== 'extension'))) &&
+            (message.kind === 'user_input' ||
+                message.kind === 'extension_input' ||
+                (message.kind === 'summary' && message.content.trim().length > 0))) ||
+        history.filter((message) => message.kind === 'summary').length !== 1)
+        return undefined;
+    return history.map(({ role, content, kind, metadata }) => ({
+        role,
+        content,
+        kind,
+        ...(parseModelInputMetadata(metadata) === undefined
+            ? {}
+            : { metadata: parseModelInputMetadata(metadata) })
+    }));
+}
+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 }
+            : {})
+    };
+}
+export function isCompactCheckpoint(record) {
+    return compactSummaryFromCheckpoint(record) !== undefined;
+}
+export function sameResumeIndex(left, right) {
+    return (left?.version === right.version &&
+        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 &&
+        left.firstUserMessageIndexed === right.firstUserMessageIndexed &&
+        left.firstUserMessagePreview === right.firstUserMessagePreview &&
+        left.modelId === right.modelId &&
+        left.modelName === right.modelName &&
+        left.reasoningEffort === right.reasoningEffort);
+}
+function isObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}

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

@@ -0,0 +1,25 @@
+import type { SessionMeta, SessionRecord } from './types.js';
+export declare function renameIfExists(from: string, to: string): Promise<boolean>;
+interface StagedSessionSegments {
+    readonly files: readonly {
+        readonly path: string;
+        readonly temporaryPath: string;
+    }[];
+    readonly segments: NonNullable<SessionMeta['segments']>;
+}
+export declare function stageSessionSegments(sessionDirectory: string, records: readonly SessionRecord[], operation?: 'rollback' | 'fork'): Promise<StagedSessionSegments>;
+export declare function stageUnreferencedImages(sessionDirectory: string, directoryName: 'input_images' | 'generated_images' | 'tool_results', retained: ReadonlySet<string>, transactionId: string): Promise<Array<{
+    from: string;
+    to: string;
+    trash: string;
+}>>;
+export declare function restoreRenamedFiles(files: readonly {
+    readonly from: string;
+    readonly to: string;
+}[]): Promise<void>;
+export declare function retainedSessionTitle(records: readonly SessionRecord[], fallback: string): string;
+export declare function forkedPayload(type: string, value: unknown, sourceSessionId: string, targetSessionId: string, title: string, identities: ReadonlyMap<string, {
+    recordId: string;
+    sequence: number;
+}>): unknown;
+export {};

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

@@ -0,0 +1,157 @@
+import { randomUUID } from 'node:crypto';
+import { open, readdir, rename, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { MarAgentError } from '../../error.js';
+import { MAX_SEGMENT_BYTES } from './records.js';
+export async function renameIfExists(from, to) {
+    try {
+        await rename(from, to);
+        return true;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+}
+export async function stageSessionSegments(sessionDirectory, records, operation = 'rollback') {
+    let group;
+    if (records.length === 0)
+        throw new MarAgentError('MAR_AGENT_SESSION_CORRUPT', 'Session history is corrupt.');
+    const transactionId = randomUUID();
+    const files = [];
+    const segments = [];
+    const flush = async () => {
+        if (group === undefined)
+            return;
+        const number = segments.length + 1;
+        const path = join(sessionDirectory, `events-${String(number).padStart(6, '0')}.jsonl`);
+        const temporaryPath = `${path}.${transactionId}.${operation}-tmp`;
+        const handle = await open(temporaryPath, 'wx', 0o600);
+        files.push({ path, temporaryPath });
+        try {
+            await handle.writeFile(group.lines.join(''));
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        segments.push({
+            number,
+            firstSequence: group.firstSequence,
+            lastSequence: group.lastSequence,
+            bytes: group.bytes
+        });
+        group = undefined;
+    };
+    try {
+        for (const record of records) {
+            const line = `${JSON.stringify(record)}\n`;
+            const bytes = Buffer.byteLength(line);
+            if (group !== undefined && group.bytes > 0 && group.bytes + bytes > MAX_SEGMENT_BYTES)
+                await flush();
+            if (group === undefined) {
+                group = {
+                    lines: [],
+                    bytes: 0,
+                    firstSequence: record.sequence,
+                    lastSequence: record.sequence
+                };
+            }
+            group.lines.push(line);
+            group.bytes += bytes;
+            group.lastSequence = record.sequence;
+        }
+        await flush();
+        return { files, segments };
+    }
+    catch (error) {
+        await Promise.all(files.map((item) => rm(item.temporaryPath, { force: true }))).catch(() => undefined);
+        throw error;
+    }
+}
+export async function stageUnreferencedImages(sessionDirectory, directoryName, retained, transactionId) {
+    const directory = join(sessionDirectory, directoryName);
+    let names;
+    try {
+        names = await readdir(directory);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+    const moved = [];
+    try {
+        for (const name of names) {
+            if (retained.has(name))
+                continue;
+            const from = join(directory, name);
+            const trash = join(directory, `.${name}.${transactionId}.rollback-trash`);
+            await rename(from, trash);
+            moved.push({ from: trash, to: from, trash });
+        }
+        return moved;
+    }
+    catch (error) {
+        await restoreRenamedFiles(moved);
+        throw error;
+    }
+}
+export async function restoreRenamedFiles(files) {
+    for (const file of files.toReversed())
+        await rename(file.from, file.to).catch(() => undefined);
+}
+export function retainedSessionTitle(records, fallback) {
+    let title = fallback;
+    for (const record of records) {
+        if ((record.type === 'session.created' || record.type === 'session.title.updated') &&
+            isObject(record.payload) &&
+            typeof record.payload.title === 'string' &&
+            record.payload.title.trim().length > 0)
+            title = record.payload.title;
+    }
+    return title;
+}
+export function forkedPayload(type, value, sourceSessionId, targetSessionId, title, identities) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return value;
+    const payload = { ...value };
+    if (payload.sessionId === sourceSessionId)
+        payload.sessionId = targetSessionId;
+    const application = (input) => {
+        if (typeof input.inputRef !== 'string')
+            return input;
+        const identity = identities.get(input.inputRef);
+        if (!identity)
+            throw new MarAgentError('MAR_AGENT_SESSION_CORRUPT', 'Fork input reference is missing.');
+        return {
+            ...input,
+            inputRef: identity.recordId,
+            ...(isObject(input.metadata)
+                ? { metadata: { ...input.metadata, recordId: identity.recordId } }
+                : {})
+        };
+    };
+    if (type === 'model.context')
+        return application(payload);
+    if (type === 'compact.completed') {
+        if (Array.isArray(payload.retainedModelContext))
+            payload.retainedModelContext = payload.retainedModelContext.map((item) => isObject(item) ? application(item) : item);
+        if (Array.isArray(payload.pendingInputs))
+            payload.pendingInputs = payload.pendingInputs.map((record) => {
+                const identity = identities.get(record.recordId);
+                if (!identity)
+                    throw new MarAgentError('MAR_AGENT_SESSION_CORRUPT', 'Fork pending input reference is missing.');
+                return { ...record, ...identity, sessionId: targetSessionId };
+            });
+    }
+    if (type === 'session.title.updated') {
+        payload.title = title;
+        payload.automatic = false;
+    }
+    return payload;
+}
+function isObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}

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

@@ -0,0 +1,21 @@
+import type { SessionInputImage, SessionInputImageMetadata, SessionRecord } from './types.js';
+export declare const MAX_INPUT_IMAGES = 5;
+export declare function generatedImageFileNames(records: readonly SessionRecord[]): readonly string[];
+export declare function copyGeneratedImages(sourceSessionDirectory: string, targetSessionDirectory: string, fileNames: readonly string[]): Promise<void>;
+interface InputImageReference {
+    readonly name: string;
+    readonly fileName: string;
+    readonly mimeType: string;
+    readonly byteSize: number;
+    readonly sha256: string;
+}
+export declare function inputImageReferencesFromRecords(records: readonly SessionRecord[]): readonly InputImageReference[];
+export declare function inputImageReferences(value: unknown): InputImageReference[];
+export declare function inputImageReference(value: unknown): InputImageReference | undefined;
+export declare function validInputImageFileName(fileName: string): boolean;
+export declare function readInputImageBytes(directory: string, reference: InputImageReference): Promise<Buffer>;
+export declare function copyInputImages(sourceSessionDirectory: string, targetSessionDirectory: string, references: readonly InputImageReference[]): Promise<void>;
+/** A pending marker is removable only after the committed JSONL references are checked. */
+export declare function recoverPendingInputImages(sessionDirectory: string, readHistory: () => Promise<SessionRecord[]>): Promise<void>;
+export declare function writeInputImages(directory: string, images: readonly SessionInputImage[]): Promise<SessionInputImageMetadata[]>;
+export {};