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

package/src/client-base.ts

@@ -2,7 +2,6 @@ import { RepositoriesClient } from "./repositories.js";
 import { AppServerManagementTransport } from "./app-server-management.js";
 import {
   AppServerSession,
-  assertRemoteSessionOptionsSupported,
   type AppServerSessionOptions,
 } from "./app-server-session.js";
 import { CloudManagementTransport } from "./cloud-management.js";
@@ -67,6 +66,7 @@ function stripCloudExecutionOptions(
   const sessionOptions = { ...options };
   delete sessionOptions.environment;
   delete sessionOptions.sandbox;
+  delete sessionOptions.filesystemConfinement;
   return sessionOptions;
 }
 
@@ -91,7 +91,7 @@ type TurnSession = LettaCodeSession & {
  *
  * `backend` selects how the SDK reaches or runs the Letta Code harness.
  * `local` spawns an SDK-owned Letta Code app-server and speaks the websocket
- * protocol by default, with an explicit stdio fallback for legacy flows.
+ * protocol.
  * `remote` connects to a user-managed Letta Code app-server websocket endpoint.
  * `cloud` uses agents hosted on Letta Cloud, with an explicit remote
  * environment or SDK-managed sandbox.
@@ -139,12 +139,10 @@ export class LettaAgentClientBase {
 
     if (this.backend === "local") {
       const localOptions = options as LettaCodeLocalClientOptions;
-      if (
-        localOptions.transport !== undefined &&
-        localOptions.transport !== "app-server" &&
-        localOptions.transport !== "stdio"
-      ) {
-        throw new Error("Invalid local transport. Valid values: app-server, stdio.");
+      if ("transport" in localOptions) {
+        throw new Error(
+          'Local transport selection has been removed. The local backend always uses the app-server protocol.',
+        );
       }
       const requestTimeoutMs = localOptions.appServer?.requestTimeoutMs;
       if (
@@ -153,13 +151,6 @@ export class LettaAgentClientBase {
       ) {
         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 &&
@@ -179,12 +170,6 @@ export class LettaAgentClientBase {
       ) {
         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") {
@@ -229,49 +214,36 @@ export class LettaAgentClientBase {
   /**
    * Create a new conversation/session.
    *
-   * Without an agent id, this uses the default/LRU agent, matching the legacy
-   * top-level createSession() helper.
+   * The app-server protocol requires an explicit agent id.
    */
   createSession(
-    agentIdOrOptions?: string | LettaCodeClientSessionOptions,
+    agentId: string,
     options: LettaCodeClientSessionOptions = {},
   ): LettaCodeSession {
-    const agentId =
-      typeof agentIdOrOptions === "string" ? agentIdOrOptions : undefined;
-    const resolvedOptions =
-      typeof agentIdOrOptions === "string" ? options : (agentIdOrOptions ?? {});
-
-    this.assertSessionBackend("createSession", resolvedOptions);
-    const sessionOptions = stripCloudExecutionOptions(resolvedOptions);
+    if (typeof agentId !== "string" || agentId.length === 0) {
+      throw new Error("createSession() requires a non-empty agent id.");
+    }
+    const sessionOptions = stripCloudExecutionOptions(options);
     validateCreateSessionOptions(sessionOptions);
+    this.assertSessionBackend("createSession", options);
 
     if (this.backend === "remote") {
-      if (!agentId) {
-        throw new Error(
-          "App-server createSession() requires an agent id. Call createAgent() first or pass an agent id.",
-        );
-      }
       return new AppServerSession(this.appServerSessionOptions(), {
         kind: "session",
         agentId,
         newConversation: true,
-        options: resolvedOptions,
+        options,
       });
     }
     if (this.backend === "cloud") {
-      if (!agentId) {
-        throw new Error(
-          "Letta Cloud createSession() requires an agent id. Call createAgent() first or pass an agent id.",
-        );
-      }
       return new CloudEnvironmentSession(this.cloudOptions(), {
         kind: "session",
         agentId,
         newConversation: true,
-        options: resolvedOptions,
+        options,
       });
     }
-    return this.createLocalSession(agentId, resolvedOptions, sessionOptions);
+    return this.createLocalSession(agentId, options);
   }
 
   /**
@@ -284,9 +256,9 @@ export class LettaAgentClientBase {
     id: string,
     options: LettaCodeClientSessionOptions = {},
   ): LettaCodeSession {
-    this.assertSessionBackend("resumeSession", options);
     const sessionOptions = stripCloudExecutionOptions(options);
     validateCreateSessionOptions(sessionOptions);
+    this.assertSessionBackend("resumeSession", options);
 
     if (this.backend === "remote") {
       if (looksLikeConversationId(id)) {
@@ -318,18 +290,16 @@ export class LettaAgentClientBase {
         options,
       });
     }
-    return this.resumeLocalSession(id, options, sessionOptions);
+    return this.resumeLocalSession(id, options);
   }
 
   /** One-shot prompt convenience helper using a new conversation. */
   async prompt(
     message: SendMessage,
-    agentId?: string,
+    agentId: string,
     options: LettaCodeClientSessionOptions = {},
   ): Promise<SDKResultMessage> {
-    const session = agentId
-      ? this.createSession(agentId, options)
-      : this.createSession(options);
+    const session = this.createSession(agentId, options);
 
     try {
       return await (session as TurnSession).runTurn(message);
@@ -342,6 +312,14 @@ export class LettaAgentClientBase {
     action: string,
     options: LettaCodeClientSessionOptions,
   ): void {
+    if (
+      options.filesystemConfinement !== undefined &&
+      options.filesystemConfinement !== "memory"
+    ) {
+      throw new Error(
+        `Invalid filesystemConfinement '${String(options.filesystemConfinement)}'. Valid value: memory.`,
+      );
+    }
     const effectiveEnvironment = options.environment ?? this.environment;
     if (this.backend === "local") {
       if (effectiveEnvironment !== undefined) {
@@ -355,13 +333,23 @@ export class LettaAgentClientBase {
       if (hasRepositoryResources(options)) {
         throw new Error(`${action}() repository resources are only valid with backend: "cloud".`);
       }
-      if (!this.useLegacyLocalStdio()) {
-        assertRemoteSessionOptionsSupported(action, options);
+      if (options.filesystemConfinement !== undefined) {
+        const localOptions = this.options as LettaCodeLocalClientOptions;
+        if (localOptions.appServer?.url !== undefined) {
+          throw new Error(
+            `${action}() filesystemConfinement requires an SDK-owned local app-server process.`,
+          );
+        }
       }
       return;
     }
 
     if (this.backend === "remote") {
+      if (options.filesystemConfinement !== undefined) {
+        throw new Error(
+          `${action}() filesystemConfinement requires an SDK-owned local app-server process.`,
+        );
+      }
       if (options.environment !== undefined) {
         throw new Error(
           `${action}() environment overrides are only valid with backend: "cloud"; remote url selects the app-server runtime.`,
@@ -373,10 +361,14 @@ export class LettaAgentClientBase {
       if (hasRepositoryResources(options)) {
         throw new Error(`${action}() repository resources are only valid with backend: "cloud".`);
       }
-      assertRemoteSessionOptionsSupported(action, options);
       return;
     }
     if (this.backend === "cloud") {
+      if (options.filesystemConfinement !== undefined) {
+        throw new Error(
+          `${action}() filesystemConfinement is only supported with backend: "local".`,
+        );
+      }
       const cloudOptions = this.cloudOptions();
       if (cloudOptions.environment !== undefined && options.sandbox !== undefined) {
         throw new Error(`Letta Cloud ${action}() cannot specify sandbox options when the client has a default environment.`);
@@ -392,18 +384,13 @@ export class LettaAgentClientBase {
     );
   }
 
-  protected useLegacyLocalStdio(): boolean {
-    return (this.options as LettaCodeLocalClientOptions).transport === "stdio";
-  }
-
   protected createLocalAgent(_options: CreateAgentOptions): Promise<string> {
     throw this.localBackendUnavailableError();
   }
 
   protected createLocalSession(
-    _agentId: string | undefined,
+    _agentId: string,
     _options: LettaCodeClientSessionOptions,
-    _sessionOptions: CreateSessionOptions,
   ): LettaCodeSession {
     throw this.localBackendUnavailableError();
   }
@@ -411,7 +398,6 @@ export class LettaAgentClientBase {
   protected resumeLocalSession(
     _id: string,
     _options: LettaCodeClientSessionOptions,
-    _sessionOptions: CreateSessionOptions,
   ): LettaCodeSession {
     throw this.localBackendUnavailableError();
   }
@@ -434,10 +420,7 @@ export class LettaAgentClientBase {
   }
 
   private appServerSessionOptions(): AppServerSessionOptions {
-    return {
-      ...this.remoteOptions(),
-      beforeConnect: () => this.releaseIdleManagementConnection(),
-    };
+    return this.remoteOptions();
   }
 
   private getRepositoriesClient(): RepositoriesClient {
@@ -448,15 +431,6 @@ export class LettaAgentClientBase {
     return this.repositoriesClient;
   }
 
-  /**
-   * The app-server accepts a single control client at a time. Before a session
-   * connects, wait for this client's management work to settle and relinquish
-   * its pooled connection; management reconnects lazily on its next call.
-   */
-  protected async releaseIdleManagementConnection(): Promise<void> {
-    await this.managementTransport?.releaseIdleConnection?.();
-  }
-
   private getManagementTransport(): ManagementTransport {
     if (this.managementTransport) return this.managementTransport;
     if (this.backend === "remote") {

package/src/client.ts

@@ -3,10 +3,8 @@ 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 { Session } from "./session.js";
 import type {
   CreateAgentOptions,
-  CreateSessionOptions,
   LettaCodeClientSessionOptions,
   LettaCodeLocalClientOptions,
   LettaCodeSession,
@@ -14,11 +12,6 @@ import type {
 
 export class LettaAgentClient extends LettaAgentClientBase {
   protected override createLocalManagementTransport(): ManagementTransport {
-    if (this.useLegacyLocalStdio()) {
-      throw new Error(
-        'client.agents and client.conversations require the local "app-server" transport.',
-      );
-    }
     const localOptions = (
       this.options as LettaCodeLocalClientOptions
     ).appServer;
@@ -39,97 +32,65 @@ export class LettaAgentClient extends LettaAgentClientBase {
       ...(localOptions?.requestTimeoutMs !== undefined
         ? { requestTimeoutMs: localOptions.requestTimeoutMs }
         : {}),
-      ...(localOptions?.idleLingerMs !== undefined
-        ? { idleLingerMs: localOptions.idleLingerMs }
-        : {}),
     });
   }
 
   protected override async createLocalAgent(
     options: CreateAgentOptions,
   ): Promise<string> {
-    if (!this.useLegacyLocalStdio()) {
-      const localOptions = this.options as LettaCodeLocalClientOptions;
-      const session = createLocalAppServerSession(
-        localOptions.appServer,
-        {
-          kind: "create-agent",
-          options,
-        },
-        () => this.releaseIdleManagementConnection(),
-      );
-      const initMsg = await session.initialize();
-      session.close();
-      return initMsg.agentId;
-    }
-
-    const session = new Session({ ...options, createOnly: true });
+    const localOptions = this.options as LettaCodeLocalClientOptions;
+    const session = createLocalAppServerSession(
+      localOptions.appServer,
+      {
+        kind: "create-agent",
+        options,
+      },
+    );
     const initMsg = await session.initialize();
     session.close();
     return initMsg.agentId;
   }
 
   protected override createLocalSession(
-    agentId: string | undefined,
+    agentId: string,
     options: LettaCodeClientSessionOptions,
-    sessionOptions: CreateSessionOptions,
   ): LettaCodeSession {
-    if (!this.useLegacyLocalStdio() && agentId) {
-      const localOptions = this.options as LettaCodeLocalClientOptions;
-      return createLocalAppServerSession(
-        localOptions.appServer,
-        {
-          kind: "session",
-          agentId,
-          newConversation: true,
-          options,
-        },
-        () => this.releaseIdleManagementConnection(),
-      );
-    }
-    if (agentId) {
-      return new Session({ ...sessionOptions, agentId, newConversation: true });
-    }
-    return new Session({ ...sessionOptions, newConversation: true });
+    const localOptions = this.options as LettaCodeLocalClientOptions;
+    return createLocalAppServerSession(
+      localOptions.appServer,
+      {
+        kind: "session",
+        agentId,
+        newConversation: true,
+        options,
+      },
+    );
   }
 
   protected override resumeLocalSession(
     id: string,
     options: LettaCodeClientSessionOptions,
-    sessionOptions: CreateSessionOptions,
   ): LettaCodeSession {
-    if (!this.useLegacyLocalStdio()) {
-      const localOptions = this.options as LettaCodeLocalClientOptions;
-      if (looksLikeConversationId(id)) {
-        return createLocalAppServerSession(
-          localOptions.appServer,
-          {
-            kind: "session",
-            conversationId: id,
-            options,
-          },
-          () => this.releaseIdleManagementConnection(),
-        );
-      }
+    const localOptions = this.options as LettaCodeLocalClientOptions;
+    if (looksLikeConversationId(id)) {
       return createLocalAppServerSession(
         localOptions.appServer,
         {
           kind: "session",
-          agentId: id,
-          defaultConversation: true,
+          conversationId: id,
           options,
         },
-        () => this.releaseIdleManagementConnection(),
       );
     }
-    if (looksLikeConversationId(id)) {
-      return new Session({ ...sessionOptions, conversationId: id });
-    }
-    return new Session({
-      ...sessionOptions,
-      agentId: id,
-      defaultConversation: true,
-    });
+    return createLocalAppServerSession(
+      localOptions.appServer,
+      {
+        kind: "session",
+        agentId: id,
+        defaultConversation: true,
+        options,
+      },
+    );
   }
 }