Add agents module documentation and fix copy script for new docs.json structure

- Add JSDoc documentation for agents module (conversations, messages, realtime subscriptions)
- Fix copy-to-local-docs script to match current docs.json nav structure (SDK anchor instead of References > JavaScript SDK)

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: wixysam

scripts/mintlify-post-processing/copy-to-local-docs.js

@@ -159,7 +159,7 @@ function updateDocsJson(repoDir, sdkFiles) {
     `SDK Reference pages: ${JSON.stringify(sdkReferencePages, null, 2)}`
   );
 
-  // Navigate to: Developers tab -> anchors -> References anchor -> groups -> JavaScript SDK -> SDK Reference
+  // Navigate to: Developers tab -> anchors -> SDK anchor -> groups -> SDK Reference
   const developersTab = docs.navigation.tabs.find(
     (tab) => tab.tab === "Developers"
   );
@@ -169,42 +169,31 @@ function updateDocsJson(repoDir, sdkFiles) {
     process.exit(1);
   }
 
-  // Find the References anchor (new structure uses anchors instead of groups at tab level)
-  const referencesAnchor = developersTab.anchors?.find(
-    (anchor) => anchor.anchor === "References"
+  // Find the SDK anchor
+  const sdkAnchor = developersTab.anchors?.find(
+    (anchor) => anchor.anchor === "SDK"
   );
 
-  if (!referencesAnchor) {
-    console.error("Could not find 'References' anchor in Developers tab");
+  if (!sdkAnchor) {
+    console.error("Could not find 'SDK' anchor in Developers tab");
     process.exit(1);
   }
 
-  // Find the JavaScript SDK group within the References anchor
-  const jsSdkGroup = referencesAnchor.groups?.find(
-    (g) => g.group === "JavaScript SDK"
-  );
-
-  if (!jsSdkGroup) {
-    console.error(
-      "Could not find 'JavaScript SDK' group in References anchor"
-    );
-    process.exit(1);
-  }
-
-  // Find SDK Reference within JavaScript SDK's pages (it's a nested group object)
-  const sdkRefIndex = jsSdkGroup.pages.findIndex(
-    (page) => typeof page === "object" && page.group === "SDK Reference"
+  // Find SDK Reference within the SDK anchor's groups
+  const sdkRefIndex = sdkAnchor.groups.findIndex(
+    (g) => g.group === "SDK Reference"
   );
 
   if (sdkRefIndex === -1) {
-    console.error("Could not find 'SDK Reference' group in JavaScript SDK");
+    console.error("Could not find 'SDK Reference' group in SDK anchor");
     process.exit(1);
   }
 
   // Update the SDK Reference pages with our generated groups
-  jsSdkGroup.pages[sdkRefIndex] = {
+  sdkAnchor.groups[sdkRefIndex] = {
     group: "SDK Reference",
     icon: "brackets-curly",
+    expanded: true,
     pages: sdkReferencePages,
   };
 

src/modules/agents.types.ts

@@ -181,7 +181,7 @@ export interface AgentsModuleConfig {
  *
  * This module is available to use with a client in all authentication modes:
  *
- * - **Anonymous or User authentication** (`base44.agents`): Access is scoped to the current user's permissions. Anonymous users can create conversations but can't retrieve them later, while authenticated users can access conversations they created.
+ * - **Anonymous or User authentication** (`base44.agents`): Access is scoped to the current user's permissions. Users must be authenticated to create and access conversations.
  * - **Service role authentication** (`base44.asServiceRole.agents`): Operations have elevated admin-level permissions. Can access all conversations that the app's admin role has access to.
  *
  */
@@ -211,6 +211,8 @@ export interface AgentsModule {
    * Retrieves a single conversation using its unique identifier. To retrieve
    * all conversations, use {@linkcode getConversations | getConversations()} To filter, sort, or paginate conversations, use {@linkcode listConversations | listConversations()}.
    *
+   * This function returns the complete stored conversation including full tool call results, even for large responses.
+   *
    * @param conversationId - The unique identifier of the conversation.
    * @returns Promise resolving to the conversation, or undefined if not found.
    *
@@ -322,6 +324,10 @@ export interface AgentsModule {
    * Establishes a WebSocket connection to receive instant updates when new
    * messages are added to the conversation. Returns an unsubscribe function
    * to clean up the connection.
+   * 
+   * <Note>
+When receiving messages through this function, tool call data is truncated for efficiency — `arguments_string` is limited to 500 characters and `results` to 50 characters. The complete tool call data is always saved in storage and can be retrieved by calling {@linkcode getConversation | getConversation()} after the message completes.
+</Note>
    *
    * @param conversationId - The conversation ID to subscribe to.
    * @param onUpdate - Callback function called when the conversation is updated. The callback receives a conversation object with the following properties: