@letta-ai/letta-agent-sdk 0.3.3 → 0.5.1

package/dist/client-entry.js

@@ -244,6 +244,18 @@ class RepositoriesClient {
 }
 
 // node_modules/@letta-ai/letta-code/dist/app-server-client.js
+function isAppServerInfoResponseMessage(message) {
+  if (!message || typeof message !== "object" || Array.isArray(message)) {
+    return false;
+  }
+  const candidate = message;
+  const capabilities = candidate.capabilities;
+  if (!capabilities || typeof capabilities !== "object" || Array.isArray(capabilities)) {
+    return false;
+  }
+  const capabilityRecord = capabilities;
+  return candidate.type === "app_server_info_response" && typeof candidate.request_id === "string" && candidate.request_id.length > 0 && candidate.success === true && (candidate.backend === "local" || candidate.backend === "api") && typeof candidate.letta_code_version === "string" && typeof candidate.protocol_version === "number" && Number.isInteger(candidate.protocol_version) && typeof capabilityRecord.agent_management === "boolean" && typeof capabilityRecord.conversation_management === "boolean" && typeof capabilityRecord.memory_management === "boolean" && typeof capabilityRecord.runtime_start === "boolean" && typeof capabilityRecord.split_channels === "boolean";
+}
 var DEFAULT_REQUEST_TIMEOUT_MS = 30000;
 var WEBSOCKET_OPEN_STATE = 1;
 function getGlobalWebSocket() {
@@ -263,9 +275,9 @@ function normalizeBaseUrl(url) {
   }
   return parsed;
 }
-function resolveAppServerChannelUrl(url, channel) {
+function resolveAppServerUrl(url) {
   const parsed = normalizeBaseUrl(url);
-  parsed.searchParams.set("channel", channel);
+  parsed.searchParams.delete("channel");
   return parsed.toString();
 }
 function attachSocketListener(socket, type, listener) {
@@ -378,6 +390,7 @@ function streamDeltaErrorMessage(message) {
 }
 
 class AppServerClient {
+  socket;
   control;
   stream;
   requestTimeoutMs;
@@ -396,26 +409,18 @@ class AppServerClient {
     }
     this.requestTimeoutMs = options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
     const socketOptions = appServerSocketOptions(options.authToken);
-    this.control = new WebSocket(resolveAppServerChannelUrl(options.url, "control"), socketOptions);
-    this.stream = new WebSocket(resolveAppServerChannelUrl(options.url, "stream"), socketOptions);
-    attachSocketListener(this.control, "message", (event) => {
+    this.socket = new WebSocket(resolveAppServerUrl(options.url), socketOptions);
+    this.control = this.socket;
+    this.stream = this.socket;
+    attachSocketListener(this.socket, "message", (event) => {
       this.handleMessage(event, "control");
     });
-    attachSocketListener(this.stream, "message", (event) => {
-      this.handleMessage(event, "stream");
-    });
-    attachSocketListener(this.control, "close", (event) => {
+    attachSocketListener(this.socket, "close", (event) => {
       this.handleDisconnect("control", event);
     });
-    attachSocketListener(this.stream, "close", (event) => {
-      this.handleDisconnect("stream", event);
-    });
   }
   async connect() {
-    await Promise.all([
-      waitForSocketOpen(this.control),
-      waitForSocketOpen(this.stream)
-    ]);
+    await waitForSocketOpen(this.socket);
     return this;
   }
   close() {
@@ -423,8 +428,7 @@ class AppServerClient {
       return;
     this.explicitlyClosed = true;
     this.rejectAllPending("App-server client closed");
-    this.control.close();
-    this.stream.close();
+    this.socket.close();
   }
   onMessage(handler) {
     this.messageHandlers.add(handler);
@@ -443,10 +447,38 @@ class AppServerClient {
     return `${prefix}-${this.nextRequestNumber}`;
   }
   send(command) {
+    this.writeCommand(command);
+  }
+  writeCommand(command) {
     for (const handler of this.sendHandlers) {
       handler(command);
     }
-    this.control.send(JSON.stringify(command));
+    this.socket.send(JSON.stringify(command));
+  }
+  sendRaw(command) {
+    this.writeCommand(command);
+  }
+  requestRaw(command, options) {
+    const timeoutMs = options.timeoutMs ?? this.requestTimeoutMs;
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        this.pending.delete(command.request_id);
+        reject(new Error(`Timed out waiting for ${command.request_id}`));
+      }, timeoutMs);
+      this.pending.set(command.request_id, {
+        resolve: (message) => resolve(message),
+        reject,
+        predicate: options.predicate,
+        timeout
+      });
+      try {
+        this.sendRaw(command);
+      } catch (error) {
+        clearTimeout(timeout);
+        this.pending.delete(command.request_id);
+        reject(error instanceof Error ? error : new Error(String(error)));
+      }
+    });
   }
   request(commandOrType, bodyOrOptions = {}, maybeOptions = {}) {
     const isTypeRequest = typeof commandOrType === "string";
@@ -477,6 +509,15 @@ class AppServerClient {
       }
     });
   }
+  info(options = {}) {
+    return this.request({
+      type: "app_server_info",
+      request_id: this.nextRequestId("app-server-info")
+    }, {
+      ...options,
+      predicate: isAppServerInfoResponseMessage
+    });
+  }
   runtimeStart(command, options = {}) {
     return this.request({
       type: "runtime_start",
@@ -696,44 +737,6 @@ function applyUniqueRequestIds(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);
@@ -770,15 +773,9 @@ 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");
@@ -845,73 +842,20 @@ 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) {
-    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 {}
+    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;
   }
   acquireConnection() {
     if (this.connectionPromise)
@@ -936,7 +880,6 @@ class AppServerManagementTransport {
     if (!url) {
       throw new Error("App-server management requires a url or connect hook.");
     }
-    const unregister = registerManagementTransport(url, this);
     let client = null;
     try {
       client = applyUniqueRequestIds(createAppServerClient({
@@ -951,29 +894,23 @@ class AppServerManagementTransport {
     } catch (error) {
       try {
         if (client) {
-          const controlClosed = waitForSocketClose(client.control);
           client.close();
           ownedConnection?.close();
-          await controlClosed;
         } else {
           ownedConnection?.close();
         }
-      } catch {} finally {
-        unregister();
-      }
+      } catch {}
       throw error;
     }
     return {
       client,
       ownedConnection,
-      detachDisconnect: () => {},
-      unregister
+      detachDisconnect: () => {}
     };
   }
   discardConnection(promise, connection) {
     if (this.connectionPromise === promise) {
       this.connectionPromise = null;
-      this.clearIdleTimer();
     }
     this.trackClosingConnection(connection);
   }
@@ -983,67 +920,11 @@ class AppServerManagementTransport {
     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();
-  });
+  connection.client.close();
+  connection.ownedConnection?.close();
 }
 
 // node_modules/@letta-ai/letta-code/dist/agent-presets.js
@@ -5950,6 +5831,12 @@ function streamDeltaMessageType2(delta) {
 function streamDeltaRunId2(delta) {
   return typeof delta.run_id === "string" ? delta.run_id : undefined;
 }
+function streamDeltaOtid(delta) {
+  return typeof delta.otid === "string" || delta.otid === null ? delta.otid : undefined;
+}
+function streamDeltaSeqId(delta) {
+  return typeof delta.seq_id === "number" ? delta.seq_id : undefined;
+}
 function streamDeltaStopReason2(delta) {
   return typeof delta.stop_reason === "string" ? delta.stop_reason : undefined;
 }
@@ -6100,6 +5987,7 @@ function toSessionDeviceStatus(status) {
     isProcessing: status.is_processing,
     permissionMode,
     workingDirectory: status.current_working_directory,
+    memoryDirectory: typeof status.memory_directory === "string" ? status.memory_directory : null,
     pendingControlRequests: pendingControlRequests(status),
     raw: { ...status }
   };
@@ -6359,6 +6247,8 @@ class RemoteTurnCoordinator {
   transformStreamDelta(delta) {
     const messageType = typeof delta.message_type === "string" ? delta.message_type : undefined;
     const runId = typeof delta.run_id === "string" ? delta.run_id : undefined;
+    const otid = streamDeltaOtid(delta);
+    const seqId = streamDeltaSeqId(delta);
     const uuid = typeof delta.id === "string" ? delta.id : `${this.label}-${++this.messageCounter}`;
     if (messageType === "assistant_message") {
       const content = extractTextFromContent(delta.content);
@@ -6366,13 +6256,27 @@ class RemoteTurnCoordinator {
         return null;
       if (this.activeTurn)
         this.activeTurn.assistantText += content;
-      return { type: "assistant", content, uuid, runId };
+      return {
+        type: "assistant",
+        content,
+        uuid,
+        ...otid !== undefined ? { otid } : {},
+        ...seqId !== undefined ? { seqId } : {},
+        runId
+      };
     }
     if (messageType === "reasoning_message") {
       const content = typeof delta.reasoning === "string" ? delta.reasoning : extractTextFromContent(delta.content);
       if (!content)
         return null;
-      return { type: "reasoning", content, uuid, runId };
+      return {
+        type: "reasoning",
+        content,
+        uuid,
+        ...otid !== undefined ? { otid } : {},
+        ...seqId !== undefined ? { seqId } : {},
+        runId
+      };
     }
     if (messageType === "tool_call_message" || messageType === "approval_request_message") {
       const toolCall = firstToolCall(delta);
@@ -7075,26 +6979,6 @@ function assertRemoteCreateAgentOptionsSupported(options) {
     throw new Error("App-server createAgent() does not yet support dreaming.behavior overrides.");
   }
 }
-function assertRemoteSessionOptionsSupported(action, options) {
-  if (options.systemPrompt !== undefined) {
-    throw new Error(`App-server ${action}() does not yet support systemPrompt overrides for existing agents.`);
-  }
-  if (options.disallowedTools !== undefined) {
-    throw new Error(`App-server ${action}() does not yet support disallowedTools.`);
-  }
-  if (options.systemInfoReminder !== undefined) {
-    throw new Error(`App-server ${action}() does not yet support systemInfoReminder overrides.`);
-  }
-  if (options.dreaming?.behavior !== undefined) {
-    throw new Error(`App-server ${action}() does not yet support dreaming.behavior overrides.`);
-  }
-  if (options.memfsStartup !== undefined) {
-    throw new Error(`App-server ${action}() does not support memfsStartup.`);
-  }
-  if (options.includePartialMessages !== undefined) {
-    throw new Error(`App-server ${action}() streams app-server deltas directly and does not support includePartialMessages.`);
-  }
-}
 function normalizeMemoryBlock(block) {
   const normalized = { ...block };
   if (normalized.value === undefined && typeof normalized.content === "string") {
@@ -7525,9 +7409,7 @@ class AppServerSession extends RemoteClientSessionCore {
     return options.memfs !== false;
   }
   async initializeRuntimeController() {
-    await this.remoteOptions.beforeConnect?.();
     const url = await this.resolveAppServerUrl();
-    await releaseAppServerManagementConnections(url);
     const client = applyUniqueRequestIds(createAppServerClient({
       url,
       ...this.remoteOptions.authToken !== undefined ? { authToken: this.remoteOptions.authToken } : {},
@@ -7837,6 +7719,222 @@ class CloudManagementTransport {
   }
 }
 
+// src/cloud-status-transport.ts
+var CONNECTING = 0;
+var OPEN = 1;
+var CLOSING = 2;
+var CLOSED = 3;
+var MAX_IDEMPOTENCY_KEYS = 1000;
+function addSocketListener(socket, type, listener) {
+  if (socket.addEventListener) {
+    socket.addEventListener(type, listener);
+    return () => socket.removeEventListener?.(type, listener);
+  }
+  if (socket.on) {
+    socket.on(type, listener);
+    return () => socket.off?.(type, listener);
+  }
+  throw new Error("WebSocket implementation does not support event listeners.");
+}
+function messageEventData(event) {
+  if (typeof event === "string")
+    return event;
+  if (!event || typeof event !== "object")
+    return null;
+  const data = event.data;
+  if (typeof data === "string")
+    return data;
+  if (data instanceof ArrayBuffer) {
+    return new TextDecoder().decode(data);
+  }
+  if (data instanceof Uint8Array) {
+    return new TextDecoder().decode(data);
+  }
+  return null;
+}
+function channelUrl(url, channel) {
+  const parsed = new URL(url);
+  parsed.searchParams.set("channel", channel);
+  return parsed.toString();
+}
+
+class CloudStatusTransport {
+  options;
+  controlSocket;
+  streamSocket;
+  state = CONNECTING;
+  openedChannels = new Set;
+  listeners = new Map;
+  removers = [];
+  seenIdempotencyKeys = new Set;
+  seenIdempotencyOrder = [];
+  lastEventSeq = null;
+  pingTimer = null;
+  closeEmitted = false;
+  constructor(options) {
+    this.options = options;
+    const socketOptions = options.headers ? { headers: options.headers } : undefined;
+    this.controlSocket = new options.WebSocket(channelUrl(options.url, "control"), socketOptions);
+    this.streamSocket = new options.WebSocket(channelUrl(options.url, "stream"), socketOptions);
+    this.bindSocket("control", this.controlSocket);
+    this.bindSocket("stream", this.streamSocket);
+    this.startPing();
+  }
+  get readyState() {
+    return this.state;
+  }
+  send(data) {
+    if (this.state !== OPEN || this.controlSocket.readyState !== OPEN) {
+      throw new Error("Cloud status control socket is not open");
+    }
+    this.controlSocket.send(data);
+  }
+  close() {
+    if (this.state === CLOSED || this.state === CLOSING)
+      return;
+    this.state = CLOSING;
+    this.stopPing();
+    this.closeUnderlyingSockets();
+    this.finishClose({});
+  }
+  addEventListener(type, listener) {
+    let listeners = this.listeners.get(type);
+    if (!listeners) {
+      listeners = new Set;
+      this.listeners.set(type, listeners);
+    }
+    listeners.add(listener);
+  }
+  removeEventListener(type, listener) {
+    this.listeners.get(type)?.delete(listener);
+  }
+  bindSocket(channel, socket) {
+    this.removers.push(addSocketListener(socket, "open", () => {
+      this.openedChannels.add(channel);
+      if (this.openedChannels.size === 2 && this.state === CONNECTING) {
+        this.state = OPEN;
+        this.emit("open", {});
+      }
+    }), addSocketListener(socket, "message", (event) => {
+      if (this.shouldForwardMessage(channel, socket, event)) {
+        this.emit("message", event);
+      }
+    }), addSocketListener(socket, "error", (event) => {
+      this.emit("error", event);
+    }), addSocketListener(socket, "close", (event) => {
+      if (this.state !== CLOSED) {
+        this.state = CLOSING;
+        this.stopPing();
+        this.closeUnderlyingSockets(socket);
+        this.finishClose(event);
+      }
+    }));
+  }
+  shouldForwardMessage(channel, socket, event) {
+    const data = messageEventData(event);
+    if (!data)
+      return true;
+    let message;
+    try {
+      message = JSON.parse(data);
+    } catch {
+      return true;
+    }
+    this.ackIfSequenced(socket, message);
+    if (channel === "control" && message.type === "stream_delta") {
+      return false;
+    }
+    if (this.isDuplicate(message))
+      return false;
+    this.trackEventSequence(message);
+    return true;
+  }
+  ackIfSequenced(socket, message) {
+    if (typeof message.seq !== "number")
+      return;
+    this.sendCommand(socket, { type: "ack", seq: message.seq });
+  }
+  isDuplicate(message) {
+    const key = typeof message.idempotency_key === "string" ? message.idempotency_key : null;
+    if (!key)
+      return false;
+    if (this.seenIdempotencyKeys.has(key))
+      return true;
+    this.seenIdempotencyKeys.add(key);
+    this.seenIdempotencyOrder.push(key);
+    while (this.seenIdempotencyOrder.length > MAX_IDEMPOTENCY_KEYS) {
+      const oldest = this.seenIdempotencyOrder.shift();
+      if (oldest)
+        this.seenIdempotencyKeys.delete(oldest);
+    }
+    return false;
+  }
+  trackEventSequence(message) {
+    if (typeof message.event_seq !== "number")
+      return;
+    if (this.lastEventSeq !== null && message.event_seq > this.lastEventSeq + 1) {
+      this.sendCommand(this.controlSocket, {
+        type: "sync",
+        runtime: this.options.runtime,
+        recover_approvals: true,
+        force_device_status: true
+      });
+    }
+    if (this.lastEventSeq === null || message.event_seq > this.lastEventSeq) {
+      this.lastEventSeq = message.event_seq;
+    }
+  }
+  sendCommand(socket, command) {
+    if (socket.readyState !== OPEN)
+      return;
+    try {
+      socket.send(JSON.stringify(command));
+    } catch {}
+  }
+  startPing() {
+    this.pingTimer = setInterval(() => {
+      this.sendCommand(this.controlSocket, { type: "ping" });
+      this.sendCommand(this.streamSocket, { type: "ping" });
+    }, this.options.pingIntervalMs);
+    this.pingTimer.unref?.();
+  }
+  stopPing() {
+    if (!this.pingTimer)
+      return;
+    clearInterval(this.pingTimer);
+    this.pingTimer = null;
+  }
+  closeUnderlyingSockets(except) {
+    for (const socket of [this.controlSocket, this.streamSocket]) {
+      if (socket !== except && (socket.readyState === CONNECTING || socket.readyState === OPEN)) {
+        socket.close();
+      }
+    }
+  }
+  finishClose(event) {
+    if (this.closeEmitted)
+      return;
+    this.closeEmitted = true;
+    this.state = CLOSED;
+    this.stopPing();
+    for (const remove of this.removers.splice(0))
+      remove();
+    this.emit("close", event);
+  }
+  emit(type, event) {
+    for (const listener of this.listeners.get(type) ?? []) {
+      listener(event);
+    }
+  }
+}
+function createCloudStatusTransportConstructor(options) {
+  return class CloudStatusTransportSocket extends CloudStatusTransport {
+    constructor(_url, _socketOptions) {
+      super(options);
+    }
+  };
+}
+
 // src/remote.ts
 function getDefaultApiKey2() {
   if (typeof process === "undefined") {
@@ -8145,191 +8243,6 @@ function buildCloudStatusWebSocketUrl(params) {
   }
   return base.toString();
 }
-function addSocketListener(socket, type, listener) {
-  if (socket.addEventListener) {
-    socket.addEventListener(type, listener);
-    return () => socket.removeEventListener?.(type, listener);
-  }
-  if (socket.on) {
-    socket.on(type, listener);
-    return () => socket.off?.(type, listener);
-  }
-  throw new Error("WebSocket implementation does not support event listeners.");
-}
-function messageEventData(event) {
-  if (typeof event === "string")
-    return event;
-  if (event && typeof event === "object") {
-    const data = event.data;
-    if (typeof data === "string")
-      return data;
-    if (data instanceof ArrayBuffer) {
-      return new TextDecoder().decode(data);
-    }
-    if (data instanceof Uint8Array) {
-      return new TextDecoder().decode(data);
-    }
-  }
-  return null;
-}
-function createCloudStatusWebSocketConstructor(params) {
-  const WebSocketCtor = getWebSocketConstructor(params.cloudOptions.WebSocket);
-  const authMode = params.cloudOptions.webSocketAuth ?? "header";
-  const cloudHeaders3 = authMode === "header" ? cloudWebSocketHeaders(params.cloudOptions) : undefined;
-  const pingIntervalMs = params.cloudOptions.pingIntervalMs ?? DEFAULT_PING_INTERVAL_MS;
-  const state = {
-    runtime: params.runtime,
-    seenIdempotencyKeys: new Set,
-    seenIdempotencyOrder: [],
-    lastEventSeq: null,
-    controlSocket: null
-  };
-
-  class CloudStatusSocketAdapter {
-    socket;
-    channel;
-    listenerRemovers = new Map;
-    pingTimer = null;
-    removeCloseListener = null;
-    constructor(url, options) {
-      this.channel = new URL(url).searchParams.get("channel");
-      const mergedHeaders = authMode === "header" ? {
-        ...options?.headers ?? {},
-        ...cloudHeaders3 ?? {}
-      } : undefined;
-      const socketOptions = mergedHeaders && Object.keys(mergedHeaders).length > 0 ? { headers: mergedHeaders } : undefined;
-      this.socket = new WebSocketCtor(url, socketOptions);
-      if (this.channel === "control") {
-        state.controlSocket = this;
-      }
-      this.removeCloseListener = addSocketListener(this.socket, "close", () => {
-        this.stopPing();
-        if (state.controlSocket === this)
-          state.controlSocket = null;
-      });
-      this.startPing(pingIntervalMs);
-    }
-    get readyState() {
-      return this.socket.readyState;
-    }
-    send(data) {
-      this.socket.send(data);
-    }
-    close() {
-      this.stopPing();
-      this.removeCloseListener?.();
-      this.removeCloseListener = null;
-      if (state.controlSocket === this)
-        state.controlSocket = null;
-      this.socket.close();
-    }
-    addEventListener(type, listener) {
-      const wrapped = type === "message" ? (event) => {
-        if (this.handleIncomingMessage(event)) {
-          listener(event);
-        }
-      } : listener;
-      const remove = addSocketListener(this.socket, type, wrapped);
-      let typeRemovers = this.listenerRemovers.get(type);
-      if (!typeRemovers) {
-        typeRemovers = new Map;
-        this.listenerRemovers.set(type, typeRemovers);
-      }
-      typeRemovers.set(listener, remove);
-    }
-    removeEventListener(type, listener) {
-      const typeRemovers = this.listenerRemovers.get(type);
-      const remove = typeRemovers?.get(listener);
-      if (!remove)
-        return;
-      remove();
-      typeRemovers?.delete(listener);
-      if (typeRemovers?.size === 0) {
-        this.listenerRemovers.delete(type);
-      }
-    }
-    handleIncomingMessage(event) {
-      const data = messageEventData(event);
-      if (!data)
-        return true;
-      let message;
-      try {
-        message = JSON.parse(data);
-      } catch {
-        return true;
-      }
-      this.ackIfSequenced(message);
-      if (this.channel === "control" && message.type === "stream_delta") {
-        return false;
-      }
-      if (this.isDuplicate(message))
-        return false;
-      this.trackEventSeq(message);
-      return true;
-    }
-    ackIfSequenced(message) {
-      if (typeof message.seq !== "number")
-        return;
-      this.sendCloudCommand({ type: "ack", seq: message.seq });
-    }
-    isDuplicate(message) {
-      const idempotencyKey = typeof message.idempotency_key === "string" ? message.idempotency_key : undefined;
-      if (!idempotencyKey)
-        return false;
-      if (state.seenIdempotencyKeys.has(idempotencyKey))
-        return true;
-      state.seenIdempotencyKeys.add(idempotencyKey);
-      state.seenIdempotencyOrder.push(idempotencyKey);
-      while (state.seenIdempotencyOrder.length > 1000) {
-        const oldest = state.seenIdempotencyOrder.shift();
-        if (oldest)
-          state.seenIdempotencyKeys.delete(oldest);
-      }
-      return false;
-    }
-    trackEventSeq(message) {
-      if (typeof message.event_seq !== "number")
-        return;
-      if (state.lastEventSeq !== null && message.event_seq > state.lastEventSeq + 1) {
-        this.sendSync(true);
-      }
-      if (state.lastEventSeq === null || message.event_seq > state.lastEventSeq) {
-        state.lastEventSeq = message.event_seq;
-      }
-    }
-    sendSync(recoverApprovals) {
-      const target = state.controlSocket?.readyState === 1 ? state.controlSocket : this;
-      target.sendCloudCommand({
-        type: "sync",
-        runtime: state.runtime,
-        recover_approvals: recoverApprovals,
-        force_device_status: true
-      });
-    }
-    sendCloudCommand(command) {
-      if (this.readyState !== 1)
-        return;
-      try {
-        this.socket.send(JSON.stringify(command));
-      } catch {}
-    }
-    startPing(intervalMs) {
-      if (this.pingTimer)
-        return;
-      this.pingTimer = setInterval(() => {
-        this.sendCloudCommand({ type: "ping" });
-      }, intervalMs);
-      this.pingTimer.unref?.();
-    }
-    stopPing() {
-      if (!this.pingTimer)
-        return;
-      clearInterval(this.pingTimer);
-      this.pingTimer = null;
-    }
-  }
-  return CloudStatusSocketAdapter;
-}
 function isCloudConversation(value) {
   return Boolean(value && typeof value === "object" && typeof value.id === "string");
 }
@@ -8373,24 +8286,6 @@ function assertCloudSessionOptionsSupported(action, options) {
   if (options.environment !== undefined && options.sandbox !== undefined) {
     throw new Error(`Letta Cloud ${action}() cannot specify both environment and sandbox options.`);
   }
-  if (options.systemPrompt !== undefined) {
-    throw new Error(`Letta Cloud ${action}() cannot rewrite an existing agent's systemPrompt from the SDK adapter yet.`);
-  }
-  if (options.disallowedTools !== undefined) {
-    throw new Error(`Letta Cloud ${action}() has not wired disallowedTools to the remote device protocol yet.`);
-  }
-  if (options.systemInfoReminder !== undefined) {
-    throw new Error(`Letta Cloud ${action}() has not wired systemInfoReminder to the remote device protocol yet.`);
-  }
-  if (options.dreaming?.behavior !== undefined) {
-    throw new Error(`Letta Cloud ${action}() does not yet support dreaming.behavior overrides.`);
-  }
-  if (options.memfsStartup !== undefined) {
-    throw new Error(`Letta Cloud ${action}() does not support memfsStartup.`);
-  }
-  if (options.includePartialMessages !== undefined) {
-    throw new Error(`Letta Cloud ${action}() streams Remote Client deltas directly; includePartialMessages is not a separate toggle.`);
-  }
 }
 
 class CloudEnvironmentSession extends RemoteClientSessionCore {
@@ -8404,6 +8299,7 @@ class CloudEnvironmentSession extends RemoteClientSessionCore {
   sandboxRefreshInFlight = null;
   sandboxLifecycleClosing = false;
   attachedRepositoryIds = new Set;
+  repositoryIdsRequiringCleanupRecompile = new Set;
   cloudMode;
   constructor(cloudOptions, mode) {
     super(mode, {
@@ -8417,7 +8313,10 @@ class CloudEnvironmentSession extends RemoteClientSessionCore {
   }
   async initializeRuntimeController() {
     const resolved = await this.resolveRuntime();
-    const connection = await this.resolveConnectionForRuntime(resolved.runtime);
+    const connection = await this.resolveConnectionForRuntime(resolved.runtime).catch(async (error) => {
+      await this.cleanupSessionRepositories(resolved.runtime.agent_id, resolved.runtime.conversation_id);
+      throw error;
+    });
     this.connectionId = connection.connectionId;
     const apiKey = getCloudApiKey2(this.cloudOptions);
     const url = buildCloudStatusWebSocketUrl({
@@ -8430,8 +8329,11 @@ class CloudEnvironmentSession extends RemoteClientSessionCore {
     });
     const client = applyUniqueRequestIds(createAppServerClient({
       url,
-      WebSocket: createCloudStatusWebSocketConstructor({
-        cloudOptions: this.cloudOptions,
+      WebSocket: createCloudStatusTransportConstructor({
+        url,
+        WebSocket: getWebSocketConstructor(this.cloudOptions.WebSocket),
+        ...(this.cloudOptions.webSocketAuth ?? "header") === "header" ? { headers: cloudWebSocketHeaders(this.cloudOptions) } : {},
+        pingIntervalMs: this.cloudOptions.pingIntervalMs ?? DEFAULT_PING_INTERVAL_MS,
         runtime: resolved.runtime
       }),
       requestTimeoutMs: this.cloudOptions.requestTimeoutMs ?? DEFAULT_TURN_TIMEOUT_MS
@@ -8469,7 +8371,7 @@ class CloudEnvironmentSession extends RemoteClientSessionCore {
       this.removeControlRequestHandler = null;
       client.close();
       await this.cleanupManagedSandbox();
-      await this.cleanupSessionRepositories(resolved.runtime.agent_id);
+      await this.cleanupSessionRepositories(resolved.runtime.agent_id, resolved.runtime.conversation_id);
       throw error;
     }
   }
@@ -8520,8 +8422,9 @@ class CloudEnvironmentSession extends RemoteClientSessionCore {
     this.removeControlRequestHandler?.();
     this.removeControlRequestHandler = null;
     this.cleanupManagedSandbox();
-    if (this.runtime?.agent_id)
-      this.cleanupSessionRepositories(this.runtime.agent_id);
+    if (this.runtime?.agent_id) {
+      this.cleanupSessionRepositories(this.runtime.agent_id, this.runtime.conversation_id);
+    }
   }
   async resolveRuntime() {
     let agentId = this.cloudMode.agentId;
@@ -8536,22 +8439,30 @@ class CloudEnvironmentSession extends RemoteClientSessionCore {
     if (!agentId) {
       throw new Error("Letta Cloud createSession()/resumeSession() requires an agent id or conversation id.");
     }
-    await this.attachSessionRepositories(agentId);
-    if (this.cloudMode.newConversation) {
-      const conversation = await this.createConversation(agentId);
-      conversationId = conversation.id;
-    } else if (this.cloudMode.defaultConversation) {
-      conversationId = "default";
-    }
-    if (!conversationId) {
-      throw new Error("Letta Cloud createSession()/resumeSession() requires an agent id or conversation id.");
+    const shouldRecompileRepositories = await this.attachSessionRepositories(agentId);
+    try {
+      if (this.cloudMode.newConversation) {
+        const conversation = await this.createConversation(agentId);
+        conversationId = conversation.id;
+      } else if (this.cloudMode.defaultConversation) {
+        conversationId = "default";
+      }
+      if (!conversationId) {
+        throw new Error("Letta Cloud createSession()/resumeSession() requires an agent id or conversation id.");
+      }
+      if (shouldRecompileRepositories) {
+        await this.recompileSystemPrompt(agentId, conversationId);
+      }
+      return { runtime: { agent_id: agentId, conversation_id: conversationId } };
+    } catch (error) {
+      await this.cleanupSessionRepositories(agentId, conversationId);
+      throw error;
     }
-    return { runtime: { agent_id: agentId, conversation_id: conversationId } };
   }
   async attachSessionRepositories(agentId) {
     const resources = this.repositoryResources();
     if (resources.length === 0)
-      return;
+      return false;
     const existing = await this.listAgentRepositories(agentId);
     const existingIds = new Set(existing.map((repository) => repository.id));
     try {
@@ -8567,15 +8478,42 @@ class CloudEnvironmentSession extends RemoteClientSessionCore {
       await this.cleanupSessionRepositories(agentId);
       throw error;
     }
+    const shouldRecompile = resources.some((resource) => resource.recompile !== false);
+    this.repositoryIdsRequiringCleanupRecompile = new Set(resources.filter((resource) => resource.recompile !== false && this.attachedRepositoryIds.has(resource.repositoryId)).map((resource) => resource.repositoryId));
+    return shouldRecompile;
   }
-  async cleanupSessionRepositories(agentId) {
+  async cleanupSessionRepositories(agentId, conversationId) {
     const repositoryIds = [...this.attachedRepositoryIds];
+    const repositoryIdsRequiringRecompile = this.repositoryIdsRequiringCleanupRecompile;
     this.attachedRepositoryIds.clear();
-    await Promise.all(repositoryIds.map(async (repositoryId) => {
+    this.repositoryIdsRequiringCleanupRecompile = new Set;
+    const recompileAfterDetach = await Promise.all(repositoryIds.map(async (repositoryId) => {
       try {
         await this.unlinkAgentRepository(agentId, repositoryId);
-      } catch {}
+        return repositoryIdsRequiringRecompile.has(repositoryId);
+      } catch {
+        return false;
+      }
     }));
+    if (recompileAfterDetach.some(Boolean)) {
+      try {
+        await this.recompileSystemPrompt(agentId, conversationId);
+      } catch {}
+    }
+  }
+  async recompileSystemPrompt(agentId, conversationId) {
+    const fetchImpl = getFetch3(this.cloudOptions.fetch);
+    const baseUrl = normalizeCloudApiBaseUrl2(this.cloudOptions.apiBaseUrl);
+    const usesAgentPrompt = !conversationId || conversationId === "default";
+    const path = usesAgentPrompt ? `/v1/agents/${encodeURIComponent(agentId)}/recompile` : `/v1/conversations/${encodeURIComponent(conversationId)}/recompile`;
+    const url = `${baseUrl}${path}`;
+    const response = await fetchImpl(url, {
+      method: "POST",
+      headers: cloudHeaders2(this.cloudOptions),
+      body: JSON.stringify(usesAgentPrompt ? {} : { agent_id: agentId })
+    });
+    const body = await parseJsonResponse3(response);
+    assertOkResponse2(response, body, "Cloud recompile system prompt", url);
   }
   repositoryResources() {
     const resources = this.cloudMode.options.resources ?? [];
@@ -9019,7 +8957,23 @@ function validateApprovalRecoveryOptions(options) {
   }
 }
 function validateRemovedSessionOptions(options) {
-  if (options.memfsStartup !== undefined) {
+  const removedOptions = options;
+  if (removedOptions.systemPrompt !== undefined) {
+    throw new Error("systemPrompt is not supported when opening an existing agent session.");
+  }
+  if (removedOptions.disallowedTools !== undefined) {
+    throw new Error("disallowedTools is not supported when opening an existing agent session.");
+  }
+  if (removedOptions.systemInfoReminder !== undefined) {
+    throw new Error("systemInfoReminder is not supported when opening an existing agent session.");
+  }
+  if (removedOptions.includePartialMessages !== undefined) {
+    throw new Error("includePartialMessages is not supported by app-server sessions.");
+  }
+  if (options.dreaming && "behavior" in options.dreaming && options.dreaming.behavior !== undefined) {
+    throw new Error("dreaming.behavior is not supported when opening an existing agent session.");
+  }
+  if (removedOptions.memfsStartup !== undefined) {
     throw new Error("memfsStartup is not supported by the SDK.");
   }
 }
@@ -9069,9 +9023,6 @@ function validateReasoningEffort(value) {
   }
 }
 function validateCreateSessionOptions(options) {
-  if (options.systemPrompt !== undefined) {
-    validateSystemPromptPreset(options.systemPrompt);
-  }
   validateSkillSources(options.skillSources);
   validateReasoningEffort(options.reasoningEffort);
   validateDreamingOptions(options.dreaming);
@@ -9127,6 +9078,7 @@ function stripCloudExecutionOptions(options) {
   const sessionOptions = { ...options };
   delete sessionOptions.environment;
   delete sessionOptions.sandbox;
+  delete sessionOptions.filesystemConfinement;
   return sessionOptions;
 }
 function hasRepositoryResources(options) {
@@ -9170,17 +9122,13 @@ class LettaAgentClientBase {
     }
     if (this.backend === "local") {
       const localOptions = options;
-      if (localOptions.transport !== undefined && localOptions.transport !== "app-server" && localOptions.transport !== "stdio") {
-        throw new Error("Invalid local transport. Valid values: app-server, stdio.");
+      if ("transport" in localOptions) {
+        throw new Error("Local transport selection has been removed. The local backend always uses the app-server protocol.");
       }
       const requestTimeoutMs = localOptions.appServer?.requestTimeoutMs;
       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.");
@@ -9193,9 +9141,6 @@ 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);
@@ -9223,40 +9168,35 @@ class LettaAgentClientBase {
     }
     return this.createLocalAgent(options);
   }
-  createSession(agentIdOrOptions, options = {}) {
-    const agentId = typeof agentIdOrOptions === "string" ? agentIdOrOptions : undefined;
-    const resolvedOptions = typeof agentIdOrOptions === "string" ? options : agentIdOrOptions ?? {};
-    this.assertSessionBackend("createSession", resolvedOptions);
-    const sessionOptions = stripCloudExecutionOptions(resolvedOptions);
+  createSession(agentId, options = {}) {
+    if (typeof agentId !== "string" || agentId.length === 0) {
+      throw new Error("createSession() requires a non-empty agent id.");
+    }
+    const sessionOptions = stripCloudExecutionOptions(options);
     validateCreateSessionOptions(sessionOptions);
+    this.assertSessionBackend("createSession", options);
     if (this.backend === "remote") {
-      if (!agentId) {
-        throw new Error("App-server createSession() requires an agent id. Call createAgent() first or pass an agent id.");
-      }
       return new AppServerSession(this.appServerSessionOptions(), {
         kind: "session",
         agentId,
         newConversation: true,
-        options: resolvedOptions
+        options
       });
     }
     if (this.backend === "cloud") {
-      if (!agentId) {
-        throw new Error("Letta Cloud createSession() requires an agent id. Call createAgent() first or pass an agent id.");
-      }
       return new CloudEnvironmentSession(this.cloudOptions(), {
         kind: "session",
         agentId,
         newConversation: true,
-        options: resolvedOptions
+        options
       });
     }
-    return this.createLocalSession(agentId, resolvedOptions, sessionOptions);
+    return this.createLocalSession(agentId, options);
   }
   resumeSession(id, options = {}) {
-    this.assertSessionBackend("resumeSession", options);
     const sessionOptions = stripCloudExecutionOptions(options);
     validateCreateSessionOptions(sessionOptions);
+    this.assertSessionBackend("resumeSession", options);
     if (this.backend === "remote") {
       if (looksLikeConversationId(id)) {
         return new AppServerSession(this.appServerSessionOptions(), {
@@ -9287,10 +9227,10 @@ class LettaAgentClientBase {
         options
       });
     }
-    return this.resumeLocalSession(id, options, sessionOptions);
+    return this.resumeLocalSession(id, options);
   }
   async prompt(message, agentId, options = {}) {
-    const session = agentId ? this.createSession(agentId, options) : this.createSession(options);
+    const session = this.createSession(agentId, options);
     try {
       return await session.runTurn(message);
     } finally {
@@ -9298,6 +9238,9 @@ class LettaAgentClientBase {
     }
   }
   assertSessionBackend(action, options) {
+    if (options.filesystemConfinement !== undefined && options.filesystemConfinement !== "memory") {
+      throw new Error(`Invalid filesystemConfinement '${String(options.filesystemConfinement)}'. Valid value: memory.`);
+    }
     const effectiveEnvironment = options.environment ?? this.environment;
     if (this.backend === "local") {
       if (effectiveEnvironment !== undefined) {
@@ -9309,12 +9252,18 @@ class LettaAgentClientBase {
       if (hasRepositoryResources(options)) {
         throw new Error(`${action}() repository resources are only valid with backend: "cloud".`);
       }
-      if (!this.useLegacyLocalStdio()) {
-        assertRemoteSessionOptionsSupported(action, options);
+      if (options.filesystemConfinement !== undefined) {
+        const localOptions = this.options;
+        if (localOptions.appServer?.url !== undefined) {
+          throw new Error(`${action}() filesystemConfinement requires an SDK-owned local app-server process.`);
+        }
       }
       return;
     }
     if (this.backend === "remote") {
+      if (options.filesystemConfinement !== undefined) {
+        throw new Error(`${action}() filesystemConfinement requires an SDK-owned local app-server process.`);
+      }
       if (options.environment !== undefined) {
         throw new Error(`${action}() environment overrides are only valid with backend: "cloud"; remote url selects the app-server runtime.`);
       }
@@ -9324,10 +9273,12 @@ class LettaAgentClientBase {
       if (hasRepositoryResources(options)) {
         throw new Error(`${action}() repository resources are only valid with backend: "cloud".`);
       }
-      assertRemoteSessionOptionsSupported(action, options);
       return;
     }
     if (this.backend === "cloud") {
+      if (options.filesystemConfinement !== undefined) {
+        throw new Error(`${action}() filesystemConfinement is only supported with backend: "local".`);
+      }
       const cloudOptions = this.cloudOptions();
       if (cloudOptions.environment !== undefined && options.sandbox !== undefined) {
         throw new Error(`Letta Cloud ${action}() cannot specify sandbox options when the client has a default environment.`);
@@ -9340,16 +9291,13 @@ class LettaAgentClientBase {
     }
     throw new Error(`LettaAgentClient backend '${this.backend}' is not implemented yet. ${action} currently supports backend 'local' only.`);
   }
-  useLegacyLocalStdio() {
-    return this.options.transport === "stdio";
-  }
   createLocalAgent(_options) {
     throw this.localBackendUnavailableError();
   }
-  createLocalSession(_agentId, _options, _sessionOptions) {
+  createLocalSession(_agentId, _options) {
     throw this.localBackendUnavailableError();
   }
-  resumeLocalSession(_id, _options, _sessionOptions) {
+  resumeLocalSession(_id, _options) {
     throw this.localBackendUnavailableError();
   }
   localBackendUnavailableError() {
@@ -9365,10 +9313,7 @@ class LettaAgentClientBase {
     return this.options;
   }
   appServerSessionOptions() {
-    return {
-      ...this.remoteOptions(),
-      beforeConnect: () => this.releaseIdleManagementConnection()
-    };
+    return this.remoteOptions();
   }
   getRepositoriesClient() {
     if (this.backend !== "cloud") {
@@ -9377,9 +9322,6 @@ class LettaAgentClientBase {
     this.repositoriesClient ??= new RepositoriesClient(this.cloudOptions());
     return this.repositoriesClient;
   }
-  async releaseIdleManagementConnection() {
-    await this.managementTransport?.releaseIdleConnection?.();
-  }
   getManagementTransport() {
     if (this.managementTransport)
       return this.managementTransport;
@@ -9487,4 +9429,4 @@ export {
   CloudManagedSandboxExpiredError
 };
 
-//# debugId=0186899B952456A764756E2164756E21
+//# debugId=C4A49597208F4A6464756E2164756E21