solver-sdk 2.8.0 → 3.1.0

package/docs/QUICK_START.md

@@ -1,126 +0,0 @@
-# 🚀 Quick Start: VS Code Extension
-
-**5-минутный старт для разработчиков VS Code Extension**
-
-## 📦 Установка
-
-```bash
-npm install solver-sdk
-```
-
-## ⚡ Минимальный код (работает сразу!)
-
-```typescript
-// 1. Импорты
-import { CodeSolverSDK, VSCodeCommandEvent, CommandExecutionResult } from 'solver-sdk';
-import * as vscode from 'vscode';
-
-// 2. Инициализация SDK  
-const sdk = await CodeSolverSDK.create({
-  baseURL: 'http://localhost:3000',
-  apiKey: 'your-api-key'
-});
-
-// 3. Обработчик VS Code команд
-async function handleVSCodeCommand(command: VSCodeCommandEvent): Promise<CommandExecutionResult> {
-  const startTime = Date.now();
-  
-  try {
-    // Выполняем команду через VS Code API
-    const result = await vscode.commands.executeCommand(command.command, ...command.args);
-    
-    return {
-      requestId: command.requestId,
-      success: true,
-      result,
-      executionTime: Date.now() - startTime,
-      timestamp: Date.now()
-    };
-  } catch (error: any) {
-    return {
-      requestId: command.requestId,
-      success: false,
-      error: error.message,
-      executionTime: Date.now() - startTime,
-      timestamp: Date.now()
-    };
-  }
-}
-
-// 4. Использование
-const stream = await sdk.chat.streamChat(
-  [{ role: 'user', content: 'Создай компонент React Button' }],
-  {
-    thinking: true, // Адаптивный budget: 15000→12000→10000...→5000
-    onVSCodeCommand: handleVSCodeCommand  // Подключаем обработчик
-  }
-);
-
-// 5. Обработка событий
-for await (const chunk of stream) {
-  if (chunk.type === 'command_executed') {
-    console.log(`✅ Команда выполнена за ${chunk.commandResult?.executionTime}ms`);
-  } else if (chunk.type === 'text') {
-    console.log(`💬 AI ответ: ${chunk.text}`);
-  }
-}
-```
-
-## 🎯 Результат
-
-- **45ms** выполнение команд VS Code (вместо 443ms!)
-- **Нативная скорость** IDE  
-- **Real-time feedback** от AI
-
-## 📚 Что дальше?
-
-- **Поддерживаемые команды:** [Полный список](VSCODE_INTEGRATION.md#поддерживаемые-команды)
-- **Продвинутые примеры:** [Детальное руководство](VSCODE_INTEGRATION.md)
-- **Архитектура:** [HTTP vs WebSocket](ARCHITECTURE.md) (если интересно)
-
-## 🆘 Нужна помощь?
-
-**Самые частые вопросы:**
-
-### Q: Как зарегистрировать команды в Extension?
-```json
-// package.json
-{
-  "contributes": {
-    "commands": [
-      { "command": "aiSolver.native.createFile", "title": "AI: Create File" },
-      { "command": "aiSolver.native.editFile", "title": "AI: Edit File" }
-    ]
-  }
-}
-```
-
-### Q: Как обрабатывать ошибки команд?
-```typescript
-onVSCodeCommand: async (command) => {
-  try {
-    const result = await vscode.commands.executeCommand(command.command, ...command.args);
-    return { requestId: command.requestId, success: true, result, ... };
-  } catch (error) {
-    return { requestId: command.requestId, success: false, error: error.message, ... };
-  }
-}
-```
-
-### Q: Какие команды поддерживаются?
-```typescript
-import { VSCodeCommands } from 'solver-sdk';
-
-// Создание файлов
-VSCodeCommands.CREATE_FILE = 'aiSolver.native.createFile'
-
-// Редактирование  
-VSCodeCommands.EDIT_FILE = 'aiSolver.native.editFile'
-
-// Поиск
-VSCodeCommands.FIND_FILES = 'vscode.workspace.findFiles'
-
-// И еще 5 команд...
-```
-
-**🎉 Готово! Ваш Extension работает со скоростью нативного VS Code!** 

package/docs/WEBSOCKET.md

@@ -1,472 +0,0 @@
-# WebSocket API v2.7.0
-
-Полная документация по работе с WebSocket соединениями в AI Solver SDK v2.7.0 с поддержкой VS Code интеграции.
-
-## 🆕 Что нового в v2.7.0
-
-- ✅ **VS Code интеграция**: HTTP Streaming для команд VS Code
-- ✅ **5 WebSocket namespace'ов**: расширенная функциональность  
-- ✅ **Гибридная архитектура**: HTTP + WebSocket оптимально
-- ✅ **Performance**: 45ms VS Code команды vs 443ms старая архитектура
-
-## Инициализация с контролируемыми подключениями
-
-```javascript
-import { CodeSolverSDK } from 'solver-sdk';
-
-// Рекомендуемый способ v2.7.0
-const sdk = await CodeSolverSDK.create({
-  baseURL: 'http://localhost:3000',
-  apiKey: 'dev_sk_test_12345678',
-  websocket: {
-    autoConnect: false,  // Контролируемые WebSocket подключения
-    reconnect: true,     // Автоматическое переподключение
-    reconnectAttempts: 3 // Максимум попыток
-  }
-});
-
-// Диагностика перед подключением
-const wsStatus = await sdk.diagnoseWebSocket();
-console.log('WebSocket readiness:', wsStatus);
-```
-
-## 🏗️ Архитектурный выбор: HTTP vs WebSocket
-
-### 📊 **HTTP Streaming** (НОВОЕ в v2.7.0):
-```typescript
-// Используется для VS Code команд и AI чатов
-const stream = await sdk.chat.streamChat(messages, {
-  onVSCodeCommand: async (command) => {
-    // 45ms latency - 10x улучшение!
-    return await executeVSCodeCommand(command);
-  }
-});
-```
-
-**Когда использовать HTTP Streaming:**
-- ✅ AI модели ответы (Claude, GPT)
-- ✅ VS Code команды (создание файлов, редактирование)
-- ✅ Thinking токены
-- ✅ Быстрые операции (<30 сек)
-
-### 🔌 **WebSocket** (для специальных задач):
-**Когда использовать WebSocket:**
-- ✅ Индексирование файлов (прогресс в реальном времени)
-- ✅ Анализ проектов (длительные операции)
-- ✅ Граф зависимостей
-- ✅ Двусторонняя связь
-
-## WebSocket Namespaces (5 штук)
-
-SDK поддерживает 3 WebSocket namespace'а:
-
-1. **Default** (`/`) - события индексации, зависимостей и уведомления
-2. **Filesystem** (`/filesystem`) - удаленный доступ к файловой системе (VS Code remote)
-3. **File-editing** (`/file-editing`) - AI предложения изменений файлов
-
-> **Примечания:**
-> - **Dependencies и indexing** используют основной namespace `/` 
-> - **Reasoning** временно отключен из-за сложных зависимостей
-
-## Projects WebSocket
-
-### Подключение
-
-```javascript
-// Подключение к основному namespace для событий проектов
-await sdk.projects.connectWebSocket();
-
-// Проверка статуса подключения
-const isConnected = sdk.projects.isWebSocketConnected();
-console.log('Projects WebSocket connected:', isConnected);
-```
-
-### События индексации
-
-#### `indexing_progress`
-
-Прогресс индексации в реальном времени.
-
-```javascript
-sdk.projects.onIndexingProgress((data) => {
-  console.log(`Progress: ${data.percentage}%`);
-  console.log(`Files: ${data.processedFiles}/${data.totalFiles}`);
-  console.log(`Current: ${data.currentFile}`);
-  console.log(`Status: ${data.status}`);
-  console.log(`Speed: ${data.filesPerSecond} files/sec`);
-});
-```
-
-#### `indexing_complete`
-
-Завершение индексации.
-
-```javascript
-sdk.projects.onIndexingComplete((data) => {
-  console.log('Indexing completed:', data.projectId);
-  console.log('Total files:', data.totalFiles);
-  console.log('Duration:', data.duration);
-  console.log('Success:', data.success);
-  console.log('Errors:', data.errors);
-});
-```
-
-#### `indexing_error`
-
-Ошибки индексации.
-
-```javascript
-sdk.projects.onIndexingError((error) => {
-  console.error('Indexing error:', error.message);
-  console.error('Project:', error.projectId);
-  console.error('File:', error.fileName);
-  console.error('Code:', error.errorCode);
-});
-```
-
-### Пример полного цикла индексации
-
-```javascript
-async function indexProjectWithProgress(projectId) {
-  // Подключение к WebSocket
-  await sdk.projects.connectWebSocket();
-  
-  // Настройка обработчиков
-  sdk.projects.onIndexingProgress((data) => {
-    const progress = Math.round(data.percentage);
-    console.log(`[${progress}%] ${data.currentFile}`);
-  });
-  
-  sdk.projects.onIndexingComplete((data) => {
-    console.log('✅ Indexing completed!');
-    console.log(`📊 ${data.totalFiles} files indexed in ${data.duration}ms`);
-    sdk.projects.disconnectWebSocket();
-  });
-  
-  sdk.projects.onIndexingError((error) => {
-    console.error('❌ Indexing failed:', error.message);
-    sdk.projects.disconnectWebSocket();
-  });
-  
-  // Запуск индексации
-  await sdk.projects.startIndexing(projectId);
-}
-```
-
-## Reasoning WebSocket
-
-### Подключение
-
-```javascript
-// Подключение к reasoning namespace
-await sdk.reasoning.connectWebSocket();
-```
-
-### События reasoning
-
-#### `reasoning_started`
-
-Начало reasoning процесса.
-
-```javascript
-sdk.reasoning.onReasoningStarted((data) => {
-  console.log('🚀 Reasoning started:', data.id);
-  console.log('📝 Query:', data.query);
-  console.log('🎯 Project:', data.projectId);
-});
-```
-
-#### `reasoning_progress`
-
-Прогресс reasoning.
-
-```javascript
-sdk.reasoning.onReasoningProgress((data) => {
-  console.log('⚡ Progress:', data.progress);
-  console.log('📍 Step:', data.currentStep);
-  console.log('🔍 Action:', data.action);
-});
-```
-
-#### `reasoning_completed`
-
-Завершение reasoning.
-
-```javascript
-sdk.reasoning.onReasoningCompleted((data) => {
-  console.log('✅ Reasoning completed:', data.id);
-  console.log('📊 Results:', data.results);
-  console.log('⏱️ Duration:', data.duration);
-});
-```
-
-#### `reasoning_error`
-
-Ошибки reasoning.
-
-```javascript
-sdk.reasoning.onReasoningError((error) => {
-  console.error('❌ Reasoning error:', error.message);
-  console.error('🆔 Reasoning ID:', error.reasoningId);
-});
-```
-
-### Пример reasoning с WebSocket
-
-```javascript
-async function runReasoningWithEvents(projectId, query) {
-  // Подключение
-  await sdk.reasoning.connectWebSocket();
-  
-  // Обработчики
-  sdk.reasoning.onReasoningStarted((data) => {
-    console.log('🚀 Started reasoning:', data.id);
-  });
-  
-  sdk.reasoning.onReasoningProgress((data) => {
-    console.log(`⚡ ${data.progress}% - ${data.currentStep}`);
-  });
-  
-  sdk.reasoning.onReasoningCompleted((data) => {
-    console.log('✅ Results:', data.results);
-    sdk.reasoning.disconnectWebSocket();
-  });
-  
-  // Создание и запуск
-  const reasoning = await sdk.reasoning.create({
-    projectId: projectId,
-    query: query
-  });
-  
-  await sdk.reasoning.start(reasoning.id);
-}
-```
-
-## Chat WebSocket
-
-### Подключение
-
-```javascript
-// Подключение к chat namespace
-await sdk.chat.connectWebSocket();
-```
-
-### События потокового чата
-
-#### `text_delta`
-
-Фрагменты текстового ответа.
-
-```javascript
-sdk.chat.onTextDelta((text) => {
-  process.stdout.write(text); // Вывод в реальном времени
-});
-```
-
-#### `thinking_delta`
-
-Фрагменты thinking блоков (Claude 4).
-
-```javascript
-sdk.chat.onThinkingDelta((thinking) => {
-  console.log('🧠 Thinking:', thinking);
-});
-```
-
-#### `tool_use`
-
-Использование инструментов AI.
-
-```javascript
-sdk.chat.onToolUse((tool) => {
-  console.log('🔧 Tool used:', tool.name);
-  console.log('📥 Input:', tool.input);
-});
-```
-
-#### `message_complete`
-
-Завершение сообщения.
-
-```javascript
-sdk.chat.onMessageComplete((message) => {
-  console.log('✅ Message completed');
-  console.log('📄 Full content:', message.content);
-});
-```
-
-### Потоковый чат с thinking
-
-```javascript
-async function streamChatWithThinking(messages) {
-  // Подключение
-  await sdk.chat.connectWebSocket();
-  
-  let fullResponse = '';
-  let thinkingContent = '';
-  
-  // Обработчики
-  sdk.chat.onThinkingDelta((thinking) => {
-    thinkingContent += thinking;
-    console.log('🧠 Thinking fragment:', thinking);
-  });
-  
-  sdk.chat.onTextDelta((text) => {
-    fullResponse += text;
-    process.stdout.write(text);
-  });
-  
-  sdk.chat.onToolUse((tool) => {
-    console.log(`\n🔧 Using tool: ${tool.name}`);
-  });
-  
-  sdk.chat.onMessageComplete((message) => {
-    console.log('\n✅ Response completed');
-    console.log('💭 Full thinking:', thinkingContent);
-    sdk.chat.disconnectWebSocket();
-  });
-  
-  // Отправка с thinking
-  await sdk.chat.stream(messages, {
-    thinking: true,
-    model: 'claude-3-5-sonnet-20241022',
-    tool_choice: { type: 'auto' }
-  });
-}
-```
-
-## Управление подключениями
-
-### Подключение/отключение
-
-```javascript
-// Подключение к конкретным namespace
-await sdk.projects.connectWebSocket();
-await sdk.reasoning.connectWebSocket();
-await sdk.chat.connectWebSocket();
-
-// Отключение
-await sdk.projects.disconnectWebSocket();
-await sdk.reasoning.disconnectWebSocket();
-await sdk.chat.disconnectWebSocket();
-
-// Проверка статуса
-console.log('Projects WS:', sdk.projects.isWebSocketConnected());
-console.log('Reasoning WS:', sdk.reasoning.isWebSocketConnected());
-console.log('Chat WS:', sdk.chat.isWebSocketConnected());
-```
-
-### Диагностика WebSocket
-
-```javascript
-// Полная диагностика WebSocket
-const wsStatus = await sdk.diagnoseWebSocket();
-console.log('WebSocket Diagnostics:', wsStatus);
-
-/* Пример ответа:
-{
-  projects: { connected: true, url: 'ws://localhost:3000/projects' },
-  reasoning: { connected: false, url: 'ws://localhost:3000/reasoning' },
-  chat: { connected: true, url: 'ws://localhost:3000/chat' }
-}
-*/
-```
-
-## Обработка ошибок WebSocket
-
-```javascript
-// Обработка ошибок подключения
-try {
-  await sdk.projects.connectWebSocket();
-} catch (error) {
-  console.error('WebSocket connection failed:', error.message);
-  // Fallback к HTTP API
-}
-
-// Обработка разрывов соединения
-sdk.projects.on('disconnect', () => {
-  console.log('Projects WebSocket disconnected');
-  // Логика переподключения
-});
-
-sdk.reasoning.on('error', (error) => {
-  console.error('Reasoning WebSocket error:', error);
-});
-```
-
-## WebSocket URLs
-
-| Namespace | URL | Описание |
-|-----------|-----|----------|
-| Projects | `ws://localhost:3000/projects` | События проектов и индексации |
-| Reasoning | `ws://localhost:3000/reasoning` | События AI reasoning |
-| Chat | `ws://localhost:3000/chat` | Потоковый чат и thinking |
-
-## Аутентификация
-
-WebSocket соединения автоматически используют API ключ из настроек SDK:
-
-```javascript
-const sdk = CodeSolverSDK.create({
-  baseURL: 'http://localhost:3000',
-  apiKey: 'dev_sk_test_12345678', // Автоматически используется для WS
-  autoConnect: false
-});
-```
-
-## Производительность
-
-### Рекомендации
-
-1. **Используйте autoConnect: false** для контроля подключений
-2. **Подключайтесь только к нужным namespace** для экономии ресурсов
-3. **Отключайтесь после завершения** операций
-4. **Используйте диагностику** для мониторинга состояния
-
-### Пример оптимизированного использования
-
-```javascript
-async function optimizedWorkflow(projectId, query) {
-  const sdk = CodeSolverSDK.create({
-    baseURL: 'http://localhost:3000',
-    apiKey: 'dev_sk_test_12345678',
-    autoConnect: false
-  });
-  
-  try {
-    // 1. Индексация проекта
-    await sdk.projects.connectWebSocket();
-    await sdk.projects.startIndexing(projectId);
-    
-    await new Promise(resolve => {
-      sdk.projects.onIndexingComplete(() => {
-        sdk.projects.disconnectWebSocket();
-        resolve();
-      });
-    });
-    
-    // 2. Reasoning
-    await sdk.reasoning.connectWebSocket();
-    const reasoning = await sdk.reasoning.create({ projectId, query });
-    await sdk.reasoning.start(reasoning.id);
-    
-    await new Promise(resolve => {
-      sdk.reasoning.onReasoningCompleted(() => {
-        sdk.reasoning.disconnectWebSocket();
-        resolve();
-      });
-    });
-    
-    console.log('✅ Workflow completed');
-    
-  } catch (error) {
-    console.error('❌ Workflow failed:', error);
-  }
-}
-```
-
----
-
-**Документация WebSocket API для SDK v2.5.0**  
-**Совместимость:** AI Solver Backend v1.0.0  
-**Обновлено:** 28 июня 2025