@myagentroam/agent 0.11.20 → 0.11.22

package/dist/agent-core/session/inline-media.js

@@ -0,0 +1,163 @@
+import { MarAgentError } from '../error.js';
+import { appliedInputRecord } from './deferred-input.js';
+const MiB = 1_048_576;
+export const INLINE_MEDIA_POLICY = Object.freeze({
+    historicalInlineMediaTrigger: 7 * MiB,
+    historicalInlineMediaTarget: 5 * MiB,
+    requestInlineMediaHardLimit: 12 * MiB
+});
+export function parseInlineMediaGc(value) {
+    if (!value || typeof value !== 'object')
+        return undefined;
+    const item = value;
+    const state = parseInlineMediaState(item.state);
+    return state?.evictedThrough &&
+        state.consideredThrough &&
+        Number.isSafeInteger(item.beforeBytes) &&
+        item.beforeBytes > 0 &&
+        Number.isSafeInteger(item.afterBytes) &&
+        item.afterBytes >= 0 &&
+        item.afterBytes <= INLINE_MEDIA_POLICY.historicalInlineMediaTarget &&
+        item.afterBytes < item.beforeBytes &&
+        (item.reason === 'SOFT_LIMIT' || item.reason === 'HARD_LIMIT' || item.reason === 'TEXT_GC') &&
+        (item.reason !== 'SOFT_LIMIT' ||
+            item.beforeBytes > INLINE_MEDIA_POLICY.historicalInlineMediaTrigger) &&
+        (item.reason !== 'TEXT_GC' ||
+            item.beforeBytes > INLINE_MEDIA_POLICY.historicalInlineMediaTarget)
+        ? { reason: item.reason, state, beforeBytes: item.beforeBytes, afterBytes: item.afterBytes }
+        : undefined;
+}
+export function inlineMediaSource(message) {
+    return message.callId !== undefined
+        ? `tool:${message.callId}`
+        : message.metadata?.recordId !== undefined
+            ? `input:${message.metadata.recordId}`
+            : message;
+}
+/** GC may advance only a durable, already-considered source prefix. */
+export function inlineMediaGcAnchored(records, media) {
+    const history = inlineMediaHistory(records);
+    const positions = new Map();
+    const key = (cursor) => JSON.stringify([cursor?.sourceId, cursor?.imageIndex]);
+    for (const cursor of history.cursors) {
+        const identity = key({ sourceId: cursor.sourceId, imageIndex: cursor.imageIndex });
+        if (!positions.has(identity))
+            positions.set(identity, { index: positions.size, rollout: cursor.rollout });
+    }
+    const evicted = positions.get(key(media.state.evictedThrough));
+    const considered = positions.get(key(media.state.consideredThrough));
+    const previous = positions.get(key(history.state?.evictedThrough));
+    return (evicted !== undefined &&
+        considered !== undefined &&
+        key(media.state.consideredThrough) === key(history.state?.consideredThrough) &&
+        evicted.index <= considered.index &&
+        evicted.index > (previous?.index ?? -1) &&
+        (media.reason === 'HARD_LIMIT' || history.rollouts - evicted.rollout >= 2));
+}
+export function inlineMediaBytes(image) {
+    const bytes = image.dataBase64 !== undefined
+        ? image.dataBase64.length
+        : image.byteSize !== undefined
+            ? 4 * Math.ceil(image.byteSize / 3)
+            : undefined;
+    if (bytes === undefined)
+        throw new MarAgentError('MAR_AGENT_SESSION_CORRUPT', 'Resource size is unavailable.');
+    return bytes + Buffer.byteLength(`data:${image.mimeType};base64,`);
+}
+export function inlineMediaLimit() {
+    throw new MarAgentError('MAR_AGENT_INLINE_MEDIA_LIMIT', 'Inline images exceed the 12 MiB request limit. Reduce this image batch or use view_image with resize or region before retrying.');
+}
+/** Final encoding guard; URL-only images do not consume the inline budget. */
+export function assertInlineMediaBudget(request) {
+    let total = 0;
+    for (const message of request.messages)
+        for (const image of message.images ?? [])
+            if (image.dataBase64 !== undefined)
+                total += inlineMediaBytes(image);
+    for (const image of request.images ?? [])
+        if (image.dataBase64 !== undefined)
+            total += inlineMediaBytes(image);
+    if (total > INLINE_MEDIA_POLICY.requestInlineMediaHardLimit)
+        inlineMediaLimit();
+}
+export function parseInlineMediaState(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const state = value;
+    const cursor = (value) => {
+        if (!value || typeof value !== 'object')
+            return false;
+        const item = value;
+        return (typeof item.sourceId === 'string' &&
+            item.sourceId.length > 0 &&
+            item.sourceId.length <= 256 &&
+            Number.isSafeInteger(item.imageIndex) &&
+            item.imageIndex >= 0);
+    };
+    if (state.version !== 1 ||
+        (state.consideredThrough !== undefined && !cursor(state.consideredThrough)) ||
+        (state.evictedThrough !== undefined && !cursor(state.evictedThrough)))
+        return undefined;
+    return structuredClone(state);
+}
+/** Recover ordering once at the lifecycle boundary, including GC-omitted sources. */
+export function inlineMediaHistory(records) {
+    const cursors = [];
+    let rollouts = 0;
+    let state;
+    const add = (sourceId, images) => {
+        if (!sourceId || !Array.isArray(images))
+            return;
+        for (let imageIndex = 0; imageIndex < images.length; imageIndex++)
+            cursors.push({ sourceId, imageIndex, rollout: rollouts });
+    };
+    for (const record of records) {
+        const payload = record.payload;
+        if (!payload || typeof payload !== 'object')
+            continue;
+        if (record.type === 'model.attempt' &&
+            payload.purpose === 'EXECUTION' &&
+            payload.state === 'SUCCEEDED')
+            rollouts++;
+        if (record.type === 'compact.completed') {
+            cursors.splice(0);
+            state = parseInlineMediaState(payload.inlineMediaState);
+            for (const item of (payload.retainedModelContext ?? [])) {
+                const applied = appliedInputRecord({ ...record, type: 'model.context', payload: item });
+                if (applied) {
+                    add(`input:${applied.recordId}`, applied.payload.images);
+                    continue;
+                }
+                const key = inlineMediaSource(item);
+                add(typeof key === 'string' ? key : undefined, item.images);
+            }
+        }
+        else if (record.type === 'resource.window') {
+            state = parseInlineMediaState(payload);
+        }
+        else if (record.type === 'context.gc.completed' && payload.inlineMedia !== undefined) {
+            const media = parseInlineMediaGc(payload.inlineMedia);
+            if (!media)
+                throw new MarAgentError('MAR_AGENT_SESSION_CORRUPT', 'Inline media GC state is invalid.');
+            state = media.state;
+        }
+        else if ((record.type === 'turn.user' || record.type === 'extension.input') &&
+            payload.deferred !== true) {
+            add(`input:${record.recordId}`, payload.images);
+        }
+        else if (record.type === 'model.context') {
+            const applied = appliedInputRecord(record);
+            if (applied) {
+                add(`input:${applied.recordId}`, applied.payload.images);
+                continue;
+            }
+            const key = typeof payload.inputRef === 'string'
+                ? `input:${payload.inputRef}`
+                : typeof payload.callId === 'string'
+                    ? `tool:${payload.callId}`
+                    : undefined;
+            add(key, payload.images);
+        }
+    }
+    return { cursors, rollouts, ...(state ? { state } : {}) };
+}

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

@@ -10,6 +10,7 @@ import type { SessionListInput, SessionSource, SessionTitleUpdateInput } from '.
 import type { CompactHistoryMessage, RestoredSessionInputImage, SessionExecutionState, SessionInputImage, SessionInputImageData, SessionInputImageMetadata, SessionRecord } from './types.js';
 export type { CompactHistoryMessage, CompactUserInput, RestoredSessionInputImage, SessionExecutionState, SessionInputImage, SessionInputImageData, SessionInputImageMetadata, SessionRecord } from './types.js';
 export type { CodeModeStateEntry } from '../../tools/code-mode/state.js';
+export type { SessionResource } from './resources.js';
 export type { TodoSnapshot, TodoItem } from '../../tools/contracts.js';
 export type { CodeToolCallRecord, CodeObservation } from '../../tools/code-mode/observations.js';
 export type { ModelMessage, ModelUsage, ModelInputMetadata, ModelTextBlock, ModelContextualBlock } from '../../model/contracts.js';
@@ -38,6 +39,7 @@ export interface SessionStoreCompactInput {
     summary: string;
     replacementHistory?: readonly CompactHistoryMessage[];
     retainedModelContext?: readonly ModelMessage[];
+    inlineMediaState?: import('../inline-media.js').InlineMediaState;
     pendingInputs?: readonly SessionRecord[];
     snapshotRecordId?: string;
     snapshotMessageCount?: number;
@@ -116,6 +118,15 @@ export interface SessionStore {
     }): Promise<SessionRecord>;
     commitContextGc(sessionId: string, draft: ContextGcCheckpointDraft, planningRecords?: readonly SessionRecord[]): Promise<SessionRecord>;
     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>;
     readInputImages(sessionId: string, value: unknown): Promise<RestoredSessionInputImage[]>;
     readInputImage(sessionId: string, input: {
         readonly sequence: number;

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

@@ -8,7 +8,7 @@ interface StagedSessionSegments {
     readonly segments: NonNullable<SessionMeta['segments']>;
 }
 export declare function stageSessionSegments(sessionDirectory: string, records: readonly SessionRecord[], operation?: 'rollback' | 'fork'): Promise<StagedSessionSegments>;
-export declare function stageUnreferencedImages(sessionDirectory: string, directoryName: 'input_images' | 'generated_images' | 'tool_results', retained: ReadonlySet<string>, transactionId: string): Promise<Array<{
+export declare function stageUnreferencedImages(sessionDirectory: string, directoryName: 'generated_images' | 'tool_results' | 'resources', retained: ReadonlySet<string>, transactionId: string): Promise<Array<{
     from: string;
     to: string;
     trash: string;

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

@@ -2,6 +2,7 @@ import { randomUUID } from 'node:crypto';
 import { open, readdir, rename, rm } from 'node:fs/promises';
 import { join } from 'node:path';
 import { MarAgentError } from '../../error.js';
+import { parseInlineMediaState } from '../inline-media.js';
 import { MAX_SEGMENT_BYTES } from './records.js';
 export async function renameIfExists(from, to) {
     try {
@@ -117,11 +118,32 @@ export function forkedPayload(type, value, sourceSessionId, targetSessionId, tit
     if (value === null || typeof value !== 'object' || Array.isArray(value))
         return value;
     const payload = { ...value };
+    const remapWindow = (value) => {
+        const state = parseInlineMediaState(value);
+        if (!state)
+            return value;
+        for (const cursor of [state.consideredThrough, state.evictedThrough]) {
+            if (!cursor?.sourceId.startsWith('input:'))
+                continue;
+            const target = identities.get(cursor.sourceId.slice(6));
+            if (!target)
+                throw new MarAgentError('MAR_AGENT_SESSION_CORRUPT', 'Fork media reference is missing.');
+            cursor.sourceId = `input:${target.recordId}`;
+        }
+        return state;
+    };
+    if (type === 'resource.window')
+        return remapWindow(payload);
     if (payload.sessionId === sourceSessionId)
         payload.sessionId = targetSessionId;
     const application = (input) => {
-        if (typeof input.inputRef !== 'string')
-            return input;
+        if (typeof input.inputRef !== 'string') {
+            const recordId = isObject(input.metadata) ? input.metadata.recordId : undefined;
+            const identity = typeof recordId === 'string' ? identities.get(recordId) : undefined;
+            return identity && isObject(input.metadata)
+                ? { ...input, metadata: { ...input.metadata, recordId: identity.recordId } }
+                : input;
+        }
         const identity = identities.get(input.inputRef);
         if (!identity)
             throw new MarAgentError('MAR_AGENT_SESSION_CORRUPT', 'Fork input reference is missing.');
@@ -136,6 +158,8 @@ export function forkedPayload(type, value, sourceSessionId, targetSessionId, tit
     if (type === 'model.context')
         return application(payload);
     if (type === 'compact.completed') {
+        if (payload.inlineMediaState)
+            payload.inlineMediaState = remapWindow(payload.inlineMediaState);
         if (Array.isArray(payload.retainedModelContext))
             payload.retainedModelContext = payload.retainedModelContext.map((item) => isObject(item) ? application(item) : item);
         if (Array.isArray(payload.pendingInputs))

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

@@ -1,4 +1,4 @@
-import type { SessionInputImage, SessionInputImageMetadata, SessionRecord } from './types.js';
+import type { SessionRecord } from './types.js';
 export declare const MAX_INPUT_IMAGES = 5;
 export declare function generatedImageFileNames(records: readonly SessionRecord[]): readonly string[];
 export declare function copyGeneratedImages(sourceSessionDirectory: string, targetSessionDirectory: string, fileNames: readonly string[]): Promise<void>;
@@ -8,14 +8,12 @@ interface InputImageReference {
     readonly mimeType: string;
     readonly byteSize: number;
     readonly sha256: string;
+    readonly resourceId?: string;
+    readonly url?: string;
+    readonly urlExpiresAt?: number;
 }
-export declare function inputImageReferencesFromRecords(records: readonly SessionRecord[]): readonly InputImageReference[];
 export declare function inputImageReferences(value: unknown): InputImageReference[];
 export declare function inputImageReference(value: unknown): InputImageReference | undefined;
 export declare function validInputImageFileName(fileName: string): boolean;
 export declare function readInputImageBytes(directory: string, reference: InputImageReference): Promise<Buffer>;
-export declare function copyInputImages(sourceSessionDirectory: string, targetSessionDirectory: string, references: readonly InputImageReference[]): Promise<void>;
-/** A pending marker is removable only after the committed JSONL references are checked. */
-export declare function recoverPendingInputImages(sessionDirectory: string, readHistory: () => Promise<SessionRecord[]>): Promise<void>;
-export declare function writeInputImages(directory: string, images: readonly SessionInputImage[]): Promise<SessionInputImageMetadata[]>;
 export {};

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

@@ -1,8 +1,9 @@
-import { createHash, randomUUID } from 'node:crypto';
+import { createHash } from 'node:crypto';
 import { constants } from 'node:fs';
-import { copyFile, lstat, mkdir, open, readdir, rename, rm, writeFile } from 'node:fs/promises';
+import { copyFile, lstat, mkdir, open } from 'node:fs/promises';
 import { basename, join } from 'node:path';
 import { MarAgentError } from '../../error.js';
+import { isModelImageUrl } from '../../model/image.js';
 export const MAX_INPUT_IMAGES = 5;
 const MAX_INPUT_IMAGE_BYTES = 5 * 1024 * 1024;
 const MAX_INPUT_IMAGES_BYTES = 10 * 1024 * 1024;
@@ -36,23 +37,6 @@ export async function copyGeneratedImages(sourceSessionDirectory, targetSessionD
     for (const fileName of fileNames)
         await copyFile(join(source, fileName), join(target, fileName));
 }
-export function inputImageReferencesFromRecords(records) {
-    const references = new Map();
-    for (const record of records) {
-        if (record.type !== 'turn.user' || !isObject(record.payload))
-            continue;
-        for (const reference of inputImageReferences(record.payload.images)) {
-            const existing = references.get(reference.fileName);
-            if (existing !== undefined &&
-                (existing.mimeType !== reference.mimeType ||
-                    existing.byteSize !== reference.byteSize ||
-                    existing.sha256 !== reference.sha256))
-                throw corruptInputImageReference();
-            references.set(reference.fileName, reference);
-        }
-    }
-    return [...references.values()];
-}
 export function inputImageReferences(value) {
     if (!Array.isArray(value))
         return [];
@@ -82,14 +66,27 @@ export function inputImageReference(value) {
         typeof value.fileName !== 'string' ||
         !validInputImageFileName(value.fileName) ||
         typeof value.sha256 !== 'string' ||
-        !/^[a-f0-9]{64}$/u.test(value.sha256))
+        !/^[a-f0-9]{64}$/u.test(value.sha256) ||
+        (value.resourceId !== undefined &&
+            (typeof value.resourceId !== 'string' ||
+                !/^[a-f0-9]{64}$/u.test(value.resourceId) ||
+                value.fileName !== `${value.resourceId}.bin`)) ||
+        (value.url !== undefined && !isModelImageUrl(value.url)) ||
+        (value.urlExpiresAt !== undefined &&
+            (typeof value.urlExpiresAt !== 'number' ||
+                !Number.isSafeInteger(value.urlExpiresAt) ||
+                value.urlExpiresAt <= 0)) ||
+        (value.urlExpiresAt !== undefined && value.url === undefined))
         throw corruptInputImageReference();
     return {
         name: value.name,
         fileName: value.fileName,
         mimeType: value.mimeType,
         byteSize: value.byteSize,
-        sha256: value.sha256
+        sha256: value.sha256,
+        ...(typeof value.resourceId === 'string' ? { resourceId: value.resourceId } : {}),
+        ...(value.url === undefined ? {} : { url: value.url }),
+        ...(typeof value.urlExpiresAt === 'number' ? { urlExpiresAt: value.urlExpiresAt } : {})
     };
 }
 export function validInputImageFileName(fileName) {
@@ -148,101 +145,11 @@ async function readExactBytes(handle, byteSize) {
         throw corruptInputImageReference();
     return data;
 }
-export async function copyInputImages(sourceSessionDirectory, targetSessionDirectory, references) {
-    if (references.length === 0)
-        return;
-    const source = join(sourceSessionDirectory, 'input_images');
-    const target = join(targetSessionDirectory, 'input_images');
-    await mkdir(target, { recursive: true, mode: 0o700 });
-    for (const reference of references) {
-        const data = await readInputImageBytes(source, reference);
-        await writeFile(join(target, reference.fileName), data, { mode: 0o600, flag: 'wx' });
-    }
-}
 function corruptInputImageReference(cause) {
     return new MarAgentError('MAR_AGENT_SESSION_CORRUPT', 'Session input image is corrupt.', {
         ...(cause === undefined ? {} : { cause })
     });
 }
-/** A pending marker is removable only after the committed JSONL references are checked. */
-export async function recoverPendingInputImages(sessionDirectory, readHistory) {
-    const directory = join(sessionDirectory, 'input_images');
-    let names;
-    try {
-        names = await readdir(directory);
-    }
-    catch (error) {
-        if (error.code === 'ENOENT')
-            return;
-        throw error;
-    }
-    const pending = names.filter((name) => /^\.[0-9a-f-]{36}\.bin\.pending$/iu.test(name));
-    const temporary = names.filter((name) => /^\.[0-9a-f-]{36}\.bin\.[0-9a-f-]{36}\.tmp$/iu.test(name));
-    if (pending.length === 0 && temporary.length === 0)
-        return;
-    const referenced = pending.length === 0
-        ? new Set()
-        : new Set(inputImageReferencesFromRecords(await readHistory()).map((image) => image.fileName));
-    for (const name of pending) {
-        const fileName = name.slice(1, -'.pending'.length);
-        if (!referenced.has(fileName))
-            await rm(join(directory, fileName), { force: true });
-        await rm(join(directory, name), { force: true });
-    }
-    for (const name of temporary)
-        await rm(join(directory, name), { force: true });
-}
-export async function writeInputImages(directory, images) {
-    await mkdir(directory, { recursive: true, mode: 0o700 });
-    const written = [];
-    const pending = [];
-    let temporary;
-    let totalBytes = 0;
-    try {
-        const metadata = [];
-        for (const image of images) {
-            if (!INPUT_IMAGE_MIME_TYPES.has(image.mimeType))
-                throw new MarAgentError('MAR_AGENT_INPUT_CAPABILITY_UNSUPPORTED', 'Image input MIME type is unsupported.');
-            const data = Buffer.from(image.dataBase64, 'base64');
-            totalBytes += data.byteLength;
-            if (data.byteLength === 0 ||
-                data.byteLength > MAX_INPUT_IMAGE_BYTES ||
-                totalBytes > MAX_INPUT_IMAGES_BYTES)
-                throw new MarAgentError('MAR_AGENT_HOST_LIMIT_EXCEEDED', 'Image input exceeds the supported size limit.');
-            const fileName = `${randomUUID()}.bin`;
-            temporary = join(directory, `.${fileName}.${randomUUID()}.tmp`);
-            const handle = await open(temporary, 'wx', 0o600);
-            try {
-                await handle.writeFile(data);
-                await handle.sync();
-            }
-            finally {
-                await handle.close();
-            }
-            const marker = join(directory, `.${fileName}.pending`);
-            await writeFile(marker, '', { mode: 0o600, flag: 'wx', flush: true });
-            pending.push(marker);
-            await rename(temporary, join(directory, fileName));
-            temporary = undefined;
-            written.push(fileName);
-            metadata.push({
-                name: image.name,
-                mimeType: image.mimeType,
-                byteSize: data.byteLength,
-                fileName,
-                sha256: createHash('sha256').update(data).digest('hex')
-            });
-        }
-        return metadata;
-    }
-    catch (error) {
-        if (temporary !== undefined)
-            await rm(temporary, { force: true }).catch(() => undefined);
-        await Promise.all(pending.map((marker) => rm(marker, { force: true })));
-        await Promise.all(written.map((fileName) => rm(join(directory, fileName), { force: true }).catch(() => undefined)));
-        throw error;
-    }
-}
 function isObject(value) {
     return value !== null && typeof value === 'object' && !Array.isArray(value);
 }

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

@@ -19,6 +19,15 @@ export declare class JsonlSessionStore implements SessionStore {
     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;