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

package/src/cloud-session.ts

@@ -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,40 +408,21 @@ 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);
+      this.watchTransportDisconnect(client, { recoverWhenIdle: true });
 
       const tools = agentToolNames(response.agent);
       const skillSources = options.skillSources;
@@ -428,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,
@@ -490,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) {
@@ -982,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";

package/src/remote-client-session-core.ts

@@ -78,6 +78,9 @@ export abstract class RemoteClientSessionCore implements LettaCodeSession {
   private initializePromise: Promise<SDKInitMessage> | null = null;
   private removeMessageHandler: (() => void) | null = null;
   private detachTransportDisconnect: (() => void) | null = null;
+  private idleTransportDisconnected = false;
+  private transportRecoveryPromise: Promise<void> | null = null;
+  private transportDisconnectGeneration = 0;
   private readonly turns: RemoteTurnCoordinator;
   private toolNames: string[] | undefined;
   private deviceStatusListeners = new Set<(status: SessionDeviceStatus) => void>();
@@ -207,18 +210,25 @@ export abstract class RemoteClientSessionCore implements LettaCodeSession {
   }
 
   async send(message: SendMessage): Promise<void> {
+    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) {
@@ -556,6 +566,7 @@ export abstract class RemoteClientSessionCore implements LettaCodeSession {
     this.deviceStatusListeners.clear();
     this.controller?.close();
     this.controller = null;
+    this.idleTransportDisconnected = false;
     this.onCoreClose();
   }
 
@@ -625,27 +636,31 @@ export abstract class RemoteClientSessionCore implements LettaCodeSession {
   protected abstract initializeRuntimeController(): Promise<RuntimeSessionInit>;
 
   /**
-   * Fail the session when its transport drops unexpectedly.
-   *
-   * Without this an in-flight turn parks forever: nextMessage() only settles
-   * through the coordinator, and the socket's own pending-request rejection
-   * covers request/response commands, not streaming turns.
-   *
-   * The session is not revived — the runtime lived on the dead socket. The
-   * caller observes the error and rebuilds via resumeSession().
-   *
-   * Subclasses call this only once their runtime is live: a drop before that
-   * already surfaces as a rejected connect or runtime-start, and failing the
-   * session there would defeat initialize()'s retry path. Explicit closes do
-   * not notify, so this fires for faults only. Detaching stays here so every
-   * teardown path — clean close and failed initialize alike — covers it.
+   * Active turns fail because the input may have reached the listener. Cloud
+   * sessions may recover an idle connection before the next turn is tracked.
    */
-  protected watchTransportDisconnect(client: {
-    onDisconnect(handler: () => void): () => void;
-  }): void {
+  protected watchTransportDisconnect(
+    client: { onDisconnect(handler: () => void): () => void },
+    options: { recoverWhenIdle?: boolean } = {},
+  ): void {
     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.`,
       );
@@ -653,6 +668,62 @@ export abstract class RemoteClientSessionCore implements LettaCodeSession {
     });
   }
 
+  private async recoverIdleTransportIfNeeded(): Promise<void> {
+    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;
+  }
+
+  protected async recoverIdleTransport(
+    _runtime: RuntimeScope,
+  ): Promise<RuntimeSessionInit> {
+    throw new Error(`${this.label} sessions do not support idle transport recovery`);
+  }
+
+  protected onIdleTransportDisconnect(): void {
+    // Optional hook for transport-specific handler cleanup before recovery.
+  }
+
+  protected onRecoveredTransportDiscarded(): void {
+    // Optional hook when a recovery finishes after the session closed or dropped again.
+  }
+
   protected async afterRuntimeInitialized(): Promise<void> {
     // Optional hook for subclasses to send transport-specific startup frames.
   }

package/src/remote.ts

@@ -35,6 +35,12 @@ export interface RemoteEnvironmentConnection {
   metadata?: Record<string, unknown>;
 }
 
+export interface RemoteEnvironmentListOptions {
+  limit?: number;
+  after?: string;
+  onlineOnly?: boolean;
+}
+
 export interface RemoteEnvironmentListResult {
   connections: RemoteEnvironmentConnection[];
   hasNextPage: boolean;
@@ -59,7 +65,7 @@ function ensureOnline(
           : "connectionName" in target
             ? target.connectionName
             : environment.deviceId;
-    throw new Error(`Remote environment is offline: ${label}`);
+    throw new Error(`Computer is offline: ${label}`);
   }
 
   return {
@@ -84,8 +90,16 @@ export class RemoteEnvironmentClient {
     }),
   ) {}
 
-  async listEnvironments(): Promise<RemoteEnvironmentListResult> {
-    return await this.client.environments.list() as RemoteEnvironmentListResult;
+  async listEnvironments(
+    options: RemoteEnvironmentListOptions = {},
+  ): Promise<RemoteEnvironmentListResult> {
+    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),
+    }) as RemoteEnvironmentListResult;
   }
 
   async getEnvironmentByDeviceId(deviceId: string): Promise<RemoteEnvironmentConnection> {
@@ -103,7 +117,15 @@ export class RemoteEnvironmentClient {
       return ensureOnline(await this.getEnvironmentByDeviceId(target.deviceId), target);
     }
 
-    const { connections } = await this.listEnvironments();
+    const connections: RemoteEnvironmentConnection[] = [];
+    let after: string | undefined;
+    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) {
@@ -116,17 +138,24 @@ export class RemoteEnvironmentClient {
       (env) => env.connectionName === target.connectionName,
     );
     if (matches.length === 0) {
-      throw new Error(`Remote environment not found: ${target.connectionName}`);
+      throw new Error(`Computer not found: ${target.connectionName}`);
     }
-    if (matches.length > 1) {
+    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(
-        `Remote environment name is ambiguous: ${target.connectionName}`,
+        `Computer name is ambiguous: ${target.connectionName}. Matches: ${candidates}. Select one by deviceId.`,
       );
     }
-    const match = matches[0];
-    if (!match) {
-      throw new Error(`Remote environment not found: ${target.connectionName}`);
-    }
-    return ensureOnline(match, target);
+    return ensureOnline(onlineMatches[0]!, target);
   }
 }

package/src/types.ts

@@ -17,6 +17,7 @@ import type {
 import type { Message as LettaMessage } from "@letta-ai/letta-client/resources/agents/messages";
 import type { CreateBlock } from "@letta-ai/letta-client/resources/blocks/blocks";
 import type { LettaCodeCloudSandboxOptions } from "./cloud-sandbox.js";
+import type { ComputerSelector } from "./computers.js";
 export type { CreateBlock } from "@letta-ai/letta-client/resources/blocks/blocks";
 export type {
   GitHubRepositoryRef,
@@ -301,18 +302,8 @@ export type McpServers = Record<string, McpServerConfig>;
  */
 export type LettaCodeBackend = "local" | "remote" | "cloud";
 
-/**
- * Stable execution target for remote/cloud runtimes.
- *
- * Strings are treated as human-readable environment names. Object forms allow
- * callers to avoid relying on names as unique identifiers.
- */
-export type LettaCodeEnvironment =
-  | string
-  | { name: string }
-  | { id: string }
-  | { connectionId: string }
-  | { deviceId: string };
+/** @deprecated Use `ComputerSelector` from the package root. */
+export type LettaCodeEnvironment = ComputerSelector;
 
 export interface LettaCodeLocalAppServerOptions {
   /**
@@ -383,11 +374,13 @@ export interface LettaCodeCloudClientOptions {
   /** Heartbeat interval for the Cloud status websocket. Defaults to 30s. */
   pingIntervalMs?: number;
   /**
-   * Execution target for Letta Cloud sessions. If omitted, the SDK creates
-   * and owns a sandbox for the session.
+   * Computer where Letta Cloud sessions run. If omitted, the SDK creates and
+   * owns a managed sandbox for the session.
    */
+  computer?: ComputerSelector;
+  /** @deprecated Use `computer`. */
   environment?: LettaCodeEnvironment;
-  /** Options for SDK-managed sandboxes when environment is omitted. */
+  /** Options for SDK-managed sandboxes when no computer is selected. */
   sandbox?: LettaCodeCloudSandboxOptions;
 }
 
@@ -709,12 +702,14 @@ export interface CreateSessionOptions {
 /**
  * Session options accepted by LettaAgentClient methods.
  *
- * `environment` is a cloud execution-target override. It is deliberately
+ * `computer` is a Cloud execution-target override. It is deliberately
  * session-scoped rather than part of createAgent() options.
  */
 export interface LettaCodeClientSessionOptions extends CreateSessionOptions {
+  computer?: ComputerSelector;
+  /** @deprecated Use `computer`. */
   environment?: LettaCodeEnvironment;
-  /** Per-session SDK-managed sandbox options when environment is omitted. */
+  /** Per-session SDK-managed sandbox options when no computer is selected. */
   sandbox?: LettaCodeCloudSandboxOptions;
   /**
    * Extra environment variables for the session's harness process. Each