@mooncompany/uplink-chat 0.5.0

package/server/routes/artifacts.js

@@ -0,0 +1,174 @@
+/**
+ * Artifacts Routes - Read-only API for artifacts directory
+ * Provides file listing and content reading for agent-generated documents
+ */
+
+import fs from 'fs/promises';
+import fsSync from 'fs';
+import path from 'path';
+import { badRequest, internalError, ErrorCodes } from '../../utils/errors.js';
+
+/**
+ * Setup artifacts routes
+ * @param {Express} app - Express app instance
+ * @param {Object} context - Request context
+ */
+export function setupArtifactsRoutes(app, context) {
+  const { log, config } = context;
+  
+  // Artifacts directory — check multiple locations:
+  // 1. ARTIFACTS_DIR env var (explicit override)
+  // 2. Workspace root (parent of uplink dir) — common for OpenClaw workspace layout
+  // 3. Uplink server directory itself (fallback)
+  const rootDir = config.ROOT_DIR || process.cwd();
+  const candidates = [
+    process.env.ARTIFACTS_DIR,
+    path.join(path.dirname(rootDir), 'artifacts'),
+    path.join(rootDir, 'artifacts'),
+  ].filter(Boolean);
+  
+  let artifactsDir = candidates[candidates.length - 1]; // default to last
+  for (const candidate of candidates) {
+    try {
+      const stat = fsSync.statSync(candidate);
+      if (stat.isDirectory()) {
+        artifactsDir = candidate;
+        break;
+      }
+    } catch { /* continue */ }
+  }
+  
+  // Allowed file extensions for security (read-only access to text/doc files)
+  const ALLOWED_EXTENSIONS = [
+    '.md', '.txt', '.html', '.json', '.csv', 
+    '.yml', '.yaml', '.xml', '.log'
+  ];
+
+  /**
+   * Validate filename - prevent path traversal and restrict to allowed extensions
+   */
+  function validateFilename(filename) {
+    if (!filename || typeof filename !== 'string') {
+      return { valid: false, error: 'Invalid filename' };
+    }
+    
+    // Security: No path separators, no parent directory refs
+    if (filename.includes('..') || filename.includes('/') || filename.includes('\\')) {
+      return { valid: false, error: 'Invalid characters in filename' };
+    }
+    
+    // Security: Must have an allowed extension
+    const ext = path.extname(filename).toLowerCase();
+    if (!ALLOWED_EXTENSIONS.includes(ext)) {
+      return { valid: false, error: 'File type not allowed' };
+    }
+    
+    // Additional security: Restrict to alphanumeric, dash, underscore, dot
+    if (!/^[a-zA-Z0-9._-]+$/.test(filename)) {
+      return { valid: false, error: 'Invalid filename format' };
+    }
+    
+    return { valid: true };
+  }
+
+  // ===========================================
+  // GET /api/artifacts
+  // List all artifacts in the directory
+  // ===========================================
+  
+  app.get('/api/artifacts', async (req, res) => {
+    try {
+      // Check if directory exists
+      const stat = await fs.stat(artifactsDir).catch(() => null);
+      if (!stat || !stat.isDirectory()) {
+        // Empty list if directory doesn't exist yet
+        return res.json([]);
+      }
+      
+      // Read directory
+      const files = await fs.readdir(artifactsDir);
+      
+      // Filter to allowed types and gather metadata
+      const artifacts = [];
+      for (const filename of files) {
+        const validation = validateFilename(filename);
+        if (!validation.valid) continue;
+        
+        const filePath = path.join(artifactsDir, filename);
+        const stat = await fs.stat(filePath).catch(() => null);
+        
+        if (!stat || !stat.isFile()) continue;
+        
+        artifacts.push({
+          name: filename,
+          size: stat.size,
+          modified: stat.mtime.toISOString(),
+          extension: path.extname(filename).toLowerCase()
+        });
+      }
+      
+      // Sort by modified date (newest first)
+      artifacts.sort((a, b) => new Date(b.modified) - new Date(a.modified));
+      
+      res.json(artifacts);
+      
+    } catch (error) {
+      log('error', '[Artifacts] List error:', error);
+      internalError(res, 'Failed to list artifacts', ErrorCodes.INTERNAL_ERROR);
+    }
+  });
+
+  // ===========================================
+  // GET /api/artifacts/:filename
+  // Read artifact file contents
+  // ===========================================
+  
+  app.get('/api/artifacts/:filename', async (req, res) => {
+    try {
+      const { filename } = req.params;
+      
+      // Validate filename
+      const validation = validateFilename(filename);
+      if (!validation.valid) {
+        return badRequest(res, validation.error, ErrorCodes.INVALID_FILE_TYPE);
+      }
+      
+      const filePath = path.join(artifactsDir, filename);
+      
+      // Security: Double-check the resolved path is within artifacts directory
+      const resolvedPath = path.resolve(filePath);
+      const resolvedDir = path.resolve(artifactsDir);
+      if (!resolvedPath.startsWith(resolvedDir)) {
+        log('warn', `[Artifacts] Path traversal attempt: ${filename}`);
+        return badRequest(res, 'Invalid file path', ErrorCodes.INVALID_FILE_TYPE);
+      }
+      
+      // Check file exists
+      const stat = await fs.stat(filePath).catch(() => null);
+      if (!stat || !stat.isFile()) {
+        return res.status(404).json({ error: 'File not found' });
+      }
+      
+      // Read file content
+      const content = await fs.readFile(filePath, 'utf-8');
+      
+      // Return content with metadata
+      res.json({
+        name: filename,
+        content,
+        size: stat.size,
+        modified: stat.mtime.toISOString(),
+        extension: path.extname(filename).toLowerCase()
+      });
+      
+    } catch (error) {
+      log('error', '[Artifacts] Read error:', error);
+      
+      if (error.code === 'ENOENT') {
+        return res.status(404).json({ error: 'File not found' });
+      }
+      
+      internalError(res, 'Failed to read artifact', ErrorCodes.INTERNAL_ERROR);
+    }
+  });
+}

package/server/routes/chat.js

@@ -0,0 +1,311 @@
+/**
+ * Chat Routes - Text chat and streaming endpoints
+ */
+
+import { MAX_INPUT_LENGTHS, SSE_KEEPALIVE_INTERVAL_MS } from '../config.js';
+import { badRequest, internalError, ErrorCodes } from '../../utils/errors.js';
+import { broadcastSyncMessage, generateMessageId, broadcastSyncThinking, broadcastSyncDelta, broadcastSyncTool, broadcastSyncComplete, cleanupSyncDeltaThrottle } from '../websocket/index.js';
+import { isGatewayCommand, sendGatewayCommand } from '../gateway-commands.js';
+
+/**
+ * Validate input length and return error if exceeded
+ * @param {string} value - Input value to validate
+ * @param {number} maxLength - Maximum allowed length
+ * @param {string} fieldName - Field name for error message
+ * @returns {string|null} Error message or null if valid
+ */
+function validateLength(value, maxLength, fieldName) {
+  if (value && value.length > maxLength) {
+    return `${fieldName} exceeds maximum length of ${maxLength} characters`;
+  }
+  return null;
+}
+
+/**
+ * Setup chat routes
+ * @param {Express} app - Express app instance
+ * @param {Object} context - Request context
+ */
+export function setupChatRoutes(app, context) {
+  const {
+    chat,
+    chatWithParallelTTS,
+    generateTTS,
+    sendMessage,
+    saveMessageToSync,
+    log,
+    config,
+  } = context;
+
+  const { SESSION_USER } = config;
+
+  // ===========================================
+  // Text Chat (Streaming)
+  // ===========================================
+
+  app.post('/api/chat', async (req, res) => {
+    const { message, mode = 'text', stream = false, satelliteId: rawSatelliteId = 'main', satelliteName: rawSatelliteName, agentId: rawAgentId } = req.body;
+
+    if (!message) {
+      return badRequest(res, 'No message provided', ErrorCodes.MISSING_FIELD);
+    }
+
+    const lengthError = validateLength(message, MAX_INPUT_LENGTHS.MESSAGE, 'Message');
+    if (lengthError) return badRequest(res, lengthError, ErrorCodes.VALIDATION_ERROR);
+    
+    // Validate satelliteId
+    const satelliteId = String(rawSatelliteId).replace(/[^a-zA-Z0-9_-]/g, '').substring(0, 32) || 'main';
+    
+    // Sanitize satellite name (for session label)
+    const satelliteName = rawSatelliteName ? String(rawSatelliteName).substring(0, 64) : null;
+
+    // Validate agentId (optional — defaults to 'main')
+    const agentId = rawAgentId ? String(rawAgentId).replace(/[^a-z0-9-]/g, '').substring(0, 64) || 'main' : 'main';
+    
+    if (satelliteId !== rawSatelliteId) {
+      log('warn', `[Chat] Sanitized satelliteId: "${rawSatelliteId}" → "${satelliteId}"`);
+    }
+
+    log('debug', `[${mode === 'voice' ? 'Voice' : 'Text'}] [satellite:${satelliteId}] [agent:${agentId}] [label:${satelliteName}] "${message}"`);
+    await saveMessageToSync('user', message);
+    
+    // Broadcast user message to WebSocket clients for cross-device sync
+    const userMessageId = generateMessageId();
+    broadcastSyncMessage('user', message, satelliteId, userMessageId);
+
+    // Intercept gateway slash commands — send via WebSocket instead of HTTP API
+    // The /v1/chat/completions endpoint doesn't process slash commands
+    if (isGatewayCommand(message)) {
+      log('info', `[Chat] Gateway command detected: ${message}`);
+      try {
+        const sessionKey = satelliteId === 'main'
+          ? `agent:${agentId}:main`
+          : `agent:${agentId}:uplink:satellite:${satelliteId}`;
+        const result = await sendGatewayCommand(message, sessionKey);
+        
+        if (stream) {
+          res.setHeader('Content-Type', 'text/event-stream; charset=utf-8');
+          res.setHeader('Cache-Control', 'no-cache');
+          res.setHeader('Connection', 'keep-alive');
+          res.flushHeaders();
+          
+          if (result.response) {
+            res.write(`data: ${JSON.stringify({ content: result.response })}\n\n`);
+            await saveMessageToSync('assistant', result.response);
+            const assistantMessageId = generateMessageId();
+            broadcastSyncMessage('assistant', result.response, satelliteId, assistantMessageId);
+          }
+          res.write(`data: ${JSON.stringify({ done: true })}\n\n`);
+          res.write(`data: [DONE]\n\n`);
+          res.end();
+        } else {
+          if (result.response) {
+            await saveMessageToSync('assistant', result.response);
+            const assistantMessageId = generateMessageId();
+            broadcastSyncMessage('assistant', result.response, satelliteId, assistantMessageId);
+          }
+          res.json({ response: result.response || 'Command executed.' });
+        }
+      } catch (err) {
+        log('error', `[Chat] Gateway command error: ${err.message}`);
+        // Always return generic error to client; detailed error logged server-side
+        const genericMessage = 'Command execution failed';
+        if (stream) {
+          res.setHeader('Content-Type', 'text/event-stream; charset=utf-8');
+          res.setHeader('Cache-Control', 'no-cache');
+          res.flushHeaders();
+          res.write(`data: ${JSON.stringify({ error: true, message: genericMessage })}\n\n`);
+          res.end();
+        } else {
+          internalError(res, genericMessage, ErrorCodes.INTERNAL_ERROR);
+        }
+      }
+      return;
+    }
+
+    // Streaming SSE response
+    if (stream && mode === 'text') {
+      res.setHeader('Content-Type', 'text/event-stream; charset=utf-8');
+      res.setHeader('Cache-Control', 'no-cache');
+      res.setHeader('Connection', 'keep-alive');
+      res.setHeader('X-Accel-Buffering', 'no');
+      res.flushHeaders();
+
+      // Track disconnect state and create abort controller for cleanup
+      const abortController = new AbortController();
+      let clientDisconnected = false;
+
+      const keepAlive = setInterval(() => {
+        if (!clientDisconnected) {
+          res.write(`: keepalive\n\n`);
+        }
+      }, SSE_KEEPALIVE_INTERVAL_MS);
+
+      // Cleanup function to handle disconnect
+      const cleanup = () => {
+        clientDisconnected = true;
+        abortController.abort();
+        clearInterval(keepAlive);
+      };
+
+      // Listen for client disconnect
+      req.on('close', () => {
+        if (!clientDisconnected) {
+          log('debug', '[Stream] Client disconnected mid-stream');
+          cleanup();
+        }
+      });
+
+      // Safe write helper - only write if client still connected
+      const safeWrite = (data) => {
+        if (!clientDisconnected && !res.writableEnded) {
+          try {
+            res.write(data);
+          } catch (e) {
+            // Client disconnected during write
+            cleanup();
+          }
+        }
+      };
+
+      // Generate request ID for correlating sync stream deltas with final message
+      const syncRequestId = generateMessageId();
+
+      try {
+        // Use unified sendMessage (routes through channel if enabled)
+        const result = await sendMessage({
+          message,
+          satelliteId,
+          satelliteName,
+          agentId,
+          mode,
+          signal: abortController.signal,
+          onThinking: () => {
+            safeWrite(`data: ${JSON.stringify({ status: 'thinking' })}\n\n`);
+            broadcastSyncThinking(syncRequestId, satelliteId);
+          },
+          onChunk: (content) => {
+            safeWrite(`data: ${JSON.stringify({ content })}\n\n`);
+            broadcastSyncDelta(syncRequestId, content, satelliteId);
+          },
+          onTool: (tool) => {
+            safeWrite(`data: ${JSON.stringify({ tool })}\n\n`);
+            broadcastSyncTool(syncRequestId, tool, satelliteId);
+          },
+        });
+
+        // Only complete if client still connected
+        if (!clientDisconnected) {
+          // Process media references if present
+          let mediaUrls = null;
+          if (result.media && result.media.length > 0 && app.registerAgentMedia) {
+            mediaUrls = result.media
+              .map(filePath => app.registerAgentMedia(filePath))
+              .filter(url => url !== null);
+            
+            if (mediaUrls.length > 0) {
+              log('debug', `[Media] Registered ${mediaUrls.length} file(s)`);
+            }
+          }
+
+          if (result.response) {
+            await saveMessageToSync('assistant', result.response);
+
+            // Flush remaining deltas before sending final sync message
+            cleanupSyncDeltaThrottle(syncRequestId);
+
+            // Broadcast assistant response to WebSocket clients for cross-device sync
+            const assistantMessageId = generateMessageId();
+            broadcastSyncMessage('assistant', result.response, satelliteId, assistantMessageId, null, syncRequestId);
+          }
+
+          // Broadcast usage stats via WebSocket for WS-streaming clients
+          broadcastSyncComplete(syncRequestId, result.usage, satelliteId);
+
+          safeWrite(`data: ${JSON.stringify({ 
+            done: true, 
+            usage: result.usage,
+            tools: result.tools,
+            media: mediaUrls
+          })}\n\n`);
+          safeWrite(`data: [DONE]\n\n`);
+
+          log('debug', `[Response] "${result.response.substring(0, 100)}..." tokens: ${result.usage?.total_tokens || '?'}${result.usage?.estimated ? ' (est)' : ''}`);
+        }
+
+        cleanup();
+        if (!res.writableEnded) {
+          res.end();
+        }
+
+      } catch (error) {
+        cleanupSyncDeltaThrottle(syncRequestId);
+        cleanup();
+
+        // Don't log or send error if client disconnected (AbortError or write failure)
+        if (clientDisconnected || error.name === 'AbortError') {
+          log('debug', '[Stream] Request aborted due to client disconnect');
+        } else {
+          log('error', 'Stream error:', error);
+          if (!res.writableEnded) {
+            try {
+              // Always return generic error to client; detailed error logged server-side
+              const genericMessage = 'Unable to reach the AI service';
+              res.write(`data: ${JSON.stringify({ error: true, message: genericMessage })}\n\n`);
+            } catch (e) {
+              // Ignore write errors during error handling
+            }
+          }
+        }
+        
+        if (!res.writableEnded) {
+          res.end();
+        }
+      }
+      return;
+    }
+
+    // Non-streaming fallback - use unified sendMessage for session sync
+    try {
+      let response = '';
+      let audioUrl = null;
+      let audioUrls = [];
+      
+      if (mode === 'voice') {
+        try {
+          const result = await chatWithParallelTTS(message, SESSION_USER);
+          response = result.response;
+          audioUrl = result.audioUrl;
+          audioUrls = result.audioUrls || [];
+        } catch (parallelError) {
+          log('warn', 'Parallel TTS failed, falling back:', parallelError.message);
+          // Use sendMessage for consistent session key handling
+          const result = await sendMessage({ message, satelliteId, satelliteName, agentId, mode });
+          response = result.response;
+          try {
+            audioUrl = await generateTTS(response);
+            audioUrls = audioUrl ? [audioUrl] : [];
+          } catch (e) {
+            log('error', 'TTS failed:', e.message);
+          }
+        }
+      } else {
+        // Use sendMessage for consistent session key handling (session sync)
+        const result = await sendMessage({ message, satelliteId, satelliteName, agentId, mode });
+        response = result.response;
+      }
+      
+      log('debug', `[Response] "${response.substring(0, 100)}..."`);
+      await saveMessageToSync('assistant', response);
+      
+      // Broadcast assistant response to WebSocket clients for cross-device sync
+      const assistantMsgId = generateMessageId();
+      broadcastSyncMessage('assistant', response, satelliteId, assistantMsgId);
+
+      res.json({ response, audioUrl, audioUrls });
+    } catch (error) {
+      log('error', 'Chat error:', error);
+      internalError(res, error.message, ErrorCodes.INTERNAL_ERROR);
+    }
+  });
+}