@letta-ai/letta-code-sdk 0.0.4 → 0.0.6

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**](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,302 +14,46 @@ 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 (has default conversation)
-const agentId = await createAgent();
+const agentId = await createAgent({
+  persona: "You are a helpful coding assistant for TypeScript projects.",
+});
 
-// 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);
+  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"
-}
-```
-
-## 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
-
-### Memory Blocks
-
-Configure which memory blocks the session uses:
-
-```typescript
-// Use default blocks (persona, human, project)
-createSession(agentId);
-
-// Use specific preset blocks
-createSession(agentId, {
-  memory: ['project', 'persona']  // Only these blocks
-});
-
-// Use custom blocks
-createSession(agentId, {
-  memory: [
-    { label: 'context', value: 'API documentation for Acme Corp...' },
-    { label: 'rules', value: 'Always use TypeScript. Prefer functional patterns.' }
-  ]
-});
-
-// No optional blocks (only core skills blocks)
-createSession(agentId, {
-  memory: []
-});
-```
-
-### Convenience Props
-
-Quickly customize common memory blocks:
-
-```typescript
-createSession(agentId, {
-  persona: 'You are a senior Python developer who writes clean, tested code.',
-  human: 'Name: Alice. Prefers concise responses.',
-  project: 'FastAPI backend for a todo app using PostgreSQL.'
-});
-```
-
-### Tool Execution
-
-Execute tools with automatic permission handling:
-
-```typescript
-import { createAgent, createSession } from '@letta-ai/letta-code-sdk';
-
-// Create agent and run commands
-const agentId = await createAgent();
-const session = createSession(agentId, {
-  allowedTools: ['Glob', 'Bash'],
-  permissionMode: 'bypassPermissions',
-  cwd: '/path/to/project'
-});
-await session.send('List all TypeScript files');
-for await (const msg of session.stream()) { /* ... */ }
-```
-
-## API Reference
-
-### Functions
-
-| Function | Description |
-|----------|-------------|
-| `createAgent()` | Create new agent with default conversation, returns `agentId` |
-| `createSession()` | New conversation on default agent |
-| `createSession(agentId)` | New conversation on specified agent |
-| `resumeSession(id, options?)` | Resume session - pass `agent-xxx` for default conv, `conv-xxx` for specific conv |
-| `prompt(message)` | One-shot query with default agent (like `letta -p`) |
-| `prompt(message, agentId)` | One-shot query with specific agent |
-
-### 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
-
-```typescript
-interface SessionOptions {
-  model?: string;
-  systemPrompt?: string | { type: 'preset'; preset: string; append?: string };
-  memory?: Array<string | CreateBlock | { blockId: string }>;
-  persona?: string;
-  human?: string;
-  project?: string;
-  cwd?: string;
-
-  // Tool configuration
-  allowedTools?: string[];
-  permissionMode?: 'default' | 'acceptEdits' | 'bypassPermissions';
-  canUseTool?: (toolName: string, toolInput: object) => Promise<CanUseToolResponse>;
-  maxTurns?: number;
-}
-```
-
-### 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

@@ -28,22 +28,31 @@
  * ```
  */
 import { Session } from "./session.js";
-import type { SessionOptions, SDKResultMessage } from "./types.js";
-export type { SessionOptions, SDKMessage, SDKInitMessage, SDKAssistantMessage, SDKToolCallMessage, SDKToolResultMessage, SDKReasoningMessage, SDKResultMessage, SDKStreamEventMessage, PermissionMode, CanUseToolCallback, CanUseToolResponse, CanUseToolResponseAllow, CanUseToolResponseDeny, } from "./types.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, 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.
  *
  * @example
  * ```typescript
+ * // Create agent with default settings
  * const agentId = await createAgent();
  *
+ * // Create agent with custom memory
+ * const agentId = await createAgent({
+ *   memory: ['persona', 'project'],
+ *   persona: 'You are a helpful coding assistant',
+ *   model: 'claude-sonnet-4'
+ * });
+ *
  * // Then resume the default conversation:
  * const session = resumeSession(agentId);
  * ```
  */
-export declare function createAgent(): Promise<string>;
+export declare function createAgent(options?: CreateAgentOptions): Promise<string>;
 /**
  * Create a new conversation (session).
  *
@@ -59,7 +68,7 @@ export declare function createAgent(): Promise<string>;
  * await using session = createSession(agentId);
  * ```
  */
-export declare function createSession(agentId?: string, options?: SessionOptions): Session;
+export declare function createSession(agentId?: string, options?: CreateSessionOptions): Session;
 /**
  * Resume an existing session.
  *
@@ -78,7 +87,7 @@ export declare function createSession(agentId?: string, options?: SessionOptions
  * await using session = resumeSession('conv-xxx');
  * ```
  */
-export declare function resumeSession(id: string, options?: SessionOptions): Session;
+export declare function resumeSession(id: string, options?: CreateSessionOptions): Session;
 /**
  * One-shot prompt convenience function.
  *
@@ -92,4 +101,44 @@ export declare function resumeSession(id: string, options?: SessionOptions): Ses
  * ```
  */
 export declare function prompt(message: string, agentId?: string): Promise<SDKResultMessage>;
+import type { ImageContent } from "./types.js";
+/**
+ * Create image content from a file path.
+ *
+ * @example
+ * ```typescript
+ * await session.send([
+ *   { type: "text", text: "What's in this image?" },
+ *   imageFromFile("./screenshot.png")
+ * ]);
+ * ```
+ */
+export declare function imageFromFile(filePath: string): ImageContent;
+/**
+ * Create image content from base64 data.
+ *
+ * @example
+ * ```typescript
+ * const base64 = fs.readFileSync("image.png").toString("base64");
+ * await session.send([
+ *   { type: "text", text: "Describe this" },
+ *   imageFromBase64(base64, "image/png")
+ * ]);
+ * ```
+ */
+export declare function imageFromBase64(data: string, media_type?: ImageContent["source"]["media_type"]): ImageContent;
+/**
+ * Create image content from a URL.
+ * Fetches the image and converts to base64.
+ *
+ * @example
+ * ```typescript
+ * const img = await imageFromURL("https://example.com/image.png");
+ * await session.send([
+ *   { type: "text", text: "What's this?" },
+ *   img
+ * ]);
+ * ```
+ */
+export declare function imageFromURL(url: string): Promise<ImageContent>;
 //# sourceMappingURL=index.d.ts.map

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,cAAc,EAAc,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAG/E,YAAY,EACV,cAAc,EACd,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,GACvB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAEvC;;;;;;;;;;;GAWG;AACH,wBAAsB,WAAW,IAAI,OAAO,CAAC,MAAM,CAAC,CAKnD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,aAAa,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAMrF;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,aAAa,CAC3B,EAAE,EAAE,MAAM,EACV,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAMT;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,MAAM,CAC1B,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,gBAAgB,CAAC,CA+B3B"}
+{"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"}