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

package/src/client-base.ts

@@ -8,6 +8,11 @@ import {
 } from "./app-server-session.js";
 import { CloudManagementTransport } from "./cloud-management.js";
 import { createCloudClient } from "./cloud-client.js";
+import {
+  ComputersClientImpl,
+  type ComputerSelector,
+  type ComputersClient,
+} from "./computers.js";
 import {
   CloudEnvironmentSession,
   assertCloudSessionOptionsSupported,
@@ -55,19 +60,21 @@ function isLettaCodeBackend(value: string): value is LettaCodeBackend {
   return VALID_BACKENDS.has(value as LettaCodeBackend);
 }
 
-function getOptionsEnvironment(
+function getOptionsComputer(
   options: LettaCodeClientOptions,
-): LettaCodeEnvironment | undefined {
-  if ("environment" in options) {
-    return options.environment;
+): ComputerSelector | undefined {
+  if (!("computer" in options) && !("environment" in options)) return undefined;
+  if (options.computer !== undefined && options.environment !== undefined) {
+    throw new Error('Specify either "computer" or deprecated "environment", not both.');
   }
-  return undefined;
+  return options.computer ?? options.environment;
 }
 
 function stripCloudExecutionOptions(
   options: LettaCodeClientSessionOptions,
 ): CreateSessionOptions {
   const sessionOptions = { ...options };
+  delete sessionOptions.computer;
   delete sessionOptions.environment;
   delete sessionOptions.sandbox;
   delete sessionOptions.filesystemConfinement;
@@ -102,12 +109,15 @@ type OneShotSession = LettaCodeSession & {
  */
 export class LettaAgentClientBase {
   readonly backend: LettaCodeBackend;
+  readonly computer: ComputerSelector | undefined;
+  /** @deprecated Use `computer`. */
   readonly environment: LettaCodeEnvironment | undefined;
   readonly agents: AgentsClient;
   readonly conversations: ConversationsClient;
   readonly models: ModelsClient;
   protected readonly options: LettaCodeClientOptions;
   private repositoriesClient: RepositoriesClient | null = null;
+  private computersClient: ComputersClientImpl | null = null;
   private agentRepositoriesClient: AgentRepositoriesClient | null = null;
   private cloudClient: Letta | null = null;
   private managementTransport: ManagementTransport | null = null;
@@ -121,7 +131,8 @@ export class LettaAgentClientBase {
     }
 
     this.backend = backend;
-    this.environment = getOptionsEnvironment(options);
+    this.computer = getOptionsComputer(options);
+    this.environment = this.computer;
     this.options = options;
     this.agents = createAgentsClient(
       () => this.getManagementTransport(),
@@ -132,14 +143,20 @@ export class LettaAgentClientBase {
     );
     this.models = createModelsClient(() => this.getManagementTransport());
 
-    if (this.backend === "local" && this.environment !== undefined) {
+    if (this.backend === "local" && this.computer !== undefined) {
+      const field = "computer" in options && options.computer !== undefined
+        ? "computer"
+        : "environment";
       throw new Error(
-        'LettaAgentClient environment is only valid with backend: "cloud".',
+        `LettaAgentClient ${field} is only valid with backend: "cloud".`,
       );
     }
-    if (this.backend === "remote" && this.environment !== undefined) {
+    if (this.backend === "remote" && this.computer !== undefined) {
+      const field = "computer" in options && options.computer !== undefined
+        ? "computer"
+        : "environment";
       throw new Error(
-        'LettaAgentClient environment is only valid with backend: "cloud"; remote url selects the app-server runtime.',
+        `LettaAgentClient ${field} is only valid with backend: "cloud"; remote url selects the app-server runtime.`,
       );
     }
     if (this.backend !== "cloud" && (options as { sandbox?: unknown }).sandbox !== undefined) {
@@ -196,6 +213,11 @@ export class LettaAgentClientBase {
     return this.getRepositoriesClient();
   }
 
+  /** Discover and resolve computers registered with this Letta Cloud account. */
+  get computers(): ComputersClient {
+    return this.getComputersClient();
+  }
+
   async createAgent(options: CreateAgentOptions = {}): Promise<string> {
     if (hasCreateAgentEnvironment(options)) {
       throw new Error(
@@ -336,6 +358,11 @@ export class LettaAgentClientBase {
     action: string,
     options: LettaCodeClientSessionOptions,
   ): void {
+    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"
@@ -344,11 +371,13 @@ export class LettaAgentClientBase {
         `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) {
+      if (effectiveComputer !== undefined) {
+        const field = options.computer !== undefined ? "computer" : "environment";
         throw new Error(
-          `${action}() environment overrides are only valid with backend: "cloud".`,
+          `${action}() ${field} overrides are only valid with backend: "cloud".`,
         );
       }
       if (options.sandbox !== undefined) {
@@ -374,9 +403,10 @@ export class LettaAgentClientBase {
           `${action}() filesystemConfinement requires an SDK-owned local app-server process.`,
         );
       }
-      if (options.environment !== undefined) {
+      if (options.computer !== undefined || options.environment !== undefined) {
+        const field = options.computer !== undefined ? "computer" : "environment";
         throw new Error(
-          `${action}() environment overrides are only valid with backend: "cloud"; remote url selects the app-server runtime.`,
+          `${action}() ${field} overrides are only valid with backend: "cloud"; remote url selects the app-server runtime.`,
         );
       }
       if (options.sandbox !== undefined) {
@@ -394,11 +424,20 @@ export class LettaAgentClientBase {
         );
       }
       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;
@@ -447,6 +486,14 @@ export class LettaAgentClientBase {
     return this.remoteOptions();
   }
 
+  private getComputersClient(): ComputersClientImpl {
+    if (this.backend !== "cloud") {
+      throw new Error('client.computers is only available with backend: "cloud".');
+    }
+    this.computersClient ??= new ComputersClientImpl(this.getCloudClient());
+    return this.computersClient;
+  }
+
   private getRepositoriesClient(): RepositoriesClient {
     if (this.backend !== "cloud") {
       throw new Error('client.repositories is only available with backend: "cloud".');

package/src/client-entry.ts

@@ -25,6 +25,15 @@ export class LettaAgentClient extends LettaAgentClientBase {
 
 export { CloudManagedSandboxExpiredError } from "./cloud-session.js";
 export { RepositoriesClient } from "./repositories.js";
+export type {
+  Computer,
+  ComputerMetadata,
+  ComputerSelector,
+  ComputersClient,
+  ListComputersOptions,
+  ListComputersResult,
+  ResolvedComputer,
+} from "./computers.js";
 export type * from "./management-types.js";
 export { extractStreamTextDelta } from "./stream-events.js";
 export { createReactNativeWebSocketConstructor } from "./websocket.js";

package/src/cloud-session.ts

@@ -5,10 +5,10 @@ import {
   createAppServerClient,
   type AppServerClient,
 } from "@letta-ai/letta-code/app-server-client";
+import { createAgentBody } from "./agent-creation.js";
 import {
   AppServerRuntimeController,
   agentToolNames,
-  createAgentBody,
   createExternalToolCallHandler,
   externalToolGroups,
   registerAppServerControlRequestHandler,
@@ -171,8 +171,19 @@ function validatePositiveInteger(value: number | undefined, name: string): void
 export function validateCloudClientOptions(options: LettaCodeCloudClientOptions): void {
   validatePositiveInteger(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 &&
@@ -346,12 +357,44 @@ export class CloudEnvironmentSession extends RemoteClientSessionCore {
     );
     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;
+    }
+  }
+
+  private async openCloudTransport(
+    runtime: RuntimeScope,
+    connectionId: string,
+  ): Promise<RuntimeSessionInit> {
     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",
     });
@@ -365,39 +408,22 @@ export class CloudEnvironmentSession extends RemoteClientSessionCore {
           : {}),
         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, { recoverWhenIdle: true });
+
       const tools = agentToolNames(response.agent);
       const skillSources = options.skillSources;
       const clientToolset = "toolset" in options ? options.toolset : undefined;
@@ -426,21 +452,64 @@ export 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;
     }
   }
 
+  private installTransportHandlers(client: AppServerClient): void {
+    this.cleanupTransportHandlers();
+    this.removeControlRequestHandler = registerAppServerControlRequestHandler({
+      client,
+      getRuntime: () => this.runtime,
+      getOptions: () => this.currentOptions(),
+    });
+    if (this.externalTools.size > 0) {
+      this.removeExternalToolHandler = client.onExternalToolCall(
+        createExternalToolCallHandler(this.externalTools),
+      );
+    }
+  }
+
+  private cleanupTransportHandlers(): void {
+    this.removeExternalToolHandler?.();
+    this.removeExternalToolHandler = null;
+    this.removeControlRequestHandler?.();
+    this.removeControlRequestHandler = null;
+  }
+
+  protected override async recoverIdleTransport(
+    runtime: RuntimeScope,
+  ): Promise<RuntimeSessionInit> {
+    const connection = await this.resolveRecoveryConnection(runtime);
+    this.connectionId = connection.connectionId;
+    return this.openCloudTransport(runtime, connection.connectionId);
+  }
+
+  private async resolveRecoveryConnection(
+    runtime: RuntimeScope,
+  ): Promise<ResolvedCloudConnection> {
+    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);
+  }
+
+  protected override onIdleTransportDisconnect(): void {
+    this.cleanupTransportHandlers();
+  }
+
+  protected override onRecoveredTransportDiscarded(): void {
+    this.cleanupTransportHandlers();
+  }
+
   private async startCloudRuntime(
     client: AppServerClient,
     runtime: RuntimeScope,
@@ -488,10 +557,7 @@ export class CloudEnvironmentSession extends RemoteClientSessionCore {
   }
 
   protected override onCoreClose(): void {
-    this.removeExternalToolHandler?.();
-    this.removeExternalToolHandler = null;
-    this.removeControlRequestHandler?.();
-    this.removeControlRequestHandler = null;
+    this.cleanupTransportHandlers();
     this.mcpCleanup = this.closeMcpBridge();
     void this.cleanupManagedSandbox();
     if (this.runtime?.agent_id) {
@@ -980,10 +1046,12 @@ export class CloudEnvironmentSession extends RemoteClientSessionCore {
   }
 
   private effectiveEnvironment(): LettaCodeEnvironment | undefined {
-    const modeEnvironment = this.mode.kind === "session"
-      ? this.mode.options.environment
+    const modeComputer = this.mode.kind === "session"
+      ? this.mode.options.computer ?? this.mode.options.environment
       : undefined;
-    return modeEnvironment ?? this.cloudOptions.environment;
+    return modeComputer ??
+      this.cloudOptions.computer ??
+      this.cloudOptions.environment;
   }
 
   private effectiveSandboxOptions(): LettaCodeCloudSandboxOptions | undefined {

package/src/computers.ts

@@ -0,0 +1,132 @@
+import type { Letta } from "@letta-ai/letta-client";
+import {
+  RemoteEnvironmentClient,
+  type RemoteEnvironmentConnection,
+  type RemoteEnvironmentTarget,
+} from "./remote.js";
+
+/**
+ * Selects the computer where a Cloud session runs tools and accesses files.
+ *
+ * Strings are treated as human-readable computer names. Prefer `deviceId` when
+ * persisting a selection because connection IDs can rotate after reconnects.
+ */
+export type ComputerSelector =
+  | string
+  | { name: string }
+  | { id: string }
+  | { connectionId: string }
+  | { deviceId: string };
+
+export interface ComputerMetadata {
+  os?: string;
+  lettaCodeVersion?: string;
+  nodeVersion?: string;
+  workingDirectory?: string;
+  gitBranch?: string;
+  [key: string]: unknown;
+}
+
+/** A registered computer that can host Letta agent tool execution. */
+export interface Computer {
+  /** Environment record ID. */
+  id: string;
+  /** Stable identifier for the physical device across reconnects. */
+  deviceId: string;
+  /** Current online connection lease. This may rotate after reconnects. */
+  connectionId: string | null;
+  /** Human-readable computer name. */
+  name: string;
+  status: "online" | "offline";
+  connectedAt: number | null;
+  lastSeenAt: number;
+  metadata?: ComputerMetadata;
+}
+
+export interface ListComputersOptions {
+  limit?: number;
+  after?: string;
+  onlineOnly?: boolean;
+}
+
+export interface ListComputersResult {
+  computers: Computer[];
+  hasNextPage: boolean;
+}
+
+export interface ResolvedComputer {
+  connectionId: string;
+  /** Omitted when resolving an explicit connection ID. */
+  computer?: Computer;
+}
+
+export interface ComputersClient {
+  list(options?: ListComputersOptions): Promise<ListComputersResult>;
+  get(deviceId: string): Promise<Computer>;
+  resolve(selector: ComputerSelector): Promise<ResolvedComputer>;
+}
+
+function selectorToRemoteTarget(
+  selector: ComputerSelector,
+): RemoteEnvironmentTarget {
+  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: RemoteEnvironmentConnection): Computer {
+  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,
+  };
+}
+
+/** Public Cloud computer discovery and selection client. */
+export class ComputersClientImpl implements ComputersClient {
+  private readonly environments: RemoteEnvironmentClient;
+
+  constructor(client: Letta) {
+    this.environments = new RemoteEnvironmentClient({}, client);
+  }
+
+  async list(
+    options: ListComputersOptions = {},
+  ): Promise<ListComputersResult> {
+    const result = await this.environments.listEnvironments(options);
+    return {
+      computers: result.connections.map(toComputer),
+      hasNextPage: result.hasNextPage,
+    };
+  }
+
+  async get(deviceId: string): Promise<Computer> {
+    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: ComputerSelector): Promise<ResolvedComputer> {
+    const result = await this.environments.resolveEnvironment(
+      selectorToRemoteTarget(selector),
+    );
+    return {
+      connectionId: result.connectionId,
+      computer: result.environment
+        ? toComputer(result.environment)
+        : undefined,
+    };
+  }
+}

package/src/index.ts

@@ -173,6 +173,15 @@ export type {
 } from "./management-types.js";
 
 export { RepositoriesClient } from "./repositories.js";
+export type {
+  Computer,
+  ComputerMetadata,
+  ComputerSelector,
+  ComputersClient,
+  ListComputersOptions,
+  ListComputersResult,
+  ResolvedComputer,
+} from "./computers.js";
 export { LettaAgentClient } from "./client.js";
 export { CloudManagedSandboxExpiredError } from "./cloud-session.js";
 export { createReactNativeWebSocketConstructor } from "./websocket.js";