ai-sdk-letta 0.1.0

package/dist/history.js

@@ -0,0 +1,226 @@
+import { decodeImagePart } from './images.js';
+/** Maximum backend records loaded when restoring a conversation's display history. */
+export const HISTORY_LIMIT = 10_000;
+const record = (value) => value !== null && typeof value === 'object' && !Array.isArray(value) ? value : undefined;
+/** Strip terminal escape sequences and control characters from untrusted text. */
+export const sanitizeText = (text) => text.replace(/\x1b\][^\x07]*(?:\x07|\x1b\\)/g, '').replace(/\x1b\[[0-?]*[ -/]*[@-~]/g, '').replace(/[\x00-\x08\x0b-\x1f\x7f-\x9f]/g, '');
+/** The installed SDK drops agent_id for default history. Its supported command
+ * escape hatch forwards the backend's agent-scoped query, including real cursors.
+ * Named conversations use the ordinary SDK API. Neither path sends input.
+ */
+export async function historyPage(session, agentId, conversationId, options, timeoutMs) {
+    if (conversationId !== 'default' && timeoutMs === undefined)
+        return session.listMessages({ ...options, conversationId });
+    const response = await session.sendCommand({ type: 'conversation_messages_list', conversation_id: conversationId, query: { ...options, agent_id: agentId } }, { responseType: 'conversation_messages_list_response', ...(timeoutMs === undefined ? {} : { timeoutMs }) });
+    if (response.success !== true || !Array.isArray(response.messages))
+        throw new Error('Unable to load authoritative default conversation history');
+    return { messages: response.messages,
+        ...(typeof response.has_more === 'boolean' ? { hasMore: response.has_more } : {}),
+        ...(typeof response.next_before === 'string' || response.next_before === null ? { nextBefore: response.next_before } : {}) };
+}
+/** Page backwards through history up to `maximum` records, validating cursors and IDs. */
+export async function loadHistory(page, maximum = HISTORY_LIMIT) {
+    if (!Number.isInteger(maximum) || maximum < 1)
+        throw new Error('Invalid history bound');
+    const newest = [];
+    const ids = new Set();
+    const cursors = new Set();
+    let before;
+    let truncated = false;
+    while (true) {
+        const limit = Math.min(100, maximum - newest.length);
+        const result = await page({ order: 'desc', limit, ...(before ? { before } : {}) });
+        if (!Array.isArray(result.messages) || result.messages.length > limit)
+            throw new Error('Invalid or oversized history page');
+        for (const message of result.messages) {
+            if (!message.id || ids.has(message.id))
+                throw new Error('History pagination returned duplicate or missing message IDs');
+            ids.add(message.id);
+            newest.push(message);
+        }
+        if (result.hasMore === false)
+            break;
+        if (!result.messages.length) {
+            if (result.hasMore === true)
+                throw new Error('History pagination reported more data but returned no messages');
+            break;
+        }
+        if (newest.length >= maximum) {
+            truncated = true;
+            break;
+        }
+        const cursor = result.nextBefore ?? result.messages.at(-1)?.id;
+        if (!cursor || cursors.has(cursor) || cursor === before)
+            throw new Error('History pagination did not advance');
+        cursors.add(cursor);
+        before = cursor;
+    }
+    // Preserve backend order (including equal timestamps and split tool IDs).
+    return { messages: newest.reverse(), truncated };
+}
+function textContent(content, user = false) {
+    let text = typeof content === 'string' ? content : Array.isArray(content) ? content.map(part => {
+        const p = record(part);
+        return p?.type === 'text' && typeof p.text === 'string' ? p.text : '';
+    }).filter(Boolean).join('\n') : '';
+    if (user) {
+        // Harness inserts these as ordinary user content on reconnect. Never expose
+        // environment, memory, or system internals as if the user had typed them.
+        text = text.replace(/<system-reminder\b[^>]*>[\s\S]*?<\/system-reminder>/gi, '').replace(/<system-reminder\b[\s\S]*$/gi, '');
+        try {
+            const envelope = JSON.parse(text);
+            if (envelope && typeof envelope === 'object' && typeof envelope.type === 'string') {
+                if (envelope.type === 'user_message' && typeof envelope.message === 'string')
+                    text = envelope.message;
+                else if (['heartbeat', 'system_message', 'system_alert', 'memory_warning'].includes(envelope.type))
+                    return '';
+            }
+        }
+        catch { /* ordinary human text */ }
+    }
+    return sanitizeText(text).trim();
+}
+/** Text shown for a user image that cannot be displayed (unsupported, invalid, or over the display budget). */
+export const IMAGE_PLACEHOLDER = '[Image]';
+/** Most decoded image bytes restored for display from one conversation, newest first. Older images become placeholders. */
+export const HISTORY_IMAGE_BUDGET = 48 * 1024 * 1024;
+/** Letta `ImageContent` items of a backend user record, in order. */
+function imageItems(content) {
+    return Array.isArray(content) ? content.map(record).filter((p) => p?.type === 'image') : [];
+}
+/**
+ * Display part for one stored image: a `data:` URL for a well-formed PNG,
+ * JPEG, GIF or WebP within budget, otherwise the {@link IMAGE_PLACEHOLDER}.
+ * The bytes are re-checked, so a mislabelled record never becomes a data URL
+ * of another type.
+ */
+function imagePart(item, budget) {
+    const source = record(item.source);
+    if (budget.left > 0 && source?.type === 'base64' && typeof source.data === 'string' && typeof source.media_type === 'string') {
+        try {
+            const image = decodeImagePart({ type: 'image', image: source.data, mediaType: source.media_type });
+            if (image.bytes <= budget.left) {
+                budget.left -= image.bytes;
+                return { type: 'file', mediaType: image.mediaType, url: `data:${image.mediaType};base64,${image.base64}` };
+            }
+        }
+        catch { /* not displayable */ }
+    }
+    return { type: 'text', text: IMAGE_PLACEHOLDER };
+}
+/** Display-only message time from the backend record, when it is a valid date. */
+function timestamp(row) {
+    const time = typeof row.date === 'string' ? Date.parse(row.date) : NaN;
+    return Number.isFinite(time) ? { metadata: { createdAt: new Date(time).toISOString() } } : {};
+}
+/** Display projection only. Never reconstruct the model's context from this.
+ * Completed allowlisted app tools become inert output cards; everything else is
+ * omitted, including pending approvals, reasoning, system, memory and events.
+ * User images become `file` parts with a `data:` URL (newest first, within
+ * `imageBudget` bytes); the rest become an `[Image]` text placeholder.
+ */
+export function projectHistory(messages, appTools, imageBudget = HISTORY_IMAGE_BUDGET) {
+    const returns = new Map();
+    for (const message of messages) {
+        const row = message;
+        if (row.message_type === 'tool_return_message' && typeof row.tool_call_id === 'string')
+            returns.set(row.tool_call_id, row);
+    }
+    // Spend the image budget on the newest images first.
+    const images = new Map();
+    const budget = { left: imageBudget };
+    for (let index = messages.length - 1; index >= 0; index--) {
+        const row = messages[index];
+        if (row.message_type !== 'user_message')
+            continue;
+        const items = imageItems(row.content);
+        if (items.length)
+            images.set(messages[index].id, items.reverse().map(item => imagePart(item, budget)).reverse());
+    }
+    const shownCalls = new Set();
+    const projected = [];
+    for (const message of messages) {
+        const row = message;
+        if (row.message_type === 'user_message' || row.message_type === 'assistant_message') {
+            const role = row.message_type === 'user_message' ? 'user' : 'assistant';
+            const text = textContent(row.content, role === 'user');
+            const attached = role === 'user' ? images.get(message.id) ?? [] : [];
+            if (text || attached.length)
+                projected.push({ id: `history-${message.id}`, role, parts: [...(text ? [{ type: 'text', text }] : []), ...attached], ...timestamp(row) });
+        }
+        else if (row.message_type === 'tool_call_message' || row.message_type === 'approval_request_message') {
+            const call = record(row.tool_call);
+            const id = call?.tool_call_id;
+            const name = call?.name;
+            if (!call || typeof id !== 'string' || typeof name !== 'string' || !appTools.includes(name) || shownCalls.has(id))
+                continue;
+            const output = returns.get(id);
+            if (!output || !['success', 'error'].includes(String(output.status)))
+                continue;
+            let input;
+            try {
+                input = typeof call.arguments === 'string' ? JSON.parse(sanitizeText(call.arguments)) : JSON.parse(sanitizeText(JSON.stringify(call.arguments)));
+            }
+            catch {
+                continue;
+            }
+            const text = textContent(output.tool_return);
+            let value = text;
+            try {
+                value = JSON.parse(text);
+            }
+            catch { /* text output */ }
+            shownCalls.add(id);
+            projected.push({ id: `history-${message.id}`, role: 'assistant', ...timestamp(row), parts: [{
+                        type: 'dynamic-tool', toolName: name, toolCallId: id, input,
+                        providerExecuted: true,
+                        ...(output.status === 'error' ? { state: 'output-error', errorText: text } : { state: 'output-available', output: value }),
+                    }] });
+        }
+    }
+    return projected;
+}
+/** @throws when the conversation ends with an unanswered user turn or an unfinished tool call. */
+export function assertHistorySettled(messages) {
+    // Conservative: do not resume an abandoned prompt or half-completed tool chain.
+    let pendingUser = false;
+    const calls = new Set();
+    for (const message of messages) {
+        const row = message;
+        if (row.message_type === 'user_message' && (textContent(row.content, true) || imageItems(row.content).length))
+            pendingUser = true;
+        if (row.message_type === 'assistant_message' && textContent(row.content))
+            pendingUser = false;
+        if (row.message_type === 'tool_call_message' || row.message_type === 'approval_request_message') {
+            const id = record(row.tool_call)?.tool_call_id;
+            if (typeof id === 'string')
+                calls.add(id);
+        }
+        if (row.message_type === 'tool_return_message' && typeof row.tool_call_id === 'string')
+            calls.delete(row.tool_call_id);
+    }
+    if (pendingUser || calls.size)
+        throw new Error('Conversation history has an unfinished or uncertain turn. Inspect backend; no implicit retry or repair. Select another conversation to continue.');
+}
+/** List every conversation of one agent, failing closed on foreign or repeated rows. */
+export async function listConversations(list, agentId) {
+    const result = [];
+    const ids = new Set();
+    let after;
+    while (true) {
+        const page = await list({ agentId, limit: 100, order: 'asc', orderBy: 'createdAt', ...(after ? { after } : {}) });
+        if (!page.length)
+            break;
+        for (const conversation of page) {
+            if (conversation.agent_id !== agentId || ids.has(conversation.id))
+                throw new Error('Conversation listing returned wrong agent or non-advancing cursor');
+            ids.add(conversation.id);
+            result.push(conversation);
+        }
+        after = page.at(-1).id;
+        if (result.length > 10_000)
+            throw new Error('Conversation list exceeds 10,000; refusing to silently truncate');
+    }
+    return result;
+}
+//# sourceMappingURL=history.js.map

package/dist/history.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"history.js","sourceRoot":"","sources":["../src/history.ts"],"names":[],"mappings":"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"}

package/dist/identity.d.ts

@@ -0,0 +1,43 @@
+/** Persisted mapping from a logical definition ID to the Letta-generated agent ID. */
+export type Identity = {
+    version: 2;
+    definitionId: string;
+    name: string;
+    backend: string;
+    agentId: string;
+    conversationId: string;
+};
+/** Letta conversation IDs accepted by this library (`default` is the agent's default conversation). */
+export declare const validConversationId: (id: string) => boolean;
+/** Backend operations used while acquiring an identity. */
+export interface IdentityBackend {
+    /** Create the Letta agent. Called at most once per logical ID, ever. */
+    create(): Promise<string>;
+    /** Confirm the mapped agent still exists and matches; throw otherwise. */
+    validate(id: string): Promise<void>;
+}
+/** Handle returned by {@link acquireIdentity}. Holds an exclusive lock until `release()`. */
+export type IdentityLease = Awaited<ReturnType<typeof acquireIdentity>>;
+/**
+ * Acquire the durable identity for a definition, creating the Letta agent on
+ * first use. Fails closed on stale locks, uncertain creations or mismatches:
+ * it never searches by name, recreates, or retries.
+ *
+ * Files in `directory` (all 0600, directory 0700):
+ * - `<id>.json` the mapping; `<id>.lock` the process lock;
+ * - `<id>.pending.json` / `<id>.conversation.pending.json` uncertain creations;
+ * - `<id>.<conversation>.turn.pending.json` a turn whose delivery is not yet confirmed.
+ */
+export declare function acquireIdentity(directory: string, definition: {
+    id: string;
+    name: string;
+}, backend: string, api: IdentityBackend): Promise<{
+    identity: Identity;
+    release: () => void;
+    selectConversation: (id: string) => void;
+    createConversation: (create: (agentId: string) => Promise<string>) => Promise<string>;
+    assertNoPendingTurn: (id: string) => void;
+    beginTurn: (id: string) => void;
+    completeTurn: (id: string) => void;
+}>;
+//# sourceMappingURL=identity.d.ts.map

package/dist/identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.d.ts","sourceRoot":"","sources":["../src/identity.ts"],"names":[],"mappings":"AAGA,sFAAsF;AACtF,MAAM,MAAM,QAAQ,GAAG;IAAE,OAAO,EAAE,CAAC,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,MAAM,CAAA;CAAE,CAAC;AAEpI,uGAAuG;AACvG,eAAO,MAAM,mBAAmB,GAAI,IAAI,MAAM,KAAG,OAA8E,CAAC;AAGhI,2DAA2D;AAC3D,MAAM,WAAW,eAAe;IAC9B,wEAAwE;IACxE,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAC1B,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACrC;AAED,6FAA6F;AAC7F,MAAM,MAAM,aAAa,GAAG,OAAO,CAAC,UAAU,CAAC,OAAO,eAAe,CAAC,CAAC,CAAC;AAExE;;;;;;;;;GASG;AACH,wBAAsB,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,eAAe;;;6BA4DpG,MAAM;iCAII,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC;8BAc7C,MAAM;oBAGhB,MAAM;uBAKH,MAAM;GAOnC"}

package/dist/identity.js

@@ -0,0 +1,158 @@
+import { chmodSync, closeSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+/** Letta conversation IDs accepted by this library (`default` is the agent's default conversation). */
+export const validConversationId = (id) => id === 'default' || /^(?:conv-|local-conv-)[a-zA-Z0-9-]+$/.test(id);
+const validLocalAgentId = (id) => typeof id === 'string' && /^agent-local-[a-zA-Z0-9-]+$/.test(id);
+/**
+ * Acquire the durable identity for a definition, creating the Letta agent on
+ * first use. Fails closed on stale locks, uncertain creations or mismatches:
+ * it never searches by name, recreates, or retries.
+ *
+ * Files in `directory` (all 0600, directory 0700):
+ * - `<id>.json` the mapping; `<id>.lock` the process lock;
+ * - `<id>.pending.json` / `<id>.conversation.pending.json` uncertain creations;
+ * - `<id>.<conversation>.turn.pending.json` a turn whose delivery is not yet confirmed.
+ */
+export async function acquireIdentity(directory, definition, backend, api) {
+    if (!/^[a-z0-9-]+$/.test(definition.id))
+        throw new Error('Invalid logical agent identity');
+    mkdirSync(directory, { recursive: true, mode: 0o700 });
+    if (lstatSync(directory).isSymbolicLink())
+        throw new Error('Unsafe identity directory');
+    chmodSync(directory, 0o700);
+    const base = join(directory, definition.id);
+    const lock = `${base}.lock`;
+    let fd;
+    try {
+        fd = openSync(lock, 'wx', 0o600);
+    }
+    catch {
+        throw new Error(`Agent identity is locked: ${lock}. Another process may be running. After a crash, verify its PID is no longer running before removing the lock; never remove a pending intent blindly.`);
+    }
+    writeFileSync(fd, JSON.stringify({ pid: process.pid, createdAt: new Date().toISOString() }));
+    fsyncSync(fd);
+    closeSync(fd);
+    let released = false;
+    const release = () => { if (!released) {
+        unlinkSync(lock);
+        released = true;
+    } };
+    const file = `${base}.json`;
+    const pending = `${base}.pending.json`;
+    const syncDirectory = () => { const dir = openSync(directory, 'r'); try {
+        fsyncSync(dir);
+    }
+    finally {
+        closeSync(dir);
+    } };
+    const exists = (path) => {
+        try {
+            lstatSync(path);
+            return true;
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return false;
+            throw error;
+        }
+    };
+    const read = (path) => {
+        if (!lstatSync(path).isFile() || lstatSync(path).isSymbolicLink())
+            throw new Error('Unsafe identity file');
+        return JSON.parse(readFileSync(path, 'utf8'));
+    };
+    const durableWrite = (path, value) => {
+        const handle = openSync(path, 'wx', 0o600);
+        try {
+            writeFileSync(handle, JSON.stringify(value, null, 2));
+            fsyncSync(handle);
+        }
+        finally {
+            closeSync(handle);
+        }
+        syncDirectory();
+    };
+    try {
+        if (exists(pending))
+            throw new Error(`Unresolved agent creation intent: ${pending}. Inspect the local backend and reconcile manually; refusing to create a duplicate.`);
+        const conversationPending = `${base}.conversation.pending.json`;
+        if (exists(conversationPending))
+            throw new Error(`Unresolved conversation creation intent: ${conversationPending}. Reconcile with backend before continuing; refusing to create a duplicate.`);
+        let identity;
+        let migrate = false;
+        const save = () => {
+            if (released)
+                throw new Error('Identity lock already released');
+            durableWrite(`${file}.new`, identity);
+            renameSync(`${file}.new`, file);
+            syncDirectory();
+        };
+        if (exists(file)) {
+            const stored = read(file);
+            if (![1, 2].includes(stored.version) || stored.definitionId !== definition.id || stored.name !== definition.name || stored.backend !== backend || typeof stored.conversationId !== 'string' || !validConversationId(stored.conversationId) || (stored.version === 1 && stored.conversationId !== 'default') || !validLocalAgentId(stored.agentId))
+                throw new Error('Invalid identity mapping or backend mismatch; refusing to recreate agent');
+            migrate = stored.version === 1;
+            identity = { ...stored, version: 2 };
+        }
+        else {
+            durableWrite(pending, { definitionId: definition.id, name: definition.name, backend, createdAt: new Date().toISOString(), state: 'creation-uncertain' });
+            const agentId = await api.create();
+            if (!validLocalAgentId(agentId))
+                throw new Error('SDK returned a non-local agent ID');
+            identity = { version: 2, definitionId: definition.id, name: definition.name, backend, agentId, conversationId: 'default' };
+            // Keep the intent until an fsynced mapping is in place. Crashes fail closed.
+            durableWrite(`${file}.new`, identity);
+            renameSync(`${file}.new`, file);
+            syncDirectory();
+            unlinkSync(pending);
+        }
+        await api.validate(identity.agentId);
+        if (migrate)
+            save();
+        const selectConversation = (id) => {
+            if (!validConversationId(id))
+                throw new Error('Invalid conversation ID');
+            identity.conversationId = id;
+            save();
+        };
+        const createConversation = async (create) => {
+            if (released || exists(conversationPending))
+                throw new Error('Unresolved conversation creation or released lock');
+            durableWrite(conversationPending, { agentId: identity.agentId, createdAt: new Date().toISOString(), state: 'creation-uncertain' });
+            const id = await create(identity.agentId);
+            if (id === 'default' || !validConversationId(id))
+                throw new Error('Invalid created conversation');
+            selectConversation(id);
+            unlinkSync(conversationPending);
+            syncDirectory();
+            return id;
+        };
+        const turnPath = (id) => {
+            if (!validConversationId(id))
+                throw new Error('Invalid conversation ID');
+            return `${base}.${id}.turn.pending.json`;
+        };
+        const assertNoPendingTurn = (id) => {
+            if (exists(turnPath(id)))
+                throw new Error(`Uncertain prior delivery: ${turnPath(id)}. Inspect backend and reconcile manually; no automatic replay. Select another conversation to continue.`);
+        };
+        const beginTurn = (id) => {
+            if (released)
+                throw new Error('Identity lock already released');
+            assertNoPendingTurn(id);
+            durableWrite(turnPath(id), { agentId: identity.agentId, conversationId: id, createdAt: new Date().toISOString(), state: 'delivery-uncertain' });
+        };
+        const completeTurn = (id) => {
+            if (released)
+                throw new Error('Identity lock already released');
+            unlinkSync(turnPath(id));
+            syncDirectory();
+        };
+        return { identity, release, selectConversation, createConversation, assertNoPendingTurn, beginTurn, completeTurn };
+    }
+    catch (error) {
+        release();
+        throw error;
+    }
+}
+//# sourceMappingURL=identity.js.map

package/dist/identity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.js","sourceRoot":"","sources":["../src/identity.ts"],"names":[],"mappings":"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"}

package/dist/images.d.ts

@@ -0,0 +1,83 @@
+import type { ImageContent } from '@letta-ai/letta-agent-sdk';
+/** Image types a user turn may carry. Letta's `ImageContent` accepts exactly these. */
+export declare const IMAGE_MEDIA_TYPES: readonly ["image/png", "image/jpeg", "image/gif", "image/webp"];
+export type ImageMediaType = typeof IMAGE_MEDIA_TYPES[number];
+/**
+ * Bounds for images in one user turn (decoded bytes). They keep requests,
+ * backend history and restored views bounded; clients should downscale before
+ * sending (the browser app does).
+ */
+export interface ImageLimits {
+    maxImageBytes: number;
+    maxImages: number;
+    maxTotalBytes: number;
+}
+export declare const IMAGE_LIMITS: Readonly<ImageLimits>;
+/** Machine-readable reason for {@link ImageInputError}. */
+export type ImageInputErrorCode = 'image_unsupported_type' | 'image_invalid' | 'image_remote_url' | 'image_too_large' | 'images_too_many' | 'images_too_large';
+/** A rejected image input. `code` is stable; `message` is human-readable. */
+export declare class ImageInputError extends Error {
+    readonly code: ImageInputErrorCode;
+    readonly name = "ImageInputError";
+    constructor(code: ImageInputErrorCode, message: string);
+}
+/** Reference provider key used for images in the in-memory transcript. */
+export declare const IMAGE_REFERENCE_PROVIDER = "ai-sdk-letta-sha256";
+/** Detect PNG, JPEG, GIF or WebP from magic bytes; `undefined` otherwise. */
+export declare function sniffImageType(bytes: Uint8Array): ImageMediaType | undefined;
+/** A validated image, ready for Letta. */
+export interface DecodedImage {
+    mediaType: ImageMediaType;
+    base64: string;
+    bytes: number;
+    sha256: string;
+}
+/** An image-carrying user content part, as found in AI SDK model messages. */
+type PartLike = {
+    type: string;
+    image?: unknown;
+    data?: unknown;
+    mediaType?: unknown;
+};
+/** True for AI SDK `image` parts and `file` parts whose media type is an image. */
+export declare function isImagePart(part: PartLike): boolean;
+/**
+ * Validate one AI SDK `image` or `file` part and decode it. Accepts base64
+ * strings, `data:` URLs (string or `URL`), bytes, and the tagged
+ * `{ type: 'data' | 'url' }` file shapes. Remote URLs are rejected: images are
+ * never fetched.
+ * @throws {ImageInputError}
+ */
+export declare function decodeImagePart(part: PartLike, limit?: number): DecodedImage;
+/** Enforce count and combined size over already-decoded images. @throws {ImageInputError} */
+export declare function assertImageBudget(images: readonly {
+    bytes: number;
+}[], limits?: Readonly<ImageLimits>): void;
+/**
+ * Validate a list of base64 images (as received over HTTP) against every
+ * limit. Returns decoded images with their content hash.
+ * @throws {ImageInputError}
+ */
+export declare function validateImages(images: readonly {
+    mediaType?: unknown;
+    data?: unknown;
+}[], limits?: Readonly<ImageLimits>): DecodedImage[];
+/** Letta `ImageContent` for a decoded image. */
+export declare const toLettaImage: (image: DecodedImage) => ImageContent;
+/**
+ * Content hash of an image part, for history comparison. Compact transcript
+ * references (see {@link compactImagePart}) yield their stored hash; anything
+ * else is decoded and hashed.
+ */
+export declare function imagePartDigest(part: PartLike): string;
+/** Replace an image part's data with a content-hash reference, so transcripts never hold image bytes twice. */
+export declare function compactImagePart(part: PartLike): {
+    type: 'file';
+    mediaType: string;
+    data: {
+        type: 'reference';
+        reference: Record<string, string>;
+    };
+};
+export {};
+//# sourceMappingURL=images.d.ts.map

package/dist/images.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"images.d.ts","sourceRoot":"","sources":["../src/images.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAE9D,uFAAuF;AACvF,eAAO,MAAM,iBAAiB,iEAAkE,CAAC;AACjG,MAAM,MAAM,cAAc,GAAG,OAAO,iBAAiB,CAAC,MAAM,CAAC,CAAC;AAE9D;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAAG,aAAa,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE;AAChG,eAAO,MAAM,YAAY,EAAE,QAAQ,CAAC,WAAW,CAO7C,CAAC;AAEH,2DAA2D;AAC3D,MAAM,MAAM,mBAAmB,GAC3B,wBAAwB,GACxB,eAAe,GACf,kBAAkB,GAClB,iBAAiB,GACjB,iBAAiB,GACjB,kBAAkB,CAAC;AAEvB,6EAA6E;AAC7E,qBAAa,eAAgB,SAAQ,KAAK;IAE5B,QAAQ,CAAC,IAAI,EAAE,mBAAmB;IAD9C,SAAkB,IAAI,qBAAqB;gBACtB,IAAI,EAAE,mBAAmB,EAAE,OAAO,EAAE,MAAM;CAChE;AAID,0EAA0E;AAC1E,eAAO,MAAM,wBAAwB,wBAAwB,CAAC;AAE9D,6EAA6E;AAC7E,wBAAgB,cAAc,CAAC,KAAK,EAAE,UAAU,GAAG,cAAc,GAAG,SAAS,CAO5E;AAaD,0CAA0C;AAC1C,MAAM,WAAW,YAAY;IAAG,SAAS,EAAE,cAAc,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE;AA8B1G,8EAA8E;AAC9E,KAAK,QAAQ,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IAAC,SAAS,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAYvF,mFAAmF;AACnF,wBAAgB,WAAW,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAGnD;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,QAAQ,EAAE,KAAK,GAAE,MAAmC,GAAG,YAAY,CAmBxG;AAED,6FAA6F;AAC7F,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,EAAE,EAAE,MAAM,GAAE,QAAQ,CAAC,WAAW,CAAgB,GAAG,IAAI,CAI1H;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,SAAS;IAAE,SAAS,CAAC,EAAE,OAAO,CAAC;IAAC,IAAI,CAAC,EAAE,OAAO,CAAA;CAAE,EAAE,EAAE,MAAM,GAAE,QAAQ,CAAC,WAAW,CAAgB,GAAG,YAAY,EAAE,CASvJ;AAED,gDAAgD;AAChD,eAAO,MAAM,YAAY,GAAI,OAAO,YAAY,KAAG,YAAgH,CAAC;AAEpK;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,CAEtD;AAED,+GAA+G;AAC/G,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,QAAQ,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE;QAAE,IAAI,EAAE,WAAW,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;KAAE,CAAA;CAAE,CAMpJ"}