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

package/dist/index.js

@@ -1,3 +1,4 @@
+// Generated bundle. Canonical modules are published under src/ and maintained in the letta-agent-sdk repository.
 import { createRequire } from "node:module";
 var __create = Object.create;
 var __getProtoOf = Object.getPrototypeOf;
@@ -701,7 +702,56 @@ function createAppServerClient(options) {
   return new AppServerClient(options);
 }
 
+// src/request-ids.ts
+var processRequestCounter = 0;
+function createRequestIdGenerator() {
+  const nonce = Math.random().toString(36).slice(2, 10);
+  return (prefix = "req") => `${prefix}-${nonce}-${++processRequestCounter}`;
+}
+function applyUniqueRequestIds(client) {
+  client.nextRequestId = createRequestIdGenerator();
+  return client;
+}
+
 // src/app-server-management.ts
+var DEFAULT_IDLE_LINGER_MS = 250;
+var registeredTransportsByUrl = new Map;
+function appServerUrlKey(value) {
+  try {
+    const url = new URL(value);
+    if (url.protocol === "http:")
+      url.protocol = "ws:";
+    if (url.protocol === "https:")
+      url.protocol = "wss:";
+    url.hash = "";
+    url.searchParams.delete("channel");
+    return url.toString();
+  } catch {
+    return value;
+  }
+}
+function registerManagementTransport(url, transport) {
+  const key = appServerUrlKey(url);
+  const registration = { transport };
+  const transports = registeredTransportsByUrl.get(key) ?? new Set;
+  transports.add(registration);
+  registeredTransportsByUrl.set(key, transports);
+  return () => {
+    transports.delete(registration);
+    if (transports.size === 0) {
+      registeredTransportsByUrl.delete(key);
+    }
+  };
+}
+async function releaseAppServerManagementConnections(url) {
+  const key = appServerUrlKey(url);
+  while (true) {
+    const transports = [...registeredTransportsByUrl.get(key) ?? []];
+    if (transports.length === 0)
+      return;
+    await Promise.all(transports.map(({ transport }) => transport.releaseIdleConnection()));
+  }
+}
 function ensureResponse(response, value, fallback) {
   if (!response.success || value == null) {
     throw new Error(response.error ?? fallback);
@@ -737,8 +787,16 @@ function stringRecord(value) {
 
 class AppServerManagementTransport {
   options;
+  connectionPromise = null;
+  releasePromise = null;
+  closingConnections = new Set;
+  inFlightRequests = 0;
+  idleWaiters = new Set;
+  idleTimer = null;
+  idleLingerMs;
   constructor(options) {
     this.options = options;
+    this.idleLingerMs = options.idleLingerMs ?? DEFAULT_IDLE_LINGER_MS;
   }
   async listAgents(query) {
     const response = await this.request("agent_list", { query }, "agent_list_response");
@@ -805,38 +863,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";
@@ -5505,7 +5731,7 @@ function buildCanUseToolContext(request, requestId) {
   return context;
 }
 
-// src/remote-client-session-core.ts
+// src/remote-session-protocol.ts
 var FAILURE_STOP_REASONS = new Set([
   "error",
   "llm_api_error",
@@ -5900,856 +6126,930 @@ function normalizeSendMessage(message) {
   return message;
 }
 
-class RemoteClientSessionCore {
-  mode;
-  controller = null;
-  runtime = null;
-  initialized = false;
-  closed = false;
-  activeTurnStartedAt = 0;
-  _agentId = null;
-  _sessionId = null;
-  _conversationId = null;
-  _model = "";
-  _modelSettings = null;
+// src/remote-turn-coordinator.ts
+class RemoteTurnCoordinator {
   label;
   requestTimeoutMs;
+  onDeviceStatus;
   streamQueue = [];
   streamResolvers = [];
-  removeMessageHandler = null;
   activeTurn = null;
   pendingTurns = [];
   nextTurnId = 0;
   messageCounter = 0;
   clientMessageCounter = 0;
-  toolNames;
-  deviceStatusListeners = new Set;
-  deviceStatusRefreshCancels = new Set;
-  constructor(mode, config) {
-    this.mode = mode;
+  closed = false;
+  _activeTurnStartedAt = 0;
+  constructor(config) {
     this.label = config.label;
     this.requestTimeoutMs = config.requestTimeoutMs;
+    this.onDeviceStatus = config.onDeviceStatus;
   }
-  async initialize() {
-    if (this.initialized) {
-      throw new Error("Session already initialized");
-    }
-    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;
-    }
+  get activeTurnStartedAt() {
+    return this._activeTurnStartedAt;
   }
-  async send(message) {
-    if (!this.initialized) {
-      await this.initialize();
-    }
-    if (!this.controller || !this.runtime) {
-      throw new Error("Session is not initialized");
-    }
-    await this.beforeTurn();
-    const turn = this.trackSentTurn(this.runtime);
-    try {
-      this.controller.sendTurnMessage(this.runtime, message, {
-        clientMessageId: turn.clientMessageId
-      });
-    } catch (error) {
-      this.removeTrackedTurn(turn);
-      throw error;
-    }
+  hasInFlightTurn() {
+    return this.activeTurn !== null || this.pendingTurns.length > 0;
   }
-  async runTurn(message, _options = {}) {
-    if (this.activeTurn || this.pendingTurns.length > 0) {
-      throw new Error(`A turn is already in flight for this ${this.label} session. Use send() and stream() to let the listener queue messages.`);
-    }
-    await this.send(message);
-    for await (const msg of this.stream()) {
-      if (msg.type === "result") {
-        return msg;
-      }
-    }
-    return {
-      type: "result",
-      success: false,
-      error: "stream_closed",
-      errorCode: "stream_closed",
-      recoverable: false,
-      errorDetail: "Stream ended before terminal result",
-      durationMs: Date.now() - this.activeTurnStartedAt,
-      conversationId: this._conversationId
+  trackSentTurn(runtime) {
+    const turn = {
+      id: ++this.nextTurnId,
+      runtime,
+      clientMessageId: `sdk-message-${Date.now()}-${++this.clientMessageCounter}`,
+      queuedAt: Date.now(),
+      startedAt: 0,
+      assistantText: "",
+      runIds: new Set,
+      observedTurnEvidence: false,
+      observedRequiresApprovalStop: false,
+      abortRequested: false,
+      timeout: null
     };
-  }
-  async* stream() {
-    while (true) {
-      const msg = await this.nextMessage();
-      if (!msg)
-        break;
-      yield msg;
-      if (msg.type === "result")
-        break;
+    if (this.activeTurn) {
+      this.pendingTurns.push(turn);
+    } else {
+      this.activateTurn(turn);
     }
+    return turn;
   }
-  async abort() {
-    if (!this.initialized)
-      return;
-    if (!this.controller || !this.runtime)
+  removeTrackedTurn(turn) {
+    if (turn.timeout)
+      clearTimeout(turn.timeout);
+    if (this.activeTurn === turn) {
+      this.activeTurn = null;
       return;
+    }
+    const index = this.pendingTurns.indexOf(turn);
+    if (index !== -1)
+      this.pendingTurns.splice(index, 1);
+  }
+  markAbortRequested() {
     if (this.activeTurn)
       this.activeTurn.abortRequested = true;
-    await this.controller.abort(this.runtime);
   }
-  async sendCommand(command, options) {
-    if (!this.initialized) {
-      await this.initialize();
-    }
-    if (!this.controller) {
-      throw new Error("Session is not initialized");
+  handleProtocolMessage(message, runtime) {
+    if (!sameRuntime2(message, runtime))
+      return;
+    const statusRecord = deviceStatusRecord(message);
+    if (statusRecord) {
+      const status = toSessionDeviceStatus(statusRecord);
+      if (status)
+        this.onDeviceStatus(status);
+      return;
     }
-    if (!command || typeof command !== "object" || Array.isArray(command)) {
-      throw new Error("Invalid command. Expected a protocol command object.");
+    if (message.type === "update_queue") {
+      const sdkMessage2 = {
+        type: "queue_update",
+        queue: queueItems(message)
+      };
+      this.enqueue(sdkMessage2);
+      return;
     }
-    if (typeof command.type !== "string" || command.type.length === 0) {
-      throw new Error("Invalid command. Expected a non-empty type.");
+    if (message.type === "update_loop_status") {
+      this.handleLoopStatusMessage(message);
+      return;
     }
-    if (!options || !options.responseType && !options.predicate && options.timeoutMs === undefined) {
-      this.controller.send(command);
+    const delta = streamDeltaRecord(message);
+    if (!delta)
       return;
+    const active = this.activateNextTurnFromProtocol();
+    if (active) {
+      active.observedTurnEvidence = true;
+      const runId = streamDeltaRunId2(delta);
+      if (runId)
+        active.runIds.add(runId);
     }
-    const { type, ...body } = command;
-    const response = await this.controller.request(type, body, {
-      ...options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {},
-      predicate: options.predicate ? (message) => options.predicate?.(message) === true : options.responseType ? (message) => message.type === options.responseType : undefined
-    });
-    return response;
+    const sdkMessage = this.transformStreamDelta(delta);
+    if (sdkMessage)
+      this.enqueue(sdkMessage);
+    this.handleTurnTerminalDelta(delta, sdkMessage);
   }
-  async listModels() {
-    if (!this.initialized) {
-      await this.initialize();
-    }
-    if (!this.controller) {
-      throw new Error("Session is not initialized");
-    }
-    return this.controller.listModels();
+  nextMessage() {
+    const next = this.streamQueue.shift();
+    if (next)
+      return Promise.resolve(next);
+    if (this.closed)
+      return Promise.resolve(null);
+    return new Promise((resolve) => {
+      this.streamResolvers.push(resolve);
+    });
   }
-  async updateModel(update) {
-    if (!this.initialized) {
-      await this.initialize();
+  close() {
+    if (this.closed)
+      return;
+    this.closed = true;
+    if (this.activeTurn?.timeout)
+      clearTimeout(this.activeTurn.timeout);
+    for (const turn of this.pendingTurns) {
+      if (turn.timeout)
+        clearTimeout(turn.timeout);
+    }
+    this.activeTurn = null;
+    this.pendingTurns.length = 0;
+    this.resolveAll(null);
+  }
+  activateTurn(turn) {
+    this.activeTurn = turn;
+    turn.startedAt = Date.now();
+    this._activeTurnStartedAt = turn.startedAt;
+    if (this.requestTimeoutMs !== undefined) {
+      turn.timeout = setTimeout(() => {
+        this.failTurn(turn, `Timed out waiting for ${this.label} turn`);
+      }, this.requestTimeoutMs);
+      turn.timeout.unref?.();
+    }
+  }
+  activateNextTurnFromProtocol() {
+    if (this.activeTurn)
+      return this.activeTurn;
+    const next = this.pendingTurns.shift();
+    if (!next)
+      return null;
+    this.activateTurn(next);
+    return next;
+  }
+  failTurn(turn, detail) {
+    if (this.activeTurn !== turn)
+      return;
+    this.enqueue({
+      type: "error",
+      message: detail,
+      errorCode: "error",
+      stopReason: "error",
+      errorDetail: detail,
+      recoverable: false
+    });
+    this.completeActiveTurn({
+      runtime: turn.runtime,
+      stopReason: "error",
+      runIds: [...turn.runIds],
+      success: false,
+      detail,
+      errorCode: "error"
+    });
+  }
+  completeActiveTurn(turn) {
+    const active = this.activeTurn;
+    if (!active)
+      return;
+    if (active.timeout) {
+      clearTimeout(active.timeout);
+      active.timeout = null;
+    }
+    this.enqueue(this.resultFromTurn(turn, active));
+    this.activeTurn = null;
+  }
+  handleLoopStatusMessage(message) {
+    const status = loopStatusValue(message);
+    if (!status)
+      return;
+    const activeRunIds = loopStatusRunIds(message);
+    const sdkMessage = {
+      type: "loop_status",
+      status,
+      activeRunIds
+    };
+    this.enqueue(sdkMessage);
+    const active = this.activeTurn;
+    if (!active)
+      return;
+    for (const runId of activeRunIds)
+      active.runIds.add(runId);
+    const hadTurnEvidence = active.observedTurnEvidence || active.observedRequiresApprovalStop;
+    if (!hadTurnEvidence)
+      return;
+    if (status === "WAITING_ON_APPROVAL") {
+      this.completeActiveTurn({
+        runtime: active.runtime,
+        stopReason: "requires_approval",
+        runIds: [...active.runIds]
+      });
+      return;
+    }
+    if (status === "WAITING_ON_INPUT" && active.abortRequested) {
+      this.completeActiveTurn({
+        runtime: active.runtime,
+        stopReason: "interrupted",
+        runIds: [...active.runIds],
+        success: false,
+        detail: "Interrupted",
+        errorCode: "interrupted"
+      });
+      return;
+    }
+    if (status === "WAITING_ON_INPUT" && active.observedTurnEvidence) {
+      this.completeActiveTurn({
+        runtime: active.runtime,
+        stopReason: null,
+        runIds: [...active.runIds]
+      });
+    }
+  }
+  handleTurnTerminalDelta(delta, sdkMessage) {
+    const active = this.activeTurn;
+    if (!active)
+      return;
+    const messageType = streamDeltaMessageType2(delta);
+    if (messageType === "stop_reason") {
+      const stopReason = streamDeltaStopReason2(delta) ?? null;
+      if (stopReason === "requires_approval") {
+        active.observedRequiresApprovalStop = true;
+        return;
+      }
+      this.completeActiveTurn({
+        runtime: active.runtime,
+        stopReason,
+        runIds: [...active.runIds]
+      });
+      return;
+    }
+    if (sdkMessage?.type === "error") {
+      this.completeActiveTurn({
+        runtime: active.runtime,
+        stopReason: sdkMessage.stopReason,
+        runIds: [...active.runIds],
+        success: false,
+        detail: sdkMessage.errorDetail ?? sdkMessage.message,
+        errorCode: sdkMessage.errorCode
+      });
+    }
+  }
+  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 uuid = typeof delta.id === "string" ? delta.id : `${this.label}-${++this.messageCounter}`;
+    if (messageType === "assistant_message") {
+      const content = extractTextFromContent(delta.content);
+      if (!content)
+        return null;
+      if (this.activeTurn)
+        this.activeTurn.assistantText += content;
+      return { type: "assistant", content, uuid, 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 };
+    }
+    if (messageType === "tool_call_message" || messageType === "approval_request_message") {
+      const toolCall = firstToolCall(delta);
+      if (!toolCall)
+        return null;
+      const fn = toolCall.function && typeof toolCall.function === "object" ? toolCall.function : undefined;
+      const toolCallId = (typeof toolCall.tool_call_id === "string" ? toolCall.tool_call_id : undefined) ?? (typeof toolCall.id === "string" ? toolCall.id : undefined);
+      if (!toolCallId) {
+        const detail = `Missing tool_call_id in ${messageType} (uuid=${uuid})`;
+        return {
+          type: "error",
+          message: detail,
+          errorCode: "protocol_error",
+          stopReason: "protocol_error",
+          runId,
+          recoverable: false,
+          errorDetail: detail
+        };
+      }
+      const toolName = (typeof toolCall.name === "string" ? toolCall.name : undefined) ?? (typeof fn?.name === "string" ? fn.name : undefined) ?? "?";
+      const { input, raw } = toolInputFromArguments(toolCall.arguments ?? fn?.arguments);
+      return {
+        type: "tool_call",
+        toolCallId,
+        toolName,
+        toolInput: input,
+        rawArguments: raw,
+        uuid,
+        runId
+      };
+    }
+    if (messageType === "tool_return_message") {
+      const toolReturn = firstToolReturn(delta) ?? delta;
+      const toolCallId = (typeof delta.tool_call_id === "string" ? delta.tool_call_id : undefined) ?? (typeof toolReturn.tool_call_id === "string" ? toolReturn.tool_call_id : undefined);
+      if (!toolCallId)
+        return null;
+      const content = extractTextFromContent(delta.tool_return ?? toolReturn.tool_return ?? toolReturn.content) ?? "";
+      const status = typeof delta.status === "string" ? delta.status : toolReturn.status;
+      return {
+        type: "tool_result",
+        toolCallId,
+        content,
+        isError: status === "error",
+        uuid,
+        runId
+      };
+    }
+    if (messageType === "error_message" || messageType === "loop_error") {
+      const detail = (typeof delta.detail === "string" ? delta.detail : undefined) ?? (typeof delta.message === "string" ? delta.message : undefined) ?? `${this.label} turn failed`;
+      const stopReason = (typeof delta.stop_reason === "string" ? delta.stop_reason : undefined) ?? (typeof delta.error_type === "string" ? delta.error_type : undefined) ?? "error";
+      const approvalConflict = isApprovalConflictSignal({
+        detail,
+        message: typeof delta.message === "string" ? delta.message : undefined,
+        stopReason
+      });
+      return {
+        type: "error",
+        message: detail,
+        errorCode: approvalConflict ? "approval_conflict" : toSdkErrorCode(stopReason),
+        approvalConflict: approvalConflict || undefined,
+        recoverable: approvalConflict ? true : false,
+        errorDetail: detail,
+        stopReason,
+        runId
+      };
+    }
+    if (messageType === "retry") {
+      return {
+        type: "retry",
+        reason: typeof delta.reason === "string" ? delta.reason : "error",
+        attempt: typeof delta.attempt === "number" ? delta.attempt : 0,
+        maxAttempts: typeof delta.max_attempts === "number" ? delta.max_attempts : 0,
+        delayMs: typeof delta.delay_ms === "number" ? delta.delay_ms : 0,
+        runId
+      };
+    }
+    if (messageType === "stop_reason" || messageType === "ping") {
+      return null;
+    }
+    return {
+      type: "stream_event",
+      event: delta,
+      uuid
+    };
+  }
+  resultFromTurn(turn, tracker) {
+    const stopReason = turn.stopReason ?? (turn.success === false ? "error" : undefined);
+    const approvalConflict = isApprovalConflictSignal({
+      detail: turn.detail,
+      stopReason
+    });
+    const success = turn.success !== undefined ? turn.success && !approvalConflict && !FAILURE_STOP_REASONS.has(stopReason ?? "") : !approvalConflict && !FAILURE_STOP_REASONS.has(stopReason ?? "");
+    const errorCode = approvalConflict ? "approval_conflict" : turn.errorCode ?? toSdkErrorCode(stopReason);
+    return {
+      type: "result",
+      success,
+      result: success ? tracker?.assistantText || undefined : undefined,
+      error: success ? undefined : errorCode ?? stopReason ?? "error",
+      errorCode: success ? undefined : errorCode ?? "error",
+      approvalConflict: approvalConflict || undefined,
+      recoverable: approvalConflict ? true : success ? undefined : false,
+      errorDetail: success ? undefined : turn.detail,
+      stopReason,
+      durationMs: Date.now() - (tracker?.startedAt || this._activeTurnStartedAt),
+      conversationId: turn.runtime.conversation_id,
+      runIds: turn.runIds.length > 0 ? turn.runIds : undefined
+    };
+  }
+  enqueue(message) {
+    const resolver = this.streamResolvers.shift();
+    if (resolver) {
+      resolver(message);
+      return;
+    }
+    this.streamQueue.push(message);
+  }
+  resolveAll(value) {
+    for (const resolve of this.streamResolvers.splice(0)) {
+      resolve(value);
+    }
+  }
+}
+// src/remote-client-session-core.ts
+class RemoteClientSessionCore {
+  mode;
+  controller = null;
+  runtime = null;
+  initialized = false;
+  closed = false;
+  _agentId = null;
+  _sessionId = null;
+  _conversationId = null;
+  _model = "";
+  _modelSettings = null;
+  label;
+  requestTimeoutMs;
+  initializePromise = null;
+  removeMessageHandler = null;
+  turns;
+  toolNames;
+  deviceStatusListeners = new Set;
+  deviceStatusRefreshCancels = new Set;
+  constructor(mode, config) {
+    this.mode = mode;
+    this.label = config.label;
+    this.requestTimeoutMs = config.requestTimeoutMs;
+    this.turns = new RemoteTurnCoordinator({
+      label: config.label,
+      requestTimeoutMs: config.requestTimeoutMs,
+      onDeviceStatus: (status) => this.emitDeviceStatus(status)
+    });
+  }
+  async initialize() {
+    if (this.closed) {
+      throw new Error("Session is closed");
     }
-    if (!this.controller || !this.runtime) {
-      throw new Error("Session is not initialized");
+    if (this.initializePromise) {
+      return this.initializePromise;
     }
-    const normalized = normalizeUpdateModelInput(update);
-    const payload = await this.resolveUpdateModelPayload(normalized);
-    const result = await this.controller.updateModel(this.runtime, payload);
-    if (result.modelHandle !== undefined) {
-      this._model = result.modelHandle;
-    } else if (payload.model_handle !== undefined) {
-      this._model = payload.model_handle;
-    } else if (typeof result.modelSettings?.model === "string") {
-      this._model = result.modelSettings.model;
+    if (this.initialized) {
+      throw new Error("Session already initialized");
     }
-    if ("modelSettings" in result) {
-      this._modelSettings = result.modelSettings ?? null;
+    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((message) => {
+      if (this.runtime)
+        this.turns.handleProtocolMessage(message, this.runtime);
+    });
+    await this.afterRuntimeInitialized();
+    await this.applyPostInitializeOptions();
+    if (this.closed) {
+      throw new Error("Session is closed");
     }
-    return result;
+    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;
   }
-  async recoverPendingApprovals(options = {}) {
+  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) {
       await this.initialize();
     }
     if (!this.controller || !this.runtime) {
       throw new Error("Session is not initialized");
     }
-    return this.controller.recoverPendingApprovals(this.runtime, options);
-  }
-  async removeQueuedMessage(itemId) {
-    if (typeof itemId !== "string" || itemId.trim().length === 0) {
-      throw new Error("Invalid queue item id. Expected a non-empty string.");
-    }
-    if (!this.initialized) {
-      await this.initialize();
+    await this.beforeTurn();
+    const turn = this.turns.trackSentTurn(this.runtime);
+    try {
+      this.controller.sendTurnMessage(this.runtime, message, {
+        clientMessageId: turn.clientMessageId
+      });
+    } catch (error) {
+      this.turns.removeTrackedTurn(turn);
+      throw error;
     }
-    if (!this.controller || !this.runtime) {
-      throw new Error("Session is not initialized");
+  }
+  async runTurn(message, _options = {}) {
+    if (this.turns.hasInFlightTurn()) {
+      throw new Error(`A turn is already in flight for this ${this.label} session. Use send() and stream() to let the listener queue messages.`);
     }
-    const response = await this.controller.request("remove_queue_item", {
-      runtime: this.runtime,
-      item_id: itemId
-    }, {
-      predicate: (message) => message.type === "remove_queue_item_response" && message.item_id === itemId
-    });
-    if (typeof response.success !== "boolean") {
-      throw new Error("Invalid remove_queue_item_response from runtime");
+    await this.send(message);
+    for await (const msg of this.stream()) {
+      if (msg.type === "result") {
+        return msg;
+      }
     }
     return {
-      itemId: typeof response.item_id === "string" ? response.item_id : itemId,
-      removed: response.success
+      type: "result",
+      success: false,
+      error: "stream_closed",
+      errorCode: "stream_closed",
+      recoverable: false,
+      errorDetail: "Stream ended before terminal result",
+      durationMs: Date.now() - this.turns.activeTurnStartedAt,
+      conversationId: this._conversationId
     };
   }
-  async getDeviceStatus(options = {}) {
+  async* stream() {
+    while (true) {
+      const msg = await this.turns.nextMessage();
+      if (!msg)
+        break;
+      yield msg;
+      if (msg.type === "result")
+        break;
+    }
+  }
+  async abort() {
+    if (!this.initialized)
+      return;
+    if (!this.controller || !this.runtime)
+      return;
+    this.turns.markAbortRequested();
+    await this.controller.abort(this.runtime);
+  }
+  async sendCommand(command, options) {
     if (!this.initialized) {
       await this.initialize();
     }
-    if (!this.controller || !this.runtime) {
+    if (!this.controller) {
       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.");
+    if (!command || typeof command !== "object" || Array.isArray(command)) {
+      throw new Error("Invalid command. Expected a protocol command object.");
     }
-    return this.refreshDeviceStatus(timeoutMs);
-  }
-  onDeviceStatus(listener) {
-    if (typeof listener !== "function") {
-      throw new Error("Invalid device status listener. Expected a function.");
+    if (typeof command.type !== "string" || command.type.length === 0) {
+      throw new Error("Invalid command. Expected a non-empty type.");
     }
-    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"));
+    if (!options || !options.responseType && !options.predicate && options.timeoutMs === undefined) {
+      this.controller.send(command);
+      return;
     }
-    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)));
-      });
+    const { type, ...body } = command;
+    const response = await this.controller.request(type, body, {
+      ...options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {},
+      predicate: options.predicate ? (message) => options.predicate?.(message) === true : options.responseType ? (message) => message.type === options.responseType : undefined
     });
+    return response;
   }
-  async listMessages(options = {}) {
+  async listModels() {
     if (!this.initialized) {
       await this.initialize();
     }
     if (!this.controller) {
       throw new Error("Session is not initialized");
     }
-    const conversationId = options.conversationId ?? this._conversationId;
-    if (!conversationId) {
-      throw new Error("No conversation id available for listMessages()");
-    }
-    return this.controller.listMessages(conversationId, options);
+    return this.controller.listModels();
   }
-  async bootstrapState(options = {}) {
+  async updateModel(update) {
     if (!this.initialized) {
       await this.initialize();
     }
-    const page = await this.listMessages({
-      limit: options.limit,
-      order: options.order
-    });
-    const state = {
-      agentId: this._agentId ?? "",
-      conversationId: this._conversationId ?? "",
-      model: this._model,
-      messages: page.messages
-    };
-    if (this.toolNames !== undefined) {
-      state.tools = this.toolNames;
-    }
-    if (page.nextBefore !== undefined) {
-      state.nextBefore = page.nextBefore;
-    }
-    if (page.hasMore !== undefined) {
-      state.hasMore = page.hasMore;
+    if (!this.controller || !this.runtime) {
+      throw new Error("Session is not initialized");
     }
-    return state;
+    return this.applyModelUpdate(update);
   }
-  close() {
-    if (this.closed)
-      return;
-    this.closed = true;
-    this.removeMessageHandler?.();
-    this.removeMessageHandler = null;
-    if (this.activeTurn?.timeout)
-      clearTimeout(this.activeTurn.timeout);
-    for (const turn of this.pendingTurns) {
-      if (turn.timeout)
-        clearTimeout(turn.timeout);
-    }
-    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`));
+  async applyModelUpdate(update) {
+    if (!this.controller || !this.runtime) {
+      throw new Error("Session is not initialized");
     }
-    this.deviceStatusRefreshCancels.clear();
-    this.deviceStatusListeners.clear();
-    this.controller?.close();
-    this.controller = null;
-    this.onCoreClose();
-    this.resolveAll(null);
-  }
-  get agentId() {
-    return this._agentId;
-  }
-  get sessionId() {
-    return this._sessionId;
-  }
-  get conversationId() {
-    return this._conversationId;
-  }
-  async[Symbol.asyncDispose]() {
-    this.close();
+    const normalized = normalizeUpdateModelInput(update);
+    const payload = await this.resolveUpdateModelPayload(normalized);
+    const result = await this.controller.updateModel(this.runtime, payload);
+    if (result.modelHandle !== undefined) {
+      this._model = result.modelHandle;
+    } else if (payload.model_handle !== undefined) {
+      this._model = payload.model_handle;
+    } else if (typeof result.modelSettings?.model === "string") {
+      this._model = result.modelSettings.model;
+    }
+    if ("modelSettings" in result) {
+      this._modelSettings = result.modelSettings ?? null;
+    }
+    return result;
   }
-  async changeDeviceState(updates) {
+  async recoverPendingApprovals(options = {}) {
     if (!this.initialized) {
       await this.initialize();
     }
     if (!this.controller || !this.runtime) {
       throw new Error("Session is not initialized");
     }
-    const payload = {};
-    if (updates.cwd !== undefined)
-      payload.cwd = updates.cwd;
-    if (updates.permissionMode !== undefined) {
-      const mode = mapPermissionMode(updates.permissionMode);
-      if (mode !== undefined)
-        payload.mode = mode;
-    }
-    if (Object.keys(payload).length === 0) {
-      throw new Error("Invalid device state update. Expected cwd or permissionMode.");
-    }
-    this.controller.send({
-      type: "change_device_state",
-      runtime: this.runtime,
-      payload
-    });
+    return this.controller.recoverPendingApprovals(this.runtime, options);
   }
-  async updateToolset(toolsetPreference) {
+  async removeQueuedMessage(itemId) {
+    if (typeof itemId !== "string" || itemId.trim().length === 0) {
+      throw new Error("Invalid queue item id. Expected a non-empty string.");
+    }
     if (!this.initialized) {
       await this.initialize();
     }
     if (!this.controller || !this.runtime) {
       throw new Error("Session is not initialized");
     }
-    const response = await this.controller.request("update_toolset", {
+    const response = await this.controller.request("remove_queue_item", {
       runtime: this.runtime,
-      toolset_preference: toolsetPreference
-    }, { predicate: (message) => message.type === "update_toolset_response" });
-    ensureSuccess(response, "Failed to update toolset");
-  }
-  async afterRuntimeInitialized() {}
-  async beforeTurn() {}
-  onCoreClose() {}
-  currentOptions() {
-    return this.mode.options;
-  }
-  shouldEnableMemfs(options) {
-    return false;
-  }
-  enableMemfsBody() {
-    if (!this.runtime)
-      return {};
-    return { agent_id: this.runtime.agent_id };
-  }
-  setModel(model) {
-    this._model = model;
-  }
-  trackSentTurn(runtime) {
-    const turn = {
-      id: ++this.nextTurnId,
-      runtime,
-      clientMessageId: `sdk-message-${Date.now()}-${++this.clientMessageCounter}`,
-      queuedAt: Date.now(),
-      startedAt: 0,
-      assistantText: "",
-      runIds: new Set,
-      observedTurnEvidence: false,
-      observedRequiresApprovalStop: false,
-      abortRequested: false,
-      timeout: null
-    };
-    if (this.activeTurn) {
-      this.pendingTurns.push(turn);
-    } else {
-      this.activateTurn(turn);
-    }
-    return turn;
-  }
-  activateTurn(turn) {
-    this.activeTurn = turn;
-    turn.startedAt = Date.now();
-    this.activeTurnStartedAt = turn.startedAt;
-    if (this.requestTimeoutMs !== undefined) {
-      turn.timeout = setTimeout(() => {
-        this.failTurn(turn, `Timed out waiting for ${this.label} turn`);
-      }, this.requestTimeoutMs);
-      turn.timeout.unref?.();
-    }
-  }
-  activateNextTurnFromProtocol() {
-    if (this.activeTurn)
-      return this.activeTurn;
-    const next = this.pendingTurns.shift();
-    if (!next)
-      return null;
-    this.activateTurn(next);
-    return next;
-  }
-  removeTrackedTurn(turn) {
-    if (turn.timeout)
-      clearTimeout(turn.timeout);
-    if (this.activeTurn === turn) {
-      this.activeTurn = null;
-      return;
-    }
-    const index = this.pendingTurns.indexOf(turn);
-    if (index !== -1)
-      this.pendingTurns.splice(index, 1);
-  }
-  failTurn(turn, detail) {
-    if (this.activeTurn !== turn)
-      return;
-    this.enqueue({
-      type: "error",
-      message: detail,
-      errorCode: "error",
-      stopReason: "error",
-      errorDetail: detail,
-      recoverable: false
-    });
-    this.completeActiveTurn({
-      runtime: turn.runtime,
-      stopReason: "error",
-      runIds: [...turn.runIds],
-      success: false,
-      detail,
-      errorCode: "error"
+      item_id: itemId
+    }, {
+      predicate: (message) => message.type === "remove_queue_item_response" && message.item_id === itemId
     });
-  }
-  completeActiveTurn(turn) {
-    const active = this.activeTurn;
-    if (!active)
-      return;
-    if (active.timeout) {
-      clearTimeout(active.timeout);
-      active.timeout = null;
+    if (typeof response.success !== "boolean") {
+      throw new Error("Invalid remove_queue_item_response from runtime");
     }
-    this.enqueue(this.resultFromTurn(turn, active));
-    this.activeTurn = null;
+    return {
+      itemId: typeof response.item_id === "string" ? response.item_id : itemId,
+      removed: response.success
+    };
   }
-  async resolveUpdateModelPayload(input) {
-    if (input.reasoningEffort === undefined) {
-      return modelPayloadWithoutReasoning(input);
+  async getDeviceStatus(options = {}) {
+    if (!this.initialized) {
+      await this.initialize();
     }
-    if (!this.controller) {
+    if (!this.controller || !this.runtime) {
       throw new Error("Session is not initialized");
     }
-    const catalog = await this.controller.listModels();
-    const byId = new Map(catalog.entries.map((entry) => [entry.id, entry]));
-    const aliases = catalog.byokProviderAliases;
-    let baseEntry;
-    let explicitHandle;
-    let targetHandle;
-    if (input.modelId !== undefined) {
-      baseEntry = byId.get(input.modelId);
-      explicitHandle = input.modelHandle;
-      targetHandle = baseEntry?.handle ?? toBaseModelHandle(input.modelHandle, aliases);
-    } else if (input.modelHandle !== undefined) {
-      explicitHandle = input.modelHandle;
-      targetHandle = toBaseModelHandle(input.modelHandle, aliases);
-    } else if (input.model !== undefined) {
-      baseEntry = byId.get(input.model);
-      if (baseEntry) {
-        targetHandle = baseEntry.handle;
-      } else {
-        explicitHandle = input.model;
-        targetHandle = toBaseModelHandle(input.model, aliases);
-      }
-    } else {
-      explicitHandle = this._model || undefined;
-      targetHandle = toBaseModelHandle(this._model || undefined, aliases);
-    }
-    if (!targetHandle) {
-      throw new Error("reasoningEffort requires a current model or explicit model/modelId/modelHandle.");
-    }
-    const candidates = catalog.entries.filter((entry) => entry.handle === targetHandle || entry.handle === explicitHandle);
-    if (candidates.length === 0) {
-      throw new Error(`reasoningEffort requires a model from listModels(); no catalog entry found for ${targetHandle}.`);
-    }
-    const contextWindow = getContextWindow(baseEntry?.updateArgs) ?? getContextWindow(this._modelSettings);
-    const scopedCandidates = sameContextCandidates(candidates, contextWindow);
-    const matchingEntry = scopedCandidates.find((entry) => getReasoningEffort(entry) === input.reasoningEffort) ?? candidates.find((entry) => getReasoningEffort(entry) === input.reasoningEffort);
-    if (!matchingEntry) {
-      throw new Error(`No ${input.reasoningEffort} reasoning tier found for model ${targetHandle}.`);
+    const timeoutMs = options.timeoutMs ?? this.requestTimeoutMs ?? 30000;
+    if (!Number.isInteger(timeoutMs) || timeoutMs <= 0) {
+      throw new Error("Invalid device status timeout. Expected a positive integer.");
     }
-    const payload = { model_id: matchingEntry.id };
-    if (explicitHandle !== undefined) {
-      payload.model_handle = explicitHandle;
+    return this.refreshDeviceStatus(timeoutMs);
+  }
+  onDeviceStatus(listener) {
+    if (typeof listener !== "function") {
+      throw new Error("Invalid device status listener. Expected a function.");
     }
-    return payload;
+    this.deviceStatusListeners.add(listener);
+    return () => {
+      this.deviceStatusListeners.delete(listener);
+    };
   }
-  async applyPostInitializeOptions() {
-    if (!this.controller || !this.runtime)
-      return;
-    const options = this.currentOptions();
-    if (this.shouldEnableMemfs(options)) {
-      const response = await this.controller.request("enable_memfs", this.enableMemfsBody(), {
-        predicate: (message) => message.type === "enable_memfs_response",
-        timeoutMs: 180000
+  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)));
       });
-      ensureSuccess(response, "Failed to enable memfs");
+    });
+  }
+  async listMessages(options = {}) {
+    if (!this.initialized) {
+      await this.initialize();
     }
-    const dreamingSettings = resolveDreamingSettings(options.dreaming);
-    if (dreamingSettings) {
-      const response = await this.controller.request("set_reflection_settings", {
-        runtime: this.runtime,
-        settings: dreamingSettings,
-        scope: "both"
-      }, { predicate: (message) => message.type === "set_reflection_settings_response" });
-      ensureSuccess(response, "Failed to update dreaming settings");
+    if (!this.controller) {
+      throw new Error("Session is not initialized");
     }
-    if (this.mode.kind !== "session")
-      return;
-    if (this.mode.options.model !== undefined || this.mode.options.reasoningEffort !== undefined) {
-      await this.updateModel({
-        ...this.mode.options.model !== undefined ? { model: this.mode.options.model } : {},
-        ...this.mode.options.reasoningEffort !== undefined ? { reasoningEffort: this.mode.options.reasoningEffort } : {}
-      });
+    const conversationId = options.conversationId ?? this._conversationId;
+    if (!conversationId) {
+      throw new Error("No conversation id available for listMessages()");
     }
+    return this.controller.listMessages(conversationId, options);
   }
-  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",
-        queue: queueItems(message)
-      };
-      this.enqueue(sdkMessage2);
-      return;
+  async bootstrapState(options = {}) {
+    if (!this.initialized) {
+      await this.initialize();
     }
-    if (message.type === "update_loop_status") {
-      this.handleLoopStatusMessage(message);
-      return;
+    const page = await this.listMessages({
+      limit: options.limit,
+      order: options.order
+    });
+    const state = {
+      agentId: this._agentId ?? "",
+      conversationId: this._conversationId ?? "",
+      model: this._model,
+      messages: page.messages
+    };
+    if (this.toolNames !== undefined) {
+      state.tools = this.toolNames;
     }
-    const delta = streamDeltaRecord(message);
-    if (!delta)
-      return;
-    const active = this.activateNextTurnFromProtocol();
-    if (active) {
-      active.observedTurnEvidence = true;
-      const runId = streamDeltaRunId2(delta);
-      if (runId)
-        active.runIds.add(runId);
+    if (page.nextBefore !== undefined) {
+      state.nextBefore = page.nextBefore;
     }
-    const sdkMessage = this.transformStreamDelta(delta);
-    if (sdkMessage) {
-      this.enqueue(sdkMessage);
+    if (page.hasMore !== undefined) {
+      state.hasMore = page.hasMore;
     }
-    this.handleTurnTerminalDelta(delta, sdkMessage);
-  };
-  handleLoopStatusMessage(message) {
-    const status = loopStatusValue(message);
-    if (!status)
-      return;
-    const activeRunIds = loopStatusRunIds(message);
-    const sdkMessage = {
-      type: "loop_status",
-      status,
-      activeRunIds
-    };
-    this.enqueue(sdkMessage);
-    const active = this.activeTurn;
-    if (!active)
-      return;
-    for (const runId of activeRunIds)
-      active.runIds.add(runId);
-    const hadTurnEvidence = active.observedTurnEvidence || active.observedRequiresApprovalStop;
-    if (!hadTurnEvidence)
-      return;
-    if (status === "WAITING_ON_APPROVAL") {
-      this.completeActiveTurn({
-        runtime: active.runtime,
-        stopReason: "requires_approval",
-        runIds: [...active.runIds]
-      });
+    return state;
+  }
+  close() {
+    if (this.closed)
       return;
+    this.closed = true;
+    this.removeMessageHandler?.();
+    this.removeMessageHandler = null;
+    this.turns.close();
+    for (const cancel of [...this.deviceStatusRefreshCancels]) {
+      cancel(new Error(`Session closed while waiting for ${this.label} device status`));
     }
-    if (status === "WAITING_ON_INPUT" && active.abortRequested) {
-      this.completeActiveTurn({
-        runtime: active.runtime,
-        stopReason: "interrupted",
-        runIds: [...active.runIds],
-        success: false,
-        detail: "Interrupted",
-        errorCode: "interrupted"
-      });
-      return;
+    this.deviceStatusRefreshCancels.clear();
+    this.deviceStatusListeners.clear();
+    this.controller?.close();
+    this.controller = null;
+    this.onCoreClose();
+  }
+  get agentId() {
+    return this._agentId;
+  }
+  get sessionId() {
+    return this._sessionId;
+  }
+  get conversationId() {
+    return this._conversationId;
+  }
+  async[Symbol.asyncDispose]() {
+    this.close();
+  }
+  async changeDeviceState(updates) {
+    if (!this.initialized) {
+      await this.initialize();
     }
-    if (status === "WAITING_ON_INPUT" && active.observedTurnEvidence) {
-      this.completeActiveTurn({
-        runtime: active.runtime,
-        stopReason: null,
-        runIds: [...active.runIds]
-      });
+    if (!this.controller || !this.runtime) {
+      throw new Error("Session is not initialized");
     }
-  }
-  handleTurnTerminalDelta(delta, sdkMessage) {
-    const active = this.activeTurn;
-    if (!active)
-      return;
-    const messageType = streamDeltaMessageType2(delta);
-    if (messageType === "stop_reason") {
-      const stopReason = streamDeltaStopReason2(delta) ?? null;
-      if (stopReason === "requires_approval") {
-        active.observedRequiresApprovalStop = true;
-        return;
-      }
-      this.completeActiveTurn({
-        runtime: active.runtime,
-        stopReason,
-        runIds: [...active.runIds]
-      });
-      return;
+    const payload = {};
+    if (updates.cwd !== undefined)
+      payload.cwd = updates.cwd;
+    if (updates.permissionMode !== undefined) {
+      const mode = mapPermissionMode(updates.permissionMode);
+      if (mode !== undefined)
+        payload.mode = mode;
     }
-    if (sdkMessage?.type === "error") {
-      this.completeActiveTurn({
-        runtime: active.runtime,
-        stopReason: sdkMessage.stopReason,
-        runIds: [...active.runIds],
-        success: false,
-        detail: sdkMessage.errorDetail ?? sdkMessage.message,
-        errorCode: sdkMessage.errorCode
-      });
+    if (Object.keys(payload).length === 0) {
+      throw new Error("Invalid device state update. Expected cwd or permissionMode.");
     }
+    this.controller.send({
+      type: "change_device_state",
+      runtime: this.runtime,
+      payload
+    });
   }
-  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 uuid = typeof delta.id === "string" ? delta.id : `${this.label}-${++this.messageCounter}`;
-    if (messageType === "assistant_message") {
-      const content = extractTextFromContent(delta.content);
-      if (!content)
-        return null;
-      if (this.activeTurn)
-        this.activeTurn.assistantText += content;
-      return { type: "assistant", content, uuid, runId };
+  async updateToolset(toolsetPreference) {
+    if (!this.initialized) {
+      await this.initialize();
     }
-    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 };
+    if (!this.controller || !this.runtime) {
+      throw new Error("Session is not initialized");
     }
-    if (messageType === "tool_call_message" || messageType === "approval_request_message") {
-      const toolCall = firstToolCall(delta);
-      if (!toolCall)
-        return null;
-      const fn = toolCall.function && typeof toolCall.function === "object" ? toolCall.function : undefined;
-      const toolCallId = (typeof toolCall.tool_call_id === "string" ? toolCall.tool_call_id : undefined) ?? (typeof toolCall.id === "string" ? toolCall.id : undefined);
-      if (!toolCallId) {
-        const detail = `Missing tool_call_id in ${messageType} (uuid=${uuid})`;
-        return {
-          type: "error",
-          message: detail,
-          errorCode: "protocol_error",
-          stopReason: "protocol_error",
-          runId,
-          recoverable: false,
-          errorDetail: detail
-        };
+    const response = await this.controller.request("update_toolset", {
+      runtime: this.runtime,
+      toolset_preference: toolsetPreference
+    }, { predicate: (message) => message.type === "update_toolset_response" });
+    ensureSuccess(response, "Failed to update toolset");
+  }
+  async afterRuntimeInitialized() {}
+  async beforeTurn() {}
+  onCoreClose() {}
+  currentOptions() {
+    return this.mode.options;
+  }
+  shouldEnableMemfs(options) {
+    return false;
+  }
+  enableMemfsBody() {
+    if (!this.runtime)
+      return {};
+    return { agent_id: this.runtime.agent_id };
+  }
+  setModel(model) {
+    this._model = model;
+  }
+  async resolveUpdateModelPayload(input) {
+    if (input.reasoningEffort === undefined) {
+      return modelPayloadWithoutReasoning(input);
+    }
+    if (!this.controller) {
+      throw new Error("Session is not initialized");
+    }
+    const catalog = await this.controller.listModels();
+    const byId = new Map(catalog.entries.map((entry) => [entry.id, entry]));
+    const aliases = catalog.byokProviderAliases;
+    let baseEntry;
+    let explicitHandle;
+    let targetHandle;
+    if (input.modelId !== undefined) {
+      baseEntry = byId.get(input.modelId);
+      explicitHandle = input.modelHandle;
+      targetHandle = baseEntry?.handle ?? toBaseModelHandle(input.modelHandle, aliases);
+    } else if (input.modelHandle !== undefined) {
+      explicitHandle = input.modelHandle;
+      targetHandle = toBaseModelHandle(input.modelHandle, aliases);
+    } else if (input.model !== undefined) {
+      baseEntry = byId.get(input.model);
+      if (baseEntry) {
+        targetHandle = baseEntry.handle;
+      } else {
+        explicitHandle = input.model;
+        targetHandle = toBaseModelHandle(input.model, aliases);
       }
-      const toolName = (typeof toolCall.name === "string" ? toolCall.name : undefined) ?? (typeof fn?.name === "string" ? fn.name : undefined) ?? "?";
-      const { input, raw } = toolInputFromArguments(toolCall.arguments ?? fn?.arguments);
-      return {
-        type: "tool_call",
-        toolCallId,
-        toolName,
-        toolInput: input,
-        rawArguments: raw,
-        uuid,
-        runId
-      };
+    } else {
+      explicitHandle = this._model || undefined;
+      targetHandle = toBaseModelHandle(this._model || undefined, aliases);
     }
-    if (messageType === "tool_return_message") {
-      const toolReturn = firstToolReturn(delta) ?? delta;
-      const toolCallId = (typeof delta.tool_call_id === "string" ? delta.tool_call_id : undefined) ?? (typeof toolReturn.tool_call_id === "string" ? toolReturn.tool_call_id : undefined);
-      if (!toolCallId)
-        return null;
-      const content = extractTextFromContent(delta.tool_return ?? toolReturn.tool_return ?? toolReturn.content) ?? "";
-      const status = typeof delta.status === "string" ? delta.status : toolReturn.status;
-      return {
-        type: "tool_result",
-        toolCallId,
-        content,
-        isError: status === "error",
-        uuid,
-        runId
-      };
+    if (!targetHandle) {
+      throw new Error("reasoningEffort requires a current model or explicit model/modelId/modelHandle.");
     }
-    if (messageType === "error_message" || messageType === "loop_error") {
-      const detail = (typeof delta.detail === "string" ? delta.detail : undefined) ?? (typeof delta.message === "string" ? delta.message : undefined) ?? `${this.label} turn failed`;
-      const stopReason = (typeof delta.stop_reason === "string" ? delta.stop_reason : undefined) ?? (typeof delta.error_type === "string" ? delta.error_type : undefined) ?? "error";
-      const approvalConflict = isApprovalConflictSignal({
-        detail,
-        message: typeof delta.message === "string" ? delta.message : undefined,
-        stopReason
-      });
-      return {
-        type: "error",
-        message: detail,
-        errorCode: approvalConflict ? "approval_conflict" : toSdkErrorCode(stopReason),
-        approvalConflict: approvalConflict || undefined,
-        recoverable: approvalConflict ? true : false,
-        errorDetail: detail,
-        stopReason,
-        runId
-      };
+    const candidates = catalog.entries.filter((entry) => entry.handle === targetHandle || entry.handle === explicitHandle);
+    if (candidates.length === 0) {
+      throw new Error(`reasoningEffort requires a model from listModels(); no catalog entry found for ${targetHandle}.`);
     }
-    if (messageType === "retry") {
-      return {
-        type: "retry",
-        reason: typeof delta.reason === "string" ? delta.reason : "error",
-        attempt: typeof delta.attempt === "number" ? delta.attempt : 0,
-        maxAttempts: typeof delta.max_attempts === "number" ? delta.max_attempts : 0,
-        delayMs: typeof delta.delay_ms === "number" ? delta.delay_ms : 0,
-        runId
-      };
+    const contextWindow = getContextWindow(baseEntry?.updateArgs) ?? getContextWindow(this._modelSettings);
+    const scopedCandidates = sameContextCandidates(candidates, contextWindow);
+    const matchingEntry = scopedCandidates.find((entry) => getReasoningEffort(entry) === input.reasoningEffort) ?? candidates.find((entry) => getReasoningEffort(entry) === input.reasoningEffort);
+    if (!matchingEntry) {
+      throw new Error(`No ${input.reasoningEffort} reasoning tier found for model ${targetHandle}.`);
     }
-    if (messageType === "stop_reason" || messageType === "ping") {
-      return null;
+    const payload = { model_id: matchingEntry.id };
+    if (explicitHandle !== undefined) {
+      payload.model_handle = explicitHandle;
     }
-    return {
-      type: "stream_event",
-      event: delta,
-      uuid
-    };
-  }
-  resultFromTurn(turn, tracker) {
-    const stopReason = turn.stopReason ?? (turn.success === false ? "error" : undefined);
-    const approvalConflict = isApprovalConflictSignal({
-      detail: turn.detail,
-      stopReason
-    });
-    const success = turn.success !== undefined ? turn.success && !approvalConflict && !FAILURE_STOP_REASONS.has(stopReason ?? "") : !approvalConflict && !FAILURE_STOP_REASONS.has(stopReason ?? "");
-    const errorCode = approvalConflict ? "approval_conflict" : turn.errorCode ?? toSdkErrorCode(stopReason);
-    return {
-      type: "result",
-      success,
-      result: success ? tracker?.assistantText || undefined : undefined,
-      error: success ? undefined : errorCode ?? stopReason ?? "error",
-      errorCode: success ? undefined : errorCode ?? "error",
-      approvalConflict: approvalConflict || undefined,
-      recoverable: approvalConflict ? true : success ? undefined : false,
-      errorDetail: success ? undefined : turn.detail,
-      stopReason,
-      durationMs: Date.now() - (tracker?.startedAt || this.activeTurnStartedAt),
-      conversationId: turn.runtime.conversation_id,
-      runIds: turn.runIds.length > 0 ? turn.runIds : undefined
-    };
+    return payload;
   }
-  enqueue(message) {
-    const resolver = this.streamResolvers.shift();
-    if (resolver) {
-      resolver(message);
+  async applyPostInitializeOptions() {
+    if (!this.controller || !this.runtime)
       return;
+    const options = this.currentOptions();
+    if (this.shouldEnableMemfs(options)) {
+      const response = await this.controller.request("enable_memfs", this.enableMemfsBody(), {
+        predicate: (message) => message.type === "enable_memfs_response",
+        timeoutMs: 180000
+      });
+      ensureSuccess(response, "Failed to enable memfs");
+    }
+    const dreamingSettings = resolveDreamingSettings(options.dreaming);
+    if (dreamingSettings) {
+      const response = await this.controller.request("set_reflection_settings", {
+        runtime: this.runtime,
+        settings: dreamingSettings,
+        scope: "both"
+      }, { predicate: (message) => message.type === "set_reflection_settings_response" });
+      ensureSuccess(response, "Failed to update dreaming settings");
+    }
+    if (this.mode.kind !== "session")
+      return;
+    if (this.mode.options.model !== undefined || this.mode.options.reasoningEffort !== undefined) {
+      await this.applyModelUpdate({
+        ...this.mode.options.model !== undefined ? { model: this.mode.options.model } : {},
+        ...this.mode.options.reasoningEffort !== undefined ? { reasoningEffort: this.mode.options.reasoningEffort } : {}
+      });
     }
-    this.streamQueue.push(message);
-  }
-  nextMessage() {
-    const next = this.streamQueue.shift();
-    if (next)
-      return Promise.resolve(next);
-    if (this.closed)
-      return Promise.resolve(null);
-    return new Promise((resolve) => {
-      this.streamResolvers.push(resolve);
-    });
   }
-  resolveAll(value) {
-    for (const resolve of this.streamResolvers.splice(0)) {
-      resolve(value);
+  emitDeviceStatus(status) {
+    for (const listener of [...this.deviceStatusListeners]) {
+      try {
+        listener(status);
+      } catch {}
     }
   }
 }
@@ -7243,13 +7543,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,
@@ -7648,13 +7950,58 @@ class RemoteEnvironmentClient {
   }
 }
 
+// src/cloud-sandbox.ts
+var MIN_TTL_MINUTES = 1;
+var MAX_TTL_MINUTES = 60;
+var MAX_GITHUB_REPOSITORIES = 10;
+var GITHUB_OWNER_PATTERN = /^[A-Za-z0-9-]+$/;
+var GITHUB_REPOSITORY_PATTERN = /^[A-Za-z0-9._-]+$/;
+function validatePositiveInteger(value, name) {
+  if (value !== undefined && (!Number.isInteger(value) || value <= 0)) {
+    throw new Error(`Invalid ${name}. Expected a positive integer.`);
+  }
+}
+function validateCloudSandboxOptions(options, name) {
+  if (options === undefined)
+    return;
+  if (options === null || typeof options !== "object" || Array.isArray(options)) {
+    throw new Error(`Invalid ${name}. Expected an object.`);
+  }
+  if (options.ttlMinutes !== undefined && (!Number.isInteger(options.ttlMinutes) || options.ttlMinutes < MIN_TTL_MINUTES || options.ttlMinutes > MAX_TTL_MINUTES)) {
+    throw new Error(`Invalid ${name}.ttlMinutes. Expected an integer between ${MIN_TTL_MINUTES} and ${MAX_TTL_MINUTES}.`);
+  }
+  validatePositiveInteger(options.readyTimeoutMs, `${name}.readyTimeoutMs`);
+  validatePositiveInteger(options.readyPollIntervalMs, `${name}.readyPollIntervalMs`);
+  validatePositiveInteger(options.refreshIntervalMs, `${name}.refreshIntervalMs`);
+  if (options.githubRepositories !== undefined) {
+    if (!Array.isArray(options.githubRepositories)) {
+      throw new Error(`Invalid ${name}.githubRepositories. Expected an array.`);
+    }
+    if (options.githubRepositories.length > MAX_GITHUB_REPOSITORIES) {
+      throw new Error(`Invalid ${name}.githubRepositories. Expected at most ${MAX_GITHUB_REPOSITORIES} repositories.`);
+    }
+    for (const [index, repository] of options.githubRepositories.entries()) {
+      if (repository === null || typeof repository !== "object" || Array.isArray(repository)) {
+        throw new Error(`Invalid ${name}.githubRepositories[${index}]. Expected an object.`);
+      }
+      if (typeof repository.owner !== "string" || !GITHUB_OWNER_PATTERN.test(repository.owner)) {
+        throw new Error(`Invalid ${name}.githubRepositories[${index}].owner.`);
+      }
+      if (typeof repository.repo !== "string" || !GITHUB_REPOSITORY_PATTERN.test(repository.repo)) {
+        throw new Error(`Invalid ${name}.githubRepositories[${index}].repo.`);
+      }
+    }
+  }
+  if (options.terminateOnClose !== undefined && typeof options.terminateOnClose !== "boolean") {
+    throw new Error(`Invalid ${name}.terminateOnClose. Expected a boolean.`);
+  }
+}
+
 // src/cloud-session.ts
 var DEFAULT_CLOUD_API_BASE_URL3 = "https://api.letta.com";
 var DEFAULT_TURN_TIMEOUT_MS = 120000;
 var DEFAULT_PING_INTERVAL_MS = 30000;
 var DEFAULT_SANDBOX_TTL_MINUTES = 5;
-var MIN_SANDBOX_TTL_MINUTES = 1;
-var MAX_SANDBOX_TTL_MINUTES = 60;
 var DEFAULT_SANDBOX_READY_TIMEOUT_MS = 120000;
 var DEFAULT_SANDBOX_READY_POLL_INTERVAL_MS = 1000;
 var DEFAULT_REPOSITORY_ATTACH_TIMEOUT_MS = 1e4;
@@ -7765,34 +8112,13 @@ function assertOkResponse2(response, body, action, url) {
     throw new Error(parts.join(" — "));
   }
 }
-function validatePositiveInteger(value, name) {
+function validatePositiveInteger2(value, name) {
   if (value !== undefined && (!Number.isInteger(value) || value <= 0)) {
     throw new Error(`Invalid ${name}. Expected a positive integer.`);
   }
 }
-function validateIntegerRange(value, name, min, max) {
-  if (value === undefined)
-    return;
-  if (!Number.isInteger(value) || value < min || value > max) {
-    throw new Error(`Invalid ${name}. Expected an integer between ${min} and ${max}.`);
-  }
-}
-function validateCloudSandboxOptions(options, name) {
-  if (options === undefined)
-    return;
-  if (options === null || typeof options !== "object" || Array.isArray(options)) {
-    throw new Error(`Invalid ${name}. Expected an object.`);
-  }
-  validateIntegerRange(options.ttlMinutes, `${name}.ttlMinutes`, MIN_SANDBOX_TTL_MINUTES, MAX_SANDBOX_TTL_MINUTES);
-  validatePositiveInteger(options.readyTimeoutMs, `${name}.readyTimeoutMs`);
-  validatePositiveInteger(options.readyPollIntervalMs, `${name}.readyPollIntervalMs`);
-  validatePositiveInteger(options.refreshIntervalMs, `${name}.refreshIntervalMs`);
-  if (options.terminateOnClose !== undefined && typeof options.terminateOnClose !== "boolean") {
-    throw new Error(`Invalid ${name}.terminateOnClose. Expected a boolean.`);
-  }
-}
 function validateCloudClientOptions(options) {
-  validatePositiveInteger(options.requestTimeoutMs, "requestTimeoutMs");
+  validatePositiveInteger2(options.requestTimeoutMs, "requestTimeoutMs");
   validateCloudSandboxOptions(options.sandbox, "sandbox");
   if (options.environment !== undefined && options.sandbox !== undefined) {
     throw new Error("Letta Cloud sessions cannot specify both environment and sandbox options.");
@@ -8120,14 +8446,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,
@@ -8395,10 +8721,15 @@ class CloudEnvironmentSession extends RemoteClientSessionCore {
   async createManagedSandbox(agentId, conversationId) {
     const fetchImpl = getFetch3(this.cloudOptions.fetch);
     const baseUrl = normalizeCloudApiBaseUrl2(this.cloudOptions.apiBaseUrl);
+    const sandboxOptions = this.resolvedSandboxOptions();
+    const githubRepositories = sandboxOptions.githubRepositories;
     const response = await fetchImpl(`${baseUrl}/v1/agents/${encodeURIComponent(agentId)}/sandboxes`, {
       method: "POST",
       headers: cloudHeaders2(this.cloudOptions),
-      body: JSON.stringify(conversationId ? { conversationId } : {})
+      body: JSON.stringify({
+        ...conversationId ? { conversationId } : {},
+        ...githubRepositories && githubRepositories.length > 0 ? { githubRepositories } : {}
+      })
     });
     const body = await parseJsonResponse3(response);
     assertOkResponse2(response, body, "Cloud create managed sandbox", `${baseUrl}/v1/agents/${encodeURIComponent(agentId)}/sandboxes`);
@@ -8409,7 +8740,6 @@ class CloudEnvironmentSession extends RemoteClientSessionCore {
     if (responseConversationId !== null && responseConversationId !== conversationId) {
       throw new Error(`Cloud managed sandbox response conversation mismatch: expected ${conversationId ?? "none"}, got ${responseConversationId}.`);
     }
-    const sandboxOptions = this.resolvedSandboxOptions();
     const ttlMinutes = sandboxOptions.ttlMinutes ?? DEFAULT_SANDBOX_TTL_MINUTES;
     const readyTimeoutMs = sandboxOptions.readyTimeoutMs ?? DEFAULT_SANDBOX_READY_TIMEOUT_MS;
     const readyPollIntervalMs = sandboxOptions.readyPollIntervalMs ?? DEFAULT_SANDBOX_READY_POLL_INTERVAL_MS;
@@ -8865,6 +9195,10 @@ class LettaAgentClientBase {
       if (requestTimeoutMs !== undefined && (!Number.isInteger(requestTimeoutMs) || requestTimeoutMs <= 0)) {
         throw new Error("Invalid appServer.requestTimeoutMs. Expected a positive integer.");
       }
+      const idleLingerMs = localOptions.appServer?.idleLingerMs;
+      if (idleLingerMs !== undefined && (!Number.isInteger(idleLingerMs) || idleLingerMs < 0)) {
+        throw new Error("Invalid appServer.idleLingerMs. Expected a non-negative integer.");
+      }
       const startupTimeoutMs = localOptions.appServer?.startupTimeoutMs;
       if (startupTimeoutMs !== undefined && (!Number.isInteger(startupTimeoutMs) || startupTimeoutMs <= 0)) {
         throw new Error("Invalid appServer.startupTimeoutMs. Expected a positive integer.");
@@ -8877,6 +9211,9 @@ class LettaAgentClientBase {
       if (options.requestTimeoutMs !== undefined && (!Number.isInteger(options.requestTimeoutMs) || options.requestTimeoutMs <= 0)) {
         throw new Error("Invalid requestTimeoutMs. Expected a positive integer.");
       }
+      if (options.idleLingerMs !== undefined && (!Number.isInteger(options.idleLingerMs) || options.idleLingerMs < 0)) {
+        throw new Error("Invalid idleLingerMs. Expected a non-negative integer.");
+      }
     }
     if (this.backend === "cloud") {
       validateCloudClientOptions(options);
@@ -8891,7 +9228,7 @@ class LettaAgentClientBase {
     }
     validateCreateAgentOptions(options);
     if (this.backend === "remote") {
-      const session = new AppServerSession(this.remoteOptions(), {
+      const session = new AppServerSession(this.appServerSessionOptions(), {
         kind: "create-agent",
         options
       });
@@ -8914,7 +9251,7 @@ class LettaAgentClientBase {
       if (!agentId) {
         throw new Error("App-server createSession() requires an agent id. Call createAgent() first or pass an agent id.");
       }
-      return new AppServerSession(this.remoteOptions(), {
+      return new AppServerSession(this.appServerSessionOptions(), {
         kind: "session",
         agentId,
         newConversation: true,
@@ -8940,13 +9277,13 @@ class LettaAgentClientBase {
     validateCreateSessionOptions(sessionOptions);
     if (this.backend === "remote") {
       if (looksLikeConversationId(id)) {
-        return new AppServerSession(this.remoteOptions(), {
+        return new AppServerSession(this.appServerSessionOptions(), {
           kind: "session",
           conversationId: id,
           options
         });
       }
-      return new AppServerSession(this.remoteOptions(), {
+      return new AppServerSession(this.appServerSessionOptions(), {
         kind: "session",
         agentId: id,
         defaultConversation: true,
@@ -9045,6 +9382,12 @@ class LettaAgentClientBase {
     }
     return this.options;
   }
+  appServerSessionOptions() {
+    return {
+      ...this.remoteOptions(),
+      beforeConnect: () => this.releaseIdleManagementConnection()
+    };
+  }
   getRepositoriesClient() {
     if (this.backend !== "cloud") {
       throw new Error('client.repositories is only available with backend: "cloud".');
@@ -9052,6 +9395,9 @@ class LettaAgentClientBase {
     this.repositoriesClient ??= new RepositoriesClient(this.cloudOptions());
     return this.repositoriesClient;
   }
+  async releaseIdleManagementConnection() {
+    await this.managementTransport?.releaseIdleConnection?.();
+  }
   getManagementTransport() {
     if (this.managementTransport)
       return this.managementTransport;
@@ -9201,7 +9547,7 @@ ${output.trim()}` : ""}`));
 }
 
 // src/local-app-server-session.ts
-function createLocalAppServerSession(options, mode) {
+function createLocalAppServerSession(options, mode, beforeConnect) {
   const appServer = options ?? {};
   const sessionOptions = {
     ...appServer.url !== undefined ? { url: appServer.url } : {
@@ -9214,7 +9560,8 @@ function createLocalAppServerSession(options, mode) {
     },
     ...appServer.WebSocket !== undefined ? { WebSocket: appServer.WebSocket } : {},
     ...appServer.requestTimeoutMs !== undefined ? { requestTimeoutMs: appServer.requestTimeoutMs } : {},
-    ...appServer.pinGlobalAgent !== undefined ? { pinGlobalAgent: appServer.pinGlobalAgent } : {}
+    ...appServer.pinGlobalAgent !== undefined ? { pinGlobalAgent: appServer.pinGlobalAgent } : {},
+    ...beforeConnect ? { beforeConnect } : {}
   };
   return new AppServerSession(sessionOptions, mode);
 }
@@ -9614,6 +9961,8 @@ class Session {
   _sessionId = null;
   _conversationId = null;
   initialized = false;
+  closed = false;
+  initializePromise = null;
   externalTools = new Map;
   streamQueue = [];
   streamResolvers = [];
@@ -9636,9 +9985,28 @@ class Session {
     }
   }
   async initialize() {
+    if (this.closed) {
+      throw new Error("Session is closed");
+    }
+    if (this.initializePromise) {
+      return this.initializePromise;
+    }
     if (this.initialized) {
       throw new Error("Session already initialized");
     }
+    const attempt = this.performInitialize();
+    const memo = attempt.catch((error) => {
+      this.cleanupFailedInitialize();
+      throw error;
+    }).finally(() => {
+      if (this.initializePromise === memo) {
+        this.initializePromise = null;
+      }
+    });
+    this.initializePromise = memo;
+    return memo;
+  }
+  async performInitialize() {
     sessionLog("init", "connecting transport...");
     await this.transport.connect();
     sessionLog("init", "transport connected, sending initialize request");
@@ -9663,11 +10031,14 @@ class Session {
         this._agentId = initMsg.agent_id;
         this._sessionId = initMsg.session_id;
         this._conversationId = initMsg.conversation_id;
-        this.initialized = true;
-        this.startBackgroundPump();
         if (this.externalTools.size > 0) {
           await this.registerExternalTools();
         }
+        if (this.closed) {
+          throw new Error("Session is closed");
+        }
+        this.initialized = true;
+        this.startBackgroundPump();
         const allTools = [
           ...initMsg.tools,
           ...Array.from(this.externalTools.keys())
@@ -9698,6 +10069,16 @@ ${stderr}` : "";
     sessionLog("init", `ERROR: transport closed before init message received${detail}`);
     throw new Error(`Failed to initialize session - no init message received${detail}`);
   }
+  cleanupFailedInitialize() {
+    this.transport.close();
+    this.closed = true;
+    this.initialized = false;
+    this._agentId = null;
+    this._sessionId = null;
+    this._conversationId = null;
+    this.pumpClosed = true;
+    this.resolveAllStreamWaiters(null);
+  }
   async send(message) {
     if (!this.initialized) {
       sessionLog("send", "auto-initializing (not yet initialized)");
@@ -10374,6 +10755,9 @@ ${stderr}` : "";
     throw new Error("updateToolset() is not supported by this session. Use a Cloud, Remote, or local agent session.");
   }
   close() {
+    if (this.closed)
+      return;
+    this.closed = true;
     sessionLog("close", `closing session (agent=${this._agentId}, conversation=${this._conversationId})`);
     this.transport.close();
     this.pumpClosed = true;
@@ -10571,7 +10955,8 @@ class LettaAgentClient extends LettaAgentClientBase {
         })
       },
       ...localOptions?.WebSocket !== undefined ? { WebSocket: localOptions.WebSocket } : {},
-      ...localOptions?.requestTimeoutMs !== undefined ? { requestTimeoutMs: localOptions.requestTimeoutMs } : {}
+      ...localOptions?.requestTimeoutMs !== undefined ? { requestTimeoutMs: localOptions.requestTimeoutMs } : {},
+      ...localOptions?.idleLingerMs !== undefined ? { idleLingerMs: localOptions.idleLingerMs } : {}
     });
   }
   async createLocalAgent(options) {
@@ -10580,7 +10965,7 @@ class LettaAgentClient extends LettaAgentClientBase {
       const session2 = createLocalAppServerSession(localOptions.appServer, {
         kind: "create-agent",
         options
-      });
+      }, () => this.releaseIdleManagementConnection());
       const initMsg2 = await session2.initialize();
       session2.close();
       return initMsg2.agentId;
@@ -10598,7 +10983,7 @@ class LettaAgentClient extends LettaAgentClientBase {
         agentId,
         newConversation: true,
         options
-      });
+      }, () => this.releaseIdleManagementConnection());
     }
     if (agentId) {
       return new Session({ ...sessionOptions, agentId, newConversation: true });
@@ -10613,14 +10998,14 @@ class LettaAgentClient extends LettaAgentClientBase {
           kind: "session",
           conversationId: id,
           options
-        });
+        }, () => this.releaseIdleManagementConnection());
       }
       return createLocalAppServerSession(localOptions.appServer, {
         kind: "session",
         agentId: id,
         defaultConversation: true,
         options
-      });
+      }, () => this.releaseIdleManagementConnection());
     }
     if (looksLikeConversationId2(id)) {
       return new Session({ ...sessionOptions, conversationId: id });
@@ -10888,4 +11273,4 @@ export {
   CloudManagedSandboxExpiredError
 };
 
-//# debugId=D44861B7D6BE1C4C64756E2164756E21
+//# debugId=01C64A8CE3FD2BF964756E2164756E21