@myagentroam/agent 0.11.32 → 0.11.34

package/dist/session/store/jsonl/history.js

@@ -0,0 +1,181 @@
+import { randomUUID } from 'node:crypto';
+import { open, readdir, rename, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { AgentError } from '../../../error.js';
+import { parseInlineMediaState } from '../../inline-media.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 AgentError('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 };
+    const remapWindow = (value) => {
+        const state = parseInlineMediaState(value);
+        if (!state)
+            return value;
+        for (const cursor of [state.consideredThrough, state.evictedThrough]) {
+            if (!cursor?.sourceId.startsWith('input:'))
+                continue;
+            const target = identities.get(cursor.sourceId.slice(6));
+            if (!target)
+                throw new AgentError('MAR_AGENT_SESSION_CORRUPT', 'Fork media reference is missing.');
+            cursor.sourceId = `input:${target.recordId}`;
+        }
+        return state;
+    };
+    if (type === 'resource.window')
+        return remapWindow(payload);
+    if (payload.sessionId === sourceSessionId)
+        payload.sessionId = targetSessionId;
+    const application = (input) => {
+        if (typeof input.inputRef !== 'string') {
+            const recordId = isObject(input.metadata) ? input.metadata.recordId : undefined;
+            const identity = typeof recordId === 'string' ? identities.get(recordId) : undefined;
+            return identity && isObject(input.metadata)
+                ? { ...input, metadata: { ...input.metadata, recordId: identity.recordId } }
+                : input;
+        }
+        const identity = identities.get(input.inputRef);
+        if (!identity)
+            throw new AgentError('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 (payload.inlineMediaState)
+            payload.inlineMediaState = remapWindow(payload.inlineMediaState);
+        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 AgentError('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/session/store/jsonl/images.d.ts

@@ -0,0 +1,19 @@
+import type { 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;
+    readonly resourceId?: string;
+    readonly url?: string;
+    readonly urlExpiresAt?: number;
+}
+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 {};

package/dist/session/store/jsonl/images.js

@@ -0,0 +1,122 @@
+import { copyFile, mkdir, open, readFile } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+import { AgentError } from '../../../error.js';
+import { isModelImageUrl } from '../../../model/image.js';
+export const MAX_INPUT_IMAGES = 5;
+const MAX_INPUT_IMAGE_BYTES = 5 * 1024 * 1024;
+const MAX_INPUT_IMAGES_BYTES = 10 * 1024 * 1024;
+const INPUT_IMAGE_MIME_TYPES = new Set(['image/png', 'image/jpeg', 'image/gif', 'image/webp']);
+export function generatedImageFileNames(records) {
+    const names = new Set();
+    for (const record of records) {
+        if (record.type !== 'tool.completed' || !isObject(record.payload))
+            continue;
+        const artifacts = record.payload.artifacts;
+        if (!Array.isArray(artifacts))
+            continue;
+        for (const artifact of artifacts) {
+            if (!isObject(artifact) ||
+                artifact.kind !== 'image' ||
+                typeof artifact.fileName !== 'string' ||
+                basename(artifact.fileName) !== artifact.fileName ||
+                !/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}\.png$/u.test(artifact.fileName))
+                continue;
+            names.add(artifact.fileName);
+        }
+    }
+    return [...names];
+}
+export async function copyGeneratedImages(sourceSessionDirectory, targetSessionDirectory, fileNames) {
+    if (fileNames.length === 0)
+        return;
+    const source = join(sourceSessionDirectory, 'generated_images');
+    const target = join(targetSessionDirectory, 'generated_images');
+    await mkdir(target, { recursive: true });
+    for (const fileName of fileNames) {
+        const path = join(target, fileName);
+        await copyFile(join(source, fileName), path);
+        const handle = await open(path, 'r');
+        try {
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+    }
+}
+export function inputImageReferences(value) {
+    if (!Array.isArray(value))
+        return [];
+    const references = [];
+    let totalBytes = 0;
+    for (const image of value) {
+        const reference = inputImageReference(image);
+        if (reference === undefined)
+            continue;
+        totalBytes += reference.byteSize;
+        if (references.length >= MAX_INPUT_IMAGES || totalBytes > MAX_INPUT_IMAGES_BYTES)
+            throw corruptInputImageReference();
+        references.push(reference);
+    }
+    return references;
+}
+export function inputImageReference(value) {
+    if (!isObject(value) ||
+        (!Object.hasOwn(value, 'fileName') && !Object.hasOwn(value, 'resourceId')))
+        return undefined;
+    const fileName = value.fileName ??
+        (typeof value.resourceId === 'string' ? `${value.resourceId}.bin` : undefined);
+    if (typeof value.name !== 'string' ||
+        typeof value.mimeType !== 'string' ||
+        !INPUT_IMAGE_MIME_TYPES.has(value.mimeType) ||
+        typeof value.byteSize !== 'number' ||
+        !Number.isSafeInteger(value.byteSize) ||
+        value.byteSize <= 0 ||
+        value.byteSize > MAX_INPUT_IMAGE_BYTES ||
+        typeof fileName !== 'string' ||
+        !validInputImageFileName(fileName) ||
+        typeof value.sha256 !== 'string' ||
+        !/^[a-f0-9]{64}$/u.test(value.sha256) ||
+        (value.resourceId !== undefined &&
+            (typeof value.resourceId !== 'string' ||
+                !/^[a-f0-9]{64}$/u.test(value.resourceId) ||
+                fileName !== `${value.resourceId}.bin`)) ||
+        (value.url !== undefined && !isModelImageUrl(value.url)) ||
+        (value.urlExpiresAt !== undefined &&
+            (typeof value.urlExpiresAt !== 'number' ||
+                !Number.isSafeInteger(value.urlExpiresAt) ||
+                value.urlExpiresAt <= 0)) ||
+        (value.urlExpiresAt !== undefined && value.url === undefined))
+        throw corruptInputImageReference();
+    return {
+        name: value.name,
+        fileName,
+        mimeType: value.mimeType,
+        byteSize: value.byteSize,
+        sha256: value.sha256,
+        ...(typeof value.resourceId === 'string' ? { resourceId: value.resourceId } : {}),
+        ...(value.url === undefined ? {} : { url: value.url }),
+        ...(typeof value.urlExpiresAt === 'number' ? { urlExpiresAt: value.urlExpiresAt } : {})
+    };
+}
+export function validInputImageFileName(fileName) {
+    return (basename(fileName) === fileName && /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}\.bin$/u.test(fileName));
+}
+export async function readInputImageBytes(directory, reference) {
+    try {
+        return await readFile(join(directory, reference.fileName));
+    }
+    catch (cause) {
+        throw new AgentError('MAR_AGENT_IMAGE_UNAVAILABLE', 'Session input image is unavailable.', {
+            cause
+        });
+    }
+}
+function corruptInputImageReference(cause) {
+    return new AgentError('MAR_AGENT_SESSION_CORRUPT', 'Session input image is corrupt.', {
+        ...(cause === undefined ? {} : { cause })
+    });
+}
+function isObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}

package/dist/session/store/jsonl/index-transaction.d.ts

@@ -0,0 +1,13 @@
+import { AgentError } from '../../../error.js';
+import type { SessionIndex, SessionMeta } from '../types.js';
+export declare class ParentPublicationRejected extends AgentError {
+}
+/** Runs the short disk index transaction; the caller owns its cache. */
+export declare function commitSessionIndex(root: string, snapshot: () => {
+    index: SessionIndex;
+    dirty: ReadonlyMap<string, number>;
+    derivedOnly: ReadonlySet<string>;
+}, committed: (index: SessionIndex, dirty: ReadonlyMap<string, number>, created: ReadonlySet<string>) => void, deletedIds?: string | readonly string[], createdIds?: readonly string[], onPersisted?: () => void, storageSelection?: {
+    readonly before: SessionMeta;
+    readonly generation: string;
+}, deleteExpected?: readonly SessionMeta[]): Promise<void>;

package/dist/session/store/jsonl/index-transaction.js

@@ -0,0 +1,87 @@
+import { lstat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+import { AgentError } from '../../../error.js';
+import { acquireFileLock } from '../../../storage/file-lock.js';
+import { normalizeSessionSource, persistFormatSelection, prepareSessionIndexCommit, readSessionIndex } from './directory-index.js';
+import { treeDeleteMarker } from './transaction-recovery.js';
+export class ParentPublicationRejected extends AgentError {
+}
+/** Runs the short disk index transaction; the caller owns its cache. */
+export async function commitSessionIndex(root, snapshot, committed, deletedIds, createdIds = [], onPersisted, storageSelection, deleteExpected) {
+    const release = await acquireFileLock(join(root, 'sessions', 'index.lock'));
+    const path = join(root, 'sessions', 'index.json');
+    let failure;
+    try {
+        const disk = await readSessionIndex(path);
+        if (!disk)
+            throw new AgentError('MAR_AGENT_SESSION_CORRUPT', 'Session index is missing.');
+        for (const id of createdIds) {
+            const created = snapshot().index.sessions.find((entry) => entry.id === id);
+            if (!created)
+                throw new AgentError('MAR_AGENT_SESSION_CORRUPT', 'Session publication is missing.');
+            const source = normalizeSessionSource(created.source);
+            if (source.type !== 'subagent')
+                continue;
+            if (!disk.sessions.some((entry) => entry.id === source.parentSessionId))
+                throw new ParentPublicationRejected('MAR_AGENT_SESSION_NOT_FOUND', 'Parent Session was not found.');
+            try {
+                await lstat(treeDeleteMarker(join(root, 'sessions'), source.parentSessionId));
+                throw new ParentPublicationRejected('MAR_AGENT_SESSION_LOCKED', 'Parent Session is under maintenance.');
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+            }
+        }
+        if (deleteExpected) {
+            const ids = new Set(deleteExpected.map((entry) => entry.id));
+            for (const expected of deleteExpected) {
+                const current = disk.sessions.find((entry) => entry.id === expected.id);
+                if (!current ||
+                    current.createdAt !== expected.createdAt ||
+                    current.workspace !== expected.workspace ||
+                    !isDeepStrictEqual(current.source, expected.source) ||
+                    !isDeepStrictEqual(current.storage, expected.storage) ||
+                    current.storageTransactionId !== expected.storageTransactionId ||
+                    current.nextSequence !== expected.nextSequence)
+                    throw new AgentError('MAR_AGENT_SESSION_CORRUPT', 'Session tree changed during deletion.');
+            }
+            for (const entry of disk.sessions) {
+                const source = normalizeSessionSource(entry.source);
+                if (source.type === 'subagent' && ids.has(source.parentSessionId) && !ids.has(entry.id))
+                    throw new AgentError('MAR_AGENT_SESSION_CORRUPT', 'Session tree changed during deletion.');
+            }
+        }
+        const local = snapshot();
+        const dirty = local.dirty;
+        const derivedOnly = local.derivedOnly;
+        const created = new Set(createdIds);
+        const updated = prepareSessionIndexCommit(disk, local.index, dirty, derivedOnly, deletedIds, createdIds);
+        if (storageSelection) {
+            const before = storageSelection.before;
+            const selected = disk.sessions.find((item) => item.id === before.id);
+            const replacement = updated.sessions.find((item) => item.id === before.id);
+            if (!selected ||
+                !replacement ||
+                !isDeepStrictEqual(selected.storage, before.storage) ||
+                selected.nextSequence !== before.nextSequence ||
+                selected.storageTransactionId !== before.storageTransactionId)
+                throw new AgentError('MAR_AGENT_SESSION_CORRUPT', 'Session history changed during replacement.');
+            replacement.storage = { encoding: 2, generation: storageSelection.generation };
+        }
+        await persistFormatSelection(path, updated);
+        onPersisted?.();
+        committed(updated, dirty, created);
+    }
+    catch (error) {
+        failure = error;
+        throw error;
+    }
+    finally {
+        if (failure !== undefined)
+            await release().catch(() => undefined);
+        else
+            await release();
+    }
+}

package/dist/session/store/jsonl/jsonl-admission.d.ts

@@ -0,0 +1,10 @@
+/** Read-only version admission before any v1 recovery can modify its evidence. */
+export declare function preflightV1Session(directory: string): Promise<void>;
+/** Inspect history only when an existing v2 recovery may replace or remove it. */
+export declare function preflightV2Recovery(directory: string): Promise<void>;
+/** Retired paths may be restored or deleted by the same journal, including other generations. */
+export declare function preflightRetiredRecovery(root: string, journalDirectory: string): Promise<void>;
+/** Check known versioned fields without treating ordinary corruption as a future format. */
+export declare function admitV1RecordVersion(line: string): void;
+export declare function admitWorldStateVersion(value: unknown): void;
+export declare function admitResourceMetadataVersion(value: unknown): void;

package/dist/session/store/jsonl/jsonl-admission.js

@@ -0,0 +1,205 @@
+import { readFile, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { AgentError } from '../../../error.js';
+import { retiredSessionTrashPath } from './transaction-recovery.js';
+import { decodeJsonlValue } from './jsonl-codec.js';
+const SEGMENT_OR_STAGE = /^events-\d{6}\.jsonl(?:\.[0-9a-f-]{36}\.(?:rollback-tmp|rollback-backup|clear-backup))?$/iu;
+const WORLD_STATE = /^context-world-state\.json(?:\.\d+\.[0-9a-f-]+\.(?:rollback|clear)-backup)?$/iu;
+const JOURNAL_TEMP = /^storage-transaction\.json\.[0-9a-f-]{36}\.tmp$/iu;
+/** Read-only version admission before any v1 recovery can modify its evidence. */
+export async function preflightV1Session(directory) {
+    await preflightSession(directory, 1, false);
+}
+/** Inspect history only when an existing v2 recovery may replace or remove it. */
+export async function preflightV2Recovery(directory) {
+    await preflightSession(directory, 2, true);
+}
+/** Retired paths may be restored or deleted by the same journal, including other generations. */
+export async function preflightRetiredRecovery(root, journalDirectory) {
+    let journal;
+    try {
+        journal = await readJsonIfComplete(join(journalDirectory, 'storage-transaction.json'));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return;
+        throw error;
+    }
+    if (!isObject(journal) || typeof journal.id !== 'string' || !/^[0-9a-f-]{36}$/iu.test(journal.id))
+        return;
+    if (typeof journal.targetGeneration === 'string' &&
+        /^[0-9a-f-]{36}$/iu.test(journal.targetGeneration))
+        await preflightSession(join(root, 'v2', journal.targetGeneration), 2, false);
+    if (!Array.isArray(journal.retiredPaths))
+        return;
+    for (const path of journal.retiredPaths) {
+        if (typeof path !== 'string' ||
+            !/^(?:events-\d{6}\.jsonl|resources|tool_results|context-world-state\.json|v2\/[0-9a-f-]{36})$/u.test(path))
+            continue;
+        for (const candidate of [join(root, path), retiredSessionTrashPath(root, path, journal.id)]) {
+            if (path.startsWith('v2/'))
+                await preflightSession(candidate, 2, false);
+            else if (path === 'resources')
+                await admitResourceDirectory(candidate);
+            else if (path === 'context-world-state.json') {
+                try {
+                    admitWorldStateVersion(await readJsonIfComplete(candidate));
+                }
+                catch (error) {
+                    if (error.code !== 'ENOENT')
+                        throw error;
+                }
+            }
+            else if (path.startsWith('events-'))
+                await admitSegment(candidate, 1);
+        }
+    }
+}
+async function admitSegment(path, encoding) {
+    let content;
+    try {
+        content = await readFile(path, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return;
+        throw error;
+    }
+    for (const line of content.split('\n')) {
+        if (!line)
+            continue;
+        let value;
+        try {
+            value = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        admitRecordVersion(value, encoding);
+    }
+}
+async function preflightSession(directory, encoding, recoveryOnly) {
+    let names;
+    try {
+        names = await readdir(directory);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return;
+        throw error;
+    }
+    const journalPresent = names.includes('storage-transaction.json');
+    for (const name of names) {
+        const path = join(directory, name);
+        if (SEGMENT_OR_STAGE.test(name)) {
+            if (recoveryOnly && !journalPresent && /^events-\d{6}\.jsonl$/iu.test(name))
+                continue;
+            await admitSegment(path, encoding);
+        }
+        else if (name === 'storage-transaction.json' ||
+            JOURNAL_TEMP.test(name) ||
+            WORLD_STATE.test(name)) {
+            if (recoveryOnly && !journalPresent && name === 'context-world-state.json')
+                continue;
+            const value = await readJsonIfComplete(path);
+            if (isObject(value)) {
+                if (name === 'storage-transaction.json' || JOURNAL_TEMP.test(name))
+                    rejectFuture(value.version, 1);
+                else
+                    admitWorldStateVersion(value);
+            }
+        }
+    }
+    if (recoveryOnly && !journalPresent) {
+        await admitPendingResources(join(directory, 'resources'));
+        return;
+    }
+    await admitResourceDirectory(join(directory, 'resources'));
+    await admitPendingResources(join(directory, 'resources'));
+}
+async function admitPendingResources(directory) {
+    let names;
+    try {
+        names = await readdir(directory);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return;
+        throw error;
+    }
+    const metadata = new Set();
+    for (const name of names) {
+        const pending = /^\.([a-f0-9]{64})\.pending$/u.exec(name);
+        if (pending)
+            metadata.add(`${pending[1]}.json`);
+        if (/^\.[a-f0-9]{64}\.json\.[a-f0-9-]{36}\.tmp$/u.test(name))
+            metadata.add(name);
+    }
+    for (const name of metadata) {
+        try {
+            admitResourceMetadataVersion(await readJsonIfComplete(join(directory, name)));
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+    }
+}
+async function admitResourceDirectory(resources) {
+    let resourceNames;
+    try {
+        resourceNames = await readdir(resources);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return;
+        throw error;
+    }
+    for (const name of resourceNames) {
+        if (!/^(?:[a-f0-9]{64}\.json|\.[a-f0-9]{64}\.json\.[0-9a-f-]{36}\.rollback-trash)$/iu.test(name))
+            continue;
+        const value = await readJsonIfComplete(join(resources, name));
+        admitResourceMetadataVersion(value);
+    }
+}
+/** Check known versioned fields without treating ordinary corruption as a future format. */
+export function admitV1RecordVersion(line) {
+    const value = JSON.parse(line);
+    admitRecordVersion(value, 1);
+}
+function admitRecordVersion(value, encoding) {
+    try {
+        decodeJsonlValue(value, encoding);
+    }
+    catch (error) {
+        if (error instanceof AgentError && error.code === 'MAR_AGENT_SESSION_VERSION_UNSUPPORTED')
+            throw error;
+    }
+}
+async function readJsonIfComplete(path) {
+    const content = await readFile(path, 'utf8');
+    try {
+        return JSON.parse(content);
+    }
+    catch {
+        return undefined;
+    }
+}
+function rejectFuture(version, supported) {
+    if (typeof version === 'number' && Number.isSafeInteger(version) && version > supported)
+        throw new AgentError('MAR_AGENT_SESSION_VERSION_UNSUPPORTED', 'Session encoding is unsupported.');
+}
+export function admitWorldStateVersion(value) {
+    if (!isObject(value))
+        return;
+    rejectFuture(value.version, 1);
+    if (isObject(value.state))
+        rejectFuture(value.state.version, 2);
+}
+export function admitResourceMetadataVersion(value) {
+    if (isObject(value))
+        rejectFuture(value.resourceInputVersion, 1);
+}
+function isObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}

package/dist/session/store/jsonl/jsonl-codec.d.ts

@@ -0,0 +1,11 @@
+import type { SessionRecord } from '../types.js';
+type LogicalSessionRecord = SessionRecord;
+/** Decode one complete JSONL record using the encoding selected by the Session index. */
+export declare function decodeJsonlRecord(line: string, encoding: number): LogicalSessionRecord;
+/** Decode an already-parsed line without repeating JSON parsing. */
+export declare function decodeJsonlValue(value: unknown, encoding: number): LogicalSessionRecord;
+/** Encode one v2 record without a line delimiter; the segment writer owns framing. */
+export declare function encodeJsonlRecord(record: LogicalSessionRecord, encoding: number): string;
+/** Normalize known physical image references without examining unrelated payload fields. */
+export declare function normalizeJsonlRecord(record: LogicalSessionRecord): LogicalSessionRecord;
+export {};