@yushaw/sanqian-sdk 0.2.0 → 0.2.2

package/dist/index.mjs

@@ -11,6 +11,11 @@ var DiscoveryManager = class {
   watcher = null;
   onChange = null;
   pollInterval = null;
+  /**
+   * Cached executable path from last successful connection.json read.
+   * Persists even when Sanqian is not running, for use in auto-launch.
+   */
+  cachedExecutable = null;
   /**
    * Get the path to connection.json
    */
@@ -36,6 +41,9 @@ var DiscoveryManager = class {
       if (!info.port || !info.token || !info.pid) {
         return null;
       }
+      if (info.executable) {
+        this.cachedExecutable = info.executable;
+      }
       if (!this.isProcessRunning(info.pid)) {
         return null;
       }
@@ -197,9 +205,22 @@ var DiscoveryManager = class {
   /**
    * Launch Sanqian in hidden/tray mode
    * Returns true if launch was initiated successfully
+   *
+   * Priority for finding Sanqian executable:
+   * 1. customPath parameter (if provided)
+   * 2. Cached executable from connection.json (most reliable)
+   * 3. Search in standard installation locations (fallback)
    */
   launchSanqian(customPath) {
-    const sanqianPath = this.findSanqianPath(customPath);
+    let sanqianPath = null;
+    if (customPath) {
+      sanqianPath = this.findSanqianPath(customPath);
+    } else if (this.cachedExecutable && existsSync(this.cachedExecutable)) {
+      sanqianPath = this.cachedExecutable;
+      console.log(`[SDK] Using cached executable: ${sanqianPath}`);
+    } else {
+      sanqianPath = this.findSanqianPath();
+    }
     if (!sanqianPath) {
       console.error("[SDK] Sanqian executable not found");
       return false;
@@ -212,7 +233,7 @@ var DiscoveryManager = class {
           "/Contents/MacOS/Sanqian",
           ""
         );
-        spawn("open", ["-a", appPath, "--args", "--hidden"], {
+        spawn("open", ["-g", "-a", appPath, "--args", "--hidden"], {
           detached: true,
           stdio: "ignore"
         }).unref();
@@ -241,6 +262,172 @@ var DiscoveryManager = class {
   }
 };
 
+// src/errors.ts
+var SANQIAN_WEBSITE = "https://sanqian.io";
+var SDKErrorCode = /* @__PURE__ */ ((SDKErrorCode2) => {
+  SDKErrorCode2["NOT_INSTALLED"] = "NOT_INSTALLED";
+  SDKErrorCode2["NOT_RUNNING"] = "NOT_RUNNING";
+  SDKErrorCode2["CONNECTION_TIMEOUT"] = "CONNECTION_TIMEOUT";
+  SDKErrorCode2["STARTUP_TIMEOUT"] = "STARTUP_TIMEOUT";
+  SDKErrorCode2["REGISTRATION_FAILED"] = "REGISTRATION_FAILED";
+  SDKErrorCode2["REQUEST_TIMEOUT"] = "REQUEST_TIMEOUT";
+  SDKErrorCode2["REQUEST_FAILED"] = "REQUEST_FAILED";
+  SDKErrorCode2["DISCONNECTED"] = "DISCONNECTED";
+  SDKErrorCode2["WEBSOCKET_ERROR"] = "WEBSOCKET_ERROR";
+  SDKErrorCode2["AGENT_NOT_FOUND"] = "AGENT_NOT_FOUND";
+  SDKErrorCode2["CONVERSATION_NOT_FOUND"] = "CONVERSATION_NOT_FOUND";
+  SDKErrorCode2["TOOL_NOT_FOUND"] = "TOOL_NOT_FOUND";
+  SDKErrorCode2["TOOL_EXECUTION_TIMEOUT"] = "TOOL_EXECUTION_TIMEOUT";
+  return SDKErrorCode2;
+})(SDKErrorCode || {});
+var ErrorMessages = {
+  ["NOT_INSTALLED" /* NOT_INSTALLED */]: {
+    en: `Sanqian is not installed on this computer.`,
+    zh: `Sanqian \u5C1A\u672A\u5B89\u88C5\u5728\u6B64\u7535\u8111\u4E0A\u3002`,
+    hint: {
+      en: `Please download and install Sanqian from ${SANQIAN_WEBSITE}`,
+      zh: `\u8BF7\u8BBF\u95EE ${SANQIAN_WEBSITE} \u4E0B\u8F7D\u5B89\u88C5 Sanqian`
+    }
+  },
+  ["NOT_RUNNING" /* NOT_RUNNING */]: {
+    en: `Sanqian is not running.`,
+    zh: `Sanqian \u672A\u5728\u8FD0\u884C\u3002`,
+    hint: {
+      en: `Please start Sanqian first, or enable autoLaunchSanqian option in SDK config.`,
+      zh: `\u8BF7\u5148\u542F\u52A8 Sanqian\uFF0C\u6216\u5728 SDK \u914D\u7F6E\u4E2D\u542F\u7528 autoLaunchSanqian \u9009\u9879\u3002`
+    }
+  },
+  ["CONNECTION_TIMEOUT" /* CONNECTION_TIMEOUT */]: {
+    en: `Failed to connect to Sanqian (connection timeout).`,
+    zh: `\u8FDE\u63A5 Sanqian \u5931\u8D25\uFF08\u8FDE\u63A5\u8D85\u65F6\uFF09\u3002`,
+    hint: {
+      en: `Please check if Sanqian is running properly. If the problem persists, try restarting Sanqian.`,
+      zh: `\u8BF7\u68C0\u67E5 Sanqian \u662F\u5426\u6B63\u5E38\u8FD0\u884C\u3002\u5982\u95EE\u9898\u6301\u7EED\uFF0C\u8BF7\u5C1D\u8BD5\u91CD\u542F Sanqian\u3002`
+    }
+  },
+  ["STARTUP_TIMEOUT" /* STARTUP_TIMEOUT */]: {
+    en: `Sanqian failed to start within 2 minutes.`,
+    zh: `Sanqian \u5728 2 \u5206\u949F\u5185\u672A\u80FD\u542F\u52A8\u3002`,
+    hint: {
+      en: `Please try starting Sanqian manually. If it fails to start, reinstall from ${SANQIAN_WEBSITE}`,
+      zh: `\u8BF7\u5C1D\u8BD5\u624B\u52A8\u542F\u52A8 Sanqian\u3002\u5982\u4ECD\u65E0\u6CD5\u542F\u52A8\uFF0C\u8BF7\u4ECE ${SANQIAN_WEBSITE} \u91CD\u65B0\u5B89\u88C5\u3002`
+    }
+  },
+  ["REGISTRATION_FAILED" /* REGISTRATION_FAILED */]: {
+    en: `Failed to register with Sanqian.`,
+    zh: `\u5411 Sanqian \u6CE8\u518C\u5931\u8D25\u3002`,
+    hint: {
+      en: `Please check your SDK configuration (appName, tools). If the problem persists, try restarting Sanqian.`,
+      zh: `\u8BF7\u68C0\u67E5 SDK \u914D\u7F6E\uFF08appName\u3001tools\uFF09\u3002\u5982\u95EE\u9898\u6301\u7EED\uFF0C\u8BF7\u5C1D\u8BD5\u91CD\u542F Sanqian\u3002`
+    }
+  },
+  ["REQUEST_TIMEOUT" /* REQUEST_TIMEOUT */]: {
+    en: `Request timed out.`,
+    zh: `\u8BF7\u6C42\u8D85\u65F6\u3002`,
+    hint: {
+      en: `The operation took too long. Please try again.`,
+      zh: `\u64CD\u4F5C\u8017\u65F6\u8FC7\u957F\uFF0C\u8BF7\u91CD\u8BD5\u3002`
+    }
+  },
+  ["REQUEST_FAILED" /* REQUEST_FAILED */]: {
+    en: `Request failed.`,
+    zh: `\u8BF7\u6C42\u5931\u8D25\u3002`,
+    hint: {
+      en: `Please check the error details and try again.`,
+      zh: `\u8BF7\u68C0\u67E5\u9519\u8BEF\u8BE6\u60C5\u540E\u91CD\u8BD5\u3002`
+    }
+  },
+  ["DISCONNECTED" /* DISCONNECTED */]: {
+    en: `Disconnected from Sanqian.`,
+    zh: `\u4E0E Sanqian \u7684\u8FDE\u63A5\u5DF2\u65AD\u5F00\u3002`,
+    hint: {
+      en: `The SDK will automatically reconnect. If problems persist, check if Sanqian is still running.`,
+      zh: `SDK \u4F1A\u81EA\u52A8\u91CD\u8FDE\u3002\u5982\u95EE\u9898\u6301\u7EED\uFF0C\u8BF7\u68C0\u67E5 Sanqian \u662F\u5426\u4ECD\u5728\u8FD0\u884C\u3002`
+    }
+  },
+  ["WEBSOCKET_ERROR" /* WEBSOCKET_ERROR */]: {
+    en: `WebSocket connection error.`,
+    zh: `WebSocket \u8FDE\u63A5\u9519\u8BEF\u3002`,
+    hint: {
+      en: `Please check your network and firewall settings. Sanqian uses local WebSocket on port shown in settings.`,
+      zh: `\u8BF7\u68C0\u67E5\u7F51\u7EDC\u548C\u9632\u706B\u5899\u8BBE\u7F6E\u3002Sanqian \u4F7F\u7528\u672C\u5730 WebSocket\uFF0C\u7AEF\u53E3\u53EF\u5728\u8BBE\u7F6E\u4E2D\u67E5\u770B\u3002`
+    }
+  },
+  ["AGENT_NOT_FOUND" /* AGENT_NOT_FOUND */]: {
+    en: `Agent not found.`,
+    zh: `\u627E\u4E0D\u5230\u8BE5 Agent\u3002`,
+    hint: {
+      en: `Please check the agent ID. Use listAgents() to see available agents.`,
+      zh: `\u8BF7\u68C0\u67E5 Agent ID\u3002\u4F7F\u7528 listAgents() \u67E5\u770B\u53EF\u7528\u7684 Agent\u3002`
+    }
+  },
+  ["CONVERSATION_NOT_FOUND" /* CONVERSATION_NOT_FOUND */]: {
+    en: `Conversation not found.`,
+    zh: `\u627E\u4E0D\u5230\u8BE5\u5BF9\u8BDD\u3002`,
+    hint: {
+      en: `The conversation may have been deleted. Start a new conversation with startConversation().`,
+      zh: `\u8BE5\u5BF9\u8BDD\u53EF\u80FD\u5DF2\u88AB\u5220\u9664\u3002\u4F7F\u7528 startConversation() \u5F00\u59CB\u65B0\u5BF9\u8BDD\u3002`
+    }
+  },
+  ["TOOL_NOT_FOUND" /* TOOL_NOT_FOUND */]: {
+    en: `Tool not found.`,
+    zh: `\u627E\u4E0D\u5230\u8BE5\u5DE5\u5177\u3002`,
+    hint: {
+      en: `Please check that the tool is registered in your SDK config.`,
+      zh: `\u8BF7\u68C0\u67E5\u8BE5\u5DE5\u5177\u662F\u5426\u5DF2\u5728 SDK \u914D\u7F6E\u4E2D\u6CE8\u518C\u3002`
+    }
+  },
+  ["TOOL_EXECUTION_TIMEOUT" /* TOOL_EXECUTION_TIMEOUT */]: {
+    en: `Tool execution timed out.`,
+    zh: `\u5DE5\u5177\u6267\u884C\u8D85\u65F6\u3002`,
+    hint: {
+      en: `The tool took too long to execute. Consider increasing toolExecutionTimeout in SDK config.`,
+      zh: `\u5DE5\u5177\u6267\u884C\u65F6\u95F4\u8FC7\u957F\u3002\u53EF\u5728 SDK \u914D\u7F6E\u4E2D\u589E\u52A0 toolExecutionTimeout\u3002`
+    }
+  }
+};
+var SanqianSDKError = class extends Error {
+  code;
+  messageZh;
+  hint;
+  hintZh;
+  constructor(code, details) {
+    const msg = ErrorMessages[code];
+    const fullMessage = details ? `${msg.en} ${details}` : msg.en;
+    super(fullMessage);
+    this.name = "SanqianSDKError";
+    this.code = code;
+    this.messageZh = details ? `${msg.zh} ${details}` : msg.zh;
+    this.hint = msg.hint?.en;
+    this.hintZh = msg.hint?.zh;
+  }
+  /**
+   * Get full error message with hint (English)
+   */
+  getFullMessage() {
+    return this.hint ? `${this.message}
+${this.hint}` : this.message;
+  }
+  /**
+   * Get full error message with hint (Chinese)
+   */
+  getFullMessageZh() {
+    return this.hintZh ? `${this.messageZh}
+${this.hintZh}` : this.messageZh;
+  }
+  /**
+   * Get bilingual error message
+   */
+  getBilingualMessage() {
+    return `${this.getFullMessage()}
+
+${this.getFullMessageZh()}`;
+  }
+};
+function createSDKError(code, details) {
+  return new SanqianSDKError(code, details);
+}
+
 // src/client.ts
 var SanqianSDK = class _SanqianSDK {
   config;
@@ -263,6 +450,8 @@ var SanqianSDK = class _SanqianSDK {
   heartbeatAckPending = false;
   missedHeartbeats = 0;
   static MAX_MISSED_HEARTBEATS = 2;
+  // Connection promise for deduplication (prevents multiple concurrent connect attempts)
+  connectingPromise = null;
   // Event listeners
   eventListeners = /* @__PURE__ */ new Map();
   constructor(config) {
@@ -288,40 +477,12 @@ var SanqianSDK = class _SanqianSDK {
    *
    * If autoLaunchSanqian is enabled and Sanqian is not running,
    * SDK will attempt to start it in hidden/tray mode.
+   *
+   * @throws Error if Sanqian executable cannot be found (when autoLaunchSanqian is enabled)
+   * @throws Error if connection times out after 2 minutes
    */
   async connect() {
-    const info = this.discovery.read();
-    if (!info) {
-      if (this.config.autoLaunchSanqian) {
-        console.log("[SDK] Sanqian not running, attempting to launch...");
-        const launched = this.discovery.launchSanqian(this.config.sanqianPath);
-        if (launched) {
-          console.log("[SDK] Sanqian launch initiated, waiting for startup...");
-        } else {
-          console.warn("[SDK] Failed to launch Sanqian, will wait for manual start");
-        }
-      }
-      return new Promise((resolve, reject) => {
-        console.log("[SDK] Waiting for Sanqian...");
-        const timeout = setTimeout(() => {
-          this.discovery.stopWatching();
-          reject(new Error("Sanqian connection timeout"));
-        }, 6e4);
-        this.discovery.startWatching(async (newInfo) => {
-          if (newInfo) {
-            clearTimeout(timeout);
-            this.discovery.stopWatching();
-            try {
-              await this.connectWithInfo(newInfo);
-              resolve();
-            } catch (e) {
-              reject(e);
-            }
-          }
-        });
-      });
-    }
-    await this.connectWithInfo(info);
+    return this.ensureReady();
   }
   /**
    * Connect with known connection info
@@ -333,7 +494,7 @@ var SanqianSDK = class _SanqianSDK {
       console.log(`[SDK] Connecting to ${url}`);
       this.ws = new WebSocket(url);
       const connectTimeout = setTimeout(() => {
-        reject(new Error("WebSocket connection timeout"));
+        reject(createSDKError("CONNECTION_TIMEOUT" /* CONNECTION_TIMEOUT */));
         this.ws?.close();
       }, 1e4);
       this.ws.on("open", async () => {
@@ -414,7 +575,7 @@ var SanqianSDK = class _SanqianSDK {
         1e4
       );
       if (!response.success) {
-        throw new Error(response.error || "Registration failed");
+        throw createSDKError("REGISTRATION_FAILED" /* REGISTRATION_FAILED */, response.error);
       }
       this.state.registering = false;
       this.state.registered = true;
@@ -546,7 +707,7 @@ var SanqianSDK = class _SanqianSDK {
     this.state.registered = false;
     this.emit("disconnected", reason);
     for (const [, pending] of this.pendingRequests) {
-      pending.reject(new Error("Disconnected"));
+      pending.reject(createSDKError("DISCONNECTED" /* DISCONNECTED */));
     }
     this.pendingRequests.clear();
     this.scheduleReconnect();
@@ -638,7 +799,7 @@ var SanqianSDK = class _SanqianSDK {
     return new Promise((resolve, reject) => {
       const timer = setTimeout(() => {
         this.pendingRequests.delete(id);
-        reject(new Error("Request timeout"));
+        reject(createSDKError("REQUEST_TIMEOUT" /* REQUEST_TIMEOUT */));
       }, timeout);
       this.pendingRequests.set(id, {
         resolve: (value) => {
@@ -675,57 +836,73 @@ var SanqianSDK = class _SanqianSDK {
     return this.state.connected && this.state.registered;
   }
   /**
-   * Wait for connection to be established.
-   * Used internally by chat() and chatStream() for auto-reconnect.
-   * Relies on background scheduleReconnect() to do the actual reconnection.
+   * Ensure SDK is ready for API calls.
+   *
+   * This is the unified entry point for all API methods that require a connection.
+   * It handles:
+   * - Already connected: returns immediately
+   * - Connection in progress: waits for existing attempt (deduplication)
+   * - Not connected: initiates connection (with optional auto-launch)
+   *
+   * Design pattern: gRPC wait-for-ready + ClientFactory promise deduplication
+   *
+   * @throws Error if connection fails or times out
    */
-  async waitForConnection(timeout = 3e4) {
+  async ensureReady() {
     if (this.isConnected()) {
       return;
     }
-    console.log("[SDK] Not connected, waiting for reconnection...");
-    return new Promise((resolve, reject) => {
-      let resolved = false;
-      const timer = setTimeout(() => {
-        if (!resolved) {
-          resolved = true;
-          reject(new Error("Connection timeout. Please ensure Sanqian is running."));
-        }
-      }, timeout);
-      this.once("registered", () => {
-        if (!resolved) {
-          resolved = true;
-          clearTimeout(timer);
-          resolve();
-        }
-      });
-      if (this.isConnected()) {
-        if (!resolved) {
-          resolved = true;
-          clearTimeout(timer);
-          resolve();
+    if (this.connectingPromise) {
+      console.log("[SDK] Connection already in progress, waiting...");
+      return this.connectingPromise;
+    }
+    this.connectingPromise = this.doFullConnect();
+    try {
+      await this.connectingPromise;
+    } finally {
+      this.connectingPromise = null;
+    }
+  }
+  /**
+   * Internal: Perform full connection flow
+   * Handles launching Sanqian if needed, then connecting and registering.
+   *
+   * Note: This method is protected by connectingPromise deduplication in ensureReady(),
+   * so there's no need for additional launch-in-progress tracking within a single instance.
+   */
+  async doFullConnect() {
+    console.log("[SDK] Starting full connection flow...");
+    let info = this.discovery.read();
+    if (!info) {
+      if (this.config.autoLaunchSanqian) {
+        console.log("[SDK] Sanqian not running, attempting to launch...");
+        const launched = this.discovery.launchSanqian(this.config.sanqianPath);
+        if (!launched) {
+          throw createSDKError("NOT_INSTALLED" /* NOT_INSTALLED */);
         }
-        return;
+        console.log("[SDK] Sanqian launch initiated, waiting for startup...");
+        info = await this.waitForSanqianStartup();
+      } else {
+        throw createSDKError("NOT_RUNNING" /* NOT_RUNNING */);
       }
-      if (!this.reconnectTimer) {
-        const info = this.discovery.read();
-        if (!info && this.config.autoLaunchSanqian) {
-          console.log("[SDK] Sanqian not running, attempting to launch...");
-          const launched = this.discovery.launchSanqian(this.config.sanqianPath);
-          if (launched) {
-            this.scheduleReconnect();
-          }
-        } else if (!info) {
-          if (!resolved) {
-            resolved = true;
-            clearTimeout(timer);
-            reject(new Error("Sanqian is not running. Please start it manually."));
-          }
-        } else {
-          this.scheduleReconnect();
-        }
+    }
+    await this.connectWithInfo(info);
+  }
+  /**
+   * Wait for Sanqian to start and connection.json to become available
+   */
+  async waitForSanqianStartup(timeout = 12e4) {
+    const startTime = Date.now();
+    const pollInterval = 500;
+    while (Date.now() - startTime < timeout) {
+      const info = this.discovery.read();
+      if (info) {
+        console.log("[SDK] Sanqian started, connection info available");
+        return info;
       }
-    });
+      await new Promise((resolve) => setTimeout(resolve, pollInterval));
+    }
+    throw createSDKError("STARTUP_TIMEOUT" /* STARTUP_TIMEOUT */);
   }
   /**
    * Update tool list dynamically
@@ -762,9 +939,7 @@ var SanqianSDK = class _SanqianSDK {
    * @returns Full agent info (or agent_id string for backward compatibility)
    */
   async createAgent(config) {
-    if (!this.isConnected()) {
-      throw new Error("Not connected to Sanqian");
-    }
+    await this.ensureReady();
     const msgId = this.generateId();
     const message = {
       id: msgId,
@@ -773,7 +948,7 @@ var SanqianSDK = class _SanqianSDK {
     };
     const response = await this.sendAndWait(message, msgId, 1e4);
     if (!response.success) {
-      throw new Error(response.error || "Failed to create agent");
+      throw createSDKError("AGENT_NOT_FOUND" /* AGENT_NOT_FOUND */, response.error);
     }
     if (response.agent) {
       return response.agent;
@@ -789,9 +964,7 @@ var SanqianSDK = class _SanqianSDK {
    * List all private agents owned by this app
    */
   async listAgents() {
-    if (!this.isConnected()) {
-      throw new Error("Not connected to Sanqian");
-    }
+    await this.ensureReady();
     const msgId = this.generateId();
     const message = {
       id: msgId,
@@ -807,9 +980,7 @@ var SanqianSDK = class _SanqianSDK {
    * Delete a private agent
    */
   async deleteAgent(agentId) {
-    if (!this.isConnected()) {
-      throw new Error("Not connected to Sanqian");
-    }
+    await this.ensureReady();
     const msgId = this.generateId();
     const message = {
       id: msgId,
@@ -818,7 +989,7 @@ var SanqianSDK = class _SanqianSDK {
     };
     const response = await this.sendAndWait(message, msgId, 1e4);
     if (!response.success) {
-      throw new Error(response.error || "Failed to delete agent");
+      throw createSDKError("AGENT_NOT_FOUND" /* AGENT_NOT_FOUND */, response.error);
     }
   }
   /**
@@ -830,9 +1001,7 @@ var SanqianSDK = class _SanqianSDK {
    * @returns Updated agent info
    */
   async updateAgent(agentId, updates) {
-    if (!this.isConnected()) {
-      throw new Error("Not connected to Sanqian");
-    }
+    await this.ensureReady();
     const msgId = this.generateId();
     const message = {
       id: msgId,
@@ -842,7 +1011,7 @@ var SanqianSDK = class _SanqianSDK {
     };
     const response = await this.sendAndWait(message, msgId, 1e4);
     if (!response.success || !response.agent) {
-      throw new Error(response.error || "Failed to update agent");
+      throw createSDKError("AGENT_NOT_FOUND" /* AGENT_NOT_FOUND */, response.error);
     }
     return response.agent;
   }
@@ -853,9 +1022,7 @@ var SanqianSDK = class _SanqianSDK {
    * List conversations for this app
    */
   async listConversations(options) {
-    if (!this.isConnected()) {
-      throw new Error("Not connected to Sanqian");
-    }
+    await this.ensureReady();
     const msgId = this.generateId();
     const message = {
       id: msgId,
@@ -877,9 +1044,7 @@ var SanqianSDK = class _SanqianSDK {
    * Get conversation details with messages
    */
   async getConversation(conversationId, options) {
-    if (!this.isConnected()) {
-      throw new Error("Not connected to Sanqian");
-    }
+    await this.ensureReady();
     const msgId = this.generateId();
     const message = {
       id: msgId,
@@ -891,7 +1056,7 @@ var SanqianSDK = class _SanqianSDK {
     };
     const response = await this.sendAndWait(message, msgId, 1e4);
     if (!response.success || !response.conversation) {
-      throw new Error(response.error || "Failed to get conversation");
+      throw createSDKError("CONVERSATION_NOT_FOUND" /* CONVERSATION_NOT_FOUND */, response.error);
     }
     return response.conversation;
   }
@@ -899,9 +1064,7 @@ var SanqianSDK = class _SanqianSDK {
    * Delete a conversation
    */
   async deleteConversation(conversationId) {
-    if (!this.isConnected()) {
-      throw new Error("Not connected to Sanqian");
-    }
+    await this.ensureReady();
     const msgId = this.generateId();
     const message = {
       id: msgId,
@@ -910,7 +1073,7 @@ var SanqianSDK = class _SanqianSDK {
     };
     const response = await this.sendAndWait(message, msgId, 1e4);
     if (!response.success) {
-      throw new Error(response.error || "Failed to delete conversation");
+      throw createSDKError("CONVERSATION_NOT_FOUND" /* CONVERSATION_NOT_FOUND */, response.error);
     }
   }
   // ============================================
@@ -931,10 +1094,7 @@ var SanqianSDK = class _SanqianSDK {
    * @returns Chat response with assistant message and conversation ID
    */
   async chat(agentId, messages, options) {
-    if (!this.isConnected()) {
-      console.log("[SDK] Not connected, attempting to reconnect...");
-      await this.waitForConnection();
-    }
+    await this.ensureReady();
     const msgId = this.generateId();
     const message = {
       id: msgId,
@@ -951,7 +1111,11 @@ var SanqianSDK = class _SanqianSDK {
     };
     const response = await this.sendAndWait(message, msgId, 6e5);
     if (!response.success) {
-      throw new Error(response.error || "Chat request failed");
+      const errorLower = (response.error || "").toLowerCase();
+      if (errorLower.includes("agent") && errorLower.includes("not found")) {
+        throw createSDKError("AGENT_NOT_FOUND" /* AGENT_NOT_FOUND */, response.error);
+      }
+      throw createSDKError("REQUEST_FAILED" /* REQUEST_FAILED */, response.error);
     }
     return {
       message: response.message,
@@ -973,10 +1137,7 @@ var SanqianSDK = class _SanqianSDK {
    * @returns AsyncIterable of stream events
    */
   async *chatStream(agentId, messages, options) {
-    if (!this.isConnected()) {
-      console.log("[SDK] Not connected, attempting to reconnect...");
-      await this.waitForConnection();
-    }
+    await this.ensureReady();
     const msgId = this.generateId();
     const message = {
       id: msgId,
@@ -1102,7 +1263,7 @@ var SanqianSDK = class _SanqianSDK {
   }
   createTimeout(ms) {
     return new Promise((_, reject) => {
-      setTimeout(() => reject(new Error("Timeout")), ms);
+      setTimeout(() => reject(createSDKError("TOOL_EXECUTION_TIMEOUT" /* TOOL_EXECUTION_TIMEOUT */)), ms);
     });
   }
 };
@@ -1185,6 +1346,11 @@ var Conversation = class {
 export {
   Conversation,
   DiscoveryManager,
-  SanqianSDK
+  ErrorMessages,
+  SANQIAN_WEBSITE,
+  SDKErrorCode,
+  SanqianSDK,
+  SanqianSDKError,
+  createSDKError
 };
 //# sourceMappingURL=index.mjs.map