@qwickapps/qwickbrain-proxy 1.0.2 → 1.1.0

package/src/lib/proxy-server.ts

@@ -7,6 +7,9 @@ import {
 import { ConnectionManager } from './connection-manager.js';
 import { CacheManager } from './cache-manager.js';
 import { QwickBrainClient } from './qwickbrain-client.js';
+import { WriteQueueManager } from './write-queue-manager.js';
+import { SSEInvalidationListener } from './sse-invalidation-listener.js';
+import { QWICKBRAIN_TOOLS, requiresConnection } from './tools.js';
 import type { Config } from '../types/config.js';
 import type { DB } from '../db/client.js';
 import type { MCPResponse, MCPResponseMetadata } from '../types/mcp.js';
@@ -17,7 +20,10 @@ export class ProxyServer {
   private connectionManager: ConnectionManager;
   private cacheManager: CacheManager;
   private qwickbrainClient: QwickBrainClient;
+  private writeQueueManager: WriteQueueManager;
+  private sseInvalidationListener: SSEInvalidationListener | null = null;
   private config: Config;
+  private connectionInitialized = false;
 
   constructor(db: DB, config: Config) {
     this.config = config;
@@ -41,11 +47,42 @@ export class ProxyServer {
     );
 
     this.cacheManager = new CacheManager(db, config.cache);
+    this.writeQueueManager = new WriteQueueManager(db, this.qwickbrainClient);
+
+    // Initialize SSE invalidation listener if in SSE mode
+    if (config.qwickbrain.mode === 'sse' && config.qwickbrain.url) {
+      this.sseInvalidationListener = new SSEInvalidationListener(
+        config.qwickbrain.url,
+        this.cacheManager,
+        config.qwickbrain.apiKey
+      );
+    }
 
     this.setupHandlers();
     this.setupConnectionListeners();
   }
 
+  /**
+   * Lazy initialization: start connection manager on first tool call
+   * instead of eagerly on server startup. Saves CPU when QwickBrain
+   * tools are never used in a session.
+   */
+  private async ensureConnectionInitialized(): Promise<void> {
+    if (this.connectionInitialized) {
+      // If dormant, wake up on tool call
+      this.connectionManager.wakeUp();
+      return;
+    }
+
+    this.connectionInitialized = true;
+    console.error('First tool call received, initializing connection...');
+
+    await this.connectionManager.start();
+
+    // SSE listener starts only when connection is established (see setupConnectionListeners)
+    // Not here - avoid starting SSE reconnection loops before we know the server is reachable
+  }
+
   private setupConnectionListeners(): void {
     this.connectionManager.on('stateChange', ({ from, to }) => {
       console.error(`Connection state: ${from} → ${to}`);
@@ -57,14 +94,38 @@ export class ProxyServer {
 
     this.connectionManager.on('connected', ({ latencyMs }) => {
       console.error(`Connected to QwickBrain (latency: ${latencyMs}ms)`);
+
+      // Start SSE listener when connection is established
+      if (this.sseInvalidationListener && !this.sseInvalidationListener.isListening()) {
+        this.sseInvalidationListener.start().catch(err => {
+          console.error('SSE listener start error:', err);
+        });
+      }
+
       // Event-driven: trigger background sync when connection restored
       this.onConnectionRestored().catch(err => {
         console.error('Background sync error:', err);
       });
+      // Sync pending write operations
+      this.syncWriteQueue().catch(err => {
+        console.error('Write queue sync error:', err);
+      });
     });
 
     this.connectionManager.on('disconnected', ({ error }) => {
       console.error(`Disconnected from QwickBrain: ${error}`);
+      // Stop SSE listener when disconnected to avoid independent reconnection loops
+      if (this.sseInvalidationListener) {
+        this.sseInvalidationListener.stop();
+      }
+    });
+
+    this.connectionManager.on('dormant', () => {
+      console.error('Connection manager entered dormant mode');
+      // Stop SSE listener in dormant mode
+      if (this.sseInvalidationListener) {
+        this.sseInvalidationListener.stop();
+      }
     });
   }
 
@@ -90,66 +151,29 @@ export class ProxyServer {
     console.error('Background cache sync complete');
   }
 
+  private async syncWriteQueue(): Promise<void> {
+    const pendingCount = await this.writeQueueManager.getPendingCount();
+    if (pendingCount === 0) {
+      return;
+    }
+
+    console.error(`Syncing ${pendingCount} pending write operations...`);
+    const { synced, failed } = await this.writeQueueManager.syncPendingOperations();
+    console.error(`Write queue sync complete: ${synced} synced, ${failed} failed`);
+  }
+
   private setupHandlers(): void {
+    // Static tool listing - always returns all tools regardless of connection state
     this.server.setRequestHandler(ListToolsRequestSchema, async () => {
-      // Try to fetch tools from upstream if connected
-      if (this.connectionManager.getState() === 'connected') {
-        try {
-          const tools = await this.connectionManager.execute(async () => {
-            return await this.qwickbrainClient.listTools();
-          });
-          return { tools };
-        } catch (error) {
-          console.error('Failed to list tools from upstream:', error);
-        }
-      }
-
-      // Fallback to minimal tool set when offline or error
-      return {
-        tools: [
-          {
-            name: 'get_workflow',
-            description: 'Get a workflow definition by name (cached)',
-            inputSchema: {
-              type: 'object',
-              properties: {
-                name: { type: 'string', description: 'Workflow name' },
-              },
-              required: ['name'],
-            },
-          },
-          {
-            name: 'get_document',
-            description: 'Get a document by name and type (cached)',
-            inputSchema: {
-              type: 'object',
-              properties: {
-                name: { type: 'string', description: 'Document name' },
-                doc_type: { type: 'string', description: 'Document type (rule, frd, design, etc.)' },
-                project: { type: 'string', description: 'Project name (optional)' },
-              },
-              required: ['name', 'doc_type'],
-            },
-          },
-          {
-            name: 'get_memory',
-            description: 'Get a memory/context document by name (cached)',
-            inputSchema: {
-              type: 'object',
-              properties: {
-                name: { type: 'string', description: 'Memory name' },
-                project: { type: 'string', description: 'Project name (optional)' },
-              },
-              required: ['name'],
-            },
-          },
-        ],
-      };
+      return { tools: QWICKBRAIN_TOOLS };
     });
 
     this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
       const { name, arguments: args } = request.params;
 
+      // Lazy init: start connection on first tool call
+      await this.ensureConnectionInitialized();
+
       try {
         let result: MCPResponse;
 
@@ -171,8 +195,54 @@ export class ProxyServer {
               args?.project as string | undefined
             );
             break;
+          case 'create_document':
+          case 'update_document':
+            result = await this.handleCreateDocument(
+              args?.doc_type as string,
+              args?.name as string,
+              args?.content as string,
+              args?.project as string | undefined,
+              args?.metadata as Record<string, unknown> | undefined
+            );
+            break;
+          case 'set_memory':
+          case 'update_memory':
+            result = await this.handleSetMemory(
+              args?.name as string,
+              args?.content as string,
+              args?.project as string | undefined,
+              args?.metadata as Record<string, unknown> | undefined
+            );
+            break;
           default:
             // Generic forwarding for all other tools (analyze_repository, search_codebase, etc.)
+            // Check if tool requires connection
+            if (requiresConnection(name) && this.connectionManager.getState() !== 'connected') {
+              // Return offline error for non-cacheable tools
+              return {
+                content: [
+                  {
+                    type: 'text',
+                    text: JSON.stringify({
+                      error: {
+                        code: 'OFFLINE',
+                        message: `QwickBrain offline - "${name}" requires active connection`,
+                        suggestions: [
+                          'Check internet connection',
+                          'Wait for automatic reconnection',
+                          'Cached tools (get_workflow, get_document, get_memory) work offline',
+                        ],
+                      },
+                      _metadata: {
+                        source: 'cache',
+                        status: this.connectionManager.getState(),
+                      },
+                    }, null, 2),
+                  },
+                ],
+                isError: true,
+              };
+            }
             result = await this.handleGenericTool(name, args || {});
             break;
         }
@@ -226,17 +296,17 @@ export class ProxyServer {
     name: string,
     project?: string
   ): Promise<MCPResponse> {
-    // Try cache first
+    // Try cache first (LRU cache never expires, always valid if present)
     const cached = await this.cacheManager.getDocument(docType, name, project);
 
-    if (cached && !cached.isExpired) {
+    if (cached) {
       return {
         data: cached.data,
         _metadata: this.createMetadata('cache', cached.age),
       };
     }
 
-    // Try remote if connected
+    // Not cached - try remote if connected
     if (this.connectionManager.getState() === 'connected') {
       try {
         const result = await this.connectionManager.execute(async () => {
@@ -258,22 +328,11 @@ export class ProxyServer {
         };
       } catch (error) {
         console.error('Failed to fetch from QwickBrain:', error);
-        // Fall through to stale cache
+        // Fall through to error
       }
     }
 
-    // Try stale cache
-    if (cached) {
-      return {
-        data: cached.data,
-        _metadata: {
-          ...this.createMetadata('stale_cache', cached.age),
-          warning: `QwickBrain unavailable - serving cached data (${cached.age}s old)`,
-        },
-      };
-    }
-
-    // No cache, no connection
+    // No cache and remote failed/unavailable
     return {
       error: {
         code: 'UNAVAILABLE',
@@ -289,16 +348,17 @@ export class ProxyServer {
   }
 
   private async handleGetMemory(name: string, project?: string): Promise<MCPResponse> {
-    // Similar logic to handleGetDocument but for memories
+    // Try cache first (LRU cache never expires, always valid if present)
     const cached = await this.cacheManager.getMemory(name, project);
 
-    if (cached && !cached.isExpired) {
+    if (cached) {
       return {
         data: cached.data,
         _metadata: this.createMetadata('cache', cached.age),
       };
     }
 
+    // Not cached - try remote if connected
     if (this.connectionManager.getState() === 'connected') {
       try {
         const result = await this.connectionManager.execute(async () => {
@@ -313,19 +373,11 @@ export class ProxyServer {
         };
       } catch (error) {
         console.error('Failed to fetch memory from QwickBrain:', error);
+        // Fall through to error
       }
     }
 
-    if (cached) {
-      return {
-        data: cached.data,
-        _metadata: {
-          ...this.createMetadata('stale_cache', cached.age),
-          warning: `QwickBrain unavailable - serving cached memory (${cached.age}s old)`,
-        },
-      };
-    }
-
+    // No cache and remote failed/unavailable
     return {
       error: {
         code: 'UNAVAILABLE',
@@ -336,6 +388,94 @@ export class ProxyServer {
     };
   }
 
+  private async handleCreateDocument(
+    docType: string,
+    name: string,
+    content: string,
+    project?: string,
+    metadata?: Record<string, unknown>
+  ): Promise<MCPResponse> {
+    // Always update local cache first
+    await this.cacheManager.setDocument(docType, name, content, project, metadata);
+
+    // If connected, sync immediately
+    if (this.connectionManager.getState() === 'connected') {
+      try {
+        await this.connectionManager.execute(async () => {
+          await this.qwickbrainClient.createDocument(docType, name, content, project, metadata);
+        });
+
+        return {
+          data: { success: true },
+          _metadata: this.createMetadata('live'),
+        };
+      } catch (error) {
+        console.error('Failed to create document on QwickBrain:', error);
+        // Fall through to queue
+      }
+    }
+
+    // If offline or sync failed, queue for later
+    await this.writeQueueManager.queueOperation('create_document', {
+      docType,
+      name,
+      content,
+      project,
+      metadata,
+    });
+
+    return {
+      data: { success: true, queued: true },
+      _metadata: {
+        ...this.createMetadata('cache'),
+        warning: 'Operation queued - will sync when connection restored',
+      },
+    };
+  }
+
+  private async handleSetMemory(
+    name: string,
+    content: string,
+    project?: string,
+    metadata?: Record<string, unknown>
+  ): Promise<MCPResponse> {
+    // Always update local cache first
+    await this.cacheManager.setMemory(name, content, project, metadata);
+
+    // If connected, sync immediately
+    if (this.connectionManager.getState() === 'connected') {
+      try {
+        await this.connectionManager.execute(async () => {
+          await this.qwickbrainClient.setMemory(name, content, project, metadata);
+        });
+
+        return {
+          data: { success: true },
+          _metadata: this.createMetadata('live'),
+        };
+      } catch (error) {
+        console.error('Failed to set memory on QwickBrain:', error);
+        // Fall through to queue
+      }
+    }
+
+    // If offline or sync failed, queue for later
+    await this.writeQueueManager.queueOperation('set_memory', {
+      name,
+      content,
+      project,
+      metadata,
+    });
+
+    return {
+      data: { success: true, queued: true },
+      _metadata: {
+        ...this.createMetadata('cache'),
+        warning: 'Operation queued - will sync when connection restored',
+      },
+    };
+  }
+
   private async handleGenericTool(name: string, args: Record<string, unknown>): Promise<MCPResponse> {
     // Generic tool forwarding - no caching for non-document tools
     if (this.connectionManager.getState() !== 'connected') {
@@ -388,24 +528,25 @@ export class ProxyServer {
   }
 
   async start(): Promise<void> {
-    // Clean up expired cache entries on startup
-    const { documentsDeleted, memoriesDeleted } = await this.cacheManager.cleanupExpiredEntries();
-    if (documentsDeleted > 0 || memoriesDeleted > 0) {
-      console.error(`Cache cleanup: removed ${documentsDeleted} documents, ${memoriesDeleted} memories`);
-    }
-
-    // Start connection manager (handles connection gracefully, doesn't throw)
-    await this.connectionManager.start();
+    // Lazy init: do NOT start connection manager here.
+    // Connection is initialized on first tool call (see ensureConnectionInitialized).
+    // This means idle proxy instances use zero network resources.
 
     // Start MCP server
     const transport = new StdioServerTransport();
     await this.server.connect(transport);
 
-    console.error('QwickBrain Proxy started');
+    console.error('QwickBrain Proxy started (lazy mode - connection starts on first tool call)');
   }
 
   async stop(): Promise<void> {
     this.connectionManager.stop();
+
+    // Stop SSE invalidation listener
+    if (this.sseInvalidationListener) {
+      this.sseInvalidationListener.stop();
+    }
+
     try {
       await this.qwickbrainClient.disconnect();
     } catch (error) {

package/src/lib/qwickbrain-client.ts

@@ -229,25 +229,42 @@ export class QwickBrainClient {
 
   async healthCheck(): Promise<boolean> {
     try {
-      if (this.mode === 'mcp' || this.mode === 'sse') {
-        // For MCP/SSE mode, check if client is connected
-        if (!this.client) {
-          // Don't create new connection in health check - just return false
-          return false;
-        }
-        // Try listing tools as health check
-        await this.client.listTools();
-        return true;
-      } else {
+      if (this.mode === 'http') {
         // For HTTP mode, ping health endpoint
         if (!this.config.url) {
           return false;
         }
-        const response = await fetch(`${this.config.url}/health`);
+        const response = await fetch(`${this.config.url}/health`, {
+          signal: AbortSignal.timeout(5000),
+        });
         return response.ok;
       }
+
+      // For MCP/SSE mode: use a lightweight HTTP ping to the base URL
+      // instead of creating expensive MCP Client+Transport objects each time
+      if (this.config.url) {
+        const baseUrl = this.config.url.replace(/\/sse$/, '');
+        const response = await fetch(`${baseUrl}/health`, {
+          signal: AbortSignal.timeout(5000),
+        });
+        if (!response.ok) {
+          return false;
+        }
+      }
+
+      // Server is reachable; ensure MCP client is connected
+      if (!this.client) {
+        await this.connect();
+        if (!this.client) {
+          return false;
+        }
+      }
+
+      // Verify the MCP connection is alive
+      await this.client.listTools();
+      return true;
     } catch (error) {
-      // Connection dropped - clear client to force reconnection
+      // Connection dropped - clear client to force reconnection on next successful health check
       this.client = null;
       this.transport = null;
       return false;
@@ -310,6 +327,143 @@ export class QwickBrainClient {
     }
   }
 
+  async createDocument(
+    docType: string,
+    name: string,
+    content: string,
+    project?: string,
+    metadata?: Record<string, unknown>
+  ): Promise<void> {
+    if (this.mode === 'mcp' || this.mode === 'sse') {
+      if (!this.client) {
+        throw new Error('MCP client not connected');
+      }
+      await this.client.callTool({
+        name: 'create_document',
+        arguments: {
+          doc_type: docType,
+          name,
+          content,
+          project,
+          metadata,
+        },
+      });
+    } else {
+      if (!this.config.url) {
+        throw new Error('HTTP mode requires url to be configured');
+      }
+      const response = await fetch(`${this.config.url}/mcp/document/create`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          ...(this.config.apiKey && { 'Authorization': `Bearer ${this.config.apiKey}` }),
+        },
+        body: JSON.stringify({ doc_type: docType, name, content, project, metadata }),
+      });
+      if (!response.ok) {
+        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+      }
+    }
+  }
+
+  async setMemory(
+    name: string,
+    content: string,
+    project?: string,
+    metadata?: Record<string, unknown>
+  ): Promise<void> {
+    if (this.mode === 'mcp' || this.mode === 'sse') {
+      if (!this.client) {
+        throw new Error('MCP client not connected');
+      }
+      await this.client.callTool({
+        name: 'set_memory',
+        arguments: {
+          name,
+          content,
+          project,
+          metadata,
+        },
+      });
+    } else {
+      if (!this.config.url) {
+        throw new Error('HTTP mode requires url to be configured');
+      }
+      const response = await fetch(`${this.config.url}/mcp/memory/set`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          ...(this.config.apiKey && { 'Authorization': `Bearer ${this.config.apiKey}` }),
+        },
+        body: JSON.stringify({ name, content, project, metadata }),
+      });
+      if (!response.ok) {
+        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+      }
+    }
+  }
+
+  async deleteDocument(docType: string, name: string, project?: string): Promise<void> {
+    if (this.mode === 'mcp' || this.mode === 'sse') {
+      if (!this.client) {
+        throw new Error('MCP client not connected');
+      }
+      await this.client.callTool({
+        name: 'delete_document',
+        arguments: {
+          doc_type: docType,
+          name,
+          project,
+        },
+      });
+    } else {
+      if (!this.config.url) {
+        throw new Error('HTTP mode requires url to be configured');
+      }
+      const response = await fetch(`${this.config.url}/mcp/document/delete`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          ...(this.config.apiKey && { 'Authorization': `Bearer ${this.config.apiKey}` }),
+        },
+        body: JSON.stringify({ doc_type: docType, name, project }),
+      });
+      if (!response.ok) {
+        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+      }
+    }
+  }
+
+  async deleteMemory(name: string, project?: string): Promise<void> {
+    if (this.mode === 'mcp' || this.mode === 'sse') {
+      if (!this.client) {
+        throw new Error('MCP client not connected');
+      }
+      await this.client.callTool({
+        name: 'delete_memory',
+        arguments: {
+          name,
+          project,
+        },
+      });
+    } else {
+      if (!this.config.url) {
+        throw new Error('HTTP mode requires url to be configured');
+      }
+      const response = await fetch(`${this.config.url}/mcp/memory/delete`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          ...(this.config.apiKey && { 'Authorization': `Bearer ${this.config.apiKey}` }),
+        },
+        body: JSON.stringify({ name, project }),
+      });
+      if (!response.ok) {
+        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+      }
+    }
+  }
+
   async disconnect(): Promise<void> {
     if ((this.mode === 'mcp' || this.mode === 'sse') && this.client && this.transport) {
       await this.client.close();