@letta-ai/letta-agent-sdk 0.3.1 → 0.3.2

package/dist/index.js

@@ -701,7 +701,56 @@ function createAppServerClient(options) {
   return new AppServerClient(options);
 }
 
+// src/request-ids.ts
+var processRequestCounter = 0;
+function createRequestIdGenerator() {
+  const nonce = Math.random().toString(36).slice(2, 10);
+  return (prefix = "req") => `${prefix}-${nonce}-${++processRequestCounter}`;
+}
+function applyUniqueRequestIds(client) {
+  client.nextRequestId = createRequestIdGenerator();
+  return client;
+}
+
 // src/app-server-management.ts
+var DEFAULT_IDLE_LINGER_MS = 250;
+var registeredTransportsByUrl = new Map;
+function appServerUrlKey(value) {
+  try {
+    const url = new URL(value);
+    if (url.protocol === "http:")
+      url.protocol = "ws:";
+    if (url.protocol === "https:")
+      url.protocol = "wss:";
+    url.hash = "";
+    url.searchParams.delete("channel");
+    return url.toString();
+  } catch {
+    return value;
+  }
+}
+function registerManagementTransport(url, transport) {
+  const key = appServerUrlKey(url);
+  const registration = { transport };
+  const transports = registeredTransportsByUrl.get(key) ?? new Set;
+  transports.add(registration);
+  registeredTransportsByUrl.set(key, transports);
+  return () => {
+    transports.delete(registration);
+    if (transports.size === 0) {
+      registeredTransportsByUrl.delete(key);
+    }
+  };
+}
+async function releaseAppServerManagementConnections(url) {
+  const key = appServerUrlKey(url);
+  while (true) {
+    const transports = [...registeredTransportsByUrl.get(key) ?? []];
+    if (transports.length === 0)
+      return;
+    await Promise.all(transports.map(({ transport }) => transport.releaseIdleConnection()));
+  }
+}
 function ensureResponse(response, value, fallback) {
   if (!response.success || value == null) {
     throw new Error(response.error ?? fallback);
@@ -737,8 +786,16 @@ function stringRecord(value) {
 
 class AppServerManagementTransport {
   options;
+  connectionPromise = null;
+  releasePromise = null;
+  closingConnections = new Set;
+  inFlightRequests = 0;
+  idleWaiters = new Set;
+  idleTimer = null;
+  idleLingerMs;
   constructor(options) {
     this.options = options;
+    this.idleLingerMs = options.idleLingerMs ?? DEFAULT_IDLE_LINGER_MS;
   }
   async listAgents(query) {
     const response = await this.request("agent_list", { query }, "agent_list_response");
@@ -805,38 +862,206 @@ class AppServerManagementTransport {
     }
     return { messages: response.messages };
   }
+  releaseIdleConnection() {
+    this.clearIdleTimer();
+    if (this.releasePromise)
+      return this.releasePromise;
+    const release = this.releaseConnectionWhenIdle();
+    this.releasePromise = release;
+    release.then(() => {
+      if (this.releasePromise === release) {
+        this.releasePromise = null;
+      }
+    }, () => {
+      if (this.releasePromise === release) {
+        this.releasePromise = null;
+      }
+    });
+    return release;
+  }
   async request(type, body, responseType) {
-    const ownedConnection = this.options.url ? null : await this.options.connect?.();
+    if (this.releasePromise) {
+      await this.releasePromise;
+    }
+    if (this.closingConnections.size > 0) {
+      await Promise.all([...this.closingConnections]);
+    }
+    this.clearIdleTimer();
+    this.inFlightRequests += 1;
+    try {
+      const { client } = await this.acquireConnection();
+      const command = {
+        type,
+        request_id: client.nextRequestId(type),
+        ...body
+      };
+      const response = await client.request(command, {
+        predicate: (message) => message.type === responseType
+      });
+      return response;
+    } finally {
+      this.inFlightRequests -= 1;
+      if (this.inFlightRequests === 0) {
+        const waiters = [...this.idleWaiters];
+        this.idleWaiters.clear();
+        for (const resolve of waiters)
+          resolve();
+        if (!this.releasePromise) {
+          this.scheduleIdleRelease();
+        }
+      }
+    }
+  }
+  async releaseConnectionWhenIdle() {
+    if (this.inFlightRequests > 0) {
+      await new Promise((resolve) => {
+        this.idleWaiters.add(resolve);
+      });
+    }
+    this.clearIdleTimer();
+    const promise = this.connectionPromise;
+    try {
+      if (promise) {
+        this.connectionPromise = null;
+        await this.trackClosingConnection(await promise);
+      }
+      if (this.closingConnections.size > 0) {
+        await Promise.all([...this.closingConnections]);
+      }
+    } catch {}
+  }
+  acquireConnection() {
+    if (this.connectionPromise)
+      return this.connectionPromise;
+    const promise = this.openConnection().then((connection) => {
+      connection.detachDisconnect = connection.client.onDisconnect(() => {
+        this.discardConnection(promise, connection);
+      });
+      return connection;
+    }, (error) => {
+      if (this.connectionPromise === promise) {
+        this.connectionPromise = null;
+      }
+      throw error;
+    });
+    this.connectionPromise = promise;
+    return promise;
+  }
+  async openConnection() {
+    const ownedConnection = this.options.url ? null : await this.options.connect?.() ?? null;
     const url = this.options.url ?? ownedConnection?.url;
     if (!url) {
       throw new Error("App-server management requires a url or connect hook.");
     }
+    const unregister = registerManagementTransport(url, this);
     let client = null;
     try {
-      client = createAppServerClient({
+      client = applyUniqueRequestIds(createAppServerClient({
         url,
         ...this.options.authToken !== undefined ? { authToken: this.options.authToken } : {},
         ...this.options.WebSocket ? {
           WebSocket: this.options.WebSocket
         } : {},
         ...this.options.requestTimeoutMs !== undefined ? { requestTimeoutMs: this.options.requestTimeoutMs } : {}
-      });
+      }));
       await client.connect();
-      const command = {
-        type,
-        request_id: client.nextRequestId(type),
-        ...body
-      };
-      const response = await client.request(command, {
-        predicate: (message) => message.type === responseType
-      });
-      return response;
-    } finally {
-      client?.close();
-      ownedConnection?.close();
+    } catch (error) {
+      try {
+        if (client) {
+          const controlClosed = waitForSocketClose(client.control);
+          client.close();
+          ownedConnection?.close();
+          await controlClosed;
+        } else {
+          ownedConnection?.close();
+        }
+      } catch {} finally {
+        unregister();
+      }
+      throw error;
     }
+    return {
+      client,
+      ownedConnection,
+      detachDisconnect: () => {},
+      unregister
+    };
+  }
+  discardConnection(promise, connection) {
+    if (this.connectionPromise === promise) {
+      this.connectionPromise = null;
+      this.clearIdleTimer();
+    }
+    this.trackClosingConnection(connection);
+  }
+  trackClosingConnection(connection) {
+    const closing = closeConnection(connection);
+    this.closingConnections.add(closing);
+    closing.then(() => this.closingConnections.delete(closing), () => this.closingConnections.delete(closing));
+    return closing;
+  }
+  scheduleIdleRelease() {
+    if (!this.connectionPromise)
+      return;
+    this.clearIdleTimer();
+    const timer = setTimeout(() => {
+      this.idleTimer = null;
+      this.releaseIdleConnection();
+    }, this.idleLingerMs);
+    this.idleTimer = timer;
+    timer.unref?.();
+  }
+  clearIdleTimer() {
+    if (this.idleTimer === null)
+      return;
+    clearTimeout(this.idleTimer);
+    this.idleTimer = null;
+  }
+}
+async function closeConnection(connection) {
+  connection.detachDisconnect();
+  const controlClosed = waitForSocketClose(connection.client.control);
+  try {
+    connection.client.close();
+    connection.ownedConnection?.close();
+    await controlClosed;
+  } finally {
+    connection.unregister();
   }
 }
+function waitForSocketClose(socket) {
+  if (socket.readyState === 3)
+    return Promise.resolve();
+  return new Promise((resolve) => {
+    let settled = false;
+    let detach = () => {};
+    const finish = () => {
+      if (settled)
+        return;
+      settled = true;
+      clearTimeout(timeout);
+      detach();
+      resolve();
+    };
+    if (socket.addEventListener) {
+      socket.addEventListener("close", finish);
+      detach = () => socket.removeEventListener?.("close", finish);
+    } else if (socket.once) {
+      socket.once("close", finish);
+      detach = () => socket.off?.("close", finish);
+    } else if (socket.on) {
+      socket.on("close", finish);
+      detach = () => socket.off?.("close", finish);
+    } else {
+      resolve();
+      return;
+    }
+    const timeout = setTimeout(finish, 1000);
+    timeout.unref?.();
+    if (socket.readyState === 3)
+      finish();
+  });
+}
 
 // node_modules/@letta-ai/letta-code/dist/agent-presets.js
 var LETTA_CODE_ORIGIN_TAG = "origin:letta-code";
@@ -5914,6 +6139,7 @@ class RemoteClientSessionCore {
   _modelSettings = null;
   label;
   requestTimeoutMs;
+  initializePromise = null;
   streamQueue = [];
   streamResolvers = [];
   removeMessageHandler = null;
@@ -5931,43 +6157,72 @@ class RemoteClientSessionCore {
     this.requestTimeoutMs = config.requestTimeoutMs;
   }
   async initialize() {
+    if (this.closed) {
+      throw new Error("Session is closed");
+    }
+    if (this.initializePromise) {
+      return this.initializePromise;
+    }
     if (this.initialized) {
       throw new Error("Session already initialized");
     }
+    const attempt = this.performInitialize();
+    const memo = attempt.catch((error) => {
+      this.cleanupFailedInitialize();
+      throw error;
+    }).finally(() => {
+      if (this.initializePromise === memo) {
+        this.initializePromise = null;
+      }
+    });
+    this.initializePromise = memo;
+    return memo;
+  }
+  async performInitialize() {
+    const init = await this.initializeRuntimeController();
+    this.controller = init.controller;
+    this.runtime = init.runtime;
+    this._agentId = init.runtime.agent_id;
+    this._conversationId = init.runtime.conversation_id;
+    this._sessionId = `${init.runtime.agent_id}:${init.runtime.conversation_id}`;
+    this._modelSettings = init.modelSettings ?? null;
+    this._model = typeof init.model === "string" ? init.model : typeof this._modelSettings?.model === "string" ? this._modelSettings.model : "";
+    this.toolNames = init.tools;
+    this.removeMessageHandler = this.controller.onMessage(this.handleProtocolMessage);
+    await this.afterRuntimeInitialized();
+    await this.applyPostInitializeOptions();
     if (this.closed) {
       throw new Error("Session is closed");
     }
-    try {
-      const init = await this.initializeRuntimeController();
-      this.controller = init.controller;
-      this.runtime = init.runtime;
-      this._agentId = init.runtime.agent_id;
-      this._conversationId = init.runtime.conversation_id;
-      this._sessionId = `${init.runtime.agent_id}:${init.runtime.conversation_id}`;
-      this._modelSettings = init.modelSettings ?? null;
-      this._model = typeof init.model === "string" ? init.model : typeof this._modelSettings?.model === "string" ? this._modelSettings.model : "";
-      this.toolNames = init.tools;
-      this.removeMessageHandler = this.controller.onMessage(this.handleProtocolMessage);
-      this.initialized = true;
-      await this.afterRuntimeInitialized();
-      await this.applyPostInitializeOptions();
-      const initMessage = {
-        type: "init",
-        agentId: init.runtime.agent_id,
-        sessionId: this._sessionId,
-        conversationId: init.runtime.conversation_id,
-        model: this._model
-      };
-      if (this.toolNames !== undefined)
-        initMessage.tools = this.toolNames;
-      if (init.skillSources !== undefined) {
-        initMessage.skillSources = init.skillSources;
-      }
-      return initMessage;
-    } catch (error) {
-      this.close();
-      throw error;
+    this.initialized = true;
+    const initMessage = {
+      type: "init",
+      agentId: init.runtime.agent_id,
+      sessionId: this._sessionId,
+      conversationId: init.runtime.conversation_id,
+      model: this._model
+    };
+    if (this.toolNames !== undefined)
+      initMessage.tools = this.toolNames;
+    if (init.skillSources !== undefined) {
+      initMessage.skillSources = init.skillSources;
     }
+    return initMessage;
+  }
+  cleanupFailedInitialize() {
+    this.removeMessageHandler?.();
+    this.removeMessageHandler = null;
+    this.controller?.close();
+    this.controller = null;
+    this.onCoreClose();
+    this.runtime = null;
+    this._agentId = null;
+    this._conversationId = null;
+    this._sessionId = null;
+    this._modelSettings = null;
+    this._model = "";
+    this.toolNames = undefined;
+    this.initialized = false;
   }
   async send(message) {
     if (!this.initialized) {
@@ -6064,6 +6319,12 @@ class RemoteClientSessionCore {
     if (!this.initialized) {
       await this.initialize();
     }
+    if (!this.controller || !this.runtime) {
+      throw new Error("Session is not initialized");
+    }
+    return this.applyModelUpdate(update);
+  }
+  async applyModelUpdate(update) {
     if (!this.controller || !this.runtime) {
       throw new Error("Session is not initialized");
     }
@@ -6480,7 +6741,7 @@ class RemoteClientSessionCore {
     if (this.mode.kind !== "session")
       return;
     if (this.mode.options.model !== undefined || this.mode.options.reasoningEffort !== undefined) {
-      await this.updateModel({
+      await this.applyModelUpdate({
         ...this.mode.options.model !== undefined ? { model: this.mode.options.model } : {},
         ...this.mode.options.reasoningEffort !== undefined ? { reasoningEffort: this.mode.options.reasoningEffort } : {}
       });
@@ -7243,13 +7504,15 @@ class AppServerSession extends RemoteClientSessionCore {
     return options.memfs !== false;
   }
   async initializeRuntimeController() {
+    await this.remoteOptions.beforeConnect?.();
     const url = await this.resolveAppServerUrl();
-    const client = createAppServerClient({
+    await releaseAppServerManagementConnections(url);
+    const client = applyUniqueRequestIds(createAppServerClient({
       url,
       ...this.remoteOptions.authToken !== undefined ? { authToken: this.remoteOptions.authToken } : {},
       ...this.remoteOptions.WebSocket ? { WebSocket: this.remoteOptions.WebSocket } : {},
       ...this.remoteOptions.requestTimeoutMs !== undefined ? { requestTimeoutMs: this.remoteOptions.requestTimeoutMs } : {}
-    });
+    }));
     this.removeControlRequestHandler = registerAppServerControlRequestHandler({
       client,
       getRuntime: () => this.runtime,
@@ -8120,14 +8383,14 @@ class CloudEnvironmentSession extends RemoteClientSessionCore {
       apiKey,
       authMode: this.cloudOptions.webSocketAuth ?? "header"
     });
-    const client = createAppServerClient({
+    const client = applyUniqueRequestIds(createAppServerClient({
       url,
       WebSocket: createCloudStatusWebSocketConstructor({
         cloudOptions: this.cloudOptions,
         runtime: resolved.runtime
       }),
       requestTimeoutMs: this.cloudOptions.requestTimeoutMs ?? DEFAULT_TURN_TIMEOUT_MS
-    });
+    }));
     this.removeControlRequestHandler = registerAppServerControlRequestHandler({
       client,
       getRuntime: () => this.runtime,
@@ -8865,6 +9128,10 @@ class LettaAgentClientBase {
       if (requestTimeoutMs !== undefined && (!Number.isInteger(requestTimeoutMs) || requestTimeoutMs <= 0)) {
         throw new Error("Invalid appServer.requestTimeoutMs. Expected a positive integer.");
       }
+      const idleLingerMs = localOptions.appServer?.idleLingerMs;
+      if (idleLingerMs !== undefined && (!Number.isInteger(idleLingerMs) || idleLingerMs < 0)) {
+        throw new Error("Invalid appServer.idleLingerMs. Expected a non-negative integer.");
+      }
       const startupTimeoutMs = localOptions.appServer?.startupTimeoutMs;
       if (startupTimeoutMs !== undefined && (!Number.isInteger(startupTimeoutMs) || startupTimeoutMs <= 0)) {
         throw new Error("Invalid appServer.startupTimeoutMs. Expected a positive integer.");
@@ -8877,6 +9144,9 @@ class LettaAgentClientBase {
       if (options.requestTimeoutMs !== undefined && (!Number.isInteger(options.requestTimeoutMs) || options.requestTimeoutMs <= 0)) {
         throw new Error("Invalid requestTimeoutMs. Expected a positive integer.");
       }
+      if (options.idleLingerMs !== undefined && (!Number.isInteger(options.idleLingerMs) || options.idleLingerMs < 0)) {
+        throw new Error("Invalid idleLingerMs. Expected a non-negative integer.");
+      }
     }
     if (this.backend === "cloud") {
       validateCloudClientOptions(options);
@@ -8891,7 +9161,7 @@ class LettaAgentClientBase {
     }
     validateCreateAgentOptions(options);
     if (this.backend === "remote") {
-      const session = new AppServerSession(this.remoteOptions(), {
+      const session = new AppServerSession(this.appServerSessionOptions(), {
         kind: "create-agent",
         options
       });
@@ -8914,7 +9184,7 @@ class LettaAgentClientBase {
       if (!agentId) {
         throw new Error("App-server createSession() requires an agent id. Call createAgent() first or pass an agent id.");
       }
-      return new AppServerSession(this.remoteOptions(), {
+      return new AppServerSession(this.appServerSessionOptions(), {
         kind: "session",
         agentId,
         newConversation: true,
@@ -8940,13 +9210,13 @@ class LettaAgentClientBase {
     validateCreateSessionOptions(sessionOptions);
     if (this.backend === "remote") {
       if (looksLikeConversationId(id)) {
-        return new AppServerSession(this.remoteOptions(), {
+        return new AppServerSession(this.appServerSessionOptions(), {
           kind: "session",
           conversationId: id,
           options
         });
       }
-      return new AppServerSession(this.remoteOptions(), {
+      return new AppServerSession(this.appServerSessionOptions(), {
         kind: "session",
         agentId: id,
         defaultConversation: true,
@@ -9045,6 +9315,12 @@ class LettaAgentClientBase {
     }
     return this.options;
   }
+  appServerSessionOptions() {
+    return {
+      ...this.remoteOptions(),
+      beforeConnect: () => this.releaseIdleManagementConnection()
+    };
+  }
   getRepositoriesClient() {
     if (this.backend !== "cloud") {
       throw new Error('client.repositories is only available with backend: "cloud".');
@@ -9052,6 +9328,9 @@ class LettaAgentClientBase {
     this.repositoriesClient ??= new RepositoriesClient(this.cloudOptions());
     return this.repositoriesClient;
   }
+  async releaseIdleManagementConnection() {
+    await this.managementTransport?.releaseIdleConnection?.();
+  }
   getManagementTransport() {
     if (this.managementTransport)
       return this.managementTransport;
@@ -9201,7 +9480,7 @@ ${output.trim()}` : ""}`));
 }
 
 // src/local-app-server-session.ts
-function createLocalAppServerSession(options, mode) {
+function createLocalAppServerSession(options, mode, beforeConnect) {
   const appServer = options ?? {};
   const sessionOptions = {
     ...appServer.url !== undefined ? { url: appServer.url } : {
@@ -9214,7 +9493,8 @@ function createLocalAppServerSession(options, mode) {
     },
     ...appServer.WebSocket !== undefined ? { WebSocket: appServer.WebSocket } : {},
     ...appServer.requestTimeoutMs !== undefined ? { requestTimeoutMs: appServer.requestTimeoutMs } : {},
-    ...appServer.pinGlobalAgent !== undefined ? { pinGlobalAgent: appServer.pinGlobalAgent } : {}
+    ...appServer.pinGlobalAgent !== undefined ? { pinGlobalAgent: appServer.pinGlobalAgent } : {},
+    ...beforeConnect ? { beforeConnect } : {}
   };
   return new AppServerSession(sessionOptions, mode);
 }
@@ -9614,6 +9894,8 @@ class Session {
   _sessionId = null;
   _conversationId = null;
   initialized = false;
+  closed = false;
+  initializePromise = null;
   externalTools = new Map;
   streamQueue = [];
   streamResolvers = [];
@@ -9636,9 +9918,28 @@ class Session {
     }
   }
   async initialize() {
+    if (this.closed) {
+      throw new Error("Session is closed");
+    }
+    if (this.initializePromise) {
+      return this.initializePromise;
+    }
     if (this.initialized) {
       throw new Error("Session already initialized");
     }
+    const attempt = this.performInitialize();
+    const memo = attempt.catch((error) => {
+      this.cleanupFailedInitialize();
+      throw error;
+    }).finally(() => {
+      if (this.initializePromise === memo) {
+        this.initializePromise = null;
+      }
+    });
+    this.initializePromise = memo;
+    return memo;
+  }
+  async performInitialize() {
     sessionLog("init", "connecting transport...");
     await this.transport.connect();
     sessionLog("init", "transport connected, sending initialize request");
@@ -9663,11 +9964,14 @@ class Session {
         this._agentId = initMsg.agent_id;
         this._sessionId = initMsg.session_id;
         this._conversationId = initMsg.conversation_id;
-        this.initialized = true;
-        this.startBackgroundPump();
         if (this.externalTools.size > 0) {
           await this.registerExternalTools();
         }
+        if (this.closed) {
+          throw new Error("Session is closed");
+        }
+        this.initialized = true;
+        this.startBackgroundPump();
         const allTools = [
           ...initMsg.tools,
           ...Array.from(this.externalTools.keys())
@@ -9698,6 +10002,16 @@ ${stderr}` : "";
     sessionLog("init", `ERROR: transport closed before init message received${detail}`);
     throw new Error(`Failed to initialize session - no init message received${detail}`);
   }
+  cleanupFailedInitialize() {
+    this.transport.close();
+    this.closed = true;
+    this.initialized = false;
+    this._agentId = null;
+    this._sessionId = null;
+    this._conversationId = null;
+    this.pumpClosed = true;
+    this.resolveAllStreamWaiters(null);
+  }
   async send(message) {
     if (!this.initialized) {
       sessionLog("send", "auto-initializing (not yet initialized)");
@@ -10374,6 +10688,9 @@ ${stderr}` : "";
     throw new Error("updateToolset() is not supported by this session. Use a Cloud, Remote, or local agent session.");
   }
   close() {
+    if (this.closed)
+      return;
+    this.closed = true;
     sessionLog("close", `closing session (agent=${this._agentId}, conversation=${this._conversationId})`);
     this.transport.close();
     this.pumpClosed = true;
@@ -10571,7 +10888,8 @@ class LettaAgentClient extends LettaAgentClientBase {
         })
       },
       ...localOptions?.WebSocket !== undefined ? { WebSocket: localOptions.WebSocket } : {},
-      ...localOptions?.requestTimeoutMs !== undefined ? { requestTimeoutMs: localOptions.requestTimeoutMs } : {}
+      ...localOptions?.requestTimeoutMs !== undefined ? { requestTimeoutMs: localOptions.requestTimeoutMs } : {},
+      ...localOptions?.idleLingerMs !== undefined ? { idleLingerMs: localOptions.idleLingerMs } : {}
     });
   }
   async createLocalAgent(options) {
@@ -10580,7 +10898,7 @@ class LettaAgentClient extends LettaAgentClientBase {
       const session2 = createLocalAppServerSession(localOptions.appServer, {
         kind: "create-agent",
         options
-      });
+      }, () => this.releaseIdleManagementConnection());
       const initMsg2 = await session2.initialize();
       session2.close();
       return initMsg2.agentId;
@@ -10598,7 +10916,7 @@ class LettaAgentClient extends LettaAgentClientBase {
         agentId,
         newConversation: true,
         options
-      });
+      }, () => this.releaseIdleManagementConnection());
     }
     if (agentId) {
       return new Session({ ...sessionOptions, agentId, newConversation: true });
@@ -10613,14 +10931,14 @@ class LettaAgentClient extends LettaAgentClientBase {
           kind: "session",
           conversationId: id,
           options
-        });
+        }, () => this.releaseIdleManagementConnection());
       }
       return createLocalAppServerSession(localOptions.appServer, {
         kind: "session",
         agentId: id,
         defaultConversation: true,
         options
-      });
+      }, () => this.releaseIdleManagementConnection());
     }
     if (looksLikeConversationId2(id)) {
       return new Session({ ...sessionOptions, conversationId: id });
@@ -10888,4 +11206,4 @@ export {
   CloudManagedSandboxExpiredError
 };
 
-//# debugId=D44861B7D6BE1C4C64756E2164756E21
+//# debugId=98DBA625B202A81364756E2164756E21