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

package/src/cloud-session.ts

@@ -1,3 +1,6 @@
+import type Letta from "@letta-ai/letta-client";
+import { APIError } from "@letta-ai/letta-client/core/error";
+import type { AgentCreateParams } from "@letta-ai/letta-client/resources/agents/agents";
 import {
   createAppServerClient,
   type AppServerClient,
@@ -11,6 +14,12 @@ import {
   registerAppServerControlRequestHandler,
 } from "./app-server-session.js";
 import { createCloudStatusTransportConstructor } from "./cloud-status-transport.js";
+import { CloudManagementTransport } from "./cloud-management.js";
+import {
+  createCloudClient,
+  getCloudApiKey,
+  normalizeCloudApiBaseUrl,
+} from "./cloud-client.js";
 import {
   RemoteEnvironmentClient,
   type RemoteEnvironmentTarget,
@@ -38,7 +47,6 @@ import {
   validateCloudSandboxOptions,
 } from "./cloud-sandbox.js";
 
-const DEFAULT_CLOUD_API_BASE_URL = "https://api.letta.com";
 const DEFAULT_TURN_TIMEOUT_MS = 120_000;
 const DEFAULT_PING_INTERVAL_MS = 30_000;
 const DEFAULT_SANDBOX_TTL_MINUTES = 5;
@@ -48,8 +56,6 @@ const DEFAULT_REPOSITORY_ATTACH_TIMEOUT_MS = 10_000;
 const DEFAULT_REPOSITORY_ATTACH_POLL_INTERVAL_MS = 250;
 const SDK_AGENT_ORIGIN = "@letta-ai/letta-agent-sdk";
 
-type FetchLike = typeof fetch;
-
 type CloudRuntimeStartResponse = ProtocolMessage & {
   type: "runtime_start_response";
   success: boolean;
@@ -126,37 +132,6 @@ export class CloudManagedSandboxExpiredError extends Error {
 
 type CloudSessionMode = Extract<RuntimeSessionMode, { kind: "session" }>;
 
-type CloudAgentRepository = {
-  id: string;
-  name?: string;
-  is_primary?: boolean;
-};
-
-function getDefaultApiKey(): 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 bearerTokenFromHeaders(headers: Record<string, string> | undefined): string | undefined {
-  const authorization = headers?.Authorization ?? headers?.authorization;
-  if (!authorization) return undefined;
-  const match = /^Bearer\s+(.+)$/i.exec(authorization);
-  return match?.[1];
-}
-
-function getCloudApiKey(options: LettaCodeCloudClientOptions): string | undefined {
-  return options.apiKey ?? bearerTokenFromHeaders(options.headers) ?? getDefaultApiKey();
-}
-
-function getFetch(fetchOverride?: FetchLike): FetchLike {
-  const resolved = fetchOverride ?? globalThis.fetch;
-  if (!resolved) {
-    throw new Error("No fetch implementation available for cloud backend.");
-  }
-  return resolved.bind(globalThis) as FetchLike;
-}
-
 function getWebSocketConstructor(
   websocketOverride?: LettaCodeSocketConstructor,
 ): LettaCodeSocketConstructor {
@@ -169,26 +144,6 @@ function getWebSocketConstructor(
   return resolved;
 }
 
-function normalizeCloudApiBaseUrl(url: string | undefined): string {
-  const parsed = new URL(url ?? DEFAULT_CLOUD_API_BASE_URL);
-  parsed.pathname = parsed.pathname.replace(/\/+$/, "");
-  parsed.search = "";
-  parsed.hash = "";
-  return parsed.toString().replace(/\/$/, "");
-}
-
-function cloudHeaders(options: LettaCodeCloudClientOptions): Record<string, string> {
-  const headers: Record<string, string> = {
-    "Content-Type": "application/json",
-    ...(options.headers ?? {}),
-  };
-  const apiKey = getCloudApiKey(options);
-  if (apiKey && !headers.Authorization && !headers.authorization) {
-    headers.Authorization = `Bearer ${apiKey}`;
-  }
-  return headers;
-}
-
 function cloudWebSocketHeaders(options: LettaCodeCloudClientOptions): Record<string, string> | undefined {
   const headers = { ...(options.headers ?? {}) };
   delete headers.authorization;
@@ -198,45 +153,8 @@ function cloudWebSocketHeaders(options: LettaCodeCloudClientOptions): Record<str
   return Object.keys(headers).length > 0 ? headers : undefined;
 }
 
-async function parseJsonResponse(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;
-    const reasonText = record.reason_text;
-    const pieces = [message, reasonText]
-      .filter((value): value is string => typeof value === "string" && value.length > 0);
-    if (pieces.length > 0) return pieces.join(": ");
-  }
-  return fallback;
-}
-
-function assertOkResponse(response: Response, body: unknown, action: string, url?: string): void {
-  if (!response.ok) {
-    const detail = responseErrorMessage(body, `HTTP ${response.status}`);
-    const parts = [`${action} failed`, detail];
-    if (url) parts.push(`URL: ${url}`);
-    if (response.status === 401 || response.status === 403) {
-      const env = (globalThis as { process?: { env?: Record<string, string | undefined> } })
-        .process?.env;
-      const hasKey = !!(env?.LETTA_API_KEY ?? env?.LETTA_CLOUD_API_KEY);
-      parts.push(
-        hasKey
-          ? "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).",
-      );
-    }
-    throw new Error(parts.join(" — "));
-  }
+function isNotFound(error: unknown): boolean {
+  return error instanceof APIError && error.status === 404;
 }
 
 function validatePositiveInteger(value: number | undefined, name: string): void {
@@ -357,31 +275,15 @@ function externalToolsByName(tools: AnyAgentTool[] | undefined): Map<string, Any
 }
 
 export async function createCloudAgent(
-  clientOptions: LettaCodeCloudClientOptions,
+  client: Letta,
   agentOptions: CreateAgentOptions,
 ): Promise<string> {
   const body = await createAgentBody(agentOptions);
-
-  // No trailing slash: production api.letta.com 404s `POST /v1/agents/` at
-  // the router (GET tolerates the slash; POST does not).
-  const response = await getFetch(clientOptions.fetch)(
-    `${normalizeCloudApiBaseUrl(clientOptions.apiBaseUrl)}/v1/agents`,
-    {
-      method: "POST",
-      headers: cloudHeaders(clientOptions),
-      body: JSON.stringify(body),
-    },
-  );
-  const responseBody = await parseJsonResponse(response);
-  assertOkResponse(response, responseBody, "Cloud create agent");
-  const agentId =
-    responseBody && typeof responseBody === "object"
-      ? (responseBody as { id?: unknown }).id
-      : undefined;
-  if (typeof agentId !== "string" || agentId.length === 0) {
+  const agent = await client.agents.create(body as AgentCreateParams);
+  if (typeof agent.id !== "string" || agent.id.length === 0) {
     throw new Error("Cloud create agent response did not include an agent id.");
   }
-  return agentId;
+  return agent.id;
 }
 
 export function assertCloudSessionOptionsSupported(
@@ -404,24 +306,36 @@ export class CloudEnvironmentSession extends RemoteClientSessionCore {
   private sandboxRefreshInFlight: Promise<void> | null = null;
   private sandboxLifecycleClosing = false;
   private attachedRepositoryIds = new Set<string>();
+  private repositoryIdsRequiringCleanupRecompile = new Set<string>();
+  private readonly repositoryManagement: CloudManagementTransport;
   private readonly cloudMode: CloudSessionMode;
 
   constructor(
     private readonly cloudOptions: LettaCodeCloudClientOptions,
     mode: CloudSessionMode,
+    private readonly apiClient: Letta = createCloudClient(cloudOptions),
   ) {
     super(mode, {
       label: "cloud",
       requestTimeoutMs: cloudOptions.requestTimeoutMs ?? DEFAULT_TURN_TIMEOUT_MS,
     });
     this.cloudMode = mode;
+    this.repositoryManagement = new CloudManagementTransport(apiClient);
     const tools = mode.options.tools;
     this.externalTools = externalToolsByName(tools);
   }
 
   protected override async initializeRuntimeController(): Promise<RuntimeSessionInit> {
     const resolved = await this.resolveRuntime();
-    const connection = await this.resolveConnectionForRuntime(resolved.runtime);
+    const connection = await this.resolveConnectionForRuntime(resolved.runtime).catch(
+      async (error: unknown) => {
+        await this.cleanupSessionRepositories(
+          resolved.runtime.agent_id,
+          resolved.runtime.conversation_id,
+        );
+        throw error;
+      },
+    );
     this.connectionId = connection.connectionId;
 
     const apiKey = getCloudApiKey(this.cloudOptions);
@@ -488,7 +402,10 @@ export class CloudEnvironmentSession extends RemoteClientSessionCore {
       this.removeControlRequestHandler = null;
       client.close();
       await this.cleanupManagedSandbox();
-      await this.cleanupSessionRepositories(resolved.runtime.agent_id);
+      await this.cleanupSessionRepositories(
+        resolved.runtime.agent_id,
+        resolved.runtime.conversation_id,
+      );
       throw error;
     }
   }
@@ -545,7 +462,12 @@ export class CloudEnvironmentSession extends RemoteClientSessionCore {
     this.removeControlRequestHandler?.();
     this.removeControlRequestHandler = null;
     void this.cleanupManagedSandbox();
-    if (this.runtime?.agent_id) void this.cleanupSessionRepositories(this.runtime.agent_id);
+    if (this.runtime?.agent_id) {
+      void this.cleanupSessionRepositories(
+        this.runtime.agent_id,
+        this.runtime.conversation_id,
+      );
+    }
   }
 
   private async resolveRuntime(): Promise<{ runtime: RuntimeScope }> {
@@ -566,29 +488,41 @@ export class CloudEnvironmentSession extends RemoteClientSessionCore {
       );
     }
 
-    await this.attachSessionRepositories(agentId);
+    const shouldRecompileRepositories =
+      await this.attachSessionRepositories(agentId);
 
-    if (this.cloudMode.newConversation) {
-      const conversation = await this.createConversation(agentId);
-      conversationId = conversation.id;
-    } else if (this.cloudMode.defaultConversation) {
-      conversationId = "default";
-    }
+    try {
+      if (this.cloudMode.newConversation) {
+        const conversation = await this.createConversation(agentId);
+        conversationId = conversation.id;
+      } else if (this.cloudMode.defaultConversation) {
+        conversationId = "default";
+      }
 
-    if (!conversationId) {
-      throw new Error(
-        "Letta Cloud createSession()/resumeSession() requires an agent id or conversation id.",
-      );
-    }
+      if (!conversationId) {
+        throw new Error(
+          "Letta Cloud createSession()/resumeSession() requires an agent id or conversation id.",
+        );
+      }
+
+      if (shouldRecompileRepositories) {
+        await this.recompileSystemPrompt(agentId, conversationId);
+      }
 
-    return { runtime: { agent_id: agentId, conversation_id: conversationId } };
+      return { runtime: { agent_id: agentId, conversation_id: conversationId } };
+    } catch (error) {
+      await this.cleanupSessionRepositories(agentId, conversationId);
+      throw error;
+    }
   }
 
-  private async attachSessionRepositories(agentId: string): Promise<void> {
+  private async attachSessionRepositories(agentId: string): Promise<boolean> {
     const resources = this.repositoryResources();
-    if (resources.length === 0) return;
+    if (resources.length === 0) return false;
 
-    const existing = await this.listAgentRepositories(agentId);
+    const existing = await this.repositoryManagement.listAgentRepositories(
+      agentId,
+    );
     const existingIds = new Set(existing.map((repository) => repository.id));
 
     try {
@@ -596,7 +530,11 @@ export class CloudEnvironmentSession extends RemoteClientSessionCore {
         if (existingIds.has(resource.repositoryId) || this.attachedRepositoryIds.has(resource.repositoryId)) {
           continue;
         }
-        await this.linkAgentRepository(agentId, resource.repositoryId);
+        await this.repositoryManagement.attachAgentRepository(
+          agentId,
+          resource.repositoryId,
+          undefined,
+        );
         await this.waitForAgentRepository(agentId, resource.repositoryId);
         this.attachedRepositoryIds.add(resource.repositoryId);
       }
@@ -604,18 +542,70 @@ export class CloudEnvironmentSession extends RemoteClientSessionCore {
       await this.cleanupSessionRepositories(agentId);
       throw error;
     }
+
+    // Recompile even when every requested repository was already linked: the
+    // target conversation may still have been compiled before those links
+    // existed. One recompile after the full batch produces the desired state.
+    const shouldRecompile = resources.some(
+      (resource) => resource.recompile !== false,
+    );
+    this.repositoryIdsRequiringCleanupRecompile = new Set(
+      resources
+        .filter(
+          (resource) =>
+            resource.recompile !== false &&
+            this.attachedRepositoryIds.has(resource.repositoryId),
+        )
+        .map((resource) => resource.repositoryId),
+    );
+    return shouldRecompile;
   }
 
-  private async cleanupSessionRepositories(agentId: string): Promise<void> {
+  private async cleanupSessionRepositories(
+    agentId: string,
+    conversationId?: string,
+  ): Promise<void> {
     const repositoryIds = [...this.attachedRepositoryIds];
+    const repositoryIdsRequiringRecompile =
+      this.repositoryIdsRequiringCleanupRecompile;
     this.attachedRepositoryIds.clear();
-    await Promise.all(repositoryIds.map(async (repositoryId) => {
+    this.repositoryIdsRequiringCleanupRecompile = new Set<string>();
+    const recompileAfterDetach = await Promise.all(repositoryIds.map(async (repositoryId) => {
       try {
-        await this.unlinkAgentRepository(agentId, repositoryId);
+        await this.repositoryManagement.detachAgentRepository(
+          agentId,
+          repositoryId,
+        );
+        return repositoryIdsRequiringRecompile.has(repositoryId);
       } catch {
         // Best-effort cleanup: only repositories this SDK session attached are removed.
+        return false;
       }
     }));
+    // Best-effort recompile after detach so remaining conversations drop stale
+    // repository projections. Errors are swallowed because this runs on close.
+    if (recompileAfterDetach.some(Boolean)) {
+      try {
+        await this.recompileSystemPrompt(agentId, conversationId);
+      } catch {
+        // Best-effort: cleanup must not throw.
+      }
+    }
+  }
+
+  private async recompileSystemPrompt(
+    agentId: string,
+    conversationId?: string,
+  ): Promise<void> {
+    const usesAgentPrompt = !conversationId || conversationId === "default";
+    if (usesAgentPrompt) {
+      await this.repositoryManagement.recompileAgentSystemPrompt(agentId);
+      return;
+    }
+    await this.repositoryManagement.recompileConversationSystemPrompt(
+      agentId,
+      conversationId,
+    );
   }
 
   private repositoryResources(): RepositoryResource[] {
@@ -636,30 +626,12 @@ export class CloudEnvironmentSession extends RemoteClientSessionCore {
     return result;
   }
 
-  private async listAgentRepositories(agentId: string): Promise<CloudAgentRepository[]> {
-    const fetchImpl = getFetch(this.cloudOptions.fetch);
-    const baseUrl = normalizeCloudApiBaseUrl(this.cloudOptions.apiBaseUrl);
-    const response = await fetchImpl(
-      `${baseUrl}/v1/agents/${encodeURIComponent(agentId)}/repositories`,
-      { headers: cloudHeaders(this.cloudOptions) },
-    );
-    const body = await parseJsonResponse(response);
-    assertOkResponse(response, body, "Cloud list agent repositories");
-    if (!body || typeof body !== "object") return [];
-    const repositories = (body as Record<string, unknown>).repositories;
-    return Array.isArray(repositories)
-      ? repositories.filter((repository): repository is CloudAgentRepository => (
-        repository !== null &&
-        typeof repository === "object" &&
-        typeof (repository as Record<string, unknown>).id === "string"
-      ))
-      : [];
-  }
-
   private async waitForAgentRepository(agentId: string, repositoryId: string): Promise<void> {
     const deadline = Date.now() + DEFAULT_REPOSITORY_ATTACH_TIMEOUT_MS;
     while (true) {
-      const repositories = await this.listAgentRepositories(agentId);
+      const repositories = await this.repositoryManagement.listAgentRepositories(
+        agentId,
+      );
       if (repositories.some((repository) => repository.id === repositoryId)) return;
       if (Date.now() >= deadline) {
         throw new Error(`Cloud attach agent repository did not become visible for ${agentId}: ${repositoryId}`);
@@ -668,64 +640,24 @@ export class CloudEnvironmentSession extends RemoteClientSessionCore {
     }
   }
 
-  private async linkAgentRepository(agentId: string, repositoryId: string): Promise<void> {
-    const fetchImpl = getFetch(this.cloudOptions.fetch);
-    const baseUrl = normalizeCloudApiBaseUrl(this.cloudOptions.apiBaseUrl);
-    const response = await fetchImpl(
-      `${baseUrl}/v1/agents/${encodeURIComponent(agentId)}/repositories`,
-      {
-        method: "POST",
-        headers: cloudHeaders(this.cloudOptions),
-        body: JSON.stringify({ repository_id: repositoryId }),
-      },
-    );
-    const body = await parseJsonResponse(response);
-    assertOkResponse(response, body, "Cloud attach agent repository");
-  }
-
-  private async unlinkAgentRepository(agentId: string, repositoryId: string): Promise<void> {
-    const fetchImpl = getFetch(this.cloudOptions.fetch);
-    const baseUrl = normalizeCloudApiBaseUrl(this.cloudOptions.apiBaseUrl);
-    const response = await fetchImpl(
-      `${baseUrl}/v1/agents/${encodeURIComponent(agentId)}/repositories/${encodeURIComponent(repositoryId)}`,
-      { method: "DELETE", headers: cloudHeaders(this.cloudOptions) },
-    );
-    const body = await parseJsonResponse(response);
-    if (response.status === 404) return;
-    assertOkResponse(response, body, "Cloud detach agent repository");
-  }
-
   private async createConversation(agentId: string): Promise<{ id: string; agent_id?: string }> {
-    const fetchImpl = getFetch(this.cloudOptions.fetch);
-    const baseUrl = normalizeCloudApiBaseUrl(this.cloudOptions.apiBaseUrl);
-    const url = new URL(`${baseUrl}/v1/conversations/`);
-    url.searchParams.set("agent_id", agentId);
-    const response = await fetchImpl(url, {
-      method: "POST",
-      headers: cloudHeaders(this.cloudOptions),
-      body: JSON.stringify({}),
+    const conversation = await this.apiClient.conversations.create({
+      agent_id: agentId,
     });
-    const body = await parseJsonResponse(response);
-    assertOkResponse(response, body, "Cloud createSession()", url.toString());
-    if (!isCloudConversation(body)) {
+    if (!isCloudConversation(conversation)) {
       throw new Error("Cloud createSession() response did not include a conversation id.");
     }
-    return { id: body.id, agent_id: body.agent_id };
+    return { id: conversation.id, agent_id: conversation.agent_id };
   }
 
   private async retrieveConversation(conversationId: string): Promise<{ id: string; agent_id?: string }> {
-    const fetchImpl = getFetch(this.cloudOptions.fetch);
-    const baseUrl = normalizeCloudApiBaseUrl(this.cloudOptions.apiBaseUrl);
-    const response = await fetchImpl(
-      `${baseUrl}/v1/conversations/${encodeURIComponent(conversationId)}`,
-      { headers: cloudHeaders(this.cloudOptions) },
+    const conversation = await this.apiClient.conversations.retrieve(
+      conversationId,
     );
-    const body = await parseJsonResponse(response);
-    assertOkResponse(response, body, "Cloud resumeSession()", `${baseUrl}/v1/conversations/${encodeURIComponent(conversationId)}`);
-    if (!isCloudConversation(body)) {
+    if (!isCloudConversation(conversation)) {
       throw new Error(`Cloud resumeSession() could not retrieve conversation ${conversationId}.`);
     }
-    return { id: body.id, agent_id: body.agent_id };
+    return { id: conversation.id, agent_id: conversation.agent_id };
   }
 
   private async resolveConnectionForRuntime(
@@ -787,25 +719,19 @@ export class CloudEnvironmentSession extends RemoteClientSessionCore {
     agentId: string,
     conversationId?: string,
   ): Promise<ManagedCloudSandbox> {
-    const fetchImpl = getFetch(this.cloudOptions.fetch);
-    const baseUrl = normalizeCloudApiBaseUrl(this.cloudOptions.apiBaseUrl);
     const sandboxOptions = this.resolvedSandboxOptions();
     const githubRepositories = sandboxOptions.githubRepositories;
-    const response = await fetchImpl(
-      `${baseUrl}/v1/agents/${encodeURIComponent(agentId)}/sandboxes`,
+    const body = await this.apiClient.post<unknown>(
+      `/v1/agents/${encodeURIComponent(agentId)}/sandboxes`,
       {
-        method: "POST",
-        headers: cloudHeaders(this.cloudOptions),
-        body: JSON.stringify({
+        body: {
           ...(conversationId ? { conversationId } : {}),
           ...(githubRepositories && githubRepositories.length > 0
             ? { githubRepositories }
             : {}),
-        }),
+        },
       },
     );
-    const body = await parseJsonResponse(response);
-    assertOkResponse(response, body, "Cloud create managed sandbox", `${baseUrl}/v1/agents/${encodeURIComponent(agentId)}/sandboxes`);
     if (!isCloudAgentSandbox(body)) {
       throw new Error("Cloud create managed sandbox response did not include sandbox connection details.");
     }
@@ -863,22 +789,17 @@ export class CloudEnvironmentSession extends RemoteClientSessionCore {
   }
 
   private async refreshManagedSandboxOnce(sandbox: ManagedCloudSandbox): Promise<void> {
-    const fetchImpl = getFetch(this.cloudOptions.fetch);
-    const baseUrl = normalizeCloudApiBaseUrl(this.cloudOptions.apiBaseUrl);
-
     if (sandbox.conversationId) {
       // Conversation-scoped sandboxes refresh by id — no "latest active"
       // indirection, so ownership changes are structurally impossible.
-      const response = await fetchImpl(
-        `${baseUrl}/v1/sandboxes/${encodeURIComponent(sandbox.sandboxId)}/refresh`,
-        {
-          method: "POST",
-          headers: cloudHeaders(this.cloudOptions),
-          body: JSON.stringify({ ttlMinutes: sandbox.ttlMinutes }),
-        },
-      );
-      if (response.status === 404) {
-        await parseJsonResponse(response);
+      let body: unknown;
+      try {
+        body = await this.apiClient.post(
+          `/v1/sandboxes/${encodeURIComponent(sandbox.sandboxId)}/refresh`,
+          { body: { ttlMinutes: sandbox.ttlMinutes } },
+        );
+      } catch (error) {
+        if (!isNotFound(error)) throw error;
         // The current control and stream WebSockets are bound to this
         // sandbox's ephemeral connection id. Recreating only the sandbox would
         // leave both sockets targeting the dead connection, so surface a
@@ -889,24 +810,18 @@ export class CloudEnvironmentSession extends RemoteClientSessionCore {
           sandbox.conversationId,
         );
       }
-      const body = await parseJsonResponse(response);
-      assertOkResponse(response, body, "Cloud refresh managed sandbox");
       if (!isCloudAgentSandboxRefresh(body) || !body.success) {
         throw new Error("Cloud refresh managed sandbox response did not confirm refresh.");
       }
       return;
     }
 
-    const response = await fetchImpl(
-      `${baseUrl}/v1/agents/${encodeURIComponent(sandbox.agentId)}/sandboxes/refresh`,
+    const body = await this.apiClient.post<unknown>(
+      `/v1/agents/${encodeURIComponent(sandbox.agentId)}/sandboxes/refresh`,
       {
-        method: "POST",
-        headers: cloudHeaders(this.cloudOptions),
-        body: JSON.stringify({ ttlMinutes: sandbox.ttlMinutes }),
+        body: { ttlMinutes: sandbox.ttlMinutes },
       },
     );
-    const body = await parseJsonResponse(response);
-    assertOkResponse(response, body, "Cloud refresh managed sandbox", `${baseUrl}/v1/agents/${encodeURIComponent(sandbox.agentId)}/sandboxes/refresh`);
     if (!isCloudAgentSandboxRefresh(body) || !body.success) {
       throw new Error("Cloud refresh managed sandbox response did not confirm refresh.");
     }
@@ -918,23 +833,17 @@ export class CloudEnvironmentSession extends RemoteClientSessionCore {
   }
 
   private async terminateManagedSandbox(sandbox: ManagedCloudSandbox): Promise<void> {
-    const fetchImpl = getFetch(this.cloudOptions.fetch);
-    const baseUrl = normalizeCloudApiBaseUrl(this.cloudOptions.apiBaseUrl);
-
     if (sandbox.conversationId) {
       // Terminate exactly this sandbox — the agent-scoped DELETE targets the
       // agent's "latest active" sandbox, which may not be ours.
-      const response = await fetchImpl(
-        `${baseUrl}/v1/sandboxes/${encodeURIComponent(sandbox.sandboxId)}/terminate`,
-        {
-          method: "POST",
-          headers: cloudHeaders(this.cloudOptions),
-          body: JSON.stringify({}),
-        },
-      );
-      const body = await parseJsonResponse(response);
-      if (response.status === 404) return;
-      assertOkResponse(response, body, "Cloud terminate managed sandbox");
+      try {
+        await this.apiClient.post(
+          `/v1/sandboxes/${encodeURIComponent(sandbox.sandboxId)}/terminate`,
+          { body: {} },
+        );
+      } catch (error) {
+        if (!isNotFound(error)) throw error;
+      }
       return;
     }
 
@@ -942,16 +851,13 @@ export class CloudEnvironmentSession extends RemoteClientSessionCore {
     // "latest active" sandbox the DELETE will target is still ours.
     await this.refreshManagedSandbox(sandbox);
 
-    const response = await fetchImpl(
-      `${baseUrl}/v1/agents/${encodeURIComponent(sandbox.agentId)}/sandboxes`,
-      {
-        method: "DELETE",
-        headers: cloudHeaders(this.cloudOptions),
-      },
-    );
-    const body = await parseJsonResponse(response);
-    if (response.status === 404) return;
-    assertOkResponse(response, body, "Cloud terminate managed sandbox", `${baseUrl}/v1/agents/${encodeURIComponent(sandbox.agentId)}/sandboxes`);
+    try {
+      await this.apiClient.delete(
+        `/v1/agents/${encodeURIComponent(sandbox.agentId)}/sandboxes`,
+      );
+    } catch (error) {
+      if (!isNotFound(error)) throw error;
+    }
   }
 
   private async waitForManagedSandboxConnection(
@@ -1027,12 +933,7 @@ export class CloudEnvironmentSession extends RemoteClientSessionCore {
   }
 
   private remoteEnvironmentClient(): RemoteEnvironmentClient {
-    return new RemoteEnvironmentClient({
-      baseUrl: this.cloudOptions.apiBaseUrl,
-      apiKey: getCloudApiKey(this.cloudOptions),
-      headers: this.cloudOptions.headers,
-      fetch: this.cloudOptions.fetch,
-    });
+    return new RemoteEnvironmentClient({}, this.apiClient);
   }
 
   private effectiveEnvironment(): LettaCodeEnvironment | undefined {

package/src/index.ts

@@ -145,6 +145,10 @@ export type {
   AnyAgentTool,
 } from "./types.js";
 export type {
+  AgentRepositoriesClient,
+  AgentRepository,
+  AgentRepositoryRecompileTarget,
+  AttachAgentRepositoryOptions,
   AgentsClient,
   ConversationsClient,
   LettaAgent,
@@ -158,6 +162,8 @@ export type {
   UpdateConversationOptions,
   ConversationMessagesOptions,
   ConversationMessagesResult,
+  DetachAgentRepositoryOptions,
+  AgentRepositoryPermissions,
 } from "./management-types.js";
 
 export { RepositoriesClient } from "./repositories.js";