@myagentroam/agent 0.11.21 → 0.11.22

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

@@ -1,8 +1,10 @@
 import { randomUUID } from 'node:crypto';
+import { inlineMediaHistory } from '../inline-media.js';
 import { lstat, mkdir, open, readdir, rename, rm, stat, writeFile } from 'node:fs/promises';
 import { basename, join } from 'node:path';
 import { isDeepStrictEqual } from 'node:util';
 import { MarAgentError } from '../../error.js';
+import { isModelImageUrl } from '../../model/image.js';
 import { cloneCoreJson } from '../../extensions/data.js';
 import { acquireFileLock } from '../../storage/file-lock.js';
 import { todoItemsFromSnapshot } from '../../tools/agent/todo.js';
@@ -14,7 +16,8 @@ import { extensionCheckpointFromPayload, indexExtensionCheckpoint, restoreExtens
 import { decodeSessionListCursor, encodeSessionListCursor, mergeSessionDerivedCache, normalizeSessionSource, persistSessionIndex, readSessionIndex, sessionListFilter, sessionMatchesFilter, sessionTreeIds } from './directory-index.js';
 import { deriveExecutionState, executionModelFromRecord, isCompactCheckpoint, isNativeUserTurn, sameResumeIndex, userMessagePreviewFromRecord } from './execution-state.js';
 import { forkedPayload, renameIfExists, restoreRenamedFiles, retainedSessionTitle, stageSessionSegments, stageUnreferencedImages } from './history.js';
-import { MAX_INPUT_IMAGES, copyGeneratedImages, copyInputImages, generatedImageFileNames, inputImageReference, inputImageReferences, inputImageReferencesFromRecords, readInputImageBytes, recoverPendingInputImages, validInputImageFileName, writeInputImages } from './images.js';
+import { MAX_INPUT_IMAGES, copyGeneratedImages, generatedImageFileNames, inputImageReference, inputImageReferences, readInputImageBytes } from './images.js';
+import { persistResource, setResourceUrl, readResource, copyResources, resourceFiles, completeResources, recoverResources } from './resources.js';
 import { MAX_SEGMENT_BYTES, appendRecordBytes, readRecordPageFromTail, readRecords, readRecordsFromHead, readRecordsFromTail, repairSegmentTail, segmentNumberFromPath } from './records.js';
 const MAX_CONTEXTUAL_WORLD_STATE_BYTES = 8 * 1024 * 1024;
 const CONTEXTUAL_WORLD_STATE_FILE = 'context-world-state.json';
@@ -446,8 +449,59 @@ export class JsonlSessionStore {
             return [];
         if (images.length > MAX_INPUT_IMAGES)
             throw new MarAgentError('MAR_AGENT_HOST_LIMIT_EXCEEDED', 'Too many image inputs were provided.');
-        const directory = join(this.#sessionDirectory(sessionId), 'input_images');
-        return writeInputImages(directory, images);
+        const resources = [];
+        let total = 0;
+        for (const image of images) {
+            if ((image.url !== undefined && !isModelImageUrl(image.url)) ||
+                (image.urlExpiresAt !== undefined &&
+                    (!Number.isSafeInteger(image.urlExpiresAt) ||
+                        image.urlExpiresAt <= 0 ||
+                        image.url === undefined)))
+                throw new MarAgentError('MAR_AGENT_SESSION_INPUT_INVALID', 'Image model URL is invalid.');
+            let resource = await this.persistResource(sessionId, image);
+            if (image.url !== undefined && image.urlExpiresAt !== undefined)
+                resource = await this.setResourceUrl(sessionId, resource.resourceId, {
+                    url: image.url,
+                    urlExpiresAt: image.urlExpiresAt
+                });
+            total += resource.byteSize;
+            if (resource.byteSize > 5 * 1024 * 1024 || total > 10 * 1024 * 1024)
+                throw new MarAgentError('MAR_AGENT_HOST_LIMIT_EXCEEDED', 'Image input exceeds the supported size limit.');
+            resources.push({
+                ...resource,
+                resourceInputVersion: 1,
+                name: image.name,
+                fileName: `${resource.resourceId}.bin`
+            });
+        }
+        return resources;
+    }
+    async persistResource(sessionId, image) {
+        this.#assertOpen();
+        return this.#serializeRecordOperation(sessionId, () => persistResource(join(this.#sessionDirectory(sessionId), 'resources'), image));
+    }
+    async setResourceUrl(sessionId, resourceId, published) {
+        this.#assertOpen();
+        return this.#serializeRecordOperation(sessionId, () => setResourceUrl(join(this.#sessionDirectory(sessionId), 'resources'), resourceId, published));
+    }
+    async readResource(sessionId, resourceId) {
+        this.#assertOpen();
+        const directory = join(this.#sessionDirectory(sessionId), 'resources');
+        if (!/^[a-f0-9]{64}$/u.test(resourceId))
+            return undefined;
+        return this.#serializeRecordOperation(sessionId, async () => {
+            try {
+                await lstat(join(directory, `.${resourceId}.pending`));
+                if (this.#shared.writerLeases.get(sessionId)?.appendFailure !== undefined ||
+                    !resourceFiles(await this.#readRecords(sessionId)).has(`${resourceId}.bin`))
+                    return undefined;
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+            }
+            return readResource(directory, resourceId);
+        });
     }
     async writeToolResultResource(sessionId, text) {
         this.#assertOpen();
@@ -467,14 +521,21 @@ export class JsonlSessionStore {
     }
     async readInputImages(sessionId, value) {
         this.#assertOpen();
-        const references = inputImageReferences(value);
+        const references = inputImageReferences(Array.isArray(value) ? value.filter((item) => item?.resourceInputVersion === 1) : undefined);
         if (references.length === 0)
             return [];
-        const directory = join(this.#sessionDirectory(sessionId), 'input_images');
         const images = [];
         for (const reference of references) {
-            const data = await readInputImageBytes(directory, reference);
-            images.push({ mimeType: reference.mimeType, dataBase64: data.toString('base64') });
+            if (reference.resourceId === undefined)
+                throw new MarAgentError('MAR_AGENT_SESSION_CORRUPT', 'Session resource identity is missing.');
+            images.push({
+                resourceInputVersion: 1,
+                mimeType: reference.mimeType,
+                byteSize: reference.byteSize,
+                resourceId: reference.resourceId,
+                ...(reference.url === undefined ? {} : { url: reference.url }),
+                ...(reference.urlExpiresAt === undefined ? {} : { urlExpiresAt: reference.urlExpiresAt })
+            });
         }
         return images;
     }
@@ -497,10 +558,14 @@ export class JsonlSessionStore {
             return undefined;
         if (!Array.isArray(record.payload.images) || input.imageIndex >= record.payload.images.length)
             return undefined;
+        if (record.payload.images[input.imageIndex]?.resourceInputVersion !== 1)
+            return undefined;
         const reference = inputImageReference(record.payload.images[input.imageIndex]);
         if (reference === undefined)
             return undefined;
-        const data = await readInputImageBytes(join(this.#sessionDirectory(sessionId), 'input_images'), reference);
+        if (reference.resourceId === undefined)
+            throw new MarAgentError('MAR_AGENT_SESSION_CORRUPT', 'Session resource identity is missing.');
+        const data = await readInputImageBytes(join(this.#sessionDirectory(sessionId), 'resources'), reference);
         return {
             name: reference.name,
             mimeType: reference.mimeType,
@@ -564,6 +629,9 @@ export class JsonlSessionStore {
                     }
                 ];
                 const retained = input.boundaryTurnId === null ? [] : records.slice(1, boundaryIndex + 1);
+                const inlineState = inlineMediaHistory(retained).state;
+                const stateAnchor = inlineState &&
+                    retained.findLast((record) => record.type === 'resource.window' || record.type === 'compact.completed');
                 const forkIdentities = new Map();
                 for (const record of retained) {
                     if (record.type === 'context.gc.completed' || record.type === 'responses.continuation')
@@ -575,7 +643,14 @@ export class JsonlSessionStore {
                         ...identity,
                         sessionId: target.id,
                         type: record.type,
-                        payload: forkedPayload(record.type, record.payload, sourceSessionId, target.id, input.title, forkIdentities),
+                        payload: forkedPayload(record.type, record === stateAnchor
+                            ? record.type === 'resource.window'
+                                ? inlineState
+                                : {
+                                    ...record.payload,
+                                    inlineMediaState: inlineState
+                                }
+                            : record.payload, sourceSessionId, target.id, input.title, forkIdentities),
                         ...(record.executionId === undefined ? {} : { executionId: record.executionId }),
                         ...(record.turnId === undefined ? {} : { turnId: record.turnId }),
                         timestamp: record.timestamp
@@ -592,7 +667,7 @@ export class JsonlSessionStore {
                     this.#applyRecordToResumeIndex(target, record);
                 await copyToolResultResources(this.#sessionDirectory(sourceSessionId), this.#sessionDirectory(target.id), copied);
                 await copyGeneratedImages(this.#sessionDirectory(sourceSessionId), this.#sessionDirectory(target.id), generatedImageFileNames(retained));
-                await copyInputImages(this.#sessionDirectory(sourceSessionId), this.#sessionDirectory(target.id), inputImageReferencesFromRecords(retained));
+                await copyResources(this.#sessionDirectory(sourceSessionId), this.#sessionDirectory(target.id), retained);
                 target.lastActivityAt = target.createdAt;
                 this.#shared.pendingSessions.delete(target.id);
                 this.#shared.index = {
@@ -766,7 +841,7 @@ export class JsonlSessionStore {
         const contextualWorldStateBackup = `${contextualWorldStatePath}.${targetNextSequence}.${transactionId}.${operation.kind}-backup`;
         let contextualWorldStateStaged = false;
         let generatedTrash = [];
-        let inputTrash = [];
+        let resourceTrash = [];
         const originalMeta = structuredClone(meta);
         const originalIndexRevision = this.#shared.index.revision;
         const originalSegment = this.#shared.segments.get(sessionId);
@@ -792,10 +867,7 @@ export class JsonlSessionStore {
             await beginSessionStorageTransaction(this.#sessionDirectory(sessionId), transaction);
             contextualWorldStateStaged = await renameIfExists(contextualWorldStatePath, contextualWorldStateBackup);
             generatedTrash = await stageUnreferencedImages(this.#sessionDirectory(sessionId), 'generated_images', operation.kind === 'rollback' ? new Set(generatedImageFileNames(retained)) : new Set(), transactionId);
-            inputTrash = await stageUnreferencedImages(this.#sessionDirectory(sessionId), 'input_images', operation.kind === 'rollback'
-                ? new Set(inputImageReferencesFromRecords(retained).map((image) => image.fileName))
-                : new Set(), transactionId);
-            inputTrash.push(...(await stageUnreferencedImages(this.#sessionDirectory(sessionId), 'tool_results', operation.kind === 'rollback' ? toolResultResourceFiles(retained) : new Set(), transactionId)));
+            resourceTrash.push(...(await stageUnreferencedImages(this.#sessionDirectory(sessionId), 'resources', operation.kind === 'rollback' ? resourceFiles(retained) : new Set(), transactionId)), ...(await stageUnreferencedImages(this.#sessionDirectory(sessionId), 'tool_results', operation.kind === 'rollback' ? toolResultResourceFiles(retained) : new Set(), transactionId)));
             for (const item of backups)
                 await rename(item.path, item.backup);
             for (const item of staged.files) {
@@ -850,7 +922,7 @@ export class JsonlSessionStore {
                     await restoreRenamedFiles([
                         { from: contextualWorldStateBackup, to: contextualWorldStatePath }
                     ]);
-                await restoreRenamedFiles([...generatedTrash, ...inputTrash]);
+                await restoreRenamedFiles([...generatedTrash, ...resourceTrash]);
                 restoreSessionMeta(meta, originalMeta);
                 this.#shared.index.revision = originalIndexRevision;
                 if (originalSegment === undefined)
@@ -990,14 +1062,7 @@ export class JsonlSessionStore {
         }
         updateSessionCurrentState(this.#shared.writerLeases.get(sessionId), record.type, serialized);
         await completeToolResultResources(this.#sessionDirectory(sessionId), record);
-        if (record.type === 'turn.user' &&
-            isObject(record.payload) &&
-            Array.isArray(record.payload.images))
-            for (const image of record.payload.images)
-                if (isObject(image) &&
-                    typeof image.fileName === 'string' &&
-                    validInputImageFileName(image.fileName))
-                    await rm(join(this.#sessionDirectory(sessionId), 'input_images', `.${image.fileName}.pending`), { force: true }).catch(() => undefined);
+        await completeResources(join(this.#sessionDirectory(sessionId), 'resources'), record);
         return record;
     }
     async read(sessionId) {
@@ -1150,17 +1215,21 @@ export class JsonlSessionStore {
                 !sameContextGcBase(contextGcBaseFromRecords(records, boundarySequence), draft.base))
                 throw new MarAgentError('MAR_AGENT_SESSION_CORRUPT', 'Context GC planning boundary is invalid.');
             const previous = latestValidContextGcCheckpoint(records, boundarySequence);
-            if (!contextGcCheckpointIntervalEligible(draft.trigger, previous?.payload.trigger))
+            if ((!draft.inlineMedia || draft.inlineMedia.reason === 'TEXT_GC') &&
+                !contextGcCheckpointIntervalEligible(draft.trigger, previous?.payload.trigger))
                 throw new MarAgentError('MAR_AGENT_SESSION_CORRUPT', 'Context GC checkpoint interval validation failed.');
             const plannedReplacements = normalizeContextGcReplacements(draft.replacements);
-            if (!plannedReplacements || plannedReplacements.length === 0)
+            if (!plannedReplacements || (plannedReplacements.length === 0 && !draft.inlineMedia))
                 throw new MarAgentError('MAR_AGENT_SESSION_CORRUPT', 'Context GC checkpoint must contain a replacement.');
             const replacements = normalizeContextGcReplacements([
                 ...(previous?.payload.replacements ?? []),
                 ...plannedReplacements
             ]);
             if (!replacements ||
-                (previous && isDeepStrictEqual(replacements, previous.payload.replacements)))
+                (previous &&
+                    isDeepStrictEqual(replacements, previous.payload.replacements) &&
+                    (!draft.inlineMedia ||
+                        isDeepStrictEqual(draft.inlineMedia, previous.payload.inlineMedia))))
                 throw new MarAgentError('MAR_AGENT_SESSION_CORRUPT', 'Context GC replacement map is invalid.');
             const payload = {
                 ...structuredClone(draft),
@@ -1180,8 +1249,10 @@ export class JsonlSessionStore {
             if (Buffer.byteLength(JSON.stringify(payload)) >= MAX_SEGMENT_BYTES ||
                 validateContextGcCheckpoint(records, candidate, meta.workspace, previous?.payload.replacements) === undefined)
                 throw new MarAgentError('MAR_AGENT_SESSION_CORRUPT', 'Context GC checkpoint validation failed.');
+            const turnId = records.findLast((record) => record.type === 'execution.header')?.turnId;
             return this.#appendRecord(sessionId, {
                 type: 'context.gc.completed',
+                ...(turnId === undefined ? {} : { turnId }),
                 payload
             });
         });
@@ -1238,6 +1309,7 @@ export class JsonlSessionStore {
                 ...(input.retainedModelContext?.length
                     ? { retainedModelContext: input.retainedModelContext }
                     : {}),
+                ...(input.inlineMediaState ? { inlineMediaState: input.inlineMediaState } : {}),
                 ...(input.environment === undefined ? {} : { environment: input.environment }),
                 boundarySequence: meta.nextSequence - 1,
                 automatic: input.automatic === true,
@@ -1891,7 +1963,7 @@ export class JsonlSessionStore {
         const latestPath = paths.at(-1);
         await repairSegmentTail(latestPath);
         const records = await readRecords(latestPath);
-        await recoverPendingInputImages(this.#sessionDirectory(sessionId), () => this.#readRecords(sessionId));
+        await recoverResources(join(this.#sessionDirectory(sessionId), 'resources'), () => this.#readRecords(sessionId));
         await cleanupUnreferencedToolResources(this.#sessionDirectory(sessionId), () => this.#readRecords(sessionId));
         const last = records.at(-1);
         const match = /events-(\d{6})\.jsonl$/.exec(latestPath);

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

@@ -0,0 +1,26 @@
+import { type ModelImage } from '../../model/image.js';
+import type { SessionRecord } from './types.js';
+export interface SessionResource {
+    readonly resourceInputVersion?: 1;
+    readonly resourceId: string;
+    readonly mimeType: string;
+    readonly byteSize: number;
+    readonly sha256: string;
+    readonly url?: string;
+    readonly urlExpiresAt?: number;
+}
+export declare function resourceMetadata(directory: string, resourceId: string): Promise<SessionResource | undefined>;
+export declare function persistResource(directory: string, image: ModelImage): Promise<SessionResource>;
+export declare function setResourceUrl(directory: string, resourceId: string, published: {
+    url: string;
+    urlExpiresAt: number;
+}): Promise<SessionResource>;
+export declare function readResource(directory: string, resourceId: string): Promise<{
+    mimeType: string;
+    dataBase64: string;
+} | undefined>;
+/** Resource identities are SDK-owned metadata, never interpreted as file paths. */
+export declare function resourceFiles(records: readonly SessionRecord[]): Set<string>;
+export declare function copyResources(source: string, target: string, records: readonly SessionRecord[]): Promise<void>;
+export declare function completeResources(directory: string, record: SessionRecord): Promise<void>;
+export declare function recoverResources(directory: string, readHistory: () => Promise<SessionRecord[]>): Promise<void>;

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

@@ -0,0 +1,196 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdir, readFile, readdir, rename, rm, writeFile } from 'node:fs/promises';
+import { basename, dirname, join } from 'node:path';
+import { MarAgentError } from '../../error.js';
+import { isModelImageUrl } from '../../model/image.js';
+import { readInputImageBytes } from './images.js';
+const idPattern = /^[a-f0-9]{64}$/u;
+const mimeTypes = new Set(['image/png', 'image/jpeg', 'image/gif', 'image/webp']);
+function resourceIdentity(mimeType, sha256) {
+    return createHash('sha256').update(mimeType).update('\0').update(sha256).digest('hex');
+}
+export async function resourceMetadata(directory, resourceId) {
+    if (!idPattern.test(resourceId))
+        return undefined;
+    let text;
+    try {
+        text = await readFile(join(directory, `${resourceId}.json`), 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        // Invalid JSON is reported below without exposing metadata contents.
+    }
+    if (!value ||
+        value.resourceId !== resourceId ||
+        !mimeTypes.has(value.mimeType) ||
+        !Number.isSafeInteger(value.byteSize) ||
+        value.byteSize <= 0 ||
+        value.byteSize > 20 * 1024 * 1024 ||
+        !idPattern.test(value.sha256) ||
+        resourceIdentity(value.mimeType, value.sha256) !== resourceId ||
+        (value.url !== undefined &&
+            (!isModelImageUrl(value.url) ||
+                !Number.isSafeInteger(value.urlExpiresAt) ||
+                value.urlExpiresAt <= 0)) ||
+        (value.url === undefined && value.urlExpiresAt !== undefined))
+        throw new MarAgentError('MAR_AGENT_SESSION_CORRUPT', 'Session image resource is corrupt.');
+    return value;
+}
+export async function persistResource(directory, image) {
+    if (image.resourceId !== undefined && image.dataBase64 === undefined) {
+        const existing = await resourceMetadata(directory, image.resourceId);
+        if (existing !== undefined && existing.mimeType === image.mimeType)
+            return existing;
+        throw new MarAgentError('MAR_AGENT_SESSION_CORRUPT', 'Session image resource is missing.');
+    }
+    const data = Buffer.from(image.dataBase64 ?? '', 'base64');
+    if (data.toString('base64') !== image.dataBase64)
+        throw new MarAgentError('MAR_AGENT_SESSION_INPUT_INVALID', 'Image resource data is not canonical base64.');
+    if (!mimeTypes.has(image.mimeType) || data.length === 0 || data.length > 20 * 1024 * 1024)
+        throw new MarAgentError('MAR_AGENT_HOST_LIMIT_EXCEEDED', 'Image resource exceeds supported limits.');
+    const sha256 = createHash('sha256').update(data).digest('hex');
+    const resourceId = resourceIdentity(image.mimeType, sha256);
+    if (image.resourceId !== undefined && image.resourceId !== resourceId)
+        throw new MarAgentError('MAR_AGENT_SESSION_INPUT_INVALID', 'Image resource identity does not match its bytes.');
+    const existing = await resourceMetadata(directory, resourceId);
+    if (existing !== undefined)
+        return existing;
+    const resource = {
+        resourceInputVersion: 1,
+        resourceId,
+        mimeType: image.mimeType,
+        byteSize: data.length,
+        sha256
+    };
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    await writeFile(join(directory, `.${resourceId}.pending`), '', { mode: 0o600, flush: true });
+    await atomicWrite(join(directory, `${resourceId}.bin`), data);
+    await atomicWrite(join(directory, `${resourceId}.json`), JSON.stringify(resource));
+    return resource;
+}
+export async function setResourceUrl(directory, resourceId, published) {
+    const resource = await resourceMetadata(directory, resourceId);
+    if (!resource)
+        throw new MarAgentError('MAR_AGENT_SESSION_CORRUPT', 'Session image resource is missing.');
+    if (resource.url !== undefined)
+        return resource;
+    if (!isModelImageUrl(published.url) ||
+        !Number.isSafeInteger(published.urlExpiresAt) ||
+        published.urlExpiresAt <= 0)
+        throw new MarAgentError('MAR_AGENT_IMAGE_PUBLICATION_FAILED', 'Image URL publication failed.');
+    const result = { ...resource, url: published.url, urlExpiresAt: published.urlExpiresAt };
+    await atomicWrite(join(directory, `${resourceId}.json`), JSON.stringify(result));
+    return result;
+}
+export async function readResource(directory, resourceId) {
+    const resource = await resourceMetadata(directory, resourceId);
+    if (!resource)
+        return undefined;
+    const bytes = await readInputImageBytes(directory, {
+        ...resource,
+        name: 'image',
+        fileName: `${resourceId}.bin`
+    });
+    return { mimeType: resource.mimeType, dataBase64: bytes.toString('base64') };
+}
+/** Resource identities are SDK-owned metadata, never interpreted as file paths. */
+export function resourceFiles(records) {
+    const ids = new Set();
+    const visit = (value) => {
+        if (Array.isArray(value)) {
+            for (const item of value)
+                visit(item);
+            return;
+        }
+        if (!value || typeof value !== 'object')
+            return;
+        const item = value;
+        if (item.resourceInputVersion === 1 &&
+            typeof item.resourceId === 'string' &&
+            idPattern.test(item.resourceId))
+            ids.add(item.resourceId);
+        for (const key of ['images', 'input', 'pendingInputs', 'payload', 'retainedModelContext'])
+            if (item[key] !== undefined)
+                visit(item[key]);
+    };
+    for (const record of records)
+        visit(record.payload);
+    return new Set([...ids].flatMap((id) => [`${id}.bin`, `${id}.json`]));
+}
+export async function copyResources(source, target, records) {
+    const files = resourceFiles(records);
+    if (!files.size)
+        return;
+    await mkdir(join(target, 'resources'), { recursive: true, mode: 0o700 });
+    for (const file of files) {
+        if (!file.endsWith('.bin'))
+            continue;
+        const resourceId = file.slice(0, -4);
+        const resource = await resourceMetadata(join(source, 'resources'), resourceId);
+        if (resource === undefined)
+            throw new MarAgentError('MAR_AGENT_SESSION_CORRUPT', 'Session image resource is missing.');
+        const bytes = await readInputImageBytes(join(source, 'resources'), {
+            ...resource,
+            name: 'image',
+            fileName: file
+        });
+        await writeFile(join(target, 'resources', file), bytes, {
+            mode: 0o600,
+            flag: 'wx',
+            flush: true
+        });
+        await writeFile(join(target, 'resources', `${resourceId}.json`), JSON.stringify(resource), {
+            mode: 0o600,
+            flag: 'wx',
+            flush: true
+        });
+    }
+}
+export async function completeResources(directory, record) {
+    for (const file of resourceFiles([record]))
+        if (file.endsWith('.bin'))
+            await rm(join(directory, `.${file.slice(0, -4)}.pending`), { force: true });
+}
+export async function recoverResources(directory, readHistory) {
+    let names;
+    try {
+        names = await readdir(directory);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return;
+        throw error;
+    }
+    const pending = names.filter((name) => /^\.[a-f0-9]{64}\.pending$/u.test(name));
+    if (pending.length) {
+        const retained = resourceFiles(await readHistory());
+        for (const name of pending) {
+            const id = name.slice(1, -8);
+            if (!retained.has(`${id}.bin`))
+                for (const suffix of ['bin', 'json'])
+                    await rm(join(directory, `${id}.${suffix}`), { force: true });
+            await rm(join(directory, name), { force: true });
+        }
+    }
+    for (const name of names)
+        if (/^\.[a-f0-9]{64}\.(?:bin|json)\.[a-f0-9-]{36}\.tmp$/u.test(name))
+            await rm(join(directory, name), { force: true });
+}
+async function atomicWrite(path, data) {
+    const temporary = join(dirname(path), `.${basename(path)}.${randomUUID()}.tmp`);
+    try {
+        await writeFile(temporary, data, { mode: 0o600, flag: 'wx', flush: true });
+        await rename(temporary, path);
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}

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

@@ -1,6 +1,7 @@
 import type { ModelInputMetadata } from '../../model/contracts.js';
 import type { TodoSnapshot } from '../../tools/agent/todo.js';
 import type { SessionSource } from '../types.js';
+import type { ModelImage } from '../../model/image.js';
 export interface SessionRecord {
     schemaVersion: 1;
     recordId: string;
@@ -25,21 +26,21 @@ export interface CompactHistoryMessage extends CompactUserInput {
     role: 'user';
     kind: 'user_input' | 'extension_input' | 'summary';
 }
-export interface SessionInputImage {
+export interface SessionInputImage extends ModelImage {
     readonly name: string;
-    readonly mimeType: string;
-    readonly dataBase64: string;
 }
 export interface SessionInputImageMetadata {
+    readonly resourceInputVersion?: 1;
     readonly name: string;
     readonly mimeType: string;
     readonly byteSize: number;
     readonly fileName: string;
     readonly sha256: string;
+    readonly resourceId?: string;
+    readonly url?: string;
+    readonly urlExpiresAt?: number;
 }
-export interface RestoredSessionInputImage {
-    readonly mimeType: string;
-    readonly dataBase64: string;
+export interface RestoredSessionInputImage extends ModelImage {
 }
 export interface SessionInputImageData extends SessionInputImageMetadata {
     readonly dataBase64: string;

package/dist/agent-core/session/transaction-recovery.js

@@ -92,7 +92,7 @@ export async function recoverSessionStorageTransaction(directory, committedTrans
             await rename(backup, sidecar);
         }
     }
-    for (const folder of ['input_images', 'generated_images', 'tool_results']) {
+    for (const folder of ['generated_images', 'tool_results', 'resources']) {
         const path = join(directory, folder);
         let names;
         try {

package/dist/agent-core/tools/code-mode/cells.js

@@ -10,10 +10,9 @@ import { boundObservations, selectObservationImages, newObservationId, visibleOb
 export class CodeCellExecutionError extends MarAgentError {
     result;
     constructor(error, result) {
-        const diagnostic = describeMarAgentError(error, 'MAR_AGENT_CODE_FAILED');
-        super(diagnostic.code, diagnostic.message.startsWith(`${diagnostic.code}: `)
-            ? diagnostic.message.slice(diagnostic.code.length + 2)
-            : diagnostic.message, {
+        // Preserve the original chain; the public boundary summarizes its causes only once.
+        const diagnostic = describeMarAgentError(error, 'MAR_AGENT_CODE_FAILED', undefined, false);
+        super(diagnostic.code, diagnostic.message, {
             cause: error,
             ...(error instanceof MarAgentError ? { retryable: error.retryable } : {})
         });

package/dist/agent-core/tools/code-mode/index.js

@@ -16,6 +16,7 @@ import { BoundedTextOutput, renderCapturedText } from './text-output.js';
 import { TOOL_EXECUTION_LIMITS as limits } from '../execution-limits.js';
 import { createToolCallScheduler } from '../scheduler.js';
 import { detectImageMime } from '../local/view-image.js';
+import { isModelImageUrl } from '../../model/image.js';
 import { structuredToolFailureData } from '../output-projection.js';
 import { failedToolResultExtensions } from '../result-extensions.js';
 export const codeModeToolDefinition = {
@@ -33,7 +34,7 @@ export const codeModeToolDefinition = {
 
 Tool calls:
 - tools.NAME(input) returns a Promise. Pass a JavaScript value matching the current catalog inputSchema. For parameterless tools prefer tools.NAME({}); tools.NAME() is accepted only for explicitly closed empty-object schemas.
-- Results use the MAR envelope: { content?: string, data?: unknown, images?: Array<{mimeType:string,dataBase64:string}>, truncated?: boolean }. Redundant JSON content is omitted when it exactly renders data; independent text remains in content. Prefer data for programmatic results: result.data.results[0].text for read source text and result.data.exitCode/result.data.stdout for exec. content, when present, is rendered text, not raw file bytes. Use only fields documented by that tool; do not invent success or ok flags.
+- Results use the MAR envelope: { content?: string, data?: unknown, images?: Array<{mimeType:string,dataBase64:string,url?:string,urlExpiresAt?:number}>, truncated?: boolean }. Redundant JSON content is omitted when it exactly renders data; independent text remains in content. Prefer data for programmatic results: result.data.results[0].text for read source text and result.data.exitCode/result.data.stdout for exec. content, when present, is rendered text, not raw file bytes. Use only fields documented by that tool; do not invent success or ok flags.
 - Tool errors reject with code/message and may be caught, except nested Auto deny, which skips only that call and resolves with data.error/data.message. A failed cell preserves already emitted output alongside its status and error; completed tool effects are not rolled back. Inspect it before retrying completed work. Await every call; unawaited calls fail the cell. Use Promise.all for independent calls and sequential await for dependencies. Runtime preserves safe/serial barriers and Host checks.
 - skill, tool_search, question, code_exec, code_exec_wait and direct-only tools cannot be called here. Load Skills directly and read their instructions before the next tool call. Use direct tool_search before a later code cell for deferred tools; the current cell's tools do not change.
 
@@ -183,6 +184,7 @@ function defaultEngineFactory() {
         runtimeDirectories: [
             ...new Set([
                 fileURLToPath(new URL('.', import.meta.url)),
+                fileURLToPath(new URL('../input-diagnostics/', import.meta.url)),
                 dependencyRoot(core),
                 dependencyRoot(variant),
                 dependencyRoot(ffi)
@@ -565,10 +567,7 @@ export class CodeModeTool {
                             ok: false,
                             error: {
                                 code: diagnostic.code,
-                                // The guest carries the code separately; the outer error adds its own prefix.
-                                message: diagnostic.message.startsWith(`${diagnostic.code}: `)
-                                    ? diagnostic.message.slice(diagnostic.code.length + 2)
-                                    : diagnostic.message
+                                message: diagnostic.message
                             }
                         });
                     }
@@ -706,9 +705,27 @@ function parseImage(value) {
     if (!value || typeof value !== 'object' || Array.isArray(value))
         throw invalid();
     const image = value;
-    if (Object.keys(image).some((key) => key !== 'mimeType' && key !== 'dataBase64') ||
+    if (Object.keys(image).some((key) => !['mimeType', 'dataBase64', 'url', 'urlExpiresAt', 'resourceId', 'byteSize'].includes(key)) ||
         typeof image.mimeType !== 'string' ||
-        typeof image.dataBase64 !== 'string' ||
+        (image.resourceId !== undefined &&
+            (typeof image.resourceId !== 'string' || !/^[a-f0-9]{64}$/u.test(image.resourceId))) ||
+        (image.byteSize !== undefined &&
+            (!Number.isSafeInteger(image.byteSize) || image.byteSize <= 0)) ||
+        (image.url !== undefined && !isModelImageUrl(image.url)) ||
+        (image.urlExpiresAt !== undefined &&
+            (typeof image.urlExpiresAt !== 'number' ||
+                !Number.isSafeInteger(image.urlExpiresAt) ||
+                image.urlExpiresAt <= 0)))
+        throw invalid();
+    if (image.dataBase64 === undefined && isModelImageUrl(image.url))
+        return {
+            mimeType: image.mimeType,
+            url: image.url,
+            ...(image.urlExpiresAt === undefined ? {} : { urlExpiresAt: image.urlExpiresAt }),
+            ...(typeof image.resourceId === 'string' ? { resourceId: image.resourceId } : {}),
+            ...(typeof image.byteSize === 'number' ? { byteSize: image.byteSize } : {})
+        };
+    if (typeof image.dataBase64 !== 'string' ||
         image.dataBase64.length === 0 ||
         image.dataBase64.length > Math.ceil(limits.viewImageMaxBytes / 3) * 4 ||
         image.dataBase64.length % 4 !== 0)
@@ -718,5 +735,12 @@ function parseImage(value) {
         bytes.toString('base64') !== image.dataBase64 ||
         detectImageMime(bytes) !== image.mimeType)
         throw invalid();
-    return { mimeType: image.mimeType, dataBase64: image.dataBase64 };
+    return {
+        mimeType: image.mimeType,
+        dataBase64: image.dataBase64,
+        ...(typeof image.resourceId === 'string' ? { resourceId: image.resourceId } : {}),
+        ...(typeof image.byteSize === 'number' ? { byteSize: image.byteSize } : {}),
+        ...(image.url === undefined ? {} : { url: image.url }),
+        ...(image.urlExpiresAt === undefined ? {} : { urlExpiresAt: image.urlExpiresAt })
+    };
 }