@letta-ai/letta-agent-sdk 0.2.1 → 0.2.4

package/README.md

@@ -15,14 +15,14 @@ npm install @letta-ai/letta-agent-sdk
 ### Client creation
 
 ```ts
-import { LettaCodeClient } from "@letta-ai/letta-agent-sdk";
+import { LettaAgentClient } from "@letta-ai/letta-agent-sdk";
 
 // Local: SDK-owned Letta Code app-server over loopback websockets. The SDK
 // spawns/manages the app-server process for you.
-const localClient = new LettaCodeClient({ backend: "local" });
+const localClient = new LettaAgentClient({ backend: "local" });
 
 // Remote: connect to a user-managed Letta Code app-server over websockets.
-const remoteClient = new LettaCodeClient({
+const remoteClient = new LettaAgentClient({
   backend: "remote",
   url: "http://127.0.0.1:4500",
   // Required when the app-server is bound to a non-loopback interface with
@@ -32,7 +32,7 @@ const remoteClient = new LettaCodeClient({
 
 // Constellation: create or resume agents whose state lives in Letta's
 // agent cloud, with an SDK-managed sandbox by default.
-const client = new LettaCodeClient({
+const client = new LettaAgentClient({
   backend: "cloud",
   apiKey: process.env.LETTA_API_KEY,
 });
@@ -41,9 +41,9 @@ const client = new LettaCodeClient({
 ### Persistent agent with multi-turn conversations
 
 ```ts
-import { LettaCodeClient } from "@letta-ai/letta-agent-sdk";
+import { LettaAgentClient } from "@letta-ai/letta-agent-sdk";
 
-const client = new LettaCodeClient({ backend: "local" });
+const client = new LettaAgentClient({ backend: "local" });
 
 const agentId = await client.createAgent({
   persona: "You are a helpful coding assistant for TypeScript projects.",
@@ -92,7 +92,7 @@ Letta Code websocket protocol for `runtime_start`, `input`, streaming deltas,
 and SDK-defined external tools.
 
 ```ts
-const client = new LettaCodeClient({
+const client = new LettaAgentClient({
   backend: "remote",
   url: "http://127.0.0.1:4500",
   authToken: process.env.LETTA_APP_SERVER_TOKEN,
@@ -121,7 +121,7 @@ it to come online, refreshes it while the session is active, and cleans it up on
 close.
 
 ```ts
-const client = new LettaCodeClient({
+const client = new LettaAgentClient({
   backend: "cloud",
   apiKey: process.env.LETTA_API_KEY,
   sandbox: {
@@ -152,20 +152,34 @@ selected remote environment or managed sandbox. Local paths such as
 `process.cwd()` are not mapped into managed sandboxes automatically.
 
 You can still set a default `environment` on the client or override it per
-session to use an existing remote runtime instead of an SDK-managed sandbox:
+session to use an existing remote runtime instead of an SDK-managed sandbox. Use
+the environment name from `letta remote --env-name <name>`:
 
 ```ts
-const client = new LettaCodeClient({
+const client = new LettaAgentClient({
   backend: "cloud",
   apiKey: process.env.LETTA_API_KEY,
-  environment: { connectionId: "conn-default" },
+  environment: { name: "devbox" },
 });
 
+await using session = client.resumeSession(agentId, {
+  environment: { name: "devbox" },
+});
+```
+
+For advanced cases where you want to target a specific remote connection, pass
+its `connectionId` instead. Connection IDs are assigned when the remote listener
+registers and may change after reconnects:
+
+```ts
 await using session = client.resumeSession(agentId, {
   environment: { connectionId: "conn-123" },
 });
 ```
 
+`environment` also accepts `{ id: "env-..." }` for an environment record or
+`{ deviceId: "device-..." }` for a stable device selector.
+
 `environment` and `sandbox` are mutually exclusive. Managed sandbox refresh and
 termination operate on the latest active sandbox for an agent; set
 `sandbox.terminateOnClose: false` when multiple SDK sessions may run
@@ -183,9 +197,9 @@ remote and Constellation sessions, `cwd` must be a path inside the selected
 runtime environment.
 
 ```ts
-import { LettaCodeClient } from "@letta-ai/letta-agent-sdk";
+import { LettaAgentClient } from "@letta-ai/letta-agent-sdk";
 
-const client = new LettaCodeClient({ backend: "local" });
+const client = new LettaAgentClient({ backend: "local" });
 
 const session = client.resumeSession("agent-123", {
   model: "anthropic/claude-sonnet-4",
@@ -238,3 +252,10 @@ const sync = await session.sendCommand(
 ---
 
 Made with 💜 in San Francisco
+
+<img
+  referrerpolicy="no-referrer-when-downgrade"
+  src="https://static.scarf.sh/a.png?x-pxid=29de91a5-e18c-4366-b192-33a909e184bc&page=README.md"
+  alt=""
+  aria-hidden="true"
+/>

package/dist/client.d.ts

@@ -9,7 +9,7 @@ import type { CreateAgentOptions, LettaCodeBackend, LettaCodeClientOptions, Lett
  * `cloud` uses agents hosted on Constellation, with an explicit remote
  * environment or SDK-managed sandbox.
  */
-export declare class LettaCodeClient {
+export declare class LettaAgentClient {
     readonly backend: LettaCodeBackend;
     readonly environment: LettaCodeEnvironment | undefined;
     private readonly options;

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EACV,kBAAkB,EAElB,gBAAgB,EAChB,sBAAsB,EACtB,6BAA6B,EAC7B,oBAAoB,EAIpB,gBAAgB,EAChB,gBAAgB,EAChB,WAAW,EACZ,MAAM,YAAY,CAAC;AA8CpB;;;;;;;;;GASG;AACH,qBAAa,eAAe;IAC1B,QAAQ,CAAC,OAAO,EAAE,gBAAgB,CAAC;IACnC,QAAQ,CAAC,WAAW,EAAE,oBAAoB,GAAG,SAAS,CAAC;IACvD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAyB;gBAErC,OAAO,GAAE,sBAA2B;IAoEhD;;;;;OAKG;IACG,WAAW,CAAC,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,MAAM,CAAC;IAqCpE;;;;;OAKG;IACH,aAAa,CACX,gBAAgB,CAAC,EAAE,MAAM,GAAG,6BAA6B,EACzD,OAAO,GAAE,6BAAkC,GAC1C,gBAAgB;IAkDnB;;;;;OAKG;IACH,aAAa,CACX,EAAE,EAAE,MAAM,EACV,OAAO,GAAE,6BAAkC,GAC1C,gBAAgB;IA4DnB,mEAAmE;IAC7D,MAAM,CACV,OAAO,EAAE,WAAW,EACpB,OAAO,CAAC,EAAE,MAAM,EAChB,OAAO,GAAE,6BAAkC,GAC1C,OAAO,CAAC,gBAAgB,CAAC;IAY5B,OAAO,CAAC,kBAAkB;IAU1B,OAAO,CAAC,oBAAoB;IAgD5B,OAAO,CAAC,mBAAmB;IAI3B,OAAO,CAAC,qBAAqB;IAiB7B,OAAO,CAAC,aAAa;IAOrB,OAAO,CAAC,YAAY;CAMrB"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EACV,kBAAkB,EAElB,gBAAgB,EAChB,sBAAsB,EACtB,6BAA6B,EAC7B,oBAAoB,EAIpB,gBAAgB,EAChB,gBAAgB,EAChB,WAAW,EACZ,MAAM,YAAY,CAAC;AAkDpB;;;;;;;;;GASG;AACH,qBAAa,gBAAgB;IAC3B,QAAQ,CAAC,OAAO,EAAE,gBAAgB,CAAC;IACnC,QAAQ,CAAC,WAAW,EAAE,oBAAoB,GAAG,SAAS,CAAC;IACvD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAyB;gBAErC,OAAO,GAAE,sBAA2B;IAoEhD;;;;;OAKG;IACG,WAAW,CAAC,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,MAAM,CAAC;IA0CpE;;;;;OAKG;IACH,aAAa,CACX,gBAAgB,CAAC,EAAE,MAAM,GAAG,6BAA6B,EACzD,OAAO,GAAE,6BAAkC,GAC1C,gBAAgB;IAkDnB;;;;;OAKG;IACH,aAAa,CACX,EAAE,EAAE,MAAM,EACV,OAAO,GAAE,6BAAkC,GAC1C,gBAAgB;IA4DnB,mEAAmE;IAC7D,MAAM,CACV,OAAO,EAAE,WAAW,EACpB,OAAO,CAAC,EAAE,MAAM,EAChB,OAAO,GAAE,6BAAkC,GAC1C,OAAO,CAAC,gBAAgB,CAAC;IAY5B,OAAO,CAAC,kBAAkB;IAU1B,OAAO,CAAC,oBAAoB;IAgD5B,OAAO,CAAC,mBAAmB;IAI3B,OAAO,CAAC,qBAAqB;IAkB7B,OAAO,CAAC,aAAa;IAOrB,OAAO,CAAC,YAAY;CAMrB"}

package/dist/index.d.ts

@@ -5,9 +5,9 @@
  *
  * @example
  * ```typescript
- * import { LettaCodeClient, createAgent, createSession, resumeSession, prompt } from '@letta-ai/letta-agent-sdk';
+ * import { LettaAgentClient, createAgent, createSession, resumeSession, prompt } from '@letta-ai/letta-agent-sdk';
  *
- * const client = new LettaCodeClient({ backend: 'local' });
+ * const client = new LettaAgentClient({ backend: 'local' });
  * const agentId = await client.createAgent();
  * const clientSession = client.resumeSession(agentId);
  *
@@ -34,7 +34,7 @@
 import type { CreateSessionOptions, CreateAgentOptions, LettaCodeSession, SDKResultMessage } from "./types.js";
 export type { CreateSessionOptions, CreateAgentOptions, LettaCodeBackend, LettaCodeEnvironment, LettaCodeLocalClientOptions, LettaCodeLocalAppServerOptions, LettaCodeRemoteClientOptions, LettaCodeCloudClientOptions, LettaCodeClientOptions, LettaCodeClientSessionOptions, LettaCodeSession, LettaCodeSocketLike, LettaCodeSocketConstructor, SDKMessage, SDKInitMessage, SDKAssistantMessage, SDKToolCallMessage, SDKToolResultMessage, SDKReasoningMessage, SDKResultMessage, SDKErrorCode, SDKStreamEventMessage, SDKStreamEventPayload, SDKStreamEventDeltaPayload, SDKStreamEventMessagePayload, SDKUnknownStreamEventPayload, SDKErrorMessage, SDKRetryMessage, SDKQueueItem, SDKQueueUpdateMessage, SDKLoopStatusMessage, SDKProtocolMessage, SDKProtocolCommand, SendCommandOptions, RunTurnOptions, RecoverPendingApprovalsOptions, RecoverPendingApprovalsResult, SkillSource, DreamingOptions, DreamingTrigger, DreamingBehavior, EffectiveDreamingSettings, PermissionMode, ReasoningEffort, CanUseToolCallback, CanUseToolResponse, CanUseToolResponseAllow, CanUseToolResponseDeny, TextContent, ImageContent, MessageContentItem, SendMessage, ListMessagesOptions, ListMessagesResult, ListModelsResult, LettaCodeModelEntry, UpdateModelOptions, UpdateModelResult, BootstrapStateOptions, BootstrapStateResult, AgentTool, AgentToolResult, AgentToolResultContent, AgentToolUpdateCallback, AnyAgentTool, } from "./types.js";
 export { Session } from "./session.js";
-export { LettaCodeClient } from "./client.js";
+export { LettaAgentClient } from "./client.js";
 export { extractStreamTextDelta } from "./stream-events.js";
 export { jsonResult, readStringParam, readNumberParam, readBooleanParam, readStringArrayParam, } from "./tool-helpers.js";
 /**

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -2991,11 +2991,11 @@ function createAgentBody(options, settings = {}) {
   if (options.systemPrompt !== undefined) {
     if (typeof options.systemPrompt === "string") {
       if (isPresetSystemPrompt(options.systemPrompt)) {
-        throw new Error("App-server createAgent() does not yet support system prompt presets.");
+        throw new Error("createAgent() does not yet support system prompt presets for this backend.");
       }
       body.system = options.systemPrompt;
     } else {
-      throw new Error("App-server createAgent() does not yet support system prompt preset objects.");
+      throw new Error("createAgent() does not yet support system prompt preset objects for this backend.");
     }
   }
   const memoryBlocks = [];
@@ -4489,11 +4489,14 @@ function stripCloudExecutionOptions(options) {
 function hasCreateAgentEnvironment(options) {
   return "environment" in options;
 }
+function hasExplicitCreateAgentModel(options) {
+  return typeof options.model === "string" && options.model.trim().length > 0;
+}
 function looksLikeConversationId(id) {
   return id.startsWith("conv-") || id.startsWith("local-conv-");
 }
 
-class LettaCodeClient {
+class LettaAgentClient {
   backend;
   environment;
   options;
@@ -4506,13 +4509,13 @@ class LettaCodeClient {
     this.environment = getOptionsEnvironment(options);
     this.options = options;
     if (this.backend === "local" && this.environment !== undefined) {
-      throw new Error('LettaCodeClient environment is only valid with backend: "cloud".');
+      throw new Error('LettaAgentClient environment is only valid with backend: "cloud".');
     }
     if (this.backend === "remote" && this.environment !== undefined) {
-      throw new Error('LettaCodeClient environment is only valid with backend: "cloud"; remote url selects the app-server runtime.');
+      throw new Error('LettaAgentClient environment is only valid with backend: "cloud"; remote url selects the app-server runtime.');
     }
     if (this.backend !== "cloud" && options.sandbox !== undefined) {
-      throw new Error('LettaCodeClient sandbox options are only valid with backend: "cloud".');
+      throw new Error('LettaAgentClient sandbox options are only valid with backend: "cloud".');
     }
     if (this.backend === "local") {
       const localOptions = options;
@@ -4530,7 +4533,7 @@ class LettaCodeClient {
     }
     if (this.backend === "remote") {
       if (!("url" in options) || typeof options.url !== "string" || options.url.length === 0) {
-        throw new Error("LettaCodeClient remote backend requires a non-empty url.");
+        throw new Error("LettaAgentClient remote backend requires a non-empty url.");
       }
       if (options.requestTimeoutMs !== undefined && (!Number.isInteger(options.requestTimeoutMs) || options.requestTimeoutMs <= 0)) {
         throw new Error("Invalid requestTimeoutMs. Expected a positive integer.");
@@ -4555,6 +4558,9 @@ class LettaCodeClient {
       return initMsg2.agentId;
     }
     if (this.backend === "cloud") {
+      if (!hasExplicitCreateAgentModel(options)) {
+        throw new Error('Constellation createAgent() requires an explicit model. Pass model in createAgent({ model: "provider/model" }).');
+      }
       return createCloudAgent(this.cloudOptions(), options);
     }
     this.assertLocalBackend("createAgent");
@@ -4683,7 +4689,7 @@ class LettaCodeClient {
     if (this.backend === "local") {
       return;
     }
-    throw new Error(`LettaCodeClient backend '${this.backend}' is not implemented yet. ${action} currently supports backend 'local' only.`);
+    throw new Error(`LettaAgentClient backend '${this.backend}' is not implemented yet. ${action} currently supports backend 'local' only.`);
   }
   assertSessionBackend(action, options) {
     const effectiveEnvironment = options.environment ?? this.environment;
@@ -4720,7 +4726,7 @@ class LettaCodeClient {
       assertCloudSessionOptionsSupported(action, options);
       return;
     }
-    throw new Error(`LettaCodeClient backend '${this.backend}' is not implemented yet. ${action} currently supports backend 'local' only.`);
+    throw new Error(`LettaAgentClient backend '${this.backend}' is not implemented yet. ${action} currently supports backend 'local' only.`);
   }
   useLegacyLocalStdio() {
     return this.options.transport === "stdio";
@@ -4730,6 +4736,7 @@ class LettaCodeClient {
     const appServer = localOptions.appServer;
     return {
       local: appServer?.url === undefined,
+      localBackend: "local",
       ...appServer?.url !== undefined ? { url: appServer.url } : {},
       ...appServer?.WebSocket !== undefined ? { WebSocket: appServer.WebSocket } : {},
       ...appServer?.requestTimeoutMs !== undefined ? { requestTimeoutMs: appServer.requestTimeoutMs } : {},
@@ -4907,18 +4914,18 @@ function readStringArrayParam(params, key, options = {}) {
 import { readFileSync } from "node:fs";
 async function createAgent(options = {}) {
   validateCreateAgentOptions(options);
-  return new LettaCodeClient().createAgent(options);
+  return new LettaAgentClient().createAgent(options);
 }
 function createSession(agentId, options = {}) {
   validateCreateSessionOptions(options);
   if (agentId) {
-    return new LettaCodeClient().createSession(agentId, options);
+    return new LettaAgentClient().createSession(agentId, options);
   }
-  return new LettaCodeClient({ backend: "local", transport: "stdio" }).createSession(options);
+  return new LettaAgentClient({ backend: "local", transport: "stdio" }).createSession(options);
 }
 function resumeSession(id, options = {}) {
   validateCreateSessionOptions(options);
-  return new LettaCodeClient().resumeSession(id, options);
+  return new LettaAgentClient().resumeSession(id, options);
 }
 async function prompt(message, agentId) {
   const session = agentId ? createSession(agentId) : createSession();
@@ -4929,7 +4936,7 @@ async function prompt(message, agentId) {
   }
 }
 async function listMessagesDirect(agentId, options = {}) {
-  const session = new LettaCodeClient().resumeSession(agentId, {
+  const session = new LettaAgentClient().resumeSession(agentId, {
     permissionMode: "bypassPermissions"
   });
   await session.initialize();
@@ -4988,7 +4995,7 @@ export {
   createSession,
   createAgent,
   Session,
-  LettaCodeClient
+  LettaAgentClient
 };
 
-//# debugId=386FEEB02928954D64756E2164756E21
+//# debugId=380F2F63E2AF857764756E2164756E21