@yushaw/sanqian-sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,471 @@
+/**
+ * Sanqian SDK Type Definitions
+ */
+interface SDKConfig {
+    /** Unique app identifier (e.g., "sanqian-todolist") */
+    appName: string;
+    /** App version string */
+    appVersion: string;
+    /** Display name shown in Sanqian UI */
+    displayName?: string;
+    /** Command to launch this app (for auto-start) */
+    launchCommand?: string;
+    /** Tools provided by this app */
+    tools: ToolDefinition[];
+    /** Reconnect interval in ms (default: 5000) */
+    reconnectInterval?: number;
+    /** Heartbeat interval in ms (default: 30000) */
+    heartbeatInterval?: number;
+    /** Tool execution timeout in ms (default: 30000) */
+    toolExecutionTimeout?: number;
+    /**
+     * Auto-launch Sanqian if not running (default: false)
+     * When enabled, SDK will try to start Sanqian in hidden/tray mode
+     */
+    autoLaunchSanqian?: boolean;
+    /**
+     * Custom path to Sanqian executable (optional)
+     * If not provided, SDK will search in standard installation locations
+     */
+    sanqianPath?: string;
+}
+interface ToolDefinition {
+    /** Tool name (without app prefix) */
+    name: string;
+    /** Tool description for LLM */
+    description: string;
+    /** JSON Schema for parameters */
+    parameters: JSONSchema;
+    /** Handler function */
+    handler: (args: any) => Promise<any>;
+}
+interface JSONSchema {
+    type: "object" | "array" | "string" | "number" | "boolean";
+    properties?: Record<string, JSONSchemaProperty>;
+    required?: string[];
+    items?: JSONSchemaProperty;
+    description?: string;
+}
+interface JSONSchemaProperty {
+    type: "string" | "number" | "boolean" | "array" | "object";
+    description?: string;
+    enum?: (string | number)[];
+    default?: unknown;
+    items?: JSONSchemaProperty;
+    properties?: Record<string, JSONSchemaProperty>;
+    required?: string[];
+    format?: string;
+}
+interface ConnectionInfo {
+    version: number;
+    port: number;
+    ws_path: string;
+    token: string;
+    pid: number;
+    started_at: string;
+}
+interface ConnectionState {
+    connected: boolean;
+    registering: boolean;
+    registered: boolean;
+    lastError?: Error;
+    reconnectAttempts: number;
+}
+/** Remote tool definition for dynamic tool injection */
+interface RemoteToolDefinition {
+    /** Tool name */
+    name: string;
+    /** Tool description for LLM */
+    description: string;
+    /** JSON Schema for parameters */
+    parameters: JSONSchema;
+}
+interface ChatRequest {
+    /** Agent ID (can be short name, SDK auto-adds app prefix) */
+    agentId: string;
+    /** Messages to send */
+    messages: ChatMessage[];
+    /** Conversation ID for stateful mode (server stores messages) */
+    conversationId?: string;
+    /** Enable streaming (default: true) */
+    stream?: boolean;
+    /** Dynamic tools to inject at call time */
+    remoteTools?: RemoteToolDefinition[];
+}
+interface ChatMessage {
+    role: "user" | "assistant" | "system" | "tool";
+    content: string;
+    tool_calls?: ToolCall[];
+    tool_call_id?: string;
+}
+interface ToolCall {
+    id: string;
+    type: "function";
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+interface ChatResponse {
+    message: ChatMessage;
+    conversationId: string;
+    usage?: {
+        prompt_tokens: number;
+        completion_tokens: number;
+        total_tokens: number;
+    };
+}
+interface ChatStreamEvent {
+    type: "text" | "tool_call" | "done" | "error";
+    content?: string;
+    tool_call?: ToolCall;
+    conversationId?: string;
+    error?: string;
+}
+/** Agent configuration for create/update */
+interface AgentConfig {
+    /** Unique agent ID within this app (e.g., "assistant") */
+    agent_id: string;
+    /** Display name */
+    name: string;
+    /** Description */
+    description?: string;
+    /** System prompt */
+    system_prompt?: string;
+    /** Tool names from this app to enable (without prefix) */
+    tools?: string[];
+}
+/** Agent info returned from list */
+interface AgentInfo {
+    /** Full agent ID (app_name:agent_id) */
+    agent_id: string;
+    name: string;
+    description?: string;
+    /** Tool names with sdk_ prefix */
+    tools: string[];
+    created_at?: string;
+}
+/** Conversation info */
+interface ConversationInfo {
+    conversation_id: string;
+    agent_id: string;
+    title?: string;
+    message_count: number;
+    created_at?: string;
+    updated_at?: string;
+}
+/** Message in a conversation */
+interface ConversationMessage {
+    id: string;
+    role: "user" | "assistant" | "system" | "tool";
+    content: string;
+    tool_calls?: ToolCall[] | null;
+    tool_call_id?: string | null;
+    created_at?: string;
+}
+/** Full conversation with messages */
+interface ConversationDetail extends ConversationInfo {
+    messages?: ConversationMessage[];
+}
+/** Agent update configuration (all fields optional except agent_id) */
+interface AgentUpdateConfig {
+    /** Agent ID to update */
+    agent_id: string;
+    /** New display name */
+    name?: string;
+    /** New description */
+    description?: string;
+    /** New system prompt */
+    system_prompt?: string;
+    /** New tool names from this app to enable (without prefix) */
+    tools?: string[];
+}
+interface SDKEvents {
+    connected: () => void;
+    disconnected: (reason: string) => void;
+    registered: () => void;
+    error: (error: Error) => void;
+    tool_call: (call: {
+        name: string;
+        arguments: Record<string, unknown>;
+    }) => void;
+}
+type SDKEventName = keyof SDKEvents;
+
+/**
+ * Sanqian SDK Client
+ *
+ * Main class for connecting to Sanqian and registering tools.
+ */
+
+declare class SanqianSDK {
+    private config;
+    private discovery;
+    private ws;
+    private connectionInfo;
+    private state;
+    private toolHandlers;
+    private pendingRequests;
+    private heartbeatTimer;
+    private reconnectTimer;
+    private eventListeners;
+    constructor(config: SDKConfig);
+    /**
+     * 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.
+     */
+    connect(): Promise<void>;
+    /**
+     * Connect with known connection info
+     */
+    private connectWithInfo;
+    /**
+     * Disconnect from Sanqian
+     */
+    disconnect(): Promise<void>;
+    private register;
+    private handleMessage;
+    private handleChatStream;
+    private handleToolCall;
+    private sendToolResult;
+    private handleDisconnect;
+    private scheduleReconnect;
+    private stopReconnect;
+    private startHeartbeat;
+    private stopHeartbeat;
+    private send;
+    private sendAndWait;
+    /**
+     * Get current connection state
+     */
+    getState(): ConnectionState;
+    /**
+     * Check if connected and registered
+     */
+    isConnected(): boolean;
+    /**
+     * Update tool list dynamically
+     */
+    updateTools(tools: ToolDefinition[]): Promise<void>;
+    /**
+     * 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)
+     */
+    createAgent(config: AgentConfig): Promise<AgentInfo>;
+    /**
+     * List all private agents owned by this app
+     */
+    listAgents(): Promise<AgentInfo[]>;
+    /**
+     * Delete a private agent
+     */
+    deleteAgent(agentId: string): Promise<void>;
+    /**
+     * 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
+     */
+    updateAgent(agentId: string, updates: Omit<AgentUpdateConfig, "agent_id">): Promise<AgentInfo>;
+    /**
+     * List conversations for this app
+     */
+    listConversations(options?: {
+        agentId?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<{
+        conversations: ConversationInfo[];
+        total: number;
+    }>;
+    /**
+     * Get conversation details with messages
+     */
+    getConversation(conversationId: string, options?: {
+        includeMessages?: boolean;
+        messageLimit?: number;
+        messageOffset?: number;
+    }): Promise<ConversationDetail>;
+    /**
+     * Delete a conversation
+     */
+    deleteConversation(conversationId: string): Promise<void>;
+    private streamHandlers;
+    /**
+     * 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
+     */
+    chat(agentId: string, messages: ChatMessage[], options?: {
+        conversationId?: string;
+        remoteTools?: RemoteToolDefinition[];
+    }): Promise<ChatResponse>;
+    /**
+     * 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
+     */
+    chatStream(agentId: string, messages: ChatMessage[], options?: {
+        conversationId?: string;
+        remoteTools?: RemoteToolDefinition[];
+    }): AsyncGenerator<ChatStreamEvent>;
+    /**
+     * 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: string): Conversation;
+    /**
+     * Add event listener
+     */
+    on<T extends SDKEventName>(event: T, listener: SDKEvents[T]): this;
+    /**
+     * Remove event listener
+     */
+    off<T extends SDKEventName>(event: T, listener: SDKEvents[T]): this;
+    private emit;
+    private generateId;
+    private createTimeout;
+}
+/**
+ * Conversation helper for multi-turn chat
+ *
+ * Automatically manages conversationId for stateful conversations.
+ */
+declare class Conversation {
+    private sdk;
+    private agentId;
+    private _conversationId;
+    constructor(sdk: SanqianSDK, agentId: string, conversationId?: string);
+    /**
+     * Get the conversation ID (available after first message)
+     */
+    get id(): string | null;
+    /**
+     * Send a message and get a response
+     *
+     * First call creates a new conversation, subsequent calls continue it.
+     */
+    send(content: string, options?: {
+        remoteTools?: RemoteToolDefinition[];
+    }): Promise<ChatResponse>;
+    /**
+     * Send a message with streaming response
+     */
+    sendStream(content: string, options?: {
+        remoteTools?: RemoteToolDefinition[];
+    }): AsyncGenerator<ChatStreamEvent>;
+    /**
+     * Delete this conversation
+     */
+    delete(): Promise<void>;
+    /**
+     * Get conversation details including message history
+     */
+    getDetails(options?: {
+        messageLimit?: number;
+    }): Promise<ConversationDetail>;
+}
+
+/**
+ * Service Discovery Module
+ *
+ * Reads Sanqian's connection info from ~/.sanqian/runtime/connection.json
+ * and monitors file changes for reconnection.
+ * Also handles auto-launching Sanqian when needed.
+ */
+
+declare class DiscoveryManager {
+    private connectionInfo;
+    private watcher;
+    private onChange;
+    private pollInterval;
+    /**
+     * Get the path to connection.json
+     */
+    getConnectionFilePath(): string;
+    /**
+     * Read and validate connection info
+     *
+     * Returns null if:
+     * - File doesn't exist
+     * - File is invalid JSON
+     * - Process is not running
+     */
+    read(): ConnectionInfo | null;
+    /**
+     * Start watching for connection file changes
+     */
+    startWatching(onChange: (info: ConnectionInfo | null) => void): void;
+    private setupWatcher;
+    /**
+     * Stop watching
+     */
+    stopWatching(): void;
+    /**
+     * Check if a process is running by PID
+     */
+    private isProcessRunning;
+    /**
+     * Get cached connection info (may be stale)
+     */
+    getCached(): ConnectionInfo | null;
+    /**
+     * Build WebSocket URL from connection info
+     */
+    buildWebSocketUrl(info: ConnectionInfo): string;
+    /**
+     * Build HTTP base URL from connection info
+     */
+    buildHttpUrl(info: ConnectionInfo): string;
+    /**
+     * Find Sanqian executable path
+     * Searches in standard installation locations for each platform
+     */
+    findSanqianPath(customPath?: string): string | null;
+    /**
+     * Launch Sanqian in hidden/tray mode
+     * Returns true if launch was initiated successfully
+     */
+    launchSanqian(customPath?: string): boolean;
+    /**
+     * Check if Sanqian is running
+     */
+    isSanqianRunning(): boolean;
+}
+
+export { type AgentConfig, type AgentInfo, type AgentUpdateConfig, type ChatMessage, type ChatRequest, type ChatResponse, type ChatStreamEvent, type ConnectionInfo, type ConnectionState, Conversation, type ConversationDetail, type ConversationInfo, type ConversationMessage, DiscoveryManager, type JSONSchema, type JSONSchemaProperty, type RemoteToolDefinition, type SDKConfig, type SDKEventName, type SDKEvents, SanqianSDK, type ToolCall, type ToolDefinition };