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

package/src/local-app-server.ts

@@ -0,0 +1,231 @@
+import { spawn, type ChildProcess } from "node:child_process";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import {
+  createMemoryConfinementLauncher,
+  type MemoryConfinementLauncherInput,
+  type MemoryConfinementLauncherResult,
+} from "@letta-ai/letta-code/memory-confinement";
+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>;
+  filesystemConfinement?: "memory";
+  agentId?: string;
+}
+
+interface LocalAppServerProcess {
+  command: string;
+  args: string[];
+  env: NodeJS.ProcessEnv;
+}
+
+type MemoryConfinementLauncher = (
+  input: MemoryConfinementLauncherInput,
+) => MemoryConfinementLauncherResult;
+
+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 targetHomeDirectory(env: NodeJS.ProcessEnv): string {
+  if (process.platform === "win32") {
+    const profile = env.USERPROFILE?.trim();
+    if (profile) return profile;
+    const drive = env.HOMEDRIVE?.trim();
+    const path = env.HOMEPATH?.trim();
+    if (drive && path) return `${drive}${path}`;
+    return homedir();
+  }
+  return env.HOME?.trim() || homedir();
+}
+
+function withDefaultMemoryDirectory(
+  env: NodeJS.ProcessEnv,
+  options: StartLocalAppServerOptions,
+): NodeJS.ProcessEnv {
+  const explicitMemoryDir = options.env?.MEMORY_DIR?.trim();
+  const explicitLettaMemoryDir = options.env?.LETTA_MEMORY_DIR?.trim();
+  const scopedEnv = { ...env };
+  if (explicitMemoryDir || explicitLettaMemoryDir) {
+    if (!explicitMemoryDir) delete scopedEnv.MEMORY_DIR;
+    if (!explicitLettaMemoryDir) delete scopedEnv.LETTA_MEMORY_DIR;
+    return scopedEnv;
+  }
+
+  // Never inherit the SDK process's agent scope into a different session.
+  delete scopedEnv.MEMORY_DIR;
+  delete scopedEnv.LETTA_MEMORY_DIR;
+  if (!options.agentId) return scopedEnv;
+
+  const homeDir = targetHomeDirectory(env);
+  // Mirrors Letta Code's getScopedMemoryFilesystemRoot contract. The SDK pins
+  // an exact Letta Code version so the launch policy and layout move together.
+  const memoryDir =
+    options.backend === "api"
+      ? join(homeDir, ".letta", "agents", options.agentId, "memory")
+      : join(
+          env.LETTA_LOCAL_BACKEND_DIR?.trim() ||
+            join(homeDir, ".letta", "lc-local-backend"),
+          "memfs",
+          options.agentId,
+          "memory",
+        );
+  return { ...scopedEnv, MEMORY_DIR: memoryDir };
+}
+
+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,
+  ];
+}
+
+export function buildLocalAppServerProcess(
+  cliPath: string,
+  options: StartLocalAppServerOptions = {},
+  confineMemory: MemoryConfinementLauncher = createMemoryConfinementLauncher,
+): LocalAppServerProcess {
+  const env = { ...process.env, ...(options.env ?? {}) };
+  const launcher = [
+    process.execPath,
+    ...buildLocalAppServerArgs(cliPath, options),
+  ];
+  if (options.filesystemConfinement !== "memory") {
+    return {
+      command: launcher[0] as string,
+      args: launcher.slice(1),
+      env,
+    };
+  }
+
+  const confined = confineMemory({
+    launcher,
+    env: withDefaultMemoryDirectory(env, options),
+  });
+  return {
+    command: confined.launcher[0] as string,
+    args: confined.launcher.slice(1),
+    env: confined.env,
+  };
+}
+
+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 processSpec = buildLocalAppServerProcess(cliPath, options);
+  const startupTimeoutMs = options.startupTimeoutMs ?? DEFAULT_STARTUP_TIMEOUT_MS;
+
+  return new Promise((resolve, reject) => {
+    const child = spawn(processSpec.command, processSpec.args, {
+      stdio: ["ignore", "pipe", "pipe"],
+      env: processSpec.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);
+  });
+}

package/src/management-types.ts

@@ -0,0 +1,133 @@
+import type { ListMessagesResult, ListModelsResult } from "./types.js";
+
+/** Agent state returned by either the Cloud API or Letta Code app-server. */
+export type LettaAgent = Record<string, unknown> & {
+  id: string;
+  name: string;
+  description?: string | null;
+  model?: string | null;
+  model_settings?: Record<string, unknown> | null;
+  tags?: string[];
+  created_at?: string | null;
+  updated_at?: string | null;
+};
+
+/** Conversation state returned by either the Cloud API or Letta Code app-server. */
+export type LettaConversation = Record<string, unknown> & {
+  id: string;
+  agent_id: string;
+  summary?: string | null;
+  description?: string | null;
+  model?: string | null;
+  model_settings?: Record<string, unknown> | null;
+  archived?: boolean;
+  created_at?: string | null;
+  updated_at?: string | null;
+  last_message_at?: string | null;
+};
+
+/** Raw Letta API message returned from conversation history. */
+export type LettaConversationMessage = Record<string, unknown>;
+
+export interface ListAgentsOptions {
+  before?: string;
+  after?: string;
+  limit?: number;
+  order?: "asc" | "desc";
+  orderBy?: "createdAt" | "lastRunCompletion";
+  /** Search agent names. */
+  query?: string;
+  /** Match one exact agent name. */
+  name?: string;
+  tags?: string[];
+  matchAllTags?: boolean;
+  /** Relationships to hydrate in each returned agent. */
+  include?: string[];
+}
+
+export interface UpdateAgentOptions {
+  name?: string | null;
+  description?: string | null;
+  model?: string | null;
+  modelSettings?: Record<string, unknown> | null;
+  system?: string | null;
+  tags?: string[] | null;
+  hidden?: boolean | null;
+  contextWindowLimit?: number | null;
+}
+
+export interface ListConversationsOptions {
+  agentId?: string;
+  after?: string;
+  limit?: number;
+  order?: "asc" | "desc";
+  orderBy?: "createdAt" | "lastRunCompletion" | "lastMessageAt";
+  archiveStatus?: "unarchived" | "archived" | "all";
+  summarySearch?: string;
+}
+
+export interface CreateConversationOptions {
+  agentId: string;
+  summary?: string | null;
+  description?: string | null;
+  model?: string | null;
+  modelSettings?: Record<string, unknown> | null;
+  contextWindowLimit?: number | null;
+  hidden?: boolean;
+}
+
+export interface UpdateConversationOptions {
+  summary?: string | null;
+  description?: string | null;
+  model?: string | null;
+  modelSettings?: Record<string, unknown> | null;
+  contextWindowLimit?: number | null;
+  archived?: boolean | null;
+}
+
+export interface ConversationMessagesOptions {
+  before?: string;
+  after?: string;
+  order?: "asc" | "desc";
+  limit?: number;
+}
+
+export type ConversationMessagesResult = ListMessagesResult & {
+  messages: LettaConversationMessage[];
+};
+
+export interface AgentsClient {
+  list(options?: ListAgentsOptions): Promise<LettaAgent[]>;
+  retrieve(agentId: string): Promise<LettaAgent>;
+  update(
+    agentId: string,
+    options: UpdateAgentOptions,
+  ): Promise<LettaAgent>;
+  delete(agentId: string): Promise<void>;
+}
+
+export interface ModelsClient {
+  /**
+   * List the model catalog without opening a session.
+   *
+   * Uses the same normalized result shape as `session.listModels()`, including
+   * availability and BYOK-alias metadata when the backend provides it.
+   */
+  list(): Promise<ListModelsResult>;
+}
+
+export interface ConversationsClient {
+  list(
+    options?: ListConversationsOptions,
+  ): Promise<LettaConversation[]>;
+  retrieve(conversationId: string): Promise<LettaConversation>;
+  create(options: CreateConversationOptions): Promise<LettaConversation>;
+  update(
+    conversationId: string,
+    options: UpdateConversationOptions,
+  ): Promise<LettaConversation>;
+  listMessages(
+    conversationId: string,
+    options?: ConversationMessagesOptions,
+  ): Promise<ConversationMessagesResult>;
+}

package/src/management.ts

@@ -0,0 +1,199 @@
+import type {
+  AgentsClient,
+  ConversationsClient,
+  ConversationMessagesResult,
+  CreateConversationOptions,
+  LettaAgent,
+  LettaConversation,
+  ListAgentsOptions,
+  ListConversationsOptions,
+  ModelsClient,
+  UpdateAgentOptions,
+  UpdateConversationOptions,
+  ConversationMessagesOptions,
+} from "./management-types.js";
+import type { ListModelsResult } from "./types.js";
+
+export type ManagementQuery = Record<
+  string,
+  string | number | boolean | string[] | null | undefined
+>;
+
+export interface ManagementTransport {
+  listAgents(query: ManagementQuery): Promise<LettaAgent[]>;
+  retrieveAgent(agentId: string): Promise<LettaAgent>;
+  updateAgent(
+    agentId: string,
+    body: Record<string, unknown>,
+  ): Promise<LettaAgent>;
+  deleteAgent(agentId: string): Promise<void>;
+  listModels(): Promise<ListModelsResult>;
+  listConversations(
+    query: ManagementQuery,
+  ): Promise<LettaConversation[]>;
+  retrieveConversation(
+    conversationId: string,
+  ): Promise<LettaConversation>;
+  createConversation(
+    body: Record<string, unknown>,
+  ): Promise<LettaConversation>;
+  updateConversation(
+    conversationId: string,
+    body: Record<string, unknown>,
+  ): Promise<LettaConversation>;
+  listConversationMessages(
+    conversationId: string,
+    query: ManagementQuery,
+  ): Promise<ConversationMessagesResult>;
+}
+
+type TransportProvider = () => ManagementTransport;
+
+function definedEntries(
+  values: Record<string, unknown>,
+): Record<string, unknown> {
+  return Object.fromEntries(
+    Object.entries(values).filter(([, value]) => value !== undefined),
+  );
+}
+
+function assertNonEmptyId(value: string, name: string): void {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new Error(`Invalid ${name}. Expected a non-empty string.`);
+  }
+}
+
+function agentListQuery(options: ListAgentsOptions): ManagementQuery {
+  const orderBy = options.orderBy?.replace(
+    /[A-Z]/g,
+    (character) => `_${character.toLowerCase()}`,
+  );
+  return {
+    before: options.before,
+    after: options.after,
+    limit: options.limit,
+    order: options.order,
+    order_by: orderBy,
+    query_text: options.query,
+    name: options.name,
+    tags: options.tags,
+    match_all_tags: options.matchAllTags,
+    include: options.include,
+  };
+}
+
+function agentUpdateBody(options: UpdateAgentOptions): Record<string, unknown> {
+  return definedEntries({
+    name: options.name,
+    description: options.description,
+    model: options.model,
+    model_settings: options.modelSettings,
+    system: options.system,
+    tags: options.tags,
+    hidden: options.hidden,
+    context_window_limit: options.contextWindowLimit,
+  });
+}
+
+function conversationListQuery(
+  options: ListConversationsOptions,
+): ManagementQuery {
+  const orderBy = options.orderBy?.replace(
+    /[A-Z]/g,
+    (character) => `_${character.toLowerCase()}`,
+  );
+  return {
+    agent_id: options.agentId,
+    after: options.after,
+    limit: options.limit,
+    order: options.order,
+    order_by: orderBy,
+    archive_status: options.archiveStatus,
+    summary_search: options.summarySearch,
+  };
+}
+
+function conversationCreateBody(
+  options: CreateConversationOptions,
+): Record<string, unknown> {
+  return definedEntries({
+    agent_id: options.agentId,
+    summary: options.summary,
+    description: options.description,
+    model: options.model,
+    model_settings: options.modelSettings,
+    context_window_limit: options.contextWindowLimit,
+    hidden: options.hidden,
+  });
+}
+
+function conversationUpdateBody(
+  options: UpdateConversationOptions,
+): Record<string, unknown> {
+  return definedEntries({
+    summary: options.summary,
+    description: options.description,
+    model: options.model,
+    model_settings: options.modelSettings,
+    context_window_limit: options.contextWindowLimit,
+    archived: options.archived,
+  });
+}
+
+function conversationMessagesQuery(
+  options: ConversationMessagesOptions,
+): ManagementQuery {
+  return {
+    before: options.before,
+    after: options.after,
+    order: options.order,
+    limit: options.limit,
+  };
+}
+
+export function createAgentsClient(
+  transport: TransportProvider,
+): AgentsClient {
+  return {
+    list: (options = {}) =>
+      transport().listAgents(agentListQuery(options)),
+    retrieve: (agentId) => transport().retrieveAgent(agentId),
+    update: (agentId, options) =>
+      transport().updateAgent(agentId, agentUpdateBody(options)),
+    delete: async (agentId) => {
+      assertNonEmptyId(agentId, "agent id");
+      await transport().deleteAgent(agentId);
+    },
+  };
+}
+
+export function createModelsClient(
+  transport: TransportProvider,
+): ModelsClient {
+  return {
+    list: () => transport().listModels(),
+  };
+}
+
+export function createConversationsClient(
+  transport: TransportProvider,
+): ConversationsClient {
+  return {
+    list: (options = {}) =>
+      transport().listConversations(conversationListQuery(options)),
+    retrieve: (conversationId) =>
+      transport().retrieveConversation(conversationId),
+    create: (options) =>
+      transport().createConversation(conversationCreateBody(options)),
+    update: (conversationId, options) =>
+      transport().updateConversation(
+        conversationId,
+        conversationUpdateBody(options),
+      ),
+    listMessages: (conversationId, options = {}) =>
+      transport().listConversationMessages(
+        conversationId,
+        conversationMessagesQuery(options),
+      ),
+  };
+}