ai-sdk-letta 0.1.0

package/dist/navigation.js

@@ -0,0 +1,87 @@
+import { loadHistory, projectHistory, sanitizeText } from './history.js';
+/** Newest conversations of one agent (up to 200 plus `default`), excluding archived ones. */
+export async function listNavigationEntries(list, agentId, signal) {
+    const entries = [{ id: 'default', title: 'Default conversation', date: 'activity unavailable' }];
+    const seen = new Set(['default']);
+    let after;
+    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) => sanitizeText(text).replace(/\s+/g, ' ').trim();
+/** A short excerpt of `text` around the first match of `query`. */
+export function snippet(text, query) {
+    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 ? '…' : ''}`;
+}
+/** 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, entries, query, signal, progress = () => { }) {
+    if (!query.trim() || query.length > 200)
+        throw new Error('Search requires 1–200 characters');
+    const matches = [];
+    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 };
+}
+//# sourceMappingURL=navigation.js.map

package/dist/navigation.js.map

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

package/dist/runtime.d.ts

@@ -0,0 +1,83 @@
+import { type LettaCodeClientSessionOptions, type LettaConversation, type SessionDeviceStatus } from '@letta-ai/letta-agent-sdk';
+import type { ToolSet } from 'ai';
+import { LettaAgent } from './agent.js';
+import { type AgentDefinition } from './definition.js';
+import { type Identity } from './identity.js';
+import { type NavigationSource } from './navigation.js';
+import { type ToolActivity, type ToolBridge } from './tools.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>;
+}
+/** Letta local backend directory used to key identity mappings. */
+export declare function localBackendDirectory(env?: NodeJS.ProcessEnv): string;
+/** @throws unless the session is online, idle and has no queued or pending work. */
+export declare function assertIdle(status: SessionDeviceStatus): void;
+/** Letta session options: application tools plus MemFS tools confined to the agent's memory. */
+export declare function sessionOptions(bridge: ToolBridge, getMemoryRoot: () => string | undefined, cwd: string, memoryAuthor?: string): LettaCodeClientSessionOptions;
+/**
+ * Runtime-scoped protocol command that keeps application tools in the
+ * foreground (no auto-backgrounding) with a five-minute timeout.
+ */
+export declare function foregroundToolsCommand(bridge: Pick<ToolBridge, 'tools'>, agentId: string, conversationId: string): {
+    type: string;
+    updates: {
+        runtimes: {
+            agent_id: string;
+            conversation_id: string;
+        }[];
+        external_tools: {
+            tools: {
+                name: string;
+                label: string;
+                description: string;
+                parameters: any;
+                auto_background: boolean;
+                timeout_ms: number;
+            }[];
+        }[];
+    }[];
+};
+/** Open an agent, or throw if no conversation was selected. */
+export declare function createLettaAgent<TOOLS extends ToolSet>(definition: AgentDefinition<TOOLS>, options?: Omit<OpenAgentOptions, 'choose'>): Promise<LettaRuntime<TOOLS>>;
+/**
+ * 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 declare function openLettaAgent<TOOLS extends ToolSet>(definition: AgentDefinition<TOOLS>, options?: OpenAgentOptions): Promise<LettaRuntime<TOOLS> | undefined>;
+//# sourceMappingURL=runtime.d.ts.map

package/dist/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAEA,OAAO,EAAoB,KAAK,6BAA6B,EAAyB,KAAK,iBAAiB,EAAE,KAAK,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAC1K,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,IAAI,CAAC;AAClC,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EAA2D,KAAK,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAChH,OAAO,EAAwC,KAAK,QAAQ,EAAE,MAAM,eAAe,CAAC;AAGpF,OAAO,EAAyB,KAAK,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAE/E,OAAO,EAAqC,KAAK,YAAY,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAGnG,qGAAqG;AACrG,MAAM,MAAM,kBAAkB,GAAG;IAAE,cAAc,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAAC;AAE1F,0CAA0C;AAC1C,MAAM,WAAW,gBAAgB;IAC/B,qDAAqD;IACrD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,uEAAuE;IACvE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,0DAA0D;IAC1D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6EAA6E;IAC7E,MAAM,CAAC,EAAE,CAAC,QAAQ,EAAE,QAAQ,EAAE,aAAa,EAAE,iBAAiB,EAAE,KAAK,OAAO,CAAC,kBAAkB,CAAC,CAAC;IACjG;;;;OAIG;IACH,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAClC,8GAA8G;IAC9G,MAAM,CAAC,EAAE,OAAO,GAAG,CAAC,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAAC,CAAC;CACpD;AAED,4DAA4D;AAC5D,MAAM,WAAW,YAAY,CAAC,KAAK,SAAS,OAAO,GAAG,OAAO;IAC3D,KAAK,EAAE,UAAU,CAAC,KAAK,CAAC,CAAC;IACzB,QAAQ,EAAE,QAAQ,CAAC;IACnB,oEAAoE;IACpE,UAAU,EAAE,gBAAgB,CAAC;IAC7B,oFAAoF;IACpF,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAID,mEAAmE;AACnE,wBAAgB,qBAAqB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAElF;AAED,oFAAoF;AACpF,wBAAgB,UAAU,CAAC,MAAM,EAAE,mBAAmB,GAAG,IAAI,CAE5D;AAED,gGAAgG;AAChG,wBAAgB,cAAc,CAAC,MAAM,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,MAAM,GAAG,SAAS,EAAE,GAAG,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,6BAA6B,CAgB7J;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,IAAI,CAAC,UAAU,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM;;;;;;;;;;;;;;;;;;EAKhH;AAED,+DAA+D;AAC/D,wBAAsB,gBAAgB,CAAC,KAAK,SAAS,OAAO,EAAE,UAAU,EAAE,eAAe,CAAC,KAAK,CAAC,EAAE,OAAO,GAAE,IAAI,CAAC,gBAAgB,EAAE,QAAQ,CAAM,GAAG,OAAO,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAI9K;AAED;;;;;;;;GAQG;AACH,wBAAsB,cAAc,CAAC,KAAK,SAAS,OAAO,EAAE,UAAU,EAAE,eAAe,CAAC,KAAK,CAAC,EAAE,OAAO,GAAE,gBAAqB,GAAG,OAAO,CAAC,YAAY,CAAC,KAAK,CAAC,GAAG,SAAS,CAAC,CAyIxK"}

package/dist/runtime.js

@@ -0,0 +1,246 @@
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { LettaAgentClient } from '@letta-ai/letta-agent-sdk';
+import { LettaAgent } from './agent.js';
+import { creationOptions, dreamingCommand, INTERNAL_MEMORY_TOOLS } from './definition.js';
+import { acquireIdentity, validConversationId } from './identity.js';
+import { assertHistorySettled, historyPage, listConversations, loadHistory, projectHistory, sanitizeText } from './history.js';
+import { allowMemoryTool, memoryCommitCommand } from './memory.js';
+import { listNavigationEntries } from './navigation.js';
+import { ToolInteractions } from './interactions.js';
+import { createToolBridge, fileTraceWriter } from './tools.js';
+import { resolveStateDirectory, statePaths } from './state.js';
+const managementClient = (requestTimeoutMs) => new LettaAgentClient({ backend: 'local', appServer: { harnessBackend: 'local', ...(requestTimeoutMs ? { requestTimeoutMs } : {}) } });
+/** Letta local backend directory used to key identity mappings. */
+export function localBackendDirectory(env = process.env) {
+    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) {
+    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, getMemoryRoot, cwd, memoryAuthor) {
+    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.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, agentId, conversationId) {
+    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(definition, options = {}) {
+    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(definition, options = {}) {
+    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;
+    let release;
+    let interactions;
+    let closing;
+    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 = 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;
+        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;
+        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;
+        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(['default']);
+        const navigation = {
+            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({
+            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;
+    }
+}
+//# sourceMappingURL=runtime.js.map

package/dist/runtime.js.map

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

package/dist/state.d.ts

@@ -0,0 +1,24 @@
+/** Environment variable that overrides the state directory. */
+export declare 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 declare function resolveStateDirectory(explicit?: string, env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform, home?: string): string;
+/** Well-known subdirectories of a state root. */
+export declare function statePaths(root: string): {
+    root: string;
+    /** Identity mappings, locks and pending-intent files; also the Letta session cwd. */
+    agents: string;
+    /** Metadata-only tool audit trail. */
+    traces: string;
+    /** Per-definition HTTP runtime state (threads, runs). */
+    server: (definitionId: string) => string;
+};
+//# sourceMappingURL=state.d.ts.map

package/dist/state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../src/state.ts"],"names":[],"mappings":"AAGA,+DAA+D;AAC/D,eAAO,MAAM,aAAa,2BAA2B,CAAC;AAEtD;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,GAAG,GAAE,MAAM,CAAC,UAAwB,EAAE,QAAQ,GAAE,MAAM,CAAC,QAA2B,EAAE,IAAI,SAAY,GAAG,MAAM,CASrK;AAED,iDAAiD;AACjD,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM;;IAGnC,qFAAqF;;IAErF,sCAAsC;;IAEtC,yDAAyD;2BAClC,MAAM;EAEhC"}

package/dist/state.js

@@ -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, env = process.env, platform = process.platform, home = homedir()) {
+    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) {
+    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) => join(root, 'server', definitionId),
+    };
+}
+//# sourceMappingURL=state.js.map

package/dist/state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.js","sourceRoot":"","sources":["../src/state.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEtD,+DAA+D;AAC/D,MAAM,CAAC,MAAM,aAAa,GAAG,wBAAwB,CAAC;AAEtD;;;;;;;;;GASG;AACH,MAAM,UAAU,qBAAqB,CAAC,QAAiB,EAAE,MAAyB,OAAO,CAAC,GAAG,EAAE,WAA4B,OAAO,CAAC,QAAQ,EAAE,IAAI,GAAG,OAAO,EAAE;IAC3J,MAAM,MAAM,GAAG,QAAQ,IAAI,GAAG,CAAC,aAAa,CAAC,CAAC;IAC9C,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE;YAAE,MAAM,IAAI,KAAK,CAAC,mCAAmC,CAAC,CAAC;QACzE,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC;IACzB,CAAC;IACD,IAAI,QAAQ,KAAK,OAAO;QAAE,OAAO,IAAI,CAAC,GAAG,CAAC,YAAY,IAAI,IAAI,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,cAAc,EAAE,OAAO,CAAC,CAAC;IACnH,MAAM,GAAG,GAAG,GAAG,CAAC,cAAc,CAAC;IAC/B,OAAO,IAAI,CAAC,GAAG,IAAI,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,CAAC,EAAE,cAAc,CAAC,CAAC;AAC5F,CAAC;AAED,iDAAiD;AACjD,MAAM,UAAU,UAAU,CAAC,IAAY;IACrC,OAAO;QACL,IAAI;QACJ,qFAAqF;QACrF,MAAM,EAAE,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC;QAC5B,sCAAsC;QACtC,MAAM,EAAE,IAAI,CAAC,IAAI,EAAE,aAAa,CAAC;QACjC,yDAAyD;QACzD,MAAM,EAAE,CAAC,YAAoB,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,EAAE,YAAY,CAAC;KACrE,CAAC;AACJ,CAAC"}

package/dist/tools.d.ts

@@ -0,0 +1,83 @@
+import { type Tool, type ToolSet } from 'ai';
+import type { AnyAgentTool } from '@letta-ai/letta-agent-sdk';
+import { type Question, type ToolInteractions } from './interactions.js';
+import type { ToolPermission } from './definition.js';
+/** Name of the built-in human question tool. */
+export declare const ASK_USER_TOOL = "ask_user";
+/**
+ * Built-in tool that lets the agent ask the human a structured question
+ * mid-turn. Add it to a definition's tools as `ask_user: askUserTool`.
+ * The answer is supplied by the connected interaction renderer.
+ */
+/** Result of `ask_user`, as returned to the agent. */
+export type AskUserResult = {
+    cancelled: boolean;
+    selected?: string[];
+    text?: string;
+};
+export declare const askUserTool: Tool<Question, AskUserResult>;
+/** Metadata-only audit event. Never contains arguments, outputs or raw call IDs. */
+export type ToolActivity = {
+    type: 'tool';
+    sessionId: string;
+    callId: string;
+    tool: string;
+    status: 'start' | 'completion' | 'error' | 'denied' | 'approved' | 'cancelled';
+    durationMs: number;
+    code?: string;
+    at: string;
+};
+/** Append-only, private (0600) daily NDJSON trace writer. */
+export declare function fileTraceWriter(directory: string): (event: ToolActivity) => void;
+/** Options for {@link createToolBridge}. */
+export interface ToolBridgeOptions {
+    /** AI SDK tools available to the agent. */
+    tools: ToolSet;
+    /** Permission per tool. Tools without an entry, or with `'deny'`, are never exposed. */
+    permissions: Readonly<Record<string, ToolPermission>>;
+    /** Further restrict exposure to these names (intersection). Defaults to every permitted tool. */
+    allowedTools?: readonly string[];
+    /** Aborts every in-flight call (for example, when the turn is cancelled). */
+    signal?: AbortSignal;
+    /** Human interaction broker. Without it, `ask` tools and `ask_user` fail closed. */
+    interactions?: ToolInteractions;
+    /** Per-call execution deadline in ms, excluding human waits. @default 5000 */
+    timeoutMs?: number;
+    /** Audit sink; see {@link fileTraceWriter}. @default no persistence */
+    persist?: (event: ToolActivity) => void;
+    /** Observer for audit events. */
+    onTool?: (event: ToolActivity) => void;
+}
+type ToolOutput = {
+    content: {
+        type: 'text';
+        text: string;
+    }[];
+    isError: boolean;
+};
+/**
+ * Map AI SDK tools onto Letta client-side tools with a fail-closed policy:
+ * schema validation before anything else, exactly-once execution per call ID,
+ * per-call approval bound to a snapshot of the arguments, deadlines,
+ * cancellation, bounded output and sanitized errors.
+ */
+export declare function createToolBridge(options: ToolBridgeOptions): {
+    /** Letta client-tool descriptors. */
+    tools: AnyAgentTool[];
+    /** Names exposed to the agent. */
+    allowedTools: string[];
+    /** Execute one call through the full policy. */
+    execute: (name: string, id: string, args: unknown, sdkSignal?: AbortSignal) => Promise<ToolOutput>;
+    /** Letta `canUseTool` hook: allow only exposed tools with valid arguments. */
+    canUseTool: (name: string, input?: Record<string, unknown>, _context?: unknown) => Promise<{
+        behavior: "allow";
+        message?: undefined;
+    } | {
+        behavior: "deny";
+        message: string;
+    }>;
+};
+/** Return type of {@link createToolBridge}. */
+export type ToolBridge = ReturnType<typeof createToolBridge>;
+export {};
+//# sourceMappingURL=tools.d.ts.map

package/dist/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAA8B,KAAK,IAAI,EAAE,KAAK,OAAO,EAAE,MAAM,IAAI,CAAC;AAEzE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAI9D,OAAO,EAAoB,KAAK,QAAQ,EAAE,KAAK,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAC3F,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEtD,gDAAgD;AAChD,eAAO,MAAM,aAAa,aAAa,CAAC;AAExC;;;;GAIG;AACH,sDAAsD;AACtD,MAAM,MAAM,aAAa,GAAG;IAAE,SAAS,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvF,eAAO,MAAM,WAAW,EAAE,IAAI,CAAC,QAAQ,EAAE,aAAa,CAKpD,CAAC;AAEH,oFAAoF;AACpF,MAAM,MAAM,YAAY,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,OAAO,GAAG,YAAY,GAAG,OAAO,GAAG,QAAQ,GAAG,UAAU,GAAG,WAAW,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC;AAE5N,6DAA6D;AAC7D,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAUhF;AAED,4CAA4C;AAC5C,MAAM,WAAW,iBAAiB;IAChC,2CAA2C;IAC3C,KAAK,EAAE,OAAO,CAAC;IACf,wFAAwF;IACxF,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC,CAAC;IACtD,iGAAiG;IACjG,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,6EAA6E;IAC7E,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,oFAAoF;IACpF,YAAY,CAAC,EAAE,gBAAgB,CAAC;IAChC,8EAA8E;IAC9E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,uEAAuE;IACvE,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAAC;IACxC,iCAAiC;IACjC,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAAC;CACxC;AAED,KAAK,UAAU,GAAG;IAAE,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC;AAElF;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,iBAAiB;IA8EvD,qCAAqC;;IAErC,kCAAkC;;IAElC,gDAAgD;oBA1DrB,MAAM,MAAM,MAAM,QAAQ,OAAO,cAAc,WAAW,KAAG,OAAO,CAAC,UAAU,CAAC;IA4D3G,8EAA8E;uBACrD,MAAM,UAAU,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,aAAa,OAAO;;;;;;;EAMvF;AAED,+CAA+C;AAC/C,MAAM,MAAM,UAAU,GAAG,UAAU,CAAC,OAAO,gBAAgB,CAAC,CAAC"}