@yushaw/sanqian-sdk 0.2.0 → 0.2.1

package/dist/index.d.mts

@@ -63,6 +63,8 @@ interface ConnectionInfo {
     token: string;
     pid: number;
     started_at: string;
+    /** Path to Sanqian executable (for SDK auto-launch) */
+    executable?: string;
 }
 interface ConnectionState {
     connected: boolean;
@@ -215,6 +217,7 @@ declare class SanqianSDK {
     private heartbeatAckPending;
     private missedHeartbeats;
     private static readonly MAX_MISSED_HEARTBEATS;
+    private connectingPromise;
     private eventListeners;
     constructor(config: SDKConfig);
     /**
@@ -225,6 +228,9 @@ declare 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
      */
     connect(): Promise<void>;
     /**
@@ -256,11 +262,31 @@ declare class SanqianSDK {
      */
     isConnected(): boolean;
     /**
-     * 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
+     */
+    ensureReady(): Promise<void>;
+    /**
+     * 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.
+     */
+    private doFullConnect;
+    /**
+     * Wait for Sanqian to start and connection.json to become available
      */
-    private waitForConnection;
+    private waitForSanqianStartup;
     /**
      * Update tool list dynamically
      */
@@ -431,6 +457,11 @@ declare class DiscoveryManager {
     private watcher;
     private onChange;
     private pollInterval;
+    /**
+     * Cached executable path from last successful connection.json read.
+     * Persists even when Sanqian is not running, for use in auto-launch.
+     */
+    private cachedExecutable;
     /**
      * Get the path to connection.json
      */
@@ -482,6 +513,11 @@ declare class DiscoveryManager {
     /**
      * 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?: string): boolean;
     /**

package/dist/index.d.ts

@@ -63,6 +63,8 @@ interface ConnectionInfo {
     token: string;
     pid: number;
     started_at: string;
+    /** Path to Sanqian executable (for SDK auto-launch) */
+    executable?: string;
 }
 interface ConnectionState {
     connected: boolean;
@@ -215,6 +217,7 @@ declare class SanqianSDK {
     private heartbeatAckPending;
     private missedHeartbeats;
     private static readonly MAX_MISSED_HEARTBEATS;
+    private connectingPromise;
     private eventListeners;
     constructor(config: SDKConfig);
     /**
@@ -225,6 +228,9 @@ declare 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
      */
     connect(): Promise<void>;
     /**
@@ -256,11 +262,31 @@ declare class SanqianSDK {
      */
     isConnected(): boolean;
     /**
-     * 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
+     */
+    ensureReady(): Promise<void>;
+    /**
+     * 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.
+     */
+    private doFullConnect;
+    /**
+     * Wait for Sanqian to start and connection.json to become available
      */
-    private waitForConnection;
+    private waitForSanqianStartup;
     /**
      * Update tool list dynamically
      */
@@ -431,6 +457,11 @@ declare class DiscoveryManager {
     private watcher;
     private onChange;
     private pollInterval;
+    /**
+     * Cached executable path from last successful connection.json read.
+     * Persists even when Sanqian is not running, for use in auto-launch.
+     */
+    private cachedExecutable;
     /**
      * Get the path to connection.json
      */
@@ -482,6 +513,11 @@ declare class DiscoveryManager {
     /**
      * 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?: string): boolean;
     /**

package/dist/index.js

@@ -49,6 +49,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
    */
@@ -74,6 +79,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;
       }
@@ -235,9 +243,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 && (0, import_fs.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;
@@ -301,6 +322,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) {
@@ -326,40 +349,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
@@ -713,57 +708,77 @@ 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 new Error(
+            "Sanqian executable not found. Please ensure Sanqian is installed, or provide a custom path via sanqianPath config option."
+          );
         }
-        return;
+        console.log("[SDK] Sanqian launch initiated, waiting for startup...");
+        info = await this.waitForSanqianStartup();
+      } else {
+        throw new Error("Sanqian is not running. Please start it manually.");
       }
-      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 new Error(
+      "Sanqian startup timeout (2 minutes). Please check if Sanqian started correctly."
+    );
   }
   /**
    * Update tool list dynamically
@@ -800,9 +815,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,
@@ -827,9 +840,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,
@@ -845,9 +856,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,
@@ -868,9 +877,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,
@@ -891,9 +898,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,
@@ -915,9 +920,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,
@@ -937,9 +940,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,
@@ -969,10 +970,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,
@@ -1011,10 +1009,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,