@myagentroam/agent 0.11.32 → 0.11.34

package/dist/session/store/jsonl/open-recovery.d.ts

@@ -0,0 +1,13 @@
+import type { SessionIndex, SessionMeta, SessionRecord } from '../types.js';
+export declare const CONTEXTUAL_WORLD_STATE_FILE = "context-world-state.json";
+/** Recover the physical tail and pending resources while the caller holds the Session lease. */
+export declare function recoverJsonlTail(directory: string, latestPath: string, readHistory: () => Promise<SessionRecord[]>, encoding?: number): Promise<{
+    records: SessionRecord[];
+    segment: number;
+}>;
+/** Open the index without recovering or changing any existing Session. */
+export declare function openJsonlIndex(root: string): Promise<SessionIndex>;
+/** Reclaim only marked unpublished creations, never published Session history. */
+export declare function reclaimUnpublishedSessions(root: string): Promise<void>;
+export declare function sessionDirectoryExists(path: string): Promise<boolean>;
+export declare function recoverContextualWorldStateTransactions(root: string, meta: SessionMeta): Promise<void>;

package/dist/session/store/jsonl/open-recovery.js

@@ -0,0 +1,131 @@
+import { lstat, mkdir, readdir, rename, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { AgentError } from '../../../error.js';
+import { acquireFileLock } from '../../../storage/file-lock.js';
+import { cleanupUnreferencedToolResources } from '../../tool-result-resources.js';
+import { persistFormatSelection, readSessionIndex } from './directory-index.js';
+import { readRecords, repairSegmentTail } from './records.js';
+import { recoverResources } from './resources.js';
+import { withSessionReadDrain } from './read-pins.js';
+export const CONTEXTUAL_WORLD_STATE_FILE = 'context-world-state.json';
+/** Recover the physical tail and pending resources while the caller holds the Session lease. */
+export async function recoverJsonlTail(directory, latestPath, readHistory, encoding = 1) {
+    await repairSegmentTail(latestPath, encoding);
+    const records = await readRecords(latestPath, encoding);
+    let history;
+    const sharedHistory = () => (history ??= readHistory());
+    await recoverResources(join(directory, 'resources'), sharedHistory);
+    await cleanupUnreferencedToolResources(directory, sharedHistory);
+    const match = /events-(\d{6})\.jsonl$/.exec(latestPath);
+    return { records, segment: Number(match?.[1] ?? 1) };
+}
+/** Open the index without recovering or changing any existing Session. */
+export async function openJsonlIndex(root) {
+    const directory = join(root, 'sessions');
+    const path = join(directory, 'index.json');
+    await mkdir(directory, { recursive: true });
+    const release = await acquireFileLock(join(directory, 'index.lock'));
+    let index;
+    try {
+        const disk = await readSessionIndex(path);
+        if (disk)
+            index = disk;
+        else {
+            const entries = await readdir(directory, { withFileTypes: true });
+            if (entries.some((entry) => entry.isDirectory()))
+                throw new AgentError('MAR_AGENT_SESSION_CORRUPT', 'Session index is missing.');
+            index = { version: 2, revision: 0, sessions: [] };
+            await persistFormatSelection(path, index);
+        }
+    }
+    finally {
+        await release();
+    }
+    return index;
+}
+/** Reclaim only marked unpublished creations, never published Session history. */
+export async function reclaimUnpublishedSessions(root) {
+    const directory = join(root, 'sessions');
+    const path = join(directory, 'index.json');
+    for (const entry of await readdir(directory, { withFileTypes: true })) {
+        if (!entry.isDirectory() || !/^[0-9a-f-]{36}$/iu.test(entry.name))
+            continue;
+        const candidate = join(directory, entry.name);
+        const marker = join(candidate, 'publication-pending');
+        try {
+            if (!(await lstat(marker)).isFile())
+                continue;
+        }
+        catch {
+            continue;
+        }
+        let release;
+        try {
+            release = await acquireFileLock(join(candidate, 'lock'), 'Session already has a writer.', 0);
+        }
+        catch {
+            continue;
+        }
+        try {
+            const index = await readSessionIndex(path);
+            if (!index)
+                throw new AgentError('MAR_AGENT_SESSION_CORRUPT', 'Session index is missing.');
+            try {
+                if (!index.sessions.some((session) => session.id === entry.name))
+                    await withSessionReadDrain(candidate, () => rm(candidate, { recursive: true, force: true }));
+            }
+            catch {
+                // A damaged unrelated candidate must not prevent another Session from being written.
+            }
+        }
+        finally {
+            await release().catch(() => undefined);
+        }
+    }
+}
+export async function sessionDirectoryExists(path) {
+    try {
+        await lstat(path);
+        return true;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+}
+export async function recoverContextualWorldStateTransactions(root, meta) {
+    const sessionDirectory = join(root, 'sessions', meta.id);
+    const directory = meta.storage?.encoding === 2
+        ? join(sessionDirectory, 'v2', meta.storage.generation)
+        : sessionDirectory;
+    let names;
+    try {
+        names = await readdir(directory);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return;
+        throw error;
+    }
+    const pattern = /^context-world-state\.json\.(\d+)\.[0-9a-f-]+\.(?:rollback|clear)-backup$/u;
+    const backups = names.filter((name) => pattern.test(name));
+    if (backups.length === 0)
+        return;
+    const eventNames = names.filter((name) => /^events-\d{6}\.jsonl$/u.test(name)).sort();
+    const latestEventName = eventNames.at(-1);
+    if (latestEventName === undefined)
+        throw new AgentError('MAR_AGENT_SESSION_CORRUPT', 'Session history is corrupt.');
+    const latestRecords = await readRecords(join(directory, latestEventName), meta.storage?.encoding ?? 1);
+    const actualNextSequence = (latestRecords.at(-1)?.sequence ?? 0) + 1;
+    const canonical = join(directory, CONTEXTUAL_WORLD_STATE_FILE);
+    for (const name of backups) {
+        const match = pattern.exec(name);
+        const backup = join(directory, name);
+        const targetNextSequence = Number(match[1]);
+        if (actualNextSequence === targetNextSequence || (await sessionDirectoryExists(canonical)))
+            await rm(backup, { force: true });
+        else
+            await rename(backup, canonical);
+    }
+}

package/dist/session/store/jsonl/read-pins.d.ts

@@ -0,0 +1,4 @@
+/** Pin before selecting the index entry; nested reads reuse their caller's pin. */
+export declare function withSessionReadPin<T>(root: string, action: () => Promise<T>, allowMissing?: boolean): Promise<T>;
+/** Caller holds the Session writer; block new pins and drain existing readers before retirement. */
+export declare function withSessionReadDrain<T>(root: string, action: () => Promise<T>): Promise<T>;

package/dist/session/store/jsonl/read-pins.js

@@ -0,0 +1,131 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { randomUUID } from 'node:crypto';
+import { lstat, mkdir, readdir, rmdir, stat } from 'node:fs/promises';
+import { basename, dirname, join } from 'node:path';
+import { AgentError } from '../../../error.js';
+import { acquireFileLock } from '../../../storage/file-lock.js';
+import { treeDeleteMarker } from './transaction-recovery.js';
+const heldPins = new AsyncLocalStorage();
+const PIN = /^[0-9a-f-]{36}$/u;
+async function pinPaths(root) {
+    const parent = join(dirname(root), '.read-pins');
+    try {
+        await mkdir(parent, { mode: 0o700 });
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            throw new AgentError('MAR_AGENT_SESSION_NOT_FOUND', 'Session was not found.');
+        if (error.code !== 'EEXIST')
+            throw error;
+    }
+    const id = basename(root);
+    return { gate: join(parent, `${id}.lock`), directory: join(parent, id) };
+}
+/** Pin before selecting the index entry; nested reads reuse their caller's pin. */
+export async function withSessionReadPin(root, action, allowMissing = false) {
+    const current = heldPins.getStore();
+    if (current?.has(root))
+        return action();
+    const paths = await pinPaths(root);
+    const releaseGate = await acquireFileLock(paths.gate);
+    let releasePin;
+    let failure;
+    try {
+        try {
+            await lstat(treeDeleteMarker(dirname(root), basename(root)));
+            throw new AgentError('MAR_AGENT_SESSION_CORRUPT', 'Session deletion recovery is required.');
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        try {
+            if (!(await stat(root)).isDirectory())
+                throw new AgentError('MAR_AGENT_SESSION_NOT_FOUND', 'Session was not found.');
+        }
+        catch (error) {
+            if (error.code === 'ENOENT' && allowMissing) {
+                // Metadata may legitimately outlive a missing directory until stale-index cleanup.
+            }
+            else if (error.code === 'ENOENT')
+                throw new AgentError('MAR_AGENT_SESSION_NOT_FOUND', 'Session was not found.');
+            else
+                throw error;
+        }
+        await mkdir(paths.directory, { mode: 0o700, recursive: true });
+        releasePin = await acquireFileLock(join(paths.directory, randomUUID()));
+    }
+    catch (error) {
+        failure = { error };
+    }
+    try {
+        await releaseGate();
+    }
+    catch (error) {
+        failure ??= { error };
+    }
+    if (failure) {
+        await releasePin?.().catch(() => undefined);
+        throw failure.error;
+    }
+    let result;
+    try {
+        result = await heldPins.run(new Set([...(current ?? []), root]), action);
+    }
+    catch (error) {
+        failure = { error };
+    }
+    try {
+        await releasePin();
+    }
+    catch (error) {
+        failure ??= { error };
+    }
+    if (failure)
+        throw failure.error;
+    return result;
+}
+/** Caller holds the Session writer; block new pins and drain existing readers before retirement. */
+export async function withSessionReadDrain(root, action) {
+    const paths = await pinPaths(root);
+    const releaseGate = await acquireFileLock(paths.gate);
+    let result;
+    let failure;
+    try {
+        let entries;
+        try {
+            entries = await readdir(paths.directory);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+            entries = [];
+        }
+        const deadline = Date.now() + 30_000;
+        for (const name of entries.filter((entry) => PIN.test(entry))) {
+            const release = await acquireFileLock(join(paths.directory, name), 'Session readers are busy.', Math.max(0, deadline - Date.now()));
+            await release();
+        }
+        try {
+            await rmdir(paths.directory);
+        }
+        catch (error) {
+            if (!['ENOENT', 'ENOTEMPTY'].includes(error.code ?? ''))
+                throw error;
+        }
+        const current = heldPins.getStore();
+        result = await heldPins.run(new Set([...(current ?? []), root]), action);
+    }
+    catch (error) {
+        failure = { error };
+    }
+    try {
+        await releaseGate();
+    }
+    catch (error) {
+        failure ??= { error };
+    }
+    if (failure)
+        throw failure.error;
+    return result;
+}

package/dist/session/store/jsonl/record-append.d.ts

@@ -0,0 +1,16 @@
+import type { SessionRecordInput } from '../contracts.js';
+import type { SessionRecord } from '../types.js';
+interface AppendRecordContext {
+    readonly sequence: number;
+    directory(): string;
+    readRecordAtSequence(sequence: number): Promise<SessionRecord | undefined>;
+    currentSegment(): Promise<number>;
+    segmentPath(segment: number): string;
+    setCurrentSegment(segment: number): void;
+    markWriteFailure(error: unknown): void;
+    invalidateAfterWriteFailure(): void;
+    publish(record: SessionRecord, serialized: string, segment: number): void;
+}
+/** Bind resources and publish a single durable append under the caller's Session writer. */
+export declare function appendSessionRecord(sessionId: string, input: SessionRecordInput, context: AppendRecordContext): Promise<SessionRecord>;
+export {};

package/dist/session/store/jsonl/record-append.js

@@ -0,0 +1,49 @@
+import { randomUUID } from 'node:crypto';
+import { stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { bindToolResultResources, completeToolResultResources } from '../../tool-result-resources.js';
+import { appendRecordBytes, MAX_SEGMENT_BYTES } from './records.js';
+import { completeResources } from './resources.js';
+import { normalizeJsonlRecord } from './jsonl-codec.js';
+/** Bind resources and publish a single durable append under the caller's Session writer. */
+export async function appendSessionRecord(sessionId, input, context) {
+    const record = normalizeJsonlRecord({
+        recordId: randomUUID(),
+        sequence: context.sequence,
+        timestamp: input.timestamp ?? new Date().toISOString(),
+        sessionId,
+        ...(input.executionId ? { executionId: input.executionId } : {}),
+        ...(input.turnId ? { turnId: input.turnId } : {}),
+        type: input.type,
+        payload: input.payload
+    });
+    JSON.stringify(record); // Reject malformed payloads before binding resources.
+    await bindToolResultResources(context.directory(), record, context.readRecordAtSequence, true);
+    const serialized = `${JSON.stringify(record)}\n`;
+    let segment = await context.currentSegment();
+    let path = context.segmentPath(segment);
+    try {
+        const current = await stat(path);
+        if (current.size > 0 && current.size + Buffer.byteLength(serialized) > MAX_SEGMENT_BYTES) {
+            segment += 1;
+            context.setCurrentSegment(segment);
+            path = context.segmentPath(segment);
+        }
+    }
+    catch {
+        // The first append creates the first segment.
+    }
+    try {
+        await appendRecordBytes(path, serialized, context.markWriteFailure);
+    }
+    catch (error) {
+        context.invalidateAfterWriteFailure();
+        throw error;
+    }
+    // The callback synchronously publishes onto the metadata current after file I/O.
+    context.publish(record, serialized, segment);
+    await completeToolResultResources(context.directory(), record);
+    // The record is already durable and published; pending markers are recoverable cleanup.
+    await completeResources(join(context.directory(), 'resources'), record).catch(() => undefined);
+    return record;
+}

package/dist/session/store/jsonl/records.d.ts

@@ -0,0 +1,30 @@
+import type { SessionMeta, SessionRecord } from '../types.js';
+interface HistoryPagePositions {
+    readonly signature: string;
+    readonly offsets: Map<number, number>;
+}
+export declare const MAX_SEGMENT_BYTES: number;
+/** Read only the prefix needed by discovery; never load the entire transcript. */
+export declare function readRecordsFromHead(path: string, encoding?: number): AsyncGenerator<SessionRecord>;
+export declare function readRecords(path: string, encoding?: number): Promise<SessionRecord[]>;
+/** Repair only the final record under the Session writer lock; never skip middle damage. */
+export declare function repairSegmentTail(path: string, encoding?: number): Promise<void>;
+/** Decode complete records newest-first, releasing the file as soon as a reader stops. */
+export declare function readRecordsFromTail(path: string, page?: {
+    readonly beforeSequence: number;
+    readonly limit: number;
+    readonly positions: Map<string, HistoryPagePositions>;
+}, encoding?: number): AsyncGenerator<SessionRecord>;
+/** Owns bounded reverse-read positions for the shared Store domain. */
+export declare class SessionHistoryPageReader {
+    #private;
+    read(meta: SessionMeta, input: {
+        limit?: number;
+        beforeSequence?: number;
+    }, segmentPaths: () => Promise<string[]>): Promise<{
+        records: SessionRecord[];
+        previousBeforeSequence?: number;
+    }>;
+}
+export declare function appendRecordBytes(path: string, serialized: string, onWriteFailure: (error: unknown) => void): Promise<void>;
+export {};