@myagentroam/agent 0.11.32 → 0.11.34

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

@@ -0,0 +1,374 @@
+import { randomUUID } from 'node:crypto';
+import { lstat, mkdir, readFile, readdir, rename, rm, writeFile } from 'node:fs/promises';
+import { basename, dirname, join } from 'node:path';
+import { AgentError } from '../../../error.js';
+const JOURNAL = 'storage-transaction.json';
+const SEGMENT = /^events-\d{6}\.jsonl$/u;
+const TRANSACTION_ID = /^[0-9a-f-]{36}$/iu;
+const STAGING_FILE = /^events-\d{6}\.jsonl\.[0-9a-f-]{36}\.rollback-tmp$/iu;
+const JOURNAL_TEMP = /^storage-transaction\.json\.[0-9a-f-]{36}\.tmp$/iu;
+export function treeDeleteMarker(root, sessionId) {
+    return join(root, '.delete-pending', sessionId);
+}
+function treeDeleteTrash(root, sessionId, id) {
+    return join(root, sessionId, `.delete-${id}.trash`);
+}
+export async function readTreeDeleteTransaction(root, sessionId) {
+    let marker;
+    try {
+        marker = await readFile(treeDeleteMarker(root, sessionId), 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+    try {
+        const anchor = marker.startsWith('{') ? sessionId : marker;
+        if (!TRANSACTION_ID.test(anchor))
+            throw new Error('invalid deletion marker');
+        const content = anchor === sessionId ? marker : await readFile(treeDeleteMarker(root, anchor), 'utf8');
+        const journal = JSON.parse(content);
+        if (typeof journal.version === 'number' && journal.version > 1)
+            throw new AgentError('MAR_AGENT_SESSION_VERSION_UNSUPPORTED', 'Session encoding is unsupported.');
+        if (journal.version !== 1 ||
+            journal.kind !== 'delete' ||
+            !TRANSACTION_ID.test(journal.id) ||
+            (journal.phase !== undefined &&
+                journal.phase !== 'preparing' &&
+                journal.phase !== 'ready' &&
+                journal.phase !== 'restored') ||
+            !Array.isArray(journal.members) ||
+            journal.members.length === 0 ||
+            journal.members[0]?.id !== anchor ||
+            !journal.members.every((member) => TRANSACTION_ID.test(member.id) &&
+                typeof member.existed === 'boolean' &&
+                typeof member.identity?.createdAt === 'string' &&
+                typeof member.identity.workspace === 'string' &&
+                Number.isSafeInteger(member.identity.nextSequence) &&
+                member.identity.nextSequence > 0) ||
+            new Set(journal.members.map((member) => member.id)).size !== journal.members.length ||
+            !journal.members.some((member) => member.id === sessionId))
+            throw new Error('invalid deletion journal');
+        return journal;
+    }
+    catch (cause) {
+        if (cause instanceof AgentError && cause.code === 'MAR_AGENT_SESSION_VERSION_UNSUPPORTED')
+            throw cause;
+        throw new AgentError('MAR_AGENT_SESSION_CORRUPT', 'Session deletion recovery is required.', {
+            cause
+        });
+    }
+}
+export async function beginTreeDeleteTransaction(root, transaction, sync) {
+    const markers = join(root, '.delete-pending');
+    await mkdir(markers, { recursive: true, mode: 0o700 });
+    await sync(root);
+    const anchor = transaction.members[0].id;
+    const journal = treeDeleteMarker(root, anchor);
+    await publishTreeDeleteMarker(journal, JSON.stringify({ ...transaction, phase: 'preparing' }));
+    await sync(markers);
+    for (const member of transaction.members.slice(1))
+        await publishTreeDeleteMarker(treeDeleteMarker(root, member.id), anchor);
+    await sync(markers);
+    await publishTreeDeletePhase(root, transaction, 'ready', sync);
+}
+async function publishTreeDeletePhase(root, transaction, phase, sync) {
+    const markers = join(root, '.delete-pending');
+    const journal = treeDeleteMarker(root, transaction.members[0].id);
+    const temporary = `${journal}.${randomUUID()}.tmp`;
+    let failure;
+    try {
+        await writeFile(temporary, JSON.stringify({ ...transaction, phase }), {
+            flag: 'wx',
+            mode: 0o600,
+            flush: true
+        });
+        await rename(temporary, journal);
+        await sync(markers);
+    }
+    catch (error) {
+        failure = error;
+        throw error;
+    }
+    finally {
+        if (failure !== undefined)
+            await rm(temporary, { force: true }).catch(() => undefined);
+        else
+            await rm(temporary, { force: true });
+    }
+}
+/** Callers hold the member read gate, so an existing marker must never be replaced. */
+async function publishTreeDeleteMarker(path, content) {
+    const temporary = `${path}.${randomUUID()}.tmp`;
+    let failure;
+    try {
+        await writeFile(temporary, content, { flag: 'wx', mode: 0o600, flush: true });
+        try {
+            await lstat(path);
+            throw new AgentError('MAR_AGENT_SESSION_CORRUPT', 'Session deletion recovery is required.');
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        await rename(temporary, path);
+    }
+    catch (error) {
+        failure = error;
+        throw error;
+    }
+    finally {
+        if (failure !== undefined)
+            await rm(temporary, { force: true }).catch(() => undefined);
+        else
+            await rm(temporary, { force: true });
+    }
+}
+/** Called only with all tree writers and read gates held. */
+export async function stageTreeDelete(root, transaction, sync) {
+    for (const member of transaction.members.toReversed()) {
+        if (!member.existed)
+            continue;
+        const directory = join(root, member.id);
+        const trash = treeDeleteTrash(root, member.id, transaction.id);
+        await mkdir(trash, { mode: 0o700 });
+        await sync(directory);
+        for (const name of await readdir(directory)) {
+            if (name === 'lock' || name === 'lock.reclaim' || join(directory, name) === trash)
+                continue;
+            await rename(join(directory, name), join(trash, name));
+            await sync(trash);
+            await sync(directory);
+        }
+        await sync(trash);
+        await sync(directory);
+    }
+}
+/** Index membership selects restore versus retirement; never infer commit from file presence. */
+export async function finishTreeDelete(root, transaction, committed, sync) {
+    for (const member of transaction.members) {
+        if (!member.existed)
+            continue;
+        const directory = join(root, member.id);
+        const trash = treeDeleteTrash(root, member.id, transaction.id);
+        if (committed)
+            await rm(directory, { recursive: true, force: true });
+        else {
+            let names;
+            try {
+                names = await readdir(trash);
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+                // A missing stage is safe only while the original Session root still exists.
+                if (!(await lstat(directory)).isDirectory())
+                    throw new AgentError('MAR_AGENT_SESSION_CORRUPT', 'Session deletion recovery is incomplete.');
+                continue;
+            }
+            for (const name of names) {
+                await rename(join(trash, name), join(directory, name));
+                await sync(directory);
+                await sync(trash);
+            }
+            await rm(trash, { recursive: true, force: true });
+            await sync(directory);
+        }
+    }
+    await sync(root);
+    if (!committed)
+        await publishTreeDeletePhase(root, transaction, 'restored', sync);
+    await finishTreeDeletePreparation(root, transaction, sync);
+}
+/** Remove only markers owned by the preparing or fully restored transaction. */
+export async function finishTreeDeletePreparation(root, transaction, sync) {
+    const anchor = transaction.members[0].id;
+    for (const member of transaction.members.slice(1)) {
+        const marker = treeDeleteMarker(root, member.id);
+        let owner;
+        try {
+            owner = await readFile(marker, 'utf8');
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                continue;
+            throw error;
+        }
+        if (owner === anchor)
+            await rm(marker, { force: true });
+    }
+    await sync(join(root, '.delete-pending'));
+    const journal = treeDeleteMarker(root, anchor);
+    try {
+        const current = JSON.parse(await readFile(journal, 'utf8'));
+        if (current.id === transaction.id)
+            await rm(journal, { force: true });
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    await sync(join(root, '.delete-pending'));
+}
+export function isUnjournaledTransactionFile(name) {
+    return STAGING_FILE.test(name) || JOURNAL_TEMP.test(name);
+}
+/** Deterministic names make a partially staged retirement recoverable from the same journal. */
+export function retiredSessionTrashPath(root, path, transactionId) {
+    const source = join(root, path);
+    return join(dirname(source), `.${basename(source)}.${transactionId}.retired-trash`);
+}
+/** The index's transaction ID, not the journal's existence, decides the commit side. */
+export async function beginSessionStorageTransaction(directory, transaction) {
+    const temporary = join(directory, `${JOURNAL}.${randomUUID()}.tmp`);
+    try {
+        await writeFile(temporary, JSON.stringify(transaction), {
+            mode: 0o600,
+            flag: 'wx',
+            flush: true
+        });
+        await rename(temporary, join(directory, JOURNAL));
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}
+/** Must run under the corresponding Session writer lock. Safe to repeat after interruption. */
+export async function recoverSessionStorageTransaction(directory, committedTransactionId, sessionDirectory = directory) {
+    const journal = join(directory, JOURNAL);
+    let raw;
+    try {
+        raw = await readFile(journal, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            await removeUnjournaledTransactionFiles(directory);
+            return;
+        }
+        throw error;
+    }
+    let transaction;
+    try {
+        transaction = JSON.parse(raw);
+        if (typeof transaction?.version === 'number' && transaction.version > 1)
+            throw new AgentError('MAR_AGENT_SESSION_VERSION_UNSUPPORTED', 'Session encoding is unsupported.');
+        if (transaction?.version !== 1 ||
+            !TRANSACTION_ID.test(transaction.id) ||
+            (transaction.kind !== 'rollback' && transaction.kind !== 'clear') ||
+            !Array.isArray(transaction.originalSegments) ||
+            !transaction.originalSegments.every((name) => typeof name === 'string' && SEGMENT.test(name)) ||
+            !Array.isArray(transaction.stagedSegments) ||
+            !transaction.stagedSegments.every((entry) => typeof entry?.path === 'string' &&
+                SEGMENT.test(entry.path) &&
+                typeof entry.temporary === 'string' &&
+                /^events-\d{6}\.jsonl\.[0-9a-f-]{36}\.rollback-tmp$/iu.test(entry.temporary) &&
+                entry.temporary.startsWith(`${entry.path}.`)) ||
+            typeof transaction.sidecarBackup !== 'string' ||
+            !new RegExp(`^context-world-state\\.json\\.\\d+\\.${transaction.id}\\.${transaction.kind}-backup$`, 'u').test(transaction.sidecarBackup) ||
+            (transaction.retiredPaths !== undefined &&
+                (!Array.isArray(transaction.retiredPaths) ||
+                    !transaction.retiredPaths.every((path) => typeof path === 'string' &&
+                        (/^events-\d{6}\.jsonl$/u.test(path) ||
+                            ['resources', 'tool_results', 'context-world-state.json'].includes(path) ||
+                            /^v2\/[0-9a-f-]{36}$/u.test(path)) &&
+                        join(sessionDirectory, path) !== directory))) ||
+            (transaction.targetGeneration !== undefined &&
+                (typeof transaction.targetGeneration !== 'string' ||
+                    !TRANSACTION_ID.test(transaction.targetGeneration) ||
+                    directory !== sessionDirectory)))
+            throw new Error('invalid session transaction');
+    }
+    catch (cause) {
+        if (cause instanceof AgentError && cause.code === 'MAR_AGENT_SESSION_VERSION_UNSUPPORTED')
+            throw cause;
+        throw new AgentError('MAR_AGENT_SESSION_CORRUPT', 'Session storage transaction is corrupt.', {
+            cause
+        });
+    }
+    const committed = transaction.id === committedTransactionId;
+    const stagedDirectory = transaction.targetGeneration === undefined
+        ? directory
+        : join(sessionDirectory, 'v2', transaction.targetGeneration);
+    const originals = new Set(transaction.originalSegments);
+    for (const name of transaction.originalSegments) {
+        const canonical = join(directory, name);
+        const backup = `${canonical}.${transaction.id}.${transaction.kind}-backup`;
+        if (!(await exists(backup)))
+            continue;
+        if (committed)
+            await rm(backup, { force: true });
+        else {
+            await rm(canonical, { force: true });
+            await rename(backup, canonical);
+        }
+    }
+    if (!committed)
+        for (const entry of transaction.stagedSegments)
+            if (stagedDirectory !== directory || !originals.has(entry.path))
+                await rm(join(stagedDirectory, entry.path), { force: true });
+    for (const entry of transaction.stagedSegments)
+        await rm(join(stagedDirectory, entry.temporary), { force: true });
+    if (!committed && transaction.targetGeneration !== undefined)
+        await rm(stagedDirectory, { recursive: true, force: true });
+    const sidecar = join(directory, 'context-world-state.json');
+    const backup = join(directory, transaction.sidecarBackup);
+    if (await exists(backup)) {
+        if (committed)
+            await rm(backup, { force: true });
+        else {
+            await rm(sidecar, { force: true });
+            await rename(backup, sidecar);
+        }
+    }
+    for (const folder of ['generated_images', 'tool_results', 'resources']) {
+        const path = join(folder === 'generated_images' ? sessionDirectory : directory, folder);
+        let names;
+        try {
+            names = await readdir(path);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                continue;
+            throw error;
+        }
+        const suffix = `.${transaction.id}.rollback-trash`;
+        for (const name of names) {
+            if (!name.startsWith('.') || !name.endsWith(suffix))
+                continue;
+            const trash = join(path, name);
+            if (committed)
+                await rm(trash, { force: true });
+            else
+                await rename(trash, join(path, name.slice(1, -suffix.length)));
+        }
+    }
+    for (const path of transaction.retiredPaths ?? []) {
+        const source = join(sessionDirectory, path);
+        const trash = retiredSessionTrashPath(sessionDirectory, path, transaction.id);
+        if (!(await exists(trash)))
+            continue;
+        if (committed)
+            await rm(trash, { recursive: true, force: true });
+        else
+            await rename(trash, source);
+    }
+    await rm(journal);
+    await removeUnjournaledTransactionFiles(directory);
+}
+async function removeUnjournaledTransactionFiles(directory) {
+    for (const name of await readdir(directory))
+        if (isUnjournaledTransactionFile(name))
+            await rm(join(directory, name), { force: true });
+}
+async function exists(path) {
+    try {
+        await lstat(path);
+        return true;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+}

package/dist/session/store/jsonl/tree-maintenance.d.ts

@@ -0,0 +1,12 @@
+import type { SessionStoreMaintenance } from '../contracts.js';
+type Release = () => Promise<void>;
+/** Owns tree discovery, acquisition order and cleanup; individual writers remain store-owned. */
+export declare function acquireTreeMaintenance(input: {
+    sessionId: string;
+    kind: 'clear' | 'delete';
+    tree: () => Promise<readonly string[]>;
+    acquire: (id: string, holding: SessionStoreMaintenance, registerGate: (release: Release) => void) => Promise<Release>;
+    admitted: (holding: SessionStoreMaintenance) => void;
+    released: (holding: SessionStoreMaintenance) => void;
+}): Promise<SessionStoreMaintenance>;
+export {};

package/dist/session/store/jsonl/tree-maintenance.js

@@ -0,0 +1,59 @@
+/** Owns tree discovery, acquisition order and cleanup; individual writers remain store-owned. */
+export async function acquireTreeMaintenance(input) {
+    const acquired = new Map();
+    const gates = new Map();
+    let sessionIds = [];
+    let released = false;
+    const holding = Object.freeze({
+        get sessionIds() {
+            return sessionIds;
+        },
+        release: async () => {
+            if (released)
+                return;
+            released = true;
+            input.released(holding);
+            let failure;
+            for (const release of [...acquired.values()].reverse()) {
+                try {
+                    await release();
+                }
+                catch (error) {
+                    failure ??= { error };
+                }
+            }
+            for (const release of [...gates.values()].reverse()) {
+                try {
+                    await release();
+                }
+                catch (error) {
+                    failure ??= { error };
+                }
+            }
+            if (failure)
+                throw failure.error;
+        }
+    });
+    try {
+        for (;;) {
+            const tree = input.kind === 'delete' ? await input.tree() : [input.sessionId];
+            for (const id of tree.toReversed()) {
+                if (acquired.has(id))
+                    continue;
+                const release = await input.acquire(id, holding, (gate) => gates.set(id, gate));
+                acquired.set(id, release);
+            }
+            const current = input.kind === 'clear' ? tree : await input.tree();
+            if (current.every((id) => acquired.has(id))) {
+                sessionIds = Object.freeze(current);
+                break;
+            }
+        }
+        input.admitted(holding);
+        return holding;
+    }
+    catch (error) {
+        await holding.release().catch(() => undefined);
+        throw error;
+    }
+}

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

@@ -0,0 +1,69 @@
+import type { SessionRecord } from '../record-contract.js';
+export type { SessionRecord, CompactUserInput, CompactHistoryMessage } from '../record-contract.js';
+import type { TodoSnapshot } from '../todo.js';
+import type { SessionSource } from '../types.js';
+import type { ModelImage } from '../../model/image.js';
+export interface SessionExecutionState {
+    automaticTitlePending: boolean;
+    todo: TodoSnapshot;
+    contextRecords: SessionRecord[];
+}
+export interface SessionInputImage extends ModelImage {
+    readonly name: string;
+}
+export interface SessionInputImageMetadata {
+    readonly resourceInputVersion: 1;
+    readonly name: string;
+    readonly mimeType: string;
+    readonly byteSize: number;
+    readonly sha256: string;
+    readonly resourceId: string;
+    readonly url?: string;
+    readonly urlExpiresAt?: number;
+}
+export interface RestoredSessionInputImage extends ModelImage {
+}
+export interface SessionInputImageData extends SessionInputImageMetadata {
+    readonly dataBase64: string;
+}
+export interface SessionMeta {
+    id: string;
+    title: string;
+    workspace: string;
+    createdAt: string;
+    lastActivityAt: string;
+    source?: SessionSource;
+    nextSequence: number;
+    automaticTitlePending?: boolean;
+    storageTransactionId?: string;
+    storage?: {
+        encoding: 1;
+    } | {
+        encoding: 2;
+        generation: string;
+    };
+    resume?: {
+        version: 1;
+        userTurns?: number;
+        compactSequence?: number;
+        todoSequence?: number;
+        todoRevision: number;
+        executionModelIndexed?: true;
+        firstUserMessageIndexed?: true;
+        firstUserMessagePreview?: string;
+        modelId?: string;
+        modelName?: string;
+        reasoningEffort?: string;
+    };
+    segments?: Array<{
+        number: number;
+        firstSequence: number;
+        lastSequence: number;
+        bytes: number;
+    }>;
+}
+export interface SessionIndex {
+    version: 1 | 2;
+    revision: number;
+    sessions: SessionMeta[];
+}

package/dist/session/store/types.js

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

package/dist/session/summary.d.ts

@@ -0,0 +1,18 @@
+import type { SessionSource } from './types.js';
+export interface AgentSessionSummary {
+    id: string;
+    title: string;
+    /** First non-empty user input, whitespace-normalized and bounded to 160 characters. */
+    firstUserMessagePreview?: string;
+    workspace: string;
+    createdAt: string;
+    lastActivityAt: string;
+    source: SessionSource;
+    modelId?: string;
+    modelName?: string;
+    reasoningEffort?: string;
+}
+export interface AgentSessionPage {
+    sessions: AgentSessionSummary[];
+    nextCursor?: string;
+}

package/dist/session/summary.js

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

package/dist/session/todo.d.ts

@@ -0,0 +1,11 @@
+export interface TodoItem {
+    id: string;
+    step: string;
+    status: 'pending' | 'in_progress' | 'completed';
+}
+export interface TodoSnapshot {
+    revision: number;
+    items: TodoItem[];
+}
+export declare function todoItemsFromSnapshot(snapshot: unknown): TodoItem[] | undefined;
+export declare function normalizeTodoItems(items: readonly TodoItem[]): TodoItem[];

package/dist/session/todo.js

@@ -0,0 +1,30 @@
+import { AgentError } from '../error.js';
+export function todoItemsFromSnapshot(snapshot) {
+    if (snapshot === null || typeof snapshot !== 'object' || Array.isArray(snapshot))
+        return undefined;
+    const items = snapshot.items;
+    if (!Array.isArray(items))
+        return undefined;
+    try {
+        return normalizeTodoItems(items);
+    }
+    catch (error) {
+        if (error instanceof AgentError && error.code === 'MAR_AGENT_TOOL_INPUT_INVALID')
+            return undefined;
+        throw error;
+    }
+}
+export function normalizeTodoItems(items) {
+    if (items.filter((item) => item?.status === 'in_progress').length > 1 ||
+        new Set(items.map((item) => item?.id)).size !== items.length ||
+        items.some((item) => item === null ||
+            typeof item !== 'object' ||
+            Array.isArray(item) ||
+            typeof item.id !== 'string' ||
+            !item.id ||
+            typeof item.step !== 'string' ||
+            !item.step.trim() ||
+            !['pending', 'in_progress', 'completed'].includes(item.status)))
+        throw new AgentError('MAR_AGENT_TOOL_INPUT_INVALID', 'Todo items are invalid.');
+    return items.map((item) => ({ ...item, step: item.step.trim() }));
+}

package/dist/session/tool-result-resources.d.ts

@@ -0,0 +1,27 @@
+import { type AvailableToolResultResource } from '../tools/result-extensions.js';
+import type { SessionRecord } from './store/types.js';
+export interface ToolResultResourceInput {
+    resourceRef: string;
+    cursor?: string;
+    maxBytes?: number;
+}
+export interface ToolResultResourcePage {
+    type: 'file_changes';
+    version: 1;
+    format: 'unified-diff';
+    resourceRef: string;
+    byteSize: number;
+    sha256: string;
+    content: string;
+    nextCursor?: string;
+}
+export declare function writeToolResultResource(directory: string, text: string): Promise<AvailableToolResultResource>;
+export declare function recordToolResources(record: Pick<SessionRecord, 'type' | 'payload'>): AvailableToolResultResource[];
+/** A locator is only a hint: reads must verify its exact committed record identity. */
+export declare function bindToolResultResources(directory: string, record: SessionRecord, readRecord?: (sequence: number) => Promise<SessionRecord | undefined>, degrade?: boolean): Promise<void>;
+export declare function toolResultResourceFiles(records: readonly SessionRecord[]): Set<string>;
+export declare function copyToolResultResources(source: string, target: string, records: readonly SessionRecord[]): Promise<void>;
+export declare function completeToolResultResources(directory: string, record: SessionRecord): Promise<void>;
+export declare function cleanupUnreferencedToolResources(directory: string, readRecords: () => Promise<readonly SessionRecord[]>): Promise<void>;
+/** Caller must hold a stable history and resource generation for the entire read. */
+export declare function readToolResultResource(directory: string, sessionId: string, input: ToolResultResourceInput, readRecord: (sequence: number) => Promise<SessionRecord | undefined>): Promise<ToolResultResourcePage>;