@letta-ai/letta-agent-sdk 0.8.78 → 0.8.80

package/dist/client-base.d.ts

@@ -15,7 +15,8 @@ import type { CreateAgentOptions, LettaCodeBackend, LettaCodeClientOptions, Lett
  * 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.
+ * environment or SDK-managed sandbox. With `registerComputer`, the SDK also
+ * starts a local app-server that registers this machine as that computer.
  */
 export declare class LettaAgentClientBase implements AsyncDisposable {
     readonly backend: LettaCodeBackend;
@@ -72,6 +73,14 @@ export declare class LettaAgentClientBase implements AsyncDisposable {
     query(params: QueryParams): Query;
     private createQuerySession;
     private assertSessionBackend;
+    /**
+     * Build a Cloud session. Sessions that run on the computer this client
+     * registers start the local app-server first and wait for it to come online.
+     */
+    private createCloudSession;
+    private connectRegisteredComputer;
+    /** Start the app-server that registers this machine; overridden by the Node client. */
+    protected startRegisteredComputer(): Promise<void>;
     protected createLocalAgent(_options: CreateAgentOptions): Promise<string>;
     /**
      * Node-only skill seeding support (directory loading, memory-repo git
@@ -99,7 +108,10 @@ export declare class LettaAgentClientBase implements AsyncDisposable {
      * prompts, with or without an open session.
      */
     registerTools(options: RegisterToolsOptions): Promise<ToolRegistration>;
-    /** How the local backend reaches its App Server; overridden by the Node client. */
+    /**
+     * How the local backend, or a Cloud client's registered computer, reaches
+     * its App Server; overridden by the Node client.
+     */
     protected localAppServerConnection(): AppServerSessionOptions;
     /**
      * Release resources owned directly by this client, including its pooled

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.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client-entry.d.ts","sourceRoot":"","sources":["../src/client-entry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AACxD,OAAO,KAAK,EACV,2BAA2B,EAC3B,4BAA4B,EAC7B,MAAM,YAAY,CAAC;AAEpB,MAAM,MAAM,+BAA+B,GACvC,4BAA4B,GAC5B,2BAA2B,CAAC;AAEhC;;;;;GAKG;AACH,qBAAa,gBAAiB,SAAQ,oBAAoB;gBAC5C,OAAO,EAAE,+BAA+B;CAMrD;AAED,OAAO,EAAE,+BAA+B,EAAE,MAAM,oBAAoB,CAAC;AACrE,OAAO,EAAE,8BAA8B,EAAE,MAAM,wBAAwB,CAAC;AACxE,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,YAAY,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AACrF,mBAAmB,oBAAoB,CAAC;AACxC,YAAY,EACV,QAAQ,EACR,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,EACf,oBAAoB,EACpB,mBAAmB,EACnB,gBAAgB,GACjB,MAAM,gBAAgB,CAAC;AACxB,mBAAmB,uBAAuB,CAAC;AAC3C,OAAO,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,EAAE,2BAA2B,EAAE,MAAM,6BAA6B,CAAC;AAC1E,YAAY,EACV,qBAAqB,EACrB,qBAAqB,EACrB,uBAAuB,EACvB,aAAa,EACb,qBAAqB,EACrB,iBAAiB,EACjB,kBAAkB,EAClB,iBAAiB,EACjB,qBAAqB,EACrB,wBAAwB,EACxB,oBAAoB,GACrB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAE,qCAAqC,EAAE,MAAM,gBAAgB,CAAC;AACvE,mBAAmB,YAAY,CAAC;AAChC,mBAAmB,kBAAkB,CAAC"}
+{"version":3,"file":"client-entry.d.ts","sourceRoot":"","sources":["../src/client-entry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AACxD,OAAO,KAAK,EACV,2BAA2B,EAC3B,4BAA4B,EAC7B,MAAM,YAAY,CAAC;AAEpB,MAAM,MAAM,+BAA+B,GACvC,4BAA4B,GAC5B,2BAA2B,CAAC;AAEhC;;;;;GAKG;AACH,qBAAa,gBAAiB,SAAQ,oBAAoB;gBAC5C,OAAO,EAAE,+BAA+B;CAWrD;AAED,OAAO,EAAE,+BAA+B,EAAE,MAAM,oBAAoB,CAAC;AACrE,OAAO,EAAE,8BAA8B,EAAE,MAAM,wBAAwB,CAAC;AACxE,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,YAAY,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AACrF,mBAAmB,oBAAoB,CAAC;AACxC,YAAY,EACV,QAAQ,EACR,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,EACf,oBAAoB,EACpB,mBAAmB,EACnB,gBAAgB,GACjB,MAAM,gBAAgB,CAAC;AACxB,mBAAmB,uBAAuB,CAAC;AAC3C,OAAO,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,EAAE,2BAA2B,EAAE,MAAM,6BAA6B,CAAC;AAC1E,YAAY,EACV,qBAAqB,EACrB,qBAAqB,EACrB,uBAAuB,EACvB,aAAa,EACb,qBAAqB,EACrB,iBAAiB,EACjB,kBAAkB,EAClB,iBAAiB,EACjB,qBAAqB,EACrB,wBAAwB,EACxB,oBAAoB,GACrB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAE,qCAAqC,EAAE,MAAM,gBAAgB,CAAC;AACvE,mBAAmB,YAAY,CAAC;AAChC,mBAAmB,kBAAkB,CAAC"}

package/dist/client-entry.js

@@ -9481,18 +9481,39 @@ function onceSocketEvent(socket, type, listener) {
   });
   return detach;
 }
-function waitForSocketOpen(socket) {
+function waitForSocketOpen(socket, timeoutMs) {
   if (socket.readyState === WEBSOCKET_OPEN_STATE) {
     return Promise.resolve();
   }
-  return new Promise((resolve, reject) => {
+  return new Promise((resolvePromise, rejectPromise) => {
+    let settled = false;
+    const resolve = () => {
+      if (settled)
+        return;
+      settled = true;
+      resolvePromise();
+    };
+    const reject = (error) => {
+      if (settled)
+        return;
+      settled = true;
+      rejectPromise(error);
+    };
     let detachOpen = () => {};
     let detachError = () => {};
+    let detachClose = () => {};
     let detachResponse = () => {};
     let detachBody = () => {};
+    let upgradeRejected = false;
+    const timer = timeoutMs > 0 ? setTimeout(() => {
+      cleanup();
+      reject(new Error(`App-server WebSocket failed to open: timed out after ${timeoutMs}ms`));
+    }, timeoutMs) : undefined;
     const cleanup = () => {
+      clearTimeout(timer);
       detachOpen();
       detachError();
+      detachClose();
       detachResponse();
       detachBody();
     };
@@ -9504,6 +9525,7 @@ function waitForSocketOpen(socket) {
       const onResponse = (_request, response) => {
         if (!response)
           return;
+        upgradeRejected = true;
         const request = _request;
         let body = Buffer.alloc(0);
         let finished = false;
@@ -9545,6 +9567,12 @@ function waitForSocketOpen(socket) {
       cleanup();
       reject(new Error(`App-server WebSocket failed to open: ${String(event)}`));
     });
+    detachClose = onceSocketEvent(socket, "close", () => {
+      if (upgradeRejected)
+        return;
+      cleanup();
+      reject(new Error("App-server WebSocket failed to open: closed before opening"));
+    });
   });
 }
 function rawEventData(event) {
@@ -9612,7 +9640,7 @@ class AppServerClient {
     });
   }
   async connect() {
-    await waitForSocketOpen(this.socket);
+    await waitForSocketOpen(this.socket, this.requestTimeoutMs);
     return this;
   }
   close() {
@@ -13236,6 +13264,7 @@ function externalToolGroups(tools) {
     return;
   return [
     {
+      capabilities: { external_tool_call_cancel: true },
       tools: tools.map((tool) => ({
         name: tool.name,
         label: tool.label,
@@ -13248,14 +13277,14 @@ function externalToolGroups(tools) {
 var MAX_REMEMBERED_EXTERNAL_TOOL_CALLS = 200;
 function createExternalToolCallHandler(externalTools, fallbackRuntime) {
   const calls = new Map;
-  const execute = async (request) => {
+  const execute = async (request, signal) => {
     const tool = externalTools.get(request.tool_name);
     if (!tool) {
       throw new Error(`Unknown external tool: ${request.tool_name}`);
     }
     const runtime = request.runtime ?? fallbackRuntime?.() ?? null;
     const context = runtime ? { toolCallId: request.tool_call_id, agentId: runtime.agent_id, conversationId: runtime.conversation_id } : undefined;
-    const result = await tool.execute(request.tool_call_id, request.input, undefined, undefined, context);
+    const result = await tool.execute(request.tool_call_id, request.input, signal, undefined, context);
     return {
       content: result.content.map((part) => ({
         type: part.type,
@@ -13266,15 +13295,15 @@ function createExternalToolCallHandler(externalTools, fallbackRuntime) {
       ...result.isError === true ? { is_error: true } : {}
     };
   };
-  return (request) => {
+  return (request, signal) => {
     const requestId = request.request_id;
     if (typeof requestId !== "string" || requestId.length === 0) {
-      return execute(request);
+      return execute(request, signal);
     }
     const existing = calls.get(requestId);
     if (existing)
       return existing;
-    const call = execute(request);
+    const call = execute(request, signal);
     calls.set(requestId, call);
     while (calls.size > MAX_REMEMBERED_EXTERNAL_TOOL_CALLS) {
       const oldest = calls.keys().next().value;
@@ -13285,6 +13314,49 @@ function createExternalToolCallHandler(externalTools, fallbackRuntime) {
     return call;
   };
 }
+function registerExternalToolCallHandler(client, handler) {
+  const pending = new Map;
+  const completed = new Set;
+  const remove = client.onMessage((raw, channel) => {
+    if (channel !== "control")
+      return;
+    const message = raw;
+    const requestId = message.request_id;
+    if (typeof requestId !== "string")
+      return;
+    if (message.type === "external_tool_call_cancel") {
+      const call = pending.get(requestId);
+      if (!call)
+        return;
+      call.finish({ error: "cancelled" });
+      call.controller.abort(message.reason);
+      return;
+    }
+    if (message.type !== "external_tool_call_request" || pending.has(requestId) || completed.has(requestId))
+      return;
+    const controller = new AbortController;
+    const finish = (response) => {
+      if (!pending.delete(requestId))
+        return;
+      completed.add(requestId);
+      if (completed.size > MAX_REMEMBERED_EXTERNAL_TOOL_CALLS)
+        completed.delete(completed.values().next().value);
+      client.send({ type: "external_tool_call_response", request_id: requestId, ...response });
+    };
+    pending.set(requestId, { controller, finish });
+    try {
+      Promise.resolve(handler(raw, controller.signal)).then((result) => finish({ result }), (error) => finish({ error: error instanceof Error ? error.message : String(error) }));
+    } catch (error) {
+      finish({ error: error instanceof Error ? error.message : String(error) });
+    }
+  });
+  return () => {
+    remove();
+    for (const call of pending.values())
+      call.controller.abort();
+    pending.clear();
+  };
+}
 
 // src/runtime-tool-policy.ts
 var RUNTIME_TOOL_POLICY_CAPABILITY = "runtime_tool_policy";
@@ -15109,7 +15181,7 @@ class AppServerSession extends RemoteClientSessionCore {
       getOptions: () => this.currentOptions()
     });
     if (this.externalTools.size > 0 || this.inheritedTools) {
-      this.removeExternalToolHandler = client.onExternalToolCall(createExternalToolCallHandler(this.externalTools, () => this.runtime));
+      this.removeExternalToolHandler = registerExternalToolCallHandler(client, createExternalToolCallHandler(this.externalTools, () => this.runtime));
     }
     try {
       await client.connect();
@@ -15949,6 +16021,19 @@ function validateCloudClientOptions(options) {
     const field = options.computer !== undefined ? "computer" : "environment";
     throw new Error(`Letta Cloud sessions cannot specify both ${field} and sandbox options.`);
   }
+  if (options.registerComputer !== undefined) {
+    const name = options.registerComputer?.name;
+    if (typeof name !== "string" || !name.trim()) {
+      throw new Error("Invalid registerComputer.name. Expected a non-empty string.");
+    }
+    if (options.computer !== undefined || options.environment !== undefined) {
+      const field = options.computer !== undefined ? "computer" : "environment";
+      throw new Error(`Letta Cloud clients cannot specify both ${field} and registerComputer. Use computer for a machine that is already connected, or registerComputer to connect this one.`);
+    }
+    if (options.sandbox !== undefined) {
+      throw new Error("Letta Cloud clients cannot specify both registerComputer and sandbox options.");
+    }
+  }
   if (options.webSocketAuth !== undefined && options.webSocketAuth !== "header" && options.webSocketAuth !== "query") {
     throw new Error("Invalid webSocketAuth. Valid values: header, query.");
   }
@@ -16042,6 +16127,7 @@ function assertCloudSessionOptionsSupported(action, options) {
 class CloudEnvironmentSession extends RemoteClientSessionCore {
   cloudOptions;
   apiClient;
+  connectRegisteredComputer;
   sandbox;
   connectionId = null;
   removeExternalToolHandler = null;
@@ -16057,13 +16143,14 @@ class CloudEnvironmentSession extends RemoteClientSessionCore {
   repositoryIdsRequiringCleanupRecompile = new Set;
   repositoryManagement;
   cloudMode;
-  constructor(cloudOptions, mode, apiClient = createCloudClient(cloudOptions)) {
+  constructor(cloudOptions, mode, apiClient = createCloudClient(cloudOptions), connectRegisteredComputer) {
     super(mode, {
       label: "cloud",
       requestTimeoutMs: cloudOptions.requestTimeoutMs ?? DEFAULT_TURN_TIMEOUT_MS
     });
     this.cloudOptions = cloudOptions;
     this.apiClient = apiClient;
+    this.connectRegisteredComputer = connectRegisteredComputer;
     this.cloudMode = mode;
     this.repositoryManagement = new CloudManagementTransport(apiClient);
     this.sandbox = this.effectiveEnvironment() === undefined ? {
@@ -16199,7 +16286,7 @@ class CloudEnvironmentSession extends RemoteClientSessionCore {
       getOptions: () => this.currentOptions()
     });
     if (this.externalTools.size > 0) {
-      this.removeExternalToolHandler = client.onExternalToolCall(createExternalToolCallHandler(this.externalTools, () => this.runtime));
+      this.removeExternalToolHandler = registerExternalToolCallHandler(client, createExternalToolCallHandler(this.externalTools, () => this.runtime));
     }
   }
   cleanupTransportHandlers() {
@@ -16466,6 +16553,8 @@ class CloudEnvironmentSession extends RemoteClientSessionCore {
     return this.createManagedSandboxConnection(runtime);
   }
   async resolveExplicitConnection(environment) {
+    if (this.connectRegisteredComputer)
+      return this.connectRegisteredComputer();
     const target = environmentToRemoteTarget(environment);
     const resolved = await this.remoteEnvironmentClient().resolveEnvironment(target);
     return { connectionId: resolved.connectionId };
@@ -16955,12 +17044,12 @@ class ToolRegistry {
       ...this.options.WebSocket ? { WebSocket: this.options.WebSocket } : {},
       ...this.options.requestTimeoutMs !== undefined ? { requestTimeoutMs: this.options.requestTimeoutMs } : {}
     }));
-    client.onExternalToolCall(async (request) => {
+    registerExternalToolCallHandler(client, async (request, signal) => {
       const runtime = request.runtime;
       const entry = runtime && [...this.entries].find((candidate) => candidate.runtimes.some((r) => runtimeKey(r) === runtimeKey(runtime)));
       if (!entry)
         throw new Error(`No tools registered for conversation ${runtime?.conversation_id}`);
-      return entry.call(request);
+      return entry.call(request, signal);
     });
     try {
       await client.connect();
@@ -17265,6 +17354,15 @@ function stripCloudExecutionOptions(options) {
   delete sessionOptions.filesystemConfinement;
   return sessionOptions;
 }
+var REGISTERED_COMPUTER_READY_TIMEOUT_MS = 30000;
+var REGISTERED_COMPUTER_POLL_INTERVAL_MS = 500;
+function registeredComputerName(options) {
+  return options.backend === "cloud" ? options.registerComputer?.name : undefined;
+}
+function isRegisteredComputerPending(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  return message.startsWith("Computer not found") || message.startsWith("Computer is offline");
+}
 function hasRepositoryResources(options) {
   return options.resources !== undefined && options.resources.length > 0;
 }
@@ -17323,7 +17421,8 @@ class LettaAgentClientBase {
       throw new Error(`Invalid Letta Code backend '${String(backend)}'. Valid values: local, remote, cloud.`);
     }
     this.backend = backend;
-    this.computer = getOptionsComputer(options);
+    const registeredName = registeredComputerName(options);
+    this.computer = getOptionsComputer(options) ?? (registeredName !== undefined ? { name: registeredName } : undefined);
     this.environment = this.computer;
     this.options = options;
     this.agents = createAgentsClient(() => this.getManagementTransport(), () => this.getAgentRepositoriesClient());
@@ -17419,12 +17518,12 @@ class LettaAgentClientBase {
       });
     }
     if (this.backend === "cloud") {
-      return new CloudEnvironmentSession(this.cloudOptions(), {
+      return this.createCloudSession({
         kind: "session",
         agentId,
         newConversation: true,
         options
-      }, this.getCloudClient());
+      });
     }
     return this.createLocalSession(agentId, options);
   }
@@ -17450,19 +17549,7 @@ class LettaAgentClientBase {
       return session2;
     }
     if (this.backend === "cloud") {
-      if (looksLikeConversationId(id)) {
-        return new CloudEnvironmentSession(this.cloudOptions(), {
-          kind: "session",
-          conversationId: id,
-          options
-        }, this.getCloudClient());
-      }
-      return new CloudEnvironmentSession(this.cloudOptions(), {
-        kind: "session",
-        agentId: id,
-        defaultConversation: true,
-        options
-      }, this.getCloudClient());
+      return this.createCloudSession(looksLikeConversationId(id) ? { kind: "session", conversationId: id, options } : { kind: "session", agentId: id, defaultConversation: true, options });
     }
     const session = this.resumeLocalSession(id, options);
     if (inherited && session instanceof AppServerSession)
@@ -17528,11 +17615,11 @@ class LettaAgentClientBase {
       if (!conversation || typeof conversation !== "object" || typeof conversation.id !== "string") {
         throw new Error("Cloud query conversation response did not include a conversation id.");
       }
-      return new CloudEnvironmentSession(this.cloudOptions(), {
+      return this.createCloudSession({
         kind: "conversation",
         conversationId: conversation.id,
         options: sessionOptions
-      }, this.getCloudClient());
+      });
     }
     return this.createLocalQuerySession(options, sessionOptions);
   }
@@ -17597,6 +17684,29 @@ class LettaAgentClientBase {
     }
     throw new Error(`LettaAgentClient backend '${this.backend}' is not implemented yet. ${action} currently supports backend 'local' only.`);
   }
+  createCloudSession(mode) {
+    const name = registeredComputerName(this.options);
+    const sessionComputer = mode.options.computer ?? mode.options.environment;
+    return new CloudEnvironmentSession(this.cloudOptions(), mode, this.getCloudClient(), name !== undefined && sessionComputer === undefined ? () => this.connectRegisteredComputer(name) : undefined);
+  }
+  async connectRegisteredComputer(name) {
+    await this.startRegisteredComputer();
+    const deadline = Date.now() + REGISTERED_COMPUTER_READY_TIMEOUT_MS;
+    while (true) {
+      try {
+        const resolved = await this.getComputersClient().resolve({ name });
+        return { connectionId: resolved.connectionId };
+      } catch (error) {
+        if (!isRegisteredComputerPending(error) || Date.now() >= deadline) {
+          throw error;
+        }
+        await new Promise((resolve) => setTimeout(resolve, REGISTERED_COMPUTER_POLL_INTERVAL_MS));
+      }
+    }
+  }
+  startRegisteredComputer() {
+    return Promise.reject(this.localBackendUnavailableError());
+  }
   createLocalAgent(_options) {
     throw this.localBackendUnavailableError();
   }
@@ -17677,8 +17787,8 @@ class LettaAgentClientBase {
   }
   registerTools(options) {
     this.assertOpen();
-    if (this.backend === "cloud") {
-      return Promise.reject(new Error('registerTools() requires backend: "local" or "remote". Cloud sessions register tools through the tools session option.'));
+    if (this.backend === "cloud" && registeredComputerName(this.options) === undefined) {
+      return Promise.reject(new Error('registerTools() requires backend: "local" or "remote", or backend: "cloud" with registerComputer. Other Cloud sessions register tools through the tools session option.'));
     }
     this.toolRegistry ??= new ToolRegistry(this.backend === "remote" ? this.remoteOptions() : this.localAppServerConnection());
     return this.toolRegistry.register(options);
@@ -17709,7 +17819,8 @@ class LettaAgentClientBase {
     if (this.backend !== "cloud") {
       throw new Error('Letta Cloud options requested for non-"cloud" backend.');
     }
-    return this.options;
+    const options = this.options;
+    return options.registerComputer !== undefined ? { ...options, computer: { name: options.registerComputer.name } } : options;
   }
 }
 // src/stream-events.ts
@@ -18224,6 +18335,9 @@ class LettaAgentClient extends LettaAgentClientBase {
     if (this.backend === "local") {
       throw this.localBackendUnavailableError();
     }
+    if (options.backend === "cloud" && options.registerComputer !== undefined) {
+      throw new Error('registerComputer starts a local Letta Code app-server. Import from "@letta-ai/letta-agent-sdk" in Node.js to use it.');
+    }
   }
 }
 export {
@@ -18236,4 +18350,4 @@ export {
   CloudManagedSandboxExpiredError
 };
 
-//# debugId=E1CFC3CF63B8416B64756E2164756E21
+//# debugId=56DE4B3DCF03FA0964756E2164756E21