@letta-ai/letta-agent-sdk 0.8.23 → 0.8.25

package/README.md

@@ -51,7 +51,7 @@ measures the tracked turn and excludes session initialization; measure `ready()`
 separately when startup latency matters.
 
 For a simple question that should not create or use an agent, call `query()`.
-It creates an agent-free ephemeral conversation from the supplied model and
+It creates an ordinary conversation from the supplied model and
 system prompt, streams the turn, and closes the runtime when iteration ends:
 
 ```typescript
@@ -66,9 +66,8 @@ for await (const message of client.query({
 }
 ```
 
-`query()` requires an API-backed App Server. For `backend: "local"`, set
-`appServer.harnessBackend: "api"`; the default local harness backend does not
-store agent-free conversations.
+`query()` supports API-backed App Servers and local App Servers that advertise
+local conversation support. Older local App Servers return an upgrade error.
 
 Pass the returned `query.conversationId` as `options.conversationId` on a later
 `query()` to continue that conversation with its history. On resume, `model`,
@@ -76,7 +75,7 @@ Pass the returned `query.conversationId` as `options.conversationId` on a later
 stored configuration.
 
 Cloud queries require an explicit connected computer. Local and remote clients
-run the ephemeral conversation through their App Server.
+run the conversation through their App Server.
 
 Set `LETTA_API_KEY` for the cloud backend. See the [quickstart](https://docs.letta.com/agent-sdk/quickstart) for the local and self-hosted paths.
 

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

@@ -17,6 +17,8 @@ export type AppServerSessionOptions = Partial<LettaCodeRemoteClientOptions> & {
         url: string;
         close(): void;
     }>;
+    /** Require the app-server capability needed by local query conversations. */
+    requireLocalConversationCapability?: boolean;
 };
 export type AppServerSessionMode = RuntimeSessionMode;
 export declare function externalToolGroups(tools: AnyAgentTool[] | undefined): Array<Record<string, unknown>> | undefined;

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

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

package/dist/client-base.d.ts

@@ -3,7 +3,7 @@ import { type SkillNodeSupport } from "./skill-loading.js";
 import { type ComputerSelector, type ComputersClient } from "./computers.js";
 import { type ManagementTransport } from "./management.js";
 import type { AgentsClient, ConversationsClient, ModelsClient } from "./management-types.js";
-import type { AgentFreeQueryOptions, Query, QueryParams } from "./query-types.js";
+import type { Query, QueryOptions, QueryParams } from "./query-types.js";
 import type { CreateAgentOptions, LettaCodeBackend, LettaCodeClientOptions, LettaCodeClientSessionOptions, LettaCodeEnvironment, LettaCodeSession, SDKResultMessage, SendMessage } from "./types.js";
 /**
  * Top-level Letta Agent SDK client.
@@ -60,9 +60,9 @@ export declare class LettaAgentClientBase implements AsyncDisposable {
      * Applications should use a session when they need interactive turn state.
      */
     prompt(message: SendMessage, agentId: string, options?: LettaCodeClientSessionOptions): Promise<SDKResultMessage>;
-    /** Run one prompt in a new or resumed agent-free ephemeral conversation. */
+    /** Run one prompt in a new or resumed ordinary conversation. */
     query(params: QueryParams): Query;
-    private createAgentFreeSession;
+    private createQuerySession;
     private assertSessionBackend;
     protected createLocalAgent(_options: CreateAgentOptions): Promise<string>;
     /**
@@ -72,7 +72,7 @@ export declare class LettaAgentClientBase implements AsyncDisposable {
      */
     protected skillNodeSupport(): SkillNodeSupport | undefined;
     protected createLocalSession(_agentId: string, _options: LettaCodeClientSessionOptions): LettaCodeSession;
-    protected createLocalAgentFreeSession(_queryOptions: AgentFreeQueryOptions, _sessionOptions: LettaCodeClientSessionOptions): LettaCodeSession;
+    protected createLocalQuerySession(_queryOptions: QueryOptions, _sessionOptions: LettaCodeClientSessionOptions): LettaCodeSession;
     protected resumeLocalSession(_id: string, _options: LettaCodeClientSessionOptions): LettaCodeSession;
     protected localBackendUnavailableError(): Error;
     protected createLocalManagementTransport(): ManagementTransport;

package/dist/client-base.d.ts.map

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

package/dist/client-entry.js

@@ -9432,7 +9432,7 @@ function isAppServerInfoResponseMessage(message) {
     return false;
   }
   const capabilityRecord = capabilities;
-  return candidate.type === "app_server_info_response" && typeof candidate.request_id === "string" && candidate.request_id.length > 0 && candidate.success === true && (candidate.backend === "local" || candidate.backend === "api") && typeof candidate.letta_code_version === "string" && typeof candidate.protocol_version === "number" && Number.isInteger(candidate.protocol_version) && typeof capabilityRecord.agent_management === "boolean" && typeof capabilityRecord.conversation_management === "boolean" && typeof capabilityRecord.memory_management === "boolean" && typeof capabilityRecord.runtime_start === "boolean" && (capabilityRecord.launch_subagent === undefined || typeof capabilityRecord.launch_subagent === "boolean") && (capabilityRecord.runtime_workspace_sandbox === undefined || typeof capabilityRecord.runtime_workspace_sandbox === "boolean") && (capabilityRecord.runtime_external_tools_update === undefined || typeof capabilityRecord.runtime_external_tools_update === "boolean") && (capabilityRecord.structured_outputs === undefined || typeof capabilityRecord.structured_outputs === "boolean") && typeof capabilityRecord.split_channels === "boolean";
+  return candidate.type === "app_server_info_response" && typeof candidate.request_id === "string" && candidate.request_id.length > 0 && candidate.success === true && (candidate.backend === "local" || candidate.backend === "api") && typeof candidate.letta_code_version === "string" && typeof candidate.protocol_version === "number" && Number.isInteger(candidate.protocol_version) && typeof capabilityRecord.agent_management === "boolean" && typeof capabilityRecord.conversation_management === "boolean" && typeof capabilityRecord.memory_management === "boolean" && typeof capabilityRecord.runtime_start === "boolean" && (capabilityRecord.agent_free_conversations === undefined || typeof capabilityRecord.agent_free_conversations === "boolean") && (capabilityRecord.launch_subagent === undefined || typeof capabilityRecord.launch_subagent === "boolean") && (capabilityRecord.runtime_workspace_sandbox === undefined || typeof capabilityRecord.runtime_workspace_sandbox === "boolean") && (capabilityRecord.runtime_external_tools_update === undefined || typeof capabilityRecord.runtime_external_tools_update === "boolean") && (capabilityRecord.structured_outputs === undefined || typeof capabilityRecord.structured_outputs === "boolean") && typeof capabilityRecord.split_channels === "boolean";
 }
 var DEFAULT_REQUEST_TIMEOUT_MS = 30000;
 var WEBSOCKET_OPEN_STATE = 1;
@@ -14538,6 +14538,7 @@ class RemoteClientSessionCore {
 }
 
 // src/app-server-session.ts
+var LOCAL_CONVERSATION_CAPABILITY = "agent_free_conversations";
 function agentToolNames(agent) {
   const tools = agent && "tools" in agent ? agent.tools : undefined;
   if (!Array.isArray(tools))
@@ -14939,6 +14940,13 @@ class AppServerSession extends RemoteClientSessionCore {
     }
     try {
       await client.connect();
+      if (this.mode.kind === "conversation" && this.remoteOptions.requireLocalConversationCapability === true) {
+        const info = await client.info();
+        const capabilities = info.capabilities;
+        if (info.backend === "local" && capabilities[LOCAL_CONVERSATION_CAPABILITY] !== true) {
+          throw new Error(`Local query() requires a Letta Code app-server with local conversation support (connected version: ${info.letta_code_version}). Upgrade @letta-ai/letta-code.`);
+        }
+      }
       const response = await this.startRuntime(client);
       if (!response.success || !response.runtime) {
         throw new Error(response.error ?? "Failed to start app-server runtime");
@@ -15016,7 +15024,7 @@ class AppServerSession extends RemoteClientSessionCore {
     const mode = mapPermissionMode(options.permissionMode);
     if (mode)
       command.mode = mode;
-    if (this.mode.kind === "agent-free" && this.mode.disableMemoryGuard === true) {
+    if (this.mode.kind === "conversation" && this.mode.disableMemoryGuard === true) {
       command.execution_settings = {
         allowed_tools: [],
         disallowed_tools: [],
@@ -15042,7 +15050,7 @@ class AppServerSession extends RemoteClientSessionCore {
       };
       return command;
     }
-    if (this.mode.kind === "agent-free") {
+    if (this.mode.kind === "conversation") {
       if (this.mode.createConversation) {
         const create = this.mode.createConversation;
         command.create_conversation = {
@@ -15059,7 +15067,7 @@ class AppServerSession extends RemoteClientSessionCore {
       } else if (this.mode.conversationId) {
         command.conversation_id = this.mode.conversationId;
       } else {
-        throw new Error("Agent-free sessions require a conversation to create or resume.");
+        throw new Error("Query sessions require a conversation to create or resume.");
       }
       return command;
     }
@@ -16127,9 +16135,9 @@ class CloudEnvironmentSession extends RemoteClientSessionCore {
     return bridge?.close() ?? Promise.resolve();
   }
   async resolveRuntime() {
-    if (this.cloudMode.kind === "agent-free") {
+    if (this.cloudMode.kind === "conversation") {
       if (!this.cloudMode.conversationId) {
-        throw new Error("Cloud agent-free sessions require a conversation id.");
+        throw new Error("Cloud query sessions require a conversation id.");
       }
       return {
         runtime: {
@@ -16284,7 +16292,7 @@ class CloudEnvironmentSession extends RemoteClientSessionCore {
   }
   async createManagedSandboxConnection(runtime) {
     if (!runtime.agent_id) {
-      throw new Error("Agent-free queries require an explicit Cloud computer; managed sandboxes are agent-scoped.");
+      throw new Error("Queries without an agent require an explicit Cloud computer; managed sandboxes are agent-scoped.");
     }
     const conversationId = runtime.conversation_id && runtime.conversation_id !== "default" ? runtime.conversation_id : undefined;
     const sandbox = await this.createManagedSandbox(runtime.agent_id, conversationId);
@@ -16871,7 +16879,7 @@ function hasCreateAgentEnvironment(options) {
 function looksLikeConversationId(id) {
   return id.startsWith("conv-") || id.startsWith("local-conv-");
 }
-function agentFreeSessionOptions(options) {
+function querySessionOptions(options) {
   const {
     system: _system,
     parentAgentId: _parentAgentId,
@@ -16885,7 +16893,7 @@ function agentFreeSessionOptions(options) {
   } = options;
   return sessionOptions;
 }
-function validateAgentFreeQueryOptions(options) {
+function validateQueryOptions(options) {
   if (options.conversationId !== undefined && (typeof options.conversationId !== "string" || !options.conversationId.trim())) {
     throw new Error("query() conversationId must be a non-empty string.");
   }
@@ -16895,7 +16903,7 @@ function validateAgentFreeQueryOptions(options) {
   if (typeof options.system !== "string") {
     throw new Error("query() requires a system prompt.");
   }
-  validateCreateSessionOptions(agentFreeSessionOptions(options));
+  validateCreateSessionOptions(querySessionOptions(options));
 }
 
 class LettaAgentClientBase {
@@ -17072,20 +17080,20 @@ class LettaAgentClientBase {
   }
   query(params) {
     this.assertOpen();
-    validateAgentFreeQueryOptions(params.options);
-    return createQuery((options) => this.createAgentFreeSession(options), params);
+    validateQueryOptions(params.options);
+    return createQuery((options) => this.createQuerySession(options), params);
   }
-  async createAgentFreeSession(options) {
+  async createQuerySession(options) {
     this.assertOpen();
-    validateAgentFreeQueryOptions(options);
-    const sessionOptions = agentFreeSessionOptions(options);
+    validateQueryOptions(options);
+    const sessionOptions = querySessionOptions(options);
     this.assertSessionBackend("query", sessionOptions);
     if (options.disableMemoryGuard === true && this.backend === "cloud") {
       throw new Error('query() disableMemoryGuard is only supported with backend: "local" or "remote".');
     }
     if (this.backend === "remote") {
       return new AppServerSession(this.appServerSessionOptions(), {
-        kind: "agent-free",
+        kind: "conversation",
         ...options.conversationId ? { conversationId: options.conversationId } : {
           createConversation: {
             model: options.model,
@@ -17118,15 +17126,15 @@ class LettaAgentClientBase {
         }
       });
       if (!conversation || typeof conversation !== "object" || typeof conversation.id !== "string") {
-        throw new Error("Cloud ephemeral conversation response did not include a conversation id.");
+        throw new Error("Cloud query conversation response did not include a conversation id.");
       }
       return new CloudEnvironmentSession(this.cloudOptions(), {
-        kind: "agent-free",
+        kind: "conversation",
         conversationId: conversation.id,
         options: sessionOptions
       }, this.getCloudClient());
     }
-    return this.createLocalAgentFreeSession(options, sessionOptions);
+    return this.createLocalQuerySession(options, sessionOptions);
   }
   assertSessionBackend(action, options) {
     if (options.computer !== undefined && options.environment !== undefined) {
@@ -17198,7 +17206,7 @@ class LettaAgentClientBase {
   createLocalSession(_agentId, _options) {
     throw this.localBackendUnavailableError();
   }
-  createLocalAgentFreeSession(_queryOptions, _sessionOptions) {
+  createLocalQuerySession(_queryOptions, _sessionOptions) {
     throw this.localBackendUnavailableError();
   }
   resumeLocalSession(_id, _options) {
@@ -17815,4 +17823,4 @@ export {
   CloudManagedSandboxExpiredError
 };
 
-//# debugId=14E3E802EC2F50CB64756E2164756E21
+//# debugId=066C5652FCCEF11364756E2164756E21