@yushaw/sanqian-sdk 0.1.0

package/dist/index.mjs

@@ -0,0 +1,1069 @@
+// src/client.ts
+import WebSocket from "ws";
+
+// src/discovery.ts
+import { existsSync, readFileSync, watch } from "fs";
+import { homedir, platform } from "os";
+import { join } from "path";
+import { spawn } from "child_process";
+var DiscoveryManager = class {
+  connectionInfo = null;
+  watcher = null;
+  onChange = null;
+  pollInterval = null;
+  /**
+   * Get the path to connection.json
+   */
+  getConnectionFilePath() {
+    return join(homedir(), ".sanqian", "runtime", "connection.json");
+  }
+  /**
+   * Read and validate connection info
+   *
+   * Returns null if:
+   * - File doesn't exist
+   * - File is invalid JSON
+   * - Process is not running
+   */
+  read() {
+    const filePath = this.getConnectionFilePath();
+    if (!existsSync(filePath)) {
+      return null;
+    }
+    try {
+      const content = readFileSync(filePath, "utf-8");
+      const info = JSON.parse(content);
+      if (!info.port || !info.token || !info.pid) {
+        return null;
+      }
+      if (!this.isProcessRunning(info.pid)) {
+        return null;
+      }
+      this.connectionInfo = info;
+      return info;
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Start watching for connection file changes
+   */
+  startWatching(onChange) {
+    this.onChange = onChange;
+    const dir = join(homedir(), ".sanqian", "runtime");
+    if (!existsSync(dir)) {
+      this.pollInterval = setInterval(() => {
+        if (existsSync(dir)) {
+          if (this.pollInterval) {
+            clearInterval(this.pollInterval);
+            this.pollInterval = null;
+          }
+          this.setupWatcher(dir);
+        }
+      }, 2e3);
+      return;
+    }
+    this.setupWatcher(dir);
+  }
+  setupWatcher(dir) {
+    try {
+      this.watcher = watch(dir, (event, filename) => {
+        if (filename === "connection.json") {
+          setTimeout(() => {
+            const newInfo = this.read();
+            const oldInfoStr = JSON.stringify(this.connectionInfo);
+            const newInfoStr = JSON.stringify(newInfo);
+            if (oldInfoStr !== newInfoStr) {
+              this.connectionInfo = newInfo;
+              this.onChange?.(newInfo);
+            }
+          }, 100);
+        }
+      });
+    } catch (e) {
+      console.error("Failed to watch connection file:", e);
+    }
+  }
+  /**
+   * Stop watching
+   */
+  stopWatching() {
+    if (this.pollInterval) {
+      clearInterval(this.pollInterval);
+      this.pollInterval = null;
+    }
+    this.watcher?.close();
+    this.watcher = null;
+    this.onChange = null;
+  }
+  /**
+   * Check if a process is running by PID
+   */
+  isProcessRunning(pid) {
+    try {
+      process.kill(pid, 0);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * Get cached connection info (may be stale)
+   */
+  getCached() {
+    return this.connectionInfo;
+  }
+  /**
+   * Build WebSocket URL from connection info
+   */
+  buildWebSocketUrl(info) {
+    return `ws://127.0.0.1:${info.port}${info.ws_path}?token=${info.token}`;
+  }
+  /**
+   * Build HTTP base URL from connection info
+   */
+  buildHttpUrl(info) {
+    return `http://127.0.0.1:${info.port}`;
+  }
+  /**
+   * Find Sanqian executable path
+   * Searches in standard installation locations for each platform
+   */
+  findSanqianPath(customPath) {
+    if (customPath) {
+      if (existsSync(customPath)) {
+        return customPath;
+      }
+      console.warn(`[SDK] Custom Sanqian path not found: ${customPath}`);
+      return null;
+    }
+    const os = platform();
+    const searchPaths = [];
+    if (os === "darwin") {
+      searchPaths.push(
+        // Production: installed app
+        "/Applications/Sanqian.app/Contents/MacOS/Sanqian",
+        join(homedir(), "Applications/Sanqian.app/Contents/MacOS/Sanqian"),
+        // Development: electron-builder output
+        join(homedir(), "dev/sanqian/dist/mac-arm64/Sanqian.app/Contents/MacOS/Sanqian"),
+        join(homedir(), "dev/sanqian/dist/mac/Sanqian.app/Contents/MacOS/Sanqian")
+      );
+    } else if (os === "win32") {
+      const programFiles = process.env.PROGRAMFILES || "C:\\Program Files";
+      const programFilesX86 = process.env["PROGRAMFILES(X86)"] || "C:\\Program Files (x86)";
+      const localAppData = process.env.LOCALAPPDATA || join(homedir(), "AppData", "Local");
+      searchPaths.push(
+        // Production: installed app
+        join(programFiles, "Sanqian", "Sanqian.exe"),
+        join(programFilesX86, "Sanqian", "Sanqian.exe"),
+        join(localAppData, "Programs", "Sanqian", "Sanqian.exe"),
+        // Development: electron-builder output
+        join(homedir(), "dev", "sanqian", "dist", "win-unpacked", "Sanqian.exe")
+      );
+    } else {
+      searchPaths.push(
+        "/usr/bin/sanqian",
+        "/usr/local/bin/sanqian",
+        join(homedir(), ".local/bin/sanqian"),
+        "/opt/Sanqian/sanqian",
+        // Development
+        join(homedir(), "dev/sanqian/dist/linux-unpacked/sanqian")
+      );
+    }
+    for (const path of searchPaths) {
+      if (existsSync(path)) {
+        return path;
+      }
+    }
+    return null;
+  }
+  /**
+   * Launch Sanqian in hidden/tray mode
+   * Returns true if launch was initiated successfully
+   */
+  launchSanqian(customPath) {
+    const sanqianPath = this.findSanqianPath(customPath);
+    if (!sanqianPath) {
+      console.error("[SDK] Sanqian executable not found");
+      return false;
+    }
+    console.log(`[SDK] Launching Sanqian from: ${sanqianPath}`);
+    try {
+      const os = platform();
+      if (os === "darwin") {
+        const appPath = sanqianPath.replace(
+          "/Contents/MacOS/Sanqian",
+          ""
+        );
+        spawn("open", ["-a", appPath, "--args", "--hidden"], {
+          detached: true,
+          stdio: "ignore"
+        }).unref();
+      } else {
+        spawn(sanqianPath, ["--hidden"], {
+          detached: true,
+          stdio: "ignore",
+          // On Windows, hide the console window
+          ...os === "win32" && {
+            windowsHide: true,
+            shell: false
+          }
+        }).unref();
+      }
+      return true;
+    } catch (e) {
+      console.error("[SDK] Failed to launch Sanqian:", e);
+      return false;
+    }
+  }
+  /**
+   * Check if Sanqian is running
+   */
+  isSanqianRunning() {
+    return this.read() !== null;
+  }
+};
+
+// src/client.ts
+var SanqianSDK = class {
+  config;
+  discovery;
+  ws = null;
+  connectionInfo = null;
+  state = {
+    connected: false,
+    registering: false,
+    registered: false,
+    reconnectAttempts: 0
+  };
+  // Tool handlers by name
+  toolHandlers = /* @__PURE__ */ new Map();
+  // Pending request futures
+  pendingRequests = /* @__PURE__ */ new Map();
+  // Timers
+  heartbeatTimer = null;
+  reconnectTimer = null;
+  // Event listeners
+  eventListeners = /* @__PURE__ */ new Map();
+  constructor(config) {
+    this.config = {
+      reconnectInterval: 5e3,
+      heartbeatInterval: 3e4,
+      toolExecutionTimeout: 3e4,
+      ...config
+    };
+    this.discovery = new DiscoveryManager();
+    for (const tool of config.tools) {
+      this.toolHandlers.set(tool.name, tool.handler);
+    }
+  }
+  // ============================================
+  // Lifecycle
+  // ============================================
+  /**
+   * Connect to Sanqian
+   *
+   * Reads connection info, establishes WebSocket, and registers app.
+   * Returns when registration is complete.
+   *
+   * If autoLaunchSanqian is enabled and Sanqian is not running,
+   * SDK will attempt to start it in hidden/tray mode.
+   */
+  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);
+  }
+  /**
+   * Connect with known connection info
+   */
+  async connectWithInfo(info) {
+    this.connectionInfo = info;
+    const url = this.discovery.buildWebSocketUrl(info);
+    return new Promise((resolve, reject) => {
+      console.log(`[SDK] Connecting to ${url}`);
+      this.ws = new WebSocket(url);
+      const connectTimeout = setTimeout(() => {
+        reject(new Error("WebSocket connection timeout"));
+        this.ws?.close();
+      }, 1e4);
+      this.ws.on("open", async () => {
+        clearTimeout(connectTimeout);
+        console.log("[SDK] WebSocket connected");
+        this.state.connected = true;
+        this.state.reconnectAttempts = 0;
+        this.emit("connected");
+        try {
+          await this.register();
+          resolve();
+        } catch (e) {
+          reject(e);
+        }
+      });
+      this.ws.on("close", (code, reason) => {
+        console.log(`[SDK] WebSocket closed: ${code} ${reason.toString()}`);
+        this.handleDisconnect(reason.toString());
+      });
+      this.ws.on("error", (error) => {
+        console.error("[SDK] WebSocket error:", error);
+        this.state.lastError = error;
+        this.emit("error", error);
+      });
+      this.ws.on("message", (data) => {
+        try {
+          const message = JSON.parse(data.toString());
+          this.handleMessage(message);
+        } catch (e) {
+          console.error("[SDK] Failed to parse message:", e);
+        }
+      });
+    });
+  }
+  /**
+   * Disconnect from Sanqian
+   */
+  async disconnect() {
+    this.stopHeartbeat();
+    this.stopReconnect();
+    this.discovery.stopWatching();
+    if (this.ws) {
+      this.ws.close(1e3, "Client disconnect");
+      this.ws = null;
+    }
+    this.state = {
+      connected: false,
+      registering: false,
+      registered: false,
+      reconnectAttempts: 0
+    };
+  }
+  // ============================================
+  // Registration
+  // ============================================
+  async register() {
+    this.state.registering = true;
+    const msgId = this.generateId();
+    const message = {
+      id: msgId,
+      type: "register",
+      app: {
+        name: this.config.appName,
+        version: this.config.appVersion,
+        display_name: this.config.displayName,
+        launch_command: this.config.launchCommand
+      },
+      tools: this.config.tools.map((t) => ({
+        name: `${this.config.appName}:${t.name}`,
+        description: t.description,
+        parameters: t.parameters
+      }))
+    };
+    try {
+      const response = await this.sendAndWait(
+        message,
+        msgId,
+        1e4
+      );
+      if (!response.success) {
+        throw new Error(response.error || "Registration failed");
+      }
+      this.state.registering = false;
+      this.state.registered = true;
+      this.startHeartbeat();
+      this.emit("registered");
+      console.log(`[SDK] Registered as '${this.config.appName}'`);
+    } catch (e) {
+      this.state.registering = false;
+      throw e;
+    }
+  }
+  // ============================================
+  // Message Handling
+  // ============================================
+  handleMessage(message) {
+    const { id, type } = message;
+    if (id && this.pendingRequests.has(id)) {
+      const pending = this.pendingRequests.get(id);
+      this.pendingRequests.delete(id);
+      pending.resolve(message);
+      return;
+    }
+    switch (type) {
+      case "tool_call":
+        this.handleToolCall(message);
+        break;
+      case "heartbeat_ack":
+        break;
+      case "chat_stream":
+        this.handleChatStream(message);
+        break;
+      default:
+        console.warn(`[SDK] Unknown message type: ${type}`);
+    }
+  }
+  handleChatStream(message) {
+    const { id, event, content, tool_call, tool_result, conversation_id, usage, error } = message;
+    if (!id) return;
+    const handler = this.streamHandlers.get(id);
+    if (!handler) {
+      console.warn(`[SDK] No stream handler for message ${id}`);
+      return;
+    }
+    switch (event) {
+      case "text":
+        handler.onEvent({ type: "text", content });
+        break;
+      case "tool_call":
+        handler.onEvent({ type: "tool_call", tool_call });
+        break;
+      case "tool_result":
+        if (tool_result) {
+          handler.onEvent({
+            type: "tool_call",
+            tool_call: {
+              id: tool_result.call_id,
+              type: "function",
+              function: {
+                name: "tool_result",
+                arguments: JSON.stringify(tool_result)
+              }
+            }
+          });
+        }
+        break;
+      case "done":
+        handler.onDone({
+          message: message.message || { role: "assistant", content: "" },
+          conversationId: conversation_id || "",
+          usage
+        });
+        break;
+      case "error":
+        handler.onError(new Error(error || "Unknown stream error"));
+        break;
+    }
+  }
+  async handleToolCall(message) {
+    console.log(`[SDK] 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()));
+    const handler = this.toolHandlers.get(toolName);
+    this.emit("tool_call", { name: toolName, arguments: args });
+    if (!handler) {
+      await this.sendToolResult(msgId, call_id, false, void 0, `Tool '${toolName}' not found`);
+      return;
+    }
+    try {
+      console.log(`[SDK] 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`);
+      await this.sendToolResult(msgId, call_id, true, result);
+    } catch (e) {
+      const error = e instanceof Error ? e.message : String(e);
+      console.log(`[SDK] Tool '${toolName}' failed:`, error);
+      await this.sendToolResult(msgId, call_id, false, void 0, error);
+    }
+  }
+  async sendToolResult(id, callId, success, result, error) {
+    const message = {
+      id,
+      type: "tool_result",
+      call_id: callId,
+      success,
+      result,
+      error
+    };
+    console.log(`[SDK] Sending tool_result for ${callId}:`, success ? "success" : `error: ${error}`);
+    this.send(message);
+  }
+  // ============================================
+  // Connection Management
+  // ============================================
+  handleDisconnect(reason) {
+    this.stopHeartbeat();
+    this.state.connected = false;
+    this.state.registered = false;
+    this.emit("disconnected", reason);
+    for (const [, pending] of this.pendingRequests) {
+      pending.reject(new Error("Disconnected"));
+    }
+    this.pendingRequests.clear();
+    this.scheduleReconnect();
+  }
+  scheduleReconnect() {
+    if (this.reconnectTimer) return;
+    const delay = Math.min(
+      1e3 * Math.pow(2, this.state.reconnectAttempts),
+      3e4
+    );
+    console.log(`[SDK] Scheduling reconnect in ${delay}ms`);
+    this.reconnectTimer = setTimeout(async () => {
+      this.reconnectTimer = null;
+      this.state.reconnectAttempts++;
+      const info = this.discovery.read();
+      if (info) {
+        try {
+          await this.connectWithInfo(info);
+        } catch (e) {
+          console.error("[SDK] Reconnect failed:", e);
+          this.scheduleReconnect();
+        }
+      } else {
+        this.scheduleReconnect();
+      }
+    }, delay);
+  }
+  stopReconnect() {
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+  }
+  // ============================================
+  // Heartbeat
+  // ============================================
+  startHeartbeat() {
+    this.stopHeartbeat();
+    this.heartbeatTimer = setInterval(() => {
+      const message = {
+        type: "heartbeat",
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      };
+      this.send(message);
+    }, this.config.heartbeatInterval);
+  }
+  stopHeartbeat() {
+    if (this.heartbeatTimer) {
+      clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = null;
+    }
+  }
+  // ============================================
+  // Communication
+  // ============================================
+  send(message) {
+    if (this.ws && this.ws.readyState === WebSocket.OPEN) {
+      const data = JSON.stringify(message);
+      console.log(`[SDK] WebSocket send:`, data.substring(0, 200));
+      this.ws.send(data);
+    } else {
+      console.error(`[SDK] WebSocket not open, cannot send:`, message);
+    }
+  }
+  sendAndWait(message, id, timeout) {
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pendingRequests.delete(id);
+        reject(new Error("Request timeout"));
+      }, timeout);
+      this.pendingRequests.set(id, {
+        resolve: (value) => {
+          clearTimeout(timer);
+          resolve(value);
+        },
+        reject: (error) => {
+          clearTimeout(timer);
+          reject(error);
+        }
+      });
+      this.send(message);
+    });
+  }
+  // ============================================
+  // Public API
+  // ============================================
+  /**
+   * Get current connection state
+   */
+  getState() {
+    return { ...this.state };
+  }
+  /**
+   * Check if connected and registered
+   */
+  isConnected() {
+    return this.state.connected && this.state.registered;
+  }
+  /**
+   * Update tool list dynamically
+   */
+  async updateTools(tools) {
+    this.toolHandlers.clear();
+    for (const tool of tools) {
+      this.toolHandlers.set(tool.name, tool.handler);
+    }
+    if (this.isConnected()) {
+      const msgId = this.generateId();
+      const message = {
+        id: msgId,
+        type: "tools_update",
+        tools: tools.map((t) => ({
+          name: `${this.config.appName}:${t.name}`,
+          description: t.description,
+          parameters: t.parameters
+        }))
+      };
+      await this.sendAndWait(message, msgId, 5e3);
+    }
+  }
+  // ============================================
+  // Private Agent API
+  // ============================================
+  /**
+   * Create or update a private agent
+   *
+   * Private agents are only visible to this SDK app, not in Sanqian UI.
+   * If agent with same ID exists, it will be updated.
+   *
+   * @param config - Agent configuration
+   * @returns Full agent info (or agent_id string for backward compatibility)
+   */
+  async createAgent(config) {
+    if (!this.isConnected()) {
+      throw new Error("Not connected to Sanqian");
+    }
+    const msgId = this.generateId();
+    const message = {
+      id: msgId,
+      type: "create_agent",
+      agent: config
+    };
+    const response = await this.sendAndWait(message, msgId, 1e4);
+    if (!response.success) {
+      throw new Error(response.error || "Failed to create agent");
+    }
+    if (response.agent) {
+      return response.agent;
+    }
+    return {
+      agent_id: response.agent_id,
+      name: config.name,
+      description: config.description,
+      tools: config.tools || []
+    };
+  }
+  /**
+   * List all private agents owned by this app
+   */
+  async listAgents() {
+    if (!this.isConnected()) {
+      throw new Error("Not connected to Sanqian");
+    }
+    const msgId = this.generateId();
+    const message = {
+      id: msgId,
+      type: "list_agents"
+    };
+    const response = await this.sendAndWait(message, msgId, 1e4);
+    if (response.error) {
+      throw new Error(response.error);
+    }
+    return response.agents;
+  }
+  /**
+   * Delete a private agent
+   */
+  async deleteAgent(agentId) {
+    if (!this.isConnected()) {
+      throw new Error("Not connected to Sanqian");
+    }
+    const msgId = this.generateId();
+    const message = {
+      id: msgId,
+      type: "delete_agent",
+      agent_id: agentId
+    };
+    const response = await this.sendAndWait(message, msgId, 1e4);
+    if (!response.success) {
+      throw new Error(response.error || "Failed to delete agent");
+    }
+  }
+  /**
+   * Update a private agent
+   *
+   * Only updates the fields that are provided.
+   * @param agentId - Agent ID (short name or full)
+   * @param updates - Fields to update
+   * @returns Updated agent info
+   */
+  async updateAgent(agentId, updates) {
+    if (!this.isConnected()) {
+      throw new Error("Not connected to Sanqian");
+    }
+    const msgId = this.generateId();
+    const message = {
+      id: msgId,
+      type: "update_agent",
+      agent: {
+        agent_id: agentId,
+        ...updates
+      }
+    };
+    const response = await this.sendAndWait(message, msgId, 1e4);
+    if (!response.success || !response.agent) {
+      throw new Error(response.error || "Failed to update agent");
+    }
+    return response.agent;
+  }
+  // ============================================
+  // Conversation API
+  // ============================================
+  /**
+   * List conversations for this app
+   */
+  async listConversations(options) {
+    if (!this.isConnected()) {
+      throw new Error("Not connected to Sanqian");
+    }
+    const msgId = this.generateId();
+    const message = {
+      id: msgId,
+      type: "list_conversations",
+      agent_id: options?.agentId,
+      limit: options?.limit,
+      offset: options?.offset
+    };
+    const response = await this.sendAndWait(message, msgId, 1e4);
+    if (response.error) {
+      throw new Error(response.error);
+    }
+    return {
+      conversations: response.conversations,
+      total: response.total
+    };
+  }
+  /**
+   * Get conversation details with messages
+   */
+  async getConversation(conversationId, options) {
+    if (!this.isConnected()) {
+      throw new Error("Not connected to Sanqian");
+    }
+    const msgId = this.generateId();
+    const message = {
+      id: msgId,
+      type: "get_conversation",
+      conversation_id: conversationId,
+      include_messages: options?.includeMessages ?? true,
+      message_limit: options?.messageLimit,
+      message_offset: options?.messageOffset
+    };
+    const response = await this.sendAndWait(message, msgId, 1e4);
+    if (!response.success || !response.conversation) {
+      throw new Error(response.error || "Failed to get conversation");
+    }
+    return response.conversation;
+  }
+  /**
+   * Delete a conversation
+   */
+  async deleteConversation(conversationId) {
+    if (!this.isConnected()) {
+      throw new Error("Not connected to Sanqian");
+    }
+    const msgId = this.generateId();
+    const message = {
+      id: msgId,
+      type: "delete_conversation",
+      conversation_id: conversationId
+    };
+    const response = await this.sendAndWait(message, msgId, 1e4);
+    if (!response.success) {
+      throw new Error(response.error || "Failed to delete conversation");
+    }
+  }
+  // ============================================
+  // Chat API
+  // ============================================
+  // Pending stream handlers for streaming chat
+  streamHandlers = /* @__PURE__ */ new Map();
+  /**
+   * Send a chat message to an agent (non-streaming)
+   *
+   * Supports two modes:
+   * - Stateless (no conversationId): Caller maintains message history
+   * - Stateful (with conversationId): Server stores messages in conversations table
+   *
+   * @param agentId - Agent ID (short name or full, SDK auto-prefixes)
+   * @param messages - Messages to send
+   * @param options - Optional settings including conversationId and remoteTools
+   * @returns Chat response with assistant message and conversation ID
+   */
+  async chat(agentId, messages, options) {
+    if (!this.isConnected()) {
+      throw new Error("Not connected to Sanqian");
+    }
+    const msgId = this.generateId();
+    const message = {
+      id: msgId,
+      type: "chat",
+      agent_id: agentId,
+      messages,
+      conversation_id: options?.conversationId,
+      stream: false,
+      remote_tools: options?.remoteTools?.map((t) => ({
+        name: t.name,
+        description: t.description,
+        parameters: t.parameters
+      }))
+    };
+    const response = await this.sendAndWait(message, msgId, 6e5);
+    if (!response.success) {
+      throw new Error(response.error || "Chat request failed");
+    }
+    return {
+      message: response.message,
+      conversationId: response.conversation_id,
+      usage: response.usage
+    };
+  }
+  /**
+   * Send a chat message to an agent with streaming response
+   *
+   * Supports two modes:
+   * - Stateless (no conversationId): Caller maintains message history
+   * - Stateful (with conversationId): Server stores messages in conversations table
+   *
+   * @param agentId - Agent ID (short name or full, SDK auto-prefixes)
+   * @param messages - Messages to send
+   * @param options - Optional settings including conversationId and remoteTools
+   * @returns AsyncIterable of stream events
+   */
+  async *chatStream(agentId, messages, options) {
+    if (!this.isConnected()) {
+      throw new Error("Not connected to Sanqian");
+    }
+    const msgId = this.generateId();
+    const message = {
+      id: msgId,
+      type: "chat",
+      agent_id: agentId,
+      messages,
+      conversation_id: options?.conversationId,
+      stream: true,
+      remote_tools: options?.remoteTools?.map((t) => ({
+        name: t.name,
+        description: t.description,
+        parameters: t.parameters
+      }))
+    };
+    const eventQueue = [];
+    let done = false;
+    let error = null;
+    let resolveNext = null;
+    this.streamHandlers.set(msgId, {
+      onEvent: (event) => {
+        eventQueue.push(event);
+        resolveNext?.();
+      },
+      onDone: (response) => {
+        eventQueue.push({
+          type: "done",
+          conversationId: response.conversationId
+        });
+        done = true;
+        resolveNext?.();
+      },
+      onError: (e) => {
+        error = e;
+        resolveNext?.();
+      }
+    });
+    try {
+      this.send(message);
+      while (!done && !error) {
+        if (eventQueue.length > 0) {
+          yield eventQueue.shift();
+        } else {
+          await new Promise((resolve) => {
+            resolveNext = resolve;
+          });
+          resolveNext = null;
+        }
+      }
+      while (eventQueue.length > 0) {
+        yield eventQueue.shift();
+      }
+      if (error) {
+        throw error;
+      }
+    } finally {
+      this.streamHandlers.delete(msgId);
+    }
+  }
+  /**
+   * Start a new conversation with an agent
+   *
+   * Returns a Conversation object for convenient multi-turn chat.
+   *
+   * @example
+   * ```typescript
+   * const conv = sdk.startConversation('assistant')
+   * const r1 = await conv.send('Hello')
+   * const r2 = await conv.send('Follow up question')
+   * console.log(conv.id)  // conversation ID
+   * ```
+   */
+  startConversation(agentId) {
+    return new Conversation(this, agentId);
+  }
+  // ============================================
+  // Events
+  // ============================================
+  /**
+   * Add event listener
+   */
+  on(event, listener) {
+    if (!this.eventListeners.has(event)) {
+      this.eventListeners.set(event, /* @__PURE__ */ new Set());
+    }
+    this.eventListeners.get(event).add(listener);
+    return this;
+  }
+  /**
+   * Remove event listener
+   */
+  off(event, listener) {
+    this.eventListeners.get(event)?.delete(listener);
+    return this;
+  }
+  emit(event, ...args) {
+    const listeners = this.eventListeners.get(event);
+    if (listeners) {
+      for (const listener of listeners) {
+        try {
+          listener(...args);
+        } catch (e) {
+          console.error(`[SDK] Event listener error for '${event}':`, e);
+        }
+      }
+    }
+  }
+  // ============================================
+  // Utilities
+  // ============================================
+  generateId() {
+    return `${Date.now()}-${Math.random().toString(36).substring(2, 9)}`;
+  }
+  createTimeout(ms) {
+    return new Promise((_, reject) => {
+      setTimeout(() => reject(new Error("Timeout")), ms);
+    });
+  }
+};
+var Conversation = class {
+  sdk;
+  agentId;
+  _conversationId = null;
+  constructor(sdk, agentId, conversationId) {
+    this.sdk = sdk;
+    this.agentId = agentId;
+    this._conversationId = conversationId || null;
+  }
+  /**
+   * Get the conversation ID (available after first message)
+   */
+  get id() {
+    return this._conversationId;
+  }
+  /**
+   * Send a message and get a response
+   *
+   * First call creates a new conversation, subsequent calls continue it.
+   */
+  async send(content, options) {
+    const response = await this.sdk.chat(
+      this.agentId,
+      [{ role: "user", content }],
+      {
+        conversationId: this._conversationId || void 0,
+        remoteTools: options?.remoteTools
+      }
+    );
+    if (response.conversationId && !this._conversationId) {
+      this._conversationId = response.conversationId;
+    }
+    return response;
+  }
+  /**
+   * Send a message with streaming response
+   */
+  async *sendStream(content, options) {
+    const stream = this.sdk.chatStream(
+      this.agentId,
+      [{ role: "user", content }],
+      {
+        conversationId: this._conversationId || void 0,
+        remoteTools: options?.remoteTools
+      }
+    );
+    for await (const event of stream) {
+      if (event.type === "done" && event.conversationId && !this._conversationId) {
+        this._conversationId = event.conversationId;
+      }
+      yield event;
+    }
+  }
+  /**
+   * Delete this conversation
+   */
+  async delete() {
+    if (!this._conversationId) {
+      throw new Error("No conversation to delete");
+    }
+    await this.sdk.deleteConversation(this._conversationId);
+    this._conversationId = null;
+  }
+  /**
+   * Get conversation details including message history
+   */
+  async getDetails(options) {
+    if (!this._conversationId) {
+      throw new Error("No conversation to get details for");
+    }
+    return this.sdk.getConversation(this._conversationId, {
+      includeMessages: true,
+      messageLimit: options?.messageLimit
+    });
+  }
+};
+export {
+  Conversation,
+  DiscoveryManager,
+  SanqianSDK
+};
+//# sourceMappingURL=index.mjs.map