ai-sdk-letta 0.1.0

package/dist/tools.js

@@ -0,0 +1,162 @@
+import { tool, jsonSchema, asSchema } from 'ai';
+import { Ajv } from 'ajv';
+import { appendFileSync, mkdirSync, chmodSync, lstatSync } from 'node:fs';
+import { join } from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+import { validateQuestion } from './interactions.js';
+/** Name of the built-in human question tool. */
+export const ASK_USER_TOOL = 'ask_user';
+export const askUserTool = tool({
+    description: 'Ask a structured question during this turn. Supply choices and/or allowFreeText. User can cancel. Ordinary conversational clarification can instead use normal assistant text.',
+    inputSchema: jsonSchema({ type: 'object', properties: { question: { type: 'string', minLength: 1, maxLength: 1000 }, options: { type: 'array', maxItems: 12, items: { type: 'object', properties: { id: { type: 'string', pattern: '^[a-zA-Z0-9_-]{1,40}$' }, label: { type: 'string', minLength: 1, maxLength: 200 } }, required: ['id', 'label'], additionalProperties: false } }, allowFreeText: { type: 'boolean' }, multiSelect: { type: 'boolean' } }, required: ['question'], additionalProperties: false }),
+    // The bridge answers this tool through the interaction broker; this handler never runs.
+    execute: async (_question) => { throw new Error('interaction_unavailable'); },
+});
+/** Append-only, private (0600) daily NDJSON trace writer. */
+export function fileTraceWriter(directory) {
+    return event => {
+        mkdirSync(directory, { recursive: true, mode: 0o700 });
+        if (lstatSync(directory).isSymbolicLink())
+            throw new Error('unsafe_trace_directory');
+        chmodSync(directory, 0o700);
+        const file = join(directory, `${event.at.slice(0, 10)}.ndjson`);
+        try {
+            if (lstatSync(file).isSymbolicLink())
+                throw new Error('unsafe_trace_file');
+        }
+        catch (e) {
+            if (e.code !== 'ENOENT')
+                throw e;
+        }
+        appendFileSync(file, `${JSON.stringify(event)}\n`, { mode: 0o600 });
+        chmodSync(file, 0o600);
+    };
+}
+/**
+ * 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 function createToolBridge(options) {
+    const definitions = options.tools;
+    const permissions = options.permissions;
+    const restrict = options.allowedTools ? new Set(options.allowedTools) : undefined;
+    const allowed = new Set(Object.keys(definitions).filter(n => (!restrict || restrict.has(n)) && Object.hasOwn(permissions, n) && (permissions[n] === 'allow' || permissions[n] === 'ask') && (n === ASK_USER_TOOL || typeof definitions[n]?.execute === 'function')));
+    const sessionId = randomUUID();
+    const seen = new Set();
+    const validators = new Map();
+    const ajv = new Ajv({ strict: false, allErrors: false });
+    const validateArguments = async (name, args) => {
+        try {
+            let validate = validators.get(name);
+            if (!validate) {
+                validate = ajv.compile(await asSchema(definitions[name].inputSchema).jsonSchema);
+                validators.set(name, validate);
+            }
+            if (!validate(args))
+                return false;
+            if (name === ASK_USER_TOOL)
+                validateQuestion(args);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    };
+    const emit = (name, id, status, started, code) => {
+        const event = { type: 'tool', sessionId, callId: createHash('sha256').update(id).digest('hex').slice(0, 24), tool: Object.hasOwn(definitions, name) ? name : 'unknown', status, durationMs: Math.max(0, Date.now() - started), at: new Date().toISOString(), ...(code ? { code } : {}) };
+        options.persist?.(event);
+        options.onTool?.(event);
+    };
+    const denied = (name, id, code) => { emit(name, id, 'denied', Date.now(), code); return { content: [{ type: 'text', text: JSON.stringify({ error: code }) }], isError: true }; };
+    const execute = async (name, id, args, sdkSignal) => {
+        if (!allowed.has(name))
+            return denied(name, id, 'tool_denied');
+        if (seen.has(id) || seen.size >= 100)
+            return denied(name, id, 'duplicate_or_limit');
+        seen.add(id);
+        const definition = definitions[name];
+        // Snapshot before any await; caller mutation cannot change an approved call.
+        try {
+            args = structuredClone(args);
+        }
+        catch {
+            return denied(name, id, 'invalid_arguments');
+        }
+        const control = new AbortController();
+        const signal = AbortSignal.any([control.signal, ...[options.signal, sdkSignal].filter((s) => !!s)]);
+        if (!await validateArguments(name, args))
+            return denied(name, id, 'invalid_arguments');
+        const started = Date.now();
+        if (permissions[name] === 'ask' || name === ASK_USER_TOOL) {
+            try {
+                signal.throwIfAborted();
+                if (!options.interactions)
+                    return denied(name, id, 'interaction_unavailable');
+                if (permissions[name] === 'ask') {
+                    const answer = await options.interactions.request({ kind: 'approval', toolCallId: id, tool: name, title: `Approve ${name}?`, details: JSON.stringify(args) }, signal);
+                    signal.throwIfAborted();
+                    if (answer.approved !== true)
+                        return denied(name, id, answer.cancelled ? 'approval_cancelled' : 'user_denied');
+                    emit(name, id, 'approved', started, 'approved_once');
+                }
+                if (name === ASK_USER_TOOL) {
+                    const question = args;
+                    const answer = await options.interactions.request({ kind: 'question', toolCallId: id, tool: name, title: question.question, options: question.options, allowFreeText: question.allowFreeText, multiSelect: question.multiSelect }, signal);
+                    signal.throwIfAborted();
+                    const output = answer.cancelled ? { cancelled: true } : { cancelled: false, selected: answer.selected ?? [], ...(answer.text ? { text: answer.text } : {}) };
+                    emit(name, id, answer.cancelled ? 'cancelled' : 'completion', started, answer.cancelled ? 'user_cancelled' : 'answered');
+                    return { content: [{ type: 'text', text: JSON.stringify(output) }], isError: false };
+                }
+            }
+            catch {
+                return denied(name, id, signal.aborted ? 'tool_cancelled' : 'interaction_unavailable');
+            }
+        }
+        emit(name, id, 'start', started, permissions[name] === 'ask' ? 'approved_once' : 'static_allow');
+        let timer;
+        let abort;
+        try {
+            signal.throwIfAborted();
+            const interrupted = new Promise((_, reject) => {
+                abort = () => reject(new Error(control.signal.aborted ? 'tool_timeout' : 'tool_cancelled'));
+                signal.addEventListener('abort', abort, { once: true });
+                timer = setTimeout(() => control.abort(), options.timeoutMs ?? 5000);
+            });
+            const output = await Promise.race([Promise.resolve().then(() => { signal.throwIfAborted(); return definition.execute(args, { toolCallId: id, messages: [], abortSignal: signal }); }), interrupted]);
+            const text = JSON.stringify(output);
+            if (typeof text !== 'string' || text.length > 16000)
+                throw new Error('tool_output_limit');
+            emit(name, id, 'completion', started);
+            return { content: [{ type: 'text', text }], isError: false };
+        }
+        catch {
+            const code = signal.aborted ? (control.signal.aborted ? 'tool_timeout' : 'tool_cancelled') : 'tool_failed';
+            emit(name, id, 'error', started, code);
+            return { content: [{ type: 'text', text: JSON.stringify({ error: code }) }], isError: true };
+        }
+        finally {
+            clearTimeout(timer);
+            if (abort)
+                signal.removeEventListener('abort', abort);
+        }
+    };
+    const tools = [...allowed].map(name => ({ name, label: name, description: definitions[name].description ?? name, parameters: asSchema(definitions[name].inputSchema).jsonSchema, execute: (id, args, signal) => execute(name, id, args, signal) }));
+    return {
+        /** Letta client-tool descriptors. */
+        tools,
+        /** Names exposed to the agent. */
+        allowedTools: [...allowed],
+        /** Execute one call through the full policy. */
+        execute,
+        /** Letta `canUseTool` hook: allow only exposed tools with valid arguments. */
+        canUseTool: async (name, input, _context) => {
+            if (allowed.has(name) && (input === undefined || await validateArguments(name, input)))
+                return { behavior: 'allow' };
+            denied(name, randomUUID(), 'permission_denied');
+            return { behavior: 'deny', message: 'Tool not allowed by this session.' };
+        },
+    };
+}
+//# sourceMappingURL=tools.js.map

package/dist/tools.js.map

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

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "ai-sdk-letta",
+  "version": "0.1.0",
+  "description": "A persistent, Letta-backed Vercel AI SDK Agent with memory, dreaming, application-owned tools and human-in-the-loop.",
+  "license": "Apache-2.0",
+  "author": "Leonard Schneider",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/leonardschneider/ai-sdk-letta.git",
+    "directory": "packages/ai-sdk-letta"
+  },
+  "homepage": "https://github.com/leonardschneider/ai-sdk-letta#readme",
+  "bugs": {
+    "url": "https://github.com/leonardschneider/ai-sdk-letta/issues"
+  },
+  "keywords": [
+    "ai",
+    "ai-sdk",
+    "vercel",
+    "letta",
+    "agent",
+    "memory",
+    "stateful-agents",
+    "human-in-the-loop",
+    "tools"
+  ],
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "ai-sdk-letta-source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "CHANGELOG.md",
+    "NOTICE"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit -p .",
+    "test": "node --conditions=ai-sdk-letta-source --import tsx --test test/*.test.ts",
+    "test:live": "node --conditions=ai-sdk-letta-source --import tsx --test --test-concurrency=1 test/live/*.test.ts",
+    "prepack": "node ../../scripts/check-dist.mjs"
+  },
+  "dependencies": {
+    "@letta-ai/letta-agent-sdk": "0.8.22",
+    "ajv": "^8.20.0"
+  },
+  "peerDependencies": {
+    "ai": "^7.0.118"
+  },
+  "devDependencies": {
+    "@ai-sdk/provider": "4.0.18",
+    "ai": "7.0.118"
+  }
+}

package/src/agent.ts

@@ -0,0 +1,334 @@
+import { generateText, streamText, stepCountIs, type Agent, type AgentCallParameters, type AgentStreamParameters, type ModelMessage, type ToolSet, type UIMessage } from 'ai';
+import type { JSONValue, LanguageModelV4, LanguageModelV4StreamPart, LanguageModelV4Usage } from '@ai-sdk/provider';
+import type { LettaCodeSession, MessageContentItem, SendMessage } from '@letta-ai/letta-agent-sdk';
+import { ToolInteractions } from './interactions.js';
+import { assertImageBudget, compactImagePart, decodeImagePart, imagePartDigest, ImageInputError, isImagePart, toLettaImage, type DecodedImage } from './images.js';
+
+/** Most characters of text in one user turn. */
+export const MAX_INPUT_CHARACTERS = 8000;
+
+/** The subset of a Letta session a turn needs. */
+export type TurnSession = Pick<LettaCodeSession, 'send' | 'stream' | 'abort' | 'close'>;
+
+/** Display-only state restored when the agent was opened. Never sent to the model. */
+export interface AgentPresentation {
+  conversationId: string;
+  title: string;
+  /** Projected backend history for display (text and completed application tool cards). */
+  initialMessages: UIMessage[];
+  /** Human-readable startup summary. */
+  status: string;
+  memoryDirectory: string;
+  historyTruncated: boolean;
+}
+
+/** Durable delivery hooks: `begin` before sending, `complete` after a confirmed finish. */
+export interface DeliveryHooks { begin(): void; complete(): void }
+
+/** Options for constructing a {@link LettaAgent} directly (normally done by `openLettaAgent`). */
+export interface LettaAgentOptions<TOOLS extends ToolSet> {
+  /** Logical definition ID. */
+  id: string;
+  tools: TOOLS;
+  /** Opens a per-turn view of the (long-lived) Letta session. */
+  open: (signal: AbortSignal) => TurnSession;
+  /** Harness tool names hidden from AI SDK results (MemFS operations). */
+  memoryTools?: readonly string[];
+  /** Letta-generated agent ID. */
+  lettaAgentId?: string;
+  /** Model handle reported as `modelId` on results. */
+  modelId?: string;
+  presentation?: AgentPresentation;
+  delivery?: DeliveryHooks;
+  interactions?: ToolInteractions;
+}
+
+type Call<TOOLS extends ToolSet> = AgentCallParameters<never, TOOLS>;
+const usage = (): LanguageModelV4Usage => ({ inputTokens: { total: undefined, noCache: undefined, cacheRead: undefined, cacheWrite: undefined }, outputTokens: { total: undefined, text: undefined, reasoning: undefined } });
+
+/**
+ * Canonical key of a semantic transcript (text, user images and completed tool
+ * calls), ignoring SDK metadata and step boundaries. Used to reject replayed or
+ * edited history: a new call must extend exactly what this process already
+ * sent. Images are compared by a SHA-256 of their bytes, so a transcript may
+ * carry either the image data or a compact reference to it.
+ */
+export function historyKey(messages: ModelMessage[]): string {
+  const parts: unknown[] = [];
+  for (const message of messages) {
+    if (message.role === 'system') throw new Error('System messages are not supported');
+    const content = typeof message.content === 'string' ? [{ type: 'text' as const, text: message.content }] : message.content;
+    for (const part of content) {
+      if (part.type === 'text') {
+        const last = parts.at(-1) as { role?: string; text?: string } | undefined;
+        if (last?.role === message.role && typeof last.text === 'string') last.text += part.text;
+        else parts.push({ role: message.role, text: part.text });
+      } else if (message.role === 'user' && isImagePart(part)) {
+        // A boundary like text: an image between two texts is not the same turn as the joined text.
+        parts.push({ role: message.role, text: null, image: imagePartDigest(part) });
+      } else if (part.type === 'tool-call' && message.role === 'assistant') {
+        parts.push({ call: part.toolCallId, name: part.toolName, input: part.input });
+      } else if (part.type === 'tool-result' && (message.role === 'assistant' || message.role === 'tool')) {
+        // UI error cards stringify provider error objects; conversion returns an
+        // error-json string whereas response.messages retains the original JSON.
+        // Normalize only error payloads, never successful text/JSON outputs.
+        let output = part.output;
+        if (output.type === 'error-json' && typeof output.value === 'string') {
+          try { output = { ...output, value: JSON.parse(output.value) }; } catch { /* plain error text */ }
+        }
+        parts.push({ result: part.toolCallId, name: part.toolName, output });
+      } else throw new Error('Only text, user image and completed application tool history are supported');
+    }
+  }
+  // Parallel calls arrive call/call/result/result, while UI cards convert as
+  // call/result/call/result. Canonicalize contiguous tool groups only; retain
+  // every ID, name, input and output and all text/turn boundaries.
+  const canonical: unknown[] = [];
+  let tools: unknown[] = [];
+  const flush = () => {
+    tools.sort((a, b) => {
+      const key = (value: unknown) => { const p = value as { call?: string; result?: string }; return `${p.call ?? p.result}\u0000${p.call ? '0' : '1'}`; };
+      return key(a).localeCompare(key(b));
+    });
+    canonical.push(...tools); tools = [];
+  };
+  for (const part of parts) {
+    if ('text' in (part as object)) { flush(); canonical.push(part); }
+    else tools.push(part);
+  }
+  flush();
+  return JSON.stringify(canonical);
+}
+
+/** Replace user image data with content-hash references so the retained transcript never duplicates image bytes. */
+function compactTranscript(messages: ModelMessage[]): ModelMessage[] {
+  return messages.map(message => message.role === 'user' && typeof message.content !== 'string'
+    ? { ...message, content: message.content.map(part => isImagePart(part) ? compactImagePart(part) : part) }
+    : message);
+}
+
+/**
+ * Validate the new user turn and build the single Letta message to send:
+ * a plain string for text-only turns, or text and `ImageContent` items in
+ * their original order.
+ * @throws {ImageInputError} for unsupported, invalid or oversized images
+ */
+export function userTurnContent(content: ModelMessage['content']): { message: SendMessage; text: string; images: DecodedImage[] } {
+  const parts = typeof content === 'string' ? [{ type: 'text' as const, text: content }] : content;
+  if (!Array.isArray(parts)) throw new Error('Expected a new user turn');
+  const items: MessageContentItem[] = [];
+  const images: DecodedImage[] = [];
+  for (const part of parts) {
+    if (part.type === 'text') {
+      const last = items.at(-1);
+      if (last?.type === 'text') last.text += part.text;
+      else items.push({ type: 'text', text: part.text });
+    } else if (isImagePart(part)) {
+      const image = decodeImagePart(part);
+      images.push(image);
+      assertImageBudget(images);
+      items.push(toLettaImage(image));
+    } else if (part.type === 'file') {
+      throw new ImageInputError('image_unsupported_type', `Unsupported attachment type ${String(part.mediaType) || 'unknown'}; only PNG, JPEG, GIF and WebP images are supported`);
+    } else throw new Error('Only text and image input is supported');
+  }
+  const text = items.map(item => item.type === 'text' ? item.text : '').join('');
+  if (text.length > MAX_INPUT_CHARACTERS) throw new Error(`Input text can be up to ${MAX_INPUT_CHARACTERS} characters`);
+  if (!text.trim() && !images.length) throw new Error('Input must contain text or an image');
+  // Whitespace-only text next to images carries nothing; keep text-only turns byte-identical to before.
+  const message: SendMessage = images.length ? items.filter(item => item.type !== 'text' || item.text.trim()) : text;
+  return { message, text, images };
+}
+
+/**
+ * A persistent, Letta-backed Vercel AI SDK `Agent`.
+ *
+ * Letta owns the only reasoning and tool loop: each call sends exactly one new
+ * user message, and application tools run in this process through the Letta
+ * client-tool protocol (reported as `providerExecuted`). The AI SDK never
+ * dispatches tools itself. History you pass in must extend what this instance
+ * already sent; edits, regeneration and replay are rejected. After any failure
+ * or cancellation the instance refuses further turns, because delivery is
+ * uncertain; reopen it after inspecting the backend.
+ */
+export class LettaAgent<TOOLS extends ToolSet = ToolSet> implements Agent<never, TOOLS> {
+  readonly version = 'agent-v1' as const;
+  readonly id: string;
+  readonly tools: TOOLS;
+  /** Letta-generated agent ID, when known. */
+  readonly lettaAgentId?: string;
+  /** Display-only restored state. */
+  readonly presentation?: AgentPresentation;
+  /** Broker for approvals and `ask_user` questions; connect a renderer to it. */
+  readonly interactions: ToolInteractions;
+  private readonly open: (signal: AbortSignal) => TurnSession;
+  private readonly memoryTools: readonly string[];
+  private readonly delivery?: DeliveryHooks;
+  private readonly modelId: string;
+  private history: ModelMessage[] = [];
+  private busy = false;
+  private unusable = false;
+  private active?: AbortController;
+
+  constructor(options: LettaAgentOptions<TOOLS>) {
+    this.id = options.id;
+    this.tools = options.tools;
+    this.open = options.open;
+    this.memoryTools = options.memoryTools ?? [];
+    this.lettaAgentId = options.lettaAgentId;
+    this.presentation = options.presentation;
+    this.delivery = options.delivery;
+    this.interactions = options.interactions ?? new ToolInteractions();
+    this.modelId = options.modelId ?? 'letta';
+  }
+
+  /**
+   * A copy of the transcript this instance has sent and received (images as
+   * content-hash references, never bytes). To send a multimodal turn without
+   * keeping your own history, pass `messages: [...agent.transcript, newUserMessage]`.
+   */
+  get transcript(): ModelMessage[] { return structuredClone(this.history); }
+
+  /** Abort any running turn, cancel pending prompts, and refuse further turns. */
+  close(): void { this.unusable = true; this.active?.abort(); this.interactions.close(); }
+
+  private prepare(options: Call<TOOLS>) {
+    if (this.unusable) throw new Error('Session closed or delivery uncertain; inspect backend history before reopening (no retries).');
+    if (this.busy) throw new Error('A turn is already running');
+    for (const [key, value] of Object.entries(options)) {
+      if (!['prompt', 'messages', 'abortSignal'].includes(key) && value !== undefined) throw new Error(`Unsupported agent option: ${key}`);
+    }
+    if (options.prompt !== undefined && options.messages !== undefined) throw new Error('Use prompt or messages, not both');
+    const messages = typeof options.prompt === 'string' ? [...this.history, { role: 'user' as const, content: options.prompt }] : options.messages ?? options.prompt;
+    if (!Array.isArray(messages) || !messages.length) throw new Error('Expected a new user turn');
+    const last = messages.at(-1)!;
+    if (last.role !== 'user') throw new Error('History edits, replay, and regeneration are not supported');
+    // Validate the new turn first, so an oversized or unsupported image is reported as such.
+    const turn = userTurnContent(last.content);
+    if (historyKey(messages.slice(0, -1)) !== historyKey(this.history)) throw new Error('History edits, replay, and regeneration are not supported');
+    options.abortSignal?.throwIfAborted();
+    this.busy = true;
+    const control = new AbortController();
+    this.active = control;
+    const signal = options.abortSignal ? AbortSignal.any([options.abortSignal, control.signal]) : control.signal;
+    // The retained transcript keeps images as hashes only; Letta already holds the bytes.
+    // (Compact before cloning: URL objects in image parts are not cloneable.)
+    return { messages: structuredClone(compactTranscript(messages)), message: turn.message, prompt: turn.text.trim() ? turn.text : '[Image]', signal };
+  }
+
+  private model(message: SendMessage, signal: AbortSignal): LanguageModelV4 {
+    const run = async (emit: (part: LanguageModelV4StreamPart) => void) => {
+      let session: TurnSession | undefined;
+      let completed = false;
+      const abort = () => { void session?.abort().catch(() => {}); session?.close(); };
+      const calls = new Map<string, string>();
+      const memoryCalls = new Set<string>();
+      const tokens = usage();
+      let textId = 0;
+      let textOpen = false;
+      const endText = () => { if (textOpen) { emit({ type: 'text-end', id: String(textId) }); textOpen = false; } };
+      try {
+        signal.throwIfAborted();
+        session = this.open(signal);
+        signal.addEventListener('abort', abort, { once: true });
+        this.delivery?.begin();
+        await session.send(message);
+        signal.throwIfAborted();
+        for await (const event of session.stream()) {
+          signal.throwIfAborted();
+          if (event.type === 'assistant') {
+            if (!textOpen) { textId++; emit({ type: 'text-start', id: String(textId) }); textOpen = true; }
+            emit({ type: 'text-delta', id: String(textId), delta: event.content });
+          } else if (event.type === 'tool_call') {
+            endText();
+            if (calls.has(event.toolCallId) || memoryCalls.has(event.toolCallId)) throw new Error('Duplicate tool call');
+            // Harness memory operations are not application tool cards/history.
+            if (this.memoryTools.includes(event.toolName)) { memoryCalls.add(event.toolCallId); continue; }
+            if (!Object.hasOwn(this.tools, event.toolName)) throw new Error('Unexpected tool call');
+            calls.set(event.toolCallId, event.toolName);
+            emit({ type: 'tool-call', toolCallId: event.toolCallId, toolName: event.toolName, input: JSON.stringify(event.toolInput), providerExecuted: true });
+          } else if (event.type === 'tool_result') {
+            // The SDK can emit provisional Bash output as a tool_result before
+            // the authoritative result. Only known internal calls may use it.
+            if (memoryCalls.has(event.toolCallId) && event.uuid.startsWith('synthetic-tool-return-stream-')) continue;
+            if (memoryCalls.delete(event.toolCallId)) continue;
+            const toolName = calls.get(event.toolCallId);
+            if (!toolName) throw new Error('Unmatched tool result');
+            let result: JSONValue = event.content;
+            try { result = JSON.parse(event.content); } catch { /* SDK text output */ }
+            emit({ type: 'tool-result', toolCallId: event.toolCallId, toolName, result: result ?? 'null', isError: event.isError });
+            calls.delete(event.toolCallId);
+          } else if (event.type === 'stream_event' && event.event.message_type === 'usage_statistics') {
+            if (typeof event.event.prompt_tokens === 'number') tokens.inputTokens.total = event.event.prompt_tokens;
+            if (typeof event.event.completion_tokens === 'number') tokens.outputTokens.total = event.event.completion_tokens;
+          } else if (event.type === 'result') {
+            if (!event.success || calls.size || memoryCalls.size) throw new Error('Letta turn failed or left incomplete tools');
+            endText(); completed = true;
+            emit({ type: 'finish', finishReason: { unified: 'stop', raw: 'stop' }, usage: tokens });
+            return;
+          }
+        }
+        throw new Error('Letta stream closed before completion');
+      } catch (error) {
+        this.unusable = true;
+        throw error;
+      } finally {
+        signal.removeEventListener('abort', abort);
+        if (!completed) void session?.abort().catch(() => {});
+        session?.close();
+      }
+    };
+    return {
+      specificationVersion: 'v4', provider: 'ai-sdk-letta', modelId: this.modelId, supportedUrls: {},
+      doGenerate: async () => {
+        const content: Awaited<ReturnType<LanguageModelV4['doGenerate']>>['content'] = [];
+        let tokens = usage();
+        await run(part => {
+          if (part.type === 'text-delta') {
+            const last = content.at(-1);
+            if (last?.type === 'text') last.text += part.delta;
+            else content.push({ type: 'text', text: part.delta });
+          } else if (part.type === 'tool-call' || part.type === 'tool-result') content.push(part);
+          else if (part.type === 'finish') tokens = part.usage;
+        });
+        return { content, usage: tokens, warnings: [], finishReason: { unified: 'stop', raw: 'stop' } };
+      },
+      doStream: async () => ({ stream: new ReadableStream<LanguageModelV4StreamPart>({
+        start: controller => {
+          controller.enqueue({ type: 'stream-start', warnings: [] });
+          void run(part => controller.enqueue(part)).catch(error => {
+            try { controller.enqueue({ type: 'error', error }); } catch { /* reader closed */ }
+          }).finally(() => { try { controller.close(); } catch { /* reader closed */ } });
+        },
+        cancel: () => this.close(),
+      }) }),
+    };
+  }
+
+  /** Run one turn and wait for the full result. */
+  async generate(options: Call<TOOLS>) {
+    const turn = this.prepare(options);
+    try {
+      const result = await generateText({ model: this.model(turn.message, turn.signal), prompt: turn.prompt, tools: this.tools, maxRetries: 0, stopWhen: stepCountIs(1), abortSignal: turn.signal });
+      this.delivery?.complete();
+      this.history = [...turn.messages, ...result.response.messages];
+      return result;
+    } catch (error) { this.unusable = true; throw error; }
+    finally { this.busy = false; this.active = undefined; }
+  }
+
+  /** Run one turn as a stream (text deltas, provider-executed tool calls and results). */
+  async stream(options: AgentStreamParameters<never, TOOLS>) {
+    const turn = this.prepare(options);
+    return streamText({ model: this.model(turn.message, turn.signal), prompt: turn.prompt, tools: this.tools, maxRetries: 0, stopWhen: stepCountIs(1), abortSignal: turn.signal,
+      onError: () => { this.unusable = true; this.busy = false; },
+      onAbort: () => { this.close(); this.busy = false; },
+      onFinish: result => {
+        try { if (!this.unusable && result.finishReason === 'stop') this.delivery?.complete(); }
+        catch (error) { this.unusable = true; throw error; }
+        finally { this.busy = false; this.active = undefined; }
+        this.history = [...turn.messages, ...result.response.messages];
+      },
+    });
+  }
+}