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

package/src/cloud-management.ts

@@ -1,128 +1,48 @@
+import type Letta from "@letta-ai/letta-client";
+import { APIError } from "@letta-ai/letta-client/core/error";
 import type {
-  ManagementQuery,
-  ManagementTransport,
-} from "./management.js";
+  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 { ManagementTransport } from "./management.js";
+import type {
+  AgentRepository,
+  AgentRepositoryPermissions,
   ConversationMessagesResult,
   LettaAgent,
   LettaConversation,
 } from "./management-types.js";
 import type {
-  LettaCodeCloudClientOptions,
   LettaCodeModelEntry,
   ListModelsResult,
 } from "./types.js";
 
-const DEFAULT_CLOUD_API_BASE_URL = "https://api.letta.com";
-
-function defaultApiKey(): string | undefined {
-  const env = (
-    globalThis as {
-      process?: { env?: Record<string, string | undefined> };
-    }
-  ).process?.env;
-  return env?.LETTA_API_KEY ?? env?.LETTA_CLOUD_API_KEY;
-}
-
-function bearerToken(
-  headers: Record<string, string> | undefined,
-): string | undefined {
-  const authorization = headers?.Authorization ?? headers?.authorization;
-  return authorization?.match(/^Bearer\s+(.+)$/i)?.[1];
-}
-
-function apiBaseUrl(value: string | undefined): string {
-  const url = new URL(value ?? DEFAULT_CLOUD_API_BASE_URL);
-  url.pathname = url.pathname.replace(/\/+$/, "");
-  url.search = "";
-  url.hash = "";
-  return url.toString().replace(/\/$/, "");
-}
-
-function requestHeaders(
-  options: LettaCodeCloudClientOptions,
-): Record<string, string> {
-  const headers: Record<string, string> = {
-    "Content-Type": "application/json",
-    ...(options.headers ?? {}),
-  };
-  const apiKey =
-    options.apiKey ?? bearerToken(options.headers) ?? defaultApiKey();
-  if (apiKey && !headers.Authorization && !headers.authorization) {
-    headers.Authorization = `Bearer ${apiKey}`;
-  }
-  return headers;
-}
-
-function appendQuery(url: URL, query: ManagementQuery): void {
-  for (const [key, value] of Object.entries(query)) {
-    if (value === undefined || value === null) continue;
-    if (Array.isArray(value)) {
-      for (const item of value) url.searchParams.append(key, item);
-    } else {
-      url.searchParams.set(key, String(value));
-    }
-  }
-}
-
-async function parseResponse(response: Response): Promise<unknown> {
-  const text = await response.text();
-  if (!text) return null;
-  try {
-    return JSON.parse(text) as unknown;
-  } catch {
-    return text;
-  }
-}
-
-function responseErrorMessage(body: unknown, fallback: string): string {
-  if (body && typeof body === "object") {
-    const record = body as Record<string, unknown>;
-    const message = record.message ?? record.error ?? record.detail;
-    if (typeof message === "string" && message.length > 0) return message;
-  }
-  return fallback;
-}
-
-function cloudRequestError(
-  response: Response,
-  body: unknown,
-  action: string,
-  url: URL,
-  options: LettaCodeCloudClientOptions,
-): Error {
-  const parts = [
-    `${action} failed`,
-    responseErrorMessage(body, `HTTP ${response.status}`),
-    `URL: ${url.toString()}`,
-  ];
-  if (response.status === 401 || response.status === 403) {
-    const hasApiKey = Boolean(
-      options.apiKey ??
-        bearerToken(options.headers) ??
-        defaultApiKey(),
-    );
-    parts.push(
-      hasApiKey
-        ? "Authentication failed — the API key may be invalid or lack permissions for this resource."
-        : "No API key found. Set LETTA_API_KEY (or pass apiKey in client options).",
-    );
-  }
-  return new Error(parts.join(" — "));
-}
-
-function asObject<T>(body: unknown, action: string): T {
+function asAgentRepository(body: unknown, action: string): AgentRepository {
   if (!body || typeof body !== "object" || Array.isArray(body)) {
-    throw new Error(`${action} response did not include an object.`);
+    throw new Error(`${action} response did not include a repository.`);
+  }
+  const repository = body as Record<string, unknown>;
+  const permissions = repository.permissions;
+  if (
+    typeof repository.id !== "string" ||
+    typeof repository.name !== "string" ||
+    typeof repository.is_primary !== "boolean" ||
+    (permissions !== "read" && permissions !== "read_write")
+  ) {
+    throw new Error(`${action} response included an invalid repository.`);
   }
-  return body as T;
-}
-
-function asArray<T>(body: unknown, action: string): T[] {
-  if (!Array.isArray(body)) {
-    throw new Error(`${action} response did not include an array.`);
-  }
-  return body as T[];
+  return {
+    id: repository.id,
+    name: repository.name,
+    isPrimary: repository.is_primary,
+    permissions,
+  };
 }
 
 function cloudModelEntry(
@@ -150,211 +70,144 @@ function cloudModelEntry(
   };
 }
 
+function isNotFound(error: unknown): boolean {
+  return error instanceof APIError && error.status === 404;
+}
+
+/** Cloud management backed by the canonical generated Letta TypeScript client. */
 export class CloudManagementTransport implements ManagementTransport {
-  constructor(private readonly options: LettaCodeCloudClientOptions) {}
+  constructor(private readonly client: Letta) {}
 
-  listAgents(query: ManagementQuery): Promise<LettaAgent[]> {
-    return this.getArray("/v1/agents/", query, "Cloud list agents");
+  async listAgents(query: AgentListParams): Promise<LettaAgent[]> {
+    const page = await this.client.agents.list(query);
+    return page.items;
   }
 
-  retrieveAgent(agentId: string): Promise<LettaAgent> {
-    return this.getObject(
-      `/v1/agents/${encodeURIComponent(agentId)}`,
-      {},
-      "Cloud retrieve agent",
-    );
+  async retrieveAgent(agentId: string): Promise<LettaAgent> {
+    return this.client.agents.retrieve(agentId);
   }
 
-  updateAgent(
+  async updateAgent(
     agentId: string,
-    body: Record<string, unknown>,
+    body: AgentUpdateParams,
   ): Promise<LettaAgent> {
-    return this.requestObject(
-      `/v1/agents/${encodeURIComponent(agentId)}`,
-      "PATCH",
-      body,
-      "Cloud update agent",
-    );
+    return this.client.agents.update(agentId, body);
   }
 
   async deleteAgent(agentId: string): Promise<void> {
-    // No trailing slash: the production api.letta.com router 404s
-    // trailing-slash non-GET agent routes (see `POST /v1/agents` in
-    // cloud-session.ts — GET tolerates the slash; DELETE does not).
-    await this.requestUrl(
-      this.url(`/v1/agents/${encodeURIComponent(agentId)}`),
-      "DELETE",
-      undefined,
-      "Cloud delete agent",
+    await this.client.agents.delete(agentId);
+  }
+
+  async listAgentRepositories(agentId: string): Promise<AgentRepository[]> {
+    const body = await this.client.get<{ repositories: unknown[] }>(
+      `/v1/agents/${encodeURIComponent(agentId)}/repositories`,
+    );
+    if (!Array.isArray(body.repositories)) {
+      throw new Error(
+        "Cloud list agent repositories response did not include repositories.",
+      );
+    }
+    return body.repositories.map((repository) =>
+      asAgentRepository(repository, "Cloud list agent repositories")
     );
   }
 
-  async listModels(): Promise<ListModelsResult> {
-    // No trailing slash for consistency with the non-GET routes above (the
-    // production router only tolerates trailing slashes on GET).
-    const entries = await this.getArray<Record<string, unknown>>(
-      "/v1/models",
-      {},
-      "Cloud list models",
+  async attachAgentRepository(
+    agentId: string,
+    repositoryId: string,
+    permissions: AgentRepositoryPermissions | undefined,
+  ): Promise<AgentRepository> {
+    const body = await this.client.post<{
+      success: boolean;
+      repository: unknown;
+    }>(
+      `/v1/agents/${encodeURIComponent(agentId)}/repositories`,
+      {
+        body: {
+          repository_id: repositoryId,
+          ...(permissions !== undefined ? { permissions } : {}),
+        },
+      },
     );
+    return asAgentRepository(
+      body.repository,
+      "Cloud attach agent repository",
+    );
+  }
+
+  async detachAgentRepository(
+    agentId: string,
+    repositoryId: string,
+  ): Promise<void> {
+    try {
+      await this.client.delete(
+        `/v1/agents/${encodeURIComponent(agentId)}/repositories/${encodeURIComponent(repositoryId)}`,
+      );
+    } catch (error) {
+      if (!isNotFound(error)) throw error;
+    }
+  }
+
+  async recompileAgentSystemPrompt(agentId: string): Promise<void> {
+    await this.client.agents.recompile(agentId);
+  }
+
+  async recompileConversationSystemPrompt(
+    agentId: string,
+    conversationId: string,
+  ): Promise<void> {
+    await this.client.conversations.recompile(conversationId, {
+      agent_id: agentId,
+    });
+  }
+
+  async listModels(): Promise<ListModelsResult> {
+    const entries = await this.client.models.list();
     const normalized = entries.flatMap((entry) => {
-      const model = cloudModelEntry(entry);
+      const model = cloudModelEntry(
+        entry as unknown as Record<string, unknown>,
+      );
       return model ? [model] : [];
     });
     return {
       entries: normalized,
-      // Cloud's authenticated endpoint already returns the models available to
-      // this user, so its catalog is also the authoritative availability set.
       availableHandles: normalized.map((entry) => entry.handle),
     };
   }
 
-  listConversations(
-    query: ManagementQuery,
+  async listConversations(
+    query: ConversationListParams,
   ): Promise<LettaConversation[]> {
-    return this.getArray(
-      "/v1/conversations/",
-      query,
-      "Cloud list conversations",
-    );
+    return this.client.conversations.list(query);
   }
 
-  retrieveConversation(
+  async retrieveConversation(
     conversationId: string,
   ): Promise<LettaConversation> {
-    return this.getObject(
-      `/v1/conversations/${encodeURIComponent(conversationId)}`,
-      {},
-      "Cloud retrieve conversation",
-    );
+    return this.client.conversations.retrieve(conversationId);
   }
 
-  createConversation(
-    body: Record<string, unknown>,
+  async createConversation(
+    body: ConversationCreateParams,
   ): Promise<LettaConversation> {
-    const { agent_id: agentId, ...requestBody } = body;
-    if (typeof agentId !== "string" || agentId.length === 0) {
-      throw new Error("createConversation() requires a non-empty agentId.");
-    }
-    const url = this.url("/v1/conversations/");
-    url.searchParams.set("agent_id", agentId);
-    return this.requestUrlObject(
-      url,
-      "POST",
-      requestBody,
-      "Cloud create conversation",
-    );
+    return this.client.conversations.create(body);
   }
 
-  updateConversation(
+  async updateConversation(
     conversationId: string,
-    body: Record<string, unknown>,
+    body: ConversationUpdateParams,
   ): Promise<LettaConversation> {
-    return this.requestObject(
-      `/v1/conversations/${encodeURIComponent(conversationId)}`,
-      "PATCH",
-      body,
-      "Cloud update conversation",
-    );
+    return this.client.conversations.update(conversationId, body);
   }
 
   async listConversationMessages(
     conversationId: string,
-    query: ManagementQuery,
+    query: MessageListParams,
   ): Promise<ConversationMessagesResult> {
-    const messages = await this.getArray<Record<string, unknown>>(
-      `/v1/conversations/${encodeURIComponent(conversationId)}/messages`,
+    const page = await this.client.conversations.messages.list(
+      conversationId,
       query,
-      "Cloud list conversation messages",
-    );
-    return { messages };
-  }
-
-  private async getArray<T>(
-    path: string,
-    query: ManagementQuery,
-    action: string,
-  ): Promise<T[]> {
-    const body = await this.get(path, query, action);
-    return asArray<T>(body, action);
-  }
-
-  private async getObject<T>(
-    path: string,
-    query: ManagementQuery,
-    action: string,
-  ): Promise<T> {
-    const body = await this.get(path, query, action);
-    return asObject<T>(body, action);
-  }
-
-  private get(
-    path: string,
-    query: ManagementQuery,
-    action: string,
-  ): Promise<unknown> {
-    const url = this.url(path);
-    appendQuery(url, query);
-    return this.requestUrl(url, "GET", undefined, action);
-  }
-
-  private requestObject<T>(
-    path: string,
-    method: string,
-    body: Record<string, unknown>,
-    action: string,
-  ): Promise<T> {
-    return this.requestUrlObject(
-      this.url(path),
-      method,
-      body,
-      action,
-    );
-  }
-
-  private async requestUrlObject<T>(
-    url: URL,
-    method: string,
-    body: Record<string, unknown>,
-    action: string,
-  ): Promise<T> {
-    return asObject<T>(
-      await this.requestUrl(url, method, body, action),
-      action,
-    );
-  }
-
-  private async requestUrl(
-    url: URL,
-    method: string,
-    body: Record<string, unknown> | undefined,
-    action: string,
-  ): Promise<unknown> {
-    const fetchImpl = (this.options.fetch ?? globalThis.fetch)?.bind(
-      globalThis,
     );
-    if (!fetchImpl) {
-      throw new Error("No fetch implementation available for cloud backend.");
-    }
-    const response = await fetchImpl(url, {
-      method,
-      headers: requestHeaders(this.options),
-      ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
-    });
-    const responseBody = await parseResponse(response);
-    if (!response.ok) {
-      throw cloudRequestError(
-        response,
-        responseBody,
-        action,
-        url,
-        this.options,
-      );
-    }
-    return responseBody;
-  }
-
-  private url(path: string): URL {
-    return new URL(`${apiBaseUrl(this.options.apiBaseUrl)}${path}`);
+    return { messages: page.items };
   }
 }