@yushaw/sanqian-sdk 0.2.5 → 0.2.7

package/dist/index.d.mts

@@ -28,6 +28,11 @@ interface SDKConfig {
      * If not provided, SDK will search in standard installation locations
      */
     sanqianPath?: string;
+    /**
+     * Enable debug logging (default: false)
+     * When enabled, SDK will output detailed logs to console
+     */
+    debug?: boolean;
 }
 interface ToolDefinition {
     /** Tool name (without app prefix) */
@@ -218,7 +223,17 @@ declare class SanqianSDK {
     private missedHeartbeats;
     private static readonly MAX_MISSED_HEARTBEATS;
     private connectingPromise;
+    private reconnectRefCount;
+    private launchedBySanqian;
     private eventListeners;
+    /**
+     * Log debug message (only when config.debug is true)
+     */
+    private log;
+    /**
+     * Log warning message (only when config.debug is true)
+     */
+    private warn;
     constructor(config: SDKConfig);
     /**
      * Connect to Sanqian
@@ -247,6 +262,23 @@ declare class SanqianSDK {
     private handleToolCall;
     private sendToolResult;
     private handleDisconnect;
+    /**
+     * Check if auto-reconnect should be enabled
+     * Returns true if any component has requested persistent connection
+     */
+    private shouldAutoReconnect;
+    /**
+     * Request persistent connection (enables auto-reconnect)
+     * Call this when a component needs the connection to stay alive (e.g., chat panel opens)
+     * Must be paired with releaseReconnect() when the component no longer needs it
+     */
+    acquireReconnect(): void;
+    /**
+     * Release persistent connection request
+     * Call this when a component no longer needs the connection (e.g., chat panel closes)
+     * When refCount reaches 0, auto-reconnect is disabled
+     */
+    releaseReconnect(): void;
     private scheduleReconnect;
     private stopReconnect;
     private startHeartbeat;

package/dist/index.d.ts

@@ -28,6 +28,11 @@ interface SDKConfig {
      * If not provided, SDK will search in standard installation locations
      */
     sanqianPath?: string;
+    /**
+     * Enable debug logging (default: false)
+     * When enabled, SDK will output detailed logs to console
+     */
+    debug?: boolean;
 }
 interface ToolDefinition {
     /** Tool name (without app prefix) */
@@ -218,7 +223,17 @@ declare class SanqianSDK {
     private missedHeartbeats;
     private static readonly MAX_MISSED_HEARTBEATS;
     private connectingPromise;
+    private reconnectRefCount;
+    private launchedBySanqian;
     private eventListeners;
+    /**
+     * Log debug message (only when config.debug is true)
+     */
+    private log;
+    /**
+     * Log warning message (only when config.debug is true)
+     */
+    private warn;
     constructor(config: SDKConfig);
     /**
      * Connect to Sanqian
@@ -247,6 +262,23 @@ declare class SanqianSDK {
     private handleToolCall;
     private sendToolResult;
     private handleDisconnect;
+    /**
+     * Check if auto-reconnect should be enabled
+     * Returns true if any component has requested persistent connection
+     */
+    private shouldAutoReconnect;
+    /**
+     * Request persistent connection (enables auto-reconnect)
+     * Call this when a component needs the connection to stay alive (e.g., chat panel opens)
+     * Must be paired with releaseReconnect() when the component no longer needs it
+     */
+    acquireReconnect(): void;
+    /**
+     * Release persistent connection request
+     * Call this when a component no longer needs the connection (e.g., chat panel closes)
+     * When refCount reaches 0, auto-reconnect is disabled
+     */
+    releaseReconnect(): void;
     private scheduleReconnect;
     private stopReconnect;
     private startHeartbeat;

package/dist/index.js

@@ -501,19 +501,53 @@ var SanqianSDK = class _SanqianSDK {
   static MAX_MISSED_HEARTBEATS = 2;
   // Connection promise for deduplication (prevents multiple concurrent connect attempts)
   connectingPromise = null;
+  // Reconnect reference count - when > 0, auto-reconnect is enabled
+  // This allows multiple components to request persistent connections
+  reconnectRefCount = 0;
+  // Whether this app was launched by Sanqian (detected via environment variable)
+  launchedBySanqian = false;
   // Event listeners
   eventListeners = /* @__PURE__ */ new Map();
+  // ============================================
+  // Debug Logging
+  // ============================================
+  /**
+   * Log debug message (only when config.debug is true)
+   */
+  log(...args) {
+    if (this.config.debug) {
+      console.log("[SDK]", ...args);
+    }
+  }
+  /**
+   * Log warning message (only when config.debug is true)
+   */
+  warn(...args) {
+    if (this.config.debug) {
+      console.warn("[SDK]", ...args);
+    }
+  }
   constructor(config) {
     this.config = {
       reconnectInterval: 5e3,
       heartbeatInterval: 3e4,
       toolExecutionTimeout: 3e4,
+      debug: false,
       ...config
     };
     this.discovery = new DiscoveryManager();
     for (const tool of config.tools) {
       this.toolHandlers.set(tool.name, tool.handler);
     }
+    this.launchedBySanqian = typeof process !== "undefined" && process.env?.SANQIAN_NO_RECONNECT === "1";
+    if (this.launchedBySanqian) {
+      this.log("Detected launch by Sanqian, will connect immediately without auto-reconnect");
+      setTimeout(() => {
+        this.connect().catch((err) => {
+          console.error("[SDK] Failed to connect after Sanqian launch:", err);
+        });
+      }, 0);
+    }
   }
   // ============================================
   // Lifecycle
@@ -540,7 +574,7 @@ var SanqianSDK = class _SanqianSDK {
     this.connectionInfo = info;
     const url = this.discovery.buildWebSocketUrl(info);
     return new Promise((resolve, reject) => {
-      console.log(`[SDK] Connecting to ${url}`);
+      this.log(`Connecting to ${url}`);
       this.ws = new import_ws.default(url);
       const connectTimeout = setTimeout(() => {
         reject(createSDKError("CONNECTION_TIMEOUT" /* CONNECTION_TIMEOUT */));
@@ -548,7 +582,7 @@ var SanqianSDK = class _SanqianSDK {
       }, 1e4);
       this.ws.on("open", async () => {
         clearTimeout(connectTimeout);
-        console.log("[SDK] WebSocket connected");
+        this.log("WebSocket connected");
         this.state.connected = true;
         this.state.reconnectAttempts = 0;
         this.emit("connected");
@@ -560,7 +594,7 @@ var SanqianSDK = class _SanqianSDK {
         }
       });
       this.ws.on("close", (code, reason) => {
-        console.log(`[SDK] WebSocket closed: ${code} ${reason.toString()}`);
+        this.log(`WebSocket closed: ${code} ${reason.toString()}`);
         this.handleDisconnect(reason.toString());
       });
       this.ws.on("error", (error) => {
@@ -573,7 +607,7 @@ var SanqianSDK = class _SanqianSDK {
           const message = JSON.parse(data.toString());
           this.handleMessage(message);
         } catch (e) {
-          console.error("[SDK] Failed to parse message:", e);
+          this.warn("Failed to parse message:", e);
         }
       });
     });
@@ -630,7 +664,7 @@ var SanqianSDK = class _SanqianSDK {
       this.state.registered = true;
       this.startHeartbeat();
       this.emit("registered");
-      console.log(`[SDK] Registered as '${this.config.appName}'`);
+      this.log(`Registered as '${this.config.appName}'`);
     } catch (e) {
       this.state.registering = false;
       throw e;
@@ -659,7 +693,7 @@ var SanqianSDK = class _SanqianSDK {
         this.handleChatStream(message);
         break;
       default:
-        console.warn(`[SDK] Unknown message type: ${type}`);
+        this.warn(`Unknown message type: ${type}`);
     }
   }
   handleChatStream(message) {
@@ -667,7 +701,7 @@ var SanqianSDK = class _SanqianSDK {
     if (!id) return;
     const handler = this.streamHandlers.get(id);
     if (!handler) {
-      console.warn(`[SDK] No stream handler for message ${id}`);
+      this.warn(`No stream handler for message ${id}`);
       return;
     }
     switch (event) {
@@ -706,11 +740,11 @@ var SanqianSDK = class _SanqianSDK {
     }
   }
   async handleToolCall(message) {
-    console.log(`[SDK] handleToolCall received:`, JSON.stringify(message));
+    this.log(`handleToolCall received:`, JSON.stringify(message));
     const { id, call_id, name, arguments: args } = message;
     const msgId = id || call_id;
     const toolName = name.includes(":") ? name.split(":")[1] : name;
-    console.log(`[SDK] Looking for handler: '${toolName}', available handlers:`, Array.from(this.toolHandlers.keys()));
+    this.log(`Looking for handler: '${toolName}', available handlers:`, Array.from(this.toolHandlers.keys()));
     const handler = this.toolHandlers.get(toolName);
     this.emit("tool_call", { name: toolName, arguments: args });
     if (!handler) {
@@ -718,19 +752,19 @@ var SanqianSDK = class _SanqianSDK {
       return;
     }
     try {
-      console.log(`[SDK] Executing tool '${toolName}' with args:`, args);
+      this.log(`Executing tool '${toolName}' with args:`, args);
       const result = await Promise.race([
         handler(args),
         this.createTimeout(this.config.toolExecutionTimeout)
       ]);
-      console.log(`[SDK] Tool '${toolName}' completed successfully`);
+      this.log(`Tool '${toolName}' completed successfully`);
       await this.sendToolResult(msgId, call_id, true, result);
     } catch (e) {
       const errorMessage = e instanceof Error ? e.message : String(e);
       const errorStack = e instanceof Error ? e.stack : void 0;
-      console.log(`[SDK] Tool '${toolName}' failed:`, errorMessage);
+      this.log(`Tool '${toolName}' failed:`, errorMessage);
       if (errorStack) {
-        console.log(`[SDK] Tool error stack:`, errorStack);
+        this.log(`Tool error stack:`, errorStack);
       }
       await this.sendToolResult(msgId, call_id, false, void 0, errorMessage);
     }
@@ -744,7 +778,7 @@ var SanqianSDK = class _SanqianSDK {
       result,
       error
     };
-    console.log(`[SDK] Sending tool_result for ${callId}:`, success ? "success" : `error: ${error}`);
+    this.log(`Sending tool_result for ${callId}:`, success ? "success" : `error: ${error}`);
     this.send(message);
   }
   // ============================================
@@ -759,16 +793,49 @@ var SanqianSDK = class _SanqianSDK {
       pending.reject(createSDKError("DISCONNECTED" /* DISCONNECTED */));
     }
     this.pendingRequests.clear();
+    if (reason === "Client disconnect") {
+      this.log("Client disconnected intentionally, skipping auto-reconnect");
+      return;
+    }
     if (reason === "Replaced by new connection") {
-      console.log("[SDK] Connection replaced by newer one, skipping auto-reconnect");
+      this.log("Connection replaced by newer one, skipping auto-reconnect");
       return;
     }
     if (this.connectingPromise) {
-      console.log("[SDK] Connection attempt already in progress, skipping auto-reconnect");
+      this.log("Connection attempt already in progress, skipping auto-reconnect");
+      return;
+    }
+    if (!this.shouldAutoReconnect()) {
+      this.log("No components require reconnection (refCount=0), skipping auto-reconnect");
       return;
     }
     this.scheduleReconnect();
   }
+  /**
+   * Check if auto-reconnect should be enabled
+   * Returns true if any component has requested persistent connection
+   */
+  shouldAutoReconnect() {
+    return this.reconnectRefCount > 0;
+  }
+  /**
+   * Request persistent connection (enables auto-reconnect)
+   * Call this when a component needs the connection to stay alive (e.g., chat panel opens)
+   * Must be paired with releaseReconnect() when the component no longer needs it
+   */
+  acquireReconnect() {
+    this.reconnectRefCount++;
+    this.log(`acquireReconnect: refCount=${this.reconnectRefCount}`);
+  }
+  /**
+   * Release persistent connection request
+   * Call this when a component no longer needs the connection (e.g., chat panel closes)
+   * When refCount reaches 0, auto-reconnect is disabled
+   */
+  releaseReconnect() {
+    this.reconnectRefCount = Math.max(0, this.reconnectRefCount - 1);
+    this.log(`releaseReconnect: refCount=${this.reconnectRefCount}`);
+  }
   scheduleReconnect() {
     if (this.reconnectTimer) return;
     const baseDelay = Math.min(
@@ -778,7 +845,7 @@ var SanqianSDK = class _SanqianSDK {
     );
     const jitter = Math.random() * 500;
     const delay = baseDelay + jitter;
-    console.log(`[SDK] Scheduling reconnect in ${Math.round(delay)}ms (attempt ${this.state.reconnectAttempts + 1})`);
+    this.log(`Scheduling reconnect in ${Math.round(delay)}ms (attempt ${this.state.reconnectAttempts + 1})`);
     this.reconnectTimer = setTimeout(async () => {
       this.reconnectTimer = null;
       this.state.reconnectAttempts++;
@@ -808,9 +875,9 @@ var SanqianSDK = class _SanqianSDK {
     this.heartbeatTimer = setInterval(() => {
       if (this.heartbeatAckPending) {
         this.missedHeartbeats++;
-        console.warn(`[SDK] Missed heartbeat ack (${this.missedHeartbeats}/${_SanqianSDK.MAX_MISSED_HEARTBEATS})`);
+        this.warn(`Missed heartbeat ack (${this.missedHeartbeats}/${_SanqianSDK.MAX_MISSED_HEARTBEATS})`);
         if (this.missedHeartbeats >= _SanqianSDK.MAX_MISSED_HEARTBEATS) {
-          console.error("[SDK] Too many missed heartbeat acks, connection may be dead");
+          this.warn("Too many missed heartbeat acks, connection may be dead");
           this.ws?.close(4e3, "Heartbeat timeout");
           return;
         }
@@ -846,7 +913,7 @@ var SanqianSDK = class _SanqianSDK {
       throw error;
     }
     const data = JSON.stringify(message);
-    console.log(`[SDK] WebSocket send:`, data.substring(0, 200));
+    this.log(`WebSocket send:`, data.substring(0, 200));
     this.ws.send(data);
   }
   sendAndWait(message, id, timeout) {
@@ -907,7 +974,7 @@ var SanqianSDK = class _SanqianSDK {
       return;
     }
     if (this.connectingPromise) {
-      console.log("[SDK] Connection already in progress, waiting...");
+      this.log("Connection already in progress, waiting...");
       return this.connectingPromise;
     }
     this.connectingPromise = this.doFullConnect();
@@ -925,16 +992,16 @@ var SanqianSDK = class _SanqianSDK {
    * so there's no need for additional launch-in-progress tracking within a single instance.
    */
   async doFullConnect() {
-    console.log("[SDK] Starting full connection flow...");
+    this.log("Starting full connection flow...");
     let info = this.discovery.read();
     if (!info) {
       if (this.config.autoLaunchSanqian) {
-        console.log("[SDK] Sanqian not running, attempting to launch...");
+        this.log("Sanqian not running, attempting to launch...");
         const launched = this.discovery.launchSanqian(this.config.sanqianPath);
         if (!launched) {
           throw createSDKError("NOT_INSTALLED" /* NOT_INSTALLED */);
         }
-        console.log("[SDK] Sanqian launch initiated, waiting for startup...");
+        this.log("Sanqian launch initiated, waiting for startup...");
         info = await this.waitForSanqianStartup();
       } else {
         throw createSDKError("NOT_RUNNING" /* NOT_RUNNING */);
@@ -951,7 +1018,7 @@ var SanqianSDK = class _SanqianSDK {
     while (Date.now() - startTime < timeout) {
       const info = this.discovery.read();
       if (info) {
-        console.log("[SDK] Sanqian started, connection info available");
+        this.log("Sanqian started, connection info available");
         return info;
       }
       await new Promise((resolve) => setTimeout(resolve, pollInterval));