@letta-ai/letta-agent-sdk 0.6.2 → 0.6.3

package/dist/index.js

@@ -9514,6 +9514,9 @@ class RemoteClientSessionCore {
   initializePromise = null;
   removeMessageHandler = null;
   detachTransportDisconnect = null;
+  idleTransportDisconnected = false;
+  transportRecoveryPromise = null;
+  transportDisconnectGeneration = 0;
   turns;
   toolNames;
   deviceStatusListeners = new Set;
@@ -9603,16 +9606,24 @@ class RemoteClientSessionCore {
     this.initialized = false;
   }
   async send(message) {
+    if (this.closed)
+      throw new Error("Session is closed");
     if (!this.initialized) {
       await this.initialize();
     }
+    await this.recoverIdleTransportIfNeeded();
     if (!this.controller || !this.runtime) {
       throw new Error("Session is not initialized");
     }
     await this.beforeTurn();
-    const turn = this.turns.trackSentTurn(this.runtime);
+    const controller = this.controller;
+    const runtime = this.runtime;
+    if (!controller || !runtime) {
+      throw new Error("Session transport disconnected before the turn was sent");
+    }
+    const turn = this.turns.trackSentTurn(runtime);
     try {
-      this.controller.sendTurnMessage(this.runtime, message, {
+      controller.sendTurnMessage(runtime, message, {
         clientMessageId: turn.clientMessageId
       });
     } catch (error) {
@@ -9887,6 +9898,7 @@ class RemoteClientSessionCore {
     this.deviceStatusListeners.clear();
     this.controller?.close();
     this.controller = null;
+    this.idleTransportDisconnected = false;
     this.onCoreClose();
   }
   get agentId() {
@@ -9939,15 +9951,78 @@ class RemoteClientSessionCore {
     }, { predicate: (message) => message.type === "update_toolset_response" });
     ensureSuccess(response, "Failed to update toolset");
   }
-  watchTransportDisconnect(client) {
+  watchTransportDisconnect(client, options = {}) {
     this.detachTransportDisconnect?.();
     this.detachTransportDisconnect = client.onDisconnect(() => {
       if (this.closed)
         return;
+      this.transportDisconnectGeneration += 1;
+      if (options.recoverWhenIdle && !this.turns.hasInFlightTurn()) {
+        this.detachTransportDisconnect?.();
+        this.detachTransportDisconnect = null;
+        this.removeMessageHandler?.();
+        this.removeMessageHandler = null;
+        this.controller?.close();
+        this.controller = null;
+        const error = new Error(`${this.label} connection closed before send`);
+        for (const cancel of [...this.deviceStatusRefreshCancels])
+          cancel(error);
+        this.deviceStatusRefreshCancels.clear();
+        this.onIdleTransportDisconnect();
+        this.idleTransportDisconnected = true;
+        return;
+      }
       this.turns.closeWithError(`The ${this.label} connection closed unexpectedly; resume the conversation to continue.`);
       this.close();
     });
   }
+  async recoverIdleTransportIfNeeded() {
+    if (!this.idleTransportDisconnected)
+      return;
+    if (this.transportRecoveryPromise) {
+      await this.transportRecoveryPromise;
+      return;
+    }
+    const runtime = this.runtime;
+    if (!runtime)
+      throw new Error("Session transport disconnected without a runtime");
+    const generation = this.transportDisconnectGeneration;
+    const recovery = this.recoverIdleTransport(runtime).then(async (init) => {
+      if (this.closed || generation !== this.transportDisconnectGeneration) {
+        init.controller.close();
+        this.onRecoveredTransportDiscarded();
+        throw new Error(`${this.label} connection closed during recovery`);
+      }
+      if (init.runtime.agent_id !== runtime.agent_id || init.runtime.conversation_id !== runtime.conversation_id) {
+        init.controller.close();
+        this.onRecoveredTransportDiscarded();
+        throw new Error(`${this.label} transport recovered a different runtime`);
+      }
+      this.controller = init.controller;
+      this.runtime = init.runtime;
+      this._modelSettings = init.modelSettings ?? this._modelSettings;
+      if (typeof init.model === "string" && init.model)
+        this._model = init.model;
+      if (init.tools !== undefined)
+        this.toolNames = init.tools;
+      this.removeMessageHandler = this.controller.onMessage((message) => {
+        if (this.runtime)
+          this.turns.handleProtocolMessage(message, this.runtime);
+      });
+      this.idleTransportDisconnected = false;
+      await this.afterRuntimeInitialized();
+    }).finally(() => {
+      if (this.transportRecoveryPromise === recovery)
+        this.transportRecoveryPromise = null;
+    });
+    this.transportRecoveryPromise = recovery;
+    await recovery;
+  }
+  async recoverIdleTransport(_runtime) {
+    throw new Error(`${this.label} sessions do not support idle transport recovery`);
+  }
+  onIdleTransportDisconnect() {}
+  onRecoveredTransportDiscarded() {}
   async afterRuntimeInitialized() {}
   async beforeTurn() {}
   onCoreClose() {}
@@ -10691,6 +10766,132 @@ class CloudManagementTransport {
   }
 }
 
+// src/remote.ts
+function ensureOnline(environment, target) {
+  if (!environment.connectionId) {
+    const label = "deviceId" in target ? target.deviceId : ("environmentId" in target) ? target.environmentId : ("connectionName" in target) ? target.connectionName : environment.deviceId;
+    throw new Error(`Computer is offline: ${label}`);
+  }
+  return {
+    connectionId: environment.connectionId,
+    environment,
+    target
+  };
+}
+
+class RemoteEnvironmentClient {
+  client;
+  constructor(options = {}, client = createCloudClient({
+    backend: "cloud",
+    apiBaseUrl: options.baseUrl,
+    apiKey: options.apiKey,
+    headers: options.headers,
+    fetch: options.fetch
+  })) {
+    this.client = client;
+  }
+  async listEnvironments(options = {}) {
+    return await this.client.environments.list({
+      after: options.after,
+      limit: options.limit === undefined ? undefined : String(options.limit),
+      onlineOnly: options.onlineOnly === undefined ? undefined : String(options.onlineOnly)
+    });
+  }
+  async getEnvironmentByDeviceId(deviceId) {
+    return await this.client.environments.retrieve(deviceId);
+  }
+  async resolveEnvironment(target) {
+    if ("connectionId" in target) {
+      return { connectionId: target.connectionId, target };
+    }
+    if ("deviceId" in target) {
+      return ensureOnline(await this.getEnvironmentByDeviceId(target.deviceId), target);
+    }
+    const connections = [];
+    let after;
+    do {
+      const page = await this.listEnvironments({ limit: 100, after });
+      connections.push(...page.connections);
+      if (!page.hasNextPage || page.connections.length === 0)
+        break;
+      after = page.connections.at(-1)?.id;
+    } while (after !== undefined);
+    if ("environmentId" in target) {
+      const match = connections.find((env) => env.id === target.environmentId);
+      if (!match) {
+        throw new Error(`Remote environment not found: ${target.environmentId}`);
+      }
+      return ensureOnline(match, target);
+    }
+    const matches = connections.filter((env) => env.connectionName === target.connectionName);
+    if (matches.length === 0) {
+      throw new Error(`Computer not found: ${target.connectionName}`);
+    }
+    const onlineMatches = matches.filter((environment) => environment.connectionId !== null);
+    if (onlineMatches.length === 0) {
+      throw new Error(`Computer is offline: ${target.connectionName}`);
+    }
+    if (onlineMatches.length > 1) {
+      const candidates = onlineMatches.map((environment) => `${environment.connectionName} (${environment.deviceId}, online)`).join(", ");
+      throw new Error(`Computer name is ambiguous: ${target.connectionName}. Matches: ${candidates}. Select one by deviceId.`);
+    }
+    return ensureOnline(onlineMatches[0], target);
+  }
+}
+
+// src/computers.ts
+function selectorToRemoteTarget(selector) {
+  if (typeof selector === "string")
+    return { connectionName: selector };
+  if ("name" in selector)
+    return { connectionName: selector.name };
+  if ("id" in selector)
+    return { environmentId: selector.id };
+  if ("connectionId" in selector) {
+    return { connectionId: selector.connectionId };
+  }
+  return { deviceId: selector.deviceId };
+}
+function toComputer(environment) {
+  return {
+    id: environment.id,
+    deviceId: environment.deviceId,
+    connectionId: environment.connectionId,
+    name: environment.connectionName,
+    status: environment.connectionId ? "online" : "offline",
+    connectedAt: environment.connectedAt,
+    lastSeenAt: environment.lastSeenAt,
+    metadata: environment.metadata
+  };
+}
+
+class ComputersClientImpl {
+  environments;
+  constructor(client) {
+    this.environments = new RemoteEnvironmentClient({}, client);
+  }
+  async list(options = {}) {
+    const result = await this.environments.listEnvironments(options);
+    return {
+      computers: result.connections.map(toComputer),
+      hasNextPage: result.hasNextPage
+    };
+  }
+  async get(deviceId) {
+    if (typeof deviceId !== "string" || deviceId.trim().length === 0) {
+      throw new Error("Invalid deviceId. Expected a non-empty string.");
+    }
+    return toComputer(await this.environments.getEnvironmentByDeviceId(deviceId));
+  }
+  async resolve(selector) {
+    const result = await this.environments.resolveEnvironment(selectorToRemoteTarget(selector));
+    return {
+      connectionId: result.connectionId,
+      computer: result.environment ? toComputer(result.environment) : undefined
+    };
+  }
+}
+
 // src/cloud-status-transport.ts
 var CONNECTING = 0;
 var OPEN = 1;
@@ -10907,66 +11108,6 @@ function createCloudStatusTransportConstructor(options) {
   };
 }
 
-// src/remote.ts
-function ensureOnline(environment, target) {
-  if (!environment.connectionId) {
-    const label = "deviceId" in target ? target.deviceId : ("environmentId" in target) ? target.environmentId : ("connectionName" in target) ? target.connectionName : environment.deviceId;
-    throw new Error(`Remote environment is offline: ${label}`);
-  }
-  return {
-    connectionId: environment.connectionId,
-    environment,
-    target
-  };
-}
-
-class RemoteEnvironmentClient {
-  client;
-  constructor(options = {}, client = createCloudClient({
-    backend: "cloud",
-    apiBaseUrl: options.baseUrl,
-    apiKey: options.apiKey,
-    headers: options.headers,
-    fetch: options.fetch
-  })) {
-    this.client = client;
-  }
-  async listEnvironments() {
-    return await this.client.environments.list();
-  }
-  async getEnvironmentByDeviceId(deviceId) {
-    return await this.client.environments.retrieve(deviceId);
-  }
-  async resolveEnvironment(target) {
-    if ("connectionId" in target) {
-      return { connectionId: target.connectionId, target };
-    }
-    if ("deviceId" in target) {
-      return ensureOnline(await this.getEnvironmentByDeviceId(target.deviceId), target);
-    }
-    const { connections } = await this.listEnvironments();
-    if ("environmentId" in target) {
-      const match2 = connections.find((env) => env.id === target.environmentId);
-      if (!match2) {
-        throw new Error(`Remote environment not found: ${target.environmentId}`);
-      }
-      return ensureOnline(match2, target);
-    }
-    const matches = connections.filter((env) => env.connectionName === target.connectionName);
-    if (matches.length === 0) {
-      throw new Error(`Remote environment not found: ${target.connectionName}`);
-    }
-    if (matches.length > 1) {
-      throw new Error(`Remote environment name is ambiguous: ${target.connectionName}`);
-    }
-    const match = matches[0];
-    if (!match) {
-      throw new Error(`Remote environment not found: ${target.connectionName}`);
-    }
-    return ensureOnline(match, target);
-  }
-}
-
 // src/cloud-sandbox.ts
 var MIN_TTL_MINUTES = 1;
 var MAX_TTL_MINUTES = 60;
@@ -11065,8 +11206,12 @@ function validatePositiveInteger3(value, name) {
 function validateCloudClientOptions(options) {
   validatePositiveInteger3(options.requestTimeoutMs, "requestTimeoutMs");
   validateCloudSandboxOptions(options.sandbox, "sandbox");
-  if (options.environment !== undefined && options.sandbox !== undefined) {
-    throw new Error("Letta Cloud sessions cannot specify both environment and sandbox options.");
+  if (options.computer !== undefined && options.environment !== undefined) {
+    throw new Error("Letta Cloud clients cannot specify both computer and deprecated environment.");
+  }
+  if ((options.computer !== undefined || options.environment !== undefined) && options.sandbox !== undefined) {
+    const field = options.computer !== undefined ? "computer" : "environment";
+    throw new Error(`Letta Cloud sessions cannot specify both ${field} and sandbox options.`);
   }
   if (options.webSocketAuth !== undefined && options.webSocketAuth !== "header" && options.webSocketAuth !== "query") {
     throw new Error("Invalid webSocketAuth. Valid values: header, query.");
@@ -11183,12 +11328,30 @@ class CloudEnvironmentSession extends RemoteClientSessionCore {
       throw error;
     });
     this.connectionId = connection.connectionId;
+    const options = this.currentOptions();
+    this.mcpBridge = await connectMcpServers("mcpServers" in options ? options.mcpServers : undefined, {
+      cwd: options.cwd,
+      reservedToolNames: this.externalTools.keys()
+    });
+    for (const tool of this.mcpBridge.tools) {
+      this.externalTools.set(tool.name, tool);
+    }
+    try {
+      return await this.openCloudTransport(resolved.runtime, connection.connectionId);
+    } catch (error) {
+      await this.closeMcpBridge();
+      await this.cleanupManagedSandbox();
+      await this.cleanupSessionRepositories(resolved.runtime.agent_id, resolved.runtime.conversation_id);
+      throw error;
+    }
+  }
+  async openCloudTransport(runtime, connectionId) {
     const apiKey = getCloudApiKey(this.cloudOptions);
     const url = buildCloudStatusWebSocketUrl({
       apiBaseUrl: this.cloudOptions.apiBaseUrl,
-      connectionId: connection.connectionId,
-      agentId: resolved.runtime.agent_id,
-      conversationId: resolved.runtime.conversation_id,
+      connectionId,
+      agentId: runtime.agent_id,
+      conversationId: runtime.conversation_id,
       apiKey,
       authMode: this.cloudOptions.webSocketAuth ?? "header"
     });
@@ -11199,33 +11362,19 @@ class CloudEnvironmentSession extends RemoteClientSessionCore {
         WebSocket: getWebSocketConstructor(this.cloudOptions.WebSocket),
         ...(this.cloudOptions.webSocketAuth ?? "header") === "header" ? { headers: cloudWebSocketHeaders(this.cloudOptions) } : {},
         pingIntervalMs: this.cloudOptions.pingIntervalMs ?? DEFAULT_PING_INTERVAL_MS,
-        runtime: resolved.runtime
+        runtime
       }),
       requestTimeoutMs: this.cloudOptions.requestTimeoutMs ?? DEFAULT_TURN_TIMEOUT_MS
     }));
     const options = this.currentOptions();
-    this.mcpBridge = await connectMcpServers("mcpServers" in options ? options.mcpServers : undefined, {
-      cwd: options.cwd,
-      reservedToolNames: this.externalTools.keys()
-    });
-    for (const tool of this.mcpBridge.tools) {
-      this.externalTools.set(tool.name, tool);
-    }
-    this.removeControlRequestHandler = registerAppServerControlRequestHandler({
-      client,
-      getRuntime: () => this.runtime,
-      getOptions: () => this.currentOptions()
-    });
-    if (this.externalTools.size > 0) {
-      this.removeExternalToolHandler = client.onExternalToolCall(createExternalToolCallHandler(this.externalTools));
-    }
+    this.installTransportHandlers(client);
     try {
       await client.connect();
-      const response = await this.startCloudRuntime(client, resolved.runtime);
+      const response = await this.startCloudRuntime(client, runtime);
       if (!response.success || !response.runtime) {
         throw new Error(response.error ?? "Failed to start Cloud status runtime");
       }
-      this.watchTransportDisconnect(client);
+      this.watchTransportDisconnect(client, { recoverWhenIdle: true });
       const tools = agentToolNames(response.agent);
       const skillSources = options.skillSources;
       const clientToolset = "toolset" in options ? options.toolset : undefined;
@@ -11243,17 +11392,51 @@ class CloudEnvironmentSession extends RemoteClientSessionCore {
         ...skillSources !== undefined ? { skillSources: [...skillSources] } : {}
       };
     } catch (error) {
-      this.removeExternalToolHandler?.();
-      this.removeExternalToolHandler = null;
-      this.removeControlRequestHandler?.();
-      this.removeControlRequestHandler = null;
-      await this.closeMcpBridge();
+      this.cleanupTransportHandlers();
       client.close();
-      await this.cleanupManagedSandbox();
-      await this.cleanupSessionRepositories(resolved.runtime.agent_id, resolved.runtime.conversation_id);
       throw error;
     }
   }
+  installTransportHandlers(client) {
+    this.cleanupTransportHandlers();
+    this.removeControlRequestHandler = registerAppServerControlRequestHandler({
+      client,
+      getRuntime: () => this.runtime,
+      getOptions: () => this.currentOptions()
+    });
+    if (this.externalTools.size > 0) {
+      this.removeExternalToolHandler = client.onExternalToolCall(createExternalToolCallHandler(this.externalTools));
+    }
+  }
+  cleanupTransportHandlers() {
+    this.removeExternalToolHandler?.();
+    this.removeExternalToolHandler = null;
+    this.removeControlRequestHandler?.();
+    this.removeControlRequestHandler = null;
+  }
+  async recoverIdleTransport(runtime) {
+    const connection = await this.resolveRecoveryConnection(runtime);
+    this.connectionId = connection.connectionId;
+    return this.openCloudTransport(runtime, connection.connectionId);
+  }
+  async resolveRecoveryConnection(runtime) {
+    const sandbox = this.managedSandbox;
+    if (sandbox) {
+      await this.refreshManagedSandbox(sandbox);
+      return this.waitForManagedSandboxConnection(sandbox);
+    }
+    const environment = this.effectiveEnvironment();
+    if (!environment) {
+      throw new Error("Cloud idle transport recovery lost its execution target");
+    }
+    return this.resolveExplicitConnection(environment);
+  }
+  onIdleTransportDisconnect() {
+    this.cleanupTransportHandlers();
+  }
+  onRecoveredTransportDiscarded() {
+    this.cleanupTransportHandlers();
+  }
   async startCloudRuntime(client, runtime) {
     const options = this.currentOptions();
     const command = {
@@ -11296,10 +11479,7 @@ class CloudEnvironmentSession extends RemoteClientSessionCore {
     await this.refreshManagedSandbox(sandbox);
   }
   onCoreClose() {
-    this.removeExternalToolHandler?.();
-    this.removeExternalToolHandler = null;
-    this.removeControlRequestHandler?.();
-    this.removeControlRequestHandler = null;
+    this.cleanupTransportHandlers();
     this.mcpCleanup = this.closeMcpBridge();
     this.cleanupManagedSandbox();
     if (this.runtime?.agent_id) {
@@ -11623,8 +11803,8 @@ class CloudEnvironmentSession extends RemoteClientSessionCore {
     return new RemoteEnvironmentClient({}, this.apiClient);
   }
   effectiveEnvironment() {
-    const modeEnvironment = this.mode.kind === "session" ? this.mode.options.environment : undefined;
-    return modeEnvironment ?? this.cloudOptions.environment;
+    const modeComputer = this.mode.kind === "session" ? this.mode.options.computer ?? this.mode.options.environment : undefined;
+    return modeComputer ?? this.cloudOptions.computer ?? this.cloudOptions.environment;
   }
   effectiveSandboxOptions() {
     const modeSandbox = this.mode.kind === "session" ? this.mode.options.sandbox : undefined;
@@ -11924,14 +12104,17 @@ var VALID_BACKENDS = new Set([
 function isLettaCodeBackend(value) {
   return VALID_BACKENDS.has(value);
 }
-function getOptionsEnvironment(options) {
-  if ("environment" in options) {
-    return options.environment;
+function getOptionsComputer(options) {
+  if (!("computer" in options) && !("environment" in options))
+    return;
+  if (options.computer !== undefined && options.environment !== undefined) {
+    throw new Error('Specify either "computer" or deprecated "environment", not both.');
   }
-  return;
+  return options.computer ?? options.environment;
 }
 function stripCloudExecutionOptions(options) {
   const sessionOptions = { ...options };
+  delete sessionOptions.computer;
   delete sessionOptions.environment;
   delete sessionOptions.sandbox;
   delete sessionOptions.filesystemConfinement;
@@ -11949,12 +12132,14 @@ function looksLikeConversationId(id) {
 
 class LettaAgentClientBase {
   backend;
+  computer;
   environment;
   agents;
   conversations;
   models;
   options;
   repositoriesClient = null;
+  computersClient = null;
   agentRepositoriesClient = null;
   cloudClient = null;
   managementTransport = null;
@@ -11964,16 +12149,19 @@ class LettaAgentClientBase {
       throw new Error(`Invalid Letta Code backend '${String(backend)}'. Valid values: local, remote, cloud.`);
     }
     this.backend = backend;
-    this.environment = getOptionsEnvironment(options);
+    this.computer = getOptionsComputer(options);
+    this.environment = this.computer;
     this.options = options;
     this.agents = createAgentsClient(() => this.getManagementTransport(), () => this.getAgentRepositoriesClient());
     this.conversations = createConversationsClient(() => this.getManagementTransport());
     this.models = createModelsClient(() => this.getManagementTransport());
-    if (this.backend === "local" && this.environment !== undefined) {
-      throw new Error('LettaAgentClient environment is only valid with backend: "cloud".');
+    if (this.backend === "local" && this.computer !== undefined) {
+      const field = "computer" in options && options.computer !== undefined ? "computer" : "environment";
+      throw new Error(`LettaAgentClient ${field} is only valid with backend: "cloud".`);
     }
-    if (this.backend === "remote" && this.environment !== undefined) {
-      throw new Error('LettaAgentClient environment is only valid with backend: "cloud"; remote url selects the app-server runtime.');
+    if (this.backend === "remote" && this.computer !== undefined) {
+      const field = "computer" in options && options.computer !== undefined ? "computer" : "environment";
+      throw new Error(`LettaAgentClient ${field} is only valid with backend: "cloud"; remote url selects the app-server runtime.`);
     }
     if (this.backend !== "cloud" && options.sandbox !== undefined) {
       throw new Error('LettaAgentClient sandbox options are only valid with backend: "cloud".');
@@ -12007,6 +12195,9 @@ class LettaAgentClientBase {
   get repositories() {
     return this.getRepositoriesClient();
   }
+  get computers() {
+    return this.getComputersClient();
+  }
   async createAgent(options = {}) {
     if (hasCreateAgentEnvironment(options)) {
       throw new Error("createAgent() does not accept environment. Set a client default or pass environment to resumeSession()/createSession().");
@@ -12096,13 +12287,17 @@ class LettaAgentClientBase {
     }
   }
   assertSessionBackend(action, options) {
+    if (options.computer !== undefined && options.environment !== undefined) {
+      throw new Error(`${action}() cannot specify both computer and deprecated environment.`);
+    }
     if (options.filesystemConfinement !== undefined && options.filesystemConfinement !== "memory") {
       throw new Error(`Invalid filesystemConfinement '${String(options.filesystemConfinement)}'. Valid value: memory.`);
     }
-    const effectiveEnvironment = options.environment ?? this.environment;
+    const effectiveComputer = options.computer ?? options.environment ?? this.computer;
     if (this.backend === "local") {
-      if (effectiveEnvironment !== undefined) {
-        throw new Error(`${action}() environment overrides are only valid with backend: "cloud".`);
+      if (effectiveComputer !== undefined) {
+        const field = options.computer !== undefined ? "computer" : "environment";
+        throw new Error(`${action}() ${field} overrides are only valid with backend: "cloud".`);
       }
       if (options.sandbox !== undefined) {
         throw new Error(`${action}() sandbox options are only valid with backend: "cloud".`);
@@ -12122,8 +12317,9 @@ class LettaAgentClientBase {
       if (options.filesystemConfinement !== undefined) {
         throw new Error(`${action}() filesystemConfinement requires an SDK-owned local app-server process.`);
       }
-      if (options.environment !== undefined) {
-        throw new Error(`${action}() environment overrides are only valid with backend: "cloud"; remote url selects the app-server runtime.`);
+      if (options.computer !== undefined || options.environment !== undefined) {
+        const field = options.computer !== undefined ? "computer" : "environment";
+        throw new Error(`${action}() ${field} overrides are only valid with backend: "cloud"; remote url selects the app-server runtime.`);
       }
       if (options.sandbox !== undefined) {
         throw new Error(`${action}() sandbox options are only valid with backend: "cloud"; remote url selects the app-server runtime.`);
@@ -12138,11 +12334,13 @@ class LettaAgentClientBase {
         throw new Error(`${action}() filesystemConfinement is only supported with backend: "local".`);
       }
       const cloudOptions = this.cloudOptions();
-      if (cloudOptions.environment !== undefined && options.sandbox !== undefined) {
-        throw new Error(`Letta Cloud ${action}() cannot specify sandbox options when the client has a default environment.`);
+      if (this.computer !== undefined && options.sandbox !== undefined) {
+        const field = cloudOptions.computer !== undefined ? "computer" : "environment";
+        throw new Error(`Letta Cloud ${action}() cannot specify sandbox options when the client has a default ${field}.`);
       }
-      if (cloudOptions.sandbox !== undefined && options.environment !== undefined) {
-        throw new Error(`Letta Cloud ${action}() cannot specify an environment when the client has default sandbox options.`);
+      if (cloudOptions.sandbox !== undefined && (options.computer !== undefined || options.environment !== undefined)) {
+        const field = options.computer !== undefined ? "a computer" : "an environment";
+        throw new Error(`Letta Cloud ${action}() cannot specify ${field} when the client has default sandbox options.`);
       }
       assertCloudSessionOptionsSupported(action, options);
       return;
@@ -12173,6 +12371,13 @@ class LettaAgentClientBase {
   appServerSessionOptions() {
     return this.remoteOptions();
   }
+  getComputersClient() {
+    if (this.backend !== "cloud") {
+      throw new Error('client.computers is only available with backend: "cloud".');
+    }
+    this.computersClient ??= new ComputersClientImpl(this.getCloudClient());
+    return this.computersClient;
+  }
   getRepositoriesClient() {
     if (this.backend !== "cloud") {
       throw new Error('client.repositories is only available with backend: "cloud".');
@@ -29929,4 +30134,4 @@ export {
   CloudManagedSandboxExpiredError
 };
 
-//# debugId=9E741E442389C4A864756E2164756E21
+//# debugId=C079C2D0B42E0C4F64756E2164756E21