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

package/dist/index.js

@@ -701,18 +701,101 @@ 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);
   }
   return value;
 }
+function modelEntries(value) {
+  if (!Array.isArray(value))
+    return [];
+  return value.flatMap((entry) => {
+    if (!entry || typeof entry !== "object" || Array.isArray(entry))
+      return [];
+    const record = entry;
+    if (typeof record.id !== "string" || typeof record.handle !== "string" || typeof record.label !== "string" || typeof record.description !== "string") {
+      return [];
+    }
+    return [{
+      ...record,
+      id: record.id,
+      handle: record.handle,
+      label: record.label,
+      description: record.description
+    }];
+  });
+}
+function stringRecord(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return;
+  }
+  const entries = Object.entries(value).filter((entry) => typeof entry[1] === "string");
+  return entries.length > 0 ? Object.fromEntries(entries) : undefined;
+}
 
 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");
@@ -729,6 +812,30 @@ class AppServerManagementTransport {
     const response = await this.request("agent_update", { agent_id: agentId, body }, "agent_update_response");
     return ensureResponse(response, response.agent, `Failed to update agent ${agentId}.`);
   }
+  async deleteAgent(agentId) {
+    const response = await this.request("agent_delete", { agent_id: agentId }, "agent_delete_response");
+    if (!response.success) {
+      throw new Error(response.error ?? `Failed to delete agent ${agentId}.`);
+    }
+  }
+  async listModels() {
+    const response = await this.request("list_models", {}, "list_models_response");
+    if (!response.success) {
+      throw new Error(response.error ?? "Failed to list models.");
+    }
+    const result = {
+      entries: modelEntries(response.entries)
+    };
+    if (response.available_handles === null) {
+      result.availableHandles = null;
+    } else if (Array.isArray(response.available_handles)) {
+      result.availableHandles = response.available_handles.filter((handle) => typeof handle === "string");
+    }
+    const aliases = stringRecord(response.byok_provider_aliases);
+    if (aliases)
+      result.byokProviderAliases = aliases;
+    return result;
+  }
   async listConversations(query) {
     const response = await this.request("conversation_list", { query }, "conversation_list_response");
     if (!response.success) {
@@ -755,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";
@@ -5424,6 +5699,36 @@ function requiresRuntimeUserInput(toolName) {
 function isHeadlessAutoAllowTool(toolName) {
   return HEADLESS_AUTO_ALLOW_TOOLS.has(toolName);
 }
+function normalizePermissionSuggestions(value) {
+  if (!Array.isArray(value))
+    return;
+  const suggestions = [];
+  for (const entry of value) {
+    if (!entry || typeof entry !== "object")
+      continue;
+    const record = entry;
+    if (typeof record.id === "string" && typeof record.text === "string") {
+      suggestions.push({ id: record.id, text: record.text });
+    }
+  }
+  return suggestions;
+}
+function buildCanUseToolContext(request, requestId) {
+  const context = {};
+  if (typeof requestId === "string")
+    context.requestId = requestId;
+  if (typeof request.tool_call_id === "string")
+    context.toolCallId = request.tool_call_id;
+  const suggestions = normalizePermissionSuggestions(request.permission_suggestions);
+  if (suggestions !== undefined)
+    context.permissionSuggestions = suggestions;
+  if (typeof request.blocked_path === "string" || request.blocked_path === null) {
+    context.blockedPath = request.blocked_path;
+  }
+  if (Array.isArray(request.diffs))
+    context.diffs = request.diffs;
+  return context;
+}
 
 // src/remote-client-session-core.ts
 var FAILURE_STOP_REASONS = new Set([
@@ -5701,6 +6006,121 @@ function queueItems(message) {
     ];
   });
 }
+function deviceStatusRecord(message) {
+  if (message.type !== "update_device_status")
+    return null;
+  const status = message.device_status;
+  return status && typeof status === "object" && !Array.isArray(status) ? status : null;
+}
+function pendingControlRequests(status) {
+  const pending = status.pending_control_requests;
+  if (!Array.isArray(pending))
+    return [];
+  return pending.flatMap((item) => {
+    if (!item || typeof item !== "object" || Array.isArray(item))
+      return [];
+    const record = item;
+    if (typeof record.request_id !== "string")
+      return [];
+    const request = record.request && typeof record.request === "object" && !Array.isArray(record.request) ? record.request : null;
+    if (!request || typeof request.tool_name !== "string")
+      return [];
+    const entry = {
+      requestId: record.request_id,
+      toolName: request.tool_name,
+      permissionSuggestions: permissionSuggestions(request.permission_suggestions),
+      blockedPath: typeof request.blocked_path === "string" || request.blocked_path === null ? request.blocked_path : null
+    };
+    if (typeof request.tool_call_id === "string")
+      entry.toolCallId = request.tool_call_id;
+    if (request.input && typeof request.input === "object" && !Array.isArray(request.input)) {
+      entry.toolInput = request.input;
+    }
+    const previews = diffPreviews(request.diffs);
+    if (previews !== undefined)
+      entry.diffs = previews;
+    return [entry];
+  });
+}
+function permissionSuggestions(value) {
+  if (!Array.isArray(value))
+    return [];
+  return value.flatMap((item) => {
+    if (!item || typeof item !== "object" || Array.isArray(item))
+      return [];
+    const record = item;
+    return typeof record.id === "string" && typeof record.text === "string" ? [{ id: record.id, text: record.text }] : [];
+  });
+}
+function diffPreviews(value) {
+  if (!Array.isArray(value))
+    return;
+  return value.flatMap((item) => {
+    if (!item || typeof item !== "object" || Array.isArray(item))
+      return [];
+    const record = item;
+    if (record.mode === "advanced" && typeof record.fileName === "string" && Array.isArray(record.hunks)) {
+      return [{
+        mode: "advanced",
+        fileName: record.fileName,
+        hunks: diffHunks(record.hunks)
+      }];
+    }
+    if ((record.mode === "fallback" || record.mode === "unpreviewable") && typeof record.fileName === "string" && typeof record.reason === "string") {
+      return [{
+        mode: record.mode,
+        fileName: record.fileName,
+        reason: record.reason
+      }];
+    }
+    return [];
+  });
+}
+function diffHunks(value) {
+  return value.flatMap((item) => {
+    if (!item || typeof item !== "object" || Array.isArray(item))
+      return [];
+    const record = item;
+    if (typeof record.oldStart !== "number" || typeof record.oldLines !== "number" || typeof record.newStart !== "number" || typeof record.newLines !== "number" || !Array.isArray(record.lines)) {
+      return [];
+    }
+    const lines = [];
+    for (const line of record.lines) {
+      if (!line || typeof line !== "object" || Array.isArray(line))
+        continue;
+      const lineRecord = line;
+      const type = lineRecord.type;
+      if (type !== "context" && type !== "add" && type !== "remove" || typeof lineRecord.content !== "string") {
+        continue;
+      }
+      lines.push({
+        type,
+        content: lineRecord.content
+      });
+    }
+    return [{
+      oldStart: record.oldStart,
+      oldLines: record.oldLines,
+      newStart: record.newStart,
+      newLines: record.newLines,
+      lines
+    }];
+  });
+}
+function toSessionDeviceStatus(status) {
+  const permissionMode = normalizePermissionMode(status.current_permission_mode);
+  if (typeof status.is_online !== "boolean" || typeof status.is_processing !== "boolean" || permissionMode === undefined || !(typeof status.current_working_directory === "string" || status.current_working_directory === null)) {
+    return null;
+  }
+  return {
+    isOnline: status.is_online,
+    isProcessing: status.is_processing,
+    permissionMode,
+    workingDirectory: status.current_working_directory,
+    pendingControlRequests: pendingControlRequests(status),
+    raw: { ...status }
+  };
+}
 function normalizeSendMessage(message) {
   return message;
 }
@@ -5719,6 +6139,7 @@ class RemoteClientSessionCore {
   _modelSettings = null;
   label;
   requestTimeoutMs;
+  initializePromise = null;
   streamQueue = [];
   streamResolvers = [];
   removeMessageHandler = null;
@@ -5728,49 +6149,80 @@ class RemoteClientSessionCore {
   messageCounter = 0;
   clientMessageCounter = 0;
   toolNames;
+  deviceStatusListeners = new Set;
+  deviceStatusRefreshCancels = new Set;
   constructor(mode, config) {
     this.mode = mode;
     this.label = config.label;
     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) {
@@ -5867,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");
     }
@@ -5918,6 +6376,86 @@ class RemoteClientSessionCore {
       removed: response.success
     };
   }
+  async getDeviceStatus(options = {}) {
+    if (!this.initialized) {
+      await this.initialize();
+    }
+    if (!this.controller || !this.runtime) {
+      throw new Error("Session is not initialized");
+    }
+    const timeoutMs = options.timeoutMs ?? this.requestTimeoutMs ?? 30000;
+    if (!Number.isInteger(timeoutMs) || timeoutMs <= 0) {
+      throw new Error("Invalid device status timeout. Expected a positive integer.");
+    }
+    return this.refreshDeviceStatus(timeoutMs);
+  }
+  onDeviceStatus(listener) {
+    if (typeof listener !== "function") {
+      throw new Error("Invalid device status listener. Expected a function.");
+    }
+    this.deviceStatusListeners.add(listener);
+    return () => {
+      this.deviceStatusListeners.delete(listener);
+    };
+  }
+  refreshDeviceStatus(timeoutMs) {
+    const controller = this.controller;
+    const runtime = this.runtime;
+    if (!controller || !runtime) {
+      return Promise.reject(new Error("Session is not initialized"));
+    }
+    return new Promise((resolve, reject) => {
+      let status = null;
+      let syncAcknowledged = false;
+      let settled = false;
+      const cleanup = () => {
+        clearTimeout(timer);
+        unsubscribe();
+        this.deviceStatusRefreshCancels.delete(cancel);
+      };
+      const rejectOnce = (error) => {
+        if (settled)
+          return;
+        settled = true;
+        cleanup();
+        reject(error);
+      };
+      const resolveIfComplete = () => {
+        if (settled || !syncAcknowledged || !status)
+          return;
+        settled = true;
+        cleanup();
+        resolve(status);
+      };
+      const cancel = (error) => rejectOnce(error);
+      const timer = setTimeout(() => {
+        rejectOnce(new Error(`Timed out waiting for ${this.label} device status`));
+      }, timeoutMs);
+      timer.unref?.();
+      const unsubscribe = this.onDeviceStatus((nextStatus) => {
+        status = nextStatus;
+        resolveIfComplete();
+      });
+      this.deviceStatusRefreshCancels.add(cancel);
+      controller.request("sync", {
+        runtime,
+        recover_approvals: false,
+        force_device_status: true
+      }, {
+        timeoutMs,
+        predicate: (message) => message.type === "sync_response"
+      }).then((response) => {
+        if (response.success === false) {
+          rejectOnce(new Error(typeof response.error === "string" ? response.error : `Failed to refresh ${this.label} device status`));
+          return;
+        }
+        syncAcknowledged = true;
+        resolveIfComplete();
+      }, (error) => {
+        rejectOnce(error instanceof Error ? error : new Error(String(error)));
+      });
+    });
+  }
   async listMessages(options = {}) {
     if (!this.initialized) {
       await this.initialize();
@@ -5970,6 +6508,11 @@ class RemoteClientSessionCore {
     }
     this.activeTurn = null;
     this.pendingTurns.length = 0;
+    for (const cancel of [...this.deviceStatusRefreshCancels]) {
+      cancel(new Error(`Session closed while waiting for ${this.label} device status`));
+    }
+    this.deviceStatusRefreshCancels.clear();
+    this.deviceStatusListeners.clear();
     this.controller?.close();
     this.controller = null;
     this.onCoreClose();
@@ -6198,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 } : {}
       });
@@ -6207,6 +6750,18 @@ class RemoteClientSessionCore {
   handleProtocolMessage = (message) => {
     if (!this.runtime || !sameRuntime2(message, this.runtime))
       return;
+    const deviceStatus = deviceStatusRecord(message);
+    if (deviceStatus) {
+      const status = toSessionDeviceStatus(deviceStatus);
+      if (!status)
+        return;
+      for (const listener of [...this.deviceStatusListeners]) {
+        try {
+          listener(status);
+        } catch {}
+      }
+      return;
+    }
     if (message.type === "update_queue") {
       const sdkMessage2 = {
         type: "queue_update",
@@ -6636,7 +7191,7 @@ function createExternalToolCallHandler(externalTools) {
     };
   };
 }
-async function resolveAppServerToolApproval(options, toolName, toolInput) {
+async function resolveAppServerToolApproval(options, toolName, toolInput, context) {
   const hasCallback = typeof options.canUseTool === "function";
   const toolNeedsRuntimeUserInput = requiresRuntimeUserInput(toolName);
   if (toolNeedsRuntimeUserInput && !hasCallback) {
@@ -6651,7 +7206,7 @@ async function resolveAppServerToolApproval(options, toolName, toolInput) {
   }
   if (hasCallback) {
     try {
-      const result = await options.canUseTool(toolName, toolInput);
+      const result = await options.canUseTool(toolName, toolInput, context);
       if (result.behavior === "allow") {
         return {
           behavior: "allow",
@@ -6711,7 +7266,7 @@ function toAppServerApprovalDecision(decision) {
     selected_permission_suggestion_ids: selectedPermissionSuggestionIds
   };
 }
-function stringRecord(value) {
+function stringRecord2(value) {
   if (!value || typeof value !== "object" || Array.isArray(value))
     return;
   const record = {};
@@ -6757,7 +7312,7 @@ function normalizeListModelsResponse(response) {
   } else if (Array.isArray(response.available_handles)) {
     result.availableHandles = response.available_handles.filter((handle) => typeof handle === "string");
   }
-  const aliases = stringRecord(response.byok_provider_aliases);
+  const aliases = stringRecord2(response.byok_provider_aliases);
   if (aliases)
     result.byokProviderAliases = aliases;
   return result;
@@ -6812,7 +7367,7 @@ async function respondToAppServerControlRequest(config, message) {
     return;
   const toolName = typeof requestRecord.tool_name === "string" ? requestRecord.tool_name : "unknown";
   const toolInput = requestRecord.input && typeof requestRecord.input === "object" && !Array.isArray(requestRecord.input) ? requestRecord.input : {};
-  const decision = await resolveAppServerToolApproval(config.getOptions(), toolName, toolInput);
+  const decision = await resolveAppServerToolApproval(config.getOptions(), toolName, toolInput, buildCanUseToolContext(requestRecord, requestId));
   config.client.input({
     runtime,
     payload: {
@@ -6949,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,
@@ -7155,6 +7712,19 @@ function asArray(body, action) {
   }
   return body;
 }
+function cloudModelEntry(raw) {
+  if (typeof raw.handle !== "string" || raw.handle.length === 0) {
+    return null;
+  }
+  const label = typeof raw.display_name === "string" ? raw.display_name : typeof raw.name === "string" ? raw.name : raw.handle;
+  return {
+    ...raw,
+    id: typeof raw.id === "string" && raw.id.length > 0 ? raw.id : raw.handle,
+    handle: raw.handle,
+    label,
+    description: typeof raw.description === "string" ? raw.description : ""
+  };
+}
 
 class CloudManagementTransport {
   options;
@@ -7170,6 +7740,20 @@ class CloudManagementTransport {
   updateAgent(agentId, body) {
     return this.requestObject(`/v1/agents/${encodeURIComponent(agentId)}`, "PATCH", body, "Cloud update agent");
   }
+  async deleteAgent(agentId) {
+    await this.requestUrl(this.url(`/v1/agents/${encodeURIComponent(agentId)}`), "DELETE", undefined, "Cloud delete agent");
+  }
+  async listModels() {
+    const entries = await this.getArray("/v1/models", {}, "Cloud list models");
+    const normalized = entries.flatMap((entry) => {
+      const model = cloudModelEntry(entry);
+      return model ? [model] : [];
+    });
+    return {
+      entries: normalized,
+      availableHandles: normalized.map((entry) => entry.handle)
+    };
+  }
   listConversations(query) {
     return this.getArray("/v1/conversations/", query, "Cloud list conversations");
   }
@@ -7799,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,
@@ -8254,6 +8838,11 @@ class CloudEnvironmentSession extends RemoteClientSessionCore {
 function definedEntries(values) {
   return Object.fromEntries(Object.entries(values).filter(([, value]) => value !== undefined));
 }
+function assertNonEmptyId(value, name) {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new Error(`Invalid ${name}. Expected a non-empty string.`);
+  }
+}
 function agentListQuery(options) {
   const orderBy = options.orderBy?.replace(/[A-Z]/g, (character) => `_${character.toLowerCase()}`);
   return {
@@ -8326,7 +8915,16 @@ function createAgentsClient(transport) {
   return {
     list: (options = {}) => transport().listAgents(agentListQuery(options)),
     retrieve: (agentId) => transport().retrieveAgent(agentId),
-    update: (agentId, options) => transport().updateAgent(agentId, agentUpdateBody(options))
+    update: (agentId, options) => transport().updateAgent(agentId, agentUpdateBody(options)),
+    delete: async (agentId) => {
+      assertNonEmptyId(agentId, "agent id");
+      await transport().deleteAgent(agentId);
+    }
+  };
+}
+function createModelsClient(transport) {
+  return {
+    list: () => transport().listModels()
   };
 }
 function createConversationsClient(transport) {
@@ -8497,6 +9095,7 @@ class LettaAgentClientBase {
   environment;
   agents;
   conversations;
+  models;
   options;
   repositoriesClient = null;
   managementTransport = null;
@@ -8510,6 +9109,7 @@ class LettaAgentClientBase {
     this.options = options;
     this.agents = createAgentsClient(() => this.getManagementTransport());
     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".');
     }
@@ -8528,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.");
@@ -8540,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);
@@ -8554,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
       });
@@ -8577,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,
@@ -8603,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,
@@ -8708,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".');
@@ -8715,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;
@@ -8864,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 } : {
@@ -8876,7 +9492,9 @@ function createLocalAppServerSession(options, mode) {
       })
     },
     ...appServer.WebSocket !== undefined ? { WebSocket: appServer.WebSocket } : {},
-    ...appServer.requestTimeoutMs !== undefined ? { requestTimeoutMs: appServer.requestTimeoutMs } : {}
+    ...appServer.requestTimeoutMs !== undefined ? { requestTimeoutMs: appServer.requestTimeoutMs } : {},
+    ...appServer.pinGlobalAgent !== undefined ? { pinGlobalAgent: appServer.pinGlobalAgent } : {},
+    ...beforeConnect ? { beforeConnect } : {}
   };
   return new AppServerSession(sessionOptions, mode);
 }
@@ -9276,6 +9894,8 @@ class Session {
   _sessionId = null;
   _conversationId = null;
   initialized = false;
+  closed = false;
+  initializePromise = null;
   externalTools = new Map;
   streamQueue = [];
   streamResolvers = [];
@@ -9298,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");
@@ -9325,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())
@@ -9360,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)");
@@ -9861,7 +10513,7 @@ ${stderr}` : "";
       };
     } else if (hasCallback) {
       try {
-        const result = await this.options.canUseTool(toolName, req.input);
+        const result = await this.options.canUseTool(toolName, req.input, buildCanUseToolContext(req, requestId));
         if (result.behavior === "allow") {
           response = {
             behavior: "allow",
@@ -9993,6 +10645,12 @@ ${stderr}` : "";
   async removeQueuedMessage(_itemId) {
     throw new Error("removeQueuedMessage() is not supported by the legacy stdio transport. Use a Cloud, Remote, or local app-server session.");
   }
+  async getDeviceStatus(_options) {
+    throw new Error("getDeviceStatus() is not supported by the legacy stdio transport. Use a Cloud, Remote, or local app-server session.");
+  }
+  onDeviceStatus(_listener) {
+    throw new Error("onDeviceStatus() is not supported by the legacy stdio transport. Use a Cloud, Remote, or local app-server session.");
+  }
   async bootstrapState(options = {}) {
     if (!this.initialized) {
       throw new Error("Session must be initialized before calling bootstrapState()");
@@ -10030,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;
@@ -10227,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) {
@@ -10236,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;
@@ -10254,7 +10916,7 @@ class LettaAgentClient extends LettaAgentClientBase {
         agentId,
         newConversation: true,
         options
-      });
+      }, () => this.releaseIdleManagementConnection());
     }
     if (agentId) {
       return new Session({ ...sessionOptions, agentId, newConversation: true });
@@ -10269,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 });
@@ -10544,4 +11206,4 @@ export {
   CloudManagedSandboxExpiredError
 };
 
-//# debugId=9E81BF84F1BD3BCB64756E2164756E21
+//# debugId=98DBA625B202A81364756E2164756E21