@myagentroam/agent 0.9.157 → 0.9.159

package/dist/agent-core/model/contracts.d.ts

@@ -36,6 +36,15 @@ export interface ModelAttemptDiagnostic {
     connectionId?: string;
     connectionReused?: boolean;
     proxyType?: 'DIRECT' | 'SOCKS5';
+    /** Actual serialized WebSocket request size, including inline image Base64. */
+    requestBytes?: number;
+    imageCount?: number;
+    /** Decoded byte count of inline input images; external URLs do not add bytes. */
+    imageBytes?: number;
+    requestFrameCount?: number;
+    sentFrameCount?: number;
+    webSocketPhase?: 'CONNECT' | 'SEND' | 'RECEIVE';
+    webSocketCloseCode?: number;
     durationMs?: number;
     errorCode?: string;
     errorMessage?: string;

package/dist/agent-core/model/openai-responses.d.ts

@@ -25,6 +25,7 @@ interface PreparedResponsesRequest {
     readonly body: ResponsesRequestBody;
     readonly continuation: boolean;
 }
+type ResponsesWebSocketDiagnostic = Pick<ModelAttemptDiagnostic, 'requestBytes' | 'imageCount' | 'imageBytes' | 'requestFrameCount' | 'sentFrameCount' | 'webSocketPhase' | 'webSocketCloseCode'>;
 export declare class OpenAiResponsesAdapter implements ModelAdapter {
     #private;
     constructor(configuration: MarAgentModelConfiguration);
@@ -51,7 +52,8 @@ declare class OpenAiResponsesTurnSession implements ModelTurnSession {
     fullRequestBody(): ResponsesRequestBody;
     currentTurnState(): string | undefined;
     beginAttempt(): void;
-    connectionDiagnostic(): Pick<ModelAttemptDiagnostic, 'connectionId' | 'connectionReused' | 'proxyType'>;
+    captureWebSocketDiagnostic(diagnostic: ResponsesWebSocketDiagnostic): void;
+    connectionDiagnostic(): Pick<ModelAttemptDiagnostic, 'connectionId' | 'connectionReused' | 'proxyType'> & ResponsesWebSocketDiagnostic;
     captureTurnState(value: unknown): void;
     withTurnStateMetadata(body: ResponsesRequestBody): ResponsesRequestBody;
     invalidateWebSocket(): void;

package/dist/agent-core/model/openai-responses.js

@@ -8,6 +8,7 @@ import { isRetryableUpstreamOverloadCode, number, parseSse, record, text, observ
 import { connectSocks5Target, fetchModelResponse, isRetryableModelHttpStatus, isRetryableModelTransportError, modelRetryMaxAttempts, isRetryableModelRequestError, modelRetryDelay, waitForModelRetry } from './http.js';
 import { acquireModelCredential, appendModelCredentialHeaders } from './runtime-credential.js';
 const WEBSOCKET_IDLE_TIMEOUT_MS = 300_000;
+const WEBSOCKET_SEND_FRAME_BYTES = 1024 * 1024;
 export const OPENAI_RESPONSES_EARLY_EOF_REASON = 'OPENAI_RESPONSES_EARLY_EOF';
 export const OPENAI_RESPONSES_WEBSOCKET_CONNECTION_LIMIT_REASON = 'OPENAI_RESPONSES_WEBSOCKET_CONNECTION_LIMIT';
 const X_CODEX_TURN_STATE = 'x-codex-turn-state';
@@ -624,6 +625,7 @@ class OpenAiResponsesTurnSession {
     #fullBody;
     #completedResponseId;
     #connectionDiagnostic;
+    #webSocketDiagnostic;
     constructor(adapter, state, cacheLease) {
         this.adapter = adapter;
         this.state = state;
@@ -735,9 +737,13 @@ class OpenAiResponsesTurnSession {
     }
     beginAttempt() {
         this.#connectionDiagnostic = undefined;
+        this.#webSocketDiagnostic = undefined;
+    }
+    captureWebSocketDiagnostic(diagnostic) {
+        this.#webSocketDiagnostic = diagnostic;
     }
     connectionDiagnostic() {
-        return this.#connectionDiagnostic ?? {};
+        return { ...this.#connectionDiagnostic, ...this.#webSocketDiagnostic };
     }
     captureTurnState(value) {
         if (this.#turnState !== undefined || typeof value !== 'string')
@@ -1010,6 +1016,10 @@ async function* parseOpenAiResponsesSse(response, signal, continuation) {
     }
 }
 async function* webSocketResponseEvents(input) {
+    const body = input.turn.withTurnStateMetadata(input.body);
+    const payload = Buffer.from(JSON.stringify({ type: 'response.create', ...body }), 'utf8');
+    const diagnostic = webSocketRequestDiagnostic(body, payload.length);
+    input.turn.captureWebSocketDiagnostic(diagnostic);
     const socket = await input.turn.webSocketForRequest({
         configuration: input.configuration,
         promptCacheKey: input.promptCacheKey,
@@ -1018,32 +1028,75 @@ async function* webSocketResponseEvents(input) {
         continuation: input.continuation,
         credentialAcquired: input.credentialAcquired
     });
-    const body = input.turn.withTurnStateMetadata(input.body);
-    await sendWebSocketMessage(socket, JSON.stringify({ type: 'response.create', ...body }), input.signal);
-    let terminal = false;
-    for await (const item of webSocketMessages(socket, input.signal)) {
-        const event = record(item);
-        const type = text(event.type);
-        input.turn.captureTurnState(turnStateFromEvent(event));
-        if (type !== 'response.metadata' && type !== 'codex.response.metadata')
-            yield item;
-        if (type === 'response.completed' ||
-            type === 'response.incomplete' ||
-            type === 'response.failed' ||
-            type === 'error') {
-            terminal = true;
-            return;
+    const messages = webSocketMessages(socket, input.signal, (code) => {
+        diagnostic.webSocketCloseCode = code;
+    });
+    try {
+        diagnostic.webSocketPhase = 'SEND';
+        await sendWebSocketMessage(socket, payload, input.signal, () => {
+            diagnostic.sentFrameCount = (diagnostic.sentFrameCount ?? 0) + 1;
+        });
+        diagnostic.webSocketPhase = 'RECEIVE';
+        let terminal = false;
+        for await (const item of messages) {
+            const event = record(item);
+            const type = text(event.type);
+            input.turn.captureTurnState(turnStateFromEvent(event));
+            if (type !== 'response.metadata' && type !== 'codex.response.metadata')
+                yield item;
+            if (type === 'response.completed' ||
+                type === 'response.incomplete' ||
+                type === 'response.failed' ||
+                type === 'error') {
+                terminal = true;
+                return;
+            }
         }
+        if (!terminal && !input.signal.aborted)
+            throw new MarAgentError('MAR_AGENT_MODEL_PROTOCOL_ERROR', 'OpenAI Responses WebSocket closed before a terminal event.', {
+                details: {
+                    reason: OPENAI_RESPONSES_EARLY_EOF_REASON,
+                    transport: 'WEBSOCKET',
+                    continuation: input.continuation
+                },
+                retryable: true
+            });
+    }
+    finally {
+        messages.dispose();
     }
-    if (!terminal && !input.signal.aborted)
-        throw new MarAgentError('MAR_AGENT_MODEL_PROTOCOL_ERROR', 'OpenAI Responses WebSocket closed before a terminal event.', {
-            details: {
-                reason: OPENAI_RESPONSES_EARLY_EOF_REASON,
-                transport: 'WEBSOCKET',
-                continuation: input.continuation
-            },
-            retryable: true
-        });
+}
+function webSocketRequestDiagnostic(body, requestBytes) {
+    let imageCount = 0;
+    let imageBytes = 0;
+    for (const item of body.input) {
+        const entry = record(item);
+        const parts = Array.isArray(entry.content)
+            ? entry.content
+            : Array.isArray(entry.output)
+                ? entry.output
+                : [];
+        for (const value of parts) {
+            const part = record(value);
+            if (part.type !== 'input_image')
+                continue;
+            imageCount++;
+            const url = text(part.image_url);
+            if (url === undefined)
+                continue;
+            const marker = url.indexOf(';base64,');
+            if (url.startsWith('data:') && marker >= 0)
+                imageBytes += Buffer.byteLength(url.slice(marker + 8), 'base64');
+        }
+    }
+    return {
+        requestBytes,
+        imageCount,
+        imageBytes,
+        requestFrameCount: Math.ceil(requestBytes / WEBSOCKET_SEND_FRAME_BYTES),
+        sentFrameCount: 0,
+        webSocketPhase: 'CONNECT'
+    };
 }
 async function waitForWebSocketOpen(socket, signal) {
     if (signal.aborted) {
@@ -1101,29 +1154,55 @@ async function waitForWebSocketOpen(socket, signal) {
         socket.once('unexpected-response', unexpectedResponse);
     });
 }
-async function sendWebSocketMessage(socket, value, signal) {
-    if (signal.aborted)
-        throw signal.reason;
-    await new Promise((resolve, reject) => {
-        const cleanup = () => signal.removeEventListener('abort', abort);
-        const abort = () => {
-            socket.terminate();
-            cleanup();
-            reject(signal.reason);
-        };
-        signal.addEventListener('abort', abort, { once: true });
-        socket.send(value, (error) => {
-            cleanup();
-            if (error)
-                reject(webSocketReceiveError(error));
-            else if (signal.aborted)
+async function sendWebSocketMessage(socket, payload, signal, frameSent) {
+    for (let offset = 0; offset < payload.length; offset += WEBSOCKET_SEND_FRAME_BYTES) {
+        if (signal.aborted)
+            throw signal.reason;
+        const end = Math.min(payload.length, offset + WEBSOCKET_SEND_FRAME_BYTES);
+        await new Promise((resolve, reject) => {
+            let settled = false;
+            const cleanup = () => {
+                settled = true;
+                signal.removeEventListener('abort', abort);
+                socket.off('error', error);
+                socket.off('close', close);
+            };
+            const abort = () => {
+                cleanup();
+                socket.terminate();
                 reject(signal.reason);
-            else
-                resolve();
+            };
+            const error = (cause) => {
+                cleanup();
+                reject(webSocketReceiveError(cause));
+            };
+            const close = () => error(new Error('WebSocket closed while sending the request.'));
+            signal.addEventListener('abort', abort, { once: true });
+            socket.once('error', error);
+            socket.once('close', close);
+            try {
+                socket.send(payload.subarray(offset, end), { binary: false, fin: end === payload.length }, (cause) => {
+                    if (settled)
+                        return;
+                    cleanup();
+                    if (cause)
+                        reject(webSocketReceiveError(cause));
+                    else if (signal.aborted)
+                        reject(signal.reason);
+                    else {
+                        frameSent();
+                        resolve();
+                    }
+                });
+            }
+            catch (cause) {
+                cleanup();
+                reject(webSocketReceiveError(cause));
+            }
         });
-    });
+    }
 }
-async function* webSocketMessages(socket, signal) {
+function webSocketMessages(socket, signal, closed) {
     const queue = [];
     let resume;
     const push = (item) => {
@@ -1136,7 +1215,10 @@ async function* webSocketMessages(socket, signal) {
         value,
         observedAt: performance.now()
     });
-    const close = () => push({ type: 'closed' });
+    const close = (code) => {
+        closed(code);
+        push({ type: 'closed' });
+    };
     const error = (cause) => push({
         type: 'error',
         error: webSocketReceiveError(cause)
@@ -1153,49 +1235,57 @@ async function* webSocketMessages(socket, signal) {
     socket.on('close', close);
     socket.on('error', error);
     signal.addEventListener('abort', abort, { once: true });
-    try {
-        let idleDeadline = Date.now() + WEBSOCKET_IDLE_TIMEOUT_MS;
-        while (true) {
-            if (Date.now() >= idleDeadline)
-                throw webSocketIdleError(socket);
-            if (queue.length === 0)
-                await new Promise((resolve, reject) => {
-                    const timer = setTimeout(() => {
-                        resume = undefined;
-                        reject(webSocketIdleError(socket));
-                    }, Math.max(0, idleDeadline - Date.now()));
-                    resume = () => {
-                        clearTimeout(timer);
-                        resolve();
-                    };
-                });
-            const item = queue.shift();
-            if (item === undefined)
-                continue;
-            if (item.type === 'closed')
-                return;
-            if (item.type === 'error')
-                throw item.error;
-            const text = await webSocketMessageText(item.value);
-            if (Buffer.byteLength(text) > 16 * 1024 * 1024)
-                throw new MarAgentError('MAR_AGENT_MODEL_PROTOCOL_ERROR', 'Model response exceeded the size limit.');
-            try {
-                const event = JSON.parse(text);
-                if (!isWebSocketNonProgressEvent(event))
-                    idleDeadline = Date.now() + WEBSOCKET_IDLE_TIMEOUT_MS;
-                yield observeModelStreamEvent(event, item.observedAt);
-            }
-            catch (cause) {
-                throw new MarAgentError('MAR_AGENT_MODEL_PROTOCOL_ERROR', 'Model WebSocket contained invalid JSON.', { cause });
-            }
-        }
-    }
-    finally {
+    const dispose = () => {
         signal.removeEventListener('abort', abort);
         socket.off('message', message);
         socket.off('close', close);
         socket.off('error', error);
-    }
+    };
+    return {
+        dispose,
+        async *[Symbol.asyncIterator]() {
+            try {
+                let idleDeadline = Date.now() + WEBSOCKET_IDLE_TIMEOUT_MS;
+                while (true) {
+                    if (Date.now() >= idleDeadline)
+                        throw webSocketIdleError(socket);
+                    if (queue.length === 0)
+                        await new Promise((resolve, reject) => {
+                            const timer = setTimeout(() => {
+                                resume = undefined;
+                                reject(webSocketIdleError(socket));
+                            }, Math.max(0, idleDeadline - Date.now()));
+                            resume = () => {
+                                clearTimeout(timer);
+                                resolve();
+                            };
+                        });
+                    const item = queue.shift();
+                    if (item === undefined)
+                        continue;
+                    if (item.type === 'closed')
+                        return;
+                    if (item.type === 'error')
+                        throw item.error;
+                    const text = await webSocketMessageText(item.value);
+                    if (Buffer.byteLength(text) > 16 * 1024 * 1024)
+                        throw new MarAgentError('MAR_AGENT_MODEL_PROTOCOL_ERROR', 'Model response exceeded the size limit.');
+                    try {
+                        const event = JSON.parse(text);
+                        if (!isWebSocketNonProgressEvent(event))
+                            idleDeadline = Date.now() + WEBSOCKET_IDLE_TIMEOUT_MS;
+                        yield observeModelStreamEvent(event, item.observedAt);
+                    }
+                    catch (cause) {
+                        throw new MarAgentError('MAR_AGENT_MODEL_PROTOCOL_ERROR', 'Model WebSocket contained invalid JSON.', { cause });
+                    }
+                }
+            }
+            finally {
+                dispose();
+            }
+        }
+    };
 }
 function webSocketIdleError(socket) {
     terminateWebSocket(socket);

package/dist/agent-core/session/catalog.d.ts

@@ -4,6 +4,8 @@ import type { SessionListInput, SessionSource } from './types.js';
 export interface MarAgentSessionSummary {
     id: string;
     title: string;
+    /** First non-empty user input, whitespace-normalized and bounded to 160 characters. */
+    firstUserMessagePreview?: string;
     workspace: string;
     createdAt: string;
     lastActivityAt: string;
@@ -54,6 +56,7 @@ export interface MarAgentSessionImage {
 /** Public session catalog facade. Storage details remain SDK-private. */
 export interface MarAgentSessionCatalog {
     list(input?: SessionListInput): Promise<MarAgentSessionPage>;
+    firstUserMessagePreview(sessionId: string): Promise<string | undefined>;
     executionConfiguration(sessionId: string): Promise<{
         readonly modelId: string;
         readonly modelName?: string;

package/dist/agent-core/session/catalog.js

@@ -7,6 +7,7 @@ export async function openMarAgentSessionCatalog(input) {
     const store = await JsonlSessionStore.open(input.homeDirectory);
     return {
         list: (options) => store.list(options),
+        firstUserMessagePreview: (sessionId) => store.firstUserMessagePreview(sessionId),
         executionConfiguration: (sessionId) => store.executionConfiguration(sessionId),
         history: async (sessionId, options = {}) => {
             const beforeSequence = parseCursor(options.cursor);

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

@@ -64,6 +64,8 @@ interface SessionMeta {
         todoSequence?: number;
         todoRevision: number;
         executionModelIndexed?: true;
+        firstUserMessageIndexed?: true;
+        firstUserMessagePreview?: string;
         modelId?: string;
         modelName?: string;
         reasoningEffort?: string;
@@ -184,12 +186,13 @@ export declare class JsonlSessionStore {
             reasoningEffort?: string;
             modelName?: string;
             modelId?: string;
-            id: string;
-            title: string;
             workspace: string;
             createdAt: string;
             lastActivityAt: string;
             source: SessionSource;
+            firstUserMessagePreview?: string;
+            id: string;
+            title: string;
         }[];
     }>;
     listSubagentChildren(parentSessionId: string): Promise<{
@@ -216,6 +219,7 @@ export declare class JsonlSessionStore {
         readonly reasoningEffort?: string;
     } | undefined>;
     sessionTree(sessionId: string): Promise<readonly string[]>;
+    firstUserMessagePreview(sessionId: string): Promise<string | undefined>;
     delete(sessionId: string): Promise<{
         readonly deleted: boolean;
     }>;

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

@@ -158,6 +158,7 @@ export class JsonlSessionStore {
             closed: false,
             indexDirty: false,
             dirtySessionVersions: new Map(),
+            previewOnlyDirtySessions: new Set(),
             pendingPublishIds: new Set(),
             codeStateWrites: new Map(),
             recordWrites: new Map(),
@@ -176,19 +177,26 @@ export class JsonlSessionStore {
             if (!disk)
                 throw new MarAgentError('MAR_AGENT_SESSION_CORRUPT', 'Session index is missing.');
             const dirty = new Map(this.#shared.dirtySessionVersions);
+            const previewOnly = new Set(this.#shared.previewOnlyDirtySessions);
             const sessions = new Map(disk.sessions.map((session) => [session.id, session]));
             const created = new Set(createdIds);
             for (const session of this.#shared.index.sessions) {
                 const current = sessions.get(session.id);
                 // Disk membership is authoritative: a stale in-memory snapshot cannot revive a deletion.
                 if (created.has(session.id) || (current && dirty.has(session.id)))
-                    sessions.set(session.id, structuredClone(session));
+                    sessions.set(session.id, current && previewOnly.has(session.id)
+                        ? mergeFirstUserMessagePreviewCache(current, session)
+                        : structuredClone(session));
             }
             for (const deletedId of typeof deletedIds === 'string' ? [deletedIds] : (deletedIds ?? []))
                 sessions.delete(deletedId);
             const updated = {
                 version: 1,
-                revision: Math.max(disk.revision, this.#shared.index.revision) + 1,
+                revision: createdIds.length > 0 ||
+                    deletedIds !== undefined ||
+                    [...dirty.keys()].some((id) => !previewOnly.has(id))
+                    ? Math.max(disk.revision, this.#shared.index.revision) + 1
+                    : disk.revision,
                 sessions: [...sessions.values()]
             };
             await persistSessionIndex(path, updated);
@@ -196,8 +204,10 @@ export class JsonlSessionStore {
                 // A different creation still needs its own index transaction to publish its directory.
                 if (this.#shared.pendingPublishIds.has(id) && !created.has(id))
                     continue;
-                if (this.#shared.dirtySessionVersions.get(id) === version)
+                if (this.#shared.dirtySessionVersions.get(id) === version) {
                     this.#shared.dirtySessionVersions.delete(id);
+                    this.#shared.previewOnlyDirtySessions.delete(id);
+                }
             }
             for (const id of created)
                 this.#shared.pendingPublishIds.delete(id);
@@ -234,7 +244,11 @@ export class JsonlSessionStore {
             sessions: disk.sessions
                 .map((session) => {
                 const current = local.get(session.id);
-                return current && this.#shared.dirtySessionVersions.has(session.id) ? current : session;
+                if (!current || !this.#shared.dirtySessionVersions.has(session.id))
+                    return session;
+                return this.#shared.previewOnlyDirtySessions.has(session.id)
+                    ? mergeFirstUserMessagePreviewCache(session, current)
+                    : current;
             })
                 .concat(this.#shared.index.sessions.filter((session) => this.#shared.pendingPublishIds.has(session.id) && !published.has(session.id)))
         };
@@ -272,7 +286,12 @@ export class JsonlSessionStore {
             source: normalizeSessionSource(input.source),
             nextSequence: 1,
             automaticTitlePending: input.title === undefined,
-            resume: { version: 1, todoRevision: 0, executionModelIndexed: true },
+            resume: {
+                version: 1,
+                todoRevision: 0,
+                executionModelIndexed: true,
+                firstUserMessageIndexed: true
+            },
             segments: []
         };
         const publication = await this.#beginUnpublishedSession(id);
@@ -520,7 +539,12 @@ export class JsonlSessionStore {
                 source: { type: 'user' },
                 nextSequence: 1,
                 automaticTitlePending: false,
-                resume: { version: 1, todoRevision: 0, executionModelIndexed: true },
+                resume: {
+                    version: 1,
+                    todoRevision: 0,
+                    executionModelIndexed: true,
+                    firstUserMessageIndexed: true
+                },
                 segments: []
             };
             const publication = await this.#beginUnpublishedSession(target.id);
@@ -852,7 +876,7 @@ export class JsonlSessionStore {
                 meta.lastActivityAt = clearedAt;
                 meta.nextSequence = 2;
                 meta.storageTransactionId = transactionId;
-                meta.resume = { version: 1, todoRevision: 0 };
+                meta.resume = { version: 1, todoRevision: 0, firstUserMessageIndexed: true };
                 meta.segments = staged.segments;
                 this.#shared.segments.set(sessionId, 1);
                 this.#shared.index.revision++;
@@ -1316,6 +1340,9 @@ export class JsonlSessionStore {
         const sessions = ordered.slice(start, start + limit).map((session) => ({
             id: session.id,
             title: session.title,
+            ...(session.resume?.firstUserMessagePreview === undefined
+                ? {}
+                : { firstUserMessagePreview: session.resume.firstUserMessagePreview }),
             workspace: session.workspace,
             createdAt: session.createdAt,
             lastActivityAt: session.lastActivityAt,
@@ -1403,6 +1430,11 @@ export class JsonlSessionStore {
         const resume = meta.resume;
         if (resume?.version !== 1 || !Number.isSafeInteger(resume.todoRevision))
             return;
+        if (resume.firstUserMessageIndexed === true && resume.firstUserMessagePreview === undefined) {
+            const preview = userMessagePreviewFromRecord(record);
+            if (preview !== undefined)
+                resume.firstUserMessagePreview = preview;
+        }
         const executionModel = executionModelFromRecord(record);
         if (executionModel !== undefined) {
             resume.executionModelIndexed = true;
@@ -1488,6 +1520,56 @@ export class JsonlSessionStore {
             contextRecords: state.contextRecords
         };
     }
+    async firstUserMessagePreview(sessionId) {
+        this.#assertOpen();
+        await this.#refreshIndex();
+        await this.#ensureFirstUserMessageIndexed(sessionId);
+        return this.#shared.index.sessions.find((session) => session.id === sessionId)?.resume
+            ?.firstUserMessagePreview;
+    }
+    async #ensureFirstUserMessageIndexed(sessionId) {
+        for (;;) {
+            const before = this.#shared.index.sessions.find((session) => session.id === sessionId);
+            if (before === undefined)
+                throw new MarAgentError('MAR_AGENT_SESSION_NOT_FOUND', 'Session was not found.');
+            if (before.resume?.firstUserMessageIndexed === true)
+                return;
+            const nextSequence = before.nextSequence;
+            const transactionId = before.storageTransactionId;
+            let preview;
+            try {
+                for (const path of await this.#segmentPaths(sessionId)) {
+                    for await (const record of readRecordsFromHead(path)) {
+                        preview = userMessagePreviewFromRecord(record);
+                        if (preview !== undefined)
+                            break;
+                    }
+                    if (preview !== undefined)
+                        break;
+                }
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT' &&
+                    !(error instanceof MarAgentError && error.code === 'MAR_AGENT_SESSION_NOT_FOUND'))
+                    throw error;
+            }
+            await this.#refreshIndex();
+            const current = this.#shared.index.sessions.find((session) => session.id === sessionId);
+            if (current === undefined)
+                throw new MarAgentError('MAR_AGENT_SESSION_NOT_FOUND', 'Session was not found.');
+            if (current.resume?.firstUserMessageIndexed === true)
+                return;
+            if (current.nextSequence !== nextSequence || current.storageTransactionId !== transactionId)
+                continue;
+            const resume = (current.resume ??= { version: 1, todoRevision: 0 });
+            resume.firstUserMessageIndexed = true;
+            if (preview !== undefined)
+                resume.firstUserMessagePreview = preview;
+            // Derived preview caches do not change list membership, ordering or filters.
+            this.#markIndexDirty(sessionId, true);
+            return;
+        }
+    }
     async #ensureExecutionModelIndexed(sessionId) {
         const pending = this.#shared.executionModelReads.get(sessionId);
         if (pending !== undefined)
@@ -1586,7 +1668,11 @@ export class JsonlSessionStore {
         if (this.#leaseClosed || this.#shared.closed)
             throw new MarAgentError('MAR_AGENT_DISPOSED', 'Session store is closed.');
     }
-    #markIndexDirty(sessionId) {
+    #markIndexDirty(sessionId, previewOnly = false) {
+        if (!previewOnly)
+            this.#shared.previewOnlyDirtySessions.delete(sessionId);
+        else if (!this.#shared.dirtySessionVersions.has(sessionId))
+            this.#shared.previewOnlyDirtySessions.add(sessionId);
         this.#shared.indexDirty = true;
         this.#shared.dirtySessionVersions.set(sessionId, (this.#shared.dirtySessionVersions.get(sessionId) ?? 0) + 1);
     }
@@ -1679,6 +1765,26 @@ export class JsonlSessionStore {
         JsonlSessionStore.#instances.delete(this.#shared.root);
     }
 }
+/** Merge a derived cache only onto the unchanged history it was computed from. */
+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 })
+        }
+    };
+}
 async function readSessionIndex(path) {
     let raw;
     try {
@@ -2157,7 +2263,9 @@ function deriveExecutionState(records) {
     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;
@@ -2198,10 +2306,21 @@ function deriveExecutionState(records) {
             ...(todoSequence === undefined ? {} : { todoSequence }),
             todoRevision,
             executionModelIndexed: true,
+            firstUserMessageIndexed: true,
+            ...(firstUserMessagePreview === undefined ? {} : { firstUserMessagePreview }),
             ...(executionModel === undefined ? {} : executionModel)
         }
     };
 }
+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;
+}
 function executionModelFromRecord(record) {
     if (record.type !== 'execution.header' || !isObject(record.payload))
         return undefined;
@@ -2254,10 +2373,63 @@ function sameResumeIndex(left, right) {
         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);
 }
+/** Read only the prefix needed by discovery; never load the entire transcript. */
+async function* readRecordsFromHead(path) {
+    const handle = await open(path, 'r');
+    try {
+        const { size } = await handle.stat();
+        const chunk = Buffer.allocUnsafe(REVERSE_READ_CHUNK_BYTES);
+        let position = 0;
+        let pending = Buffer.alloc(0);
+        while (position < size) {
+            const { bytesRead } = await handle.read(chunk, 0, Math.min(chunk.length, size - position), position);
+            if (bytesRead === 0)
+                break;
+            position += bytesRead;
+            const data = Buffer.concat([pending, chunk.subarray(0, bytesRead)]);
+            let start = 0;
+            for (;;) {
+                const end = data.indexOf(0x0a, start);
+                if (end < 0)
+                    break;
+                const line = data.subarray(start, end).toString('utf8');
+                start = end + 1;
+                if (!line)
+                    continue;
+                let record;
+                try {
+                    record = JSON.parse(line);
+                }
+                catch (cause) {
+                    throw new MarAgentError('MAR_AGENT_SESSION_CORRUPT', 'Session history is corrupt.', {
+                        cause
+                    });
+                }
+                yield record;
+            }
+            pending = Buffer.from(data.subarray(start));
+        }
+        if (pending.length > 0) {
+            let record;
+            try {
+                record = JSON.parse(pending.toString('utf8'));
+            }
+            catch {
+                return; // Readers ignore only an interrupted final line.
+            }
+            yield record;
+        }
+    }
+    finally {
+        await handle.close();
+    }
+}
 async function readRecords(path) {
     const value = await readFile(path, 'utf8');
     const lines = value.split('\n');

package/dist/agent-core/tools/code-mode/quickjs-engine.js

@@ -13,6 +13,18 @@ export async function createCodeModeEngine(options) {
             if (disposed || runtime)
                 throw diagnostic('MAR_AGENT_CODE_FAILED', 'Engine is not reusable.');
             runtime = quickjs.newRuntime();
+            // QuickJS 0.32.0 caches the job's context-pointer view across WASM memory growth
+            // (upstream #240). A detached view creates an unowned Context and breaks disposal.
+            // Keep this dependency-specific correction inside the worker engine; preserve its
+            // pointer allocation/free lifecycle and always read from the current heap.
+            const newMutablePointerArray = runtime.memory.newMutablePointerArray.bind(runtime.memory);
+            runtime.memory.newMutablePointerArray = (length) => {
+                const pointer = newMutablePointerArray(length);
+                Object.defineProperty(pointer.value, 'typedArray', {
+                    get: () => new Int32Array(runtime.module.HEAP8.buffer, pointer.value.ptr, length)
+                });
+                return pointer;
+            };
             runtime.setMemoryLimit(input.limits.memoryBytes);
             runtime.setMaxStackSize(input.limits.stackBytes);
             let executionMs = 0;

package/dist/agent-core/tools/local/view-image.js

@@ -27,17 +27,25 @@ export class ViewImageTool {
         const path = await this.paths.resolve(input.path);
         const handle = await open(path, 'r');
         try {
-            const stat = await handle.stat();
+            const stat = await handle.stat({ bigint: true });
             if (!stat.isFile())
                 throw new MarAgentError('MAR_AGENT_TOOL_INPUT_INVALID', 'Path is not a regular file.');
-            if (stat.size > TOOL_EXECUTION_LIMITS.viewImageMaxBytes)
+            if (stat.size > BigInt(TOOL_EXECUTION_LIMITS.viewImageMaxBytes))
                 throw new MarAgentError('MAR_AGENT_TOOL_OUTPUT_LIMIT', `Image exceeds the ${TOOL_EXECUTION_LIMITS.viewImageMaxBytes}-byte limit.`);
             signal?.throwIfAborted();
             const data = await handle.readFile();
             signal?.throwIfAborted();
             if (data.byteLength > TOOL_EXECUTION_LIMITS.viewImageMaxBytes)
                 throw new MarAgentError('MAR_AGENT_TOOL_OUTPUT_LIMIT', `Image exceeds the ${TOOL_EXECUTION_LIMITS.viewImageMaxBytes}-byte limit.`);
+            const after = await handle.stat({ bigint: true });
+            signal?.throwIfAborted();
+            if (stat.size !== after.size ||
+                after.size !== BigInt(data.byteLength) ||
+                stat.mtimeNs !== after.mtimeNs ||
+                stat.ctimeNs !== after.ctimeNs)
+                return incompleteImage();
             const mimeType = detectImageMime(data);
+            validateImageContainer(data, mimeType);
             const metadata = {
                 path: input.path,
                 mimeType,
@@ -80,3 +88,101 @@ export function detectImageMime(data) {
 function invalidInput() {
     throw new MarAgentError('MAR_AGENT_TOOL_INPUT_INVALID', 'View image input is invalid.');
 }
+// Basic container checks catch partial writes without decoding or changing pixels.
+function validateImageContainer(data, mimeType) {
+    if (mimeType === 'image/jpeg') {
+        let offset = 2;
+        let inScan = false;
+        let hasScan = false;
+        while (offset < data.length) {
+            if (data[offset++] !== 0xff) {
+                if (!inScan)
+                    incompleteImage();
+                continue;
+            }
+            while (data[offset] === 0xff)
+                offset++;
+            if (offset >= data.length)
+                incompleteImage();
+            const marker = data[offset++];
+            if (marker === 0 || (marker >= 0xd0 && marker <= 0xd7)) {
+                if (!inScan)
+                    incompleteImage();
+                continue;
+            }
+            if (marker === 0xd9) {
+                if (!hasScan)
+                    incompleteImage();
+                return;
+            }
+            if (marker === 0xd8)
+                incompleteImage();
+            if (marker === 1)
+                continue;
+            if (data.length - offset < 2)
+                incompleteImage();
+            const length = data.readUInt16BE(offset);
+            if (length < 2 || offset + length > data.length)
+                incompleteImage();
+            offset += length;
+            if (marker === 0xda)
+                hasScan = true;
+            inScan = marker === 0xda || (inScan && marker === 0xdc);
+        }
+        incompleteImage();
+    }
+    if (mimeType === 'image/webp') {
+        const end = data.readUInt32LE(4) + 8;
+        if (end > data.length || end < 20)
+            incompleteImage();
+        let offset = 12;
+        let hasPixels = false;
+        while (offset < end) {
+            if (end - offset < 8)
+                incompleteImage();
+            const length = data.readUInt32LE(offset + 4);
+            const next = offset + 8 + length + (length % 2);
+            if (next > end)
+                incompleteImage();
+            const type = data.toString('ascii', offset, offset + 4);
+            if ((type === 'VP8 ' || type === 'VP8L' || type === 'ANMF') && length > 0)
+                hasPixels = true;
+            offset = next;
+        }
+        if (!hasPixels)
+            incompleteImage();
+        return;
+    }
+    let offset = 8;
+    let hasPixels = false;
+    while (offset < data.length) {
+        if (data.length - offset < 12)
+            incompleteImage();
+        const length = data.readUInt32BE(offset);
+        const next = offset + 12 + length;
+        if (next > data.length)
+            incompleteImage();
+        const type = data.toString('ascii', offset + 4, offset + 8);
+        if (offset === 8) {
+            if (type !== 'IHDR' ||
+                length !== 13 ||
+                data.readUInt32BE(offset + 8) === 0 ||
+                data.readUInt32BE(offset + 12) === 0)
+                incompleteImage();
+        }
+        else if (type === 'IHDR')
+            incompleteImage();
+        if (type === 'IDAT' && length > 0)
+            hasPixels = true;
+        if (type === 'IEND') {
+            if (length !== 0 || !hasPixels)
+                incompleteImage();
+            return;
+        }
+        offset = next;
+    }
+    incompleteImage();
+}
+function incompleteImage() {
+    throw new MarAgentError('MAR_AGENT_IMAGE_INCOMPLETE', 'Image file is incomplete, malformed, or changed while reading. Wait for the writer to finish and read it again.');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@myagentroam/agent",
-  "version": "0.9.157",
+  "version": "0.9.159",
   "description": "Embeddable MAR coding agent SDK and CLI.",
   "license": "Apache-2.0",
   "type": "module",