@myagentroam/agent 0.11.33 → 0.11.34

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

@@ -0,0 +1,138 @@
+import { AgentError } from '../../../error.js';
+import { inputImageReference } from './images.js';
+/** Decode one complete JSONL record using the encoding selected by the Session index. */
+export function decodeJsonlRecord(line, encoding) {
+    assertEncoding(encoding);
+    let value;
+    try {
+        value = JSON.parse(line);
+    }
+    catch (cause) {
+        throw new AgentError('MAR_AGENT_SESSION_CORRUPT', 'Session record is corrupt.', { cause });
+    }
+    return decodeJsonlValue(value, encoding);
+}
+/** Decode an already-parsed line without repeating JSON parsing. */
+export function decodeJsonlValue(value, encoding) {
+    assertEncoding(encoding);
+    return decodeRecord(value, encoding);
+}
+/** Encode one v2 record without a line delimiter; the segment writer owns framing. */
+export function encodeJsonlRecord(record, encoding) {
+    assertEncoding(encoding);
+    if (encoding !== 2)
+        throw unsupportedEncoding();
+    let line;
+    try {
+        line = JSON.stringify(normalizeJsonlRecord(record));
+    }
+    catch (cause) {
+        throw new AgentError('MAR_AGENT_SESSION_CORRUPT', 'Session record is not serializable.', {
+            cause
+        });
+    }
+    if (line === undefined)
+        throw corruptRecord();
+    return line;
+}
+/** Normalize known physical image references without examining unrelated payload fields. */
+export function normalizeJsonlRecord(record) {
+    return decodeRecord(record, 2);
+}
+function decodeRecord(value, encoding) {
+    if (!isObject(value))
+        throw corruptRecord();
+    if (isObject(value.payload)) {
+        const payload = value.payload;
+        if (value.type === 'context.gc.completed') {
+            rejectFuture(payload.version, 1);
+            if (isObject(payload.inlineMedia) && isObject(payload.inlineMedia.state))
+                rejectFuture(payload.inlineMedia.state.version, 1);
+        }
+        else if (value.type === 'resource.window') {
+            rejectFuture(payload.version, 1);
+        }
+        else if (value.type === 'compact.completed' && isObject(payload.inlineMediaState)) {
+            rejectFuture(payload.inlineMediaState.version, 1);
+        }
+    }
+    const version = value.schemaVersion;
+    if (typeof version === 'number' && Number.isSafeInteger(version) && version > 1)
+        throw unsupportedEncoding();
+    if ((encoding === 1 && version !== 1) || (encoding === 2 && 'schemaVersion' in value))
+        throw corruptRecord();
+    if (typeof value.recordId !== 'string' ||
+        value.recordId.length === 0 ||
+        !Number.isSafeInteger(value.sequence) ||
+        value.sequence < 1 ||
+        typeof value.timestamp !== 'string' ||
+        typeof value.sessionId !== 'string' ||
+        value.sessionId.length === 0 ||
+        typeof value.type !== 'string' ||
+        value.type.length === 0 ||
+        !Object.hasOwn(value, 'payload') ||
+        (value.executionId !== undefined && typeof value.executionId !== 'string') ||
+        (value.turnId !== undefined && typeof value.turnId !== 'string'))
+        throw corruptRecord();
+    const { schemaVersion: _version, ...record } = value;
+    record.payload = decodePayload(value.type, value.payload, encoding);
+    return record;
+}
+function rejectFuture(version, current) {
+    if (typeof version === 'number' && Number.isSafeInteger(version) && version > current)
+        throw unsupportedEncoding();
+}
+function decodePayload(type, payload, encoding) {
+    if (!isObject(payload))
+        return payload;
+    if (type === 'turn.user' || type === 'extension.input' || type === 'model.context')
+        return decodeImageField(payload, encoding);
+    if (type !== 'compact.completed')
+        return payload;
+    return {
+        ...payload,
+        ...(Array.isArray(payload.pendingInputs)
+            ? { pendingInputs: payload.pendingInputs.map((record) => decodeRecord(record, encoding)) }
+            : {}),
+        ...(Array.isArray(payload.retainedModelContext)
+            ? {
+                retainedModelContext: payload.retainedModelContext.map((message) => isObject(message) ? decodeImageField(message, encoding) : message)
+            }
+            : {})
+    };
+}
+function decodeImageField(payload, _encoding) {
+    if (!Array.isArray(payload.images))
+        return payload;
+    return {
+        ...payload,
+        images: payload.images.map((image) => {
+            if (isObject(image) &&
+                typeof image.resourceInputVersion === 'number' &&
+                Number.isSafeInteger(image.resourceInputVersion) &&
+                image.resourceInputVersion > 1)
+                throw unsupportedEncoding();
+            // Older unsupported image formats and already-logical image references remain untouched.
+            if (!isObject(image) || image.resourceInputVersion !== 1 || !Object.hasOwn(image, 'fileName'))
+                return image;
+            const reference = inputImageReference(image);
+            if (!reference?.resourceId)
+                throw corruptRecord();
+            const { fileName: _fileName, ...logical } = image;
+            return logical;
+        })
+    };
+}
+function assertEncoding(encoding) {
+    if (encoding !== 1 && encoding !== 2)
+        throw unsupportedEncoding();
+}
+function unsupportedEncoding() {
+    return new AgentError('MAR_AGENT_SESSION_VERSION_UNSUPPORTED', 'Session encoding is unsupported.');
+}
+function corruptRecord() {
+    return new AgentError('MAR_AGENT_SESSION_CORRUPT', 'Session record is corrupt.');
+}
+function isObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}

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

@@ -0,0 +1,12 @@
+import type { SessionMeta } from '../types.js';
+interface GenerationPreparation {
+    readonly source: string;
+    readonly destination: string;
+    readonly sessionId: string;
+    readonly nextSequence: number;
+}
+/** Prepare a candidate only; the caller owns locking and the index commit. */
+export declare function prepareJsonlV2Generation(input: GenerationPreparation): Promise<{
+    segments: NonNullable<SessionMeta['segments']>;
+}>;
+export {};

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

@@ -0,0 +1,105 @@
+import { createHash } from 'node:crypto';
+import { copyFile, lstat, mkdir, open, readFile, readdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { AgentError } from '../../../error.js';
+import { decodeJsonlRecord, encodeJsonlRecord } from './jsonl-codec.js';
+import { syncAndClose, syncJsonlDirectory } from './fs-durability.js';
+/** Prepare a candidate only; the caller owns locking and the index commit. */
+export async function prepareJsonlV2Generation(input) {
+    await mkdir(input.destination, { mode: 0o700 });
+    const names = (await readdir(input.source))
+        .filter((name) => /^events-\d{6}\.jsonl$/u.test(name))
+        .sort();
+    if (!names.length)
+        throw corruptHistory();
+    const originalHash = createHash('sha256');
+    const candidateHash = createHash('sha256');
+    const segments = [];
+    let lastSequence = 0;
+    let originalCount = 0;
+    let candidateCount = 0;
+    for (const name of names) {
+        const source = await readFile(join(input.source, name), 'utf8');
+        if (!source.endsWith('\n'))
+            throw corruptHistory();
+        const output = [];
+        let firstSequence;
+        for (const line of source.split('\n')) {
+            if (!line)
+                continue;
+            const record = decodeJsonlRecord(line, 1);
+            if (record.sessionId !== input.sessionId || record.sequence <= lastSequence)
+                throw corruptHistory();
+            firstSequence ??= record.sequence;
+            lastSequence = record.sequence;
+            originalHash.update(JSON.stringify(record)).update('\n');
+            originalCount++;
+            const encoded = encodeJsonlRecord(record, 2);
+            const reread = decodeJsonlRecord(encoded, 2);
+            candidateHash.update(JSON.stringify(reread)).update('\n');
+            candidateCount++;
+            output.push(`${encoded}\n`);
+        }
+        if (firstSequence === undefined)
+            throw corruptHistory();
+        const content = output.join('');
+        await writeFile(join(input.destination, name), content, {
+            flag: 'wx',
+            mode: 0o600,
+            flush: true
+        });
+        segments.push({
+            number: Number(name.slice(7, 13)),
+            firstSequence,
+            lastSequence,
+            bytes: Buffer.byteLength(content)
+        });
+    }
+    if (lastSequence + 1 !== input.nextSequence ||
+        originalCount !== candidateCount ||
+        originalHash.digest('hex') !== candidateHash.digest('hex'))
+        throw corruptHistory();
+    await copyOptionalFile(join(input.source, 'context-world-state.json'), join(input.destination, 'context-world-state.json'));
+    await copyPrivateDirectory(input.source, input.destination, 'resources', /^[a-f0-9]{64}\.(?:bin|json)$/u);
+    await copyPrivateDirectory(input.source, input.destination, 'tool_results', /^[0-9a-f-]{36}\.(?:diff|json)$/iu);
+    await syncJsonlDirectory(input.destination);
+    return { segments };
+}
+async function copyPrivateDirectory(source, target, name, accepted) {
+    let entries;
+    try {
+        entries = await readdir(join(source, name));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return;
+        throw error;
+    }
+    const files = entries.filter((entry) => accepted.test(entry));
+    if (!files.length)
+        return;
+    const directory = join(target, name);
+    await mkdir(directory, { mode: 0o700 });
+    for (const file of files)
+        await copyOptionalFile(join(source, name, file), join(directory, file));
+    await syncJsonlDirectory(directory);
+}
+async function copyOptionalFile(source, target) {
+    let sourceInfo;
+    try {
+        sourceInfo = await lstat(source);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return;
+        throw error;
+    }
+    if (!sourceInfo.isFile())
+        return;
+    await copyFile(source, target);
+    const handle = await open(target, 'r');
+    await syncAndClose(handle);
+}
+function corruptHistory() {
+    return new AgentError('MAR_AGENT_SESSION_CORRUPT', 'Session history is corrupt.');
+}

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

@@ -0,0 +1,171 @@
+import { type AgentSessionRollbackInput } from '../../rollback.js';
+import type { SessionStore, SessionStoreMaintenance, SessionRecordInput, SessionStoreCompactInput } from '../contracts.js';
+import { type ExtensionCheckpoint, type ExtensionJsonValue } from '../../extension-checkpoint.js';
+import { type CodeModeStateEntry } from '../../code-state.js';
+import { type ContextGcCheckpointDraft } from '../../context-gc-checkpoint.js';
+import { type ToolResultResourceInput } from '../../tool-result-resources.js';
+import type { SessionListInput, SessionSource, SessionTitleUpdateInput } from '../../types.js';
+import type { RestoredSessionInputImage, SessionExecutionState, SessionInputImage, SessionInputImageData, SessionInputImageMetadata, SessionMeta, SessionRecord } from '../types.js';
+/** SDK-owned JSONL history with per-HOME in-process sharing and cross-process file locks. */
+export declare class JsonlSessionStore implements SessionStore {
+    #private;
+    private constructor();
+    static open(home: string): Promise<JsonlSessionStore>;
+    createSession(input: {
+        title?: string;
+        workspace: string;
+        source?: SessionSource;
+    }): Promise<SessionMeta>;
+    readContextualWorldState(sessionId: string): Promise<unknown | undefined>;
+    writeContextualWorldState(sessionId: string, state: unknown): Promise<void>;
+    /** Mark each image pending before publication; turn.user or lease recovery resolves ownership. */
+    persistInputImages(sessionId: string, images: readonly SessionInputImage[]): Promise<SessionInputImageMetadata[]>;
+    persistResource(sessionId: string, image: import('../../../model/image.js').ModelImage): Promise<import("./resources.js").SessionResource>;
+    setResourceUrl(sessionId: string, resourceId: string, published: {
+        url: string;
+        urlExpiresAt: number;
+    }): Promise<import("./resources.js").SessionResource>;
+    readResource(sessionId: string, resourceId: string): Promise<{
+        mimeType: string;
+        dataBase64: string;
+    } | undefined>;
+    writeToolResultResource(sessionId: string, text: string): Promise<{
+        status: "available";
+        resourceRef: string;
+        format: "unified-diff";
+        byteSize: number;
+        sha256: string;
+    }>;
+    readToolResultResource(sessionId: string, input: ToolResultResourceInput): Promise<import("../../tool-result-resources.js").ToolResultResourcePage>;
+    readInputImages(sessionId: string, value: unknown): Promise<RestoredSessionInputImage[]>;
+    readInputImage(sessionId: string, input: {
+        readonly sequence: number;
+        readonly imageIndex: number;
+    }): Promise<SessionInputImageData | undefined>;
+    forkSession(sourceSessionId: string, input: {
+        readonly boundaryTurnId: string | null;
+        readonly title: string;
+    }): Promise<{
+        id: string;
+        title: string;
+        workspace: string;
+        createdAt: string;
+        lastActivityAt: string;
+        source: SessionSource | undefined;
+    }>;
+    /** Replace history under a journal; the indexed transaction ID decides the commit side. */
+    rollbackSession(sessionId: string, input: AgentSessionRollbackInput): Promise<{
+        id: string;
+        title: string;
+        workspace: string;
+        createdAt: string;
+        lastActivityAt: string;
+        source: SessionSource;
+    }>;
+    updateTitle(sessionId: string, title: string, input?: SessionTitleUpdateInput, owner?: object): Promise<boolean>;
+    /** Reset history with the same recovery journal while preserving the Session identity. */
+    clearSession(sessionId: string, maintenance?: SessionStoreMaintenance): Promise<{
+        id: string;
+        title: string;
+        workspace: string;
+        createdAt: string;
+        lastActivityAt: string;
+        source: SessionSource;
+    }>;
+    getSession(sessionId: string): Promise<{
+        id: string;
+        title: string;
+        workspace: string;
+        createdAt: string;
+        lastActivityAt: string;
+        source: SessionSource;
+        automaticTitlePending: boolean;
+    }>;
+    /** Serialize physical writes and honor cancellation before entering the writer. */
+    append(sessionId: string, input: SessionRecordInput, options?: {
+        readonly signal?: AbortSignal;
+    }): Promise<SessionRecord>;
+    read(sessionId: string): Promise<SessionRecord[]>;
+    readCodeModeState(sessionId: string): Promise<CodeModeStateEntry[]>;
+    readExtensionCheckpoint(sessionId: string, extensionId: string, key: string): Promise<ExtensionCheckpoint>;
+    writeExtensionCheckpoint(sessionId: string, extensionId: string, key: string, value: ExtensionJsonValue | undefined, expectedRevision: number | undefined, input: {
+        owner: object;
+        signal: AbortSignal;
+        executionId?: string;
+        turnId?: string;
+    }): Promise<ExtensionCheckpoint>;
+    commitCodeModeState(sessionId: string, mutations: unknown, input: {
+        readonly executionId: string;
+        readonly turnId: string;
+        readonly expectedState?: readonly CodeModeStateEntry[];
+    }): Promise<CodeModeStateEntry[]>;
+    readExecutionState(sessionId: string): Promise<SessionExecutionState>;
+    /** Compare the planned sequence inside the existing record writer queue. */
+    commitContextGc(sessionId: string, draft: ContextGcCheckpointDraft, planningRecords?: readonly SessionRecord[]): Promise<SessionRecord>;
+    readPage(sessionId: string, input?: {
+        limit?: number;
+        beforeSequence?: number;
+    }): Promise<{
+        records: SessionRecord[];
+        previousBeforeSequence?: number;
+    }>;
+    compact(sessionId: string, input: SessionStoreCompactInput, options?: {
+        readonly signal?: AbortSignal;
+    }): Promise<SessionRecord>;
+    /** A warm cell retains physical writer ownership between Executions of the same Agent. */
+    acquireSessionLease(sessionId: string, owner?: object): Promise<() => Promise<void>>;
+    hasRetainedSessionLease(sessionId: string, owner: object): boolean;
+    acquireSessionMaintenance(sessionId: string, kind: 'clear' | 'delete', owner?: object): Promise<SessionStoreMaintenance>;
+    /** Native writes join their Agent's sole writer, without admitting another Execution. */
+    acquireSessionWriteLease(sessionId: string, owner: object): Promise<() => Promise<void>>;
+    retainSessionLease(sessionId: string, owner: object): Promise<() => Promise<void>>;
+    list(input?: SessionListInput): Promise<{
+        nextCursor?: string;
+        sessions: {
+            reasoningEffort?: string;
+            modelName?: string;
+            modelId?: string;
+            workspace: string;
+            createdAt: string;
+            lastActivityAt: string;
+            source: SessionSource;
+            firstUserMessagePreview?: string;
+            id: string;
+            title: string;
+        }[];
+    }>;
+    listSubagentChildren(parentSessionId: string): Promise<{
+        reasoningEffort?: string;
+        modelName?: string;
+        modelId?: string;
+        id: string;
+        title: string;
+        workspace: string;
+        createdAt: string;
+        lastActivityAt: string;
+        source: {
+            readonly type: "subagent";
+            readonly parentSessionId: string;
+            readonly rootSessionId: string;
+            readonly parentExecutionId?: string;
+            readonly parentOperationId?: string;
+            readonly ownerInstanceId?: string;
+            readonly extensionId?: string;
+            readonly role: "general-purpose" | "explore";
+            readonly description: string;
+        };
+    }[]>;
+    executionConfiguration(sessionId: string): Promise<{
+        readonly modelId: string;
+        readonly modelName?: string;
+        readonly reasoningEffort?: string;
+    } | undefined>;
+    sessionTree(sessionId: string): Promise<readonly string[]>;
+    /** Counts native input records, not the post-Compact model context. */
+    userTurnCount(sessionId: string): Promise<number>;
+    firstUserMessagePreview(sessionId: string): Promise<string | undefined>;
+    delete(sessionId: string, maintenance?: SessionStoreMaintenance): Promise<{
+        readonly deleted: boolean;
+    }>;
+    close(): Promise<void>;
+}