@mooncompany/uplink-chat 0.5.0

package/server/channel.js

@@ -0,0 +1,529 @@
+/**
+ * Channel Module - OpenClaw channel webhook integration
+ * 
+ * Routes messages through the OpenClaw channel plugin for proper
+ * session isolation and unified message handling.
+ */
+
+import { log, fetchWithTimeout } from './utils.js';
+import { isGatewayCommand as isGatewayCommandUtil } from './gateway-commands.js';
+import { 
+  OPENCLAW_WEBHOOK_URL, 
+  OPENCLAW_CALLBACK_SECRET,
+  USE_CHANNEL_WEBHOOK,
+  GATEWAY_URL as STATIC_GATEWAY_URL,
+  GATEWAY_TOKEN as STATIC_GATEWAY_TOKEN,
+  SESSION_USER,
+  CHANNEL_FETCH_TIMEOUT_MS,
+  STREAM_READ_TIMEOUT_MS
+} from './config.js';
+import { loadConfig } from './runtime-config.js';
+
+/**
+ * Get gateway URL and token, preferring runtime config (which includes auto-discovery)
+ * over static config.js values. This is needed because config.js exports are set at
+ * module load time and don't reflect auto-discovered values.
+ */
+async function getGatewayConfig() {
+  try {
+    const config = await loadConfig();
+    return {
+      url: config.gatewayUrl || STATIC_GATEWAY_URL,
+      token: config.gatewayToken || STATIC_GATEWAY_TOKEN,
+    };
+  } catch {
+    // Fallback to static config if runtime config fails
+    return { url: STATIC_GATEWAY_URL, token: STATIC_GATEWAY_TOKEN };
+  }
+}
+
+/**
+ * Check if channel webhook routing is enabled and configured
+ */
+export function isChannelEnabled() {
+  return USE_CHANNEL_WEBHOOK && OPENCLAW_WEBHOOK_URL && OPENCLAW_CALLBACK_SECRET;
+}
+
+/**
+ * Send a message through the OpenClaw channel webhook
+ * Returns an async generator that yields stream chunks
+ * 
+ * @param {Object} params
+ * @param {string} params.message - The message to send
+ * @param {string} params.satelliteId - Satellite ID for session isolation
+ * @param {string} params.mode - 'text' or 'voice'
+ * @param {string} params.requestId - Optional request ID for tracking
+ * @param {string} params.userId - Optional user ID
+ */
+export async function* sendViaChannel({ message, satelliteId = 'main', mode = 'text', requestId, userId = 'default' }) {
+  if (!isChannelEnabled()) {
+    throw new Error('Channel webhook not configured');
+  }
+  
+  log('debug', `[Channel] Sending to webhook: satellite=${satelliteId}, mode=${mode}`);
+  
+  const response = await fetchWithTimeout(OPENCLAW_WEBHOOK_URL, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'X-Uplink-Secret': OPENCLAW_CALLBACK_SECRET,
+    },
+    body: JSON.stringify({
+      message,
+      satelliteId,
+      mode,
+      requestId,
+      userId,
+    }),
+  }, CHANNEL_FETCH_TIMEOUT_MS);
+  
+  if (!response.ok) {
+    const text = await response.text();
+    throw new Error(`Channel webhook error: ${response.status} - ${text}`);
+  }
+  
+  // Parse SSE stream
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = '';
+  
+  // Helper to read with timeout (prevents hanging on stalled streams)
+  const readWithTimeout = (timeoutMs = STREAM_READ_TIMEOUT_MS) => {
+    return Promise.race([
+      reader.read(),
+      new Promise((_, reject) => 
+        setTimeout(() => reject(new Error('Stream read timed out - gateway may be stalled')), timeoutMs)
+      ),
+    ]);
+  };
+  
+  try {
+    while (true) {
+      const { done, value } = await readWithTimeout();
+      if (done) break;
+      
+      buffer += decoder.decode(value, { stream: true });
+      const lines = buffer.split('\n');
+      buffer = lines.pop() || '';
+      
+      for (const line of lines) {
+        if (line.startsWith('data: ')) {
+          const data = line.slice(6);
+          if (data === '[DONE]') {
+            return;
+          }
+          
+          try {
+            const parsed = JSON.parse(data);
+            yield parsed; // { type: 'thinking' | 'chunk' | 'tool' | 'complete' | 'error', ... }
+          } catch {
+            // Skip unparseable chunks
+          }
+        }
+      }
+    }
+  } finally {
+    // Ensure reader is released on timeout or error
+    reader.releaseLock();
+  }
+}
+
+// ============================================================================
+// sendMessage Helper Functions
+// ============================================================================
+
+/**
+ * Create a reader with timeout capability
+ * Prevents hanging on stalled streams (uses STREAM_READ_TIMEOUT_MS for agent tool use)
+ * 
+ * @param {ReadableStreamDefaultReader} reader - The stream reader
+ * @param {number} timeoutMs - Timeout in milliseconds (default from config)
+ * @returns {Promise} - Resolves with read result or rejects on timeout
+ */
+function createReadWithTimeout(reader, timeoutMs = STREAM_READ_TIMEOUT_MS) {
+  return Promise.race([
+    reader.read(),
+    new Promise((_, reject) => 
+      setTimeout(() => reject(new Error('Stream read timed out - gateway may be stalled')), timeoutMs)
+    ),
+  ]);
+}
+
+/**
+ * Estimate token usage when not provided by the API
+ * 
+ * @param {string} inputMessage - The input message
+ * @param {string} outputResponse - The output response
+ * @returns {Object} - Estimated token usage object
+ */
+function estimateTokenUsage(inputMessage, outputResponse) {
+  const promptTokens = Math.ceil(inputMessage.length / 4);
+  const completionTokens = Math.ceil(outputResponse.length / 4);
+  return {
+    prompt_tokens: promptTokens,
+    completion_tokens: completionTokens,
+    total_tokens: promptTokens + completionTokens,
+    estimated: true,
+  };
+}
+
+/**
+ * Process events from the channel webhook stream
+ * 
+ * @param {Object} params
+ * @param {AsyncIterable} params.eventStream - The channel event stream
+ * @param {AbortSignal} params.signal - Abort signal for cancellation
+ * @param {Object} params.callbacks - Event callbacks
+ * @returns {Object} - { fullResponse, tokenUsage, detectedTools }
+ */
+async function processChannelStream({ eventStream, signal, callbacks }) {
+  const { onChunk, onTool, onThinking } = callbacks;
+  let fullResponse = '';
+  let tokenUsage = null;
+  const detectedTools = [];
+
+  for await (const event of eventStream) {
+    if (signal?.aborted) {
+      log('debug', '[Channel] Request aborted during channel streaming');
+      break;
+    }
+
+    switch (event.type) {
+      case 'thinking':
+        onThinking?.();
+        break;
+      case 'chunk':
+        if (event.content) {
+          fullResponse += event.content;
+          onChunk?.(event.content);
+        }
+        break;
+      case 'tool':
+        if (event.tool && !detectedTools.includes(event.tool)) {
+          detectedTools.push(event.tool);
+          onTool?.(event.tool);
+        }
+        break;
+      case 'complete':
+        if (event.response) {
+          fullResponse = event.response;
+        }
+        if (event.usage) {
+          tokenUsage = event.usage;
+        }
+        break;
+      case 'error':
+        throw new Error(event.error || 'Unknown channel error');
+    }
+  }
+
+  return { fullResponse, tokenUsage, detectedTools };
+}
+
+/**
+ * Build the gateway request configuration
+ * 
+ * @param {Object} params
+ * @param {string} params.message - The message to send
+ * @param {string} params.satelliteId - Satellite ID
+ * @param {string} params.satelliteName - Satellite display name (for session label)
+ * @param {string} params.mode - 'text' or 'voice'
+ * @param {AbortSignal} params.signal - Abort signal
+ * @returns {Object} - { url, options, sessionKey }
+ */
+// Re-use isGatewayCommand from gateway-commands.js (single source of truth - M-32 fix)
+const isGatewayCommand = isGatewayCommandUtil;
+
+async function buildGatewayRequest({ message, satelliteId, satelliteName, agentId, mode, signal }) {
+  // Get gateway config dynamically (includes auto-discovered values)
+  const gw = await getGatewayConfig();
+  
+  // Don't prefix gateway slash commands — gateway needs to see them raw
+  const isCommand = isGatewayCommand(message);
+  const prefix = isCommand
+    ? ''
+    : mode === 'voice'
+      ? '[Voice chat - keep response brief and conversational, 1-2 sentences max] '
+      : '[Text chat via Uplink] ';
+  
+  // Build canonical session key format (OpenClaw: agent:{agentId}:{provider}:{scope}:{identifier})
+  // Main satellite shares session with Dashboard: agent:main:main
+  // Other satellites get isolated: agent:{agentId}:uplink:satellite:<satelliteId>
+  // agentId determines which agent handles the session
+  const agent = agentId || 'main';
+  const sessionKey = satelliteId === 'main'
+    ? `agent:${agent}:main`  // Share with Dashboard for session sync
+    : `agent:${agent}:uplink:satellite:${satelliteId}`;
+  
+  if (!gw.url) {
+    throw new Error('Gateway URL not configured. Check OpenClaw gateway settings.');
+  }
+
+  log('debug', `[Channel] Direct gateway call: sessionKey=${sessionKey}, mode=${mode}, label=${satelliteName}`);
+  log('debug', `[Channel] Using gateway: ${gw.url}, hasToken: ${!!gw.token}`);
+
+  const url = `${gw.url}/v1/chat/completions`;
+  const headers = {
+    'Content-Type': 'application/json',
+    'Authorization': `Bearer ${gw.token}`,
+    'x-openclaw-session-key': sessionKey,
+  };
+  
+  // Add session label if satellite name provided
+  if (satelliteName) {
+    headers['x-openclaw-session-label'] = satelliteName;
+  }
+  
+  const options = {
+    method: 'POST',
+    headers,
+    body: JSON.stringify({
+      model: 'openclaw',
+      user: `uplink-default`,
+      stream: true,
+      stream_options: { include_usage: true },
+      messages: [{ role: 'user', content: `${prefix}${message}` }],
+    }),
+    signal,
+  };
+
+  return { url, options, sessionKey };
+}
+
+/**
+ * Validate gateway response and return the reader
+ * 
+ * @param {Response} response - The fetch response
+ * @returns {ReadableStreamDefaultReader} - The body reader
+ * @throws {Error} - If response is not ok or has no body
+ */
+async function validateGatewayResponse(response) {
+  if (!response.ok) {
+    const text = await response.text();
+    throw new Error(`Gateway error: ${response.status} - ${text}`);
+  }
+
+  log('debug', `[Channel] Gateway response received: status=${response.status}, hasBody=${!!response.body}, bodyType=${response.body?.constructor?.name}`);
+
+  if (!response.body) {
+    throw new Error('Response has no body');
+  }
+
+  return response.body.getReader();
+}
+
+/**
+ * Parse SSE line and extract content/metadata
+ * 
+ * @param {string} line - The SSE line to parse
+ * @returns {Object|null} - Parsed data or null if not parseable
+ */
+function parseSSELine(line) {
+  if (!line.startsWith('data: ')) {
+    return null;
+  }
+
+  const data = line.slice(6);
+  if (data === '[DONE]') {
+    log('debug', '[Channel] Got [DONE] marker');
+    return { done: true };
+  }
+
+  try {
+    const parsed = JSON.parse(data);
+    const delta = parsed.choices?.[0]?.delta;
+    
+    // Extract tool call names from OpenAI-compatible streaming format
+    const toolCalls = delta?.tool_calls;
+    let toolName = null;
+    if (toolCalls && toolCalls.length > 0) {
+      // tool_calls[].function.name appears in the first chunk for each tool call
+      toolName = toolCalls[0]?.function?.name || null;
+    }
+    
+    return {
+      content: delta?.content || '',
+      usage: parsed.usage || null,
+      toolName,
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Process the gateway SSE stream
+ * 
+ * @param {Object} params
+ * @param {ReadableStreamDefaultReader} params.reader - Stream reader
+ * @param {AbortSignal} params.signal - Abort signal
+ * @param {Object} params.callbacks - Event callbacks
+ * @returns {Object} - { fullResponse, tokenUsage, detectedTools }
+ */
+async function processGatewayStream({ reader, signal, callbacks }) {
+  const { onChunk, onTool, onThinking } = callbacks;
+  const decoder = new TextDecoder();
+  
+  let buffer = '';
+  let fullResponse = '';
+  let tokenUsage = null;
+  const detectedTools = [];
+  let chunkCount = 0;
+
+  onThinking?.();
+
+  try {
+    while (true) {
+      if (signal?.aborted) {
+        log('debug', '[Channel] Request aborted, stopping stream read');
+        break;
+      }
+
+      log('debug', `[Channel] About to read chunk ${chunkCount + 1}...`);
+      const { done, value } = await createReadWithTimeout(reader);
+      log('debug', `[Channel] Read returned: done=${done}, valueLen=${value?.length || 0}`);
+      
+      if (done) {
+        log('debug', `[Channel] Stream complete after ${chunkCount} chunks, response: ${fullResponse.length} chars`);
+        break;
+      }
+
+      chunkCount++;
+      const rawChunk = decoder.decode(value, { stream: true });
+      buffer += rawChunk;
+
+      if (chunkCount <= 3) {
+        log('debug', `[Channel] Chunk ${chunkCount}: ${rawChunk.substring(0, 200)}`);
+      }
+
+      const lines = buffer.split('\n');
+      buffer = lines.pop() || '';
+
+      for (const line of lines) {
+        const parsed = parseSSELine(line);
+        if (!parsed || parsed.done) continue;
+
+        if (parsed.usage) {
+          tokenUsage = parsed.usage;
+        }
+
+        // Detect tool usage from structured tool_calls field
+        if (parsed.toolName) {
+          log('debug', `[Channel] Tool detected from stream: ${parsed.toolName}`);
+        }
+        if (parsed.toolName && !detectedTools.includes(parsed.toolName)) {
+          detectedTools.push(parsed.toolName);
+          onTool?.(parsed.toolName);
+        }
+
+        if (parsed.content) {
+          fullResponse += parsed.content;
+          onChunk?.(parsed.content);
+
+          // Fallback: detect tool usage in content via XML pattern
+          const toolMatch = parsed.content.match(/<(?:antml:)?invoke name="(\w+)"/);
+          if (toolMatch && !detectedTools.includes(toolMatch[1])) {
+            detectedTools.push(toolMatch[1]);
+            onTool?.(toolMatch[1]);
+          }
+        }
+      }
+    }
+  } finally {
+    reader.releaseLock();
+  }
+
+  return { fullResponse, tokenUsage, detectedTools };
+}
+
+// ============================================================================
+// Main sendMessage Function
+// ============================================================================
+
+/**
+ * Send a message - routes through channel if enabled, otherwise direct to gateway
+ * Returns the full response and optional usage stats
+ * 
+ * @param {Object} params
+ * @param {string} params.message - The message to send
+ * @param {string} params.satelliteId - Satellite ID
+ * @param {string} params.satelliteName - Satellite display name (for session label)
+ * @param {string} params.mode - 'text' or 'voice'
+ * @param {AbortSignal} params.signal - Optional abort signal for cancellation
+ * @param {function} params.onChunk - Callback for stream chunks
+ * @param {function} params.onTool - Callback for tool usage
+ * @param {function} params.onThinking - Callback for thinking indicator
+ */
+export async function sendMessage({ 
+  message, 
+  satelliteId = 'main',
+  satelliteName,
+  agentId,
+  mode = 'text',
+  requestId,
+  signal,
+  onChunk,
+  onTool,
+  onThinking,
+}) {
+  const callbacks = { onChunk, onTool, onThinking };
+  let result;
+
+  if (isChannelEnabled()) {
+    // Route through channel webhook
+    const eventStream = sendViaChannel({ message, satelliteId, mode, requestId });
+    result = await processChannelStream({ eventStream, signal, callbacks });
+  } else {
+    // Direct gateway call
+    const { url, options } = await buildGatewayRequest({ message, satelliteId, satelliteName, agentId, mode, signal });
+    const response = await fetch(url, options);
+    const reader = await validateGatewayResponse(response);
+    result = await processGatewayStream({ reader, signal, callbacks });
+  }
+
+  const { fullResponse, tokenUsage, detectedTools } = result;
+
+  // Parse MEDIA: references from agent responses
+  const mediaPattern = /MEDIA:(.+?)(?:\n|$)/g;
+  const mediaRefs = [];
+  let match;
+  while ((match = mediaPattern.exec(fullResponse)) !== null) {
+    mediaRefs.push(match[1].trim());
+  }
+  
+  // Strip MEDIA: lines from displayed text
+  let cleanResponse = mediaRefs.length > 0
+    ? fullResponse.replace(/MEDIA:.+?(?:\n|$)/g, '').trim()
+    : fullResponse;
+
+  // Rewrite local file paths in markdown images to proxy URLs (if registerAgentMedia is available)
+  // This handles cases where agents embed ![alt](local/path.png) in markdown
+  const registerFn = global.registerAgentMedia || globalThis.registerAgentMedia;
+  if (registerFn && typeof registerFn === 'function') {
+    cleanResponse = cleanResponse.replace(/!\[([^\]]*)\]\(([^)]+)\)/g, (match, alt, url) => {
+      const trimmedUrl = url.trim();
+      // Skip URLs that are already http(s) or proxy URLs
+      if (/^(https?:|\/api\/)/i.test(trimmedUrl)) {
+        return match;
+      }
+      // Try to register the local path as agent media
+      const proxyUrl = registerFn(trimmedUrl);
+      if (proxyUrl) {
+        log('debug', `[Channel] Rewrote markdown image: ${trimmedUrl} -> ${proxyUrl}`);
+        return `![${alt}](${proxyUrl})`;
+      }
+      // If registration failed, leave as-is (client will handle gracefully)
+      return match;
+    });
+  }
+
+  // Use estimated tokens if not provided by API
+  const finalUsage = tokenUsage || estimateTokenUsage(message, cleanResponse);
+
+  return {
+    response: cleanResponse,
+    usage: finalUsage,
+    tools: detectedTools.length > 0 ? detectedTools : undefined,
+    media: mediaRefs.length > 0 ? mediaRefs : undefined,
+  };
+}