@yushaw/sanqian-chat 0.1.1 → 0.2.1

package/README.md

@@ -0,0 +1,116 @@
+# @yushaw/sanqian-chat
+
+Sanqian chat UI components and hooks for third-party Electron apps.
+
+## Phase 1 (Core Chat)
+- Streaming chat messages
+- Thinking section
+- Tool call timeline
+- HITL prompts
+- Simplified input (text + send + stop)
+
+## Install
+
+```bash
+npm install @yushaw/sanqian-chat
+```
+
+## Publish
+
+From the repo root:
+
+```bash
+npm publish --workspace=@yushaw/sanqian-chat
+```
+
+Or from the package directory:
+
+```bash
+cd packages/chat
+npm publish
+```
+
+## Usage (Renderer)
+
+```tsx
+import { SanqianChat, createSdkAdapter } from '@yushaw/sanqian-chat/renderer';
+import { SanqianSDK } from '@yushaw/sanqian-sdk';
+
+const sdk = new SanqianSDK({
+  appName: 'my-app',
+  appVersion: '0.1.0',
+  tools: [],
+});
+
+const adapter = createSdkAdapter({
+  getSdk: () => sdk,
+  getAgentId: () => 'assistant',
+});
+
+export function App() {
+  return (
+    <div className="h-full">
+      <SanqianChat
+        adapter={adapter}
+        config={{
+          theme: 'auto',
+          accentColor: '#e85d75',
+          locale: 'zh',
+        }}
+      />
+    </div>
+  );
+}
+```
+
+## API Reference
+
+See `packages/chat/API.md` and `packages/chat/API.zh-CN.md`.
+
+## Notes
+- **Style modes**: Default is `'safe'` (no Tailwind preflight, safe for embedding). Use `'full'` for standalone windows.
+  - Set `window.__SANQIAN_CHAT_STYLE_MODE__ = 'full'` for full styles including preflight
+  - Set `window.__SANQIAN_CHAT_DISABLE_STYLES__ = true` to disable auto-injection
+- **CSS files**:
+  - `@yushaw/sanqian-chat/renderer/styles/safe.css` - Safe (no preflight, includes utilities)
+  - `@yushaw/sanqian-chat/renderer/styles/chat.css` - Full (includes Tailwind preflight)
+  - `@yushaw/sanqian-chat/renderer/styles/variables.css` - Variables only
+- Sanqian should be running when the SDK connects.
+- Additional capabilities (history, agents, files, settings) will be added in later phases.
+
+## Developing Styles
+
+CSS uses a modular structure with a single source of truth:
+
+```
+src/renderer/styles/
+├── coreCss.ts        # ← EDIT THIS (CSS variables + utilities)
+├── preflightCss.ts   # Tailwind preflight (don't edit)
+├── safeCss.ts        # Auto-generated (imports coreCss)
+├── chatCss.ts        # Auto-generated (imports coreCss + preflight)
+├── safe.css          # Auto-generated
+└── chat.css          # Auto-generated
+```
+
+**To modify styles:**
+1. Edit `coreCss.ts`
+2. Run `npm run build:css` to regenerate all files
+3. Or just run `npm run build` (includes CSS generation)
+
+## Changelog
+
+### 2025-01-03
+- **Added**: Focus persistence - input keeps focus when clicking empty areas (unless selecting text)
+- **Added**: `Cmd+N` (macOS) / `Ctrl+N` (Windows) keyboard shortcut for new chat
+- **Added**: Hover tooltip with shortcut hint on new chat button
+
+### 2025-01-02
+- **Changed**: CSS modular structure - single source of truth (`coreCss.ts`)
+- **Changed**: `.prose` uses `font-size: inherit` for external control
+- **Changed**: IntermediateSteps uses relative font sizes (rem instead of px)
+- **Fixed**: `position` default value conflict with `rememberWindowState`
+- **Fixed**: IPC now forwards `start` event (with `run_id`) to renderer
+- **Fixed**: Center position calculation uses `workArea` (supports multi-monitor/dock)
+- **Fixed**: `console.log` only outputs in `devMode`
+- **Fixed**: Global style pollution - default to `'safe'` mode (no Tailwind preflight)
+- **Fixed**: `cancelStream` now calls `sdk.cancelRun()` for real cancellation

package/dist/core/index.d.mts

@@ -7,16 +7,80 @@ export { ChatStreamEvent, HitlInterruptPayload, HitlInterruptType, HitlResponse,
  * Re-exports SDK types + chat-specific types
  */
 
-type MessageRole = 'user' | 'assistant' | 'system';
+type Locale = 'en' | 'zh';
+interface ChatUiStrings {
+    inputPlaceholder: string;
+    inputSend: string;
+    inputStop: string;
+    chat: string;
+    recentChats: string;
+    newChat: string;
+    selectConversation: string;
+    noHistory: string;
+    loadMore: string;
+    today: string;
+    yesterday: string;
+    delete: string;
+    dismiss: string;
+    close: string;
+    pin: string;
+    unpin: string;
+    conversationUntitled: string;
+    conversationDeleteConfirm: string;
+    messageThinking: string;
+    messageError: string;
+    messageLoading: string;
+    connectionConnecting: string;
+    connectionConnected: string;
+    connectionDisconnected: string;
+    connectionReconnecting: string;
+    connectionError: string;
+    steps: string;
+    executing: string;
+    thinking: string;
+    thinkingStreaming: string;
+    thinkingPaused: string;
+    hitlApprove: string;
+    hitlReject: string;
+    hitlSubmit: string;
+    hitlCancel: string;
+    hitlRememberChoice: string;
+    hitlRequiredField: string;
+    hitlTimeoutIn: string;
+    hitlSeconds: string;
+    hitlExecuteTool: string;
+    hitlToolLabel: string;
+    hitlArgsLabel: string;
+    hitlDefaultPrefix: string;
+    hitlEnterResponse: string;
+    hitlApprovalRequest: string;
+    hitlInputRequest: string;
+    hitlApprovalRequired: string;
+    hitlInputRequired: string;
+}
+type ChatThemeMode = 'light' | 'dark' | 'auto';
+type ChatFontSize = 'small' | 'normal' | 'large' | 'extra-large';
+interface ChatUiConfigSerializable {
+    logo?: string;
+    theme?: ChatThemeMode;
+    /** Font size scale: small (13px), normal (14px), large (16px), extra-large (18px) */
+    fontSize?: ChatFontSize;
+    accentColor?: string;
+    locale?: Locale;
+    strings?: Partial<ChatUiStrings>;
+    alwaysOnTop?: boolean;
+}
+type MessageRole = 'user' | 'assistant' | 'system' | 'tool';
 type ToolCallStatus = 'pending' | 'running' | 'completed' | 'error' | 'cancelled';
 type ConnectionStatus = 'disconnected' | 'connecting' | 'connected' | 'reconnecting' | 'error';
 type ConnectionErrorCode = 'NOT_FOUND' | 'CONNECTION_FAILED' | 'WEBSOCKET_ERROR' | 'AUTH_ERROR' | 'TIMEOUT' | 'UNKNOWN';
 /** Tool call for UI rendering (extended from SDK) */
 interface ToolCall {
-    id: string;
+    id?: string;
     name: string;
-    arguments: Record<string, unknown>;
-    status: ToolCallStatus;
+    args?: Record<string, unknown>;
+    argsRaw?: string;
+    status?: ToolCallStatus;
     result?: unknown;
     error?: string;
 }
@@ -27,9 +91,11 @@ interface MessageBlock {
     timestamp: number;
     toolName?: string;
     toolArgs?: Record<string, unknown>;
+    toolArgsRaw?: string;
     toolCallId?: string;
     toolStatus?: ToolCallStatus;
     isIntermediate?: boolean;
+    fromSubagent?: boolean;
 }
 /** Chat message for UI rendering */
 interface ChatMessage {
@@ -42,8 +108,12 @@ interface ChatMessage {
     thinking?: string;
     currentThinking?: string;
     isThinkingStreaming?: boolean;
+    isThinkingPaused?: boolean;
+    isToolCallsStreaming?: boolean;
     blocks?: MessageBlock[];
+    finalContent?: string;
     isComplete?: boolean;
+    filePaths?: string[];
 }
 /** Conversation info for UI */
 interface ConversationInfo {
@@ -52,6 +122,7 @@ interface ConversationInfo {
     createdAt: string;
     updatedAt: string;
     messageCount: number;
+    agentId?: string | null;
 }
 interface ConversationDetail extends ConversationInfo {
     messages: ChatMessage[];
@@ -67,9 +138,21 @@ interface FloatingWindowConfig {
     position?: WindowPosition;
     width?: number;
     height?: number;
+    /** Minimum window width (default: 320) */
+    minWidth?: number;
+    /** Minimum window height (default: 420) */
+    minHeight?: number;
     alwaysOnTop?: boolean;
     showInTaskbar?: boolean;
     theme?: 'light' | 'dark' | 'system';
+    /** Optional UI config for renderer (serializable) */
+    uiConfig?: ChatUiConfigSerializable;
+    /** Persist size/position across sessions (stored under ~/.sanqian-chat) */
+    rememberWindowState?: boolean;
+    /** Optional storage key to avoid conflicts between apps */
+    windowStateKey?: string;
+    /** Optional full path for window state file */
+    windowStatePath?: string;
 }
 
 /**
@@ -81,6 +164,10 @@ interface FloatingWindowConfig {
 
 /** Stream event callback */
 type StreamEvent = {
+    type: 'start';
+    run_id: string;
+    conversationId?: string;
+} | {
     type: 'text';
     content: string;
 } | {
@@ -95,6 +182,16 @@ type StreamEvent = {
             arguments: string;
         };
     };
+} | {
+    type: 'tool_args_chunk';
+    tool_call_id: string;
+    tool_name?: string;
+    chunk: string;
+} | {
+    type: 'tool_args';
+    tool_call_id: string;
+    tool_name?: string;
+    args: Record<string, unknown>;
 } | {
     type: 'tool_result';
     tool_call_id: string;
@@ -111,6 +208,9 @@ type StreamEvent = {
     interrupt_type: string;
     interrupt_payload: HitlInterruptData;
     run_id?: string;
+} | {
+    type: 'cancelled';
+    run_id?: string;
 };
 /** Message to send */
 interface SendMessage {
@@ -135,7 +235,9 @@ interface ChatAdapter {
         messageLimit?: number;
     }): Promise<ConversationDetail>;
     deleteConversation(id: string): Promise<void>;
-    chatStream(messages: SendMessage[], conversationId: string | undefined, onEvent: (event: StreamEvent) => void): Promise<{
+    chatStream(messages: SendMessage[], conversationId: string | undefined, onEvent: (event: StreamEvent) => void, options?: {
+        agentId?: string | null;
+    }): Promise<{
         cancel: () => void;
     }>;
     sendHitlResponse?(response: HitlResponse, runId?: string): void;
@@ -148,9 +250,81 @@ interface SdkAdapterConfig {
     /** Agent ID getter */
     getAgentId: () => string | null;
 }
+/** Simple chat adapter config (no SDK knowledge required) */
+interface ChatAdapterConfig {
+    /** App name for registration */
+    appName: string;
+    /** App version */
+    appVersion: string;
+    /** Agent ID to chat with */
+    agentId: string;
+    /** Whether to persist conversation history (default: false) */
+    persistHistory?: boolean;
+    /** Tools to expose to the agent */
+    tools?: Array<{
+        name: string;
+        description: string;
+        parameters?: Record<string, unknown>;
+        handler?: (args: Record<string, unknown>) => Promise<unknown>;
+    }>;
+}
+/**
+ * Create a chat adapter with simple config (recommended for most use cases)
+ *
+ * This is the easiest way to integrate with Sanqian. Just provide your app info
+ * and agent ID, and the adapter handles SDK lifecycle automatically.
+ *
+ * @example
+ * ```typescript
+ * const adapter = createChatAdapter({
+ *   appName: 'my-app',
+ *   appVersion: '1.0.0',
+ *   agentId: 'assistant',
+ * });
+ *
+ * <CompactChat adapter={adapter} />
+ * ```
+ */
+declare function createChatAdapter(config: ChatAdapterConfig): ChatAdapter;
 /**
  * Create adapter that wraps @yushaw/sanqian-sdk
+ *
+ * Use this when you need more control over the SDK instance.
+ * For simpler usage, prefer `createChatAdapter()`.
  */
 declare function createSdkAdapter(config: SdkAdapterConfig): ChatAdapter;
 
-export { type ChatAdapter, type ChatMessage, type ConnectionErrorCode, type ConnectionStatus, type ConversationDetail, type ConversationInfo, type FloatingWindowConfig, type HitlInterruptData, type MessageBlock, type MessageRole, type SdkAdapterConfig, type SendMessage, type StreamEvent, type ToolCall, type ToolCallStatus, type WindowPosition, createSdkAdapter };
+/**
+ * Conversation history helpers
+ *
+ * Normalizes SDK conversation messages into ChatMessage[] with
+ * tool call blocks and merged assistant/tool rounds.
+ *
+ * NOTE: This logic is intentionally kept in sync with
+ * src/renderer/src/utils/chat-helpers.ts in the main app.
+ */
+
+interface ApiMessage {
+    id?: string;
+    role: string;
+    content: string;
+    created_at?: string;
+    timestamp?: string;
+    tool_calls?: unknown;
+    toolCalls?: unknown;
+    tool_call_id?: string | null;
+    thinking?: string | null;
+    filePaths?: string[];
+    message_id?: number;
+}
+/**
+ * Parse tool_calls from backend format (OpenAI or simplified).
+ */
+declare function parseToolCalls(toolCalls: unknown): ToolCall[] | undefined;
+/**
+ * Merge consecutive assistant + tool messages into single assistant messages,
+ * preserving blocks for intermediate steps.
+ */
+declare function mergeConsecutiveAssistantMessages(rawMessages: ApiMessage[]): ChatMessage[];
+
+export { type ApiMessage, type ChatAdapter, type ChatAdapterConfig, type ChatFontSize, type ChatMessage, type ChatThemeMode, type ChatUiConfigSerializable, type ChatUiStrings, type ConnectionErrorCode, type ConnectionStatus, type ConversationDetail, type ConversationInfo, type FloatingWindowConfig, type HitlInterruptData, type Locale, type MessageBlock, type MessageRole, type SdkAdapterConfig, type SendMessage, type StreamEvent, type ToolCall, type ToolCallStatus, type WindowPosition, createChatAdapter, createSdkAdapter, mergeConsecutiveAssistantMessages, parseToolCalls };

package/dist/core/index.d.ts

@@ -7,16 +7,80 @@ export { ChatStreamEvent, HitlInterruptPayload, HitlInterruptType, HitlResponse,
  * Re-exports SDK types + chat-specific types
  */
 
-type MessageRole = 'user' | 'assistant' | 'system';
+type Locale = 'en' | 'zh';
+interface ChatUiStrings {
+    inputPlaceholder: string;
+    inputSend: string;
+    inputStop: string;
+    chat: string;
+    recentChats: string;
+    newChat: string;
+    selectConversation: string;
+    noHistory: string;
+    loadMore: string;
+    today: string;
+    yesterday: string;
+    delete: string;
+    dismiss: string;
+    close: string;
+    pin: string;
+    unpin: string;
+    conversationUntitled: string;
+    conversationDeleteConfirm: string;
+    messageThinking: string;
+    messageError: string;
+    messageLoading: string;
+    connectionConnecting: string;
+    connectionConnected: string;
+    connectionDisconnected: string;
+    connectionReconnecting: string;
+    connectionError: string;
+    steps: string;
+    executing: string;
+    thinking: string;
+    thinkingStreaming: string;
+    thinkingPaused: string;
+    hitlApprove: string;
+    hitlReject: string;
+    hitlSubmit: string;
+    hitlCancel: string;
+    hitlRememberChoice: string;
+    hitlRequiredField: string;
+    hitlTimeoutIn: string;
+    hitlSeconds: string;
+    hitlExecuteTool: string;
+    hitlToolLabel: string;
+    hitlArgsLabel: string;
+    hitlDefaultPrefix: string;
+    hitlEnterResponse: string;
+    hitlApprovalRequest: string;
+    hitlInputRequest: string;
+    hitlApprovalRequired: string;
+    hitlInputRequired: string;
+}
+type ChatThemeMode = 'light' | 'dark' | 'auto';
+type ChatFontSize = 'small' | 'normal' | 'large' | 'extra-large';
+interface ChatUiConfigSerializable {
+    logo?: string;
+    theme?: ChatThemeMode;
+    /** Font size scale: small (13px), normal (14px), large (16px), extra-large (18px) */
+    fontSize?: ChatFontSize;
+    accentColor?: string;
+    locale?: Locale;
+    strings?: Partial<ChatUiStrings>;
+    alwaysOnTop?: boolean;
+}
+type MessageRole = 'user' | 'assistant' | 'system' | 'tool';
 type ToolCallStatus = 'pending' | 'running' | 'completed' | 'error' | 'cancelled';
 type ConnectionStatus = 'disconnected' | 'connecting' | 'connected' | 'reconnecting' | 'error';
 type ConnectionErrorCode = 'NOT_FOUND' | 'CONNECTION_FAILED' | 'WEBSOCKET_ERROR' | 'AUTH_ERROR' | 'TIMEOUT' | 'UNKNOWN';
 /** Tool call for UI rendering (extended from SDK) */
 interface ToolCall {
-    id: string;
+    id?: string;
     name: string;
-    arguments: Record<string, unknown>;
-    status: ToolCallStatus;
+    args?: Record<string, unknown>;
+    argsRaw?: string;
+    status?: ToolCallStatus;
     result?: unknown;
     error?: string;
 }
@@ -27,9 +91,11 @@ interface MessageBlock {
     timestamp: number;
     toolName?: string;
     toolArgs?: Record<string, unknown>;
+    toolArgsRaw?: string;
     toolCallId?: string;
     toolStatus?: ToolCallStatus;
     isIntermediate?: boolean;
+    fromSubagent?: boolean;
 }
 /** Chat message for UI rendering */
 interface ChatMessage {
@@ -42,8 +108,12 @@ interface ChatMessage {
     thinking?: string;
     currentThinking?: string;
     isThinkingStreaming?: boolean;
+    isThinkingPaused?: boolean;
+    isToolCallsStreaming?: boolean;
     blocks?: MessageBlock[];
+    finalContent?: string;
     isComplete?: boolean;
+    filePaths?: string[];
 }
 /** Conversation info for UI */
 interface ConversationInfo {
@@ -52,6 +122,7 @@ interface ConversationInfo {
     createdAt: string;
     updatedAt: string;
     messageCount: number;
+    agentId?: string | null;
 }
 interface ConversationDetail extends ConversationInfo {
     messages: ChatMessage[];
@@ -67,9 +138,21 @@ interface FloatingWindowConfig {
     position?: WindowPosition;
     width?: number;
     height?: number;
+    /** Minimum window width (default: 320) */
+    minWidth?: number;
+    /** Minimum window height (default: 420) */
+    minHeight?: number;
     alwaysOnTop?: boolean;
     showInTaskbar?: boolean;
     theme?: 'light' | 'dark' | 'system';
+    /** Optional UI config for renderer (serializable) */
+    uiConfig?: ChatUiConfigSerializable;
+    /** Persist size/position across sessions (stored under ~/.sanqian-chat) */
+    rememberWindowState?: boolean;
+    /** Optional storage key to avoid conflicts between apps */
+    windowStateKey?: string;
+    /** Optional full path for window state file */
+    windowStatePath?: string;
 }
 
 /**
@@ -81,6 +164,10 @@ interface FloatingWindowConfig {
 
 /** Stream event callback */
 type StreamEvent = {
+    type: 'start';
+    run_id: string;
+    conversationId?: string;
+} | {
     type: 'text';
     content: string;
 } | {
@@ -95,6 +182,16 @@ type StreamEvent = {
             arguments: string;
         };
     };
+} | {
+    type: 'tool_args_chunk';
+    tool_call_id: string;
+    tool_name?: string;
+    chunk: string;
+} | {
+    type: 'tool_args';
+    tool_call_id: string;
+    tool_name?: string;
+    args: Record<string, unknown>;
 } | {
     type: 'tool_result';
     tool_call_id: string;
@@ -111,6 +208,9 @@ type StreamEvent = {
     interrupt_type: string;
     interrupt_payload: HitlInterruptData;
     run_id?: string;
+} | {
+    type: 'cancelled';
+    run_id?: string;
 };
 /** Message to send */
 interface SendMessage {
@@ -135,7 +235,9 @@ interface ChatAdapter {
         messageLimit?: number;
     }): Promise<ConversationDetail>;
     deleteConversation(id: string): Promise<void>;
-    chatStream(messages: SendMessage[], conversationId: string | undefined, onEvent: (event: StreamEvent) => void): Promise<{
+    chatStream(messages: SendMessage[], conversationId: string | undefined, onEvent: (event: StreamEvent) => void, options?: {
+        agentId?: string | null;
+    }): Promise<{
         cancel: () => void;
     }>;
     sendHitlResponse?(response: HitlResponse, runId?: string): void;
@@ -148,9 +250,81 @@ interface SdkAdapterConfig {
     /** Agent ID getter */
     getAgentId: () => string | null;
 }
+/** Simple chat adapter config (no SDK knowledge required) */
+interface ChatAdapterConfig {
+    /** App name for registration */
+    appName: string;
+    /** App version */
+    appVersion: string;
+    /** Agent ID to chat with */
+    agentId: string;
+    /** Whether to persist conversation history (default: false) */
+    persistHistory?: boolean;
+    /** Tools to expose to the agent */
+    tools?: Array<{
+        name: string;
+        description: string;
+        parameters?: Record<string, unknown>;
+        handler?: (args: Record<string, unknown>) => Promise<unknown>;
+    }>;
+}
+/**
+ * Create a chat adapter with simple config (recommended for most use cases)
+ *
+ * This is the easiest way to integrate with Sanqian. Just provide your app info
+ * and agent ID, and the adapter handles SDK lifecycle automatically.
+ *
+ * @example
+ * ```typescript
+ * const adapter = createChatAdapter({
+ *   appName: 'my-app',
+ *   appVersion: '1.0.0',
+ *   agentId: 'assistant',
+ * });
+ *
+ * <CompactChat adapter={adapter} />
+ * ```
+ */
+declare function createChatAdapter(config: ChatAdapterConfig): ChatAdapter;
 /**
  * Create adapter that wraps @yushaw/sanqian-sdk
+ *
+ * Use this when you need more control over the SDK instance.
+ * For simpler usage, prefer `createChatAdapter()`.
  */
 declare function createSdkAdapter(config: SdkAdapterConfig): ChatAdapter;
 
-export { type ChatAdapter, type ChatMessage, type ConnectionErrorCode, type ConnectionStatus, type ConversationDetail, type ConversationInfo, type FloatingWindowConfig, type HitlInterruptData, type MessageBlock, type MessageRole, type SdkAdapterConfig, type SendMessage, type StreamEvent, type ToolCall, type ToolCallStatus, type WindowPosition, createSdkAdapter };
+/**
+ * Conversation history helpers
+ *
+ * Normalizes SDK conversation messages into ChatMessage[] with
+ * tool call blocks and merged assistant/tool rounds.
+ *
+ * NOTE: This logic is intentionally kept in sync with
+ * src/renderer/src/utils/chat-helpers.ts in the main app.
+ */
+
+interface ApiMessage {
+    id?: string;
+    role: string;
+    content: string;
+    created_at?: string;
+    timestamp?: string;
+    tool_calls?: unknown;
+    toolCalls?: unknown;
+    tool_call_id?: string | null;
+    thinking?: string | null;
+    filePaths?: string[];
+    message_id?: number;
+}
+/**
+ * Parse tool_calls from backend format (OpenAI or simplified).
+ */
+declare function parseToolCalls(toolCalls: unknown): ToolCall[] | undefined;
+/**
+ * Merge consecutive assistant + tool messages into single assistant messages,
+ * preserving blocks for intermediate steps.
+ */
+declare function mergeConsecutiveAssistantMessages(rawMessages: ApiMessage[]): ChatMessage[];
+
+export { type ApiMessage, type ChatAdapter, type ChatAdapterConfig, type ChatFontSize, type ChatMessage, type ChatThemeMode, type ChatUiConfigSerializable, type ChatUiStrings, type ConnectionErrorCode, type ConnectionStatus, type ConversationDetail, type ConversationInfo, type FloatingWindowConfig, type HitlInterruptData, type Locale, type MessageBlock, type MessageRole, type SdkAdapterConfig, type SendMessage, type StreamEvent, type ToolCall, type ToolCallStatus, type WindowPosition, createChatAdapter, createSdkAdapter, mergeConsecutiveAssistantMessages, parseToolCalls };