@letta-ai/letta-agent-sdk 0.8.35 → 0.8.37

package/dist/local-app-server-session.d.ts

@@ -1,4 +1,5 @@
 import { AppServerSession, type AppServerSessionMode } from "./app-server-session.js";
+import type { SharedLocalAppServer } from "./shared-local-app-server.js";
 import type { LettaCodeLocalAppServerOptions } from "./types.js";
-export declare function createLocalAppServerSession(options: LettaCodeLocalAppServerOptions | undefined, mode: AppServerSessionMode): AppServerSession;
+export declare function createLocalAppServerSession(options: LettaCodeLocalAppServerOptions | undefined, mode: AppServerSessionMode, sharedServer?: SharedLocalAppServer): AppServerSession;
 //# sourceMappingURL=local-app-server-session.d.ts.map

package/dist/local-app-server-session.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"local-app-server-session.d.ts","sourceRoot":"","sources":["../src/local-app-server-session.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAChB,KAAK,oBAAoB,EAE1B,MAAM,yBAAyB,CAAC;AAEjC,OAAO,KAAK,EAEV,8BAA8B,EAC/B,MAAM,YAAY,CAAC;AAEpB,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,8BAA8B,GAAG,SAAS,EACnD,IAAI,EAAE,oBAAoB,GACzB,gBAAgB,CAsClB"}
+{"version":3,"file":"local-app-server-session.d.ts","sourceRoot":"","sources":["../src/local-app-server-session.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAChB,KAAK,oBAAoB,EAE1B,MAAM,yBAAyB,CAAC;AAEjC,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AACzE,OAAO,KAAK,EAEV,8BAA8B,EAC/B,MAAM,YAAY,CAAC;AAEpB,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,8BAA8B,GAAG,SAAS,EACnD,IAAI,EAAE,oBAAoB,EAC1B,YAAY,CAAC,EAAE,oBAAoB,GAClC,gBAAgB,CAyClB"}

package/dist/local-app-server.d.ts

@@ -1,6 +1,7 @@
 import { type MemoryConfinementLauncherInput, type MemoryConfinementLauncherResult } from "@letta-ai/letta-code/memory-confinement";
 export interface LocalAppServerHandle {
     url: string;
+    isRunning(): boolean;
     close(): void;
 }
 export interface StartLocalAppServerOptions {

package/dist/local-app-server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"local-app-server.d.ts","sourceRoot":"","sources":["../src/local-app-server.ts"],"names":[],"mappings":"AAGA,OAAO,EAEL,KAAK,8BAA8B,EACnC,KAAK,+BAA+B,EACrC,MAAM,yCAAyC,CAAC;AAGjD,MAAM,WAAW,oBAAoB;IACnC,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,IAAI,IAAI,CAAC;CACf;AAED,MAAM,WAAW,0BAA0B;IACzC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACzC,qBAAqB,CAAC,EAAE,QAAQ,CAAC;IACjC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,UAAU,qBAAqB;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;CACxB;AAED,KAAK,yBAAyB,GAAG,CAC/B,KAAK,EAAE,8BAA8B,KAClC,+BAA+B,CAAC;AA6DrC,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,IAAI,CAAC,0BAA0B,EAAE,SAAS,GAAG,QAAQ,CAAM,GACnE,MAAM,EAAE,CAQV;AAED,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,0BAA+B,EACxC,aAAa,GAAE,yBAA2D,GACzE,qBAAqB,CAgCvB;AAYD;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,GAAE,0BAA+B,GACvC,OAAO,CAAC,oBAAoB,CAAC,CA+E/B"}
+{"version":3,"file":"local-app-server.d.ts","sourceRoot":"","sources":["../src/local-app-server.ts"],"names":[],"mappings":"AAGA,OAAO,EAEL,KAAK,8BAA8B,EACnC,KAAK,+BAA+B,EACrC,MAAM,yCAAyC,CAAC;AAGjD,MAAM,WAAW,oBAAoB;IACnC,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,IAAI,OAAO,CAAC;IACrB,KAAK,IAAI,IAAI,CAAC;CACf;AAED,MAAM,WAAW,0BAA0B;IACzC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACzC,qBAAqB,CAAC,EAAE,QAAQ,CAAC;IACjC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,UAAU,qBAAqB;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;CACxB;AAED,KAAK,yBAAyB,GAAG,CAC/B,KAAK,EAAE,8BAA8B,KAClC,+BAA+B,CAAC;AA6DrC,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,IAAI,CAAC,0BAA0B,EAAE,SAAS,GAAG,QAAQ,CAAM,GACnE,MAAM,EAAE,CAQV;AAED,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,0BAA+B,EACxC,aAAa,GAAE,yBAA2D,GACzE,qBAAqB,CAgCvB;AAYD;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,GAAE,0BAA+B,GACvC,OAAO,CAAC,oBAAoB,CAAC,CAgF/B"}

package/dist/shared-local-app-server.d.ts

@@ -0,0 +1,13 @@
+import { type LocalAppServerHandle, type StartLocalAppServerOptions } from "./local-app-server.js";
+/** One lazily started process owned by a local SDK client, not its sessions. */
+export declare class SharedLocalAppServer {
+    private readonly options;
+    private starting;
+    private server;
+    private closed;
+    private closing;
+    constructor(options: StartLocalAppServerOptions);
+    connect(): Promise<LocalAppServerHandle>;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=shared-local-app-server.d.ts.map

package/dist/shared-local-app-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared-local-app-server.d.ts","sourceRoot":"","sources":["../src/shared-local-app-server.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,oBAAoB,EACzB,KAAK,0BAA0B,EAChC,MAAM,uBAAuB,CAAC;AAE/B,gFAAgF;AAChF,qBAAa,oBAAoB;IAMnB,OAAO,CAAC,QAAQ,CAAC,OAAO;IALpC,OAAO,CAAC,QAAQ,CAA8C;IAC9D,OAAO,CAAC,MAAM,CAAqC;IACnD,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,OAAO,CAA8B;gBAEhB,OAAO,EAAE,0BAA0B;IAE1D,OAAO,IAAI,OAAO,CAAC,oBAAoB,CAAC;IAiC9C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAQvB"}

package/dist/tests/fixtures/shared-app-server-client.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=shared-app-server-client.d.ts.map

package/dist/tests/fixtures/shared-app-server-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared-app-server-client.d.ts","sourceRoot":"","sources":["../../../src/tests/fixtures/shared-app-server-client.ts"],"names":[],"mappings":""}

package/dist/types.d.ts

@@ -491,11 +491,11 @@ export interface LettaCodeClientSessionOptions extends CreateSessionOptions {
     /** Per-session SDK-managed sandbox options when no computer is selected. */
     sandbox?: LettaCodeCloudSandboxOptions;
     /**
-     * Extra environment variables for the session's harness process. Each
-     * SDK-owned local app-server session runs in its own process, so this
-     * scopes cleanly per session — e.g. MEMORY_DIR / LETTA_MEMORY_DIR to point
-     * the harness's memory scoping (and its guard) at a session-specific
-     * memory copy. Ignored on remote and cloud transports.
+     * Extra environment variables for the session's harness process. Nonempty
+     * overrides use a dedicated process rather than the client's shared server,
+     * so MEMORY_DIR / LETTA_MEMORY_DIR can select a session-specific memory copy.
+     * Close these independently owned sessions separately from the client.
+     * Ignored on remote and cloud transports.
      */
     env?: Record<string, string>;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@letta-ai/letta-agent-sdk",
-  "version": "0.8.35",
+  "version": "0.8.37",
   "packageManager": "bun@1.3.14",
   "description": "SDK for programmatic control of Letta agents",
   "type": "module",
@@ -40,7 +40,7 @@
   },
   "dependencies": {
     "@letta-ai/letta-client": "^1.12.1",
-    "@letta-ai/letta-code": "0.34.8",
+    "@letta-ai/letta-code": "0.34.9",
     "ajv": "^8.20.0"
   },
   "devDependencies": {

package/src/client-base.ts

@@ -742,8 +742,8 @@ export class LettaAgentClientBase implements AsyncDisposable {
 
   /**
    * Release resources owned directly by this client, including its pooled
-   * management connection and any local App Server started for that pool.
-   * Sessions have independent lifecycles and must be closed separately.
+   * management connection. The Node client also stops its shared local App
+   * Server; dedicated and externally hosted sessions remain independently owned.
    */
   close(): Promise<void> {
     if (this.closePromise) return this.closePromise;

package/src/client.ts

@@ -2,7 +2,7 @@ import { LettaAgentClientBase } from "./client-base.js";
 import { AppServerManagementTransport } from "./app-server-management.js";
 import type { ManagementTransport } from "./management.js";
 import { createLocalAppServerSession } from "./local-app-server-session.js";
-import { startLocalAppServer } from "./local-app-server.js";
+import { SharedLocalAppServer } from "./shared-local-app-server.js";
 import type { QueryOptions } from "./query-types.js";
 import type { SkillNodeSupport } from "./skill-loading.js";
 import { loadSkillDirectory, pushSkillSupportFiles } from "./skill-node.js";
@@ -14,6 +14,29 @@ import type {
 } from "./types.js";
 
 export class LettaAgentClient extends LettaAgentClientBase {
+  private localServer: SharedLocalAppServer | null = null;
+  private localClosePromise: Promise<void> | null = null;
+
+  private sharedLocalServer(): SharedLocalAppServer {
+    if (this.localClosePromise) throw new Error("LettaAgentClient is closed");
+    const options = (this.options as LettaCodeLocalClientOptions).appServer;
+    return this.localServer ??= new SharedLocalAppServer({
+      listen: options?.listen,
+      backend: options?.harnessBackend ?? "local",
+      startupTimeoutMs: options?.startupTimeoutMs,
+    });
+  }
+
+  override close(): Promise<void> {
+    if (!this.localClosePromise) {
+      this.localClosePromise = Promise.all([
+        super.close(),
+        this.localServer?.close(),
+      ]).then(() => {});
+    }
+    return this.localClosePromise;
+  }
+
   protected override skillNodeSupport(): SkillNodeSupport {
     return { loadSkillDirectory, pushSkillSupportFiles };
   }
@@ -22,16 +45,12 @@ export class LettaAgentClient extends LettaAgentClientBase {
     const localOptions = (
       this.options as LettaCodeLocalClientOptions
     ).appServer;
+    const sharedServer = this.sharedLocalServer();
     return new AppServerManagementTransport({
       ...(localOptions?.url !== undefined
         ? { url: localOptions.url }
         : {
-            connect: () =>
-              startLocalAppServer({
-                listen: localOptions?.listen,
-                backend: localOptions?.harnessBackend ?? "local",
-                startupTimeoutMs: localOptions?.startupTimeoutMs,
-              }),
+            connect: () => sharedServer.connect(),
           }),
       ...(localOptions?.WebSocket !== undefined
         ? { WebSocket: localOptions.WebSocket }
@@ -52,13 +71,17 @@ export class LettaAgentClient extends LettaAgentClientBase {
         kind: "create-agent",
         options,
       },
+      this.sharedLocalServer(),
     );
-    const initMsg = await session.initialize();
-    session.close();
-    if (!initMsg.agentId) {
-      throw new Error("Local App Server agent creation did not return an agent id.");
+    try {
+      const initMsg = await session.initialize();
+      if (!initMsg.agentId) {
+        throw new Error("Local App Server agent creation did not return an agent id.");
+      }
+      return initMsg.agentId;
+    } finally {
+      session.close();
     }
-    return initMsg.agentId;
   }
 
   protected override createLocalSession(
@@ -74,6 +97,7 @@ export class LettaAgentClient extends LettaAgentClientBase {
         newConversation: true,
         options,
       },
+      this.sharedLocalServer(),
     );
   }
 
@@ -109,7 +133,7 @@ export class LettaAgentClient extends LettaAgentClientBase {
       ...(queryOptions.disableMemoryGuard === true
         ? { disableMemoryGuard: true }
         : {}),
-    });
+    }, this.sharedLocalServer());
   }
 
   protected override resumeLocalSession(
@@ -125,6 +149,7 @@ export class LettaAgentClient extends LettaAgentClientBase {
           conversationId: id,
           options,
         },
+        this.sharedLocalServer(),
       );
     }
     return createLocalAppServerSession(
@@ -135,6 +160,7 @@ export class LettaAgentClient extends LettaAgentClientBase {
         defaultConversation: true,
         options,
       },
+      this.sharedLocalServer(),
     );
   }
 }

package/src/index.ts

@@ -253,7 +253,33 @@ export {
  */
 export async function createAgent(options: CreateAgentOptions = {}): Promise<string> {
   validateCreateAgentOptions(options);
-  return new LettaAgentClient().createAgent(options);
+  const client = new LettaAgentClient();
+  try {
+    return await client.createAgent(options);
+  } finally {
+    await client.close();
+  }
+}
+
+/** Convenience sessions own their otherwise inaccessible client as well. */
+function ownSession(client: LettaAgentClient, session: LettaCodeSession): LettaCodeSession {
+  const close = session.close.bind(session);
+  const dispose = session[Symbol.asyncDispose].bind(session);
+  session.close = () => {
+    try {
+      close();
+    } finally {
+      void client.close();
+    }
+  };
+  session[Symbol.asyncDispose] = async () => {
+    try {
+      await dispose();
+    } finally {
+      await client.close();
+    }
+  };
+  return session;
 }
 
 /**
@@ -272,7 +298,8 @@ export function createSession(
   options: CreateSessionOptions = {},
 ): LettaCodeSession {
   validateCreateSessionOptions(options);
-  return new LettaAgentClient().createSession(agentId, options);
+  const client = new LettaAgentClient();
+  return ownSession(client, client.createSession(agentId, options));
 }
 
 /**
@@ -298,7 +325,8 @@ export function resumeSession(
   options: CreateSessionOptions = {},
 ): LettaCodeSession {
   validateCreateSessionOptions(options);
-  return new LettaAgentClient().resumeSession(id, options);
+  const client = new LettaAgentClient();
+  return ownSession(client, client.resumeSession(id, options));
 }
 
 /**
@@ -338,10 +366,29 @@ export async function prompt(
 
 /** Run a query in a new ordinary conversation. */
 export function query(params: QueryParams): Query {
-  return new LettaAgentClient({
+  const client = new LettaAgentClient({
     backend: "local",
     appServer: { harnessBackend: "api" },
-  }).query(params);
+  });
+  const inner = client.query(params);
+  const result = (async function* () {
+    try {
+      yield* inner;
+    } finally {
+      await client.close();
+    }
+  })();
+  return Object.defineProperties(Object.assign(result, {
+    interrupt: () => inner.interrupt(),
+    close() {
+      inner.close();
+      void client.close();
+      void result.return();
+    },
+  }), {
+    conversationId: { get: () => inner.conversationId, enumerable: true },
+    agentId: { get: () => inner.agentId, enumerable: true },
+  }) as Query;
 }
 
 // ═══════════════════════════════════════════════════════════════
@@ -383,11 +430,11 @@ export async function listMessagesDirect(
 ): Promise<ListMessagesResult> {
   // resumeSession uses --default which maps to the agent's default conversation.
   // The session is transient: we only need it long enough to list messages.
-  const session = new LettaAgentClient().resumeSession(agentId, {
+  const session = resumeSession(agentId, {
     permissionMode: "unrestricted",
   });
-  await (session as InitializableSession).initialize();
   try {
+    await (session as InitializableSession).initialize();
     return await session.listMessages(options);
   } finally {
     session.close();

package/src/local-app-server-session.ts

@@ -4,6 +4,7 @@ import {
   type AppServerSessionOptions,
 } from "./app-server-session.js";
 import { startLocalAppServer } from "./local-app-server.js";
+import type { SharedLocalAppServer } from "./shared-local-app-server.js";
 import type {
   LettaCodeClientSessionOptions,
   LettaCodeLocalAppServerOptions,
@@ -12,8 +13,12 @@ import type {
 export function createLocalAppServerSession(
   options: LettaCodeLocalAppServerOptions | undefined,
   mode: AppServerSessionMode,
+  sharedServer?: SharedLocalAppServer,
 ): AppServerSession {
   const appServer = options ?? {};
+  const session = mode.options as LettaCodeClientSessionOptions;
+  const needsOwnProcess = session.filesystemConfinement === "memory" ||
+    Object.keys(session.env ?? {}).length > 0;
   const sessionOptions: AppServerSessionOptions = {
     ...(mode.kind === "conversation" &&
     (appServer.harnessBackend ?? "local") === "local"
@@ -23,7 +28,7 @@ export function createLocalAppServerSession(
       ? { url: appServer.url }
       : {
           connect: (sessionEnv?: Record<string, string>) =>
-            startLocalAppServer({
+            sharedServer && !needsOwnProcess ? sharedServer.connect() : startLocalAppServer({
               listen: appServer.listen,
               backend: appServer.harnessBackend ?? "local",
               startupTimeoutMs: appServer.startupTimeoutMs,

package/src/local-app-server.ts

@@ -10,6 +10,7 @@ import { findLettaCli } from "./cli-resolver.js";
 
 export interface LocalAppServerHandle {
   url: string;
+  isRunning(): boolean;
   close(): void;
 }
 
@@ -194,6 +195,7 @@ export function startLocalAppServer(
       cleanup();
       resolve({
         url,
+        isRunning: () => child.exitCode === null && child.signalCode === null,
         close: () => terminateProcess(child),
       });
     };

package/src/shared-local-app-server.ts

@@ -0,0 +1,57 @@
+import {
+  startLocalAppServer,
+  type LocalAppServerHandle,
+  type StartLocalAppServerOptions,
+} from "./local-app-server.js";
+
+/** One lazily started process owned by a local SDK client, not its sessions. */
+export class SharedLocalAppServer {
+  private starting: Promise<LocalAppServerHandle> | null = null;
+  private server: LocalAppServerHandle | null = null;
+  private closed = false;
+  private closing: Promise<void> | null = null;
+
+  constructor(private readonly options: StartLocalAppServerOptions) {}
+
+  async connect(): Promise<LocalAppServerHandle> {
+    if (this.closed) throw new Error("Local App Server owner is closed");
+    // A later call can replace an exited process; never replay a failed turn.
+    if (this.server && !this.server.isRunning()) {
+      this.server = null;
+      this.starting = null;
+    }
+    if (!this.starting) {
+      this.starting = startLocalAppServer(this.options).then(
+        (server) => {
+          if (this.closed) {
+            server.close();
+            throw new Error("Local App Server owner closed during startup");
+          }
+          this.server = server;
+          return server;
+        },
+        (error: unknown) => {
+          this.starting = null;
+          throw error;
+        },
+      );
+    }
+    const server = await this.starting;
+    if (this.closed) throw new Error("Local App Server owner is closed");
+    return {
+      url: server.url,
+      isRunning: server.isRunning,
+      // Session/management disposal releases only its socket, not the process.
+      close() {},
+    };
+  }
+
+  close(): Promise<void> {
+    if (this.closing) return this.closing;
+    this.closed = true;
+    this.closing = this.starting
+      ? this.starting.then((server) => server.close(), () => {})
+      : Promise.resolve();
+    return this.closing;
+  }
+}

package/src/types.ts

@@ -686,11 +686,11 @@ export interface LettaCodeClientSessionOptions extends CreateSessionOptions {
   /** Per-session SDK-managed sandbox options when no computer is selected. */
   sandbox?: LettaCodeCloudSandboxOptions;
   /**
-   * Extra environment variables for the session's harness process. Each
-   * SDK-owned local app-server session runs in its own process, so this
-   * scopes cleanly per session — e.g. MEMORY_DIR / LETTA_MEMORY_DIR to point
-   * the harness's memory scoping (and its guard) at a session-specific
-   * memory copy. Ignored on remote and cloud transports.
+   * Extra environment variables for the session's harness process. Nonempty
+   * overrides use a dedicated process rather than the client's shared server,
+   * so MEMORY_DIR / LETTA_MEMORY_DIR can select a session-specific memory copy.
+   * Close these independently owned sessions separately from the client.
+   * Ignored on remote and cloud transports.
    */
   env?: Record<string, string>;
   /**