@letta-ai/letta-agent-sdk 0.2.1 → 0.2.5

package/dist/index.js

@@ -1354,6 +1354,249 @@ ${stderr}` : "";
   }
 }
 
+// src/repositories.ts
+var DEFAULT_CLOUD_API_BASE_URL = "https://api.letta.com";
+function getDefaultApiKey() {
+  const env = globalThis.process?.env;
+  return env?.LETTA_API_KEY ?? env?.LETTA_CLOUD_API_KEY;
+}
+function bearerTokenFromHeaders(headers) {
+  const authorization = headers?.Authorization ?? headers?.authorization;
+  if (!authorization)
+    return;
+  const match = /^Bearer\s+(.+)$/i.exec(authorization);
+  return match?.[1];
+}
+function getCloudApiKey(options) {
+  return options.apiKey ?? bearerTokenFromHeaders(options.headers) ?? getDefaultApiKey();
+}
+function getFetch(fetchOverride) {
+  const resolved = fetchOverride ?? globalThis.fetch;
+  if (!resolved)
+    throw new Error("No fetch implementation available for cloud backend.");
+  return resolved.bind(globalThis);
+}
+function normalizeCloudApiBaseUrl(url) {
+  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) {
+  const headers = {
+    "Content-Type": "application/json",
+    ...options.headers ?? {}
+  };
+  const apiKey = getCloudApiKey(options);
+  if (apiKey && !headers.Authorization && !headers.authorization) {
+    headers.Authorization = `Bearer ${apiKey}`;
+  }
+  return headers;
+}
+async function parseJsonResponse(response) {
+  const text = await response.text();
+  if (!text)
+    return null;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+function responseErrorMessage(body, fallback) {
+  if (body && typeof body === "object") {
+    const record = body;
+    const message = record.message ?? record.error ?? record.detail;
+    const reasonText = record.reason_text;
+    const pieces = [message, reasonText].filter((value) => typeof value === "string" && value.length > 0);
+    if (pieces.length > 0)
+      return pieces.join(": ");
+  }
+  return fallback;
+}
+function assertOkResponse(response, body, action) {
+  if (!response.ok) {
+    throw new Error(responseErrorMessage(body, `${action} failed with HTTP ${response.status}`));
+  }
+}
+function optionalString(value) {
+  return typeof value === "string" ? value : undefined;
+}
+function requireString(value, name) {
+  if (typeof value !== "string")
+    throw new Error(`Cloud repositories response missing ${name}.`);
+  return value;
+}
+function toRepository(body) {
+  if (!body || typeof body !== "object") {
+    throw new Error("Cloud repositories response did not include a repository.");
+  }
+  const record = body;
+  return {
+    id: requireString(record.id, "id"),
+    name: requireString(record.name, "name"),
+    createdAt: requireString(record.created_at, "created_at"),
+    updatedAt: requireString(record.updated_at, "updated_at")
+  };
+}
+function toFileMutation(body) {
+  if (!body || typeof body !== "object") {
+    throw new Error("Cloud repositories file response did not include file details.");
+  }
+  const record = body;
+  return {
+    path: requireString(record.path, "path"),
+    contentSha256: requireString(record.content_sha256, "content_sha256"),
+    commitSha: requireString(record.commit_sha, "commit_sha")
+  };
+}
+function addOptionalSearchParam(url, key, value) {
+  if (value !== undefined)
+    url.searchParams.set(key, String(value));
+}
+
+class RepositoriesClient {
+  options;
+  constructor(options) {
+    this.options = options;
+  }
+  async create(params) {
+    return toRepository(await this.request("/v1/repositories", "POST", { name: params.name }, "Cloud create repository"));
+  }
+  async list(params = {}) {
+    const url = this.url("/v1/repositories");
+    addOptionalSearchParam(url, "limit", params.limit);
+    addOptionalSearchParam(url, "offset", params.offset);
+    const body = await this.requestUrl(url, "GET", undefined, "Cloud list repositories");
+    if (!body || typeof body !== "object") {
+      throw new Error("Cloud list repositories response did not include repositories.");
+    }
+    const record = body;
+    const repositories = Array.isArray(record.repositories) ? record.repositories.map(toRepository) : [];
+    return {
+      repositories,
+      hasNextPage: record.has_next_page === true
+    };
+  }
+  async get(repositoryId) {
+    return toRepository(await this.request(`/v1/repositories/${encodeURIComponent(repositoryId)}`, "GET", undefined, "Cloud get repository"));
+  }
+  async delete(repositoryId) {
+    await this.request(`/v1/repositories/${encodeURIComponent(repositoryId)}`, "DELETE", undefined, "Cloud delete repository");
+  }
+  files = {
+    list: async (repositoryId, params = {}) => {
+      const url = this.url(`/v1/repositories/${encodeURIComponent(repositoryId)}/files`);
+      addOptionalSearchParam(url, "path_prefix", params.pathPrefix);
+      addOptionalSearchParam(url, "depth", params.depth);
+      addOptionalSearchParam(url, "ref", params.ref);
+      const body = await this.requestUrl(url, "GET", undefined, "Cloud list repository files");
+      if (!body || typeof body !== "object") {
+        throw new Error("Cloud list repository files response did not include files.");
+      }
+      const record = body;
+      const files = Array.isArray(record.files) ? record.files.map((entry) => {
+        if (!entry || typeof entry !== "object") {
+          throw new Error("Cloud list repository files response included an invalid file entry.");
+        }
+        const file = entry;
+        const type = file.type;
+        if (type !== "file" && type !== "directory") {
+          throw new Error("Cloud list repository files response included an invalid file type.");
+        }
+        return { path: requireString(file.path, "path"), type };
+      }) : [];
+      return { files, ref: requireString(record.ref, "ref") };
+    },
+    create: async (repositoryId, params) => toFileMutation(await this.request(`/v1/repositories/${encodeURIComponent(repositoryId)}/files`, "POST", { path: params.path, content: params.content }, "Cloud create repository file")),
+    read: async (repositoryId, params) => {
+      const url = this.url(`/v1/repositories/${encodeURIComponent(repositoryId)}/files/content`);
+      url.searchParams.set("path", params.path);
+      addOptionalSearchParam(url, "ref", params.ref);
+      const body = await this.requestUrl(url, "GET", undefined, "Cloud read repository file");
+      if (!body || typeof body !== "object") {
+        throw new Error("Cloud read repository file response did not include file content.");
+      }
+      const record = body;
+      return {
+        path: requireString(record.path, "path"),
+        content: requireString(record.content, "content"),
+        contentSha256: requireString(record.content_sha256, "content_sha256"),
+        ref: optionalString(record.ref)
+      };
+    },
+    update: async (repositoryId, params) => toFileMutation(await this.request(`/v1/repositories/${encodeURIComponent(repositoryId)}/files/content`, "POST", {
+      path: params.path,
+      ...params.content !== undefined ? { content: params.content } : {},
+      ...params.newPath !== undefined ? { new_path: params.newPath } : {},
+      ...params.precondition !== undefined ? {
+        precondition: {
+          type: "content_sha256",
+          content_sha256: params.precondition.contentSha256
+        }
+      } : {}
+    }, "Cloud update repository file")),
+    delete: async (repositoryId, params) => {
+      const body = await this.request(`/v1/repositories/${encodeURIComponent(repositoryId)}/files/content`, "DELETE", { path: params.path }, "Cloud delete repository file");
+      if (!body || typeof body !== "object") {
+        throw new Error("Cloud delete repository file response did not include delete details.");
+      }
+      const record = body;
+      return { success: record.success === true, commitSha: requireString(record.commit_sha, "commit_sha") };
+    }
+  };
+  versions = {
+    list: async (repositoryId, params = {}) => {
+      const url = this.url(`/v1/repositories/${encodeURIComponent(repositoryId)}/versions`);
+      addOptionalSearchParam(url, "path", params.path);
+      addOptionalSearchParam(url, "limit", params.limit);
+      const body = await this.requestUrl(url, "GET", undefined, "Cloud list repository versions");
+      if (Array.isArray(body))
+        return body;
+      if (body && typeof body === "object") {
+        const record = body;
+        if (Array.isArray(record.commits))
+          return record.commits;
+        if (Array.isArray(record.versions))
+          return record.versions;
+      }
+      return [];
+    },
+    get: async (repositoryId, sha, params) => {
+      const url = this.url(`/v1/repositories/${encodeURIComponent(repositoryId)}/versions/${encodeURIComponent(sha)}`);
+      url.searchParams.set("path", params.path);
+      const body = await this.requestUrl(url, "GET", undefined, "Cloud get repository version");
+      if (!body || typeof body !== "object") {
+        throw new Error("Cloud get repository version response did not include file content.");
+      }
+      const record = body;
+      return {
+        path: requireString(record.path, "path"),
+        content: requireString(record.content, "content"),
+        contentSha256: requireString(record.content_sha256, "content_sha256"),
+        ref: requireString(record.sha, "sha")
+      };
+    }
+  };
+  url(path) {
+    return new URL(`${normalizeCloudApiBaseUrl(this.options.apiBaseUrl)}${path}`);
+  }
+  async request(path, method, body, action) {
+    return this.requestUrl(this.url(path), method, body, action);
+  }
+  async requestUrl(url, method, body, action) {
+    const response = await getFetch(this.options.fetch)(url, {
+      method,
+      headers: cloudHeaders(this.options),
+      ...body !== undefined ? { body: JSON.stringify(body) } : {}
+    });
+    const parsed = await parseJsonResponse(response);
+    assertOkResponse(response, parsed, action);
+    return parsed;
+  }
+}
+
 // node_modules/@letta-ai/letta-code/dist/app-server-client.js
 var DEFAULT_REQUEST_TIMEOUT_MS = 30000;
 var WEBSOCKET_OPEN_STATE = 1;
@@ -2991,11 +3234,11 @@ function createAgentBody(options, settings = {}) {
   if (options.systemPrompt !== undefined) {
     if (typeof options.systemPrompt === "string") {
       if (isPresetSystemPrompt(options.systemPrompt)) {
-        throw new Error("App-server createAgent() does not yet support system prompt presets.");
+        throw new Error("createAgent() does not yet support system prompt presets for this backend.");
       }
       body.system = options.systemPrompt;
     } else {
-      throw new Error("App-server createAgent() does not yet support system prompt preset objects.");
+      throw new Error("createAgent() does not yet support system prompt preset objects for this backend.");
     }
   }
   const memoryBlocks = [];
@@ -3479,20 +3722,20 @@ class AppServerSession extends RemoteClientSessionCore {
 }
 
 // src/remote.ts
-function getDefaultApiKey() {
+function getDefaultApiKey2() {
   if (typeof process === "undefined") {
     return;
   }
   return process.env.LETTA_API_KEY;
 }
 function createHeaders(options) {
-  const apiKey = options.apiKey ?? getDefaultApiKey();
+  const apiKey = options.apiKey ?? getDefaultApiKey2();
   return {
     ...apiKey ? { Authorization: `Bearer ${apiKey}` } : {},
     ...options.headers ?? {}
   };
 }
-function getFetch(options) {
+function getFetch2(options) {
   const fetchImpl = options.fetch ?? globalThis.fetch;
   if (!fetchImpl) {
     throw new Error("Remote environments require a fetch implementation");
@@ -3513,7 +3756,7 @@ function ensureOnline(environment, target) {
     target
   };
 }
-async function parseJsonResponse(response) {
+async function parseJsonResponse2(response) {
   const text = await response.text();
   const body = text ? JSON.parse(text) : null;
   if (!response.ok) {
@@ -3530,18 +3773,18 @@ class RemoteEnvironmentClient {
   constructor(options = {}) {
     this.options = options;
     this.baseUrl = normalizeBaseUrl2(options.baseUrl);
-    this.fetchImpl = getFetch(options);
+    this.fetchImpl = getFetch2(options);
   }
   async listEnvironments() {
     const url = new URL(`${this.baseUrl}/v1/environments`);
     const response = await this.fetchImpl(url, {
       headers: createHeaders(this.options)
     });
-    return parseJsonResponse(response);
+    return parseJsonResponse2(response);
   }
   async getEnvironmentByDeviceId(deviceId) {
     const response = await this.fetchImpl(`${this.baseUrl}/v1/environments/${encodeURIComponent(deviceId)}`, { headers: createHeaders(this.options) });
-    return parseJsonResponse(response);
+    return parseJsonResponse2(response);
   }
   async resolveEnvironment(target) {
     if ("connectionId" in target) {
@@ -3574,7 +3817,7 @@ class RemoteEnvironmentClient {
 }
 
 // src/cloud-session.ts
-var DEFAULT_CLOUD_API_BASE_URL = "https://api.letta.com";
+var DEFAULT_CLOUD_API_BASE_URL2 = "https://api.letta.com";
 var DEFAULT_TURN_TIMEOUT_MS = 120000;
 var DEFAULT_PING_INTERVAL_MS = 30000;
 var DEFAULT_SANDBOX_TTL_MINUTES = 5;
@@ -3582,25 +3825,27 @@ var MIN_SANDBOX_TTL_MINUTES = 1;
 var MAX_SANDBOX_TTL_MINUTES = 60;
 var DEFAULT_SANDBOX_READY_TIMEOUT_MS = 120000;
 var DEFAULT_SANDBOX_READY_POLL_INTERVAL_MS = 1000;
+var DEFAULT_REPOSITORY_ATTACH_TIMEOUT_MS = 1e4;
+var DEFAULT_REPOSITORY_ATTACH_POLL_INTERVAL_MS = 250;
 var SDK_AGENT_ORIGIN = "@letta-ai/letta-agent-sdk";
 
 class CloudManagedSandboxOwnershipError extends Error {
 }
-function getDefaultApiKey2() {
+function getDefaultApiKey3() {
   const env = globalThis.process?.env;
   return env?.LETTA_API_KEY ?? env?.LETTA_CLOUD_API_KEY;
 }
-function bearerTokenFromHeaders(headers) {
+function bearerTokenFromHeaders2(headers) {
   const authorization = headers?.Authorization ?? headers?.authorization;
   if (!authorization)
     return;
   const match = /^Bearer\s+(.+)$/i.exec(authorization);
   return match?.[1];
 }
-function getCloudApiKey(options) {
-  return options.apiKey ?? bearerTokenFromHeaders(options.headers) ?? getDefaultApiKey2();
+function getCloudApiKey2(options) {
+  return options.apiKey ?? bearerTokenFromHeaders2(options.headers) ?? getDefaultApiKey3();
 }
-function getFetch2(fetchOverride) {
+function getFetch3(fetchOverride) {
   const resolved = fetchOverride ?? globalThis.fetch;
   if (!resolved) {
     throw new Error("No fetch implementation available for cloud backend.");
@@ -3614,19 +3859,19 @@ function getWebSocketConstructor(websocketOverride) {
   }
   return resolved;
 }
-function normalizeCloudApiBaseUrl(url) {
-  const parsed = new URL(url ?? DEFAULT_CLOUD_API_BASE_URL);
+function normalizeCloudApiBaseUrl2(url) {
+  const parsed = new URL(url ?? DEFAULT_CLOUD_API_BASE_URL2);
   parsed.pathname = parsed.pathname.replace(/\/+$/, "");
   parsed.search = "";
   parsed.hash = "";
   return parsed.toString().replace(/\/$/, "");
 }
-function cloudHeaders(options) {
+function cloudHeaders2(options) {
   const headers = {
     "Content-Type": "application/json",
     ...options.headers ?? {}
   };
-  const apiKey = getCloudApiKey(options);
+  const apiKey = getCloudApiKey2(options);
   if (apiKey && !headers.Authorization && !headers.authorization) {
     headers.Authorization = `Bearer ${apiKey}`;
   }
@@ -3636,12 +3881,12 @@ function cloudWebSocketHeaders(options) {
   const headers = { ...options.headers ?? {} };
   delete headers.authorization;
   delete headers.Authorization;
-  const apiKey = getCloudApiKey(options);
+  const apiKey = getCloudApiKey2(options);
   if (apiKey)
     headers.Authorization = `Bearer ${apiKey}`;
   return Object.keys(headers).length > 0 ? headers : undefined;
 }
-async function parseJsonResponse2(response) {
+async function parseJsonResponse3(response) {
   const text = await response.text();
   if (!text)
     return null;
@@ -3651,7 +3896,7 @@ async function parseJsonResponse2(response) {
     return text;
   }
 }
-function responseErrorMessage(body, fallback) {
+function responseErrorMessage2(body, fallback) {
   if (body && typeof body === "object") {
     const record = body;
     const message = record.message ?? record.error ?? record.detail;
@@ -3662,9 +3907,9 @@ function responseErrorMessage(body, fallback) {
   }
   return fallback;
 }
-function assertOkResponse(response, body, action) {
+function assertOkResponse2(response, body, action) {
   if (!response.ok) {
-    throw new Error(responseErrorMessage(body, `${action} failed with HTTP ${response.status}`));
+    throw new Error(responseErrorMessage2(body, `${action} failed with HTTP ${response.status}`));
   }
 }
 function validatePositiveInteger(value, name) {
@@ -3724,7 +3969,7 @@ function environmentToRemoteTarget(environment) {
   throw new Error("Unknown cloud environment selector.");
 }
 function buildCloudStatusWebSocketUrl(params) {
-  const base = new URL(normalizeCloudApiBaseUrl(params.apiBaseUrl));
+  const base = new URL(normalizeCloudApiBaseUrl2(params.apiBaseUrl));
   if (base.protocol === "http:") {
     base.protocol = "ws:";
   } else if (base.protocol === "https:") {
@@ -3771,7 +4016,7 @@ function messageEventData(event) {
 function createCloudStatusWebSocketConstructor(params) {
   const WebSocketCtor = getWebSocketConstructor(params.cloudOptions.WebSocket);
   const authMode = params.cloudOptions.webSocketAuth ?? "header";
-  const cloudHeaders2 = authMode === "header" ? cloudWebSocketHeaders(params.cloudOptions) : undefined;
+  const cloudHeaders3 = authMode === "header" ? cloudWebSocketHeaders(params.cloudOptions) : undefined;
   const pingIntervalMs = params.cloudOptions.pingIntervalMs ?? DEFAULT_PING_INTERVAL_MS;
   const state = {
     runtime: params.runtime,
@@ -3791,7 +4036,7 @@ function createCloudStatusWebSocketConstructor(params) {
       this.channel = new URL(url).searchParams.get("channel");
       const mergedHeaders = authMode === "header" ? {
         ...options?.headers ?? {},
-        ...cloudHeaders2 ?? {}
+        ...cloudHeaders3 ?? {}
       } : undefined;
       const socketOptions = mergedHeaders && Object.keys(mergedHeaders).length > 0 ? { headers: mergedHeaders } : undefined;
       this.socket = new WebSocketCtor(url, socketOptions);
@@ -3951,10 +4196,10 @@ function externalToolsByName(tools) {
 }
 function cloudHarnessAppServerOptions(clientOptions) {
   const appServer = clientOptions.appServer;
-  const apiKey = getCloudApiKey(clientOptions);
+  const apiKey = getCloudApiKey2(clientOptions);
   const localEnv = {
     ...apiKey ? { LETTA_API_KEY: apiKey } : {},
-    ...clientOptions.apiBaseUrl ? { LETTA_BASE_URL: normalizeCloudApiBaseUrl(clientOptions.apiBaseUrl) } : {}
+    ...clientOptions.apiBaseUrl ? { LETTA_BASE_URL: normalizeCloudApiBaseUrl2(clientOptions.apiBaseUrl) } : {}
   };
   return {
     local: appServer?.url === undefined,
@@ -4013,6 +4258,7 @@ class CloudEnvironmentSession extends RemoteClientSessionCore {
   managedSandbox = null;
   sandboxRefreshTimer = null;
   sandboxRefreshInFlight = null;
+  attachedRepositoryIds = new Set;
   cloudMode;
   constructor(cloudOptions, mode) {
     super(mode, {
@@ -4028,7 +4274,7 @@ class CloudEnvironmentSession extends RemoteClientSessionCore {
     const resolved = await this.resolveRuntime();
     const connection = await this.resolveConnectionForRuntime(resolved.runtime);
     this.connectionId = connection.connectionId;
-    const apiKey = getCloudApiKey(this.cloudOptions);
+    const apiKey = getCloudApiKey2(this.cloudOptions);
     const url = buildCloudStatusWebSocketUrl({
       apiBaseUrl: this.cloudOptions.apiBaseUrl,
       connectionId: connection.connectionId,
@@ -4076,6 +4322,7 @@ class CloudEnvironmentSession extends RemoteClientSessionCore {
       this.removeControlRequestHandler = null;
       client.close();
       await this.cleanupManagedSandbox();
+      await this.cleanupSessionRepositories(resolved.runtime.agent_id);
       throw error;
     }
   }
@@ -4123,16 +4370,12 @@ class CloudEnvironmentSession extends RemoteClientSessionCore {
     this.removeControlRequestHandler?.();
     this.removeControlRequestHandler = null;
     this.cleanupManagedSandbox();
+    if (this.runtime?.agent_id)
+      this.cleanupSessionRepositories(this.runtime.agent_id);
   }
   async resolveRuntime() {
     let agentId = this.cloudMode.agentId;
     let conversationId = this.cloudMode.conversationId;
-    if (agentId && this.cloudMode.newConversation) {
-      const conversation = await this.createConversation(agentId);
-      conversationId = conversation.id;
-    } else if (agentId && this.cloudMode.defaultConversation) {
-      conversationId = "default";
-    }
     if (!agentId && conversationId) {
       const conversation = await this.retrieveConversation(conversationId);
       if (!conversation.agent_id) {
@@ -4140,34 +4383,134 @@ class CloudEnvironmentSession extends RemoteClientSessionCore {
       }
       agentId = conversation.agent_id;
     }
-    if (!agentId || !conversationId) {
+    if (!agentId) {
+      throw new Error("Constellation createSession()/resumeSession() requires an agent id or conversation id.");
+    }
+    await this.attachSessionRepositories(agentId);
+    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("Constellation createSession()/resumeSession() requires an agent id or conversation id.");
     }
     return { runtime: { agent_id: agentId, conversation_id: conversationId } };
   }
+  async attachSessionRepositories(agentId) {
+    const resources = this.repositoryResources();
+    if (resources.length === 0)
+      return;
+    const existing = await this.listAgentRepositories(agentId);
+    const existingIds = new Set(existing.map((repository) => repository.id));
+    try {
+      for (const resource of resources) {
+        if (existingIds.has(resource.repositoryId) || this.attachedRepositoryIds.has(resource.repositoryId)) {
+          continue;
+        }
+        await this.linkAgentRepository(agentId, resource.repositoryId);
+        await this.waitForAgentRepository(agentId, resource.repositoryId);
+        this.attachedRepositoryIds.add(resource.repositoryId);
+      }
+    } catch (error) {
+      await this.cleanupSessionRepositories(agentId);
+      throw error;
+    }
+  }
+  async cleanupSessionRepositories(agentId) {
+    const repositoryIds = [...this.attachedRepositoryIds];
+    this.attachedRepositoryIds.clear();
+    await Promise.all(repositoryIds.map(async (repositoryId) => {
+      try {
+        await this.unlinkAgentRepository(agentId, repositoryId);
+      } catch {}
+    }));
+  }
+  repositoryResources() {
+    const resources = this.cloudMode.options.resources ?? [];
+    const seen = new Set;
+    const result = [];
+    for (const resource of resources) {
+      if (resource.type !== "repository") {
+        throw new Error(`Unsupported Cloud session resource type: ${String(resource.type)}`);
+      }
+      if (typeof resource.repositoryId !== "string" || resource.repositoryId.length === 0) {
+        throw new Error("Cloud session repository resources require repositoryId.");
+      }
+      if (seen.has(resource.repositoryId))
+        continue;
+      seen.add(resource.repositoryId);
+      result.push(resource);
+    }
+    return result;
+  }
+  async listAgentRepositories(agentId) {
+    const fetchImpl = getFetch3(this.cloudOptions.fetch);
+    const baseUrl = normalizeCloudApiBaseUrl2(this.cloudOptions.apiBaseUrl);
+    const response = await fetchImpl(`${baseUrl}/v1/agents/${encodeURIComponent(agentId)}/repositories`, { headers: cloudHeaders2(this.cloudOptions) });
+    const body = await parseJsonResponse3(response);
+    assertOkResponse2(response, body, "Cloud list agent repositories");
+    if (!body || typeof body !== "object")
+      return [];
+    const repositories = body.repositories;
+    return Array.isArray(repositories) ? repositories.filter((repository) => repository !== null && typeof repository === "object" && typeof repository.id === "string") : [];
+  }
+  async waitForAgentRepository(agentId, repositoryId) {
+    const deadline = Date.now() + DEFAULT_REPOSITORY_ATTACH_TIMEOUT_MS;
+    while (true) {
+      const repositories = await this.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}`);
+      }
+      await sleep(DEFAULT_REPOSITORY_ATTACH_POLL_INTERVAL_MS);
+    }
+  }
+  async linkAgentRepository(agentId, repositoryId) {
+    const fetchImpl = getFetch3(this.cloudOptions.fetch);
+    const baseUrl = normalizeCloudApiBaseUrl2(this.cloudOptions.apiBaseUrl);
+    const response = await fetchImpl(`${baseUrl}/v1/agents/${encodeURIComponent(agentId)}/repositories`, {
+      method: "POST",
+      headers: cloudHeaders2(this.cloudOptions),
+      body: JSON.stringify({ repository_id: repositoryId })
+    });
+    const body = await parseJsonResponse3(response);
+    assertOkResponse2(response, body, "Cloud attach agent repository");
+  }
+  async unlinkAgentRepository(agentId, repositoryId) {
+    const fetchImpl = getFetch3(this.cloudOptions.fetch);
+    const baseUrl = normalizeCloudApiBaseUrl2(this.cloudOptions.apiBaseUrl);
+    const response = await fetchImpl(`${baseUrl}/v1/agents/${encodeURIComponent(agentId)}/repositories/${encodeURIComponent(repositoryId)}`, { method: "DELETE", headers: cloudHeaders2(this.cloudOptions) });
+    const body = await parseJsonResponse3(response);
+    if (response.status === 404)
+      return;
+    assertOkResponse2(response, body, "Cloud detach agent repository");
+  }
   async createConversation(agentId) {
-    const fetchImpl = getFetch2(this.cloudOptions.fetch);
-    const baseUrl = normalizeCloudApiBaseUrl(this.cloudOptions.apiBaseUrl);
+    const fetchImpl = getFetch3(this.cloudOptions.fetch);
+    const baseUrl = normalizeCloudApiBaseUrl2(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),
+      headers: cloudHeaders2(this.cloudOptions),
       body: JSON.stringify({})
     });
-    const body = await parseJsonResponse2(response);
-    assertOkResponse(response, body, "Cloud createSession()");
+    const body = await parseJsonResponse3(response);
+    assertOkResponse2(response, body, "Cloud createSession()");
     if (!isCloudConversation(body)) {
       throw new Error("Cloud createSession() response did not include a conversation id.");
     }
     return { id: body.id, agent_id: body.agent_id };
   }
   async retrieveConversation(conversationId) {
-    const fetchImpl = getFetch2(this.cloudOptions.fetch);
-    const baseUrl = normalizeCloudApiBaseUrl(this.cloudOptions.apiBaseUrl);
-    const response = await fetchImpl(`${baseUrl}/v1/conversations/${encodeURIComponent(conversationId)}`, { headers: cloudHeaders(this.cloudOptions) });
-    const body = await parseJsonResponse2(response);
-    assertOkResponse(response, body, "Cloud resumeSession()");
+    const fetchImpl = getFetch3(this.cloudOptions.fetch);
+    const baseUrl = normalizeCloudApiBaseUrl2(this.cloudOptions.apiBaseUrl);
+    const response = await fetchImpl(`${baseUrl}/v1/conversations/${encodeURIComponent(conversationId)}`, { headers: cloudHeaders2(this.cloudOptions) });
+    const body = await parseJsonResponse3(response);
+    assertOkResponse2(response, body, "Cloud resumeSession()");
     if (!isCloudConversation(body)) {
       throw new Error(`Cloud resumeSession() could not retrieve conversation ${conversationId}.`);
     }
@@ -4203,15 +4546,15 @@ class CloudEnvironmentSession extends RemoteClientSessionCore {
     }
   }
   async createManagedSandbox(agentId) {
-    const fetchImpl = getFetch2(this.cloudOptions.fetch);
-    const baseUrl = normalizeCloudApiBaseUrl(this.cloudOptions.apiBaseUrl);
+    const fetchImpl = getFetch3(this.cloudOptions.fetch);
+    const baseUrl = normalizeCloudApiBaseUrl2(this.cloudOptions.apiBaseUrl);
     const response = await fetchImpl(`${baseUrl}/v1/agents/${encodeURIComponent(agentId)}/sandboxes`, {
       method: "POST",
-      headers: cloudHeaders(this.cloudOptions),
+      headers: cloudHeaders2(this.cloudOptions),
       body: JSON.stringify({})
     });
-    const body = await parseJsonResponse2(response);
-    assertOkResponse(response, body, "Cloud create managed sandbox");
+    const body = await parseJsonResponse3(response);
+    assertOkResponse2(response, body, "Cloud create managed sandbox");
     if (!isCloudAgentSandbox(body)) {
       throw new Error("Cloud create managed sandbox response did not include sandbox connection details.");
     }
@@ -4245,15 +4588,15 @@ class CloudEnvironmentSession extends RemoteClientSessionCore {
     }
   }
   async refreshManagedSandboxOnce(sandbox) {
-    const fetchImpl = getFetch2(this.cloudOptions.fetch);
-    const baseUrl = normalizeCloudApiBaseUrl(this.cloudOptions.apiBaseUrl);
+    const fetchImpl = getFetch3(this.cloudOptions.fetch);
+    const baseUrl = normalizeCloudApiBaseUrl2(this.cloudOptions.apiBaseUrl);
     const response = await fetchImpl(`${baseUrl}/v1/agents/${encodeURIComponent(sandbox.agentId)}/sandboxes/refresh`, {
       method: "POST",
-      headers: cloudHeaders(this.cloudOptions),
+      headers: cloudHeaders2(this.cloudOptions),
       body: JSON.stringify({ ttlMinutes: sandbox.ttlMinutes })
     });
-    const body = await parseJsonResponse2(response);
-    assertOkResponse(response, body, "Cloud refresh managed sandbox");
+    const body = await parseJsonResponse3(response);
+    assertOkResponse2(response, body, "Cloud refresh managed sandbox");
     if (!isCloudAgentSandboxRefresh(body) || !body.success) {
       throw new Error("Cloud refresh managed sandbox response did not confirm refresh.");
     }
@@ -4263,16 +4606,16 @@ class CloudEnvironmentSession extends RemoteClientSessionCore {
   }
   async terminateManagedSandbox(sandbox) {
     await this.refreshManagedSandbox(sandbox);
-    const fetchImpl = getFetch2(this.cloudOptions.fetch);
-    const baseUrl = normalizeCloudApiBaseUrl(this.cloudOptions.apiBaseUrl);
+    const fetchImpl = getFetch3(this.cloudOptions.fetch);
+    const baseUrl = normalizeCloudApiBaseUrl2(this.cloudOptions.apiBaseUrl);
     const response = await fetchImpl(`${baseUrl}/v1/agents/${encodeURIComponent(sandbox.agentId)}/sandboxes`, {
       method: "DELETE",
-      headers: cloudHeaders(this.cloudOptions)
+      headers: cloudHeaders2(this.cloudOptions)
     });
-    const body = await parseJsonResponse2(response);
+    const body = await parseJsonResponse3(response);
     if (response.status === 404)
       return;
-    assertOkResponse(response, body, "Cloud terminate managed sandbox");
+    assertOkResponse2(response, body, "Cloud terminate managed sandbox");
   }
   async waitForManagedSandboxConnection(sandbox) {
     const deadline = Date.now() + sandbox.readyTimeoutMs;
@@ -4325,7 +4668,7 @@ class CloudEnvironmentSession extends RemoteClientSessionCore {
   remoteEnvironmentClient() {
     return new RemoteEnvironmentClient({
       baseUrl: this.cloudOptions.apiBaseUrl,
-      apiKey: getCloudApiKey(this.cloudOptions),
+      apiKey: getCloudApiKey2(this.cloudOptions),
       headers: this.cloudOptions.headers,
       fetch: this.cloudOptions.fetch
     });
@@ -4486,17 +4829,24 @@ function stripCloudExecutionOptions(options) {
   delete sessionOptions.sandbox;
   return sessionOptions;
 }
+function hasRepositoryResources(options) {
+  return options.resources !== undefined && options.resources.length > 0;
+}
 function hasCreateAgentEnvironment(options) {
   return "environment" in options;
 }
+function hasExplicitCreateAgentModel(options) {
+  return typeof options.model === "string" && options.model.trim().length > 0;
+}
 function looksLikeConversationId(id) {
   return id.startsWith("conv-") || id.startsWith("local-conv-");
 }
 
-class LettaCodeClient {
+class LettaAgentClient {
   backend;
   environment;
   options;
+  repositoriesClient = null;
   constructor(options = {}) {
     const backend = options.backend ?? "local";
     if (!isLettaCodeBackend(backend)) {
@@ -4506,13 +4856,13 @@ class LettaCodeClient {
     this.environment = getOptionsEnvironment(options);
     this.options = options;
     if (this.backend === "local" && this.environment !== undefined) {
-      throw new Error('LettaCodeClient environment is only valid with backend: "cloud".');
+      throw new Error('LettaAgentClient environment is only valid with backend: "cloud".');
     }
     if (this.backend === "remote" && this.environment !== undefined) {
-      throw new Error('LettaCodeClient environment is only valid with backend: "cloud"; remote url selects the app-server runtime.');
+      throw new Error('LettaAgentClient environment is only valid with backend: "cloud"; remote url selects the app-server runtime.');
     }
     if (this.backend !== "cloud" && options.sandbox !== undefined) {
-      throw new Error('LettaCodeClient sandbox options are only valid with backend: "cloud".');
+      throw new Error('LettaAgentClient sandbox options are only valid with backend: "cloud".');
     }
     if (this.backend === "local") {
       const localOptions = options;
@@ -4530,7 +4880,7 @@ class LettaCodeClient {
     }
     if (this.backend === "remote") {
       if (!("url" in options) || typeof options.url !== "string" || options.url.length === 0) {
-        throw new Error("LettaCodeClient remote backend requires a non-empty url.");
+        throw new Error("LettaAgentClient remote backend requires a non-empty url.");
       }
       if (options.requestTimeoutMs !== undefined && (!Number.isInteger(options.requestTimeoutMs) || options.requestTimeoutMs <= 0)) {
         throw new Error("Invalid requestTimeoutMs. Expected a positive integer.");
@@ -4540,6 +4890,9 @@ class LettaCodeClient {
       validateCloudClientOptions(options);
     }
   }
+  get repositories() {
+    return this.getRepositoriesClient();
+  }
   async createAgent(options = {}) {
     if (hasCreateAgentEnvironment(options)) {
       throw new Error("createAgent() does not accept environment. Set a client default or pass environment to resumeSession()/createSession().");
@@ -4555,6 +4908,9 @@ class LettaCodeClient {
       return initMsg2.agentId;
     }
     if (this.backend === "cloud") {
+      if (!hasExplicitCreateAgentModel(options)) {
+        throw new Error('Constellation createAgent() requires an explicit model. Pass model in createAgent({ model: "provider/model" }).');
+      }
       return createCloudAgent(this.cloudOptions(), options);
     }
     this.assertLocalBackend("createAgent");
@@ -4683,7 +5039,7 @@ class LettaCodeClient {
     if (this.backend === "local") {
       return;
     }
-    throw new Error(`LettaCodeClient backend '${this.backend}' is not implemented yet. ${action} currently supports backend 'local' only.`);
+    throw new Error(`LettaAgentClient backend '${this.backend}' is not implemented yet. ${action} currently supports backend 'local' only.`);
   }
   assertSessionBackend(action, options) {
     const effectiveEnvironment = options.environment ?? this.environment;
@@ -4694,6 +5050,9 @@ class LettaCodeClient {
       if (options.sandbox !== undefined) {
         throw new Error(`${action}() sandbox options are only valid with backend: "cloud".`);
       }
+      if (hasRepositoryResources(options)) {
+        throw new Error(`${action}() repository resources are only valid with backend: "cloud".`);
+      }
       if (!this.useLegacyLocalStdio()) {
         assertRemoteSessionOptionsSupported(action, options);
       }
@@ -4706,6 +5065,9 @@ class LettaCodeClient {
       if (options.sandbox !== undefined) {
         throw new Error(`${action}() sandbox options are only valid with backend: "cloud"; remote url selects the app-server runtime.`);
       }
+      if (hasRepositoryResources(options)) {
+        throw new Error(`${action}() repository resources are only valid with backend: "cloud".`);
+      }
       assertRemoteSessionOptionsSupported(action, options);
       return;
     }
@@ -4720,7 +5082,7 @@ class LettaCodeClient {
       assertCloudSessionOptionsSupported(action, options);
       return;
     }
-    throw new Error(`LettaCodeClient backend '${this.backend}' is not implemented yet. ${action} currently supports backend 'local' only.`);
+    throw new Error(`LettaAgentClient backend '${this.backend}' is not implemented yet. ${action} currently supports backend 'local' only.`);
   }
   useLegacyLocalStdio() {
     return this.options.transport === "stdio";
@@ -4730,6 +5092,7 @@ class LettaCodeClient {
     const appServer = localOptions.appServer;
     return {
       local: appServer?.url === undefined,
+      localBackend: "local",
       ...appServer?.url !== undefined ? { url: appServer.url } : {},
       ...appServer?.WebSocket !== undefined ? { WebSocket: appServer.WebSocket } : {},
       ...appServer?.requestTimeoutMs !== undefined ? { requestTimeoutMs: appServer.requestTimeoutMs } : {},
@@ -4743,6 +5106,13 @@ class LettaCodeClient {
     }
     return this.options;
   }
+  getRepositoriesClient() {
+    if (this.backend !== "cloud") {
+      throw new Error('client.repositories is only available with backend: "cloud".');
+    }
+    this.repositoriesClient ??= new RepositoriesClient(this.cloudOptions());
+    return this.repositoriesClient;
+  }
   cloudOptions() {
     if (this.backend !== "cloud") {
       throw new Error('Constellation options requested for non-"cloud" backend.');
@@ -4907,18 +5277,18 @@ function readStringArrayParam(params, key, options = {}) {
 import { readFileSync } from "node:fs";
 async function createAgent(options = {}) {
   validateCreateAgentOptions(options);
-  return new LettaCodeClient().createAgent(options);
+  return new LettaAgentClient().createAgent(options);
 }
 function createSession(agentId, options = {}) {
   validateCreateSessionOptions(options);
   if (agentId) {
-    return new LettaCodeClient().createSession(agentId, options);
+    return new LettaAgentClient().createSession(agentId, options);
   }
-  return new LettaCodeClient({ backend: "local", transport: "stdio" }).createSession(options);
+  return new LettaAgentClient({ backend: "local", transport: "stdio" }).createSession(options);
 }
 function resumeSession(id, options = {}) {
   validateCreateSessionOptions(options);
-  return new LettaCodeClient().resumeSession(id, options);
+  return new LettaAgentClient().resumeSession(id, options);
 }
 async function prompt(message, agentId) {
   const session = agentId ? createSession(agentId) : createSession();
@@ -4929,7 +5299,7 @@ async function prompt(message, agentId) {
   }
 }
 async function listMessagesDirect(agentId, options = {}) {
-  const session = new LettaCodeClient().resumeSession(agentId, {
+  const session = new LettaAgentClient().resumeSession(agentId, {
     permissionMode: "bypassPermissions"
   });
   await session.initialize();
@@ -4988,7 +5358,8 @@ export {
   createSession,
   createAgent,
   Session,
-  LettaCodeClient
+  RepositoriesClient,
+  LettaAgentClient
 };
 
-//# debugId=386FEEB02928954D64756E2164756E21
+//# debugId=7B3400A69740F48F64756E2164756E21