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

package/src/cloud-management.ts

@@ -0,0 +1,360 @@
+import type {
+  ManagementQuery,
+  ManagementTransport,
+} from "./management.js";
+import type {
+  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 {
+  if (!body || typeof body !== "object" || Array.isArray(body)) {
+    throw new Error(`${action} response did not include an object.`);
+  }
+  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[];
+}
+
+function cloudModelEntry(
+  raw: Record<string, unknown>,
+): LettaCodeModelEntry | null {
+  if (typeof raw.handle !== "string" || raw.handle.length === 0) {
+    return null;
+  }
+  const label =
+    typeof raw.display_name === "string"
+      ? raw.display_name
+      : typeof raw.name === "string"
+        ? raw.name
+        : raw.handle;
+  return {
+    ...raw,
+    id:
+      typeof raw.id === "string" && raw.id.length > 0
+        ? raw.id
+        : raw.handle,
+    handle: raw.handle,
+    label,
+    description:
+      typeof raw.description === "string" ? raw.description : "",
+  };
+}
+
+export class CloudManagementTransport implements ManagementTransport {
+  constructor(private readonly options: LettaCodeCloudClientOptions) {}
+
+  listAgents(query: ManagementQuery): Promise<LettaAgent[]> {
+    return this.getArray("/v1/agents/", query, "Cloud list agents");
+  }
+
+  retrieveAgent(agentId: string): Promise<LettaAgent> {
+    return this.getObject(
+      `/v1/agents/${encodeURIComponent(agentId)}`,
+      {},
+      "Cloud retrieve agent",
+    );
+  }
+
+  updateAgent(
+    agentId: string,
+    body: Record<string, unknown>,
+  ): Promise<LettaAgent> {
+    return this.requestObject(
+      `/v1/agents/${encodeURIComponent(agentId)}`,
+      "PATCH",
+      body,
+      "Cloud update agent",
+    );
+  }
+
+  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",
+    );
+  }
+
+  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",
+    );
+    const normalized = entries.flatMap((entry) => {
+      const model = cloudModelEntry(entry);
+      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,
+  ): Promise<LettaConversation[]> {
+    return this.getArray(
+      "/v1/conversations/",
+      query,
+      "Cloud list conversations",
+    );
+  }
+
+  retrieveConversation(
+    conversationId: string,
+  ): Promise<LettaConversation> {
+    return this.getObject(
+      `/v1/conversations/${encodeURIComponent(conversationId)}`,
+      {},
+      "Cloud retrieve conversation",
+    );
+  }
+
+  createConversation(
+    body: Record<string, unknown>,
+  ): 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",
+    );
+  }
+
+  updateConversation(
+    conversationId: string,
+    body: Record<string, unknown>,
+  ): Promise<LettaConversation> {
+    return this.requestObject(
+      `/v1/conversations/${encodeURIComponent(conversationId)}`,
+      "PATCH",
+      body,
+      "Cloud update conversation",
+    );
+  }
+
+  async listConversationMessages(
+    conversationId: string,
+    query: ManagementQuery,
+  ): Promise<ConversationMessagesResult> {
+    const messages = await this.getArray<Record<string, unknown>>(
+      `/v1/conversations/${encodeURIComponent(conversationId)}/messages`,
+      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}`);
+  }
+}

package/src/cloud-sandbox.ts

@@ -0,0 +1,117 @@
+/** A GitHub repository cloned into an SDK-managed Cloud sandbox. */
+export interface GitHubRepositoryRef {
+  owner: string;
+  repo: string;
+}
+
+export interface LettaCodeCloudSandboxOptions {
+  /**
+   * TTL to request when refreshing an SDK-managed sandbox. Defaults to 5
+   * minutes, matching the Cloud API default. Valid range: 1-60.
+   */
+  ttlMinutes?: number;
+  /** Timeout waiting for a newly created sandbox environment to come online. */
+  readyTimeoutMs?: number;
+  /** Poll interval while waiting for a newly created sandbox environment. */
+  readyPollIntervalMs?: number;
+  /** Interval for proactive TTL refreshes while the session is open. */
+  refreshIntervalMs?: number;
+  /**
+   * GitHub repositories to clone into `/root/workspace` when creating the
+   * managed sandbox. Up to 10 repositories may be provided. Private
+   * repositories require access through the organization's GitHub integration.
+   */
+  githubRepositories?: GitHubRepositoryRef[];
+  /**
+   * Best-effort terminate the SDK-managed sandbox on session close. Defaults to
+   * false so other sessions for the same conversation and reconnecting clients
+   * can continue using it. Set true to restore eager cleanup when this session
+   * exclusively owns the sandbox.
+   */
+  terminateOnClose?: boolean;
+}
+
+const MIN_TTL_MINUTES = 1;
+const MAX_TTL_MINUTES = 60;
+const MAX_GITHUB_REPOSITORIES = 10;
+const GITHUB_OWNER_PATTERN = /^[A-Za-z0-9-]+$/;
+const GITHUB_REPOSITORY_PATTERN = /^[A-Za-z0-9._-]+$/;
+
+function validatePositiveInteger(value: number | undefined, name: string): void {
+  if (value !== undefined && (!Number.isInteger(value) || value <= 0)) {
+    throw new Error(`Invalid ${name}. Expected a positive integer.`);
+  }
+}
+
+export function validateCloudSandboxOptions(
+  options: LettaCodeCloudSandboxOptions | undefined,
+  name: string,
+): void {
+  if (options === undefined) return;
+  if (options === null || typeof options !== "object" || Array.isArray(options)) {
+    throw new Error(`Invalid ${name}. Expected an object.`);
+  }
+  if (
+    options.ttlMinutes !== undefined &&
+    (!Number.isInteger(options.ttlMinutes) ||
+      options.ttlMinutes < MIN_TTL_MINUTES ||
+      options.ttlMinutes > MAX_TTL_MINUTES)
+  ) {
+    throw new Error(
+      `Invalid ${name}.ttlMinutes. Expected an integer between ${MIN_TTL_MINUTES} and ${MAX_TTL_MINUTES}.`,
+    );
+  }
+  validatePositiveInteger(options.readyTimeoutMs, `${name}.readyTimeoutMs`);
+  validatePositiveInteger(
+    options.readyPollIntervalMs,
+    `${name}.readyPollIntervalMs`,
+  );
+  validatePositiveInteger(options.refreshIntervalMs, `${name}.refreshIntervalMs`);
+
+  if (options.githubRepositories !== undefined) {
+    if (!Array.isArray(options.githubRepositories)) {
+      throw new Error(
+        `Invalid ${name}.githubRepositories. Expected an array.`,
+      );
+    }
+    if (options.githubRepositories.length > MAX_GITHUB_REPOSITORIES) {
+      throw new Error(
+        `Invalid ${name}.githubRepositories. Expected at most ${MAX_GITHUB_REPOSITORIES} repositories.`,
+      );
+    }
+    for (const [index, repository] of options.githubRepositories.entries()) {
+      if (
+        repository === null ||
+        typeof repository !== "object" ||
+        Array.isArray(repository)
+      ) {
+        throw new Error(
+          `Invalid ${name}.githubRepositories[${index}]. Expected an object.`,
+        );
+      }
+      if (
+        typeof repository.owner !== "string" ||
+        !GITHUB_OWNER_PATTERN.test(repository.owner)
+      ) {
+        throw new Error(
+          `Invalid ${name}.githubRepositories[${index}].owner.`,
+        );
+      }
+      if (
+        typeof repository.repo !== "string" ||
+        !GITHUB_REPOSITORY_PATTERN.test(repository.repo)
+      ) {
+        throw new Error(
+          `Invalid ${name}.githubRepositories[${index}].repo.`,
+        );
+      }
+    }
+  }
+
+  if (
+    options.terminateOnClose !== undefined &&
+    typeof options.terminateOnClose !== "boolean"
+  ) {
+    throw new Error(`Invalid ${name}.terminateOnClose. Expected a boolean.`);
+  }
+}