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

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

@@ -20,6 +20,7 @@ import type {
   SDKResultMessage,
   SendCommandOptions,
   SendMessage,
+  SendOptions,
   SessionDeviceStatus,
   UpdateModelOptions,
   UpdateModelResult,
@@ -43,6 +44,7 @@ import {
   resolveDreamingSettings,
   sameContextCandidates,
   toBaseModelHandle,
+  turnSendOptions,
   type NormalizedUpdateModelInput,
   type RemoteClientSessionCoreConfig,
   type RemoteClientRuntimeController,
@@ -78,6 +80,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>();
@@ -122,8 +127,7 @@ export abstract class RemoteClientSessionCore implements LettaCodeSession {
     const attempt = this.performInitialize();
     const memo = attempt
       .catch((error: unknown) => {
-        // Tear down only this attempt's partial state. Never close() the
-        // session here: a failed remote attempt is retryable.
+        // Tear down only this attempt's partial state. A failed remote attempt is retryable.
         this.cleanupFailedInitialize();
         throw error;
       })
@@ -164,8 +168,7 @@ export abstract class RemoteClientSessionCore implements LettaCodeSession {
       throw new Error("Session is closed");
     }
 
-    // This is the lifecycle commit point. Lazy entry points must continue to
-    // await initializePromise until every post-initialize option is applied.
+    // Lazy entry points must await this lifecycle commit after all post-initialize options.
     this.initialized = true;
 
     const initMessage: SDKInitMessage = {
@@ -206,21 +209,26 @@ export abstract class RemoteClientSessionCore implements LettaCodeSession {
     this.initialized = false;
   }
 
-  async send(message: SendMessage): Promise<void> {
+  async send(message: SendMessage, options?: SendOptions): 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, options?.otid);
     try {
-      this.controller.sendTurnMessage(this.runtime, message, {
-        clientMessageId: turn.clientMessageId,
-      });
+      controller.sendTurnMessage(runtime, message, turnSendOptions(turn));
     } catch (error) {
       this.turns.removeTrackedTurn(turn);
       throw error;
@@ -317,6 +325,11 @@ export abstract class RemoteClientSessionCore implements LettaCodeSession {
   }
 
   async updateModel(update: string | UpdateModelOptions): Promise<UpdateModelResult> {
+    if (this.mode.kind === "session" && this.mode.options.stateless === true) {
+      throw new Error(
+        "updateModel() is unavailable in a stateless session because it changes persisted agent configuration.",
+      );
+    }
     if (!this.initialized) {
       await this.initialize();
     }
@@ -556,6 +569,7 @@ export abstract class RemoteClientSessionCore implements LettaCodeSession {
     this.deviceStatusListeners.clear();
     this.controller?.close();
     this.controller = null;
+    this.idleTransportDisconnected = false;
     this.onCoreClose();
   }
 
@@ -625,27 +639,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 +671,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.
   }
@@ -779,7 +853,9 @@ export abstract class RemoteClientSessionCore implements LettaCodeSession {
     }
 
     const dreamingSettings = resolveDreamingSettings(options.dreaming);
-    if (dreamingSettings) {
+    const isStatelessSession =
+      this.mode.kind === "session" && this.mode.options.stateless === true;
+    if (dreamingSettings && !isStatelessSession) {
       const response = await this.controller.request(
         "set_reflection_settings",
         {

package/src/remote-session-protocol.ts

@@ -55,6 +55,8 @@ export type RuntimeTurnResult = {
 
 export type RuntimeSendTurnOptions = {
   clientMessageId: string;
+  /** Caller-supplied OTID for the user message, when one was provided. */
+  otid?: string;
 };
 
 export type RuntimeRequestOptions = {
@@ -128,6 +130,8 @@ export type TurnTracker = {
   id: number;
   runtime: RuntimeScope;
   clientMessageId: string;
+  /** Caller-supplied OTID for this turn's user message, when one was provided. */
+  otid?: string;
   queuedAt: number;
   startedAt: number;
   assistantText: string;
@@ -677,3 +681,23 @@ export function toSessionDeviceStatus(
 export function normalizeSendMessage(message: SendMessage): string | MessageContentItem[] {
   return message;
 }
+
+/**
+ * Validate a caller-supplied OTID. Empty/whitespace-only values would silently
+ * defeat correlation, so they are rejected instead of being dropped.
+ */
+export function normalizeCallerOtid(otid: string | undefined): string | undefined {
+  if (otid === undefined) return undefined;
+  if (typeof otid !== "string" || otid.trim() === "") {
+    throw new Error("send() otid must be a non-empty string");
+  }
+  return otid;
+}
+
+/** Wire correlation options for a tracked turn. */
+export function turnSendOptions(turn: TurnTracker): RuntimeSendTurnOptions {
+  return {
+    clientMessageId: turn.clientMessageId,
+    ...(turn.otid !== undefined ? { otid: turn.otid } : {}),
+  };
+}

package/src/remote-turn-coordinator.ts

@@ -15,6 +15,7 @@ import {
   isApprovalConflictSignal,
   loopStatusRunIds,
   loopStatusValue,
+  normalizeCallerOtid,
   queueItems,
   sameRuntime,
   streamDeltaMessageType,
@@ -76,11 +77,19 @@ export class RemoteTurnCoordinator {
     return this.activeTurn !== null || this.pendingTurns.length > 0;
   }
 
-  trackSentTurn(runtime: RuntimeScope): TurnTracker {
+  /**
+   * Start tracking a turn. A caller-supplied OTID doubles as the turn's
+   * `clientMessageId` so queue updates carry the same correlation id the
+   * persisted message will; otherwise the SDK mints one.
+   */
+  trackSentTurn(runtime: RuntimeScope, callerOtid?: string): TurnTracker {
+    const otid = normalizeCallerOtid(callerOtid);
     const turn: TurnTracker = {
       id: ++this.nextTurnId,
       runtime,
-      clientMessageId: `sdk-message-${Date.now()}-${++this.clientMessageCounter}`,
+      ...(otid !== undefined ? { otid } : {}),
+      clientMessageId:
+        otid ?? `sdk-message-${Date.now()}-${++this.clientMessageCounter}`,
       queuedAt: Date.now(),
       startedAt: 0,
       assistantText: "",

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);
   }
 }