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

package/src/app-server-management.ts

@@ -3,7 +3,6 @@ import {
   type AppServerClient,
   type AppServerRequestCommandWithId,
   type AppServerSocketConstructor,
-  type AppServerSocketLike,
 } from "@letta-ai/letta-code/app-server-client";
 import type {
   ManagementQuery,
@@ -59,92 +58,14 @@ export type AppServerManagementOptions =
   Partial<LettaCodeRemoteClientOptions> & {
     url?: string;
     connect?: () => Promise<OwnedConnection>;
-    /**
-     * How long (in milliseconds) an idle control connection lingers before it
-     * is released. Defaults to {@link DEFAULT_IDLE_LINGER_MS}.
-     */
-    idleLingerMs?: number;
   };
 
-/**
- * How long an idle control connection lingers before it is released.
- *
- * Long enough to batch a burst of management calls (for example a screen
- * fetching a list plus a retrieve together) over one connection, short enough
- * that the app-server's single control-client slot frees up quickly for
- * sessions.
- */
-const DEFAULT_IDLE_LINGER_MS = 250;
-
 type ActiveConnection = {
   client: AppServerClient;
   ownedConnection: OwnedConnection | null;
   detachDisconnect: () => void;
-  unregister: () => void;
-};
-
-type RegisteredManagementTransport = {
-  releaseIdleConnection(): Promise<void>;
-};
-
-type ManagementTransportRegistration = {
-  transport: RegisteredManagementTransport;
 };
 
-const registeredTransportsByUrl =
-  new Map<string, Set<ManagementTransportRegistration>>();
-
-function appServerUrlKey(value: string): string {
-  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: string,
-  transport: RegisteredManagementTransport,
-): () => void {
-  const key = appServerUrlKey(url);
-  const registration = { transport };
-  const transports =
-    registeredTransportsByUrl.get(key) ??
-    new Set<ManagementTransportRegistration>();
-  transports.add(registration);
-  registeredTransportsByUrl.set(key, transports);
-  return () => {
-    transports.delete(registration);
-    if (transports.size === 0) {
-      registeredTransportsByUrl.delete(key);
-    }
-  };
-}
-
-/**
- * Wait for every management transport targeting this app-server to release
- * its control connection. The registry is process-wide so a session created
- * by a different `LettaAgentClient` instance can still take the server's
- * single control slot safely.
- */
-export async function releaseAppServerManagementConnections(
-  url: string,
-): Promise<void> {
-  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<T>(
   response: { success: boolean; error?: string },
   value: T | null | undefined,
@@ -192,40 +113,17 @@ function stringRecord(value: unknown): Record<string, string> | undefined {
 /**
  * Management transport that speaks the app-server control protocol.
  *
- * Connection lifecycle: the Letta Code app-server currently accepts a single
- * control client at a time — while one control socket is attached, additional
- * control sockets are rejected with close code 1008
- * `"control channel already connected"` (see letta-ai/letta-code
- * `src/websocket/app-server.ts`). Sessions (`AppServerSession`) need that same
- * control slot, so a management transport that holds an idle connection
- * starves any later `resumeSession()`/`createSession()` from the same process
- * (live-reproduced in the letta-mobile reference app, SDK-FEEDBACK.md #00).
- *
- * To stay out of the way, this transport pools a single lazily-connected
- * client while requests are in flight (bursts share one connection and one
- * request-id counter, so responses correlate correctly), then releases the
- * connection shortly after it goes idle ({@link DEFAULT_IDLE_LINGER_MS}) and
- * reconnects lazily on the next request. Before a session connects, all
- * management transports registered for the same app-server URL relinquish
- * their connections; the handoff waits for in-flight work and for the control
- * socket's close event. The inverse contention — a management request issued
- * while a session holds the control slot — cannot be solved client-side and
- * still fails until the app-server allows multiple control clients.
+ * The app-server assigns every client an independent connection, so management
+ * keeps one lazy pooled client while sessions connect alongside it. Unexpected
+ * disconnects discard the pool and the next management request reconnects.
  */
 export class AppServerManagementTransport
   implements ManagementTransport
 {
   private connectionPromise: Promise<ActiveConnection> | null = null;
-  private releasePromise: Promise<void> | null = null;
   private closingConnections = new Set<Promise<void>>();
-  private inFlightRequests = 0;
-  private idleWaiters = new Set<() => void>();
-  private idleTimer: ReturnType<typeof setTimeout> | null = null;
-  private readonly idleLingerMs: number;
 
-  constructor(private readonly options: AppServerManagementOptions) {
-    this.idleLingerMs = options.idleLingerMs ?? DEFAULT_IDLE_LINGER_MS;
-  }
+  constructor(private readonly options: AppServerManagementOptions) {}
 
   async listAgents(query: ManagementQuery): Promise<LettaAgent[]> {
     const response = await this.request<AgentListResponse>(
@@ -384,97 +282,28 @@ export class AppServerManagementTransport
     return { messages: response.messages };
   }
 
-  /**
-   * Release the pooled control connection instead of waiting out the idle
-   * linger. If requests are in flight, wait for them to settle first.
-   *
-   * The app-server accepts a single control client (see the class docs), so
-   * This is called before opening a session to hand the control slot over
-   * without a linger-sized or socket-close race window.
-   */
-  releaseIdleConnection(): Promise<void> {
-    this.clearIdleTimer();
-    if (this.releasePromise) return this.releasePromise;
-
-    const release = this.releaseConnectionWhenIdle();
-    this.releasePromise = release;
-    void release.then(
-      () => {
-        if (this.releasePromise === release) {
-          this.releasePromise = null;
-        }
-      },
-      () => {
-        if (this.releasePromise === release) {
-          this.releasePromise = null;
-        }
-      },
-    );
-    return release;
-  }
-
   private async request<TResponse extends { type: string }>(
     type: string,
     body: Record<string, unknown>,
     responseType: string,
   ): Promise<TResponse> {
-    if (this.releasePromise) {
-      await this.releasePromise;
-    }
     if (this.closingConnections.size > 0) {
       await Promise.all([...this.closingConnections]);
     }
-    this.clearIdleTimer();
-    this.inFlightRequests += 1;
-    try {
-      // Concurrent requests share the pooled connection (queueing behind the
-      // same connect promise) and its request-id counter, so correlation is
-      // stable across a burst and across reconnects: a fresh connection gets a
-      // fresh client whose pending map starts empty.
-      const { client } = await this.acquireConnection();
-      const command = {
-        type,
-        request_id: client.nextRequestId(type),
-        ...body,
-      } as AppServerRequestCommandWithId;
-      const response = await client.request(command, {
-        predicate: (message): message is typeof message =>
-          message.type === responseType,
-      });
-      return response as unknown as TResponse;
-    } 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();
-        }
-      }
-    }
-  }
-
-  private async releaseConnectionWhenIdle(): Promise<void> {
-    if (this.inFlightRequests > 0) {
-      await new Promise<void>((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 {
-      // A failed connect already closes its partially-created resources.
-    }
+    // Concurrent requests share the same connect promise and request-id
+    // counter, while connection identity keeps this pool independent from
+    // session clients using the same app-server.
+    const { client } = await this.acquireConnection();
+    const command = {
+      type,
+      request_id: client.nextRequestId(type),
+      ...body,
+    } as AppServerRequestCommandWithId;
+    const response = await client.request(command, {
+      predicate: (message): message is typeof message =>
+        message.type === responseType,
+    });
+    return response as unknown as TResponse;
   }
 
   private acquireConnection(): Promise<ActiveConnection> {
@@ -507,7 +336,6 @@ export class AppServerManagementTransport
     if (!url) {
       throw new Error("App-server management requires a url or connect hook.");
     }
-    const unregister = registerManagementTransport(url, this);
 
     let client: AppServerClient | null = null;
     try {
@@ -530,17 +358,13 @@ export class AppServerManagementTransport
     } catch (error) {
       try {
         if (client) {
-          const controlClosed = waitForSocketClose(client.control);
           client.close();
           ownedConnection?.close();
-          await controlClosed;
         } else {
           ownedConnection?.close();
         }
       } catch {
         // Preserve the original connect error after best-effort cleanup.
-      } finally {
-        unregister();
       }
       throw error;
     }
@@ -548,7 +372,6 @@ export class AppServerManagementTransport
       client,
       ownedConnection,
       detachDisconnect: () => {},
-      unregister,
     };
   }
 
@@ -558,7 +381,6 @@ export class AppServerManagementTransport
   ): void {
     if (this.connectionPromise === promise) {
       this.connectionPromise = null;
-      this.clearIdleTimer();
     }
     void this.trackClosingConnection(connection);
   }
@@ -574,68 +396,10 @@ export class AppServerManagementTransport
     );
     return closing;
   }
-
-  private scheduleIdleRelease(): void {
-    if (!this.connectionPromise) return;
-    this.clearIdleTimer();
-    const timer = setTimeout(() => {
-      this.idleTimer = null;
-      this.releaseIdleConnection();
-    }, this.idleLingerMs);
-    this.idleTimer = timer;
-    // Do not keep a Node event loop alive just for the linger.
-    (timer as unknown as { unref?: () => void }).unref?.();
-  }
-
-  private clearIdleTimer(): void {
-    if (this.idleTimer === null) return;
-    clearTimeout(this.idleTimer);
-    this.idleTimer = null;
-  }
 }
 
 async function closeConnection(connection: ActiveConnection): Promise<void> {
   connection.detachDisconnect();
-  const controlClosed = waitForSocketClose(connection.client.control);
-  try {
-    connection.client.close();
-    connection.ownedConnection?.close();
-    await controlClosed;
-  } finally {
-    connection.unregister();
-  }
-}
-
-function waitForSocketClose(socket: AppServerSocketLike): Promise<void> {
-  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, 1_000);
-    (timeout as unknown as { unref?: () => void }).unref?.();
-    if (socket.readyState === 3) finish();
-  });
+  connection.client.close();
+  connection.ownedConnection?.close();
 }

package/src/app-server-session.ts

@@ -10,7 +10,6 @@ import {
   GIT_MEMORY_ENABLED_TAG,
   LETTA_CODE_ORIGIN_TAG,
 } from "@letta-ai/letta-code/agent-presets";
-import { releaseAppServerManagementConnections } from "./app-server-management.js";
 import {
   buildCanUseToolContext,
   isHeadlessAutoAllowTool,
@@ -127,11 +126,6 @@ export type AppServerSessionOptions = Partial<LettaCodeRemoteClientOptions> & {
   connect?: (
     sessionEnv?: Record<string, string>,
   ) => Promise<{ url: string; close(): void }>;
-  /**
-   * Internal handoff hook used to release a management connection owned by
-   * the same SDK client before this session opens its control socket.
-   */
-  beforeConnect?: () => Promise<void>;
   /** Whether SDK create-agent payloads should add the origin tag automatically. */
   includeSdkOriginTag?: boolean;
 };
@@ -165,30 +159,6 @@ function assertRemoteCreateAgentOptionsSupported(options: CreateAgentOptions): v
   }
 }
 
-export function assertRemoteSessionOptionsSupported(
-  action: string,
-  options: LettaCodeClientSessionOptions,
-): void {
-  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 as { memfsStartup?: unknown }).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: Record<string, unknown>): Record<string, unknown> {
   const normalized = { ...block };
   if (normalized.value === undefined && typeof normalized.content === "string") {
@@ -771,9 +741,7 @@ export class AppServerSession extends RemoteClientSessionCore {
   }
 
   protected override async initializeRuntimeController(): Promise<RuntimeSessionInit> {
-    await this.remoteOptions.beforeConnect?.();
     const url = await this.resolveAppServerUrl();
-    await releaseAppServerManagementConnections(url);
     const client = applyUniqueRequestIds(createAppServerClient({
       url,
       ...(this.remoteOptions.authToken !== undefined