@letta-ai/letta-agent-sdk 0.3.2 → 0.3.3

package/src/index.ts

@@ -0,0 +1,440 @@
+/**
+ * Letta Agent SDK
+ *
+ * Programmatic control of Letta Code CLI with persistent agent memory.
+ *
+ * @example
+ * ```typescript
+ * import { LettaAgentClient, createAgent, createSession, resumeSession, prompt } from '@letta-ai/letta-agent-sdk';
+ *
+ * const client = new LettaAgentClient({ backend: 'local' });
+ * const agentId = await client.createAgent();
+ * const clientSession = client.resumeSession(agentId);
+ *
+ * // Start session with default agent + new conversation (like `letta`)
+ * const session = createSession();
+ *
+ * // Create a new agent explicitly
+ * const agentId = await createAgent();
+ *
+ * // Resume default conversation on an agent
+ * const session = resumeSession(agentId);
+ *
+ * // Resume specific conversation
+ * const session = resumeSession('conv-xxx');
+ *
+ * // Create new conversation on specific agent
+ * const session = createSession(agentId);
+ *
+ * // One-shot prompt (uses default agent)
+ * const result = await prompt('Hello');
+ * const result = await prompt('Hello', agentId);  // specific agent
+ * ```
+ */
+
+import { Session } from "./session.js";
+import { LettaAgentClient } from "./client.js";
+import type {
+  CreateSessionOptions,
+  CreateAgentOptions,
+  LettaCodeSession,
+  SDKInitMessage,
+  SDKResultMessage,
+  SendMessage,
+} from "./types.js";
+import { validateCreateSessionOptions, validateCreateAgentOptions } from "./validation.js";
+
+// Re-export types
+export type {
+  CreateSessionOptions,
+  CreateAgentOptions,
+  LettaCodePersonalityId,
+  LettaCodeBackend,
+  LettaCodeEnvironment,
+  LettaCodeLocalClientOptions,
+  LettaCodeLocalAppServerOptions,
+  LettaCodeRemoteClientOptions,
+  LettaCodeCloudClientOptions,
+  LettaCodeCloudSandboxOptions,
+  GitHubRepositoryRef,
+  LettaCodeClientOptions,
+  LettaCodeClientSessionOptions,
+  LettaCodeSession,
+  LettaCodeSocketLike,
+  LettaCodeSocketConstructor,
+  LettaCodeReactNativeSocketConstructor,
+  SDKMessage,
+  SDKInitMessage,
+  SDKAssistantMessage,
+  SDKToolCallMessage,
+  SDKToolResultMessage,
+  SDKReasoningMessage,
+  SDKResultMessage,
+  SDKErrorCode,
+  SDKStreamEventMessage,
+  SDKStreamEventPayload,
+  SDKStreamEventDeltaPayload,
+  SDKStreamEventMessagePayload,
+  SDKUnknownStreamEventPayload,
+  SDKErrorMessage,
+  SDKRetryMessage,
+  SDKQueueItem,
+  SDKQueueUpdateMessage,
+  SDKLoopStatusMessage,
+  SDKProtocolMessage,
+  SDKProtocolCommand,
+  SendCommandOptions,
+  RunTurnOptions,
+  RecoverPendingApprovalsOptions,
+  RecoverPendingApprovalsResult,
+  ChangeDeviceStateOptions,
+  RemoveQueuedMessageResult,
+  GetDeviceStatusOptions,
+  SessionDeviceStatus,
+  SessionPendingControlRequest,
+  SessionPermissionSuggestion,
+  SessionDiffHunkLine,
+  SessionDiffHunk,
+  SessionDiffPreview,
+  SkillSource,
+  DreamingOptions,
+  DreamingTrigger,
+  DreamingBehavior,
+  EffectiveDreamingSettings,
+  PermissionMode,
+  ReasoningEffort,
+  CanUseToolCallback,
+  CanUseToolContext,
+  CanUseToolPermissionSuggestion,
+  CanUseToolResponse,
+  CanUseToolResponseAllow,
+  CanUseToolResponseDeny,
+  // Multimodal content types
+  TextContent,
+  ImageContent,
+  MessageContentItem,
+  SendMessage,
+  // List messages API
+  ListMessagesOptions,
+  ListMessagesResult,
+  ListModelsResult,
+  LettaCodeModelEntry,
+  UpdateModelOptions,
+  UpdateModelResult,
+  Repository,
+  CreateRepositoryParams,
+  ListRepositoriesParams,
+  ListRepositoriesResult,
+  RepositoryResource,
+  RepositoryFileEntry,
+  ListRepositoryFilesParams,
+  ListRepositoryFilesResult,
+  CreateRepositoryFileParams,
+  RepositoryFile,
+  UpdateRepositoryFileParams,
+  RepositoryFileMutationResult,
+  DeleteRepositoryFileParams,
+  DeleteRepositoryFileResult,
+  RepositoryVersion,
+  ListRepositoryVersionsParams,
+  GetRepositoryVersionParams,
+  // Bootstrap API
+  BootstrapStateOptions,
+  BootstrapStateResult,
+  // Tool types
+  AgentTool,
+  AgentToolResult,
+  AgentToolResultContent,
+  AgentToolUpdateCallback,
+  AnyAgentTool,
+} from "./types.js";
+export type {
+  AgentsClient,
+  ConversationsClient,
+  LettaAgent,
+  LettaConversation,
+  LettaConversationMessage,
+  ModelsClient,
+  ListAgentsOptions,
+  UpdateAgentOptions,
+  ListConversationsOptions,
+  CreateConversationOptions,
+  UpdateConversationOptions,
+  ConversationMessagesOptions,
+  ConversationMessagesResult,
+} from "./management-types.js";
+
+export { Session } from "./session.js";
+export { RepositoriesClient } from "./repositories.js";
+export { LettaAgentClient } from "./client.js";
+export { CloudManagedSandboxExpiredError } from "./cloud-session.js";
+export { createReactNativeWebSocketConstructor } from "./websocket.js";
+
+export { extractStreamTextDelta } from "./stream-events.js";
+
+// Tool helpers
+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',
+ *   tags: ['project:docs']
+ * });
+ *
+ * // Then resume the default conversation:
+ * const session = resumeSession(agentId);
+ * ```
+ */
+export async function createAgent(options: CreateAgentOptions = {}): Promise<string> {
+  validateCreateAgentOptions(options);
+  return new LettaAgentClient().createAgent(options);
+}
+
+/**
+ * Create a new conversation (session).
+ *
+ * - Without agentId: uses default/LRU agent with new conversation (like `letta`)
+ * - With agentId: creates new conversation on specified agent
+ *
+ * @example
+ * ```typescript
+ * // New conversation on default agent (like `letta`)
+ * await using session = createSession();
+ *
+ * // New conversation on specific agent
+ * await using session = createSession(agentId);
+ * ```
+ */
+export function createSession(
+  agentId?: string,
+  options: CreateSessionOptions = {},
+): LettaCodeSession {
+  validateCreateSessionOptions(options);
+  if (agentId) {
+    return new LettaAgentClient().createSession(agentId, options);
+  }
+  // The app-server runtime_start protocol requires an explicit agent id. Keep
+  // the historical default/LRU-agent helper on the legacy stdio transport.
+  return new LettaAgentClient({ backend: "local", transport: "stdio" }).createSession(options);
+}
+
+/**
+ * Resume an existing session.
+ *
+ * - Pass an agent ID (agent-xxx) to resume the default conversation
+ * - Pass a conversation ID (conv-xxx) to resume a specific conversation
+ *
+ * The default conversation always exists after createAgent, so you can:
+ * `createAgent()` → `resumeSession(agentId)` without needing createSession first.
+ *
+ * @example
+ * ```typescript
+ * // Resume default conversation
+ * await using session = resumeSession(agentId);
+ *
+ * // Resume specific conversation
+ * await using session = resumeSession('conv-xxx');
+ * ```
+ */
+export function resumeSession(
+  id: string,
+  options: CreateSessionOptions = {},
+): LettaCodeSession {
+  validateCreateSessionOptions(options);
+  return new LettaAgentClient().resumeSession(id, options);
+}
+
+/**
+ * One-shot prompt convenience function.
+ *
+ * - Without agentId: uses default agent (like `letta -p`), new conversation
+ * - With agentId: uses specific agent, new conversation
+ * - Uses a short-lived session and returns the final turn result.
+ *
+ * @example
+ * ```typescript
+ * const result = await prompt('What is 2+2?');  // default agent
+ * const result = await prompt('What is the capital of France?', agentId);  // specific agent
+ * ```
+ */
+type TurnSession = LettaCodeSession & {
+  runTurn(message: SendMessage): Promise<SDKResultMessage>;
+};
+
+type InitializableSession = LettaCodeSession & {
+  initialize(): Promise<SDKInitMessage>;
+};
+
+export async function prompt(
+  message: string,
+  agentId?: string
+): Promise<SDKResultMessage> {
+  // Use default agent behavior (like letta -p) when no agentId specified
+  const session = agentId
+    ? createSession(agentId)
+    : createSession();
+
+  try {
+    return await (session as TurnSession).runTurn(message);
+  } finally {
+    session.close();
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════
+// SESSIONLESS APIs
+// ═══════════════════════════════════════════════════════════════
+
+import type { ListMessagesOptions, ListMessagesResult } from "./types.js";
+
+/**
+ * Fetch conversation messages without requiring a pre-existing session.
+ *
+ * Creates a transient CLI subprocess, fetches the requested message page, and
+ * closes the subprocess.  Useful for prefetching conversation histories before
+ * opening a full session (e.g. desktop sidebar warm-up).
+ *
+ * Routing follows the same agent/conversation semantics as session history:
+ * - Pass a conv-xxx conversationId to read a specific conversation.
+ * - Omit conversationId to read the agent's default conversation.
+ *
+ * @param agentId - Agent ID to fetch messages for.
+ * @param options - Pagination / filtering options (same as ListMessagesOptions).
+ *
+ * @example
+ * ```typescript
+ * // Prefetch default conversation
+ * const { messages } = await listMessagesDirect(agentId);
+ *
+ * // Prefetch a specific conversation
+ * const { messages, hasMore, nextBefore } = await listMessagesDirect(agentId, {
+ *   conversationId: 'conv-abc',
+ *   limit: 20,
+ *   order: 'desc',
+ * });
+ * ```
+ */
+export async function listMessagesDirect(
+  agentId: string,
+  options: ListMessagesOptions = {},
+): Promise<ListMessagesResult> {
+  // resumeSession uses --default which maps to the agent's default conversation.
+  // The session is transient: we only need it long enough to list messages.
+  const session = new LettaAgentClient().resumeSession(agentId, {
+    permissionMode: "unrestricted",
+  });
+  await (session as InitializableSession).initialize();
+  try {
+    return await session.listMessages(options);
+  } finally {
+    session.close();
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════
+// IMAGE HELPERS
+// ═══════════════════════════════════════════════════════════════
+
+import { readFileSync } from "node:fs";
+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 function imageFromFile(filePath: string): ImageContent {
+  const data = readFileSync(filePath).toString("base64");
+  const ext = filePath.toLowerCase();
+  const media_type: ImageContent["source"]["media_type"] = 
+    ext.endsWith(".png") ? "image/png"
+    : ext.endsWith(".gif") ? "image/gif"
+    : ext.endsWith(".webp") ? "image/webp"
+    : "image/jpeg";
+  
+  return {
+    type: "image",
+    source: { type: "base64", media_type, data }
+  };
+}
+
+/**
+ * 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 function imageFromBase64(
+  data: string,
+  media_type: ImageContent["source"]["media_type"] = "image/png"
+): ImageContent {
+  return {
+    type: "image",
+    source: { type: "base64", media_type, data }
+  };
+}
+
+/**
+ * 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 async function imageFromURL(url: string): Promise<ImageContent> {
+  const response = await fetch(url);
+  const buffer = await response.arrayBuffer();
+  const data = Buffer.from(buffer).toString("base64");
+  
+  // Detect media type from content-type header or URL
+  const contentType = response.headers.get("content-type");
+  let media_type: ImageContent["source"]["media_type"] = "image/png";
+  
+  if (contentType?.includes("jpeg") || contentType?.includes("jpg") || url.match(/\.jpe?g$/i)) {
+    media_type = "image/jpeg";
+  } else if (contentType?.includes("gif") || url.endsWith(".gif")) {
+    media_type = "image/gif";
+  } else if (contentType?.includes("webp") || url.endsWith(".webp")) {
+    media_type = "image/webp";
+  }
+  
+  return {
+    type: "image",
+    source: { type: "base64", media_type, data }
+  };
+}

package/src/interactiveToolPolicy.ts

@@ -0,0 +1,62 @@
+// Interactive tool policy for SDK permission callbacks.
+// Centralizes behavior so transport/session logic doesn't hardcode names inline.
+
+import type { CanUseToolContext, CanUseToolPermissionSuggestion } from "./types.js";
+
+const INTERACTIVE_APPROVAL_TOOLS = new Set([
+  "AskUserQuestion",
+  "EnterPlanMode",
+  "ExitPlanMode",
+]);
+
+const RUNTIME_USER_INPUT_TOOLS = new Set(["AskUserQuestion", "ExitPlanMode"]);
+
+const HEADLESS_AUTO_ALLOW_TOOLS = new Set(["EnterPlanMode"]);
+
+export function isInteractiveApprovalTool(toolName: string): boolean {
+  return INTERACTIVE_APPROVAL_TOOLS.has(toolName);
+}
+
+export function requiresRuntimeUserInput(toolName: string): boolean {
+  return RUNTIME_USER_INPUT_TOOLS.has(toolName);
+}
+
+export function isHeadlessAutoAllowTool(toolName: string): boolean {
+  return HEADLESS_AUTO_ALLOW_TOOLS.has(toolName);
+}
+
+function normalizePermissionSuggestions(
+  value: unknown,
+): CanUseToolPermissionSuggestion[] | undefined {
+  if (!Array.isArray(value)) return undefined;
+  const suggestions: CanUseToolPermissionSuggestion[] = [];
+  for (const entry of value) {
+    if (!entry || typeof entry !== "object") continue;
+    const record = entry as Record<string, unknown>;
+    if (typeof record.id === "string" && typeof record.text === "string") {
+      suggestions.push({ id: record.id, text: record.text });
+    }
+  }
+  return suggestions;
+}
+
+/**
+ * Build the {@link CanUseToolContext} passed to canUseTool callbacks from a raw
+ * `can_use_tool` control request body. Fields absent from the wire request are
+ * left undefined so callbacks can distinguish "not provided" from empty values.
+ */
+export function buildCanUseToolContext(
+  request: Record<string, unknown>,
+  requestId?: string,
+): CanUseToolContext {
+  const context: CanUseToolContext = {};
+  if (typeof requestId === "string") context.requestId = requestId;
+  if (typeof request.tool_call_id === "string") context.toolCallId = request.tool_call_id;
+  const suggestions = normalizePermissionSuggestions(request.permission_suggestions);
+  if (suggestions !== undefined) context.permissionSuggestions = suggestions;
+  if (typeof request.blocked_path === "string" || request.blocked_path === null) {
+    context.blockedPath = request.blocked_path as string | null;
+  }
+  if (Array.isArray(request.diffs)) context.diffs = request.diffs as unknown[];
+  return context;
+}

package/src/local-app-server-session.ts

@@ -0,0 +1,39 @@
+import {
+  AppServerSession,
+  type AppServerSessionMode,
+  type AppServerSessionOptions,
+} from "./app-server-session.js";
+import { startLocalAppServer } from "./local-app-server.js";
+import type { LettaCodeLocalAppServerOptions } from "./types.js";
+
+export function createLocalAppServerSession(
+  options: LettaCodeLocalAppServerOptions | undefined,
+  mode: AppServerSessionMode,
+  beforeConnect?: () => Promise<void>,
+): AppServerSession {
+  const appServer = options ?? {};
+  const sessionOptions: AppServerSessionOptions = {
+    ...(appServer.url !== undefined
+      ? { url: appServer.url }
+      : {
+          connect: (sessionEnv?: Record<string, string>) =>
+            startLocalAppServer({
+              listen: appServer.listen,
+              backend: appServer.harnessBackend ?? "local",
+              startupTimeoutMs: appServer.startupTimeoutMs,
+              env: sessionEnv,
+            }),
+        }),
+    ...(appServer.WebSocket !== undefined
+      ? { WebSocket: appServer.WebSocket }
+      : {}),
+    ...(appServer.requestTimeoutMs !== undefined
+      ? { requestTimeoutMs: appServer.requestTimeoutMs }
+      : {}),
+    ...(appServer.pinGlobalAgent !== undefined
+      ? { pinGlobalAgent: appServer.pinGlobalAgent }
+      : {}),
+    ...(beforeConnect ? { beforeConnect } : {}),
+  };
+  return new AppServerSession(sessionOptions, mode);
+}

package/src/local-app-server.ts

@@ -0,0 +1,137 @@
+import { spawn, type ChildProcess } from "node:child_process";
+import { findLettaCli } from "./cli-resolver.js";
+
+export interface LocalAppServerHandle {
+  url: string;
+  close(): void;
+}
+
+export interface StartLocalAppServerOptions {
+  listen?: string;
+  backend?: string;
+  startupTimeoutMs?: number;
+  cliPath?: string;
+  env?: Record<string, string | undefined>;
+}
+
+const DEFAULT_LISTEN_URL = "ws://127.0.0.1:0";
+const DEFAULT_STARTUP_TIMEOUT_MS = 30_000;
+const LISTENING_RE = /^Listening on\s+(ws:\/\/\S+)\s*$/m;
+
+function appendLine(buffer: string, chunk: unknown): string {
+  return buffer + String(chunk);
+}
+
+function tryExtractListeningUrl(output: string): string | null {
+  const match = output.match(LISTENING_RE);
+  return match?.[1] ?? null;
+}
+
+export function buildLocalAppServerArgs(
+  cliPath: string,
+  options: Pick<StartLocalAppServerOptions, "backend" | "listen"> = {},
+): string[] {
+  return [
+    cliPath,
+    ...(options.backend !== undefined ? ["--backend", options.backend] : []),
+    "app-server",
+    "--listen",
+    options.listen ?? DEFAULT_LISTEN_URL,
+  ];
+}
+
+function terminateProcess(child: ChildProcess): void {
+  if (child.exitCode !== null || child.signalCode !== null) return;
+  child.kill("SIGTERM");
+  setTimeout(() => {
+    if (child.exitCode === null && child.signalCode === null) {
+      child.kill("SIGKILL");
+    }
+  }, 1_000).unref?.();
+}
+
+/**
+ * Spawn an SDK-owned Letta Code app-server on an ephemeral loopback port.
+ */
+export function startLocalAppServer(
+  options: StartLocalAppServerOptions = {},
+): Promise<LocalAppServerHandle> {
+  const cliPath = options.cliPath ?? findLettaCli();
+  const args = buildLocalAppServerArgs(cliPath, options);
+  const startupTimeoutMs = options.startupTimeoutMs ?? DEFAULT_STARTUP_TIMEOUT_MS;
+
+  return new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, args, {
+      stdio: ["ignore", "pipe", "pipe"],
+      env: { ...process.env, ...(options.env ?? {}) },
+    });
+
+    let settled = false;
+    let output = "";
+
+    const cleanup = () => {
+      child.stdout?.off("data", onStdout);
+      child.stderr?.off("data", onStderr);
+      child.off("error", onError);
+      child.off("exit", onExit);
+      clearTimeout(timeout);
+    };
+
+    const fail = (error: Error) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      terminateProcess(child);
+      reject(error);
+    };
+
+    const succeed = (url: string) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      resolve({
+        url,
+        close: () => terminateProcess(child),
+      });
+    };
+
+    const onOutput = (chunk: unknown) => {
+      output = appendLine(output, chunk);
+      const url = tryExtractListeningUrl(output);
+      if (url) succeed(url);
+    };
+
+    const onStdout = (chunk: unknown) => onOutput(chunk);
+    const onStderr = (chunk: unknown) => {
+      // Startup failures are printed to stderr by the CLI. Keep stderr in the
+      // collected output so timeout/exit errors are actionable.
+      output = appendLine(output, chunk);
+    };
+    const onError = (error: Error) => fail(error);
+    const onExit = (code: number | null, signal: NodeJS.Signals | null) => {
+      if (settled) return;
+      fail(
+        new Error(
+          `Local Letta Code app-server exited before listening (code=${code ?? "null"}, signal=${signal ?? "null"}).${
+            output ? ` Output:\n${output.trim()}` : ""
+          }`,
+        ),
+      );
+    };
+
+    const timeout = setTimeout(() => {
+      fail(
+        new Error(
+          `Timed out waiting for local Letta Code app-server to start.${
+            output ? ` Output:\n${output.trim()}` : ""
+          }`,
+        ),
+      );
+    }, startupTimeoutMs);
+
+    child.stdout?.on("data", onStdout);
+    child.stderr?.on("data", onStderr);
+    child.once("error", onError);
+    child.once("exit", onExit);
+  });
+}