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

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,206 @@
+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>;
+  /**
+   * Release the pooled connection, waiting for in-flight work when necessary,
+   * so other clients of the same backend (for example sessions, which compete
+   * for the app-server's single control-client slot) can connect. Optional;
+   * transports whose backend has no such contention (Cloud REST) omit it.
+   */
+  releaseIdleConnection?(): Promise<void> | void;
+}
+
+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),
+      ),
+  };
+}

package/src/protocol.ts

@@ -0,0 +1,249 @@
+/**
+ * Local protocol type surface consumed by the SDK.
+ *
+ * @letta-ai/letta-code@0.27.11 publishes these declarations under an internal
+ * dist path while its package.json points the public `./protocol` export at a
+ * missing file. Keep the SDK's public types self-contained so CI and consumers
+ * do not depend on that broken subpath export.
+ */
+
+export interface MessageEnvelope {
+  type: string;
+  session_id?: string;
+  uuid?: string;
+  timestamp?: string;
+  event_seq?: number;
+  agent_id?: string;
+  conversation_id?: string;
+  [key: string]: unknown;
+}
+
+/**
+ * System prompt preset configuration used by the CLI protocol.
+ */
+export interface SystemPromptPresetConfig {
+  type: "preset";
+  preset: string;
+  append?: string;
+}
+
+/**
+ * Custom memory block definition accepted when creating agents.
+ */
+export interface CreateBlock {
+  label: string;
+  value: string;
+  base_template_id?: string | null;
+  deployment_id?: string | null;
+  description?: string | null;
+  entity_id?: string | null;
+  hidden?: boolean | null;
+  is_template?: boolean;
+  limit?: number;
+  metadata?: Record<string, unknown> | null;
+  preserve_on_migration?: boolean | null;
+  project_id?: string | null;
+  read_only?: boolean;
+  tags?: string[] | null;
+  template_id?: string | null;
+  template_name?: string | null;
+}
+
+export interface SystemInitMessage extends MessageEnvelope {
+  type: "system";
+  subtype: "init";
+  agent_id: string;
+  conversation_id: string;
+  model: string;
+  tools: string[];
+  cwd: string;
+  mcp_servers: Array<{
+    name: string;
+    status: string;
+  }>;
+  permission_mode: string;
+  slash_commands: string[];
+  memfs_enabled?: boolean;
+  skill_sources?: Array<"bundled" | "global" | "agent" | "project">;
+  system_info_reminder_enabled?: boolean;
+  reflection_trigger?: "off" | "step-count" | "compaction-event";
+  reflection_behavior?: "reminder" | "auto-launch";
+  reflection_step_count?: number;
+}
+
+export interface MessageWire extends MessageEnvelope {
+  type: "message";
+  message_type?: string;
+  run_id?: string;
+}
+
+export interface StreamEvent extends MessageEnvelope {
+  type: "stream_event";
+  event: unknown;
+}
+
+export type ResultSubtype = "success" | "interrupted" | "error" | string;
+
+export interface ResultMessage extends MessageEnvelope {
+  type: "result";
+  subtype: ResultSubtype;
+  agent_id?: string;
+  conversation_id: string;
+  duration_ms: number;
+  duration_api_ms?: number;
+  num_turns?: number;
+  result?: string | null;
+  run_ids?: string[];
+  usage?: unknown;
+  stop_reason?: string;
+}
+
+export interface ErrorMessage extends MessageEnvelope {
+  type: "error";
+  message: string;
+  stop_reason: string;
+  run_id?: string;
+  api_error?: Record<string, unknown>;
+}
+
+export interface CanUseToolControlRequest {
+  subtype: "can_use_tool";
+  tool_name: string;
+  input: Record<string, unknown>;
+  tool_call_id: string;
+  permission_suggestions?: unknown[];
+  blocked_path?: string | null;
+  diffs?: unknown[];
+}
+
+export interface RegisterExternalToolsRequest {
+  subtype: "register_external_tools";
+  tools: Array<{
+    name: string;
+    label?: string;
+    description: string;
+    parameters: Record<string, unknown>;
+  }>;
+}
+
+export interface BootstrapSessionStateRequest {
+  subtype: "bootstrap_session_state";
+  limit?: number;
+  order?: "asc" | "desc";
+}
+
+export interface RecoverPendingApprovalsControlRequest {
+  subtype: "recover_pending_approvals";
+  agent_id?: string;
+  conversation_id?: string;
+}
+
+export interface ListMessagesControlRequest {
+  subtype: "list_messages";
+  conversation_id?: string;
+  agent_id?: string;
+  before?: string;
+  after?: string;
+  order?: "asc" | "desc";
+  limit?: number;
+}
+
+export interface InterruptControlRequest {
+  subtype: "interrupt";
+}
+
+export interface InitializeControlRequest {
+  subtype: "initialize";
+}
+
+export interface ExecuteExternalToolControlRequest {
+  subtype: "execute_external_tool";
+  tool_call_id: string;
+  tool_name: string;
+  input: Record<string, unknown>;
+}
+
+export type ControlRequestBody =
+  | InitializeControlRequest
+  | InterruptControlRequest
+  | RegisterExternalToolsRequest
+  | BootstrapSessionStateRequest
+  | RecoverPendingApprovalsControlRequest
+  | ListMessagesControlRequest
+  | CanUseToolControlRequest
+  | ExecuteExternalToolControlRequest
+  | (Record<string, unknown> & { subtype: string });
+
+export interface ControlRequest extends MessageEnvelope {
+  type: "control_request";
+  request_id: string;
+  request: ControlRequestBody;
+}
+
+export interface CanUseToolResponseAllow {
+  behavior: "allow";
+  message?: string;
+  updatedInput?: Record<string, unknown> | null;
+  updatedPermissions?: unknown[];
+}
+
+export interface CanUseToolResponseDeny {
+  behavior: "deny";
+  message: string;
+  interrupt?: boolean;
+}
+
+export type CanUseToolResponse = CanUseToolResponseAllow | CanUseToolResponseDeny;
+
+export interface ExternalToolResultContent {
+  type: "text" | "image";
+  text?: string;
+  data?: string;
+  mimeType?: string;
+}
+
+export interface ExternalToolResultResponse {
+  subtype: "external_tool_result";
+  request_id: string;
+  tool_call_id: string;
+  content: ExternalToolResultContent[];
+  is_error: boolean;
+}
+
+export type ControlResponseBody =
+  | {
+      subtype: "success";
+      request_id: string;
+      response?: CanUseToolResponse | Record<string, unknown>;
+    }
+  | {
+      subtype: "error";
+      request_id: string;
+      error: string;
+    }
+  | ExternalToolResultResponse;
+
+export interface ControlResponse extends MessageEnvelope {
+  type: "control_response";
+  response: ControlResponseBody;
+}
+
+export interface RetryMessage extends MessageEnvelope {
+  type: "retry";
+  reason: string;
+  attempt: number;
+  max_attempts: number;
+  delay_ms: number;
+  run_id?: string;
+}
+
+export type WireMessage =
+  | SystemInitMessage
+  | MessageWire
+  | StreamEvent
+  | ResultMessage
+  | ErrorMessage
+  | RetryMessage
+  | ControlRequest
+  | ControlResponse
+  | (MessageEnvelope & { type: string });