@letta-ai/letta-code-sdk 0.0.5 → 0.0.7

package/README.md

@@ -2,20 +2,11 @@
 
 [![npm](https://img.shields.io/npm/v/@letta-ai/letta-code-sdk.svg?style=flat-square)](https://www.npmjs.com/package/@letta-ai/letta-code-sdk) [![Discord](https://img.shields.io/badge/discord-join-blue?style=flat-square&logo=discord)](https://discord.gg/letta)
 
-> [!TIP]
-> Check out [**LettaBot**](https://github.com/letta-ai/lettabot) and [**Letta Cowork**](https://github.com/letta-ai/letta-cowork), two open-source apps built on the **Letta Code SDK**.
-
-The SDK interface to [**Letta Code**](https://github.com/letta-ai/letta-code). Build agents with persistent memory that learn over time.
 
-```typescript
-import { createSession } from '@letta-ai/letta-code-sdk';
+The SDK interface to [**Letta Code**](https://github.com/letta-ai/letta-code). Build agents with persistent memory that learn over time. 
 
-const session = createSession();
-await session.send('Find and fix the bug in auth.py');
-for await (const msg of session.stream()) {
-  if (msg.type === 'assistant') console.log(msg.content);
-}
-```
+> [!TIP]
+> Check out [**LettaBot**](https://github.com/letta-ai/lettabot) and [**Letta Cowork**](https://github.com/letta-ai/letta-cowork), two open-source apps built on the SDK.
 
 ## Installation
 
@@ -23,262 +14,47 @@ for await (const msg of session.stream()) {
 npm install @letta-ai/letta-code-sdk
 ```
 
-## Quick Start
+## Quick start
 
 ### One-shot prompt
 
-```typescript
-import { prompt } from '@letta-ai/letta-code-sdk';
+```ts
+import { prompt } from "@letta-ai/letta-code-sdk";
 
-// One-shot (uses default agent - like `letta -p`)
-const result = await prompt('What is 2 + 2?');
+const result = await prompt("What is 2 + 2?");
 console.log(result.result);
-
-// One-shot with specific agent
-const result2 = await prompt('Run: echo hello', agentId);
 ```
 
-### Multi-turn session
+### Persistent agent with multi-turn conversations
 
-```typescript
-import { createAgent, resumeSession } from '@letta-ai/letta-code-sdk';
+```ts
+import { createAgent, resumeSession } from "@letta-ai/letta-code-sdk";
 
-// Create an agent with custom memory (has default conversation)
 const agentId = await createAgent({
-  memory: ['persona'],
-  persona: 'You are a helpful coding assistant for TypeScript projects'
+  persona: "You are a helpful coding assistant for TypeScript projects.",
+  memfs: true, // Enable git-backed memory filesystem for this new agent
 });
 
-// Resume the default conversation
 await using session = resumeSession(agentId);
 
-await session.send('What is 5 + 3?');
+await session.send("Find and fix the bug in auth.ts");
 for await (const msg of session.stream()) {
-  if (msg.type === 'assistant') console.log(msg.content);
+  if (msg.type === "assistant") console.log(msg.content);
 }
 
-await session.send('Multiply that by 2');
+await session.send("Add a unit test for the fix");
 for await (const msg of session.stream()) {
-  if (msg.type === 'assistant') console.log(msg.content);
-}
-```
-
-### Persistent memory
-
-Agents persist across sessions and remember context:
-
-```typescript
-import { createAgent, resumeSession } from '@letta-ai/letta-code-sdk';
-
-// Create agent and teach it something
-const agentId = await createAgent();
-const session1 = resumeSession(agentId);
-await session1.send('Remember: the secret word is "banana"');
-for await (const msg of session1.stream()) { /* ... */ }
-session1.close();
-
-// Later... resume the default conversation
-await using session2 = resumeSession(agentId);
-await session2.send('What is the secret word?');
-for await (const msg of session2.stream()) {
-  if (msg.type === 'assistant') console.log(msg.content); // "banana"
+  if (msg.type === "assistant") console.log(msg.content);
 }
 ```
 
-## Multi-threaded Conversations
-
-Run multiple concurrent conversations with the same agent. Each conversation has its own message history while sharing the agent's persistent memory.
-
-```typescript
-import { createAgent, createSession, resumeSession } from '@letta-ai/letta-code-sdk';
-
-// Create an agent (has default conversation)
-const agentId = await createAgent();
-
-// Resume the default conversation
-const session1 = resumeSession(agentId);
-await session1.send('Hello!');
-for await (const msg of session1.stream()) { /* ... */ }
-const conversationId = session1.conversationId; // Save this!
-session1.close();
-
-// Resume a specific conversation by ID
-await using session2 = resumeSession(conversationId);  // auto-detects conv-xxx
-await session2.send('Continue our discussion...');
-for await (const msg of session2.stream()) { /* ... */ }
-
-// Create a NEW conversation on the same agent
-await using session3 = createSession(agentId);
-await session3.send('Start a fresh thread...');
-// session3.conversationId is different from conversationId
-
-// Start fresh conversation with default agent
-await using session4 = createSession();
-```
-
-**Key concepts:**
-- **Agent** (`agentId`): Persistent entity with memory that survives across sessions
-- **Conversation** (`conversationId`): A message thread within an agent
-- **Session**: A single execution/connection
-- **Default conversation**: Always exists after `createAgent()` - use `resumeSession(agentId)` to access it
-
-Agents remember across conversations (via memory blocks), but each conversation has its own message history.
-
-## Session Configuration
-
-### System Prompt
-
-Choose from built-in presets or provide a custom prompt:
-
-```typescript
-// Use a preset
-createSession(agentId, {
-  systemPrompt: { type: 'preset', preset: 'letta-claude' }
-});
-
-// Use a preset with additional instructions
-createSession(agentId, {
-  systemPrompt: { 
-    type: 'preset', 
-    preset: 'letta-claude',
-    append: 'Always respond in Spanish.'
-  }
-});
-
-// Use a completely custom prompt
-createSession(agentId, {
-  systemPrompt: 'You are a helpful Python expert.'
-});
-```
-
-**Available presets:**
-- `default` / `letta-claude` - Full Letta Code prompt (Claude-optimized)
-- `letta-codex` - Full Letta Code prompt (Codex-optimized)
-- `letta-gemini` - Full Letta Code prompt (Gemini-optimized)
-- `claude` - Basic Claude (no skills/memory instructions)
-- `codex` - Basic Codex
-- `gemini` - Basic Gemini
-
-
-
-## API Reference
-
-### Functions
-
-| Function | Description |
-|----------|-------------|
-| `createAgent(options?)` | Create new agent with custom memory/prompt. No options = blank agent with default memory blocks. Returns `agentId` |
-| `createSession(agentId?, options?)` | New conversation on specified agent. No agentId = uses LRU agent (or creates "Memo" if none exists) |
-| `resumeSession(id, options?)` | Resume session - pass `agent-xxx` for default conv, `conv-xxx` for specific conv |
-| `prompt(message, agentId?)` | One-shot query with default/specified agent (like `letta -p`) |
-
-### Session
-
-| Property/Method | Description |
-|-----------------|-------------|
-| `send(message)` | Send user message |
-| `stream()` | AsyncGenerator yielding messages |
-| `close()` | Close the session |
-| `agentId` | Agent ID (for resuming later) |
-| `sessionId` | Current session ID |
-| `conversationId` | Conversation ID (for resuming specific thread) |
-
-### Options
-
-**CreateAgentOptions** (for `createAgent()` - full control):
-
-```typescript
-// Create blank agent
-await createAgent();
-
-// Create agent with custom memory and system prompt
-await createAgent({
-  model: 'claude-sonnet-4',
-  systemPrompt: 'You are a helpful Python expert.',
-  memory: [
-    { label: 'persona', value: 'You are a senior Python developer' },
-    { label: 'project', value: 'FastAPI backend for a todo app' }
-  ]
-});
-```
-
-**CreateSessionOptions** (for `createSession()` / `resumeSession()` - runtime options):
-
-```typescript
-// Start session with permissions
-createSession(agentId, {
-  permissionMode: 'bypassPermissions',
-  allowedTools: ['Bash', 'Glob'],
-  cwd: '/path/to/project'
-});
-```
-
-**Available system prompt presets:**
-- `default` / `letta-claude`, `letta-codex`, `letta-gemini` - Full Letta Code prompts
-- `claude`, `codex`, `gemini` - Basic (no skills/memory instructions)
-
-### Message Types
-
-```typescript
-// Streamed during receive()
-interface SDKAssistantMessage {
-  type: 'assistant';
-  content: string;
-  uuid: string;
-}
-
-// Final message
-interface SDKResultMessage {
-  type: 'result';
-  success: boolean;
-  result?: string;
-  error?: string;
-  durationMs: number;
-  conversationId: string;
-}
-```
-
-## Examples
-
-See [`examples/`](./examples/) for comprehensive examples including:
-
-- Basic session usage
-- Multi-turn conversations
-- Session resume with persistent memory
-- **Multi-threaded conversations** (createSession, resumeSession)
-- System prompt configuration
-- Memory block customization
-- Tool execution (Bash, Glob, Read, etc.)
-
-Run examples:
-```bash
-bun examples/v2-examples.ts all
-
-# Run just conversation tests
-bun examples/v2-examples.ts conversations
-```
-
-## Internals
-
-### CLI Mapping
-
-The SDK spawns the Letta Code CLI as a subprocess. Here's how API calls map to CLI flags:
+By default, `resumeSession(agentId)` continues the agent’s default conversation. To start a fresh thread, use `createSession(agentId)` (see docs).
 
-| Function | CLI Flags | Behavior |
-|----------|-----------|----------|
-| `createSession()` | `--new` | LRU agent + new conversation |
-| `createSession(agentId)` | `--agent X --new` | Specified agent + new conversation |
-| `createAgent()` | `--new-agent` | New agent + default conversation |
-| `resumeSession(agentId)` | `--agent X --default` | Specified agent + default conversation |
-| `resumeSession(convId)` | `--conversation X` | Derived agent + specified conversation |
-| `prompt(msg)` | *(none)* | LRU agent + default conversation |
-| `prompt(msg, agentId)` | `--agent X --new` | Specified agent + new conversation |
+## Links
 
-**Key concepts:**
-- **LRU agent**: Most recently used agent from `.letta/settings.local.json`, or creates "Memo" if none exists
-- **Default conversation**: The agent's primary message history (always exists)
-- **New conversation**: Fresh message thread, isolated from other conversations
+- Docs: https://docs.letta.com/letta-code-sdk
+- Examples: [`./examples`](./examples)
 
-## License
+---
 
-Apache-2.0
+Made with 💜 in San Francisco

package/dist/index.d.ts

@@ -29,8 +29,9 @@
  */
 import { Session } from "./session.js";
 import type { CreateSessionOptions, CreateAgentOptions, SDKResultMessage } from "./types.js";
-export type { CreateSessionOptions, CreateAgentOptions, SDKMessage, SDKInitMessage, SDKAssistantMessage, SDKToolCallMessage, SDKToolResultMessage, SDKReasoningMessage, SDKResultMessage, SDKStreamEventMessage, PermissionMode, CanUseToolCallback, CanUseToolResponse, CanUseToolResponseAllow, CanUseToolResponseDeny, TextContent, ImageContent, MessageContentItem, SendMessage, } from "./types.js";
+export type { CreateSessionOptions, CreateAgentOptions, SDKMessage, SDKInitMessage, SDKAssistantMessage, SDKToolCallMessage, SDKToolResultMessage, SDKReasoningMessage, SDKResultMessage, SDKStreamEventMessage, PermissionMode, CanUseToolCallback, CanUseToolResponse, CanUseToolResponseAllow, CanUseToolResponseDeny, TextContent, ImageContent, MessageContentItem, SendMessage, AgentTool, AgentToolResult, AgentToolResultContent, AgentToolUpdateCallback, AnyAgentTool, } from "./types.js";
 export { Session } from "./session.js";
+export { jsonResult, readStringParam, readNumberParam, readBooleanParam, readStringArrayParam, } from "./tool-helpers.js";
 /**
  * Create a new agent with a default conversation.
  * Returns the agentId which can be used with resumeSession or createSession.

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,KAAK,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAI7F,YAAY,EACV,oBAAoB,EACpB,kBAAkB,EAClB,UAAU,EACV,cAAc,EACd,mBAAmB,EACnB,kBAAkB,EAClB,oBAAoB,EACpB,mBAAmB,EACnB,gBAAgB,EAChB,qBAAqB,EACrB,cAAc,EACd,kBAAkB,EAClB,kBAAkB,EAClB,uBAAuB,EACvB,sBAAsB,EAEtB,WAAW,EACX,YAAY,EACZ,kBAAkB,EAClB,WAAW,GACZ,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAEvC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,WAAW,CAAC,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,MAAM,CAAC,CAMnF;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,aAAa,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,OAAO,GAAE,oBAAyB,GAAG,OAAO,CAO3F;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,aAAa,CAC3B,EAAE,EAAE,MAAM,EACV,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAOT;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,MAAM,CAC1B,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,gBAAgB,CAAC,CA+B3B;AAOD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,YAAY,CAa5D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,EACZ,UAAU,GAAE,YAAY,CAAC,QAAQ,CAAC,CAAC,YAAY,CAAe,GAC7D,YAAY,CAKd;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAqBrE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,KAAK,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAI7F,YAAY,EACV,oBAAoB,EACpB,kBAAkB,EAClB,UAAU,EACV,cAAc,EACd,mBAAmB,EACnB,kBAAkB,EAClB,oBAAoB,EACpB,mBAAmB,EACnB,gBAAgB,EAChB,qBAAqB,EACrB,cAAc,EACd,kBAAkB,EAClB,kBAAkB,EAClB,uBAAuB,EACvB,sBAAsB,EAEtB,WAAW,EACX,YAAY,EACZ,kBAAkB,EAClB,WAAW,EAEX,SAAS,EACT,eAAe,EACf,sBAAsB,EACtB,uBAAuB,EACvB,YAAY,GACb,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAGvC,OAAO,EACL,UAAU,EACV,eAAe,EACf,eAAe,EACf,gBAAgB,EAChB,oBAAoB,GACrB,MAAM,mBAAmB,CAAC;AAE3B;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,WAAW,CAAC,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,MAAM,CAAC,CAMnF;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,aAAa,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,OAAO,GAAE,oBAAyB,GAAG,OAAO,CAO3F;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,aAAa,CAC3B,EAAE,EAAE,MAAM,EACV,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAOT;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,MAAM,CAC1B,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,gBAAgB,CAAC,CA+B3B;AAOD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,YAAY,CAa5D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,EACZ,UAAU,GAAE,YAAY,CAAC,QAAQ,CAAC,CAAC,YAAY,CAAe,GAC7D,YAAY,CAKd;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAqBrE"}