ai-sdk-letta 0.1.0

package/src/index.ts

@@ -0,0 +1,23 @@
+/**
+ * ai-sdk-letta: a persistent, Letta-backed Vercel AI SDK `Agent` with
+ * application-owned tools and human-in-the-loop interactions.
+ *
+ * @packageDocumentation
+ */
+export { LettaAgent, historyKey, userTurnContent, MAX_INPUT_CHARACTERS, type LettaAgentOptions, type AgentPresentation, type DeliveryHooks, type TurnSession } from './agent.js';
+export {
+  IMAGE_LIMITS, IMAGE_MEDIA_TYPES, IMAGE_REFERENCE_PROVIDER, ImageInputError, validateImages, decodeImagePart, assertImageBudget, isImagePart, sniffImageType, toLettaImage, imagePartDigest, compactImagePart,
+  type ImageInputErrorCode, type ImageMediaType, type ImageLimits, type DecodedImage,
+} from './images.js';
+export {
+  defineAgent, creationOptions, dreamingCommand, memoryPolicyInstructions, DEFAULT_DREAMING, INTERNAL_MEMORY_TOOLS,
+  type AgentDefinition, type AgentDefinitionInput, type DreamingSettings, type DreamingTrigger, type ToolPermission,
+} from './definition.js';
+export { openLettaAgent, createLettaAgent, assertIdle, sessionOptions, foregroundToolsCommand, localBackendDirectory, type OpenAgentOptions, type LettaRuntime, type ConversationChoice } from './runtime.js';
+export { acquireIdentity, validConversationId, type Identity, type IdentityBackend, type IdentityLease } from './identity.js';
+export { HISTORY_LIMIT, HISTORY_IMAGE_BUDGET, IMAGE_PLACEHOLDER, sanitizeText, historyPage, loadHistory, projectHistory, assertHistorySettled, listConversations } from './history.js';
+export { listNavigationEntries, searchConversations, snippet, SEARCH_CONVERSATIONS, SEARCH_RECORDS, SEARCH_TOTAL, SEARCH_MATCHES, SEARCH_MILLISECONDS, type ConversationEntry, type NavigationSource, type SearchMatch } from './navigation.js';
+export { ToolInteractions, validateQuestion, validateResponse, type Question, type InteractionRequest, type InteractionResponse, type InteractionHandler } from './interactions.js';
+export { createToolBridge, askUserTool, fileTraceWriter, ASK_USER_TOOL, type AskUserResult, type ToolActivity, type ToolBridge, type ToolBridgeOptions } from './tools.js';
+export { allowMemoryTool, memoryCommitCommand } from './memory.js';
+export { resolveStateDirectory, statePaths, STATE_DIR_ENV } from './state.js';

package/src/interactions.ts

@@ -0,0 +1,121 @@
+import { randomUUID } from 'node:crypto';
+
+/** Arguments of the built-in `ask_user` tool. */
+export type Question = { question: string; options?: { id: string; label: string }[]; allowFreeText?: boolean; multiSelect?: boolean };
+
+/** A prompt the application must show to a human: approve a tool call, or answer a question. */
+export type InteractionRequest = {
+  /** Unique per prompt; a response must echo it. */
+  id: string;
+  toolCallId: string;
+  tool: string;
+  kind: 'approval' | 'question';
+  title: string;
+  /** For approvals: the exact JSON arguments that will run if approved. */
+  details?: string;
+  options?: Question['options'];
+  allowFreeText?: boolean;
+  multiSelect?: boolean;
+};
+
+/** A human's answer. Approvals use `approved`; questions use `selected` and/or `text`. */
+export type InteractionResponse = { id: string; approved?: boolean; cancelled?: boolean; selected?: string[]; text?: string };
+
+/** Renders one request and resolves with the human's response. `signal` aborts when the prompt is withdrawn. */
+export type InteractionHandler = (request: InteractionRequest, signal: AbortSignal) => Promise<unknown>;
+
+type Pending = { request: InteractionRequest; signal: AbortSignal; resolve(value: InteractionResponse): void; reject(error: Error): void; cleanup(): void; control: AbortController };
+
+/**
+ * Interaction broker: serializes human prompts (FIFO, one at a time) between
+ * tool calls and a single connected renderer (TUI, GUI, or your own).
+ *
+ * Responses are validated against the exact request and are never interpreted
+ * as chat turns. Without a connected renderer, requests fail closed.
+ */
+export class ToolInteractions {
+  private handler?: InteractionHandler;
+  private queue: Pending[] = [];
+  private active?: Pending;
+  private closed = false;
+
+  /** Attach the renderer. Returns a disconnect function that cancels all pending prompts. */
+  readonly connect = (handler: InteractionHandler): (() => void) => {
+    if (this.closed || this.handler) throw new Error('interaction_unavailable');
+    this.handler = handler;
+    this.pump();
+    return () => { this.handler = undefined; this.cancelAll(); };
+  };
+
+  /** Permanently close the broker and cancel every pending prompt. */
+  close(): void { this.closed = true; this.handler = undefined; this.cancelAll(); }
+
+  private cancelAll() {
+    for (const pending of [...this.queue]) pending.control.abort();
+  }
+
+  /** Queue a prompt. Rejects with `interaction_unavailable` if no renderer is connected. */
+  request(request: Omit<InteractionRequest, 'id'>, signal: AbortSignal): Promise<InteractionResponse> {
+    if (this.closed || !this.handler) return Promise.reject(new Error('interaction_unavailable'));
+    if (signal.aborted) return Promise.reject(new Error('tool_cancelled'));
+    return new Promise((resolve, reject) => {
+      const control = new AbortController();
+      const combined = AbortSignal.any([signal, control.signal]);
+      const pending: Pending = { request: structuredClone({ ...request, id: randomUUID() }), signal: combined, resolve, reject, control, cleanup: () => combined.removeEventListener('abort', abort) };
+      const abort = () => { this.finish(pending, undefined, new Error('tool_cancelled')); };
+      combined.addEventListener('abort', abort, { once: true });
+      this.queue.push(pending);
+      this.pump();
+    });
+  }
+
+  private pump() {
+    if (this.active || !this.handler || !this.queue.length) return;
+    const pending = this.active = this.queue[0]!;
+    const handler = this.handler;
+    void Promise.resolve().then(() => {
+      pending.signal.throwIfAborted();
+      return handler(structuredClone(pending.request), pending.signal);
+    }).then(value => {
+      if (this.active !== pending) return;
+      try { this.finish(pending, validateResponse(pending.request, value)); }
+      catch { this.finish(pending, undefined, new Error('invalid_interaction_response')); }
+    }, () => this.finish(pending, undefined, new Error('interaction_cancelled')));
+  }
+
+  private finish(pending: Pending, value?: InteractionResponse, error?: Error) {
+    const index = this.queue.indexOf(pending);
+    if (index < 0) return;
+    this.queue.splice(index, 1);
+    pending.cleanup();
+    if (this.active === pending) this.active = undefined;
+    // Close the renderer before showing another prompt, including abort races.
+    pending.control.abort();
+    if (error) pending.reject(error); else pending.resolve(value!);
+    queueMicrotask(() => this.pump());
+  }
+}
+
+/** @throws `invalid_arguments` when a question offers no way to answer or has duplicate option IDs. */
+export function validateQuestion(question: Question): void {
+  const options = question.options ?? [];
+  if ((!options.length && !question.allowFreeText) || new Set(options.map(o => o.id)).size !== options.length) throw new Error('invalid_arguments');
+}
+
+/** Validate a human response against the exact request it answers. */
+export function validateResponse(request: InteractionRequest, value: unknown): InteractionResponse {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('invalid_response');
+  const response = value as InteractionResponse;
+  if (response.id !== request.id) throw new Error('stale_response');
+  if (response.cancelled === true) return { id: request.id, cancelled: true };
+  if (request.kind === 'approval') {
+    if (typeof response.approved !== 'boolean') throw new Error('invalid_response');
+    return { id: request.id, approved: response.approved };
+  }
+  const selected = response.selected ?? [];
+  if (!Array.isArray(selected) || new Set(selected).size !== selected.length || selected.some(id => typeof id !== 'string' || !request.options?.some(o => o.id === id)) || (!request.multiSelect && selected.length > 1)) throw new Error('invalid_response');
+  if (response.text !== undefined && (typeof response.text !== 'string' || !request.allowFreeText || response.text.length > 2000)) throw new Error('invalid_response');
+  const text = response.text?.trim();
+  if (!selected.length && !text) throw new Error('empty_response');
+  return { id: request.id, selected, ...(text ? { text } : {}) };
+}

package/src/memory.ts

@@ -0,0 +1,42 @@
+import { lstatSync, realpathSync } from 'node:fs';
+import { isAbsolute, relative, resolve, sep } from 'node:path';
+import { INTERNAL_MEMORY_TOOLS } from './definition.js';
+
+const quote = (value: string) => `'${value.replaceAll("'", "'\\''")}'`;
+
+/**
+ * The only shell command the agent may run: commit Markdown changes in its own
+ * MemFS repository, with hooks disabled and a fixed author.
+ */
+export function memoryCommitCommand(root: string, author = 'ai-sdk-letta agent'): string {
+  const git = `git -c core.hooksPath=/dev/null -C ${quote(root)}`;
+  return `${git} add -- '*.md' && ${git} -c user.name=${quote(author.replace(/[\r\n]/g, ' '))} -c user.email='agent@localhost' commit -m 'Update agent memory'`;
+}
+
+/**
+ * Strict per-call permission for harness memory tools: own Markdown files only;
+ * no general shell, traversal, dot-files (including `.git`), symlinks or hard links.
+ */
+export function allowMemoryTool(name: string, input: Record<string, unknown>, root?: string, author?: string): boolean {
+  if (!root || !(INTERNAL_MEMORY_TOOLS as readonly string[]).includes(name)) return false;
+  if (name === 'Bash') return input.command === memoryCommitCommand(root, author) && !input.run_in_background;
+  if (typeof input.file_path !== 'string' || !isAbsolute(input.file_path) || !input.file_path.endsWith('.md')) return false;
+  try {
+    const canonicalRoot = realpathSync(root);
+    const path = resolve(input.file_path);
+    // Accept the backend-provided spelling (e.g. macOS /var -> /private/var)
+    // or its canonical spelling; inspect every component below the real root.
+    const rawSuffix = relative(resolve(root), path);
+    const suffix = !rawSuffix.startsWith(`..${sep}`) && rawSuffix !== '..' && !isAbsolute(rawSuffix) ? rawSuffix : relative(canonicalRoot, path);
+    if (!suffix || suffix.startsWith(`..${sep}`) || suffix === '..' || isAbsolute(suffix)) return false;
+    const parts = suffix.split(sep);
+    if (parts.some(part => part.startsWith('.'))) return false;
+    let current = canonicalRoot;
+    for (const part of parts) {
+      current = resolve(current, part);
+      try { const stat = lstatSync(current); if (stat.isSymbolicLink() || (stat.isFile() && stat.nlink > 1)) return false; }
+      catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') return false; }
+    }
+    return true;
+  } catch { return false; }
+}

package/src/navigation.ts

@@ -0,0 +1,84 @@
+import type { ListMessagesOptions, ListMessagesResult, LettaConversation } from '@letta-ai/letta-agent-sdk';
+import { loadHistory, projectHistory, sanitizeText } from './history.js';
+
+/** One row of a conversation picker. */
+export type ConversationEntry = { id: string; title: string; date: string };
+/** Read-only access to the current agent's conversations, used by pickers and search. */
+export type NavigationSource = {
+  agentId: string;
+  currentId: string;
+  list: (signal?: AbortSignal) => Promise<{ entries: ConversationEntry[]; limited: boolean }>;
+  page: (id: string, options: ListMessagesOptions) => Promise<ListMessagesResult>;
+  validate: (id: string, signal?: AbortSignal) => Promise<void>;
+};
+/** Newest conversations of one agent (up to 200 plus `default`), excluding archived ones. */
+export async function listNavigationEntries(list: (query: { agentId: string; limit: number; order: 'desc'; orderBy: 'createdAt'; after?: string }) => Promise<LettaConversation[]>, agentId: string, signal?: AbortSignal) {
+  const entries: ConversationEntry[] = [{ id: 'default', title: 'Default conversation', date: 'activity unavailable' }];
+  const seen = new Set<string>(['default']);
+  let after: string | undefined;
+  let limited = false;
+  for (let index = 0; index < 3; index++) {
+    signal?.throwIfAborted();
+    const page = await list({ agentId, limit: 100, order: 'desc', orderBy: 'createdAt', ...(after ? { after } : {}) });
+    signal?.throwIfAborted();
+    if (page.length > 100) throw new Error('Oversized conversation page');
+    if (!page.length) break;
+    for (const row of page) {
+      if (row.agent_id !== agentId || seen.has(row.id)) throw new Error('Conversation listing escaped current agent or repeated cursor');
+      seen.add(row.id);
+      if (index === 2) { limited = true; continue; }
+      if (!row.archived) entries.push({ id: row.id, title: sanitizeText(row.summary || 'Untitled conversation'), date: row.last_message_at || row.updated_at || row.created_at || 'activity unavailable' });
+    }
+    if (limited) break;
+    after = page.at(-1)!.id;
+  }
+  return { entries, limited };
+}
+
+export const SEARCH_CONVERSATIONS = 50;
+export const SEARCH_RECORDS = 500;
+export const SEARCH_TOTAL = 5000;
+export const SEARCH_MATCHES = 100;
+export const SEARCH_MILLISECONDS = 30_000;
+const plain = (text: string) => sanitizeText(text).replace(/\s+/g, ' ').trim();
+/** A short excerpt of `text` around the first match of `query`. */
+export function snippet(text: string, query: string) {
+  const clean = plain(text);
+  const at = clean.toLowerCase().indexOf(query.toLowerCase());
+  const start = Math.max(0, at - 65);
+  return `${start ? '…' : ''}${clean.slice(start, start + 220)}${clean.length > start + 220 ? '…' : ''}`;
+}
+export type SearchMatch = { conversation: ConversationEntry; role: string; snippet: string };
+/** Literal, case-insensitive text search. Only authoritative human/assistant text
+ * enters the projection: never tools, reasoning, system or memory records. */
+export async function searchConversations(source: NavigationSource, entries: ConversationEntry[], query: string, signal: AbortSignal, progress: (text: string) => void = () => {}) {
+  if (!query.trim() || query.length > 200) throw new Error('Search requires 1–200 characters');
+  const matches: SearchMatch[] = [];
+  let records = 0;
+  let scanned = 0;
+  let limited = entries.length > SEARCH_CONVERSATIONS;
+  const deadline = Date.now() + SEARCH_MILLISECONDS;
+  const check = () => { signal.throwIfAborted(); if (Date.now() >= deadline) throw new Error('Search deadline reached'); };
+  for (const conversation of entries.slice(0, SEARCH_CONVERSATIONS)) {
+    check();
+    if (records >= SEARCH_TOTAL || matches.length >= SEARCH_MATCHES) { limited = true; break; }
+    progress(`Searching ${scanned + 1}/${Math.min(entries.length, SEARCH_CONVERSATIONS)} · ${records} records · Esc cancels after current read`);
+    const history = await loadHistory(async options => {
+      check();
+      const page = await source.page(conversation.id, options);
+      check();
+      records += page.messages.length;
+      return page;
+    }, Math.min(SEARCH_RECORDS, SEARCH_TOTAL - records));
+    limited ||= history.truncated;
+    scanned++;
+    for (const message of projectHistory(history.messages, [], 0)) {
+      const text = message.parts.filter(p => p.type === 'text').map(p => p.text).join('\n');
+      if (plain(text).toLowerCase().includes(query.toLowerCase())) {
+        if (matches.length >= SEARCH_MATCHES) { limited = true; break; }
+        matches.push({ conversation, role: message.role, snippet: snippet(text, query) });
+      }
+    }
+  }
+  return { matches, records, scanned, limited };
+}

package/src/runtime.ts

@@ -0,0 +1,243 @@
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { LettaAgentClient, type LettaCodeClientSessionOptions, type LettaCodeSession, type LettaConversation, type SessionDeviceStatus } from '@letta-ai/letta-agent-sdk';
+import type { ToolSet } from 'ai';
+import { LettaAgent } from './agent.js';
+import { creationOptions, dreamingCommand, INTERNAL_MEMORY_TOOLS, type AgentDefinition } from './definition.js';
+import { acquireIdentity, validConversationId, type Identity } from './identity.js';
+import { assertHistorySettled, historyPage, listConversations, loadHistory, projectHistory, sanitizeText } from './history.js';
+import { allowMemoryTool, memoryCommitCommand } from './memory.js';
+import { listNavigationEntries, type NavigationSource } from './navigation.js';
+import { ToolInteractions } from './interactions.js';
+import { createToolBridge, fileTraceWriter, type ToolActivity, type ToolBridge } from './tools.js';
+import { resolveStateDirectory, statePaths } from './state.js';
+
+/** Which conversation to open. `null` means "open nothing" (for example, the user quit a picker). */
+export type ConversationChoice = { conversationId: string } | { newTitle: string } | null;
+
+/** Options for {@link openLettaAgent}. */
+export interface OpenAgentOptions {
+  /** State root; see {@link resolveStateDirectory}. */
+  stateDirectory?: string;
+  /** Open this conversation (`'default'` or a Letta conversation ID). */
+  conversationId?: string;
+  /** Create and open a new conversation with this title. */
+  newTitle?: string;
+  /** Interactive picker; takes precedence over `conversationId`/`newTitle`. */
+  choose?: (identity: Identity, conversations: LettaConversation[]) => Promise<ConversationChoice>;
+  /**
+   * Keep application tools in the foreground for up to five minutes. Without
+   * this, the Letta harness backgrounds a client tool after about 10 seconds,
+   * which breaks human approvals and questions. @default true
+   */
+  foregroundExternalTools?: boolean;
+  /** Tool audit trail: `true` writes private NDJSON under the state directory, or pass a sink. @default true */
+  traces?: boolean | ((event: ToolActivity) => void);
+}
+
+/** An opened agent plus the resources that belong to it. */
+export interface LettaRuntime<TOOLS extends ToolSet = ToolSet> {
+  agent: LettaAgent<TOOLS>;
+  identity: Identity;
+  /** Read-only conversation listing and search for the same agent. */
+  navigation: NavigationSource;
+  /** Close the session and SDK client, then release the identity lock. Idempotent. */
+  close(): Promise<void>;
+}
+
+const managementClient = (requestTimeoutMs?: number) => new LettaAgentClient({ backend: 'local', appServer: { harnessBackend: 'local', ...(requestTimeoutMs ? { requestTimeoutMs } : {}) } });
+
+/** Letta local backend directory used to key identity mappings. */
+export function localBackendDirectory(env: NodeJS.ProcessEnv = process.env): string {
+  return resolve(env.LETTA_LOCAL_BACKEND_DIR?.trim() || join(homedir(), '.letta', 'lc-local-backend'));
+}
+
+/** @throws unless the session is online, idle and has no queued or pending work. */
+export function assertIdle(status: SessionDeviceStatus): void {
+  if (status.isOnline !== true || status.isProcessing !== false || !Array.isArray(status.pendingControlRequests) || !status.raw || status.pendingControlRequests.length || (Array.isArray(status.raw.queue) && status.raw.queue.length) || (Array.isArray(status.raw.active_run_ids) && status.raw.active_run_ids.length)) throw new Error('Conversation has unfinished work or is offline; inspect backend before continuing (no retry/repair).');
+}
+
+/** Letta session options: application tools plus MemFS tools confined to the agent's memory. */
+export function sessionOptions(bridge: ToolBridge, getMemoryRoot: () => string | undefined, cwd: string, memoryAuthor?: string): LettaCodeClientSessionOptions {
+  return {
+    stateless: false, cwd,
+    toolset: { base: 'none', include: [...INTERNAL_MEMORY_TOOLS] },
+    allowedTools: [...bridge.allowedTools, ...INTERNAL_MEMORY_TOOLS], tools: bridge.tools,
+    permissionMode: 'strict', skillSources: [],
+    // Avoid the SDK convenience `dreaming` option; app-scoped settings are applied after ready().
+    canUseTool: async (name, input, context) => {
+      if ((INTERNAL_MEMORY_TOOLS as readonly string[]).includes(name)) {
+        const root = getMemoryRoot();
+        if (allowMemoryTool(name, input, root, memoryAuthor)) return { behavior: 'allow' };
+        return { behavior: 'deny', message: `Only own-memory Markdown operations are permitted.${root ? ` The only permitted Bash command is: ${memoryCommitCommand(root, memoryAuthor)}` : ''}` };
+      }
+      return bridge.canUseTool(name, input, context);
+    },
+  };
+}
+
+/**
+ * Runtime-scoped protocol command that keeps application tools in the
+ * foreground (no auto-backgrounding) with a five-minute timeout.
+ */
+export function foregroundToolsCommand(bridge: Pick<ToolBridge, 'tools'>, agentId: string, conversationId: string) {
+  return { type: 'runtime_external_tools_update', updates: [{
+    runtimes: [{ agent_id: agentId, conversation_id: conversationId }],
+    external_tools: [{ tools: bridge.tools.map(tool => ({ name: tool.name, label: tool.label, description: tool.description, parameters: tool.parameters, auto_background: false, timeout_ms: 300_000 })) }],
+  }] };
+}
+
+/** Open an agent, or throw if no conversation was selected. */
+export async function createLettaAgent<TOOLS extends ToolSet>(definition: AgentDefinition<TOOLS>, options: Omit<OpenAgentOptions, 'choose'> = {}): Promise<LettaRuntime<TOOLS>> {
+  const runtime = await openLettaAgent(definition, options);
+  if (!runtime) throw new Error('No conversation selected');
+  return runtime;
+}
+
+/**
+ * Open (creating on first use) the persistent Letta agent for a definition on
+ * the local Letta backend, and return a ready {@link LettaAgent}.
+ *
+ * Steps, each failing closed: acquire the identity lock and mapping; select or
+ * create a conversation; resume the session; verify it is idle and its history
+ * settled; restore display history; apply project-scoped dreaming and verify
+ * it; confirm MemFS. Returns `undefined` if `choose` returned `null`.
+ */
+export async function openLettaAgent<TOOLS extends ToolSet>(definition: AgentDefinition<TOOLS>, options: OpenAgentOptions = {}): Promise<LettaRuntime<TOOLS> | undefined> {
+  const paths = statePaths(resolveStateDirectory(options.stateDirectory));
+  const cwd = paths.agents;
+  const client = new LettaAgentClient({ backend: 'local', appServer: { harnessBackend: 'local', requestTimeoutMs: 180_000, startupTimeoutMs: 60_000 } });
+  let session: LettaCodeSession | undefined;
+  let release: (() => void) | undefined;
+  let interactions: ToolInteractions | undefined;
+  let closing: Promise<void> | undefined;
+  const close = () => closing ??= (async () => {
+    try { interactions?.close(); session?.close(); await client.close(); }
+    finally { release?.(); }
+  })();
+  try {
+    const backend = localBackendDirectory();
+    const lease = await acquireIdentity(cwd, definition, backend, {
+      create: async () => {
+        const models = await client.models.list();
+        if (!models.entries.some(model => model.handle === definition.model)) throw new Error(`Model "${definition.model}" is not available on the local Letta backend; connect its provider first`);
+        return client.createAgent(creationOptions(definition, cwd));
+      },
+      validate: async id => {
+        // Local management snapshots can predate createAgent's separate process.
+        const inspector = managementClient();
+        try {
+          const agent = await inspector.agents.retrieve(id);
+          if (agent.id !== id || agent.name !== definition.name) throw new Error('Mapped agent identity mismatch; refusing to recreate');
+          if (!agent.tags?.includes('git-memory-enabled')) throw new Error('Mapped agent has MemFS disabled; refusing to continue');
+        } finally { await inspector.close(); }
+      },
+    });
+    const { identity, selectConversation, createConversation, assertNoPendingTurn, beginTurn, completeTurn } = lease;
+    release = lease.release;
+    // A fresh management client sees agents created by the SDK's separate process.
+    const manager = managementClient();
+    let conversationId = identity.conversationId;
+    let conversationTitle = 'Default conversation';
+    try {
+      const choice: ConversationChoice = options.choose
+        ? await options.choose(identity, await listConversations(query => manager.conversations.list(query), identity.agentId))
+        : options.newTitle !== undefined ? { newTitle: options.newTitle } : { conversationId: options.conversationId ?? identity.conversationId };
+      if (choice === null) { await close(); return undefined; }
+      if ('newTitle' in choice) {
+        if (!choice.newTitle.trim() || choice.newTitle.length > 120) throw new Error('Conversation title must contain 1–120 characters');
+        conversationId = await createConversation(async agentId => {
+          const created = await manager.conversations.create({ agentId, summary: sanitizeText(choice.newTitle.trim()) });
+          if (created.agent_id !== agentId) throw new Error('Created conversation belongs to a different agent');
+          return created.id;
+        });
+      } else conversationId = choice.conversationId;
+      if (!validConversationId(conversationId)) throw new Error('Invalid conversation ID');
+      if (conversationId !== 'default') {
+        const conversation = await manager.conversations.retrieve(conversationId);
+        if (conversation.agent_id !== identity.agentId || conversation.archived) throw new Error('Conversation is archived or belongs to another agent');
+        conversationTitle = sanitizeText(conversation.summary ?? 'Untitled conversation');
+      }
+    } finally { await manager.close(); }
+    assertNoPendingTurn(conversationId);
+    let turnSignal: AbortSignal | undefined;
+    const broker = interactions = new ToolInteractions();
+    const persist = options.traces === false ? undefined : typeof options.traces === 'function' ? options.traces : fileTraceWriter(paths.traces);
+    // Background harness work must never open a prompt over an idle chat input.
+    const bridge = createToolBridge({
+      tools: definition.tools, permissions: definition.permissions, timeoutMs: definition.toolTimeoutMs, persist,
+      get interactions() { return turnSignal ? broker : undefined; }, get signal() { return turnSignal; },
+    });
+    let memoryRoot: string | undefined;
+    session = client.resumeSession(conversationId === 'default' ? identity.agentId : conversationId, sessionOptions(bridge, () => memoryRoot, cwd, definition.name));
+    const ready = await session.ready();
+    if (ready.agentId !== identity.agentId || ready.conversationId !== conversationId) throw new Error('Backend resumed a different identity/conversation');
+    assertIdle(await session.getDeviceStatus());
+    if (options.foregroundExternalTools !== false && bridge.tools.length) {
+      // The SDK's tools serializer drops auto_background/timeout_ms. Use the
+      // supported runtime-scoped protocol rather than global defaults.
+      const configured = await session.sendCommand(foregroundToolsCommand(bridge, ready.agentId, ready.conversationId), { responseType: 'runtime_external_tools_update_response' });
+      if (configured.success !== true) throw new Error('Unable to configure foreground interaction tools');
+    }
+    const live = session;
+    const history = await loadHistory(query => historyPage(live, identity.agentId, conversationId, query));
+    assertHistorySettled(history.messages);
+    const initialMessages = projectHistory(history.messages, Object.keys(definition.tools));
+    // The SDK's dreaming option writes global defaults. Use the protocol
+    // command with project scope (the private state cwd) instead.
+    const configured = await session.sendCommand(dreamingCommand(definition, ready.agentId, ready.conversationId), { responseType: 'set_reflection_settings_response' });
+    if (configured.success !== true) throw new Error('Unable to configure project-scoped dreaming');
+    const status = await session.getDeviceStatus();
+    if (!status.memoryDirectory) throw new Error('MemFS unavailable; refusing to run without memory');
+    const reflection = status.raw.reflection_settings as { trigger?: string; step_count?: number } | undefined;
+    if (reflection?.trigger !== definition.dreaming.trigger || reflection.step_count !== definition.dreaming.stepCount) throw new Error('Persistent dreaming configuration differs from the definition; inspect agent settings before continuing');
+    assertIdle(status);
+    memoryRoot = status.memoryDirectory;
+    selectConversation(conversationId);
+    // Navigation reads through this same mapped runtime; it never enumerates other agents.
+    let listedIds = new Set<string>(['default']);
+    const navigation: NavigationSource = {
+      agentId: identity.agentId, currentId: conversationId,
+      list: async signal => {
+        assertIdle(await live.getDeviceStatus());
+        const reader = managementClient(15_000);
+        try {
+          const result = await listNavigationEntries(query => reader.conversations.list(query), identity.agentId, signal);
+          listedIds = new Set(result.entries.map(entry => entry.id));
+          return result;
+        } finally { await reader.close(); }
+      },
+      page: async (id, pageOptions) => {
+        if (!listedIds.has(id)) throw new Error('Conversation outside current-agent listing');
+        return historyPage(live, identity.agentId, id, pageOptions, 10_000);
+      },
+      validate: async (id, signal) => {
+        if (!listedIds.has(id) || !validConversationId(id)) throw new Error('Conversation outside current-agent listing');
+        assertIdle(await live.getDeviceStatus());
+        assertNoPendingTurn(id);
+        const deadline = Date.now() + 30_000;
+        const loaded = await loadHistory(pageOptions => {
+          signal?.throwIfAborted();
+          if (Date.now() >= deadline) throw new Error('Selection validation deadline reached');
+          return historyPage(live, identity.agentId, id, pageOptions, 10_000);
+        });
+        signal?.throwIfAborted();
+        assertHistorySettled(loaded.messages);
+      },
+    };
+    const dreamingLine = definition.dreaming.trigger === 'off' ? 'Dreaming: off' : `Dreaming: ${reflection.trigger}${reflection.trigger === 'step-count' ? ` ${reflection.step_count}` : ''} configured (not evidence a dream ran)`;
+    const startupStatus = `${definition.name}\nLogical ID: ${definition.id}\nLetta ID: ${identity.agentId}\nConversation: ${conversationTitle} (${conversationId})\nStartup status: idle / ready · MemFS confirmed enabled\n${dreamingLine}\nHistory: ${initialMessages.length} visible records restored${history.truncated ? ' · LIMITED to newest 10,000 backend records; older history omitted' : ' · complete backend pagination'}`;
+    // Keep one session alive between turns so background dreaming can progress.
+    // LettaAgent closes only its per-turn wrapper, not this shared session.
+    const agent = new LettaAgent<TOOLS>({
+      id: definition.id, tools: definition.tools, memoryTools: INTERNAL_MEMORY_TOOLS, lettaAgentId: identity.agentId, modelId: definition.model, interactions: broker,
+      open: signal => {
+        turnSignal = signal;
+        return { send: message => live.send(message), stream: () => live.stream(), abort: () => live.abort(), close: () => { if (turnSignal === signal) turnSignal = undefined; } };
+      },
+      presentation: { conversationId, title: conversationTitle, initialMessages, status: startupStatus, memoryDirectory: memoryRoot, historyTruncated: history.truncated },
+      delivery: { begin: () => beginTurn(conversationId), complete: () => completeTurn(conversationId) },
+    });
+    return { agent, identity, navigation, close: async () => { agent.close(); await close(); } };
+  } catch (error) { await close(); throw error; }
+}

package/src/state.ts

@@ -0,0 +1,39 @@
+import { homedir } from 'node:os';
+import { isAbsolute, join, resolve } from 'node:path';
+
+/** Environment variable that overrides the state directory. */
+export const STATE_DIR_ENV = 'AI_SDK_LETTA_STATE_DIR';
+
+/**
+ * Resolve the root state directory.
+ *
+ * Order: explicit argument, `AI_SDK_LETTA_STATE_DIR`, then the platform state
+ * location: `$XDG_STATE_HOME/ai-sdk-letta` or `~/.local/state/ai-sdk-letta` on
+ * Linux and macOS, `%LOCALAPPDATA%\ai-sdk-letta\state` on Windows.
+ *
+ * The identity mapping lives in `<stateDir>/agents/`; point this at an
+ * existing directory to keep using an agent created earlier.
+ */
+export function resolveStateDirectory(explicit?: string, env: NodeJS.ProcessEnv = process.env, platform: NodeJS.Platform = process.platform, home = homedir()): string {
+  const chosen = explicit ?? env[STATE_DIR_ENV];
+  if (chosen !== undefined) {
+    if (!chosen.trim()) throw new Error('State directory must not be empty');
+    return resolve(chosen);
+  }
+  if (platform === 'win32') return join(env.LOCALAPPDATA ?? join(home, 'AppData', 'Local'), 'ai-sdk-letta', 'state');
+  const xdg = env.XDG_STATE_HOME;
+  return join(xdg && isAbsolute(xdg) ? xdg : join(home, '.local', 'state'), 'ai-sdk-letta');
+}
+
+/** Well-known subdirectories of a state root. */
+export function statePaths(root: string) {
+  return {
+    root,
+    /** Identity mappings, locks and pending-intent files; also the Letta session cwd. */
+    agents: join(root, 'agents'),
+    /** Metadata-only tool audit trail. */
+    traces: join(root, 'tool-traces'),
+    /** Per-definition HTTP runtime state (threads, runs). */
+    server: (definitionId: string) => join(root, 'server', definitionId),
+  };
+}