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

package/src/management-types.ts

@@ -1,102 +1,145 @@
+import type {
+  AgentListParams,
+  AgentState,
+  AgentUpdateParams,
+} from "@letta-ai/letta-client/resources/agents/agents";
+import type { Message } from "@letta-ai/letta-client/resources/agents/messages";
+import type {
+  Conversation,
+  ConversationCreateParams,
+  ConversationListParams,
+  ConversationUpdateParams,
+} from "@letta-ai/letta-client/resources/conversations/conversations";
+import type { MessageListParams } from "@letta-ai/letta-client/resources/conversations/messages";
 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;
-};
+export type LettaAgent = AgentState;
 
 /** 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;
-};
+export type LettaConversation = Conversation;
 
 /** Raw Letta API message returned from conversation history. */
-export type LettaConversationMessage = Record<string, unknown>;
+export type LettaConversationMessage = Message;
+
+type Present<T> = Exclude<T, null | undefined>;
 
 export interface ListAgentsOptions {
-  before?: string;
-  after?: string;
-  limit?: number;
+  before?: Present<AgentListParams["before"]>;
+  after?: Present<AgentListParams["after"]>;
+  limit?: Present<AgentListParams["limit"]>;
   order?: "asc" | "desc";
   orderBy?: "createdAt" | "lastRunCompletion";
   /** Search agent names. */
-  query?: string;
+  query?: Present<AgentListParams["query_text"]>;
   /** Match one exact agent name. */
-  name?: string;
-  tags?: string[];
-  matchAllTags?: boolean;
+  name?: Present<AgentListParams["name"]>;
+  tags?: Present<AgentListParams["tags"]>;
+  matchAllTags?: Present<AgentListParams["match_all_tags"]>;
   /** Relationships to hydrate in each returned agent. */
-  include?: string[];
+  include?: Present<AgentListParams["include"]>;
 }
 
 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;
+  name?: AgentUpdateParams["name"];
+  description?: AgentUpdateParams["description"];
+  model?: AgentUpdateParams["model"];
+  modelSettings?: AgentUpdateParams["model_settings"];
+  system?: AgentUpdateParams["system"];
+  tags?: AgentUpdateParams["tags"];
+  hidden?: AgentUpdateParams["hidden"];
+  contextWindowLimit?: AgentUpdateParams["context_window_limit"];
 }
 
 export interface ListConversationsOptions {
-  agentId?: string;
-  after?: string;
-  limit?: number;
-  order?: "asc" | "desc";
+  agentId?: Present<ConversationListParams["agent_id"]>;
+  after?: Present<ConversationListParams["after"]>;
+  limit?: Present<ConversationListParams["limit"]>;
+  order?: Present<ConversationListParams["order"]>;
   orderBy?: "createdAt" | "lastRunCompletion" | "lastMessageAt";
-  archiveStatus?: "unarchived" | "archived" | "all";
-  summarySearch?: string;
+  archiveStatus?: Present<ConversationListParams["archive_status"]>;
+  summarySearch?: Present<ConversationListParams["summary_search"]>;
 }
 
 export interface CreateConversationOptions {
-  agentId: string;
-  summary?: string | null;
-  description?: string | null;
-  model?: string | null;
-  modelSettings?: Record<string, unknown> | null;
-  contextWindowLimit?: number | null;
-  hidden?: boolean;
+  agentId: ConversationCreateParams["agent_id"];
+  summary?: ConversationCreateParams["summary"];
+  description?: ConversationCreateParams["description"];
+  model?: ConversationCreateParams["model"];
+  modelSettings?: ConversationCreateParams["model_settings"];
+  contextWindowLimit?: ConversationCreateParams["context_window_limit"];
+  hidden?: ConversationCreateParams["hidden"];
 }
 
 export interface UpdateConversationOptions {
-  summary?: string | null;
-  description?: string | null;
-  model?: string | null;
-  modelSettings?: Record<string, unknown> | null;
-  contextWindowLimit?: number | null;
-  archived?: boolean | null;
+  summary?: ConversationUpdateParams["summary"];
+  description?: ConversationUpdateParams["description"];
+  model?: ConversationUpdateParams["model"];
+  modelSettings?: ConversationUpdateParams["model_settings"];
+  contextWindowLimit?: ConversationUpdateParams["context_window_limit"];
+  archived?: ConversationUpdateParams["archived"];
 }
 
 export interface ConversationMessagesOptions {
-  before?: string;
-  after?: string;
+  before?: Present<MessageListParams["before"]>;
+  after?: Present<MessageListParams["after"]>;
   order?: "asc" | "desc";
-  limit?: number;
+  limit?: Present<MessageListParams["limit"]>;
+}
+
+export type ConversationMessagesResult = ListMessagesResult;
+
+export type AgentRepositoryPermissions = "read" | "read_write";
+export type AgentRepositoryRecompileTarget = "default" | false;
+
+/** A repository relationship persisted on an agent. */
+export interface AgentRepository {
+  id: string;
+  name: string;
+  isPrimary: boolean;
+  permissions: AgentRepositoryPermissions;
 }
 
-export type ConversationMessagesResult = ListMessagesResult & {
-  messages: LettaConversationMessage[];
-};
+export interface AttachAgentRepositoryOptions {
+  /** Access granted to the agent. Defaults to `read_write` on the server. */
+  permissions?: AgentRepositoryPermissions;
+  /** Recompile the agent's default conversation after attachment. Defaults to `default`. */
+  recompile?: AgentRepositoryRecompileTarget;
+}
+
+export interface DetachAgentRepositoryOptions {
+  /** Recompile the agent's default conversation after detachment. Defaults to `default`. */
+  recompile?: AgentRepositoryRecompileTarget;
+}
+
+/** Persistent agent-repository relationships. Available on the Cloud backend. */
+export interface AgentRepositoriesClient {
+  list(agentId: string): Promise<AgentRepository[]>;
+  /**
+   * Persistently attach a repository, wait for the relationship to become
+   * visible, then recompile the agent's default conversation unless disabled.
+   * If recompilation fails, the relationship remains attached and retrying is safe.
+   */
+  attach(
+    agentId: string,
+    repositoryId: string,
+    options?: AttachAgentRepositoryOptions,
+  ): Promise<AgentRepository>;
+  /**
+   * Persistently detach a repository, wait for the relationship to disappear,
+   * then recompile the agent's default conversation unless disabled. If
+   * recompilation fails, the relationship remains detached and retrying is safe.
+   */
+  detach(
+    agentId: string,
+    repositoryId: string,
+    options?: DetachAgentRepositoryOptions,
+  ): Promise<void>;
+}
 
 export interface AgentsClient {
+  /** Persistent repository relationships for this agent. Cloud only. */
+  readonly repositories: AgentRepositoriesClient;
   list(options?: ListAgentsOptions): Promise<LettaAgent[]>;
   retrieve(agentId: string): Promise<LettaAgent>;
   update(

package/src/management.ts

@@ -1,4 +1,15 @@
 import type {
+  AgentListParams,
+  AgentUpdateParams,
+} from "@letta-ai/letta-client/resources/agents/agents";
+import type {
+  ConversationCreateParams,
+  ConversationListParams,
+  ConversationUpdateParams,
+} from "@letta-ai/letta-client/resources/conversations/conversations";
+import type { MessageListParams } from "@letta-ai/letta-client/resources/conversations/messages";
+import type {
+  AgentRepositoriesClient,
   AgentsClient,
   ConversationsClient,
   ConversationMessagesResult,
@@ -14,60 +25,48 @@ import type {
 } 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[]>;
+  listAgents(query: AgentListParams): Promise<LettaAgent[]>;
   retrieveAgent(agentId: string): Promise<LettaAgent>;
   updateAgent(
     agentId: string,
-    body: Record<string, unknown>,
+    body: AgentUpdateParams,
   ): Promise<LettaAgent>;
   deleteAgent(agentId: string): Promise<void>;
   listModels(): Promise<ListModelsResult>;
   listConversations(
-    query: ManagementQuery,
+    query: ConversationListParams,
   ): Promise<LettaConversation[]>;
   retrieveConversation(
     conversationId: string,
   ): Promise<LettaConversation>;
   createConversation(
-    body: Record<string, unknown>,
+    body: ConversationCreateParams,
   ): Promise<LettaConversation>;
   updateConversation(
     conversationId: string,
-    body: Record<string, unknown>,
+    body: ConversationUpdateParams,
   ): Promise<LettaConversation>;
   listConversationMessages(
     conversationId: string,
-    query: ManagementQuery,
+    query: MessageListParams,
   ): 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()}`,
-  );
+function agentListQuery(options: ListAgentsOptions): AgentListParams {
+  const orderBy = options.orderBy === "createdAt"
+    ? "created_at"
+    : options.orderBy === "lastRunCompletion"
+      ? "last_run_completion"
+      : undefined;
   return {
     before: options.before,
     after: options.after,
@@ -82,8 +81,8 @@ function agentListQuery(options: ListAgentsOptions): ManagementQuery {
   };
 }
 
-function agentUpdateBody(options: UpdateAgentOptions): Record<string, unknown> {
-  return definedEntries({
+function agentUpdateBody(options: UpdateAgentOptions): AgentUpdateParams {
+  return {
     name: options.name,
     description: options.description,
     model: options.model,
@@ -92,16 +91,20 @@ function agentUpdateBody(options: UpdateAgentOptions): Record<string, unknown> {
     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()}`,
-  );
+): ConversationListParams {
+  const orderBy: ConversationListParams["order_by"] =
+    options.orderBy === "createdAt"
+      ? "created_at"
+      : options.orderBy === "lastRunCompletion"
+        ? "last_run_completion"
+        : options.orderBy === "lastMessageAt"
+          ? "last_message_at"
+          : undefined;
   return {
     agent_id: options.agentId,
     after: options.after,
@@ -115,8 +118,8 @@ function conversationListQuery(
 
 function conversationCreateBody(
   options: CreateConversationOptions,
-): Record<string, unknown> {
-  return definedEntries({
+): ConversationCreateParams {
+  return {
     agent_id: options.agentId,
     summary: options.summary,
     description: options.description,
@@ -124,25 +127,25 @@ function conversationCreateBody(
     model_settings: options.modelSettings,
     context_window_limit: options.contextWindowLimit,
     hidden: options.hidden,
-  });
+  };
 }
 
 function conversationUpdateBody(
   options: UpdateConversationOptions,
-): Record<string, unknown> {
-  return definedEntries({
+): ConversationUpdateParams {
+  return {
     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 {
+): MessageListParams {
   return {
     before: options.before,
     after: options.after,
@@ -153,8 +156,12 @@ function conversationMessagesQuery(
 
 export function createAgentsClient(
   transport: TransportProvider,
+  repositories: () => AgentRepositoriesClient,
 ): AgentsClient {
   return {
+    get repositories() {
+      return repositories();
+    },
     list: (options = {}) =>
       transport().listAgents(agentListQuery(options)),
     retrieve: (agentId) => transport().retrieveAgent(agentId),

package/src/remote-session-protocol.ts

@@ -71,11 +71,11 @@ export interface RemoteClientRuntimeController {
     options: RuntimeSendTurnOptions,
   ): void;
   abort(runtime: RuntimeScope): Promise<void>;
-  request(
+  request<TResponse extends ProtocolMessage = ProtocolMessage>(
     type: string,
     body: Record<string, unknown>,
     options?: RuntimeRequestOptions,
-  ): Promise<ProtocolMessage>;
+  ): Promise<TResponse>;
   recoverPendingApprovals(
     runtime: RuntimeScope,
     options?: RecoverPendingApprovalsOptions,
@@ -664,6 +664,10 @@ export function toSessionDeviceStatus(
     isProcessing: status.is_processing,
     permissionMode,
     workingDirectory: status.current_working_directory,
+    memoryDirectory:
+      typeof status.memory_directory === "string"
+        ? status.memory_directory
+        : null,
     pendingControlRequests: pendingControlRequests(status),
     raw: { ...status },
   };

package/src/remote.ts

@@ -1,3 +1,6 @@
+import type Letta from "@letta-ai/letta-client";
+import { createCloudClient } from "./cloud-client.js";
+
 export type RemoteEnvironmentTarget =
   | { connectionId: string }
   | { environmentId: string }
@@ -43,35 +46,6 @@ export interface ResolvedRemoteEnvironment {
   target: RemoteEnvironmentTarget;
 }
 
-type RemoteFetch = typeof fetch;
-
-function getDefaultApiKey(): string | undefined {
-  if (typeof process === "undefined") {
-    return undefined;
-  }
-  return process.env.LETTA_API_KEY;
-}
-
-function createHeaders(options: RemoteEnvironmentClientOptions): Record<string, string> {
-  const apiKey = options.apiKey ?? getDefaultApiKey();
-  return {
-    ...(apiKey ? { Authorization: `Bearer ${apiKey}` } : {}),
-    ...(options.headers ?? {}),
-  };
-}
-
-function getFetch(options: RemoteEnvironmentClientOptions): RemoteFetch {
-  const fetchImpl = options.fetch ?? globalThis.fetch;
-  if (!fetchImpl) {
-    throw new Error("Remote environments require a fetch implementation");
-  }
-  return fetchImpl.bind(globalThis) as RemoteFetch;
-}
-
-function normalizeBaseUrl(baseUrl?: string): string {
-  return (baseUrl ?? "https://api.letta.com").replace(/\/$/, "");
-}
-
 function ensureOnline(
   environment: RemoteEnvironmentConnection,
   target: RemoteEnvironmentTarget,
@@ -95,47 +69,29 @@ function ensureOnline(
   };
 }
 
-async function parseJsonResponse<T>(response: Response): Promise<T> {
-  const text = await response.text();
-  const body = text ? JSON.parse(text) : null;
-
-  if (!response.ok) {
-    const message =
-      body && typeof body === "object" && "message" in body
-        ? String((body as { message: unknown }).message)
-        : response.statusText;
-    throw new Error(`Letta API request failed (${response.status}): ${message}`);
-  }
-
-  return body as T;
-}
-
 /**
- * Small Cloud API helper for resolving explicit Letta Code environments.
+ * Resolve explicit Letta Code environments through the generated Letta client.
  */
 export class RemoteEnvironmentClient {
-  private readonly baseUrl: string;
-  private readonly fetchImpl: RemoteFetch;
-
-  constructor(private readonly options: RemoteEnvironmentClientOptions = {}) {
-    this.baseUrl = normalizeBaseUrl(options.baseUrl);
-    this.fetchImpl = getFetch(options);
-  }
+  constructor(
+    options: RemoteEnvironmentClientOptions = {},
+    private readonly client: Letta = createCloudClient({
+      backend: "cloud",
+      apiBaseUrl: options.baseUrl,
+      apiKey: options.apiKey,
+      headers: options.headers,
+      fetch: options.fetch,
+    }),
+  ) {}
 
   async listEnvironments(): Promise<RemoteEnvironmentListResult> {
-    const url = new URL(`${this.baseUrl}/v1/environments`);
-    const response = await this.fetchImpl(url, {
-      headers: createHeaders(this.options),
-    });
-    return parseJsonResponse<RemoteEnvironmentListResult>(response);
+    return await this.client.environments.list() as RemoteEnvironmentListResult;
   }
 
   async getEnvironmentByDeviceId(deviceId: string): Promise<RemoteEnvironmentConnection> {
-    const response = await this.fetchImpl(
-      `${this.baseUrl}/v1/environments/${encodeURIComponent(deviceId)}`,
-      { headers: createHeaders(this.options) },
-    );
-    return parseJsonResponse<RemoteEnvironmentConnection>(response);
+    return await this.client.environments.retrieve(
+      deviceId,
+    ) as RemoteEnvironmentConnection;
   }
 
   async resolveEnvironment(target: RemoteEnvironmentTarget): Promise<ResolvedRemoteEnvironment> {
@@ -173,5 +129,4 @@ export class RemoteEnvironmentClient {
     }
     return ensureOnline(match, target);
   }
-
 }