@myagentroam/agent 0.11.33 → 0.11.34

package/dist/sdk/model-runtime.js

@@ -0,0 +1,91 @@
+import { AgentError } from '../error.js';
+import { normalizeRuntimeModelConfiguration, resolveModelDefaultReasoningEffort } from '../model/configuration.js';
+import { observeModelProgress } from '../runtime/model-progress.js';
+import { projectModelRequest } from './model-input-projection.js';
+export function resolveAgentModels(configurations, requestedDefaultModelId) {
+    const configuredModels = configurations.map((input) => {
+        const model = normalizeRuntimeModelConfiguration(input);
+        return { ...model, defaultReasoningEffort: resolveModelDefaultReasoningEffort(model) };
+    });
+    const credentialProviders = new Set();
+    for (const model of configuredModels) {
+        if (model.credentialProvider !== undefined)
+            credentialProviders.add(model.credentialProvider);
+    }
+    const models = new Map(configuredModels.filter((model) => model.enabled).map((model) => [model.id, model]));
+    if (models.size === 0)
+        throw new AgentError('MAR_AGENT_MODEL_CONFIG_INVALID', 'At least one enabled model is required.');
+    const defaultModelId = requestedDefaultModelId ??
+        [...models.values()].find((model) => model.conversationModel !== false)?.id;
+    if (!defaultModelId ||
+        !models.has(defaultModelId) ||
+        models.get(defaultModelId).conversationModel === false)
+        throw new AgentError('MAR_AGENT_MODEL_CONFIG_INVALID', 'Default conversation model is unavailable.');
+    return { models, defaultModelId, credentialProviders };
+}
+export function createModelTurnSession(adapter) {
+    const turn = adapter.createTurnSession?.() ?? {
+        start: (request, signal) => adapter.start(request, signal),
+        close: async () => undefined
+    };
+    return {
+        async *start(request, signal) {
+            const before = request.retryState?.attempts;
+            try {
+                yield* observeModelProgress((requestSignal) => turn.start(projectModelRequest(request), requestSignal), signal);
+            }
+            finally {
+                // Custom adapters may not participate in the shared attempt accounting.
+                if (request.retryState && request.retryState.attempts === before)
+                    request.retryState.attempts++;
+            }
+        },
+        resetContinuation: () => turn.resetContinuation?.(),
+        continuationInputCount: () => turn.continuationInputCount?.() ?? 0,
+        commitContinuationInput: (count) => turn.commitContinuationInput?.(count),
+        close: () => turn.close()
+    };
+}
+/** Owns only one Execution's model turn and explicitly transferred adapters. */
+export function createExecutionModelResources(activeAdapters) {
+    let turn;
+    const ownedAdapters = new Set();
+    return {
+        openTurn(adapter, ownsAdapter) {
+            if (ownsAdapter) {
+                ownedAdapters.add(adapter);
+                activeAdapters.add(adapter);
+            }
+            turn = createModelTurnSession(adapter);
+            return turn;
+        },
+        async close() {
+            try {
+                await turn?.close();
+            }
+            catch {
+                // Model cleanup must not replace the Execution result.
+            }
+            try {
+                await closeModelAdapters(ownedAdapters);
+            }
+            catch {
+                // Model cleanup must not replace the Execution result.
+            }
+            finally {
+                for (const adapter of ownedAdapters)
+                    activeAdapters.delete(adapter);
+            }
+        }
+    };
+}
+export async function closeModelAdapters(adapters) {
+    const results = await Promise.allSettled([...new Set(adapters)].flatMap((adapter) => adapter.close === undefined ? [] : [Promise.resolve().then(() => adapter.close())]));
+    const failure = results.find((result) => result.status === 'rejected');
+    if (failure !== undefined)
+        throw failure.reason;
+}
+export function addModelCredentialProviders(target, configuration) {
+    if (configuration.credentialProvider !== undefined)
+        target.add(configuration.credentialProvider);
+}

package/dist/sdk/native-steer.d.ts

@@ -0,0 +1,20 @@
+import type { ExtensionOperationContext } from '../extensions/operation.js';
+import { type ExtensionPromptInput, type ExtensionPromptResult } from '../extensions/prompt-input.js';
+import type { SessionInputCoordinator } from '../extensions/session-input.js';
+import type { SessionRecord } from '../session/store/index.js';
+import type { SteerInput, SteerResult } from './types.js';
+/** Admission reserves the existing FIFO before any asynchronous Hook or writer work. */
+export declare function createNativeSteer(input: {
+    readonly executionId: string;
+    readonly inputs: SessionInputCoordinator;
+    readonly signal: AbortSignal;
+    isOpen(): boolean;
+    operation<T>(action: (call: ExtensionOperationContext) => T): T;
+    admit(content: ExtensionPromptInput, call: ExtensionOperationContext, write: (content: ExtensionPromptInput, call: ExtensionOperationContext) => Promise<ExtensionPromptResult>): Promise<unknown>;
+    receive(content: ExtensionPromptInput, clientMessageId: string, call: ExtensionOperationContext): Promise<SessionRecord>;
+    notify(entry: Extract<SteerResult, {
+        status: 'accepted';
+    }>['entry']): Promise<unknown>;
+    diagnose(): void;
+    wake(): void;
+}): (request: SteerInput) => Promise<SteerResult>;

package/dist/sdk/native-steer.js

@@ -0,0 +1,84 @@
+import { AgentError } from '../error.js';
+import { captureCorePromptInput } from '../extensions/prompt-input.js';
+import { imageMetadata } from '../session/catalog.js';
+/** Admission reserves the existing FIFO before any asynchronous Hook or writer work. */
+export function createNativeSteer(input) {
+    const retries = new Map();
+    let admissionTail = Promise.resolve();
+    return async (request) => {
+        if (request.expectedExecutionId !== input.executionId)
+            return Promise.resolve({ status: 'notAccepted' });
+        const previous = retries.get(request.clientMessageId);
+        if (previous)
+            return previous;
+        if (!input.isOpen() || input.signal.aborted || input.inputs.hasIdleBarrier)
+            return Promise.resolve({ status: 'notAccepted' });
+        if (typeof request.clientMessageId !== 'string' ||
+            !request.clientMessageId.trim() ||
+            request.clientMessageId.length > 512)
+            return Promise.reject(new AgentError('MAR_AGENT_SESSION_INPUT_INVALID', 'A stable client message ID is required.'));
+        const content = captureCorePromptInput({
+            text: request.prompt,
+            ...(request.modelText === undefined ? {} : { modelText: request.modelText }),
+            ...(request.images === undefined ? {} : { images: request.images })
+        });
+        const result = Promise.withResolvers();
+        const ready = Promise.withResolvers();
+        const entry = input.operation((call) => input.inputs.accept({ kind: 'submit', input: content }, call, (request, effective, next) => next(request, effective), 'accepted'));
+        entry.nativeSteer = { ready: ready.promise };
+        const aborted = () => ready.resolve();
+        input.signal.addEventListener('abort', aborted, { once: true });
+        let committed = false;
+        const admission = admissionTail
+            .catch(() => undefined)
+            .then(() => input.operation((call) => input.admit(content, call, async (actual, effective) => {
+            if (committed)
+                return {};
+            effective.signal.throwIfAborted();
+            if (!input.isOpen()) {
+                result.resolve({ status: 'notAccepted' });
+                return {};
+            }
+            const record = await input.receive(actual, request.clientMessageId, effective);
+            committed = true;
+            entry.nativeSteer.recordId = record.recordId;
+            const payload = record.payload;
+            const images = imageMetadata(payload.images);
+            const historyEntry = {
+                kind: 'user',
+                recordId: record.recordId,
+                sequence: record.sequence,
+                timestamp: record.timestamp,
+                sessionId: record.sessionId,
+                executionId: record.executionId,
+                turnId: record.turnId,
+                text: payload.prompt,
+                clientMessageId: request.clientMessageId,
+                ...(images.length ? { images } : {})
+            };
+            // Neither Hook post-processing nor a failed observer can revoke the writer's receipt.
+            void input.notify(historyEntry).catch(() => input.diagnose());
+            ready.resolve();
+            result.resolve({ status: 'accepted', entry: historyEntry });
+            input.wake();
+            return {};
+        })));
+        void admission
+            .then(() => {
+            if (!committed)
+                result.resolve({ status: 'handled' });
+        }, (error) => {
+            if (!committed)
+                result.reject(error);
+            else
+                input.diagnose();
+        })
+            .finally(() => {
+            ready.resolve();
+            input.signal.removeEventListener('abort', aborted);
+        });
+        admissionTail = result.promise;
+        retries.set(request.clientMessageId, result.promise);
+        return result.promise;
+    };
+}

package/dist/sdk/request-preparation.d.ts

@@ -0,0 +1,9 @@
+import type { ClientToolDefinition } from '../tools/contracts.js';
+import type { SessionModelMessage as ModelMessage } from '../session/model-request.js';
+import type { SessionModelRequest as ModelRequest } from '../session/model-request.js';
+import type { AgentModelConfiguration } from '../model/configuration.js';
+import { type ContextualWorldState } from '../runtime/context/world-state.js';
+/** Assemble captured round values only. Admission, Hooks and publication belong to Session. */
+export declare function prepareSessionModelRequest(candidate: ModelRequest, model: Pick<AgentModelConfiguration, 'protocol' | 'inputCapabilities'>, entries: ContextualWorldState['entries'], residentTools: readonly ClientToolDefinition[], autoPermission: boolean): ModelRequest;
+/** The actual candidate and current Session view share the same side-effect-free projection. */
+export declare function projectSessionRequestMessages(messages: readonly ModelMessage[], entries: ContextualWorldState['entries'], supportsImages: boolean, codeMode: boolean, autoPermission?: boolean): ModelMessage[];

package/dist/sdk/resource-input.d.ts

@@ -0,0 +1,33 @@
+import type { SessionModelMessage as ModelMessage } from '../session/model-request.js';
+import type { SessionModelRequest as ModelRequest } from '../session/model-request.js';
+import { type ModelImage } from '../model/image.js';
+import type { SessionStore } from '../session/store/contracts.js';
+import type { SessionRecord } from '../session/record-contract.js';
+import { type InlineMediaGcCandidate, type InlineMediaState } from '../session/inline-media.js';
+interface Options {
+    records?: readonly SessionRecord[];
+    persist?: (state: InlineMediaState) => Promise<void>;
+}
+/** SDK-owned ordered visual window; durable image references are never rewritten. */
+export declare class ResourceInputProjection {
+    #private;
+    private readonly useResourceUrl;
+    private readonly store;
+    private readonly sessionId;
+    private readonly options;
+    constructor(useResourceUrl: boolean, store: Pick<SessionStore, 'readResource'>, sessionId: string, history: readonly ModelMessage[], options?: Options);
+    observe(messages: readonly ModelMessage[]): void;
+    /** Called only at an explicit context replacement, never as a history diff detector. */
+    replace(messages: readonly ModelMessage[]): void;
+    hasPendingImages(messages: readonly ModelMessage[]): boolean;
+    /** Reference-only view shared by GC; no byte loading or new eviction decisions. */
+    historyView(messages: readonly ModelMessage[]): ModelMessage[];
+    checkpoint(messages?: readonly ModelMessage[]): InlineMediaState;
+    prepare(request: ModelRequest, mirroredImages?: readonly ModelImage[], canonicalMessages?: readonly ModelMessage[]): Promise<ModelRequest>;
+    complete(request: ModelRequest): Promise<void>;
+    /** Propose a cursor; only the unified GC checkpoint may adopt it. */
+    gcCandidate(request?: ModelRequest, mirroredImages?: readonly ModelImage[]): Promise<InlineMediaGcCandidate | undefined>;
+    adoptGc(state: InlineMediaState | undefined): void;
+    releaseBytes(): void;
+}
+export {};

package/dist/sdk/resource-input.js

@@ -0,0 +1,402 @@
+import { inlineMediaBytes, inlineMediaLimit } from '../model/inline-media-budget.js';
+import { isDeepStrictEqual } from 'node:util';
+import { AgentError } from '../error.js';
+import { isModelImageUrl } from '../model/image.js';
+import { observationImages, renderObservationResult, selectObservationImages } from '../session/code-observation-projection.js';
+import { INLINE_MEDIA_POLICY as policy, inlineMediaHistory, inlineMediaSource } from '../session/inline-media.js';
+function releasedImageNotice(message, indices, unavailable) {
+    return indices
+        .map((index) => {
+        if (unavailable?.has(index))
+            return 'Image unavailable; omitted from context.';
+        const resourceId = message.images?.[index]?.resourceId;
+        const hint = resourceId
+            ? ` Reopen with view_image(${JSON.stringify({ resourceId })}) if needed.`
+            : '';
+        return `<mar_context_gc kind="image">Image released.${hint}</mar_context_gc>`;
+    })
+        .join('\n');
+}
+function projectRetainedImages(message, images, removed, unavailable) {
+    if (!removed.size)
+        return { ...message, images };
+    if (message.observations) {
+        const observations = message.observations.map((observation) => {
+            const removedIndices = observationImages(observation).filter((index) => removed.has(index));
+            if (!removedIndices.length)
+                return observation;
+            const notice = releasedImageNotice(message, removedIndices, unavailable);
+            return observation.type === 'tool_result'
+                ? {
+                    ...observation,
+                    result: { ...observation.result, content: `${observation.result.content}\n${notice}` }
+                }
+                : { ...observation, value: `${observation.value}\n${notice}` };
+        });
+        const selected = selectObservationImages(observations, images);
+        return {
+            ...message,
+            ...selected,
+            content: renderObservationResult(selected.observations, message.content)
+        };
+    }
+    const notice = releasedImageNotice(message, [...removed], unavailable);
+    return {
+        ...message,
+        images: images.filter(Boolean),
+        content: `${message.content}\n${notice}`,
+        ...(message.textBlocks ? { textBlocks: [...message.textBlocks, { text: notice }] } : {})
+    };
+}
+/** SDK-owned ordered visual window; durable image references are never rewritten. */
+export class ResourceInputProjection {
+    useResourceUrl;
+    store;
+    sessionId;
+    options;
+    #entries = [];
+    #sources = new Map();
+    #candidates = new WeakMap();
+    #resourceReads = new Map();
+    #cachedBytes = 0;
+    #considered = -1;
+    #rollout = 0;
+    #evicted = -1;
+    constructor(useResourceUrl, store, sessionId, history, options = {}) {
+        this.useResourceUrl = useResourceUrl;
+        this.store = store;
+        this.sessionId = sessionId;
+        this.options = options;
+        const restored = inlineMediaHistory(options.records ?? []);
+        this.#rollout = restored.rollouts;
+        for (const cursor of restored.cursors)
+            this.#entries[this.#entry(cursor.sourceId, cursor.imageIndex)].rollout = cursor.rollout;
+        this.observe(history);
+        if (restored.state) {
+            this.#considered = this.#position(restored.state.consideredThrough);
+            this.#evicted = this.#position(restored.state.evictedThrough);
+        }
+        else if (options.records === undefined)
+            this.#considered = this.#entries.length - 1;
+    }
+    #entry(source, imageIndex) {
+        let positions = this.#sources.get(source);
+        if (!positions)
+            this.#sources.set(source, (positions = []));
+        let position = positions[imageIndex];
+        if (position === undefined) {
+            position = this.#entries.length;
+            positions[imageIndex] = position;
+            this.#entries.push({ source, imageIndex, active: false, rollout: this.#rollout });
+        }
+        return position;
+    }
+    #position(cursor) {
+        if (!cursor)
+            return -1;
+        const position = this.#sources.get(cursor.sourceId)?.[cursor.imageIndex];
+        if (position === undefined)
+            throw new AgentError('MAR_AGENT_SESSION_CORRUPT', 'Inline media boundary is missing.');
+        return position;
+    }
+    observe(messages) {
+        for (const message of messages)
+            for (const [index, image] of (message.images ?? []).entries()) {
+                const entry = this.#entries[this.#entry(inlineMediaSource(message), index)];
+                if (entry.image && !isDeepStrictEqual(entry.image, image))
+                    delete entry.unavailable;
+                entry.image = image;
+                entry.active = true;
+            }
+    }
+    /** Called only at an explicit context replacement, never as a history diff detector. */
+    replace(messages) {
+        this.releaseBytes();
+        for (const entry of this.#entries) {
+            entry.active = false;
+            delete entry.image;
+        }
+        this.observe(messages);
+    }
+    hasPendingImages(messages) {
+        return messages.some((message) => (message.images ?? []).some((_, index) => {
+            const position = this.#sources.get(inlineMediaSource(message))?.[index];
+            return position === undefined || position > this.#considered;
+        }));
+    }
+    /** Reference-only view shared by GC; no byte loading or new eviction decisions. */
+    historyView(messages) {
+        return this.#historyView(messages, this.#evicted);
+    }
+    #historyView(messages, evicted, fromEvicted = -1) {
+        return messages.map((message) => {
+            const positions = this.#sources
+                .get(inlineMediaSource(message))
+                ?.filter((position) => position > fromEvicted);
+            const images = message.images ??
+                positions?.flatMap((position) => {
+                    const entry = this.#entries[position];
+                    return entry.active && entry.image ? [entry.image] : [];
+                });
+            if (!images?.length)
+                return message;
+            const removed = new Set();
+            const unavailable = new Set();
+            const retained = [];
+            images.forEach((image, index) => {
+                const position = positions?.[index];
+                const entry = position === undefined ? undefined : this.#entries[position];
+                if (entry?.unavailable && isDeepStrictEqual(entry.image, image)) {
+                    removed.add(index);
+                    unavailable.add(index);
+                }
+                else if (!this.useResourceUrl &&
+                    positions?.[index] !== undefined &&
+                    positions[index] <= evicted)
+                    removed.add(index);
+                else
+                    retained[index] = image;
+            });
+            return projectRetainedImages({ ...message, images }, retained, removed, unavailable);
+        });
+    }
+    checkpoint(messages) {
+        const retained = messages && new Set(messages.map(inlineMediaSource));
+        const cursor = (through) => {
+            for (let index = through; index >= 0; index--) {
+                const entry = this.#entries[index];
+                if (typeof entry.source === 'string' && (!retained || retained.has(entry.source)))
+                    return { sourceId: entry.source, imageIndex: entry.imageIndex };
+            }
+            return undefined;
+        };
+        const consideredThrough = cursor(this.#considered);
+        const evictedThrough = cursor(this.#evicted);
+        return {
+            version: 1,
+            ...(consideredThrough ? { consideredThrough } : {}),
+            ...(evictedThrough ? { evictedThrough } : {})
+        };
+    }
+    async prepare(request, mirroredImages = [], canonicalMessages = request.messages) {
+        this.observe(canonicalMessages);
+        const through = this.#entries.length - 1;
+        const cached = new Map();
+        const project = (image, entry) => {
+            const key = entry && isDeepStrictEqual(entry.image, image) ? entry : image;
+            let value = cached.get(key);
+            if (!value)
+                cached.set(key, (value = this.#project(image, entry)));
+            return value;
+        };
+        const top = (request.images ?? []).filter((image) => !mirroredImages.some((mirror) => isDeepStrictEqual(image, mirror)));
+        const evicted = this.#evicted;
+        const messages = await Promise.all(request.messages.map(async (message) => {
+            if (!message.images?.length)
+                return message;
+            const removed = new Set();
+            const unavailable = new Set();
+            const images = [];
+            await Promise.all(message.images.map(async (image, index) => {
+                const position = this.#sources.get(inlineMediaSource(message))?.[index];
+                const entry = position === undefined ? undefined : this.#entries[position];
+                const original = entry?.image;
+                if (!this.useResourceUrl &&
+                    position !== undefined &&
+                    position <= evicted &&
+                    isDeepStrictEqual(original, image))
+                    removed.add(index);
+                else {
+                    const projected = await project(image, entry);
+                    if (projected)
+                        images[index] = projected;
+                    else {
+                        removed.add(index);
+                        unavailable.add(index);
+                    }
+                }
+            }));
+            return projectRetainedImages(message, images, removed, unavailable);
+        }));
+        const { images: _topImages, ...retained } = request;
+        const images = (await Promise.all(top.map((image) => project(image)))).filter((image) => image !== undefined);
+        const result = { ...retained, messages, ...(images.length ? { images } : {}) };
+        this.#candidates.set(result.messages, through);
+        return result;
+    }
+    async complete(request) {
+        const candidate = this.#candidates.get(request.messages);
+        if (candidate === undefined)
+            return;
+        this.#candidates.delete(request.messages);
+        this.#rollout++;
+        const considered = Math.max(this.#considered, candidate);
+        if (considered === this.#considered)
+            return;
+        const before = this.#considered;
+        this.#considered = considered;
+        try {
+            await this.options.persist?.(this.checkpoint());
+        }
+        catch (error) {
+            this.#considered = before;
+            this.#rollout--;
+            throw error;
+        }
+    }
+    /** Propose a cursor; only the unified GC checkpoint may adopt it. */
+    async gcCandidate(request, mirroredImages = []) {
+        if (this.useResourceUrl)
+            return undefined;
+        const size = async (image, entry) => {
+            if (entry?.unavailable && isDeepStrictEqual(entry.image, image))
+                return 0;
+            const sized = image.byteSize !== undefined || image.dataBase64 !== undefined
+                ? image
+                : await this.#project(image, entry);
+            return sized ? inlineMediaBytes(sized) : 0;
+        };
+        const actualSize = async (image, entry) => {
+            const projected = await this.#project(image, entry);
+            return projected ? inlineMediaBytes(projected) : 0;
+        };
+        const history = await Promise.all(this.#entries.map(async (entry, index) => ({
+            index,
+            bytes: entry.active && entry.image && index > this.#evicted && index <= this.#considered
+                ? await size(entry.image, entry)
+                : 0
+        })));
+        let beforeBytes = history.reduce((sum, entry) => sum + entry.bytes, 0);
+        let freshBytes = 0;
+        let requestBytes = 0;
+        const requestHistory = new Map();
+        if (request) {
+            for (const message of request.messages)
+                for (const [index, image] of (message.images ?? []).entries()) {
+                    const position = this.#sources.get(inlineMediaSource(message))?.[index];
+                    const entry = position === undefined ? undefined : this.#entries[position];
+                    const original = entry && isDeepStrictEqual(entry.image, image);
+                    if (original && position <= this.#evicted)
+                        continue;
+                    const bytes = await actualSize(image, entry);
+                    requestBytes += bytes;
+                    if (original && position <= this.#considered) {
+                        requestHistory.set(position, (requestHistory.get(position) ?? 0) + bytes);
+                        history[position].bytes = bytes;
+                    }
+                    else
+                        freshBytes += bytes;
+                }
+            for (const image of request.images ?? []) {
+                if (mirroredImages.some((mirror) => isDeepStrictEqual(image, mirror)))
+                    continue;
+                const bytes = await actualSize(image);
+                freshBytes += bytes;
+                requestBytes += bytes;
+            }
+            beforeBytes = history.reduce((sum, item) => sum + item.bytes, 0);
+            if (freshBytes > policy.requestInlineMediaHardLimit)
+                inlineMediaLimit();
+        }
+        const hard = requestBytes > policy.requestInlineMediaHardLimit;
+        if (!hard && beforeBytes <= policy.historicalInlineMediaTarget)
+            return undefined;
+        const target = hard
+            ? Math.max(0, policy.historicalInlineMediaTarget - freshBytes)
+            : policy.historicalInlineMediaTarget;
+        let afterBytes = beforeBytes;
+        let evicted = this.#evicted;
+        for (const item of history) {
+            if (afterBytes <= target && (!hard || requestBytes <= policy.requestInlineMediaHardLimit))
+                break;
+            if (!item.bytes)
+                continue;
+            if (!hard && this.#rollout - this.#entries[item.index].rollout < 2)
+                break;
+            afterBytes -= item.bytes;
+            requestBytes -= requestHistory.get(item.index) ?? 0;
+            evicted = item.index;
+        }
+        if (afterBytes > target || (hard && requestBytes > policy.requestInlineMediaHardLimit))
+            return undefined;
+        const entry = this.#entries[evicted];
+        if (!entry || typeof entry.source !== 'string' || evicted <= this.#evicted)
+            return undefined;
+        return {
+            reason: hard
+                ? 'HARD_LIMIT'
+                : beforeBytes > policy.historicalInlineMediaTrigger
+                    ? 'SOFT_LIMIT'
+                    : 'TEXT_GC',
+            state: {
+                ...this.checkpoint(),
+                evictedThrough: { sourceId: entry.source, imageIndex: entry.imageIndex }
+            },
+            beforeBytes,
+            afterBytes,
+            project: (messages) => this.#historyView(messages, evicted, this.#evicted)
+        };
+    }
+    adoptGc(state) {
+        if (state) {
+            this.#evicted = this.#position(state.evictedThrough);
+            this.releaseBytes();
+        }
+    }
+    releaseBytes() {
+        this.#resourceReads.clear();
+        this.#cachedBytes = 0;
+    }
+    #readBytes(resourceId) {
+        const cached = this.#resourceReads.get(resourceId);
+        if (cached)
+            return cached;
+        const pending = this.store.readResource(this.sessionId, resourceId).then((resource) => {
+            if (this.#resourceReads.get(resourceId) === pending) {
+                const bytes = resource?.dataBase64 ? inlineMediaBytes(resource) : 0;
+                if (!bytes || this.#cachedBytes + bytes > policy.requestInlineMediaHardLimit)
+                    this.#resourceReads.delete(resourceId);
+                else
+                    this.#cachedBytes += bytes;
+            }
+            return resource;
+        }, (error) => {
+            if (this.#resourceReads.get(resourceId) === pending)
+                this.#resourceReads.delete(resourceId);
+            throw error;
+        });
+        this.#resourceReads.set(resourceId, pending);
+        return pending;
+    }
+    async #project(image, entry) {
+        const original = entry && isDeepStrictEqual(entry.image, image);
+        if (original && entry.unavailable)
+            return undefined;
+        if (this.useResourceUrl) {
+            if (!isModelImageUrl(image.url))
+                throw new AgentError('MAR_AGENT_RESOURCE_URL_UNAVAILABLE', 'Resource URL is unavailable.');
+            const { dataBase64: _bytes, ...reference } = image;
+            return reference;
+        }
+        let bytes;
+        try {
+            bytes =
+                image.dataBase64 !== undefined
+                    ? image
+                    : image.resourceId === undefined
+                        ? undefined
+                        : await this.#readBytes(image.resourceId);
+        }
+        catch (error) {
+            if (!(error instanceof AgentError) || error.code !== 'MAR_AGENT_IMAGE_UNAVAILABLE')
+                throw error;
+        }
+        if (!bytes?.dataBase64) {
+            if (original)
+                entry.unavailable = true;
+            return undefined;
+        }
+        const { url: _url, urlExpiresAt: _expires, ...reference } = image;
+        return { ...reference, dataBase64: bytes.dataBase64 };
+    }
+}

package/dist/sdk/session-catalog.d.ts

@@ -0,0 +1,2 @@
+import { type AgentSessionCatalog, type OpenAgentSessionCatalogInput } from '../session/catalog.js';
+export declare function openAgentSessionCatalog(input: OpenAgentSessionCatalogInput): Promise<AgentSessionCatalog>;

package/dist/sdk/session-catalog.js

@@ -0,0 +1,12 @@
+import { AgentError } from '../error.js';
+import { createSessionCatalog } from '../session/catalog.js';
+import { JsonlSessionStore } from '../session/store/jsonl/jsonl-store.js';
+export async function openAgentSessionCatalog(input) {
+    const borrowed = input.sessionStore !== undefined;
+    if (input.sessionStore === null ||
+        borrowed === (input.homeDirectory !== undefined) ||
+        (!borrowed && (typeof input.homeDirectory !== 'string' || !input.homeDirectory)))
+        throw new AgentError('MAR_AGENT_SESSION_STORE_INVALID', 'Specify exactly one Session store or home directory.');
+    const store = input.sessionStore ?? (await JsonlSessionStore.open(input.homeDirectory));
+    return createSessionCatalog(store, borrowed);
+}