ai-sdk-letta 0.1.0

package/src/definition.ts

@@ -0,0 +1,136 @@
+import type { ToolSet } from 'ai';
+import type { CreateAgentOptions } from '@letta-ai/letta-agent-sdk';
+import { ASK_USER_TOOL } from './tools.js';
+
+/** How a single application tool call is authorized. */
+export type ToolPermission = 'allow' | 'ask' | 'deny';
+
+/** When Letta runs background memory consolidation ("dreaming"). */
+export type DreamingTrigger = 'off' | 'step-count' | 'compaction-event';
+
+export interface DreamingSettings {
+  /** @default 'step-count' */
+  trigger: DreamingTrigger;
+  /** Steps between dreams when `trigger` is `'step-count'`. @default 25 */
+  stepCount: number;
+}
+
+/** Input accepted by {@link defineAgent}. */
+export interface AgentDefinitionInput<TOOLS extends ToolSet = ToolSet> {
+  /**
+   * Stable, application-owned logical ID (lowercase letters, digits and `-`).
+   * It is mapped once to the Letta-generated agent ID and never re-created.
+   */
+  id: string;
+  /** Display name. Also stored on the Letta agent and checked on every start. */
+  name: string;
+  /**
+   * Letta model handle, e.g. `openai-codex/gpt-5.5` or `anthropic/claude-sonnet-4-5`.
+   * Only used when the agent is first created; must be connected on the local backend.
+   */
+  model: string;
+  /** System instructions, applied when the agent is first created. */
+  instructions: string;
+  /** AI SDK tools executed in this process when the agent calls them. */
+  tools: TOOLS;
+  /**
+   * Permission per tool. Fail-closed: every tool must be listed.
+   * `ask_user` defaults to `'allow'` (it is itself a human interaction).
+   */
+  permissions?: Partial<Record<Extract<keyof TOOLS, string>, ToolPermission>>;
+  /** Background memory consolidation. @default { trigger: 'step-count', stepCount: 25 } */
+  dreaming?: Partial<DreamingSettings>;
+  /** Per-call tool execution deadline in milliseconds (human waits excluded). @default 5000 */
+  toolTimeoutMs?: number;
+}
+
+/** A validated, immutable agent definition. */
+export interface AgentDefinition<TOOLS extends ToolSet = ToolSet> {
+  readonly id: string;
+  readonly name: string;
+  readonly model: string;
+  readonly instructions: string;
+  readonly tools: TOOLS;
+  readonly permissions: Readonly<Record<string, ToolPermission>>;
+  readonly dreaming: Readonly<DreamingSettings>;
+  readonly toolTimeoutMs: number;
+}
+
+/** Tools the harness uses for MemFS. They are confined to the agent's own memory directory. */
+export const INTERNAL_MEMORY_TOOLS = ['Read', 'Write', 'Edit', 'Bash'] as const;
+
+export const DEFAULT_DREAMING: Readonly<DreamingSettings> = Object.freeze({ trigger: 'step-count', stepCount: 25 });
+
+const permissionValues: readonly ToolPermission[] = ['allow', 'ask', 'deny'];
+
+/**
+ * Validate and freeze an agent definition.
+ *
+ * @throws if the ID is invalid, a tool lacks a permission, or a permission names an unknown tool.
+ */
+export function defineAgent<TOOLS extends ToolSet>(input: AgentDefinitionInput<TOOLS>): AgentDefinition<TOOLS> {
+  if (typeof input.id !== 'string' || !/^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$/.test(input.id)) {
+    throw new Error('Agent id must be 1–64 lowercase letters, digits or "-", starting and ending with a letter or digit');
+  }
+  if (typeof input.name !== 'string' || !input.name.trim() || input.name.length > 120) throw new Error('Agent name must contain 1–120 characters');
+  if (typeof input.model !== 'string' || !input.model.includes('/')) throw new Error('Agent model must be a Letta model handle such as "provider/model"');
+  if (typeof input.instructions !== 'string' || !input.instructions.trim()) throw new Error('Agent instructions are required');
+  if (input.tools === null || typeof input.tools !== 'object' || Array.isArray(input.tools)) throw new Error('Agent tools must be an object of AI SDK tools; use {} for none');
+  const names = Object.keys(input.tools);
+  for (const name of names) {
+    if ((INTERNAL_MEMORY_TOOLS as readonly string[]).includes(name)) throw new Error(`Tool name "${name}" is reserved for memory operations`);
+    if (!/^[a-zA-Z0-9_-]{1,64}$/.test(name)) throw new Error(`Invalid tool name "${name}"`);
+  }
+  const permissions: Record<string, ToolPermission> = {};
+  for (const [name, mode] of Object.entries(input.permissions ?? {})) {
+    if (!names.includes(name)) throw new Error(`Permission for unknown tool "${name}"`);
+    if (!permissionValues.includes(mode as ToolPermission)) throw new Error(`Invalid permission for "${name}"`);
+    permissions[name] = mode as ToolPermission;
+  }
+  if (names.includes(ASK_USER_TOOL)) {
+    permissions[ASK_USER_TOOL] ??= 'allow';
+    if (permissions[ASK_USER_TOOL] === 'ask') throw new Error('ask_user is already interactive; use "allow" or "deny"');
+  }
+  const missing = names.filter(name => !Object.hasOwn(permissions, name));
+  if (missing.length) throw new Error(`Missing permission for tool(s): ${missing.join(', ')}. Every tool needs "allow", "ask" or "deny".`);
+  const dreaming = { ...DEFAULT_DREAMING, ...input.dreaming };
+  if (!['off', 'step-count', 'compaction-event'].includes(dreaming.trigger)) throw new Error('Invalid dreaming trigger');
+  if (!Number.isInteger(dreaming.stepCount) || dreaming.stepCount < 1 || dreaming.stepCount > 10_000) throw new Error('Dreaming stepCount must be a positive integer');
+  const toolTimeoutMs = input.toolTimeoutMs ?? 5000;
+  if (!Number.isInteger(toolTimeoutMs) || toolTimeoutMs < 1 || toolTimeoutMs > 300_000) throw new Error('toolTimeoutMs must be 1–300000');
+  return Object.freeze({
+    id: input.id, name: input.name, model: input.model, instructions: input.instructions, tools: input.tools,
+    permissions: Object.freeze(permissions), dreaming: Object.freeze(dreaming), toolTimeoutMs,
+  });
+}
+
+/**
+ * Appended to the definition's instructions at creation, so the model knows
+ * what the (enforced) memory policy allows.
+ */
+export function memoryPolicyInstructions(dreaming: DreamingSettings): string {
+  return 'Maintain useful long-term memory in your own MemFS only. Read, Write and Edit are restricted to Markdown files in your memory directory. '
+    + 'Bash is restricted to the exact memory commit command supplied in tool permission feedback; no general shell or filesystem actions are available. '
+    + (dreaming.trigger === 'off'
+      ? 'Background dreaming is off.'
+      : `Background dreaming consolidates memory${dreaming.trigger === 'step-count' ? ` after ${dreaming.stepCount} steps` : ' after compaction'}; do not claim a dream ran without evidence.`);
+}
+
+/** Letta Agent SDK creation options for a definition. */
+export function creationOptions(definition: AgentDefinition, cwd: string): CreateAgentOptions {
+  return {
+    name: definition.name, model: definition.model, cwd, memfs: true,
+    baseTools: [], skillSources: [], systemPrompt: `${definition.instructions}\n\n${memoryPolicyInstructions(definition.dreaming)}`,
+    // Do not pass `dreaming` here: the SDK applies it with scope 'both', which
+    // mutates the user's global Letta defaults. The runtime installs the
+    // definition's settings with scope 'local_project' in the private state cwd.
+  };
+}
+
+/** Protocol command that applies dreaming settings to this project scope only. */
+export function dreamingCommand(definition: AgentDefinition, agentId: string, conversationId = 'default') {
+  return {
+    type: 'set_reflection_settings', runtime: { agent_id: agentId, conversation_id: conversationId },
+    scope: 'local_project', settings: { trigger: definition.dreaming.trigger, step_count: definition.dreaming.stepCount },
+  } as const;
+}

package/src/history.ts

@@ -0,0 +1,198 @@
+import type { LettaCodeSession, ListMessagesOptions, ListMessagesResult, LettaConversation } from '@letta-ai/letta-agent-sdk';
+import type { UIMessage } from 'ai';
+import { decodeImagePart } from './images.js';
+
+/** Maximum backend records loaded when restoring a conversation's display history. */
+export const HISTORY_LIMIT = 10_000;
+type Row = Record<string, unknown>;
+const record = (value: unknown): Row | undefined => value !== null && typeof value === 'object' && !Array.isArray(value) ? value as Row : undefined;
+/** Strip terminal escape sequences and control characters from untrusted text. */
+export const sanitizeText = (text: string) => 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: Pick<LettaCodeSession, 'listMessages' | 'sendCommand'>, agentId: string, conversationId: string, options: ListMessagesOptions, timeoutMs?: number): Promise<ListMessagesResult> {
+  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 as ListMessagesResult['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: (options: ListMessagesOptions) => Promise<ListMessagesResult>, maximum = HISTORY_LIMIT): Promise<{ messages: ListMessagesResult['messages']; truncated: boolean }> {
+  if (!Number.isInteger(maximum) || maximum < 1) throw new Error('Invalid history bound');
+  const newest: ListMessagesResult['messages'] = [];
+  const ids = new Set<string>();
+  const cursors = new Set<string>();
+  let before: string | undefined;
+  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: unknown, user = false): string {
+  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: unknown): Row[] {
+  return Array.isArray(content) ? content.map(record).filter((p): p is Row => 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: Row, budget: { left: number }): UIMessage['parts'][number] {
+  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: Row): { metadata?: { createdAt: string } } {
+  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: ListMessagesResult['messages'], appTools: readonly string[], imageBudget = HISTORY_IMAGE_BUDGET): UIMessage[] {
+  const returns = new Map<string, Row>();
+  for (const message of messages) {
+    const row = message as unknown as Row;
+    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<string, UIMessage['parts']>();
+  const budget = { left: imageBudget };
+  for (let index = messages.length - 1; index >= 0; index--) {
+    const row = messages[index] as unknown as Row;
+    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<string>();
+  const projected: UIMessage[] = [];
+  for (const message of messages) {
+    const row = message as unknown as Row;
+    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' as const, 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: unknown;
+      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: unknown = 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: ListMessagesResult['messages']) {
+  // Conservative: do not resume an abandoned prompt or half-completed tool chain.
+  let pendingUser = false;
+  const calls = new Set<string>();
+  for (const message of messages) {
+    const row = message as unknown as Row;
+    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: (options: { agentId: string; after?: string; limit: number; order: 'asc'; orderBy: 'createdAt' }) => Promise<LettaConversation[]>, agentId: string): Promise<LettaConversation[]> {
+  const result: LettaConversation[] = [];
+  const ids = new Set<string>();
+  let after: string | undefined;
+  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;
+}

package/src/identity.ts

@@ -0,0 +1,125 @@
+import { chmodSync, closeSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/** 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 const validConversationId = (id: string): boolean => id === 'default' || /^(?:conv-|local-conv-)[a-zA-Z0-9-]+$/.test(id);
+const validLocalAgentId = (id: unknown): id is string => typeof id === 'string' && /^agent-local-[a-zA-Z0-9-]+$/.test(id);
+
+/** 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 async function acquireIdentity(directory: string, definition: { id: string; name: string }, backend: string, api: IdentityBackend) {
+  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: number;
+  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: string) => {
+    try { lstatSync(path); return true; }
+    catch (error) { if ((error as NodeJS.ErrnoException).code === 'ENOENT') return false; throw error; }
+  };
+  const read = (path: string) => {
+    if (!lstatSync(path).isFile() || lstatSync(path).isSymbolicLink()) throw new Error('Unsafe identity file');
+    return JSON.parse(readFileSync(path, 'utf8'));
+  };
+  const durableWrite = (path: string, value: unknown) => {
+    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: 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: string) => {
+      if (!validConversationId(id)) throw new Error('Invalid conversation ID');
+      identity.conversationId = id; save();
+    };
+    const createConversation = async (create: (agentId: string) => Promise<string>) => {
+      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: string) => {
+      if (!validConversationId(id)) throw new Error('Invalid conversation ID');
+      return `${base}.${id}.turn.pending.json`;
+    };
+    const assertNoPendingTurn = (id: string) => {
+      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: string) => {
+      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: string) => {
+      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; }
+}

package/src/images.ts

@@ -0,0 +1,184 @@
+import { createHash } from 'node:crypto';
+import type { ImageContent } from '@letta-ai/letta-agent-sdk';
+
+/** Image types a user turn may carry. Letta's `ImageContent` accepts exactly these. */
+export const IMAGE_MEDIA_TYPES = ['image/png', 'image/jpeg', 'image/gif', 'image/webp'] as const;
+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 const IMAGE_LIMITS: Readonly<ImageLimits> = Object.freeze({
+  /** Largest single image. */
+  maxImageBytes: 5 * 1024 * 1024,
+  /** Most images in one user turn. */
+  maxImages: 4,
+  /** Largest combined size of all images in one user turn. */
+  maxTotalBytes: 10 * 1024 * 1024,
+});
+
+/** Machine-readable reason for {@link ImageInputError}. */
+export type ImageInputErrorCode =
+  | 'image_unsupported_type' // not PNG, JPEG, GIF or WebP (by declared type or content)
+  | 'image_invalid' // not base64, empty, or bytes that do not match the declared type
+  | 'image_remote_url' // http(s) or other URLs: images are never fetched
+  | 'image_too_large' // one image over maxImageBytes
+  | 'images_too_many' // more than maxImages
+  | 'images_too_large'; // combined size over maxTotalBytes
+
+/** A rejected image input. `code` is stable; `message` is human-readable. */
+export class ImageInputError extends Error {
+  override readonly name = 'ImageInputError';
+  constructor(readonly code: ImageInputErrorCode, message: string) { super(message); }
+}
+
+const MB = (bytes: number) => `${Math.round(bytes / 1024 / 1024)} MB`;
+const base64Pattern = /^[A-Za-z0-9+/]*={0,2}$/;
+/** Reference provider key used for images in the in-memory transcript. */
+export const IMAGE_REFERENCE_PROVIDER = 'ai-sdk-letta-sha256';
+
+/** Detect PNG, JPEG, GIF or WebP from magic bytes; `undefined` otherwise. */
+export function sniffImageType(bytes: Uint8Array): ImageMediaType | undefined {
+  const at = (offset: number, ...values: number[]) => values.every((value, index) => bytes[offset + index] === value);
+  if (at(0, 0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a)) return 'image/png';
+  if (at(0, 0xff, 0xd8, 0xff)) return 'image/jpeg';
+  if (at(0, 0x47, 0x49, 0x46, 0x38) && (bytes[4] === 0x37 || bytes[4] === 0x39) && bytes[5] === 0x61) return 'image/gif';
+  if (at(0, 0x52, 0x49, 0x46, 0x46) && at(8, 0x57, 0x45, 0x42, 0x50)) return 'image/webp';
+  return undefined;
+}
+
+/** Normalize a declared media type: `image/jpg` → `image/jpeg`, parameters and case dropped; `image`/`image/*` mean "detect". */
+function declaredType(mediaType: unknown): ImageMediaType | 'detect' {
+  if (mediaType === undefined) return 'detect';
+  if (typeof mediaType !== 'string') throw new ImageInputError('image_unsupported_type', 'Image media type must be a string');
+  const type = mediaType.split(';', 1)[0]!.trim().toLowerCase();
+  if (type === 'image' || type === 'image/*') return 'detect';
+  const normalized = type === 'image/jpg' ? 'image/jpeg' : type;
+  if (!(IMAGE_MEDIA_TYPES as readonly string[]).includes(normalized)) throw new ImageInputError('image_unsupported_type', `Unsupported image type ${type || 'unknown'}; use PNG, JPEG, GIF or WebP`);
+  return normalized as ImageMediaType;
+}
+
+/** A validated image, ready for Letta. */
+export interface DecodedImage { mediaType: ImageMediaType; base64: string; bytes: number; sha256: string }
+
+function fromBase64(base64: string, declared: ImageMediaType | 'detect', limit: number): DecodedImage {
+  const clean = base64.replace(/\s+/g, '');
+  if (!clean || clean.length % 4 === 1 || !base64Pattern.test(clean)) throw new ImageInputError('image_invalid', 'Image data is not valid base64');
+  // Cheap bound before decoding anything large.
+  if (Math.floor(clean.length * 3 / 4) - 2 > limit) throw new ImageInputError('image_too_large', `Each image can be up to ${MB(limit)}`);
+  const buffer = Buffer.from(clean, 'base64');
+  return fromBytes(buffer, declared, limit, clean);
+}
+
+function fromBytes(bytes: Uint8Array, declared: ImageMediaType | 'detect', limit: number, base64?: string): DecodedImage {
+  if (!bytes.byteLength) throw new ImageInputError('image_invalid', 'Image is empty');
+  if (bytes.byteLength > limit) throw new ImageInputError('image_too_large', `Each image can be up to ${MB(limit)}`);
+  const sniffed = sniffImageType(bytes);
+  if (!sniffed) throw new ImageInputError(declared === 'detect' ? 'image_unsupported_type' : 'image_invalid', declared === 'detect' ? 'Unsupported image; use PNG, JPEG, GIF or WebP' : `Image content is not a valid ${declared.slice(6).toUpperCase()}`);
+  if (declared !== 'detect' && declared !== sniffed) throw new ImageInputError('image_invalid', `Image content (${sniffed}) does not match its declared type (${declared})`);
+  const data = base64 ?? Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength).toString('base64');
+  return { mediaType: sniffed, base64: data, bytes: bytes.byteLength, sha256: createHash('sha256').update(bytes).digest('hex') };
+}
+
+/** Parse a `data:` URL (base64 only). */
+function fromDataUrl(url: string, declared: ImageMediaType | 'detect', limit: number): DecodedImage {
+  const match = /^data:([^,;]*)((?:;[^,;]*)*),(.*)$/s.exec(url);
+  if (!match || !match[2]!.split(';').includes('base64')) throw new ImageInputError('image_invalid', 'Image data URLs must be base64-encoded');
+  const urlType = match[1] ? declaredType(match[1]) : 'detect';
+  if (declared !== 'detect' && urlType !== 'detect' && urlType !== declared) throw new ImageInputError('image_invalid', 'Image data URL type does not match the declared type');
+  return fromBase64(match[3]!, declared === 'detect' ? urlType : declared, limit);
+}
+
+/** An image-carrying user content part, as found in AI SDK model messages. */
+type PartLike = { type: string; image?: unknown; data?: unknown; mediaType?: unknown };
+
+/** The reference hash in a compact transcript part, if this part is one. */
+function referenceOf(value: unknown): string | undefined {
+  const pick = (v: unknown) => {
+    const ref = v && typeof v === 'object' && !(v instanceof Uint8Array) && !(v instanceof ArrayBuffer) && !(v instanceof URL) ? (v as Record<string, unknown>)[IMAGE_REFERENCE_PROVIDER] : undefined;
+    return typeof ref === 'string' && /^[a-f0-9]{64}$/.test(ref) ? ref : undefined;
+  };
+  if (value && typeof value === 'object' && (value as { type?: unknown }).type === 'reference') return pick((value as { reference?: unknown }).reference);
+  return pick(value);
+}
+
+/** True for AI SDK `image` parts and `file` parts whose media type is an image. */
+export function isImagePart(part: PartLike): boolean {
+  if (part.type === 'image') return true;
+  return part.type === 'file' && typeof part.mediaType === 'string' && /^image(?:\/|$)/i.test(part.mediaType.trim());
+}
+
+/**
+ * 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 function decodeImagePart(part: PartLike, limit: number = IMAGE_LIMITS.maxImageBytes): DecodedImage {
+  const declared = declaredType(part.mediaType);
+  let value: unknown = part.type === 'image' ? part.image : part.data;
+  if (value && typeof value === 'object' && !(value instanceof Uint8Array) && !(value instanceof ArrayBuffer) && !(value instanceof URL)) {
+    const tagged = value as { type?: unknown; data?: unknown; url?: unknown };
+    if (tagged.type === 'data') value = tagged.data;
+    else if (tagged.type === 'url') value = tagged.url;
+    else throw new ImageInputError('image_invalid', 'Provider file references and inline text are not supported for images');
+  }
+  if (value instanceof URL) value = value.href;
+  if (typeof value === 'string') {
+    if (/^data:/i.test(value)) return fromDataUrl(value, declared, limit);
+    // Base64 never contains ':'; anything with a scheme is a URL we will not fetch.
+    if (/^[a-z][a-z0-9+.-]*:/i.test(value.trimStart())) throw new ImageInputError('image_remote_url', 'Image URLs are not fetched; attach the image data instead');
+    return fromBase64(value, declared, limit);
+  }
+  if (value instanceof ArrayBuffer) return fromBytes(new Uint8Array(value), declared, limit);
+  if (value instanceof Uint8Array) return fromBytes(value, declared, limit);
+  throw new ImageInputError('image_invalid', 'Unsupported image data');
+}
+
+/** Enforce count and combined size over already-decoded images. @throws {ImageInputError} */
+export function assertImageBudget(images: readonly { bytes: number }[], limits: Readonly<ImageLimits> = IMAGE_LIMITS): void {
+  if (images.length > limits.maxImages) throw new ImageInputError('images_too_many', `Attach up to ${limits.maxImages} images per message`);
+  const total = images.reduce((sum, image) => sum + image.bytes, 0);
+  if (total > limits.maxTotalBytes) throw new ImageInputError('images_too_large', `Images in one message can total up to ${MB(limits.maxTotalBytes)}`);
+}
+
+/**
+ * Validate a list of base64 images (as received over HTTP) against every
+ * limit. Returns decoded images with their content hash.
+ * @throws {ImageInputError}
+ */
+export function validateImages(images: readonly { mediaType?: unknown; data?: unknown }[], limits: Readonly<ImageLimits> = IMAGE_LIMITS): DecodedImage[] {
+  if (!Array.isArray(images)) throw new ImageInputError('image_invalid', 'Images must be a list');
+  if (images.length > limits.maxImages) throw new ImageInputError('images_too_many', `Attach up to ${limits.maxImages} images per message`);
+  const decoded = images.map(image => {
+    if (!image || typeof image !== 'object' || typeof image.data !== 'string') throw new ImageInputError('image_invalid', 'Each image needs base64 data');
+    return decodeImagePart({ type: 'image', image: image.data, mediaType: image.mediaType }, limits.maxImageBytes);
+  });
+  assertImageBudget(decoded, limits);
+  return decoded;
+}
+
+/** Letta `ImageContent` for a decoded image. */
+export const toLettaImage = (image: DecodedImage): ImageContent => ({ type: 'image', source: { type: 'base64', media_type: image.mediaType, data: image.base64 } });
+
+/**
+ * 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 function imagePartDigest(part: PartLike): string {
+  return referenceOf(part.type === 'image' ? part.image : part.data) ?? decodeImagePart(part, Number.MAX_SAFE_INTEGER).sha256;
+}
+
+/** Replace an image part's data with a content-hash reference, so transcripts never hold image bytes twice. */
+export function compactImagePart(part: PartLike): { type: 'file'; mediaType: string; data: { type: 'reference'; reference: Record<string, string> } } {
+  const existing = referenceOf(part.type === 'image' ? part.image : part.data);
+  const mediaType = typeof part.mediaType === 'string' && part.mediaType.includes('/') ? part.mediaType : 'image';
+  if (existing) return { type: 'file', mediaType, data: { type: 'reference', reference: { [IMAGE_REFERENCE_PROVIDER]: existing } } };
+  const image = decodeImagePart(part, Number.MAX_SAFE_INTEGER);
+  return { type: 'file', mediaType: image.mediaType, data: { type: 'reference', reference: { [IMAGE_REFERENCE_PROVIDER]: image.sha256 } } };
+}